sigqueue (BPX1SGQ, BPX4SGQ) — Queue a signal to a process

Function

The sigqueue callable service queues a signal to a process, a process group, or all processes in the system to which the caller has permission to queue a signal.

CAUTION:
Note that when a caller with appropriate privileges (see Authorization) specifies a process ID equal to -1, the signal will normally be queued to all processes in the system, excluding the INIT process (process ID 1). If the signal action is to terminate the process, all processes will terminate. This may not be the desired action, considering that some processes may be necessary for the continued operation of the system.

Requirements

Operation Environment
Authorization: Problem program or supervisor state, any PSW key
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1SGQ): 31-bit
AMODE (BPX4SGQ): 64-bit
ASC mode: Primary address space control (ASC) 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

CALL BPX1SGQ,(Process_ID,
              Signal,
              Signal_Value,
              Signal_Options,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4SGQ with the same parameters. Signal_Value is a doubleword field.

Parameters

Process_ID
Supplied parameter
Type:
Integer
Length:
Fullword
The name of a fullword whose value specifies the process or processes to which the caller wants to queue a signal:
  • If Process_ID is greater than 0, it is assumed to be a process ID. The signal is queued to the process with that process ID.
  • If Process_ID is equal to 0, the signal is queued to all processes that have a process group ID equal to that of the caller, and for which the caller has permission to queue the signal.
  • If Process_ID is -1, the signal is queued to all processes for which the caller has permission to queue the signal.
  • If Process_ID is less than -1, its absolute value is assumed to be a process group ID. The signal is queued to all processes that have a process group ID equal to this absolute value, and for which the caller has permission to queue a signal.

Note the restrictions in Characteristics and restrictions.

Signal
Supplied parameter
Type:
Integer
Length:
Fullword

The name of a fullword that contains the signal number that is to be queued to the processes indicated by the Process_ID parameter. The signal number must be defined in the BPXYSIGH macro, or it must be 0. See BPXYSIGH — Signal constants.

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

Signal_Value
Supplied parameter
Type:
Integer
Length:
Fullword (doubleword)

The name of a fullword (doubleword) that contains data to be delivered with the signal.

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 the system and the user-supplied signal interface routine (SIR). This byte of user information is passed to the SIR in a data structure mapped by the PBXYPPSD macro. See BPXYPPSD — Map signal delivery data.

Signal options are mapped as follows:
First 2 bytes
User-defined bytes to be 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 - the 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 sigqueue service returns 0 if it has permission to queue the specified signal to any of the processes specified by the Process_ID parameter. A return value of 0 means that a signal was queued (or could have been queued, if the signal value was 0) to at least one of the specified processes.

If a signal is not queued, the return value is -1.

Return_code
Returned parameter
Type:
Integer
Length:
Fullword

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

Return code Explanation
EAGAIN The caller has reached the maximum number of queued signals (MAXQUEUEDSIGS) allowed in a process.
EINVAL The value specified in the Signal parameter is incorrect, or not the number of a supported signal.
EMVSSAF2ERR The SAF ck_process_owner (IRRSKO00) callable service returned with an unexpected error.
EPERM The caller does not have permission to queue the signal to any process specified in the Process_ID parameter.
ESRCH No processes or process groups corresponding to the value specified in the Process_ID parameter were found.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the sigqueue service stores the reason code. The sigqueue service stores a reason code only when the return value is -1. The reason code further qualifies the return code value. See z/OS UNIX System Services Messages and Codes for the reason 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

Characteristics and restrictions

  1. A caller can queue 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 queue signals if it has appropriate privileges (see Authorization).
  2. Regardless of its user ID, a caller can always queue a SIGCONT signal to a process that is a member of the same session.
  3. A caller can queue a signal to itself. If the signal is not blocked, at least one pending unblocked signal is delivered to the caller before the service returns control. Provided that no other unblocked signals are pending, the signal that is delivered is the signal that is queued. See The relationship of z/OS UNIX signals to callable services for more information.
  4. Note the caution at the beginning of this callable service description.

Examples

For an example using this callable service, see BPX1SGQ (sigqueue) example.

Parent topic: Callable services descriptions