Provided by: liburing-dev_2.2-2_amd64 
NAME
io_uring_prep_accept - prepare an accept request
SYNOPSIS
#include <sys/socket.h>
#include <liburing.h>
void io_uring_prep_accept(struct io_uring_sqe *sqe,
int sockfd,
struct sockaddr *addr,
socklen_t *addrlen,
int flags);
void io_uring_prep_accept_direct(struct io_uring_sqe *sqe,
int sockfd,
struct sockaddr *addr,
socklen_t *addrlen,
int flags,
unsigned int file_index);
void io_uring_prep_multishot_accept(struct io_uring_sqe *sqe,
int sockfd,
struct sockaddr *addr,
socklen_t *addrlen,
int flags);
void io_uring_prep_multishot_accept_direct(struct io_uring_sqe *sqe,
int sockfd,
struct sockaddr *addr,
socklen_t *addrlen,
int flags);
DESCRIPTION
The io_uring_prep_accept(3) function prepares an accept request. The submission queue
entry sqe is setup to use the file descriptor sockfd to start accepting a connection
request described by the socket address at addr and of structure length addrlen and using
modifier flags in flags.
For a direct descriptor accept request, the offset is specified by the file_index
argument. 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. To do so, IOSQE_FIXED_FILE must be set in the SQE flags
member, and the SQE fd field should use the direct descriptor value rather than the
regular file descriptor. Direct descriptors are managed like registered files.
If the direct variant is used, the application must first have registered a file table
using io_uring_register_files(3) of the appropriate size. Once registered, a direct accept
request may use any entry in that table, as long as it is within the size of the
registered table. If a specified entry already contains a file, the file will first be
removed from the table and closed. It's consistent with the behavior of updating an
existing file with io_uring_register_files_update(3). Note that old kernels don't check
the SQE file_index field, which is not a problem for liburing helpers, but users of the
raw io_uring interface need to zero SQEs to avoid unexpected behavior. This also means
that applications should check for availability of IORING_OP_ACCEPT_DIRECT before using
it, they cannot rely on a -EINVAL CQE res return.
For a direct descriptor accept request, the file_index argument can be set to
IORING_FILE_INDEX_ALLOC, In this case a free entry in io_uring file table will be used
automatically and the file index will be returned as CQE res. -ENFILE is otherwise
returned if there is no free entries in the io_uring file table.
The multishot version accept and accept_direct 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 flags and see
if IORING_CQE_F_MORE is set on completion as an indication of whether or not the accept
request will generate further CQEs. The multishot variants are available since 5.19.
For multishot with direct descriptors, IORING_FILE_INDEX_ALLOC must be used as the file
descriptor. This tells io_uring to allocate a free direct descriptor from our table,
rather than the application passing one in. Failure to do so will result in the accept
request being terminated with -EINVAL. The allocated descriptor will be returned in the
CQE res field, like a non-direct accept request.
These functions prepare an async accept4(2) request. See that man page for details.
RETURN VALUE
None
ERRORS
The CQE res field will contain the result of the operation. For singleshot accept, the
non-direct accept returns the installed file descriptor as its value, the direct accept
returns 0 on success. The caller must know which direct descriptor was picked for this
request. For multishot accept, the non-direct accept returns the installed file descriptor
as its value, the direct accept returns the file index used on success. See the related
man page for details on possible values for the non-direct accept. Note that 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.
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 IORING_FEAT_SUBMIT_STABLE flag passed back from
io_uring_queue_init_params(3).
SEE ALSO
io_uring_get_sqe(3), io_uring_submit(3), io_uring_register(2), accept4(2)