aio_read()

Asynchronously read from a file

Synopsis:

#include <aio.h>

int aio_read( struct aiocb * aiocbptr );

Arguments:

aiocbptr

A pointer to an asynchronous I/O control block of type aiocb that defines how much data to read, and from where.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The aio_read() function asynchronously reads aiocbptr->aio_nbytes from the file associated with aiocbptr->aio_fildes into the buffer pointed to by aiocbptr->aio_buf. It returns when the read request has been initiated or queued to the file or device (even when the data can't be delivered immediately).

You can pass the aiocbptr argument to aio_error() and aio_return(), to determine the error status and return status of the asynchronous operation while it's proceeding. If an error condition is encountered during queuing, the function call returns without having initiated or queued the request. 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 of SEEK_SET. After a successful call to enqueue an asynchronous I/O operation, the value of the file offset for the file is unspecified.

This function ignores the aiocbptr->aio_lio_opcode field.

The following conditions may be detected synchronously at the time of the call to aio_read(), or asynchronously. If any of these conditions are detected synchronously, aio_read() returns -1 and sets errno to the corresponding value. If any of these conditions are detected asynchronously, the return status of the asynchronous operation is set to -1, and the error status of the asynchronous operation is set to the corresponding value:

EBADF

The aiocbptr->aio_fildes argument isn't a valid file descriptor that's open for reading.

EINVAL

The file offset value implied by aiocbptr->aio_offset would be invalid, aiocbptr->aio_reqprio isn't a valid value, or aiocbptr->aio_nbytes is invalid.

If 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 values normally returned by read(). In addition, the error status of the asynchronous operation is set to one of the error statuses normally set read(), or one of the following:

EBADF

The aiocbptr->aio_fildes isn't a valid file descriptor that's open for reading.

ECANCELED

The requested I/O was canceled before the I/O was completed, due to an explicit aio_cancel(), request.

EINVAL

The file offset value implied by aiocbptr->aio_offset would be invalid.

The following condition may be detected synchronously or asynchronously:

EOVERFLOW

The file is a regular file, aiocbptr->aio_nbytes is greater than 0, and the starting offset in aiocbptr->aio_offset is before the end of the file and is at or beyond the offset maximum in the open file description associated with aiocbptr->aio_fildes.

Returns:

0 if the I/O operation was successfully queued, or -1 if an error occurred (errno is set).

Errors:

EAGAIN

The requested asynchronous I/O operation wasn't queued because of system resource limitations.

Classification:

POSIX 1003.1 AIO

Caveats:

The first time you call an aio_* function, a thread pool is created, making your process multithreaded if it isn't already. The thread pool isn't destroyed until your process ends.

See also:

aio_cancel(), aio_error(), aio_fsync(), aio_return(), aio_suspend(), aio_write(), read()