llapi_file_open_volatile_idx(3)

LLAPI_LAYOUT_FILE_OPEN_VOLATILE(3)

Lustre Library Functions

LLAPI_LAYOUT_FILE_OPEN_VOLATILE(3)

NAME

llapi_layout_file_open_volatile, llapi_file_open_volatile - open new temporary file with layout

SYNOPSIS

#include <lustre/lustreapi.h>

int llapi_layout_file_open_volatile(const char *directory,
                                    int mdt_idx, int open_flags,
                                    mode_t mode,
                                    const struct llapi_layout *layout)

int llapi_file_open_volatile(const char *directory, int open_flags)

int llapi_file_open_volatile_idx(const char *directory,
                                 int mdt_idx, int open_flags)

int llapi_file_open_volatile_param(const char *directory,
                                 int mdt_idx, int open_flags,
                                 mode_t mode,
                                 const struct llapi_stripe_param *param)

The llapi_layout_file_open_volatile() function and its llapi_file_open_volatile*() variants open a file handle on a new anonymous, temporary, volatile file on a Lustre filesystem, similar to the Linux kernel open(2) O_TMPFILE functionality. The variants allow increasing specificity in the layout of the created file, see llapi_file_open_param(3) and llapi_layout_file_create(3) for details of usage. The created file is not visible in the namespace with ls(1). Once the file is closed, or the owning process dies, the file and its objects are permanently deleted from the filesystem.

With no layout or stripe parameters these functions will also work on a non-Lustre filesystem, where the file is created then unlinked, leaving only the file descriptor to access the file. This is not strictly equivalent because there is a small window during which the file is visible to users (provided they have access to the parent directory). Given a layout or stripe_param, the call instead fails there, since the striping cannot be applied: ENOTTY in general, or ENODEV when stripe_param names a pool, which is looked up before the filesystem is touched.

The directory parameter indicates where to create the file on the Lustre filesystem.

mdt_idx is the MDT index onto which to create the file. To use a default MDT, set mdt_idx to -1.

open_flags are standard open(2) flags, but a read-only access mode is promoted to O_RDWR and O_CREAT, O_EXCL and O_NOFOLLOW are always added: the file has to be created to be returned.

mode is the same as open(2).

layout and param are different structures that describe the striping information. If it is NULL, then the default for the directory is used. struct llapi_layout is an opaque data structure that is allocated by llapi_layout_alloc(3) and modified with the llapi_layout(7) functions.

RETURN VALUE

All variants return an open file descriptor on success, or a negative errno on failure.

ERRORS

The negative errno can be, but is not limited to:

-EINVAL: An invalid value was passed.
-ENOMEM: Not enough memory to allocate a resource.
-ENAMETOOLONG: The generated volatile file name does not fit in PATH_MAX.
-ENODEV: stripe_param names a pool and directory is not on a Lustre filesystem.
-ENOTTY: layout is non-NULL and directory is not on a Lustre filesystem.

EXAMPLES

Create volatile file on MDT0002, copy data to it, and swap layouts:

#include <lustre/lustreapi.h>
int main(int argc, char *argv[])
{


        int fd_src, fd_dst;


        __u64 dv_src, dv_dst;
	struct llapi_layout *layout = NULL;


        int rc;
	layout = llapi_layout_alloc();
	if (!layout) {


                fprintf(stderr, "%s: layout allocation failed: %s\n",


                        argv[0], strerror(errno));
		return errno;
	}
	rc = llapi_layout_stripe_count_set(layout, 2);
	:


        fd_dst = llapi_layout_file_open_volatile(argv[1], 2, 0, 0644, layout);


        if (fd_dst < 0) {
		rc = -fd_dst;


                fprintf(stderr, "%s: volatile file creation failed: %s\n",


                        argv[0], strerror(rc));


                goto out;


        }


        fd_src = open(argv[2], O_RDWR);


        rc = llapi_get_data_version(fd_src, &dv_src, 0);
	:


        /* copy data from @fd_src to @fd_dst */
	:


        rc = llapi_get_data_version(fd_src, &dv_dst, LL_DV_RD_FLUSH);
	:


        rc = llapi_fswap_layouts(fd_src, fd_dst, dv_src, dv_dst,


                                 SWAP_LAYOUTS_CLOSE);


        if (rc < 0) {


                fprintf(stderr, "%s: swap layouts failed: %s\n",


                        argv[0], strerror(-rc));


                goto out;


        }
out:
	llapi_layout_free(layout);


        return rc;
}

AVAILABILITY

The llapi_layout_file_open_volatile(), llapi_file_open_volatile(), llapi_file_open_volatile_idx(), and llapi_file_open_volatile_param() variants are part of the lustre(7) user application interface library since release 2.18.0. These functions were originally implemented as llapi_create_volatile_param(), llapi_create_volatile_idx(), and llapi_create_volatile() in release 2.4.0, but were renamed and deprecated because the create name does not accurately reflect that they return an open file descriptor.

AUTHORS

Frank Zago for Cray Inc.