From 021e9986bb219d9d2b5a3dc6de0c1c7c1e03f6df Mon Sep 17 00:00:00 2001 From: anserper Date: Fri, 24 Jul 2009 08:52:59 +0000 Subject: [PATCH] b=16267 i=ZhiYong Tian man page for llapi_file_open --- lustre/doc/Makefile.am | 2 +- lustre/doc/llapi_file_open.3 | 154 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 155 insertions(+), 1 deletion(-) create mode 100644 lustre/doc/llapi_file_open.3 diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am index 0a79a29..8ae1de5 100644 --- a/lustre/doc/Makefile.am +++ b/lustre/doc/Makefile.am @@ -49,7 +49,7 @@ SUFFIXES = .lin .lyx .pdf .ps .sgml .html .txt .tex .fig .eps .dvi MANFILES = lustre.7 lfs.1 mount.lustre.8 mkfs.lustre.8 tunefs.lustre.8 lctl.8 \ llverdev.8 llbackup.8 llapi_quotactl.3 llobdstat.8 llstat.8 \ plot-llstat.8 l_getgroups.8 lst.8 routerstat.8 \ - ll_recover_lost_found_objs.8 llog_reader.8 + ll_recover_lost_found_objs.8 llog_reader.8 llapi_file_open.3 if UTILS man_MANS = $(MANFILES) diff --git a/lustre/doc/llapi_file_open.3 b/lustre/doc/llapi_file_open.3 new file mode 100644 index 0000000..0d84d72 --- /dev/null +++ b/lustre/doc/llapi_file_open.3 @@ -0,0 +1,154 @@ +.TH LLAPI_FILE_OPEN 3 "2009 Jul 10" Lustre API +.SH NAME +llapi_file_open, llapi_file_create \- open and possibly create a file or a device on a Lustre filesystem +.SH SYNOPSIS +.nf +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.B #include +.sp +.BI "int llapi_file_open(const char *"name ", int " flags ", int " mode "," +.BI " unsigned long long " stripe_size ", int " stripe_offset "," +.BI " int " stripe_count ", int " stripe_pattern ); + +.BI "int llapi_file_create(const char *" name ", unsigned long long " stripe_size "," +.BI " int " stripe_offset ", int " stripe_count "," +.BI " int " stripe_pattern ); +.sp +.fi +.SH DESCRIPTION +.LP +.B llapi_file_create(\|) +call is equivalent to +.B llapi_file_open +call with +.I flags +equal to +.B O_CREAT|O_WRONLY +and +.I mode +equal to +.BR 0644 , +followed by file close. +.PP +.B llapi_file_open(\|) +opens a file with a given +.I name +on a Lustre filesystem. +.TP 15 +.I flags +can be a combination of +.BR O_RDONLY , +.BR O_WRONLY , +.BR O_RDWR , +.BR O_CREAT , +.BR O_EXCL , +.BR O_NOCTTY , +.BR O_TRUNC , +.BR O_APPEND , +.BR O_NONBLOCK , +.BR O_SYNC , +.BR FASYNC , +.BR O_DIRECT , +.BR O_LARGEFILE , +.BR O_DIRECTORY , +.BR O_NOFOLLOW , +.BR O_NOATIME . + +Refer to +.BR open(2) +man page for a detailed description. +.TP 15 +.I mode +specifies the permission bits to be used for a new file when +.BR O_CREAT +is used. + +Refer to +.BR open(2) +man page for a detailed description. +.TP 15 +.I stripe_size +specifies stripe size in bytes and should be multiple of 64 KiB not exceeding 4 GiB. +.TP 15 +.I stripe_offset +specifies an OST index from which the file should start, -1 to use the default setting. +.TP 15 +.I stripe_count +specifies number of OSTs to stripe the file across, -1 to use the default setting. +.TP 15 +.I stripe_pattern +specifies striping pattern, only LOV_PATTERN_RAID0 is available in this Lustre version, 0 to use the default setting. +.SH RETURN VALUES +.LP +.B llapi_file_open(\|) +and +.B llapi_file_create(\|) +return: +.TP +>=0 +on success, for +.B llapi_file_open +the return value is a file descriptor. +.TP +<0 +on failure, the absolute value is an error code. +.SH ERRORS +.TP 15 +.SM EINVAL +.I stripe_size +or +.I stripe_offset +or +.I stripe_count +or +.I stripe_pattern +is invalid. +.TP +.SM EEXIST +Striping information has already been set and cannot be altered. +.IP +.I name +already exists. +.TP +.SM EALREADY +Striping information has already been set and cannot be altered. +.TP +.SM ENOTTY +.I name +may not point to a Lustre filesystem. +.SH "EXAMPLE" +.nf +#include +#include +#include +#include +#include +#include +#include +#include +#include +int main(int argc, char *argv[]) +{ + int rc; + + if (argc != 2) + return -1; + + rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0); + if (rc < 0) { + fprintf(stderr, "file creation has failed, %s\\n", strerror(-rc)); + return -1; + } + printf("%s with stripe size 1048576, striped across 2 OSTs," + " has been created!\\n", argv[1]); + return 0; +} +.fi +.SH "SEE ALSO" +.BR open (2), +.BR lustre (7) -- 1.8.3.1