LLAPI\_LAYOUT(7) Lustre Miscellaneous Information LLAPI\_LAYOUT(7)

# [NAME](#NAME)

llapi\_layout - abstract interface to the layout of a Lustre file

# [SYNOPSIS](#SYNOPSIS)

```
#include <lustre/lustreapi.h>
```

# [DESCRIPTION](#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)](/man/enterprise-packages/lustre/llapi_layout_alloc.3).

•

Assign attribute values using the **llapi\_layout\_\*[\_set (3)](/man/enterprise-packages/lustre/_set.3)** functions.

•

Create the file using [**llapi\_layout\_file\_create**(3)](/man/enterprise-packages/lustre/llapi_layout_file_create.3).

•

Free the layout memory using [**llapi\_layout\_free**(3)](/man/enterprise-packages/lustre/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)](/man/enterprise-packages/lustre/llapi_layout_get_by_path.3), [**llapi\_layout\_get\_by\_fd**(3)](/man/enterprise-packages/lustre/llapi_layout_get_by_fd.3), [**llapi\_layout\_get\_by\_fid**(3)](/man/enterprise-packages/lustre/llapi_layout_get_by_fid.3), or [**llapi\_layout\_get\_by\_xattr**(3)](/man/enterprise-packages/lustre/llapi_layout_get_by_xattr.3) functions.

•

To access attribute values from **struct llapi\_layout** use the **llapi\_layout\_\*[\_get (3)](/man/enterprise-packages/lustre/_get.3)** functions.

•

To free the previously allocated layout memory use [**llapi\_layout\_free**(3)](/man/enterprise-packages/lustre/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)](/man/enterprise-packages/lustre/llapi_layout_alloc.3).

•

Assign attribute values using the **llapi\_layout\_\*[\_set (3)](/man/enterprise-packages/lustre/_set.3)** functions.

•

Allocate second layout component with [**llapi\_layout\_alloc**(3)](/man/enterprise-packages/lustre/llapi_layout_alloc.3).

•

Add the second layout into the first one using [**llapi\_layout\_comp\_add**(3)](/man/enterprise-packages/lustre/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)](/man/enterprise-packages/lustre/llapi_layout_file_create.3).

•

Free the layout memory using [**llapi\_layout\_free**(3)](/man/enterprise-packages/lustre/llapi_layout_free.3).

# [BUGS](#BUGS)

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

The RAID pattern may only be set to 0.

# [EXAMPLES](#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](#AVAILABILITY)

**llapi\_layout** is part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) user application interface library since release 2.7.0

# [SEE ALSO](#SEE_ALSO)

[**lfs**(1)](/man/enterprise-packages/lustre/lfs.1), [**lfs-setstripe**(1)](/man/enterprise-packages/lustre/lfs-setstripe.1), [**open**(2)](/man/enterprise-packages/lustre/open.2), [**llapi\_layout\_alloc**(3)](/man/enterprise-packages/lustre/llapi_layout_alloc.3), [**llapi\_layout\_comp\_add**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_add.3), [**llapi\_layout\_comp\_del**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_del.3), [**llapi\_layout\_comp\_extent\_get**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_extent_get.3), [**llapi\_layout\_comp\_extent\_set**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_extent_set.3), [**llapi\_layout\_comp\_flags\_clear**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_flags_clear.3), [**llapi\_layout\_comp\_flags\_get**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_flags_get.3), [**llapi\_layout\_comp\_flags\_set**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_flags_set.3), [**llapi\_layout\_comp\_id\_get**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_id_get.3), [**llapi\_layout\_comp\_use**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_use.3), [**llapi\_layout\_comp\_use\_id**(3)](/man/enterprise-packages/lustre/llapi_layout_comp_use_id.3), [**llapi\_layout\_file\_comp\_add**(3)](/man/enterprise-packages/lustre/llapi_layout_file_comp_add.3), [**llapi\_layout\_file\_comp\_del**(3)](/man/enterprise-packages/lustre/llapi_layout_file_comp_del.3), [**llapi\_layout\_file\_create**(3)](/man/enterprise-packages/lustre/llapi_layout_file_create.3), [**llapi\_layout\_file\_open**(3)](/man/enterprise-packages/lustre/llapi_layout_file_open.3), [**llapi\_layout\_file\_open\_volatile**(3)](/man/enterprise-packages/lustre/llapi_layout_file_open_volatile.3), [**llapi\_layout\_free**(3)](/man/enterprise-packages/lustre/llapi_layout_free.3), [**llapi\_layout\_get\_by\_fd**(3)](/man/enterprise-packages/lustre/llapi_layout_get_by_fd.3), [**llapi\_layout\_get\_by\_fid**(3)](/man/enterprise-packages/lustre/llapi_layout_get_by_fid.3), [**llapi\_layout\_get\_by\_path**(3)](/man/enterprise-packages/lustre/llapi_layout_get_by_path.3), [**llapi\_layout\_get\_by\_xattr**(3)](/man/enterprise-packages/lustre/llapi_layout_get_by_xattr.3), [**llapi\_layout\_ost\_index\_get**(3)](/man/enterprise-packages/lustre/llapi_layout_ost_index_get.3), [**llapi\_layout\_ost\_index\_reset**(3)](/man/enterprise-packages/lustre/llapi_layout_ost_index_reset.3), [**llapi\_layout\_ost\_index\_set**(3)](/man/enterprise-packages/lustre/llapi_layout_ost_index_set.3), [**llapi\_layout\_pattern\_get**(3)](/man/enterprise-packages/lustre/llapi_layout_pattern_get.3), [**llapi\_layout\_pattern\_set**(3)](/man/enterprise-packages/lustre/llapi_layout_pattern_set.3), [**llapi\_layout\_pool\_name\_get**(3)](/man/enterprise-packages/lustre/llapi_layout_pool_name_get.3), [**llapi\_layout\_pool\_name\_set**(3)](/man/enterprise-packages/lustre/llapi_layout_pool_name_set.3), [**llapi\_layout\_stripe\_count\_get**(3)](/man/enterprise-packages/lustre/llapi_layout_stripe_count_get.3), [**llapi\_layout\_stripe\_count\_set**(3)](/man/enterprise-packages/lustre/llapi_layout_stripe_count_set.3), [**llapi\_layout\_stripe\_size\_get**(3)](/man/enterprise-packages/lustre/llapi_layout_stripe_size_get.3), [**llapi\_layout\_stripe\_size\_set**(3)](/man/enterprise-packages/lustre/llapi_layout_stripe_size_set.3), [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7), [**lustreapi**(7)](/man/enterprise-packages/lustre/lustreapi.7)

2024-08-27 Lustre User API

---

Document: llapi_layout(7) from lustre 2.17.59-r1 (Chainguard OS)
Source: https://github.com/lustre/lustre-release