pthread_setintr (BPX1PSI, BPX4PSI) — Examine and change the interrupt state

Function

The pthread_setintr callable service sets the specified interruptability state of the calling thread and atomically returns the previous interruptability state.

Requirements

Parameters

Interrupt_state

Supplied parameter

Type:

Structure

Length:

Fullword

Specifies the name of a fullword that contains a numeric value that identifies the interrupt state that is to be set. The following constants, which are defined in the BPXYCONS macro, define the valid states (see BPXYCONS — Constants used by services):

Constant	Description
PTHREAD_INTR_ENABLE#	When interruptability is enabled, new or pending cancelation requests are acted upon according to the interruptability type set by the pthread_setintrtype service (BPX1PST, BPX4PST).
PTHREAD_INTR_DISABLE#	When interruptability is disabled, cancelation requests against the target thread are held pending.

Return_value

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the service returns the previous interrupt state, or -1 if the service did not complete successfully.

Return_code

Returned parameter

Type:

Integer

Length:

Fullword

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

Return code	Explanation
EINVAL	One of the parameters contains a value that is not valid.

Reason_code

Returned parameter

Type:

Integer

Length:

Fullword

The name of a fullword in which the pthread_setintr service stores the reason code. The pthread_setintr 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. Setting the interruptability state allows you to control when cancelation requests sent via the pthread_cancel (BPX1PTB, BPX4PTB) service are handled.
2. The pthread_setintr (BPX1PSI, BPX4PSI) and pthread_intrtype (BPX1PST, BPX4PST) services establish three interruptability states:
   • Disabled: Cancellation requests are left pending.
   • Controlled: Cancellation requests are left pending until the next cancelation point is reached. Cancellation points are defined as when:
     • The pthread_testinr service is invoked (BPX1PTI, BPX4PTI).
     • A thread is placed in an unbounded wait during a call to a z/OS UNIX service. Some examples of these types of calls are
       • close (BPX1CLO, BPX4CLO) — Close a file
       • cond_wait (BPX1CWA, BPX4CWA) — Suspend a thread for an event
       • fcntl (BPX1FCT, BPX4FCT) — Control open file descriptors
       • open (BPX1OPN, BPX4OPN) — Open a file
       • pause (BPX1PAS, BPX4PAS) — Suspend a process pending a signal
       • pthread_join (BPX1PTJ, BPX4PTJ) — Wait on a thread
       • pthread_testintr (BPX1PTI, BPX4PTI) — Cause a cancellation point to occur
       • read (BPX1RED, BPX4RED) — Read from a file or socket
       • sigsuspend (BPX1SSU, BPX4SSU) — Change the signal mask and suspend the thread until a signal is delivered
       • sigwait (BPX1SWT, BPX4SWT) — Wait for a signal
       • sleep (BPX1SLP, BPX4SLP) — Suspend execution of a process for an interval of time
       • tcdrain (BPX1TDR, BPX4TDR) — Wait until output has been transmitted
       • tcsetattr (BPX1TSA, BPX4TSA) — Set the attributes for a terminal
       • wait (BPX1WAT, BPX4WAT) — Wait for a child process to end
       • write (BPX1WRT, BPX4WRT) — Write to a file or a socket
   • Asynchronous: Cancellation request can be delivered at any time.
3. The default interrupt state for newly created threads and the initial thread is PTHREAD_INTR_ENABLE#.
4. The default interrupt type for newly created threads and the initial thread is PTHREAD_INTR_CONTROLLED#.
5. The interruption types of controlled and asynchronous are set with pthread_intrtype (BPX1PST, BPX4PST). See pthread_setintrtype (BPX1PST, BPX4PST) — Examine and change the interrupt type. These states are acted upon only if thread interruption is enabled. If a cancelation request is pending and the interrupt state or type is set to allow asynchronous cancelation requests, the thread is canceled before control is returned to the invoker.
6. See Optimizing performance using process- and thread-level information.

Related services

• pthread_cancel (BPX1PTB, BPX4PTB) — Cancel a thread
• pthread_setintrtype (BPX1PST, BPX4PST) — Examine and change the interrupt type
• pthread_testintr (BPX1PTI, BPX4PTI) — Cause a cancellation point to occur

Characteristics and restrictions

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