NAME
lio_listio - List directed I/O
SYNOPSYS
#include <errno.h>
#include <libaio.h>
int lio_listio(int mode, struct aiocb *const list[], int nent, struct
sigevent *sig);
DESCRIPTION
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(2) and
writev(2).
The 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.
lio_listio gets the nent requests from the array pointed to by list.
The operation to be performed is determined by the aio_lio_opcode
member in each element of list. If this field is LIO_READ a read
operation is enqueued, similar to a call of 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 aio_lio_opcode member is
LIO_WRITE a write operation is enqueued. Otherwise the aio_lio_opcode
must be LIO_NOP in which case this element of list is simply ignored.
This ‘‘operation’’ is useful in situations where one has a fixed array
of struct aiocb elements from which only a few need to be handled at a
time. Another situation is where the 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 list must
have values suitable for the operation as described in the
documentation for aio_read and aio_write above.
The mode argument determines how lio_listio behaves after having
enqueued all the requests. If mode is LIO_WAIT it waits until all
requests terminated. Otherwise 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 sig parameter. If sig is
NULL no notification is send. Otherwise a signal is sent or a thread
is started, just as described in the description for aio_read or
aio_write.
When the sources are compiled with _FILE_OFFSET_BITS == 64, this
function is in fact lio_listio64 since the LFS interface transparently
replaces the normal implementation.
RETURN VALUES
If mode is LIO_WAIT, the return value of lio_listio is 0 when all
requests completed successfully. Otherwise the function return 1 and
errno is set accordingly. To find out which request or requests failed
one has to use the aio_error function 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 using aio_error and aio_return as described above. If lio_listio
returns -1 in this mode, the global variable errno is set accordingly.
If a request did not yet terminate, a call to aio_error returns
EINPROGRESS. 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 using aio_return.
ERRORS
Possible values for errno are:
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_listio function is not supported.
If the mode parameter is LIO_NOWAIT and the caller cancels a request,
the error status for this request returned by aio_error is ECANCELED.
SEE ALSO
aio(3), aio_cancel(3), aio_cancel64(3), aio_error(3), aio_error64(3),
aio_fsync(3), aio_fsync64(3), aio_init(3), aio_read(3), aio_read64(3),
aio_return(3), aio_return64(3), aio_suspend(3), aio_suspend64(3),
aio_write(3), aio_write64(3).