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)