LLAPI_POOL_PIN_FILE(3)

💖 LLAPI_POOL_PIN_FILE(3) 💖

okay bestie, welcome to the Lustre Library Functions corner of the manual 💅 this is the one about pinning a Lustre file to an OST pool, and honestly? it's giving "tiny function, big responsibility."

---

✨ 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);

three little functions, one big vibe. let's get into it 🦋

---

✨ DESCRIPTION ✨

So. The llapi_pool_pin_*(3) functions are all about manipulating the Lustre lustre.pin extended attribute of a file, specifically to record whether that file is pinned to a particular OST pool. no cap.

Pool pins get stored as YAML entries that look exactly like this:

pool: pool_name

…inside the lustre.pin attribute. and here's the cute part: that attribute can also hold other entries, like the hsm pins used by the PCC subsystem. so multiple pool pins and PCC pins can all coexist in the same attribute like the besties they are. 💖

Now, llapi_pool_pin_fd(), llapi_pool_pin_file() and llapi_pool_pin_fid() add a pool entry for the specified pool_name to the lustre.pin extended attribute of the referenced file — but only if it's not already there. if the entry already exists, they leave the attribute completely unchanged. respectful. iconic. ✨

If you're looking for the unpinning squad, llapi_pool_unpin_fd(), llapi_pool_unpin_file() and llapi_pool_unpin_fid() are documented over in llapi_pool_unpin_file(3) 🫶

And if you just wanna know whether something's pinned (the nosy bestie energy), llapi_pool_is_pinned_fd(), llapi_pool_is_pinned_file() and llapi_pool_is_pinned_fid() live in llapi_pool_is_pinned_file(3).

One more thing, and this is important so listen up 👑 — the pool_name parameter can optionally be qualified with a filesystem name using the "fsname.pool" notation that Lustre tools commonly use. when that happens, the "fsname." prefix gets silently discarded before the pool name is stored or compared, and only the unqualified pool name is recorded in the lustre.pin attribute. periodt. it just disappears. no drama, no error, poof 💨

---

✨ 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. so yeah, check both, bestie.

---

✨ ERRORS ✨

Errors coming from llapi_pool_name_validate(3) will be returned on malformed pool names. (basically if your pool name is cursed, that function has opinions and you'll hear about them 💀)

• EINVAL — An invalid argument was specified.

---

✨ EXAMPLES ✨

here's the whole thing in action, look at her go 🌸

#include <lustre/lustreapi.h>

if (llapi_pool_pin_file(path, pool_name) < 0) {
     perror("llapi_pool_pin_file");
     /* handle error based on errno */
}

see that perror? that's your bestie telling you what went wrong. always handle your errors, we don't do silent failures in this house 🎀

---

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

---

and that's the whole page babes 🦋 this gem shipped as part of the Lustre User API, dated 2026-08-23 — go forth and pin responsibly, mwah 💅💖✨