LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

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>
This commit is contained in:
Michael Kerrisk 2012-05-08 14:41:17 +12:00
parent dd3ec6febb
commit e1c5ebfa25
5 changed files with 151 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
man2/io_cancel.2
View File

@ -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.
The wrapper provided in
.I libaio
for
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
.BR io_cancel ()
does not follow the usual C library conventions for indicating error:
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
Note that the
.I libaio
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.

55
man2/io_destroy.2
View File

@ -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.
The wrapper provided in
.I libaio
for
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
.BR io_destroy ()
does not follow the usual C library conventions for indicating error:
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
Note that the
.I libaio
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.

45
man2/io_getevents.2
View File

@ -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.
The wrapper provided in
.I libaio
for
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
.BR io_getevents ()
does not follow the usual C library conventions for indicating error:
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
Note that the
.I libaio
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.

52
man2/io_setup.2
View File

@ -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.
The wrapper provided in
.I libaio
for
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
.BR io_setup ()
does not follow the usual C library conventions for indicating error:
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
Note that the
.I libaio
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.

50
man2/io_submit.2
View File

@ -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.
The wrapper provided in
.I libaio
for
You could invoke it using
.BR syscall (2).
But instead, you probably want to use the
.BR io_submit ()
does not follow the usual C library conventions for indicating error:
wrapper function provided by
.\" http://git.fedorahosted.org/git/?p=libaio.git
.IR libaio .
Note that the
.I libaio
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.