Next: Status of AIO Operations, Up: Asynchronous I/O
This function initiates an asynchronous read operation. It immediately returns after the operation was enqueued or when an error was encountered.
The first
aiocbp->aio_nbytesbytes of the file for whichaiocbp->aio_fildesis a descriptor are written to the buffer starting ataiocbp->aio_buf. Reading starts at the absolute positionaiocbp->aio_offsetin the file.If prioritized I/O is supported by the platform the
aiocbp->aio_reqpriovalue 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
aiocbp->aio_sigeventvalue.When
aio_readreturns, 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 -1 and setserrnoto one of the following values:
EAGAIN- The request was not enqueued due to (temporarily) exceeded resource limitations.
ENOSYS- The
aio_readfunction is not implemented.EBADF- The
aiocbp->aio_fildesdescriptor is not valid. This condition need not be recognized before enqueueing the request and so this error might also be signaled asynchronously.EINVAL- The
aiocbp->aio_offsetoraiocbp->aio_reqpirovalue is invalid. This condition need not be recognized before enqueueing the request and so this error might also be signaled asynchronously.If
aio_readreturns zero, the current status of the request can be queried usingaio_errorandaio_returnfunctions. As long as the value returned byaio_errorisEINPROGRESSthe operation has not yet completed. Ifaio_errorreturns 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 toaio_return. The returned value is the same as an equivalent call toreadwould have returned. Possible error codes returned byaio_errorare:
EBADF- The
aiocbp->aio_fildesdescriptor is not valid.ECANCELED- The operation was canceled before the operation was finished (see Cancel AIO Operations)
EINVAL- The
aiocbp->aio_offsetvalue is invalid.When the sources are compiled with
_FILE_OFFSET_BITS == 64this function is in factaio_read64since the LFS interface transparently replaces the normal implementation.
This function is similar to the
aio_readfunction. The only difference is that on 32 bit machines, the file descriptor should be opened in the large file mode. Internally,aio_read64uses functionality equivalent tolseek64(see File Position Primitive) to position the file descriptor correctly for the reading, as opposed tolseekfunctionality used inaio_read.When the sources are compiled with
_FILE_OFFSET_BITS == 64, this function is available under the nameaio_readand so transparently replaces the interface for small files on 32 bit machines.
To write data asynchronously to a file, there exists an equivalent pair of functions with a very similar interface.
This function initiates an asynchronous write operation. The function call immediately returns after the operation was enqueued or if before this happens an error was encountered.
The first
aiocbp->aio_nbytesbytes from the buffer starting ataiocbp->aio_bufare written to the file for whichaiocbp->aio_fildesis an descriptor, starting at the absolute positionaiocbp->aio_offsetin the file.If prioritized I/O is supported by the platform, the
aiocbp->aio_reqpriovalue 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
aiocbp->aio_sigeventvalue.When
aio_writereturns, 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 -1 and setserrnoto one of the following values.
EAGAIN- The request was not enqueued due to (temporarily) exceeded resource limitations.
ENOSYS- The
aio_writefunction is not implemented.EBADF- The
aiocbp->aio_fildesdescriptor is not valid. This condition may not be recognized before enqueueing the request, and so this error might also be signaled asynchronously.EINVAL- The
aiocbp->aio_offsetoraiocbp->aio_reqpriovalue is invalid. This condition may not be recognized before enqueueing the request and so this error might also be signaled asynchronously.In the case
aio_writereturns zero, the current status of the request can be queried usingaio_errorandaio_returnfunctions. As long as the value returned byaio_errorisEINPROGRESSthe operation has not yet completed. Ifaio_errorreturns 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 get using a call toaio_return. The returned value is the same as an equivalent call toreadwould have returned. Possible error codes returned byaio_errorare:
EBADF- The
aiocbp->aio_fildesdescriptor is not valid.ECANCELED- The operation was canceled before the operation was finished. (see Cancel AIO Operations)
EINVAL- The
aiocbp->aio_offsetvalue is invalid.When the sources are compiled with
_FILE_OFFSET_BITS == 64, this function is in factaio_write64since the LFS interface transparently replaces the normal implementation.
This function is similar to the
aio_writefunction. The only difference is that on 32 bit machines the file descriptor should be opened in the large file mode. Internallyaio_write64uses functionality equivalent tolseek64(see File Position Primitive) to position the file descriptor correctly for the writing, as opposed tolseekfunctionality used inaio_write.When the sources are compiled with
_FILE_OFFSET_BITS == 64, this function is available under the nameaio_writeand so transparently replaces the interface for small files on 32 bit machines.
Besides these functions with the more or less traditional interface,
POSIX.1b also defines a function which can initiate more than one
operation at a time, and which can handle freely mixed read and write
operations. It is therefore similar to a combination of readv and
writev.
The
lio_listiofunction can be used to enqueue an arbitrary number of read and write requests at one time. The requests can all be meant for the same file, all for different files or every solution in between.
lio_listiogets the nent requests from the array pointed to by list. The operation to be performed is determined by theaio_lio_opcodemember in each element of list. If this field isLIO_READa read operation is enqueued, similar to a call ofaio_readfor this element of the array (except that the way the termination is signalled is different, as we will see below). If theaio_lio_opcodemember isLIO_WRITEa write operation is enqueued. Otherwise theaio_lio_opcodemust beLIO_NOPin which case this element of list is simply ignored. This “operation” is useful in situations where one has a fixed array ofstruct aiocbelements from which only a few need to be handled at a time. Another situation is where thelio_listiocall was canceled before all requests are processed (see Cancel AIO Operations) and the remaining requests have to be reissued.The other members of each element of the array pointed to by
listmust have values suitable for the operation as described in the documentation foraio_readandaio_writeabove.The mode argument determines how
lio_listiobehaves after having enqueued all the requests. If mode isLIO_WAITit waits until all requests terminated. Otherwise mode must beLIO_NOWAITand in this case the function returns immediately after having enqueued all the requests. In this case the caller gets a notification of the termination of all requests according to the sig parameter. If sig isNULLno notification is send. Otherwise a signal is sent or a thread is started, just as described in the description foraio_readoraio_write.If mode is
LIO_WAIT, the return value oflio_listiois 0 when all requests completed successfully. Otherwise the function return -1 anderrnois set accordingly. To find out which request or requests failed one has to use theaio_errorfunction on all the elements of the array list.In case mode is
LIO_NOWAIT, the function returns 0 if all requests were enqueued correctly. The current state of the requests can be found usingaio_errorandaio_returnas described above. Iflio_listioreturns -1 in this mode, the global variableerrnois set accordingly. If a request did not yet terminate, a call toaio_errorreturnsEINPROGRESS. If the value is different, the request is finished and the error value (or 0) is returned and the result of the operation can be retrieved usingaio_return.Possible values for
errnoare:
EAGAIN- The resources necessary to queue all the requests are not available at the moment. The error status for each element of list must be checked to determine which request failed.
Another reason could be that the system wide limit of AIO requests is exceeded. This cannot be the case for the implementation on GNU systems since no arbitrary limits exist.
EINVAL- The mode parameter is invalid or nent is larger than
AIO_LISTIO_MAX.EIO- One or more of the request's I/O operations failed. The error status of each request should be checked to determine which one failed.
ENOSYS- The
lio_listiofunction is not supported.If the mode parameter is
LIO_NOWAITand the caller cancels a request, the error status for this request returned byaio_errorisECANCELED.When the sources are compiled with
_FILE_OFFSET_BITS == 64, this function is in factlio_listio64since the LFS interface transparently replaces the normal implementation.
This function is similar to the
lio_listiofunction. The only difference is that on 32 bit machines, the file descriptor should be opened in the large file mode. Internally,lio_listio64uses functionality equivalent tolseek64(see File Position Primitive) to position the file descriptor correctly for the reading or writing, as opposed tolseekfunctionality used inlio_listio.When the sources are compiled with
_FILE_OFFSET_BITS == 64, this function is available under the namelio_listioand so transparently replaces the interface for small files on 32 bit machines.