OSDN Git Service

LDP: Update original to LDP v3.79
[linuxjm/LDP_man-pages.git] / original / man2 / io_setup.2
index d9b5117..431f3f4 100644 (file)
@@ -1,66 +1,51 @@
 .\" Copyright (C) 2003 Free Software Foundation, Inc.
+.\"
+.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
 .\" This file is distributed according to the GNU General Public License.
-.\" See the file COPYING in the top level source directory for details.
+.\" %%%LICENSE_END
 .\"
-.\" .de Sh \" Subsection
-.\" .br
-.\" .if t .Sp
-.\" .ne 5
-.\" .PP
-.\" \fB\\$1\fP
-.\" .PP
-.\" ..
-.\" .de Sp \" Vertical space (when we can't use .PP)
-.\" .if t .sp .5v
-.\" .if n .sp
-.\" ..
-.\" .de Ip \" List item
-.\" .br
-.\" .ie \\n(.$>=3 .ne \\$3
-.\" .el .ne 3
-.\" .IP "\\$1" \\$2
-.\" ..
-.TH IO_SETUP 2 2008-06-18 "Linux" "Linux Programmer's Manual"
+.TH IO_SETUP 2 2013-06-21 "Linux" "Linux Programmer's Manual"
 .SH NAME
 io_setup \- create an asynchronous I/O context
-.SH "SYNOPSIS"
+.SH SYNOPSIS
 .nf
-.\" .ad l
-.\" .hy 0
-.B #include <libaio.h>
-.\" #include <linux/aio.h>
-.sp
-.\" .HP 15
-.BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctxp );
-.\" .ad
-.\" .hy
-.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"
+
+.IR Note :
+There is no glibc wrapper for this system call; see NOTES.
+.SH DESCRIPTION
 .PP
+The
 .BR io_setup ()
-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
+system call
+creates an asynchronous I/O context suitable for concurrently processing
+\fInr_events\fP operations.
+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"
+.SH RETURN VALUE
 On success,
 .BR io_setup ()
 returns 0.
 For the failure return, see NOTES.
-.SH "ERRORS"
+.SH ERRORS
 .TP
 .B EAGAIN
-The specified \fInr_events\fP exceeds the user's limit of available events.
+The specified \fInr_events\fP exceeds the user's limit of available events,
+as defined in
+.IR /proc/sys/fs/aio-max-nr .
 .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
@@ -70,22 +55,36 @@ Insufficient kernel resources are available.
 .B ENOSYS
 .BR io_setup ()
 is not implemented on this architecture.
-.SH "VERSIONS"
+.SH VERSIONS
 .PP
-The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
-.SH "CONFORMING TO"
+The asynchronous I/O system calls first appeared in Linux 2.5.
+.SH CONFORMING TO
 .PP
 .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.
+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
@@ -94,14 +93,20 @@ 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"
+.SH SEE ALSO
 .BR io_cancel (2),
 .BR io_destroy (2),
 .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.
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.