From bd073938e95cc12ae08984609dab55ed0f3964e9 Mon Sep 17 00:00:00 2001 From: jkoshy Date: Thu, 19 Nov 1998 04:07:55 +0000 Subject: Man page for aio_read(2). Submitted by: Terry Lambert on the -doc lists. --- lib/libc/sys/aio_read.2 | 189 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) create mode 100644 lib/libc/sys/aio_read.2 diff --git a/lib/libc/sys/aio_read.2 b/lib/libc/sys/aio_read.2 new file mode 100644 index 0000000..16dab67 --- /dev/null +++ b/lib/libc/sys/aio_read.2 @@ -0,0 +1,189 @@ +.\" 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. +.\" +.\" $Id$ +.\" +.Dd November 17, 1998 +.Dt AIO_READ 2 +.Os +.Sh NAME +.Nm aio_read +.Nd asynchronus read from a file (REALTIME) +.Sh SYNOPSIS +.Fd #include +.Ft int +.Fn aio_read "struct aiocb *iocb" +.Sh DESCRIPTION +The +.Fn aio_read +function allows the calling process to read +.Ar iocb->aio_nbytes +from the descriptor +.Ar iocb->aio_fildes +beginning at the offset +.Ar iocb->aio_offset +into the buffer pointed to by +.Ar iocb->aio_buf . +The call returns 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 +If _POSIX_PRIORITIZED_IO is defined, and the descriptor supports it, +then the enqueued operation is submitted at a priority equal to that +of the calling process minus +.Ar iocb->aio_reqprio . +.Pp +The +.Ar iocb->aio_lio_opcode +is ignored by the +.Fn aio_read +call. +.Pp +The +.Ar 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 +.Ar iocb->aio_offset +can be modified during the request as context, so this value must +not be referenced after the request is enqueued. +.Sh RESTRICTIONS +The Asynchronous I/O Control Block structure pointed to by +.Ar iocb +and the buffer that the +.Ar iocb->aio_buf +member of that structure references must remain valid until the +operation has completed. For this reason, use of auto (stack) variables +for these objects is discouraged. +.Pp +Modifications of the Asynchronous I/O Control Block structure or the +buffer contents after the request has been enqueued, but before the +request has completed, are not allowed. +.Pp +If the file offset in +.Ar iocb->aio_offset +is past the offset maximum for +.Ar iocb->aio_fildes , +no I/O will occur. +.Sh RETURN VALUES +.Rv -std aio_read +.Sh STANDARDS +The +.Fn aio_read +call conforms to the +.St -p1003.2 +standard. +.Sh DIAGNOSTICS +None. +.Sh ERRORS +The +.Fn aio_read +function will fail if: +.Bl -tag -width Er +.It Bq Er EAGAIN +The request was not queued because of system resource limitations. +.It Bq Er ENOSYS +The +.Fn aio_read +call is not supported. +.El +.Pp +The following conditions may be synchronously detected when the +.Fn aio_read +call is made, or asynchronously, at any time thereafter. If they +are detected at call time, +.Fn aio_read +returns -1 and sets +.Ar errno +appropriately; otherwise the +.Fn aio_return +function must be called, and will return -1, and +Fn aio_error +must be called to determine the actual calue that would have been +returned in +.Ar errno . +.Pp +.Bl -tag -width Er +.It Bq Er EBADF +.Ar iocb->aio_fildes +is invalid. +.It Bq Er EINVAL +The offset +.Ar iocb->aio_offset +is not valid, the priority specified by +.Ar iocb->aio_reqprio +is not a valid priority, or the number of bytes specified by +.Ar iocb->aio_nbytes +is not valid. +.It Bq Er EOVERFLOW +The file is a regular file, +.Ar iocb->aio_nbytes +is greater than zero, the starting offset in +.Ar iocb->aio_offset +is before the end of the file, but is at or beyond the +.Ar 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 +function is per the +.Xr read 2 +call, and the value returned by the +.Fn aio_error +function is either one of the error returns from the +.Xr read 2 +call, or one of: +.Bl -tag -width Er +.It Bq Er EBADF +.Ar iocb->aio_fildes +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 +.Ar iocb->aio_offset +would be invalid. +.El +.Sh HISTORY +The +.Nm +Function first appeared in +.Fx 3.0 . +.Sh AUTHOR +This +manual page was written by +.An Terry Lambert Aq terry@whistle.com . +.Sh BUGS +The value of iocb->aio_offset is ignored. -- cgit v1.1