signal()

Set handling for exceptional conditions

Synopsis:

#include <signal.h>

void ( * signal( int sig, 
                void ( * func)(int) ) )( int );

Arguments:

sig

The signal number (defined in <signal.h>). For more information, see “POSIX signals” in the documentation for SignalAction().

func

The function that you want to call when the signal is raised.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The signal() function is used to specify an action to take place when certain conditions are detected while a program executes. See the <signal.h> header file for definitions of these conditions, and also refer to the System Architecture manual.

There are three types of actions that can be associated with a signal: SIG_DFL, SIG_IGN or a pointer to a function. Initially, all signals are set to SIG_DFL or SIG_IGN prior to entry of the main() routine. An action can be specified for each of the conditions, depending upon the value of the func argument, as discussed below.

func is a function

When func is a function name, that function is called in a manner equivalent to the following code sequence:

/* "sig_no" is condition being signalled */
signal( sig_no, SIG_DFL );
(*func)( sig_no );

The func function may do the following:

• Return.
• Terminate the program by calling exit() or abort().
• Call longjmp() or siglongjmp(). If you use longjmp() to return from a signal handler, the signal remains masked. You can use siglongjmp() to restore the mask to the state saved in a previous call to sigsetjmp().

After returning from the signal-catching function, the receiving process resumes execution at the point at which it was interrupted.

The signal catching function is described as follows:

void func( int sig_no )
{
  …
}

It isn't possible to catch the SIGSTOP or SIGKILL signals.

Since signal-catching functions are invoked asynchronously with process execution, use the atomic_*, InterruptLock(), and InterruptUnlock() functions for atomic operations.

func is SIG_DFL

If func is SIG_DFL, the default action for the condition is taken.

If the default action is to stop the process, the execution of that process is temporarily suspended. When a process stops, a SIGCHLD signal is generated for its parent process, unless the parent process has set the SA_NOCLDSTOP flag (see sigaction()). While a process is stopped, any additional signals that are sent to the process aren't delivered until the process is continued, except SIGKILL, which always terminates the receiving process.

Setting a signal action to SIG_DFL for a signal that is pending, and whose default action is to ignore the signal (for example, SIGCHLD), causes the pending signal to be discarded, whether or not it's blocked.

func is SIG_IGN

If func is SIG_IGN, the indicated condition is ignored.

You can't set the action for the SIGSTOP and SIGKILL signals to SIG_IGN.

Setting a signal action to SIG_IGN for a signal that's pending causes the pending signal to be discarded, whether or not it is blocked.

If a process sets the action for the SIGCHLD signal to SIG_IGN, the behavior is unspecified.

Handling a condition

When a condition is detected, it may be handled by a program, it may be ignored, or it may be handled by the usual default action (often causing an error message to be printed on the stderr stream followed by program termination).

A condition can be generated by a program using the raise() or kill() function

Returns:

The previous value of func for the indicated condition, or SIG_ERR if the request couldn't be handled (errno is set to EINVAL).

Examples:

#include <stdlib.h>
#include <signal.h>

sig_atomic_t signal_count;

void MyHandler( int sig_number )
  {
     ++signal_count;
  }

int main( void )
  {
    signal( SIGFPE, MyHandler );   /* set own handler */
    signal( SIGABRT, SIG_DFL );    /* Default action */
    signal( SIGFPE, SIG_IGN );     /* Ignore condition */
    return (EXIT_SUCCESS);
  }

Classification:

ANSI, POSIX 1003.1

See also:

atomic_add(), atomic_add_value(), atomic_clr(), atomic_clr_value(), atomic_set(), atomic_set_value(), atomic_sub(), atomic_sub_value(), atomic_toggle(), atomic_toggle_value(), InterruptLock(), InterruptUnlock(), kill(), longjmp(), pthread_sigmask(), raise(), siglongjmp(), sigprocmask()