NAME

lio_listio − list directed I/O

SYNOPSIS

#include <aio.h>

int lio_listio(mode, aiocbp, count, signal)

int mode;

struct aiocb ∗∗aiocbp;

int count;

struct sigevent ∗signal;

DESCRIPTION

The lio_listio function allows the calling process to initiate a list of I/O requests with a single function call. 

The mode argument must be specified as either LIO_WAIT or LIO_NOWAIT.  If the mode argument is LIO_WAIT, the function waits until all I/O is complete and the signal argument is ignored.  If the mode argument is LIO_NOWAIT, the function returns as soon as the I/O operations are queued, and the signal specified by signal is delivered to the process when the entire list of I/O operations is complete.  If signal is NULL or signal->sigev_signo is zero, then no signal is delivered. 

The aiocbp argument is a pointer to an array of pointers to aiocb structures, which describe the I/O operations which are to be performed. The array contains count elements. 

The aio_lio_opcode field of each aiocb structure specifies the operation to be performed. The supported operations are LIO_READ, LIO_WRITE, and LIO_NOP.  If the aio_lio_opcode element is equal to LIO_READ, then an I/O operation is submitted as if by a call to aio_read(3P4) with the given aiocb structure.  If the aio_lio_opcode element is equal to LIO_WRITE, then an I/O operation is submitted as if by a call to aio_write(3P4) with the given aiocb structure.  If the aio_lio_opcode element is equal to LIO_NOP, the aiocb is ignored. 

RETURN VALUE

If the mode argument has the value LIO_NOWAIT, the lio_listio function returns the value 0 to the calling process if the I/O operations are successfully queued; otherwise, the function returns the value -1 and sets errno to indicate the error. 

If the mode argument has the value LIO_WAIT, the lio_listio function returns the value 0 to the calling process when all the indicated I/O has completed successfully.  Otherwise, lio_listio returns a -1 to the calling process, and sets errno to indicate the error. 

In either case, the return value only indicates 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 does not prevent completion of any other individual request. To determine the outcome of each I/O request, the application can examine the error status associated with each aiocb control block. The error status, which is returned by aio_error(3P4), is identical to that returned by aio_read(3P4) or aio_write(3P4). 

If any of the following conditions occur, the lio_listio function returns -1 and sets errno to the corresponding value:

[EAGAIN] The resources necessary to queue all the I/O requests were not available. The application may check the error status for each aiocb to determine the individual requests that failed. 

[EAGAIN] The number of entries indicated by count would cause the system-wide limit {AIO_MAX} to be exceeded. 

[EINVAL] The mode argument is not a proper value. 

[EINVAL] count is greater than AIO_LISTIO_MAX.

[EINTR] A signal was delivered while waiting for all I/O requests to complete during an LIO_WAIT operation.  Outstanding I/O requests are not canceled. The application may examine each list element to determine whether the request was initiated, canceled, or completed. 

[EIO] One or more of the individual I/O operations failed.  The application may check the error status for each aiocb structure to determine the individual requests that failed.  It is possible to receive this error return only when the mode argument to the lio_listio request is LIO_WAIT. 

[EFAIL] One or more of the individual I/O operations failed.  The application may check the error status for each aiocb structure to determine the individual requests that failed.  It is possible to receive this error return only when the mode argument to the lio_listio request is LIO_NOWAIT. 

[EFAULT] The system is unable to access the aiocb structure that the aiocbp argument points to. 

FILES

/usr/lib/libposix4.a

SEE ALSO

aio_read(3P4), aio_write(3P4), aio_fsync(3P4), aio_error(3P4), aio_return(3P4), aio_cancel(3P4), aio_suspend(3P4), lio_listio(3P4), "CX/UX Programmer’s Guide"

WARNING

The interface to lio_listio is based on IEEE Draft Standard P1003.4/D12.  This is an unapproved draft, subject to change. Use of information contained in this unapproved draft is at your own risk.  This interface will change to reflect any changes made by future drafts of POSIX 1003.4. 

CX/UX Programmer’s Reference Manual