lio_listio

lio_listio - List directed I/O

#include <errno.h>
#include <libaio.h>

I int lio_listio (int mode, struct aiocb *const list[], int nent, struct sigevent *sig)

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 R readv and R writev . The R lio_listio function 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. R lio_listio gets the R nent requests from the array pointed to by R list R aio_lio_opcode member in each element of R list field is LIO_READ a read operation is enqueued, similar to a call of R aio_read for this element of the array (except that the way the termination is signalled is different, as we will see below). If the R aio_lio_opcode member is LIO_WRITE a write operation is enqueued. Otherwise the R aio_lio_opcode must be LIO_NOP in which case this element of R list is simply ignored. This ``operation'' is useful in situations where one has a fixed array of R struct aiocb elements from which only a few need to be handled at a time. Another situation is where the R lio_listio call was canceled before all requests are processed and the remaining requests have to be reissued. The other members of each element of the array pointed to by R list must have values suitable for the operation as described in the documentation for R aio_read and R aio_write above. The R mode argument determines how R lio_listio behaves after having enqueued all the requests. If R mode is LIO_WAIT it waits until all requests terminated. Otherwise R mode must be LIO_NOWAIT and 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 R sig parameter. If R sig is NULL no notification is send. Otherwise a signal is sent or a thread is started, just as described in the description for R aio_read or R aio_write . When the sources are compiled with _FILE_OFFSET_BITS == 64 , this function is in fact R lio_listio64 since the LFS interface transparently replaces the normal implementation.

If R mode is LIO_WAIT , the return value of R lio_listio is R 0 when all requests completed successfully. Otherwise the function return R 1 and R errno is set accordingly. To find out which request or requests failed one has to use the R aio_error function on all the elements of the array R list . In case R mode is LIO_NOWAIT , the function returns R 0 if all requests were enqueued correctly. The current state of the requests can be found using R aio_error and R aio_return as described above. If R lio_listio returns R -1 in this mode, the global variable R errno is set accordingly. If a request did not yet terminate, a call to R aio_error returns EINPROGRESS the value is different, the request is finished and the error value (or R 0 ) is returned and the result of the operation can be retrieved using R aio_return .

Possible values for R errno are:

EAGAIN

EINVAL

EIO

ENOSYS

If the R mode parameter is LIO_NOWAIT and the caller cancels a request, the error status for this request returned by R aio_error is ECANCELED .

R aio(3), R aio_cancel(3), R aio_cancel64(3), R aio_error(3), R aio_error64(3), R aio_fsync(3), R aio_fsync64(3), R aio_init(3), R aio_read(3), R aio_read64(3), R aio_return(3), R aio_return64(3), R aio_suspend(3), R aio_suspend64(3), R aio_write(3), R aio_write64(3)