lio_listio.2 (2010 09)

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
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:
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
completed.
-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
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1