LLAPI_HSM_STATE_GET(3)

NAME
llapi_hsm_state_get, llapi_hsm_state_get_fd - get HSM state information for a file on a Lustre filesystem

SYNOPSIS
#include <lustre/lustreapi.h>

int llapi_hsm_state_get(const char *path, struct hsm_user_state *hus);

int llapi_hsm_state_get_fd(int fd, struct hsm_user_state *hus);

DESCRIPTION
These functions return the HSM state flags and HSM archive ID for the file referred to by path or fd. Information is returned in the hus argument which should already be allocated.

struct hsm_user_state {
	__u32	hus_states;
	__u32	hus_archive_id;
};

hus_archive_id
    External HSM archive ID associated with this file.

hus_states
    Flag mask for different HSM states and policy hints.

The value of hus_states is formed by bitwise or'ing the following possible states:

HS_EXISTS
    The file has been assigned to an archive and provided to the backend for archiving. Partial copies may exist in the HSM archive and will need to be deleted when the file is removed.

HS_DIRTY
    The file content is not in sync with the HSM archive. This flag is set automatically when a file with HS_EXISTS set is changed, and can be set explicitly by a user.

HS_RELEASED
    The file content is not present in Lustre, and must be restored from the HSM archive before the file can be accessed. File must also be HS_ARCHIVED state and not HS_DIRTY.

HS_ARCHIVED
    A complete copy of the file content exists in the HSM archive.

HS_NORELEASE
    This flag indicates the file content should never be released. File content will stay in Lustre even if a copy exists in HSM backend. This can be set by a user.

HS_NOARCHIVE
    The file will not be archived. This might be used for a large temporary file, for example. This can be set by a user.

HS_LOST
    The file content in the archive is not available, and file can not be restored. If this file is also HS_RELEASED, then attempts to access the file will fail. This flag can be set by an administrator.

RETURN VALUES
llapi_hsm_state_get() and llapi_hsm_state_get_fd() return:

0   on success

-errno
    on failure

ERRORS

-ENOMEM
    failed to allocate memory.

-ENAMETOOLONG
    path was too long.

-ENOENT
    path does not point to a file or a directory.

-ENOTTY
    path does not point to a Lustre filesystem.

EXAMPLES
#include <stdlib.h>
#include <stdio.h>
#include <errno.h>

#include <lustre/lustreapi.h>

int main(int argc, char **argv)
{
	struct hsm_user_state hus;
	int rc;

	if (argc < 2) {
		fprintf(stderr, "usage: prog FILEPATH\n");
		exit(1);
	}

	rc = llapi_hsm_state_get(argv[1], &hus);
	if (rc) {
		fprintf(stderr, "can't get hsm state for %s: %s\n",
			argv[1], strerror(-rc));
		exit(rc);
	}

	if (hus.hus_states & HS_RELEASED)
		printf(" released");
	if (hus.hus_states & HS_EXISTS)
		printf(" exists");
	if (hus.hus_states & HS_ARCHIVED)
		printf(" archived");

	/* Display settable flags */
	if (hus.hus_states & HS_NORELEASE)
		printf(" never_release");
	if (hus.hus_states & HS_NOARCHIVE)
		printf(" never_archive");
	if (hus.hus_states & HS_DIRTY)
		printf(" dirty");
	if (hus.hus_states & HS_LOST)
		printf(" lost_from_hsm");

	if (hus.hus_archive_id != 0)
		printf(", archive_id:%d", hus.hus_archive_id);

	printf("\n");

	exit(0);
}

AVAILABILITY
llapi_hsm_state_get() and llapi_hsm_state_get_fd() are part of the lustre(7) user application interface library since release 2.4.0

SEE ALSO
lfs-hsm(1), llapi_hsm_state_set(3), llapi_hsm_state_set_fd(3), lustre(7), lustreapi(7)