kill (BPX1KIL, BPX4KIL) — Send a signal to a process

Function

The kill callable service sends a signal to a process, a process group, or all processes in the system to which the caller has permission to send a signal.

Requirements

Parameters

Process_ID

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword whose value specifies the process or processes to which the signal is to be sent:

• If Process_ID is greater than 0, it is assumed to be a process ID. The signal is sent to the process with that specific process ID.
• If Process_ID is equal to 0, the signal is sent to all processes with a process group ID equal to that of the caller, and for which the caller has permission to send a signal.
• If Process_ID is -1, the signal is sent to all processes for which the caller has permission to send the signal.
• If Process_ID is less than -1, its absolute value is assumed to be a process group ID. The signal is sent to all processes with a process group ID equal to that absolute value, and for which the caller has permission to send a signal.

For more information, see Characteristics and restrictions.

Signal

Supplied parameter

Type:

Integer

Length:

Fullword

The name of a fullword that contains the signal number to be sent to the processes that are indicated by the Process_ID parameter. The signal number must be defined in the BPXYSIGH macro, or 0.

If the signal is 0, error checking takes place, but no signal is sent. Use a signal value of 0 to verify that the Process_ID parameter is correct before actually sending a signal. This method does not verify permission to send the signal to the specified Process_ID.

Signal_Options

Supplied parameter

Type:

Structure

Length:

Fullword

The name of a fullword that contains the binary flags that describe how the signal is to be handled by z/OS UNIX and the user-supplied signal interface routine (SIR). This byte of user information is passed to the SIR in a data structure that is mapped by the BPXYPPSD macro. 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 PPSDKILDATA.

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 first 2 bytes, set by the application
• Fourth bit - reserved
• Fifth bit - enhanced SIGKILL deliverability (superkill)
• Sixth bit - Indicates whether to override the SIGTRACE action. If this bit is ON, then the seventh bit indicates the override action. If this bit is OFF, the SIGTRACE action is to toggle the current user syscall trace setting for the target processes.
• Seventh bit - If this bit is ON, the SIGTRACE signal turns user syscall tracing ON. If OFF, then SIGTRACE turns user syscall tracing OFF.
• Remaining bits - reserved.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the kill service returns 0 if it has permission to send the specified signal to any of the processes specified by the Process_ID parameter. A return value of 0 means that a signal was sent (or could have been sent, if the signal value was 0) to at least one of the specified processes.

If no signal is sent, -1 is returned.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Return_code	Explanation
EINVAL	The value of Signal is incorrect, or is not the number of a supported signal.
EMVSSAF2ERR	The caller does not have the appropriate RACF® permissions.
EPERM	The caller does not have permission to send the signal to any process that was specified by the Process_ID parameter.
ESRCH	No processes or process groups that correspond to Process_ID were found.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

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

In the case of EMVSSAF2ERR, the reason code contains the security product return and reason codes, respectively, in the two low-order bytes. For a more detailed description of the security product Check Privilege service return and reason code values, see the following table:

Security Product Return Code	Security Product Reason Code	Explanation
8	4	The caller is not the owner of the target process.
8	12	There was an internal error during security product processing.

Related services

• getpid (BPX1GPI, BPX4GPI) — Get the process ID
• setpgid (BPX1SPG, BPX4SPG) — Set a process group ID for job control
• setsid (BPX1SSI, BPX4SSI) — Create a session and set the process group ID
• sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action

Characteristics and restrictions

1. A caller can send a signal if the real or effective user ID of the caller is the same as the real or saved set user ID of the intended recipient. A caller can also send signals if it has appropriate privileges.

   Permissions are discussed in Authorization.

2. Regardless of user ID, a caller can always send a SIGCONT signal to a process that is a member of the same session as the sender.
3. A caller can also send a signal to itself. If the signal is not blocked, at least one pending unblocked signal is delivered to the sender before the service returns control. Provided that no other unblocked signals are pending, the signal delivered is the signal sent. See The relationship of z/OS UNIX signals to callable services for more information.
4. The thread-scoped signals (SIGTHSTOP and SIGTHCONT) cannot be issued by the kill callable service. They can be issued only by the pthread_kill service.
5. An enhanced SIGKILL (superkill) can be sent by setting the PPSDSUPERKILL bit on in the BPXYPPSD (BPXYPPSD — Map signal delivery data). The superkill will break through most of the signal deterrents that can be an obstacle to the normal delivery of a SIGKILL and the resulting termination of the target process.
   Note:

   1. You cannot use pthread_kill() or sigqueue() to do a superkill. The superkill option is ignored for these services.
   2. You cannot do a superkill to a group, or specify a PID of -1 (kill everyone).
   3. When a target process has blocked all signals with the set_dub_default (BPX1SDD/BPX4SDD) service, superkills are deferred. The kill does not fail; it is simply ignored by the target process.
   4. Before a process can be superkilled, a regular SIGKILL must be sent to it, or the attempt will result in EINVAL/JRSigkillNotSent. This is analogous to the required "cancel" before a "force arm".
   If the environment is valid, the target process is abended with a X'422' abend and reason code X'0109'.

MVS-related information

For signal information, see The relationship of z/OS UNIX signals to callable services.