mirror of https://github.com/mkerrisk/man-pages
165 lines
6.1 KiB
Plaintext
165 lines
6.1 KiB
Plaintext
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
||
|
.TH "AIO_READ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
||
|
.\" aio_read
|
||
|
.SH NAME
|
||
|
aio_read \- asynchronous read from a file (\fBREALTIME\fP)
|
||
|
.SH SYNOPSIS
|
||
|
.LP
|
||
|
\fB#include <aio.h>
|
||
|
.br
|
||
|
.sp
|
||
|
int aio_read(struct aiocb *\fP\fIaiocbp\fP\fB); \fP
|
||
|
\fB
|
||
|
.br
|
||
|
\fP
|
||
|
.SH DESCRIPTION
|
||
|
.LP
|
||
|
The \fIaio_read\fP() function shall read \fIaiocbp\fP->\fIaio_nbytes\fP
|
||
|
from the file associated with
|
||
|
\fIaiocbp\fP->\fIaio_fildes\fP into the buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP.
|
||
|
The function call shall return
|
||
|
when the read request has been initiated or queued to the file or
|
||
|
device (even when the data cannot be delivered immediately).
|
||
|
.LP
|
||
|
If prioritized I/O is supported for this file, then the asynchronous
|
||
|
operation shall be submitted at a priority equal to the
|
||
|
scheduling priority of the process minus \fIaiocbp\fP->\fIaio_reqprio\fP.
|
||
|
.LP
|
||
|
The \fIaiocbp\fP value may be used as an argument to \fIaio_error\fP()
|
||
|
and \fIaio_return\fP() in order to determine the error status and
|
||
|
return status, respectively, of
|
||
|
the asynchronous operation while it is proceeding. If an error condition
|
||
|
is encountered during queuing, the function call shall
|
||
|
return without having initiated or queued the request. The requested
|
||
|
operation takes place at the absolute position in the file as
|
||
|
given by \fIaio_offset\fP, as if \fIlseek\fP() were called immediately
|
||
|
prior to the
|
||
|
operation with an \fIoffset\fP equal to \fIaio_offset\fP and a \fIwhence\fP
|
||
|
equal to SEEK_SET. After a successful call to
|
||
|
enqueue an asynchronous I/O operation, the value of the file offset
|
||
|
for the file is unspecified.
|
||
|
.LP
|
||
|
The \fIaiocbp\fP->\fIaio_lio_opcode\fP field shall be ignored by \fIaio_read\fP().
|
||
|
.LP
|
||
|
The \fIaiocbp\fP argument points to an \fBaiocb\fP structure. If the
|
||
|
buffer pointed to by \fIaiocbp\fP->\fIaio_buf\fP or
|
||
|
the control block pointed to by \fIaiocbp\fP becomes an illegal address
|
||
|
prior to asynchronous I/O completion, then the behavior is
|
||
|
undefined.
|
||
|
.LP
|
||
|
Simultaneous asynchronous operations using the same \fIaiocbp\fP produce
|
||
|
undefined results.
|
||
|
.LP
|
||
|
If synchronized I/O is enabled on the file associated with \fIaiocbp\fP->\fIaio_fildes\fP,
|
||
|
the behavior of this function shall
|
||
|
be according to the definitions of synchronized I/O data integrity
|
||
|
completion and synchronized I/O file integrity completion.
|
||
|
.LP
|
||
|
For any system action that changes the process memory space while
|
||
|
an asynchronous I/O is outstanding to the address range being
|
||
|
changed, the result of that action is undefined.
|
||
|
.LP
|
||
|
For regular files, no data transfer shall occur past the offset maximum
|
||
|
established in the open file description associated with
|
||
|
\fIaiocbp\fP->\fIaio_fildes\fP.
|
||
|
.SH RETURN VALUE
|
||
|
.LP
|
||
|
The \fIaio_read\fP() function shall return the value zero to the calling
|
||
|
process if the I/O operation is successfully queued;
|
||
|
otherwise, the function shall return the value -1 and set \fIerrno\fP
|
||
|
to indicate the error.
|
||
|
.SH ERRORS
|
||
|
.LP
|
||
|
The \fIaio_read\fP() function shall fail if:
|
||
|
.TP 7
|
||
|
.B EAGAIN
|
||
|
The requested asynchronous I/O operation was not queued due to system
|
||
|
resource limitations.
|
||
|
.sp
|
||
|
.LP
|
||
|
Each of the following conditions may be detected synchronously at
|
||
|
the time of the call to \fIaio_read\fP(), or asynchronously.
|
||
|
If any of the conditions below are detected synchronously, the \fIaio_read\fP()
|
||
|
function shall return -1 and set \fIerrno\fP to
|
||
|
the corresponding value. If any of the conditions below are detected
|
||
|
asynchronously, the return status of the asynchronous
|
||
|
operation is set to -1, and the error status of the asynchronous operation
|
||
|
is set to the corresponding value.
|
||
|
.TP 7
|
||
|
.B EBADF
|
||
|
The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor
|
||
|
open for reading.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would
|
||
|
be invalid, \fIaiocbp\fP->\fIaio_reqprio\fP is
|
||
|
not a valid value, or \fIaiocbp\fP->\fIaio_nbytes\fP is an invalid
|
||
|
value.
|
||
|
.sp
|
||
|
.LP
|
||
|
In the case that the \fIaio_read\fP() successfully queues the I/O
|
||
|
operation but the operation is subsequently canceled or
|
||
|
encounters an error, the return status of the asynchronous operation
|
||
|
is one of the values normally returned by the \fIread\fP() function
|
||
|
call. In addition, the error status of the asynchronous operation
|
||
|
is set to one
|
||
|
of the error statuses normally set by the \fIread\fP() function call,
|
||
|
or one of the following
|
||
|
values:
|
||
|
.TP 7
|
||
|
.B EBADF
|
||
|
The \fIaiocbp\fP->\fIaio_fildes\fP argument is not a valid file descriptor
|
||
|
open for reading.
|
||
|
.TP 7
|
||
|
.B ECANCELED
|
||
|
The requested I/O was canceled before the I/O completed due to an
|
||
|
explicit \fIaio_cancel\fP() request.
|
||
|
.TP 7
|
||
|
.B EINVAL
|
||
|
The file offset value implied by \fIaiocbp\fP->\fIaio_offset\fP would
|
||
|
be invalid.
|
||
|
.sp
|
||
|
.LP
|
||
|
The following condition may be detected synchronously or asynchronously:
|
||
|
.TP 7
|
||
|
.B EOVERFLOW
|
||
|
The file is a regular file, \fIaiobcp\fP->\fIaio_nbytes\fP is greater
|
||
|
than 0, and the starting offset in
|
||
|
\fIaiobcp\fP->\fIaio_offset\fP is before the end-of-file and is at
|
||
|
or beyond the offset maximum in the open file description
|
||
|
associated with \fIaiocbp\fP->\fIaio_fildes\fP.
|
||
|
.sp
|
||
|
.LP
|
||
|
\fIThe following sections are informative.\fP
|
||
|
.SH EXAMPLES
|
||
|
.LP
|
||
|
None.
|
||
|
.SH APPLICATION USAGE
|
||
|
.LP
|
||
|
The \fIaio_read\fP() function is part of the Asynchronous Input and
|
||
|
Output option and need not be available on all
|
||
|
implementations.
|
||
|
.SH RATIONALE
|
||
|
.LP
|
||
|
None.
|
||
|
.SH FUTURE DIRECTIONS
|
||
|
.LP
|
||
|
None.
|
||
|
.SH SEE ALSO
|
||
|
.LP
|
||
|
\fIaio_cancel\fP() , \fIaio_error\fP() , \fIlio_listio\fP() , \fIaio_return\fP()
|
||
|
, \fIaio_write\fP() , \fIclose\fP() , \fIexec\fP() , \fIexit\fP()
|
||
|
, \fIfork\fP() , \fIlseek\fP() , \fIread\fP() , the Base Definitions
|
||
|
volume of
|
||
|
IEEE\ Std\ 1003.1-2001, \fI<aio.h>\fP
|
||
|
.SH COPYRIGHT
|
||
|
Portions of this text are reprinted and reproduced in electronic form
|
||
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
||
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
||
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
||
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
||
|
event of any discrepancy between this version and the original IEEE and
|
||
|
The Open Group Standard, the original IEEE and The Open Group Standard
|
||
|
is the referee document. The original Standard can be obtained online at
|
||
|
http://www.opengroup.org/unix/online.html .
|