original/man2/io_setup.2

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