mvssigsetup (BPX1MSS, BPX4MSS) — Set up MVS signals

Function

The mvssigsetup callable service allows a task to catch or intercept signals. This service also allows a task to intercept cancellation and quiesce interrupts. Only one mvssigsetup service in a process can be active. If a second mvssigsetup service must be performed in a process, an mvsunsigsetup service must be performed on the thread that issued the mvssigsetup service request before the second invocation of the mvssigsetup service.

Both MVS™ task termination and the mvsprocclp service (BPX1MPC, BPX4MPC) perform the mvsunsigsetup service.

Requirements

Operation Environment
Authorization: Problem program or supervisor state, PSW key when the process was created (not PSW key 0)
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE (BPX1MSS): 31-bit
AMODE (BPX4MSS): 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

CALL BPX1MSS,(Signal_interface_routine_address,
              User_data,
              Default_override_signal_set,
              Default_terminate_signal_set,
              Return_value,
              Return_code,
              Reason_code)

AMODE 64 callers use BPX4MSS with the same parameters. The Signal_interface_routine_address parameter and the User_data parameter are doublewords.

Parameters

Signal_interface_routine_address
Supplied parameter
Type:
Address
Length:
Fullword (doubleword)

The name of a fullword (doubleword) containing the address of the user-supplied signal interface routine (SIR) that gets control when a signal handler needs to be invoked. The signal handler is defined by the sigaction call; see sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action. You can also invoke the SIR to process a default signal action, depending on the values specified for Default_override_signal_set. See the usage note on using the upper bit of the SIR address for indirect signal handler addresses.

User_data
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
Fullword (doubleword)

The name of a fullword (in 31–bit mode) or doubleword (in 64–bit mode) containing 4 or 8 bytes of user-supplied data that is passed to the signal interface routine on invocation from signal processing.

Default_override_signal_set
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
8 bytes

The name of an 8-byte area containing a 64-bit mask of signals that the SIR processes when their respective default actions take place. The leftmost bit represents signal number 1, and the rightmost bit represents signal number 64. The signals SIGSTOP, SIGDUMP, and SIGTRACE cannot be intercepted. The bit positions that represent these signals are ignored. Signal 64 represents cancellation or quiesce requests. For more information, see BPXYSIGH — Signal constants.

Default_terminate_signal_set
Supplied parameter
Type:
Character string
Character set:
No restriction
Length:
8 bytes

The name of an 8-byte area containing a 64-bit mask of signals specified in the Default_override_signal_set parameter that also causes the process to end. The leftmost bit represents signal number 1, and the rightmost bit represents signal number 64. When set to 1, the signal represented results in a task that is either stopped or in a wait state to be interrupted by the signal. It is up to the signal interface routine to end the process. The bit that represents signal 64 of this mask is reserved. For more information, see BPXYSIGH — Signal constants.

Return_value
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the mvssigsetup 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 mvssigsetup service stores the return code. The mvssigsetup 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 mvssigsetup service can return one of the following values in the Return_code parameter:
Return_code Explanation
EMVSINITIAL The service failed. The following reason codes can accompany the return code: JRNotPRB, JRPSWKeyNotValid, and JRAlreadySigSetup.
Reason_code
Returned parameter
Type:
Integer
Length:
Fullword

The name of a fullword in which the mvssigsetup service stores the reason code. The mvssigsetup 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 user-supplied signal interface routine (SIR) is given control when the current PSW key is equal to the signal delivery key for the process. The signal delivery key for the process is defined as the PSW key when the process was dubbed for the first request for a callable service. A process image that results after the exec service or the execmvs service always has a signal delivery key of 8 and is not set up for signals.

If the signal handler addresses specified on the call to sigaction are not the actual handler addresses but pointers to the handler addresses, turn on the upper bit of the SIR address supplied on this service to enable ptrace to set breakpoints at the beginning of the signal handlers.

For information about the BPXYPPSD macro, see BPXYPPSD — Map signal delivery data.

The SIR receives control with the following register interface:

Register Contents
Reg 0 0
Reg 1 Address of standard parameter list. PARM1= address of BPXYPPSD; Reg 1 = ADDR(PpsdSirPARMS).
Regs 2–12 0
Reg 13 0 No save area for registers is provided to the SIR. The SIR does not save caller's registers.
Reg 14 0 No return address.
Reg 15 Set to address of the SIR.

The SIR receives control in the following system state:

Operation Environment
Authorization: Problem program state, PSW key when the process was created (not PSW key 0)
Dispatchable unit mode: Task
Cross memory mode: PASN = HASN
AMODE: The same as the caller of mvssigsetup (BPX1MSS, BPX4MSS)
ASC mode: Primary mode
Interrupt status: Enabled for interrupts
Locks: Unlocked
Signal mask: All signals that may be blocked by the signal mask are blocked.
Following are the steps that a user-supplied SIR must perform.
  1. The SIR must obtain local storage for a local copy of the BPXYPPSD and copy the BPXYPPSD information into this local storage.
  2. The PPSD contains the information necessary for the SIR to determine the reason for the interruption. The interruption can be the result of a signal, cancellation, or quiesce request.
  3. If the interrupt cannot be processed at this time, possibly due to general register 13 not currently containing the address of a program stack, or the last service called on the current thread was cond_setup, then the queue_interrupt service request is issued (see queue_interrupt (BPX1SPB, BPX4SPB) — Return the last interrupt delivered). Then go to step 11.
  4. If the interrupt is a signal and the default action is to be performed by the SIR, write the appropriate messages to the terminal and end the process. For more information about how to end the process, see _exit (BPX1EXI, BPX4EXI) — End a process and bypass the cleanup.
  5. If the interrupt is a cancellation or a terminating quiesce request, clean up any necessary thread-related resources and end the thread. To end the thread, issue the pthread_get_and_exit service with Options_field set to PTEXITTHREAD. If the interrupt is because of a cancellation, issue the pthread_exit_and_get service with Status_field set to -1. For more information about how to end the thread, see pthread_exit_and_get (BPX1PTX, BPX4PTX) — Exit and get a new thread. If the interrupt is a freeze quiesce request, issue the quiesce_threads service to freeze the thread; see pthread_quiesce (BPX1PTQ, BPX4PTQ) — Quiesce threads in a process. The SIR receives these types of interrupts only if bit 64 of the Default_override_signal_set is set on.
  6. Obtain language stack storage for the signal handler.
  7. Examine the sigaction call flags in the BPXYPPSD for the signal being delivered. Some of these flags, specified on the sigaction call, are intended to allow the user certain options when interfacing with signal catchers, or to provide additional processing. For example, the SA_SIGINFO flag specifies that additional signal information, also present in BPXYPPSD, should be passed to the signal catcher in a siginfo structure. It is up to the SIR to interpret and implement these sigaction flags. Refer to sigaction (BPX1SIA, BPX4SIA) — Examine or change a signal action for more information about the function of the sigaction flags. The relevant flags are:
    • SA_ONSTACK
    • SA_RESETHAND
    • SA_RESTART
    • SA_SIGINFO
    • SA_NODEFER
  8. Set the signal processor mask to the appropriate value before invoking the signal handler. This mask is formed by taking the union of the current signal mask (PPSDCATCHERMASK), the value of Sa_mask specified on the sigaction call for the signal being delivered (PPSDSAMASK), and then including the signal being delivered (unless the SA_NODEFER flag is set). The signal processor mask is set by calling the sigprocmask service (BPX1SPM, BPX4SPM). Recursive calls to the SIR can occur after calling the sigprocmask service here to unblock signals. Therefore, the SIR must use the local copy of the BPXYPPSD macro after calling the sigprocmask service.
  9. Conform to the language-dependent requirements for invoking signal-handlers.
  10. On return from the signal handler, call the sigprocmask service to set the signal processor mask to the interrupted value that was saved in the BPXYPPSD field PPSDCURRENTMASK on entry to this SIR.
  11. Use the CSRL16J MVS service to load 16 registers and jump to the address that was interrupted by the signal.

The use of the Default_terminate_signal_set is to indicate to the kernel which signals intercepted by the SIR cause the process to end. For example, a user might wish to intercept the SIGUSR1 signal, but rather than performing the default of termination, the user might wish to have a message issued and then the signal thrown away (ignored). In this case, the user would turn the corresponding bit on in the Default_override_signal_set and off in the Default_terminate_signal_set. This bit set combination tells the kernel not to interrupt functions that return an EINTR.

Related services

Characteristics and restrictions

See The relationship of z/OS UNIX signals to callable services.

Examples

For an example using this callable service, see BPX1MSS (mvssigsetup) example.

Parent topic: Callable services descriptions