LLAPI_GET_FSNAME(3)

💖 LLAPI_GET_FSNAME_INSTANCE — lustre library functions, bestie edition 💖

okay so this is a page from the Lustre Library Functions section (section 3 of the manual, iykyk) and it's literally all about finding out which filesystem you're standing in and which mount of it you're talking to. four little functions, one big slay. let's get into it 🫶

---

✨ NAME ✨

llapi_get_fsname_instance, llapi_get_fsname, llapi_get_instance, llapi_getname — get the client filesystem name and instance, periodt.

---

🌸 SYNOPSIS 🌸

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <lustre/lustreapi.h>

int llapi_getname(const char *path, char *name, size_t namelen);

int llapi_get_fsname_instance(const char *path, char *fsname,
                              size_t fsname_len, char *instance,
                              size_t instance_len);

int llapi_get_fsname(const char *path, char *fsname,
                     size_t fsname_len);

int llapi_get_instance(const char *path, char *instance,
                       size_t instance_len);

like. four whole functions. no cap. 🦋

---

👑 DESCRIPTION 👑

so llapi_get_fsname_instance() is the main character here 💅 — you hand it a path, and it goes and retrieves the filesystem fsname and the instance for that path, dropping them into the fsname and instance buffers respectively. each buffer can respectively hold at least fsname_len (which is at least LUSTRE_MAXFSNAME bytes) and instance_len (at least LUSTRE_MAXINSTANCE bytes). so like. size your buffers, bestie. 🎀

if you only need one of the two, don't be extra about it — just use llapi_get_fsname(3) or llapi_get_instance(3) for the one you actually want. and if you want them glued together into one string? that's llapi_getname(3), which returns the combined fsname-instance string. one-stop shop. ⭐

now let's talk about what these things even are:

• the filesystem fsname is a short name — think 'testfs' or 'lfs2g' — that identifies the filesystem on the clients and the servers, for mounting and configuration. it's the name-name.
• the instance is a client-unique temporary identifier, like 'ffff8803c9c0f000', that differentiates multiple mounts of the same filesystem on the same client. so if you've got the same fs mounted twice on one box, the instance is how you tell them apart.

lowkey important caveat bestie: the instance is not guaranteed to be unique between different clients, and it's not expected to be the same for repeated mounts on the same client. so don't go building your whole personality on it being stable. 🙈

and where do these show up in the wild? the filesystem identifier gets used in client-side parameters, like mdc.fsname-MDT0000-mdc-instance.max_rpcs_in_flight for MDC and OSC devices, or llite.fsname-instance.max_cached_mb and similar for llite tunable values and statistics. that's the real-world glow-up. ✨

---

🔥 RETURN VALUES 🔥

• 0 — on success, we ate 💅
• -ve — error code on failure, and it sets errno appropriately. so like, check errno, girl.

---

💀 ERRORS 💀

• EINVAL — Invalid filesystem information found. something's off and it's not giving what it needs to give.
• ENAMETOOLONG — The fsname_len, instance_len, or namelen buffer length was not large enough to hold the string. your buffer said "i can't hold all this" 😭 size up and try again.

---

🌈 AVAILABILITY 🌈

llapi_get_fsname_instance(), llapi_get_fsname(), llapi_get_instance(), and llapi_getname() are all part of the lustre(7) user application interface library. iconic behavior honestly.

version tea ☕:

• llapi_get_fsname_instance and llapi_get_fsname were added in release 2.14.0.
• llapi_get_instance and llapi_getname were added in release 2.2.0.

so if you're on something ancient, that's why your code is screaming at you. not me though. 💜

---

🧚 SEE ALSO 🧚

• lfs-getname(1)
• lustreapi(7)

---

and that's the whole vibe check bestie 🩷 — this page is from the Lustre User API, dated 2024-08-26. go forth and get your fsname. slay. 💅✨