]>
Commit | Line | Data |
---|---|---|
00b30181 MK |
1 | .\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" | |
1dd72f9c | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
00b30181 MK |
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. | |
8 | .\" | |
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. | |
13 | .\" | |
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. | |
18 | .\" | |
19 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
20 | .\" License along with this manual; if not, see |
21 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 22 | .\" %%%LICENSE_END |
00b30181 | 23 | .\" |
4b8c67d9 | 24 | .TH LIO_LISTIO 3 2017-09-15 "" "Linux Programmer's Manual" |
00b30181 MK |
25 | .SH NAME |
26 | lio_listio \- initiate a list of I/O requests | |
27 | .SH SYNOPSIS | |
28 | .nf | |
29 | .B "#include <aio.h>" | |
dbfe9c70 | 30 | .PP |
00b30181 MK |
31 | .BI "int lio_listio(int " mode ", struct aiocb *const " aiocb_list [], |
32 | .BI " int " nitems ", struct sigevent *" sevp ); | |
dbfe9c70 | 33 | .PP |
00b30181 MK |
34 | Link with \fI\-lrt\fP. |
35 | .fi | |
36 | .SH DESCRIPTION | |
37 | The | |
38 | .BR lio_listio () | |
39 | function initiates the list of I/O operations described by the array | |
40 | .IR aiocb_list . | |
847e0d88 | 41 | .PP |
00b30181 MK |
42 | The |
43 | .I mode | |
44 | operation has one of the following values: | |
45 | .TP 12 | |
46 | .B LIO_WAIT | |
47 | The call blocks until all operations are complete. | |
48 | The | |
49 | .I sevp | |
50 | argument is ignored. | |
51 | .TP | |
52 | .B LIO_NOWAIT | |
53 | The I/O operations are queued for processing and the call returns immediately. | |
9dacae96 | 54 | When all of the I/O operations complete, asynchronous notification occurs, |
00b30181 MK |
55 | as specified by the |
56 | .IR sevp | |
57 | argument; see | |
58 | .BR sigevent (7) | |
59 | for details. | |
60 | If | |
61 | .IR sevp | |
62 | is NULL, no asynchronous notification occurs. | |
63 | .PP | |
64 | The | |
65 | .I aiocb_list | |
66 | argument is an array of pointers to | |
67 | .I aiocb | |
68 | structures that describe I/O operations. | |
69 | These operations are executed in an unspecified order. | |
70 | The | |
71 | .I nitems | |
72 | argument specifies the size of the array | |
73 | .IR aiocb_list . | |
b437fdd9 | 74 | null pointers in |
00b30181 MK |
75 | .I aiocb_list |
76 | are ignored. | |
847e0d88 | 77 | .PP |
00b30181 MK |
78 | In each control block in |
79 | .IR aiocb_list , | |
80 | the | |
81 | .I aio_lio_opcode | |
82 | field specifies the I/O operation to be initiated, as follows: | |
83 | .TP 10 | |
84 | .BR LIO_READ | |
85 | Initiate a read operation. | |
86 | The operation is queued as for a call to | |
87 | .BR aio_read (3) | |
88 | specifying this control block. | |
89 | .TP | |
90 | .BR LIO_WRITE | |
91 | Initiate a write operation. | |
92 | The operation is queued as for a call to | |
93 | .BR aio_write (3) | |
94 | specifying this control block. | |
95 | .TP | |
96 | .BR LIO_NOP | |
97 | Ignore this control block. | |
98 | .PP | |
99 | The remaining fields in each control block have the same meanings as for | |
100 | .BR aio_read (3) | |
101 | and | |
102 | .BR aio_write (3). | |
103 | The | |
104 | .I aio_sigevent | |
105 | fields of each control block can be used to specify notifications | |
106 | for the individual I/O operations (see | |
107 | .BR sigevent (7)). | |
108 | .SH RETURN VALUE | |
109 | If | |
110 | .I mode | |
111 | is | |
112 | .BR LIO_NOWAIT , | |
113 | .BR lio_listio () | |
114 | returns 0 if all I/O operations are successfully queued. | |
115 | Otherwise, \-1 is returned, and | |
116 | .I errno | |
117 | is set to indicate the error. | |
847e0d88 | 118 | .PP |
00b30181 MK |
119 | If |
120 | .I mode | |
121 | is | |
122 | .BR LIO_WAIT , | |
123 | .BR lio_listio () | |
124 | returns 0 when all of the I/O operations have completed successfully. | |
125 | Otherwise, \-1 is returned, and | |
126 | .I errno | |
127 | is set to indicate the error. | |
847e0d88 | 128 | .PP |
00b30181 MK |
129 | The return status from |
130 | .BR lio_listio () | |
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 | |
136 | .IR aiocb_list | |
137 | can be determined using | |
138 | .BR aio_error (3). | |
139 | When an operation has completed, | |
140 | its return status can be obtained using | |
141 | .BR aio_return (3). | |
142 | Individual I/O operations can fail for the reasons described in | |
143 | .BR aio_read (3) | |
144 | and | |
145 | .BR aio_write (3). | |
146 | .SH ERRORS | |
147 | The | |
148 | .BR lio_listio () | |
149 | function may fail for the following reasons: | |
150 | .TP | |
151 | .B EAGAIN | |
152 | Out of resources. | |
153 | .TP | |
154 | .B EAGAIN | |
155 | .\" Doesn't happen in glibc(?) | |
156 | The number of I/O operations specified by | |
157 | .I nitems | |
158 | would cause the limit | |
159 | .BR AIO_MAX | |
160 | to be exceeded. | |
161 | .TP | |
00b30181 MK |
162 | .B EINTR |
163 | .I mode | |
164 | was | |
165 | .BR LIO_WAIT | |
166 | and a signal | |
bb14af39 MK |
167 | was caught before all I/O operations completed; see |
168 | .BR signal (7). | |
00b30181 MK |
169 | (This may even be one of the signals used for |
170 | asynchronous I/O completion notification.) | |
171 | .TP | |
6b0d93ef MK |
172 | .B EINVAL |
173 | .I mode | |
174 | is invalid, or | |
175 | .\" Doesn't happen in glibc(?) | |
176 | .I nitems | |
177 | exceeds the limit | |
178 | .BR AIO_LISTIO_MAX . | |
179 | .TP | |
00b30181 MK |
180 | .B EIO |
181 | One of more of the operations specified by | |
182 | .IR aiocb_list | |
183 | failed. | |
184 | .\" e.g., ioa_reqprio or aio_lio_opcode was invalid | |
185 | The application can check the status of each operation using | |
186 | .BR aio_return (3). | |
187 | .PP | |
188 | If | |
189 | .BR lio_listio () | |
190 | fails with the error | |
191 | .BR EAGAIN , | |
192 | .BR EINTR , | |
193 | or | |
194 | .BR EIO , | |
195 | then some of the operations in | |
196 | .IR aiocb_list | |
197 | may have been initiated. | |
198 | If | |
199 | .BR lio_listio () | |
200 | fails for any other reason, | |
201 | then none of the I/O operations has been initiated. | |
202 | .SH VERSIONS | |
203 | The | |
204 | .BR lio_listio () | |
205 | function is available since glibc 2.1. | |
2fdbf140 MS |
206 | .SH ATTRIBUTES |
207 | For an explanation of the terms used in this section, see | |
208 | .BR attributes (7). | |
209 | .TS | |
210 | allbox; | |
211 | lb lb lb | |
212 | l l l. | |
213 | Interface Attribute Value | |
214 | T{ | |
215 | .BR lio_listio () | |
216 | T} Thread safety MT-Safe | |
217 | .TE | |
847e0d88 | 218 | .sp 1 |
47297adb | 219 | .SH CONFORMING TO |
00b30181 MK |
220 | POSIX.1-2001, POSIX.1-2008. |
221 | .SH NOTES | |
222 | It is a good idea to zero out the control blocks before use. | |
223 | The control blocks must not be changed while the I/O operations | |
224 | are in progress. | |
225 | The buffer areas being read into or written from | |
226 | .\" or the control block of the operation | |
227 | must not be accessed during the operations or undefined results may occur. | |
228 | The memory areas involved must remain valid. | |
847e0d88 | 229 | .PP |
00b30181 MK |
230 | Simultaneous I/O operations specifying the same |
231 | .I aiocb | |
232 | structure produce undefined results. | |
47297adb | 233 | .SH SEE ALSO |
00b30181 MK |
234 | .BR aio_cancel (3), |
235 | .BR aio_error (3), | |
236 | .BR aio_fsync (3), | |
237 | .BR aio_return (3), | |
238 | .BR aio_suspend (3), | |
239 | .BR aio_write (3), | |
240 | .BR aio (7) |