The lio_listio or lio_listio64 subroutine includes information for the POSIX AIO lio_listio subroutine (as defined in the IEEE std 1003.1-2001), and the Legacy AIO lio_listio subroutine.
POSIX AIO lio_listio Subroutine
Initiates a list of asynchronous I/O requests with a single call.
#include <aio.h>
int lio_listio(mode, list, nent, sig)
int mode;
struct aiocb *restrict const list[restrict];
int nent;
struct sigevent *restrict sig;The lio_listio subroutine initiates a list of I/O requests with a single function call.
The mode parameter takes one of the values (LIO_WAIT, LIO_NOWAIT or LIO_NOWAIT_AIOWAIT) declared in <aio.h> and determines whether the subroutine returns when the I/O operations have been completed, or as soon as the operations have been queued. If the mode parameter is set to LIO_WAIT, the subroutine waits until all I/O is complete and the sig parameter is ignored.
If the mode parameter is set to LIO_NOWAIT or LIO_NOWAIT_AIOWAIT, the subroutine returns immediately. If LIO_NOWAIT is set, asynchronous notification occurs, according to the sig parameter, when all I/O operations complete. If sig is NULL, no asynchronous notification occurs. If sig is not NULL, asynchronous notification occurs when all the requests in list have completed. If LIO_NOWAIT_AIOWAIT is set, the aio_nwait subroutine must be called for the aio control blocks to be updated. For more information, see the aio_nwait Subroutine.
The I/O requests enumerated by list are submitted in an unspecified order.
The list parameter is an array of pointers to aiocb structures. The array contains nent elements. The array may contain NULL elements, which are ignored.
The aio_lio_opcode field of each aiocb structure specifies the operation to be performed. The supported operations are LIO_READ, LIO_WRITE, and LIO_NOP; these symbols are defined in <aio.h>. The LIO_NOP operation causes the list entry to be ignored. If the aio_lio_opcode element is equal to LIO_READ, an I/O operation is submitted as if by a call to aio_read with the aiocbp equal to the address of the aiocb structure. If the aio_lio_opcode element is equal to LIO_WRITE, an I/O operation is submitted as if by a call to aio_write with the aiocbp argument equal to the address of the aiocb structure.
The aio_fildes member specifies the file descriptor on which the operation is to be performed.
The aio_buf member specifies the address of the buffer to or from which the data is transferred.
The aio_nbytes member specifies the number of bytes of data to be transferred.
The members of the aiocb structure further describe the I/O operation to be performed, in a manner identical to that of the corresponding aiocb structure when used by the aio_read and aio_write subroutines.
The nent parameter specifies how many elements are members of the list.
The behavior of the lio_listio subroutine 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 aio_fildes .
For regular files, no data transfer occurs past the offset maximum established in the open file description.
| Item | Description |
|---|---|
| mode | Determines whether the subroutine returns when the I/O operations are completed, or as soon as the operations are queued. |
| list | An array of pointers to aio control structures defined in the aio.h file. |
| nent | Specifies the length of the array. |
| sig | Determines when asynchronous notification occurs. |
The lio_listio and lio_listio64 subroutines can be called from the process environment only.
| Item | Description |
|---|---|
| EAGAIN | The resources necessary to queue all the I/O
requests were not available. The application may check the error status
of each aiocb to determine the individual request(s) that failed. The number of entries indicated by nent would cause the system-wide limit (AIO_MAX) to be exceeded. |
| EINVAL | The mode parameter is not a proper value, or the value of nent was greater than AIO_LISTIO_MAX. |
| EINTR | A signal was delivered while waiting for all I/O requests to complete during an LIO_WAIT operation. Since each I/O operation invoked by the lio_listio subroutine may 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 examines each list element to determine whether the request was initiated, canceled, or completed. |
| EIO | One or more of the individual I/O operations failed. The application may check the error status for each aiocb structure to determine the individual request(s) that failed. |
| Item | Description |
|---|---|
| EAGAIN | The requested I/O operation was not queued due to resource limitations. |
| ECANCELED | The requested I/O was canceled before the I/O completed due to an aio_cancel request. |
| EFBIG | The aio_lio_opcode argument is LIO_WRITE, the file is a regular file, aio_nbytes is greater than 0, and aio_offset is greater than or equal to the offset maximum in the open file description associated with aio_fildes. |
| EINPROGRESS | The requested I/O is in progress. |
| EOVERFLOW | The aio_lio_opcode argument is set to LIO_READ, the file is a regular file, aio_nbytes is greater than 0, and the aio_offset argument is before the end-of-file and is greater than or equal to the offset maximum in the open file description associated with aio_fildes. |
Legacy AIO lio_listio Subroutine
Initiates a list of asynchronous I/O requests with a single call.
#include <aio.h>int lio_listio (cmd,
list, nent, eventp)
int cmd, nent;
struct liocb * list[ ];
struct event * eventp;int lio_listio64
(cmd, list,nent, eventp)
int cmd, nent; struct liocb64 *list;
struct event *eventp;The lio_listio subroutine allows the calling process to initiate the nent parameter asynchronous I/O requests. These requests are specified in the liocb structures pointed to by the elements of the list array. The call may block or return immediately depending on the cmd parameter. If the cmd parameter requests that I/O completion be asynchronously notified, a SIGIO signal is delivered when all I/O operations are completed.
The lio_listio64 subroutine is similar to the lio_listio subroutine except that it takes an array of pointers to liocb64 structures. This allows the lio_listio64 subroutine to specify offsets in excess of OFF_MAX (2 gigbytes minus 1).
In the large file enabled programming environment, lio_listio is redefined to be lio_listio64.
| Item | Description |
|---|---|
| cmd | The cmd parameter takes one of the following values:
|
| list | Points to an array of pointers to liocb structures.
The structure array contains nent elements:
|
| nent | Specifies the number of entries in the array of pointers to listio structures. |
| eventp | Points to an event structure to be used when the cmd parameter is set to the LIO_ASYNC value. This parameter is currently ignored. |
The lio_listio and lio_listio64 subroutines can be called from the process environment only.
When the lio_listio subroutine is successful, it returns a value of 0. Otherwise, it returns a value of -1 and sets the errno global variable to identify the error. The returned value indicates the success or failure of the lio_listio subroutine itself and not of the asynchronous I/O requests (except when the command is LIO_WAIT). The aio_error subroutine returns the status of each I/O request.
If the lio_listio subroutine succeeds or fails with errors of EAGAIN, EINTR, or EIO, some of the I/O specified by the list might have been initiated. If the lio_listio subroutine fails with an error code other than EAGAIN, EINTR, or EIO, no operations from the list were 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 aiocb control block contains the associated error code. The error codes that can be set are the same as would be set by the read or write subroutines, with the following additional error codes possible:
| Item | Description |
|---|---|
| EAGAIN | Indicates that the system resources required to queue the request are not available. Specifically, the transmit queue may be full, or the maximum number of opens may have been reached. |
| EINTR | Indicates that a signal or event interrupted the lio_listio subroutine call. |
| EINVAL | Indicates that the aio_whence field does not have a valid value or that the resulting pointer is not valid. |
| EIO | One or more of the individual I/O operations failed. The application can check the error status for each aiocb structure to determine the individual request that failed. |