libgo/go/os/signal/doc.go

   1 // Copyright 2015 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 /*
   6 Package signal implements access to incoming signals.
   7
   8 Signals are primarily used on Unix-like systems. For the use of this
   9 package on Windows and Plan 9, see below.
  10
  11 Types of signals
  12
  13 The signals SIGKILL and SIGSTOP may not be caught by a program, and
  14 therefore cannot be affected by this package.
  15
  16 Synchronous signals are signals triggered by errors in program
  17 execution: SIGBUS, SIGFPE, and SIGSEGV. These are only considered
  18 synchronous when caused by program execution, not when sent using
  19 os.Process.Kill or the kill program or some similar mechanism. In
  20 general, except as discussed below, Go programs will convert a
  21 synchronous signal into a run-time panic.
  22
  23 The remaining signals are asynchronous signals. They are not
  24 triggered by program errors, but are instead sent from the kernel or
  25 from some other program.
  26
  27 Of the asynchronous signals, the SIGHUP signal is sent when a program
  28 loses its controlling terminal. The SIGINT signal is sent when the
  29 user at the controlling terminal presses the interrupt character,
  30 which by default is ^C (Control-C). The SIGQUIT signal is sent when
  31 the user at the controlling terminal presses the quit character, which
  32 by default is ^\ (Control-Backslash). In general you can cause a
  33 program to simply exit by pressing ^C, and you can cause it to exit
  34 with a stack dump by pressing ^\.
  35
  36 Default behavior of signals in Go programs
  37
  38 By default, a synchronous signal is converted into a run-time panic. A
  39 SIGHUP, SIGINT, or SIGTERM signal causes the program to exit. A
  40 SIGQUIT, SIGILL, SIGTRAP, SIGABRT, SIGSTKFLT, SIGEMT, or SIGSYS signal
  41 causes the program to exit with a stack dump. A SIGTSTP, SIGTTIN, or
  42 SIGTTOU signal gets the system default behavior (these signals are
  43 used by the shell for job control). The SIGPROF signal is handled
  44 directly by the Go runtime to implement runtime.CPUProfile. Other
  45 signals will be caught but no action will be taken.
  46
  47 If the Go program is started with either SIGHUP or SIGINT ignored
  48 (signal handler set to SIG_IGN), they will remain ignored.
  49
  50 If the Go program is started with a non-empty signal mask, that will
  51 generally be honored. However, some signals are explicitly unblocked:
  52 the synchronous signals, SIGILL, SIGTRAP, SIGSTKFLT, SIGCHLD, SIGPROF,
  53 and, on GNU/Linux, signals 32 (SIGCANCEL) and 33 (SIGSETXID)
  54 (SIGCANCEL and SIGSETXID are used internally by glibc). Subprocesses
  55 started by os.Exec, or by the os/exec package, will inherit the
  56 modified signal mask.
  57
  58 Changing the behavior of signals in Go programs
  59
  60 The functions in this package allow a program to change the way Go
  61 programs handle signals.
  62
  63 Notify disables the default behavior for a given set of asynchronous
  64 signals and instead delivers them over one or more registered
  65 channels. Specifically, it applies to the signals SIGHUP, SIGINT,
  66 SIGQUIT, SIGABRT, and SIGTERM. It also applies to the job control
  67 signals SIGTSTP, SIGTTIN, and SIGTTOU, in which case the system
  68 default behavior does not occur. It also applies to some signals that
  69 otherwise cause no action: SIGUSR1, SIGUSR2, SIGPIPE, SIGALRM,
  70 SIGCHLD, SIGCONT, SIGURG, SIGXCPU, SIGXFSZ, SIGVTALRM, SIGWINCH,
  71 SIGIO, SIGPWR, SIGSYS, SIGINFO, SIGTHR, SIGWAITING, SIGLWP, SIGFREEZE,
  72 SIGTHAW, SIGLOST, SIGXRES, SIGJVM1, SIGJVM2, and any real time signals
  73 used on the system. Note that not all of these signals are available
  74 on all systems.
  75
  76 If the program was started with SIGHUP or SIGINT ignored, and Notify
  77 is called for either signal, a signal handler will be installed for
  78 that signal and it will no longer be ignored. If, later, Reset or
  79 Ignore is called for that signal, or Stop is called on all channels
  80 passed to Notify for that signal, the signal will once again be
  81 ignored. Reset will restore the system default behavior for the
  82 signal, while Ignore will cause the system to ignore the signal
  83 entirely.
  84
  85 If the program is started with a non-empty signal mask, some signals
  86 will be explicitly unblocked as described above. If Notify is called
  87 for a blocked signal, it will be unblocked. If, later, Reset is
  88 called for that signal, or Stop is called on all channels passed to
  89 Notify for that signal, the signal will once again be blocked.
  90
  91 SIGPIPE
  92
  93 When a Go program writes to a broken pipe, the kernel will raise a
  94 SIGPIPE signal.
  95
  96 If the program has not called Notify to receive SIGPIPE signals, then
  97 the behavior depends on the file descriptor number. A write to a
  98 broken pipe on file descriptors 1 or 2 (standard output or standard
  99 error) will cause the program to exit with a SIGPIPE signal. A write
 100 to a broken pipe on some other file descriptor will take no action on
 101 the SIGPIPE signal, and the write will fail with an EPIPE error.
 102
 103 If the program has called Notify to receive SIGPIPE signals, the file
 104 descriptor number does not matter. The SIGPIPE signal will be
 105 delivered to the Notify channel, and the write will fail with an EPIPE
 106 error.
 107
 108 This means that, by default, command line programs will behave like
 109 typical Unix command line programs, while other programs will not
 110 crash with SIGPIPE when writing to a closed network connection.
 111
 112 Go programs that use cgo or SWIG
 113
 114 In a Go program that includes non-Go code, typically C/C++ code
 115 accessed using cgo or SWIG, Go's startup code normally runs first. It
 116 configures the signal handlers as expected by the Go runtime, before
 117 the non-Go startup code runs. If the non-Go startup code wishes to
 118 install its own signal handlers, it must take certain steps to keep Go
 119 working well. This section documents those steps and the overall
 120 effect changes to signal handler settings by the non-Go code can have
 121 on Go programs. In rare cases, the non-Go code may run before the Go
 122 code, in which case the next section also applies.
 123
 124 If the non-Go code called by the Go program does not change any signal
 125 handlers or masks, then the behavior is the same as for a pure Go
 126 program.
 127
 128 If the non-Go code installs any signal handlers, it must use the
 129 SA_ONSTACK flag with sigaction. Failing to do so is likely to cause
 130 the program to crash if the signal is received. Go programs routinely
 131 run with a limited stack, and therefore set up an alternate signal
 132 stack. Also, the Go standard library expects that any signal handlers
 133 will use the SA_RESTART flag. Failing to do so may cause some library
 134 calls to return "interrupted system call" errors.
 135
 136 If the non-Go code installs a signal handler for any of the
 137 synchronous signals (SIGBUS, SIGFPE, SIGSEGV), then it should record
 138 the existing Go signal handler. If those signals occur while
 139 executing Go code, it should invoke the Go signal handler (whether the
 140 signal occurs while executing Go code can be determined by looking at
 141 the PC passed to the signal handler). Otherwise some Go run-time
 142 panics will not occur as expected.
 143
 144 If the non-Go code installs a signal handler for any of the
 145 asynchronous signals, it may invoke the Go signal handler or not as it
 146 chooses. Naturally, if it does not invoke the Go signal handler, the
 147 Go behavior described above will not occur. This can be an issue with
 148 the SIGPROF signal in particular.
 149
 150 The non-Go code should not change the signal mask on any threads
 151 created by the Go runtime. If the non-Go code starts new threads of
 152 its own, it may set the signal mask as it pleases.
 153
 154 If the non-Go code starts a new thread, changes the signal mask, and
 155 then invokes a Go function in that thread, the Go runtime will
 156 automatically unblock certain signals: the synchronous signals,
 157 SIGILL, SIGTRAP, SIGSTKFLT, SIGCHLD, SIGPROF, SIGCANCEL, and
 158 SIGSETXID. When the Go function returns, the non-Go signal mask will
 159 be restored.
 160
 161 If the Go signal handler is invoked on a non-Go thread not running Go
 162 code, the handler generally forwards the signal to the non-Go code, as
 163 follows. If the signal is SIGPROF, the Go handler does
 164 nothing. Otherwise, the Go handler removes itself, unblocks the
 165 signal, and raises it again, to invoke any non-Go handler or default
 166 system handler. If the program does not exit, the Go handler then
 167 reinstalls itself and continues execution of the program.
 168
 169 Non-Go programs that call Go code
 170
 171 When Go code is built with options like -buildmode=c-shared, it will
 172 be run as part of an existing non-Go program. The non-Go code may
 173 have already installed signal handlers when the Go code starts (that
 174 may also happen in unusual cases when using cgo or SWIG; in that case,
 175 the discussion here applies).  For -buildmode=c-archive the Go runtime
 176 will initialize signals at global constructor time.  For
 177 -buildmode=c-shared the Go runtime will initialize signals when the
 178 shared library is loaded.
 179
 180 If the Go runtime sees an existing signal handler for the SIGCANCEL or
 181 SIGSETXID signals (which are used only on GNU/Linux), it will turn on
 182 the SA_ONSTACK flag and otherwise keep the signal handler.
 183
 184 For the synchronous signals and SIGPIPE, the Go runtime will install a
 185 signal handler. It will save any existing signal handler. If a
 186 synchronous signal arrives while executing non-Go code, the Go runtime
 187 will invoke the existing signal handler instead of the Go signal
 188 handler.
 189
 190 Go code built with -buildmode=c-archive or -buildmode=c-shared will
 191 not install any other signal handlers by default. If there is an
 192 existing signal handler, the Go runtime will turn on the SA_ONSTACK
 193 flag and otherwise keep the signal handler. If Notify is called for an
 194 asynchronous signal, a Go signal handler will be installed for that
 195 signal. If, later, Reset is called for that signal, the original
 196 handling for that signal will be reinstalled, restoring the non-Go
 197 signal handler if any.
 198
 199 Go code built without -buildmode=c-archive or -buildmode=c-shared will
 200 install a signal handler for the asynchronous signals listed above,
 201 and save any existing signal handler. If a signal is delivered to a
 202 non-Go thread, it will act as described above, except that if there is
 203 an existing non-Go signal handler, that handler will be installed
 204 before raising the signal.
 205
 206 Windows
 207
 208 On Windows a ^C (Control-C) or ^BREAK (Control-Break) normally cause
 209 the program to exit. If Notify is called for os.Interrupt, ^C or ^BREAK
 210 will cause os.Interrupt to be sent on the channel, and the program will
 211 not exit. If Reset is called, or Stop is called on all channels passed
 212 to Notify, then the default behavior will be restored.
 213
 214 Plan 9
 215
 216 On Plan 9, signals have type syscall.Note, which is a string. Calling
 217 Notify with a syscall.Note will cause that value to be sent on the
 218 channel when that string is posted as a note.
 219
 220 */
 221 package signal