mirror of https://github.com/mkerrisk/man-pages
226 lines
9.1 KiB
Plaintext
226 lines
9.1 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "LIO_LISTIO" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" lio_listio
|
|
.SH NAME
|
|
lio_listio \- list directed I/O (\fBREALTIME\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <aio.h>
|
|
.br
|
|
.sp
|
|
int lio_listio(int\fP \fImode\fP\fB, struct aiocb *restrict const\fP
|
|
\fIlist\fP\fB[restrict],
|
|
.br
|
|
\ \ \ \ \ \ int\fP \fInent\fP\fB, struct sigevent *restrict\fP \fIsig\fP\fB);
|
|
\fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIlio_listio\fP() function shall initiate a list of I/O requests
|
|
with a single function call.
|
|
.LP
|
|
The \fImode\fP argument takes one of the values LIO_WAIT or LIO_NOWAIT
|
|
declared in \fI<aio.h>\fP 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 \fImode\fP
|
|
argument is LIO_WAIT, the function shall wait until
|
|
all I/O is complete and the \fIsig\fP argument shall be ignored.
|
|
.LP
|
|
If the \fImode\fP argument is LIO_NOWAIT, the function shall return
|
|
immediately, and asynchronous notification shall occur,
|
|
according to the \fIsig\fP argument, when all the I/O operations complete.
|
|
If \fIsig\fP is NULL, then no asynchronous
|
|
notification shall occur. If \fIsig\fP is not NULL, asynchronous notification
|
|
occurs as specified in \fISignal Generation and Delivery\fP when all
|
|
the requests in \fIlist\fP have
|
|
completed.
|
|
.LP
|
|
The I/O requests enumerated by \fIlist\fP are submitted in an unspecified
|
|
order.
|
|
.LP
|
|
The \fIlist\fP argument is an array of pointers to \fBaiocb\fP structures.
|
|
The array contains \fInent\fP elements. The array
|
|
may contain NULL elements, which shall be ignored.
|
|
.LP
|
|
The \fIaio_lio_opcode\fP field of each \fBaiocb\fP structure specifies
|
|
the operation to be performed. The supported operations
|
|
are LIO_READ, LIO_WRITE, and LIO_NOP; these symbols are defined in
|
|
\fI<aio.h>\fP. The
|
|
LIO_NOP operation causes the list entry to be ignored. If the \fIaio_lio_opcode\fP
|
|
element is equal to LIO_READ, then an I/O
|
|
operation is submitted as if by a call to \fIaio_read\fP() with the
|
|
\fIaiocbp\fP equal
|
|
to the address of the \fBaiocb\fP structure. If the \fIaio_lio_opcode\fP
|
|
element is equal to LIO_WRITE, then an I/O operation is
|
|
submitted as if by a call to \fIaio_write\fP() with the \fIaiocbp\fP
|
|
equal to the
|
|
address of the \fBaiocb\fP structure.
|
|
.LP
|
|
The \fIaio_fildes\fP member specifies the file descriptor on which
|
|
the operation is to be performed.
|
|
.LP
|
|
The \fIaio_buf\fP member specifies the address of the buffer to or
|
|
from which the data is transferred.
|
|
.LP
|
|
The \fIaio_nbytes\fP member specifies the number of bytes of data
|
|
to be transferred.
|
|
.LP
|
|
The members of the \fBaiocb\fP structure further describe the I/O
|
|
operation to be performed, in a manner identical to that of
|
|
the corresponding \fBaiocb\fP structure when used by the \fIaio_read\fP()
|
|
and \fIaio_write\fP() functions.
|
|
.LP
|
|
The \fInent\fP argument specifies how many elements are members of
|
|
the list; that is, the length of the array.
|
|
.LP
|
|
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 \fIaio_fildes\fP.
|
|
.LP
|
|
For regular files, no data transfer shall occur past the offset maximum
|
|
established in the open file description associated with
|
|
\fIaiocbp\fP->\fIaio_fildes\fP.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
If the \fImode\fP argument has the value LIO_NOWAIT, the \fIlio_listio\fP()
|
|
function shall return the value zero if the I/O
|
|
operations are successfully queued; otherwise, the function shall
|
|
return the value -1 and set \fIerrno\fP to indicate the
|
|
error.
|
|
.LP
|
|
If the \fImode\fP argument has the value LIO_WAIT, the \fIlio_listio\fP()
|
|
function shall return the value zero when all the
|
|
indicated I/O has completed successfully. Otherwise, \fIlio_listio\fP()
|
|
shall return a value of -1 and set \fIerrno\fP to
|
|
indicate the error.
|
|
.LP
|
|
In either case, the return value only indicates the success or failure
|
|
of the \fIlio_listio\fP() 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 \fBaiocb\fP control
|
|
block. The error statuses so returned are identical to
|
|
those returned as the result of an \fIaio_read\fP() or \fIaio_write\fP()
|
|
function.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIlio_listio\fP() function shall fail if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
The resources necessary to queue all the I/O requests were not available.
|
|
The application may check the error status for each
|
|
\fBaiocb\fP to determine the individual request(s) that failed.
|
|
.TP 7
|
|
.B EAGAIN
|
|
The number of entries indicated by \fInent\fP would cause the system-wide
|
|
limit {AIO_MAX} to be exceeded.
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fImode\fP argument is not a proper value, or the value of \fInent\fP
|
|
was greater than {AIO_LISTIO_MAX}.
|
|
.TP 7
|
|
.B 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 \fIlio_listio\fP() 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.
|
|
.TP 7
|
|
.B EIO
|
|
One or more of the individual I/O operations failed. The application
|
|
may check the error status for each \fBaiocb\fP structure
|
|
to determine the individual request(s) that failed.
|
|
.sp
|
|
.LP
|
|
In addition to the errors returned by the \fIlio_listio\fP() function,
|
|
if the \fIlio_listio\fP() 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
|
|
\fIlio_listio\fP() 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
|
|
\fBaiocb\fP control block contains the associated error code.
|
|
The error codes that can be set are the same as would be set by a
|
|
\fIread\fP() or \fIwrite\fP() function, with the following additional
|
|
error codes possible:
|
|
.TP 7
|
|
.B EAGAIN
|
|
The requested I/O operation was not queued due to resource limitations.
|
|
.TP 7
|
|
.B ECANCELED
|
|
The requested I/O was canceled before the I/O completed due to an
|
|
explicit \fIaio_cancel\fP() request.
|
|
.TP 7
|
|
.B EFBIG
|
|
The \fIaiocbp\fP->\fIaio_lio_opcode\fP is LIO_WRITE, the file is a
|
|
regular file, \fIaiocbp\fP->\fIaio_nbytes\fP is
|
|
greater than 0, and the \fIaiocbp\fP->\fIaio_offset\fP is greater
|
|
than or equal to the offset maximum in the open file
|
|
description associated with \fIaiocbp\fP->\fIaio_fildes\fP.
|
|
.TP 7
|
|
.B EINPROGRESS
|
|
The requested I/O is in progress.
|
|
.TP 7
|
|
.B EOVERFLOW
|
|
The \fIaiocbp\fP->\fIaio_lio_opcode\fP is LIO_READ, the file is a
|
|
regular file, \fIaiocbp\fP->\fIaio_nbytes\fP is
|
|
greater than 0, and the \fIaiocbp\fP->\fIaio_offset\fP is before the
|
|
end-of-file and is greater than or equal to the offset
|
|
maximum in the open file description associated with \fIaiocbp\fP->\fIaio_fildes\fP.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
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 \fIaio_lio_opcode\fP field is
|
|
invalid, and \fIaio_error\fP() returns [EINVAL]) or might arise from
|
|
application behavior (for example, the
|
|
file descriptor is closed before the operation is initiated, and \fIaio_error\fP()
|
|
returns [EBADF]).
|
|
.LP
|
|
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 \fIaio_error\fP()
|
|
is valid for a
|
|
specific operation.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIaio_read\fP() , \fIaio_write\fP() , \fIaio_error\fP() , \fIaio_return\fP()
|
|
, \fIaio_cancel\fP() , \fIclose\fP() , \fIexec\fP() , \fIexit\fP()
|
|
, \fIfork\fP() , \fIlseek\fP() , \fIread\fP() , the Base Definitions
|
|
volume of
|
|
IEEE\ Std\ 1003.1-2001, \fI<aio.h>\fP
|
|
.SH COPYRIGHT
|
|
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 .
|