polyphony 0.94 → 0.95

data/vendor/liburing/man/io_uring_get_events.3

@@ -0,0 +1,33 @@
+.\" Copyright (C) 2022 Dylan Yudaken
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_get_events 3 "September 5, 2022" "liburing-2.3" "liburing Manual"
+.SH NAME
+io_uring_get_events \- Flush outstanding requests to CQE ring
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_get_events(struct io_uring *" ring ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_get_events (3)
+function runs outstanding work and flushes completion events to the CQE ring.
+
+There can be events needing to be flushed if the ring was full and had overflowed.
+Alternatively if the ring was setup with the
+.BR IORING_SETUP_DEFER_TASKRUN
+flag then this will process outstanding tasks, possibly resulting in more CQEs.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_get_events (3)
+returns 0. On failure it returns
+.BR -errno .
+.SH SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit_and_get_events (3),
+.BR io_uring_cq_has_overflow (3)

data/vendor/liburing/man/io_uring_get_probe.3

@@ -2,21 +2,22 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH io_uring_get_probe "January 25, 2022" "liburing-2.1" "liburing Manual"
+.TH io_uring_get_probe 3 "January 25, 2022" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_get_probe - get probe instance
+io_uring_get_probe \- get probe instance
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "io_uring_probe *io_uring_get_probe(void)"
+.BI "io_uring_probe *io_uring_get_probe(void);"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The function io_uring_get_probe() returns an allocated io_uring_probe
-structure to the caller. The caller is responsible for freeing the
-structure with the function io_uring_free_probe().
+The function
+.BR io_uring_get_probe (3)
+returns an allocated io_uring_probe structure to the caller. The caller is
+responsible for freeing the structure with the function
+.BR io_uring_free_probe (3).
 
 .SH NOTES
 Earlier versions of the Linux kernel do not support probe. If the kernel

data/vendor/liburing/man/io_uring_get_sqe.3

@@ -5,24 +5,26 @@
 .\"
 .TH io_uring_get_sqe 3 "July 10, 2020" "liburing-0.7" "liburing Manual"
 .SH NAME
-io_uring_get_sqe - get the next available submission queue entry from the
+io_uring_get_sqe \- get the next available submission queue entry from the
 submission queue
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "struct io_uring_sqe *io_uring_get_sqe(struct io_uring " *ring );
+.BI "struct io_uring_sqe *io_uring_get_sqe(struct io_uring *" ring ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_get_sqe() function gets the next available submission queue entry
-from the submission queue belonging to the
+The
+.BR io_uring_get_sqe (3)
+function gets the next available submission queue entry from the submission
+queue belonging to the
 .I ring
 param.
 
-On success io_uring_get_sqe() returns a pointer to the submission queue entry.
-On failure NULL is returned.
+On success
+.BR io_uring_get_sqe (3)
+returns a pointer to the submission queue entry. On failure NULL is returned.
 
 If a submission queue entry is returned, it should be filled out via one of the
 prep functions such as
@@ -30,9 +32,26 @@ prep functions such as
 and submitted via
 .BR io_uring_submit (3).
 
+Note that neither
+.BR io_uring_get_sqe
+nor the prep functions set (or clear) the
+.B user_data
+field of the SQE. If the caller expects
+.BR io_uring_cqe_get_data (3)
+or
+.BR io_uring_cqe_get_data64 (3)
+to return valid data when reaping IO completions, either
+.BR io_uring_sqe_set_data (3)
+or
+.BR io_uring_sqe_set_data64 (3)
+.B MUST
+have been called before submitting the request.
+
 .SH RETURN VALUE
 .BR io_uring_get_sqe (3)
 returns a pointer to the next submission queue event on success and NULL on
-failure.
+failure. If NULL is returned, the SQ ring is currently full and entries must
+be submitted for processing before new ones can get allocated.
 .SH SEE ALSO
-.BR io_uring_submit (3)
+.BR io_uring_submit (3),
+.BR io_uring_sqe_set_data (3)

data/vendor/liburing/man/io_uring_opcode_supported.3

@@ -2,28 +2,29 @@
 .\"
 .\" SPDX-License-Identifier: LGPL-2.0-or-later
 .\"
-.TH io_uring_opcode_supported "January 25, 2022" "liburing-2.1" "liburing Manual"
+.TH io_uring_opcode_supported 3 "January 25, 2022" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_opcode_supported - is op code supported?
+io_uring_opcode_supported \- is op code supported?
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "int io_uring_opcode_supported(struct io_uring_probe *probe,"
-.BI "                              int opode)
+.BI "int io_uring_opcode_supported(struct io_uring_probe *" probe ","
+.BI "                              int " opcode ");"
 .fi
-.PP
 .SH DESCRIPTION
 .PP
-The function io_uring_opcode_supported allows the caller to determine if
-the passed in
+The function
+.BR io_uring_opcode_supported (3)
+allows the caller to determine if the passed in
 .I opcode
 belonging to the
 .I probe
 param is supported. An instance of the io_uring_probe instance can be
-obtained by calling the function io_uring_get_probe().
+obtained by calling the function
+.BR io_uring_get_probe (3).
 
 .SH RETURN VALUE
 On success it returns 1, otherwise it returns 0.
 .SH SEE ALSO
-.BR io_uring_get_probe (3)
+.BR io_uring_get_probe (3)

data/vendor/liburing/man/io_uring_peek_cqe.3

@@ -0,0 +1,38 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_peek_cqe 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_peek_cqe \- check if an io_uring completion event is available
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_peek_cqe(struct io_uring *" ring ","
+.BI "                      struct io_uring_cqe **" cqe_ptr ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_peek_cqe (3)
+function returns an IO completion from the queue belonging to the
+.I ring
+param, if one is readily available. On successful return,
+.I cqe_ptr
+param is filled with a valid CQE entry.
+
+This function does not enter the kernel to wait for an event, an event
+is only returned if it's already available in the CQ ring.
+
+.SH RETURN VALUE
+On success
+.BR io_uring_peek_cqe (3)
+returns
+.B 0
+and the cqe_ptr parameter is filled in. On failure it returns
+.BR -EAGAIN .
+.SH SEE ALSO
+.BR io_uring_submit (3),
+.BR io_uring_wait_cqes (3),
+.BR io_uring_wait_cqe (3)

data/vendor/liburing/man/io_uring_prep_accept.3

@@ -0,0 +1,197 @@
+.\" 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 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 targetted 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)

data/vendor/liburing/man/io_uring_prep_accept_direct.3

@@ -0,0 +1 @@
+io_uring_prep_accept.3

data/vendor/liburing/man/io_uring_prep_cancel.3

@@ -0,0 +1,118 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_cancel 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_cancel \- prepare a cancelation request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_cancel64(struct io_uring_sqe *" sqe ","
+.BI "                            __u64 " user_data ","
+.BI "                            int " flags ");"
+.PP
+.BI "void io_uring_prep_cancel(struct io_uring_sqe *" sqe ","
+.BI "                          void *" user_data ","
+.BI "                          int " flags ");"
+.PP
+.BI "void io_uring_prep_cancel_fd(struct io_uring_sqe *" sqe ","
+.BI "                          int " fd ","
+.BI "                          int " flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_cancel (3)
+function prepares a cancelation request. The submission queue entry
+.I sqe
+is prepared to cancel an existing request identified by
+.IR user_data .
+For the
+.I flags
+argument, see below.
+
+.BR io_uring_prep_cancel64 (3)
+is identical to
+.BR io_uring_prep_cancel (3) ,
+except it takes a 64-bit integer rather than a pointer type.
+
+The cancelation request will attempt to find the previously issued request
+identified by
+.I user_data
+and cancel it. The identifier is what the previously issued request has in
+their
+.I user_data
+field in the SQE.
+
+The
+.BR io_uring_prep_cancel_fd (3)
+function prepares a cancelation request. The submission queue entry
+.I sqe
+is prepared to cancel an existing request that used the file descriptor
+.IR fd .
+For the
+.I flags
+argument, see below.
+
+The cancelation request will attempt to find the previously issued request
+that used
+.I fd
+as the file descriptor and cancel it.
+
+By default, the first request matching the criteria given will be canceled.
+This can be modified with any of the following flags passed in:
+.TP
+.B IORING_ASYNC_CANCEL_ALL
+Cancel all requests that match the given criteria, rather than just canceling
+the first one found. Available since 5.19.
+.TP
+.B IORING_ASYNC_CANCEL_FD
+Match based on the file descriptor used in the original request rather than
+the user_data. This is what
+.BR io_uring_prep_cancel_fd (3)
+sets up. Available since 5.19.
+.TP
+.B IORING_ASYNC_CANCEL_ANY
+Match any request in the ring, regardless of user_data or file descriptor.
+Can be used to cancel any pending request in the ring. Available since 5.19.
+.P
+
+.SH RETURN VALUE
+None
+.SH ERRORS
+These are the errors that are reported in the CQE
+.I res
+field. If no flags are used to cancel multiple requests,
+.B 0
+is returned on success. If flags are used to match multiple requests, then
+a positive value is returned indicating how many requests were found and
+canceled.
+.TP
+.B -ENOENT
+The request identified by
+.I user_data
+could not be located. This could be because it completed before the cancelation
+request was issued, or if an invalid identifier is used.
+.TP
+.B -EINVAL
+One of the fields set in the SQE was invalid.
+.TP
+.B -EALREADY
+The execution state of the request has progressed far enough that cancelation
+is no longer possible. This should normally mean that it will complete shortly,
+either successfully, or interrupted due to the cancelation.
+.SH NOTES
+Although the cancelation request uses async request syntax, the kernel side of
+the cancelation is always run synchronously. It is guaranteed that a CQE is
+always generated by the time the cancel request has been submitted. If the
+cancelation is successful, the completion for the request targeted for
+cancelation will have been posted by the time submission returns. For
+.B -EALREADY
+it may take a bit of time to do so. For this case, the caller must wait for the
+canceled request to post its completion event.
+.SH SEE ALSO
+.BR io_uring_prep_poll_remove (3),
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3)

data/vendor/liburing/man/io_uring_prep_cancel64.3

@@ -0,0 +1 @@
+io_uring_prep_cancel.3

data/vendor/liburing/man/io_uring_prep_close.3

@@ -0,0 +1,59 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_close 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_close \- prepare a file descriptor close request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_close(struct io_uring_sqe *" sqe ","
+.BI "                          int " fd ");"
+.PP
+.BI "void io_uring_prep_close_direct(struct io_uring_sqe *" sqe ","
+.BI "                                unsigned " file_index ");"
+.PP
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_close (3)
+function prepares a close request. The submission queue entry
+.I sqe
+is setup to close the file descriptor indicated by
+.IR fd .
+
+For a direct descriptor close request, the offset is specified by the
+.I file_index
+argument instead of the
+.IR fd .
+This is identical to unregistering the direct descriptor, and is provided as
+a convenience.
+
+These functions prepare an async
+.BR close (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. See the related man page for
+details on possible values. 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 SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
+.BR close (2)

data/vendor/liburing/man/io_uring_prep_close_direct.3

@@ -0,0 +1 @@
+io_uring_prep_close.3

data/vendor/liburing/man/io_uring_prep_connect.3

@@ -0,0 +1,66 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_connect 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_connect \- prepare a connect request
+.SH SYNOPSIS
+.nf
+.B #include <sys/types.h>
+.B #include <sys/socket.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_connect(struct io_uring_sqe *" sqe ","
+.BI "                           int " sockfd ","
+.BI "                           const struct sockaddr *" addr ","
+.BI "                           socklen_t " addrlen ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_connect (3)
+function prepares a connect request. The submission queue entry
+.I sqe
+is setup to use the file descriptor
+.I sockfd
+to start connecting to the destination described by the socket address at
+.I addr
+and of structure length
+.IR addrlen .
+
+This function prepares an async
+.BR connect (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. See the related man page for
+details on possible values. 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 connect (2)