LLAPI_HSM_STATE_GET(3)

💖 LLAPI_HSM_STATE_GET(3) 💖

okay bestie, welcome to the Lustre Library Functions section of the manual, and today's main character is llapi_hsm_state_get — she's the one who tells you what's going on with a file's HSM state, no cap 🦋

---

✨ 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 🌸

So basically, these functions hand you the HSM state flags and the HSM archive ID for whichever file you're pointing at — either by path or by fd, your choice, we don't gatekeep 💅

The tea gets poured into the hus argument, and heads up: you gotta have that memory already allocated yourself. She's not malloc-ing for you, that's your job, periodt.

struct hsm_user_state {
     __u32     hus_states;
     __u32     hus_archive_id;
};

the struct fields, explained (affectionately)

• hus_archive_id — the External HSM archive ID associated with this file 🔥
• hus_states — a flag mask for all the different HSM states and policy hints. It's giving bitfield energy, iykyk.

---

the state flags 🎀

the value of hus_states is literally built by bitwise or'ing all the following possible states together, so like, stack 'em up:

• 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. she exists, she's archived-ish, tread carefully 🫶
• HS_DIRTY — the file content is not in sync with the HSM archive. This flag gets set automatically when a file with HS_EXISTS set is changed, and a user can also set it explicitly. messy on purpose 💀
• HS_RELEASED — the file content is not present in Lustre, and must be restored from the HSM archive before the file can be accessed. Also the file must be HS_ARCHIVED state and not HS_DIRTY. so many requirements, honestly iconic 🙈
• HS_ARCHIVED — a complete copy of the file content exists in the HSM archive. slay 💖
• HS_NORELEASE — this flag says the file content should never be released. file content will stay in Lustre even if a copy exists in HSM backend. a user can set this one. she's staying put, no takebacks ✨
• HS_NOARCHIVE — the file will not be archived. might be used for a large temporary file, for example. a user can set this. yeah she's not getting archived bestie 🌈
• HS_LOST — the file content in the archive is not available, and the file can not be restored. If this file is also HS_RELEASED, then attempts to access the file will fail. An administrator can set this flag. 💀💀💀

---

👑 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 🦋

ngl this example is so cute, it just prints out the flags that are set:

#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)

---

okay that's the whole page bestie, you're officially HSM-state-literate 💅✨ this was brought to you by the Lustre User API, dated 2024-08-27, under the very important heading LLAPI_HSM_STATE_GET(3) — go forth and state_get responsibly 🎀🦋💖