[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]
AIX Version 4.3 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.
[ Previous |
Next |
Contents |
Glossary |
Home |
Search ]