HP-UX Reference (11i v2 07/12) - 2 System Calls (vol 5)

l
lio_listio(2) lio_listio(2)
NAME
lio_listio() - start a list of asynchronous I/O operations
SYNOPSIS
#include <aio.h>
int lio_listio(
int
mode,
struct aiocb *const
list[],
int
nent,
struct sigevent *
sig
);
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 cal-
ling 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 asyn-
chronous I/O operation is outstanding (that is, 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:
0 Success. All of the non-empty operations, if any, were successfully enqueued.
-1 Failure or partial success. At least one requested operation was either not enqueued or com-
pleted with an error before the lio_listio() function call returned. errno is set to indi-
cate the error.
When LIO_WAIT is set, lio_listio() returns the following values:
0 Success. All of the non-empty operations, if any, were successfully enqueued and completed.
-1 Failure or partial success. At least one requested operation was either not enqueued or com-
pleted with an error. errno is set to indicate the error.
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:
HP-UX 11i Version 2: December 2007 Update − 1 − Hewlett-Packard Company 161