From c791602d1e000bacee6fa871ac15e715ed1363d1 Mon Sep 17 00:00:00 2001 From: Frederick Dilger Date: Tue, 27 Aug 2024 14:35:44 -0600 Subject: [PATCH] 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 Change-Id: Ifdf0d86e76898bf3b4e7febb40acecb8f12ad702 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56173 Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin Tested-by: jenkins Tested-by: Maloo --- lustre/doc/llapi_layout_get_by_fd.3 | 78 ++++++++++++++++-------------- lustre/doc/llapi_layout_ost_index_get.3 | 21 +++++--- lustre/doc/llapi_layout_ost_index_reset.3 | 20 +++++--- lustre/doc/llapi_layout_pattern_get.3 | 29 ++++++----- lustre/doc/llapi_layout_pool_name_get.3 | 26 +++++----- lustre/doc/llapi_layout_stripe_count_get.3 | 18 ++++--- lustre/doc/llapi_layout_stripe_size_get.3 | 22 ++++++--- 7 files changed, 127 insertions(+), 87 deletions(-) diff --git a/lustre/doc/llapi_layout_get_by_fd.3 b/lustre/doc/llapi_layout_get_by_fd.3 index 377835e..c1519f7 100644 --- 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 @@ -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 --- 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 @@ -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 --- 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 --- 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 .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 --- 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 .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 --- 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 @@ -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 --- 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 @@ -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) -- 1.8.3.1