ia64/xen-unstable

view tools/libaio/man/lio_listio.3 @ 10736:2937703f0ed0

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