1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
|
'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.\" 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.
.\" 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.
.\" 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]
.TH AIOREAD 3C "May 13, 2017"
.SH NAME
aioread, aiowrite \- read or write asynchronous I/O operations
.SH SYNOPSIS
.LP
.nf
#include <sys/types.h>
#include <sys/asynch.h>
\fBint\fR \fBaioread\fR(\fBint\fR \fIfildes\fR, \fBchar *\fR\fIbufp\fR, \fBint\fR \fIbufs\fR, \fBoff_t\fR \fIoffset\fR,
\fBint\fR \fIwhence\fR, \fBaio_result_t *\fR\fIresultp\fR);
.fi
.LP
.nf
\fBint\fR \fBaiowrite\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIbufp\fR, \fBint\fR \fIbufs\fR, \fBoff_t\fR \fIoffset\fR,
\fBint\fR \fIwhence\fR, \fBaio_result_t *\fR\fIresultp\fR);
.fi
.SH DESCRIPTION
.LP
The \fBaioread()\fR function initiates one asynchronous \fBread\fR(2) and
returns control to the calling program. The read continues concurrently with
other activity of the process. An attempt is made to read \fIbufs\fR bytes of
data from the object referenced by the descriptor \fIfildes\fR into the buffer
pointed to by \fIbufp\fR.
.sp
.LP
The \fBaiowrite()\fR function initiates one asynchronous \fBwrite\fR(2) and
returns control to the calling program. The write continues concurrently with
other activity of the process. An attempt is made to write \fIbufs\fR bytes of
data from the buffer pointed to by \fIbufp\fR to the object referenced by the
descriptor \fIfildes\fR.
.sp
.LP
On objects capable of seeking, the I/O operation starts at the position
specified by \fIwhence\fR and \fIoffset\fR. These parameters have the same
meaning as the corresponding parameters to the \fBllseek\fR(2) function. On
objects not capable of seeking the I/O operation always start from the current
position and the parameters \fBwhence\fR and \fIoffset\fR are ignored. The seek
pointer for objects capable of seeking is not updated by \fBaioread()\fR or
\fBaiowrite()\fR. Sequential asynchronous operations on these devices must be
managed by the application using the \fIwhence\fR and \fIoffset\fR parameters.
.sp
.LP
The result of the asynchronous operation is stored in the structure pointed to
by \fIresultp\fR:
.sp
.in +2
.nf
int aio_return; /* return value of read() or write() */
int aio_errno; /* value of errno for read() or write() */
.fi
.in -2
.sp
.LP
Upon completion of the operation both \fBaio_return\fR and \fBaio_errno\fR are
set to reflect the result of the operation. Since \fBAIO_INPROGRESS\fR is not a
value used by the system, the client can detect a change in state by
initializing \fBaio_return\fR to this value.
.sp
.LP
The application-supplied buffer \fIbufp\fR should not be referenced by the
application until after the operation has completed. While the operation is in
progress, this buffer is in use by the operating system.
.sp
.LP
Notification of the completion of an asynchronous I/O operation can be
obtained synchronously through the \fBaiowait\fR(3C) function, or
asynchronously by installing a signal handler for the \fBSIGIO\fR signal.
Asynchronous notification is accomplished by sending the process a \fBSIGIO\fR
signal. If a signal handler is not installed for the \fBSIGIO\fR signal,
asynchronous notification is disabled. The delivery of this instance of the
\fBSIGIO\fR signal is reliable in that a signal delivered while the handler is
executing is not lost. If the client ensures that \fBaiowait()\fR returns
nothing (using a polling timeout) before returning from the signal handler, no
asynchronous I/O notifications are lost. The \fBaiowait()\fR function is the
only way to dequeue an asynchronous notification. The \fBSIGIO\fR signal can
have several meanings simultaneously. For example, it can signify that a
descriptor generated \fBSIGIO\fR and an asynchronous operation completed.
Further, issuing an asynchronous request successfully guarantees that space
exists to queue the completion notification.
.sp
.LP
The \fBclose\fR(2), \fBexit\fR(2) and \fBexecve\fR(2)) functions block until
all pending asynchronous I/O operations can be canceled by the system.
.sp
.LP
It is an error to use the same result buffer in more than one outstanding
request. These structures can be reused only after the system has completed the
operation.
.SH RETURN VALUES
.LP
Upon successful completion, \fBaioread()\fR and \fBaiowrite()\fR return
\fB0\fR. Upon failure, \fBaioread()\fR and \fBaiowrite()\fR return \fB\(mi1\fR
and set \fBerrno\fR to indicate the error.
.SH ERRORS
.LP
The \fBaioread()\fR and \fBaiowrite()\fR functions will fail if:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 10n
The number of asynchronous requests that the system can handle at any one time
has been exceeded
.RE
.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 10n
The \fIfildes\fR argument is not a valid file descriptor open for reading.
.RE
.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 10n
At least one of \fIbufp\fR or \fIresultp\fR points to an address outside the
address space of the requesting process. This condition is reported only if
detected by the application process.
.RE
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIresultp\fR argument is currently being used by an outstanding
asynchronous request.
.RE
.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
The \fIoffset\fR argument is not a valid offset for this file system type.
.RE
.sp
.ne 2
.na
\fB\fBENOMEM\fR\fR
.ad
.RS 10n
Memory resources are unavailable to initiate request.
.RE
.SH USAGE
.LP
The \fBaioread()\fR and \fBaiowrite()\fR functions have transitional interfaces
for 64-bit file offsets. See \fBlf64\fR(7).
.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp
.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
MT-Level Safe
.TE
.SH SEE ALSO
.LP
.BR close (2),
.BR execve (2),
.BR exit (2),
.BR llseek (2),
.BR lseek (2),
.BR open (2),
.BR read (2),
.BR write (2),
.BR aiocancel (3C),
.BR aiowait (3C),
.BR attributes (7),
.BR lf64 (7)
|
