]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/aio_read.2
xnu-792.tar.gz
[apple/xnu.git] / bsd / man / man2 / aio_read.2
CommitLineData
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
40The
41.Fn aio_read
42system call allows the calling process to read
43.Fa iocb->aio_nbytes
44from the descriptor
45.Fa iocb->aio_fildes
46beginning at the offset
47.Fa iocb->aio_offset
48into the buffer pointed to by
49.Fa iocb->aio_buf .
50The call returns immediately after the read request has
51been enqueued to the descriptor; the read may or may not have
52completed at the time the call returns.
53.Pp
54If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it,
55then the enqueued operation is submitted at a priority equal to that
56of the calling process minus
57.Fa iocb->aio_reqprio .
58.Pp
59The
60.Fa iocb->aio_lio_opcode
61argument
62is ignored by the
63.Fn aio_read
64system call.
65.Pp
66The
67.Fa iocb
68pointer may be subsequently used as an argument to
69.Fn aio_return
70and
71.Fn aio_error
72in order to determine return or error status for the enqueued operation
73while it is in progress.
74.Pp
75If the request could not be enqueued (generally due to invalid arguments),
76then the call returns without having enqueued the request.
77.Pp
78If the request is successfully enqueued, the value of
79.Fa iocb->aio_offset
80can be modified during the request as context, so this value must
81not be referenced after the request is enqueued.
82.Sh RESTRICTIONS
83The Asynchronous I/O Control Block structure pointed to by
84.Fa iocb
85and the buffer that the
86.Fa iocb->aio_buf
87member of that structure references must remain valid until the
88operation has completed. For this reason, use of auto (stack) variables
89for these objects is discouraged.
90.Pp
91The asynchronous I/O control buffer
92.Fa iocb
93should be zeroed before the
94.Fn aio_read
95call to avoid passing bogus context information to the kernel.
96.Pp
97Modifications of the Asynchronous I/O Control Block structure or the
98buffer contents after the request has been enqueued, but before the
99request has completed, are not allowed.
100.Pp
101If the file offset in
102.Fa iocb->aio_offset
103is past the offset maximum for
104.Fa iocb->aio_fildes ,
105no I/O will occur.
106.Sh RETURN VALUES
107.Rv -std aio_read
108.Sh DIAGNOSTICS
109None.
110.Sh ERRORS
111The
112.Fn aio_read
113system call will fail if:
114.Bl -tag -width Er
115.It Bq Er EAGAIN
116The request was not queued because of system resource limitations.
117.It Bq Er ENOSYS
118The
119.Fn aio_read
120system call is not supported.
121.El
122.Pp
123The following conditions may be synchronously detected when the
124.Fn aio_read
125system call is made, or asynchronously, at any time thereafter. If they
126are detected at call time,
127.Fn aio_read
128returns -1 and sets
129.Va errno
130appropriately; otherwise the
131.Fn aio_return
132system call must be called, and will return -1, and
133.Fn aio_error
134must be called to determine the actual value that would have been
135returned in
136.Va errno .
137.Pp
138.Bl -tag -width Er
139.It Bq Er EBADF
140The
141.Fa iocb->aio_fildes
142argument
143is invalid.
144.It Bq Er EINVAL
145The offset
146.Fa iocb->aio_offset
147is not valid, the priority specified by
148.Fa iocb->aio_reqprio
149is not a valid priority, or the number of bytes specified by
150.Fa iocb->aio_nbytes
151is not valid.
152.It Bq Er EOVERFLOW
153The file is a regular file,
154.Fa iocb->aio_nbytes
155is greater than zero, the starting offset in
156.Fa iocb->aio_offset
157is before the end of the file, but is at or beyond the
158.Fa iocb->aio_fildes
159offset maximum.
160.El
161.Pp
162If the request is successfully enqueued, but subsequently cancelled
163or an error occurs, the value returned by the
164.Fn aio_return
165system call is per the
166.Xr read 2
167system call, and the value returned by the
168.Fn aio_error
169system call is either one of the error returns from the
170.Xr read 2
171system call, or one of:
172.Bl -tag -width Er
173.It Bq Er EBADF
174The
175.Fa iocb->aio_fildes
176argument
177is invalid for reading.
178.It Bq Er ECANCELED
179The request was explicitly cancelled via a call to
180.Fn aio_cancel .
181.It Bq Er EINVAL
182The offset
183.Fa iocb->aio_offset
184would 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
194The
195.Fn aio_read
196system call is expected to conform to the
197.St -p1003.1
198standard.
199.Sh HISTORY
200The
201.Fn aio_read
202system call first appeared in
203.Fx 3.0 .
204.Sh AUTHORS
205This
206manual page was written by
207.An Terry Lambert Aq terry@whistle.com .
208.Sh BUGS
209Invalid information in
210.Fa iocb->_aiocb_private
211may confuse the kernel.