LU-4315 doc: update llapi-layout-[f-s] man page style

Updating files to match the new code style for Lustre manual pages as
enforced by 'contrib/scripts/checkpatch-man.pl'.

This also includes other changes like removing < > or { } for singular
required arguments and placing [ ] around optional ones as well as
making all arguments CAPITAL and italicized, literal arguments are
bolded. Lines over 80 characters should be split at the natural line
end rather than the word that goes over the limit as fewer lines will
need to be modified when making changes if each sentence is on it's
own line.

Only using features that appear in groff 1.22.3 as this is the
available version is CentOS 8.

Checked files:
- llapi_layout_free.3
- llapi_layout_get_by_fd.3
- llapi_layout_get_by_fid.3
- llapi_layout_get_by_path.3
- llapi_layout_get_by_xattr.3
- llapi_layout_ost_index_get.3
- llapi_layout_ost_index_reset.3
- llapi_layout_ost_index_set.3
- llapi_layout_pattern_get.3
- llapi_layout_pattern_set.3
- llapi_layout_pool_name_get.3
- llapi_layout_pool_name_set.3
- llapi_layout_stripe_count_get.3
- llapi_layout_stripe_count_set.3
- llapi_layout_stripe_size_get.3
- llapi_layout_stripe_size_set.3

Test-Parameters: trivial
Signed-off-by: Frederick Dilger <fdilger@whamcloud.com>
Change-Id: Ifdf0d86e76898bf3b4e7febb40acecb8f12ad702
Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56173
Reviewed-by: Andreas Dilger <adilger@whamcloud.com>
Reviewed-by: Arshad Hussain <arshad.hussain@aeoncomputing.com>
Reviewed-by: Oleg Drokin <green@whamcloud.com>
Tested-by: jenkins <devops@whamcloud.com>
Tested-by: Maloo <maloo@whamcloud.com>

diff --git a/lustre/doc/llapi_layout_get_by_fd.3 b/lustre/doc/llapi_layout_get_by_fd.3
index 377835e..c1519f7 100644 (file)
--- a/lustre/doc/llapi_layout_get_by_fd.3
+++ b/lustre/doc/llapi_layout_get_by_fd.3
@@ -1,7 +1,6 @@
-.TH llapi_layout_get_by_fd 3 "2013 Oct 31" "Lustre User API"
+.TH LLAPI_LAYOUT_GET_BY_FD 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
 .SH NAME
-llapi_layout_get_by_fd, llapi_layout_get_by_fid, llapi_layout_get_by_path, \-
-obtain the layout of a Lustre file
+llapi_layout_get_by_fd, llapi_layout_get_by_fid, llapi_layout_get_by_path, llapi_layout_get_by_xattr \- obtain the layout of a Lustre file
 .SH SYNOPSIS
 .nf
 .B #include <lustre/lustreapi.h>
@@ -21,7 +20,6 @@ obtain the layout of a Lustre file
 .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() ,
@@ -36,11 +34,11 @@ containing the layout information for the file referenced by
 .IR fid ,
 or
 .IR path ,
-respectively.  The
+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
-accessed by an application.  See
+Lustre filesystem. Its internal structure should not be directly
+accessed by an application. See
 .BR llapi_layout (7).
 The pointer should be freed with
 .B llapi_layout_free()
@@ -67,7 +65,7 @@ For
 identifies the Lustre filesystem containing the file represented by
 .IR fid .
 It is typically the filesystem root directory, but may also be any path beneath
-the root.  Use the function
+the root. Use the function
 .BR llapi_path2fid (3)
 to obtain a
 .B struct lu_fid
@@ -81,7 +79,7 @@ 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
-to control how a layout is retrieved.  Currently
+to control how a layout is retrieved. Currently
 .B llapi_layout_get_by_fd()
 and
 .B llapi_layout_get_by_fid()
@@ -91,7 +89,7 @@ while
 .B llapi_layout_get_by_path()
 accepts only one flag as follows:
 .TP 5
-.SM LLAPI_LAYOUT_GET_EXPECTED
+.B 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
@@ -100,29 +98,29 @@ This flag is only recognized by
 .BR llapi_layout_get_by_path() .
 Unspecified attributes may belong to directories and never-written-to
 files.
-.sp
+.P
 By default, layouts report the abstract value
 .B LLAPI_LAYOUT_DEFAULT
-to indicate an unspecified attribute.  Use
+to indicate an unspecified attribute. Use
 .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
+directory. Do not use it if you need to distinguish between specified
+and unspecified attributes. The flag has no effect if
 .I path
 names a file or directory with a fully specified layout.
-.sp
+.P
 For concreteness, consider a Lustre filesystem with a default stripe
-size of 1048576 and a default stripe count of 1.  A user sets the stripe
+size of 1048576 and a default stripe count of 1. A user sets the stripe
 count for directory D to 2 (thus overriding the filesystem-wide
-default) but leaves the stripe size unspecified.  Newly created files in
+default) but leaves the stripe size unspecified. Newly created files in
 D inherit a stripe count of 2 from D and a stripe size of 1048576 from
-the filesystem default.  The layout of D returned by
+the filesystem default. The layout of D returned by
 .B llapi_layout_get_by_path(D, 0)
 has the abstract stripe size value
 .BR LLAPI_LAYOUT_DEFAULT ,
 since stripe size is unspecified, while
 .B llapi_layout_get_by_path(D, LLAPI_LAYOUT_GET_EXPECTED)
-reports the literal value 1048576.  Both forms report a stripe count
+reports the literal value 1048576. Both forms report a stripe count
 of 2, since that attribute is specified.
 .PP
 Valid arguments for
@@ -131,7 +129,7 @@ with
 .B llapi_layout_get_by_xattr()
 are:
 .TP 5
-.SM LLAPI_LAYOUT_GET_CHECK
+.B LLAPI_LAYOUT_GET_CHECK
 If the
 .B LLAPI_LAYOUT_GET_CHECK
 flag is set, this function will check whether the objects count in lum
@@ -139,7 +137,7 @@ 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
+.B LLAPI_LAYOUT_GET_COPY
 If the
 .B LLAPI_LAYOUT_GET_COPY
 flag is set, this function will use a temporary buffer for byte swapping
@@ -148,14 +146,6 @@ when necessary, leaving
 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
 These functions return a valid pointer on success or
 .B NULL
@@ -164,22 +154,40 @@ on failure with
 set to an appropriate error code.
 .SH ERRORS
 .TP 15
-.SM ENOMEM
+.B ENOMEM
 Insufficient storage space is available.
 .TP
-.SM ENOTTY
+.B ENOTTY
 File does not reside on a Lustre filesystem.
 .TP
-.SM ENOENT
+.B ENOENT
 .I path
 does not exist.
 .TP
-.SM EINVAL
+.B EINVAL
 An invalid argument was specified.
 .TP
-.SM EINTR
+.B EINTR
 The kernel returned less than the expected amount of data.
-.SH "SEE ALSO"
+.SH NOTES
+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 AVAILABILITY
+.BR llapi_layout_get_by_fd(),
+.BR llapi_layout_get_by_fid(),
+.B llapi_layout_get_by_path()
+and
+.B llapi_layout_get_by_xattr()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.7.0
+.\" Added in commit v2_6_51_0-23-g3d3a37c9c8
+.SH SEE ALSO
 .BR llapi_layout_file_open (3),
 .BR llapi_layout_ost_index_reset (3),
 .BR llapi_path2fid (3),

diff --git a/lustre/doc/llapi_layout_ost_index_get.3 b/lustre/doc/llapi_layout_ost_index_get.3
index 5e3b990..6923079 100644 (file)
--- a/lustre/doc/llapi_layout_ost_index_get.3
+++ b/lustre/doc/llapi_layout_ost_index_get.3
@@ -1,7 +1,6 @@
-.TH llapi_layout_ost_index_get 3 "2013 Oct 31" "Lustre User API"
+.TH LLAPI_LAYOUT_OST_INDEX_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
 .SH NAME
-llapi_layout_ost_index_get, llapi_layout_ost_index_set \- get or set the
-OST index of a stripe of a Lustre file
+llapi_layout_ost_index_get, llapi_layout_ost_index_set \- get or set the OST index of a stripe of a Lustre file
 .SH SYNOPSIS
 .nf
 .B #include <lustre/lustreapi.h>
@@ -13,7 +12,6 @@ OST index of a stripe of a Lustre file
 .BI "                               int " stripe_number ", uint64_t " ost_index );
 .fi
 .SH DESCRIPTION
-.PP
 .B llapi_layout_ost_index_get()
 stores into
 .I ost_index
@@ -58,7 +56,6 @@ filesystem and will reset previously-set
 .I stripe_number
 assignments.
 .SH RETURN VALUES
-.LP
 .B llapi_layout_ost_index_get()
 and
 .B llapi_layout_ost_index_set()
@@ -66,12 +63,20 @@ return 0 on success, or -1 if an error occurred (in which case, errno is
 set appropriately).
 .SH ERRORS
 .TP 15
-.SM EINVAL
+.B EINVAL
 An invalid argument was specified.
 .TP 15
-.SM EOPNOTSUPP
+.B EOPNOTSUPP
 Attempted to set index of a stripe other than stripe 0.
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_layout_ost_index_get()
+and
+.B llapi_layout_ost_index_set()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.7.0
+.\" Added in commit v2_6_51_0-23-g3d3a37c9c8
+.SH SEE ALSO
 .BR llapi_layout_alloc (3),
 .BR llapi_layout_file_open (3),
 .BR llapi_layout (7),

diff --git a/lustre/doc/llapi_layout_ost_index_reset.3 b/lustre/doc/llapi_layout_ost_index_reset.3
index e6db465..19da9c9 100644 (file)
--- a/lustre/doc/llapi_layout_ost_index_reset.3
+++ b/lustre/doc/llapi_layout_ost_index_reset.3
@@ -1,4 +1,4 @@
-.TH llapi_layout_ost_index_reset 3 "2024 Mar 27" "Lustre User API"
+.TH LLAPI_LAYOUT_OST_INDEX_RESET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
 .SH NAME
 llapi_layout_ost_index_reset \- reset OST index of all Lustre file components
 .SH SYNOPSIS
@@ -8,7 +8,6 @@ llapi_layout_ost_index_reset \- reset OST index of all Lustre file components
 .BI "int llapi_layout_ost_index_reset(struct llapi_layout *" layout );
 .fi
 .SH DESCRIPTION
-.PP
 .B llapi_layout_ost_index_reset()
 resets the starting ost_index number of all components in the specified file
 .I layout 
@@ -30,23 +29,28 @@ it is used with
 .BR llapi_layout_file_open (3)
 to create a new file for migration, mirroring, or other replication task.
 .SH RETURN VALUES
-.LP
 .B llapi_layout_ost_index_reset()
 returns 0 on success, or a negative error if an error occurred (in which case,
 errno is set appropriately).
 .SH ERRORS
 .TP 15
-.SM EINVAL
+.B EINVAL
 An invalid argument was specified.
 .TP 15
-.SM ENOENT
+.B ENOENT
 The layout does not have any valid components.
 .TP 15
-.SM ENOMEM
+.B ENOMEM
 Insufficient memory to complete operation.
-.SH "SEE ALSO"
-.BR llapi_layout (7),
+.SH AVAILABILITY
+.B llapi_layout_ost_index_reset()
+is part of the
+.BR lustre (7)
+user application interface library since release 2.7.0
+.\" Added in commit v2_6_51_0-23-g3d3a37c9c8
+.SH SEE ALSO
 .BR llapi_layout_alloc (3),
 .BR llapi_layout_file_open (3),
 .BR llapi_layout_ost_index_set (3),
+.BR llapi_layout (7),
 .BR lustreapi (7)

diff --git a/lustre/doc/llapi_layout_pattern_get.3 b/lustre/doc/llapi_layout_pattern_get.3
index 56385d4..d7c8936 100644 (file)
--- a/lustre/doc/llapi_layout_pattern_get.3
+++ b/lustre/doc/llapi_layout_pattern_get.3
@@ -1,17 +1,17 @@
-.TH llapi_layout_pattern_get 3 "2013 Oct 31" "Lustre User API"
+.TH LLAPI_LAYOUT_PATTERN_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
 .SH NAME
-llapi_layout_pattern_get, llapi_layout_pattern_set \- get or set the
-RAID striping pattern of a Lustre file
+llapi_layout_pattern_get, llapi_layout_pattern_set \- get or set the RAID striping pattern of a Lustre file
 .SH SYNOPSIS
 .nf
 .B #include <lustre/lustreapi.h>
 .PP
-.BI "int llapi_layout_pattern_get(const struct llapi_layout *" layout ", uint64_t *" pattern );
+.BI "int llapi_layout_pattern_get(const struct llapi_layout *" layout ,
+.BI "                             uint64_t *" pattern );
 .PP
-.BI "int llapi_layout_pattern_set(struct llapi_layout *" layout ", uint64_t " pattern );
+.BI "int llapi_layout_pattern_set(struct llapi_layout *" layout ,
+.BI "                             uint64_t " pattern );
 .fi
 .SH DESCRIPTION
-.PP
 .B llapi_layout_pattern_get()
 stores into
 .I pattern
@@ -41,7 +41,6 @@ value of
 .B LLAPI_LAYOUT_RAID0
 means that the RAID0 pattern will be used.
 .SH RETURN VALUES
-.LP
 .B llapi_layout_pattern_get()
 and
 .B llapi_layout_pattern_set()
@@ -49,12 +48,20 @@ return 0 on success, or -1 if an error occurred (in which case, errno is
 set appropriately).
 .SH ERRORS
 .TP 15
-.SM EINVAL
+.B EINVAL
 An invalid argument was specified.
-.TP 15
-.SM EOPNOTSUPP
+.TP
+.B EOPNOTSUPP
 An unsupported RAID pattern was specified.
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_layout_pattern_get()
+and
+.B llapi_layout_pattern_set()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.7.0
+.\" Added in commit v2_6_51_0-23-g3d3a37c9c8
+.SH SEE ALSO
 .BR llapi_layout_alloc (3),
 .BR llapi_layout_file_open (3),
 .BR llapi_layout (7),

diff --git a/lustre/doc/llapi_layout_pool_name_get.3 b/lustre/doc/llapi_layout_pool_name_get.3
index d530a3a..dfb6279 100644 (file)
--- a/lustre/doc/llapi_layout_pool_name_get.3
+++ b/lustre/doc/llapi_layout_pool_name_get.3
@@ -1,19 +1,17 @@
-.TH llapi_layout_pool_name_get 3 "2013 Oct 31" "Lustre User API"
+.TH LLAPI_LAYOUT_POOL_NAME_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
 .SH NAME
-llapi_layout_pool_name_get, llapi_layout_pool_name_set \- get or set the
-OST pool name of a Lustre file
+llapi_layout_pool_name_get, llapi_layout_pool_name_set \- get or set the OST pool name of a Lustre file
 .SH SYNOPSIS
 .nf
 .B #include <lustre/lustreapi.h>
 .PP
 .BI "int llapi_layout_pool_name_get(const struct llapi_layout *" layout ",
 .BI "                               char *" pool_name ", size_t " n ");
-.sp
+.PP
 .BI "int llapi_layout_pool_name_set(struct llapi_layout *" layout ",
 .BI "                               const char *" pool_name );
 .fi
 .SH DESCRIPTION
-.PP
 .B llapi_layout_pool_name_get()
 stores into
 .I pool_name
@@ -45,7 +43,6 @@ will fail if given a
 .I layout
 with a pool that does not exist or contains no OSTs.
 .SH RETURN VALUES
-.LP
 .B llapi_layout_pool_name_get()
 and
 .B llapi_layout_pool_name_set()
@@ -53,10 +50,9 @@ return 0 on success, or -1 if an error occurred (in which case, errno is
 set appropriately).
 .SH ERRORS
 .TP 15
-.SM EINVAL
+.B EINVAL
 An invalid argument was specified.
 .SH NOTES
-.PP
 A pool defines a set of OSTs from which objects may be allocated
 to store a file in a Lustre filesystem.
 Pools are created by the filesystem administrator using the
@@ -66,9 +62,17 @@ existing pool, or to query the name of a pool that a file was created
 in. It does not provide an interface for creating or destroying pools.
 Refer to the Lustre Operations Manual for detailed background material
 about OST pools.
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_layout_pool_name_get()
+and
+.B llapi_layout_pool_name_set()
+are part of the
+.BR lustre (7)
+user application interface library since release 2.7.0
+.\" Added in commit v2_6_51_0-23-g3d3a37c9c8
+.SH SEE ALSO
+.BR lctl (1),
 .BR llapi_layout_alloc (3),
 .BR llapi_layout_file_open (3),
 .BR llapi_layout (7),
-.BR lustreapi (7),
-.BR lctl (1)
+.BR lustreapi (7)

diff --git a/lustre/doc/llapi_layout_stripe_count_get.3 b/lustre/doc/llapi_layout_stripe_count_get.3
index c095e87..35baa76 100644 (file)
--- a/lustre/doc/llapi_layout_stripe_count_get.3
+++ b/lustre/doc/llapi_layout_stripe_count_get.3
@@ -1,7 +1,6 @@
-.TH llapi_layout_stripe_count_get 3 "2013 Oct 31" "Lustre User API"
+.TH LLAPI_LAYOUT_STRIPE_COUNT_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
 .SH NAME
-llapi_layout_stripe_count_get, llapi_layout_stripe_count_set \- get or set the
-stripe count of a Lustre file
+llapi_layout_stripe_count_get, llapi_layout_stripe_count_set \- get or set the stripe count of a Lustre file
 .SH SYNOPSIS
 .nf
 .B #include <lustre/lustreapi.h>
@@ -13,7 +12,6 @@ stripe count of a Lustre file
 .BI "                                  uint64_t " stripe_count );
 .fi
 .SH DESCRIPTION
-.PP
 The stripe count of a Lustre file defines the number of OSTs used to
 store the file.
 .PP
@@ -48,9 +46,17 @@ return 0 on success, or -1 if an error occurred (in which case, errno is
 set appropriately).
 .SH ERRORS
 .TP 15
-.SM EINVAL
+.B EINVAL
 An invalid argument was specified.
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_layout_stripe_count_get()
+and
+.B llapi_layout_stripe_count_set()
+is part of the
+.BR lustre (7)
+user application interface library since release 2.7.0
+.\" Added in commit v2_6_51_0-23-g3d3a37c9c8
+.SH SEE ALSO
 .BR llapi_layout_alloc (3),
 .BR llapi_layout_file_open (3),
 .BR llapi_layout (7),

diff --git a/lustre/doc/llapi_layout_stripe_size_get.3 b/lustre/doc/llapi_layout_stripe_size_get.3
index b7937be..c7a5c5b 100644 (file)
--- a/lustre/doc/llapi_layout_stripe_size_get.3
+++ b/lustre/doc/llapi_layout_stripe_size_get.3
@@ -1,7 +1,6 @@
-.TH llapi_layout_stripe_size_get 3 "2013 Oct 31" "Lustre User API"
+.TH LLAPI_LAYOUT_STRIPE_SIZE_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions"
 .SH NAME
-llapi_layout_stripe_size_get, llapi_layout_stripe_size_set \- get or set the
-stripe size of a Lustre file
+llapi_layout_stripe_size_get, llapi_layout_stripe_size_set \- get or set the stripe size of a Lustre file
 .SH SYNOPSIS
 .nf
 .B #include <lustre/lustreapi.h>
@@ -13,7 +12,6 @@ stripe size of a Lustre file
 .BI "                                 uint64_t " stripe_size );
 .fi
 .SH DESCRIPTION
-.PP
 The stripe size indicates how much data to write to one OST before
 moving to the next OST.
 .PP
@@ -42,12 +40,20 @@ return 0 on success, or -1 if an error occurred (in which case, errno is
 set appropriately).
 .SH ERRORS
 .TP 15
-.SM EINVAL
+.B EINVAL
 An invalid argument was specified.
-.SH "SEE ALSO"
+.SH AVAILABILITY
+.B llapi_layout_stripe_size_get()
+and
+.B llapi_layout_stripe_size_set()
+is part of the
+.BR lustre (7)
+user application interface library since release 2.7.0
+.\" Added in commit v2_6_51_0-23-g3d3a37c9c8
+.SH SEE ALSO
 .BR llapi_layout_alloc (3),
-.BR llapi_layout_file_open (3),
-.BR llapi_layout_extension_size_set (3),
 .BR llapi_layout_extension_size_get (3),
+.BR llapi_layout_extension_size_set (3),
+.BR llapi_layout_file_open (3),
 .BR llapi_layout (7),
 .BR lustreapi (7)