polyphony 0.94 → 0.95

data/vendor/liburing/man/io_uring_prep_openat.3

@@ -0,0 +1,117 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_openat 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_openat \- prepare an openat request
+.SH SYNOPSIS
+.nf
+.B #include <sys/types.h>
+.B #include <sys/stat.h>
+.B #include <fcntl.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_openat(struct io_uring_sqe *" sqe ","
+.BI "                          int " dfd ","
+.BI "                          const char *" path ","
+.BI "                          int " flags ","
+.BI "                          mode_t " mode ");"
+.PP
+.BI "void io_uring_prep_openat_direct(struct io_uring_sqe *" sqe ","
+.BI "                                 int " dfd ","
+.BI "                                 const char *" path ","
+.BI "                                 int " flags ","
+.BI "                                 mode_t " mode ","
+.BI "                                 unsigned " file_index ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_openat (3)
+function prepares an openat request. The submission queue entry
+.I sqe
+is setup to use the directory file descriptor
+.I dfd
+to start opening a file described by
+.I path
+and using the open flags in
+.I flags
+and using the file mode bits specified in
+.IR mode .
+
+For a direct descriptor open request, the offset is specified by the
+.I file_index
+argument. 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. To do so,
+.B IOSQE_FIXED_FILE
+must be set in the SQE
+.I flags
+member, and the SQE
+.I fd
+field should use the direct descriptor value rather than the regular file
+descriptor. Direct descriptors are managed like registered files.
+
+If the direct variant is used, the application must first have registered
+a file table using
+.BR io_uring_register_files (3)
+of the appropriate size. Once registered, a direct accept request may use any
+entry in that table, as long as it is within the size of the registered table.
+If a specified entry already contains a file, the file will first be removed
+from the table and closed. It's consistent with the behavior of updating an
+existing file with
+.BR io_uring_register_files_update (3).
+Note that old kernels don't check the SQE
+.I file_index
+field, which is not a problem for liburing helpers, but users of the raw
+io_uring interface need to zero SQEs to avoid unexpected behavior.
+
+If
+.B IORING_FILE_INDEX_ALLOC
+is used as the
+.I file_index
+for a direct open, then io_uring will allocate a free direct descriptor in
+the existing table. The allocated descriptor is returned in the CQE
+.I res
+field just like it would be for a non-direct open request. If no more entries
+are available in the direct descriptor table,
+.B -ENFILE
+is returned instead.
+
+These functions prepare an async
+.BR openat (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 io_uring_register (2),
+.BR openat (2)

data/vendor/liburing/man/io_uring_prep_openat2.3

@@ -0,0 +1,117 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_openat2 3 "March 13, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_openat2 \- prepare an openat2 request
+.SH SYNOPSIS
+.nf
+.B #include <sys/types.h>
+.B #include <sys/stat.h>
+.B #include <fcntl.h>
+.B #include <linux/openat2.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_openat2(struct io_uring_sqe *" sqe ","
+.BI "                           int " dfd ","
+.BI "                           const char *" path ","
+.BI "                           int " flags ","
+.BI "                           struct open_how *" how ");"
+.PP
+.BI "void io_uring_prep_openat2_direct(struct io_uring_sqe *" sqe ","
+.BI "                                  int " dfd ","
+.BI "                                  const char *" path ","
+.BI "                                  int " flags ","
+.BI "                                  struct open_how *" how ","
+.BI "                                  unsigned " file_index ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_openat2 (3)
+function prepares an openat2 request. The submission queue entry
+.I sqe
+is setup to use the directory file descriptor
+.I dfd
+to start opening a file described by
+.I path
+and using the open flags in
+.I flags
+and using the instructions on how to open the file given in
+.IR how .
+
+For a direct descriptor open request, the offset is specified by the
+.I file_index
+argument. 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. To do so,
+.B IOSQE_FIXED_FILE
+must be set in the SQE
+.I flags
+member, and the SQE
+.I fd
+field should use the direct descriptor value rather than the regular file
+descriptor. Direct descriptors are managed like registered files.
+
+If the direct variant is used, the application must first have registered
+a file table using
+.BR io_uring_register_files (3)
+of the appropriate size. Once registered, a direct accept request may use any
+entry in that table, as long as it is within the size of the registered table.
+If a specified entry already contains a file, the file will first be removed
+from the table and closed. It's consistent with the behavior of updating an
+existing file with
+.BR io_uring_register_files_update (3).
+Note that old kernels don't check the SQE
+.I file_index
+field, which is not a problem for liburing helpers, but users of the raw
+io_uring interface need to zero SQEs to avoid unexpected behavior.
+If
+.B IORING_FILE_INDEX_ALLOC
+is used as the
+.I file_index
+for a direct open, then io_uring will allocate a free direct descriptor in
+the existing table. The allocated descriptor is returned in the CQE
+.I res
+field just like it would be for a non-direct open request. If no more entries
+are available in the direct descriptor table,
+.B -ENFILE
+is returned instead.
+
+These functions prepare an async
+.BR openat2 (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 io_uring_register (2),
+.BR openat2 (2)

data/vendor/liburing/man/io_uring_prep_openat2_direct.3

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

data/vendor/liburing/man/io_uring_prep_openat_direct.3

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

data/vendor/liburing/man/io_uring_prep_poll_add.3

@@ -0,0 +1,72 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_poll_add 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_poll_add \- prepare a poll request
+.SH SYNOPSIS
+.nf
+.B #include <poll.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_poll_add(struct io_uring_sqe *" sqe ","
+.BI "                            int " fd ","
+.BI "                            unsigned " poll_mask ");"
+.PP
+.BI "void io_uring_prep_poll_multishot(struct io_uring_sqe *" sqe ","
+.BI "                                  int " fd ","
+.BI "                                  unsigned " poll_mask ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_poll_add (3)
+function prepares a poll request. The submission queue entry
+.I sqe
+is setup to use the file descriptor
+.I fd
+that should get polled, with the events desired specified in the
+.I poll_mask
+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)
+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
+.B IORING_CQE_F_MORE
+set in the CQE
+.I flags
+member, indicating that the application should expect more completions from
+this request. If the multishot poll request gets terminated or experiences
+an error, this flag will not be set in the CQE. If this happens, the application
+should not expect further CQEs from the original request and must reissue a
+new one if it still wishes to get notifications on this file descriptor.
+
+.SH RETURN VALUE
+None
+.SH ERRORS
+The CQE
+.I res
+field will contain the result of the operation, which is a bitmask of the
+events notified. See the
+.BR poll (2)
+man page for details. 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 poll (2),
+.BR epoll_ctl (3)

data/vendor/liburing/man/io_uring_prep_poll_multishot.3

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

data/vendor/liburing/man/io_uring_prep_poll_remove.3

@@ -0,0 +1,55 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_poll_remove 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_poll_remove \- prepare a poll deletion request
+.SH SYNOPSIS
+.nf
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_poll_remove(struct io_uring_sqe *" sqe ","
+.BI "                               __u64 " user_data ");"
+.BI "
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_poll_remove (3)
+function prepares a poll removal request. The submission queue entry
+.I sqe
+is setup to remove a poll request identified by
+.I user_data
+
+Works like
+.BR io_uring_prep_cancel (3)
+except only looks for poll requests. Apart from that, behavior is identical.
+See that man page for specific details.
+
+.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 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 SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
+.BR io_uring_prep_cancel (3)

data/vendor/liburing/man/io_uring_prep_poll_update.3

@@ -0,0 +1,89 @@
+.\" Copyright (C) 2022 Jens Axboe <axboe@kernel.dk>
+.\"
+.\" SPDX-License-Identifier: LGPL-2.0-or-later
+.\"
+.TH io_uring_prep_poll_update 3 "March 12, 2022" "liburing-2.2" "liburing Manual"
+.SH NAME
+io_uring_prep_poll_update \- update an existing poll request
+.SH SYNOPSIS
+.nf
+.B #include <poll.h>
+.B #include <liburing.h>
+.PP
+.BI "void io_uring_prep_poll_update(struct io_uring_sqe *" sqe ","
+.BI "                               __u64 " old_user_data ","
+.BI "                               __u64 " new_user_data ","
+.BI "                               unsigned " poll_mask ","
+.BI "                               unsigned " flags ");"
+.fi
+.SH DESCRIPTION
+.PP
+The
+.BR io_uring_prep_poll_update (3)
+function prepares a poll update request. The submission queue entry
+.I sqe
+is setup to update a poll request identified by
+.IR old_user_data ,
+replacing it with the
+.I new_user_data
+information. The
+.I poll_mask
+arguments contains the new mask to use for the poll request, and
+.I flags
+argument contains modifier flags telling io_uring what fields to update.
+
+The
+.I flags
+modifier flags is a bitmask and may contain and OR'ed mask of:
+.TP
+.B IORING_POLL_UPDATE_EVENTS
+If set, the poll update request will replace the existing events being waited
+for with the ones specified in the
+.I poll_mask
+argument to the function.
+.TP
+.B IORING_POLL_UPDATE_USER_DATA
+If set, the poll update request will update the existing user_data of the
+request with the value passed in as the
+.I new_user_data
+argument.
+.TP
+.B IORING_POLL_ADD_MULTI
+If set, this will change the poll request from a singleshot to a multishot
+request. This must be used along with
+.B IORING_POLL_UPDATE_EVENTS
+as the event field must be updated to enable multishot.
+
+.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 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.
+.TP
+.B -ECANCELED
+.B IORING_POLL_UPDATE_EVENTS
+was set and an error occurred re-arming the poll request with the new mask.
+The original poll request is terminated if this happens, and that termination
+CQE will contain the reason for the error re-arming.
+.SH SEE ALSO
+.BR io_uring_get_sqe (3),
+.BR io_uring_submit (3),
+.BR io_uring_prep_poll_add (3),
+.BR io_uring_prep_poll_multishot (3)

data/vendor/liburing/man/io_uring_prep_provide_buffers.3

@@ -0,0 +1,131 @@
+.\" 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 len
+number of 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.
+
+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 the number of successfully provided 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 -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 -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
+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

@@ -4,21 +4,22 @@
 .\"
 .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
-
+io_uring_prep_read \- prepare I/O read request
 .SH SYNOPSIS
 .nf
-.BR "#include <liburing.h>"
+.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)"
-
+.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 io_uring_prep_read() prepares an IO read request. The submission queue entry
+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
@@ -27,10 +28,10 @@ to start reading
 into 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 read operation commences at the file offset, and the file offset is
 incremented by the number of bytes read. See
 .BR read (2)
@@ -39,12 +40,30 @@ 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 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), io_uring_prep_readv (3), io_uring_prep_readv2 (3), io_uring_submit(3)
+.BR io_uring_get_sqe (3),
+.BR io_uring_prep_readv (3),
+.BR io_uring_prep_readv2 (3),
+.BR io_uring_submit (3)