LU-8998 llapi: rename llapi_layout_comp_move -> *use

Rename llapi_layout_comp_move() and llapi_layout_comp_move_at()
to llapi_layout_comp_use() and llapi_layout_comp_use_id(),
respectively.  This avoids confusion about what "move" and "at" in
the function name implies. The component itself is not actually
being moved, just a different layout component is being selected
for access or modification.  Using "_id" instead of "_at" also
makes it more clear what the difference is between these functions.

Rename LLAPI_LAYOUT_COMP_POS_{FIRST,NEXT,LAST} correspondingly to
LLAPI_LAYOUT_COMP_USE_{FIRST,NEXT,LAST} to match.

Split llapi_layout_comp_use_id.3 from llapi_layout_comp_use.3 since
they are mostly independent anyway.

Test-Parameters: trivial testlist=sanity-pfl
Signed-off-by: Andreas Dilger <andreas.dilger@intel.com>
Change-Id: I85926d4ec9774745bc49b0d178ed9b23ec2cab07
Reviewed-on: https://review.whamcloud.com/26483
Tested-by: Jenkins
Reviewed-by: Niu Yawei <yawei.niu@intel.com>
Tested-by: Maloo <hpdd-maloo@intel.com>
Reviewed-by: Jinshan Xiong <jinshan.xiong@intel.com>
Reviewed-by: Oleg Drokin <oleg.drokin@intel.com>

diff --git a/lustre/doc/Makefile.am b/lustre/doc/Makefile.am
index 06a315f..4e29038 100644 (file)
--- a/lustre/doc/Makefile.am
+++ b/lustre/doc/Makefile.am
@@ -78,8 +78,8 @@ MANFILES =                                    \
        llapi_layout_comp_flags_get.3           \
        llapi_layout_comp_flags_set.3           \
        llapi_layout_comp_id_get.3              \
-       llapi_layout_comp_move.3                \
-       llapi_layout_comp_move_at.3             \
+       llapi_layout_comp_use.3                 \
+       llapi_layout_comp_use_id.3              \
        llapi_layout_file_comp_add.3            \
        llapi_layout_file_comp_del.3            \
        llapi_layout_file_create.3              \

diff --git a/lustre/doc/llapi_layout.7 b/lustre/doc/llapi_layout.7
index 5ca7052..8658275 100644 (file)
--- a/lustre/doc/llapi_layout.7
+++ b/lustre/doc/llapi_layout.7
@@ -151,7 +151,7 @@ Example 3: Traverse components of a composite layout.
        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);
+       rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
 
        /* Traverse all components */
        while (rc == 0) {
@@ -161,7 +161,7 @@ Example 3: Traverse components of a composite layout.
                llapi_layout_comp_extent_get(layout, &start, &end);
 
                /* Advance cursor */
-               rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_NEXT);
+               rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
        };
 
        /* Free layout */
@@ -202,8 +202,8 @@ The RAID pattern may only be set to 0.
 .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_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),

diff --git a/lustre/doc/llapi_layout_comp_move.3 b/lustre/doc/llapi_layout_comp_move.3
deleted file mode 100644 (file)
index a1feec8..0000000
--- a/lustre/doc/llapi_layout_comp_move.3
+++ /dev/null
@@ -1,54 +0,0 @@
-.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 <lustre/lustreapi.h>
-.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 lustreapi (7)

diff --git a/lustre/doc/llapi_layout_comp_move_at.3 b/lustre/doc/llapi_layout_comp_move_at.3
deleted file mode 100644 (file)
index 95e93a8..0000000
--- a/lustre/doc/llapi_layout_comp_move_at.3
+++ /dev/null
@@ -1 +0,0 @@
-.so man3/llapi_layout_comp_move.3

diff --git a/lustre/doc/llapi_layout_comp_use.3 b/lustre/doc/llapi_layout_comp_use.3
new file mode 100644 (file)
index 0000000..32ac428
--- /dev/null
+++ b/lustre/doc/llapi_layout_comp_use.3
@@ -0,0 +1,47 @@
+.TH llapi_layout_comp_use 3 "2017 Apr 7" "Lustre User API"
+.SH NAME
+llapi_layout_comp_use \- change current component to relative position
+.SH SYNOPSIS
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_layout_comp_use(struct llapi_layout *" layout ",
+.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
+.IR pos .
+Possible values for
+.I pos
+are:
+.PP
+.BR LLAPI_LAYOUT_COMP_USE_FIRST :
+The first component of the layout.
+.PP
+.BR LLAPI_LAYOUT_COMP_USE_NEXT :
+The next component after the current one.
+.PP
+.BR LLAPI_LAYOUT_COMP_USE_LAST :
+The last component of the layout.
+.SH RETURN VALUES
+Return 0 on success, and 1 when there is no next component. Otherwise,
+if an error occurred -1 is returned and
+.I errno
+is set appropriately.
+.SH ERRORS
+.TP 15
+.SM EINVAL
+An invalid argument was specified.
+.TP 15
+.SM ENOENT
+No such component ID exists.
+.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 (7),
+.BR lustreapi (7)

diff --git a/lustre/doc/llapi_layout_comp_use_id.3 b/lustre/doc/llapi_layout_comp_use_id.3
new file mode 100644 (file)
index 0000000..b9d2fe5
--- /dev/null
+++ b/lustre/doc/llapi_layout_comp_use_id.3
@@ -0,0 +1,35 @@
+.TH llapi_layout_comp_use_id 3 "2017 Apr 7" "Lustre User API"
+.SH NAME
+llapi_layout_comp_use_id \- set currently active component to given ID
+.SH SYNOPSIS
+.nf
+.B #include <lustre/lustreapi.h>
+.PP
+.BI "int llapi_layout_comp_use_id(struct llapi_layout *" layout ",
+.BI "                             uint32_t *" comp_id );
+.fi
+.SH DESCRIPTION
+.PP
+Sets currently active component of
+.I layout
+to the component with specified
+.IR comp_id .
+.SH RETURN VALUES
+Return 0 on success. Otherwise, if an error occurred -1 is returned and
+.I errno
+is set appropriately.
+.SH ERRORS
+.TP 15
+.SM ENOENT
+No such component ID exists.
+.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_del (3),
+.BR llapi_layout_comp_id_get (3),
+.BR llapi_layout_comp_use (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 a958b58..5a726df 100644 (file)
--- a/lustre/doc/llapi_layout_file_comp_del.3
+++ b/lustre/doc/llapi_layout_file_comp_del.3
@@ -46,6 +46,6 @@ Add description for the
 .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_comp_use_id (3),
 .BR llapi_layout (7),
 .BR lustreapi (7)

diff --git a/lustre/doc/lustreapi.7 b/lustre/doc/lustreapi.7
index 2de6ce8..261c024 100644 (file)
--- a/lustre/doc/lustreapi.7
+++ b/lustre/doc/lustreapi.7
@@ -38,8 +38,8 @@ quotas, file layouts, etc).  See the referenced man pages for details.
 .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_move (3),
-.BR llapi_layout_comp_move_at (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),

diff --git a/lustre/include/lustre/lustreapi.h b/lustre/include/lustre/lustreapi.h
index cd06b47..dc21d1a 100644 (file)
--- a/lustre/include/lustre/lustreapi.h
+++ b/lustre/include/lustre/lustreapi.h
@@ -762,20 +762,20 @@ int llapi_layout_comp_add(struct llapi_layout *layout);
  */
 int llapi_layout_comp_del(struct llapi_layout *layout);
 
-enum {
-       LLAPI_LAYOUT_COMP_POS_NEXT = 0,
-       LLAPI_LAYOUT_COMP_POS_FIRST = 1,
-       LLAPI_LAYOUT_COMP_POS_LAST = 2
+enum llapi_layout_comp_use {
+       LLAPI_LAYOUT_COMP_USE_FIRST = 1,
+       LLAPI_LAYOUT_COMP_USE_LAST = 2,
+       LLAPI_LAYOUT_COMP_USE_NEXT = 3,
 };
 
 /**
- * Move the current component pointer by specified component ID.
+ * Set the currently active component to the specified component ID.
  */
-int llapi_layout_comp_move_at(struct llapi_layout *layout, uint32_t id);
+int llapi_layout_comp_use_id(struct llapi_layout *layout, uint32_t id);
 /**
- * Move the current component pointer to a specified position.
+ * Select the currently active component at the specified position.
  */
-int llapi_layout_comp_move(struct llapi_layout *layout, uint32_t pos);
+int llapi_layout_comp_use(struct llapi_layout *layout, uint32_t pos);
 /**
  * Add layout components to an existing file.
  */

diff --git a/lustre/tests/llapi_layout_test.c b/lustre/tests/llapi_layout_test.c
index 401003d..805d235 100644 (file)
--- a/lustre/tests/llapi_layout_test.c
+++ b/lustre/tests/llapi_layout_test.c
@@ -1380,7 +1380,7 @@ void test30(void)
        ASSERTF(s == start[2] && e == end[2],
                "s: %"PRIu64", e: %"PRIu64"", s, e);
 
-       rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_FIRST);
+       rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
        ASSERTF(rc == 0, "rc %d, errno %d", rc, errno);
 
        /* delete non-tail component will fail */
@@ -1392,7 +1392,7 @@ void test30(void)
        ASSERTF(s == start[0] && e == end[0],
                "s: %"PRIu64", e: %"PRIu64"", s, e);
 
-       rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_NEXT);
+       rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
        ASSERTF(rc == 0, "rc %d, errno %d", rc,  errno);
 
        rc = llapi_layout_comp_extent_get(layout, &s, &e);
@@ -1400,7 +1400,7 @@ void test30(void)
        ASSERTF(s == start[1] && e == end[1],
                "s: %"PRIu64", e: %"PRIu64"", s, e);
 
-       rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_NEXT);
+       rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
        ASSERTF(rc == 0, "rc %d, errno %d", rc,  errno);
 
        rc = llapi_layout_comp_del(layout);
@@ -1465,7 +1465,7 @@ void test31(void)
        layout = llapi_layout_get_by_path(path, 0);
        ASSERTF(layout != NULL, "errno = %d", errno);
 
-       rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_FIRST);
+       rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
        ASSERTF(rc == 0, "rc %d, errno %d", rc, errno);
        i = 0;
        do {
@@ -1478,9 +1478,8 @@ void test31(void)
                ASSERTF(rc == 0 && id[i] != 0, "i %d, errno %d, id %d",
                        i, errno, id[i]);
 
-               rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_NEXT);
-               ASSERTF(rc >= 0, "i %d, rc %d, errno %d", i, rc, errno);
-
+               rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_NEXT);
+               ASSERTF(rc == 0 || i == 1, "i=%d rc=%d errno=%d", i, rc, errno);
                i++;
        } while (rc == 0);
 
@@ -1497,7 +1496,7 @@ void test31(void)
        layout = llapi_layout_get_by_path(path, 0);
        ASSERTF(layout != NULL, "errno = %d", errno);
 
-       rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_FIRST);
+       rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
        ASSERTF(rc == 0, "rc %d, errno %d", rc, errno);
 
        rc = llapi_layout_comp_extent_get(layout, &s, &e);

diff --git a/lustre/utils/lfs.c b/lustre/utils/lfs.c
index b682d2d..7371289 100644 (file)
--- a/lustre/utils/lfs.c
+++ b/lustre/utils/lfs.c
@@ -1201,7 +1201,7 @@ static int adjust_first_extent(char *fname, struct llapi_layout *layout)
        llapi_layout_free(head);
 
        /* Make sure we use the first component of the layout to be added. */
-       rc = llapi_layout_comp_move(layout, LLAPI_LAYOUT_COMP_POS_FIRST);
+       rc = llapi_layout_comp_use(layout, LLAPI_LAYOUT_COMP_USE_FIRST);
        if (rc < 0) {
                fprintf(stderr, "Move component cursor failed. %s\n",
                        strerror(errno));

diff --git a/lustre/utils/liblustreapi_layout.c b/lustre/utils/liblustreapi_layout.c
index 7f364fd..af54943 100644 (file)
--- a/lustre/utils/liblustreapi_layout.c
+++ b/lustre/utils/liblustreapi_layout.c
@@ -1785,26 +1785,26 @@ int llapi_layout_comp_del(struct llapi_layout *layout)
  * \retval     =0 : moved successfully
  * \retval     <0 if error occurs
  */
-int llapi_layout_comp_move_at(struct llapi_layout *layout, uint32_t id)
+int llapi_layout_comp_use_id(struct llapi_layout *layout, uint32_t comp_id)
 {
        struct llapi_layout_comp *comp;
 
        comp = __llapi_layout_cur_comp(layout);
        if (comp == NULL)
-               return -1;
+               return -1; /* use previously set errno */
 
        if (!layout->llot_is_composite) {
                errno = EINVAL;
                return -1;
        }
 
-       if (id == 0) {
+       if (comp_id == LCME_ID_INVAL) {
                errno = EINVAL;
                return -1;
        }
 
        list_for_each_entry(comp, &layout->llot_comp_list, llc_list) {
-               if (comp->llc_id == id) {
+               if (comp->llc_id == comp_id) {
                        layout->llot_cur_comp = comp;
                        return 0;
                }
@@ -1818,15 +1818,15 @@ int llapi_layout_comp_move_at(struct llapi_layout *layout, uint32_t id)
  *
  * \param[in] layout   composite layout
  * \param[in] pos      the position to be moved, it can be:
- *                     LLAPI_LAYOUT_COMP_POS_FIRST: move to head
- *                     LLAPI_LAYOUT_COMP_POS_LAST: move to tail
- *                     LLAPI_LAYOUT_COMP_POS_NEXT: move to next
+ *                     LLAPI_LAYOUT_COMP_USE_FIRST: use first component
+ *                     LLAPI_LAYOUT_COMP_USE_LAST: use last component
+ *                     LLAPI_LAYOUT_COMP_USE_NEXT: use next component
  *
  * \retval     =0 : moved successfully
- * \retval     =1 : already at the tail when move to the next
+ * \retval     =1 : at last component with NEXT
  * \retval     <0 if error occurs
  */
-int llapi_layout_comp_move(struct llapi_layout *layout, uint32_t pos)
+int llapi_layout_comp_use(struct llapi_layout *layout, uint32_t pos)
 {
        struct llapi_layout_comp *comp, *head, *tail;
 
@@ -1844,14 +1844,14 @@ int llapi_layout_comp_move(struct llapi_layout *layout, uint32_t pos)
        tail = list_entry(layout->llot_comp_list.prev, typeof(*tail),
                          llc_list);
 
-       if (pos == LLAPI_LAYOUT_COMP_POS_NEXT) {
+       if (pos == LLAPI_LAYOUT_COMP_USE_NEXT) {
                if (comp == tail)
                        return 1;
                layout->llot_cur_comp = list_entry(comp->llc_list.next,
                                                   typeof(*comp), llc_list);
-       } else if (pos == LLAPI_LAYOUT_COMP_POS_FIRST) {
+       } else if (pos == LLAPI_LAYOUT_COMP_USE_FIRST) {
                layout->llot_cur_comp = head;
-       } else if (pos == LLAPI_LAYOUT_COMP_POS_LAST) {
+       } else if (pos == LLAPI_LAYOUT_COMP_USE_LAST) {
                layout->llot_cur_comp = tail;
        } else {
                errno = EINVAL;