HP-UX Reference (11i v3 07/02) - 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
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:
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 completed with an error before the lio_listio() function call returned.
errno is set to indicate 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 com-
pleted.
-1 Failure or partial success. At least one requested operation was either not enqueued
or completed 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:
[EAGAIN] At least one request could not be queued either because of a resource shortage or
because the per-process or system-wide limit on asynchronous I/O operations or asyn-
chronous threads would have been exceeded.
174 Hewlett-Packard Company − 1 − HP-UX 11i Version 3: February 2007