aio_read(3)aio_read(3)NAMEaio_read - Queues a single asynchronous read request
SYNOPSIS
#include <aio.h>
int aio_read (
struct aiocb *aiocbp );
LIBRARY
Asynchronous I/O Library (libaio, libaio_raw)
PARAMETERS
A pointer to an aiocb structure.
DESCRIPTION
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 initi‐
ated, the aio_read function returns with an error status. If an error
condition occurs during queuing, the function call returns without ini‐
tiating 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 gen‐
erated 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.
RETURN VALUES
On an unsuccessful call, a value of -1 is returned and errno is set to
indicate the type of error that occurred.
ERRORS
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 oper‐
ation 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 fol‐
lowing additional errors may occur: The operation was canceled by
aio_cancel. The offset in aio_offset is invalid for the file speci‐
fied.
SEE ALSO
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)
