Re: [PATCH liburing 3/3] man/io_uring_enter.2: add EACCES and EBADFD errors

[Jens Axboe <axboe@kernel.dk>]

On 9/14/20 2:05 AM, Stefano Garzarella wrote:
> On Fri, Sep 11, 2020 at 09:36:02AM -0600, Jens Axboe wrote:
>> On 9/11/20 7:34 AM, Stefano Garzarella wrote:
>>> These new errors are added with the restriction series recently
>>> merged in io_uring (Linux 5.10).
>>>
>>> Signed-off-by: Stefano Garzarella <sgarzare@redhat.com>
>>> ---
>>>  man/io_uring_enter.2 | 18 ++++++++++++++++++
>>>  1 file changed, 18 insertions(+)
>>>
>>> diff --git a/man/io_uring_enter.2 b/man/io_uring_enter.2
>>> index 5443d5f..4773dfd 100644
>>> --- a/man/io_uring_enter.2
>>> +++ b/man/io_uring_enter.2
>>> @@ -842,6 +842,16 @@ is set appropriately.
>>>  .PP
>>>  .SH ERRORS
>>>  .TP
>>> +.B EACCES
>>> +The
>>> +.I flags
>>> +field or
>>> +.I opcode
>>> +in a submission queue entry is not allowed due to registered restrictions.
>>> +See
>>> +.BR io_uring_register (2)
>>> +for details on how restrictions work.
>>> +.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
>>> @@ -861,6 +871,14 @@ field in the submission queue entry is invalid, or the
>>>  flag was set in the submission queue entry, but no files were registered
>>>  with the io_uring instance.
>>>  .TP
>>> +.B EBADFD
>>> +The
>>> +.I fd
>>> +field in the submission queue entry is valid, but the io_uring ring is not
>>> +in the right state (enabled). See
>>> +.BR io_uring_register (2)
>>> +for details on how to enable the ring.
>>> +.TP
>>
>> I actually think some of this needs general updating. io_uring_enter()
>> will not return an error on behalf of an sqe, it'll only return an error
>> if one happened outside the context of a specific sqe. Any error
>> specific to an sqe will generate a cqe with the result.
> 
> Mmm, right.
> 
> For example in this case, EACCES is returned by a cqe and EBADFD is
> returned by io_uring_enter().
> 
> Should we create 2 error sections?

Yep, I think we should. One that describes that io_uring_enter() would
return in terms of errors, and one that describes cqe->res returns.

Are you up for this? Would be a great change, making it a lot more
accurate.

-- 
Jens Axboe