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