NAME

aio_read − Queue an asynchronous read request on the specified file descriptor (P1003.1b)

SYNOPSIS

#include <aio.h>

int aio_read (
struct aiocb ∗aiocbp);

PARAMETERS

aiocbp A pointer to an aiocb structure. 

DESCRIPTION

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 aiocbp structure contains asynchronous operation information, such as the file offset for the read operation.  The aiocb structure has the following members:

int aio_fildes;

off_t aio_offset;

volatile char ∗aio_buf;

size_t aio_nbytes;

int aio_reqprio;

struct sigevent aio_sigevent;

int 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. 

Prioritized asynchronous I/O operations are not supported for this release.  For portability reasons, set the aio_reqprio member to AIO_PRIO_DFL, default priority as defined in the <limits.h> header file. 

The aio_sigevent member defines the signal generated once the I/O operation is complete. If aio_sigevent.sevt_signo is zero, no signal is posted on completion. 

The aio_lio_opcode member is ignored by aio_read(). 

Pending asynchronous I/O operations are handled as follows:

•On close, outstanding asynchronous I/O operations can be canceled. 

•On _exit and exec, outstanding asynchronous I/O operations can be canceled. 

•On fork, no asynchronous I/O is inherited. 

RETURN VALUES

On a successful call, a value of 0 is returned and the function is queued. 

On an unsuccessful call, a value of −1 is returned and errno is set to indicate that an error occurred. 

ERRORS

The aio_read function fails under the following conditions:

[EAGAIN] The requested asynchronous I/O operation was not queued due to system resource limitations. 

[EBADF] The aiocbp−>aio_fildes argument is not a valid file descriptor open for reading. 

[EINVAL] The file offset value implied by aiocbp−>aio_offset would be invalid. 

RELATED INFORMATION

Functions: close(2), exec(2), _exit(2), fork(2), lseek(2), read(2), write(2), aio_cancel(3), aio_error(3), aio_return(3), aio_write(3), lio_listio(3)