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