1io_uring_prep_accept(3)         liburing Manual        io_uring_prep_accept(3)
2
3
4

NAME

6       io_uring_prep_accept - prepare an accept request
7

SYNOPSIS

9       #include <sys/socket.h>
10       #include <liburing.h>
11
12       void io_uring_prep_accept(struct io_uring_sqe *sqe,
13                                 int sockfd,
14                                 struct sockaddr *addr,
15                                 socklen_t *addrlen,
16                                 int flags);
17
18       void io_uring_prep_accept_direct(struct io_uring_sqe *sqe,
19                                        int sockfd,
20                                        struct sockaddr *addr,
21                                        socklen_t *addrlen,
22                                        int flags,
23                                        unsigned int file_index);
24
25       void io_uring_prep_multishot_accept(struct io_uring_sqe *sqe,
26                                           int sockfd,
27                                           struct sockaddr *addr,
28                                           socklen_t *addrlen,
29                                           int flags);
30
31       void io_uring_prep_multishot_accept_direct(struct io_uring_sqe *sqe,
32                                                  int sockfd,
33                                                  struct sockaddr *addr,
34                                                  socklen_t *addrlen,
35                                                  int flags);
36

DESCRIPTION

38       The  io_uring_prep_accept(3) function and its three variants prepare an
39       accept request similar to accept4(2).  The submission queue  entry  sqe
40       is setup to use the file descriptor sockfd to start accepting a connec‐
41       tion request described by the socket address at addr and  of  structure
42       length addrlen and using modifier flags in flags.
43
44       The  three variants allow combining the direct file table and multishot
45       features.
46
47       Direct descriptors are io_uring private file  descriptors.  They  avoid
48       some  of the overhead associated with thread shared file tables and can
49       be used in any io_uring request that takes a file descriptor.  The  two
50       direct  variants  here  create  such direct descriptors.  Subsequent to
51       their creation, they can be used by setting IOSQE_FIXED_FILE in the SQE
52       flags  member,  and  setting  the SQE fd field to the direct descriptor
53       value rather than the regular file descriptor. Direct  descriptors  are
54       managed like registered files.
55
56       To use an accept direct variant, the application must first have regis‐
57       tered a file table of a desired size  using  io_uring_register_files(3)
58       or    io_uring_register_files_sparse(3).    Once   registered,   io_ur‐
59       ing_prep_accept_direct(3) allows an entry in that table to be  specifi‐
60       cally selected through the file_index argument.  If the specified entry
61       already contains a file, the file will first be removed from the  table
62       and  closed,  consistent with the behavior of updating an existing file
63       with io_uring_register_files_update(3).  file_index can also be set  to
64       IORING_FILE_INDEX_ALLOC for this variant and an unused table index will
65       be dynamically chosen  and  returned.   Likewise,  io_uring_prep_multi‐
66       shot_accept_direct  will  have an unused table index dynamically chosen
67       and returned for each connection accepted.  If both forms of direct se‐
68       lection  will  be  employed,  specific and dynamic, see io_uring_regis‐
69       ter_file_alloc_range(3) for setting up the table so dynamically  chosen
70       entries  are made against a different range than that targetted by spe‐
71       cific requests.
72
73       Note that old kernels don't check the SQE file_index field meaning  ap‐
74       plications  cannot  rely  on  a -EINVAL CQE res being returned when the
75       kernel is too old because older kernels may not recognize they are  be‐
76       ing asked to use a direct table slot.
77
78       When a direct descriptor accept request asks for a table slot to be dy‐
79       namically chosen but there are no free entries, -ENFILE is returned  as
80       the CQE res.
81
82       The  multishot  variants  allow an application to issue a single accept
83       request, which will repeatedly trigger a CQE when a connection  request
84       comes  in.  Like  other multishot type requests, the application should
85       look at the CQE flags and see if IORING_CQE_F_MORE is set on completion
86       as  an  indication  of  whether or not the accept request will generate
87       further CQEs. Note that for the multishot variants,  setting  addr  and
88       addrlen  may  not  make a lot of sense, as the same value would be used
89       for every accepted connection. This means that the data written to addr
90       may  be  overwritten by a new connection before the application has had
91       time to process a past connection. If the application knows that a  new
92       connection  cannot come in before a previous one has been processed, it
93       may be used as expected. The multishot  variants  are  available  since
94       5.19.
95
96       See the man page accept4(2) for details of the accept function itself.
97
98

RETURN VALUE

100       None
101

ERRORS

103       The CQE res field will contain the result of the operation.
104
105       io_uring_prep_accept(3)  generates the installed file descriptor as its
106       result.
107
108       io_uring_prep_accept_direct(3) and file_index set to a specific  direct
109       descriptor  generates 0 on success.  The caller must remember which di‐
110       rect descriptor was picked for this request.
111
112       io_uring_prep_accept_direct(3) and file_index  set  to  IORING_FILE_IN‐
113       DEX_ALLOC generates the dynamically chosen direct descriptor.
114
115       io_uring_prep_multishot_accept(3) generates the installed file descrip‐
116       tor in each result.
117
118       io_uring_prep_multishot_accept_direct(3),  generates  the   dynamically
119       chosen direct descriptor in each result.
120
121       Note  that where synchronous system calls will return -1 on failure and
122       set errno to the actual error value, io_uring never  uses  errno.   In‐
123       stead it generates the negated errno directly in the CQE res field.
124

NOTES

126       As with any request that passes in data in a struct, that data must re‐
127       main valid until the request has been successfully submitted.  It  need
128       not  remain  valid until completion. Once a request has been submitted,
129       the in-kernel state is stable. Very early kernels (5.4 and earlier) re‐
130       quired  state  to be stable until the completion occurred. Applications
131       can test for this behavior by inspecting the  IORING_FEAT_SUBMIT_STABLE
132       flag passed back from io_uring_queue_init_params(3).
133

SEE ALSO

135       io_uring_get_sqe(3),   io_uring_submit(3),  io_uring_register_files(3),
136       io_uring_register_files_sparse(3),           io_uring_register_file_al‐
137       loc_range(3), io_uring_register(2), accept4(2)
138
139
140
141liburing-2.2                    March 13, 2022         io_uring_prep_accept(3)
Impressum