From cppreference.com
Defined in header
/*signal-handler*/*signal(intsig,/*signal-handler*/*handler); (1) extern"C"using/*signal-handler*/=void(int); (2)(exposition only*)Changes handling of the signal sig. Depending on the value of handler, the signal can be ignored, set to default, or handled by a user-defined function invoked as (*handler)(sig).
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
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: handler - the signal handler. This must be one of the following:
macro. The signal handler is set to default signal handler.
macro. The signal is ignored.
A pointer to a function. The signature of the function must be equivalent to the following:
extern"C"voidfun(intsig);Return value
Previous signal handler on success or
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 signal handler is called NOT as a result of
or
(asynchronous signal), the behavior is undefined if
the signal handler calls any function within the standard library, except
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 storage duration that is not
or (since C++11)volatilestd::sig_atomic_t.
(until C++17)A plain lock-free atomic operation is an invocation of a function f from
or
(since C++23), such that:
f is the function
,
f is the member function is_lock_free (e.g.
),
f is a non-static member function of
,
f is a non-member function, and the first parameter of f has type cvstd::atomic_flag*,
f is a non-static member function invoked on an object obj, such that obj.is_lock_free() yields true, or
f is a non-member function, and for every pointer-to-atomic argument arg passed to f, std::atomic_is_lock_free(arg) yields true.
The behavior is undefined if any signal handler performs any of the following:
call to any library function, except for plain lock-free atomic operations and the following signal-safe functions (note, in particular, dynamic allocation is not signal-safe):
std::signal with the first argument being the number of the signal currently handled (signal handler can re-register itself, but not other signals).
member functions of
The member functions of
and the std::initializer_list overloads of
and
, std::move,
All functions from
and
access to an object with thread storage duration
a
expression
a
expression
entry to a
initialization of a static variable that performs
dynamic non-local initialization
(including delayed until first ODR-use)
waits for completion of initialization of any variable with static storage duration due to another thread concurrently initializing it
(since C++17)If the user defined function returns when handling
,
,
or any other implementation-defined signal specifying a computational exception, the behavior is undefined.
If the signal handler is called as a result of
or
(synchronous signal), the behavior is undefined if the signal handler calls
.
On entry to the signal handler, the state of the
and the values of all objects is unspecified, except for
objects of type volatilestd::sig_atomic_t
On return from a signal handler, the value of any object modified by the signal handler that is not volatilestd::sig_atomic_t or lock-free
is indeterminate.
(until C++14)A call to the function signal()
any resulting invocation of the signal handler.
If a signal handler is executed as a result of a call to
(synchronously), then the execution of the handler is sequenced-after the invocation of std::raise and sequenced-before the return from it and runs on the same thread as std::raise. Execution of the handlers for other signals is unsequenced with respect to the rest of the program and runs on an unspecified thread.
Two accesses to the same object of type volatilestd::sig_atomic_t do not result in a data race if both occur in the same thread, even if one or more occurs in a signal handler. For each signal handler invocation, evaluations performed by the thread invoking a signal handler can be divided into two groups A and B, such that no evaluations in B happen-before evaluations in A, and the evaluations of such volatilestd::sig_atomic_t objects take values as though all evaluations in A
the execution of the signal handler and the execution of the signal handler happened-before all evaluations in B.
(since C++14)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
and, in general, only use the features from the common subset of C and C++. However, common implementations allow a function with C++ linkage to be used as a signal handler.
Example
Run this code
#include<csignal>#include<iostream>namespace{volatilestd::sig_atomic_tgSignalStatus;}voidsignal_handler(intsignal){gSignalStatus=signal;}intmain(){// Install a signal handlerstd::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 References
C++23 standard (ISO/IEC 14882:2024):
17.13.5 Signal handlers [support.signal]
C++20 standard (ISO/IEC 14882:2020):
17.13.5 Signal handlers [support.signal]
C++17 standard (ISO/IEC 14882:2017):
21.10.4 Signal handlers [support.signal]
Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
DR Applied to Behavior as published Correct behavior
C++17 it was unclear whether
is signal-safe it is See also