diff options
Diffstat (limited to 'man3/lio_listio.3')
| -rw-r--r-- | man3/lio_listio.3 | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/man3/lio_listio.3 b/man3/lio_listio.3 new file mode 100644 index 0000000..0cca6e4 --- /dev/null +++ b/man3/lio_listio.3 @@ -0,0 +1,225 @@ +'\" t +.\" Copyright (C) 2010, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH lio_listio 3 2023-07-20 "Linux man-pages 6.05.01" +.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>" +.PP +.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 . +.PP +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 (7) +for details. +If +.I sevp +is NULL, no asynchronous notification occurs. +.PP +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. +.PP +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. +.PP +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. +.PP +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. +.PP +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). +.PP +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 +.sp 1 +.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. +.PP +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) |