sigpause

sigpause

Suspend Execution and Control Blocking of Signals

Portability: UNIX compatible

SYNOPSIS
DESCRIPTION
RETURN VALUE
CAUTION
IMPLEMENTATION
EXAMPLE
RELATED FUNCTIONS
SEE ALSO

SYNOPSIS

#include <lcsignal.h>

int sigpause(int mask);

DESCRIPTION

sigpause temporarily changes the signal mask for asynchronous signals and suspends program execution until an unblocked signal is discovered. When the program resumes, the signal mask is restored to its previous settings. The mask argument is an integer interpreted as a bit string. You use this bit string to set the mask of blocked signals. If program execution is suspended and a signal occurs that is blocked by the mask, the program does not resume.

The most common use of this function is to unblock all signals while program execution is suspended. For example, sigpause(0) suspends execution until any signal occurs and then restores the previous mask to block whatever signals were blocked before the pause began.

When a signal that is not blocked by the mask is discovered, execution of the program resumes, the signal mask in effect when sigpause was called is restored, and the handler for the signal is called. Because sigpause restores the previous mask when the pause ends, you can use sigpause to handle a single occurrence of a signal, even if more than one signal is pending.

Note: If the mask that sigpause restores unblocks any signals that were blocked by the call to sigpause , you may encounter problems when several signals of different types are pending. Refer to CAUTION. [cautionend]

RETURN VALUE

sigpause returns the errno value EINTR, which indicates that it was interrupted by a signal. Refer to The errno Variable for more information on errno .

CAUTION

If your program uses USS signals, use sigsuspend rather than sigpause . The sigpause function does not allow you to control the blocking of USS signals.

The most common use of sigpause is to specify sigpause(0) , which allows any signal to be handled. If you specify an argument for sigpause other than 0, avoid blocking a signal in the mask that is not blocked when you call sigpause . The reason for this caution is that when an unblocked signal occurs, the old mask is restored, which unblocks pending signals. If there are pending signals, they may interrupt the handler for the original signal, causing considerable confusion.

For example, suppose that SIGINT signals are not blocked and you call sigpause(1< < (SIGINT-1)) . This call causes SIGINT signals to be blocked before execution is suspended. Suppose that execution resumes because SIGALRM occurs and that a SIGINT signal also occurs. Before the handler for SIGALRM is called, sigpause restores the original mask. This means the pending SIGINT signal can now be discovered during the execution of the handler for SIGALRM; the program must be prepared for this possibility.

IMPLEMENTATION

sigpause is implemented using idle waiting; that is, no CPU time is consumed (other than set-up time) while sigpause is executing.

EXAMPLE

#include <lcsignal.h>

volatile int shutdown = 0;

   /* SIGINT signals are blocked while the SIGINT handler */
   /*  executes.                                          */
signal(SIGINT, &int_handler);
sigblock(1<<(SIGINT-1));

   /* Wait for and handle interrupts one at a time. It is */
   /*  assumed that the SIGINT handler sets shutdown to   */
   /*  nonzero to cause program termination.              */
while(!shutdown)
   sigpause(0);

RELATED FUNCTIONS

ecbpause , pause , sigsuspend , sleep