LISTIO(2-SVR3) RISC/os Reference Manual LISTIO(2-SVR3)
NAME
listio - listed directed I/O
SYNOPSIS
#include <sys/aio.h>
int listio(int cmd, struct liocb *list, aiohandlet *han-
dle, int nent, int signo);
DESCRIPTION
listio allows the calling process to initiate a list of I/O
requests with a single system call.
The cmd argument takes one of the values LIO_WAIT,
LIO_NOWAIT, or LIO_ASYNC (defined in <sys/aio.h>) and deter-
mines whether the function returns when the I/O requests
have been completed, or as soon as the operations have been
queued.
If cmd is LIO_WAIT, the function waits until all I/O is com-
pleted; the signo argument is ignored. If cmd is
LIO_NOWAIT, the function returns immediately; the signo
argument is ignored. If cmd is LIO_ASYNC, the function
returns immediately, and the signal signo is delivered when
the I/O is completed.
list is a pointer to an array of pointers to liocb struc-
tures, each of which includes the following members:
struct liocb {
int lio_opcode;
int lio_fides;
struct aiorb lio_aiorb;
}
The lio_opcode element specifies the operation to be per-
formed. The supported operations are LIO_READ, LIO_READV,
LIO_WRITE, LIO_WRITEV, and LIO_NOOP; these symbols are
defined in <sys/aio.h>. The LIO_NOOP operation causes the
list entry to be skipped, and the corresponding lio_aiorb
structure to be ignored.
The lio_fides element specifies the file descriptor on which
the operation is to be performed. The lio_aiorb element
further describes the I/O operation to be performed, in the
same manner that the corresponding aiorb structure is used
by the aread, areadv, awrite, and awritev functions.
The handle argument is a pointer to an array of asynchronous
I/O handles to be returned by the system.
Printed 11/19/92 Page 1
LISTIO(2-SVR3) RISC/os Reference Manual LISTIO(2-SVR3)
The nent argument specifies how many elements are members of
the list, that is, the length of the array.
The signo argument is the signal to be delivered when the
entire list of I/O requests is completed; this is used only
when cmd has the value LIO_ASYNC. If signo is zero, no sig-
nal is delivered.
RETURNS
listio function returns the value 0 to the calling process
if the function is successful; otherwise, the function
returns the value -1, and sets errno to indicate the error.
The return value indicates the success or failure of the
listio call, 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 request. To determine
the outcome of each I/O request, the application needs to
get the completion block from the handle returned and exam-
ine the aio_errno in the completion block. The error codes
returned in aio_errno are identical to those returned as the
result of an aread, areadv, awrite, or awritev function.
ERRORS
If any of the following conditions occur, listio returns -1
and sets errno to the corresponding value:
[EAGAIN]
The resources necessary to queue all I/O requests were
not available. The application may call await to check
for individual request(s) that failed.
[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 impossible to receive this error
when the cmd argument to the listio request was
LIO_NOWAIT or LIO_ASYNC.
[EINVAL]
The cmd argument is not a proper value. The number of
entries indicated by nent is too large.
[EINTR]
A signal was delivered while waiting for all I/O
requests to complete during an LIO_WAIT operation.
Outstanding I/O requests are not canceled, and the
application must examine each list element to determine
whether the request was initiated, interrupted, or com-
pleted.
Page 2 Printed 11/19/92
LISTIO(2-SVR3) RISC/os Reference Manual LISTIO(2-SVR3)
In addition to the errors returned by listio, if listio
succeeds or fails with one of the errors EAGAIN, EINTR, or
EFAIL then each list element can encounter errors specific
to the individual read or write function being performed.
In this event, the aio_errno element of the aiocb completion
block returned by await contains the associated error code.
The error code is the same as that returned by a read(2) or
write(2) system call, with the following additional error
codes possible:
[ECANCEL] The requested I/O was canceled before the I/O
completed by an explicit acancel request.
[EINPROGRESS] The requested I/O is in progress.
SEE ALSO
acancel(2), aread(2), areadv(2), astatus(2), await(2),
awrite(2), awritev(2), aio(5).
Printed 11/19/92 Page 3