LLAPI_FILE_GET_STRIPE(3)

💖 LLAPI_FILE_GET_STRIPE 💖

okay so bestie, welcome to llapi_file_get_stripe — that's section 3 of the manual, Lustre Library Functions, and she's here to spill all the tea about how your file is striped across a Lustre filesystem. no cap. 🦋

---

✨ NAME ✨

llapi_file_get_stripe — get striping information for a file or a directory on a Lustre filesystem

---

✨ SYNOPSIS ✨

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

int llapi_file_get_stripe(const char *path, void *lum);

---

✨ DESCRIPTION ✨

llapi_file_get_stripe() literally hands you the striping info for a file or a directory at path, and drops it into lum (which lowkey needs to point at a big enough chunk of memory, so don't be stingy 💅). it comes back in one of these two formats:

struct lov_user_md_v1 {
        __u32 lmm_magic;
        __u32 lmm_pattern;
        __u64 lmm_object_id;
        __u64 lmm_object_seq;
        __u32 lmm_stripe_size;
        __u16 lmm_stripe_count;
        __u16 lmm_stripe_offset;
        struct lov_user_ost_data_v1 lmm_objects[];
} __attribute__((packed));

struct lov_user_md_v3 {
        __u32 lmm_magic;
        __u32 lmm_pattern;
        __u64 lmm_object_id;
        __u64 lmm_object_seq;
        __u32 lmm_stripe_size;
        __u16 lmm_stripe_count;
        __u16 lmm_stripe_offset;
        char  lmm_pool_name[LOV_MAXPOOLNAME + 1];
        struct lov_user_ost_data_v1 lmm_objects[];
} __attribute__((packed));

and here's the field-by-field gossip, bestie 🫶

• lmm_magic — tells you which format the returned striping info is in. LOV_MAGIC_V1 means you got lov_user_md_v1. LOV_MAGIC_V3 means you got lov_user_md_v3.
• lmm_pattern — holds the striping pattern. heads up: only LOV_PATTERN_RAID0 is possible in this Lustre version. that's it, that's the whole menu 🎀
• lmm_object_id — holds the MDS object id.
• lmm_object_gr — holds the MDS object group.
• lmm_stripe_size — holds the stripe size in bytes.
• lmm_stripe_count — holds the number of OSTs the file is striped across.
• lmm_stripe_offset — holds the OST index from which the file starts.
• lmm_pool_name — holds the OST pool name to which the file belongs.
• lmm_objects — an array of lmm_stripe_count members, holding per-OST file information in this format:

struct lov_user_ost_data_v1 {
        __u64 l_object_id;
        __u64 l_object_seq;
        __u32 l_ost_gen;
        __u32 l_ost_idx;
} __attribute__((packed));

and inside that little guy:

• l_object_id — holds the OST object id.
• l_object_seq — holds the OST object group.
• l_ost_gen — holds the generation of the OST index.
• l_ost_idx — holds the OST index in LOV.

---

✨ RETURN VALUES ✨

llapi_file_get_stripe() returns:

• 0 — on success 🎉
• != 0 — on failure, and errno is set appropriately. not the vibe, but okay. 😭

---

✨ ERRORS ✨

• ENOMEM — failed to allocate memory.
• ENAMETOOLONG — path was too long.
• ENOENT — path does not point to a file or a directory.
• ENOTTY — path does not point to a Lustre filesystem.
• EFAULT — memory region pointed by lum is not properly mapped.

---

✨ EXAMPLES ✨

here's a whole little program that ate, fr fr 👑

#include <sys/vfs.h>
#include <lustre/lustreapi.h>

static inline int maxint(int a, int b)
{
        return a > b ? a : b;
}

static void *alloc_lum()
{
        int v1, v3, join;

        v1 = sizeof(struct lov_user_md_v1) +
             LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);
        v3 = sizeof(struct lov_user_md_v3) +
             LOV_MAX_STRIPE_COUNT * sizeof(struct lov_user_ost_data_v1);

        return malloc(maxint(v1, v3));
}

int main(int argc, char** argv)
{
        struct lov_user_md *lum_file = NULL;
        int rc;
        int lum_size;

        if (argc != 2) {
                fprintf(stderr, "Usage: %s <filename>\n", argv[0]);
                return 1;
        }

        lum_file = alloc_lum();
        if (lum_file == NULL) {
                rc = ENOMEM;
                goto cleanup;
        }

        rc = llapi_file_get_stripe(argv[1], lum_file);
        if (rc) {
                rc = errno;
                goto cleanup;
        }

        /* stripe_size stripe_count */
        printf("%d %d\n",
               lum_file->lmm_stripe_size,
               lum_file->lmm_stripe_count);

cleanup:
        if (lum_file != NULL)
                free(lum_file);

        return rc;
}

---

✨ AVAILABILITY ✨

llapi_file_get_stripe() is part of the lustre(7) user application interface library since release 2.4.0. she's been iconic for a minute. 💅

---

✨ SEE ALSO ✨

lustre(7), lustreapi(7)

---

and that's the whole page, bestie! 🌸 this was Lustre User API, dated 2024-08-23 — go forth and stripe responsibly, ily 🫶✨