LLAPI_GET_LUM_FILE_FD(3)

📦 version 2.17.58, in ubuntu stonking

💖 LLAPI_GET_LUM_FILE_FD 💖

okay bestie, so this is a page from the Lustre Library Functions manual — third section, <kbd>3</kbd>, the library-call section, iykyk — and it's all about pulling valid file attributes and LOV stripe information out to you, the user. ✨

🌸 NAME 🌸

llapi_get_lum_file_fd, llapi_get_lum_dir_fd, llapi_get_lum_file, llapi_get_lum_dir — get valid file attributes and LOV stripe information to the user. 🎀

✨ SYNOPSIS ✨

#include <lustre/lustreapi.h>

int llapi_get_lum_file_fd(int dir_fd, const char *fname,
                          __u64 *valid, lstatx_t *statx,
                          struct lov_user_md *lum,
                          size_t lumsize);

int llapi_get_lum_dir_fd(int dir_fd, __u64 *valid,
                         lstatx_t *statx, struct lov_user_md *lum,
                         size_t lumsize);

int llapi_get_lum_file(const char *path, __u64 *valid,
                       lstatx_t *statx, struct lov_user_md *lum,
                       size_t lumsize);

int llapi_get_lum_dir(const char *path, __u64 *valid,
                      lstatx_t *statx, struct lov_user_md *lum,
                      size_t lumsize);

four little functions, all serving looks 🫶

💅 DESCRIPTION 💅

So the way this works is: llapi_get_lum_file_fd(), llapi_get_lum_dir_fd(), llapi_get_lum_file(), and llapi_get_lum_dir() hand you back file attributes and LOV stripe information, and they do it by an ioctl on the dir. that's the whole vibe. 🌈

dir_fd is a file descriptor that refers to a directory. and for llapi_get_lum_file_fd() specifically, if fname is provided, it's a relative pathname that gets interpreted relative to the directory that dir_fd refers to. no cap.

For the "I'm just doing one thing" girlies:

  • llapi_get_lum_dir_fd(), llapi_get_lum_file(), and llapi_get_lum_dir() can be used for applications that are only processing a single file or directory, referred to by dir_fd or path.

And for the "I have a MILLION files" girlies:

  • llapi_get_lum_file_fd() can be used for applications that process lots of files. It avoids opening, locking, and closing each file on the client if that is not needed. Multiple calls of this llapi can be done on the parent dir referenced by dir_fd with a single open for all files in that directory, and it also does not pollute the client dcache with millions of dentries when traversing a large filesystem. that's the icon behaviour honestly 👑

🦋 What actually comes back 🦋

The stripe information for the target file is returned to the user in the struct lov_user_md pointed to by lum — but only if it is not a NULL pointer. 🙈

The file attribute information for the target file is returned in the lstatx_t structure pointed to by statx — again, only if it is not a NULL pointer.

And the output argument valid contains the flags that indicate which fields in the returned file attributes have been validly filled in. it's giving receipts. 🧾✨

⭐ The valid flags ⭐

  • OBD_MD_FLSIZE — The returned file size is known strictly correct.
  • OBD_MD_FLBLOCKS — The returned file blocks is known strictly correct.
  • OBD_MD_FLLAZYSIZE — The returned file size is approximate, may never have been strictly correct.
  • OBD_MD_FLLAZYBLOCKS — The returned file blocks is approximate, may never have been strictly correct.
  • OBD_MD_FLID — The returned object ID is valid.
  • OBD_MD_FLATIME — The returned access time is valid.
  • OBD_MD_FLMTIME — The returned data modification time is valid.
  • OBD_MD_FLCTIME — The returned change time is valid.
  • OBD_MD_FLBLKSZ — The returned block size is valid.
  • OBD_MD_FLMODE — The returned access bits (mode & ~S_IFMT) is valid.
  • OBD_MD_FLTYPE — The returned object type (mode & S_IFMT) is valid.
  • OBD_MD_FLUID — The returned user ID is valid.
  • OBD_MD_FLGID — The returned group ID is valid.
  • OBD_MD_FLFLAGS — The returned flags word is valid.
  • OBD_MD_FLNLINK — The returned link count is valid.
  • OBD_MD_FLRDEV — The returned device number is valid.

sixteen flags, all accounted for, nobody left behind 💜

🔥 RETURN VALUES 🔥

llapi_get_lum_file_fd(), llapi_get_lum_dir_fd(), llapi_get_lum_file(), and llapi_get_lum_dir() return 0 on success, or a negative errno value on failure. so if it's zero you're slaying, and if it's negative... bestie, check errno. 😭

💀 ERRORS 💀

  • -ENOMEM — Insufficient memory to complete operation.
  • -EFAULT — Memory region is not properly mapped.
  • -EINVAL — One or more invalid arguments are given.
  • -EOPNOTSUPP — The operation is not supported.
  • -ENOTTY — File does not reside on a Lustre filesystem.
  • -ENOENT — path does not exist.
  • -EBADF — dir_fd is not a valid open file descriptor.
fr fr, -ENOTTY is the sneaky one — it doesn't mean "wrong ioctl", it means the file isn't on a Lustre filesystem at all. read the room. 🫠

🎀 AVAILABILITY 🎀

llapi_get_lum_file_fd(), llapi_get_lum_file(), llapi_get_lum_dir_fd() and llapi_get_lum_dir() are part of the lustre(7) user application interface library since release 2.13.0. so if your Lustre is older than that... not me being the bearer of bad news 🙈

🌟 SEE ALSO 🌟

that's the whole page, bestie, no notes 💖

this was Lustre User API, dated 2024-08-27, and it lives in section 3 of the manual as LLAPI_GET_LUM_FILE_FD(3) — mwah, go read your file attributes, you're doing amazing 🌸💅✨

📦 where this page comes from