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