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
.PP
Using this interface to create a file might consist of the following steps.
.IP \[bu]
-Allocate a layout with
-.BR llapi_layout_alloc() .
+Allocate
+.B struct layout
+with
+.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() ,
+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() .
+.BR llapi_layout_get_by_fid (3)
+functions.
+.IP \[bu]
+To access attribute values from
+.B struct llapi_layout
+use the
+.B llapi_layout_*_get (3)
+functions.
+.IP \[bu]
+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:
+.IP \[bu]
+Allocate first layout component with
+.BR llapi_layout_alloc (3).
.IP \[bu]
-Read attribute values using the
-.B llapi_layout_*_get()
+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;
+ /* Allocate layout */
+ struct llapi_layout *layout = llapi_layout_alloc();
- path = argv[1];
- 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);
+}
+.fi
+.PP
+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);
+ 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_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);
- return 0;
}
.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_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)
git://git.whamcloud.com / fs / lustre-release.git / blobdiff