xref: /freebsd/lib/libsys/aio_read.2 (revision 8269e7673cf033aba67dab8264fe719920c70f87) 
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.Dd November 15, 2023
26.Dt AIO_READ 2
27.Os
28.Sh NAME
29.Nm aio_read ,
30.Nm aio_readv
31.Nd asynchronous read from a file (REALTIME)
32.Sh LIBRARY
33.Lb libc
34.Sh SYNOPSIS
35.In aio.h
36.Ft int
37.Fn aio_read "struct aiocb *iocb"
38.In sys/uio.h
39.Ft int
40.Fn aio_readv "struct aiocb *iocb"
41.Sh DESCRIPTION
42The
43.Fn aio_read
44and
45.Fn aio_readv
46system calls allow the calling process to read
47from the descriptor
48.Fa iocb->aio_fildes
49beginning at the offset
50.Fa iocb->aio_offset .
51.Fn aio_read
52will read
53.Fa iocb->aio_nbytes
54into the buffer pointed to by
55.Fa iocb->aio_buf ,
56whereas
57.Fn aio_readv
58reads the data into the
59.Fa iocb->aio_iovcnt
60buffers specified by the members of the
61.Fa iocb->aio_iov
62array.
63Both syscalls return immediately after the read request has
64been enqueued to the descriptor; the read may or may not have
65completed at the time the call returns.
66.Pp
67For
68.Fn aio_readv
69the
70.Fa iovec
71structure is defined in
72.Xr readv 2 .
73.Pp
74The
75.Fa iocb
76pointer may be subsequently used as an argument to
77.Fn aio_return
78and
79.Fn aio_error
80in order to determine return or error status for the enqueued operation
81while it is in progress.
82.Pp
83If the request could not be enqueued (generally due to invalid arguments),
84then the call returns without having enqueued the request.
85.Pp
86If the request is successfully enqueued, the value of
87.Fa iocb->aio_offset
88can be modified during the request as context, so this value must
89not be referenced after the request is enqueued.
90.Pp
91The
92.Fa iocb->aio_sigevent
93structure can be used to request notification of the operation's
94completion as described in
95.Xr aio 4 .
96.Sh RESTRICTIONS
97The Asynchronous I/O Control Block structure pointed to by
98.Fa iocb
99and the buffer that the
100.Fa iocb->aio_buf
101member of that structure references must remain valid until the
102operation has completed.
103.Pp
104The asynchronous I/O control buffer
105.Fa iocb
106should be zeroed before the
107.Fn aio_read
108call to avoid passing bogus context information to the kernel.
109.Pp
110Modifications of the Asynchronous I/O Control Block structure or the
111buffer contents are not allowed while the request is queued.
112.Pp
113If the file offset in
114.Fa iocb->aio_offset
115is past the offset maximum for
116.Fa iocb->aio_fildes ,
117no I/O will occur.
118.Sh RETURN VALUES
119.Rv -std aio_read aio_readv
120.Sh DIAGNOSTICS
121None.
122.Sh ERRORS
123The
124.Fn aio_read
125and
126.Fn aio_readv
127system calls will fail if:
128.Bl -tag -width Er
129.It Bq Er EAGAIN
130The request was not queued because of system resource limitations.
131.It Bq Er EFAULT
132Part of
133.Fa aio_iov
134points outside the process's allocated address space.
135.It Bq Er EINVAL
136The asynchronous notification method in
137.Fa iocb->aio_sigevent.sigev_notify
138is invalid or not supported.
139.It Bq Er EOPNOTSUPP
140Asynchronous read operations on the file descriptor
141.Fa iocb->aio_fildes
142are unsafe and unsafe asynchronous I/O operations are disabled.
143.El
144.Pp
145The following conditions may be synchronously detected when the
146.Fn aio_read
147or
148.Fn aio_readv
149system call is made, or asynchronously, at any time thereafter.
150If they
151are detected at call time,
152.Fn aio_read
153or
154.Fn aio_readv
155returns -1 and sets
156.Va errno
157appropriately; otherwise the
158.Fn aio_return
159system call must be called, and will return -1, and
160.Fn aio_error
161must be called to determine the actual value that would have been
162returned in
163.Va errno .
164.Bl -tag -width Er
165.It Bq Er EBADF
166The
167.Fa iocb->aio_fildes
168argument
169is invalid.
170.It Bq Er EINVAL
171The offset
172.Fa iocb->aio_offset
173is not valid, the priority specified by
174.Fa iocb->aio_reqprio
175is not a valid priority, or the number of bytes specified by
176.Fa iocb->aio_nbytes
177is not valid.
178.It Bq Er EOVERFLOW
179The file is a regular file,
180.Fa iocb->aio_nbytes
181is greater than zero, the starting offset in
182.Fa iocb->aio_offset
183is before the end of the file, but is at or beyond the
184.Fa iocb->aio_fildes
185offset maximum.
186.El
187.Pp
188If the request is successfully enqueued, but subsequently cancelled
189or an error occurs, the value returned by the
190.Fn aio_return
191system call is per the
192.Xr read 2
193system call, and the value returned by the
194.Fn aio_error
195system call is either one of the error returns from the
196.Xr read 2
197system call, or one of:
198.Bl -tag -width Er
199.It Bq Er EBADF
200The
201.Fa iocb->aio_fildes
202argument
203is invalid for reading.
204.It Bq Er ECANCELED
205The request was explicitly cancelled via a call to
206.Fn aio_cancel .
207.It Bq Er EINVAL
208The offset
209.Fa iocb->aio_offset
210would be invalid.
211.El
212.Sh SEE ALSO
213.Xr aio_cancel 2 ,
214.Xr aio_error 2 ,
215.Xr aio_return 2 ,
216.Xr aio_suspend 2 ,
217.Xr aio_waitcomplete 2 ,
218.Xr aio_write 2 ,
219.Xr sigevent 3 ,
220.Xr siginfo 3 ,
221.Xr aio 4
222.Sh STANDARDS
223The
224.Fn aio_read
225system call is expected to conform to the
226.St -p1003.1
227standard.
228The
229.Fn aio_readv
230system call is a FreeBSD extension, and should not be used in portable code.
231.Sh HISTORY
232The
233.Fn aio_read
234system call first appeared in
235.Fx 3.0 .
236The
237.Fn aio_readv
238system call first appeared in
239.Fx 13.0 .
240.Sh AUTHORS
241This
242manual page was written by
243.An Terry Lambert Aq Mt terry@whistle.com .
244.Sh BUGS
245Invalid information in
246.Fa iocb->_aiocb_private
247may confuse the kernel.
248