pthread_kill (BPX1PTK, BPX4PTK) — Send a signal to a thread

Function

The pthread_kill callable service targets a signal to a particular thread. The service is limited to interthread communication within a process.

Requirements

Operation	Environment
Authorization:	Supervisor state or problem state, any PSW key
Dispatchable unit mode:	Task
Cross memory mode:	PASN = HASN
AMODE (BPX1PTK):	31-bit
AMODE (BPX4PTK):	64-bit
ASC mode:	Primary mode
Interrupt status:	Enabled for interrupts
Locks:	Unlocked
Control parameters:	All parameters must be addressable by the caller and in the primary address space.

Format

The syntax format is as follows:

CALL BPX1PTK,(Thread_ID,
              Signal,
              Signal_options,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4PTK with the same parameters.

Parameters

Thread_ID

Supplied parameter

Type:: Character string
Length:: 8 bytes

The name of an 8-byte field that contains the target thread that is to receive the signal.

Signal

Supplied parameter

Type:: Integer
Length:: Fullword

The name of a fullword field that contains the signal number that is to be sent to the thread that is indicated by the Thread_ID parameter. This must be one of the signals defined in BPXYSIGH macro, or 0.

If the signal is 0, error checking takes place, but no signal is sent. The pthread_kill service can be called with a signal value of 0, to verify that Thread_ID parameter is correct before the signal is actually sent.

Signal_options

Supplied parameter

Type:: Bit
Length:: Fullword

The name of a fullword field that contains the binary flags that describe how the signal is to be handled by both the kernel and the user-supplied signal interface routine (SIR). The signaling options are passed to the SIR in the signal information control block, which is mapped by BPXYPPSD; see BPXYPPSD — Map signal delivery data. Signal_options are mapped as follows:

First 2 bytes

User-defined bytes that are delivered with the signal to the SIR in the signal information control block. These bytes are mapped by the BPXYPPSD macro.

Last 2 bytes

Flag bits, mapped by PPSDKILOPTS, that are defined as follows:

First bit - signal to bypass Ptrace processing
Second bit - reserved
Third bit - signal code specified in the first 2 bytes is set by the application
Remaining bits - reserved

Return_Value

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the pthread_kill 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 pthread_kill service stores the return code. The pthread_kill 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_kill service can return one of the following values in the Return_code parameter:

Return_code	Explanation
EINVAL	One of the following conditions causes this return code: The value of Signal is not valid, or is not the number of a supported signal. The thread corresponding to Thread_ID was not found, not valid, or ended. The following reason codes can accompany the return code: JRInvalidSignal, JRLightWeightThid, JRThreadNotFound, and JRThreadTerm.

Return_code

Explanation

EINVAL

One of the following conditions causes this return code:

The value of Signal is not valid, or is not the number of a supported signal.
The thread corresponding to Thread_ID was not found, not valid, or ended.

The following reason codes can accompany the return code: JRInvalidSignal, JRLightWeightThid, JRThreadNotFound, and JRThreadTerm.

Reason_Code

Returned parameter

Type:: Integer
Length:: Fullword

The name of a fullword in which the pthread_kill service stores the reason code. The pthread_kill 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

The pthread_kill service provides a mechanism for asynchronously directing a signal to a thread in the calling process. This mechanism could be used, for instance, by one thread to cause the processing of other threads within the process.
The pthread_kill service is the only function that can issue the thread-scoped signals (SIGTHSTOP and SIGTHCONT). The SIGTHSTOP signal stops a specific thread; other threads in the process are not affected. The SIGTHCONT signal can be issued by the pthread_kill service to resume the stopped thread.
SIGTHSTOP and SIGTHCONT can only be issued to threads within the same process. If all the threads in a process are stopped with SIGTHSTOP, the process is virtually hung. No other threads can send a SIGTHCONT signal to wake them up. The stopped threads must be manually killed.

The SIGTHSTOP and SIGTHCONT signals are noncatchable, nonblockable, and cannot be ignored.

Related services

Characteristics and restrictions

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

Examples

For an example using this callable service, see BPX1PTK (pthread_kill) example.

MVS-related information

Delivery of a signal to the signal interface routine occurs only when the PSW key of the caller is equal to the signal delivery key of the process. The signal delivery key is set to the PSW key of the caller of the first callable service that dubbed the process.