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

Library:

libc

Description:

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

If mode is set to LIO_WAIT, lio_listio() behaves synchronously, waiting until all I/O is completed, and the sig argument is ignored.

If mode is set to LIO_NOWAIT, lio_listio() behaves asynchronously, returning immediately, and signal delivery occurs, according to the sig argument, when all the I/O operations from this function complete. If sig is NULL, or the sigev_signo member of the sigevent structure pointed to by sig is zero, then no signal delivery occurs. Otherwise, the signal number indicated by sigev_signo is delivered when all the requests in list have completed.

The list argument is an array of pointers to aiocb structures. This array consists of nent elements. The array may contain NULL pointers, which are ignored.

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.

The nent argument specifies the length of the array (i.e. the number of members in the list).

When mode has the value LIO_NOWAIT, a pointer to a signal control structure, sig, is used to define both the signal to be generated and how the calling process is notified upon I/O completion:

• 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 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, the application must 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 an improper value.

The value of nent is greater than _POSIX_AIO_LISTIO_MAX.

EINTR

A signal was delivered while waiting for all I/O requests to complete 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 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 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 (Realtime Extensions)

See also:

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