man/io_uring_prep_accept.3 - platform/external/liburing - Git at Google

 .\" Copyright (C) 2022 Jens Axboe <[email protected]>
 .\"
 .\" 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 and its three variants prepare an accept request similar to
 .BR accept4 (2).
 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 .

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

 .SH RETURN VALUE
 None
 .SH ERRORS
 The CQE
 .I res
 field will contain the result of the operation.

 .BR io_uring_prep_accept (3)
 generates the installed file descriptor as its result.

 .BR io_uring_prep_accept_direct (3)
 and
 .I file_index
 set to a specific direct descriptor
 generates
 .B 0
 on success.
 The caller must remember which direct descriptor was picked for this request.

 .BR io_uring_prep_accept_direct (3)
 and
 .I file_index
 set to
 .B IORING_FILE_INDEX_ALLOC
 generates the dynamically chosen direct descriptor.

 .BR io_uring_prep_multishot_accept (3)
 generates the installed file descriptor in each result.

 .BR io_uring_prep_multishot_accept_direct (3),
 generates the dynamically chosen direct descriptor in each result.

 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 generates 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_files (3),
 .BR io_uring_register_files_sparse (3),
 .BR io_uring_register_file_alloc_range (3),
 .BR io_uring_register (2),
 .BR accept4 (2)
	.\" Copyright (C) 2022 Jens Axboe <[email protected]>
	.\"
	.\" 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 and its three variants prepare an accept request similar to
	.BR accept4 (2).
	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 .

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

	.SH RETURN VALUE
	None
	.SH ERRORS
	The CQE
	.I res
	field will contain the result of the operation.

	.BR io_uring_prep_accept (3)
	generates the installed file descriptor as its result.

	.BR io_uring_prep_accept_direct (3)
	and
	.I file_index
	set to a specific direct descriptor
	generates
	.B 0
	on success.
	The caller must remember which direct descriptor was picked for this request.

	.BR io_uring_prep_accept_direct (3)
	and
	.I file_index
	set to
	.B IORING_FILE_INDEX_ALLOC
	generates the dynamically chosen direct descriptor.

	.BR io_uring_prep_multishot_accept (3)
	generates the installed file descriptor in each result.

	.BR io_uring_prep_multishot_accept_direct (3),
	generates the dynamically chosen direct descriptor in each result.

	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 generates 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_files (3),
	.BR io_uring_register_files_sparse (3),
	.BR io_uring_register_file_alloc_range (3),
	.BR io_uring_register (2),
	.BR accept4 (2)