polyphony 1.0.1 → 1.1

data/vendor/liburing/man/io_uring_prep_provide_buffers.3

@@ -1,140 +0,0 @@
-.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
-.\"
-.\" SPDX-License-Identifier: LGPL-2.0-or-later
-.\"
-.TH io_uring_prep_provide_buffers 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
-.SH NAME
-io_uring_prep_provide_buffers \- prepare a provide buffers request
-.SH SYNOPSIS
-.nf
-.B #include <liburing.h>
-.PP
-.BI "void io_uring_prep_provide_buffers(struct io_uring_sqe *" sqe ","
-.BI "                                   void *" addr ","
-.BI "                                   int " len ","
-.BI "                                   int " nr ","
-.BI "                                   int " bgid ","
-.BI "                                   int " bid ");"
-.fi
-.SH DESCRIPTION
-.PP
-The
-.BR io_uring_prep_provide_buffers (3)
-function prepares a request for providing the kernel with buffers. The
-submission queue entry
-.I sqe
-is setup to consume
-.I nr
-number of
-.I len
-sized buffers starting at
-.I addr
-and identified by the buffer group ID of
-.I bgid
-and numbered sequentially starting at
-.IR bid .
-
-This function sets up a request to provide buffers to the io_uring context
-that can be used by read or receive operations. This is done by filling in
-the SQE
-.I buf_group
-field and setting
-.B IOSQE_BUFFER_SELECT
-in the SQE
-.I flags
-member. If buffer selection is used for a request, no buffer should be provided
-in the address field. Instead, the group ID is set to match one that was
-previously provided to the kernel. The kernel will then select a buffer from
-this group for the IO operation. On successful completion of the IO request,
-the CQE
-.I flags
-field will have
-.B IORING_CQE_F_BUFFER
-set and the selected buffer ID will be indicated by the upper 16-bits of the
-.I flags
-field.
-
-Different buffer group IDs can be used by the application to have different
-sizes or types of buffers available. Once a buffer has been consumed for an
-operation, it is no longer known to io_uring. It must be re-provided if so
-desired or freed by the application if no longer needed.
-
-The buffer IDs are internally tracked from
-.I bid
-and sequentially ascending from that value. If
-.B 16
-buffers are provided and start with an initial
-.I bid
-of 0, then the buffer IDs will range from
-.BR 0..15 .
-The application must be aware of this to make sense of the buffer ID passed
-back in the CQE.
-
-Buffer IDs always range from
-.B 0
-to
-.B 65535 ,
-as there are only 16-bits available in the CQE to pass them back. This range
-is independent of how the buffer group initially got created. Attempting to
-add buffer IDs larger than that, or buffer IDs that will wrap when cast to
-a 16-bit value, will cause the request to fail with
-.B -E2BIG
-or
-.B -EINVAL .
-
-Not all requests support buffer selection, as it only really makes sense for
-requests that receive data from the kernel rather than write or provide data.
-Currently, this mode of operation is supported for any file read or socket
-receive request. Attempting to use
-.B IOSQE_BUFFER_SELECT
-with a command that doesn't support it will result in a CQE
-.I res
-error of
-.BR -EINVAL .
-Buffer selection will work with operations that take a
-.B struct iovec
-as its data destination, but only if 1 iovec is provided.
-.
-.SH RETURN VALUE
-None
-.SH ERRORS
-These are the errors that are reported in the CQE
-.I res
-field. On success,
-.I res
-will contain
-.B 0
-or the number of successfully provided buffers.
-.TP
-.B -ENOMEM
-The kernel was unable to allocate memory for the request.
-.TP
-.B -EINVAL
-One of the fields set in the SQE was invalid.
-.TP
-.B -E2BIG
-The number of buffers provided was too big, or the
-.I bid
-was too big. A max value of
-.B USHRT_MAX
-buffers can be specified.
-.TP
-.B -EFAULT
-Some of the user memory given was invalid for the application.
-.TP
-.B -EOVERFLOW
-The product of
-.I len
-and
-.I nr
-exceed the valid amount or overflowed, or the sum of
-.I addr
-and the length of buffers overflowed.
-.TP
-.B -EBUSY
-Attempt to update a slot that is already used.
-.SH SEE ALSO
-.BR io_uring_get_sqe (3),
-.BR io_uring_submit (3),
-.BR io_uring_register (2),
-.BR io_uring_prep_remove_buffers (3)

data/vendor/liburing/man/io_uring_prep_read.3

@@ -1,69 +0,0 @@
-.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com>
-.\"
-.\" SPDX-License-Identifier: LGPL-2.0-or-later
-.\"
-.TH io_uring_prep_read 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
-.SH NAME
-io_uring_prep_read \- prepare I/O read request
-.SH SYNOPSIS
-.nf
-.B #include <liburing.h>
-.PP
-.BI "void io_uring_prep_read(struct io_uring_sqe *" sqe ","
-.BI "                        int " fd ","
-.BI "                        void *" buf ","
-.BI "                        unsigned " nbytes ","
-.BI "                        __u64 " offset ");"
-.fi
-.SH DESCRIPTION
-.PP
-The
-.BR io_uring_prep_read (3)
-prepares an IO read request. The submission queue entry
-.I sqe
-is setup to use the file descriptor
-.I fd
-to start reading
-.I nbytes
-into the buffer
-.I buf
-at the specified
-.IR offset .
-
-On files that support seeking, if the offset is set to
-.BR -1 ,
-the read operation commences at the file offset, and the file offset is
-incremented by the number of bytes read. See
-.BR read (2)
-for more details. Note that for an async API, reading and updating the
-current file offset may result in unpredictable behavior, unless access
-to the file is serialized. It is not encouraged to use this feature, if it's
-possible to provide the desired IO offset from the application or library.
-
-On files that are not capable of seeking, the offset must be 0 or -1.
-
-After the read has been prepared it can be submitted with one of the submit
-functions.
-
-.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_prep_readv (3),
-.BR io_uring_prep_readv2 (3),
-.BR io_uring_submit (3)

data/vendor/liburing/man/io_uring_prep_read_fixed.3

@@ -1,72 +0,0 @@
-.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
-.\"
-.\" SPDX-License-Identifier: LGPL-2.0-or-later
-.\"
-.TH io_uring_prep_read 3 "February 13, 2022" "liburing-2.1" "liburing Manual"
-.SH NAME
-io_uring_prep_read_fixed \- prepare I/O read request with registered buffer
-.SH SYNOPSIS
-.nf
-.B #include <liburing.h>
-.PP
-.BI "void io_uring_prep_read_fixed(struct io_uring_sqe *" sqe ","
-.BI "                        int " fd ","
-.BI "                        void *" buf ","
-.BI "                        unsigned " nbytes ","
-.BI "                        __u64 " offset ","
-.BI "                        int " buf_index ");"
-.fi
-.SH DESCRIPTION
-.PP
-The
-.BR io_uring_prep_read_fixed (3)
-prepares an IO read request with a previously registered IO buffer. The
-submission queue entry
-.I sqe
-is setup to use the file descriptor
-.I fd
-to start reading
-.I nbytes
-into the buffer
-.I buf
-at the specified
-.IR offset ,
-and with the buffer matching the registered index of
-.IR buf_index .
-
-This works just like
-.BR io_uring_prep_read (3)
-except it requires the use of buffers that have been registered with
-.BR io_uring_register_buffers (3).
-The
-.I buf
-and
-.I nbytes
-arguments must fall within a region specified by
-.I buf_index
-in the previously registered buffer. The buffer need not be aligned with
-the start of the registered buffer.
-
-After the read has been prepared it can be submitted with one of the submit
-functions.
-
-.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_prep_read (3),
-.BR io_uring_register_buffers (3)

data/vendor/liburing/man/io_uring_prep_readv.3

@@ -1,85 +0,0 @@
-.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com>
-.\"
-.\" SPDX-License-Identifier: LGPL-2.0-or-later
-.\"
-.TH io_uring_prep_readv 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
-.SH NAME
-io_uring_prep_readv \- prepare vector I/O read request
-.SH SYNOPSIS
-.nf
-.B #include <sys/uio.h>
-.B #include <liburing.h>
-.PP
-.BI "void io_uring_prep_readv(struct io_uring_sqe *" sqe ","
-.BI "                         int " fd ","
-.BI "                         const struct iovec *" iovecs ","
-.BI "                         unsigned " nr_vecs ","
-.BI "                         __u64 " offset ");"
-.fi
-.SH DESCRIPTION
-.PP
-The
-.BR io_uring_prep_readv (3)
-prepares a vectored IO read request. The submission queue entry
-.I sqe
-is setup to use the file descriptor
-.I fd
-to start reading
-.I nr_vecs
-into the
-.I iovecs
-array at the specified
-.IR offset .
-
-On files that support seeking, if the offset is set to
-.BR -1 ,
-the read operation commences at the file offset, and the file offset is
-incremented by the number of bytes read. See
-.BR read (2)
-for more details. Note that for an async API, reading and updating the
-current file offset may result in unpredictable behavior, unless access
-to the file is serialized. It is not encouraged to use this feature, if it's
-possible to provide the desired IO offset from the application or library.
-
-On files that are not capable of seeking, the offset must be 0 or -1.
-
-After the read has been prepared it can be submitted with one of the submit
-functions.
-
-.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
-Unless an application explicitly needs to pass in more than one iovec, it
-is more efficient to use
-.BR io_uring_prep_read (3)
-rather than this function, as no state has to be maintained for a
-non-vectored IO request.
-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_prep_read (3),
-.BR io_uring_prep_readv2 (3),
-.BR io_uring_submit (3)

data/vendor/liburing/man/io_uring_prep_readv2.3

@@ -1,111 +0,0 @@
-.\" Copyright (C) 2021 Stefan Roesch <shr@fb.com>
-.\"
-.\" SPDX-License-Identifier: LGPL-2.0-or-later
-.\"
-.TH io_uring_prep_readv2 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
-.SH NAME
-io_uring_prep_readv2 \- prepare vector I/O read request with flags
-.SH SYNOPSIS
-.nf
-.B #include <sys/uio.h>
-.B #include <liburing.h>
-.PP
-.BI "void io_uring_prep_readv2(struct io_uring_sqe *" sqe ","
-.BI "                          int " fd ","
-.BI "                          const struct iovec *" iovecs ","
-.BI "                          unsigned " nr_vecs ","
-.BI "                          __u64 " offset ","
-.BI "                          int " flags ");"
-.fi
-.SH DESCRIPTION
-.PP
-The
-.BR io_uring_prep_readv2 (3)
-prepares a vectored IO read request. The submission queue entry
-.I sqe
-is setup to use the file descriptor
-.I fd
-to start reading
-.I nr_vecs
-into the
-.I iovecs
-array at the specified
-.IR offset .
-The behavior of the function can be controlled with the
-.I flags
-parameter.
-
-Supported values for
-.I flags
-are:
-.TP
-.B RWF_HIPRI
-High priority request, poll if possible
-.TP
-.B RWF_DSYNC
-per-IO O_DSYNC
-.TP
-.B RWF_SYNC
-per-IO O_SYNC
-.TP
-.B RWF_NOWAIT
-per-IO, return
-.B -EAGAIN
-if operation would block
-.TP
-.B RWF_APPEND
-per-IO O_APPEND
-
-.P
-On files that support seeking, if the offset is set to
-.BR -1 ,
-the read operation commences at the file offset, and the file offset is
-incremented by the number of bytes read. See
-.BR read (2)
-for more details. Note that for an async API, reading and updating the
-current file offset may result in unpredictable behavior, unless access
-to the file is serialized. It is not encouraged to use this feature, if it's
-possible to provide the desired IO offset from the application or library.
-
-On files that are not capable of seeking, the offset must be 0 or -1.
-
-After the read has been prepared, it can be submitted with one of the submit
-functions.
-
-.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
-Unless an application explicitly needs to pass in more than one iovec, it
-is more efficient to use
-.BR io_uring_prep_read (3)
-rather than this function, as no state has to be maintained for a
-non-vectored IO request.
-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_prep_read (3),
-.BR io_uring_prep_readv (3),
-.BR io_uring_submit (3)

data/vendor/liburing/man/io_uring_prep_recv.3

@@ -1,105 +0,0 @@
-.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
-.\"
-.\" SPDX-License-Identifier: LGPL-2.0-or-later
-.\"
-.TH io_uring_prep_recv 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
-.SH NAME
-io_uring_prep_recv \- prepare a recv request
-.SH SYNOPSIS
-.nf
-.B #include <liburing.h>
-.PP
-.BI "void io_uring_prep_recv(struct io_uring_sqe *" sqe ","
-.BI "                        int " sockfd ","
-.BI "                        void *" buf ","
-.BI "                        size_t " len ","
-.BI "                        int " flags ");"
-.PP
-.BI "void io_uring_prep_recv_multishot(struct io_uring_sqe *" sqe ","
-.BI "                                  int " sockfd ","
-.BI "                                  void *" buf ","
-.BI "                                  size_t " len ","
-.BI "                                  int " flags ");"
-.fi
-.SH DESCRIPTION
-.PP
-The
-.BR io_uring_prep_recv (3)
-function prepares a recv request. The submission
-queue entry
-.I sqe
-is setup to use the file descriptor
-.I sockfd
-to start receiving the data into the destination buffer
-.I buf
-of size
-.I len
-and with modifier flags
-.IR flags .
-
-This function prepares an async
-.BR recv (2)
-request. See that man page for details on the arguments specified to this
-prep helper.
-
-The multishot version allows the application to issue a single receive request,
-which repeatedly posts a CQE when data is available. It requires length to
-be 0, the
-.B IOSQE_BUFFER_SELECT
-flag to be set and no
-.B MSG_WAITALL
-flag to be set.
-Therefore each CQE will take a buffer out of a provided buffer pool for receiving.
-The application should check the flags of each CQE, regardless of its result.
-If a posted CQE does not have the
-.B IORING_CQE_F_MORE
-flag set then the multishot receive will be done and the application should issue a
-new request.
-Multishot variants are available since kernel 6.0.
-
-
-After calling this function, additional io_uring internal modifier flags
-may be set in the SQE
-.I ioprio
-field. The following flags are supported:
-.TP
-.B IORING_RECVSEND_POLL_FIRST
-If set, io_uring will assume the socket is currently empty and attempting to
-receive data will be unsuccessful. For this case, io_uring will arm internal
-poll and trigger a receive of the data when the socket has data to be read.
-This initial receive attempt can be wasteful for the case where the socket
-is expected to be empty, setting this flag will bypass the initial receive
-attempt and go straight to arming poll. If poll does indicate that data is
-ready to be received, the operation will proceed.
-
-Can be used with the CQE
-.B IORING_CQE_F_SOCK_NONEMPTY
-flag, which io_uring will set on CQEs after a
-.BR recv (2)
-or
-.BR recvmsg (2)
-operation. If set, the socket still had data to be read after the operation
-completed. Both these flags are available since 5.19.
-.P
-
-.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 recv (2)

data/vendor/liburing/man/io_uring_prep_recv_multishot.3

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