From e61be5b3bc31178fe44e7eec447d3e18b3f3bda6 Mon Sep 17 00:00:00 2001 From: Niu Yawei Date: Tue, 23 Feb 2016 04:27:25 -0500 Subject: [PATCH] LU-8998 docs: man pages for composite layout APIs Added man pages for the new layout component interfaces: 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_get(3) llapi_layout_comp_flags_set(3) llapi_layout_comp_flags_clear(3) llapi_layout_comp_id_get(3) llapi_layout_comp_move(3) llapi_layout_comp_move_at(3) llapi_layout_file_comp_add(3) llapi_layout_file_comp_del(3) Signed-off-by: Niu Yawei Change-Id: I8fd466b9cb0352bb7812f0b748816801f20f5e71 Reviewed-on: https://review.whamcloud.com/25740 Tested-by: Jenkins Reviewed-by: James Nunez Tested-by: Maloo Reviewed-by: Andreas Dilger Reviewed-by: Jinshan Xiong --- lustre/doc/llapi_layout.7 | 160 ++++++++++++++++++++++------- lustre/doc/llapi_layout_comp_add.3 | 56 ++++++++++ lustre/doc/llapi_layout_comp_del.3 | 1 + lustre/doc/llapi_layout_comp_extent_get.3 | 45 ++++++++ lustre/doc/llapi_layout_comp_extent_set.3 | 1 + lustre/doc/llapi_layout_comp_flags_clear.3 | 1 + lustre/doc/llapi_layout_comp_flags_get.3 | 53 ++++++++++ lustre/doc/llapi_layout_comp_flags_set.3 | 1 + lustre/doc/llapi_layout_comp_id_get.3 | 29 ++++++ lustre/doc/llapi_layout_comp_move.3 | 54 ++++++++++ lustre/doc/llapi_layout_comp_move_at.3 | 1 + lustre/doc/llapi_layout_file_comp_add.3 | 36 +++++++ lustre/doc/llapi_layout_file_comp_del.3 | 51 +++++++++ 13 files changed, 452 insertions(+), 37 deletions(-) create mode 100644 lustre/doc/llapi_layout_comp_add.3 create mode 100644 lustre/doc/llapi_layout_comp_del.3 create mode 100644 lustre/doc/llapi_layout_comp_extent_get.3 create mode 100644 lustre/doc/llapi_layout_comp_extent_set.3 create mode 100644 lustre/doc/llapi_layout_comp_flags_clear.3 create mode 100644 lustre/doc/llapi_layout_comp_flags_get.3 create mode 100644 lustre/doc/llapi_layout_comp_flags_set.3 create mode 100644 lustre/doc/llapi_layout_comp_id_get.3 create mode 100644 lustre/doc/llapi_layout_comp_move.3 create mode 100644 lustre/doc/llapi_layout_comp_move_at.3 create mode 100644 lustre/doc/llapi_layout_file_comp_add.3 create mode 100644 lustre/doc/llapi_layout_file_comp_del.3 diff --git a/lustre/doc/llapi_layout.7 b/lustre/doc/llapi_layout.7 index 045d742..5ca7052 100644 --- a/lustre/doc/llapi_layout.7 +++ b/lustre/doc/llapi_layout.7 @@ -28,74 +28,147 @@ that are used to read and assign the attribute value in a given layout. Using this interface to create a file might consist of the following steps. .IP \[bu] Allocate a layout with -.BR llapi_layout_alloc() . +.BR llapi_layout_alloc (3). .IP \[bu] Assign attribute values using the -.B llapi_layout_*_set() +.B llapi_layout_*_set (3) functions. .IP \[bu] Create the file using -.BR llapi_layout_file_create() . +.BR llapi_layout_file_create (3). .IP \[bu] Free the layout memory using -.BR llapi_layout_free() . +.BR llapi_layout_free (3). .PP Similarly, these steps might be used to read a file layout: .IP \[bu] Obtain the layout with -.BR llapi_layout_get_by_path() , -.BR llapi_layout_get_by_fd() , +.BR llapi_layout_get_by_path (3), +.BR llapi_layout_get_by_fd (3), or -.BR llapi_layout_get_by_fid() . +.BR llapi_layout_get_by_fid (3). .IP \[bu] Read attribute values using the -.B llapi_layout_*_get() +.B llapi_layout_*_get (3) +functions. +.IP \[bu] +Free the layout memory using +.BR llapi_layout_free (3). +.PP +Using this interface to create a file with composite layout consists of the +following steps. +.IP \[bu] +Allocate first layout component with +.BR llapi_layout_alloc (3). +.IP \[bu] +Assign attribute values using the +.B llapi_layout_*_set (3) +functions. +.IP \[bu] +Allocate second layout component with +.BR llapi_layout_alloc (3). +.IP \[bu] +Add the second layout into the first one using +.BR llapi_layout_comp_add (3). +.IP \[bu] +Assign attribute values to second layout using the +.BR llapi_layout_*_set (3) functions. .IP \[bu] +Repeat above two steps to add more components. +.IP \[bu] +Create the file using +.BR llapi_layout_file_create (3). +.IP \[bu] Free the layout memory using -.BR llapi_layout_free() . +.BR llapi_layout_free (3). .SH "EXAMPLE" +Example 1: Create file with specified layout, then query the layout attributes. +.PP .nf -#include -#include -#include -#include -#include -#include - -int main(int argc, char *argv[]) { - int fd; - struct llapi_layout *layout; - uint64_t count = 2; - uint64_t size = 1048576; - char *path; - - if (argc != 2) - return -1; - - path = argv[1]; + /* Allocate 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); - if (fd < 0) { - fprintf(stderr, "cannot create %s: %s\\n", path, - strerror(errno)); - return -1; - } - close(fd); + + /* 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); - printf("%s with stripe size %llu, striped across %llu OSTs," - " has been created!\\n", path, size, count); + + /* Free layout */ llapi_layout_free(layout); - return 0; } .fi +.PP +Example 2: Create file with composite layout. +.PP +.nf +{ + /* 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, + (u_int64t)-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); +} +.fi +.PP +Example 3: Traverse components of a composite layout. +.PP +.nf +{ + /* Retrieve composite layout from file */ + layout = llapi_layout_get_by_path(path, 0); + + /* Move cursor to the first component */ + rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_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_move(layout, LLAPI_LAYOUT_COMP_POS_NEXT); + }; + + /* Free layout */ + llapi_layout_free(layout); +} +.fi + .SH "BUGS" Setting the OST index number is only supported for stripe number 0. @@ -121,4 +194,17 @@ 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 lfs (1) +.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_move (3), +.BR llapi_layout_comp_move_at (3), +.BR llapi_layout_file_comp_add (3), +.BR llapi_layout_file_comp_del (3), +.BR lfs (1), +.BR lfs-setstripe (1) diff --git a/lustre/doc/llapi_layout_comp_add.3 b/lustre/doc/llapi_layout_comp_add.3 new file mode 100644 index 0000000..64aeb31 --- /dev/null +++ b/lustre/doc/llapi_layout_comp_add.3 @@ -0,0 +1,56 @@ +.TH llapi_layout_comp_add 3 "2015 Nov 4" "Lustre User API" +.SH NAME +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 " struct llapi_layout *" comp ); +.PP +.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) +adds the layout component +.I comp +into the +.IR layout . +The +.IR layout +will be turned into composite if it was plain before adding. All layout +attributes of +.I comp +will be inherited from the +.IR layout , +unless otherwise specified for this component by llapi_layout_*_set(3) +functions. +.PP +.BR llapi_layout_comp_del (3) +deletes the layout component +.I comp +from the +.IR layout . +.PP +.SH RETURN VALUES +.B llapi_layout_comp_add() +and +.B llapi_layout_comp_del() +return 0 on success, or -1 if an error occurred (in which case, errno is +set appropriately). +.SH ERRORS +.TP 15 +.SM EINVAL +An invalid argument was specified. +.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 (7), +.BR liblustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_del.3 b/lustre/doc/llapi_layout_comp_del.3 new file mode 100644 index 0000000..3acc72a --- /dev/null +++ b/lustre/doc/llapi_layout_comp_del.3 @@ -0,0 +1 @@ +.so man3/llapi_layout_comp_add.3 diff --git a/lustre/doc/llapi_layout_comp_extent_get.3 b/lustre/doc/llapi_layout_comp_extent_get.3 new file mode 100644 index 0000000..2412397 --- /dev/null +++ b/lustre/doc/llapi_layout_comp_extent_get.3 @@ -0,0 +1,45 @@ +.TH llapi_layout_comp_extent_get 3 "2015 Nov 4" "Lustre User API" +.SH NAME +llapi_layout_comp_extent_get, llapi_layout_comp_extent_set \- get or set the +extent of a layout component. +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int llapi_layout_comp_extent_get(const struct llapi_layout *" layout ", +.BI " uint64_t *" start ", uint64_t *" end ); +.PP +.BI "int llapi_layout_comp_extent_set(const struct llapi_layout *" layout ", +.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) +gets the extent of the current component of +.I layout +and stores it into +.I start +and +.IR end . +.PP +.BR llapi_layout_comp_extent_set (3) +sets the extent [\fIstart\fR, \fIend\fR) to the current component of +.IR layout . +.PP +.SH RETURN VALUES +.B llapi_layout_comp_extent_get() +and +.B llapi_layout_comp_extent_set() +return 0 on success, or -1 if an error occurred (in which case, errno is +set appropriately). +.SH ERRORS +.TP 15 +.SM EINVAL +An invalid argument was specified. +.SH "SEE ALSO" +.BR llapi_layout_alloc (3), +.BR llapi_layout_file_open (3), +.BR llapi_layout (7), +.BR liblustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_extent_set.3 b/lustre/doc/llapi_layout_comp_extent_set.3 new file mode 100644 index 0000000..1785083 --- /dev/null +++ b/lustre/doc/llapi_layout_comp_extent_set.3 @@ -0,0 +1 @@ +.so man3/llapi_layout_comp_extent_get.3 diff --git a/lustre/doc/llapi_layout_comp_flags_clear.3 b/lustre/doc/llapi_layout_comp_flags_clear.3 new file mode 100644 index 0000000..e36fffb --- /dev/null +++ b/lustre/doc/llapi_layout_comp_flags_clear.3 @@ -0,0 +1 @@ +.so man3/llapi_layout_comp_flags_get.3 diff --git a/lustre/doc/llapi_layout_comp_flags_get.3 b/lustre/doc/llapi_layout_comp_flags_get.3 new file mode 100644 index 0000000..17146cd --- /dev/null +++ b/lustre/doc/llapi_layout_comp_flags_get.3 @@ -0,0 +1,53 @@ +.TH llapi_layout_comp_flags_get 3 "2015 Nov 4" "Lustre User API" +.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. +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int llapi_layout_comp_flags_get(const struct llapi_layout *" layout ", +.BI " uint32_t *" flags ); +.PP +.BI "int llapi_layout_comp_flags_set(struct llapi_layout *" layout ", +.BI " uint32_t " flags ); +.PP +.BI "int llapi_layout_comp_flags_clear(struct llapi_layout *" layout ", +.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. +.PP +.BR llapi_layout_comp_flags_get (3) +gets the flags of +.I layout +and stores it into +.IR flags . +.PP +.BR llapi_layout_comp_flags_set (3) +sets the specified +.I flags +to the +.IR layout . +.PP +.BR llapi_layout_comp_flags_clear (3) +clears the specified +.I flags +from the +.IR layout . +.SH RETURN VALUES +Return 0 on success, or -1 if an error occurred (in which case, errno is +set appropriately). +.SH ERRORS +.TP 15 +.SM EINVAL +An invalid argument was specified. +.SH "SEE ALSO" +.BR llapi_layout_alloc (3), +.BR llapi_layout_file_open (3), +.BR llapi_layout (7), +.BR liblustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_flags_set.3 b/lustre/doc/llapi_layout_comp_flags_set.3 new file mode 100644 index 0000000..e36fffb --- /dev/null +++ b/lustre/doc/llapi_layout_comp_flags_set.3 @@ -0,0 +1 @@ +.so man3/llapi_layout_comp_flags_get.3 diff --git a/lustre/doc/llapi_layout_comp_id_get.3 b/lustre/doc/llapi_layout_comp_id_get.3 new file mode 100644 index 0000000..5be61a6 --- /dev/null +++ b/lustre/doc/llapi_layout_comp_id_get.3 @@ -0,0 +1,29 @@ +.TH llapi_layout_comp_id_get 3 "2015 Nov 4" "Lustre User API" +.SH NAME +llapi_layout_comp_id_get \- get the ID of a layout component. +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int llapi_layout_comp_id_get(const struct llapi_layout *" layout ", +.BI " uint32_t *" id ); +.fi +.SH DESCRIPTION +.PP +Return the unique numeric +.I id +of the current component of +.IR layout . +.PP +.SH RETURN VALUES +Return 0 on success, or -1 if an error occurred (in which case, errno is +set appropriately). +.SH ERRORS +.TP 15 +.SM EINVAL +An invalid argument was specified. +.SH "SEE ALSO" +.BR llapi_layout_alloc (3), +.BR llapi_layout_file_open (3), +.BR llapi_layout (7), +.BR liblustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_move.3 b/lustre/doc/llapi_layout_comp_move.3 new file mode 100644 index 0000000..ea6ed50 --- /dev/null +++ b/lustre/doc/llapi_layout_comp_move.3 @@ -0,0 +1,54 @@ +.TH llapi_layout_comp_move 3 "2015 Nov 4" "Lustre User API" +.SH NAME +llapi_layout_comp_move \- Move the current component of layout to a specified +position: first, next or last. +llapi_layout_comp_move_at \- Move the current component of layout to a component +with specified component id. +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int llapi_layout_comp_move(struct llapi_layout *" layout ", +.BI " uint32_t *" pos ); +.PP +.BI "int llapi_layout_comp_move_at(struct llapi_layout *" layout ", +.BI " uint32_t *" comp_id ); +.fi +.SH DESCRIPTION +.PP +Moves the current component of the +.IR layout . +to a specified position. +.PP +.BR llapi_layout_comp_move (3) +Moves current component to +.IR pos . +Available +.IR pos +are: +.PP +.BR LLAPI_LAYOUT_COMP_POS_FIRST: +The first component of the layout. +.PP +.BR LLAPI_LAYOUT_COMP_POS_NEXT: +The next component of current one. +.PP +.BR LLAPI_LAYOUT_COMP_POS_LAST: +The last component of the layout. +.PP +.BR llapi_layout_comp_move_at (3) +Moves current component to the component with specified +.IR comp_id . +.SH RETURN VALUES +Return 0 on success, 1 when reaches last component when try to move next, or -1 if +an error occurred (in which case, errno is set appropriately). +.SH ERRORS +.TP 15 +.SM EINVAL +An invalid argument was specified. +.SH "SEE ALSO" +.BR llapi_layout_alloc (3), +.BR llapi_layout_file_open (3), +.BR llapi_layout_comp_id (3), +.BR llapi_layout (7), +.BR liblustreapi (7) diff --git a/lustre/doc/llapi_layout_comp_move_at.3 b/lustre/doc/llapi_layout_comp_move_at.3 new file mode 100644 index 0000000..95e93a8 --- /dev/null +++ b/lustre/doc/llapi_layout_comp_move_at.3 @@ -0,0 +1 @@ +.so man3/llapi_layout_comp_move.3 diff --git a/lustre/doc/llapi_layout_file_comp_add.3 b/lustre/doc/llapi_layout_file_comp_add.3 new file mode 100644 index 0000000..7584e03 --- /dev/null +++ b/lustre/doc/llapi_layout_file_comp_add.3 @@ -0,0 +1,36 @@ +.TH llapi_layout_file_comp_add 3 "2015 Nov 4" "Lustre User API" +.SH NAME +llapi_layout_file_comp_add \- add one or more components into an +existing file. +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int llapi_layout_file_comp_add(const char *" path ", +.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). +.SH ERRORS +.TP 15 +.SM EINVAL +An invalid argument was specified. +.TP +.SM ENOENT +.I path +doesn't exist. +.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 (7), +.BR liblustreapi (7) diff --git a/lustre/doc/llapi_layout_file_comp_del.3 b/lustre/doc/llapi_layout_file_comp_del.3 new file mode 100644 index 0000000..eb854e1 --- /dev/null +++ b/lustre/doc/llapi_layout_file_comp_del.3 @@ -0,0 +1,51 @@ +.TH llapi_layout_file_comp_del 3 "2015 Nov 4" "Lustre User API" +.SH NAME +llapi_layout_file_comp_del \- delete the specified layout component +from an existing file. +.SH SYNOPSIS +.nf +.B #include +.PP +.BI "int llapi_layout_file_comp_del(const char *" path ", +.BI " uint32_t "id ); +.fi +.SH DESCRIPTION +.PP +Deletes the layout component(s) specified by +.I id +from an existing file. The +.I id +can be a real unique component ID or a +.IR lcme_id . +Available +.IR lcme_id +are: +.PP +.BR LCME_ID_ALL: +All components in the layout. +.PP +.BR LCME_ID_NONE|LCME_FL_INIT: +All the instantiated components in the layout. +.SH RETURN VALUES +Returns 0 on success, or -1 if an error occurred (in which case, errno is +set appropriately). +.SH ERRORS +.TP 15 +.SM EINVAL +An invalid argument was specified. +.TP +.SM ENOENT +.I path +doesn't exist or the specified component isn't found in file. +.SH TODO +Add description for the +.IR lcme_id . +.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_move_at (3), +.BR llapi_layout (7), +.BR liblustreapi (7) -- 1.8.3.1