lustre/doc/llapi_file_open.3

   1 .TH lustreapi 3 "2009 Jul 10" The Lustre user application interface library
   2 .SH NAME
   3 llapi_file_open, llapi_file_create \- open and possibly create a file or a device on a Lustre filesystem
   4 .SH SYNOPSIS
   5 .nf
   6 .B #include <sys/types.h>
   7 .B #include <sys/stat.h>
   8 .B #include <fcntl.h>
   9 .B #include <lustre/lustreapi.h>
  10 .sp
  11 .BI "int llapi_file_open(const char *"name ", int " flags ", int " mode ","
  12 .BI "                    unsigned long long " stripe_size ", int " stripe_offset ","
  13 .BI "                    int " stripe_count ", int " stripe_pattern );
  14
  15 .BI "int llapi_file_create(const char *" name ", unsigned long long " stripe_size ","
  16 .BI "                      int " stripe_offset ", int " stripe_count ","
  17 .BI "                      int " stripe_pattern );
  18 .sp
  19 .fi
  20 .SH DESCRIPTION
  21 .LP
  22 .B llapi_file_create(\|)
  23 call is equivalent to
  24 .B llapi_file_open
  25 call with
  26 .I flags
  27 equal to
  28 .B O_CREAT|O_WRONLY
  29 and
  30 .I mode
  31 equal to
  32 .BR 0644 ,
  33 followed by file close.
  34 .PP
  35 .B llapi_file_open(\|)
  36 opens a file with a given
  37 .I name
  38 on a Lustre filesystem.
  39 .TP 15
  40 .I flags
  41 can be a combination of
  42 .BR O_RDONLY ,
  43 .BR O_WRONLY ,
  44 .BR O_RDWR ,
  45 .BR O_CREAT ,
  46 .BR O_EXCL ,
  47 .BR O_NOCTTY ,
  48 .BR O_TRUNC ,
  49 .BR O_APPEND ,
  50 .BR O_NONBLOCK ,
  51 .BR O_SYNC ,
  52 .BR FASYNC ,
  53 .BR O_DIRECT ,
  54 .BR O_LARGEFILE ,
  55 .BR O_DIRECTORY ,
  56 .BR O_NOFOLLOW ,
  57 .BR O_NOATIME .
  58
  59 Refer to
  60 .BR open(2)
  61 man page for a detailed description.
  62 .TP 15
  63 .I mode
  64 specifies the permission bits to be used for a new file when
  65 .BR O_CREAT
  66 is used.
  67
  68 Refer to
  69 .BR open(2)
  70 man page for a detailed description.
  71 .TP 15
  72 .I stripe_size
  73 specifies stripe size in bytes and should be multiple of 64 KiB not exceeding 4 GiB.
  74 .TP 15
  75 .I stripe_offset
  76 specifies an OST index from which the file should start, -1 to use the default setting.
  77 .TP 15
  78 .I stripe_count
  79 specifies number of OSTs to stripe the file across, -1 to use the default setting.
  80 .TP 15
  81 .I stripe_pattern
  82 specifies striping pattern, only LOV_PATTERN_RAID0 is available in this Lustre version, 0 to use the default setting.
  83 .SH RETURN VALUES
  84 .LP
  85 .B llapi_file_open(\|)
  86 and
  87 .B llapi_file_create(\|)
  88 return:
  89 .TP
  90 >=0
  91 on success, for
  92 .B llapi_file_open
  93 the return value is a file descriptor.
  94 .TP
  95 <0
  96 on failure, the absolute value is an error code.
  97 .SH ERRORS
  98 .TP 15
  99 .SM EINVAL
 100 .I stripe_size
 101 or
 102 .I stripe_offset
 103 or
 104 .I stripe_count
 105 or
 106 .I stripe_pattern
 107 is invalid.
 108 .TP
 109 .SM EEXIST
 110 Striping information has already been set and cannot be altered.
 111 .IP
 112 .I name
 113 already exists.
 114 .TP
 115 .SM EALREADY
 116 Striping information has already been set and cannot be altered.
 117 .TP
 118 .SM ENOTTY
 119 .I name
 120 may not point to a Lustre filesystem.
 121 .SH "EXAMPLE"
 122 .nf
 123 #include <sys/types.h>
 124 #include <sys/stat.h>
 125 #include <fcntl.h>
 126 #include <errno.h>
 127 #include <stdio.h>
 128 #include <lustre/lustreapi.h>
 129 int main(int argc, char *argv[])
 130 {
 131         int rc;
 132
 133         if (argc != 2)
 134                 return -1;
 135
 136         rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0);
 137         if (rc < 0) {
 138                 fprintf(stderr, "file creation has failed, %s\\n", strerror(-rc));
 139                 return -1;
 140         }
 141         printf("%s with stripe size 1048576, striped across 2 OSTs,"
 142                " has been created!\\n", argv[1]);
 143         return 0;
 144 }
 145 .fi
 146 .SH "SEE ALSO"
 147 .BR open (2),
 148 .BR lustre (7),
 149 .BR lustreapi (7)