original/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 2012-05-08  "" "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
  31 .BI "int lio_listio(int " mode ", struct aiocb *const " aiocb_list [],
  32 .BI "               int " nitems ", struct sigevent *" sevp );
  33
  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
  42 The
  43 .I mode
  44 operation has one of the following values:
  45 .TP 12
  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
  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 10
  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
 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
 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 EINVAL
 163 .I mode
 164 is invalid, or
 165 .\" Doesn't happen in glibc(?)
 166 .I nitems
 167 exceeds the limit
 168 .BR AIO_LISTIO_MAX .
 169 .TP
 170 .B EINTR
 171 .I mode
 172 was
 173 .BR LIO_WAIT
 174 and a signal
 175 was caught before all I/O operations completed.
 176 (This may even be one of the signals used for
 177 asynchronous I/O completion notification.)
 178 .TP
 179 .B EIO
 180 One of more of the operations specified by
 181 .IR aiocb_list
 182 failed.
 183 .\" e.g., ioa_reqprio or aio_lio_opcode was invalid
 184 The application can check the status of each operation using
 185 .BR aio_return (3).
 186 .PP
 187 If
 188 .BR lio_listio ()
 189 fails with the error
 190 .BR EAGAIN ,
 191 .BR EINTR ,
 192 or
 193 .BR EIO ,
 194 then some of the operations in
 195 .IR aiocb_list
 196 may have been initiated.
 197 If
 198 .BR lio_listio ()
 199 fails for any other reason,
 200 then none of the I/O operations has been initiated.
 201 .SH VERSIONS
 202 The
 203 .BR lio_listio ()
 204 function is available since glibc 2.1.
 205 .SH CONFORMING TO
 206 POSIX.1-2001, POSIX.1-2008.
 207 .SH NOTES
 208 It is a good idea to zero out the control blocks before use.
 209 The control blocks must not be changed while the I/O operations
 210 are in progress.
 211 The buffer areas being read into or written from
 212 .\" or the control block of the operation
 213 must not be accessed during the operations or undefined results may occur.
 214 The memory areas involved must remain valid.
 215
 216 Simultaneous I/O operations specifying the same
 217 .I aiocb
 218 structure produce undefined results.
 219 .SH SEE ALSO
 220 .BR aio_cancel (3),
 221 .BR aio_error (3),
 222 .BR aio_fsync (3),
 223 .BR aio_return (3),
 224 .BR aio_suspend (3),
 225 .BR aio_write (3),
 226 .BR aio (7)
 227 .SH COLOPHON
 228 This page is part of release 3.67 of the Linux
 229 .I man-pages
 230 project.
 231 A description of the project,
 232 information about reporting bugs,
 233 and the latest version of this page,
 234 can be found at
 235 \%http://www.kernel.org/doc/man\-pages/.