lio_listio or lio_listio64 Subroutine

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

Purpose

Initiates a list of asynchronous I/O requests with a single call.

Syntax

#include <aio.h>
int lio_listio(mode, list, nent, sig)
int mode;
struct aiocb *restrict const list[restrict];
int nent;
struct sigevent *restrict sig;

Description

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.

Parameters

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.

Execution Environment

The lio_listio and lio_listio64 subroutines can be called from the process environment only.

Return Values

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.
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:
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.

Purpose

Legacy AIO lio_listio Subroutine

Initiates a list of asynchronous I/O requests with a single call.

Syntax

#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;

Description

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.

Note: The pointer to the event structure eventp parameter is currently not in use, but is included for future compatibility.

Parameters

Item Description
cmd The cmd parameter takes one of the following values:
LIO_WAIT
Queues the requests and waits until they are complete before returning.
LIO_NOWAIT
Queues the requests and returns immediately, without waiting for them to complete. The event parameter is ignored.
LIO_NOWAIT_AIOWAIT
Queues the requests and returns immediately, without waiting for them to complete. The aio_nwait subroutine must be called for the aio control blocks to be updated. Use of the aio_suspend subroutine and the aio_cancel subroutine on these requests are not supported, nor is any form of asynchronous notification for individual requests.
LIO_ASYNC
Queues the requests and returns immediately, without waiting for them to complete. An enhanced signal is delivered when all the operations are completed. Currently this command is not implemented.
LIO_ASIG
Queues the requests and returns immediately, without waiting for them to complete. A SIGIO signal is generated when all the I/O operations are completed.
LIO_NOWAIT_GMCS
Queues the requests and returns immediately, without waiting for them to complete. The GetMultipleCompletionStatus subroutine must be called to retrieve the completion status for the requests. The aio control blocks are not updated. Use of the aio_suspend subroutine and the aio_cancel subroutine on these requests are not supported, nor is any form of asynchronous notification.
list Points to an array of pointers to liocb structures. The structure array contains nent elements:
lio_aiocb
The asynchronous I/O control block associated with this I/O request. This is an actual aiocb structure, not a pointer to one.
lio_fildes
Identifies the file object on which the I/O is to be performed.
lio_opcode
This field may have one of the following values defined in the /usr/include/sys/aio.h file:
LIO_READ
Indicates that the read I/O operation is requested.
LIO_WRITE
Indicates that the write I/O operation is requested.
LIO_NOP
Specifies that no I/O is requested (that is, this element will be ignored).
 
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.

Execution Environment

The lio_listio and lio_listio64 subroutines can be called from the process environment only.

Return Values

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.