man/io_uring_prep_accept.3 - master - githubmirror/liburing

man/io_uring_prep_accept.3
203 строки7 KB
Jens Axboe
man/io_uring_prep_accept.3: SOCK_CLOEXEC isn't supported with direct files
17 янв 2025, 18:43
17 янв 2025, 18:4319134a8
.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
.\"
.\" SPDX-License-Identifier: LGPL-2.0-or-later
.\"
.TH io_uring_prep_accept 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
.SH NAME
io_uring_prep_accept \- prepare an accept request
.SH SYNOPSIS
.nf
.B #include <sys/socket.h>
.B #include <liburing.h>
.PP
.BI "void io_uring_prep_accept(struct io_uring_sqe *" sqe ","
.BI "                          int " sockfd ","
.BI "                          struct sockaddr *" addr ","
.BI "                          socklen_t *" addrlen ","
.BI "                          int " flags ");"
.PP
.BI "void io_uring_prep_accept_direct(struct io_uring_sqe *" sqe ","
.BI "                                 int " sockfd ","
.BI "                                 struct sockaddr *" addr ","
.BI "                                 socklen_t *" addrlen ","
.BI "                                 int " flags ","
.BI "                                 unsigned int " file_index ");"
.PP
.BI "void io_uring_prep_multishot_accept(struct io_uring_sqe *" sqe ","
.BI "                                    int " sockfd ","
.BI "                                    struct sockaddr *" addr ","
.BI "                                    socklen_t *" addrlen ","
.BI "                                    int " flags ");"
.PP
.BI "void io_uring_prep_multishot_accept_direct(struct io_uring_sqe *" sqe ","
.BI "                                           int " sockfd ","
.BI "                                           struct sockaddr *" addr ","
.BI "                                           socklen_t *" addrlen ","
.BI "                                           int " flags ");"
.fi
.SH DESCRIPTION
.PP
The
.BR io_uring_prep_accept (3)
function and its three variants prepare an accept request similar to
.BR accept4 (2).
The submission queue entry
.I sqe
is setup to use the file descriptor
.I sockfd
to start accepting a connection request described by the socket address at
.I addr
and of structure length
.I addrlen
and using modifier flags in
.IR flags .

The three variants allow combining the direct file table and multishot features.

Direct descriptors are io_uring private file descriptors. They
avoid some of the overhead associated with thread shared file tables and
can be used in any io_uring request that takes a file descriptor.
The two direct variants here create such direct descriptors.
Subsequent to their creation, they can be used by setting
.B IOSQE_FIXED_FILE
in the SQE
.I flags
member, and setting the SQE
.I fd
field to the direct descriptor value rather than the regular file
descriptor. Direct descriptors are managed like registered files.

To use an accept direct variant, the application must first have registered
a file table of a desired size using
.BR io_uring_register_files (3)
or
.BR io_uring_register_files_sparse (3).
Once registered,
.BR io_uring_prep_accept_direct (3)
allows an entry in that table to be specifically selected through the
.I file_index
argument.
If the specified entry already contains a file, the file will first be removed
from the table and closed, consistent with the behavior of updating an
existing file with
.BR io_uring_register_files_update (3).
.I file_index
can also be set to
.B IORING_FILE_INDEX_ALLOC
for this variant and
an unused table index will be dynamically chosen and returned.
Likewise,
.B io_uring_prep_multishot_accept_direct
will have an unused table index dynamically chosen and returned for each connection accepted.
If both forms of direct selection will be employed, specific and dynamic, see
.BR io_uring_register_file_alloc_range (3)
for setting up the table so dynamically chosen entries are made against
a different range than that targeted by specific requests.

Note that old kernels don't check the SQE
.I file_index
field meaning
applications cannot rely on a
.B -EINVAL
CQE
.I res
being returned when the kernel is too old because older kernels
may not recognize they are being asked to use a direct table slot.

When a direct descriptor accept request asks for a table slot to be
dynamically chosen but there are no free entries,
.B -ENFILE
is returned as the CQE
.IR res .

The multishot variants allow an application to issue
a single accept request, which will repeatedly trigger a CQE when a connection
request comes in. Like other multishot type requests, the application should
look at the CQE
.I flags
and see if
.B IORING_CQE_F_MORE
is set on completion as an indication of whether or not the accept request
will generate further CQEs. Note that for the multishot variants, setting
.B addr
and
.B addrlen
may not make a lot of sense, as the same value would be used for every
accepted connection. This means that the data written to
.B addr
may be overwritten by a new connection before the application has had time
to process a past connection. If the application knows that a new connection
cannot come in before a previous one has been processed, it may be used as
expected. The multishot variants are available since 5.19.

See the man page
.BR accept4 (2)
for details of the accept function itself.

.SH RETURN VALUE
None
.SH ERRORS
The CQE
.I res
field will contain the result of the operation.

.BR io_uring_prep_accept (3)
generates the installed file descriptor as its result.

.BR io_uring_prep_accept_direct (3)
and
.I file_index
set to a specific direct descriptor
generates
.B 0
on success.
The caller must remember which direct descriptor was picked for this request.

.BR io_uring_prep_accept_direct (3)
and
.I file_index
set to
.B IORING_FILE_INDEX_ALLOC
generates the dynamically chosen direct descriptor.

.BR io_uring_prep_multishot_accept (3)
generates the installed file descriptor in each result.

.BR io_uring_prep_multishot_accept_direct (3),
generates the dynamically chosen direct descriptor in each result.

Note that where synchronous system calls will return
.B -1
on failure and set
.I errno
to the actual error value, io_uring never uses
.IR errno .
Instead it generates the negated
.I errno
directly in the CQE
.I res
field.
.SH NOTES
As with any request that passes in data in a struct, that data must remain
valid until the request has been successfully submitted. It need not remain
valid until completion. Once a request has been submitted, the in-kernel
state is stable. Very early kernels (5.4 and earlier) required state to be
stable until the completion occurred. Applications can test for this
behavior by inspecting the
.B IORING_FEAT_SUBMIT_STABLE
flag passed back from
.BR io_uring_queue_init_params (3).
.P
Note that the direct versions of accept do not accept
.B SOCK_CLOEXEC ,
and setting that flag will result in an
.B -EINVAL
error in the CQE.
.SH SEE ALSO
.BR io_uring_get_sqe (3),
.BR io_uring_submit (3),
.BR io_uring_register_files (3),
.BR io_uring_register_files_sparse (3),
.BR io_uring_register_file_alloc_range (3),
.BR io_uring_register (2),
.BR accept4 (2)