original/man2/io_setup.2

   1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
   2 .\" This file is distributed according to the GNU General Public License.
   3 .\" See the file COPYING in the top level source directory for details.
   4 .\"
   5 .TH IO_SETUP 2 2012-05-08 "Linux" "Linux Programmer's Manual"
   6 .SH NAME
   7 io_setup \- create an asynchronous I/O context
   8 .SH "SYNOPSIS"
   9 .nf
  10 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
  11
  12 .BI "int io_setup(unsigned " nr_events ", aio_context_t *" ctx_idp );
  13 .fi
  14 .SH "DESCRIPTION"
  15 .PP
  16 The
  17 .BR io_setup ()
  18 system call
  19 creates an asynchronous I/O context capable of receiving
  20 at least \fInr_events\fP.
  21 The
  22 .I ctx_idp
  23 argument must not point to an AIO context that already exists, and must
  24 be initialized to 0 prior to the call.
  25 On successful creation of the AIO context, \fI*ctx_idp\fP is filled in
  26 with the resulting handle.
  27 .SH "RETURN VALUE"
  28 On success,
  29 .BR io_setup ()
  30 returns 0.
  31 For the failure return, see NOTES.
  32 .SH "ERRORS"
  33 .TP
  34 .B EAGAIN
  35 The specified \fInr_events\fP exceeds the user's limit of available events.
  36 .TP
  37 .B EFAULT
  38 An invalid pointer is passed for \fIctx_idp\fP.
  39 .TP
  40 .B EINVAL
  41 \fIctx_idp\fP is not initialized, or the specified \fInr_events\fP
  42 exceeds internal limits.
  43 \fInr_events\fP should be greater than 0.
  44 .TP
  45 .B ENOMEM
  46 Insufficient kernel resources are available.
  47 .TP
  48 .B ENOSYS
  49 .BR io_setup ()
  50 is not implemented on this architecture.
  51 .SH "VERSIONS"
  52 .PP
  53 The asynchronous I/O system calls first appeared in Linux 2.5.
  54 .SH "CONFORMING TO"
  55 .PP
  56 .BR io_setup ()
  57 is Linux-specific and should not be used in programs
  58 that are intended to be portable.
  59 .SH NOTES
  60 Glibc does not provide a wrapper function for this system call.
  61 You could invoke it using
  62 .BR syscall (2).
  63 But instead, you probably want to use the
  64 .BR io_setup ()
  65 wrapper function provided by
  66 .\" http://git.fedorahosted.org/git/?p=libaio.git
  67 .IR libaio .
  68
  69 Note that the
  70 .I libaio
  71 wrapper function uses a different type
  72 .RI ( "io_context_t\ *" )
  73 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
  74 .\" the system call.
  75 for the
  76 .I ctx_idp
  77 argument.
  78 Note also that the
  79 .I libaio
  80 wrapper does not follow the usual C library conventions for indicating errors:
  81 on error it returns a negated error number
  82 (the negative of one of the values listed in ERRORS).
  83 If the system call is invoked via
  84 .BR syscall (2),
  85 then the return value follows the usual conventions for
  86 indicating an error: \-1, with
  87 .I errno
  88 set to a (positive) value that indicates the error.
  89 .SH "SEE ALSO"
  90 .BR io_cancel (2),
  91 .BR io_destroy (2),
  92 .BR io_getevents (2),
  93 .BR io_submit (2),
  94 .BR aio (7)
  95 .\" .SH AUTHOR
  96 .\" Kent Yoder.