Originální popis anglicky:
lio_listio - list directed I/O (
REALTIME)
Návod, kniha: POSIX Programmer's Manual
#include <aio.h>
int lio_listio(int
mode, struct aiocb *restrict
const list[restrict],
int
nent, struct sigevent *restrict
sig );
The
lio_listio() function shall initiate a list of I/O requests with a
single function call.
The
mode argument takes one of the values LIO_WAIT or LIO_NOWAIT declared
in
<aio.h> 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 shall wait until
all I/O is complete and the
sig argument shall be ignored.
If the
mode argument is LIO_NOWAIT, the function shall return
immediately, and asynchronous notification shall occur, according to the
sig argument, when all the I/O operations complete. If
sig is
NULL, then no asynchronous notification shall occur. If
sig is not
NULL, asynchronous notification occurs as specified in
Signal Generation
and Delivery when all the requests in
list have completed.
The I/O requests enumerated by
list are submitted in an unspecified
order.
The
list argument is an array of pointers to
aiocb structures. The
array contains
nent elements. The array may contain NULL elements,
which shall be ignored.
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; these symbols are defined in
<aio.h>. The LIO_NOP
operation causes the 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.
The
aio_fildes member specifies the file descriptor on which the
operation is to be performed.
The
aio_buf member specifies the address of the buffer to or from which
the data is transferred.
The
aio_nbytes 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
aio_read() and
aio_write() 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 synchronized I/O is enabled on the file associated with
aio_fildes.
For regular files, no data transfer shall occur past the offset maximum
established in the open file description associated with
aiocbp->
aio_fildes.
If the
mode argument has the value LIO_NOWAIT, the
lio_listio()
function shall return the value zero 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 shall return the value zero when all the indicated I/O has completed
successfully. Otherwise,
lio_listio() shall return a value of -1 and
set
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 so returned are identical to those returned
as the result of an
aio_read() or
aio_write() function.
The
lio_listio() function shall fail if:
- 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.
- EINVAL
- The mode argument is not a proper value, or 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 an 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.
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 [EIO], then some of the I/O specified by the list may have been
initiated. If the
lio_listio() function fails with an error code other
than [EAGAIN], [EINTR], or [EIO], no operations from the list shall 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() or
write() 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 aio_cancel() request.
- EFBIG
- The aiocbp->aio_lio_opcode is LIO_WRITE,
the file is a regular file, aiocbp->aio_nbytes is greater
than 0, and the aiocbp->aio_offset is greater than or
equal to the offset maximum in the open file description associated with
aiocbp->aio_fildes.
- EINPROGRESS
- The requested I/O is in progress.
- EOVERFLOW
- The aiocbp->aio_lio_opcode is LIO_READ,
the file is a regular file, aiocbp->aio_nbytes is greater
than 0, and the aiocbp->aio_offset is before the
end-of-file and is greater than or equal to the offset maximum in the open
file description associated with aiocbp->aio_fildes.
The following sections are informative.
None.
None.
Although it may appear that there are inconsistencies in the specified
circumstances for error codes, the [EIO] error condition applies when any
circumstance relating to an individual operation makes that operation fail.
This might be due to a badly formulated request (for example, the
aio_lio_opcode field is invalid, and
aio_error() returns
[EINVAL]) or might arise from application behavior (for example, the file
descriptor is closed before the operation is initiated, and
aio_error()
returns [EBADF]).
The limitation on the set of error codes returned when operations from the list
shall have been initiated enables applications to know when operations have
been started and whether
aio_error() is valid for a specific operation.
None.
aio_read() ,
aio_write() ,
aio_error() ,
aio_return() ,
aio_cancel() ,
close() ,
exec() ,
exit() ,
fork() ,
lseek() ,
read() , the Base
Definitions volume of IEEE Std 1003.1-2001,
<aio.h>
Portions of this text are reprinted and reproduced in electronic form from IEEE
Std 1003.1, 2003 Edition, Standard for Information Technology -- Portable
Operating System Interface (POSIX), The Open Group Base Specifications Issue
6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics
Engineers, Inc and The Open Group. In the event of any discrepancy between
this version and the original IEEE and The Open Group Standard, the original
IEEE and The Open Group Standard is the referee document. The original
Standard can be obtained online at http://www.opengroup.org/unix/online.html
.
