From 219c0bec564605a96314830fd12a1e8d8d9477f0 Mon Sep 17 00:00:00 2001 From: Frederick Dilger Date: Thu, 22 Aug 2024 15:20:29 -0600 Subject: [PATCH] LU-4315 doc: updating llapi-[cha] 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_changelog_clear.3 - llapi_changelog_fini.3 - llapi_changelog_free.3 - llapi_changelog_get_fd.3 - llapi_changelog_in_buf.3 - llapi_changelog_recv.3 - llapi_changelog_set_xflags.3 - llapi_changelog_start.3 Test-Parameters: trivial Signed-off-by: Frederick Dilger Change-Id: Id2b6f92811b8ffbe23fc7a902a14360b8cf583c5 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56131 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin --- lustre/doc/llapi_changelog_clear.3 | 17 +++++++++++------ lustre/doc/llapi_changelog_get_fd.3 | 14 +++++++++----- lustre/doc/llapi_changelog_in_buf.3 | 14 +++++++++----- lustre/doc/llapi_changelog_recv.3 | 14 ++++++++++---- lustre/doc/llapi_changelog_start.3 | 30 +++++++++++++++++------------- 5 files changed, 56 insertions(+), 33 deletions(-) diff --git a/lustre/doc/llapi_changelog_clear.3 b/lustre/doc/llapi_changelog_clear.3 index afa79fc..b589bbf 100644 --- a/lustre/doc/llapi_changelog_clear.3 +++ b/lustre/doc/llapi_changelog_clear.3 @@ -1,4 +1,4 @@ -.TH llapi_changelog_clear 3 "2022-11-08" "" "Lustre User API" +.TH LLAPI_CHANGELOG_CLEAR 3 2024-08-22 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_changelog_clear \- Clear changelog records for a changelog consumer .SH SYNOPSIS @@ -9,7 +9,6 @@ llapi_changelog_clear \- Clear changelog records for a changelog consumer .BI " long long " endrec ");" .fi .SH DESCRIPTION -.PP The function .B llapi_changelog_clear() indicates that changelog records previous to @@ -29,7 +28,6 @@ MDT node using: .br .BI "lctl --device " MDT_NAME " changelog_register" .SH RETURN VALUES -.PP Return the file descriptor on success or a negative errno value on failure. .SH ERRORS .TP 15 @@ -46,11 +44,18 @@ is only accessible to the root user. An example can be found in lfs.c source file. .B lfs_changelog_clear implements the following command: -.br +.EX .BI "lfs changelog_clear " MDTNAME " " ID " " ENDREC "" -.SH "SEE ALSO" +.EE +.SH AVAILABILITY +.B llapi_changelog_clear() +is part of the +.BR lustre (7) +user application interface library since before release 2.4.0 +.\" Added in commit 2.3.53-7-gf715e4e298 +.SH SEE ALSO .BR lfs-changelog_clear (1), -.BR llapi_changelog_get_fd (3) +.BR llapi_changelog_get_fd (3), .BR llapi_changelog_in_buf (3), .BR llapi_changelog_recv (3), .BR llapi_changelog_start (3), diff --git a/lustre/doc/llapi_changelog_get_fd.3 b/lustre/doc/llapi_changelog_get_fd.3 index d178979..7640472 100644 --- a/lustre/doc/llapi_changelog_get_fd.3 +++ b/lustre/doc/llapi_changelog_get_fd.3 @@ -1,4 +1,4 @@ -.TH llapi_changelog_get_fd 3 "2022-11-08" "" "Lustre User API" +.TH LLAPI_CHANGELOG_GET_FD 3 "2024-08-22 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_changelog_get_fd \- Return the file descriptor of the changelog device .SH SYNOPSIS @@ -8,7 +8,6 @@ llapi_changelog_get_fd \- Return the file descriptor of the changelog device .BI "int llapi_changelog_get_fd(void *" priv ");" .fi .SH DESCRIPTION -.PP The function .B llapi_changelog_get_fd() returns the file descriptor of changelog char device for the instance @@ -19,16 +18,21 @@ This can be used to call on the file descriptor to get events on the changelog device. .SH RETURN VALUES -.PP Return the file descriptor on success or a negative errno value on failure. .SH ERRORS .TP 15 .SM -EINVAL .I priv argument is invalid. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_changelog_get_fd +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 poll (2), -.BR llapi_changelog_clear (3) +.BR llapi_changelog_clear (3), .BR llapi_changelog_in_buf (3), .BR llapi_changelog_recv (3), .BR llapi_changelog_start (3), diff --git a/lustre/doc/llapi_changelog_in_buf.3 b/lustre/doc/llapi_changelog_in_buf.3 index 749ca37..ae214dd 100644 --- a/lustre/doc/llapi_changelog_in_buf.3 +++ b/lustre/doc/llapi_changelog_in_buf.3 @@ -1,4 +1,4 @@ -.TH llapi_changelog_in_buf 3 "2022-11-08" "" "Lustre User API" +.TH LLAPI_CHANGELOG_IN_BUF 3 2024-08-22 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_changelog_in_buf \- Check if there is changelog records in the internal buffer .SH SYNOPSIS @@ -8,7 +8,6 @@ llapi_changelog_in_buf \- Check if there is changelog records in the internal bu .BI "int llapi_changelog_in_buf(void *" priv ");" .fi .SH DESCRIPTION -.PP The function .B llapi_changelog_in_buf() checks if there are still changelog records in the read buffer for the @@ -20,11 +19,16 @@ with .B llapi_changelog_recv() can be used to dequeue all the changelog records still in the read buffer. .SH RETURN VALUES -.PP Returns 1 if changelogs records are present in the internal read buffer, otherwise return 0. -.SH "SEE ALSO" -.BR llapi_changelog_clear (3) +.SH AVAILABILITY +.B llapi_changelog_in_buf +is part of the +.BR lustre (7) +user application interface library since release 2.13.0 +.\# Added in commit 2.12.56-87-ge215002883 +.SH SEE ALSO +.BR llapi_changelog_clear (3), .BR llapi_changelog_get_fd (3), .BR llapi_changelog_recv (3), .BR llapi_changelog_start (3), diff --git a/lustre/doc/llapi_changelog_recv.3 b/lustre/doc/llapi_changelog_recv.3 index 42b349e..4a6c9cd 100644 --- a/lustre/doc/llapi_changelog_recv.3 +++ b/lustre/doc/llapi_changelog_recv.3 @@ -1,4 +1,4 @@ -.TH llapi_changelog_recv 3 "2022-11-08" "" "Lustre User API" +.TH LLAPI_CHANGELOG_RECV 3 2024-08-22 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_changelog_recv, llapi_changelog_free \- Read and free a changelog records .SH SYNOPSIS @@ -10,7 +10,6 @@ llapi_changelog_recv, llapi_changelog_free \- Read and free a changelog records .BI "int llapi_changelog_free(struct changelog_rec **" rech ");" .fi .SH DESCRIPTION -.PP The function .B llapi_changelog_recv() allocates and reads the next changelog record @@ -54,9 +53,16 @@ Failed to read the changelog record on the MDT. An example can be found for in lfs.c source file. .B lfs_changelog() implements the following command: -.br +.EX .BI "lfs changelog [--follow] " MDTNAME " [" STARTREC " [" ENDREC "]]" -.SH "SEE ALSO" +.EE +.SH AVAILABILITY +.B llapi_changelog_recv +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 lfs-changelog (1), .BR llapi_changelog_clear (3), .BR llapi_changelog_get_fd (3), diff --git a/lustre/doc/llapi_changelog_start.3 b/lustre/doc/llapi_changelog_start.3 index dd4505c..df6d21e 100644 --- a/lustre/doc/llapi_changelog_start.3 +++ b/lustre/doc/llapi_changelog_start.3 @@ -1,4 +1,4 @@ -.TH llapi_changelog_start 3 "2022-11-08" "" "Lustre User API" +.TH LLAPI_CHANGELOG_START 3 2024-08-22 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_changelog_start, llapi_changelog_set_xflags, llapi_changelog_fini \- Initialize and clean a read instance for MDT changelogs .SH SYNOPSIS @@ -14,7 +14,6 @@ llapi_changelog_start, llapi_changelog_set_xflags, llapi_changelog_fini \- Initi .BI "int llapi_changelog_fini(void **" priv ");" .fi .SH DESCRIPTION -.PP The function .B llapi_changelog_start() initializes a new instance @@ -23,7 +22,7 @@ to read MDT changelogs. It opens the changelog char device corresponding to the MDT's name given by .I device (e.g: "lustrefs-MDT0000"). -.br +.P A changelog starting point can be specified with .I startrec record number. @@ -40,18 +39,17 @@ mask. .PP .B enum changelog_send_flag values: -.nf -.LP +.EX CHANGELOG_FLAG_FOLLOW CHANGELOG_FLAG_BLOCK CHANGELOG_FLAG_JOBID CHANGELOG_FLAG_EXTRA_FLAGS -.fi +.EE .TP CHANGELOG_FLAG_FOLLOW Use changelog follow mode: .B llapi_changelog_recv() -will not return when all records have been read. Instead it will block until a +will not return when all records have been read. Instead it will block until a new record is available. It avoids restarting an instance and re-scan for newer changelogs. .TP @@ -78,13 +76,12 @@ parameter. .PP .B enum changelog_send_extra_flag values: -.nf -.LP +.EX CHANGELOG_EXTRA_FLAG_UIDGID CHANGELOG_EXTRA_FLAG_NID CHANGELOG_EXTRA_FLAG_OMODE CHANGELOG_EXTRA_FLAG_XATTR -.fi +.EE .TP CHANGELOG_EXTRA_FLAG_UIDGID Pack uid/gid into the changelog record @@ -123,11 +120,18 @@ is only accessible to the root user. An example can be found for in lfs.c source file. .B lfs_changelog() implements the following command: -.br +.EX .BI "lfs changelog [--follow] " MDTNAME " [" STARTREC " [" ENDREC "]]" -.SH "SEE ALSO" +.EE +.SH AVAILABILITY +.B llapi_changelog_start +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 lfs-changelog (1), -.BR llapi_changelog_clear (3) +.BR llapi_changelog_clear (3), .BR llapi_changelog_get_fd (3), .BR llapi_changelog_in_buf (3), .BR llapi_changelog_recv (3), -- 1.8.3.1