original/man2/io_submit.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_SUBMIT 2 2012-05-08 "Linux" "Linux Programmer's Manual"
   6 .SH NAME
   7 io_submit \- submit asynchronous I/O blocks for processing
   8 .SH "SYNOPSIS"
   9 .nf
  10 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
  11
  12 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
  13 ", struct iocb **" iocbpp );
  14 .fi
  15 .SH "DESCRIPTION"
  16 .PP
  17 The
  18 .BR io_submit ()
  19 system call
  20 queues \fInr\fP I/O request blocks for processing in
  21 the AIO context \fIctx_id\fP.
  22 The
  23 .I iocbpp
  24 argument should be an array of \fInr\fP AIO control blocks,
  25 which will be submitted to context \fIctx_id\fP.
  26 .SH "RETURN VALUE"
  27 On success,
  28 .BR io_submit ()
  29 returns the number of \fIiocb\fPs submitted (which may be
  30 0 if \fInr\fP is zero).
  31 For the failure return, see NOTES.
  32 .SH "ERRORS"
  33 .TP
  34 .B EAGAIN
  35 Insufficient resources are available to queue any \fIiocb\fPs.
  36 .TP
  37 .B EBADF
  38 The file descriptor specified in the first \fIiocb\fP is invalid.
  39 .TP
  40 .B EFAULT
  41 One of the data structures points to invalid data.
  42 .TP
  43 .B EINVAL
  44 The AIO context specified by \fIctx_id\fP is invalid.
  45 \fInr\fP is less than 0.
  46 The \fIiocb\fP at
  47 .I *iocbpp[0]
  48 is not properly initialized,
  49 or the operation specified is invalid for the file descriptor
  50 in the \fIiocb\fP.
  51 .TP
  52 .B ENOSYS
  53 .BR io_submit ()
  54 is not implemented on this architecture.
  55 .SH "VERSIONS"
  56 .PP
  57 The asynchronous I/O system calls first appeared in Linux 2.5.
  58 .SH "CONFORMING TO"
  59 .PP
  60 .BR io_submit ()
  61 is Linux-specific and should not be used in
  62 programs that are intended to be portable.
  63 .SH NOTES
  64 Glibc does not provide a wrapper function for this system call.
  65 You could invoke it using
  66 .BR syscall (2).
  67 But instead, you probably want to use the
  68 .BR io_submit ()
  69 wrapper function provided by
  70 .\" http://git.fedorahosted.org/git/?p=libaio.git
  71 .IR libaio .
  72
  73 Note that the
  74 .I libaio
  75 wrapper function uses a different type
  76 .RI ( io_context_t )
  77 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
  78 .\" the system call.
  79 for the
  80 .I ctx_id
  81 argument.
  82 Note also that the
  83 .I libaio
  84 wrapper does not follow the usual C library conventions for indicating errors:
  85 on error it returns a negated error number
  86 (the negative of one of the values listed in ERRORS).
  87 If the system call is invoked via
  88 .BR syscall (2),
  89 then the return value follows the usual conventions for
  90 indicating an error: \-1, with
  91 .I errno
  92 set to a (positive) value that indicates the error.
  93 .SH "SEE ALSO"
  94 .BR io_cancel (2),
  95 .BR io_destroy (2),
  96 .BR io_getevents (2),
  97 .BR io_setup (2),
  98 .BR aio (7)
  99 .\" .SH AUTHOR
 100 .\" Kent Yoder.