Digital

NAME

aio_read − queue an asynchronous read request on the specified file descriptor (P1003.4/D10)

SYNOPSIS

#include <aio.h>

int aio_read (
int fildes ,
struct aiocb ∗aiocbp) ;

PARAMETERS

fildes The file descriptor of the file from which data is read. 

aiocbp A pointer to an aiocb structure. 

DESCRIPTION

The aio_read function issues a read request and returns when the request is initiated or queued, even when the data cannot be delivered immediately. If an error condition occurs during queueing, the function call returns without initiating the queue request. 

The aiocbp argument points to an asynchronous control block structure, aiocb, used in many of the asynchronous I/O interfaces.  The aiocbp structure contains asychronous operation information, such as the initial point for the read operation, and a handle value that is used to determine the error and return status of the asynchronous operation.  The aiocb structure has the following members:

int aio_whence;

off_t aio_offset;

volatile char ∗aio_buf;

size_t aio_nbytes;

int aio_reqprio;

struct sigevent aio_event;

int aio_flag;

aiohandle_t aio_handle;

The aio_whence and aio_offset members are the same as the whence and offset arguments defined by the lseek function. If aio_whence is set to SEEK_CUR and aio_offset is zero, no implied lseek takes place.  When the asynchronous I/O completes, the aio_whence and aio_offset members update the file pointer to the next byte after the number of bytes that were read. 

The aio_nbytes and aio_buf members are the same as the nbyte and buf arguments defined by the read function. 

The aio_reqprio member defines the priority of the asynchronous I/O operation and serves as an indicator of the desired order of execution relative to other asynchronous I/O operations requested by the process. If more than one request has the same priority, execution is done on a first in, first out basis. The value of the aio_reqprio member must be within the range AIO_PRIO_MIN and AIO_PRIO_MAX. The default priority is specified as AIO_PRIO_DFL. These symbols are defined in the <limits.h> header file. 

The aio_event member defines the signal generated once the I/O operation is complete. If the AIO_EVENT bit in aio_flag is zero, no signal is sent.  Whether the operation fails or succeeds, the error and return status for the operation will be appropriately set and can be retrieved using the aio_error and aio_return functions. 

The aio_handle member is a unique identifier, which is set when the asynchronous I/O operation is first submitted. Each separate asynchronous I/O operation, whether submitted as an aio_read or as a single item in a list using the lio_listio function, has a unique handle associated with the I/O request. The handle is used by the aio_error and aio_return functions to return status information for the specific asynchronous I/O request. 

Pending asynchronous I/O operations are handled as follows:

•On close, the close function waits for all asynchronous I/O to complete before closing the file. 

•On _exit and fork, outstanding asynchronous I/O operations are undefined. 

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 fildes argument is not a valid file descriptor open for reading. 

[EFAULT] The aiocbp argument was not a valid address. 

[EINVAL] The aio_whence member is not a proper value, or the resulting file pointer is invalid. 

In the case that aio_read successfully queues the I/O operation, but the operation is subsequently canceled or encounters an error, the return status of the asynchronous operation is one of the status values normally returned by the read function. In this case, errno is set to the following value:

[ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit aio_cancel request. 

Use the aio_error and aio_return functions to retrieve the error and return status. 

RELATED INFORMATION

aio_cancel(3), aio_error(3), aio_return(3), aio_write(3), lio_listio(3)