Provided by: liburing-dev_2.5-1build1_amd64 bug

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  and  its  three variants prepare an accept request
       similar to accept4(2).  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.

       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 IOSQE_FIXED_FILE in the SQE
       flags member, and setting the SQE 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 io_uring_register_files(3)  or  io_uring_register_files_sparse(3).
       Once  registered,  io_uring_prep_accept_direct(3)  allows  an  entry  in  that table to be
       specifically selected through the 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   io_uring_register_files_update(3).
       file_index can also be set to IORING_FILE_INDEX_ALLOC for this variant and an unused table
       index     will     be      dynamically      chosen      and      returned.       Likewise,
       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 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 file_index field meaning applications cannot
       rely on a -EINVAL CQE 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, -ENFILE is returned as the CQE 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 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. Note that for the multishot variants, setting addr and 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 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 accept4(2) for details of the accept function itself.

RETURN VALUE

       None

ERRORS

       The CQE res 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)   and  file_index  set  to  a  specific  direct  descriptor
       generates 0 on success.  The caller must remember which direct descriptor was  picked  for
       this request.

       io_uring_prep_accept_direct(3) and file_index set to IORING_FILE_INDEX_ALLOC generates 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 -1 on failure and set errno to the
       actual error value, io_uring never uses errno.  Instead it  generates  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_files(3),
       io_uring_register_files_sparse(3),                  io_uring_register_file_alloc_range(3),
       io_uring_register(2), accept4(2)