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-07-13 "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
  16 .IR Note :
  17 There is no glibc wrapper for this system call; see NOTES.
  18 .SH DESCRIPTION
  19 .PP
  20 The
  21 .BR io_submit ()
  22 system call
  23 queues \fInr\fP I/O request blocks for processing in
  24 the AIO context \fIctx_id\fP.
  25 The
  26 .I iocbpp
  27 argument should be an array of \fInr\fP AIO control blocks,
  28 which will be submitted to context \fIctx_id\fP.
  29 .SH RETURN VALUE
  30 On success,
  31 .BR io_submit ()
  32 returns the number of \fIiocb\fPs submitted (which may be
  33 0 if \fInr\fP is zero).
  34 For the failure return, see NOTES.
  35 .SH ERRORS
  36 .TP
  37 .B EAGAIN
  38 Insufficient resources are available to queue any \fIiocb\fPs.
  39 .TP
  40 .B EBADF
  41 The file descriptor specified in the first \fIiocb\fP is invalid.
  42 .TP
  43 .B EFAULT
  44 One of the data structures points to invalid data.
  45 .TP
  46 .B EINVAL
  47 The AIO context specified by \fIctx_id\fP is invalid.
  48 \fInr\fP is less than 0.
  49 The \fIiocb\fP at
  50 .I *iocbpp[0]
  51 is not properly initialized,
  52 or the operation specified is invalid for the file descriptor
  53 in the \fIiocb\fP.
  54 .TP
  55 .B ENOSYS
  56 .BR io_submit ()
  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_submit ()
  64 is Linux-specific and should not be used in
  65 programs 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_submit ()
  72 wrapper function provided by
  73 .\" http://git.fedorahosted.org/git/?p=libaio.git
  74 .IR libaio .
  75
  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_id
  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_setup (2),
 101 .BR aio (7)
 102 .\" .SH AUTHOR
 103 .\" Kent Yoder.