io_uring_prep_socket(3)

💖 io_uring_prep_socket — the liburing manual, but make it cute 💖

okay bestie, so you know how liburing is that girl 💅 and you wanna make sockets without doing the whole boring sync thing? yeah. this is the page. it's io_uring_prep_socket(3), straight outta the liburing manual, and we're gonna go through it together, no skips, no cap. 🦋

---

✨ NAME ✨

io_uring_prep_socket — prepare a socket creation request

like, you're not making the socket right this second, you're getting the request all dressed up and ready to submit. main character energy. 👑

---

🌸 SYNOPSIS 🌸

#include <sys/socket.h>
#include <liburing.h>

void io_uring_prep_socket(struct io_uring_sqe *sqe,
                          int domain,
                          int type,
                          int protocol,
                          unsigned int flags);

void io_uring_prep_socket_direct(struct io_uring_sqe *sqe,
                                 int domain,
                                 int type,
                                 int protocol,
                                 unsigned int file_index,
                                 unsigned int flags);

void io_uring_prep_socket_direct_alloc(struct io_uring_sqe *sqe,
                                 int domain,
                                 int type,
                                 int protocol,
                                 unsigned int flags);

three whole sisters, one vibe. pick your fighter. 🎀

---

💜 DESCRIPTION 💜

so io_uring_prep_socket(3) prepares a socket creation request. it sets up the submission queue entry sqe to use the communication domain you give it in domain, the communication type in type, and the protocol in protocol. and the flags argument? currently unused. literally just sitting there. it's giving placeholder. 🙈

io_uring_prep_socket_direct(3) works exactly like io_uring_prep_socket(3), except it maps the socket to a direct descriptor instead of handing you back a normal file descriptor. the file_index argument is the slot you want this socket to live in. so you're picking your own seat at the table, basically. 🪑

io_uring_prep_socket_direct_alloc(3) works just like io_uring_prep_socket_direct(3), except instead of you passing in a free slot, it allocates a brand new direct descriptor for you. it's equivalent to calling io_uring_prep_socket_direct(3) with IORING_FILE_INDEX_ALLOC as the file_index. and when it's done? the res field of the CQE will hand you back the direct slot that got allocated. it's giving surprise gift. 🎁

ok important part, bestie, don't scroll past this: if you're using the direct variants, your application must first have registered a file table using io_uring_register_files(3), and it needs to be the appropriate size. once that's registered, a direct socket request can use any entry in that table, as long as it's within the size of the registered table. and if a specified entry already contains a file? the file gets removed from the table first and then closed. that's consistent with the behavior of updating an existing file with io_uring_register_files_update(3). so yeah, it replaces, it doesn't hoard. 💀

for a direct descriptor socket request, the file_index argument can be set to IORING_FILE_INDEX_ALLOC. in that case a free entry in the io_uring file table will be used automatically, and the file index gets returned as the CQE res. otherwise, -ENFILE is returned if there are no free entries in the io_uring file table. 😭 no free seats, no socket, sorry babe.

these functions prepare an async socket(2) request. go read that man page for the deets. 📖

---

⭐ RETURN VALUE ⭐

None

that's it. that's the whole section. she said nothing and left. 💅

---

🔥 ERRORS 🔥

the CQE res field will contain the result of the operation — check the related man page for details on possible values.

and here's the thing you gotta internalize: where synchronous system calls will return -1 on failure and set errno to the actual error value, io_uring never uses errno. instead it returns the negated errno directly in the CQE res field. so don't go checking errno, she doesn't live here anymore. 🚫

---

🫶 SEE ALSO 🫶

• io_uring_get_sqe(3)
• io_uring_submit(3)
• socket(2)

---

and that's the whole page, bestie!! go make some sockets, register that file table first though, i'm not playing with you 😤✨

this was brought to you by liburing-2.2, dated May 27, 2022 — mwah, love u, bye 💖🎀🦋