Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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*/* handler);
       (1)
	  extern "C" using /*signal-handler*/ =	void(int); //  exposition-only
       (2)

	  Sets	the  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  immedi-
       ately before the
	  start	of signal handler. Also, the implementation can	prevent	some
	  implementation-defined  set of signals from occurring	while the sig-
       nal handler runs.

	  For some of the  signals,  the  implementation  may  call  std::sig-
       nal(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  implementa-
       tion-defined
	  behaviors)

Parameters
		    the	signal to set the signal handler to. It	can be an
		    implementation-defined  value or one of the	following val-
       ues:

		    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.
	  handler -   *	SIG_IGN	macro. The signal is ignored.
		      *	 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
       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 std::abort	or
	  std::raise (asynchronous signal), the	behavior is undefined if

	    * the signal handler calls any function within  the	 standard  li-
       brary,
	      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(since C++11) or volatile
	      std::sig_atomic_t.
	  The behavior is undefined if any signal handler performs any of the
	  following:

	    * call to any library function, except the following signal-safe
	      functions	(note, in particular, dynamic allocation is not
	      signal-safe):

		* members functions of std::atomic  and	 non-member  functions
       from
		  <atomic>  if	the  atomic type they operate on is lock-free.
       The
		  functions std::atomic_is_lock_free and
		  std::atomic::is_lock_free are	 signal-safe  for  any	atomic
       type.
		* 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
       (since C++17)
		* 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, including function-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 sta-
       tic
	      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 ex-
       ception,	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 (since C++11)
	    *  side  effects  made  visible  through  std::atomic_signal_fence
       (since  (until C++14)
	      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 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-af-
       ter
	  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++. It is
       (until C++17)
	  implementation-defined if a function with C++	linkage	can be used as
       a
	  signal handler.
	  There	 is  no	 restriction  on  the  linkage	of  signal   handlers.
       (since C++17)

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)
	  atomic_signal_fence fence between a thread and a signal handler exe-
       cuted in	the same
	  (C++11)	      thread
			      (function)

http://cppreference.com		  2022.07.31			std::signal(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=std::signal&sektion=3&manpath=FreeBSD+Ports+15.0>

home | help