1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
.TH lio_listio 3 2002-09-12 "Linux 2.4" Linux AIO"
.SH NAME
lio_listio - List directed I/O
.SH SYNOPSYS
.B #include <errno.h>
.br
.B #include <libaio.h>
.LP
.BI "int lio_listio (int mode, struct aiocb *const list[], int nent, struct sigevent *sig)"
.nf
.SH DESCRIPTION
Besides these functions with the more or less traditional interface,
POSIX.1b also defines a function which can initiate more than one
operation at a time, and which can handle freely mixed read and write
operations. It is therefore similar to a combination of
.IR readv
and
.IR "writev"
.
The
.IR "lio_listio"
function can be used to enqueue an arbitrary
number of read and write requests at one time. The requests can all be
meant for the same file, all for different files or every solution in
between.
.IR "lio_listio"
gets the
.IR "nent"
requests from the array pointed to
by
.IR "list"
. The operation to be performed is determined by the
.IR "aio_lio_opcode"
member in each element of
.IR "list"
. If this
field is
.B "LIO_READ"
a read operation is enqueued, similar to a call
of
.IR "aio_read"
for this element of the array (except that the way
the termination is signalled is different, as we will see below). If
the
.IR "aio_lio_opcode"
member is
.B "LIO_WRITE"
a write operation
is enqueued. Otherwise the
.IR "aio_lio_opcode"
must be
.B "LIO_NOP"
in which case this element of
.IR "list"
is simply ignored. This
``operation'' is useful in situations where one has a fixed array of
.IR "struct aiocb"
elements from which only a few need to be handled at
a time. Another situation is where the
.IR "lio_listio"
call was
canceled before all requests are processed and the remaining requests have to be reissued.
The other members of each element of the array pointed to by
.IR "list"
must have values suitable for the operation as described in
the documentation for
.IR "aio_read"
and
.IR "aio_write"
above.
The
.IR "mode"
argument determines how
.IR "lio_listio"
behaves after
having enqueued all the requests. If
.IR "mode"
is
.B "LIO_WAIT"
it
waits until all requests terminated. Otherwise
.IR "mode"
must be
.B "LIO_NOWAIT"
and in this case the function returns immediately after
having enqueued all the requests. In this case the caller gets a
notification of the termination of all requests according to the
.IR "sig"
parameter. If
.IR "sig"
is
.B "NULL"
no notification is
send. Otherwise a signal is sent or a thread is started, just as
described in the description for
.IR "aio_read"
or
.IR "aio_write"
.
When the sources are compiled with
.B "_FILE_OFFSET_BITS == 64"
, this
function is in fact
.IR "lio_listio64"
since the LFS interface
transparently replaces the normal implementation.
.SH "RETURN VALUES"
If
.IR "mode"
is
.B "LIO_WAIT"
, the return value of
.IR "lio_listio"
is
.IR 0
when all requests completed successfully. Otherwise the
function return
.IR 1
and
.IR "errno"
is set accordingly. To find
out which request or requests failed one has to use the
.IR "aio_error"
function on all the elements of the array
.IR "list"
.
In case
.IR "mode"
is
.B "LIO_NOWAIT"
, the function returns
.IR 0
if
all requests were enqueued correctly. The current state of the requests
can be found using
.IR "aio_error"
and
.IR "aio_return"
as described
above. If
.IR "lio_listio"
returns
.IR -1
in this mode, the
global variable
.IR "errno"
is set accordingly. If a request did not
yet terminate, a call to
.IR "aio_error"
returns
.B "EINPROGRESS"
. If
the value is different, the request is finished and the error value (or
.IR 0
) is returned and the result of the operation can be retrieved
using
.IR "aio_return"
.
.SH ERRORS
Possible values for
.IR "errno"
are:
.TP
.B EAGAIN
The resources necessary to queue all the requests are not available at
the moment. The error status for each element of
.IR "list"
must be
checked to determine which request failed.
Another reason could be that the system wide limit of AIO requests is
exceeded. This cannot be the case for the implementation on GNU systems
since no arbitrary limits exist.
.TP
.B EINVAL
The
.IR "mode"
parameter is invalid or
.IR "nent"
is larger than
.B "AIO_LISTIO_MAX"
.
.TP
.B EIO
One or more of the request's I/O operations failed. The error status of
each request should be checked to determine which one failed.
.TP
.B ENOSYS
The
.IR "lio_listio"
function is not supported.
.PP
If the
.IR "mode"
parameter is
.B "LIO_NOWAIT"
and the caller cancels
a request, the error status for this request returned by
.IR "aio_error"
is
.B "ECANCELED"
.
.SH "SEE ALSO"
.BR aio(3),
.BR aio_cancel(3),
.BR aio_cancel64(3),
.BR aio_error(3),
.BR aio_error64(3),
.BR aio_fsync(3),
.BR aio_fsync64(3),
.BR aio_init(3),
.BR aio_read(3),
.BR aio_read64(3),
.BR aio_return(3),
.BR aio_return64(3),
.BR aio_suspend(3),
.BR aio_suspend64(3),
.BR aio_write(3),
.BR aio_write64(3)
|
