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 2017-09-15 "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 .PP
  14 .BI "int io_setup(unsigned " nr_events ", io_context_t *" ctx_idp );
  15 .fi
  16 .PP
  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 suitable for concurrently processing
  25 \fInr_events\fP operations.
  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 limit of available events,
  41 as defined in
  42 .IR /proc/sys/fs/aio-max-nr
  43 (see
  44 .BR proc (5)).
  45 .TP
  46 .B EFAULT
  47 An invalid pointer is passed for \fIctx_idp\fP.
  48 .TP
  49 .B EINVAL
  50 \fIctx_idp\fP is not initialized, or the specified \fInr_events\fP
  51 exceeds internal limits.
  52 \fInr_events\fP should be greater than 0.
  53 .TP
  54 .B ENOMEM
  55 Insufficient kernel resources are available.
  56 .TP
  57 .B ENOSYS
  58 .BR io_setup ()
  59 is not implemented on this architecture.
  60 .SH VERSIONS
  61 .PP
  62 The asynchronous I/O system calls first appeared in Linux 2.5.
  63 .SH CONFORMING TO
  64 .PP
  65 .BR io_setup ()
  66 is Linux-specific and should not be used in programs
  67 that are intended to be portable.
  68 .SH NOTES
  69 Glibc does not provide a wrapper function for this system call.
  70 You could invoke it using
  71 .BR syscall (2).
  72 But instead, you probably want to use the
  73 .BR io_setup ()
  74 wrapper function provided by
  75 .\" http://git.fedorahosted.org/git/?p=libaio.git
  76 .IR libaio .
  77 .PP
  78 Note that the
  79 .I libaio
  80 wrapper function uses a different type
  81 .RI ( "io_context_t\ *" )
  82 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
  83 .\" the system call.
  84 for the
  85 .I ctx_idp
  86 argument.
  87 Note also that the
  88 .I libaio
  89 wrapper does not follow the usual C library conventions for indicating errors:
  90 on error it returns a negated error number
  91 (the negative of one of the values listed in ERRORS).
  92 If the system call is invoked via
  93 .BR syscall (2),
  94 then the return value follows the usual conventions for
  95 indicating an error: \-1, with
  96 .I errno
  97 set to a (positive) value that indicates the error.
  98 .SH SEE ALSO
  99 .BR io_cancel (2),
 100 .BR io_destroy (2),
 101 .BR io_getevents (2),
 102 .BR io_submit (2),
 103 .BR aio (7)
 104 .\" .SH AUTHOR
 105 .\" Kent Yoder.