llapi_layout_get_by_fd(3)

LLAPI_LAYOUT_GET_BY_FD(3)

Lustre Library Functions

LLAPI_LAYOUT_GET_BY_FD(3)

NAME

llapi_layout_get_by_fd, llapi_layout_get_by_fid, llapi_layout_get_by_path, llapi_layout_get_by_xattr, - obtain the layout of a Lustre file

SYNOPSIS

#include <lustre/lustreapi.h>

struct llapi_layout *llapi_layout_get_by_fd(int fd,
                                     enum llapi_layout_get_flags flags);

struct llapi_layout *llapi_layout_get_by_fid(const char *lustre_path,
                                     const struct lu_fid *fid,
                                     enum llapi_layout_get_flags flags);

struct llapi_layout *llapi_layout_get_by_path(const char *path,
                                     enum llapi_layout_get_flags flags);

struct llapi_layout *llapi_layout_get_by_xattr(void *lov_xattr,
                                     ssize_t lov_xattr_size,
                                     enum llapi_layout_get_flags flags);

The functions llapi_layout_get_by_xattr(), llapi_layout_get_by_fd(), llapi_layout_get_by_fid(), and llapi_layout_get_by_path() return a pointer to a newly-allocated struct llapi_layout containing the layout information for the file referenced by lov_xattr, fd, fid, or path, respectively. The 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. See llapi_layout(7). The pointer should be freed with llapi_layout_free() when it is no longer needed.

For llapi_layout_get_by_xattr(), lov_xattr is a Lustre layout extended attribute (LOV EA) from a file or directory in a Lustre filesystem. The lov_xattr should be the raw xattr without being byte-swapped, since this function will swap it to the local machine endianness properly.

For llapi_layout_get_by_fd(), fd is a valid open file descriptor for a file or directory in a Lustre filesystem.

For llapi_layout_get_by_fid(), lustre_path identifies the Lustre filesystem containing the file represented by fid. It is typically the filesystem root directory, but may also be any path beneath the root. Use the function llapi_path2fid(3) to obtain a struct lu_fid associated with a given path.

The function llapi_layout_get_by_path() accepts a path argument that names a file or directory in a Lustre filesystem.

Zero or more flags may be bitwise-or'd together in flags to control how a layout is retrieved. Currently llapi_layout_get_by_fd() and llapi_layout_get_by_fid() do not accept any values for flags, while llapi_layout_get_by_path() accepts only one flag as follows:

LLAPI_LAYOUT_GET_EXPECTED: Unspecified attribute values are replaced by the literal default values that will be assigned when the file is created or first written to. A default value is inherited from the parent directory if the attribute is specified there, otherwise it is inherited from the filesystem root. This flag is only recognized by llapi_layout_get_by_path(). Unspecified attributes may belong to directories and never-written-to files.

By default, layouts report the abstract value LLAPI_LAYOUT_DEFAULT to indicate an unspecified attribute. Use LLAPI_LAYOUT_GET_EXPECTED to discover the expected literal values for new files in a given directory. Do not use it if you need to distinguish between specified and unspecified attributes. The flag has no effect if path names a file or directory with a fully specified layout.

For concreteness, consider a Lustre filesystem with a default stripe size of 1048576 and a default stripe count of 1. A user sets the stripe count for directory D to 2 (thus overriding the filesystem-wide default) but leaves the stripe size unspecified. Newly created files in D inherit a stripe count of 2 from D and a stripe size of 1048576 from the filesystem default. The layout of D returned by llapi_layout_get_by_path(D, 0) has the abstract stripe size value LLAPI_LAYOUT_DEFAULT, since stripe size is unspecified, while llapi_layout_get_by_path(D, LLAPI_LAYOUT_GET_EXPECTED) reports the literal value 1048576. Both forms report a stripe count of 2, since that attribute is specified.

Valid arguments for flags with llapi_layout_get_by_xattr() are:

LLAPI_LAYOUT_GET_CHECK: If the LLAPI_LAYOUT_GET_CHECK flag is set, this function will check whether the objects count in lum is consistent with the stripe count in lum. This check only apply to regular files, so it should not be passed if the xattr is a default layout from a directory.
LLAPI_LAYOUT_GET_COPY: If the LLAPI_LAYOUT_GET_COPY flag is set, this function will use a temporary buffer for byte swapping when necessary, leaving lov_xattr unmodified. Otherwise, the byte swapping will be done to the fields of the lov_xattr buffer directly.

RETURN VALUES

These functions return a valid pointer on success or NULL on failure with errno set to an appropriate error code.

ERRORS

ENOMEM: Insufficient storage space is available.
ENOTTY: File does not reside on a Lustre filesystem.
ENOENT: path does not exist.
EINVAL: An invalid argument was specified.
EINTR: The kernel returned less than the expected amount of data.

NOTES

When using these functions to copy an existing file's layout to create a new file with llapi_layout_file_open (3) for mirroring, migration, or as the template for a new file, llapi_layout_ost_index_reset(3) should be called to reset the OST index values for each component, so that the file copy is not created on exactly the same OSTs as the original file.

AVAILABILITY

llapi_layout_get_by_fd(), llapi_layout_get_by_fid(), llapi_layout_get_by_path() and llapi_layout_get_by_xattr() are part of the lustre(7) user application interface library since release 2.7.0