1 files changed, 224 insertions, 0 deletions
diff --git a/man/man3/lio_listio.3 b/man/man3/lio_listio.3
new file mode 100644
index 0000000..2e38492
--- /dev/null
+++ b/man/man3/lio_listio.3
@@ -0,0 +1,224 @@
+'\" t
+.\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH lio_listio 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+lio_listio \- initiate a list of I/O requests
+.SH LIBRARY
+Real-time library
+.RI ( librt ", " \-lrt )
+.SH SYNOPSIS
+.nf
+.B "#include <aio.h>"
+.P
+.BI "int lio_listio(int " mode ,
+.BI "               struct aiocb *restrict const " aiocb_list [restrict],
+.BI "               int " nitems ", struct sigevent *restrict " sevp );
+.fi
+.SH DESCRIPTION
+The
+.BR lio_listio ()
+function initiates the list of I/O operations described by the array
+.IR aiocb_list .
+.P
+The
+.I mode
+operation has one of the following values:
+.TP
+.B LIO_WAIT
+The call blocks until all operations are complete.
+The
+.I sevp
+argument is ignored.
+.TP
+.B LIO_NOWAIT
+The I/O operations are queued for processing and the call returns immediately.
+When all of the I/O operations complete, asynchronous notification occurs,
+as specified by the
+.I sevp
+argument; see
+.BR sigevent (3type)
+for details.
+If
+.I sevp
+is NULL, no asynchronous notification occurs.
+.P
+The
+.I aiocb_list
+argument is an array of pointers to
+.I aiocb
+structures that describe I/O operations.
+These operations are executed in an unspecified order.
+The
+.I nitems
+argument specifies the size of the array
+.IR aiocb_list .
+Null pointers in
+.I aiocb_list
+are ignored.
+.P
+In each control block in
+.IR aiocb_list ,
+the
+.I aio_lio_opcode
+field specifies the I/O operation to be initiated, as follows:
+.TP
+.B LIO_READ
+Initiate a read operation.
+The operation is queued as for a call to
+.BR aio_read (3)
+specifying this control block.
+.TP
+.B LIO_WRITE
+Initiate a write operation.
+The operation is queued as for a call to
+.BR aio_write (3)
+specifying this control block.
+.TP
+.B LIO_NOP
+Ignore this control block.
+.P
+The remaining fields in each control block have the same meanings as for
+.BR aio_read (3)
+and
+.BR aio_write (3).
+The
+.I aio_sigevent
+fields of each control block can be used to specify notifications
+for the individual I/O operations (see
+.BR sigevent (7)).
+.SH RETURN VALUE
+If
+.I mode
+is
+.BR LIO_NOWAIT ,
+.BR lio_listio ()
+returns 0 if all I/O operations are successfully queued.
+Otherwise, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.P
+If
+.I mode
+is
+.BR LIO_WAIT ,
+.BR lio_listio ()
+returns 0 when all of the I/O operations have completed successfully.
+Otherwise, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.P
+The return status from
+.BR lio_listio ()
+provides information only about the call itself,
+not about the individual I/O operations.
+One or more of the I/O operations may fail,
+but this does not prevent other operations completing.
+The status of individual I/O operations in
+.I aiocb_list
+can be determined using
+.BR aio_error (3).
+When an operation has completed,
+its return status can be obtained using
+.BR aio_return (3).
+Individual I/O operations can fail for the reasons described in
+.BR aio_read (3)
+and
+.BR aio_write (3).
+.SH ERRORS
+The
+.BR lio_listio ()
+function may fail for the following reasons:
+.TP
+.B EAGAIN
+Out of resources.
+.TP
+.B EAGAIN
+.\" Doesn't happen in glibc(?)
+The number of I/O operations specified by
+.I nitems
+would cause the limit
+.B AIO_MAX
+to be exceeded.
+.TP
+.B EINTR
+.I mode
+was
+.B LIO_WAIT
+and a signal
+was caught before all I/O operations completed; see
+.BR signal (7).
+(This may even be one of the signals used for
+asynchronous I/O completion notification.)
+.TP
+.B EINVAL
+.I mode
+is invalid, or
+.\" Doesn't happen in glibc(?)
+.I nitems
+exceeds the limit
+.BR AIO_LISTIO_MAX .
+.TP
+.B EIO
+One of more of the operations specified by
+.I aiocb_list
+failed.
+.\" e.g., ioa_reqprio or aio_lio_opcode was invalid
+The application can check the status of each operation using
+.BR aio_return (3).
+.P
+If
+.BR lio_listio ()
+fails with the error
+.BR EAGAIN ,
+.BR EINTR ,
+or
+.BR EIO ,
+then some of the operations in
+.I aiocb_list
+may have been initiated.
+If
+.BR lio_listio ()
+fails for any other reason,
+then none of the I/O operations has been initiated.
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR lio_listio ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 2.1.
+POSIX.1-2001.
+.SH NOTES
+It is a good idea to zero out the control blocks before use.
+The control blocks must not be changed while the I/O operations
+are in progress.
+The buffer areas being read into or written from
+.\" or the control block of the operation
+must not be accessed during the operations or undefined results may occur.
+The memory areas involved must remain valid.
+.P
+Simultaneous I/O operations specifying the same
+.I aiocb
+structure produce undefined results.
+.SH SEE ALSO
+.BR aio_cancel (3),
+.BR aio_error (3),
+.BR aio_fsync (3),
+.BR aio_return (3),
+.BR aio_suspend (3),
+.BR aio_write (3),
+.BR aio (7)