man3/lio_listio.3

   1 '\" t
   2 .\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .TH lio_listio 3 (date) "Linux man-pages (unreleased)"
   7 .SH NAME
   8 lio_listio \- initiate a list of I/O requests
   9 .SH LIBRARY
  10 Real-time library
  11 .RI ( librt ", " \-lrt )
  12 .SH SYNOPSIS
  13 .nf
  14 .B "#include <aio.h>"
  15 .PP
  16 .BI "int lio_listio(int " mode ,
  17 .BI "               struct aiocb *restrict const " aiocb_list [restrict],
  18 .BI "               int " nitems ", struct sigevent *restrict " sevp );
  19 .fi
  20 .SH DESCRIPTION
  21 The
  22 .BR lio_listio ()
  23 function initiates the list of I/O operations described by the array
  24 .IR aiocb_list .
  25 .PP
  26 The
  27 .I mode
  28 operation has one of the following values:
  29 .TP
  30 .B LIO_WAIT
  31 The call blocks until all operations are complete.
  32 The
  33 .I sevp
  34 argument is ignored.
  35 .TP
  36 .B LIO_NOWAIT
  37 The I/O operations are queued for processing and the call returns immediately.
  38 When all of the I/O operations complete, asynchronous notification occurs,
  39 as specified by the
  40 .I sevp
  41 argument; see
  42 .BR sigevent (7)
  43 for details.
  44 If
  45 .I sevp
  46 is NULL, no asynchronous notification occurs.
  47 .PP
  48 The
  49 .I aiocb_list
  50 argument is an array of pointers to
  51 .I aiocb
  52 structures that describe I/O operations.
  53 These operations are executed in an unspecified order.
  54 The
  55 .I nitems
  56 argument specifies the size of the array
  57 .IR aiocb_list .
  58 Null pointers in
  59 .I aiocb_list
  60 are ignored.
  61 .PP
  62 In each control block in
  63 .IR aiocb_list ,
  64 the
  65 .I aio_lio_opcode
  66 field specifies the I/O operation to be initiated, as follows:
  67 .TP
  68 .B LIO_READ
  69 Initiate a read operation.
  70 The operation is queued as for a call to
  71 .BR aio_read (3)
  72 specifying this control block.
  73 .TP
  74 .B LIO_WRITE
  75 Initiate a write operation.
  76 The operation is queued as for a call to
  77 .BR aio_write (3)
  78 specifying this control block.
  79 .TP
  80 .B LIO_NOP
  81 Ignore this control block.
  82 .PP
  83 The remaining fields in each control block have the same meanings as for
  84 .BR aio_read (3)
  85 and
  86 .BR aio_write (3).
  87 The
  88 .I aio_sigevent
  89 fields of each control block can be used to specify notifications
  90 for the individual I/O operations (see
  91 .BR sigevent (7)).
  92 .SH RETURN VALUE
  93 If
  94 .I mode
  95 is
  96 .BR LIO_NOWAIT ,
  97 .BR lio_listio ()
  98 returns 0 if all I/O operations are successfully queued.
  99 Otherwise, \-1 is returned, and
 100 .I errno
 101 is set to indicate the error.
 102 .PP
 103 If
 104 .I mode
 105 is
 106 .BR LIO_WAIT ,
 107 .BR lio_listio ()
 108 returns 0 when all of the I/O operations have completed successfully.
 109 Otherwise, \-1 is returned, and
 110 .I errno
 111 is set to indicate the error.
 112 .PP
 113 The return status from
 114 .BR lio_listio ()
 115 provides information only about the call itself,
 116 not about the individual I/O operations.
 117 One or more of the I/O operations may fail,
 118 but this does not prevent other operations completing.
 119 The status of individual I/O operations in
 120 .I aiocb_list
 121 can be determined using
 122 .BR aio_error (3).
 123 When an operation has completed,
 124 its return status can be obtained using
 125 .BR aio_return (3).
 126 Individual I/O operations can fail for the reasons described in
 127 .BR aio_read (3)
 128 and
 129 .BR aio_write (3).
 130 .SH ERRORS
 131 The
 132 .BR lio_listio ()
 133 function may fail for the following reasons:
 134 .TP
 135 .B EAGAIN
 136 Out of resources.
 137 .TP
 138 .B EAGAIN
 139 .\" Doesn't happen in glibc(?)
 140 The number of I/O operations specified by
 141 .I nitems
 142 would cause the limit
 143 .B AIO_MAX
 144 to be exceeded.
 145 .TP
 146 .B EINTR
 147 .I mode
 148 was
 149 .B LIO_WAIT
 150 and a signal
 151 was caught before all I/O operations completed; see
 152 .BR signal (7).
 153 (This may even be one of the signals used for
 154 asynchronous I/O completion notification.)
 155 .TP
 156 .B EINVAL
 157 .I mode
 158 is invalid, or
 159 .\" Doesn't happen in glibc(?)
 160 .I nitems
 161 exceeds the limit
 162 .BR AIO_LISTIO_MAX .
 163 .TP
 164 .B EIO
 165 One of more of the operations specified by
 166 .I aiocb_list
 167 failed.
 168 .\" e.g., ioa_reqprio or aio_lio_opcode was invalid
 169 The application can check the status of each operation using
 170 .BR aio_return (3).
 171 .PP
 172 If
 173 .BR lio_listio ()
 174 fails with the error
 175 .BR EAGAIN ,
 176 .BR EINTR ,
 177 or
 178 .BR EIO ,
 179 then some of the operations in
 180 .I aiocb_list
 181 may have been initiated.
 182 If
 183 .BR lio_listio ()
 184 fails for any other reason,
 185 then none of the I/O operations has been initiated.
 186 .SH ATTRIBUTES
 187 For an explanation of the terms used in this section, see
 188 .BR attributes (7).
 189 .ad l
 190 .nh
 191 .TS
 192 allbox;
 193 lbx lb lb
 194 l l l.
 195 Interface       Attribute       Value
 196 T{
 197 .BR lio_listio ()
 198 T}      Thread safety   MT-Safe
 199 .TE
 200 .hy
 201 .ad
 202 .sp 1
 203 .SH STANDARDS
 204 POSIX.1-2008.
 205 .SH HISTORY
 206 glibc 2.1.
 207 POSIX.1-2001.
 208 .SH NOTES
 209 It is a good idea to zero out the control blocks before use.
 210 The control blocks must not be changed while the I/O operations
 211 are in progress.
 212 The buffer areas being read into or written from
 213 .\" or the control block of the operation
 214 must not be accessed during the operations or undefined results may occur.
 215 The memory areas involved must remain valid.
 216 .PP
 217 Simultaneous I/O operations specifying the same
 218 .I aiocb
 219 structure produce undefined results.
 220 .SH SEE ALSO
 221 .BR aio_cancel (3),
 222 .BR aio_error (3),
 223 .BR aio_fsync (3),
 224 .BR aio_return (3),
 225 .BR aio_suspend (3),
 226 .BR aio_write (3),
 227 .BR aio (7)