man3/lio_listio.3

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