lio_listio(3) — Subroutines
Digital
NAME
lio_listio − let the calling process initiate a list of asynchronous I/O requests (P1003.4/D10)
SYNOPSIS
#include <aio.h>
int lio_listio (
int mode ,
struct liocb ∗list[] ,
int nent ,
struct sigevent ∗event) ;
PARAMETERS
mode A bit mask that defines how lio_listio returns.
list A pointer to an array of pointers to liocb structures.
nent The length of the array list which also specifies the number of operations to potentially perform.
event A pointer to a signal control structure.
DESCRIPTION
The lio_listio function allows the calling process to initiate a list of I/O requests with a single function call. The mode argument determines whether the function returns after the I/O operations are complete or as soon as they have been queued.
The mode argument can take any one of three values; LIO_WAIT, LIO_NOWAIT, or LIO_ASYNC. If you specify LIO_WAIT, the function waits until all I/O operations are completed. If you specify LIO_NOWAIT, the function returns immediately. If you specify LIO_ASYNC, the function returns immediately and a specified signal is issued when the entire list of I/O requests is complete. When the mode argument has the value LIO_ASYNC, the event argument defines the signal generated. If the mode is specified as LIO_WAIT or LIO_NOWAIT, event is ignored.
The list argument is a pointer to an array of pointers to liocb structures. The liocb structure contains at least the following members:
int lio_opcode;
int lio_fildes;
struct aiocb lio_aiocb;
The lio_opcode member specifies the operation and can take any one of three values; LIO_READ, LIO_WRITE, and LIO_NOP. If the lio_opcode is LIO_READ, the I/O operation is submitted as an aio_read operation. If the lio_opcode is LIO_WRITE the I/O operation is submitted as an aio_write operation. If the lio_opcode is LIO_NOP, the list entry is skipped.
The lio_fildes member specifies the file descriptor, and the lio_aiocb.aio_buf member specifies the address of the data transfer buffer.
The nent argument specifies the number of elements to be operated on.
The event argument points to a sigevent structure, which contains the signal number of the signal to be sent upon completion of the asynchronous I/O operation. A signal may be sent upon completion of each asynchronous I/O operation. That is, on completion of each read or write, whether initiated by a call to an aio_read or aio_write function as well as each read or write performed through a call to the lio_listio function a signal can be returned. The lio_listio function can also send a signal when all list elements have been serviced.
The sigevent structure is defined in <signal.h> and contains the following members:
void ∗sevt_value;
signal_t sevt_signo;
The sevt_value member is an application-defined value to be passed to the signal catching function at the time of signal delivery. This member is used in P1003.4/D10 Realtime Signals Extensions, which are not currently supported. Specify a value of NULL for this member.
The sevt_signo member specifies the signal number to be sent on completion of the asynchronous I/O operation.
RETURN VALUES
On a successful call, a value of 0 is returned indicating that the function is successfully queued.
On an unsuccessful call, a value of −1 is returned and errno is set to indicate that an error occurred.
The return indicates the success or failure of the lio_listio call, not the status of the individual I/O requests. In some cases one or more of the I/O requests contained in the list may fail. Failure of an individual request does not prevent completion of any other individual request. To determine the outcome of each I/O request, the application needs to examine the error status associated with the handle in each lio_aiocb control block. You can do this by calling the aio_error function. The error codes returned are identical to those returned as the result of an aio_read or aio_write function.
ERRORS
The lio_listio function fails under the following conditions:
[EAGAIN] The resources necessary to queue all the I/O requests were not available. The application may check the error status for each lio_aiocb to determine the individual request(s) that failed.
[EIO] One or more of the individual I/O operations failed. The application may check error status for each aiocb structure to determine the individual requests that failed, by calling aio_error. It is not possible to receive this error return when the mode argument to the lio_listio request was LIO_NOWAIT or LIO_ASYNC.
[EINVAL] The mode argument is not a proper value. The number of entries indicated by nent was too large.
[EINTR] A signal or event was delivered while waiting for all I/O requests to complete during a LIO_WAIT operation. Outstanding I/O requests are not canceled and application must examine each list element to determine whether the request was initiated, interrupted, or completed.
[ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit aio_cancel request.
[EINPROG] The requested I/O is in progress.