| .TH aio_read 3 2002-09-12 "Linux 2.4" Linux AIO" |
| .SH NAME |
| aio_read \- Initiate an asynchronous read operation |
| .SH SYNOPSYS |
| .nf |
| .B #include <errno.h> |
| .sp |
| .br |
| .B #include <aio.h> |
| .sp |
| .br |
| .BI "int aio_read (struct aiocb *aiocbp)" |
| .fi |
| .SH DESCRIPTION |
| This function initiates an asynchronous read operation. It |
| immediately returns after the operation was enqueued or when an |
| error was encountered. |
| |
| The first |
| .IR "aiocbp->aio_nbytes" |
| bytes of the file for which |
| .IR "aiocbp->aio_fildes" |
| is a descriptor are written to the buffer |
| starting at |
| .IR "aiocbp->aio_buf" |
| . Reading starts at the absolute |
| position |
| .IR "aiocbp->aio_offset" |
| in the file. |
| |
| If prioritized I/O is supported by the platform the |
| .IR "aiocbp->aio_reqprio" |
| value is used to adjust the priority before |
| the request is actually enqueued. |
| |
| The calling process is notified about the termination of the read |
| request according to the |
| .IR "aiocbp->aio_sigevent" |
| value. |
| |
| .SH "RETURN VALUES" |
| When |
| .IR "aio_read" |
| returns, the return value is zero if no error |
| occurred that can be found before the process is enqueued. If such an |
| early error is found, the function returns |
| .IR -1 |
| and sets |
| .IR "errno". |
| |
| .PP |
| If |
| .IR "aio_read" |
| returns zero, the current status of the request |
| can be queried using |
| .IR "aio_error" |
| and |
| .IR "aio_return" |
| functions. |
| As long as the value returned by |
| .IR "aio_error" |
| is |
| .IR "EINPROGRESS" |
| the operation has not yet completed. If |
| .IR "aio_error" |
| returns zero, |
| the operation successfully terminated, otherwise the value is to be |
| interpreted as an error code. If the function terminated, the result of |
| the operation can be obtained using a call to |
| .IR "aio_return" |
| . The |
| returned value is the same as an equivalent call to |
| .IR "read" |
| would |
| have returned. |
| When the sources are compiled with |
| .IR "_FILE_OFFSET_BITS == 64" |
| this |
| function is in fact |
| .IR "aio_read64" |
| since the LFS interface transparently |
| replaces the normal implementation. |
| |
| .SH ERRORS |
| In the case of an early error: |
| .TP |
| .B EAGAIN |
| The request was not enqueued due to (temporarily) exceeded resource |
| limitations. |
| .TP |
| .B ENOSYS |
| The |
| .IR "aio_read" |
| function is not implemented. |
| .TP |
| .B EBADF |
| The |
| .IR "aiocbp->aio_fildes" |
| descriptor is not valid. This condition |
| need not be recognized before enqueueing the request and so this error |
| might also be signaled asynchronously. |
| .TP |
| .B EINVAL |
| The |
| .IR "aiocbp->aio_offset" |
| or |
| .IR "aiocbp->aio_reqpiro" |
| value is |
| invalid. This condition need not be recognized before enqueueing the |
| request and so this error might also be signaled asynchronously. |
| |
| .PP |
| In the case of a normal return, possible error codes returned by |
| .IR "aio_error" |
| are: |
| .TP |
| .B EBADF |
| The |
| .IR "aiocbp->aio_fildes" |
| descriptor is not valid. |
| .TP |
| .B ECANCELED |
| The operation was canceled before the operation was finished |
| .TP |
| .B EINVAL |
| The |
| .IR "aiocbp->aio_offset" |
| value is invalid. |
| .PP |
| .SH "SEE ALSO" |
| .BR aio(3), |
| .BR aio_cancel(3), |
| .BR aio_cancel64(3), |
| .BR aio_error(3), |
| .BR aio_error64(3), |
| .BR aio_fsync(3), |
| .BR aio_fsync64(3), |
| .BR aio_init(3), |
| .BR aio_read64(3), |
| .BR aio_return(3), |
| .BR aio_return64(3), |
| .BR aio_suspend(3), |
| .BR aio_suspend64(3), |
| .BR aio_write(3), |
| .BR aio_write64(3), |
| .BR errno(3), |
