lio_listio.3p (10488B)
- '\" 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 .