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 .\" .de Sh \" Subsection
   6 .\" .br
   7 .\" .if t .Sp
   8 .\" .ne 5
   9 .\" .PP
  10 .\" \fB\\$1\fP
  11 .\" .PP
  12 .\" ..
  13 .\" .de Sp \" Vertical space (when we can't use .PP)
  14 .\" .if t .sp .5v
  15 .\" .if n .sp
  16 .\" ..
  17 .\" .de Ip \" List item
  18 .\" .br
  19 .\" .ie \\n(.$>=3 .ne \\$3
  20 .\" .el .ne 3
  21 .\" .IP "\\$1" \\$2
  22 .\" ..
  23 .TH IO_SUBMIT 2 2008-06-18 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 io_submit \- submit asynchronous I/O blocks for processing
  26 .SH "SYNOPSIS"
  27 .nf
  28 .\" .ad l
  29 .\" .hy 0
  30 .B #include <libaio.h>
  31 .\" #include <linux/aio.h>
  32 .sp
  33 .\" .HP 16
  34 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
  35 ", struct iocb **" iocbpp );
  36 .\" .ad
  37 .\" .hy
  38 .sp
  39 Link with \fI\-laio\fP.
  40 .fi
  41 .SH "DESCRIPTION"
  42 .PP
  43 .BR io_submit ()
  44 queues \fInr\fP I/O request blocks for processing in
  45 the AIO context \fIctx_id\fP.
  46 \fIiocbpp\fP should be an array of \fInr\fP AIO control blocks,
  47 which will be submitted to context \fIctx_id\fP.
  48 .SH "RETURN VALUE"
  49 On success,
  50 .BR io_submit ()
  51 returns the number of \fIiocb\fPs submitted (which may be
  52 0 if \fInr\fP is zero).
  53 For the failure return, see NOTES.
  54 .SH "ERRORS"
  55 .TP
  56 .B EAGAIN
  57 Insufficient resources are available to queue any \fIiocb\fPs.
  58 .TP
  59 .B EBADF
  60 The file descriptor specified in the first \fIiocb\fP is invalid.
  61 .TP
  62 .B EFAULT
  63 One of the data structures points to invalid data.
  64 .TP
  65 .B EINVAL
  66 The \fIaio_context\fP specified by \fIctx_id\fP is invalid.
  67 \fInr\fP is less than 0.
  68 The \fIiocb\fP at *iocbpp[0] is not properly initialized,
  69 or the operation specified is invalid for the file descriptor
  70 in the \fIiocb\fP.
  71 .TP
  72 .B ENOSYS
  73 .BR io_submit ()
  74 is not implemented on this architecture.
  75 .SH "VERSIONS"
  76 .PP
  77 The asynchronous I/O system calls first appeared in Linux 2.5, August 2002.
  78 .SH "CONFORMING TO"
  79 .PP
  80 .BR io_submit ()
  81 is Linux-specific and should not be used in
  82 programs that are intended to be portable.
  83 .SH NOTES
  84 Glibc does not provide a wrapper function for this system call.
  85
  86 The wrapper provided in
  87 .I libaio
  88 for
  89 .BR io_submit ()
  90 does not follow the usual C library conventions for indicating error:
  91 on error it returns a negated error number
  92 (the negative of one of the values listed in ERRORS).
  93 If the system call is invoked via
  94 .BR syscall (2),
  95 then the return value follows the usual conventions for
  96 indicating an error: \-1, with
  97 .I errno
  98 set to a (positive) value that indicates the error.
  99 .SH "SEE ALSO"
 100 .BR io_cancel (2),
 101 .BR io_destroy (2),
 102 .BR io_getevents (2),
 103 .BR io_setup (2)
 104 .\" .SH "NOTES"
 105 .\" .PP
 106 .\" The asynchronous I/O system calls were written by Benjamin LaHaise.
 107 .\" .SH AUTHOR
 108 .\" Kent Yoder.