[GIT PULL] update io_uring_prep_close.3

[cmazakas]

Setting the IOSQE_FIXED_FILE flag in the direct close() SQE causes erroneous behavior users may not be aware of.

Update the docs on io_uring_prep_close() to specify if the IOSQE_FIXED_FILE flag should be set or not and what it's ramifications are.

git request-pull output:

The following changes since commit 660cefae669c985aeaeaf50e45b635777ac40edc:

  test/wq-aff: add test case for SQPOLL io-wq affinity (2023-08-14 08:21:02 -0600)

are available in the Git repository at:

  https://github.com/cmazakas/liburing.git io_uring_prep_close_man_page_updates

for you to fetch changes up to be521645cad1dcc22b3909cad1662c139afd5e55:

  update io_uring_prep_close.3 (2023-08-20 12:50:44 -0700)

----------------------------------------------------------------
Christian Mazakas (1):
      update io_uring_prep_close.3

 man/io_uring_prep_close.3 | 10 ++++++++++
 1 file changed, 10 insertions(+)

---

Click to show/hide pull request guidelines

Pull Request Guidelines

1. To make everyone easily filter pull request from the email
   notification, use [GIT PULL] as a prefix in your PR title.

[GIT PULL] Your Pull Request Title

2. Follow the commit message format rules below.
3. Follow the Linux kernel coding style (see: https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst).

Commit message format rules:

1. The first line is title (don't be more than 72 chars if possible).
2. Then an empty line.
3. Then a description (may be omitted for truly trivial changes).
4. Then an empty line again (if it has a description).
5. Then a Signed-off-by tag with your real name and email. For example:

Signed-off-by: Foo Bar <[email protected]>

The description should be word-wrapped at 72 chars. Some things should
not be word-wrapped. They may be some kind of quoted text - long
compiler error messages, oops reports, Link, etc. (things that have a
certain specific format).

Note that all of this goes in the commit message, not in the pull
request text. The pull request text should introduce what this pull
request does, and each commit message should explain the rationale for
why that particular change was made. The git tree is canonical source
of truth, not github.

Each patch should do one thing, and one thing only. If you find yourself
writing an explanation for why a patch is fixing multiple issues, that's
a good indication that the change should be split into separate patches.

If the commit is a fix for an issue, add a Fixes tag with the issue
URL.

Don't use GitHub anonymous email like this as the commit author:

[email protected]

Use a real email address!

Commit message example:

src/queue: don't flush SQ ring for new wait interface

If we have IORING_FEAT_EXT_ARG, then timeouts are done through the
syscall instead of by posting an internal timeout. This was done
to be both more efficient, but also to enable multi-threaded use
the wait side. If we touch the SQ state by flushing it, that isn't
safe without synchronization.

Fixes: https://github.com/axboe/liburing/issues/402
Signed-off-by: Jens Axboe <[email protected]>

---

By submitting this pull request, I acknowledge that:

1. I have followed the above pull request guidelines.
2. I have the rights to submit this work under the same license.
3. I agree to a Developer Certificate of Origin (see https://developercertificate.org for more information).

[axboe]

I think this would be a lot more useful if it explains how the sqe is setup for a direct close, rather than just detail one way it definitely doesn't work. Under the covers, they basically all use __io_uring_set_target_fixed_file() which sets sqe->file_index. This is different than a file that just takes a direct descriptor without manipulating it, where you would indeed use IOSQE_FIXED_FILE to tell the kernel that the sqe->fd is a direct descriptor index rather than a normal file descriptor.

[cmazakas]

You know what's interesting, I actually have no idea when, where or why we're supposed to set IOSQE_FIXED_FILE.

I tried looking into the liburing src and more of the docs and I feel like I have more questions than answers now.

Where do I read more about this?

[axboe]

See the io_uring_enter.2 man page, it has a description of the sqe flags. But it's pretty simple - if your request takes a file descriptor, then you can set this flag and then io_uring will interpret it as "fd isn't a normal file descriptor, it's a direct descriptor".

[cmazakas]

Alright, so maybe something like...

To properly close a direct descriptor, perform something like the following:

struct io_uring_sqe *sqe = io_uring_get_sqe(ring);
io_uring_prep_close_direct(sqe, fd);
io_uring_sqe_set_flags(sqe, IOSQE_CQE_SKIP_SUCCESS);
io_uring_sqe_data(sqe, NULL);
io_uring_submit(ring);