cvs commit: src/lib/libc/sys aio_return.2

[Ruslan Ermilov]

Hi Tom,

On Sat, Oct 07, 2006 at 05:34:51AM +0000, Tom Rhodes wrote:
> trhodes     2006-10-07 05:34:51 UTC
> 
>   FreeBSD src repository
> 
>   Modified files:
>     lib/libc/sys         aio_return.2 
>   Log:
>   Fix ambiguity in description.  Note that the aio_return() system call should
>   only be called once after failure or completion of an AIO request.  Bump doc
>   date while I'm here.
>   
>   Noticed by:     Samy Al Bahra
>   
>   Revision  Changes    Path
>   1.18      +9 -5      src/lib/libc/sys/aio_return.2
> 
To me, what's now is more confusing than what it was, see below.

: The
: .Fn aio_return
: system call
: should only be called once, to obtain the final status of an asynchronous
: I/O operation once
: .Xr aio_error 2
: returns something other than
: .Er EINPROGRESS .

What was there was technically correct and unambiguous: once the
request has completed (which can be determined by aio_error()
returning !EINPROGRESS), either successfully or unsuccessfully,
the aio_return() may be called, only once, to return a status
of an operation (return value and errno if return value == -1).

Now,

: The
: .Fn aio_return
: system call
: should only be called once, to obtain the final status of an asynchronous
: I/O operation.
: If the error status of the request is
: .Er EINPROGRESS ,
: an undefined value is returned.
: The
: .Fn aio_return
: function should only be called on completion or failure of an
: AIO request.

it is more confusing.  You removed the description of how you
can determine when it's safe to call aio_return() (when the
operation has completed):

If an operation is still in progress, and you call aio_return(),
the results are undefined, both for an operation and this function.
Both POSIX standard and our manpage (both old and new versions)
say that calling it again is prohibited.  So before calling
aio_return() you need to make sure that the call has completed.

"If the error status of the request is EINPROGRESS, an undefined
value is returned."  This is very confusing while correct for a
standard.

I think this is a deficiency in the standard; I'd expect that
for in-progress operations, aio_return() returned -1 and set
errno == EINPROGRESS, and allowed to be called again.


Cheers,
-- 
Ruslan Ermilov
ru at FreeBSD.org
FreeBSD committer
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://lists.freebsd.org/pipermail/cvs-src/attachments/20061007/0179a0ce/attachment.pgp