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.
The lio_listio and lio_listio64 subroutines can be called from the process environment only.
| 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. |
If the lio_listio subroutine succeeds or fails with errors of EAGAIN, EINTR, or EIO, some of the I/O specified by the list may 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:
| 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. |
aio_cancel or aio_cancel64 Subroutine, aio_error or aio_error64 Subroutine, aio_read or aio_read64 Subroutine, aio_return or aio_return64 Subroutine, aio_suspend or aio_suspend64 Subroutine, aio_write or aio_write64 Subroutine, close Subroutine, exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine, exit, atexit, _exit, or _Exit Subroutine, fork, f_fork, or vfork Subroutine, and lseek, llseek or lseek64 Subroutine.
The read, readx, readv, readvx, or pread Subroutine in AIX 5L Version 5.2 Technical Reference: Base Operating System and Extensions Volume 2.
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.
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.
Return codes can be set to the following errno values:
The aio_cancel or aio_cancel64 (aio_cancel or aio_cancel64 Subroutine) subroutine, aio_error or aio_error64 (aio_error or aio_error64 Subroutine) subroutine, aio_read or aio_read64 (aio_read or aio_read64 Subroutine) subroutine, aio_return or aio_return64 (aio_return or aio_return64 Subroutine) subroutine, aio_suspend or aio_suspend64 (aio_suspend or aio_suspend64 Subroutine) subroutine, aio_write or aio_write64 (aio_write or aio_write64 Subroutine) subroutine.
The Asynchronous I/O Overview and the Communications I/O Subsystem: Programming Introduction in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.
The Input and Output Handling Programmer's Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs describes the files, commands, and subroutines used for low-level, stream, terminal, and asynchronous I/O interfaces.