original/man2/io_submit.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_SUBMIT 2 2012-07-13 "Linux" "Linux Programmer's Manual"
   8 .SH NAME
   9 io_submit \- submit asynchronous I/O blocks for processing
  10 .SH SYNOPSIS
  11 .nf
  12 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
  13
  14 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
  15 ", struct iocb **" iocbpp );
  16 .fi
  17
  18 .IR Note :
  19 There is no glibc wrapper for this system call; see NOTES.
  20 .SH DESCRIPTION
  21 .PP
  22 The
  23 .BR io_submit ()
  24 system call
  25 queues \fInr\fP I/O request blocks for processing in
  26 the AIO context \fIctx_id\fP.
  27 The
  28 .I iocbpp
  29 argument should be an array of \fInr\fP AIO control blocks,
  30 which will be submitted to context \fIctx_id\fP.
  31 .SH RETURN VALUE
  32 On success,
  33 .BR io_submit ()
  34 returns the number of \fIiocb\fPs submitted (which may be
  35 0 if \fInr\fP is zero).
  36 For the failure return, see NOTES.
  37 .SH ERRORS
  38 .TP
  39 .B EAGAIN
  40 Insufficient resources are available to queue any \fIiocb\fPs.
  41 .TP
  42 .B EBADF
  43 The file descriptor specified in the first \fIiocb\fP is invalid.
  44 .TP
  45 .B EFAULT
  46 One of the data structures points to invalid data.
  47 .TP
  48 .B EINVAL
  49 The AIO context specified by \fIctx_id\fP is invalid.
  50 \fInr\fP is less than 0.
  51 The \fIiocb\fP at
  52 .I *iocbpp[0]
  53 is not properly initialized,
  54 or the operation specified is invalid for the file descriptor
  55 in the \fIiocb\fP.
  56 .TP
  57 .B ENOSYS
  58 .BR io_submit ()
  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_submit ()
  66 is Linux-specific and should not be used in
  67 programs 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_submit ()
  74 wrapper function provided by
  75 .\" http://git.fedorahosted.org/git/?p=libaio.git
  76 .IR libaio .
  77
  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_id
  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_setup (2),
 103 .BR aio (7)
 104 .\" .SH AUTHOR
 105 .\" Kent Yoder.
 106 .SH COLOPHON
 107 This page is part of release 3.65 of the Linux
 108 .I man-pages
 109 project.
 110 A description of the project,
 111 and information about reporting bugs,
 112 can be found at
 113 \%http://www.kernel.org/doc/man\-pages/.