man2/io_submit.2

   1 .\" Copyright (C) 2003 Free Software Foundation, Inc.
   2 .\" and Copyright (C) 2017 Goldwyn Rodrigues <rgoldwyn@suse.de>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-1.0-or-later
   5 .\"
   6 .TH io_submit 2 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 io_submit \- submit asynchronous I/O blocks for processing
   9 .SH LIBRARY
  10 Standard C library
  11 .RI ( libc ", " \-lc )
  12 .P
  13 Alternatively, Asynchronous I/O library
  14 .RI ( libaio ", " \-laio );
  15 see VERSIONS.
  16 .SH SYNOPSIS
  17 .nf
  18 .BR "#include <linux/aio_abi.h>" "          /* Defines needed types */"
  19 .P
  20 .BI "int io_submit(aio_context_t " ctx_id ", long " nr \
  21 ", struct iocb **" iocbpp );
  22 .fi
  23 .P
  24 .IR Note :
  25 There is no glibc wrapper for this system call; see VERSIONS.
  26 .SH DESCRIPTION
  27 .IR Note :
  28 this page describes the raw Linux system call interface.
  29 The wrapper function provided by
  30 .I libaio
  31 uses a different type for the
  32 .I ctx_id
  33 argument.
  34 See VERSIONS.
  35 .P
  36 The
  37 .BR io_submit ()
  38 system call
  39 queues \fInr\fP I/O request blocks for processing in
  40 the AIO context \fIctx_id\fP.
  41 The
  42 .I iocbpp
  43 argument should be an array of \fInr\fP AIO control blocks,
  44 which will be submitted to context \fIctx_id\fP.
  45 .P
  46 The
  47 .I iocb
  48 (I/O control block) structure defined in
  49 .I linux/aio_abi.h
  50 defines the parameters that control the I/O operation.
  51 .P
  52 .in +4n
  53 .EX
  54 #include <linux/aio_abi.h>
  55 \&
  56 struct iocb {
  57     __u64   aio_data;
  58     __u32   PADDED(aio_key, aio_rw_flags);
  59     __u16   aio_lio_opcode;
  60     __s16   aio_reqprio;
  61     __u32   aio_fildes;
  62     __u64   aio_buf;
  63     __u64   aio_nbytes;
  64     __s64   aio_offset;
  65     __u64   aio_reserved2;
  66     __u32   aio_flags;
  67     __u32   aio_resfd;
  68 };
  69 .EE
  70 .in
  71 .P
  72 The fields of this structure are as follows:
  73 .TP
  74 .I aio_data
  75 This data is copied into the
  76 .I data
  77 field of the
  78 .I io_event
  79 structure upon I/O completion (see
  80 .BR io_getevents (2)).
  81 .TP
  82 .I aio_key
  83 This is an internal field used by the kernel.
  84 Do not modify this field after an
  85 .BR io_submit ()
  86 call.
  87 .TP
  88 .I aio_rw_flags
  89 This defines the R/W flags passed with structure.
  90 The valid values are:
  91 .RS
  92 .TP
  93 .BR RWF_APPEND " (since Linux 4.16)"
  94 .\" commit e1fc742e14e01d84d9693c4aca4ab23da65811fb
  95 Append data to the end of the file.
  96 See the description of the flag of the same name in
  97 .BR pwritev2 (2)
  98 as well as the description of
  99 .B O_APPEND
 100 in
 101 .BR open (2).
 102 The
 103 .I aio_offset
 104 field is ignored.
 105 The file offset is not changed.
 106 .TP
 107 .BR RWF_DSYNC " (since Linux 4.13)"
 108 Write operation complete according to requirement of
 109 synchronized I/O data integrity.
 110 See the description of the flag of the same name in
 111 .BR pwritev2 (2)
 112 as well the description of
 113 .B O_DSYNC
 114 in
 115 .BR open (2).
 116 .TP
 117 .BR RWF_HIPRI " (since Linux 4.13)"
 118 High priority request, poll if possible
 119 .TP
 120 .BR RWF_NOWAIT " (since Linux 4.14)"
 121 Don't wait if the I/O will block for operations such as
 122 file block allocations, dirty page flush, mutex locks,
 123 or a congested block device inside the kernel.
 124 If any of these conditions are met, the control block is returned
 125 immediately with a return value of
 126 .B \-EAGAIN
 127 in the
 128 .I res
 129 field of the
 130 .I io_event
 131 structure (see
 132 .BR io_getevents (2)).
 133 .TP
 134 .BR RWF_SYNC " (since Linux 4.13)"
 135 Write operation complete according to requirement of
 136 synchronized I/O file integrity.
 137 See the description of the flag of the same name in
 138 .BR pwritev2 (2)
 139 as well the description of
 140 .B O_SYNC
 141 in
 142 .BR open (2).
 143 .RE
 144 .TP
 145 .I aio_lio_opcode
 146 This defines the type of I/O to be performed by the
 147 .I iocb
 148 structure.
 149 The
 150 valid values are defined by the enum defined in
 151 .IR linux/aio_abi.h :
 152 .IP
 153 .in +4n
 154 .EX
 155 enum {
 156     IOCB_CMD_PREAD = 0,
 157     IOCB_CMD_PWRITE = 1,
 158     IOCB_CMD_FSYNC = 2,
 159     IOCB_CMD_FDSYNC = 3,
 160     IOCB_CMD_POLL = 5,
 161     IOCB_CMD_NOOP = 6,
 162     IOCB_CMD_PREADV = 7,
 163     IOCB_CMD_PWRITEV = 8,
 164 };
 165 .EE
 166 .in
 167 .TP
 168 .I aio_reqprio
 169 This defines the requests priority.
 170 .TP
 171 .I aio_fildes
 172 The file descriptor on which the I/O operation is to be performed.
 173 .TP
 174 .I aio_buf
 175 This is the buffer used to transfer data for a read or write operation.
 176 .TP
 177 .I aio_nbytes
 178 This is the size of the buffer pointed to by
 179 .IR aio_buf .
 180 .TP
 181 .I aio_offset
 182 This is the file offset at which the I/O operation is to be performed.
 183 .TP
 184 .I aio_flags
 185 This is the set of flags associated with the
 186 .I iocb
 187 structure.
 188 The valid values are:
 189 .RS
 190 .TP
 191 .B IOCB_FLAG_RESFD
 192 Asynchronous I/O control must signal the file
 193 descriptor mentioned in
 194 .I aio_resfd
 195 upon completion.
 196 .TP
 197 .BR IOCB_FLAG_IOPRIO " (since Linux 4.18)"
 198 .\" commit d9a08a9e616beeccdbd0e7262b7225ffdfa49e92
 199 Interpret the
 200 .I aio_reqprio
 201 field as an
 202 .B IOPRIO_VALUE
 203 as defined by
 204 .IR linux/ioprio.h .
 205 .RE
 206 .TP
 207 .I aio_resfd
 208 The file descriptor to signal in the event of asynchronous I/O completion.
 209 .SH RETURN VALUE
 210 On success,
 211 .BR io_submit ()
 212 returns the number of \fIiocb\fPs submitted (which may be
 213 less than \fInr\fP, or 0 if \fInr\fP is zero).
 214 For the failure return, see VERSIONS.
 215 .SH ERRORS
 216 .TP
 217 .B EAGAIN
 218 Insufficient resources are available to queue any \fIiocb\fPs.
 219 .TP
 220 .B EBADF
 221 The file descriptor specified in the first \fIiocb\fP is invalid.
 222 .TP
 223 .B EFAULT
 224 One of the data structures points to invalid data.
 225 .TP
 226 .B EINVAL
 227 The AIO context specified by \fIctx_id\fP is invalid.
 228 \fInr\fP is less than 0.
 229 The \fIiocb\fP at
 230 .I *iocbpp[0]
 231 is not properly initialized, the operation specified is invalid for the file
 232 descriptor in the \fIiocb\fP, or the value in the
 233 .I aio_reqprio
 234 field is invalid.
 235 .TP
 236 .B ENOSYS
 237 .BR io_submit ()
 238 is not implemented on this architecture.
 239 .TP
 240 .B EPERM
 241 The
 242 .I aio_reqprio
 243 field is set with the class
 244 .BR IOPRIO_CLASS_RT ,
 245 but the submitting context does not have the
 246 .B CAP_SYS_ADMIN
 247 capability.
 248 .SH VERSIONS
 249 glibc does not provide a wrapper for this system call.
 250 You could invoke it using
 251 .BR syscall (2).
 252 But instead, you probably want to use the
 253 .BR io_submit ()
 254 wrapper function provided by
 255 .\" http://git.fedorahosted.org/git/?p=libaio.git
 256 .IR libaio .
 257 .P
 258 Note that the
 259 .I libaio
 260 wrapper function uses a different type
 261 .RI ( io_context_t )
 262 .\" But glibc is confused, since <libaio.h> uses 'io_context_t' to declare
 263 .\" the system call.
 264 for the
 265 .I ctx_id
 266 argument.
 267 Note also that the
 268 .I libaio
 269 wrapper does not follow the usual C library conventions for indicating errors:
 270 on error it returns a negated error number
 271 (the negative of one of the values listed in ERRORS).
 272 If the system call is invoked via
 273 .BR syscall (2),
 274 then the return value follows the usual conventions for
 275 indicating an error: \-1, with
 276 .I errno
 277 set to a (positive) value that indicates the error.
 278 .SH STANDARDS
 279 Linux.
 280 .SH HISTORY
 281 Linux 2.5.
 282 .SH SEE ALSO
 283 .BR io_cancel (2),
 284 .BR io_destroy (2),
 285 .BR io_getevents (2),
 286 .BR io_setup (2),
 287 .BR aio (7)
 288 .\" .SH AUTHOR
 289 .\" Kent Yoder.