go-neb/pkg/os/signal/index.html

<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#375EAB">

  <title>signal - The Go Programming Language</title>

<link type="text/css" rel="stylesheet" href="../../../lib/godoc/style.css">

<link rel="stylesheet" href="../../../lib/godoc/jquery.treeview.css">
<script type="text/javascript">window.initFuncs = [];</script>
</head>
<body>

<div id='lowframe' style="position: fixed; bottom: 0; left: 0; height: 0; width: 100%; border-top: thin solid grey; background-color: white; overflow: auto;">
...
</div><!-- #lowframe -->

<div id="topbar" class="wide"><div class="container">
<div class="top-heading" id="heading-wide"><a href="http://localhost:6060/">The Go Programming Language</a></div>
<div class="top-heading" id="heading-narrow"><a href="http://localhost:6060/">Go</a></div>
<a href="index.html#" id="menu-button"><span id="menu-button-arrow">&#9661;</span></a>
<form method="GET" action="http://localhost:6060/search">
<div id="menu">
<a href="http://localhost:6060/doc/">Documents</a>
<a href="http://localhost:6060/pkg/">Packages</a>
<a href="http://localhost:6060/project/">The Project</a>
<a href="http://localhost:6060/help/">Help</a>
<a href="http://localhost:6060/blog/">Blog</a>

<input type="text" id="search" name="q" class="inactive" value="Search" placeholder="Search">
</div>
</form>

</div></div>


<div id="page" class="wide">
<div class="container">


  <h1>Package signal</h1>


<div id="nav"></div>


<!--
	Copyright 2009 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.
-->
<!--
	Note: Static (i.e., not template-generated) href and id
	attributes start with "pkg-" to make it impossible for
	them to conflict with generated attributes (some of which
	correspond to Go identifiers).
-->

	<script type='text/javascript'>
	document.ANALYSIS_DATA = null;
	document.CALLGRAPH = null;
	</script>

	
		<div id="short-nav">
			<dl>
			<dd><code>import "os/signal"</code></dd>
			</dl>
			<dl>
			<dd><a href="index.html#pkg-overview" class="overviewLink">Overview</a></dd>
			<dd><a href="index.html#pkg-index" class="indexLink">Index</a></dd>
			
				<dd><a href="index.html#pkg-examples" class="examplesLink">Examples</a></dd>
			
			
			</dl>
		</div>
		<!-- The package's Name is printed as title by the top-level template -->
		<div id="pkg-overview" class="toggleVisible">
			<div class="collapsed">
				<h2 class="toggleButton" title="Click to show Overview section">Overview ▹</h2>
			</div>
			<div class="expanded">
				<h2 class="toggleButton" title="Click to hide Overview section">Overview ▾</h2>
				<p>
Package signal implements access to incoming signals.
</p>
<p>
Signals are primarily used on Unix-like systems. For the use of this
package on Windows and Plan 9, see below.
</p>
<h3 id="hdr-Types_of_signals">Types of signals</h3>
<p>
The signals SIGKILL and SIGSTOP may not be caught by a program, and
therefore can not be affected by this package.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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 ^\.
</p>
<h3 id="hdr-Default_behavior_of_signals_in_Go_programs">Default behavior of signals in Go programs</h3>
<p>
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 will be caught but no action will be taken.
</p>
<p>
If the Go program is started with either SIGHUP or SIGINT ignored
(signal handler set to SIG_IGN), they will remain ignored.
</p>
<p>
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). Subprocesses
started by os.Exec, or by the os/exec package, will inherit the
modified signal mask.
</p>
<h3 id="hdr-Changing_the_behavior_of_signals_in_Go_programs">Changing the behavior of signals in Go programs</h3>
<p>
The functions in this package allow a program to change the way Go
programs handle signals.
</p>
<p>
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
otherwise cause no action: SIGUSR1, SIGUSR2, SIGPIPE, SIGALRM,
SIGCHLD, SIGCONT, 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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<h3 id="hdr-SIGPIPE">SIGPIPE</h3>
<p>
When a Go program writes to a broken pipe, the kernel will raise a
SIGPIPE signal.
</p>
<p>
If the program has not called Notify to receive SIGPIPE signals, then
the behavior depends on the file descriptor number. A write to a
broken pipe on file descriptors 1 or 2 (standard output or standard
error) will cause the program to exit with a SIGPIPE signal. A write
to a broken pipe on some other file descriptor will take no action on
the SIGPIPE signal, and the write will fail with an EPIPE error.
</p>
<p>
If the program has called Notify to receive SIGPIPE signals, the file
descriptor number does not matter. The SIGPIPE signal will be
delivered to the Notify channel, and the write will fail with an EPIPE
error.
</p>
<p>
This means that, by default, command line programs will behave like
typical Unix command line programs, while other programs will not
crash with SIGPIPE when writing to a closed network connection.
</p>
<h3 id="hdr-Go_programs_that_use_cgo_or_SWIG">Go programs that use cgo or SWIG</h3>
<p>
In a Go program that includes non-Go code, typically C/C++ code
accessed using cgo or SWIG, Go&#39;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.
</p>
<p>
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.
</p>
<p>
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 &#34;interrupted system call&#34; errors.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<p>
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.
</p>
<h3 id="hdr-Non_Go_programs_that_call_Go_code">Non-Go programs that call Go code</h3>
<p>
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).  For -buildmode=c-archive the Go runtime
will initialize signals at global constructor time.  For
-buildmode=c-shared the Go runtime will initialize signals when the
shared library is loaded.
</p>
<p>
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.
</p>
<p>
For the synchronous signals, 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.
</p>
<p>
Go code built with -buildmode=c-archive or -buildmode=c-shared will
not install any other signal handlers by default. If there is an
existing signal handler, the Go runtime will turn on the SA_ONSTACK
flag and otherwise keep the signal handler. If Notify is called for an
asynchronous signal, a Go signal handler will be installed for that
signal. If, later, Reset is called for that signal, the original
handling for that signal will be reinstalled, restoring the non-Go
signal handler if any.
</p>
<p>
Go code built without -buildmode=c-archive or -buildmode=c-shared will
install a signal handler for the asynchronous signals listed above,
and save any existing 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.
</p>
<h3 id="hdr-Windows">Windows</h3>
<p>
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.
</p>
<h3 id="hdr-Plan_9">Plan 9</h3>
<p>
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.
</p>

			</div>
		</div>
		

		<div id="pkg-index" class="toggleVisible">
		<div class="collapsed">
			<h2 class="toggleButton" title="Click to show Index section">Index ▹</h2>
		</div>
		<div class="expanded">
			<h2 class="toggleButton" title="Click to hide Index section">Index ▾</h2>

		<!-- Table of contents for API; must be named manual-nav to turn off auto nav. -->
			<div id="manual-nav">
			<dl>
			
			
				<dd><a href="index.html#Ignore">func Ignore(sig ...os.Signal)</a></dd>
			
				
				<dd><a href="index.html#Notify">func Notify(c chan&lt;- os.Signal, sig ...os.Signal)</a></dd>
			
				
				<dd><a href="index.html#Reset">func Reset(sig ...os.Signal)</a></dd>
			
				
				<dd><a href="index.html#Stop">func Stop(c chan&lt;- os.Signal)</a></dd>
			
			
			</dl>
			</div><!-- #manual-nav -->

		
		<div id="pkg-examples">
			<h4>Examples</h4>
			<dl>
			
			<dd><a class="exampleLink" href="index.html#example_Notify">Notify</a></dd>
			
			</dl>
		</div>
		

			<h4>Package files</h4>
			<p>
			<span style="font-size:90%">
			
				<a href="http://localhost:6060/src/os/signal/doc.go">doc.go</a>
			
				<a href="http://localhost:6060/src/os/signal/signal.go">signal.go</a>
			
				<a href="http://localhost:6060/src/os/signal/signal_unix.go">signal_unix.go</a>
			
			</span>
			</p>
		
		</div><!-- .expanded -->
		</div><!-- #pkg-index -->

		<div id="pkg-callgraph" class="toggle" style="display: none">
		<div class="collapsed">
			<h2 class="toggleButton" title="Click to show Internal Call Graph section">Internal call graph ▹</h2>
		</div> <!-- .expanded -->
		<div class="expanded">
			<h2 class="toggleButton" title="Click to hide Internal Call Graph section">Internal call graph ▾</h2>
			<p>
			  In the call graph viewer below, each node
			  is a function belonging to this package
			  and its children are the functions it
			  calls&mdash;perhaps dynamically.
			</p>
			<p>
			  The root nodes are the entry points of the
			  package: functions that may be called from
			  outside the package.
			  There may be non-exported or anonymous
			  functions among them if they are called
			  dynamically from another package.
			</p>
			<p>
			  Click a node to visit that function's source code.
			  From there you can visit its callers by
			  clicking its declaring <code>func</code>
			  token.
			</p>
			<p>
			  Functions may be omitted if they were
			  determined to be unreachable in the
			  particular programs or tests that were
			  analyzed.
			</p>
			<!-- Zero means show all package entry points. -->
			<ul style="margin-left: 0.5in" id="callgraph-0" class="treeview"></ul>
		</div>
		</div> <!-- #pkg-callgraph -->

		
			<h2 id="Ignore">func <a href="http://localhost:6060/src/os/signal/signal.go?s=1546:1575#L62">Ignore</a></h2>
			<pre>func Ignore(sig ...<a href="../index.html">os</a>.<a href="../index.html#Signal">Signal</a>)</pre>
			<p>
Ignore causes the provided signals to be ignored. If they are received by
the program, nothing will happen. Ignore undoes the effect of any prior
calls to Notify for the provided signals.
If no signals are provided, all incoming signals will be ignored.
</p>

			
			<h2 id="Notify">func <a href="http://localhost:6060/src/os/signal/signal.go?s=2413:2462#L82">Notify</a></h2>
			<pre>func Notify(c chan&lt;- <a href="../index.html">os</a>.<a href="../index.html#Signal">Signal</a>, sig ...<a href="../index.html">os</a>.<a href="../index.html#Signal">Signal</a>)</pre>
			<p>
Notify causes package signal to relay incoming signals to c.
If no signals are provided, all incoming signals will be relayed to c.
Otherwise, just the provided signals will.
</p>
<p>
Package signal will not block sending to c: the caller must ensure
that c has sufficient buffer space to keep up with the expected
signal rate.  For a channel used for notification of just one signal value,
a buffer of size 1 is sufficient.
</p>
<p>
It is allowed to call Notify multiple times with the same channel:
each call expands the set of signals sent to that channel.
The only way to remove signals from the set is to call Stop.
</p>
<p>
It is allowed to call Notify multiple times with different channels
and the same signals: each channel receives copies of incoming
signals independently.
</p>

			<div id="example_Notify" class="toggle">
	<div class="collapsed">
		<p class="exampleHeading toggleButton">▹ <span class="text">Example</span></p>
	</div>
	<div class="expanded">
		<p class="exampleHeading toggleButton">▾ <span class="text">Example</span></p>
		
		
			<p>Code:</p>
			<pre class="code">
<span class="comment">// Set up channel on which to send signal notifications.</span>
<span class="comment">// We must use a buffered channel or risk missing the signal</span>
<span class="comment">// if we&#39;re not ready to receive when the signal is sent.</span>
c := make(chan os.Signal, 1)
signal.Notify(c, os.Interrupt)

<span class="comment">// Block until a signal is received.</span>
s := &lt;-c
fmt.Println(&#34;Got signal:&#34;, s)
</pre>
			
		
	</div>
</div>

			
			<h2 id="Reset">func <a href="http://localhost:6060/src/os/signal/signal.go?s=3176:3204#L126">Reset</a></h2>
			<pre>func Reset(sig ...<a href="../index.html">os</a>.<a href="../index.html#Signal">Signal</a>)</pre>
			<p>
Reset undoes the effect of any prior calls to Notify for the provided
signals.
If no signals are provided, all signal handlers will be reset.
</p>

			
			<h2 id="Stop">func <a href="http://localhost:6060/src/os/signal/signal.go?s=3446:3475#L133">Stop</a></h2>
			<pre>func Stop(c chan&lt;- <a href="../index.html">os</a>.<a href="../index.html#Signal">Signal</a>)</pre>
			<p>
Stop causes package signal to stop relaying incoming signals to c.
It undoes the effect of all prior calls to Notify using c.
When Stop returns, it is guaranteed that c will receive no more signals.
</p>

			
<div id="footer">
Build version go1.6.<br>
Except as <a href="https://developers.google.com/site-policies#restrictions">noted</a>,
the content of this page is licensed under the
Creative Commons Attribution 3.0 License,
and code is licensed under a <a href="http://localhost:6060/LICENSE">BSD license</a>.<br>
<a href="http://localhost:6060/doc/tos.html">Terms of Service</a> | 
<a href="http://www.google.com/intl/en/policies/privacy/">Privacy Policy</a>
</div>

</div><!-- .container -->
</div><!-- #page -->

<!-- TODO(adonovan): load these from <head> using "defer" attribute? -->
<script type="text/javascript" src="../../../lib/godoc/jquery.js"></script>
<script type="text/javascript" src="../../../lib/godoc/jquery.treeview.js"></script>
<script type="text/javascript" src="../../../lib/godoc/jquery.treeview.edit.js"></script>


<script type="text/javascript" src="../../../lib/godoc/godocs.js"></script>

</body>
</html>