pthread_cancel (BPX1PTB, BPX4PTB) — Cancel a thread

Function

The pthread_cancel callable service generates a cancelation request for the target thread.

Requirements

Parameters

Thread_ID

Supplied parameter

Type:

Character string

Length:

8 bytes

The name of an 8-byte field that contains the thread ID for the thread that is to be canceled.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pthread_cancel service returns 0 if the thread is canceled or the cancel is pending, or -1 if a failure occurs.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Return Code	Explanation
EINVAL	The value that was specified by thread ID is not valid. It does not contain a value that is consistent with thread IDs managed by the system. The following reason code can accompany this return code: JRLightWeightThID.
ESRCH	The value that was specified by Thread_ID does not refer to a thread that currently exists. The following reason codes can accompany this return code: JRThreadNotFound and JRAlreadyTerminated.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pthread_cancel service stores the reason code. The pthread_cancel 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. A successful call to pthread_cancel generates a cancelation request for the target thread.
2. Delivery of the cancelation request either causes a nonretryable 422 abend (with reason code 01A0), or causes the signal interface routine (established with BPX1MSS/BPX4MSS) to receive control.
3. If the invoking process sets _BPXK_FORCE_CANCEL=YES, this service is allowed to cancel threads that are not cancelable when this environment variable is set to NO, which is the default. To do this, the pthread_cancel() service will wait up to three seconds for the thread cancelation to take effect before terminating the target task with a 422 non-retryable abend, ReasonCode=1A0. The abend occurs only if after three seconds the thread has not terminated. If the target of the pthread_cancel() is the invoking thread, the service exits without waiting three seconds and the cancelation occurs upon exit from the pthread_cancel() service. If the invoking process sets _BPXK_FORCE_CANCEL=YES and then cancels a large number of threads, the amount of time to complete the cancels may be significantly larger than when the environment variable is NO. This is because the pthread_cancel() service may wait for up to three seconds before terminating each thread. For more information, see Commonly used environment variables in z/OS UNIX System Services Planning.
4. See the usage notes in pthread_setintr (BPX1PSI, BPX4PSI) — Examine and change the interrupt state for the definition of thread cancelation points.

Related services

• pthread_create (BPX1PTC, BPX4PTC) — Create a thread
• pthread_exit_and_get (BPX1PTX, BPX4PTX) — Exit and get a new thread
• pthread_join (BPX1PTJ, BPX4PTJ) — Wait on a thread
• pthread_kill (BPX1PTK, BPX4PTK) — Send a signal to a thread
• pthread_self (BPX1PTS, BPX4PTS) — Query the thread ID

Characteristics and restrictions

There are no restrictions on the use of the pthread_cancel service.