No manual entry for -- in section 3 lio_listio(3) Library Functions Manual lio_listio(3) NAME lio_listio - initiate a list of I/O requests LIBRARY Real-time library (librt, -lrt) SYNOPSIS #include <aio.h> int lio_listio(int mode, struct aiocb *restrict const aiocb_list[restrict], int nitems, struct sigevent *restrict sevp); DESCRIPTION The lio_listio() function initiates the list of I/O operations described by the array aiocb_list. The mode operation has one of the following values: LIO_WAIT The call blocks until all operations are complete. The sevp ar- gument is ignored. LIO_NOWAIT The I/O operations are queued for processing and the call returns immediately. When all of the I/O operations complete, asynchro- nous notification occurs, as specified by the sevp argument; see sigevent(3type) for details. If sevp is NULL, no asynchronous notification occurs. The aiocb_list argument is an array of pointers to aiocb structures that describe I/O operations. These operations are executed in an unspeci- fied order. The nitems argument specifies the size of the array aiocb_list. Null pointers in aiocb_list are ignored. In each control block in aiocb_list, the aio_lio_opcode field specifies the I/O operation to be initiated, as follows: LIO_READ Initiate a read operation. The operation is queued as for a call to aio_read(3) specifying this control block. LIO_WRITE Initiate a write operation. The operation is queued as for a call to aio_write(3) specifying this control block. LIO_NOP Ignore this control block. The remaining fields in each control block have the same meanings as for aio_read(3) and aio_write(3). The aio_sigevent fields of each control block can be used to specify notifications for the individual I/O opera- tions (see sigevent(7)). RETURN VALUE If mode is LIO_NOWAIT, lio_listio() returns 0 if all I/O operations are successfully queued. Otherwise, -1 is returned, and errno is set to in- dicate the error. If mode is LIO_WAIT, lio_listio() returns 0 when all of the I/O opera- tions have completed successfully. Otherwise, -1 is returned, and errno is set to indicate the error. The return status from 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 aiocb_list can be determined using aio_error(3). When an operation has completed, its return status can be obtained using aio_return(3). Individual I/O oper- ations can fail for the reasons described in aio_read(3) and aio_write(3). ERRORS The lio_listio() function may fail for the following reasons: EAGAIN Out of resources. EAGAIN The number of I/O operations specified by nitems would cause the limit AIO_MAX to be exceeded. EINTR mode was LIO_WAIT and a signal was caught before all I/O opera- tions completed; see signal(7). (This may even be one of the signals used for asynchronous I/O completion notification.) EINVAL mode is invalid, or nitems exceeds the limit AIO_LISTIO_MAX. EIO One of more of the operations specified by aiocb_list failed. The application can check the status of each operation using aio_return(3). If lio_listio() fails with the error EAGAIN, EINTR, or EIO, then some of the operations in aiocb_list may have been initiated. If lio_listio() fails for any other reason, then none of the I/O operations has been initiated. ATTRIBUTES For an explanation of the terms used in this section, see attributes(7). +--------------------------------------------+---------------+---------+ | Interface | Attribute | Value | +--------------------------------------------+---------------+---------+ | lio_listio() | Thread safety | MT-Safe | +--------------------------------------------+---------------+---------+ STANDARDS POSIX.1-2008. HISTORY glibc 2.1. POSIX.1-2001. NOTES It is a good idea to zero out the control blocks before use. The con- trol blocks must not be changed while the I/O operations are in progress. The buffer areas being read into or written from must not be accessed during the operations or undefined results may occur. The mem- ory areas involved must remain valid. Simultaneous I/O operations specifying the same aiocb structure produce undefined results. SEE ALSO aio_cancel(3), aio_error(3), aio_fsync(3), aio_return(3), aio_sus- pend(3), aio_write(3), aio(7) Linux man-pages 6.9.1 2024-05-02 lio_listio(3)