Debian Codegraph @

upstream/debian-unstable/man3/lio_listio.3

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