lio_listio(2)

DESCRIPTION

The lio_listio() function allows the calling process to request a list of asynchronous I/O operations with a single function call. The function call returns when all operation requests have been enqueued for processing. At this point, processing of the operations may proceed concurrently with execution of the calling process or thread.

The list argument is an array of nent pointers to aiocb structures. Each aiocb in list is treated as if it were being handled in a separate call to aio_read() or aio_write() depending on the value of its aio_lio_opcode. When aio_lio_opcode is LIO_READ, the aiocb is treated as though it had been referenced in a call to aio_read(), and the aio_fildes, aio_buf, and aio_nbytes fields are interpreted accordingly. When aio_lio_opcode is LIO_WRITE, the aiocb is treated as though it had been referenced in a call to aio_write(), and the aio_fildes, aio_buf, and aio_nbytes fields are interpreted accordingly. If aio_lio_opcode is LIO_NOP, nothing is enqueued.

If an error condition is detected that prevents the list from being processed, lio_listio() returns -1 and sets errno to indicate the cause of the failure. If any requests are enqueued by the call to lio_listio(), and mode is LIO_WAIT, then the function returns only after all enqueued operation requests have completed. The sig argument of the call is ignored. If mode is LIO_NOWAIT, the function returns as soon as all requests are enqueued. The sigevent action specified by sig is performed after all enqueued requests have completed.

Once the requested operations have been successfully enqueued, an aio_error() and aio_return() function referencing the corresponding aiocb from list must be used to determine their status and any error conditions, including those normally reported by read() or write(), as appropriate. Requests remain enqueued and consume process and system resources until aio_return() is called for each one.

Re-using or deallocating memory referred to by the list or any aiocb referenced in the list while an asynchronous I/O operation is outstanding (i.e. before aio_return() has been called) may produce unpredictable results.

To use this function, link in the realtime library by specifying -lrt on the compiler or linker command line.

RETURN VALUE

When LIO_NOWAIT is set, lio_listio() returns the following values:

When LIO_WAIT is set, lio_listio() returns the following values:

The three errno values EAGAIN, EINTR, and EIO are the only ones associated with partial success. aio_error() and aio_return() must be used to determine the outcomes of individual requests.

ERRORS

If lio_listio() detects one of the following error conditions, errno is set to the indicated value:

Once an operation has been enqueued by lio_listio(), the following errors, in addition to all of the errors normally reported by the appropriate read() or write() function, may be reported asynchronously by a subsequent call to aio_error() or aio_return() referencing its aiocbp.

EXAMPLE

The following code sequence and call to lio_listio() starts two asynchronous write operations and one asynchronous read operation and waits for all operations to complete.

SEE ALSO

aio_cancel(2), aio_error(2), aio_fsync(2), aio_read(2), aio_return(2), aio_suspend(2), aio_write(2), read(2), write(2), aio(5).

STANDARDS CONFORMANCE

lio_listio(): POSIX Realtime Extensions, IEEE Std 1003.1b