lio_listio(), lio

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 event doesn't need to be registered. 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>):

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

If sig is NULL or sig->sigev_notify is SIGEV_NONE, then no signal delivery occurs.
If sig->sigev_notify is SIGEV_SIGNAL:
- If nonzero, the signal specified in sig->sigev_signo is delivered to the process when all the requests in the list have been completed. 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; see siginfo_t.
- If sigev_signo is zero, then no signal delivery occurs.
You can use other SIGEV_* types, including those that are QNX Neutrino extensions.

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

lio_listio(), lio_listio64()