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 <errno.h>
-#include <string.h>
-#include <stdint.h>
-#include <unistd.h>
-#include <stdio.h>
-#include <lustre/lustreapi.h>
-
-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.
.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)
--- /dev/null
+.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 <lustre/lustreapi.h>
+.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)
--- /dev/null
+.so man3/llapi_layout_comp_add.3
--- /dev/null
+.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 <lustre/lustreapi.h>
+.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)
--- /dev/null
+.so man3/llapi_layout_comp_extent_get.3
--- /dev/null
+.so man3/llapi_layout_comp_flags_get.3
--- /dev/null
+.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 <lustre/lustreapi.h>
+.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)
--- /dev/null
+.so man3/llapi_layout_comp_flags_get.3
--- /dev/null
+.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 <lustre/lustreapi.h>
+.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)
--- /dev/null
+.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 liblustreapi (7)
--- /dev/null
+.so man3/llapi_layout_comp_move.3
--- /dev/null
+.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 <lustre/lustreapi.h>
+.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)
--- /dev/null
+.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 <lustre/lustreapi.h>
+.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)
git://git.whamcloud.com / fs / lustre-release.git / commitdiff