man2/io_submit.2

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