aio_return(3): misleading RETURN VALUE

aio_return(3): misleading RETURN VALUE

[Alexander Holler]

Hello,

I've just typed in the following commit message:

--
The man page was misleading and I must have had a bad moment 
mechanically coding what the man page says without thinking about it.
So I seem to have assumed that aio_return() might return EINVAL which 
can't be the case. In fact the error is returned in errno which isn't 
mentioned by the Linux man page for aio_return.
--

I suggest to use the same wording as in write(2) in the paragraph RETURN 
VALUE:

"On error, -1 is returned, and errno is set appropriately."

I've verified it by looking at the source for aio_return of glibc.

Regards,

Alexander Holler
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: aio_return(3): misleading RETURN VALUE

[Stéphane Aulery]

Hello Alexander,

Le mercredi 18 mars 2015 à 09:03:38, Alexander Holler a écrit :
> 
> I suggest to use the same wording as in write(2) in the paragraph RETURN
> VALUE:
> 
> "On error, -1 is returned, and errno is set appropriately."

Like that ?

    If the asynchronous I/O operation has completed, this function
    returns the value that would have been returned in case of a
    synchronous read(2), write(2), fsync(2) or fdatasync(2), call. On
    error, -1 is returned, and errno is set appropriately.

    If the asynchronous I/O operation has not yet completed, the return
    value and effect of aio_return() are undefined.

I think that's what you meant. What will happen if the asynchronous I/O
operation has not yet completed please ?

Regards,

-- 
Stéphane Aulery
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: aio_return(3): misleading RETURN VALUE

[Alexander Holler]

Am 18.03.2015 um 13:14 schrieb Stéphane Aulery:
> Hello Alexander,
>
> Le mercredi 18 mars 2015 à 09:03:38, Alexander Holler a écrit :
>>
>> I suggest to use the same wording as in write(2) in the paragraph RETURN
>> VALUE:
>>
>> "On error, -1 is returned, and errno is set appropriately."
>
> Like that ?
>
>      If the asynchronous I/O operation has completed, this function
>      returns the value that would have been returned in case of a
>      synchronous read(2), write(2), fsync(2) or fdatasync(2), call. On
>      error, -1 is returned, and errno is set appropriately.
>
>      If the asynchronous I/O operation has not yet completed, the return
>      value and effect of aio_return() are undefined.

Exactly. Thanks a lot if you change that.

> I think that's what you meant. What will happen if the asynchronous I/O
> operation has not yet completed please ?

It is still undefined, but I haven't looked that up in the source of glibc.

The reason is that aio_return() should only be called if the operation 
before has completed, which must be checked with calling aio_error() 
before calling aio_return().

That's how I've understood all that and how it currently seems to work 
in the SW in question I've fixed a problem.

Regards,

Alexander Holler

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] aio_return.3: Specifies the return values for errors

[Stéphane Aulery]

Reported by Alexander Holler <holler-SXC+2es9fhnfWeYVQQPykw@public.gmane.org>

Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
---
 man3/aio_return.3 | 1 +
 1 file changed, 1 insertion(+)

diff --git a/man3/aio_return.3 b/man3/aio_return.3
index 3e6f334..37d735c 100644
--- a/man3/aio_return.3
+++ b/man3/aio_return.3
@@ -55,6 +55,7 @@ the value that would have been returned in case of a synchronous
 or
 .BR fdatasync (2),
 call.
+On error, \-1 is returned, and \fIerrno\fP is set appropriately.
 
 If the asynchronous I/O operation has not yet completed,
 the return value and effect of
-- 
2.1.4

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: aio_return(3): misleading RETURN VALUE

[Stéphane Aulery]

Hello Alexander,

Le mercredi 18 mars 2015 à 08:21:28, Alexander Holler a écrit :
> Am 18.03.2015 um 13:14 schrieb Stéphane Aulery:
> >Le mercredi 18 mars 2015 à 09:03:38, Alexander Holler a écrit :
> >>
> >>I suggest to use the same wording as in write(2) in the paragraph RETURN
> >>VALUE:
> >>
> >>"On error, -1 is returned, and errno is set appropriately."
> >
> >Like that ?
> >
> >     If the asynchronous I/O operation has completed, this function
> >     returns the value that would have been returned in case of a
> >     synchronous read(2), write(2), fsync(2) or fdatasync(2), call. On
> >     error, -1 is returned, and errno is set appropriately.
> >
> >     If the asynchronous I/O operation has not yet completed, the return
> >     value and effect of aio_return() are undefined.
> 
> Exactly. Thanks a lot if you change that.

Patch is pending for review by Michael.

> >I think that's what you meant. What will happen if the asynchronous I/O
> >operation has not yet completed please ?
> 
> It is still undefined, but I haven't looked that up in the source of glibc.
> 
> The reason is that aio_return() should only be called if the operation
> before has completed, which must be checked with calling aio_error() before
> calling aio_return().
> 
> That's how I've understood all that and how it currently seems to work in
> the SW in question I've fixed a problem.

Thank you for yours clarifications.

Regards,

-- 
Stéphane Aulery
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] aio_return.3: Specifies the return values for errors

[Michael Kerrisk (man-pages)]

On 03/18/2015 08:51 PM, Stéphane Aulery wrote:
> Reported by Alexander Holler <holler-SXC+2es9fhnfWeYVQQPykw@public.gmane.org>
> 
> Signed-off-by: Stéphane Aulery <saulery-GANU6spQydw@public.gmane.org>
> ---
>  man3/aio_return.3 | 1 +
>  1 file changed, 1 insertion(+)
> 
> diff --git a/man3/aio_return.3 b/man3/aio_return.3
> index 3e6f334..37d735c 100644
> --- a/man3/aio_return.3
> +++ b/man3/aio_return.3
> @@ -55,6 +55,7 @@ the value that would have been returned in case of a synchronous
>  or
>  .BR fdatasync (2),
>  call.
> +On error, \-1 is returned, and \fIerrno\fP is set appropriately.
>  
>  If the asynchronous I/O operation has not yet completed,
>  the return value and effect of

Hi Stéphane,

Thanks! Patch applied.

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html