sigaction()

Examine or specify the action associated with a signal

Synopsis:

#include <signal.h>

int sigaction( int sig,
               const struct sigaction * act,
               struct sigaction * oact );

Arguments:

sig: The signal number (defined in <signal.h>). For more information, see “POSIX and QNX Neutrino signals” in the documentation for SignalAction().
If the signal terminates a process, the cleanup of the terminated process occurs by default at the priority of the thread that sent the signal. As a QNX Neutrino extension, if you OR the SIG_TERMER_NOINHERIT flag (defined in <signal.h>) into sig, the cleanup occurs at the priority of the thread that received the signal.
act: NULL, or a pointer to a sigaction structure that specifies how you want to modify the action for the given signal.
oact: NULL, or a pointer to a sigaction structure that the function fills with information about the current action for the signal.

Library:

libc

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

Description:

You can use sigaction() to examine or specify (or both) the action that's associated with a specific signal:

If act isn't NULL, the specified signal is modified.
If oact isn't NULL, the previous action is stored in the structure it points to.

Signal handlers and actions are defined for the process and affect all threads in the process. For example, if one thread ignores a signal, then all threads ignore the signal.

You can target a signal at a thread, process, or process group (see SignalKill()). When targeted at a process, at most one thread receives the signal. This thread must have the signal unblocked (see SignalProcmask()) to be a candidate for receiving it. All synchronously generated signals (e.g., SIGSEGV) are always delivered to the thread that caused them.

Note:

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 by a previous call to sigsetjmp().
It isn't safe to use floating-point operations in signal handlers.

Returns:

0: Success.
-1: An error occurred (errno is set).

Errors:

EAGAIN: Insufficient system resources are available to set up the signal's action.
EFAULT: A fault occurred trying to access the buffers provided.
EINVAL: The signal sig isn't valid.

Examples:

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

int main( void )
  {
    void handler(int);
    sigset_t set;
    struct sigaction act = {
      .sa_flags = 0;
      .sa_mask = set,
      .sa_handler = &handler,
    }; 

    sigemptyset( &set );
    sigaddset( &set, SIGUSR1 );
    sigaddset( &set, SIGUSR2 );

    /*
     * Define a handler for SIGUSR1 such that when
     * entered both SIGUSR1 and SIGUSR2 are masked.
     */
    sigaction( SIGUSR1, &act, NULL );

    kill( getpid(), SIGUSR1 );

    /* Program will terminate with a SIGUSR2 */
    return EXIT_SUCCESS;
  }

void handler( int signo )
  {
    static int first = 1;

    if( first ) {
      first = 0;
      kill( getpid(), SIGUSR1 );  /* Prove signal masked */
      kill( getpid(), SIGUSR2 );  /* Prove signal masked */
    }
  }

/*
 * - SIGUSR1 is set from main(), handler() is called.
 * - SIGUSR1 and SIGUSR2 are set from handler().
 * - however, signals are masked until we return to main().
 * - returning to main() unmasks SIGUSR1 and SIGUSR2.
 * - pending SIGUSR1 now occurs, handler() is called.
 * - pending SIGUSR2 now occurs. Since we don't have
 *   a handler for SIGUSR2, we are killed.
 */

Classification:

POSIX 1003.1

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes