aio_nwait_timeout Subroutine

Purpose

Extends the capabilities of the aio_nwait subroutine by specifying timeout values.

Library

Standard C library (libc.a).

Syntax

int aio_nwait_timeout (cnt, nwait, list, timeout)
int cnt;
int nwait;
struct aiocbp **list;
int timeout;

Description

The aio_nwait_timeout subroutine waits for a certain number of asynchronous I/O operations to complete as specified by the nwait parameter, or until the call has blocked for a certain duration specified by the timeout parameter.

Parameters

Item	Description
cnt	Indicates the maximum number of pointers to the aiocbp structure that can be copied into the list array.
list	An array of pointers to aio control structures defined in the aio.h file.
nwait	Specifies the number of asynchronous I/O operations that must complete before the aio_nwait_timout subroutine returns.
timeout	Specified in units of milliseconds. A timeout value of `-1` indicates that the subroutine behaves like the aio_nwait subroutine, blocking until all of the requested I/O operations complete or until there are no more asynchronous I/O requests pending from the process. A timeout value of `0` indicates that the subroutine returns immediately with the current completed number of asynchronous I/O requests. All other positive timeout values indicate that the subroutine must block until either the timeout value is reached or the requested number of asynchronous I/O operations complete.

Return Values

The return value is the total number of requests the aio_nwait subroutine has waited on to complete. It can not be more than cnt. Although nwait is the desired amount of requests to find, the actual amount returned could be less than, equal to, or greater than nwait. The return value indicates how much of the list array to access.

The return value may be greater than the nwait value if the lio_listio subroutine initiated more than nwait requests and the cnt variable is larger than nwait. The nwait parameter represents a minimal value desired for the return value, and cnt is the maximum value possible for the return.

The return value may be less than the nwait value if some of the requests initiated by the lio_listio subroutine occur at a time of high activity, and there is a lack of resources available for the number of requests. The EAGAIN return code (error try again later) might be returned in some request's aio control blocks, but these requests will not be seen by the aio_nwait subroutine. In this situation, theaiocb structure addresses that are not found on the list must be accessed using the aio_error subroutine after the aio_nwait subroutine is called. You might need to increase the aio parameters max servers or max requests if this occurs. Increasing the parameters will ensure that the system is well tuned, and an EAGAIN error is less likely to occur. The return value might be less than the nwait value due to the setting of the new timeout parameter in the following cases:

timeout > 0 and a timeout has occurred before nwait requests are done
timeout = 0 and the current requests completed at the time of the aio_nwait_timeout call are less then nwait parameter

In the event of an error, the aio_nwait subroutine returns a value of -1 and sets the errno global variable to identify the error. Return codes can be set to the following errno values:

Item	Description
EBUSY	An aio_nwait call is in process.
EINVAL	The application has retrieved all of the aiocb pointers, but the user buffer does not have enough space for them.
EINVAL	There are no outstanding async I/O calls.