path: root/man-pages-posix-2017/man3p/lio_listio.3p

'\" et
.TH LIO_LISTIO "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
lio_listio
\(em list directed I/O
.SH SYNOPSIS
.LP
.nf
#include <aio.h>
.P
int lio_listio(int \fImode\fP, struct aiocb *restrict const \fIlist\fP[restrict],
    int \fInent\fP, struct sigevent *restrict \fIsig\fP);
.fi
.SH DESCRIPTION
The
\fIlio_listio\fR()
function shall initiate a list of I/O requests with a single
function call.
.P
The
.IR mode
argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in
.IR <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
.IR mode
argument is LIO_WAIT, the function shall wait until all I/O is
complete and the
.IR sig
argument shall be ignored.
.P
If the
.IR mode
argument is LIO_NOWAIT, the function shall return immediately, and
asynchronous notification shall occur, according to the
.IR sig
argument, when all the I/O operations complete. If
.IR sig
is NULL, then no asynchronous notification shall occur. If
.IR sig
is not NULL, asynchronous notification occurs as specified in
.IR "Section 2.4.1" ", " "Signal Generation and Delivery"
when all the requests in
.IR list
have completed.
.P
The I/O requests enumerated by
.IR list
are submitted in an unspecified order.
.P
The
.IR list
argument is an array of pointers to
.BR aiocb
structures. The array contains
.IR nent
elements. The array may contain NULL elements, which shall be ignored.
.P
If the buffer pointed to by
.IR list
or the
.BR aiocb
structures pointed to by the elements of the array
.IR list
become illegal addresses before all asynchronous I/O completed and, if
necessary, the notification is sent, then the behavior is undefined. If
the buffers pointed to by the
.IR aio_buf
member of the
.BR aiocb
structure pointed to by the elements of the array
.IR list
become illegal addresses prior to the asynchronous I/O associated with
that
.BR aiocb
structure being completed, the behavior is undefined.
.P
The
.IR aio_lio_opcode
field of each
.BR aiocb
structure specifies the operation to be performed. The supported
operations are LIO_READ, LIO_WRITE, and LIO_NOP;
these symbols are defined in
.IR <aio.h> .
The LIO_NOP operation causes the list entry to be ignored. If the
.IR aio_lio_opcode
element is equal to LIO_READ, then an I/O operation is submitted as if
by a call to
\fIaio_read\fR()
with the
.IR aiocbp
equal to the address of the
.BR aiocb
structure. If the
.IR aio_lio_opcode
element is equal to LIO_WRITE, then an I/O operation is submitted as if
by a call to
\fIaio_write\fR()
with the
.IR aiocbp
equal to the address of the
.BR aiocb
structure.
.P
The
.IR aio_fildes
member specifies the file descriptor on which the operation is to be
performed.
.P
The
.IR aio_buf
member specifies the address of the buffer to or from which the data is
transferred.
.P
The
.IR aio_nbytes
member specifies the number of bytes of data to be transferred.
.P
The members of the
.BR aiocb
structure further describe the I/O operation to be performed, in a
manner identical to that of the corresponding
.BR aiocb
structure when used by the
\fIaio_read\fR()
and
\fIaio_write\fR()
functions.
.P
The
.IR nent
argument specifies how many elements are members of the list; that is,
the length of the array.
.P
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
.IR aio_fildes .
.P
For regular files, no data transfer shall occur past the offset maximum
established in the open file description associated with
\fIaiocbp\fR\->\fIaio_fildes\fR.
.P
If \fIsig\fR\->\fIsigev_notify\fR is SIGEV_THREAD and
\fIsig\fR\->\fIsigev_notify_attributes\fR is a non-null pointer and the
block pointed to by this pointer becomes an illegal address prior to
all asynchronous I/O being completed, then the behavior is undefined.
.SH "RETURN VALUE"
If the
.IR mode
argument has the value LIO_NOWAIT, the
\fIlio_listio\fR()
function shall return the value zero if the I/O operations are
successfully queued; otherwise, the function shall return the value
\-1 and set
.IR errno
to indicate the error.
.P
If the
.IR mode
argument has the value LIO_WAIT, the
\fIlio_listio\fR()
function shall return the value zero when all the indicated I/O has
completed successfully. Otherwise,
\fIlio_listio\fR()
shall return a value of \-1 and set
.IR errno
to indicate the error.
.P
In either case, the return value only indicates the success or failure
of the
\fIlio_listio\fR()
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
.BR aiocb
control block. The error statuses so returned are identical to those
returned as the result of an
\fIaio_read\fR()
or
\fIaio_write\fR()
function.
.SH ERRORS
The
\fIlio_listio\fR()
function shall fail if:
.TP
.BR EAGAIN
The resources necessary to queue all the I/O requests were not
available. The application may check the error status for each
.BR aiocb
to determine the individual request(s) that failed.
.TP
.BR EAGAIN
The number of entries indicated by
.IR nent
would cause the system-wide limit
{AIO_MAX}
to be exceeded.
.TP
.BR EINVAL
The
.IR mode
argument is not a proper value, or the value of
.IR nent
was greater than
{AIO_LISTIO_MAX}.
.TP
.BR 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\fR()
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
.BR EIO
One or more of the individual I/O operations failed. The application
may check the error status for each
.BR aiocb
structure to determine the individual request(s) that failed.
.P
In addition to the errors returned by the
\fIlio_listio\fR()
function, if the
\fIlio_listio\fR()
function succeeds or fails with errors of
.BR [EAGAIN] ,
.BR [EINTR] ,
or
.BR [EIO] ,
then some of the I/O specified by the list may have been initiated. If
the
\fIlio_listio\fR()
function fails with an error code other than
.BR [EAGAIN] ,
.BR [EINTR] ,
or
.BR [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
.BR aiocb
control block contains the associated error code. The error codes that
can be set are the same as would be set by a
\fIread\fR()
or
\fIwrite\fR()
function, with the following additional error codes possible:
.TP
.BR EAGAIN
The requested I/O operation was not queued due to resource limitations.
.TP
.BR ECANCELED
The requested I/O was canceled before the I/O completed due to an
explicit
\fIaio_cancel\fR()
request.
.TP
.BR 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
.BR EINPROGRESS
The requested I/O is in progress.
.TP
.BR 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.
.LP
.IR "The following sections are informative."
.SH EXAMPLES
None.
.SH "APPLICATION USAGE"
None.
.SH RATIONALE
Although it may appear that there are inconsistencies in the specified
circumstances for error codes, the
.BR [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
.IR aio_lio_opcode
field is invalid, and
\fIaio_error\fR()
returns
.BR [EINVAL] )
or might arise from application behavior (for example, the file
descriptor is closed before the operation is initiated, and
\fIaio_error\fR()
returns
.BR [EBADF] ).
.P
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\fR()
is valid for a specific operation.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIaio_read\fR\^(\|)",
.IR "\fIaio_write\fR\^(\|)",
.IR "\fIaio_error\fR\^(\|)",
.IR "\fIaio_return\fR\^(\|)",
.IR "\fIaio_cancel\fR\^(\|)",
.IR "\fIclose\fR\^(\|)",
.IR "\fIexec\fR\^",
.IR "\fIexit\fR\^(\|)",
.IR "\fIfork\fR\^(\|)",
.IR "\fIlseek\fR\^(\|)",
.IR "\fIread\fR\^(\|)"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "\fB<aio.h>\fP"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 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 .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .