home | help 
std::signal(3)		       C++ Standard Libary		  std::signal(3)

NAME
     std::signal - std::signal

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

	Changes handling of the signal sig. Depending on handler, the signal can
     be ignored,
	set to default, or handled by a user-defined function.

	When  signal handler is set to a function and a signal occurs, it is im-
     plementation
	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
		  the signal to set the signal handler to. It can be an
		  implementation-defined value or one of the following values:

		  SIGABRT
	sig	- SIGFPE
		  SIGILL  defines signal types
		  SIGINT  (macro constant)
		  SIGSEGV
		  SIGTERM
		  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.
	handler -   * A pointer to a function. The  signature  of  the	function
     must be
		      equivalent to the following:

		  extern "C" void fun(int sig);

Return value
	Previous signal handler on success or SIG_ERR on failure (setting a sig-
     nal 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 std::abort or
	std::raise (asynchronous signal), the behavior is undefined if

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

	  * std::abort
	  *							      std::_Exit
     (until C++17)
	  * 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 storage
	    duration that is not
	    std::atomic or
	    (since C++11)volatile std::sig_atomic_t.
	A plain lock-free atomic operation is an invocation of a function f
	from <atomic>
	or <stdatomic.h>
	(since C++23), such that:

	  * f is the function std::atomic_is_lock_free,
	  * f is the member function is_lock_free (e.g.
	    std::atomic::is_lock_free()),
	  * f is a non-static member function of std::atomic_flag,
	  * f is a non-member function, and the first parameter of f has type
	    cv std::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):
     (since C++17)

	  * 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 std::numeric_limits
	  * std::_Exit
	  * std::abort
	  * std::quick_exit
	  * The member functions of std::initializer_list and the
	    std::initializer_list overloads of std::begin and std::end
	  * std::forward, std::move, std::move_if_noexcept
	  * All functions from <type_traits>
	  * std::memcpy and std::memmove
	  * access to an object with thread storage duration
	  * a dynamic_cast expression
	  * a throw expression
	  * entry to a try block
	  * 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

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

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

	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	 lock-free	 std::atomic	   types
     (until C++14)
	  * side effects made visible through			 (since C++11)
	    std::atomic_signal_fence

	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 lock-free
	std::atomic is indeterminate.
	A call to the function signal() synchronizes-with any resulting
	invocation of the signal handler.

	If a signal handler is executed as a result of a call to std::raise
	(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.
									       (since
     C++14)
	Two accesses to the same object of type volatile std::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 volatile std::sig_atomic_t objects take values as though all
	evaluations in A happened-before the execution of the signal handler
	and the execution of the signal handler happened-before all
	evaluations in B.

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++. However, common  implemen-
     tations allow
	a function with C++ linkage to 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

References
	  * C++23 standard (ISO/IEC 14882:2023):

	  * 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 retroac-
     tively to
	previously published C++ standards.

	   DR	 Applied to		 Behavior as published		    Cor-
     rect behavior
	LWG 3756 C++17	    it was unclear whether std::atomic_flag  is       it
     is
			    signal-safe

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

http://cppreference.com 	   2024.06.10			  std::signal(3)
home | help