lio_listio(), lio_listio64()

Updated: April 19, 2023

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

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

Arguments:

mode
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.
list
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.
nent
The number of entries in the list array.
sig
NULL, or a pointer to a sigevent structure that specifies the notification 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() and lio_listio64() functions let the calling process or thread initiate a list of I/O requests within a single function call. The lio_listio64() function is a large-file support version of lio_listio().

Note: In QNX Neutrino 6.6 or later, the large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. For more information, see Classification in What's in a Function Description?

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 the signal to be generated when all 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_filedes.

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_filedes. (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, 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().

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().
EINVAL
The mode argument is invalid.
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_filedes.
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_filedes.

Classification:

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

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