llapi_pool_pin_file(3)

NAME

llapi_pool_pin_fd, llapi_pool_pin_file, llapi_pool_pin_fid - pin a Lustre file to an OST pool

SYNOPSIS

#include <lustre/lustreapi.h>

int llapi_pool_pin_fd(int fd, const char *pool_name);

int llapi_pool_pin_file(const char *path, const char *pool_name);

int llapi_pool_pin_fid(const char *lustre_dir, const struct lu_fid *fid,
                       const char *pool_name);

DESCRIPTION

The llapi_pool_pin_*(3) functions manipulate the Lustre lustre.pin extended attribute of a file in order to record whether the file is pinned to a particular OST pool.

Pool pins are stored as YAML entries of the form

pool: pool_name

The llapi_pool_pin_fd(), llapi_pool_pin_file() and llapi_pool_pin_fid() functions add a pool entry for the specified pool_name to the lustre.pin extended attribute of the referenced file if it is not already present, leaving the attribute unchanged when the entry already exists.

The llapi_pool_unpin_fd(), llapi_pool_unpin_file() and llapi_pool_unpin_fid() functions are documented in llapi_pool_unpin_file(3).

The llapi_pool_is_pinned_fd(), llapi_pool_is_pinned_file() and llapi_pool_is_pinned_fid() functions are documented in llapi_pool_is_pinned_file(3).

The pool_name parameter may optionally be qualified with a filesystem name using the "fsname.pool" notation commonly used by Lustre tools. In this case the "fsname." prefix is silently discarded before the pool name is stored or compared, and only the unqualified pool name is recorded in the lustre.pin attribute.

RETURN VALUES

The llapi_pool_pin_*() functions return 0 on success. On failure they return a negative errno value and set errno to the corresponding error code.

ERRORS

Errors from llapi_pool_name_validate(3) will be returned on malformed pool names.

EINVAL

An invalid argument was specified.

EXAMPLES

#include <lustre/lustreapi.h>
if (llapi_pool_pin_file(path, pool_name) < 0) {
	perror("llapi_pool_pin_file");
	/* handle error based on errno */
}

AVAILABILITY

The llapi_pool_pin_fd(), llapi_pool_pin_file(), llapi_pool_pin_fid() functions are part of the lustre(7) user application interface library since release 2.18.0.

SEE ALSO

llapi_pool_is_pinned_file(3), llapi_pool_name_validate(3), llapi_pool_unpin_file(3), lustre(7), lustreapi(7)