io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2: Rewrite to focus...

Rewrite to focus on the system call interface, adding
some notes on the libaio wrapper differences.
See the following mail:
2012-05-07 "aio manuals", linux-man@vger.kernel.org
http://thread.gmane.org/gmane.linux.man/1935/focus=2910

Other minor rewrites.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index cce36c147f2a1faa5f8b53df39bc7b7494b7039b..0faa6b1b5add38bc855c25849e322ab680c3a7c8 100644 (file)
--- a/man2/io_cancel.2
+++ b/man2/io_cancel.2
@@ -2,25 +2,26 @@
 .\" This file is distributed according to the GNU General Public License.
 .\" See the file COPYING in the top level source directory for details.
 .\"
-.TH IO_CANCEL 2 2008-06-18 "Linux" "Linux Programmer's Manual"
+.TH IO_CANCEL 2 2012-05-08 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_cancel \- cancel an outstanding asynchronous I/O operation
 .SH "SYNOPSIS"
 .nf
-.B #include <libaio.h>
-.\"#include <linux/aio.h>
-.sp
+.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
+
 .BI "int io_cancel(aio_context_t " ctx_id ", struct iocb *" iocb ,
 .BI "              struct io_event *" result );
-.sp
-Link with \fI\-laio\fP.
 .fi
 .SH "DESCRIPTION"
 .PP
+The
 .BR io_cancel ()
+system call
 attempts to cancel an asynchronous I/O operation previously submitted with
 .BR io_submit (2).
-\fIctx_id\fP is the AIO context ID of the operation to be canceled.
+The
+.I ctx_id
+argument is the AIO context ID of the operation to be canceled.
 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.
@@ -45,7 +46,7 @@ The AIO context specified by \fIctx_id\fP is invalid.
 is not implemented on this architecture.
 .SH "VERSIONS"
 .PP
-The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
+The asynchronous I/O system calls first appeared in Linux 2.5.
 .SH "CONFORMING TO"
 .PP
 .BR io_cancel ()
@@ -53,12 +54,26 @@ 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.
+You could invoke it using
+.BR syscall (2).
+But instead, you probably want to use the
+.BR io_cancel ()
+wrapper function provided by
+.\" http://git.fedorahosted.org/git/?p=libaio.git
+.IR libaio .
 
-The wrapper provided in
+Note that the
 .I libaio
-for
-.BR io_cancel ()
-does not follow the usual C library conventions for indicating error:
+wrapper function uses a different type
+.RI ( io_context_t )
+.\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
+.\" the system call.
+for the
+.I ctx_id
+argument.
+Note also that the
+.I libaio
+wrapper does not follow the usual C library conventions for indicating errors:
 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
@@ -73,10 +88,5 @@ set to a (positive) value that indicates the error.
 .BR io_setup (2),
 .BR io_submit (2),
 .BR aio (7)
-.\" .SH "NOTES"
-.\"
-.\" .PP
-.\" The asynchronous I/O system calls were written by Benjamin LaHaise.
-.\"
 .\" .SH AUTHOR
 .\" Kent Yoder.

diff --git a/man2/io_destroy.2 b/man2/io_destroy.2
index 1948f151e8b8685b56c0036f0fe40e2707297fd8..5be8afeed51ad6a0ae1c63421f08f63673da4b2e 100644 (file)
--- a/man2/io_destroy.2
+++ b/man2/io_destroy.2
@@ -3,26 +3,26 @@
 .\" See the file COPYING in the top level source directory for details.
 .\"
 .\" ..
-.TH IO_DESTROY 2 2008-06-18 "Linux" "Linux Programmer's Manual"
+.TH IO_DESTROY 2 2012-05-08 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_destroy \- destroy an asynchronous I/O context
 .SH "SYNOPSIS"
 .nf
-.B #include <libaio.h>
-.\" #include <linux/aio.h>
-.sp
-.BI "int io_destroy(aio_context_t " ctx );
-.sp
-Link with \fI\-laio\fP.
+.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
+
+.BI "int io_destroy(aio_context_t " ctx_id );
 .fi
 .SH "DESCRIPTION"
 .PP
+The
 .BR io_destroy ()
-removes the asynchronous I/O context from the list of
+system call
+removes the asynchronous I/O context specified by
+.I ctx_id
+from the list of
 I/O contexts and then destroys it.
-.BR io_destroy ()
-can also cancel any outstanding asynchronous I/O
-actions on \fIctx\fP and block on completion.
+It can also cancel any outstanding asynchronous I/O
+actions on \fIctx_id\fP and block on completion.
 .SH "RETURN VALUE"
 On success,
 .BR io_destroy ()
@@ -34,14 +34,14 @@ For the failure return, see NOTES.
 The context pointed to is invalid.
 .TP
 .B EINVAL
-The AIO context specified by \fIctx\fP is invalid.
+The AIO context specified by \fIctx_id\fP is invalid.
 .TP
 .B ENOSYS
 .BR io_destroy ()
 is not implemented on this architecture.
 .SH "VERSIONS"
 .PP
-The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
+The asynchronous I/O system calls first appeared in Linux 2.5.
 .SH "CONFORMING TO"
 .PP
 .BR io_destroy ()
@@ -49,12 +49,26 @@ 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.
+You could invoke it using
+.BR syscall (2).
+But instead, you probably want to use the
+.BR io_destroy ()
+wrapper function provided by
+.\" http://git.fedorahosted.org/git/?p=libaio.git
+.IR libaio .
 
-The wrapper provided in
+Note that the
 .I libaio
-for
-.BR io_destroy ()
-does not follow the usual C library conventions for indicating error:
+wrapper function uses a different type
+.RI ( io_context_t )
+.\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
+.\" the system call.
+for the
+.I ctx_id
+argument.
+Note also that the
+.I libaio
+wrapper does not follow the usual C library conventions for indicating errors:
 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
@@ -69,10 +83,5 @@ set to a (positive) value that indicates the error.
 .BR io_setup (2),
 .BR io_submit (2),
 .BR aio (7)
-.\" .SH "NOTES"
-.\"
-.\" .PP
-.\" The asynchronous I/O system calls were written by Benjamin LaHaise.
-.\"
 .\" .SH AUTHOR
 .\" Kent Yoder.

diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
index 6c42ce5cffeb947fd0162edfb60b3c0227ce925d..d959045a599a524cad75cbd7ad41e9105c453115 100644 (file)
--- a/man2/io_getevents.2
+++ b/man2/io_getevents.2
@@ -2,28 +2,28 @@
 .\" This file is distributed according to the GNU General Public License.
 .\" See the file COPYING in the top level source directory for details.
 .\"
-.TH IO_GETEVENTS 2 2008-07-04 "Linux" "Linux Programmer's Manual"
+.TH IO_GETEVENTS 2 2012-05-08 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_getevents \- read asynchronous I/O events from the completion queue
 .SH "SYNOPSIS"
 .nf
-.B #include <linux/time.h>
-.B #include <libaio.h>
-.\" #include <linux/aio.h>
+.BR "#include <linux/aio_abi.h>" "         /* Defines needed types */"
+.BR "#include <linux/time.h>" "            /* Defines 'struct timespec' */"
+
 .sp
 .BI "int io_getevents(aio_context_t " ctx_id ", long " min_nr ", long " nr ,
 .BI "                 struct io_event *" events \
 ", struct timespec *" timeout );
-.sp
-Link with \fI\-laio\fP.
 .fi
 .SH "DESCRIPTION"
 .PP
+The
 .BR io_getevents ()
+system call
 attempts to read at least \fImin_nr\fP events and
 up to \fInr\fP events from the completion queue of the AIO context
 specified by \fIctx_id\fP.
-\fItimeout\fP specifies the amount of time to wait for events,
+The \fItimeout\fP argument specifies the amount of time to wait for events,
 where a NULL timeout waits until at least \fImin_nr\fP events
 have been seen.
 Note that \fItimeout\fP is relative and will be updated if not NULL
@@ -53,7 +53,7 @@ Interrupted by a signal handler; see
 is not implemented on this architecture.
 .SH "VERSIONS"
 .PP
-The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
+The asynchronous I/O system calls first appeared in Linux 2.5.
 .SH "CONFORMING TO"
 .PP
 .BR io_getevents ()
@@ -61,12 +61,26 @@ 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.
+You could invoke it using
+.BR syscall (2).
+But instead, you probably want to use the
+.BR io_getevents ()
+wrapper function provided by
+.\" http://git.fedorahosted.org/git/?p=libaio.git
+.IR libaio .
 
-The wrapper provided in
+Note that the
 .I libaio
-for
-.BR io_getevents ()
-does not follow the usual C library conventions for indicating error:
+wrapper function uses a different type
+.RI ( io_context_t )
+.\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
+.\" the system call.
+for the
+.I ctx_id
+argument.
+Note also that the
+.I libaio
+wrapper does not follow the usual C library conventions for indicating errors:
 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
@@ -83,10 +97,5 @@ set to a (positive) value that indicates the error.
 .BR io_submit (2),
 .BR aio (7),
 .BR time (7)
-.\" .SH "NOTES"
-.\"
-.\" .PP
-.\" The asynchronous I/O system calls were written by Benjamin LaHaise.
-.\"
 .\" .SH AUTHOR
 .\" Kent Yoder.

diff --git a/man2/io_setup.2 b/man2/io_setup.2
index beab7635e45faccb1614a25ac4ed58d40c625d81..c8e16eade250cabfa0b443a3144f4644860389fd 100644 (file)
--- a/man2/io_setup.2
+++ b/man2/io_setup.2
@@ -2,26 +2,27 @@
 .\" This file is distributed according to the GNU General Public License.
 .\" See the file COPYING in the top level source directory for details.
 .\"
-.TH IO_SETUP 2 2008-06-18 "Linux" "Linux Programmer's Manual"
+.TH IO_SETUP 2 2012-05-08 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_setup \- create an asynchronous I/O context
 .SH "SYNOPSIS"
 .nf
-.B #include <libaio.h>
-.\" #include <linux/aio.h>
-.sp
-.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctxp );
-.sp
-Link with \fI\-laio\fP.
+.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
+
+.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
 .fi
 .SH "DESCRIPTION"
 .PP
+The
 .BR io_setup ()
+system call
 creates an asynchronous I/O context capable of receiving
 at least \fInr_events\fP.
-\fIctxp\fP must not point to an AIO context that already exists, and must
+The
+.I ctx_idp
+argument must not point to an AIO context that already exists, and must
 be initialized to 0 prior to the call.
-On successful creation of the AIO context, \fI*ctxp\fP is filled in
+On successful creation of the AIO context, \fI*ctx_idp\fP is filled in
 with the resulting handle.
 .SH "RETURN VALUE"
 On success,
@@ -34,10 +35,10 @@ For the failure return, see NOTES.
 The specified \fInr_events\fP exceeds the user's limit of available events.
 .TP
 .B EFAULT
-An invalid pointer is passed for \fIctxp\fP.
+An invalid pointer is passed for \fIctx_idp\fP.
 .TP
 .B EINVAL
-\fIctxp\fP is not initialized, or the specified \fInr_events\fP
+\fIctx_idp\fP is not initialized, or the specified \fInr_events\fP
 exceeds internal limits.
 \fInr_events\fP should be greater than 0.
 .TP
@@ -49,7 +50,7 @@ Insufficient kernel resources are available.
 is not implemented on this architecture.
 .SH "VERSIONS"
 .PP
-The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
+The asynchronous I/O system calls first appeared in Linux 2.5.
 .SH "CONFORMING TO"
 .PP
 .BR io_setup ()
@@ -57,12 +58,26 @@ 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.
+You could invoke it using
+.BR syscall (2).
+But instead, you probably want to use the
+.BR io_setup ()
+wrapper function provided by
+.\" http://git.fedorahosted.org/git/?p=libaio.git
+.IR libaio .
 
-The wrapper provided in
+Note that the
 .I libaio
-for
-.BR io_setup ()
-does not follow the usual C library conventions for indicating error:
+wrapper function uses a different type
+.RI ( "io_context_t\ *" )
+.\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
+.\" the system call.
+for the
+.I ctx_idp
+argument.
+Note also that the
+.I libaio
+wrapper does not follow the usual C library conventions for indicating errors:
 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
@@ -77,8 +92,5 @@ set to a (positive) value that indicates the error.
 .BR io_getevents (2),
 .BR io_submit (2),
 .BR aio (7)
-.\" .SH "NOTES"
-.\" .PP
-.\" The asynchronous I/O system calls were written by Benjamin LaHaise.
 .\" .SH AUTHOR
 .\" Kent Yoder.

diff --git a/man2/io_submit.2 b/man2/io_submit.2
index 52239e2fead4725f62e7d0f78eeb1f2ee9c95f24..0449f366388e492b31a76c29feaa3b90b57e5e10 100644 (file)
--- a/man2/io_submit.2
+++ b/man2/io_submit.2
@@ -2,25 +2,26 @@
 .\" This file is distributed according to the GNU General Public License.
 .\" See the file COPYING in the top level source directory for details.
 .\"
-.TH IO_SUBMIT 2 2008-06-18 "Linux" "Linux Programmer's Manual"
+.TH IO_SUBMIT 2 2012-05-08 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_submit \- submit asynchronous I/O blocks for processing
 .SH "SYNOPSIS"
 .nf
-.B #include <libaio.h>
-.\" #include <linux/aio.h>
-.sp
+.BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
+
 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
 ", struct iocb **" iocbpp );
-.sp
-Link with \fI\-laio\fP.
 .fi
 .SH "DESCRIPTION"
 .PP
+The
 .BR io_submit ()
+system call
 queues \fInr\fP I/O request blocks for processing in
 the AIO context \fIctx_id\fP.
-\fIiocbpp\fP should be an array of \fInr\fP AIO control blocks,
+The
+.I iocbpp
+argument should be an array of \fInr\fP AIO control blocks,
 which will be submitted to context \fIctx_id\fP.
 .SH "RETURN VALUE"
 On success,
@@ -40,9 +41,11 @@ The file descriptor specified in the first \fIiocb\fP is invalid.
 One of the data structures points to invalid data.
 .TP
 .B EINVAL
-The \fIaio_context\fP specified by \fIctx_id\fP is invalid.
+The AIO context specified by \fIctx_id\fP is invalid.
 \fInr\fP is less than 0.
-The \fIiocb\fP at *iocbpp[0] is not properly initialized,
+The \fIiocb\fP at
+.I *iocbpp[0]
+is not properly initialized,
 or the operation specified is invalid for the file descriptor
 in the \fIiocb\fP.
 .TP
@@ -51,7 +54,7 @@ in the \fIiocb\fP.
 is not implemented on this architecture.
 .SH "VERSIONS"
 .PP
-The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
+The asynchronous I/O system calls first appeared in Linux 2.5.
 .SH "CONFORMING TO"
 .PP
 .BR io_submit ()
@@ -59,12 +62,26 @@ 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.
+You could invoke it using
+.BR syscall (2).
+But instead, you probably want to use the
+.BR io_submit ()
+wrapper function provided by
+.\" http://git.fedorahosted.org/git/?p=libaio.git
+.IR libaio .
 
-The wrapper provided in
+Note that the
 .I libaio
-for
-.BR io_submit ()
-does not follow the usual C library conventions for indicating error:
+wrapper function uses a different type
+.RI ( io_context_t )
+.\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
+.\" the system call.
+for the
+.I ctx_id
+argument.
+Note also that the
+.I libaio
+wrapper does not follow the usual C library conventions for indicating errors:
 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
@@ -79,8 +96,5 @@ set to a (positive) value that indicates the error.
 .BR io_getevents (2),
 .BR io_setup (2),
 .BR aio (7)
-.\" .SH "NOTES"
-.\" .PP
-.\" The asynchronous I/O system calls were written by Benjamin LaHaise.
 .\" .SH AUTHOR
 .\" Kent Yoder.