lustre/doc/llapi_file_open.3

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