[PATCH liburing] man/io_uring_enter.2: split ERRORS section in two sections

[PATCH liburing] man/io_uring_enter.2: split ERRORS section in two sections

[Stefano Garzarella]

This patch creates a new 'CQE ERRORS' section to better divide the
errors returned by the io_uring_enter() system call from those
returned by the CQE.

Signed-off-by: Stefano Garzarella <sgarzare@redhat.com>
---
Hi Jens,
I gave a first pass. I'm sharing it with you for a first comment. :-)

The ERRORS section should now contain all the errors returned from the
system call.
In CQE ERRORS I've added something new, but I need to better check all
the possibilities. which are not few :-(

Thanks,
Stefano
---
 man/io_uring_enter.2 | 85 ++++++++++++++++++++++++++++++++------------
 1 file changed, 63 insertions(+), 22 deletions(-)

diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
index 6f580a3..8b87e23 100644
--- a/man/io_uring_enter.2
+++ b/man/io_uring_enter.2
@@ -824,7 +824,10 @@ will need to access upon completion of this particular I/O.  The
 .I flags
 is reserved for future use.
 .I res
-is the operation-specific result.
+is the operation-specific result, but io_uring-specific errors
+(e.g. flags or opcode invalid) are returned through this field.
+They are described in section
+.B CQE ERRORS.
 .PP
 For read and write opcodes, the
 return values match those documented in the
@@ -840,9 +843,12 @@ description of the opcodes above.
 returns the number of I/Os successfully consumed.  This can be zero
 if
 .I to_submit
-was zero or if the submission queue was empty. The errors below that refer to
-an error in a submission queue entry will be returned though a completion queue
-entry, rather than through the system call itself.
+was zero or if the submission queue was empty.
+
+The errors related to a submission queue entry will be returned through a
+completion queue entry (see section
+.B CQE ERRORS),
+rather than through the system call itself.
 
 Errors that occur not on behalf of a submission queue entry are returned via the
 system call directly. On such an error, -1 is returned and
@@ -850,18 +856,54 @@ system call directly. On such an error, -1 is returned and
 is set appropriately.
 .PP
 .SH ERRORS
+These are the errors returned by
+.BR io_uring_enter ()
+system call.
 .TP
 .B EAGAIN
 The kernel was unable to allocate memory for the request, or otherwise ran out
 of resources to handle it. The application should wait for some completions and
 try again.
 .TP
+.B EBADF
+.I fd
+is not a valid file descriptor.
+.TP
 .B EBUSY
 The application is attempting to overcommit the number of requests it can have
 pending. The application should wait for some completions and try again. May
 occur if the application tries to queue more requests than we have room for in
 the CQ ring.
 .TP
+.B EINVAL
+Some bits in the
+.I flags
+argument are invalid.
+.TP
+.B EFAULT
+An invalid user space address was specified for the
+.I sig
+argument.
+.TP
+.B ENXIO
+The io_uring instance is in the process of being torn down.
+.TP
+.B EOPNOTSUPP
+.I fd
+does not refer to an io_uring instance.
+.TP
+.B EINTR
+The operation was interrupted by a delivery of a signal before it could
+complete; see
+.BR signal(7).
+Can happen while waiting for events with
+.B IORING_ENTER_GETEVENTS.
+
+.SH CQE ERRORS
+These io_uring-specific errors are returned as a negative value in the
+.I res
+field of the completion queue entry.
+.TP
 .B EBADF
 The
 .I fd
@@ -890,17 +932,22 @@ does not fit within the buffer registered at
 .TP
 .B EINVAL
 The
-.I index
-member of the submission queue entry is invalid.
-.TP
-.B EINVAL
-The
 .I flags
 field or
 .I opcode
 in a submission queue entry is invalid.
 .TP
 .B EINVAL
+The
+.I buf_index
+member of the submission queue entry is invalid.
+.TP
+.B EINVAL
+The
+.I personality
+field in a submission queue entry is invalid.
+.TP
+.B EINVAL
 .B IORING_OP_NOP
 was specified in the submission queue entry, but the io_uring context
 was setup for polling
@@ -964,20 +1011,14 @@ field of the submission queue entry, and the
 .I addr
 field was non-zero.
 .TP
-.B ENXIO
-The io_uring instance is in the process of being torn down.
-.TP
-.B EOPNOTSUPP
-.I fd
-does not refer to an io_uring instance.
-.TP
 .B EOPNOTSUPP
 .I opcode
 is valid, but not supported by this kernel.
 .TP
-.B EINTR
-The operation was interrupted by a delivery of a signal before it could
-complete; see
-.BR signal(7).
-Can happen while waiting for events with
-.B IORING_ENTER_GETEVENTS.
+.B EOPNOTSUPP
+.B IOSQE_BUFFER_SELECT
+was set in the
+.I flags
+field of the submission queue entry, but the
+.I opcode
+doesn't support buffer selection.
-- 
2.26.2

Re: [PATCH liburing] man/io_uring_enter.2: split ERRORS section in two sections

[Jens Axboe]

On 9/18/20 10:14 AM, Stefano Garzarella wrote:
> This patch creates a new 'CQE ERRORS' section to better divide the
> errors returned by the io_uring_enter() system call from those
> returned by the CQE.

Thanks, this is a great start, applied.

-- 
Jens Axboe

Re: [PATCH liburing] man/io_uring_enter.2: split ERRORS section in two sections

[Stefano Garzarella]

On Mon, Sep 28, 2020 at 02:44:42PM -0600, Jens Axboe wrote:
> On 9/18/20 10:14 AM, Stefano Garzarella wrote:
> > This patch creates a new 'CQE ERRORS' section to better divide the
> > errors returned by the io_uring_enter() system call from those
> > returned by the CQE.
> 
> Thanks, this is a great start, applied.
> 

Thanks!

I'll rebase restrictions man pages on top of master, and I'll try to
find new CQE errors ;-)

Stefano