*** UNIX MANUAL PAGE BROWSER ***

aio_read(3) Library Functions Manual aio_read(3) NAME aio_read - Queue a single asynchronous read request SYNOPSIS #include <aio.h> int aio_read ( struct aiocb *aiocbp ); 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 re- turn 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: int aio_fildes; off_t aio_offset; volatile void *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. The aio_sigevent member of the aiocb structure defines the signal gen- erated once the I/O operation is complete. If aio_sigevent.sigev_no- tify equals SIGEV_SIGNAL and aio_sigevent.sigev_signo is non-zero, a signal will be generated when the asynchronous read operation has com- pleted. The aio_lio_opcode and aio_reqprio members are ignored by aio_read(). Pending asynchronous I/O operations are handled as follows: o On close, _exit, or exec, any I/O that was directed to a file sys- tem file, a tty device, or a streams device is cancelled. Any I/O that was directed to any raw character device, excluding terminal and streams devices, is not cancelled. o 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: [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 de- scriptor open for reading. [EINVAL] The file offset value implied by aiocbp->aio_offset would be invalid. On a successful call, a value of 0 is returned and the I/O operation 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 following additional errors may occur: [ECANCELED] The operation was cancelled by aio_cancel. [EINVAL] The offset in aio_offset is invalid for the file specified. RELATED INFORMATION 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_write(3), lio_listio(3). delim off aio_read(3)