LLAPI_POOL_UNPIN_FILE(3)

📦 version 2.17.58, in ubuntu stonking

💖 LLAPI_POOL_UNPIN_FILE(3) — Lustre Library Functions 💖

okay bestie, so this is the manual page for llapi_pool_unpin_fd, llapi_pool_unpin_file, and llapi_pool_unpin_fid, and it lives in the Lustre Library Functions section of the manual. she's niche, she's specific, and she's about to un-pin your pools. let's get into it 🫶

✨ NAME ✨

llapi_pool_unpin_fd, llapi_pool_unpin_file, llapi_pool_unpin_fid — remove pool pinning from a Lustre file

that's it, that's the whole vibe: unpin a pool pin from a file. 💅

🌸 SYNOPSIS 🌸

#include <lustre/lustreapi.h>

int llapi_pool_unpin_fd(int fd, const char *pool_name);

int llapi_pool_unpin_file(const char *path, const char *pool_name);

int llapi_pool_unpin_fid(const char *lustre_dir, const struct lu_fid *fid,
                         const char *pool_name);

look at those three icons. one takes an fd, one takes a path, one takes a fid + a lustre_dir. pick your fighter, they all do the same job 💖

🦋 DESCRIPTION 🦋

The llapi_pool_unpin_*(3) functions manipulate the Lustre lustre.pin extended attribute of a file in order to remove any pin for a particular OST pool.

so basically: your file has an xattr called lustre.pin, and that xattr is holding onto a pin tying the file to a specific OST pool. these functions go in and yeet that pin out. 🧚

Pool pins are stored as YAML entries of the form

pool: pool_name

inside the lustre.pin attribute, which may also contain other entries such as hsm pins used by the PCC subsystem. Multiple pool pins and PCC pins can coexist in the same attribute.

so like, the lustre.pin xattr isn't a one-pin-only situation — it's a whole group chat. pool pins and hsm pins (the PCC subsystem ones) can all be sitting in there together, coexisting, no drama. ✨

The llapi_pool_unpin_fd(), llapi_pool_unpin_file() and llapi_pool_unpin_fid() functions remove the pool entry for pool_name from the lustre.pin attribute of the referenced file. If no matching entry is found, or if the lustre.pin attribute is missing, the call fails with ENOENT and the file is not modified. When the last entry is removed from lustre.pin , the attribute itself is deleted.

okay so lowkey important stuff here, bestie:

  • they remove the pool entry for pool_name from the lustre.pin attribute of the file you referenced.
  • no matching entry? or the lustre.pin attribute just... isn't there? then the call fails with ENOENT and the file is not modified. no partial chaos, no half-edits. 🙈
  • and when the last entry gets removed from lustre.pin , the attribute itself gets deleted too. clean exit, she takes the whole xattr with her. 💀

The pool_name parameter may optionally be qualified with a filesystem name using the "fsname.pool" notation commonly used by Lustre tools. In this case the "fsname." prefix is silently discarded before the pool name is stored or compared, and only the unqualified pool name is recorded in the lustre.pin attribute.

so you can write your pool name the fancy way, "fsname.pool", the notation Lustre tools love. and the "fsname." prefix? she gets silently discarded before the name is stored or compared. only the unqualified pool name ever lands in the lustre.pin attribute. no cap. 🎀

💜 RETURN VALUES 💜

The llapi_pool_unpin_*() functions return 0 on success. On failure they return a negative errno value and set errno to the corresponding error code.

0 = slay, it worked. negative errno + errno set to match = not slay, go read errno. ⭐

🔥 ERRORS 🔥

Errors from llapi_pool_name_validate(3) will be returned on malformed pool names.

if your pool name is malformed, you get whatever llapi_pool_name_validate(3) throws back at you. iykyk. ✨

  • EINVAL — An invalid argument was specified.
  • ENOENT — No pool entry for the specified pool_name was found in the lustre.pin attribute when calling one of the llapi_pool_unpin_*() functions, or the attribute itself was missing.

🌈 EXAMPLES 🌈

#include <lustre/lustreapi.h>

if (llapi_pool_unpin_file(path, pool_name) < 0) {
     if (errno == ENOENT) {
          /* file was not pinned to this pool */
     } else {
          perror("llapi_pool_unpin_file");
     }
}

see how she handles the ENOENT case all casual? "oh, file was not pinned to this pool, that's fine, no notes." and literally anything else gets the perror("llapi_pool_unpin_file"). iconique error handling fr fr. 💅

👑 AVAILABILITY 👑

The llapi_pool_unpin_fd(), llapi_pool_unpin_file(), and llapi_pool_unpin_fid() functions are part of the lustre(7) user application interface library since release 2.18.0.

so if you're on 2.18.0 or later, you're in. before that? bestie, she wasn't born yet. 🍼

💖 SEE ALSO 💖

go read llapi_pool_pin_file(3) if you wanna do the opposite and pin it back, and llapi_pool_is_pinned_file(3) if you just gotta know. 🦋

and that's the whole page, bestie!! this came from the Lustre User API, dated 2026-08-23 — so go forth, unpin those pools, and remember: if it's ENOENT, the file was literally just not pinned to that pool, and that's genuinely fine. periodt. 💖✨🎀

📦 where this page comes from