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

Function

The aio_suspend callable service suspends the calling thread until a specified asynchronous I/O event, specified timeout, or signal occurs.

Requirements

Parameters

Aiocb_Ptr_List

Supplied parameter

Type:

Structure

Length:

Variable

The name of a list of 31(64)-bit pointers. Each pointer in the list is the address of an Aiocb. Each Aiocb represents a previously submitted asynchronous I/O operation that the thread is to wait on for completion. The number of Aiocb pointers in the list is represented by the Aiocb_Ptr_Count parameter.

Aiocb_Ptr_Count

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the number of pointers in the Aiocb_Ptr_List. If you do not want to wait on any asynchronous I/O requests, define Aiocb_Ptr_Count as the name of a fullword that contains 0.

Seconds

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains an unsigned integer that is the maximum number of seconds the calling program is willing to wait for one of specified asynchronous I/O events to occur.

Note:

1. Seconds can be any value greater than or equal to 0 and less than or equal to 4 294 967 295.
2. The Seconds and Nanoseconds values are combined to determine the timeout value. A combined value of zero indicates that the aio_suspend service will not wait at all. A value of AIO#NO_ASP_TIMEOUT (see BPXYAIO — Map asyncio parameter list) indicates that no timeout value is set.

Nanoseconds

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains an unsigned integer that is the number of nanoseconds to be added to the value specified by the Seconds parameter.

Notes:

1. Nanoseconds can be any value greater than or equal to 0 and less than or equal to 1 000 000 000.
2. The Seconds and Nanoseconds values are combined to determine the timeout value.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the aio_suspend service returns 0 if the request is successful, or -1 if it is not successful.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the aio_suspend service stores the return code. The aio_suspend service returns Return_code only if Return_value is -1. See z/OS UNIX System Services Messages and Codes for a complete list of possible return code values. The aio_suspend service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	One or more of the specified parameters are not valid. The following reason codes unique to the aio_suspend service can accompany the return code: JrNanoSecondsTooBig, JrMaxAiocbECB.
EFAULT	One of the parameters specified contains the address of a storage area that is not accessible to the caller. The following reason codes unique to the aio_suspend service can accompany the return code: JrOK, JrBadAioEcb.
EINTR	The service was interrupted by a signal. One or more of the specified asynchronous I/O requests may have completed.
EAGAIN	The service timed out before any of the specified asynchronous I/O requests had completed.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the aio_suspend service stores the reason code. The aio_suspend service returns Reason_code only if Return_value is -1. Reason_code further qualifies the Return_code value. For the reason codes, see z/OS UNIX System Services Messages and Codes.

Usage notes

1. The number of pointers to Aiocbs that use application-supplied ECB pointers for invocations of the aio_suspend service is limited to 254 when the Seconds and Nanoseconds parameters are both set to zero, and to 253 if either is nonzero. See asyncio (BPX1AIO, BPX4AIO) — Asynchronous I/O for sockets for information on how to supply user-defined ECBs in the Aiocb data area.
2. If the Aiocbs are specified without application-supplied ECB pointers, there is no limit on the number of Aiocb pointers.
3. The Aiocbs that are represented by the list of Aiocb pointers must reside in the same storage key as the caller of the aio_suspend service. If the Aiocb Pointer List or any of the Aiocbs represented in the list are not accessible by the caller, an error of EFAULT may occur.
4. Aiocb pointers in the list with a value of zero are ignored.
5. A timeout value of zero (Seconds + Nanoseconds) means that the aio_suspend service does not wait at all, but checks for any completed asynchronous I/O requests. If it finds none, it returns with an error of EAGAIN; otherwise, it returns with a Return_value of 0.
6. A passed timeout value of AIO#NO_ASP_TIMEOUT (see BPXYAIO — Map asyncio parameter list) means that no timeout value is set. The aio_suspend service waits until an asynchronous I/O request completes or until a signal is received.
7. The Aiocbs that are passed to the aio_suspend service must not be freed or reused by other threads in the process while this service is still in progress. The service may use the Aiocbs even after the asynchronous I/O completes. This restriction prevents multiple threads from doing aio_suspend()s on the same Aiocb at the same time. The results of modifying the Aiocb during an aio_suspend are unpredictable.
8. If the aio_suspend service is being called in AMODE 64 (BPX4ASP), the Aiocb_Ptr_List must contain 64-bit pointers only.

Related services

• asyncio (BPX1AIO, BPX4AIO) — Asynchronous I/O for sockets

Characteristics and restrictions

None.