1 .\" Copyright (c) 1998 Terry Lambert
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
33 .Nd asynchronous read from a file (REALTIME)
39 .Fn aio_read "struct aiocb *iocb"
42 .Fn aio_readv "struct aiocb *iocb"
48 system calls allow the calling process to read
51 beginning at the offset
52 .Fa iocb->aio_offset .
56 from the buffer pointed to by
60 reads the data into the
62 buffers specified by the members of the
65 Both syscalls return immediately after the read request has
66 been enqueued to the descriptor; the read may or may not have
67 completed at the time the call returns.
73 structure is defined in
76 If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it,
77 then the enqueued operation is submitted at a priority equal to that
78 of the calling process minus
79 .Fa iocb->aio_reqprio .
82 .Fa iocb->aio_lio_opcode
92 pointer may be subsequently used as an argument to
96 in order to determine return or error status for the enqueued operation
97 while it is in progress.
99 If the request could not be enqueued (generally due to invalid arguments),
100 then the call returns without having enqueued the request.
102 If the request is successfully enqueued, the value of
104 can be modified during the request as context, so this value must
105 not be referenced after the request is enqueued.
108 .Fa iocb->aio_sigevent
109 structure can be used to request notification of the operation's
110 completion as described in
113 The Asynchronous I/O Control Block structure pointed to by
115 and the buffer that the
117 member of that structure references must remain valid until the
118 operation has completed.
120 The asynchronous I/O control buffer
122 should be zeroed before the
124 call to avoid passing bogus context information to the kernel.
126 Modifications of the Asynchronous I/O Control Block structure or the
127 buffer contents are not allowed while the request is queued.
129 If the file offset in
131 is past the offset maximum for
132 .Fa iocb->aio_fildes ,
135 .Rv -std aio_read aio_readv
143 system calls will fail if:
146 The request was not queued because of system resource limitations.
150 points outside the process's allocated address space.
152 The asynchronous notification method in
153 .Fa iocb->aio_sigevent.sigev_notify
154 is invalid or not supported.
156 Asynchronous read operations on the file descriptor
158 are unsafe and unsafe asynchronous I/O operations are disabled.
161 The following conditions may be synchronously detected when the
165 system call is made, or asynchronously, at any time thereafter.
167 are detected at call time,
173 appropriately; otherwise the
175 system call must be called, and will return -1, and
177 must be called to determine the actual value that would have been
189 is not valid, the priority specified by
190 .Fa iocb->aio_reqprio
191 is not a valid priority, or the number of bytes specified by
195 The file is a regular file,
197 is greater than zero, the starting offset in
199 is before the end of the file, but is at or beyond the
204 If the request is successfully enqueued, but subsequently cancelled
205 or an error occurs, the value returned by the
207 system call is per the
209 system call, and the value returned by the
211 system call is either one of the error returns from the
213 system call, or one of:
219 is invalid for reading.
221 The request was explicitly cancelled via a call to
233 .Xr aio_waitcomplete 2 ,
241 system call is expected to conform to the
246 system call is a FreeBSD extension, and should not be used in portable code.
250 system call first appeared in
254 system call first appeared in
258 manual page was written by
259 .An Terry Lambert Aq Mt terry@whistle.com .
261 Invalid information in
262 .Fa iocb->_aiocb_private
263 may confuse the kernel.