1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<!-- Copyright (C) 1988-2021 Free Software Foundation, Inc. 4 5Permission is granted to copy, distribute and/or modify this document 6under the terms of the GNU Free Documentation License, Version 1.3 or 7any later version published by the Free Software Foundation; with the 8Invariant Sections being "Free Software" and "Free Software Needs 9Free Documentation", with the Front-Cover Texts being "A GNU Manual," 10and with the Back-Cover Texts as in (a) below. 11 12(a) The FSF's Back-Cover Text is: "You are free to copy and modify 13this GNU Manual. Buying copies from GNU Press supports the FSF in 14developing GNU and promoting software freedom." --> 15<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> 16<head> 17<title>Debugging with GDB: Signals</title> 18 19<meta name="description" content="Debugging with GDB: Signals"> 20<meta name="keywords" content="Debugging with GDB: Signals"> 21<meta name="resource-type" content="document"> 22<meta name="distribution" content="global"> 23<meta name="Generator" content="makeinfo"> 24<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> 25<link href="index.html#Top" rel="start" title="Top"> 26<link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index"> 27<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents"> 28<link href="Stopping.html#Stopping" rel="up" title="Stopping"> 29<link href="Thread-Stops.html#Thread-Stops" rel="next" title="Thread Stops"> 30<link href="Skipping-Over-Functions-and-Files.html#Skipping-Over-Functions-and-Files" rel="previous" title="Skipping Over Functions and Files"> 31<style type="text/css"> 32<!-- 33a.summary-letter {text-decoration: none} 34blockquote.smallquotation {font-size: smaller} 35div.display {margin-left: 3.2em} 36div.example {margin-left: 3.2em} 37div.indentedblock {margin-left: 3.2em} 38div.lisp {margin-left: 3.2em} 39div.smalldisplay {margin-left: 3.2em} 40div.smallexample {margin-left: 3.2em} 41div.smallindentedblock {margin-left: 3.2em; font-size: smaller} 42div.smalllisp {margin-left: 3.2em} 43kbd {font-style:oblique} 44pre.display {font-family: inherit} 45pre.format {font-family: inherit} 46pre.menu-comment {font-family: serif} 47pre.menu-preformatted {font-family: serif} 48pre.smalldisplay {font-family: inherit; font-size: smaller} 49pre.smallexample {font-size: smaller} 50pre.smallformat {font-family: inherit; font-size: smaller} 51pre.smalllisp {font-size: smaller} 52span.nocodebreak {white-space:nowrap} 53span.nolinebreak {white-space:nowrap} 54span.roman {font-family:serif; font-weight:normal} 55span.sansserif {font-family:sans-serif; font-weight:normal} 56ul.no-bullet {list-style: none} 57--> 58</style> 59 60 61</head> 62 63<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> 64<a name="Signals"></a> 65<div class="header"> 66<p> 67Next: <a href="Thread-Stops.html#Thread-Stops" accesskey="n" rel="next">Thread Stops</a>, Previous: <a href="Skipping-Over-Functions-and-Files.html#Skipping-Over-Functions-and-Files" accesskey="p" rel="previous">Skipping Over Functions and Files</a>, Up: <a href="Stopping.html#Stopping" accesskey="u" rel="up">Stopping</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 68</div> 69<hr> 70<a name="Signals-1"></a> 71<h3 class="section">5.4 Signals</h3> 72<a name="index-signals"></a> 73 74<p>A signal is an asynchronous event that can happen in a program. The 75operating system defines the possible kinds of signals, and gives each 76kind a name and a number. For example, in Unix <code>SIGINT</code> is the 77signal a program gets when you type an interrupt character (often <kbd>Ctrl-c</kbd>); 78<code>SIGSEGV</code> is the signal a program gets from referencing a place in 79memory far away from all the areas in use; <code>SIGALRM</code> occurs when 80the alarm clock timer goes off (which happens only if your program has 81requested an alarm). 82</p> 83<a name="index-fatal-signals"></a> 84<p>Some signals, including <code>SIGALRM</code>, are a normal part of the 85functioning of your program. Others, such as <code>SIGSEGV</code>, indicate 86errors; these signals are <em>fatal</em> (they kill your program immediately) if the 87program has not specified in advance some other way to handle the signal. 88<code>SIGINT</code> does not indicate an error in your program, but it is normally 89fatal so it can carry out the purpose of the interrupt: to kill the program. 90</p> 91<p><small>GDB</small> has the ability to detect any occurrence of a signal in your 92program. You can tell <small>GDB</small> in advance what to do for each kind of 93signal. 94</p> 95<a name="index-handling-signals"></a> 96<p>Normally, <small>GDB</small> is set up to let the non-erroneous signals like 97<code>SIGALRM</code> be silently passed to your program 98(so as not to interfere with their role in the program’s functioning) 99but to stop your program immediately whenever an error signal happens. 100You can change these settings with the <code>handle</code> command. 101</p> 102<dl compact="compact"> 103<dd><a name="index-info-signals"></a> 104<a name="index-info-handle"></a> 105</dd> 106<dt><code>info signals</code></dt> 107<dt><code>info handle</code></dt> 108<dd><p>Print a table of all the kinds of signals and how <small>GDB</small> has been told to 109handle each one. You can use this to see the signal numbers of all 110the defined types of signals. 111</p> 112</dd> 113<dt><code>info signals <var>sig</var></code></dt> 114<dd><p>Similar, but print information only about the specified signal number. 115</p> 116<p><code>info handle</code> is an alias for <code>info signals</code>. 117</p> 118</dd> 119<dt><code>catch signal <span class="roman">[</span><var>signal</var>… <span class="roman">|</span> ‘<samp>all</samp>’<span class="roman">]</span></code></dt> 120<dd><p>Set a catchpoint for the indicated signals. See <a href="Set-Catchpoints.html#Set-Catchpoints">Set Catchpoints</a>, 121for details about this command. 122</p> 123<a name="index-handle"></a> 124</dd> 125<dt><code>handle <var>signal</var> <span class="roman">[</span><var>keywords</var>…<span class="roman">]</span></code></dt> 126<dd><p>Change the way <small>GDB</small> handles signal <var>signal</var>. The <var>signal</var> 127can be the number of a signal or its name (with or without the 128‘<samp>SIG</samp>’ at the beginning); a list of signal numbers of the form 129‘<samp><var>low</var>-<var>high</var></samp>’; or the word ‘<samp>all</samp>’, meaning all the 130known signals. Optional arguments <var>keywords</var>, described below, 131say what change to make. 132</p></dd> 133</dl> 134 135<p>The keywords allowed by the <code>handle</code> command can be abbreviated. 136Their full names are: 137</p> 138<dl compact="compact"> 139<dt><code>nostop</code></dt> 140<dd><p><small>GDB</small> should not stop your program when this signal happens. It may 141still print a message telling you that the signal has come in. 142</p> 143</dd> 144<dt><code>stop</code></dt> 145<dd><p><small>GDB</small> should stop your program when this signal happens. This implies 146the <code>print</code> keyword as well. 147</p> 148</dd> 149<dt><code>print</code></dt> 150<dd><p><small>GDB</small> should print a message when this signal happens. 151</p> 152</dd> 153<dt><code>noprint</code></dt> 154<dd><p><small>GDB</small> should not mention the occurrence of the signal at all. This 155implies the <code>nostop</code> keyword as well. 156</p> 157</dd> 158<dt><code>pass</code></dt> 159<dt><code>noignore</code></dt> 160<dd><p><small>GDB</small> should allow your program to see this signal; your program 161can handle the signal, or else it may terminate if the signal is fatal 162and not handled. <code>pass</code> and <code>noignore</code> are synonyms. 163</p> 164</dd> 165<dt><code>nopass</code></dt> 166<dt><code>ignore</code></dt> 167<dd><p><small>GDB</small> should not allow your program to see this signal. 168<code>nopass</code> and <code>ignore</code> are synonyms. 169</p></dd> 170</dl> 171 172<p>When a signal stops your program, the signal is not visible to the 173program until you 174continue. Your program sees the signal then, if <code>pass</code> is in 175effect for the signal in question <em>at that time</em>. In other words, 176after <small>GDB</small> reports a signal, you can use the <code>handle</code> 177command with <code>pass</code> or <code>nopass</code> to control whether your 178program sees that signal when you continue. 179</p> 180<p>The default is set to <code>nostop</code>, <code>noprint</code>, <code>pass</code> for 181non-erroneous signals such as <code>SIGALRM</code>, <code>SIGWINCH</code> and 182<code>SIGCHLD</code>, and to <code>stop</code>, <code>print</code>, <code>pass</code> for the 183erroneous signals. 184</p> 185<p>You can also use the <code>signal</code> command to prevent your program from 186seeing a signal, or cause it to see a signal it normally would not see, 187or to give it any signal at any time. For example, if your program stopped 188due to some sort of memory reference error, you might store correct 189values into the erroneous variables and continue, hoping to see more 190execution; but your program would probably terminate immediately as 191a result of the fatal signal once it saw the signal. To prevent this, 192you can continue with ‘<samp>signal 0</samp>’. See <a href="Signaling.html#Signaling">Giving your 193Program a Signal</a>. 194</p> 195<a name="index-stepping-and-signal-handlers"></a> 196<a name="stepping-and-signal-handlers"></a> 197<p><small>GDB</small> optimizes for stepping the mainline code. If a signal 198that has <code>handle nostop</code> and <code>handle pass</code> set arrives while 199a stepping command (e.g., <code>stepi</code>, <code>step</code>, <code>next</code>) is 200in progress, <small>GDB</small> lets the signal handler run and then resumes 201stepping the mainline code once the signal handler returns. In other 202words, <small>GDB</small> steps over the signal handler. This prevents 203signals that you’ve specified as not interesting (with <code>handle 204nostop</code>) from changing the focus of debugging unexpectedly. Note that 205the signal handler itself may still hit a breakpoint, stop for another 206signal that has <code>handle stop</code> in effect, or for any other event 207that normally results in stopping the stepping command sooner. Also 208note that <small>GDB</small> still informs you that the program received a 209signal if <code>handle print</code> is set. 210</p> 211<a name="stepping-into-signal-handlers"></a> 212<p>If you set <code>handle pass</code> for a signal, and your program sets up a 213handler for it, then issuing a stepping command, such as <code>step</code> 214or <code>stepi</code>, when your program is stopped due to the signal will 215step <em>into</em> the signal handler (if the target supports that). 216</p> 217<p>Likewise, if you use the <code>queue-signal</code> command to queue a signal 218to be delivered to the current thread when execution of the thread 219resumes (see <a href="Signaling.html#Signaling">Giving your Program a Signal</a>), then a 220stepping command will step into the signal handler. 221</p> 222<p>Here’s an example, using <code>stepi</code> to step to the first instruction 223of <code>SIGUSR1</code>’s handler: 224</p> 225<div class="smallexample"> 226<pre class="smallexample">(gdb) handle SIGUSR1 227Signal Stop Print Pass to program Description 228SIGUSR1 Yes Yes Yes User defined signal 1 229(gdb) c 230Continuing. 231 232Program received signal SIGUSR1, User defined signal 1. 233main () sigusr1.c:28 23428 p = 0; 235(gdb) si 236sigusr1_handler () at sigusr1.c:9 2379 { 238</pre></div> 239 240<p>The same, but using <code>queue-signal</code> instead of waiting for the 241program to receive the signal first: 242</p> 243<div class="smallexample"> 244<pre class="smallexample">(gdb) n 24528 p = 0; 246(gdb) queue-signal SIGUSR1 247(gdb) si 248sigusr1_handler () at sigusr1.c:9 2499 { 250(gdb) 251</pre></div> 252 253<a name="index-extra-signal-information"></a> 254<a name="extra-signal-information"></a> 255<p>On some targets, <small>GDB</small> can inspect extra signal information 256associated with the intercepted signal, before it is actually 257delivered to the program being debugged. This information is exported 258by the convenience variable <code>$_siginfo</code>, and consists of data 259that is passed by the kernel to the signal handler at the time of the 260receipt of a signal. The data type of the information itself is 261target dependent. You can see the data type using the <code>ptype 262$_siginfo</code> command. On Unix systems, it typically corresponds to the 263standard <code>siginfo_t</code> type, as defined in the <samp>signal.h</samp> 264system header. 265</p> 266<p>Here’s an example, on a <small>GNU</small>/Linux system, printing the stray 267referenced address that raised a segmentation fault. 268</p> 269<div class="smallexample"> 270<pre class="smallexample">(gdb) continue 271Program received signal SIGSEGV, Segmentation fault. 2720x0000000000400766 in main () 27369 *(int *)p = 0; 274(gdb) ptype $_siginfo 275type = struct { 276 int si_signo; 277 int si_errno; 278 int si_code; 279 union { 280 int _pad[28]; 281 struct {...} _kill; 282 struct {...} _timer; 283 struct {...} _rt; 284 struct {...} _sigchld; 285 struct {...} _sigfault; 286 struct {...} _sigpoll; 287 } _sifields; 288} 289(gdb) ptype $_siginfo._sifields._sigfault 290type = struct { 291 void *si_addr; 292} 293(gdb) p $_siginfo._sifields._sigfault.si_addr 294$1 = (void *) 0x7ffff7ff7000 295</pre></div> 296 297<p>Depending on target support, <code>$_siginfo</code> may also be writable. 298</p> 299<a name="index-Intel-MPX-boundary-violations"></a> 300<a name="index-boundary-violations_002c-Intel-MPX"></a> 301<p>On some targets, a <code>SIGSEGV</code> can be caused by a boundary 302violation, i.e., accessing an address outside of the allowed range. 303In those cases <small>GDB</small> may displays additional information, 304depending on how <small>GDB</small> has been told to handle the signal. 305With <code>handle stop SIGSEGV</code>, <small>GDB</small> displays the violation 306kind: "Upper" or "Lower", the memory address accessed and the 307bounds, while with <code>handle nostop SIGSEGV</code> no additional 308information is displayed. 309</p> 310<p>The usual output of a segfault is: 311</p><div class="smallexample"> 312<pre class="smallexample">Program received signal SIGSEGV, Segmentation fault 3130x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 31468 value = *(p + len); 315</pre></div> 316 317<p>While a bound violation is presented as: 318</p><div class="smallexample"> 319<pre class="smallexample">Program received signal SIGSEGV, Segmentation fault 320Upper bound violation while accessing address 0x7fffffffc3b3 321Bounds: [lower = 0x7fffffffc390, upper = 0x7fffffffc3a3] 3220x0000000000400d7c in upper () at i386-mpx-sigsegv.c:68 32368 value = *(p + len); 324</pre></div> 325 326<hr> 327<div class="header"> 328<p> 329Next: <a href="Thread-Stops.html#Thread-Stops" accesskey="n" rel="next">Thread Stops</a>, Previous: <a href="Skipping-Over-Functions-and-Files.html#Skipping-Over-Functions-and-Files" accesskey="p" rel="previous">Skipping Over Functions and Files</a>, Up: <a href="Stopping.html#Stopping" accesskey="u" rel="up">Stopping</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html#Concept-Index" title="Index" rel="index">Index</a>]</p> 330</div> 331 332 333 334</body> 335</html> 336