lio_listio(2) lio_listio(2)
NAME [Toc] [Back]
lio_listio() - start a list of asynchronous I/O operations
SYNOPSIS [Toc] [Back]
#include <aio.h>
int lio_listio(int mode, struct aiocb * const list[], int nent, struct
sigevent *sig);
DESCRIPTION [Toc] [Back]
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.
Hewlett-Packard Company - 1 - HP-UX 11i Version 2: August 2003
lio_listio(2) lio_listio(2)
RETURN VALUE [Toc] [Back]
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 [Toc] [Back]
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 asynchronous threads would have
been exceeded.
[EINVAL] The sigevent specified by sig is not valid.
[EINVAL] The mode argument is neither LIO_WAIT nor
LIO_NOWAIT.
[EINVAL] The value of the nent argument is negative or
greater than the maximum value allowed. The
maximum value allowed can be obtained using the
sysconf() call with the argument
_SC_AIO_LISTIO_MAX.
[EINTR] The mode argument was LIO_WAIT and a signal was
delivered while waiting for the requested
operations to complete. This signal may result
from completion of one or more of the requested
Hewlett-Packard Company - 2 - HP-UX 11i Version 2: August 2003
lio_listio(2) lio_listio(2)
operations and other requests may still be pending
or completed.
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.
[EBADF] The aiocbp->aio_fildes was not a valid file
descriptor open for reading or writing as
appropriate to the aio_lio_opcode.
[EINVAL] The value of aiocbp->aio_reqprio is not valid, or
the value of aiocbp->aio_nbytes is invalid, or the
file offset implied by aiocbp->aio_offset or
aiocbp->aio_offset+aiocbp->aio_nbytes is not
valid.
[EIO] One or more of the enqueued operations did not
complete successfully.
EXAMPLE [Toc] [Back]
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.
#include <fcntl.h>
#include <errno.h>
#include <aio.h>
char buf1[4096], buf2[4096], buf3[4096];
int nent;
struct aiocb myaiocb1, myaiocb2, myaiocb3;
struct aiocb *list[] = { &myaiocb1, &myaiocb2, &myaiocb3 };
bzero( &myaiocb1, sizeof (struct aiocb));
bzero( &myaiocb2, sizeof (struct aiocb));
bzero( &myaiocb3, sizeof (struct aiocb));
myaiocb1.aio_fildes = open( "/dev/null", O_RDWR);
myaiocb3.aio_fildes = myaiocb2.aio_fildes = myaiocb1.aio_fildes;
myaiocb1.aio_offset = 0;
myaiocb3.aio_offset = myaiocb2.aio_offset = myaiocb1.aio_offset;
myaiocb1.aio_buf = (void *) buf1;
myaiocb2.aio_buf = (void *) buf2;
myaiocb3.aio_buf = (void *) buf3;
myaiocb3.aio_nbytes = sizeof (buf3);
myaiocb2.aio_nbytes = sizeof (buf2);
myaiocb1.aio_nbytes = sizeof (buf1);
myaiocb1.aio_lio_opcode = myaiocb3.aio_lio_opcode = LIO_WRITE;
myaiocb2.aio_lio_opcode = LIO_READ;
myaiocb1.aio_sigevent.sigev_notify = SIGEV_NONE;
myaiocb2.aio_sigevent.sigev_notify = SIGEV_NONE;
Hewlett-Packard Company - 3 - HP-UX 11i Version 2: August 2003
lio_listio(2) lio_listio(2)
myaiocb3.aio_sigevent.sigev_notify = SIGEV_NONE;
retval = lio_listio( LIO_WAIT, list, 3, NULL );
if (retval) perror("lio_listio:");
while ( nent-- ) { (void) aio_return( list[nent] ); }
SEE ALSO [Toc] [Back]
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 [Toc] [Back]
lio_listio(): POSIX Realtime Extensions, IEEE Std 1003.1b
Hewlett-Packard Company - 4 - HP-UX 11i Version 2: August 2003 [ Back ] |
