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 Linux, signals 32 (SIGCANCEL) and 33 (SIGSETXID)
    54  (SIGCANCEL and SIGSETXID are used internally by glibc). Subprocesses
    55  started by [os.Exec], or by [os/exec], 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, 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 a [syscall.EPIPE]
   102  error.
   103  
   104  If the program has called Notify to receive SIGPIPE signals, the file
   105  descriptor number does not matter. The SIGPIPE signal will be
   106  delivered to the Notify channel, and the write will fail with a
   107  [syscall.EPIPE] error.
   108  
   109  This means that, by default, command line programs will behave like
   110  typical Unix command line programs, while other programs will not
   111  crash with SIGPIPE when writing to a closed network connection.
   112  
   113  # Go programs that use cgo or SWIG
   114  
   115  In a Go program that includes non-Go code, typically C/C++ code
   116  accessed using cgo or SWIG, Go's startup code normally runs first. It
   117  configures the signal handlers as expected by the Go runtime, before
   118  the non-Go startup code runs. If the non-Go startup code wishes to
   119  install its own signal handlers, it must take certain steps to keep Go
   120  working well. This section documents those steps and the overall
   121  effect changes to signal handler settings by the non-Go code can have
   122  on Go programs. In rare cases, the non-Go code may run before the Go
   123  code, in which case the next section also applies.
   124  
   125  If the non-Go code called by the Go program does not change any signal
   126  handlers or masks, then the behavior is the same as for a pure Go
   127  program.
   128  
   129  If the non-Go code installs any signal handlers, it must use the
   130  SA_ONSTACK flag with sigaction. Failing to do so is likely to cause
   131  the program to crash if the signal is received. Go programs routinely
   132  run with a limited stack, and therefore set up an alternate signal
   133  stack.
   134  
   135  If the non-Go code installs a signal handler for any of the
   136  synchronous signals (SIGBUS, SIGFPE, SIGSEGV), then it should record
   137  the existing Go signal handler. If those signals occur while
   138  executing Go code, it should invoke the Go signal handler (whether the
   139  signal occurs while executing Go code can be determined by looking at
   140  the PC passed to the signal handler). Otherwise some Go run-time
   141  panics will not occur as expected.
   142  
   143  If the non-Go code installs a signal handler for any of the
   144  asynchronous signals, it may invoke the Go signal handler or not as it
   145  chooses. Naturally, if it does not invoke the Go signal handler, the
   146  Go behavior described above will not occur. This can be an issue with
   147  the SIGPROF signal in particular.
   148  
   149  The non-Go code should not change the signal mask on any threads
   150  created by the Go runtime. If the non-Go code starts new threads
   151  itself, those threads may set the signal mask as they please.
   152  
   153  If the non-Go code starts a new thread, changes the signal mask, and
   154  then invokes a Go function in that thread, the Go runtime will
   155  automatically unblock certain signals: the synchronous signals,
   156  SIGILL, SIGTRAP, SIGSTKFLT, SIGCHLD, SIGPROF, SIGCANCEL, and
   157  SIGSETXID. When the Go function returns, the non-Go signal mask will
   158  be restored.
   159  
   160  If the Go signal handler is invoked on a non-Go thread not running Go
   161  code, the handler generally forwards the signal to the non-Go code, as
   162  follows. If the signal is SIGPROF, the Go handler does
   163  nothing. Otherwise, the Go handler removes itself, unblocks the
   164  signal, and raises it again, to invoke any non-Go handler or default
   165  system handler. If the program does not exit, the Go handler then
   166  reinstalls itself and continues execution of the program.
   167  
   168  If a SIGPIPE signal is received, the Go program will invoke the
   169  special handling described above if the SIGPIPE is received on a Go
   170  thread.  If the SIGPIPE is received on a non-Go thread the signal will
   171  be forwarded to the non-Go handler, if any; if there is none the
   172  default system handler will cause the program to terminate.
   173  
   174  # Non-Go programs that call Go code
   175  
   176  When Go code is built with options like -buildmode=c-shared, it will
   177  be run as part of an existing non-Go program. The non-Go code may
   178  have already installed signal handlers when the Go code starts (that
   179  may also happen in unusual cases when using cgo or SWIG; in that case,
   180  the discussion here applies).  For -buildmode=c-archive the Go runtime
   181  will initialize signals at global constructor time.  For
   182  -buildmode=c-shared the Go runtime will initialize signals when the
   183  shared library is loaded.
   184  
   185  If the Go runtime sees an existing signal handler for the SIGCANCEL or
   186  SIGSETXID signals (which are used only on Linux), it will turn on
   187  the SA_ONSTACK flag and otherwise keep the signal handler.
   188  
   189  For the synchronous signals and SIGPIPE, the Go runtime will install a
   190  signal handler. It will save any existing signal handler. If a
   191  synchronous signal arrives while executing non-Go code, the Go runtime
   192  will invoke the existing signal handler instead of the Go signal
   193  handler.
   194  
   195  Go code built with -buildmode=c-archive or -buildmode=c-shared will
   196  not install any other signal handlers by default. If there is an
   197  existing signal handler, the Go runtime will turn on the SA_ONSTACK
   198  flag and otherwise keep the signal handler. If Notify is called for an
   199  asynchronous signal, a Go signal handler will be installed for that
   200  signal. If, later, Reset is called for that signal, the original
   201  handling for that signal will be reinstalled, restoring the non-Go
   202  signal handler if any.
   203  
   204  Go code built without -buildmode=c-archive or -buildmode=c-shared will
   205  install a signal handler for the asynchronous signals listed above,
   206  and save any existing signal handler. If a signal is delivered to a
   207  non-Go thread, it will act as described above, except that if there is
   208  an existing non-Go signal handler, that handler will be installed
   209  before raising the signal.
   210  
   211  # Windows
   212  
   213  On Windows a ^C (Control-C) or ^BREAK (Control-Break) normally cause
   214  the program to exit. If Notify is called for [os.Interrupt], ^C or ^BREAK
   215  will cause [os.Interrupt] to be sent on the channel, and the program will
   216  not exit. If Reset is called, or Stop is called on all channels passed
   217  to Notify, then the default behavior will be restored.
   218  
   219  Additionally, if Notify is called, and Windows sends CTRL_CLOSE_EVENT,
   220  CTRL_LOGOFF_EVENT or CTRL_SHUTDOWN_EVENT to the process, Notify will
   221  return syscall.SIGTERM. Unlike Control-C and Control-Break, Notify does
   222  not change process behavior when either CTRL_CLOSE_EVENT,
   223  CTRL_LOGOFF_EVENT or CTRL_SHUTDOWN_EVENT is received - the process will
   224  still get terminated unless it exits. But receiving syscall.SIGTERM will
   225  give the process an opportunity to clean up before termination.
   226  
   227  # Plan 9
   228  
   229  On Plan 9, signals have type syscall.Note, which is a string. Calling
   230  Notify with a syscall.Note will cause that value to be sent on the
   231  channel when that string is posted as a note.
   232  */
   233  package signal
   234
View as plain text