# lio_listio

## NAME



           lio_listio - initiate a list of I/O requests
    


## LIBRARY



           Real-time library (_librt_ , _-lrt_)
    


## SYNOPSIS



           **#include <aio.h>**
    
           **int lio_listio(** int n;
                          **int** _mode_**,**
                          **struct aiocb *restrict const** _aiocb_list_**[restrict** _n_**],**
                          **int** _n_**, 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_ argument 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, asynchronous 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 unspecified order.  The _n_ 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 operations (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 indicate the error.
    
           If _mode_ is **LIO_WAIT** , **lio_listio**() returns 0 when all of the I/O
           operations 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 operations 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 _n_ would cause the
                  limit **AIO_MAX** to be exceeded.
    
           **EINTR** _mode_ was **LIO_WAIT** and a signal was caught before all I/O
                  operations completed; see signal(7).  (This may even be one
                  of the signals used for asynchronous I/O completion
                  notification.)
    
           **EINVAL** _mode_ is invalid, or _n_ 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.
    


## 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 must
           not be accessed during the operations or undefined results may
           occur.  The memory areas involved must remain valid.
    
           Simultaneous I/O operations specifying the same _aiocb_ structure
           produce undefined results.
    


* * *