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 2017-09-15 "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 .PP
  14 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
  15 ", struct iocb **" iocbpp );
  16 .fi
  17 .PP
  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 The
  32 .I iocb
  33 (I/O control block) structure defined in linux/aio_abi.h
  34 defines the parameters that control the I/O operation.
  35 .PP
  36 .in +4n
  37 .nf
  38
  39 #include <linux/aio_abi.h>
  40
  41 struct iocb {
  42         __u64   aio_data;
  43         __u32   PADDED(aio_key, aio_rw_flags);
  44
  45         __u16   aio_lio_opcode;
  46         __s16   aio_reqprio;
  47         __u32   aio_fildes;
  48
  49         __u64   aio_buf;
  50         __u64   aio_nbytes;
  51         __s64   aio_offset;
  52
  53         __u64   aio_reserved2;
  54
  55         __u32   aio_flags;
  56         __u32   aio_resfd;
  57 };
  58
  59 .fi
  60 .in
  61 The fields of this structure are as follows:
  62 .TP
  63 .I aio_data
  64 This is a internal field used by the kernel. Do not modify this field after an
  65 .B io_submit (2)
  66 call.
  67 .TP
  68 .I aio_key
  69 This is a internal field used by the kernel. Do not modify this field after an
  70 .B io_submit (2)
  71 call.
  72 .TP
  73 .I aio_rw_flags
  74 This defines the R/W flags passed with structure. The valid values are:
  75 .RS
  76 .TP
  77 .I RWF_HIPRI
  78 High priority request, poll if possible
  79 .TP
  80 .I RWF_DSYNC
  81 Write operation complete according to requirement of synchronized I/O data integrity. Similar to a file passed
  82 .B O_DSYNC
  83 parameter to
  84 .B open(2)
  85 .TP
  86 .I RWF_SYNC
  87 Write operation complete according to requirement of synchronized I/O file integrity. Similar to a file passed
  88 .B .O_SYNC
  89 parameter to
  90 .B open(2)
  91 .TP
  92 .I RWF_NOWAIT
  93 Don't wait if the I/O will block for operations such as file block allocations,
  94 dirty page flush, mutex locks, or a congested block device inside the kernel.
  95 If any of these conditions are met, the control block is returned immediately
  96 with a return value of
  97 .B -EAGAIN
  98 in the res field of the io_event structure.
  99 .RE
 100 .TP
 101 .I aio_lio_opcode
 102 This defines the type of I/O to be performed by the iocb structure. The
 103 valid values are defined by the enum defined in linux/aio_abi.h:
 104 .in +4
 105 .nf
 106 enum {
 107         IOCB_CMD_PREAD = 0,
 108         IOCB_CMD_PWRITE = 1,
 109         IOCB_CMD_FSYNC = 2,
 110         IOCB_CMD_FDSYNC = 3,
 111         IOCB_CMD_NOOP = 6,
 112         IOCB_CMD_PREADV = 7,
 113         IOCB_CMD_PWRITEV = 8,
 114 };
 115 .fi
 116 .in
 117 .TP
 118 .I aio_reqprio
 119 This defines the requests priority.
 120 .TP
 121 .I aio_filedes
 122 The file descriptor on which the I/O operation is to be performed.
 123 .TP
 124 .I aio_buf
 125 This is the buffer used to transfer data for a read or write operation.
 126 .TP
 127 .I aio_nbytes
 128 This is the size of the buffer pointed to by
 129 .IR aio_buf .
 130 .TP
 131 .I aio_offset
 132 This is the file offset at which the I/O operation is to be performed.
 133 .TP
 134 .I aio_flags
 135 This is the flag to be passed iocb structure. The only valid value is
 136 .I IOCB_FLAG_RESFD
 137 , which indicates that the asynchronous I/O control must signal the file
 138 descriptor mentioned in
 139 .I aio_resfd
 140 upon completion.
 141 .TP
 142 .I aio_resfd
 143 The file descriptor to signal in the event of asynchronous I/O completion.
 144
 145 .SH RETURN VALUE
 146 On success,
 147 .BR io_submit ()
 148 returns the number of \fIiocb\fPs submitted (which may be
 149 less than \fInr\fP, or 0 if \fInr\fP is zero).
 150 For the failure return, see NOTES.
 151 .SH ERRORS
 152 .TP
 153 .B EAGAIN
 154 Insufficient resources are available to queue any \fIiocb\fPs.
 155 .TP
 156 .B EBADF
 157 The file descriptor specified in the first \fIiocb\fP is invalid.
 158 .TP
 159 .B EFAULT
 160 One of the data structures points to invalid data.
 161 .TP
 162 .B EINVAL
 163 The AIO context specified by \fIctx_id\fP is invalid.
 164 \fInr\fP is less than 0.
 165 The \fIiocb\fP at
 166 .I *iocbpp[0]
 167 is not properly initialized,
 168 or the operation specified is invalid for the file descriptor
 169 in the \fIiocb\fP.
 170 .TP
 171 .B ENOSYS
 172 .BR io_submit ()
 173 is not implemented on this architecture.
 174 .SH VERSIONS
 175 .PP
 176 The asynchronous I/O system calls first appeared in Linux 2.5.
 177 .SH CONFORMING TO
 178 .PP
 179 .BR io_submit ()
 180 is Linux-specific and should not be used in
 181 programs that are intended to be portable.
 182 .SH NOTES
 183 Glibc does not provide a wrapper function for this system call.
 184 You could invoke it using
 185 .BR syscall (2).
 186 But instead, you probably want to use the
 187 .BR io_submit ()
 188 wrapper function provided by
 189 .\" http://git.fedorahosted.org/git/?p=libaio.git
 190 .IR libaio .
 191 .PP
 192 Note that the
 193 .I libaio
 194 wrapper function uses a different type
 195 .RI ( io_context_t )
 196 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
 197 .\" the system call.
 198 for the
 199 .I ctx_id
 200 argument.
 201 Note also that the
 202 .I libaio
 203 wrapper does not follow the usual C library conventions for indicating errors:
 204 on error it returns a negated error number
 205 (the negative of one of the values listed in ERRORS).
 206 If the system call is invoked via
 207 .BR syscall (2),
 208 then the return value follows the usual conventions for
 209 indicating an error: \-1, with
 210 .I errno
 211 set to a (positive) value that indicates the error.
 212 .SH SEE ALSO
 213 .BR io_cancel (2),
 214 .BR io_destroy (2),
 215 .BR io_getevents (2),
 216 .BR io_setup (2),
 217 .BR aio (7)
 218 .\" .SH AUTHOR
 219 .\" Kent Yoder.