lustre/doc/llapi_layout_file_create.3

   1 .TH llapi_layout_file_open 3 "2013 Oct 31" "Lustre User API"
   2 .SH NAME
   3 llapi_layout_file_open, llapi_layout_file_create \- open and apply a layout to a Lustre file
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <lustre/lustreapi.h>
   7 .PP
   8 .BI "int llapi_layout_file_open(char *" path ", int " open_flags ", int " mode ,
   9 .BI "                           const struct llapi_layout *" layout );
  10 .PP
  11 .BI "int llapi_layout_file_create(char *" path ", int " open_flags ", int " mode ,
  12 .BI "                             const struct llapi_layout *" layout );
  13 .fi
  14 .SH DESCRIPTION
  15 .LP
  16 The functions
  17 .B llapi_layout_file_open()
  18 and
  19 .B llapi_layout_file_create()
  20 open and possibly create a file at
  21 .I path
  22 with the permissions specified in
  23 .I mode
  24 using the Lustre layout attributes in
  25 .IR layout .
  26 The returned file descriptor may be used in subsequent system calls
  27 .RB ( read (2),
  28 .BR write (2),
  29 .BR lseek (2),
  30 etc.), and closed with
  31 .BR close (2).
  32 One access mode and zero or more file creation flags and file status
  33 flags may be bitwise-or'd in
  34 .IR open_flags .
  35 See
  36 .BR open (2).
  37 If
  38 .I layout
  39 is non-NULL and
  40 .I path
  41 is not on a Lustre filesystem this function will fail and set
  42 .B errno
  43 to
  44 .BR ENOTTY .
  45 .PP
  46 The function call
  47 .PP
  48 .B "    llapi_layout_file_create(path, open_flags, mode, layout)"
  49 .PP
  50 shall be equivalent to:
  51 .PP
  52 .B "    llapi_layout_file_open(path, open_flags|O_CREAT|O_EXCL, mode, layout)"
  53 .PP
  54 The
  55 .I layout
  56 and
  57 .I mode
  58 will not be applied to a file which already exists. Callers requiring a
  59 guarantee that the opened file is created with the specified
  60 .I layout
  61 and
  62 .I mode
  63 should use
  64 .BR llapi_layout_file_create() .
  65 .PP
  66 A
  67 .B NULL
  68 .I layout
  69 may be specified, in which case the standard Lustre behavior for
  70 assigning layouts to newly-created files will apply.
  71 .PP
  72 If the pool name attribute of
  73 .I layout
  74 has been set, it must refer to an OST pool that exists and contains one
  75 or more OSTs, otherwise these functions will fail and set
  76 .B errno
  77 to
  78 .BR EINVAL .
  79 See
  80 .BR llapi_layout_pool_name_set (3).
  81 .SH RETURN VALUES
  82 .LP
  83 .B llapi_layout_file_open()
  84 and
  85 .B llapi_layout_file_create()
  86 return a new file descriptor, or -1 if an error occurred (in which
  87 case, errno is set appropriately).
  88 .SH ERRORS
  89 .TP 15
  90 .SM ENOTTY
  91 .I path
  92 does not reside on a Lustre filesystem.
  93 .TP
  94 .SM EINVAL
  95 An invalid argument was specified.
  96 .SH "SEE ALSO"
  97 .BR llapi_layout (7),
  98 .BR lustreapi (7),
  99 .BR llapi_layout_alloc (3),
 100 .BR llapi_layout_pool_name_set (3),
 101 .BR open (2),
 102 .BR close (2)