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: Set Catchpoints</title> 18 19<meta name="description" content="Debugging with GDB: Set Catchpoints"> 20<meta name="keywords" content="Debugging with GDB: Set Catchpoints"> 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="Breakpoints.html#Breakpoints" rel="up" title="Breakpoints"> 29<link href="Delete-Breaks.html#Delete-Breaks" rel="next" title="Delete Breaks"> 30<link href="Set-Watchpoints.html#Set-Watchpoints" rel="previous" title="Set Watchpoints"> 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="Set-Catchpoints"></a> 65<div class="header"> 66<p> 67Next: <a href="Delete-Breaks.html#Delete-Breaks" accesskey="n" rel="next">Delete Breaks</a>, Previous: <a href="Set-Watchpoints.html#Set-Watchpoints" accesskey="p" rel="previous">Set Watchpoints</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</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="Setting-Catchpoints"></a> 71<h4 class="subsection">5.1.3 Setting Catchpoints</h4> 72<a name="index-catchpoints_002c-setting"></a> 73<a name="index-exception-handlers"></a> 74<a name="index-event-handling"></a> 75 76<p>You can use <em>catchpoints</em> to cause the debugger to stop for certain 77kinds of program events, such as C<tt>++</tt> exceptions or the loading of a 78shared library. Use the <code>catch</code> command to set a catchpoint. 79</p> 80<dl compact="compact"> 81<dd><a name="index-catch"></a> 82</dd> 83<dt><code>catch <var>event</var></code></dt> 84<dd><p>Stop when <var>event</var> occurs. The <var>event</var> can be any of the following: 85</p> 86<dl compact="compact"> 87<dt><code>throw <span class="roman">[</span><var>regexp</var><span class="roman">]</span></code></dt> 88<dt><code>rethrow <span class="roman">[</span><var>regexp</var><span class="roman">]</span></code></dt> 89<dt><code>catch <span class="roman">[</span><var>regexp</var><span class="roman">]</span></code></dt> 90<dd><a name="index-catch-throw"></a> 91<a name="index-catch-rethrow"></a> 92<a name="index-catch-catch"></a> 93<a name="index-stop-on-C_002b_002b-exceptions"></a> 94<p>The throwing, re-throwing, or catching of a C<tt>++</tt> exception. 95</p> 96<p>If <var>regexp</var> is given, then only exceptions whose type matches the 97regular expression will be caught. 98</p> 99<a name="index-_0024_005fexception_002c-convenience-variable"></a> 100<p>The convenience variable <code>$_exception</code> is available at an 101exception-related catchpoint, on some systems. This holds the 102exception being thrown. 103</p> 104<p>There are currently some limitations to C<tt>++</tt> exception handling in 105<small>GDB</small>: 106</p> 107<ul> 108<li> The support for these commands is system-dependent. Currently, only 109systems using the ‘<samp>gnu-v3</samp>’ C<tt>++</tt> ABI (see <a href="ABI.html#ABI">ABI</a>) are 110supported. 111 112</li><li> The regular expression feature and the <code>$_exception</code> convenience 113variable rely on the presence of some SDT probes in <code>libstdc++</code>. 114If these probes are not present, then these features cannot be used. 115These probes were first available in the GCC 4.8 release, but whether 116or not they are available in your GCC also depends on how it was 117built. 118 119</li><li> The <code>$_exception</code> convenience variable is only valid at the 120instruction at which an exception-related catchpoint is set. 121 122</li><li> When an exception-related catchpoint is hit, <small>GDB</small> stops at a 123location in the system library which implements runtime exception 124support for C<tt>++</tt>, usually <code>libstdc++</code>. You can use <code>up</code> 125(see <a href="Selection.html#Selection">Selection</a>) to get to your code. 126 127</li><li> If you call a function interactively, <small>GDB</small> normally returns 128control to you when the function has finished executing. If the call 129raises an exception, however, the call may bypass the mechanism that 130returns control to you and cause your program either to abort or to 131simply continue running until it hits a breakpoint, catches a signal 132that <small>GDB</small> is listening for, or exits. This is the case even if 133you set a catchpoint for the exception; catchpoints on exceptions are 134disabled within interactive calls. See <a href="Calling.html#Calling">Calling</a>, for information on 135controlling this with <code>set unwind-on-terminating-exception</code>. 136 137</li><li> You cannot raise an exception interactively. 138 139</li><li> You cannot install an exception handler interactively. 140</li></ul> 141 142</dd> 143<dt><code>exception <span class="roman">[</span><var>name</var><span class="roman">]</span></code></dt> 144<dd><a name="index-catch-exception"></a> 145<a name="index-Ada-exception-catching"></a> 146<a name="index-catch-Ada-exceptions"></a> 147<p>An Ada exception being raised. If an exception name is specified 148at the end of the command (eg <code>catch exception Program_Error</code>), 149the debugger will stop only when this specific exception is raised. 150Otherwise, the debugger stops execution when any Ada exception is raised. 151</p> 152<p>When inserting an exception catchpoint on a user-defined exception whose 153name is identical to one of the exceptions defined by the language, the 154fully qualified name must be used as the exception name. Otherwise, 155<small>GDB</small> will assume that it should stop on the pre-defined exception 156rather than the user-defined one. For instance, assuming an exception 157called <code>Constraint_Error</code> is defined in package <code>Pck</code>, then 158the command to use to catch such exceptions is <kbd>catch exception 159Pck.Constraint_Error</kbd>. 160</p> 161<a name="index-_0024_005fada_005fexception_002c-convenience-variable"></a> 162<p>The convenience variable <code>$_ada_exception</code> holds the address of 163the exception being thrown. This can be useful when setting a 164condition for such a catchpoint. 165</p> 166</dd> 167<dt><code>exception unhandled</code></dt> 168<dd><a name="index-catch-exception-unhandled"></a> 169<p>An exception that was raised but is not handled by the program. The 170convenience variable <code>$_ada_exception</code> is set as for <code>catch 171exception</code>. 172</p> 173</dd> 174<dt><code>handlers <span class="roman">[</span><var>name</var><span class="roman">]</span></code></dt> 175<dd><a name="index-catch-handlers"></a> 176<a name="index-Ada-exception-handlers-catching"></a> 177<a name="index-catch-Ada-exceptions-when-handled"></a> 178<p>An Ada exception being handled. If an exception name is 179specified at the end of the command 180 (eg <kbd>catch handlers Program_Error</kbd>), the debugger will stop 181only when this specific exception is handled. 182Otherwise, the debugger stops execution when any Ada exception is handled. 183</p> 184<p>When inserting a handlers catchpoint on a user-defined 185exception whose name is identical to one of the exceptions 186defined by the language, the fully qualified name must be used 187as the exception name. Otherwise, <small>GDB</small> will assume that it 188should stop on the pre-defined exception rather than the 189user-defined one. For instance, assuming an exception called 190 <code>Constraint_Error</code> is defined in package <code>Pck</code>, then the 191command to use to catch such exceptions handling is 192<kbd>catch handlers Pck.Constraint_Error</kbd>. 193</p> 194<p>The convenience variable <code>$_ada_exception</code> is set as for 195<code>catch exception</code>. 196</p> 197</dd> 198<dt><code>assert</code></dt> 199<dd><a name="index-catch-assert"></a> 200<p>A failed Ada assertion. Note that the convenience variable 201<code>$_ada_exception</code> is <em>not</em> set by this catchpoint. 202</p> 203</dd> 204<dt><code>exec</code></dt> 205<dd><a name="index-catch-exec"></a> 206<a name="index-break-on-fork_002fexec"></a> 207<p>A call to <code>exec</code>. 208</p> 209<a name="catch-syscall"></a></dd> 210<dt><code>syscall</code></dt> 211<dt><code>syscall <span class="roman">[</span><var>name</var> <span class="roman">|</span> <var>number</var> <span class="roman">|</span> <span class="roman">group:</span><var>groupname</var> <span class="roman">|</span> <span class="roman">g:</span><var>groupname</var><span class="roman">]</span> …</code></dt> 212<dd><a name="index-catch-syscall"></a> 213<a name="index-break-on-a-system-call_002e"></a> 214<p>A call to or return from a system call, a.k.a. <em>syscall</em>. A 215syscall is a mechanism for application programs to request a service 216from the operating system (OS) or one of the OS system services. 217<small>GDB</small> can catch some or all of the syscalls issued by the 218debuggee, and show the related information for each syscall. If no 219argument is specified, calls to and returns from all system calls 220will be caught. 221</p> 222<p><var>name</var> can be any system call name that is valid for the 223underlying OS. Just what syscalls are valid depends on the OS. On 224GNU and Unix systems, you can find the full list of valid syscall 225names on <samp>/usr/include/asm/unistd.h</samp>. 226</p> 227 228<p>Normally, <small>GDB</small> knows in advance which syscalls are valid for 229each OS, so you can use the <small>GDB</small> command-line completion 230facilities (see <a href="Completion.html#Completion">command completion</a>) to list the 231available choices. 232</p> 233<p>You may also specify the system call numerically. A syscall’s 234number is the value passed to the OS’s syscall dispatcher to 235identify the requested service. When you specify the syscall by its 236name, <small>GDB</small> uses its database of syscalls to convert the name 237into the corresponding numeric code, but using the number directly 238may be useful if <small>GDB</small>’s database does not have the complete 239list of syscalls on your system (e.g., because <small>GDB</small> lags 240behind the OS upgrades). 241</p> 242<p>You may specify a group of related syscalls to be caught at once using 243the <code>group:</code> syntax (<code>g:</code> is a shorter equivalent). For 244instance, on some platforms <small>GDB</small> allows you to catch all 245network related syscalls, by passing the argument <code>group:network</code> 246to <code>catch syscall</code>. Note that not all syscall groups are 247available in every system. You can use the command completion 248facilities (see <a href="Completion.html#Completion">command completion</a>) to list the 249syscall groups available on your environment. 250</p> 251<p>The example below illustrates how this command works if you don’t provide 252arguments to it: 253</p> 254<div class="smallexample"> 255<pre class="smallexample">(gdb) catch syscall 256Catchpoint 1 (syscall) 257(gdb) r 258Starting program: /tmp/catch-syscall 259 260Catchpoint 1 (call to syscall 'close'), \ 261 0xffffe424 in __kernel_vsyscall () 262(gdb) c 263Continuing. 264 265Catchpoint 1 (returned from syscall 'close'), \ 266 0xffffe424 in __kernel_vsyscall () 267(gdb) 268</pre></div> 269 270<p>Here is an example of catching a system call by name: 271</p> 272<div class="smallexample"> 273<pre class="smallexample">(gdb) catch syscall chroot 274Catchpoint 1 (syscall 'chroot' [61]) 275(gdb) r 276Starting program: /tmp/catch-syscall 277 278Catchpoint 1 (call to syscall 'chroot'), \ 279 0xffffe424 in __kernel_vsyscall () 280(gdb) c 281Continuing. 282 283Catchpoint 1 (returned from syscall 'chroot'), \ 284 0xffffe424 in __kernel_vsyscall () 285(gdb) 286</pre></div> 287 288<p>An example of specifying a system call numerically. In the case 289below, the syscall number has a corresponding entry in the XML 290file, so <small>GDB</small> finds its name and prints it: 291</p> 292<div class="smallexample"> 293<pre class="smallexample">(gdb) catch syscall 252 294Catchpoint 1 (syscall(s) 'exit_group') 295(gdb) r 296Starting program: /tmp/catch-syscall 297 298Catchpoint 1 (call to syscall 'exit_group'), \ 299 0xffffe424 in __kernel_vsyscall () 300(gdb) c 301Continuing. 302 303Program exited normally. 304(gdb) 305</pre></div> 306 307<p>Here is an example of catching a syscall group: 308</p> 309<div class="smallexample"> 310<pre class="smallexample">(gdb) catch syscall group:process 311Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7] 312'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190] 313'exit_group' [252] 'waitid' [284] 'unshare' [310]) 314(gdb) r 315Starting program: /tmp/catch-syscall 316 317Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 () 318 from /lib64/ld-linux-x86-64.so.2 319 320(gdb) c 321Continuing. 322</pre></div> 323 324<p>However, there can be situations when there is no corresponding name 325in XML file for that syscall number. In this case, <small>GDB</small> prints 326a warning message saying that it was not able to find the syscall name, 327but the catchpoint will be set anyway. See the example below: 328</p> 329<div class="smallexample"> 330<pre class="smallexample">(gdb) catch syscall 764 331warning: The number '764' does not represent a known syscall. 332Catchpoint 2 (syscall 764) 333(gdb) 334</pre></div> 335 336<p>If you configure <small>GDB</small> using the ‘<samp>--without-expat</samp>’ option, 337it will not be able to display syscall names. Also, if your 338architecture does not have an XML file describing its system calls, 339you will not be able to see the syscall names. It is important to 340notice that these two features are used for accessing the syscall 341name database. In either case, you will see a warning like this: 342</p> 343<div class="smallexample"> 344<pre class="smallexample">(gdb) catch syscall 345warning: Could not open "syscalls/i386-linux.xml" 346warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. 347GDB will not be able to display syscall names. 348Catchpoint 1 (syscall) 349(gdb) 350</pre></div> 351 352<p>Of course, the file name will change depending on your architecture and system. 353</p> 354<p>Still using the example above, you can also try to catch a syscall by its 355number. In this case, you would see something like: 356</p> 357<div class="smallexample"> 358<pre class="smallexample">(gdb) catch syscall 252 359Catchpoint 1 (syscall(s) 252) 360</pre></div> 361 362<p>Again, in this case <small>GDB</small> would not be able to display syscall’s names. 363</p> 364</dd> 365<dt><code>fork</code></dt> 366<dd><a name="index-catch-fork"></a> 367<p>A call to <code>fork</code>. 368</p> 369</dd> 370<dt><code>vfork</code></dt> 371<dd><a name="index-catch-vfork"></a> 372<p>A call to <code>vfork</code>. 373</p> 374</dd> 375<dt><code>load <span class="roman">[</span><var>regexp</var><span class="roman">]</span></code></dt> 376<dt><code>unload <span class="roman">[</span><var>regexp</var><span class="roman">]</span></code></dt> 377<dd><a name="index-catch-load"></a> 378<a name="index-catch-unload"></a> 379<p>The loading or unloading of a shared library. If <var>regexp</var> is 380given, then the catchpoint will stop only if the regular expression 381matches one of the affected libraries. 382</p> 383</dd> 384<dt><code>signal <span class="roman">[</span><var>signal</var>… <span class="roman">|</span> ‘<samp>all</samp>’<span class="roman">]</span></code></dt> 385<dd><a name="index-catch-signal"></a> 386<p>The delivery of a signal. 387</p> 388<p>With no arguments, this catchpoint will catch any signal that is not 389used internally by <small>GDB</small>, specifically, all signals except 390‘<samp>SIGTRAP</samp>’ and ‘<samp>SIGINT</samp>’. 391</p> 392<p>With the argument ‘<samp>all</samp>’, all signals, including those used by 393<small>GDB</small>, will be caught. This argument cannot be used with other 394signal names. 395</p> 396<p>Otherwise, the arguments are a list of signal names as given to 397<code>handle</code> (see <a href="Signals.html#Signals">Signals</a>). Only signals specified in this list 398will be caught. 399</p> 400<p>One reason that <code>catch signal</code> can be more useful than 401<code>handle</code> is that you can attach commands and conditions to the 402catchpoint. 403</p> 404<p>When a signal is caught by a catchpoint, the signal’s <code>stop</code> and 405<code>print</code> settings, as specified by <code>handle</code>, are ignored. 406However, whether the signal is still delivered to the inferior depends 407on the <code>pass</code> setting; this can be changed in the catchpoint’s 408commands. 409</p> 410</dd> 411</dl> 412 413</dd> 414<dt><code>tcatch <var>event</var></code></dt> 415<dd><a name="index-tcatch"></a> 416<p>Set a catchpoint that is enabled only for one stop. The catchpoint is 417automatically deleted after the first time the event is caught. 418</p> 419</dd> 420</dl> 421 422<p>Use the <code>info break</code> command to list the current catchpoints. 423</p> 424 425<hr> 426<div class="header"> 427<p> 428Next: <a href="Delete-Breaks.html#Delete-Breaks" accesskey="n" rel="next">Delete Breaks</a>, Previous: <a href="Set-Watchpoints.html#Set-Watchpoints" accesskey="p" rel="previous">Set Watchpoints</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</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> 429</div> 430 431 432 433</body> 434</html> 435