2 .\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .TH lio_listio 3 (date) "Linux man-pages (unreleased)"
8 lio_listio \- initiate a list of I/O requests
11 .RI ( librt ", " \-lrt )
16 .BI "int lio_listio(int " mode ,
17 .BI " struct aiocb *restrict const " aiocb_list [restrict],
18 .BI " int " nitems ", struct sigevent *restrict " sevp );
23 function initiates the list of I/O operations described by the array
28 operation has one of the following values:
31 The call blocks until all operations are complete.
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,
46 is NULL, no asynchronous notification occurs.
50 argument is an array of pointers to
52 structures that describe I/O operations.
53 These operations are executed in an unspecified order.
56 argument specifies the size of the array
62 In each control block in
66 field specifies the I/O operation to be initiated, as follows:
69 Initiate a read operation.
70 The operation is queued as for a call to
72 specifying this control block.
75 Initiate a write operation.
76 The operation is queued as for a call to
78 specifying this control block.
81 Ignore this control block.
83 The remaining fields in each control block have the same meanings as for
89 fields of each control block can be used to specify notifications
90 for the individual I/O operations (see
98 returns 0 if all I/O operations are successfully queued.
99 Otherwise, \-1 is returned, and
101 is set to indicate the error.
108 returns 0 when all of the I/O operations have completed successfully.
109 Otherwise, \-1 is returned, and
111 is set to indicate the error.
113 The return status from
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
121 can be determined using
123 When an operation has completed,
124 its return status can be obtained using
126 Individual I/O operations can fail for the reasons described in
133 function may fail for the following reasons:
139 .\" Doesn't happen in glibc(?)
140 The number of I/O operations specified by
142 would cause the limit
151 was caught before all I/O operations completed; see
153 (This may even be one of the signals used for
154 asynchronous I/O completion notification.)
159 .\" Doesn't happen in glibc(?)
165 One of more of the operations specified by
168 .\" e.g., ioa_reqprio or aio_lio_opcode was invalid
169 The application can check the status of each operation using
179 then some of the operations in
181 may have been initiated.
184 fails for any other reason,
185 then none of the I/O operations has been initiated.
189 function is available since glibc 2.1.
191 For an explanation of the terms used in this section, see
199 Interface Attribute Value
202 T} Thread safety MT-Safe
208 POSIX.1-2001, POSIX.1-2008.
210 It is a good idea to zero out the control blocks before use.
211 The control blocks must not be changed while the I/O operations
213 The buffer areas being read into or written from
214 .\" or the control block of the operation
215 must not be accessed during the operations or undefined results may occur.
216 The memory areas involved must remain valid.
218 Simultaneous I/O operations specifying the same
220 structure produce undefined results.