LLAPI_FILE_OPEN(3)

📦 version 2.17.58, in ubuntu stonking

💖 llapi_file_open, llapi_file_create — Lustre Library Functions (section 3) 💖

okay bestie so picture this: you're on a Lustre filesystem and you need to open a file — or make one — and you want to control exactly how it gets striped across OSTs. that's literally what these two functions are for. this comes from the Lustre Library Functions manual, section 3, and it's giving main character energy for your whole storage setup. 🦋

✨ NAME ✨

llapi_file_open, llapi_file_create — open and possibly create a file or a device on a Lustre filesystem

🌸 SYNOPSIS 🌸

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

int llapi_file_open(const char *name, int flags, int mode,
                    unsigned long long stripe_size, int stripe_offset,
                    int stripe_count, int stripe_pattern);

int llapi_file_create(const char *name, unsigned long long stripe_size,
                      int stripe_offset, int stripe_count,
                      int stripe_pattern);

💅 DESCRIPTION 💅

kay so first things first, the cute shortcut: llapi_file_create() is literally equivalent to calling llapi_file_open with flags equal to O_CREAT|O_WRONLY and mode equal to 0644, and then closing the file. that's it. that's the whole trick. slay. ✨

and llapi_file_open()? it opens a file with a given name on a Lustre filesystem. no cap.

the args, one by one, because we love clarity:

  • flags — a combo platter of any of these bad boys: O_RDONLY, O_WRONLY, O_RDWR, O_CREAT, O_EXCL, O_NOCTTY, O_TRUNC, O_APPEND, O_NONBLOCK, O_SYNC, FASYNC, O_DIRECT, O_LARGEFILE, O_DIRECTORY, O_NOFOLLOW, O_NOATIME. for the whole detailed breakdown, go read the open(2) man page, she's iconic for that.
  • mode — the permission bits that get used for a new file when O_CREAT is in play. again, open(2) man page has the full tea on this one. 🫖
  • stripe_size — stripe size in bytes, and it should be a multiple of 64 KiB and must not exceed 4 GiB. no exceptions bestie, math is math.
  • stripe_offset — an OST index telling the file where to start. pass -1 to just use the default setting. easy.
  • stripe_count — how many OSTs to stripe the file across. -1 again means "default setting, pls."
  • stripe_pattern — the striping pattern. in this Lustre version, only LOV_PATTERN_RAID0 is available, and 0 means use the default setting.

🎀 RETURN VALUES 🎀

both llapi_file_open() and llapi_file_create() come back with:

  • >=0 — success!! and for llapi_file_open specifically, that return value is a file descriptor. 👑
  • <0 — failure. and the absolute value of it? that's your error code. take the abs value, girl, it's valid.

😭 ERRORS 😭

  • EINVAL — stripe_size or stripe_offset or stripe_count or stripe_pattern is invalid. something in there is not giving what it's supposed to give.
  • EEXIST — two possible reasons, bestie: striping information has already been set and cannot be altered, or name already exists. either way, already taken. 💀
  • EALREADY — striping information has already been set and cannot be altered.
  • ENOTTY — name may not point to a Lustre filesystem. wrong vibe check, friend.

🌈 EXAMPLES 🌈

here's a whole little program doing the thing, verbatim, copy-paste blessed:

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <errno.h>
#include <stdio.h>
#include <lustre/lustreapi.h>
int main(int argc, char *argv[])
{
        int rc;

        if (argc != 2)
                return -1;

        rc = llapi_file_create(argv[1], 1048576, 0, 2, LOV_PATTERN_RAID0);
        if (rc < 0) {
                fprintf(stderr, "file creation has failed, %s\n", strerror(-rc));
                return -1;
        }
        printf("%s with stripe size 1048576, striped across 2 OSTs,"
               " has been created!\n", argv[1]);
        return 0;
}

🧚 AVAILABILITY 🧚

llapi_file_open() and llapi_file_create() are part of the lustre(7) user application interface library since release 2.4.0. been here, been slaying. 💜

💖 SEE ALSO 💖

okay that's the whole page bestie, you're fully caught up. this was Lustre User API, dated 2024-08-23 — and yes, this is LLAPI_FILE_OPEN(3), periodt. go stripe something gorgeous. 🔥👑🌸

📦 where this page comes from