1io_uring_prep_accept(3) liburing Manual io_uring_prep_accept(3)
2
6 io_uring_prep_accept - prepare an accept request
7
9 #include <sys/socket.h>
10 #include <liburing.h>
11 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 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 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 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
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 The three variants allow combining the direct file table and multishot
45 features.
46 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 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 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 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 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 See the man page accept4(2) for details of the accept function itself.
97
100 None
101
103 The CQE res field will contain the result of the operation.
104 io_uring_prep_accept(3) generates the installed file descriptor as its
106 result.
107 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 io_uring_prep_accept_direct(3) and file_index set to IORING_FILE_IN‐
113 DEX_ALLOC generates the dynamically chosen direct descriptor.
114 io_uring_prep_multishot_accept(3) generates the installed file descrip‐
116 tor in each result.
117 io_uring_prep_multishot_accept_direct(3), generates the dynamically
119 chosen direct descriptor in each result.
120 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
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
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)
138liburing-2.2 March 13, 2022 io_uring_prep_accept(3)