llapi_pool_is_pinned_fd(3)

NAME

llapi_pool_is_pinned_fd, llapi_pool_is_pinned_file, llapi_pool_is_pinned_fid - test whether a Lustre file is pinned to an OST pool

SYNOPSIS

#include <lustre/lustreapi.h>

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

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

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

DESCRIPTION

The llapi_pool_is_pinned_*(3) functions test whether a Lustre file currently has a pool entry for pool_name in its lustre.pin extended attribute.

Pool pins are stored as YAML entries of the form

pool: pool_name

The llapi_pool_is_pinned_fd(), llapi_pool_is_pinned_file() and llapi_pool_is_pinned_fid() functions return 1 only if a matching pool entry for pool_name is present in the lustre.pin attribute. They return 0 when no such entry exists, including when the lustre.pin attribute is missing entirely. On error, such as an invalid pool_name argument, failures resolving a FID, or I/O or parse errors while reading the attribute, these functions return a negative error code (-errno), for example -EINVAL or -ENOENT.

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_is_pinned_*() functions return 1 if a matching pool pin entry is present, 0 if not, and a negative error code (-errno) on failure.

ERRORS

ENAMETOOLONG

The pool_name exceeds the maximum number of characters.

ENXIO

The pool_name was not specified.

EINVAL

An invalid argument was specified.

EXAMPLES

#include <lustre/lustreapi.h>
int pinned;
pinned = llapi_pool_is_pinned_file(path, pool_name);
if (pinned < 0) {
	/* error: report and abort */
	fprintf(stderr, "llapi_pool_is_pinned_file failed: %s0,
		strerror(-pinned));
	exit(EXIT_FAILURE);
}
if (pinned) {
	/* file is pinned to this pool */
} else {
	/* file is not pinned to this pool */
}

AVAILABILITY

The llapi_pool_is_pinned_fd(), llapi_pool_is_pinned_file(), and llapi_pool_is_pinned_fid() functions are part of the lustre(7) user application interface library since release 2.18.0.

SEE ALSO

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