| blob | f785269bc129d524812ce23aefec43fce0de393e |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved.
45 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH LIO_LISTIO 3C "Feb 5, 2008"
48 .SH NAME
49 lio_listio \- list directed I/O
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <aio.h>
55 \fBint\fR \fBlio_listio\fR(\fBint\fR \fImode\fR, \fBstruct aiocb *restrict const\fR \fIlist\fR[],
56 \fBint\fR \fInent\fR, \fBstruct sigevent *restrict\fR \fIsig\fR);
57 .fi
59 .SH DESCRIPTION
60 .sp
61 .LP
62 The \fBlio_listio()\fR function allows the calling process, LWP, or thread, to
63 initiate a list of I/O requests within a single function call.
64 .sp
65 .LP
66 The \fImode\fR argument takes one of the values \fBLIO_WAIT\fR or
67 \fBLIO_NOWAIT\fR declared in <\fBaio.h\fR> and determines whether the function
68 returns when the I/O operations have been completed, or as soon as the
69 operations have been queued. If the \fImode\fR argument is \fBLIO_WAIT\fR, the
70 function waits until all I/O is complete and the \fIsig\fR argument is ignored.
71 .sp
72 .LP
73 If the \fImode\fR argument is \fBLIO_NOWAIT\fR, the function returns
74 immediately, and asynchronous notification occurs, according to the \fIsig\fR
75 argument, when all the I/O operations complete. If \fIsig\fR is \fINULL\fR, no
76 asynchronous notification occurs. If \fIsig\fR is not \fINULL\fR, asynchronous
77 notification occurs as specified in \fBsignal.h\fR(3HEAD) when all the requests
78 in \fIlist\fR have completed.
79 .sp
80 .LP
81 The I/O requests enumerated by \fIlist\fR are submitted in an unspecified
82 order.
83 .sp
84 .LP
85 The \fIlist\fR argument is an array of pointers to \fBaiocb\fR structures. The
86 array contains \fInent\fR elements. The array may contain null elements, which
87 are ignored.
88 .sp
89 .LP
90 The \fIaio_lio_opcode\fR field of each \fBaiocb\fR structure specifies the
91 operation to be performed. The supported operations are \fBLIO_READ\fR,
92 \fBLIO_WRITE\fR, and \fBLIO_NOP\fR; these symbols are defined in <\fBaio.h\fR>.
93 The \fBLIO_NOP\fR operation causes the list entry to be ignored. If the
94 \fIaio_lio_opcode\fR element is equal to \fBLIO_READ,\fR then an I/O operation
95 is submitted as if by a call to \fBaio_read\fR(3C) with the \fIaiocbp\fR equal
96 to the address of the \fBaiocb\fR structure. If the \fIaio_lio_opcode\fR
97 element is equal to \fBLIO_WRITE\fR, then an I/O operation is submitted as if
98 by a call to \fBaio_write\fR(3C) with the \fIaiocbp\fR equal to the address of
99 the \fBaiocb\fR structure.
100 .sp
101 .LP
102 The \fIaio_fildes\fR member specifies the file descriptor on which the
103 operation is to be performed.
104 .sp
105 .LP
106 The \fIaio_buf\fR member specifies the address of the buffer to or from which
107 the data is to be transferred.
108 .sp
109 .LP
110 The \fIaio_nbytes\fR member specifies the number of bytes of data to be
111 transferred.
112 .sp
113 .LP
114 The members of the \fIaiocb\fR structure further describe the I/O operation to
115 be performed, in a manner identical to that of the corresponding \fBaiocb\fR
116 structure when used by the \fBaio_read\fR(3C) and \fBaio_write\fR(3C)
117 functions.
118 .sp
119 .LP
120 The \fInent\fR argument specifies how many elements are members of the list,
121 that is, the length of the array.
122 .sp
123 .LP
124 The behavior of this function is altered according to the definitions of
125 synchronized I/O data integrity completion and synchronized I/O file integrity
126 completion if synchronized I/O is enabled on the file associated with
127 \fBaio_fildes\fR. See \fBfcntl.h\fR(3HEAD) definitions of \fBO_DSYNC\fR and
128 \fBO_SYNC\fR.
129 .sp
130 .LP
131 For regular files, no data transfer will occur past the offset maximum
132 established in the open file description associated with
133 \fIaiocbp\fR\(->\fBaio_fildes\fR.
134 .SH RETURN VALUES
135 .sp
136 .LP
137 If the \fImode\fR argument has the value \fBLIO_NOWAIT\fR, and the I/O
138 operations are successfully queued, \fBlio_listio()\fR returns \fB0\fR;
139 otherwise, it returns \fB\(mi1\fR, and sets \fBerrno\fR to indicate the error.
140 .sp
141 .LP
142 If the \fImode\fR argument has the value \fBLIO_WAIT\fR, and all the
143 indicated I/O has completed successfully, \fBlio_listio()\fR returns \fB0\fR;
144 otherwise, it returns \fB\(mi1\fR, and sets \fBerrno\fR to indicate the error.
145 .sp
146 .LP
147 In either case, the return value only indicates the success or failure of the
148 \fBlio_listio()\fR call itself, not the status of the individual I/O requests.
149 In some cases, one or more of the I/O requests contained in the list may fail.
150 Failure of an individual request does not prevent completion of any other
151 individual request. To determine the outcome of each I/O request, the
152 application must examine the error status associated with each \fIaiocb\fR
153 control block. Each error status so returned is identical to that returned as
154 a result of an \fBaio_read\fR(3C) or \fBaio_write\fR(3C) function.
155 .SH ERRORS
156 .sp
157 .LP
158 The \fBlio_listio()\fR function will fail if:
159 .sp
160 .ne 2
161 .na
162 \fB\fBEAGAIN\fR\fR
163 .ad
164 .RS 10n
165 The resources necessary to queue all the I/O requests were not available. The
166 error status for each request is recorded in the \fBaio_error\fR member of the
167 corresponding \fBaiocb\fR structure, and can be retrieved using
168 \fBaio_error\fR(3C).
169 .RE
171 .sp
172 .ne 2
173 .na
174 \fB\fBEAGAIN\fR\fR
175 .ad
176 .RS 10n
177 The number of entries indicated by \fInent\fR would cause the system-wide limit
178 \fBAIO_MAX\fR to be exceeded.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fBEINVAL\fR\fR
185 .ad
186 .RS 10n
187 The \fImode\fR argument is an improper value, or the value of \fInent\fR is
188 greater than \fBAIO_LISTIO_MAX\fR.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBEINTR\fR\fR
195 .ad
196 .RS 10n
197 A signal was delivered while waiting for all I/O requests to complete during an
198 \fBLIO_WAIT\fR operation. Note that, since each I/O operation invoked by
199 \fBlio_listio()\fR may possibly provoke a signal when it completes, this error
200 return may be caused by the completion of one (or more) of the very I/O
201 operations being awaited. Outstanding I/O requests are not canceled, and the
202 application can use \fBaio_fsync\fR(3C) to determine if any request was
203 initiated; \fBaio_return\fR(3C) to determine if any request has completed; or
204 \fBaio_error\fR(3C) to determine if any request was canceled.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fBEIO\fR\fR
211 .ad
212 .RS 10n
213 One or more of the individual I/O operations failed. The application can use
214 \fBaio_error\fR(3C) to check the error status for each \fBaiocb\fR structure to
215 determine the individual request(s) that failed.
216 .RE
218 .sp
219 .LP
220 In addition to the errors returned by the \fBlio_listio()\fR function, if the
221 \fBlio_listio()\fR function succeeds or fails with errors of \fBEAGAIN\fR,
222 \fBEINTR\fR, or \fBEIO\fR, then some of the I/O specified by the list may have
223 been initiated. If the \fBlio_listio()\fR function fails with an error code
224 other than \fBEAGAIN\fR, \fBEINTR\fR, or \fBEIO\fR, no operations from the list
225 have been initiated. The I/O operation indicated by each list element can
226 encounter errors specific to the individual read or write function being
227 performed. In this event, the error status for each \fBaiocb\fR control block
228 contains the associated error code. The error codes that can be set are the
229 same as would be set by a \fBread\fR(2) or \fBwrite\fR(2) function, with the
230 following additional error codes possible:
231 .sp
232 .ne 2
233 .na
234 \fB\fBEAGAIN\fR\fR
235 .ad
236 .RS 15n
237 The requested I/O operation was not queued due to resource limitations.
238 .RE
240 .sp
241 .ne 2
242 .na
243 \fB\fBECANCELED\fR\fR
244 .ad
245 .RS 15n
246 The requested I/O was canceled before the I/O completed due to an explicit
247 \fBaio_cancel\fR(3C) request.
248 .RE
250 .sp
251 .ne 2
252 .na
253 \fB\fBEFBIG\fR\fR
254 .ad
255 .RS 15n
256 The \fIaiocbp\fR\(->\fBaio_lio_opcode\fR is \fBLIO_WRITE\fR, the file is a
257 regular file, \fIaiocbp\fR\(->\fBaio_nbytes\fR is greater than 0, and the
258 \fIaiocbp\fR\(->\fBaio_offset\fR is greater than or equal to the offset maximum
259 in the open file description associated with \fIaiocbp\fR\(->\fBaio_fildes.\fR
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fBEINPROGRESS\fR\fR
266 .ad
267 .RS 15n
268 The requested I/O is in progress.
269 .RE
271 .sp
272 .ne 2
273 .na
274 \fB\fBEOVERFLOW\fR\fR
275 .ad
276 .RS 15n
277 The \fIaiocbp\fR\(->\fBaio_lio_opcode\fR is \fBLIO_READ\fR, the file is a
278 regular file, \fIaiocbp\fR\(->\fBaio_nbytes\fR is greater than 0, and the
279 \fIaiocbp\fR\(->\fBaio_offset\fR is before the end-of-file and is greater than
280 or equal to the offset maximum in the open file description associated with
281 \fIaiocbp\fR\(->\fBaio_fildes.\fR
282 .RE
284 .SH USAGE
285 .sp
286 .LP
287 The \fBlio_listio()\fR function has a transitional interface for 64-bit file
288 offsets. See \fBlf64\fR(5).
289 .SH ATTRIBUTES
290 .sp
291 .LP
292 See \fBattributes\fR(5) for descriptions of the following attributes:
293 .sp
295 .sp
296 .TS
297 box;
298 c | c
299 l | l .
300 ATTRIBUTE TYPE ATTRIBUTE VALUE
301 _
302 Interface Stability Committed
303 _
304 MT-Level MT-Safe
305 _
306 Standard See \fBstandards\fR(5).
307 .TE
309 .SH SEE ALSO
310 .sp
311 .LP
312 \fBclose\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBlseek\fR(2),
313 \fBread\fR(2), \fBwrite\fR(2), \fBaio_cancel\fR(3C), \fBaio_error\fR(3C),
314 \fBaio_fsync\fR(3C), \fBaio_read\fR(3C), \fBaio_return\fR(3C),
315 \fBaio_write\fR(3C), \fBaio.h\fR(3HEAD), \fBfcntl.h\fR(3HEAD),
316 \fBsiginfo.h\fR(3HEAD), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5),
317 \fBlf64\fR(5), \fBstandards\fR(5)