io_uring_prep_close(3)

💖 io_uring_prep_close — from the liburing manual, bestie edition 🎀

okay so. you wanna close a file descriptor but you wanna do it the io_uring way, all async and chic, and you opened the man page and it's giving... man page. don't worry, i got you. this whole page is about io_uring_prep_close(3) and its direct-descriptor sibling, and honestly? it's short. slay. let's go. ✨

---

🌸 NAME 🌸

io_uring_prep_close — prepare a file descriptor close request

like, it preps the request. it does not do the closing itself. we'll get there, bestie, patience 💅

---

🦋 SYNOPSIS 🦋

#include <liburing.h>

void io_uring_prep_close(struct io_uring_sqe *sqe,
                          int fd);

void io_uring_prep_close_direct(struct io_uring_sqe *sqe,
                                unsigned file_index);

two functions. two vibes. one of them takes a regular fd, the other one takes a file_index because it's fancy. 😌

---

✨ DESCRIPTION ✨

So io_uring_prep_close(3) prepares a close request. The submission queue entry sqe gets set up so that it will close the file descriptor indicated by fd. That's it. That's the whole thing. Queen of being straightforward. 👑

Now for the direct descriptor version — the one that closes a direct descriptor — the offset is specified by the file_index argument instead of the fd. This is identical to unregistering the direct descriptor, and it's just provided as a convenience. They really said "we'll do it for you, mwah". 🫶

⚠️ okay but listen. Even though it's closing a direct descriptor, the application must not set IOSQE_FIXED_FILE on the SQE. Otherwise the request will complete with -EBADF as the result. Like, it will literally fail on you and you will be sad. do not do it. no cap. 💀

Both of these functions prepare an async close(2) request. So go read that man page for the details, because this page is not about to re-explain close(2) to you. iykyk.

---

💜 RETURN VALUE 💜

None.

(genuinely nothing. it's void. the results come back somewhere else, keep reading.) 🙈

---

🎀 ERRORS 🎀

The CQE res field will contain the result of the operation. See the related man page for the details on possible values. ✨

For closing of a direct descriptor, the only failure cases are:

• the kernel running completely out of memory 😭
• the application having specified an invalid direct descriptor 💀

🚨 important vibe check: 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 like, look at res, not errno. periodt. 🌈

---

🔥 SEE ALSO 🔥

• io_uring_get_sqe(3)
• io_uring_submit(3)
• close(2)

---

and that's the whole page, bestie, you ate it 💅 go forth and close your file descriptors responsibly. this was liburing-2.2, dated March 13, 2022 — mwah, bye, love you, don't forget the IOSQE_FIXED_FILE thing 🦋💖🌸