lio_listio(3aio) lio_listio(3aio)
NAME
lio_listio - issue list of I/O requests
SYNOPSIS
cc [options] -D_REENTRANT file -lthread
#include <aio.h>
int lio_listio(int mode, struct aiocb *list[],
int nent,struct sigevent *sig);
DESCRIPTION
lio_listio supports issuing a list of I/O requests with a
single function call.
The mode argument takes one of the values LIO_WAIT or
LIO_NOWAIT and determines whether the function returns when
the I/O operations have been completed, or as soon as the
operations have been queued. If the mode argument is
LIO_WAIT, the function waits until all I/O is complete and the
sig argument is ignored.
When LIO_WAIT is selected, lio_listio waits for all requests
that were successfully queued to complete before returning.
If no requests were successfully queued, it returns
immediately.
If the mode argument is LIO_NOWAIT, the function returns
immediately, and completion notification occurs according to
the sig argument, when all the I/O operations complete. If
sig is NULL, no notification occurs. If sig is not NULL,
notification occurs according to the same rules as the
aio_sigevent aiocb field.
The list argument is an array of pointers to aiocb structures.
The array contains nent elements. The array may contain NULL
elements which are ignored.
The I/O requests enumerated by list are submitted in an
unspecified order.
The aio_lio_opcode field of each aiocb structure specifies the
operation to be performed. The supported operations are
LIO_READ, LIO_WRITE, and LIO_NOP. The LIO_NOP operation
causes the list entry to be ignored. If the aio_lio_opcode
element is equal to LIO_READ, an I/O operation is submitted as
if by a call to aio_read with the aiocb equal to the address
of the aiocb structure. If the aio_lio_opcode element is
Copyright 1994 Novell, Inc. Page 1
lio_listio(3aio) lio_listio(3aio)
equal to LIO_WRITE, an I/O operation is submitted as if by a
call to aio_write with the aiocb equal to the address of the
aiocb structure.
Other aiocb structure members (i.e. aio_fildes, aio_buf,
aio_nbytes, etc) are set in a manner equivalent to how they
would be set if you use them in a direct call to aio_write or
aio_read.
The nent argument specifies how many elements are members of
the list, or the length of the array.
The sig argument is a pointer to a signal control structure,
used when the mode argument has the value LIO_NOWAIT, which
defines the notification to be issued when the entire list of
I/O requests have been completed.
The behavior of lio_listio is altered according to the
definitions of synchronized I/O data integrity completion and
synchronized I/O file integrity completion if synchronized I/O
is enabled on the file associated with the requests.
Mixing of requests with and without the AIO_RAW flag set in
aio_flags is supported. The implementation should, but is not
required to, return an error if this is attempted. The
setting of the AIO_RAW flag can be determined by examing the
first request in list.
Return Values
If the mode argument has the value LIO_NOWAIT, the lio_listio
function returns the value zero if the I/O operations are
successfully queued; otherwise, the function returns the value
-1 and sets errno to indicate the error.
If the mode argument has the value LIO_WAIT, the lio_listio
function returns zero when all the indicated I/O has completed
successfully. Otherwise, lio_listio returns a value of -1 and
sets errno to indicate the error.
Both of these return values only indicate the success or
failure of the lio_listio call itself, not the status of the
individual I/O requests. In some cases one or more of the I/O
requests contained in the list may fail. Failure of an
individual request does not prevent completion of any other
individual request. To determine the outcome of each I/O
request, the application examines the error status associated
Copyright 1994 Novell, Inc. Page 2
lio_listio(3aio) lio_listio(3aio)
with each lio_aiocb control block. The error statuses
returned are identical to those returned as the result of an
aio_read or aio_write function.
Errors
If any of the following conditions occur, the lio_listio
function returns -1 and sets errno to:
EAGAIN
The resources necessary to queue all the I/O requests
were not available. The application may check the error
status for each aiocb to determine the individual
request(s) that failed.
EAGAIN
The number of entries indicated by nent would cause the
system-wide limit {AIO_MAX} to be exceeded. All entries
return EAGAIN when queried with aio_error.
EINVAL
The mode argument is not a proper value.
EINVAL
the value of nent was greater than {AIO_LISTIO_MAX}, or
nent is zero.
EINVAL
All requests are NULL or have their lio_listio set to
LIO_NOP.
EFAULT
A memory fault occurred while accessing a lio_listio
request. In this cause, lio_listio returns immediately
without processing subsequent requests in the list. On
some implementations, memory faults might result in a
SIGSEGV signal being delivered to the processes instead
of returning the error code.
EINTR A signal was delivered while waiting for all I/O
requests to complete during a LIO_WAIT operation. Note
that, since each I/O operation invoked by lio_listio may
possibly provoke a signal when it completes, this error
return may be caused by the completion of one (or more)
of the very I/O operations being awaited. Outstanding
I/O requests are not canceled, and the application shall
examine each list element to determine whether the
Copyright 1994 Novell, Inc. Page 3
lio_listio(3aio) lio_listio(3aio)
request was initiated, canceled or completed.
EIO One or more of the individual I/O operations failed.
The application may check the error status for each
aiocb structure to determine the individual request(s)
that failed.
REFERENCES
aiocb(5), aio_read(3aio), aio_suspend(3aio), aio_write(3aio)
Copyright 1994 Novell, Inc. Page 4