-.TH llapi_create_volatile_param 3 "2015-01-14" "" "Lustre User API"
+.TH LLAPI_CREATE_VOLATILE_PARAM 3 2024-08-23 "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_create_volatile_param \- Lustre API file management
.SH SYNOPSIS
-.sp
-\fB#include <lustre/lustreapi.h>\fP
-.sp
-\fBint llapi_create_volatile_param(const char *\fPdirectory\fB,
-int\fP mdt_idx\fB, int\fP open_flags\fB, mode_t\fP mode\fB, const
-struct llapi_stripe_param *\fPstripe_param\fB)\fP
-.sp
-\fBint llapi_create_volatile_idx(char *\fPdirectory\fB, int\fP idx\fB, int\fP open_flags\fB)\fP
-.sp
-\fBint llapi_create_volatile(char *\fPdirectory\fB, int\fP mode\fB)\fP
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_create_volatile_param(const char *" directory ", int " mdt_indx ,
+.BI " int " open_flags ", mode_t " mode ,
+.BI " const struct llapi_stripe_param *" stripe_param )
+.PP
+.BI "int llapi_create_volatile_idx(char *" directory ", int " idx ", int " open_flags )
+.PP
+.BI "int llapi_create_volatile(char *" directory ", int " mode )
+.fi
.SH DESCRIPTION
-.sp
These three functions create an anonymous, temporary, volatile file on
a Lustre filesystem. The created file is not visible with
-\fBls(1)\fP\&. Once the file is closed, or the owning process dies, the
-file is permanently removed from the filesystem.
-.sp
+.BR ls (1).
+Once the file is closed, or the owning process dies,
+the file is permanently removed from the filesystem.
+.P
These functions will also work on a non\-Lustre filesystem, where the
file is created then unlinked, leaving only the file descriptor to
access the file. This is not strictly equivalent because there is a
small window during which the file is visible to users (provided they
-have access to the \fIdirectory\fP).
-.sp
-The \fIdirectory\fP parameter indicates where to create the file on the
-Lustre filesystem.
-.sp
-\fImdt_idx\fP is the MDT index onto which to create the file. To use a
-default MDT, set mdt_idx to \-1.
-.sp
-\fIopen_flags\fP and \fImode\fP are the same as \fBopen(2)\fP\&.
-.sp
-\fIstripe_param\fP describes the striping information. If it is NULL, then
-the default for the directory is used.
+have access to the
+.IR directory ).
+.P
+The
+.I directory
+parameter indicates where to create the file on the Lustre filesystem.
+.P
+.I mdt_idx
+is the MDT index onto which to create the file.
+To use a default MDT, set mdt_idx to \-1.
+.P
+.I open_flags
+and
+.I mode
+are the same as
+.BR open (2).
+.P
+.I stripe_param
+describes the striping information.
+If it is NULL, then the default for the directory is used.
.SH RETURN VALUE
-.sp
-\fBllapi_create_volatile_param\fP, \fBllapi_create_volatile_idx\fP and
-\fBllapi_create_volatile\fP return a file descriptor on success. They
-all return a negative errno on failure.
+.BR llapi_create_volatile_param ,
+.B llapi_create_volatile_idx
+and
+.B llapi_create_volatile
+return a file descriptor on success.
+They all return a negative errno on failure.
.SH ERRORS
-.sp
The negative errno can be, but is not limited to:
-.sp
-\fB\-EINVAL\fP An invalid value was passed.
-.sp
-\fB\-ENOMEM\fP Not enough memory to allocate a resource.
-.SH SEE ALSO
-.sp
-\fBlustreapi\fP(7)
-.SH AUTHOR
+.TP 15
+.B -EINVAL
+An invalid value was passed.
+.TP 15
+.B -ENOMEM
+Not enough memory to allocate a resource.
+.SH AUTHORS
Frank Zago for Cray Inc.
+.SH AVAILABILITY
+.BR llapi_create_volatile_param() ,
+.B llapi_create_volatile_idx()
+and
+.B llapi_create_volatile()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\" Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
+.BR lustreapi (7)
-.TH lustreapi 3 "2019 Sep 13" Lustre user application interface library
+.TH LLAPI_FID_PARSE 3 2024-08-23 "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_fid_parse \- parse ASCII FID string into binary lu_fid
.SH SYNOPSIS
.nf
.B #include <lustre/lustreapi.h>
-.sp
+.PP
.BI "int llapi_fid_parse(const char *" fidstr ", struct lu_fid *" fid ,
.BI " char **" endptr ");"
-.sp
+.PP
.fi
.SH DESCRIPTION
-.LP
.B llapi_fid_parse()
converts an ASCII FID string into a binary
.B struct lu_fid
.IR *endptr ,
or the character immediately following the end of the parsed FID.
.SH RETURN VALUES
-.LP
.B llapi_fid_parse()
returns:
.TP
a negative errno on failure and sets errno.
.SH ERRORS
.TP 15
-.SM EINVAL
+.B -EINVAL
.I fidstr
is NULL or does not contain a valid FID format.
-.TP
-.SM ERANGE
+.TP 15
+.B -ERANGE
.I fidstr
contains numeric values that exceed valid values for a component.
-.SH "EXAMPLE"
+.SH EXAMPLES
.nf
#include <lustre/lustreapi.h>
-
+\&
int main(int argc, char *argv[])
{
char fidstr = "[0x200000004:0x2:0x0] [0x200000400:0x345:0x0]";
struct lu_fid fid1, fid2;
char *end;
int rc;
-
+\&
fidstr = argv[1];
rc = llapi_fid_parse(fidstr, &fid1, &end);
if (rc < 0) {
fidstr, strerror(-rc));
return -1;
}
-
+\&
fidstr = end;
rc = llapi_fid_parse(fidstr, &fid2, &end);
if (rc < 0) {
fidstr, strerror(-rc));
return -1;
}
-
+\&
printf("fid1=" DFID " fid2="DFID"\\n", PFID(&fid1), PFID(&fid2));
return 0;
}
.fi
-.SH "SEE ALSO"
-.BR lustre (7),
+.SH AVAILABILITY
+.B llapi_fid_parse()
+is part of the
+.BR lustre (7)
+user application interface library since release 2.14.0
+.\" Added in commit v2_13_50-48-g21d671b3af
+.SH SEE ALSO
.BR llapi_path2parent (3),
+.BR lustre (7),
.BR lustreapi (7)
-.TH llapi_fid_to_handle 3 "2022-11-08" "Lustre User API"
+.TH LLAPI_FID_TO_HANDLE 3 2024-08-23" "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_fid_to_handle \- allocate an NFS handle for File Identifier
.SH SYNOPSIS
.BI "int llapi_fid_to_handle(struct file_handle **" handle ", struct lu_fid *" fid ");"
.fi
.SH DESCRIPTION
-.PP
.BR llapi_fid_to_handle()
allocates an NFS file
.I handle
and returned to the caller must be freed with
.IR free (2).
.SH RETURN VALUES
-.LP
returns 0 on success or a negative errno on failure.
.SH ERRORS
.TP 15
-.SM -ENOMEM
+.B -ENOMEM
No memory was available for allocating
.IR handle .
+.SH AVAILABILITY
+.B llapi_fid_to_handle()
+is part of the
+.BR lustre (7)
+user application interface library since release 2.16.0
+.\" Added in commit v2_15_52-154-gbdf7788d19
.SH SEE ALSO
+.BR name_to_handle (2),
+.BR open_by_handle_at (2),
.BR free (3),
.BR llapi_fid_parse (3),
.BR llapi_fid2path (3),
.BR llapi_path2fid (3),
.BR lustreapi (7),
-.BR name_to_handle (2)
-.BR open_by_handle_at (2)
-.TH lustreapi 3 "2009 Jul 10" The Lustre user application interface library
+.TH LLAPI_FILE_CREATE_FOREIGN 3 2024-08-23 "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_file_create_foreign \- create a file with foreign layout on a Lustre filesystem
.SH SYNOPSIS
.B #include <sys/stat.h>
.B #include <fcntl.h>
.B #include <lustre/lustreapi.h>
-.sp
+.PP
.BI "int llapi_file_create_foreign(const char *" name ", mode_t " mode ","
-.BI " __u32 " type ", __u32 " flags ", char *" foreign_lov );
-.sp
+.BI " __u32 " type ", __u32 " flags ,
+.BI " char *" foreign_lov );
.fi
.SH DESCRIPTION
-.LP
-.B llapi_file_create_foreign(\|)
+.B llapi_file_create_foreign()
creates a file with
.I foreign_lov
free format layout and
free-format string to be set as file layout/LOV EA.
.SH RETURN VALUES
.LP
-.B llapi_file_create_foreign(\|)
+.B llapi_file_create_foreign()
return:
.TP
>=0
on success, for
-.B llapi_file_open
+.B llapi_file_open()
the return value is a file descriptor.
.TP
<0
.SM ENOTTY
.I name
may not point to a Lustre filesystem.
-.SH "EXAMPLE"
+.SH EXAMPLES
.nf
#include <sys/types.h>
#include <sys/stat.h>
int main(int argc, char *argv[])
{
int rc;
-
+\&
if (argc != 2)
return -1;
-
+\&
rc = llapi_file_create_foreign(argv[1], 0600, LOV_FOREIGN_TYPE_SYMLINK,
0xda05, "PUUID/CUUID");
if (rc < 0) {
return 0;
}
.fi
-.SH "SEE ALSO"
-.BR llapi_file_open (3)
+.SH AVAILABILITY
+.B llapi_file_create_foreign()
+is part of the
+.BR lustre (7)
+user application interface library since release 2.13.0
+.\" Added in commit v2_12_53-14-g6a20bdcc60
+.SH SEE ALSO
+.BR open (2),
+.BR llapi_file_open (3),
.BR lustre (7),
.BR lustreapi (7)
-.BR open (2),
-.TH lustreapi 3 "2009 Jul 22" The Lustre user application interface library
+.TH LLAPI_FILE_GET_STRIPE 3 2024-08-23 "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_file_get_stripe \- get striping information for a file or a directory on a Lustre filesystem
.SH SYNOPSIS
.B #include <sys/stat.h>
.B #include <fcntl.h>
.B #include <lustre/lustreapi.h>
-.sp
+.PP
.BI "int llapi_file_get_stripe(const char *"path ", void *"lum );
-.sp
.fi
.SH DESCRIPTION
.LP
-.B llapi_file_get_stripe(\|)
+.B llapi_file_get_stripe()
returns striping information for a file or a directory
.I path
in
.I lum
(which should point to a large enough memory region) in one of the following formats:
-
+.PP
.nf
struct lov_user_md_v1 {
__u32 lmm_magic;
__u16 lmm_stripe_offset;
struct lov_user_ost_data_v1 lmm_objects[];
} __attribute__((packed));
-
+\&
struct lov_user_md_v3 {
__u32 lmm_magic;
__u32 lmm_pattern;
struct lov_user_ost_data_v1 lmm_objects[];
} __attribute__((packed));
.fi
-
.TP 20
.I lmm_magic
specifies the format of the returned striping information.
is an array of
.I lmm_stripe_count
members containing per OST file information in the following format:
-
+.PP
.nf
struct lov_user_ost_data_v1 {
__u64 l_object_id;
holds the OST index in LOV.
.SH RETURN VALUES
.LP
-.B llapi_file_get_stripe(\|)
+.B llapi_file_get_stripe()
returns:
.TP
0
memory region pointed by
.I lum
is not properly mapped.
-.SH "EXAMPLE"
+.SH EXAMPLES
.nf
#include <sys/vfs.h>
#include <lustre/lustreapi.h>
-
+\&
static inline int maxint(int a, int b)
{
return a > b ? a : b;
}
-
+\&
static void *alloc_lum()
{
int v1, v3, join;
-
+\&
v1 = sizeof(struct lov_user_md_v1) +
LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
v3 = sizeof(struct lov_user_md_v3) +
LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
-
+\&
return malloc(maxint(v1, v3));
}
-
+\&
int main(int argc, char** argv)
{
struct lov_user_md *lum_file = NULL;
int rc;
int lum_size;
-
+\&
if (argc != 2) {
fprintf(stderr, "Usage: %s <filename>\\n", argv[0]);
return 1;
}
-
+\&
lum_file = alloc_lum();
if (lum_file == NULL) {
rc = ENOMEM;
goto cleanup;
}
-
+\&
rc = llapi_file_get_stripe(argv[1], lum_file);
if (rc) {
rc = errno;
goto cleanup;
}
-
+\&
/* stripe_size stripe_count */
printf("%d %d\\n",
lum_file->lmm_stripe_size,
lum_file->lmm_stripe_count);
-
+\&
cleanup:
if (lum_file != NULL)
free(lum_file);
-
+\&
return rc;
}
.fi
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_file_get_stripe()
+is part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\" Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
.BR lustre (7),
.BR lustreapi (7)
-.TH lustreapi 3 "2009 Jul 10" The Lustre user application interface library
+.TH LLAPI_FILE_OPEN 3 2024-08-23 "Lustre User API" "Lustre Library Functions"
.SH NAME
llapi_file_open, llapi_file_create \- open and possibly create a file or a device on a Lustre filesystem
.SH SYNOPSIS
.B #include <sys/stat.h>
.B #include <fcntl.h>
.B #include <lustre/lustreapi.h>
-.sp
+.PP
.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 );
-
+.PP
.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_create()
+call is equivalent to
.B llapi_file_open
-call with
-.I flags
+call with
+.I flags
equal to
.B O_CREAT|O_WRONLY
and
.BR 0644 ,
followed by file close.
.PP
-.B llapi_file_open(\|)
-opens a file with a given
+.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
+can be a combination of
.BR O_RDONLY ,
.BR O_WRONLY ,
.BR O_RDWR ,
.BR O_DIRECTORY ,
.BR O_NOFOLLOW ,
.BR O_NOATIME .
-
+.IP
Refer to
.BR open(2)
man page for a detailed description.
specifies the permission bits to be used for a new file when
.BR O_CREAT
is used.
-
+.IP
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.
+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.
+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.
+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.
+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(\|)
+.B llapi_file_open(\|)
+and
+.B llapi_file_create(\|)
return:
.TP
>=0
.SM ENOTTY
.I name
may not point to a Lustre filesystem.
-.SH "EXAMPLE"
+.SH EXAMPLES
.nf
#include <sys/types.h>
#include <sys/stat.h>
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 0;
}
.fi
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_file_open()
+and
+.B llapi_file_create()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.4.0
+.\" Added in commit 2.3.53-7-gf715e4e298
+.SH SEE ALSO
.BR open (2),
.BR lustre (7),
.BR lustreapi (7)
git://git.whamcloud.com / fs / lustre-release.git / commitdiff