Describe the unconventional error return provided by the wrapper

function in libaio (and contrast with behavior if the system call
is invoked via syscall(2)).

man2/io_cancel.2

@@ -20,7 +20,7 @@
 .\" .el .ne 3
 .\" .IP "\\$1" \\$2
 .\" ..
-.TH IO_CANCEL 2 2003-02-21 "Linux" "Linux Programmer's Manual"
+.TH IO_CANCEL 2 2008-06-18 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_cancel \- cancel an outstanding asynchronous I/O operation
 .SH "SYNOPSIS"
@@ -49,10 +49,10 @@ If the AIO context is found, the event will be canceled and then copied
 into the memory pointed to by \fIresult\fP without being placed
 into the completion queue.
 .SH "RETURN VALUE"
-.PP
+On success,
 .BR io_cancel ()
-returns 0 on success;
-on failure, it returns one of the errors listed under ERRORS.
+returns 0.
+For the failure return, see NOTES.
 .SH "ERRORS"
 .TP
 .B EAGAIN
@@ -75,6 +75,22 @@ The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
 .BR io_cancel ()
 is Linux-specific and should not be used
 in programs that are intended to be portable.
+.SH NOTES
+Glibc does not provide a wrapper function for this system call.
+
+The wrapper provided in
+.I libaio
+for
+.BR io_cancel ()
+does not follow the usual C library conventions for indicating error:
+on error it returns a negated error number
+(the negative of one of the values listed in ERRORS).
+If the system call is invoked via
+.BR syscall (2),
+then the return value follows the usual conventions for
+indicating an error: \-1, with
+.I errno
+set to a (positive) value that indicates the error.
 .SH "SEE ALSO"
 .BR io_destroy (2),
 .BR io_getevents (2),

man2/io_destroy.2

@@ -20,7 +20,7 @@
 .\" .el .ne 3
 .\" .IP "\\$1" \\$2
 .\" ..
-.TH IO_DESTROY 2 2003-02-21 "Linux" "Linux Programmer's Manual"
+.TH IO_DESTROY 2 2008-06-18 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_destroy \- destroy an asynchronous I/O context
 .SH "SYNOPSIS"
@@ -46,10 +46,10 @@ I/O contexts and then destroys it.
 can also cancel any outstanding asynchronous I/O
 actions on \fIctx\fP and block on completion.
 .SH "RETURN VALUE"
-.PP
+On success,
 .BR io_destroy ()
-returns 0 on success;
-on failure, it returns one of the errors listed under ERRORS.
+returns 0.
+For the failure return, see NOTES.
 .SH "ERRORS"
 .TP
 .B EFAULT
@@ -69,6 +69,22 @@ The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
 .BR io_destroy ()
 is Linux-specific and should not be used in programs
 that are intended to be portable.
+.SH NOTES
+Glibc does not provide a wrapper function for this system call.
+
+The wrapper provided in
+.I libaio
+for
+.BR io_destroy ()
+does not follow the usual C library conventions for indicating error:
+on error it returns a negated error number
+(the negative of one of the values listed in ERRORS).
+If the system call is invoked via
+.BR syscall (2),
+then the return value follows the usual conventions for
+indicating an error: \-1, with
+.I errno
+set to a (positive) value that indicates the error.
 .SH "SEE ALSO"
 .BR io_cancel (2),
 .BR io_getevents (2),

man2/io_getevents.2

@@ -20,7 +20,7 @@
 .\" .el .ne 3
 .\" .IP "\\$1" \\$2
 .\" ..
-.TH IO_GETEVENTS 2 2003-02-21 "Linux" "Linux Programmer's Manual"
+.TH IO_GETEVENTS 2 2008-06-18 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_getevents \- read asynchronous I/O events from the completion queue
 .SH "SYNOPSIS"
@@ -52,12 +52,11 @@ have been seen.
 Note that \fItimeout\fP is relative and will be updated if not NULL
 and the operation blocks.
 .SH "RETURN VALUE"
-.PP
 On success,
 .BR io_getevents ()
 returns the number of events read: 0 if no events are
-available, or less than \fImin_nr\fP if the \fItimeout\fP has elapsed;
-on failure, it returns one of the errors listed under ERRORS.
+available, or less than \fImin_nr\fP if the \fItimeout\fP has elapsed.
+For the failure return, see NOTES.
 .SH "ERRORS"
 .TP
 .B EFAULT
@@ -79,6 +78,22 @@ The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
 .BR io_getevents ()
 is Linux-specific and should not be used in
 programs that are intended to be portable.
+.SH NOTES
+Glibc does not provide a wrapper function for this system call.
+
+The wrapper provided in
+.I libaio
+for
+.BR io_getevents ()
+does not follow the usual C library conventions for indicating error:
+on error it returns a negated error number
+(the negative of one of the values listed in ERRORS).
+If the system call is invoked via
+.BR syscall (2),
+then the return value follows the usual conventions for
+indicating an error: \-1, with
+.I errno
+set to a (positive) value that indicates the error.
 .SH "SEE ALSO"
 .PP
 .BR io_cancel (2),

man2/io_setup.2

@@ -20,7 +20,7 @@
 .\" .el .ne 3
 .\" .IP "\\$1" \\$2
 .\" ..
-.TH IO_SETUP 2 2003-02-21 "Linux" "Linux Programmer's Manual"
+.TH IO_SETUP 2 2008-06-18 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_setup \- create an asynchronous I/O context
 .SH "SYNOPSIS"
@@ -47,6 +47,10 @@ be initialized to 0 prior to the call.
 On successful creation of the AIO context, \fI*ctxp\fP is filled in
 with the resulting handle.
 .SH "RETURN VALUE"
+On success,
+.BR io_setup ()
+returns 0.
+For the failure return, see NOTES.
 .PP
 .BR io_setup ()
 returns 0 on success;
@@ -77,6 +81,22 @@ The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
 .BR io_setup ()
 is Linux-specific and should not be used in programs
 that are intended to be portable.
+.SH NOTES
+Glibc does not provide a wrapper function for this system call.
+
+The wrapper provided in
+.I libaio
+for
+.BR io_setup ()
+does not follow the usual C library conventions for indicating error:
+on error it returns a negated error number
+(the negative of one of the values listed in ERRORS).
+If the system call is invoked via
+.BR syscall (2),
+then the return value follows the usual conventions for
+indicating an error: \-1, with
+.I errno
+set to a (positive) value that indicates the error.
 .SH "SEE ALSO"
 .BR io_cancel (2),
 .BR io_destroy (2),

man2/io_submit.2

@@ -20,7 +20,7 @@
 .\" .el .ne 3
 .\" .IP "\\$1" \\$2
 .\" ..
-.TH IO_SUBMIT 2 2003-02-21 "Linux" "Linux Programmer's Manual"
+.TH IO_SUBMIT 2 2008-06-18 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_submit \- submit asynchronous I/O blocks for processing
 .SH "SYNOPSIS"
@@ -46,12 +46,11 @@ the AIO context \fIctx_id\fP.
 \fIiocbpp\fP should be an array of \fInr\fP AIO request blocks,
 which will be submitted to context \fIctx_id\fP.
 .SH "RETURN VALUE"
-.PP
 On success,
 .BR io_submit ()
 returns the number of \fIiocb\fPs submitted (which may be
-0 if \fInr\fP is zero);
-on failure, it returns one of the errors listed under ERRORS.
+0 if \fInr\fP is zero).
+For the failure return, see NOTES.
 .SH "ERRORS"
 .TP
 .B EAGAIN
@@ -81,6 +80,22 @@ The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
 .BR io_submit ()
 is Linux-specific and should not be used in
 programs that are intended to be portable.
+.SH NOTES
+Glibc does not provide a wrapper function for this system call.
+
+The wrapper provided in
+.I libaio
+for
+.BR io_submit ()
+does not follow the usual C library conventions for indicating error:
+on error it returns a negated error number
+(the negative of one of the values listed in ERRORS).
+If the system call is invoked via
+.BR syscall (2),
+then the return value follows the usual conventions for
+indicating an error: \-1, with
+.I errno
+set to a (positive) value that indicates the error.
 .SH "SEE ALSO"
 .BR io_cancel (2),
 .BR io_destroy (2),