LIOLISTIO(3) LIOLISTIO(3)
NAME
lio_listio, lio_listio64 - linked asynchronous I/O operations
C SYNOPSIS
#include <aio.h>
int liolistio(int mode, aiocbt * const list[], int nent, sigeventt *sig);
int liolistio64(int mode, aiocb64t * const list[], int nent, sigeventt *sig);
DESCRIPTION
The liolistio function allows the calling process to initiate a list of
I/O requests with a single function call.
The liolistio64() function is identical to liolistio() except that it
takes an array of aiocb64t * (see <aio.h>). This structure allows for
the specification of a file offset greater than 2 Gigabytes.
The mode argument takes a value of either 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.
If the mode argument is LIO_NOWAIT, the function returns immediately, and
signal delivery shall occur, according to the sig argument, when all the
I/O operations complete. If sig is NULL, then no signal delivery occurs
at the completion of all the items in the list, however notifications for
each item in the list will happen according to their aiocb->aiosigevent
structures. If sig is not NULL then notification will happen according
to sig->sigevnotify when all items in the list have completed their I/O
operations.
If sigevnotify is SIGEVNONE, then no notification will be posted to the
calling application.
If sigevnotify is SIGEVSIGNAL, then the signal specified in sigevsigno
will be sent to the calling process. If SASIGINFO is set for the signal
(see sigaction(2)) and the signal is in the range of SIGRTMIN and
SIGRTMAX then the signal will be queued to the process and the value in
sigevvalue will be the sivalue in the generated signal.
If sigevnotify is SIGEVCALLBACK then the function sigevfunc will be
called with sigevvalue as the argument. Only one callback will be called
at a time, however programs should be careful to note that a callback may
be run in parallel with the calling process.
If sigevnotify is SIGEVTHREAD then the function sigevnotifyfunction
will be called by a new thread (see pthreads(5)) with sigevvalue as the
argument. This thread is created when the event arrives with the
attributes specified in sigevnotifyattributes except that it is
automatically detached. The calling process should ensure there are
Page 1
LIOLISTIO(3) LIOLISTIO(3)
sufficient resources to create the thread.
The list argument is a pointer to an array of pointers to aiocb
structures. The array contains nent elements.
The I/O requests enumerated by list are submitted in an unspecified order
unless the file was opened with the OAPPEND in which case the write
operations will happen in the order that they appear in the list.
The aiolioopcode field of each aiocb structure specifies the operation
to be performed. The supported operations are LIOREAD, LIOWRITE, and
LIONOP. The LIONOP operation causes that list entry to be ignored. If
the aiolioopcode element is equal to LIOREAD, then an I/O operation is
submitted as if by a call to aioread() with the aiocbp equal to the
address of the aiocb structure. If the aiolioopcode element is equal to
LIOWRITE, then an I/O operation is submitted as if by a call to
aiowrite() with the aiocbp equal to the address of the aiocb structure.
SEE ALSO
aio_read(3), aio_write(3), aio_error(3), aio_return(3), aio_cancel(3),
aio_sgi_init(3), aio_hold(3), aio_fsync(3), read(2), lseek(2), close(2),
_exit(2), exec(2), fork(2), pthreads(5).
DIAGNOSTICS
If the mode argument has the value LIO_NOWAIT, the liolistio() function
returns the value 0 to the calling process if the I/O operations are
successfully queued; otherwise, the function shall return the value -1
and set errno to indicate the error.
If the mode argument has the value LIOWAIT, the liolistio()function
returns the value 0 to the calling process when all the indicated I/O has
completed successfully. Otherwise, liolistio() returns -1 to the calling
process, and sets errno to indicate the error.
In either case, the return value only indicates the success or failure of
the liolistio() 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 shall examine the error status
associated with each aiocb control block. The error statuses returned
are identical to those returned as the result of an aioread(3) or
aiowrite(3) function.
If any of the following conditions occur, the liolistio() function shall
return -1 and set errno to the corresponding value:
[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.
Page 2
LIOLISTIO(3) LIOLISTIO(3)
[EAGAIN] The number of entries indicated by nent would cause the
system wide limit AIOMAX to be exceeded.
[EINVAL] The mode argument is not a proper value. The value of nent
was greater than AIOLISTIOMAX.
[EINTR] A signal was delivered while waiting for all I/O requests
to complete during a LIOWAIT operation. Note that, since
each I/O operation invoked by liolistio() 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 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. It is not possible to receive this error return
when the mode argument to the liolistio() request was
LIONOWAIT.
In addition to the errors returned by the liolistio() function, if the
liolistio() function succeeds or fails with errors of EAGAIN, EINTR or
ERIO, then some of the I/O operations specified by the list may have been
initiated. The I/O operation indicated by each list element can encounter
errors specific to the individual read or write function being performed.
In this event, the error status for each aiocb control block contains the
associated error code. The error codes which can be set are the same as
would be set by a read(2) or write(2) function, with the following error
codes possible:
[EAGAIN] The requested asynchronous I/O operation was not queued
due to system resource limitations.
[ECANCELED] The requested I/O was canceled before the I/O completed
due to an explicit aiocancel(3) request.
[EINPROGRESS] The requested I/O is in progress.
Page 3