LLAPI_LAYOUT_FILE_OPEN(3)

💖 LLAPI_LAYOUT_FILE_CREATE 💖

okay bestie, so this is a page from the Lustre Library Functions manual (section 3, the library calls one 🎀) and it's all about opening files and giving them a look. A layout. A whole aesthetic. Let's get into it fr fr.

---

✨ NAME ✨

llapi_layout_file_open, llapi_layout_file_create, llapi_layout_set_by_fd, llapi_layout_set_by_xattr — open a file and/or slap a layout on a Lustre file, like a queen choosing her outfit 👑

---

🌸 SYNOPSIS 🌸

no because the way you just include one header and get four whole functions 😭

#include <lustre/lustreapi.h>

int llapi_layout_file_open(char *path, int open_flags, int mode,
                           const struct llapi_layout *layout);

int llapi_layout_file_create(char *path, int open_flags,
                             int mode,
                             const struct llapi_layout *layout);

int llapi_layout_set_by_fd(int fd,
                           struct llapi_layout *layout);

int llapi_layout_set_by_xattr(int fd, struct lov_user_md *lum);

---

🦋 DESCRIPTION 🦋

So llapi_layout_file_open() and llapi_layout_file_create() open a file at path — and maybe even create it — using the permissions in mode and the Lustre layout attributes in layout. It's giving main character energy. ✨

The file descriptor they hand back? You can use it in all your subsequent system calls — read(2), write(2), lseek(2), whichever — and close it with close(2). Bestie behavior.

In open_flags you may bitwise-or one access mode plus zero or more file creation flags and file status flags. Go read open(2) if you need the lore. 📖

⚠️ Heads up: if layout is non-NULL and path is not on a Lustre filesystem, this function will fail and set errno to ENOTTY. It's not going to sneak by, she will clock it.

The function llapi_layout_set_by_fd sets the layout on an already-open file or directory specified by fd. No new file, just a glow-up on what's there. 💅

And the way that

llapi_layout_file_create(path, open_flags, mode, layout)

shall be equivalent to:

llapi_layout_file_open(path, open_flags|O_CREAT|O_EXCL, mode, layout)

periodt. 💅

Now real talk (still cute tho) — the layout and mode will not be applied to a file that already exists. So if you need a guarantee that the opened file was created with your specified layout and mode, you should use llapi_layout_file_create(). That's the whole point of it, iykyk.

You can also pass a NULL layout, and that's totally fine — in that case the standard Lustre behavior for assigning layouts to newly-created files will apply. Let Lustre do her thing. 💁

If the pool name attribute of layout has been set, it must refer to an OST pool that exists and contains one or more OSTs. Otherwise these functions fail and set errno to EINVAL. No ghost pools allowed, not today. See llapi_layout_pool_name_set(3).

For llapi_layout_set_by_fd(), fd is a valid file descriptor for a file or directory in a Lustre filesystem, and layout is a valid Lustre layout to set on the file.

For llapi_layout_set_by_xattr(), fd is a valid file descriptor for a file or a directory in a Lustre filesystem, and lum is a valid raw xattr to set on the file. Raw. Unfiltered. Iconic. 🌈

---

🌟 RETURN VALUES 🌟

llapi_layout_file_open() and llapi_layout_file_create() return a shiny new file descriptor ✨ — or -1 if an error occurred, in which case errno is set appropriately. (Not the moment we wanted, but okay.)

---

💀 ERRORS 💀

• ENOTTY — path does not reside on a Lustre filesystem. (She's not from here, bestie.)
• EINVAL — An invalid argument was specified. (Respectfully, what did you pass in.)

---

👑 AVAILABILITY 👑

llapi_layout_file_open() and llapi_layout_file_create() are part of the lustre(7) user application interface library since release 2.7.0. Been here since 2.7.0 and she's still serving. 🫶

---

🎀 SEE ALSO 🎀

close(2), open(2), llapi_layout_alloc(3), llapi_layout_pool_name_set(3), llapi_layout(7), lustreapi(7)

go read those next, you'll eat I promise 💖

---

and that's a wrap, bestie!! 🦋 this lil love letter was written by the Lustre User API crew, dated 2025-04-14, and yeah it's the LLAPI_LAYOUT_FILE_CREATE(3) page — mwah 💋 slay, go make some files with gorgeous layouts ✨🌸