LLAPI_POOL_IS_PINNED_FILE(3)

✨ llapi_pool_is_pinned_fd, llapi_pool_is_pinned_file, llapi_pool_is_pinned_fid ✨

okay bestie, welcome to the Lustre Library Functions corner of the manual 💖 you're reading the page for llapi_pool_is_pinned_fd, llapi_pool_is_pinned_file, and llapi_pool_is_pinned_fid — the trio that tells you whether a Lustre file is pinned to an OST pool 🎀

---

🌸 NAME 🌸

llapi_pool_is_pinned_fd, llapi_pool_is_pinned_file, llapi_pool_is_pinned_fid — the girlies that 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 💜

So the llapi_pool_is_pinned_*(3) functions check whether a Lustre file currently has a pool entry for pool_name inside its lustre.pin extended attribute. no cap, that's the whole vibe check 🔥

Pool pins live as YAML entries shaped like this:

pool: pool_name

...stored inside the lustre.pin attribute, which can also hold other entries — like the hsm pins that the PCC subsystem uses 👑 and yes, multiple pool pins AND PCC pins can all coexist in that same attribute, they're not fighting, they're just roommates 🫶

Now, the receipts 📋: llapi_pool_is_pinned_fd(), llapi_pool_is_pinned_file(), and llapi_pool_is_pinned_fid() 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 — and yes, that includes when the lustre.pin attribute is missing entirely, like not even a trace 🌸 On error — say 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 can optionally be qualified with a filesystem name using the "fsname.pool" notation that Lustre tools use all the time. In that case the "fsname." prefix is silently discarded before the pool name is stored or compared, and only the unqualified pool name gets recorded in the lustre.pin attribute 🙈 just so you know.

---

🎀 RETURN VALUES 🎀

The llapi_pool_is_pinned_*() functions return 1 if a matching pool pin entry is present, 0 if it's not, and a negative error code (-errno) if something went wrong 💀

---

⭐ ERRORS ⭐

• ENAMETOOLONG — the pool_name exceeds the maximum number of characters. too long bestie, it's giving overflow 💅
• ENXIO — the pool_name was not specified. not me passing nothing 😭
• EINVAL — an invalid argument was specified. classic. iconic. invalid.

---

🌈 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 */
}

like, if pinned is negative, something broke, report it and abort 🚨 if it's truthy, the file is pinned to this pool ✨ and if it's 0, she's not pinned to this pool at all, simple as that 💖

---

👑 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 🎉 so if your release is older than that, this is not the page for you, sorry bestie 😭

---

💖 SEE ALSO 💖

llapi_pool_name_validate(3), llapi_pool_pin_file(3), llapi_pool_unpin_file(3), lustre(7), lustreapi(7) — go read those next, they're all in the same friend group 🫶

---

okay that's the whole page, you ate it 💅 this was the Lustre User API edition, dated 2026-08-23, brought to you by the fine humans of the Lustre project — stay pinned, stay slay, and remember: 0 means not pinned, 1 means pinned, negative means go check errno 🎀✨