aio_read(3P4)

NAME

aio_read − asynchronous read

SYNOPSIS

#include <aio.h>

int aio_read(aiocbp)

struct aiocb ∗aiocbp;

DESCRIPTION

The aio_read function allows the calling process to read aiocbp->aio_nbytes from the file associated with aiocbp->aio_fildes into the buffer pointed to by aiocbp->aio_buf. The function call returns after the request is successfully queued.

The requested read operation takes place at the absolute position in the file as given by aiocbp->aio_offset, as if lseek(2) were called immediately prior to the read with an offset equal to aiocbp->aio_offset and a whence equal to SEEK_SET. After a successful call to queue an asynchronous read operation, the value of the file offset for the file is aiocbp->aio_offset plus aiocbp->aio_nbytes.

If prioritized I/O is supported for the specified file and the process is scheduled under either the SCHED_RR or SCHED_FIFO scheduling policies, then the asynchronous read operation is submitted at a priority equal to (process priority minus aiocbp->aio_reqprio). aiocbp->aio_reqprio must be a value from zero through AIO_PRIO_DELTA_MAX. Currently, prioritized I/O is only supported for disk files.

The aiocbp value may be used as an argument to aio_error(3P4) and aio_return(3P4) to determine the error status and return status, respectively, of the asynchronous operation while it is proceeding. If an error condition is encountered while attempting to queue the operation, aio_read returns without having initiated or queued the request.

The aiocbp->aio_lio_opcode field is ignored by aio_read.

If synchronized I/O is enabled on the file associated with aiocbp->aio_fildes, the behavior of this function is modified according to the definitions of synchronized I/O data integrity completion and synchronized I/O file integrity completion. See open(2) and fcntl(2).

On close(2), cancelable operations for the file descriptor may be deleted. All operations which are not canceled are completed as if the close(2) blocked until the operations completed. An asynchronous I/O request is still cancelable if the request hasn’t been submitted to the device.

On _exit(2) and exec(2), cancelable operations for all file descriptors may be deleted. All operations which are not canceled shall complete as if there were no call to _exit(2) or exec(2), but any associated signal notifications are suppressed. For fork(2), no asynchronous I/O is inherited.

RETURN VALUE

The aio_read function returns the value 0 to the calling process if the I/O operation is successfully queued; otherwise, the function returns the value -1 and sets errno to indicate the error.

If any of the following conditions occur, the aio_read function returns a -1 and sets errno to the corresponding value:

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

[EFAULT] The system is unable to access the aiocb structure that the aiocbp argument points to.

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

[EINVAL] The file offset value specified by aiocbp->aio_offset would be invalid, aiocbp->aio_reqprio is not a valid value, or aiocbp->aio_nbytes is an invalid value.

If the aio_read call successfully queues the I/O operation but the operation encounters an error, the error status of the asynchronous operation, which is returned by aio_error(3P4), will be one of the errors normally returned by the read(2) function call. If the operation is canceled via the aio_cancel(3P4) function, the status of the asynchronous operation will be ECANCELED.

FILES

/usr/lib/libposix4.a

WARNING

The interface to aio_read is based on IEEE Draft Standard P1003.4/D12. This is an unapproved draft, subject to change. Use of information contained in this unapproved draft is at your own risk. This interface will change to reflect any changes made by future drafts of POSIX 1003.4.

CX/UX Programmer’s Reference Manual

Museum

Related Articles