Standard C Library Functions liolistio(3C)
NAME
liolistio - list directed I/O
SYNOPSIS
#include
int liolistio(int mode, struct aiocb *restrict const list[],
int nent, struct sigevent *restrict sig);
DESCRIPTION
The liolistio() function allows the calling process, LWP,
or thread, to initiate a list of I/O requests within a sin-
gle function call.
The mode argument takes one of the values LIOWAIT or
LIONOWAIT declared in and determines whether the
function returns when the I/O operations have been com-
pleted, or as soon as the operations have been queued. If
the mode argument is LIOWAIT, the function waits until all
I/O is complete and the sig argument is ignored.
If the mode argument is LIONOWAIT, the function returns
immediately, and asynchronous notification occurs, according
to the sig argument, when all the I/O operations complete.
If sig is NUL, no asynchronous notification occurs. If sig
is not NUL, asynchronous notification occurs as specified
in signal.h(3HEAD) when all the requests in list have com-
pleted.
The I/O requests enumerated by list are submitted in an
unspecified order.
The list argument is an array of pointers to aiocb struc-
tures. The array contains nent elements. The array may con-
tain null elements, which are ignored.
The aiolioopcode field of each aiocb structure specifies
the operation to be performed. The supported operations are
LIOREAD, LIOWRITE, and LIONOP; these symbols are defined
in . The LIONOP operation causes the 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(3C) 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(3C) with the aiocbp equal to the address
SunOS 5.11 Last change: 5 Feb 2008 1
Standard C Library Functions liolistio(3C)
of the aiocb structure.
The aiofildes member specifies the file descriptor on which
the operation is to be performed.
The aiobuf member specifies the address of the buffer to or
from which the data is to be transferred.
The aionbytes member specifies the number of bytes of data
to be transferred.
The members of the aiocb structure further describe the I/O
operation to be performed, in a manner identical to that of
the corresponding aiocb structure when used by the
aioread(3C) and aiowrite(3C) functions.
The nent argument specifies how many elements are members of
the list, that is, the length of the array.
The behavior of this function is altered according to the
definitions of synchronized I/O data integrity completion
and synchronized I/O file integrity completion if synchron-
ized I/O is enabled on the file associated with aiofildes.
See fcntl.h(3HEAD) definitions of ODSYNC and OSYNC.
For regular files, no data transfer will occur past the
offset maximum established in the open file description
associated with aiocbp->aiofildes.
RETURN VALUES
If the mode argument has the value LIONOWAIT, and the I/O
operations are successfully queued, liolistio() returns 0;
otherwise, it returns -1, and sets errno to indicate the
error.
If the mode argument has the value LIOWAIT, and all the
indicated I/O has completed successfully, liolistio()
returns 0; otherwise, it returns -1, 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
SunOS 5.11 Last change: 5 Feb 2008 2
Standard C Library Functions liolistio(3C)
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 must examine the error status
associated with each aiocb control block. Each error status
so returned is identical to that returned as a result of an
aioread(3C) or aiowrite(3C) function.
ERORS
The liolistio() function will fail if:
EAGAIN The resources necessary to queue all the I/O
requests were not available. The error status for
each request is recorded in the aioerror member
of the corresponding aiocb structure, and can be
retrieved using aioerror(3C).
EAGAIN The number of entries indicated by nent would
cause the system-wide limit AIOMAX to be
exceeded.
EINVAL The mode argument is an improper value, or the
value of nent is greater than AIOLISTIOMAX.
EINTR A signal was delivered while waiting for all I/O
requests to complete during an 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 opera-
tions being awaited. Outstanding I/O requests are
not canceled, and the application can use
aiofsync(3C) to determine if any request was ini-
tiated; aioreturn(3C) to determine if any request
has completed; or aioerror(3C) to determine if
any request was canceled.
EIO One or more of the individual I/O operations
failed. The application can use aioerror(3C) to
check the error status for each aiocb structure to
determine the individual request(s) that failed.
In addition to the errors returned by the liolistio() func-
tion, if the liolistio() function succeeds or fails with
errors of EAGAIN, EINTR, or EIO, then some of the I/O speci-
fied by the list may have been initiated. If the
SunOS 5.11 Last change: 5 Feb 2008 3
Standard C Library Functions liolistio(3C)
liolistio() function fails with an error code other than
EAGAIN, EINTR, or EIO, no operations from the list 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 that can be set are the same as
would be set by a read(2) or write(2) function, with the
following additional error codes possible:
EAGAIN The requested I/O operation was not queued
due to resource limitations.
ECANCELED The requested I/O was canceled before the I/O
completed due to an explicit aiocancel(3C)
request.
EFBIG The aiocbp->aiolioopcode is LIOWRITE, the
file is a regular file, aiocbp->aionbytes is
greater than 0, and the aiocbp->aiooffset is
greater than or equal to the offset maximum
in the open file description associated with
aiocbp->aiofildes.
EINPROGRES The requested I/O is in progress.
EOVERFLOW The aiocbp->aiolioopcode is LIOREAD, the
file is a regular file, aiocbp->aionbytes is
greater than 0, and the aiocbp->aiooffset is
before the end-of-file and is greater than or
equal to the offset maximum in the open file
description associated with
aiocbp->aiofildes.
USAGE
The liolistio() function has a transitional interface for
64-bit file offsets. See lf64(5).
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 5 Feb 2008 4
Standard C Library Functions liolistio(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Committed
MT-Level MT-Safe
Standard See standards(5).
SEE ALSO
close(2), exec(2), exit(2), fork(2), lseek(2), read(2),
write(2), aiocancel(3C), aioerror(3C), aiofsync(3C),
aioread(3C), aioreturn(3C), aiowrite(3C), aio.h(3HEAD),
fcntl.h(3HEAD), siginfo.h(3HEAD), signal.h(3HEAD), attri-
butes(5), lf64(5), standards(5)
SunOS 5.11 Last change: 5 Feb 2008 5
|
