LU-14459 mdt: support fixed directory layout

[fs/lustre-release.git] / lustre / doc / llapi_layout_get_by_fd.3

diff --git a/lustre/doc/llapi_layout_get_by_fd.3 b/lustre/doc/llapi_layout_get_by_fd.3
index a29e9b0..864bf24 100644 (file)
--- a/lustre/doc/llapi_layout_get_by_fd.3
+++ b/lustre/doc/llapi_layout_get_by_fd.3
@@ -6,17 +6,23 @@ obtain the layout of a Lustre file
 .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
+.BR llapi_layout_get_by_xattr() ,
 .BR llapi_layout_get_by_fd() ,
 .BR llapi_layout_get_by_fid() ,
 and
@@ -24,6 +30,7 @@ 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
@@ -39,6 +46,15 @@ The pointer should be freed with
 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 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
@@ -46,16 +62,16 @@ filesystem.
 .PP
 For
 .BR llapi_layout_get_by_fid() ,
-the path named by
+the
 .I lustre_path
-serves to identify the Lustre filesystem containing the file
+argument serves to identify the Lustre filesystem containing the file
 represented by
 .IR fid .
 It is typically the filesystem root, 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
@@ -66,15 +82,19 @@ argument that names a file or directory in a Lustre filesystem.
 .PP
 Zero or more flags may be bitwise-or'd together in
 .I flags
+or
+.I xattr_flags
 to control how a layout is retrieved.  Currently
 .B llapi_layout_get_by_path()
-accepts only one flag, and
+accepts only one flag, while
 .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 use any flags. The list of flags that can be used in
+.I flags
+is 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
@@ -87,7 +107,7 @@ files.
 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
@@ -104,9 +124,32 @@ the filesystem default.  The layout of D returned by
 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
+The values that can be used by
+.B llapi_layout_get_by_xattr()
+.I flags
+argument is as follows:
+.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 RETURN VALUES
 .LP
 .BR llapi_layout_get_by_fd() ,
@@ -139,4 +182,4 @@ The kernel returned less than the expected amount of data.
 .BR llapi_layout_file_open (3),
 .BR llapi_path2fid (3),
 .BR llapi_layout (7),
-.BR liblustreapi (7)
+.BR lustreapi (7)