lio_listio or lio_listio64 Subroutine

Base Operating System and Extensions Technical Reference, Volume 1

lio_listio or lio_listio64 Subroutine

Purpose

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 SIGIO signal will be replaced by real-time signals when they are available. The pointer to the event structure eventp parameter is currently not in use but is included for future compatibility.

Parameters

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

Return codes can be set to the following errno values:

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.
EFAIL	Indicates that one or more I/O operations was not successful. This error can be received only if the cmd parameter has a LIO_WAIT value.
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.

Implementation Specifics

The lio_listio and lio_listio64 subroutines are part of the Base Operating System (BOS) Runtime.

Related Information

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

The Asynchronous I/O Overview and the Communications I/O Subsystem: Programming Introduction in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs.

The Input and Output Handling Programmer's Overview in AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs describes the files, commands, and subroutines used for low-level, stream, terminal, and asynchronous I/O interfaces.