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.6.2.5 2002/12/29 16:35:34 schweikh Exp $ 26.\" 27.Dd November 17, 1998 28.Dt AIO_READ 3 29.Os 30.Sh NAME 31.Nm aio_read 32.Nd asynchronous read from a file (REALTIME) 33.Sh LIBRARY 34.Lb librt 35.Sh SYNOPSIS 36.In time.h 37.In aio.h 38.Ft int 39.Fn aio_read "struct aiocb *iocb" 40.Sh DESCRIPTION 41The 42.Fn aio_read 43function allows the calling process to read 44.Fa iocb->aio_nbytes 45from the descriptor 46.Fa iocb->aio_fildes 47beginning at the offset 48.Fa iocb->aio_offset 49into the buffer pointed to by 50.Fa iocb->aio_buf . 51The function returns immediately after the read request has 52been enqueued to the descriptor; the read may or may not have 53completed at the time the function returns. 54.Pp 55If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, 56then the enqueued operation is submitted at a priority equal to that 57of the calling process minus 58.Fa iocb->aio_reqprio . 59.Pp 60The 61.Fa iocb->aio_lio_opcode 62is ignored by the 63.Fn aio_read 64function. 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 function 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. 89For this reason, use of auto (stack) variables 90for these objects is discouraged. 91.Pp 92The asynchronous I/O control buffer 93.Fa iocb 94should be zeroed before the 95.Fn aio_read 96function . 97.Pp 98Modifications of the Asynchronous I/O Control Block structure or the 99buffer contents after the request has been enqueued, but before the 100request has completed, are not allowed. 101.Pp 102If the file offset in 103.Fa iocb->aio_offset 104is past the offset maximum for 105.Fa iocb->aio_fildes , 106no I/O will occur. 107.Sh RETURN VALUES 108.Rv -std aio_read 109.Sh DIAGNOSTICS 110None. 111.Sh ERRORS 112The 113.Fn aio_read 114function will fail if: 115.Bl -tag -width Er 116.It Bq Er EAGAIN 117The request was not queued because of system resource limitations. 118.It Bq Er ENOSYS 119The 120.Fn aio_read 121function is not supported. 122.El 123.Pp 124The following conditions may be synchronously detected when the 125.Fn aio_read 126function is made, or asynchronously, at any time thereafter. 127If they are detected at call time, 128.Fn aio_read 129returns -1 and sets 130.Va errno 131appropriately; otherwise the 132.Fn aio_return 133function must be called, and will return -1, and 134.Fn aio_error 135must be called to determine the actual value that would have been 136returned in 137.Va errno . 138.Bl -tag -width Er 139.It Bq Er EBADF 140.Fa iocb->aio_fildes 141is invalid. 142.It Bq Er EINVAL 143The offset 144.Fa iocb->aio_offset 145is not valid, the priority specified by 146.Fa iocb->aio_reqprio 147is not a valid priority, or the number of bytes specified by 148.Fa iocb->aio_nbytes 149is not valid. 150.It Bq Er EOVERFLOW 151The file is a regular file, 152.Fa iocb->aio_nbytes 153is greater than zero, the starting offset in 154.Fa iocb->aio_offset 155is before the end of the file, but is at or beyond the 156.Fa iocb->aio_fildes 157offset maximum. 158.El 159.Pp 160If the request is successfully enqueued, but subsequently cancelled 161or an error occurs, the value returned by the 162.Fn aio_return 163function is per the 164.Xr read 2 165call, and the value returned by the 166.Fn aio_error 167function is either one of the error returns from the 168.Xr read 2 169call, or one of: 170.Bl -tag -width Er 171.It Bq Er EBADF 172.Fa iocb->aio_fildes 173is invalid for reading. 174.It Bq Er ECANCELED 175The request was explicitly cancelled via a call to 176.Fn aio_cancel . 177.It Bq Er EINVAL 178The offset 179.Fa iocb->aio_offset 180would be invalid. 181.El 182.Sh STANDARDS 183The 184.Fn aio_read 185function is expected to conform to the 186.St -p1003.2 187standard. 188.Sh HISTORY 189The 190.Nm 191function first appeared in 192.Fx 3.0 . 193.Sh AUTHORS 194This 195manual page was written by 196.An Terry Lambert Aq Mt terry@whistle.com . 197