LLAPI\_HSM\_STATE\_GET(3) Lustre Library Functions LLAPI\_HSM\_STATE\_GET(3)

# [NAME](#NAME)

llapi\_hsm\_state\_get, llapi\_hsm\_state\_get\_fd - get HSM state information for a file on a Lustre filesystem

# [SYNOPSIS](#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](#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*](#hus_archive_id)

External HSM archive ID associated with this file.

[*hus\_states*](#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**](#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**](#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**](#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**](#HS_ARCHIVED)

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

[**HS\_NORELEASE**](#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**](#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**](#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](#RETURN_VALUES)

**llapi\_hsm\_state\_get()** and **llapi\_hsm\_state\_get\_fd()** return:

**0**

on success

[**-errno**](#errno)

on failure

# [ERRORS](#ERRORS)

[**-ENOMEM**](#ENOMEM)

failed to allocate memory.

[**-ENAMETOOLONG**](#ENAMETOOLONG)

*path* was too long.

[**-ENOENT**](#ENOENT)

*path* does not point to a file or a directory.

[**-ENOTTY**](#ENOTTY)

*path* does not point to a Lustre filesystem.

# [EXAMPLES](#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](#AVAILABILITY)

**llapi\_hsm\_state\_get()** and **llapi\_hsm\_state\_get\_fd()** are part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) user application interface library since release 2.4.0

# [SEE ALSO](#SEE_ALSO)

[**lfs-hsm**(1)](/man/enterprise-packages/lustre/lfs-hsm.1), [**llapi\_hsm\_state\_set**(3)](/man/enterprise-packages/lustre/llapi_hsm_state_set.3), [**llapi\_hsm\_state\_set\_fd**(3)](/man/enterprise-packages/lustre/llapi_hsm_state_set_fd.3), [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7), [**lustreapi**(7)](/man/enterprise-packages/lustre/lustreapi.7)

2024-08-27 Lustre User API

---

Document: llapi_hsm_state_get(3) from lustre 2.17.60-r0 (Chainguard OS)
Source: https://github.com/lustre/lustre-release