aio_read - Queues a single asynchronous read request
#include <aio.h>
int aio_read (
struct aiocb *aiocbp );
Asynchronous I/O Library (libaio, libaio_raw)
A pointer to an aiocb structure.
The aio_read function allows the calling process to asynchronously
read aiocbp->aio_nbytes from the file associated
with aiocbp->aio_fildes into the buffer pointed to by
aiocbp->aio_buf.
The aio_read function issues a read request and returns
even when the data cannot be delivered immediately. If the
request cannot be initiated, the aio_read function returns
with an error status. If an error condition occurs during
queuing, the function call returns without initiating the
queue request. The aiocbp value may be used as an argument
to the aio_error and aio_return functions to determine the
error or return status of the asynchronous read operation.
The requested operation takes place at the absolute position
in the file as given by aio_offset, as if lseek()
were called immediately prior to the operation with an
offset equal to aio_offset and a whence equal to SEEK_SET.
The aiocbp argument points to an asynchronous control
block structure, aiocb, used in the asynchronous I/O
interfaces. The aiocb structure contains asynchronous
operation information, such as the file offset for the
read operation. The aiocb structure has the following members:
aio_fildes; aio_offset; *aio_buf; aio_nbytes;
aio_reqprio; aio_sigevent; aio_lio_opcode;
The aio_fildes member is the file descriptor on which the
asynchronous operation is to be performed. After any asynchronous
I/O operation, the aio_offset member is undefined
and must be set explicitly for every asynchronous I/O
request.
The aio_nbytes and aio_buf members are the same as the
nbyte and buf arguments defined by POSIX.1 read and write
functions.
The aio_sigevent member of the aiocb structure defines the
signal generated when the I/O operation is complete. If
aio_sigevent.sigev_notify equals SIGEV_SIGNAL and
aio_sigevent.sigev_signo is non-zero, a signal is generated
when the asynchronous read operation has completed.
The aio_lio_opcode and aio_reqprio members are ignored by
aio_read().
Pending asynchronous I/O operations are handled as follows:
On close, _exit, or exec, any I/O that was directed
to a file system file, a tty device, or a streams device
is canceled. Any I/O that was directed to any raw character
device, excluding terminal and streams devices, is not
canceled. On fork, no asynchronous I/O is inherited.
On an unsuccessful call, a value of -1 is returned and
errno is set to indicate the type of error that occurred.
The aio_read function fails under the following conditions:
The requested asynchronous I/O operation was not
queued due to system resource limitations. The
aiocbp->aio_fildes argument is not a valid file descriptor
open for reading. The file offset value implied by
aiocbp->aio_offset would be invalid.
On a successful call, a value of 0 (zero) is returned and
the I/O operation is queued. After successful queuing of
aio_read, return and error values are the same as for a
call to the read function. One of the following additional
errors may occur: The operation was canceled by aio_cancel.
The offset in aio_offset is invalid for the file
specified.
Functions: close(2), exec(2), _exit(2), fork(2), lseek(2),
read(2), write(2), aio_cancel(3), aio_error(3),
aio_group_completion_np(3), aio_results_np(3),
aio_return(3), aio_suspend(3), aio_write(3), lio_listio(3)
Guide to Realtime Programming
aio_read(3)
[ Back ] |
