| blob | 9159532e3bedc15e2ea3e106eb105ccb2a3c4c40 |
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 AIO_READ 3C "Feb 5, 2008"
48 .SH NAME
49 aio_read \- asynchronous read from a file
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <aio.h>
55 \fBint\fR \fBaio_read\fR(\fBstruct aiocb *\fR\fIaiocbp\fR);
56 .fi
58 .SH DESCRIPTION
59 .sp
60 .LP
61 The \fBaio_read()\fR function allows the calling process to read
62 \fIaiocbp\fR->\fBaio_nbytes\fR from the file associated with
63 \fIaiocbp\fR->\fBaio_fildes\fR into the buffer pointed to by
64 \fIaiocbp\fR->\fBaio_buf\fR. The function call returns when the read request
65 has been initiated or queued to the file or device (even when the data cannot
66 be delivered immediately). If \fB_POSIX_PRIORITIZED_IO\fR is defined and
67 prioritized I/O is supported for this file, then the asynchronous operation is
68 submitted at a priority equal to the scheduling priority of the process minus
69 \fIaiocbp\fR->\fBaio_reqprio\fR. The \fIaiocbp\fR value may be used as an
70 argument to \fBaio_error\fR(3C) and \fBaio_return\fR(3C) in order to determine
71 the error status and return status, respectively, of the asynchronous operation
72 while it is proceeding. If an error condition is encountered during queuing,
73 the function call returns without having initiated or queued the request. The
74 requested operation takes place at the absolute position in the file as given
75 by \fIaio_offset\fR, as if \fBlseek\fR(2) were called immediately prior to the
76 operation with an \fIoffset\fR equal to \fIaio_offset\fR and a \fBwhence\fR
77 equal to \fBSEEK_SET\fR. After a successful call to enqueue an asynchronous I/O
78 operation, the value of the file offset for the file is unspecified.
79 .sp
80 .LP
81 The \fIaiocbp\fR->\fBaio_sigevent\fR structure defines what asynchronous
82 notification is to occur when the asynchronous operation completes, as
83 specified in \fBsignal.h\fR(3HEAD).
84 .sp
85 .LP
86 The \fIaiocbp\fR->\fBaio_lio_opcode\fR field is ignored by \fBaio_read()\fR.
87 .sp
88 .LP
89 The \fIaiocbp\fR argument points to an \fBaiocb\fR structure. If the buffer
90 pointed to by \fIaiocbp\fR->\fBaio_buf\fR or the control block pointed to by
91 \fIaiocbp\fR becomes an illegal address prior to asynchronous I/O completion,
92 then the behavior is undefined.
93 .sp
94 .LP
95 Simultaneous asynchronous operations using the same \fIaiocbp\fR produce
96 undefined results.
97 .sp
98 .LP
99 If \fB_POSIX_SYNCHRONIZED_IO\fR is defined and synchronized I/O is enabled on
100 the file associated with \fIaiocbp\fR->\fBaio_fildes,\fR the behavior of this
101 function is according to the definitions of synchronized I/O data integrity
102 completion and synchronized I/O file integrity completion.
103 .sp
104 .LP
105 For any system action that changes the process memory space while an
106 asynchronous I/O is outstanding to the address range being changed, the result
107 of that action is undefined.
108 .sp
109 .LP
110 For regular files, no data transfer will occur past the offset maximum
111 established in the open file description associated with
112 \fIaiocbp\fR->\fBaio_fildes\fR.
113 .SH RETURN VALUES
114 .sp
115 .LP
116 The \fBaio_read()\fR function returns \fB0\fR to the calling process if the I/O
117 operation is successfully queued; otherwise, the function returns \fB\(mi1\fR
118 and sets \fBerrno\fR to indicate the error.
119 .SH ERRORS
120 .sp
121 .LP
122 The \fBaio_read()\fR function will fail if:
123 .sp
124 .ne 2
125 .na
126 \fB\fBEAGAIN\fR\fR
127 .ad
128 .RS 10n
129 The requested asynchronous I/O operation was not queued due to system resource
130 limitations.
131 .RE
133 .sp
134 .LP
135 Each of the following conditions may be detected synchronously at the time of
136 the call to \fBaio_read()\fR, or asynchronously. If any of the conditions below
137 are detected synchronously, the \fBaio_read()\fR function returns \fB-1\fR and
138 sets \fBerrno\fR to the corresponding value. If any of the conditions below are
139 detected asynchronously, the return status of the asynchronous operation is set
140 to \(mi1, and the error status of the asynchronous operation will be set to the
141 corresponding value.
142 .sp
143 .ne 2
144 .na
145 \fB\fBEBADF\fR\fR
146 .ad
147 .RS 10n
148 The \fIaiocbp\fR->\fBaio_fildes\fR argument is not a valid file descriptor open
149 for reading.
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fB\fBEINVAL\fR\fR
156 .ad
157 .RS 10n
158 The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be
159 invalid, \fIaiocbp->\fR\fBaio_reqprio\fR is not a valid value, or
160 \fIaiocbp\fR->\fBaio_nbytes\fR is an invalid value.
161 .RE
163 .sp
164 .LP
165 In the case that the \fBaio_read()\fR successfully queues the I/O operation but
166 the operation is subsequently canceled or encounters an error, the return
167 status of the asynchronous operation is one of the values normally returned by
168 the \fBread\fR(2) function call. In addition, the error status of the
169 asynchronous operation will be set to one of the error statuses normally set by
170 the \fBread()\fR function call, or one of the following values:
171 .sp
172 .ne 2
173 .na
174 \fB\fBEBADF\fR\fR
175 .ad
176 .RS 13n
177 The \fIaiocbp\fR->\fBaio_fildes\fR argument is not a valid file descriptor open
178 for reading.
179 .RE
181 .sp
182 .ne 2
183 .na
184 \fB\fBECANCELED\fR\fR
185 .ad
186 .RS 13n
187 The requested I/O was canceled before the I/O completed due to an explicit
188 \fBaio_cancel\fR(3C) request.
189 .RE
191 .sp
192 .ne 2
193 .na
194 \fB\fBEINVAL\fR\fR
195 .ad
196 .RS 13n
197 The file offset value implied by \fIaiocbp\fR->\fBaio_offset\fR would be
198 invalid.
199 .RE
201 .sp
202 .LP
203 The following condition may be detected synchronously or asynchronously:
204 .sp
205 .ne 2
206 .na
207 \fB\fBEOVERFLOW\fR\fR
208 .ad
209 .RS 13n
210 The file is a regular file, \fIaiobcp\fR->\fBaio_nbytes\fR is greater than 0
211 and the starting offset in \fIaiobcp\fR->\fBaio_offset\fR is before the
212 end-of-file and is at or beyond the offset maximum in the open file description
213 associated with \fIaiocbp\fR->\fBaio_fildes\fR.
214 .RE
216 .SH USAGE
217 .sp
218 .LP
219 For portability, the application should set \fIaiocb->\fR\fBaio_reqprio\fR to
220 \fB0\fR.
221 .SH ATTRIBUTES
222 .sp
223 .LP
224 See \fBattributes\fR(5) for descriptions of the following attributes:
225 .sp
227 .sp
228 .TS
229 box;
230 c | c
231 l | l .
232 ATTRIBUTE TYPE ATTRIBUTE VALUE
233 _
234 Interface Stability Committed
235 _
236 MT-Level MT-Safe
237 _
238 Standard See \fBstandards\fR(5).
239 .TE
241 .SH SEE ALSO
242 .sp
243 .LP
244 \fBclose\fR(2), \fBexec\fR(2), \fBexit\fR(2), \fBfork\fR(2), \fBlseek\fR(2),
245 \fBread\fR(2), \fBwrite\fR(2), \fBaio_cancel\fR(3C), \fBaio_return\fR(3C),
246 \fBaio.h\fR(3HEAD), \fBlio_listio\fR(3C), \fBsiginfo.h\fR(3HEAD),
247 \fBsignal.h\fR(3HEAD), \fBattributes\fR(5), \fBstandards\fR(5)