|This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.|
Initiate a list of I/O requests
#include <aio.h> int lio_listio( int mode, struct aiocb* const list, int nent, struct sigevent* sig );
- The mode of operation; one of:
- LIO_WAIT — lio_listio() behaves synchronously, waiting until all I/O is completed, and ignores the sig argument.
- LIO_NOWAIT — lio_listio() behaves asynchronously, returning immediately, and 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 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 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() 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:
- 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, 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().
- 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
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.
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()