Signaling Yourself (The GNU C Library)

#### 25.6.1 Signaling Yourself ¶

A process can send itself a signal with the `raise` function. This function is declared in `signal.h`.

Function: `int` raise `(int signum)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  The `raise` function sends the signal signum to the calling process. It returns zero if successful and a nonzero value if it fails. About the only reason for failure would be if the value of signum is invalid.

Function: `int` gsignal `(int signum)` ¶

  Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

  The `gsignal` function does the same thing as `raise`; it is provided only for compatibility with SVID.

One convenient use for `raise` is to reproduce the default behavior of a signal that you have trapped. For instance, suppose a user of your program types the SUSP character (usually `C-z`; see Special Characters) to send it an interactive stop signal (`SIGTSTP`), and you want to clean up some internal data buffers before stopping. You might set this up like this:

    #include <signal.h>

    /* When a stop signal arrives, set the action back to the default
       and then resend the signal after doing cleanup actions. */

    void
    tstp_handler (int sig)
    {
      signal (SIGTSTP, SIG_DFL);
      /* Do cleanup actions here. */
      ...
      raise (SIGTSTP);
    }

    /* When the process is continued again, restore the signal handler. */

    void
    cont_handler (int sig)
    {
      signal (SIGCONT, cont_handler);
      signal (SIGTSTP, tstp_handler);
    }

    /* Enable both handlers during program initialization. */

    int
    main (void)
    {
      signal (SIGCONT, cont_handler);
      signal (SIGTSTP, tstp_handler);
      ...
    }

Portability note: `raise` was invented by the ISO C committee. Older systems may not support it, so using `kill` may be more portable. See Signaling Another Process.