aio_read, aio_read64 --
cc [options] -Kthread file
int aio_read(struct aiocb *aiocbp);
int aio_read64(struct aiocb64 *aiocbp);
aio_read supports an
asynchronous read capability that allows the calling process to read
aiocbp->aio_nbytes from the file associated with
the file descriptor aiocbp->aio_fildes
into the buffer pointed to by aiocbp->aio_buf.
aiocbp points to an aiocb
structure which contains other input parameters as well as completion
If you do not wish to be notified of completion,
you should set aio_sigevent.sigev_notify to
SIGEV_NONE in the asynchronous I/O control block.
If you require notification,
you must set the
to the address of the function to be called,
to the argument to be passed to the function.
You may also want the
to be the address of the asynchronous I/O control
block that was used to initiate the I/O request.
If the control block pointed to by
aiocbp or the buffer pointed to by
becomes an invalid address prior to asynchronous I/O completion,
then the behavior is undefined.
The call to aio_read
returns 0 when the read request has been initiated or queued to the file
If an error condition is encountered during queuing,
the call returns -1 without having initiated or queued the request.
After successfully completing, calls to aio_read and aio_read64 return 0 and
the structure member
aio_errno is set to
If a call to aio_read or aio_read64 fails,
-1 is returned with errno set to indicate the error.
After the read operation has successfully completed, the
aio_error function is set to 0.
The return value of the underlying read can
be assessed with the aio_return function.
There are two types of errors that are associated with an asynchronous
The first occurs during the validity checking of the I/O request submitted
by the aio_read and aio_read64 routines.
This error is returned to the caller of
aio_read or aio_read64.
The other occurs during the processing of the actual read operation.
The read operation may fail for any of the reasons that a normal
read may fail.
If the call to aio_read or aio_read64
successfully queues the I/O operation but the operation
is canceled or encounters an error,
the aio_error function
returns one of the values normally returned by the
read system call or one of the errors listed below.
The time at which the error occurs is implementation-dependent;
for example, an invalid file descriptor may not be determined at the
time of the call to
aio_read or aio_read64 which could successfully
However, aio_error then returns
EBADF to indicate the error.
Under the following conditions, aio_read fails and sets errno
aio_errno structure member to:
The file is a regular file,
greater than 0 and the starting offset in
aiocbp->aio_offset is before the end-of-file
and is at or beyond the offset maximum in the open file
descriptor associated with
Under the following conditions, aio_read
and aio_read64 fail and set errno
aio_errno structure member to:
The requested asynchronous I/O operation was not queued
because of system resource limitations.
aiocbp or the aio_buf
member points outside the allocated address space.
The requested I/O was canceled before the I/O completed
because of aio_cancel.
On SVR4.2, the request does not have the
AIO_RAW flag bit set in aio_flags.
There were no internal kernal aio control blocks available to service
the request (number of kernel aio control blocks is tunable via
the NUMAIO kernel parameter; see
``Miscellaneous parameters'' in Monitoring and tuning the system).
When developing applications for both SVR4.2 and future versions, the
flag should be set in aio_flags to insure that performance is
Considerations for large file support
aio_read64 supports large files, but is otherwise identical
For details on programming for large file capable applications, see
``Large File Support''
© 2004 The SCO Group, Inc. All rights reserved.
UnixWare 7 Release 7.1.4 - 25 April 2004