1 .\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com>
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.
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.
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.
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/>.
24 .TH LIO_LISTIO 3 2012-05-08 "" "Linux Programmer's Manual"
26 lio_listio \- initiate a list of I/O requests
31 .BI "int lio_listio(int " mode ", struct aiocb *const " aiocb_list [],
32 .BI " int " nitems ", struct sigevent *" sevp );
34 Link with \fI\-lrt\fP.
39 function initiates the list of I/O operations described by the array
44 operation has one of the following values:
47 The call blocks until all operations are complete.
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,
62 is NULL, no asynchronous notification occurs.
66 argument is an array of pointers to
68 structures that describe I/O operations.
69 These operations are executed in an unspecified order.
72 argument specifies the size of the array
78 In each control block in
82 field specifies the I/O operation to be initiated, as follows:
85 Initiate a read operation.
86 The operation is queued as for a call to
88 specifying this control block.
91 Initiate a write operation.
92 The operation is queued as for a call to
94 specifying this control block.
97 Ignore this control block.
99 The remaining fields in each control block have the same meanings as for
105 fields of each control block can be used to specify notifications
106 for the individual I/O operations (see
114 returns 0 if all I/O operations are successfully queued.
115 Otherwise, \-1 is returned, and
117 is set to indicate the error.
124 returns 0 when all of the I/O operations have completed successfully.
125 Otherwise, \-1 is returned, and
127 is set to indicate the error.
129 The return status from
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
137 can be determined using
139 When an operation has completed,
140 its return status can be obtained using
142 Individual I/O operations can fail for the reasons described in
149 function may fail for the following reasons:
155 .\" Doesn't happen in glibc(?)
156 The number of I/O operations specified by
158 would cause the limit
165 .\" Doesn't happen in glibc(?)
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.)
180 One of more of the operations specified by
183 .\" e.g., ioa_reqprio or aio_lio_opcode was invalid
184 The application can check the status of each operation using
194 then some of the operations in
196 may have been initiated.
199 fails for any other reason,
200 then none of the I/O operations has been initiated.
204 function is available since glibc 2.1.
206 POSIX.1-2001, POSIX.1-2008.
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
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.
216 Simultaneous I/O operations specifying the same
218 structure produce undefined results.