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