LIO_LISTIO(3)LIO_LISTIO(3)NAME
lio_listio, lio_listio64 - linked asynchronous I/O operations
C SYNOPSIS
#include <aio.h>
int lio_listio(int mode, aiocb_t * const list[], int nent, sigevent_t *sig);
int lio_listio64(int mode, aiocb64_t * const list[], int nent, sigevent_t *sig);
DESCRIPTION
The lio_listio function allows the calling process to initiate a list of
I/O requests with a single function call.
The lio_listio64() function is identical to lio_listio() except that it
takes an array of aiocb64_t * (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->aio_sigevent
structures. If sig is not NULL then notification will happen according
to sig->sigev_notify when all items in the list have completed their I/O
operations.
If sigev_notify is SIGEV_NONE, then no notification will be posted to the
calling application.
If sigev_notify is SIGEV_SIGNAL, then the signal specified in sigev_signo
will be sent to the calling process. If SA_SIGINFO 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
sigev_value will be the si_value in the generated signal.
If sigev_notify is SIGEV_CALLBACK then the function sigev_func will be
called with sigev_value 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 sigev_notify is SIGEV_THREAD then the function sigev_notify_function
will be called by a new thread (see pthreads(5)) with sigev_value as the
argument. This thread is created when the event arrives with the
attributes specified in sigev_notify_attributes except that it is
automatically detached. The calling process should ensure there are
Page 1
LIO_LISTIO(3)LIO_LISTIO(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 O_APPEND in which case the write
operations will happen in the order that they appear in the list.
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 that list entry to be ignored. If
the aio_lio_opcode element is equal to LIO_READ, then an I/O operation is
submitted as if by a call to aio_read() with the aiocbp equal to the
address of the aiocb structure. If the aio_lio_opcode element is equal to
LIO_WRITE, then an I/O operation is submitted as if by a call to
aio_write() with the aiocbp equal to the address of the aiocb structure.
SEE ALSOaio_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 lio_listio() 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 LIO_WAIT, the lio_listio()function
returns the value 0 to the calling process when all the indicated I/O has
completed successfully. Otherwise, lio_listio() 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 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 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 aio_read(3) or
aio_write(3) function.
If any of the following conditions occur, the lio_listio() 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
LIO_LISTIO(3)LIO_LISTIO(3)
[EAGAIN] The number of entries indicated by nent would cause the
system wide limit _AIO_MAX to be exceeded.
[EINVAL] The mode argument is not a proper value. The value of nent
was greater than _AIO_LISTIO_MAX.
[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 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 lio_listio() request was
LIO_NOWAIT.
In addition to the errors returned by the lio_listio() function, if the
lio_listio() 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 aio_cancel(3) request.
[EINPROGRESS] The requested I/O is in progress.
Page 3
