io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2: Rewrite to focus on system call API

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>
author: Michael Kerrisk <mtk.manpages@gmail.com> 2012-05-08 14:41:17 +1200
committer: Michael Kerrisk <mtk.manpages@gmail.com> 2012-05-10 11:57:03 +1200
commit: e1c5ebfa250d1664d9cc2033c33307aa0a1668f4 (patch)
tree: c4a3df7991a94c3652148eefc2bca7c0165fd76d
parent: dd3ec6febbfa81b34fd05366f8e0360f11607a23 (diff)
download: man-pages-e1c5ebfa250d1664d9cc2033c33307aa0a1668f4.tar.gz
5 files changed, 146 insertions, 92 deletions
diff --git a/man2/io_cancel.2 b/man2/io_cancel.2
index cce36c147f..0faa6b1b5a 100644
--- 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 1948f151e8..5be8afeed5 100644
--- 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 6c42ce5cff..d959045a59 100644
--- 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 beab7635e4..c8e16eade2 100644
--- 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 52239e2fea..0449f36638 100644
--- 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.
author	Michael Kerrisk <mtk.manpages@gmail.com>	2012-05-08 14:41:17 +1200
committer	Michael Kerrisk <mtk.manpages@gmail.com>	2012-05-10 11:57:03 +1200
commit	e1c5ebfa250d1664d9cc2033c33307aa0a1668f4 (patch)
tree	c4a3df7991a94c3652148eefc2bca7c0165fd76d
parent	dd3ec6febbfa81b34fd05366f8e0360f11607a23 (diff)
download	man-pages-e1c5ebfa250d1664d9cc2033c33307aa0a1668f4.tar.gz