diff options
Diffstat (limited to 'lib/libsys/aio_read.2')
| -rw-r--r-- | lib/libsys/aio_read.2 | 290 |
1 files changed, 290 insertions, 0 deletions
diff --git a/lib/libsys/aio_read.2 b/lib/libsys/aio_read.2 new file mode 100644 index 000000000000..45779fff94c4 --- /dev/null +++ b/lib/libsys/aio_read.2 @@ -0,0 +1,290 @@ +.\" Copyright (c) 1998 Terry Lambert +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.Dd March 27, 2025 +.Dt AIO_READ 2 +.Os +.Sh NAME +.Nm aio_read , +.Nm aio_read2 , +.Nm aio_readv +.Nd asynchronous read from a file (REALTIME) +.Sh LIBRARY +.Lb libc +.Sh SYNOPSIS +.In aio.h +.Ft int +.Fn aio_read "struct aiocb *iocb" +.Ft int +.Fn aio_read2 "struct aiocb *iocb" "int flags" +.In sys/uio.h +.Ft int +.Fn aio_readv "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_read , +.Fn aio_read2 +and +.Fn aio_readv +system calls allow the calling process to read +from the descriptor +.Fa iocb->aio_fildes . +The syscalls return immediately after the read request has +been enqueued to the descriptor; the read may or may not have +completed at the time the call returns. +.Pp +For the +.Fn aio_read +and +.Fn aio_readv +calls, the read begins at the offset +.Fa iocb->aio_offset . +.Pp +The +.Fn aio_read +call will read +.Fa iocb->aio_nbytes +into the buffer pointed to by +.Fa iocb->aio_buf , +whereas +.Fn aio_readv +reads the data into the +.Fa iocb->aio_iovcnt +buffers specified by the members of the +.Fa iocb->aio_iov +array. +For +.Fn aio_readv +the +.Fa iovec +structure is defined in +.Xr readv 2 . +.Pp +The +.Fn aio_read2 +call takes the +.Fa flags +argument. +If +.Fa flags +is passed as zero, the call behaves identically to +.Fn aio_read . +The following flags can be specified by logical or: +.Bl -tag -width AIO_OP2_VECTORED +.It AIO_OP2_FOFFSET +The read occurs at the file descriptor offset, +which is advanced by the operation as done by the +.Xr read 2 +syscall. +The +.Fa iocb->aio_offset +field is ignored. +.It AIO_OP2_VECTORED +Similar to +.Fn aio_readv , +the read buffers are specified by the +.Fa aiocb->aio_iov +array. +.El +.Pp +The +.Fa iocb +pointer may be subsequently used as an argument to +.Fn aio_return +and +.Fn aio_error +in order to determine return or error status for the enqueued operation +while it is in progress. +.Pp +If the request could not be enqueued (generally due to invalid arguments), +then the call returns without having enqueued the request. +.Pp +If the request is successfully enqueued, the value of +.Fa iocb->aio_offset +can be modified during the request as context, so this value must +not be referenced after the request is enqueued. +.Pp +The +.Fa iocb->aio_sigevent +structure can be used to request notification of the operation's +completion as described in +.Xr aio 4 . +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Fa iocb +and the buffer that the +.Fa iocb->aio_buf +member of that structure references must remain valid until the +operation has completed. +.Pp +The asynchronous I/O control buffer +.Fa iocb +should be zeroed before the system +calls to avoid passing bogus context information to the kernel. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +buffer contents are not allowed while the request is queued. +.Pp +If the file offset in +.Fa iocb->aio_offset +is past the offset maximum for +.Fa iocb->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_read aio_read2 aio_readv +.Sh DIAGNOSTICS +None. +.Sh ERRORS +The +.Fn aio_read , +.Fn aio_read2 , +and +.Fn aio_readv +system calls will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er EFAULT +Part of +.Fa aio_iov +points outside the process's allocated address space. +.It Bq Er EINVAL +The asynchronous notification method in +.Fa iocb->aio_sigevent.sigev_notify +is invalid or not supported. +.It Bq Er EOPNOTSUPP +Asynchronous read operations on the file descriptor +.Fa iocb->aio_fildes +are unsafe and unsafe asynchronous I/O operations are disabled. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_read +or +.Fn aio_readv +system call is made, or asynchronously, at any time thereafter. +If they +are detected at call time, +The calls return -1 and set +.Va errno +appropriately; otherwise the +.Fn aio_return +system call must be called, and will return -1, and +.Fn aio_error +must be called to determine the actual value that would have been +returned in +.Va errno . +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid. +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +is not valid, the priority specified by +.Fa iocb->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Fa iocb->aio_nbytes +is not valid. +.It Bq Er EOVERFLOW +The file is a regular file, +.Fa iocb->aio_nbytes +is greater than zero, the starting offset in +.Fa iocb->aio_offset +is before the end of the file, but is at or beyond the +.Fa iocb->aio_fildes +offset maximum. +.El +.Pp +If the request is successfully enqueued, but subsequently cancelled +or an error occurs, the value returned by the +.Fn aio_return +system call is per the +.Xr read 2 +system call, and the value returned by the +.Fn aio_error +system call is either one of the error returns from the +.Xr read 2 +system call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +The +.Fa iocb->aio_fildes +argument +is invalid for reading. +.It Bq Er ECANCELED +The request was explicitly cancelled via a call to +.Fn aio_cancel . +.It Bq Er EINVAL +The offset +.Fa iocb->aio_offset +would be invalid. +.El +.Sh SEE ALSO +.Xr aio_cancel 2 , +.Xr aio_error 2 , +.Xr aio_return 2 , +.Xr aio_suspend 2 , +.Xr aio_waitcomplete 2 , +.Xr aio_write 2 , +.Xr sigevent 3 , +.Xr siginfo 3 , +.Xr aio 4 +.Sh STANDARDS +The +.Fn aio_read +system call is expected to conform to the +.St -p1003.1 +standard. +The +.Fn aio_read2 +and +.Fn aio_readv +system calls are +.Fx +extensions, +and should not be used in portable code. +.Sh HISTORY +The +.Fn aio_read +system call first appeared in +.Fx 3.0 . +The +.Fn aio_readv +system call first appeared in +.Fx 13.0 . +The +.Fn aio_read2 +system call first appeared in +.Fx 14.1 . +.Sh AUTHORS +This +manual page was written by +.An Terry Lambert Aq Mt terry@whistle.com . +.Sh BUGS +Invalid information in +.Fa iocb->_aiocb_private +may confuse the kernel. |