Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

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:
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>):

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:

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

See also:

aio_cancel(), aio_error(), aio_fsync(), aio_read(), aio_return(), aio_write(), aiocb, close(), execl(), execle(), execlp(), execlpe(), execv(), execve(), execvp(), execvpe(), exit(), fcntl(), fork(), lseek(), read(), sigevent, write()