HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. |  |
NAME |SYNOPSIS |DESCRIPTION |RETURN VALUE |ERRORS |NOTES |SEE ALSO |COLOPHON | |
io_uring_prep_accept(3) liburing Manualio_uring_prep_accept(3)io_uring_prep_accept - prepare an accept request
#include <sys/socket.h>#include <liburing.h>void io_uring_prep_accept(struct io_uring_sqe *sqe,intsockfd,struct sockaddr *addr,socklen_t *addrlen,intflags);void io_uring_prep_accept_direct(struct io_uring_sqe *sqe,intsockfd,struct sockaddr *addr,socklen_t *addrlen,intflags,unsigned intfile_index);void io_uring_prep_multishot_accept(struct io_uring_sqe *sqe,intsockfd,struct sockaddr *addr,socklen_t *addrlen,intflags);void io_uring_prep_multishot_accept_direct(struct io_uring_sqe *sqe,intsockfd,struct sockaddr *addr,socklen_t *addrlen,intflags);
Theio_uring_prep_accept(3) function and its three variants prepare an accept request similar toaccept4(2). The submission queue entrysqe is setup to use the file descriptorsockfd to start accepting a connection request described by the socket address ataddr and of structure lengthaddrlen and using modifier flags inflags. 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 settingIOSQE_FIXED_FILEin the SQEflags member, and setting the SQEfd 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 usingio_uring_register_files(3) orio_uring_register_files_sparse(3). Once registered,io_uring_prep_accept_direct(3) allows an entry in that table to be specifically selected through thefile_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 withio_uring_register_files_update(3).file_index can also be set toIORING_FILE_INDEX_ALLOCfor this variant and an unused table index will be dynamically chosen and returned. Likewise,io_uring_prep_multishot_accept_directwill 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, seeio_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 SQEfile_index field meaning applications cannot rely on a-EINVALCQEres 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,-ENFILEis returned as the CQEres. 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 CQEflags and see ifIORING_CQE_F_MOREis set on completion as an indication of whether or not the accept request will generate further CQEs. Note that for the multishot variants, settingaddrandaddrlenmay not make a lot of sense, as the same value would be used for every accepted connection. This means that the data written toaddrmay 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 pageaccept4(2) for details of the accept function itself.
None
The CQEres field will contain the result of the operation.io_uring_prep_accept(3) generates the installed file descriptor as its result.io_uring_prep_accept_direct(3) andfile_index set to a specific direct descriptor generates0on success. The caller must remember which direct descriptor was picked for this request.io_uring_prep_accept_direct(3) andfile_index set toIORING_FILE_INDEX_ALLOCgenerates the dynamically chosen direct descriptor.io_uring_prep_multishot_accept(3) generates the installed file descriptor in each result.io_uring_prep_multishot_accept_direct(3), generates the dynamically chosen direct descriptor in each result. Note that where synchronous system calls will return-1on failure and seterrno to the actual error value, io_uring never useserrno. Instead it generates the negatederrno directly in the CQEres field.
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 theIORING_FEAT_SUBMIT_STABLEflag passed back fromio_uring_queue_init_params(3). Note that the direct versions of accept do not acceptSOCK_CLOEXEC,and setting that flag will result in an-EINVALerror in the CQE.
io_uring_get_sqe(3),io_uring_submit(3),io_uring_register_files(3),io_uring_register_files_sparse(3),io_uring_register_file_alloc_range(3),io_uring_register(2),accept4(2)
This page is part of theliburing (A library for io_uring) project. Information about the project can be found at ⟨https://github.com/axboe/liburing⟩. If you have a bug report for this manual page, send it to io-uring@vger.kernel.org. This page was obtained from the project's upstream Git repository ⟨https://github.com/axboe/liburing⟩ on 2025-08-11. (At that time, the date of the most recent commit that was found in the repository was 2025-08-02.) If you discover any rendering problems in this HTML version of the page, or you believe there is a better or more up-to-date source for the page, or you have corrections or improvements to the information in this COLOPHON (which isnot part of the original manual page), send a mail to man-pages@man7.orgliburing-2.2 March 13, 2022io_uring_prep_accept(3)Pages that refer to this page:io_uring_prep_accept(3), io_uring_prep_accept_direct(3), io_uring_prep_multishot_accept(3), io_uring_prep_multishot_accept_direct(3)
HTML rendering created 2025-09-06 byMichael Kerrisk, author ofThe Linux Programming Interface. For details of in-depthLinux/UNIX system programming training courses that I teach, lookhere. Hosting byjambit GmbH. | |