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