]>
Commit | Line | Data |
---|---|---|
91447636 A |
1 | .\" Copyright (c) 1998 Terry Lambert |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" | |
13 | .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND | |
14 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
15 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
16 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE | |
17 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
18 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
19 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
20 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
21 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
22 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
23 | .\" SUCH DAMAGE. | |
24 | .\" | |
25 | .\" $FreeBSD: src/lib/libc/sys/aio_read.2,v 1.19 2003/01/14 02:37:06 tjr Exp $ | |
26 | .\" | |
27 | .Dd November 17, 1998 | |
28 | .Dt AIO_READ 2 | |
29 | .Os | |
30 | .Sh NAME | |
31 | .Nm aio_read | |
32 | .Nd asynchronous read from a file (REALTIME) | |
33 | .Sh LIBRARY | |
34 | .Lb libc | |
35 | .Sh SYNOPSIS | |
36 | .In aio.h | |
37 | .Ft int | |
38 | .Fn aio_read "struct aiocb *iocb" | |
39 | .Sh DESCRIPTION | |
40 | The | |
41 | .Fn aio_read | |
42 | system call allows the calling process to read | |
43 | .Fa iocb->aio_nbytes | |
44 | from the descriptor | |
45 | .Fa iocb->aio_fildes | |
46 | beginning at the offset | |
47 | .Fa iocb->aio_offset | |
48 | into the buffer pointed to by | |
49 | .Fa iocb->aio_buf . | |
50 | The call returns immediately after the read request has | |
51 | been enqueued to the descriptor; the read may or may not have | |
52 | completed at the time the call returns. | |
53 | .Pp | |
54 | If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, | |
55 | then the enqueued operation is submitted at a priority equal to that | |
56 | of the calling process minus | |
57 | .Fa iocb->aio_reqprio . | |
58 | .Pp | |
59 | The | |
60 | .Fa iocb->aio_lio_opcode | |
61 | argument | |
62 | is ignored by the | |
63 | .Fn aio_read | |
64 | system call. | |
65 | .Pp | |
66 | The | |
67 | .Fa iocb | |
68 | pointer may be subsequently used as an argument to | |
69 | .Fn aio_return | |
70 | and | |
71 | .Fn aio_error | |
72 | in order to determine return or error status for the enqueued operation | |
73 | while it is in progress. | |
74 | .Pp | |
75 | If the request could not be enqueued (generally due to invalid arguments), | |
76 | then the call returns without having enqueued the request. | |
77 | .Pp | |
78 | If the request is successfully enqueued, the value of | |
79 | .Fa iocb->aio_offset | |
80 | can be modified during the request as context, so this value must | |
81 | not be referenced after the request is enqueued. | |
82 | .Sh RESTRICTIONS | |
83 | The Asynchronous I/O Control Block structure pointed to by | |
84 | .Fa iocb | |
85 | and the buffer that the | |
86 | .Fa iocb->aio_buf | |
87 | member of that structure references must remain valid until the | |
88 | operation has completed. For this reason, use of auto (stack) variables | |
89 | for these objects is discouraged. | |
90 | .Pp | |
91 | The asynchronous I/O control buffer | |
92 | .Fa iocb | |
93 | should be zeroed before the | |
94 | .Fn aio_read | |
95 | call to avoid passing bogus context information to the kernel. | |
96 | .Pp | |
97 | Modifications of the Asynchronous I/O Control Block structure or the | |
98 | buffer contents after the request has been enqueued, but before the | |
99 | request has completed, are not allowed. | |
100 | .Pp | |
101 | If the file offset in | |
102 | .Fa iocb->aio_offset | |
103 | is past the offset maximum for | |
104 | .Fa iocb->aio_fildes , | |
105 | no I/O will occur. | |
106 | .Sh RETURN VALUES | |
107 | .Rv -std aio_read | |
108 | .Sh DIAGNOSTICS | |
109 | None. | |
110 | .Sh ERRORS | |
111 | The | |
112 | .Fn aio_read | |
113 | system call will fail if: | |
114 | .Bl -tag -width Er | |
115 | .It Bq Er EAGAIN | |
116 | The request was not queued because of system resource limitations. | |
117 | .It Bq Er ENOSYS | |
118 | The | |
119 | .Fn aio_read | |
120 | system call is not supported. | |
121 | .El | |
122 | .Pp | |
123 | The following conditions may be synchronously detected when the | |
124 | .Fn aio_read | |
125 | system call is made, or asynchronously, at any time thereafter. If they | |
126 | are detected at call time, | |
127 | .Fn aio_read | |
128 | returns -1 and sets | |
129 | .Va errno | |
130 | appropriately; otherwise the | |
131 | .Fn aio_return | |
132 | system call must be called, and will return -1, and | |
133 | .Fn aio_error | |
134 | must be called to determine the actual value that would have been | |
135 | returned in | |
136 | .Va errno . | |
137 | .Pp | |
138 | .Bl -tag -width Er | |
139 | .It Bq Er EBADF | |
140 | The | |
141 | .Fa iocb->aio_fildes | |
142 | argument | |
143 | is invalid. | |
144 | .It Bq Er EINVAL | |
145 | The offset | |
146 | .Fa iocb->aio_offset | |
147 | is not valid, the priority specified by | |
148 | .Fa iocb->aio_reqprio | |
149 | is not a valid priority, or the number of bytes specified by | |
150 | .Fa iocb->aio_nbytes | |
151 | is not valid. | |
152 | .It Bq Er EOVERFLOW | |
153 | The file is a regular file, | |
154 | .Fa iocb->aio_nbytes | |
155 | is greater than zero, the starting offset in | |
156 | .Fa iocb->aio_offset | |
157 | is before the end of the file, but is at or beyond the | |
158 | .Fa iocb->aio_fildes | |
159 | offset maximum. | |
160 | .El | |
161 | .Pp | |
162 | If the request is successfully enqueued, but subsequently cancelled | |
163 | or an error occurs, the value returned by the | |
164 | .Fn aio_return | |
165 | system call is per the | |
166 | .Xr read 2 | |
167 | system call, and the value returned by the | |
168 | .Fn aio_error | |
169 | system call is either one of the error returns from the | |
170 | .Xr read 2 | |
171 | system call, or one of: | |
172 | .Bl -tag -width Er | |
173 | .It Bq Er EBADF | |
174 | The | |
175 | .Fa iocb->aio_fildes | |
176 | argument | |
177 | is invalid for reading. | |
178 | .It Bq Er ECANCELED | |
179 | The request was explicitly cancelled via a call to | |
180 | .Fn aio_cancel . | |
181 | .It Bq Er EINVAL | |
182 | The offset | |
183 | .Fa iocb->aio_offset | |
184 | would be invalid. | |
185 | .El | |
186 | .Sh SEE ALSO | |
187 | .Xr aio_cancel 2 , | |
188 | .Xr aio_error 2 , | |
189 | .Xr aio_return 2 , | |
190 | .Xr aio_suspend 2 , | |
191 | .Xr aio_write 2 , | |
192 | .Xr aio 4 | |
193 | .Sh STANDARDS | |
194 | The | |
195 | .Fn aio_read | |
196 | system call is expected to conform to the | |
197 | .St -p1003.1 | |
198 | standard. | |
199 | .Sh HISTORY | |
200 | The | |
201 | .Fn aio_read | |
202 | system call first appeared in | |
203 | .Fx 3.0 . | |
204 | .Sh AUTHORS | |
205 | This | |
206 | manual page was written by | |
207 | .An Terry Lambert Aq terry@whistle.com . | |
208 | .Sh BUGS | |
209 | Invalid information in | |
210 | .Fa iocb->_aiocb_private | |
211 | may confuse the kernel. |