.nf
.B #include <lustre/lustreapi.h>
.PP
-.BI "struct llapi_layout *llapi_layout_get_by_fd(int "fd ", uint32_t " flags );
+.BI "struct llapi_layout *llapi_layout_get_by_fd(int " fd ,
+.BI " enum llapi_layout_get_flags " flags );
.PP
.BI "struct llapi_layout *llapi_layout_get_by_fid(const char *"lustre_path ,
-.BI " const lustre_fid *"fid ,
-.BI " uint32_t " flags );
+.BI " const struct lu_fid *"fid ,
+.BI " enum llapi_layout_get_flags " flags );
.PP
.BI "struct llapi_layout *llapi_layout_get_by_path(const char *"path ,
-.BI " uint32_t " flags );
+.BI " enum llapi_layout_get_flags " flags );
+.PP
+.BI "struct llapi_layout *llapi_layout_get_by_xattr(void *"lov_xattr ,
+.BI " ssize_t " lov_xattr_size ,
+.BI " enum llapi_layout_get_flags " flags );
.fi
.SH DESCRIPTION
.PP
+The functions
+.BR llapi_layout_get_by_xattr() ,
.BR llapi_layout_get_by_fd() ,
.BR llapi_layout_get_by_fid() ,
and
return a pointer to a newly-allocated
.B struct llapi_layout
containing the layout information for the file referenced by
+.IR lov_xattr ,
.IR fd ,
.IR fid ,
or
-.IR path .
-The
+.IR path ,
+respectively. The
.B struct llapi_layout
is an opaque entity containing the layout information for a file in a
Lustre filesystem. Its internal structure should not be directly
when it is no longer needed.
.PP
For
+.BR llapi_layout_get_by_xattr() ,
+.I lov_xattr
+is a Lustre layout extended attribute (LOV EA) from a file or directory in
+a Lustre filesystem. The
+.I lov_xattr
+should be the raw xattr without being byte-swapped, since this function will
+swap it to the local machine endianness properly.
+.PP
+For
.BR llapi_layout_get_by_fd() ,
.I fd
is a valid open file descriptor for a file or directory in a Lustre
.PP
For
.BR llapi_layout_get_by_fid() ,
-the path named by
.I lustre_path
-serves to identify the Lustre filesystem containing the file
-represented by
+identifies the Lustre filesystem containing the file represented by
.IR fid .
-It is typically the filesystem root, but may also be any path beneath
+It is typically the filesystem root directory, but may also be any path beneath
the root. Use the function
.BR llapi_path2fid (3)
to obtain a
-.B lustre_fid
+.B struct lu_fid
associated with a given path.
.PP
The function
Zero or more flags may be bitwise-or'd together in
.I flags
to control how a layout is retrieved. Currently
-.B llapi_layout_get_by_path()
-accepts only one flag, and
.B llapi_layout_get_by_fd()
and
.B llapi_layout_get_by_fid()
-do not accept any flags. The list of flags is as follows:
+do not accept any values for
+.IR flags ,
+while
+.B llapi_layout_get_by_path()
+accepts only one flag as follows:
.TP 5
-.SM LAYOUT_GET_EXPECTED
+.SM LLAPI_LAYOUT_GET_EXPECTED
Unspecified attribute values are replaced by the literal default values
that will be assigned when the file is created or first written to.
A default value is inherited from the parent directory if the attribute
By default, layouts report the abstract value
.B LLAPI_LAYOUT_DEFAULT
to indicate an unspecified attribute. Use
-.B LAYOUT_GET_EXPECTED
+.B LLAPI_LAYOUT_GET_EXPECTED
to discover the expected literal values for new files in a given
directory. Do not use it if you need to distinguish between specified
and unspecified attributes. The flag has no effect if
has the abstract stripe size value
.BR LLAPI_LAYOUT_DEFAULT ,
since stripe size is unspecified, while
-.B llapi_layout_get_by_path(D, LAYOUT_GET_EXPECTED)
+.B llapi_layout_get_by_path(D, LLAPI_LAYOUT_GET_EXPECTED)
reports the literal value 1048576. Both forms report a stripe count
of 2, since that attribute is specified.
+.PP
+Valid arguments for
+.I flags
+with
+.B llapi_layout_get_by_xattr()
+are:
+.TP 5
+.SM LLAPI_LAYOUT_GET_CHECK
+If the
+.B LLAPI_LAYOUT_GET_CHECK
+flag is set, this function will check whether the objects count in lum
+is consistent with the stripe count in lum. This check only apply to
+regular files, so it should not be passed if the xattr is a default
+layout from a directory.
+.TP
+.SM LLAPI_LAYOUT_GET_COPY
+If the
+.B LLAPI_LAYOUT_GET_COPY
+flag is set, this function will use a temporary buffer for byte swapping
+when necessary, leaving
+.I lov_xattr
+unmodified. Otherwise, the byte swapping will be done to the fields of the
+.I lov_xattr
+buffer directly.
+.SH NOTE
+When using these functions to copy an existing file's layout to create a
+new file with
+.B llapi_layout_file_open (3)
+for mirroring, migration, or as the template for a new file,
+.BR llapi_layout_ost_index_reset (3)
+should be called to reset the OST index values for each component, so that
+the file copy is not created on exactly the same OSTs as the original file.
.SH RETURN VALUES
-.LP
-.BR llapi_layout_get_by_fd() ,
-.BR llapi_layout_get_by_fid() ,
-and
-.B llapi_layout_get_by_path()
-return a valid pointer on success or
+These functions return a valid pointer on success or
.B NULL
on failure with
.B errno
The kernel returned less than the expected amount of data.
.SH "SEE ALSO"
.BR llapi_layout_file_open (3),
+.BR llapi_layout_ost_index_reset (3),
.BR llapi_path2fid (3),
.BR llapi_layout (7),
-.BR liblustreapi (7)
+.BR lustreapi (7)
git://git.whamcloud.com / fs / lustre-release.git / blobdiff