From 351537f9861f214a7502c5c9114ef2a0ccaf45f3 Mon Sep 17 00:00:00 2001 From: Frederick Dilger Date: Fri, 23 Aug 2024 10:24:33 -0600 Subject: [PATCH] LU-4315 doc: updating llapi-[cr-f] 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_create_volatile_param.3 - llapi_fd2parent.3 - llapi_fid_parse.3 - llapi_fid_to_handle.3 - llapi_file_create.3 - llapi_file_create_foreign.3 - llapi_file_get_stripe.3 - llapi_file_open.3 Test-Parameters: trivial Signed-off-by: Frederick Dilger Change-Id: I9b9728e9611da455cb4ff61f424f4b976c533b36 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56138 Tested-by: jenkins Tested-by: Maloo Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin Reviewed-by: Andreas Dilger --- lustre/doc/llapi_create_volatile_param.3 | 100 ++++++++++++++++++------------- lustre/doc/llapi_fid_parse.3 | 34 ++++++----- lustre/doc/llapi_fid_to_handle.3 | 16 +++-- lustre/doc/llapi_file_create_foreign.3 | 33 +++++----- lustre/doc/llapi_file_get_stripe.3 | 48 ++++++++------- lustre/doc/llapi_file_open.3 | 61 +++++++++++-------- 6 files changed, 170 insertions(+), 122 deletions(-) diff --git a/lustre/doc/llapi_create_volatile_param.3 b/lustre/doc/llapi_create_volatile_param.3 index 7ba2fdf..2c4165c 100644 --- a/lustre/doc/llapi_create_volatile_param.3 +++ b/lustre/doc/llapi_create_volatile_param.3 @@ -1,54 +1,74 @@ -.TH llapi_create_volatile_param 3 "2015-01-14" "" "Lustre User API" +.TH LLAPI_CREATE_VOLATILE_PARAM 3 2024-08-23 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_create_volatile_param \- Lustre API file management .SH SYNOPSIS -.sp -\fB#include \fP -.sp -\fBint llapi_create_volatile_param(const char *\fPdirectory\fB, -int\fP mdt_idx\fB, int\fP open_flags\fB, mode_t\fP mode\fB, const -struct llapi_stripe_param *\fPstripe_param\fB)\fP -.sp -\fBint llapi_create_volatile_idx(char *\fPdirectory\fB, int\fP idx\fB, int\fP open_flags\fB)\fP -.sp -\fBint llapi_create_volatile(char *\fPdirectory\fB, int\fP mode\fB)\fP +.nf +.B #include +.PP +.BI "int llapi_create_volatile_param(const char *" directory ", int " mdt_indx , +.BI " int " open_flags ", mode_t " mode , +.BI " const struct llapi_stripe_param *" stripe_param ) +.PP +.BI "int llapi_create_volatile_idx(char *" directory ", int " idx ", int " open_flags ) +.PP +.BI "int llapi_create_volatile(char *" directory ", int " mode ) +.fi .SH DESCRIPTION -.sp These three functions create an anonymous, temporary, volatile file on a Lustre filesystem. The created file is not visible with -\fBls(1)\fP\&. Once the file is closed, or the owning process dies, the -file is permanently removed from the filesystem. -.sp +.BR ls (1). +Once the file is closed, or the owning process dies, +the file is permanently removed from the filesystem. +.P These functions will also work on a non\-Lustre filesystem, where the file is created then unlinked, leaving only the file descriptor to access the file. This is not strictly equivalent because there is a small window during which the file is visible to users (provided they -have access to the \fIdirectory\fP). -.sp -The \fIdirectory\fP parameter indicates where to create the file on the -Lustre filesystem. -.sp -\fImdt_idx\fP is the MDT index onto which to create the file. To use a -default MDT, set mdt_idx to \-1. -.sp -\fIopen_flags\fP and \fImode\fP are the same as \fBopen(2)\fP\&. -.sp -\fIstripe_param\fP describes the striping information. If it is NULL, then -the default for the directory is used. +have access to the +.IR directory ). +.P +The +.I directory +parameter indicates where to create the file on the Lustre filesystem. +.P +.I mdt_idx +is the MDT index onto which to create the file. +To use a default MDT, set mdt_idx to \-1. +.P +.I open_flags +and +.I mode +are the same as +.BR open (2). +.P +.I stripe_param +describes the striping information. +If it is NULL, then the default for the directory is used. .SH RETURN VALUE -.sp -\fBllapi_create_volatile_param\fP, \fBllapi_create_volatile_idx\fP and -\fBllapi_create_volatile\fP return a file descriptor on success. They -all return a negative errno on failure. +.BR llapi_create_volatile_param , +.B llapi_create_volatile_idx +and +.B llapi_create_volatile +return a file descriptor on success. +They all return a negative errno on failure. .SH ERRORS -.sp The negative errno can be, but is not limited to: -.sp -\fB\-EINVAL\fP An invalid value was passed. -.sp -\fB\-ENOMEM\fP Not enough memory to allocate a resource. -.SH SEE ALSO -.sp -\fBlustreapi\fP(7) -.SH AUTHOR +.TP 15 +.B -EINVAL +An invalid value was passed. +.TP 15 +.B -ENOMEM +Not enough memory to allocate a resource. +.SH AUTHORS Frank Zago for Cray Inc. +.SH AVAILABILITY +.BR llapi_create_volatile_param() , +.B llapi_create_volatile_idx() +and +.B llapi_create_volatile() +are 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 lustreapi (7) diff --git a/lustre/doc/llapi_fid_parse.3 b/lustre/doc/llapi_fid_parse.3 index 2889ba8..63cfb15 100644 --- a/lustre/doc/llapi_fid_parse.3 +++ b/lustre/doc/llapi_fid_parse.3 @@ -1,16 +1,15 @@ -.TH lustreapi 3 "2019 Sep 13" Lustre user application interface library +.TH LLAPI_FID_PARSE 3 2024-08-23 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_fid_parse \- parse ASCII FID string into binary lu_fid .SH SYNOPSIS .nf .B #include -.sp +.PP .BI "int llapi_fid_parse(const char *" fidstr ", struct lu_fid *" fid , .BI " char **" endptr ");" -.sp +.PP .fi .SH DESCRIPTION -.LP .B llapi_fid_parse() converts an ASCII FID string into a binary .B struct lu_fid @@ -31,7 +30,6 @@ stores the address of the first invalid character in .IR *endptr , or the character immediately following the end of the parsed FID. .SH RETURN VALUES -.LP .B llapi_fid_parse() returns: .TP @@ -42,24 +40,24 @@ on success, a negative errno on failure and sets errno. .SH ERRORS .TP 15 -.SM EINVAL +.B -EINVAL .I fidstr is NULL or does not contain a valid FID format. -.TP -.SM ERANGE +.TP 15 +.B -ERANGE .I fidstr contains numeric values that exceed valid values for a component. -.SH "EXAMPLE" +.SH EXAMPLES .nf #include - +\& int main(int argc, char *argv[]) { char fidstr = "[0x200000004:0x2:0x0] [0x200000400:0x345:0x0]"; struct lu_fid fid1, fid2; char *end; int rc; - +\& fidstr = argv[1]; rc = llapi_fid_parse(fidstr, &fid1, &end); if (rc < 0) { @@ -67,7 +65,7 @@ int main(int argc, char *argv[]) fidstr, strerror(-rc)); return -1; } - +\& fidstr = end; rc = llapi_fid_parse(fidstr, &fid2, &end); if (rc < 0) { @@ -75,12 +73,18 @@ int main(int argc, char *argv[]) fidstr, strerror(-rc)); return -1; } - +\& printf("fid1=" DFID " fid2="DFID"\\n", PFID(&fid1), PFID(&fid2)); return 0; } .fi -.SH "SEE ALSO" -.BR lustre (7), +.SH AVAILABILITY +.B llapi_fid_parse() +is part of the +.BR lustre (7) +user application interface library since release 2.14.0 +.\" Added in commit v2_13_50-48-g21d671b3af +.SH SEE ALSO .BR llapi_path2parent (3), +.BR lustre (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_fid_to_handle.3 b/lustre/doc/llapi_fid_to_handle.3 index 38136f3..7a2c5bf 100644 --- a/lustre/doc/llapi_fid_to_handle.3 +++ b/lustre/doc/llapi_fid_to_handle.3 @@ -1,4 +1,4 @@ -.TH llapi_fid_to_handle 3 "2022-11-08" "Lustre User API" +.TH LLAPI_FID_TO_HANDLE 3 2024-08-23" "Lustre User API" "Lustre Library Functions" .SH NAME llapi_fid_to_handle \- allocate an NFS handle for File Identifier .SH SYNOPSIS @@ -8,7 +8,6 @@ llapi_fid_to_handle \- allocate an NFS handle for File Identifier .BI "int llapi_fid_to_handle(struct file_handle **" handle ", struct lu_fid *" fid ");" .fi .SH DESCRIPTION -.PP .BR llapi_fid_to_handle() allocates an NFS file .I handle @@ -31,18 +30,23 @@ The memory allocated for and returned to the caller must be freed with .IR free (2). .SH RETURN VALUES -.LP returns 0 on success or a negative errno on failure. .SH ERRORS .TP 15 -.SM -ENOMEM +.B -ENOMEM No memory was available for allocating .IR handle . +.SH AVAILABILITY +.B llapi_fid_to_handle() +is part of the +.BR lustre (7) +user application interface library since release 2.16.0 +.\" Added in commit v2_15_52-154-gbdf7788d19 .SH SEE ALSO +.BR name_to_handle (2), +.BR open_by_handle_at (2), .BR free (3), .BR llapi_fid_parse (3), .BR llapi_fid2path (3), .BR llapi_path2fid (3), .BR lustreapi (7), -.BR name_to_handle (2) -.BR open_by_handle_at (2) diff --git a/lustre/doc/llapi_file_create_foreign.3 b/lustre/doc/llapi_file_create_foreign.3 index 2f647ed..97353e2 100644 --- a/lustre/doc/llapi_file_create_foreign.3 +++ b/lustre/doc/llapi_file_create_foreign.3 @@ -1,4 +1,4 @@ -.TH lustreapi 3 "2009 Jul 10" The Lustre user application interface library +.TH LLAPI_FILE_CREATE_FOREIGN 3 2024-08-23 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_file_create_foreign \- create a file with foreign layout on a Lustre filesystem .SH SYNOPSIS @@ -7,14 +7,13 @@ llapi_file_create_foreign \- create a file with foreign layout on a Lustre files .B #include .B #include .B #include -.sp +.PP .BI "int llapi_file_create_foreign(const char *" name ", mode_t " mode "," -.BI " __u32 " type ", __u32 " flags ", char *" foreign_lov ); -.sp +.BI " __u32 " type ", __u32 " flags , +.BI " char *" foreign_lov ); .fi .SH DESCRIPTION -.LP -.B llapi_file_create_foreign(\|) +.B llapi_file_create_foreign() creates a file with .I foreign_lov free format layout and @@ -39,12 +38,12 @@ specifies any flags for foreign layout. free-format string to be set as file layout/LOV EA. .SH RETURN VALUES .LP -.B llapi_file_create_foreign(\|) +.B llapi_file_create_foreign() return: .TP >=0 on success, for -.B llapi_file_open +.B llapi_file_open() the return value is a file descriptor. .TP <0 @@ -58,7 +57,7 @@ already exists. .SM ENOTTY .I name may not point to a Lustre filesystem. -.SH "EXAMPLE" +.SH EXAMPLES .nf #include #include @@ -69,10 +68,10 @@ may not point to a Lustre filesystem. int main(int argc, char *argv[]) { int rc; - +\& if (argc != 2) return -1; - +\& rc = llapi_file_create_foreign(argv[1], 0600, LOV_FOREIGN_TYPE_SYMLINK, 0xda05, "PUUID/CUUID"); if (rc < 0) { @@ -84,8 +83,14 @@ int main(int argc, char *argv[]) return 0; } .fi -.SH "SEE ALSO" -.BR llapi_file_open (3) +.SH AVAILABILITY +.B llapi_file_create_foreign() +is part of the +.BR lustre (7) +user application interface library since release 2.13.0 +.\" Added in commit v2_12_53-14-g6a20bdcc60 +.SH SEE ALSO +.BR open (2), +.BR llapi_file_open (3), .BR lustre (7), .BR lustreapi (7) -.BR open (2), diff --git a/lustre/doc/llapi_file_get_stripe.3 b/lustre/doc/llapi_file_get_stripe.3 index 5d74b73..9b15ed4 100644 --- a/lustre/doc/llapi_file_get_stripe.3 +++ b/lustre/doc/llapi_file_get_stripe.3 @@ -1,4 +1,4 @@ -.TH lustreapi 3 "2009 Jul 22" The Lustre user application interface library +.TH LLAPI_FILE_GET_STRIPE 3 2024-08-23 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_file_get_stripe \- get striping information for a file or a directory on a Lustre filesystem .SH SYNOPSIS @@ -7,19 +7,18 @@ llapi_file_get_stripe \- get striping information for a file or a directory on a .B #include .B #include .B #include -.sp +.PP .BI "int llapi_file_get_stripe(const char *"path ", void *"lum ); -.sp .fi .SH DESCRIPTION .LP -.B llapi_file_get_stripe(\|) +.B llapi_file_get_stripe() returns striping information for a file or a directory .I path in .I lum (which should point to a large enough memory region) in one of the following formats: - +.PP .nf struct lov_user_md_v1 { __u32 lmm_magic; @@ -31,7 +30,7 @@ struct lov_user_md_v1 { __u16 lmm_stripe_offset; struct lov_user_ost_data_v1 lmm_objects[]; } __attribute__((packed)); - +\& struct lov_user_md_v3 { __u32 lmm_magic; __u32 lmm_pattern; @@ -44,7 +43,6 @@ struct lov_user_md_v3 { struct lov_user_ost_data_v1 lmm_objects[]; } __attribute__((packed)); .fi - .TP 20 .I lmm_magic specifies the format of the returned striping information. @@ -80,7 +78,7 @@ holds the OST pool name to which the file belongs. is an array of .I lmm_stripe_count members containing per OST file information in the following format: - +.PP .nf struct lov_user_ost_data_v1 { __u64 l_object_id; @@ -103,7 +101,7 @@ holds the generation of the OST index. holds the OST index in LOV. .SH RETURN VALUES .LP -.B llapi_file_get_stripe(\|) +.B llapi_file_get_stripe() returns: .TP 0 @@ -134,63 +132,69 @@ does not point to a Lustre filesystem. memory region pointed by .I lum is not properly mapped. -.SH "EXAMPLE" +.SH EXAMPLES .nf #include #include - +\& static inline int maxint(int a, int b) { return a > b ? a : b; } - +\& static void *alloc_lum() { int v1, v3, join; - +\& v1 = sizeof(struct lov_user_md_v1) + LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1); v3 = sizeof(struct lov_user_md_v3) + LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1); - +\& return malloc(maxint(v1, v3)); } - +\& int main(int argc, char** argv) { struct lov_user_md *lum_file = NULL; int rc; int lum_size; - +\& if (argc != 2) { fprintf(stderr, "Usage: %s \\n", argv[0]); return 1; } - +\& lum_file = alloc_lum(); if (lum_file == NULL) { rc = ENOMEM; goto cleanup; } - +\& rc = llapi_file_get_stripe(argv[1], lum_file); if (rc) { rc = errno; goto cleanup; } - +\& /* stripe_size stripe_count */ printf("%d %d\\n", lum_file->lmm_stripe_size, lum_file->lmm_stripe_count); - +\& cleanup: if (lum_file != NULL) free(lum_file); - +\& return rc; } .fi -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_file_get_stripe() +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 lustre (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_file_open.3 b/lustre/doc/llapi_file_open.3 index a62a2dc..5570ff4 100644 --- a/lustre/doc/llapi_file_open.3 +++ b/lustre/doc/llapi_file_open.3 @@ -1,4 +1,4 @@ -.TH lustreapi 3 "2009 Jul 10" The Lustre user application interface library +.TH LLAPI_FILE_OPEN 3 2024-08-23 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_file_open, llapi_file_create \- open and possibly create a file or a device on a Lustre filesystem .SH SYNOPSIS @@ -7,23 +7,22 @@ llapi_file_open, llapi_file_create \- open and possibly create a file or a devic .B #include .B #include .B #include -.sp +.PP .BI "int llapi_file_open(const char *"name ", int " flags ", int " mode "," .BI " unsigned long long " stripe_size ", int " stripe_offset "," .BI " int " stripe_count ", int " stripe_pattern ); - +.PP .BI "int llapi_file_create(const char *" name ", unsigned long long " stripe_size "," .BI " int " stripe_offset ", int " stripe_count "," .BI " int " stripe_pattern ); .sp .fi .SH DESCRIPTION -.LP -.B llapi_file_create(\|) -call is equivalent to +.B llapi_file_create() +call is equivalent to .B llapi_file_open -call with -.I flags +call with +.I flags equal to .B O_CREAT|O_WRONLY and @@ -32,13 +31,13 @@ equal to .BR 0644 , followed by file close. .PP -.B llapi_file_open(\|) -opens a file with a given +.B llapi_file_open() +opens a file with a given .I name on a Lustre filesystem. .TP 15 .I flags -can be a combination of +can be a combination of .BR O_RDONLY , .BR O_WRONLY , .BR O_RDWR , @@ -55,7 +54,7 @@ can be a combination of .BR O_DIRECTORY , .BR O_NOFOLLOW , .BR O_NOATIME . - +.IP Refer to .BR open(2) man page for a detailed description. @@ -64,27 +63,31 @@ man page for a detailed description. specifies the permission bits to be used for a new file when .BR O_CREAT is used. - +.IP Refer to .BR open(2) man page for a detailed description. .TP 15 .I stripe_size -specifies stripe size in bytes and should be multiple of 64 KiB not exceeding 4 GiB. +specifies stripe size in bytes +and should be multiple of 64 KiB not exceeding 4 GiB. .TP 15 .I stripe_offset -specifies an OST index from which the file should start, -1 to use the default setting. +specifies an OST index from which the file should start, +-1 to use the default setting. .TP 15 .I stripe_count -specifies number of OSTs to stripe the file across, -1 to use the default setting. +specifies number of OSTs to stripe the file across, +-1 to use the default setting. .TP 15 .I stripe_pattern -specifies striping pattern, only LOV_PATTERN_RAID0 is available in this Lustre version, 0 to use the default setting. +specifies striping pattern, +only LOV_PATTERN_RAID0 is available in this Lustre version, +0 to use the default setting. .SH RETURN VALUES -.LP -.B llapi_file_open(\|) -and -.B llapi_file_create(\|) +.B llapi_file_open(\|) +and +.B llapi_file_create(\|) return: .TP >=0 @@ -118,7 +121,7 @@ Striping information has already been set and cannot be altered. .SM ENOTTY .I name may not point to a Lustre filesystem. -.SH "EXAMPLE" +.SH EXAMPLES .nf #include #include @@ -129,10 +132,10 @@ may not point to a Lustre filesystem. int main(int argc, char *argv[]) { int rc; - +\& if (argc != 2) return -1; - +\& rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0); if (rc < 0) { fprintf(stderr, "file creation has failed, %s\\n", strerror(-rc)); @@ -143,7 +146,15 @@ int main(int argc, char *argv[]) return 0; } .fi -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_file_open() +and +.B llapi_file_create() +are 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 open (2), .BR lustre (7), .BR lustreapi (7) -- 1.8.3.1