llapi_layout(7)

NAME

llapi_layout - abstract interface to the layout of a Lustre file

SYNOPSIS

#include <lustre/lustreapi.h>

DESCRIPTION

The llapi_layout family of 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 struct llapi_layout which is passed as a handle to the various functions.

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. 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 _get and _set 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.

•

Allocate struct llapi_layout with llapi_layout_alloc(3).

•

Assign attribute values using the llapi_layout_*_set (3) functions.

•

Create the file using llapi_layout_file_create(3).

•

Free the layout memory using llapi_layout_free(3).

Similarly, these steps might be used to read a file layout:

•

One can allocate and initialize a new struct layout from an existing file with one of the llapi_layout_get_by_path(3), llapi_layout_get_by_fd(3), llapi_layout_get_by_fid(3), or llapi_layout_get_by_xattr(3) functions.

•

To access attribute values from struct llapi_layout use the llapi_layout_*_get (3) functions.

•

To free the previously allocated layout memory use llapi_layout_free(3).

Using this interface to create a file with composite layout consists of the following steps:

•

Allocate first layout component with llapi_layout_alloc(3).

•

Assign attribute values using the llapi_layout_*_set (3) functions.

•

Allocate second layout component with llapi_layout_alloc(3).

•

Add the second layout into the first one using llapi_layout_comp_add(3).

•

Assign attribute values to second layout using the llapi_layout_*_set(3) functions.

•

Repeat above two steps to add more components.

•

Create the file using llapi_layout_file_create(3).

•

Free the layout memory using llapi_layout_free(3).

BUGS

Setting the OST index number is only supported for stripe number 0.

The RAID pattern may only be set to 0.

EXAMPLES

Example 1: Create file with specified layout, then query the layout attributes.

{
	/* Allocate layout */
	struct llapi_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);
	/* 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);
	/* Free layout */
	llapi_layout_free(layout);
}

Example 2: Create file with composite layout.

{
	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,
			     (uint64_t)-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);
}

Example 3: Traverse components of a composite layout.

{
	/* 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);
}

AVAILABILITY

llapi_layout is part of the lustre(7) user application interface library since release 2.7.0

SEE ALSO

lfs(1), lfs-setstripe(1), open(2), llapi_layout_alloc(3), 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_clear(3), llapi_layout_comp_flags_get(3), llapi_layout_comp_flags_set(3), llapi_layout_comp_id_get(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), llapi_layout_file_open(3), llapi_layout_file_open_volatile(3), llapi_layout_free(3), llapi_layout_get_by_fd(3), llapi_layout_get_by_fid(3), llapi_layout_get_by_path(3), llapi_layout_get_by_xattr(3), llapi_layout_ost_index_get(3), llapi_layout_ost_index_reset(3), llapi_layout_ost_index_set(3), llapi_layout_pattern_get(3), llapi_layout_pattern_set(3), llapi_layout_pool_name_get(3), llapi_layout_pool_name_set(3), llapi_layout_stripe_count_get(3), llapi_layout_stripe_count_set(3), llapi_layout_stripe_size_get(3), llapi_layout_stripe_size_set(3), lustre(7), lustreapi(7)