aio_read(3aio) aio_read(3aio)
NAME
aio_read - asynchronous read
SYNOPSIS
cc [options] -D_REENTRANT file -lthread
#include <aio.h>
int aio_read(struct aiocb *aiocbp);
DESCRIPTION
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 status members.
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 aio_sigevent.sigev_notify to SIGEV_CALLBACK,
aio_sigevent.sigev_func to the address of the function to be
called, and aio_sigevent.sigev_value to the argument to be
passed to the function. You may also want the
aio_sigevent.sigev_value to be the address of the asynchronous
I/O control block that was used to initiate the I/O request.
[See aiocb(5)].
If the control block pointed to by aiocbp or the buffer
pointed to by aiocpb->aio_buf 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 or device. If an error
condition is encountered during queuing, the call returns -1
without having initiated or queued the request.
Return Values
After successfully completing the call to aio_read, aio_read
returns 0 and the structure member aio_errno is set to
EINPROGRESS. If the call to aio_read 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.
Copyright 1994 Novell, Inc. Page 1
aio_read(3aio) aio_read(3aio)
Errors
There are two types of errors that are associated with an
asynchronous I/O request. The first occurs during the
validity checking of the I/O request submitted by the aio_read
routine. This error is returned to the caller of aio_read.
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
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 which could successfully complete.
However, aio_error then returns EBADF to indicate the error.
Under the following conditions, aio_read fails and sets errno
or the aio_errno structure member to:
EAGAIN The requested asynchronous I/O operation was not queued
because of system resource limitations.
EFAULT aiocbp or the aio_buf member points outside the
allocated address space.
ECANCELED
The requested I/O was canceled before the I/O completed
because of aio_cancel.
EINVAL On SVR4.2, the request does not have the AIO_RAW flag
bit set in aio_flags.
REFERENCES
aio_cancel(3aio), aiocb(5), aio_suspend(3aio),
aio_write(3aio), read(2)
NOTICES
When developing applications for both SVR4.2 and future
versions, the AIO_RAW flag should be set in aio_flags to
insure that performance is maintained.
Copyright 1994 Novell, Inc. Page 2