1.\" $NetBSD: aio_read.3,v 1.6 2022/12/04 01:29:33 uwe Exp $ 2.\" 3.\" Copyright (c) 1998 Terry Lambert 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.\" $FreeBSD: /repoman/r/ncvs/src/lib/libc/sys/aio_read.2,v 1.23 2005/12/13 13:43:35 davidxu Exp $ 28.\" 29.Dd May 17, 2010 30.Dt AIO_READ 3 31.Os 32.Sh NAME 33.Nm aio_read 34.Nd asynchronous read from a file (REALTIME) 35.Sh LIBRARY 36.Lb librt 37.Sh SYNOPSIS 38.In aio.h 39.Ft int 40.Fn aio_read "struct aiocb *aiocbp" 41.Sh DESCRIPTION 42The 43.Fn aio_read 44system call allows the calling process to read 45.Fa aiocbp->aio_nbytes 46from the descriptor 47.Fa aiocbp->aio_fildes 48beginning at the offset 49.Fa aiocbp->aio_offset 50into the buffer pointed to by 51.Fa aiocbp->aio_buf . 52The call returns immediately after the read request has 53been enqueued to the descriptor; the read may or may not have 54completed at the time the call returns. 55.Pp 56If 57.Dv _POSIX_PRIORITIZED_IO 58is defined, and the descriptor supports it, 59then the enqueued operation is submitted at a priority equal to that 60of the calling process minus 61.Fa aiocbp->aio_reqprio . 62.Pp 63The 64.Fa aiocbp->aio_lio_opcode 65argument 66is ignored by the 67.Fn aio_read 68system call. 69.Pp 70The 71.Fa aiocbp 72pointer may be subsequently used as an argument to 73.Fn aio_return 74and 75.Fn aio_error 76in order to determine return or error status for the enqueued operation 77while it is in progress. 78.Pp 79If the request could not be enqueued (generally due to invalid arguments), 80then the call returns without having enqueued the request. 81.Pp 82If the request is successfully enqueued, the value of 83.Fa aiocbp->aio_offset 84can be modified during the request as context, so this value must 85not be referenced after the request is enqueued. 86.Sh RESTRICTIONS 87The Asynchronous I/O Control Block structure pointed to by 88.Fa aiocbp 89and the buffer that the 90.Fa aiocbp->aio_buf 91member of that structure references must remain valid until the 92operation has completed. 93For this reason, use of auto (stack) variables 94for these objects is discouraged. 95.Pp 96The asynchronous I/O control buffer 97.Fa aiocbp 98should be zeroed before the 99.Fn aio_read 100call to avoid passing bogus context information to the kernel. 101.Pp 102Modifications of the Asynchronous I/O Control Block structure or the 103buffer contents after the request has been enqueued, but before the 104request has completed, are not allowed. 105.Pp 106If the file offset in 107.Fa aiocbp->aio_offset 108is past the offset maximum for 109.Fa aiocbp->aio_fildes , 110no I/O will occur. 111.Sh RETURN VALUES 112.Rv -std aio_read 113.Sh ERRORS 114The 115.Fn aio_read 116system call will fail if: 117.Bl -tag -width Er 118.It Bq Er EAGAIN 119The request was not queued because of system resource limitations. 120.El 121.Pp 122The following conditions may be synchronously detected when the 123.Fn aio_read 124system call is made, or asynchronously, at any time thereafter. 125If 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 aiocbp->aio_fildes 142argument 143is invalid. 144.It Bq Er EINVAL 145The offset 146.Fa aiocbp->aio_offset 147is not valid, the priority specified by 148.Fa aiocbp->aio_reqprio 149is not a valid priority, or the number of bytes specified by 150.Fa aiocbp->aio_nbytes 151is not valid. 152.It Bq Er EOVERFLOW 153The file is a regular file, 154.Fa aiocbp->aio_nbytes 155is greater than zero, the starting offset in 156.Fa aiocbp->aio_offset 157is before the end of the file, but is at or beyond the 158.Fa aiocbp->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 aiocbp->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 aiocbp->aio_offset 184would be invalid. 185.El 186.Sh SEE ALSO 187.Xr siginfo 2 , 188.Xr aio 3 189.Sh STANDARDS 190The 191.Fn aio_read 192system call is expected to conform to the 193.St -p1003.1-2001 194standard. 195.Sh HISTORY 196The 197.Fn aio_read 198system call first appeared in 199.Nx 5.0 . 200