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