polyphony 0.94 → 0.95

data/vendor/liburing/man/io_uring_prep_read_fixed.3

@@ -4,23 +4,24 @@
 .\"
 .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
-
+io_uring_prep_read_fixed \- prepare I/O read request with registered buffer
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.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)"
-
+.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 io_uring_prep_read_fixed() prepares an IO read request with a previously
-registered IO buffer. The submission queue entry
+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
@@ -29,19 +30,20 @@ to start reading
 into the buffer
 .I buf
 at the specified
-.I offset,
+.IR offset ,
 and with the buffer matching the registered index of
-.I buf_index.
+.IR buf_index .
 
-This work just like
-.B io_uring_prep_read(3)
-except it requires the user of buffers that have been registered with
-.B io_uring_register_buffers(3). The
+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 specificed by
-.I buf_index.
+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.
 
@@ -50,5 +52,21 @@ 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), io_uring_register_buffers (3)
+.BR io_uring_prep_read (3),
+.BR io_uring_register_buffers (3)

data/vendor/liburing/man/io_uring_prep_readv.3

@@ -4,22 +4,23 @@
 .\"
 .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
-.fi
+io_uring_prep_readv \- prepare vector I/O read request
 .SH SYNOPSIS
 .nf
-.BR "#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)"
+.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 io_uring_prep_readv() prepares a vectored IO read request. The submission
-queue entry
+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
@@ -28,10 +29,10 @@ to start reading
 into the
 .I iovecs
 array at the specified
-.I offset.
+.IR offset .
 
 On files that support seeking, if the offset is set to
-.B -1,
+.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)
@@ -40,12 +41,45 @@ 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 is ignored.
+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
 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 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), io_uring_prep_read (3), io_uring_prep_readv2 (3), io_uring_submit (3)
+.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

@@ -4,25 +4,24 @@
 .\"
 .TH io_uring_prep_readv2 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-.fi
-io_uring_prep_readv2 - prepare vector I/O read request with flags
-
+io_uring_prep_readv2 \- prepare vector I/O read request with flags
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.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)"
+.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
-.PP
 .SH DESCRIPTION
 .PP
-The io_uring_prep_readv2() prepares a vectored IO read request. The submission
-queue entry
+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
@@ -31,7 +30,7 @@ to start reading
 into the
 .I iovecs
 array at the specified
-.I offset.
+.IR offset .
 The behavior of the function can be controlled with the
 .I flags
 parameter.
@@ -59,7 +58,7 @@ per-IO O_APPEND
 
 .P
 On files that support seeking, if the offset is set to
-.B -1,
+.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)
@@ -68,12 +67,45 @@ 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 is ignored.
+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
 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 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), io_uring_prep_read (3), io_uring_prep_readv (3), io_uring_submit (3)
+.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

@@ -0,0 +1,105 @@
+.\" 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 buffer destination
+.I buf
+of size
+.I size
+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 it's 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

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

data/vendor/liburing/man/io_uring_prep_recvmsg.3

@@ -0,0 +1,124 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_recvmsg 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_recvmsg \- prepare a recvmsg request
+.SH SYNOPSIS
+.nf
+.B #include <sys/types.h>
+.B #include <sys/socket.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_recvmsg(struct io_uring_sqe *" sqe ","
+.BI "                           int " fd ","
+.BI "                           struct msghdr *" msg ","
+.BI "                           unsigned " flags ");"
+.PP
+.BI "void io_uring_prep_recvmsg_multishot(struct io_uring_sqe *" sqe ","
+.BI "                                     int " fd ","
+.BI "                                     struct msghdr *" msg ","
+.BI "                                     unsigned " flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_recvmsg (3)
+function prepares a recvmsg request. The submission queue entry
+.I sqe
+is setup to use the file descriptor
+.I fd
+to start receiving the data indicated by
+.I msg
+with the
+.BR recvmsg (2)
+defined flags in the
+.I flags
+argument.
+
+This function prepares an async
+.BR recvmsg (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 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.
+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
+.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)
+for more information on accessing the data.
+
+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 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 recvmsg (2)

data/vendor/liburing/man/io_uring_prep_recvmsg_multishot.3

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

data/vendor/liburing/man/io_uring_prep_remove_buffers.3

@@ -0,0 +1,52 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_remove_buffers 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_remove_buffers \- prepare a remove buffers request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_remove_buffers(struct io_uring_sqe *" sqe ","
+.BI "                                   int " nr ","
+.BI "                                   int " bgid ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_remove_buffers (3)
+function prepares a request for removing previously supplied buffers. The
+submission queue entry
+.I sqe
+is setup to remove
+.I nr
+number of buffers from the buffer group ID indicated by
+.IR bgid .
+
+.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 the number of successfully removed buffers. On error,
+the following errors can occur.
+.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 -ENOENT
+No buffers exist at the specified
+.I bgid
+buffer group ID.
+.SH SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
+.BR io_uring_register (2),
+.BR io_uring_prep_provide_buffers (3)

data/vendor/liburing/man/io_uring_prep_rename.3

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

data/vendor/liburing/man/io_uring_prep_renameat.3

@@ -0,0 +1,96 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_renameat 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_renameat \- prepare a renameat request
+.SH SYNOPSIS
+.nf
+.B #include <fcntl.h>
+.B #include <stdio.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_renameat(struct io_uring_sqe *" sqe ","
+.BI "                            int " olddirfd ","
+.BI "                            const char *" oldpath ","
+.BI "                            int " newdirfd ","
+.BI "                            const char *" newpath ","
+.BI "                            unsigned int " flags ");"
+.PP
+.BI "void io_uring_prep_rename(struct io_uring_sqe *" sqe ","
+.BI "                          const char *" oldpath ","
+.BI "                          const char *" newpath ","
+.BI "                          unsigned int " flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_renameat (3)
+function prepares a renameat request. The submission queue entry
+.I sqe
+is setup to use the old directory file descriptor pointed to by
+.I olddirfd
+and old path pointed to by
+.I oldpath
+with the new directory file descriptor pointed to by
+.I newdirfd
+and the new path pointed to by
+.I newpath
+and using the specified flags in
+.IR flags .
+
+The
+.BR io_uring_prep_rename (3)
+function prepares a rename request. The submission queue entry
+.I sqe
+is setup to use the old path pointed to by
+.I oldpath
+with the new path pointed to by
+.IR newpath ,
+both relative to the current working directory and using the specified flags in
+.IR flags .
+
+These functions prepare an async
+.BR renameat2 (2)
+or
+.BR rename (2)
+request. If
+.I flags
+is zero, then this call is similar to the
+.BR renameat (2)
+system call. See those man pages 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 renameat (2),
+.BR renameat2 (2),
+.BR rename (2)