LLAPI_LAYOUT_FILE_CREATE(3)

NAME
llapi_layout_file_open, llapi_layout_file_create, llapi_layout_set_by_fd, llapi_layout_set_by_xattr - open and apply a layout to a Lustre file

SYNOPSIS
#include <lustre/lustreapi.h>

int llapi_layout_file_open(char *path, int open_flags, int mode,
                           const struct llapi_layout *layout);

int llapi_layout_file_create(char *path, int open_flags,
                             int mode,
                             const struct llapi_layout *layout);

int llapi_layout_set_by_fd(int fd,
                           struct llapi_layout *layout);

int llapi_layout_set_by_xattr(int fd, struct lov_user_md *lum);

DESCRIPTION
The functions llapi_layout_file_open() and llapi_layout_file_create() open and possibly create a file at path with the permissions specified in mode using the Lustre layout attributes in layout. The returned file descriptor may be used in subsequent system calls (read(2), write(2), lseek(2), etc.), and closed with close(2). One access mode and zero or more file creation flags and file status flags may be bitwise-or'd in open_flags. See open(2). If layout is non-NULL and path is not on a Lustre filesystem this function will fail and set errno to ENOTTY.

The function llapi_layout_set_by_fd set the layout on an open file or directory specified by fd.

The function call

llapi_layout_file_create(path, open_flags, mode, layout)

shall be equivalent to:

llapi_layout_file_open(path, open_flags|O_CREAT|O_EXCL, mode, layout)

The layout and mode will not be applied to a file which already exists. Callers requiring a guarantee that the opened file is created with the specified layout and mode should use llapi_layout_file_create().

A NULL layout may be specified, in which case the standard Lustre behavior for assigning layouts to newly-created files will apply.

If the pool name attribute of layout has been set, it must refer to an OST pool that exists and contains one or more OSTs, otherwise these functions will fail and set errno to EINVAL. See llapi_layout_pool_name_set(3).

For llapi_layout_set_by_fd(), fd is a valid file descriptor for a file or directory in a Lustre filesystem and layout is a valid Lustre layout to set on the file.

For llapi_layout_set_by_xattr(), fd is a valid file descriptor for a file or a directory in a Lustre filesystem and lum is a valid raw xattr to set on the file.

RETURN VALUES
llapi_layout_file_open() and llapi_layout_file_create() return a new file descriptor, or -1 if an error occurred (in which case, errno is set appropriately).

ERRORS

ENOTTY
    path does not reside on a Lustre filesystem.

EINVAL
    An invalid argument was specified.

AVAILABILITY
llapi_layout_file_open() and llapi_layout_file_create() are part of the lustre(7) user application interface library since release 2.7.0

SEE ALSO
close(2), open(2), llapi_layout_alloc(3), llapi_layout_pool_name_set(3), llapi_layout(7), lustreapi(7)