160 lines
5.9 KiB
Groff
160 lines
5.9 KiB
Groff
|
.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
|
||
|
|
.\"
|
||
|
|
.\" SPDX-License-Identifier: LGPL-2.0-or-later
|
||
|
|
.\"
|
||
|
|
.TH io_uring_prep_accept 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
|
||
|
|
.SH NAME
|
||
|
|
io_uring_prep_accept \- prepare an accept request
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
.B #include <sys/socket.h>
|
||
|
|
.B #include <liburing.h>
|
||
|
|
.PP
|
||
|
|
.BI "void io_uring_prep_accept(struct io_uring_sqe *" sqe ","
|
||
|
|
.BI " int " sockfd ","
|
||
|
|
.BI " struct sockaddr *" addr ","
|
||
|
|
.BI " socklen_t *" addrlen ","
|
||
|
|
.BI " int " flags ");"
|
||
|
|
.PP
|
||
|
|
.BI "void io_uring_prep_accept_direct(struct io_uring_sqe *" sqe ","
|
||
|
|
.BI " int " sockfd ","
|
||
|
|
.BI " struct sockaddr *" addr ","
|
||
|
|
.BI " socklen_t *" addrlen ","
|
||
|
|
.BI " int " flags ","
|
||
|
|
.BI " unsigned int " file_index ");"
|
||
|
|
.PP
|
||
|
|
.BI "void io_uring_prep_multishot_accept(struct io_uring_sqe *" sqe ","
|
||
|
|
.BI " int " sockfd ","
|
||
|
|
.BI " struct sockaddr *" addr ","
|
||
|
|
.BI " socklen_t *" addrlen ","
|
||
|
|
.BI " int " flags ");"
|
||
|
|
.PP
|
||
|
|
.BI "void io_uring_prep_multishot_accept_direct(struct io_uring_sqe *" sqe ","
|
||
|
|
.BI " int " sockfd ","
|
||
|
|
.BI " struct sockaddr *" addr ","
|
||
|
|
.BI " socklen_t *" addrlen ","
|
||
|
|
.BI " int " flags ");"
|
||
|
|
.fi
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
The
|
||
|
|
.BR io_uring_prep_accept (3)
|
||
|
|
function prepares an accept request. The submission queue entry
|
||
|
|
.I sqe
|
||
|
|
is setup to use the file descriptor
|
||
|
|
.I sockfd
|
||
|
|
to start accepting a connection request described by the socket address at
|
||
|
|
.I addr
|
||
|
|
and of structure length
|
||
|
|
.I addrlen
|
||
|
|
and using modifier flags in
|
||
|
|
.IR flags .
|
||
|
|
|
||
|
|
For a direct descriptor accept request, the offset is specified by the
|
||
|
|
.I 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,
|
||
|
|
.B IOSQE_FIXED_FILE
|
||
|
|
must be set in the SQE
|
||
|
|
.I flags
|
||
|
|
member, and the SQE
|
||
|
|
.I 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
|
||
|
|
.BR 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
|
||
|
|
.BR io_uring_register_files_update (3).
|
||
|
|
Note that old kernels don't check the SQE
|
||
|
|
.I 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
|
||
|
|
.B IORING_OP_ACCEPT_DIRECT
|
||
|
|
before using it, they cannot rely on a
|
||
|
|
.B -EINVAL
|
||
|
|
CQE
|
||
|
|
.I res
|
||
|
|
return.
|
||
|
|
|
||
|
|
For a direct descriptor accept request, the
|
||
|
|
.I file_index
|
||
|
|
argument can be set to
|
||
|
|
.BR 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
|
||
|
|
.IR res .
|
||
|
|
.B -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
|
||
|
|
.I flags
|
||
|
|
and see if
|
||
|
|
.B 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,
|
||
|
|
.B 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
|
||
|
|
.BR -EINVAL .
|
||
|
|
The allocated descriptor will be returned in the CQE
|
||
|
|
.I res
|
||
|
|
field, like a non-direct accept request.
|
||
|
|
|
||
|
|
These functions prepare an async
|
||
|
|
.BR accept4 (2)
|
||
|
|
request. See that man page for details.
|
||
|
|
|
||
|
|
.SH RETURN VALUE
|
||
|
|
None
|
||
|
|
.SH ERRORS
|
||
|
|
The CQE
|
||
|
|
.I 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
|
||
|
|
.B 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
|
||
|
|
.B -1
|
||
|
|
on failure and set
|
||
|
|
.I errno
|
||
|
|
to the actual error value, io_uring never uses
|
||
|
|
.IR errno .
|
||
|
|
Instead it returns the negated
|
||
|
|
.I errno
|
||
|
|
directly in the CQE
|
||
|
|
.I res
|
||
|
|
field.
|
||
|
|
.SH 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
|
||
|
|
.B IORING_FEAT_SUBMIT_STABLE
|
||
|
|
flag passed back from
|
||
|
|
.BR io_uring_queue_init_params (3).
|
||
|
|
.SH SEE ALSO
|
||
|
|
.BR io_uring_get_sqe (3),
|
||
|
|
.BR io_uring_submit (3),
|
||
|
|
.BR io_uring_register (2),
|
||
|
|
.BR accept4 (2)
|