std::signal

 

C++

Language

Standard library headers

Concepts

Utilities library

Strings library

Containers library

Algorithms library

Iterators library

Numerics library

Input/output library

Localizations library

Regular expressions library (C++11)

Atomic operations library (C++11)

Thread support library (C++11)

Filesystem library (C++17)

Technical Specifications

 

Utilities library

Type support (basic types, RTTI, type traits)

Dynamic memory management

Error handling

Program utilities

Variadic functions

Date and time

Function objects

initializer_list (C++11)

bitset

hash (C++11)

Relational operators

rel_ops::operator!=rel_ops::operator>rel_ops::operator<=rel_ops::operator>=

optional, any and variant (C++17)

optional

any

variant

in_placein_place_typein_place_indexin_place_tin_place_type_tin_place_index_t

Pairs and tuples

pair

tuple (C++11)

apply (C++17)

make_from_tuple (C++17)

piecewise_construct_t (C++11)

piecewise_construct (C++11)

integer_sequence (C++14)

Swap, forward and move

swap

exchange (C++14)

forward (C++11)

move (C++11)

move_if_noexcept (C++11)

Elementary string conversions

to_chars (C++17)

from_chars (C++17)

chars_format (C++17)

Type operations

declval (C++11)

as_const (C++17)

 

Program support utilities

Program termination
abort exit quick_exit (C++11) _Exit (C++11)	atexit at_quick_exit (C++11) EXIT_SUCCESSEXIT_FAILURE
Communicating with the environment
system	getenv
Signals
signal raise sig_atomic_t	SIG_DFLSIG_IGN SIG_ERR
Signal types
SIGABRTSIGFPESIGILLSIGINTSIGSEGVSIGTERM
Non-local jumps
setjmp
longjmp
Types
jmp_buf

 

Defined in header <csignal>
/*signal-handler*/* signal(int sig, /*signal-handler*/* handler);	(1)
extern "C" using /*signal-handler*/ = void(int); // exposition-only	(2)

Sets the error handler for signal sig. The signal handler can be set so that default handling will occur, signal is ignored, or a user-defined function is called.

When signal handler is set to a function and a signal occurs, it is implementation defined whether std::signal(sig, SIG_DFL) will be executed immediately before the start of signal handler. Also, the implementation can prevent some implementation-defined set of signals from occurring while the signal handler runs.

For some of the signals, the implementation may call std::signal(sig, SIG_IGN) at the startup of the program. For the rest, the implementation must call std::signal(sig, SIG_DFL).

(Note: POSIX introduced sigaction to standardize these implementation-defined behaviors)

Parameters

sig	-	the signal to set the signal handler to. It can be an implementation-defined value or one of the following values: SIGABRTSIGFPESIGILLSIGINTSIGSEGVSIGTERM defines signal types (macro constant)
handler	-	the signal handler. This must be one of the following: SIG_DFL macro. The signal handler is set to default signal handler. SIG_IGN macro. The signal is ignored. pointer to a function. The signature of the function must be equivalent to the following: void fun(int sig);

Return value

Previous signal handler on success or SIG_ERR on failure (setting a signal handler can be disabled on some implementations).

Signal handler

The following limitations are imposed on the user-defined function that is installed as a signal handler.

If the user defined function returns when handling SIGFPE, SIGILL, SIGSEGV or any other implementation-defined signal specifying a computational exception, the behavior is undefined.

If the signal handler is called as a result of std::abort or std::raise, the behavior is undefined if the signal handler calls std::raise.

If the signal handler is called NOT as a result of std::abort or std::raise, the behavior is undefined if

• the signal handler calls any function within the standard library, except

• std::abort
• std::_Exit
• std::quick_exit
• std::signal with the first argument being the number of the signal currently handled (async handler can re-register itself, but not other signals).

• the signal handler refers to any object with static or thread-local(since C++11) storage duration that is not std::atomic(since C++11) or volatile std::sig_atomic_t.

On entry to the signal handler, the state of the floating-point environment and the values of all objects is unspecified, except for

• objects of type volatile std::sig_atomic_t
• objects of std::atomic types (since C++11)
• side effects made visible through std::atomic_signal_fence (since C++11)

On return from a signal handler, the value of any object modified by the signal handler that is not volatile std::sig_atomic_t or std::atomic is undefined.

The behavior is undefined if std::signal is used in a multithreaded program. It is not required to be thread-safe.

Notes

POSIX requires that signal is thread-safe, and specifies a list of async-signal-safe library functions that may be called from any signal handler.

Signal handlers are expected to have C linkage and, in general, only use the features from the common subset of C and C++. It is implementation-defined if a function with C++ linkage can be used as a signal handler.

Example

Run this code

#include <csignal>
#include <iostream>
 
namespace
{
  volatile std::sig_atomic_t gSignalStatus;
}
 
void signal_handler(int signal)
{
  gSignalStatus = signal;
}
 
int main()
{
  // Install a signal handler
  std::signal(SIGINT, signal_handler);
 
  std::cout << "SignalValue: " << gSignalStatus << '\n';
  std::cout << "Sending signal " << SIGINT << '\n';
  std::raise(SIGINT);
  std::cout << "SignalValue: " << gSignalStatus << '\n';
}

Possible output:

SignalValue: 0
Sending signal 2
SignalValue: 2

See also

raise	runs the signal handler for particular signal (function)
C documentation for signal
atomic_signal_fence (C++11)	fence between a thread and a signal handler executed in the same thread (function)