lio_listio(), lio_listio64()

Initiate a list of I/O requests


#include <aio.h>

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

int lio_listio64( int mode,
                  struct aiocb64* const list[],
                  int nent,
                  struct sigevent* sig );


The mode of operation; one of:
  • LIO_WAIT — behave synchronously, waiting until all I/O is completed, and ignore the sig argument.
  • LIO_NOWAIT — behave asynchronously, returning immediately; the signal specified by the sig argument is delivered to the calling process when all the I/O operations from this function are completed.
An array of pointers to aiocb or aiocb64 structures that specify the I/O operations that you want to initiate. The array may contain NULL pointers, which the function ignores.
The number of entries in the list array. This must not exceed the system-wide limit, _POSIX_AIO_MAX.
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.



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


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 lio_listio64() function is a large-file version of lio_listio().

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

If mode is LIO_NOWAIT, lio_listio() and lio_listio64() use 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() .)


If the mode argument is LIO_NOWAIT, and the I/O operations are successfully queued, these functions return 0; otherwise they return -1 and set errno .

If the mode argument is LIO_WAIT, and all the indicated I/O has been completed successfully, these functions return 0; otherwise, they return -1 and set 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().


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.

The mode argument is invalid.

The value of nent is greater than _POSIX_AIO_LISTIO_MAX.

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.
One or more of the individual I/O operations failed. Use aio_error() with each aiocb structure to determine which request(s) failed.
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:

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

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

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.
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.


lio_listio() is POSIX 1003.1 AIO; lio_listio64() is Large-file support

Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes