aio_suspend() — Wait for an asynchronous I/O request

Standards

Format

#define _XOPEN_SOURCE 500
#include <aio.h>

int aio_suspend(const struct aiocb *const list[],
                int nent, const struct timespec *timeout);

General description

The aio_suspend() function suspends the calling thread when the timeout is a NULL pointer until at least one of the asynchronous I/O operations referenced by the list argument has completed, or until a signal interrupts the function. Or, if timeout is not NULL, it is suspended until the time interval specified by timeout has passed. If the time interval indicated in the timespec structure pointed to by timeout passes before any of the I/O operations referenced by list, then aio_suspend() returns with an error. If any of the aoicb structures in the list correspond to completed asynchronous I/O operations (that is, the error status for the operation is not equal to EINPROGRESS) at the time of the call, the function returns without suspending the calling thread.

The list argument is an array of pointers to asynchronous I/O control blocks (AIOCBs). The nent argument indicates the number of elements in the array. Each aiocb structure pointed to will have been used in initiating an asynchronous I/O request. This array may contain NULL pointers, which are ignored. If this array contains pointers that refer to aiocb structures that have not been used in submitting asynchronous I/O or aiocb structures that are not valid, the results are unpredictable.

Returned value

If successful, aio_suspend() returns 0.

Usage notes

1. The AIOCBs represented by the list of AIOCB pointers must reside in the same storage key as the key of the invoker of aio_suspend. If the AIOCB Pointer List or any of the AIOCBs represented in the list are not accessible by the invoker an EFAULT may occur.
2. AIOCB pointers in the list with a value of zero will be ignored.
3. A timeout value of zero (seconds+nanoseconds) means that the aio_suspend() call will not wait at all. It will check for any completed asynchronous I/O requests. If none are found it will return with a EAGAIN. If at least one is found aio_suspend() will return with success.
4. A timeout value of a timespec with the tv_sec field set with INT_MAX, as defined in <limits.h>, will cause the aio_suspend service to wait until a asynchronous I/O request completes or a signal is received.

   If the Macro _AIO_OS390 is defined then the following may also apply.

5. The number of pointers to AIOCBs that use application supplied event control block (ECB) pointers for invocations of asynchronous I/O is limited to 253. There is no limit when not using the _AIO_OS390 Feature Test Macro. See z/OS UNIX System Services Programming: Assembler Callable Services Reference under the BPX1AIO for information on supplying user-defined ECBs in the AIOCB data area.
6. The AIOCBs passed to aio_suspend() must not be freed or reused by other threads in the process while this service is still in progress. This service may use the AIOCBs even after the asynchronous I/O completes. This restriction excludes multiple threads from doing aio_suspend() on the same AIOCB at the same time. Modifying the AIOCB during an aio_suspend() will produce unpredictable results.
7. The use of these extensions will require macros from SYS1.CSSLIB. Make sure that it is included in the SYSLIB concatenation during the compile.

Related information

• aio.h
• aio_error() — Retrieve error status for an asynchronous I/O operation
• aio_read() — Asynchronous read from a socket
• aio_return() — Retrieve status for an asynchronous I/O operation