src/os/signal/doc.go - go - Git at Google

 // Copyright 2015 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.

 /*
 Package signal implements access to incoming signals.

 Signals are primarily used on Unix-like systems. For the use of this
 package on Windows and Plan 9, see below.

 Types of signals

 The signals SIGKILL and SIGSTOP may not be caught by a program, and
 therefore can not be affected by this package.

 Synchronous signals are signals triggered by errors in program
 execution: SIGBUS, SIGFPE, and SIGSEGV. These are only considered
 synchronous when caused by program execution, not when sent using
 os.Process.Kill or the kill program or some similar mechanism. In
 general, except as discussed below, Go programs will convert a
 synchronous signal into a run-time panic.

 The remaining signals are asynchronous signals. They are not
 triggered by program errors, but are instead sent from the kernel or
 from some other program.

 Of the asynchronous signals, the SIGHUP signal is sent when a program
 loses its controlling terminal. The SIGINT signal is sent when the
 user at the controlling terminal presses the interrupt character,
 which by default is ^C (Control-C). The SIGQUIT signal is sent when
 the user at the controlling terminal presses the quit character, which
 by default is ^\ (Control-Backslash). In general you can cause a
 program to simply exit by pressing ^C, and you can cause it to exit
 with a stack dump by pressing ^\.

 Default behavior of signals in Go programs

 By default, a synchronous signal is converted into a run-time panic. A
 SIGHUP, SIGINT, or SIGTERM signal causes the program to exit. A
 SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGSTKFLT, SIGEMT, or SIGSYS signal
 causes the program to exit with a stack dump. A SIGTSTP, SIGTTIN, or
 SIGTTOU signal gets the system default behavior (these signals are
 used by the shell for job control). The SIGPROF signal is handled
 directly by the Go runtime to implement runtime.CPUProfile. Other
 signals are ignored.

 If the Go program is started with either SIGHUP or SIGINT ignored,
 they will remain ignored. Go always registers a handler for the other
 signals.

 If the Go program is started with a non-empty signal mask, that will
 generally be honored. However, some signals are explicitly unblocked:
 the synchronous signals, SIGILL, SIGTRAP, SIGSTKFLT, SIGCHLD, SIGPROF,
 and, on GNU/Linux, signals 32 (SIGCANCEL) and 33 (SIGSETXID)
 (SIGCANCEL and SIGSETXID are used internally by glibc).

 Changing the behavior of signals in Go programs

 The functions in this package allow a program to change the way Go
 programs handle signals.

 Notify disables the default behavior for a given set of asynchronous
 signals and instead delivers them over one or more registered
 channels. Specifically, it applies to the signals SIGHUP, SIGINT,
 SIGQUIT, SIGABRT, and SIGTERM. It also applies to the job control
 signals SIGTSTP, SIGTTIN, and SIGTTOU, in which case the system
 default behavior does not occur. It also applies to some signals that
 are otherwise ignored: SIGUSR1, SIGUSR2, SIGPIPE, SIGALRM, SIGCHLD,
 SIGURG, SIGXCPU, SIGXFSZ, SIGVTALRM, SIGWINCH, SIGIO, SIGPWR, SIGSYS,
 SIGINFO, SIGTHR, SIGWAITING, SIGLWP, SIGFREEZE, SIGTHAW, SIGLOST,
 SIGXRES, SIGJVM1, SIGJVM2, and any real time signals used on the
 system. Note that not all of these signals are available on all
 systems.

 If the program was started with SIGHUP or SIGINT ignored, and Notify
 is called for either signal, a signal handler will be installed for
 that signal and it will no longer be ignored. If, later, Reset or
 Ignore is called for that signal, or Stop is called on all channels
 passed to Notify for that signal, the signal will once again be
 ignored. Reset will restore the system default behavior for the
 signal, while Ignore will cause the system to ignore the signal
 entirely.

 If the program is started with a non-empty signal mask, some signals
 will be explicitly unblocked as described above. If Notify is called
 for a blocked signal, it will be unblocked. If, later, Reset is
 called for that signal, or Stop is called on all channels passed to
 Notify for that signal, the signal will once again be blocked.

 Go programs that use cgo or SWIG

 In a Go program that includes non-Go code, typically C/C++ code
 accessed using cgo or SWIG, Go's startup code normally runs first. It
 configures the signal handlers as expected by the Go runtime, before
 the non-Go startup code runs. If the non-Go startup code wishes to
 install its own signal handlers, it must take certain steps to keep Go
 working well. This section documents those steps and the overall
 effect changes to signal handler settings by the non-Go code can have
 on Go programs. In rare cases, the non-Go code may run before the Go
 code, in which case the next section also applies.

 If the non-Go code called by the Go program does not change any signal
 handlers or masks, then the behavior is the same as for a pure Go
 program.

 If the non-Go code installs any signal handlers, it must use the
 SA_ONSTACK flag with sigaction. Failing to do so is likely to cause
 the program to crash if the signal is received. Go programs routinely
 run with a limited stack, and therefore set up an alternate signal
 stack. Also, the Go standard library expects that any signal handlers
 will use the SA_RESTART flag. Failing to do so may cause some library
 calls to return "interrupted system call" errors.

 If the non-Go code installs a signal handler for any of the
 synchronous signals (SIGBUS, SIGFPE, SIGSEGV), then it should record
 the existing Go signal handler. If those signals occur while
 executing Go code, it should invoke the Go signal handler (whether the
 signal occurs while executing Go code can be determined by looking at
 the PC passed to the signal handler). Otherwise some Go run-time
 panics will not occur as expected.

 If the non-Go code installs a signal handler for any of the
 asynchronous signals, it may invoke the Go signal handler or not as it
 chooses. Naturally, if it does not invoke the Go signal handler, the
 Go behavior described above will not occur. This can be an issue with
 the SIGPROF signal in particular.

 The non-Go code should not change the signal mask on any threads
 created by the Go runtime. If the non-Go code starts new threads of
 its own, it may set the signal mask as it pleases.

 If the non-Go code starts a new thread, changes the signal mask, and
 then invokes a Go function in that thread, the Go runtime will
 automatically unblock certain signals: the synchronous signals,
 SIGILL, SIGTRAP, SIGSTKFLT, SIGCHLD, SIGPROF, SIGCANCEL, and
 SIGSETXID. When the Go function returns, the non-Go signal mask will
 be restored.

 If the Go signal handler is invoked on a non-Go thread not running Go
 code, the handler generally forwards the signal to the non-Go code, as
 follows. If the signal is SIGPROF, the Go handler does
 nothing. Otherwise, the Go handler removes itself, unblocks the
 signal, and raises it again, to invoke any non-Go handler or default
 system handler. If the program does not exit, the Go handler then
 reinstalls itself and continues execution of the program.

 Non-Go programs that call Go code

 When Go code is built with options like -buildmode=c-shared, it will
 be run as part of an existing non-Go program. The non-Go code may
 have already installed signal handlers when the Go code starts (that
 may also happen in unusual cases when using cgo or SWIG; in that case,
 the discussion here applies).

 If the Go runtime sees an existing signal handler for the SIGCANCEL or
 SIGSETXID signals (which are used only on GNU/Linux), it will turn on
 the SA_ONSTACK flag and otherwise keep the signal handler.

 For other signals listed above, the Go runtime will install a signal
 handler. It will save any existing signal handler. If a synchronous
 signal arrives while executing non-Go code, the Go runtime will invoke
 the existing signal handler instead of the Go signal handler.

 If a signal is delivered to a non-Go thread, it will act as described
 above, except that if there is an existing non-Go signal handler, that
 handler will be installed before raising the signal.

 Windows

 On Windows a ^C (Control-C) or ^BREAK (Control-Break) normally cause
 the program to exit. If Notify is called for os.SIGINT, ^C or ^BREAK
 will cause os.SIGINT to be sent on the channel, and the program will
 not exit. If Reset is called, or Stop is called on all channels passed
 to Notify, then the default behavior will be restored.

 Plan 9

 On Plan 9, signals have type syscall.Note, which is a string. Calling
 Notify with a syscall.Note will cause that value to be sent on the
 channel when that string is posted as a note.

 */
 package signal
	// Copyright 2015 The Go Authors. All rights reserved.
	// Use of this source code is governed by a BSD-style
	// license that can be found in the LICENSE file.

	/*
	Package signal implements access to incoming signals.

	Signals are primarily used on Unix-like systems. For the use of this
	package on Windows and Plan 9, see below.

	Types of signals

	The signals SIGKILL and SIGSTOP may not be caught by a program, and
	therefore can not be affected by this package.

	Synchronous signals are signals triggered by errors in program
	execution: SIGBUS, SIGFPE, and SIGSEGV. These are only considered
	synchronous when caused by program execution, not when sent using
	os.Process.Kill or the kill program or some similar mechanism. In
	general, except as discussed below, Go programs will convert a
	synchronous signal into a run-time panic.

	The remaining signals are asynchronous signals. They are not
	triggered by program errors, but are instead sent from the kernel or
	from some other program.

	Of the asynchronous signals, the SIGHUP signal is sent when a program
	loses its controlling terminal. The SIGINT signal is sent when the
	user at the controlling terminal presses the interrupt character,
	which by default is ^C (Control-C). The SIGQUIT signal is sent when
	the user at the controlling terminal presses the quit character, which
	by default is ^\ (Control-Backslash). In general you can cause a
	program to simply exit by pressing ^C, and you can cause it to exit
	with a stack dump by pressing ^\.

	Default behavior of signals in Go programs

	By default, a synchronous signal is converted into a run-time panic. A
	SIGHUP, SIGINT, or SIGTERM signal causes the program to exit. A
	SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGSTKFLT, SIGEMT, or SIGSYS signal
	causes the program to exit with a stack dump. A SIGTSTP, SIGTTIN, or
	SIGTTOU signal gets the system default behavior (these signals are
	used by the shell for job control). The SIGPROF signal is handled
	directly by the Go runtime to implement runtime.CPUProfile. Other
	signals are ignored.

	If the Go program is started with either SIGHUP or SIGINT ignored,
	they will remain ignored. Go always registers a handler for the other
	signals.

	If the Go program is started with a non-empty signal mask, that will
	generally be honored. However, some signals are explicitly unblocked:
	the synchronous signals, SIGILL, SIGTRAP, SIGSTKFLT, SIGCHLD, SIGPROF,
	and, on GNU/Linux, signals 32 (SIGCANCEL) and 33 (SIGSETXID)
	(SIGCANCEL and SIGSETXID are used internally by glibc).

	Changing the behavior of signals in Go programs

	The functions in this package allow a program to change the way Go
	programs handle signals.

	Notify disables the default behavior for a given set of asynchronous
	signals and instead delivers them over one or more registered
	channels. Specifically, it applies to the signals SIGHUP, SIGINT,
	SIGQUIT, SIGABRT, and SIGTERM. It also applies to the job control
	signals SIGTSTP, SIGTTIN, and SIGTTOU, in which case the system
	default behavior does not occur. It also applies to some signals that
	are otherwise ignored: SIGUSR1, SIGUSR2, SIGPIPE, SIGALRM, SIGCHLD,
	SIGURG, SIGXCPU, SIGXFSZ, SIGVTALRM, SIGWINCH, SIGIO, SIGPWR, SIGSYS,
	SIGINFO, SIGTHR, SIGWAITING, SIGLWP, SIGFREEZE, SIGTHAW, SIGLOST,
	SIGXRES, SIGJVM1, SIGJVM2, and any real time signals used on the
	system. Note that not all of these signals are available on all
	systems.

	If the program was started with SIGHUP or SIGINT ignored, and Notify
	is called for either signal, a signal handler will be installed for
	that signal and it will no longer be ignored. If, later, Reset or
	Ignore is called for that signal, or Stop is called on all channels
	passed to Notify for that signal, the signal will once again be
	ignored. Reset will restore the system default behavior for the
	signal, while Ignore will cause the system to ignore the signal
	entirely.

	If the program is started with a non-empty signal mask, some signals
	will be explicitly unblocked as described above. If Notify is called
	for a blocked signal, it will be unblocked. If, later, Reset is
	called for that signal, or Stop is called on all channels passed to
	Notify for that signal, the signal will once again be blocked.

	Go programs that use cgo or SWIG

	In a Go program that includes non-Go code, typically C/C++ code
	accessed using cgo or SWIG, Go's startup code normally runs first. It
	configures the signal handlers as expected by the Go runtime, before
	the non-Go startup code runs. If the non-Go startup code wishes to
	install its own signal handlers, it must take certain steps to keep Go
	working well. This section documents those steps and the overall
	effect changes to signal handler settings by the non-Go code can have
	on Go programs. In rare cases, the non-Go code may run before the Go
	code, in which case the next section also applies.

	If the non-Go code called by the Go program does not change any signal
	handlers or masks, then the behavior is the same as for a pure Go
	program.

	If the non-Go code installs any signal handlers, it must use the
	SA_ONSTACK flag with sigaction. Failing to do so is likely to cause
	the program to crash if the signal is received. Go programs routinely
	run with a limited stack, and therefore set up an alternate signal
	stack. Also, the Go standard library expects that any signal handlers
	will use the SA_RESTART flag. Failing to do so may cause some library
	calls to return "interrupted system call" errors.

	If the non-Go code installs a signal handler for any of the
	synchronous signals (SIGBUS, SIGFPE, SIGSEGV), then it should record
	the existing Go signal handler. If those signals occur while
	executing Go code, it should invoke the Go signal handler (whether the
	signal occurs while executing Go code can be determined by looking at
	the PC passed to the signal handler). Otherwise some Go run-time
	panics will not occur as expected.

	If the non-Go code installs a signal handler for any of the
	asynchronous signals, it may invoke the Go signal handler or not as it
	chooses. Naturally, if it does not invoke the Go signal handler, the
	Go behavior described above will not occur. This can be an issue with
	the SIGPROF signal in particular.

	The non-Go code should not change the signal mask on any threads
	created by the Go runtime. If the non-Go code starts new threads of
	its own, it may set the signal mask as it pleases.

	If the non-Go code starts a new thread, changes the signal mask, and
	then invokes a Go function in that thread, the Go runtime will
	automatically unblock certain signals: the synchronous signals,
	SIGILL, SIGTRAP, SIGSTKFLT, SIGCHLD, SIGPROF, SIGCANCEL, and
	SIGSETXID. When the Go function returns, the non-Go signal mask will
	be restored.

	If the Go signal handler is invoked on a non-Go thread not running Go
	code, the handler generally forwards the signal to the non-Go code, as
	follows. If the signal is SIGPROF, the Go handler does
	nothing. Otherwise, the Go handler removes itself, unblocks the
	signal, and raises it again, to invoke any non-Go handler or default
	system handler. If the program does not exit, the Go handler then
	reinstalls itself and continues execution of the program.

	Non-Go programs that call Go code

	When Go code is built with options like -buildmode=c-shared, it will
	be run as part of an existing non-Go program. The non-Go code may
	have already installed signal handlers when the Go code starts (that
	may also happen in unusual cases when using cgo or SWIG; in that case,
	the discussion here applies).

	If the Go runtime sees an existing signal handler for the SIGCANCEL or
	SIGSETXID signals (which are used only on GNU/Linux), it will turn on
	the SA_ONSTACK flag and otherwise keep the signal handler.

	For other signals listed above, the Go runtime will install a signal
	handler. It will save any existing signal handler. If a synchronous
	signal arrives while executing non-Go code, the Go runtime will invoke
	the existing signal handler instead of the Go signal handler.

	If a signal is delivered to a non-Go thread, it will act as described
	above, except that if there is an existing non-Go signal handler, that
	handler will be installed before raising the signal.

	Windows

	On Windows a ^C (Control-C) or ^BREAK (Control-Break) normally cause
	the program to exit. If Notify is called for os.SIGINT, ^C or ^BREAK
	will cause os.SIGINT to be sent on the channel, and the program will
	not exit. If Reset is called, or Stop is called on all channels passed
	to Notify, then the default behavior will be restored.

	Plan 9

	On Plan 9, signals have type syscall.Note, which is a string. Calling
	Notify with a syscall.Note will cause that value to be sent on the
	channel when that string is posted as a note.

	*/
	package signal