io_uring_register_files(3)

✨ io_uring_register_files — register file descriptors ✨

okay bestie, welcome to the liburing Manual 🫶 this is the page for io_uring_register_files(3) and its little squad of file-table-registering besties, and honestly? it's giving ✨kernel-level efficiency✨. let's get into it.

🌸 NAME 🌸

io_uring_register_files — register file descriptors 💅

🎀 SYNOPSIS 🎀

#include <liburing.h>

int io_uring_register_files(struct io_uring *ring,
                            const int *files,
                            unsigned nr_files);

int io_uring_register_files_tags(struct io_uring *ring,
                                 const int *files,
                                 const __u64 *tags,
                                 unsigned nr);

int io_uring_register_files_sparse(struct io_uring *ring,
                                   unsigned nr_files);

int io_uring_register_files_update(struct io_uring *ring,
                                   unsigned off,
                                   const int *files,
                                   unsigned nr_files);

int io_uring_register_files_update_tag(struct io_uring *ring,
                                       unsigned off,
                                       const int *files,
                                       const __u64 *tags,
                                       unsigned nr_files);

💖 DESCRIPTION 💖

so. the main character: io_uring_register_files(3). she registers nr_files number of file descriptors, defined by the array files, and those belong to the ring for all the operations that come after. registering them = they're officially part of the ring's roster now 🎀

then there's io_uring_register_files_tags(3), which literally behaves the same as io_uring_register_files(3) except it also takes a tags parameter. the resource tagging deets live over in IORING_REGISTER_BUFFERS2, so go peek at that if you need the lore 👑

and io_uring_register_files_sparse(3)? she registers an empty file table of nr_files number of file descriptors. those files have to be updated before you actually use them, like, for example with io_uring_register_files_update_tag(3). no cap, an empty table is an empty table. 🙈

real talk though: if the size of that sparse table exceeds what RLIMIT_NOFILE allows, then io_uring_register_files_sparse(3) will attempt to raise the limit using setrlimit(2) and then retry the operation. and if the registration still fails after all that effort? an error gets returned. periodt. 💀

also the sparse variant is only available in kernels 5.19 and later — so check your kernel before you get attached.

registering a file table is a prerequisite for using any request that uses direct descriptors. like, you cannot skip this step, bestie, it's the vibe check for direct descriptors ✨

okay now the fun part — why even bother? registered files have less overhead per operation than normal files. here's the tea: the kernel grabs a reference count on a file when an operation begins, and drops it when it's done. and when the process file table is shared — for example, if the process has ever created any threads — that cost goes up even more. so using registered files reduces the overhead of file reference management across requests that operate on a file. efficiency slay 🔥

moving on to updates:

io_uring_register_files_update(3) updates existing registered files. off is the offset on which to start the update, and it updates nr_files number of files defined by the array files belonging to the ring. it's giving "we're editing the roster, not rewriting it" 💅

and io_uring_register_files_update_tag(3)? behaves the same as io_uring_register_files_update(3) but additionally takes a tags parameter. again — see IORING_REGISTER_BUFFERS2 for the resource tagging description. iykyk 🦋

⭐ RETURN VALUE ⭐

• on success, io_uring_register_files(3), io_uring_register_files_tags(3) and io_uring_register_files_sparse(3) return 0. clean, iconic, no drama 💖
• io_uring_register_files_update(3) and io_uring_register_files_update_tag(3) return the number of files updated 👑
• on failure, all of them return -errno. 😭

🌈 SEE ALSO 🌈

• io_uring_register(2)
• io_uring_get_sqe(3)
• io_uring_unregister_files(3)

and that's the whole page bestie 🫶 this was liburing-2.1, dated November 15, 2021 — go forth and register those files, you absolute main character 🎀💅✨