polyphony 0.98 → 0.99.1

data/vendor/liburing/man/io_uring_check_version.3

@@ -0,0 +1,72 @@
+.\" Copyright (C) 2022 Christian Hergert <chergert@redhat.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_check_version 3 "December 1, 2022" "liburing-2.4" "liburing Manual"
+.SH NAME
+io_uring_check_version \- functions and macros to check the liburing version
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "bool io_uring_check_version(int " major ", int " minor ");"
+.BI "IO_URING_CHECK_VERSION(" major ", " minor ");"
+.PP
+.BI "int io_uring_major_version(void);"
+.BI "IO_URING_VERSION_MAJOR;"
+.PP
+.BI "int io_uring_minor_version(void);"
+.BI "IO_URING_VERSION_MINOR;"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_check_version (3)
+function returns
+.I true
+if the liburing library loaded by the dynamic linker is greater-than
+or equal-to the
+.I major
+and
+.I minor
+numbers provided.
+
+.PP
+The
+.BR IO_URING_CHECK_VERSION (3)
+macro returns
+.I 1
+if the liburing library being compiled against is greater-than or equal-to the
+.I major
+and
+.I minor
+numbers provided.
+
+.PP
+The
+.BR io_uring_major_version (3)
+function returns the
+.I major
+version number of the liburing library loaded by the dynamic linker.
+
+.PP
+The
+.BR IO_URING_VERSION_MAJOR (3)
+macro returns the
+.I major
+version number of the liburing library being compiled against.
+
+.PP
+The
+.BR io_uring_minor_version (3)
+function returns the
+.I minor
+version number of the liburing library loaded by the dynamic linker.
+
+.PP
+The
+.BR IO_URING_VERSION_MINOR (3)
+macro returns the
+.I minor
+version number of the liburing library being compiled against.
+

data/vendor/liburing/man/io_uring_close_ring_fd.3

@@ -0,0 +1,43 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\" Copyright (C) 2022 Josh Triplett <josh@joshtriplett.org>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_close_ring_fd 3 "September 25, 2022" "liburing-2.4" "liburing Manual"
+.SH NAME
+io_uring_close_ring_fd \- close a ring file descriptor and use it only via registered index
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "int io_uring_close_ring_fd(struct io_uring *" ring ");"
+.fi
+.SH DESCRIPTION
+.PP
+.BR io_uring_close_ring_fd (3)
+closes the ring file descriptor, which must have been previously registered.
+The file will remain open, but accessible only via the registered index, not
+via any file descriptor. Subsequent liburing calls will continue to work, using
+the registered ring fd.
+
+The kernel must support
+.BR IORING_FEAT_REG_REG_RING .
+
+Libraries that must avoid disrupting their users' uses of file descriptors, and
+must continue working even in the face of
+.BR close_range (2)
+and similar, can use
+.BR io_uring_close_ring_fd (3)
+to work with liburing without having any open file descriptor.
+
+.SH NOTES
+Each thread that wants to make use of io_uring must register the fd. A library
+that may get called from arbitrary theads may need to detect when it gets
+called on a previously unseen thread and create and register a ring for that
+thread.
+.SH RETURN VALUE
+Returns 1 on success, or
+.BR -errno
+on error.
+.SH SEE ALSO
+.BR io_uring_register_ring_fd (3)

data/vendor/liburing/man/io_uring_major_version.3

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

data/vendor/liburing/man/io_uring_minor_version.3

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

data/vendor/liburing/man/io_uring_prep_accept.3

@@ -92,7 +92,7 @@ will have an unused table index dynamically chosen and returned for each connect
 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.
+a different range than that targeted by specific requests.
 
 Note that old kernels don't check the SQE
 .I file_index

data/vendor/liburing/man/io_uring_prep_fgetxattr.3

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

data/vendor/liburing/man/io_uring_prep_fsetxattr.3

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

data/vendor/liburing/man/io_uring_prep_getxattr.3

@@ -0,0 +1,61 @@
+.\" Copyright (C) 2023 Rutvik Patel <heyrutvik@gmail.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_getxattr 3 "January 23, 2023" "liburing-2.4" "liburing Manual"
+.SH NAME
+io_uring_prep_getxattr, io_uring_prep_fgetxattr \- prepare a request to get an 
+extended attribute value
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_getxattr(struct io_uring_sqe *" sqe ","
+.BI "                            const char *" name ","
+.BI "                            char *" value ","
+.BI "                            const char *" path ","
+.BI "                            unsigned int " len ");"
+.PP
+.BI "void io_uring_prep_fgetxattr(struct io_uring_sqe *" sqe ","
+.BI "                             int " fd ","
+.BI "                             const char *" name ","
+.BI "                             char *" value ","
+.BI "                             unsigned int " len ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_getxattr (3)
+function prepares a request to get an extended attribute value. The submission 
+queue entry
+.I sqe
+is setup to get the
+.I value
+of the extended attribute identified by
+.I name
+and associated with the given
+.I path
+in the filesystem.
+The
+.I len
+argument specifies the size (in bytes) of
+.IR value .
+
+.BR io_uring_prep_fgetxattr (3)
+is identical to 
+.BR io_uring_prep_getxattr (3),
+only the open file referred to by
+.I fd
+is interrogated in place of
+.IR path .
+
+This function prepares an async 
+.BR getxattr (2)
+request. See that man page for details.
+
+.SH RETURN VALUE
+None
+
+.SH SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR getxattr (2)

data/vendor/liburing/man/io_uring_prep_link_timeout.3

@@ -0,0 +1,94 @@
+.\" Copyright (C) 2023 Rutvik Patel <heyrutvik@gmail.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_link_timeout 3 "January 23, 2023" "liburing-2.4" "liburing Manual"
+.SH NAME
+io_uring_prep_link_timeout \- a timeout request for linked sqes
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_link_timeout(struct io_uring_sqe *" sqe ","
+.BI "                                struct __kernel_timespec *" ts ","
+.BI "                                unsigned " flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+The 
+.BR io_uring_prep_link_timeout (3)
+function prepares a timeout request for linked sqes. The submission queue entry 
+.I sqe
+is setup a timeout specified by
+.IR ts .
+The flags argument holds modifier
+.I flags
+for the timeout behaviour of the request.
+
+The
+.I ts
+argument must be filled in with the appropriate information for the timeout. It looks as follows:
+.PP
+.in +4n
+.EX
+struct __kernel_timespec {
+    __kernel_time64_t tv_sec;
+    long long tv_nsec;
+};
+.EE
+.in
+.PP
+
+The
+.I flags
+argument may contain:
+.TP
+.B IORING_TIMEOUT_ABS
+The value specified in
+.I ts
+is an absolute value rather than a relative one.
+.TP
+.B IORING_TIMEOUT_BOOTTIME
+The boottime clock source should be used.
+.TP
+.B IORING_TIMEOUT_REALTIME
+The realtime clock source should be used.
+.TP
+.B IORING_TIMEOUT_ETIME_SUCCESS
+Consider an expired timeout a success in terms of the posted completion.
+.PP
+
+It is invalid to create a chain (linked sqes) consisting only of a link timeout 
+request. If all the requests in the chain are completed before timeout, then the 
+link timeout request gets cancelled. Upon timeout, all the uncompleted requests 
+in the chain get cancelled.
+
+.SH RETURN VALUE
+None
+
+.SH ERRORS
+.PP
+These are the errors that are reported in the CQE
+.I res
+field. On success,
+.B 0
+is returned.
+.TP
+.B -ETIME
+The specified timeout occurred and triggered the completion event.
+.TP
+.B -EINVAL
+One of the fields set in the SQE was invalid. For example, two clock sources 
+where given, or the specified timeout seconds or nanoseconds where < 0.
+.TP
+.B -EFAULT
+io_uring was unable to access the data specified by ts.
+.TP
+.B -ECANCELED
+The timeout was canceled because all submitted requests were completed successfully 
+or one of the requests resulted in failure.
+
+
+.SH SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_prep_timeout (3)

data/vendor/liburing/man/io_uring_prep_msg_ring.3

@@ -14,11 +14,18 @@ io_uring_prep_msg_ring \- send a message to another ring
 .BI "                        unsigned int " len ","
 .BI "                        __u64 " data ","
 .BI "                        unsigned int " flags ");"
+.PP
+.BI "void io_uring_prep_msg_ring_cqe_flags(struct io_uring_sqe *" sqe ","
+.BI "                        int " fd ","
+.BI "                        unsigned int " len ","
+.BI "                        __u64 " data ","
+.BI "                        unsigned int " flags ","
+.BI "                        unsigned int " cqe_flags ");"
 .fi
 .SH DESCRIPTION
 .PP
 .BR io_uring_prep_msg_ring (3)
-prepares a to send a CQE to an io_uring file descriptor. The submission queue
+prepares to send a CQE to an io_uring file descriptor. The submission queue
 entry
 .I sqe
 is setup to use the file descriptor
@@ -47,6 +54,18 @@ fields. The use case may be anything from simply waking up someone waiting
 on the targeted ring, or it can be used to pass messages between the two
 rings.
 
+.BR io_uring_prep_msg_ring_cqe_flags (3)
+is similar to
+.BR io_uring_prep_msg_ring (3) .
+But has an addition
+.I cqe_flags
+parameter, which is used to set
+.I flags
+field on CQE side. That way, you can set the CQE flags field
+.I cqe->flags
+when sending a message. Be aware that io_uring could potentially set additional
+bits into this field.
+
 .SH RETURN VALUE
 None
 
@@ -64,7 +83,8 @@ One of the fields set in the SQE was invalid.
 .B -EBADFD
 The descriptor passed in
 .I fd
-does not refer to an io_uring file descriptor.
+does not refer to an io_uring file descriptor, or the ring is in a disabled
+state.
 .TP
 .B -EOVERFLOW
 The kernel was unable to fill a CQE on the target ring. This can happen if

data/vendor/liburing/man/io_uring_prep_msg_ring_cqe_flags.3

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

data/vendor/liburing/man/io_uring_prep_poll_add.3

@@ -33,7 +33,7 @@ argument.
 The default behavior is a single-shot poll request. When the specified event
 has triggered, a completion CQE is posted and no more events will be generated
 by the poll request.
-.BR io_uring_prep_multishot (3)
+.BR io_uring_prep_poll_multishot (3)
 behaves identically in terms of events, but it persist across notifications
 and will repeatedly post notifications for the same registration. A CQE
 posted from a multishot poll request will have

data/vendor/liburing/man/io_uring_prep_provide_buffers.3

@@ -24,8 +24,10 @@ 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
-number of buffers starting at
+sized buffers starting at
 .I addr
 and identified by the buffer group ID of
 .I bgid
@@ -68,6 +70,18 @@ of 0, then the buffer IDs will range from
 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
@@ -88,8 +102,9 @@ These are the errors that are reported in the CQE
 .I res
 field. On success,
 .I res
-will contain the number of successfully provided buffers. On error,
-the following errors can occur.
+will contain
+.B 0
+or the number of successfully provided buffers.
 .TP
 .B -ENOMEM
 The kernel was unable to allocate memory for the request.
@@ -107,12 +122,6 @@ buffers can be specified.
 .B -EFAULT
 Some of the user memory given was invalid for the application.
 .TP
-.B -EBADF
-On of the descriptors located in
-.I fds
-didn't refer to a valid file descriptor, or one of the file descriptors in
-the array referred to an io_uring instance.
-.TP
 .B -EOVERFLOW
 The product of
 .I len

data/vendor/liburing/man/io_uring_prep_readv.3

@@ -43,7 +43,7 @@ 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 write has been prepared it can be submitted with one of the submit
+After the read has been prepared it can be submitted with one of the submit
 functions.
 
 .SH RETURN VALUE
@@ -64,8 +64,8 @@ directly in the CQE
 .I res
 field.
 .SH NOTES
-Unless an application explicitly needs to pass in more than iovec, it is more
-efficient to use
+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.

data/vendor/liburing/man/io_uring_prep_readv2.3

@@ -69,7 +69,7 @@ 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 write has been prepared, it can be submitted with one of the submit
+After the read has been prepared, it can be submitted with one of the submit
 functions.
 
 .SH RETURN VALUE
@@ -90,8 +90,8 @@ directly in the CQE
 .I res
 field.
 .SH NOTES
-Unless an application explicitly needs to pass in more than iovec, it is more
-efficient to use
+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.

data/vendor/liburing/man/io_uring_prep_recv.3

@@ -30,10 +30,10 @@ queue entry
 .I sqe
 is setup to use the file descriptor
 .I sockfd
-to start receiving the data into the buffer destination
+to start receiving the data into the destination buffer
 .I buf
 of size
-.I size
+.I len
 and with modifier flags
 .IR flags .
 
@@ -43,14 +43,14 @@ 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
+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 it's result.
+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

data/vendor/liburing/man/io_uring_prep_recvmsg.3

@@ -49,20 +49,20 @@ 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 it's result.
+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.
 
 Unlike
-.BR recvmsg (2)
-, multishot recvmsg will prepend a
+.BR recvmsg (2),
+multishot recvmsg will prepend a
 .I struct io_uring_recvmsg_out
 which describes the layout of the rest of the buffer in combination with the initial
 .I struct msghdr
 submitted with the request. See
-.B io_uring_recvmsg_out (3)
+.BR io_uring_recvmsg_out (3)
 for more information on accessing the data.
 
 Multishot variants are available since kernel 6.0.

data/vendor/liburing/man/io_uring_prep_send.3

@@ -30,6 +30,15 @@ of size
 bytes and with modifier flags
 .IR flags .
 
+Note that using
+.B IOSQE_IO_LINK
+with this request type requires the setting of
+.B MSG_WAITALL
+in the
+.IR flags
+argument, as a short send isn't a considered an error condition without
+that being set.
+
 This function prepares an async
 .BR send (2)
 request. See that man page for details.

data/vendor/liburing/man/io_uring_prep_send_set_addr.3

@@ -0,0 +1,38 @@
+.\" Copyright (C) 2023 Rutvik Patel <heyrutvik@gmail.com>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_send_set_addr 3 "January 23, 2023" "liburing-2.4" "liburing Manual"
+.SH NAME
+io_uring_prep_send_set_addr \- set address details for send requests
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_send_set_addr(struct io_uring_sqe *" sqe ","
+.BI "                                 const struct sockaddr *" dest_addr ","
+.BI "                                 __u16 " addr_len ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_send_set_addr (3)
+function sets a socket destination address specified by
+.I dest_addr
+and its length using
+.I addr_len
+parameters. It can be used once 
+.I sqe
+is prepared using any of the
+.BR send (2)
+io_uring helpers. See man pages of
+.BR io_uring_prep_send (3)
+or
+.BR io_uring_prep_send_zc (3).
+.SH RETURN VALUE
+None
+.SH SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_prep_send (3),
+.BR io_uring_prep_send_zc (3),
+.BR send (2)

data/vendor/liburing/man/io_uring_prep_send_zc.3

@@ -10,11 +10,19 @@ io_uring_prep_send_zc \- prepare a zerocopy send request
 .B #include <liburing.h>
 .PP
 .BI "void io_uring_prep_send_zc(struct io_uring_sqe *" sqe ","
-.BI "                        int " sockfd ","
-.BI "                        const void *" buf ","
-.BI "                        size_t " len ","
-.BI "                        int " flags ","
-.BI "                        int " zc_flags ");"
+.BI "                           int " sockfd ","
+.BI "                           const void *" buf ","
+.BI "                           size_t " len ","
+.BI "                           int " flags ","
+.BI "                           unsigned " zc_flags ");"
+.PP
+.BI "void io_uring_prep_send_zc_fixed(struct io_uring_sqe *" sqe ","
+.BI "                                 int " sockfd ","
+.BI "                                 const void *" buf ","
+.BI "                                 size_t " len ","
+.BI "                                 int " flags ","
+.BI "                                 unsigned " zc_flags ");"
+.BI "                                 unsigned " buf_index ");"
 .fi
 .SH DESCRIPTION
 .PP
@@ -29,11 +37,35 @@ to start sending the data from
 of size
 .I len
 bytes with send modifier flags
-.IR flags
+.I flags
 and zerocopy modifier flags
 .IR zc_flags .
 
-This function prepares an async zerocopy
+The 
+.BR io_uring_prep_send_zc_fixed (3)
+works just like
+.BR io_uring_prep_send_zc (3)
+except it requires the use of buffers that have been registered with 
+.BR io_uring_register_buffers (3).
+The
+.I buf
+and
+.I len
+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.
+
+Note that using
+.B IOSQE_IO_LINK
+with this request type requires the setting of
+.B MSG_WAITALL
+in the
+.I flags
+argument, as a short send isn't considered an error condition without
+that being set.
+
+These functions prepare an async zerocopy
 .BR send (2)
 request. See that man page for details. For details on the zerocopy nature
 of it, see

data/vendor/liburing/man/io_uring_prep_send_zc_fixed.3

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

data/vendor/liburing/man/io_uring_prep_sendmsg.3

@@ -15,6 +15,11 @@ io_uring_prep_sendmsg \- prepare a sendmsg request
 .BI "                           int " fd ","
 .BI "                           const struct msghdr *" msg ","
 .BI "                           unsigned " flags ");"
+.PP
+.BI "void io_uring_prep_sendmsg_zc(struct io_uring_sqe *" sqe ","
+.BI "                              int " fd ","
+.BI "                              const struct msghdr *" msg ","
+.BI "                              unsigned " flags ");"
 .fi
 .SH DESCRIPTION
 .PP
@@ -32,6 +37,21 @@ defined flags in the
 .I flags
 argument.
 
+The
+.BR io_uring_prep_sendmsg_zc (3)
+accepts the same parameters as 
+.BR io_uring_prep_sendmsg (3)
+but prepares a zerocopy sendmsg request.
+
+Note that using
+.B IOSQE_IO_LINK
+with this request type requires the setting of
+.B MSG_WAITALL
+in the
+.I flags
+argument, as a short send isn't considered an error condition without
+that being set.
+
 This function prepares an async
 .BR sendmsg (2)
 request. See that man page for details.

data/vendor/liburing/man/io_uring_prep_sendmsg_zc.3

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