From 59bbec814c4ee5cac2c52fabde6ea1f39d072c06 Mon Sep 17 00:00:00 2001 From: Frederick Dilger Date: Tue, 27 Aug 2024 11:58:46 -0600 Subject: [PATCH] LU-4315 doc: updating llapi-[i-l] 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_ioctl.3 - llapi_ladvise.3 - llapi_layout.7 - llapi_layout_alloc.3 - llapi_layout_comp_add.3 - llapi_layout_comp_del.3 - llapi_layout_comp_extent_get.3 - llapi_layout_comp_extent_set.3 - llapi_layout_comp_flags_clear.3 - llapi_layout_comp_flags_get.3 - llapi_layout_comp_flags_set.3 - llapi_layout_comp_id_get.3 - llapi_layout_comp_use.3 - llapi_layout_comp_use_id.3 - llapi_layout_extension_size_get.3 - llapi_layout_extension_size_set.3 - llapi_layout_file_comp_add.3 - llapi_layout_file_comp_del.3 - llapi_layout_file_create.3 - llapi_layout_file_open.3 Test-Parameters: trivial Signed-off-by: Frederick Dilger Change-Id: I9e475fa6f170a52000b220e5e90f7e6c39bee737 Reviewed-on: https://review.whamcloud.com/c/fs/lustre-release/+/56171 Reviewed-by: Andreas Dilger Reviewed-by: Arshad Hussain Reviewed-by: Oleg Drokin Tested-by: jenkins Tested-by: Maloo --- lustre/doc/llapi_ioctl.3 | 28 +++++---- lustre/doc/llapi_ladvise.3 | 44 +++++++------- lustre/doc/llapi_layout.7 | 87 +++++++++++++++------------- lustre/doc/llapi_layout_alloc.3 | 29 +++++----- lustre/doc/llapi_layout_comp_add.3 | 27 +++++---- lustre/doc/llapi_layout_comp_extent_get.3 | 23 +++++--- lustre/doc/llapi_layout_comp_flags_get.3 | 20 ++++--- lustre/doc/llapi_layout_comp_id_get.3 | 18 +++--- lustre/doc/llapi_layout_comp_use.3 | 19 +++--- lustre/doc/llapi_layout_comp_use_id.3 | 19 +++--- lustre/doc/llapi_layout_extension_size_get.3 | 37 +++++++----- lustre/doc/llapi_layout_file_comp_add.3 | 19 +++--- lustre/doc/llapi_layout_file_comp_del.3 | 24 ++++---- lustre/doc/llapi_layout_file_create.3 | 26 +++++---- 14 files changed, 245 insertions(+), 175 deletions(-) diff --git a/lustre/doc/llapi_ioctl.3 b/lustre/doc/llapi_ioctl.3 index 9059aa4..343183e 100644 --- a/lustre/doc/llapi_ioctl.3 +++ b/lustre/doc/llapi_ioctl.3 @@ -1,13 +1,13 @@ -.TH lustreapi 3 "2023 Mar 22" Lustre user application interface library +.TH LLAPI_IOCTL 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_ioctl \- call ioctl() with possible command remapping .SH SYNOPSIS .nf .B #include -.sp +.PP .BI "int llapi_ioctl(int " fd ", unsigned int " cmd ", void *" buf ");" +.fi .SH DESCRIPTION -.LP .B llapi_ioctl() calls the .BR ioctl (2) @@ -18,7 +18,6 @@ system call with the supplied arguments. However, if the ioctl() returns has been remapped from an older ioctl command number the ioctl() call will be retried with the old ioctl command number. .SH RETURN VALUES -.LP .B llapi_ioctl() typically returns: .TP @@ -35,35 +34,40 @@ and errno as appropriate for the number, and argument .I buf passed. -.SH "EXAMPLE" +.SH EXAMPLES .nf #include - +\& int main(int argc, char *argv[]) { unsigned long group = 1234; int rc, fd; - +\& fd = open(argv[1], O_RDONLY); if (rc < 0) { fprintf(stderr, "error opening file '%s': %s\\n", argv[1], strerror(errno)); return -1; } - +\& rc = llapi_ioctl(fd, LL_IOC_GROUP_LOCK, &group); if (rc < 0) { fprintf(stderr, "%s: ioctl error: %s\\n", argv[1], strerror(errno)); return rc; } - +\& printf("%s: locked with group %lu\\n", argv[1], group); return 0; } .fi -.SH "SEE ALSO" -.BR lustre (7), +.SH AVAILABILITY +.B llapi_ioctl() +is part of the +.BR lustre (7) +user application interface library since release 2.16.0 +.\" Added in commit v2_15_55-173-g594b780062 +.SH SEE ALSO .BR ioctl (2), +.BR lustre (7), .BR lustreapi (7) - diff --git a/lustre/doc/llapi_ladvise.3 b/lustre/doc/llapi_ladvise.3 index 0d9bb5c..8caa942 100644 --- a/lustre/doc/llapi_ladvise.3 +++ b/lustre/doc/llapi_ladvise.3 @@ -1,17 +1,15 @@ -.TH llapi_ladvise 3 "2015 Dec 15" "Lustre User API" +.TH LLAPI_LADVISE 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_ladvise \- give IO advice/hints on a Lustre file to the server .SH SYNOPSIS .nf .B #include -.sp +.PP .BI "int llapi_ladvise(int " fd ", unsigned long long " flags , .BI " int " num_advise ", .BI " struct llapi_lu_ladvise *" ladvise ");" -.sp .fi .SH DESCRIPTION -.LP .B llapi_ladvise() passes an array of .I num_advise @@ -38,7 +36,7 @@ elements is an .B llapi_lu_ladvise structure, which contains the following fields: .PP -.in +4n +.RS 3.5 .nf struct llapi_lu_ladvise { __u16 lla_advice; /* advice type */ @@ -50,7 +48,7 @@ struct llapi_lu_ladvise { __u32 lla_value4; }; .fi -.in +.RE .TP .I lla_advice specifies the advice for the given file range, currently one of: @@ -78,28 +76,28 @@ additional arguments for future advice types and should be set to zero if not explicitly required for a given advice type. Advice-specific names for these fields follow. .TP -.IR lla_lockahead_mode +.I lla_lockahead_mode When using LU_ADVISE_LOCKAHEAD, the 'lla_value1' field is used to communicate the requested lock mode, and can be referred to as lla_lockahead_mode. .TP -.IR lla_peradvice_flags +.I lla_peradvice_flags When using advices which support them, the 'lla_value2' field is used to communicate per-advice flags and can be referred to as lla_peradvice_flags. Both LF_ASYNC and LF_UNSET are supported as peradvice flags. .TP -.IR lla_lockahead_result +.I lla_lockahead_result When using LU_ADVISE_LOCKAHEAD, the 'lla_value3' field is used to -communicate the result of the request, and can be referred to as lla_lockahead_result. -.PP +communicate the result of the request, +and can be referred to as lla_lockahead_result. .PP .B llapi_ladvise() forwards the advice to Lustre servers without guaranteeing how and when servers will react to the advice. Actions may or may not be triggered when the advices are received, depending on the type of the advice as well as the real-time decision of the affected server-side components. - +.PP Typical usage of .B llapi_ladvise() is to enable applications and users (via @@ -111,14 +109,14 @@ with big linear reads before the random IO is a net benefit. Fetching that data into each client cache with .B fadvise() may not be, due to much more data being sent to the clients. - +.PP LU_LADVISE_LOCKAHEAD merits a special comment. While it is possible and encouraged to use it directly in your application to avoid lock contention (primarily for writing to a single file from multiple clients), it will also be available in the MPI-I/O / MPICH library from ANL for use with the i/o aggregation mode of that library. This is intended (eventually) to be the primary way this feature is used. - +.PP While conceptually similar to the .BR posix_fadvise (2) and Linux @@ -131,27 +129,31 @@ are client side mechanisms that do not pass advice to the filesystem, while .B llapi_ladvise() sends advice or hints to one or more Lustre servers on which the file is stored. In some cases it may be desirable to use both interfaces. -.PP .SH RETURN VALUES -.PP .B llapi_ladvise() return 0 on success, or -1 if an error occurred (in which case, errno is set appropriately). .SH ERRORS .TP 15 -.SM ENOMEM +.B ENOMEM Insufficient memory to complete operation. .TP -.SM EINVAL +.B EINVAL One or more invalid arguments are given. .TP -.SM EFAULT +.B EFAULT memory region pointed by .I ladvise is not properly mapped. .TP -.SM ENOTSUPP +.B ENOTSUPP Advice type is not supported. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_ladvise() +is part of the +.BR lustre (7) +user application interface library since release 2.9.0 +.\" Added in commit v2_8_51-30-ge14246641c +.SH SEE ALSO .BR lfs-ladvise (1), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout.7 b/lustre/doc/llapi_layout.7 index ee796bf..a52ca6c 100644 --- a/lustre/doc/llapi_layout.7 +++ b/lustre/doc/llapi_layout.7 @@ -1,11 +1,11 @@ -.TH llapi_layout 7 "2013 Oct 31" "Lustre User API" +.TH LLAPI_LAYOUT 7 2024-08-27 "Lustre User API" "Lustre Miscellaneous Information" .SH NAME llapi_layout \- abstract interface to the layout of a Lustre file .SH SYNOPSIS .nf .B #include +.fi .SH DESCRIPTION -.LP The .B llapi_layout family of functions provides an abstract interface to @@ -91,31 +91,35 @@ Create the file using .IP \[bu] Free the layout memory using .BR llapi_layout_free (3). -.SH "EXAMPLE" +.SH BUGS +Setting the OST index number is only supported for stripe number 0. +.P +The RAID pattern may only be set to 0. +.SH EXAMPLES Example 1: Create file with specified layout, then query the layout attributes. .PP .nf { /* Allocate layout */ struct llapi_layout *layout = llapi_layout_alloc(); - +\& /* Set attributes of layout */ llapi_layout_stripe_count_set(layout, count); llapi_layout_stripe_size_set(layout, size); - +\& /* Create file with specified layout */ fd = llapi_layout_file_create(path, 0, 0640, layout); - +\& /* Free layout */ llapi_layout_free(layout); - +\& /* Retrieve layout from file */ layout = llapi_layout_get_by_path(path, 0); - +\& /* Get attributes of layout */ llapi_layout_stripe_size_get(layout, &size), llapi_layout_stripe_count_get(layout, &count); - +\& /* Free layout */ llapi_layout_free(layout); } @@ -126,29 +130,29 @@ Example 2: Create file with composite layout. .nf { struct llapi_layout *head, *comp; - +\& /* Create first component */ head = llapi_layout_alloc(); llapi_layout_stripe_count_set(head, 1); llapi_layout_stripe_size_set(head, 1048576); llapi_layout_comp_extent_set(NULL, head, 0, 2097152); //[0, 2M) - +\& /* Create the second component */ comp = llapi_layout_alloc(); llapi_layout_comp_add(head, comp); llapi_layout_comp_extent_set(head, comp, 2097152, 67108864); //[2M, 64M) llapi_layout_stripe_count_set(comp, 4); - +\& /* Create the third component */ comp = llapi_layout_alloc(); llapi_layout_comp_add(head, comp); llapi_layout_comp_extent_set(head, comp, 67108864, (uint64_t)-1); //[64M, EOF) llapi_layout_stripe_count_set(comp, LLAPI_LAYOUT_WIDE); - +\& /* Create file with specified composite layout */ fd = llapi_layout_file_create(path, 0, 0640, head); - +\& /* Free layout */ llapi_layout_free(head); } @@ -160,35 +164,48 @@ Example 3: Traverse components of a composite layout. { /* Retrieve composite layout from file */ layout = llapi_layout_get_by_path(path, 0); - +\& /* Move cursor to the first component */ rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST); - +\& /* Traverse all components */ while (rc == 0) { /* Get attributes of each component */ llapi_layout_stripe_count_get(comp, &count); llapi_layout_stripe_size_get(comp, &size); llapi_layout_comp_extent_get(layout, &start, &end); - +\& /* Advance cursor */ rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT); }; - +\& /* Free layout */ llapi_layout_free(layout); } .fi - -.SH "BUGS" -Setting the OST index number is only supported for stripe number 0. - -The RAID pattern may only be set to 0. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_layout +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 lfs (1), +.BR lfs-setstripe (1), .BR open (2), -.BR lustre (7), -.BR lustreapi (7), .BR llapi_layout_alloc (3), +.BR llapi_layout_comp_add (3), +.BR llapi_layout_comp_del (3), +.BR llapi_layout_comp_extent_get (3), +.BR llapi_layout_comp_extent_set (3), +.BR llapi_layout_comp_flags_clear (3), +.BR llapi_layout_comp_flags_get (3), +.BR llapi_layout_comp_flags_set (3), +.BR llapi_layout_comp_id_get (3), +.BR llapi_layout_comp_use (3), +.BR llapi_layout_comp_use_id (3), +.BR llapi_layout_file_comp_add (3), +.BR llapi_layout_file_comp_del (3), .BR llapi_layout_file_create (3), .BR llapi_layout_file_open (3), .BR llapi_layout_free (3), @@ -197,8 +214,8 @@ The RAID pattern may only be set to 0. .BR llapi_layout_get_by_path (3), .BR llapi_layout_get_by_xattr (3), .BR llapi_layout_ost_index_get (3), -.BR llapi_layout_ost_index_set (3), .BR llapi_layout_ost_index_reset (3), +.BR llapi_layout_ost_index_set (3), .BR llapi_layout_pattern_get (3), .BR llapi_layout_pattern_set (3), .BR llapi_layout_pool_name_get (3), @@ -207,17 +224,5 @@ The RAID pattern may only be set to 0. .BR llapi_layout_stripe_count_set (3), .BR llapi_layout_stripe_size_get (3), .BR llapi_layout_stripe_size_set (3), -.BR llapi_layout_comp_extent_get (3), -.BR llapi_layout_comp_extent_set (3), -.BR llapi_layout_comp_flags_get (3), -.BR llapi_layout_comp_flags_set (3), -.BR llapi_layout_comp_flags_clear (3), -.BR llapi_layout_comp_id_get (3), -.BR llapi_layout_comp_add (3), -.BR llapi_layout_comp_del (3), -.BR llapi_layout_comp_use (3), -.BR llapi_layout_comp_use_id (3), -.BR llapi_layout_file_comp_add (3), -.BR llapi_layout_file_comp_del (3), -.BR lfs (1), -.BR lfs-setstripe (1) +.BR lustre (7), +.BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_alloc.3 b/lustre/doc/llapi_layout_alloc.3 index 3d1160e..8a5f7a4 100644 --- a/lustre/doc/llapi_layout_alloc.3 +++ b/lustre/doc/llapi_layout_alloc.3 @@ -1,19 +1,15 @@ -.TH llapi_layout_alloc 3 "2013 Oct 31" "Lustre User API" +.TH LLAPI_LAYOUT_ALLOC 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME -llapi_layout_alloc, llapi_layout_free \- allocate and destroy -.B struct llapi_layout -objects. +llapi_layout_alloc, llapi_layout_free \- allocate and destroy struct llapi_layout objects. .SH SYNOPSIS .nf .B #include -.sp +.PP .BI "struct llapi_layout *llapi_layout_alloc(void);" -.sp +.PP .BI "void llapi_layout_free(struct llapi_layout *"layout ); -.sp .fi .SH DESCRIPTION -.LP .B llapi_layout_alloc() returns a pointer to a newly-allocated .BR "struct llapi_layout" . @@ -44,21 +40,28 @@ when it is no longer needed. frees the memory associated with .IR layout . .SH RETURN VALUES -.PP .B llapi_layout_alloc() returns a valid pointer on success or .B NULL on failure with .B errno -set to an appropriate error code. -.sp +set to an approporiate error code. +.PP .B llapi_layout_free() returns no value. .SH ERRORS .TP 15 -.SM ENOMEM +.B ENOMEM Insufficient storage space is available. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_layout_alloc() +and +.B llapi_layout_free() +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_create (3), .BR llapi_layout (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_add.3 b/lustre/doc/llapi_layout_comp_add.3 index f91692f..e279f38 100644 --- a/lustre/doc/llapi_layout_comp_add.3 +++ b/lustre/doc/llapi_layout_comp_add.3 @@ -1,19 +1,17 @@ -.TH llapi_layout_comp_add 3 "2017 Apr 7" "Lustre User API" +.TH LLAPI_LAYOUT_COMP_ADD 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME -llapi_layout_comp_add, llapi_layout_comp_del \- add or delete a layout -component into/from the layout. +llapi_layout_comp_add, llapi_layout_comp_del \- add or delete a layout component into/from the layout. .SH SYNOPSIS .nf .B #include .PP -.BI "int llapi_layout_comp_add(struct llapi_layout *" layout ", +.BI "int llapi_layout_comp_add(struct llapi_layout *" layout , .BI " struct llapi_layout *" comp ); .PP -.BI "int llapi_layout_comp_del(struct llapi_layout *" layout ", +.BI "int llapi_layout_comp_del(struct llapi_layout *" layout , .BI " struct llapi_layout *" comp ); .fi .SH DESCRIPTION -.PP A composite layout is made of several layout components. .PP .BR llapi_layout_comp_add (3) @@ -39,7 +37,6 @@ deletes the layout component from the in-memory .IR layout , but does not delete the component from an existing file layout on the MDT. -.PP .SH RETURN VALUES .B llapi_layout_comp_add() and @@ -49,13 +46,21 @@ return 0 on success, or -1 if an error occurred (in which case, is set appropriately). .SH ERRORS .TP 15 -.SM EINVAL +.B EINVAL An invalid argument was specified. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_layout_comp_add() +and +.B llapi_layout_comp_del() +are part of the +.BR lustre (7) +user application interface library since release 2.10.0. +.\" Added in commit v2_9_55_0-18-gc4702b7443 +.SH SEE ALSO .BR llapi_layout_alloc (3), -.BR llapi_layout_free (3), -.BR llapi_layout_file_open (3), .BR llapi_layout_file_comp_add (3), .BR llapi_layout_file_comp_del (3), +.BR llapi_layout_file_open (3), +.BR llapi_layout_free (3), .BR llapi_layout (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_extent_get.3 b/lustre/doc/llapi_layout_comp_extent_get.3 index c2b9dd7..2487b11 100644 --- a/lustre/doc/llapi_layout_comp_extent_get.3 +++ b/lustre/doc/llapi_layout_comp_extent_get.3 @@ -1,7 +1,6 @@ -.TH llapi_layout_comp_extent_get 3 "2017 Apr 7" "Lustre User API" +.TH LLAPI_LAYOUT_COMP_EXTENT_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME -llapi_layout_comp_extent_get, llapi_layout_comp_extent_set \- get or set the -extent of a layout component. +llapi_layout_comp_extent_get, llapi_layout_comp_extent_set \- get or set the extent of a layout component. .SH SYNOPSIS .nf .B #include @@ -13,7 +12,6 @@ extent of a layout component. .BI " uint64_t " start ", uint64_t "end ); .fi .SH DESCRIPTION -.PP The extent [start, end) defines the range of a layout component. .PP .BR llapi_layout_comp_extent_get (3) @@ -25,9 +23,10 @@ and .IR end . .PP .BR llapi_layout_comp_extent_set (3) -sets the extent [\fIstart\fR, \fIend\fR) to the current component of +sets the extent +.RI [ start ", " end ) +to the current component of .IR layout . -.PP .SH RETURN VALUES .B llapi_layout_comp_extent_get() and @@ -36,9 +35,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_comp_extent_get() +and +.B llapi_layout_comp_extent_set() +are part of the +.BR lustre (7) +user application interface library since release 2.10.0 +.\" Added in commit v2_9_55_0-18-gc4702b7443 +.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_comp_flags_get.3 b/lustre/doc/llapi_layout_comp_flags_get.3 index f20bffb..bf71a8f 100644 --- a/lustre/doc/llapi_layout_comp_flags_get.3 +++ b/lustre/doc/llapi_layout_comp_flags_get.3 @@ -1,8 +1,6 @@ -.TH llapi_layout_comp_flags_get 3 "2017 Apr 7" "Lustre User API" +.TH LLAPI_LAYOUT_COMP_FLAGS_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME -llapi_layout_comp_flags_get, llapi_layout_comp_flags_set, -llapi_layout_comp_flags_clear \- get, set or clear the flags of a layout -component. +llapi_layout_comp_flags_get, llapi_layout_comp_flags_set, llapi_layout_comp_flags_clear \- get, set or clear the flags of a layout component. .SH SYNOPSIS .nf .B #include @@ -17,7 +15,6 @@ component. .BI " uint32_t " flags ); .fi .SH DESCRIPTION -.PP Layout component flags are used to indicate the status of the component, only LCME_FL_INIT is supported now, which indicates the OST objects of the component have been initialized. @@ -44,9 +41,18 @@ 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 +.BR llapi_layout_comp_flags_get(), +.B llapi_layout_comp_flags_set() +and +.B llapi_layout_comp_flags_clear() +are part of the +.BR lustre (7) +user application interface library since release 2.10.0 +.\" Added in commit v2_9_55_0-18-gc4702b7443 +.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_comp_id_get.3 b/lustre/doc/llapi_layout_comp_id_get.3 index fc2a992..71421e9 100644 --- a/lustre/doc/llapi_layout_comp_id_get.3 +++ b/lustre/doc/llapi_layout_comp_id_get.3 @@ -1,6 +1,6 @@ -.TH llapi_layout_comp_id_get 3 "2017 Apr 7" "Lustre User API" +.TH LLAPI_LAYOUT_COMP_ID_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME -llapi_layout_comp_id_get \- get the ID of a layout component. +llapi_layout_comp_id_get \- get the ID of a layout component. .SH SYNOPSIS .nf .B #include @@ -9,7 +9,6 @@ llapi_layout_comp_id_get \- get the ID of a layout component. .BI " uint32_t *" comp_id ); .fi .SH DESCRIPTION -.PP Return the unique numeric ID .I comp_id of the currently active component of @@ -19,17 +18,22 @@ within the layout of each file, and no age, ordering, relative position, or other semantics are implied by the component ID. If a file's layout is modified a large number of times, the component ID may be re-used but will always be unique within a single file's layout. -.PP .SH RETURN VALUES Return 0 on success. Return -1 if an error occurred and set errno appropriately. .SH ERRORS .TP 15 -.SM EINVAL +.B EINVAL An invalid argument was specified. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_layout_comp_id_get() +is part of the +.BR lustre (7) +user application interface library since release 2.10.0 +.\" Added in commit v2_9_55_0-18-gc4702b7443 +.SH SEE ALSO .BR llapi_layout_alloc (3), -.BR llapi_layout_file_open (3), .BR llapi_layout_comp_use_id (3), +.BR llapi_layout_file_open (3), .BR llapi_layout (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_use.3 b/lustre/doc/llapi_layout_comp_use.3 index fedf3e9..f9a279c 100644 --- a/lustre/doc/llapi_layout_comp_use.3 +++ b/lustre/doc/llapi_layout_comp_use.3 @@ -1,4 +1,4 @@ -.TH llapi_layout_comp_use 3 "2017 Apr 7" "Lustre User API" +.TH LLAPI_LAYOUT_COMP_USE 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_layout_comp_use \- change current component to relative position .SH SYNOPSIS @@ -9,7 +9,6 @@ llapi_layout_comp_use \- change current component to relative position .BI " enum llapi_layout_comp_use *" pos ); .fi .SH DESCRIPTION -.PP Changes the currently active component of .I layout to the relative position given by @@ -36,15 +35,21 @@ Otherwise, if an error occurred -1 is returned and is set appropriately. .SH ERRORS .TP 15 -.SM EINVAL +.B EINVAL An invalid argument was specified. -.TP 15 -.SM ENOENT +.TP +.B ENOENT No such component ID exists. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_layout_comp_use() +is part of the +.BR lustre (7) +user application interface library since release 2.10.0 +.\" Added in commit v2_9_55_0-18-gc4702b7443 +.SH SEE ALSO .BR llapi_layout_alloc (3), -.BR llapi_layout_file_open (3), .BR llapi_layout_comp_del (3), .BR llapi_layout_comp_use_id (3), +.BR llapi_layout_file_open (3), .BR llapi_layout (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_use_id.3 b/lustre/doc/llapi_layout_comp_use_id.3 index b9d2fe5..158eb4b 100644 --- a/lustre/doc/llapi_layout_comp_use_id.3 +++ b/lustre/doc/llapi_layout_comp_use_id.3 @@ -1,4 +1,4 @@ -.TH llapi_layout_comp_use_id 3 "2017 Apr 7" "Lustre User API" +.TH LLAPI_LAYOUT_COMP_USE_ID 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_layout_comp_use_id \- set currently active component to given ID .SH SYNOPSIS @@ -9,7 +9,6 @@ llapi_layout_comp_use_id \- set currently active component to given ID .BI " uint32_t *" comp_id ); .fi .SH DESCRIPTION -.PP Sets currently active component of .I layout to the component with specified @@ -20,16 +19,22 @@ Return 0 on success. Otherwise, if an error occurred -1 is returned and is set appropriately. .SH ERRORS .TP 15 -.SM ENOENT +.B ENOENT No such component ID exists. -.TP 15 -.SM EINVAL +.TP +.B EINVAL An invalid argument was specified. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_layout_comp_use_id() +is part of the +.BR lustre (7) +user application interface library since release 2.10.0 +.\" Added in commit v2_9_55_0-18-gc4702b7443 +.SH SEE ALSO .BR llapi_layout_alloc (3), -.BR llapi_layout_file_open (3), .BR llapi_layout_comp_del (3), .BR llapi_layout_comp_id_get (3), .BR llapi_layout_comp_use (3), +.BR llapi_layout_file_open (3), .BR llapi_layout (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_extension_size_get.3 b/lustre/doc/llapi_layout_extension_size_get.3 index 5a78f92..a725744 100644 --- a/lustre/doc/llapi_layout_extension_size_get.3 +++ b/lustre/doc/llapi_layout_extension_size_get.3 @@ -1,7 +1,6 @@ -.TH llapi_layout_extension_size_get 3 "2019 May 23" "Lustre User API" +.TH LLAPI_LAYOUT_EXTENSION_SIZE_GET 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME -llapi_layout_extension_size_get, llapi_layout_extension_size_set \- get or set -the extension size of an extension component of a Lustre file +llapi_layout_extension_size_get, llapi_layout_extension_size_set \- get or set the extension size of an extension component of a Lustre file .SH SYNOPSIS .nf .B #include @@ -13,18 +12,22 @@ the extension size of an extension component of a Lustre file .BI " uint64_t " ext_size ); .fi .SH DESCRIPTION -.PP The extension size is the unit of increase the previous component size when -writing within the region of the current extension component. At the time of the -change the OSTs of the previous component layout are checked if they have -at least \fIext_size\fR free space. In case there is not enough free space, +writing within the region of the current extension component. +At the time of the change the OSTs of the previous component layout +are checked if they have at least +.I ext_size +free space. In case there is not enough free space, the space covered by the extension component spills over to the next component -(see examples in \fBlfs-setstripe (1)\fR). +(see examples in +.BR lfs-setstripe (1)). .PP In case of a random write to a middle of the extension component, the extension happens from the beginning of the extension component up to the current writing -position plus the \fIext_size\fR. However, the check for low space is still -done for the \fIext_size\fR. +position plus the +.IR ext_size . +However, the check for low space is still done for the +.IR ext_size . .PP .B llapi_layout_extension_size_get() stores into @@ -45,13 +48,21 @@ 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_extension_size_get() +and +.B llapi_layout_extension_size_set() +are part of the +.BR lustre (7) +user application interface library since release 2.13.0. +.\" Added in commit v2_12_55-82-gfed241911f +.SH SEE ALSO .BR lfs-setstripe (1), .BR llapi_layout_alloc (3), .BR llapi_layout_file_open (3), -.BR llapi_layout_stripe_size_set (3), .BR llapi_layout_stripe_size_get (3), +.BR llapi_layout_stripe_size_set (3), .BR llapi_layout (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_file_comp_add.3 b/lustre/doc/llapi_layout_file_comp_add.3 index 0d90965..30ae496 100644 --- a/lustre/doc/llapi_layout_file_comp_add.3 +++ b/lustre/doc/llapi_layout_file_comp_add.3 @@ -1,7 +1,6 @@ -.TH llapi_layout_file_comp_add 3 "2017 Apr 7" "Lustre User API" +.TH LLAPI_LAYOUT_FILE_COMP_ADD 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME -llapi_layout_file_comp_add \- add one or more components into an -existing file. +llapi_layout_file_comp_add \- add one or more components into an existing file. .SH SYNOPSIS .nf .B #include @@ -10,12 +9,10 @@ existing file. .BI " const struct llapi_layout *" layout ); .fi .SH DESCRIPTION -.PP Add component(s) specified in .I layout into the existing file .IR path . -.PP .SH RETURN VALUES Return 0 on success, or -1 if an error occurred (in which case, errno is set appropriately). @@ -24,13 +21,19 @@ set appropriately). .SM EINVAL An invalid argument was specified. .TP -.SM ENOENT +.B ENOENT .I path doesn't exist. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_layout_file_comp_add() +is part of the +.BR lustre (7) +user application interface library since release 2.10.0 +.\" Added in commit v2_9_55_0-18-gc4702b7443 +.SH SEE ALSO .BR llapi_layout_alloc (3), -.BR llapi_layout_file_open (3), .BR llapi_layout_comp_add (3), .BR llapi_layout_comp_del (3), +.BR llapi_layout_file_open (3), .BR llapi_layout (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_file_comp_del.3 b/lustre/doc/llapi_layout_file_comp_del.3 index 3e91d072..ca0ba18 100644 --- a/lustre/doc/llapi_layout_file_comp_del.3 +++ b/lustre/doc/llapi_layout_file_comp_del.3 @@ -1,7 +1,6 @@ -.TH llapi_layout_file_comp_del 3 "2015 Nov 4" "Lustre User API" +.TH LLAPI_LAYOUT_FILE_COMP_DEL 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME -llapi_layout_file_comp_del \- delete the specified layout component -from an existing file. +llapi_layout_file_comp_del \- delete the specified layout component from an existing file. .SH SYNOPSIS .nf .B #include @@ -10,7 +9,6 @@ from an existing file. .BI " uint32_t "id ", uint32_t "flags ); .fi .SH DESCRIPTION -.PP Deletes the layout component(s) specified by .I id or @@ -36,18 +34,24 @@ Returns 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 -.SM ENOENT +.B ENOENT .I path doesn't exist or the specified component isn't found in file. -.SH "SEE ALSO" +.SH AVAILABILITY +.B llapi_layout_file_comp_del() +is part of the +.BR lustre (7) +user application interface library since release 2.10.0 +.\" Added in commit v2_9_55_0-18-gc4702b7443 +.SH SEE ALSO .BR llapi_layout_alloc (3), -.BR llapi_layout_file_open (3), -.BR llapi_layout_get_by_path (3), -.BR llapi_layout_file_comp_add (3), .BR llapi_layout_comp_id_get (3), .BR llapi_layout_comp_use_id (3), +.BR llapi_layout_file_comp_add (3), +.BR llapi_layout_file_open (3), +.BR llapi_layout_get_by_path (3), .BR llapi_layout (7), .BR lustreapi (7) diff --git a/lustre/doc/llapi_layout_file_create.3 b/lustre/doc/llapi_layout_file_create.3 index 52f82e2..985193b 100644 --- a/lustre/doc/llapi_layout_file_create.3 +++ b/lustre/doc/llapi_layout_file_create.3 @@ -1,4 +1,4 @@ -.TH llapi_layout_file_open 3 "2013 Oct 31" "Lustre User API" +.TH LLAPI_LAYOUT_FILE_CREATE 3 2024-08-27 "Lustre User API" "Lustre Library Functions" .SH NAME llapi_layout_file_open, llapi_layout_file_create \- open and apply a layout to a Lustre file .SH SYNOPSIS @@ -12,7 +12,6 @@ llapi_layout_file_open, llapi_layout_file_create \- open and apply a layout to a .BI " const struct llapi_layout *" layout ); .fi .SH DESCRIPTION -.LP The functions .B llapi_layout_file_open() and @@ -79,7 +78,6 @@ to See .BR llapi_layout_pool_name_set (3). .SH RETURN VALUES -.LP .B llapi_layout_file_open() and .B llapi_layout_file_create() @@ -87,16 +85,24 @@ return a new file descriptor, or -1 if an error occurred (in which case, errno is set appropriately). .SH ERRORS .TP 15 -.SM ENOTTY +.B ENOTTY .I path does not reside on a Lustre filesystem. .TP -.SM EINVAL +.B EINVAL An invalid argument was specified. -.SH "SEE ALSO" -.BR llapi_layout (7), -.BR lustreapi (7), +.SH AVAILABILITY +.B llapi_layout_file_open() +and +.B llapi_layout_file_create() +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 close (2), +.BR open (2), .BR llapi_layout_alloc (3), .BR llapi_layout_pool_name_set (3), -.BR open (2), -.BR close (2) +.BR llapi_layout (7), +.BR lustreapi (7) -- 1.8.3.1