LU-930 doc: remove llapi_layout_t from man pages

Remove the use of the non-existent llapi_layout_t from llapi_layout.7
and llapi_layout_alloc.3 and replace with struct llapi_layout.

Test-Parameters: trivial
Signed-off-by: Andreas Dilger <andreas.dilger@intel.com>
Change-Id: Icb3753038677ce95a35ed8f3b8266315553ebbe5
Reviewed-on: https://review.whamcloud.com/26698
Tested-by: Jenkins
Tested-by: Maloo <hpdd-maloo@intel.com>
Reviewed-by: Lai Siyao <lai.siyao@intel.com>
Reviewed-by: Niu Yawei <yawei.niu@intel.com>
Reviewed-by: Oleg Drokin <oleg.drokin@intel.com>

diff --git a/lustre/doc/llapi_layout.7 b/lustre/doc/llapi_layout.7
index 8658275..c077c04 100644 (file)
--- a/lustre/doc/llapi_layout.7
+++ b/lustre/doc/llapi_layout.7
@@ -11,15 +11,16 @@ The
 family of functions functions provides an abstract interface to
 manipulating the layout information of a file in a Lustre filesystem.
 Layouts are represented by the opaque data type
-.B llapi_layout_t
+.B struct llapi_layout
 which is passed as a handle to the various functions.
 .PP
 A layout has a number of attributes that describe how a file's data are
 stored in the filesystem.  These include stripe count, stripe size, RAID
-pattern, pool name, and the OST index associated with each stripe. Refer
-to the Lustre Operations Manual for detailed descriptions of these
-attributes.  For each attribute, there exists a pair of functions with
-the suffixes
+pattern, pool name, and the OST index associated with each stripe. In more
+complex layouts, a file may have multiple components that describe a different
+layout for separate regions of the file. Refer to the Lustre Operations Manual
+for detailed descriptions of these attributes.  For each attribute, there
+exists a pair of functions with the suffixes
 .B _get
 and
 .B _set
@@ -27,7 +28,9 @@ that are used to read and assign the attribute value in a given layout.
 .PP
 Using this interface to create a file might consist of the following steps.
 .IP \[bu]
-Allocate a layout with
+Allocate
+.B struct layout
+with
 .BR llapi_layout_alloc (3).
 .IP \[bu]
 Assign attribute values using the
@@ -42,21 +45,26 @@ Free the layout memory using
 .PP
 Similarly, these steps might be used to read a file layout:
 .IP \[bu]
-Obtain the layout with
+One can allocate and initialize a new
+.B struct layout
+from an existing file with one of the
 .BR llapi_layout_get_by_path (3),
 .BR llapi_layout_get_by_fd (3),
 or
-.BR llapi_layout_get_by_fid (3).
+.BR llapi_layout_get_by_fid (3)
+functions.
 .IP \[bu]
-Read attribute values using the
+To access attribute values from
+.B struct llapi_layout
+use the
 .B llapi_layout_*_get (3)
 functions.
 .IP \[bu]
-Free the layout memory using
+To free the previously allocated layout memory use
 .BR llapi_layout_free (3).
 .PP
 Using this interface to create a file with composite layout consists of the
-following steps.
+following steps:
 .IP \[bu]
 Allocate first layout component with
 .BR llapi_layout_alloc (3).
@@ -88,7 +96,7 @@ Example 1: Create file with specified layout, then query the layout attributes.
 .nf
 {
        /* Allocate layout */
-       layout = llapi_layout_alloc();
+       struct llapi_layout *layout = llapi_layout_alloc();
 
        /* Set attributes of layout */
        llapi_layout_stripe_count_set(layout, count);
@@ -116,6 +124,8 @@ Example 2: Create file with composite layout.
 .PP
 .nf
 {
+       struct llapi_layout *head, *comp;
+
        /* Create first component */
        head = llapi_layout_alloc();
        llapi_layout_stripe_count_set(head, 1);

diff --git a/lustre/doc/llapi_layout_alloc.3 b/lustre/doc/llapi_layout_alloc.3
index 57b7ce2..3bab4cc 100644 (file)
--- a/lustre/doc/llapi_layout_alloc.3
+++ b/lustre/doc/llapi_layout_alloc.3
@@ -1,7 +1,7 @@
 .TH llapi_layout_alloc 3 "2013 Oct 31" "Lustre User API"
 .SH NAME
 llapi_layout_alloc, llapi_layout_free \- allocate and destroy
-.B llapi_layout_t
+.B struct llapi_layout
 objects.
 .SH SYNOPSIS
 .nf
@@ -16,9 +16,9 @@ objects.
 .LP
 .B llapi_layout_alloc()
 returns a pointer to a newly-allocated
-.BR struct llapi_layout .
+.BR "struct llapi_layout" .
 The
-.B llapi_layout_t
+.B struct llapi_layout
 is an opaque entity containing the layout information for a file in a
 Lustre filesystem.  Its internal structure should not be directly
 accessed by an application.  It may be used in
@@ -28,12 +28,12 @@ manual page to modify layout attributes and create files with the given
 layout.
 .PP
 The returned
-.B llapi_layout_t
+.B struct llapi_layout
 object is initialized with default attribute values that will effect the
 standard Lustre behavior for assigning layouts to newly-created files.
 These values may be modified using the group of
-functions in the
-.B llapi_layout
+functions in
+.B struct llapi_layout
 API whose names end with
 .BR _set .
 The pointer should be freed with

diff --git a/lustre/doc/llapi_layout_comp_add.3 b/lustre/doc/llapi_layout_comp_add.3
index 1ea53b7..f91692f 100644 (file)
--- a/lustre/doc/llapi_layout_comp_add.3
+++ b/lustre/doc/llapi_layout_comp_add.3
@@ -19,10 +19,12 @@ A composite layout is made of several layout components.
 .BR llapi_layout_comp_add (3)
 adds the layout component
 .I comp
-into the in-memory
-.IR layout
-under construction.  The
-.IR layout
+into the existing in-memory
+.I layout
+under construction, and
+.I comp
+is freed.  The
+.I layout
 will be turned into composite if it was plain before adding. All layout
 attributes of
 .I comp
@@ -42,8 +44,9 @@ but does not delete the component from an existing file layout on the MDT.
 .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).
+return 0 on success, or -1 if an error occurred (in which case,
+.B errno
+is set appropriately).
 .SH ERRORS
 .TP 15
 .SM EINVAL