lio_listio()

Initiate a list of I/O requests

Synopsis:

#include <aio.h>

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

Arguments:

mode

The mode of operation; one of:

LIO_WAIT — lio_listio() behaves synchronously, waiting until all I/O is completed, and ignores the sig argument.
LIO_NOWAIT — lio_listio() behaves asynchronously, returning immediately, and the signal specified by the sig argument is delivered to the calling process when all the I/O operations from this function are completed.

list

An array of pointers to aiocb structures that specify the I/O operations that you want to initiate. The array may contain NULL pointers, which the function ignores.

nent

The number of entries in the list array. This must not exceed the system-wide limit, _POSIX_AIO_MAX.

sig

NULL, or a pointer to a sigevent structure that specifies the signal that you want to deliver to the calling process when all of the I/O operations are completed. The function ignores this argument if mode is LIO_WAIT.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The lio_listio() function lets the calling process, lightweight process (LWP), or thread initiate a list of I/O requests within a single function call.

The aio_lio_opcode field of each aiocb structure in list specifies the operation to be performed (see <aio.h>):

LIO_READ requests aio_read().
LIO_WRITE requests aio_write().
LIO_NOP causes the list entry to be ignored.

If mode is LIO_NOWAIT, lio_listio() uses the sigevent structure pointed to by sig to define both the signal to be generated and how the calling process is notified when the I/O operations are complete:

If sig is NULL, or the sigev_signo member of the sigevent structure is zero, then no signal delivery occurs. Otherwise, the signal number indicated by sigev_signo is delivered when all the requests in the list have been completed.
If sig->sigev_notify is SIGEV_NONE, no signal is posted upon I/O completion, but the error status and the return status for the operation are set appropriately.
If sig->sigev_notify is SIGEV_SIGNAL, the signal specified in sig->sigev_signo is sent to the process. If the SA_SIGINFO flag is set for that signal number, the signal is queued to the process, and the value specified in sig->sigev_value is the si_value component of the generated signal.

For regular files, no data transfer occurs past the offset maximum established in the open file description associated with aiocbp->aio_fildes.

The behavior of this function is altered according to the definitions of synchronized I/O data integrity completion and synchronized I/O file integrity completion if synchronized I/O is enabled on the file associated with aio_fildes. (see the definitions of O_DSYNC and O_SYNC in the description of fcntl().)

Returns:

If the mode argument is LIO_NOWAIT, and the I/O operations are successfully queued, lio_listio() returns 0; otherwise, it returns -1, and sets errno.

If the mode argument is LIO_WAIT, and all the indicated I/O has been completed successfully, lio_listio() returns 0; otherwise, it returns -1, and sets errno.

In either case, the return value indicates only the success or failure of the lio_listio() call itself, not the status of the individual I/O requests. In some cases, one or more of the I/O requests contained in the list may fail. Failure of an individual request doesn't prevent completion of any other individual request. To determine the outcome of each I/O request, examine the error status associated with each aiocb control block. Each error status so returned is identical to that returned as a result of calling aio_read() or aio_write().

Errors:

EAGAIN: The resources necessary to queue all the I/O requests weren't available. The error status for each request is recorded in the aio_error member of the corresponding aiocb structure, and can be retrieved using aio_error().
The number of entries, nent, exceeds the system-wide limit, _POSIX_AIO_MAX.
EINVAL: The mode argument is invalid.
The value of nent is greater than _POSIX_AIO_LISTIO_MAX.
EINTR: A signal was delivered while waiting for all I/O requests to be completed during an LIO_WAIT operation. However, the outstanding I/O requests aren't canceled. Use aio_fsync() to determine if any request was initiated; aio_return() to determine if any request has been completed; or aio_error() to determine if any request was canceled.
EIO: One or more of the individual I/O operations failed. Use aio_error() with each aiocb structure to determine which request(s) failed.
ENOSYS: The lio_listio() function isn't supported by this implementation.

If either lio_listio() succeeds in queuing all of its requests, or errno is set to EAGAIN, EINTR, or EIO, then some of the I/O specified from the list may have been initiated. In this event, each aiocb structure contains errors specific to the read() or write() function being performed:

EAGAIN: The requested I/O operation wasn't queued due to resource limitations.
ECANCELED: The requested I/O was canceled before the I/O was completed due to an explicit aio_cancel() request.
EINPROGRESS: The requested I/O is in progress.

The following additional error codes may be set for each aiocb control block:

EOVERFLOW: The aiocbp->aio_lio_opcode is LIO_READ, the file is a regular file, aiocbp->aio_nbytes is greater than 0, and the aiocbp->aio_offset is before the end-of-file and is greater than or equal to the offset maximum in the open file description associated with aiocbp->aio_fildes.
EFBIG: The aiocbp->aio_lio_opcode is LIO_WRITE, the file is a regular file, aiocbp->aio_nbytes is greater than 0, and the aiocbp->aio_offset is greater than or equal to the offset maximum in the open file description associated with aiocbp->aio_fildes.

Classification:

POSIX 1003.1 AIO

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes