polyphony 0.94 → 0.95

data/vendor/liburing/man/io_uring_prep_tee.3

@@ -0,0 +1,74 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_tee 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_tee \- prepare a tee request
+.SH SYNOPSIS
+.nf
+.B #include <fcntl.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_tee(struct io_uring_sqe *" sqe ","
+.BI "                       int " fd_in ","
+.BI "                       int " fd_out ","
+.BI "                       unsigned int " nbytes ","
+.BI "                       unsigned int " splice_flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_tee (3)
+function prepares a tee request. The submission queue entry
+.I sqe
+is setup to use as input the file descriptor
+.I fd_in
+and as output the file descriptor
+.I fd_out
+duplicating
+.I nbytes
+bytes worth of data.
+.I splice_flags
+are modifier flags for the operation. See
+.BR tee (2)
+for the generic splice flags.
+
+If the
+.I fd_out
+descriptor,
+.B IOSQE_FIXED_FILE
+can be set in the SQE to indicate that. For the input file, the io_uring
+specific
+.B SPLICE_F_FD_IN_FIXED
+can be set and
+.I fd_in
+given as a registered file descriptor offset.
+
+This function prepares an async
+.BR tee (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 io_uring_register (2),
+.BR splice (2),
+.BR tee (2)

data/vendor/liburing/man/io_uring_prep_timeout.3

@@ -0,0 +1,95 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_poll_timeout 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_timeoute \- prepare a timeout request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_timeout(struct io_uring_sqe *" sqe ","
+.BI "                           struct __kernel_timespec *" ts ","
+.BI "                           unsigned " count ","
+.BI "                           unsigned " flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_timeout (3)
+function prepares a timeout request. The submission queue entry
+.I sqe
+is setup to arm a timeout specified by
+.I ts
+and with a timeout count of
+.I count
+completion entries. The
+.I flags
+argument holds modifier flags for the request.
+
+This request type can be used as a timeout waking anyone sleeping
+for events on the CQ ring. 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.
+Normally a timeout that triggers would return in a
+.B -ETIME
+CQE
+.I res
+value.
+.PP
+The timeout completion event will trigger if either the specified timeout
+has occurred, or the specified number of events to wait for have been posted
+to the CQ ring.
+
+.SH RETURN VALUE
+None
+.SH ERRORS
+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 clocksources
+where given, or the specified timeout seconds or nanoseconds where < 0.
+.TP
+.B -EFAULT
+io_uring was unable to access the data specified by
+.IR ts .
+.TP
+.B -ECANCELED
+The timeout was canceled by a removal request.
+.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_prep_timeout_remove (3),
+.BR io_uring_prep_timeout_update (3)

data/vendor/liburing/man/io_uring_prep_timeout_remove.3

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

data/vendor/liburing/man/io_uring_prep_timeout_update.3

@@ -0,0 +1,98 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_poll_timeout_update 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_timeoute_update \- prepare a request to update an existing timeout
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_timeout_update(struct io_uring_sqe *" sqe ","
+.BI "                                  struct __kernel_timespec *" ts ","
+.BI "                                  __u64 " user_data ","
+.BI "                                  unsigned " flags ");"
+.PP
+.BI "void io_uring_prep_timeout_remove(struct io_uring_sqe *" sqe ","
+.BI "                                  __u64 " user_data ","
+.BI "                                  unsigned " flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+These functions modify or cancel an existing timeout request. The submission
+queue entry
+.I sqe
+is setup to arm a timeout update or removal specified by
+.I user_data
+and with modifier flags given by
+.IR flags .
+Additionally, the update request includes a
+.I ts
+structure, which contains new timeout information.
+
+For an update request, the
+.I flags
+member may contain a bitmask of the following values:
+.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.
+Normally a timeout that triggers would return in a
+.B -ETIME
+CQE
+.I res
+value.
+.PP
+
+.SH RETURN VALUE
+None
+.SH ERRORS
+These are the errors that are reported in the CQE
+.I res
+field. On success,
+.B 0
+is returned.
+.TP
+.B -ENOENT
+The timeout identified by
+.I user_data
+could not be found. It may be invalid, or triggered before the update or
+removal request was processed.
+.TP
+.B -EALREADY
+The timeout identified by
+.I user_data
+is already firing and cannot be canceled.
+.TP
+.B -EINVAL
+One of the fields set in the SQE was invalid. For example, two clocksources
+where given, or the specified timeout seconds or nanoseconds where < 0.
+.TP
+.B -EFAULT
+io_uring was unable to access the data specified by
+.IR ts .
+.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_prep_timeout (3)

data/vendor/liburing/man/io_uring_prep_unlink.3

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

data/vendor/liburing/man/io_uring_prep_unlinkat.3

@@ -0,0 +1,82 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_unlinkat 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_unlinkat \- prepare an unlinkat request
+.SH SYNOPSIS
+.nf
+.B #include <fcntl.h>
+.B #include <unistd.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_unlinkat(struct io_uring_sqe *" sqe ","
+.BI "                            int " dirfd ","
+.BI "                            const char *" path ","
+.BI "                            int " flags ");"
+.PP
+.BI "void io_uring_prep_unlink(struct io_uring_sqe *" sqe ","
+.BI "                          const char *" path ","
+.BI "                          int " flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_unlinkat (3)
+function prepares an unlinkat request. The submission queue entry
+.I sqe
+is setup to use the directory file descriptor pointed to by
+.I dirfd
+to start an unlinkat operation on the path identified by
+.I path
+and using the flags given in
+.IR flags .
+
+The
+.BR io_uring_prep_unlink (3)
+function prepares an unlink request. The submission queue entry
+.I sqe
+is setup to start an unlinkat operation on the path identified by
+.I path
+relative to the current working directory and using the flags given in
+.IR flags .
+
+These functions prepare an async
+.BR unlinkat (2)
+or
+.BR unlink (2)
+request. 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 unlinkat (2),
+.BR unlink (2)

data/vendor/liburing/man/io_uring_prep_write.3

@@ -4,21 +4,22 @@
 .\"
 .TH io_uring_prep_write 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_prep_write   - prepare I/O write request
-
+io_uring_prep_write \- prepare I/O write request
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
-.PP
-.BI "void io_uring_prep_write(struct io_uring_sqe *sqe,"
-.BI "                         int fd,"
-.BI "                         const void *buf,"
-.BI "                         unsigned nbytes,"
-.BI "                         __u64 offset)"
+.B #include <liburing.h>
 .PP
+.BI "void io_uring_prep_write(struct io_uring_sqe *" sqe ","
+.BI "                         int " fd ","
+.BI "                         const void *" buf ","
+.BI "                         unsigned " nbytes ","
+.BI "                         __u64 " offset ");"
+.fi
 .SH DESCRIPTION
 .PP
-The io_uring_prep_write() prepares an IO write request. The submission queue entry
+The
+.BR io_uring_prep_write (3)
+prepares an IO write request. The submission queue entry
 .I sqe
 is setup to use the file descriptor
 .I fd
@@ -27,24 +28,40 @@ to start writing
 from the buffer
 .I buf
 at the specified
-.I offset.
+.IR offset .
 
 On files that support seeking, if the offset is set to
-.B -1,
+.BR -1 ,
 the write operation commences at the file offset, and the file offset is
 incremented by the number of bytes written. See
 .BR write (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
+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 SEE ALSO
-.BR io_uring_get_sqe (3), io_uring_submit (3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3)

data/vendor/liburing/man/io_uring_prep_write_fixed.3

@@ -4,23 +4,24 @@
 .\"
 .TH io_uring_prep_write 3 "February 13, 2022" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_prep_write_fixed   - prepare I/O write request with registered buffer
-
+io_uring_prep_write_fixed \- prepare I/O write request with registered buffer
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.B #include <liburing.h>
 .PP
-.BI "void io_uring_prep_write_fixed(struct io_uring_sqe *sqe,"
-.BI "                        int fd,"
-.BI "                        const void *buf,"
-.BI "                        unsigned nbytes,"
-.BI "                        __u64 offset,"
-.BI "                        int buf_index)"
-
+.BI "void io_uring_prep_write_fixed(struct io_uring_sqe *" sqe ","
+.BI "                        int " fd ",
+.BI "                        const void *" buf ","
+.BI "                        unsigned " nbytes ","
+.BI "                        __u64 " offset ","
+.BI "                        int " buf_index ");"
+.fi
 .SH DESCRIPTION
 .PP
-The io_uring_prep_write_fixed() prepares an IO write request with a previously
-registered IO buffer. The submission queue entry
+The
+.BR io_uring_prep_write_fixed (3)
+prepares an IO write 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 writing
 from the buffer
 .I buf
 at the specified
-.I offset,
+.I offset
 and with the buffer matching the registered index of
-.I buf_index.
+.IR buf_index .
 
-This work just like
-.B io_uring_prep_write(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_write (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_write (3), io_uring_register_buffers (3)
+.BR io_uring_prep_write (3),
+.BR io_uring_register_buffers (3)

data/vendor/liburing/man/io_uring_prep_writev.3

@@ -4,22 +4,23 @@
 .\"
 .TH io_uring_prep_writev 3 "November 15, 2021" "liburing-2.1" "liburing Manual"
 .SH NAME
-io_uring_prep_writev  - prepare vector I/O write request
-
+io_uring_prep_writev \- prepare vector I/O write request
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
-.PP
-.BI "void io_uring_prep_writev(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_writev(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_writev() prepares a vectored IO write request. The submission
-queue entry
+The
+.BR io_uring_prep_writev (3)
+prepares a vectored IO write request. The submission queue entry
 .I sqe
 is setup to use the file descriptor
 .I fd
@@ -28,24 +29,57 @@ to start writing
 from 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 write operation commences at the file offset, and the file offset is
 incremented by the number of bytes written. See
 .BR write (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
+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_write (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_write (3), io_uring_prep_writev2 (3), io_uring_submit (3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_prep_write (3),
+.BR io_uring_prep_writev2 (3),
+.BR io_uring_submit (3)