Set-Catchpoints.html 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423
  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-2019 Free Software Foundation, Inc.
  4. Permission is granted to copy, distribute and/or modify this document
  5. under the terms of the GNU Free Documentation License, Version 1.3 or
  6. any later version published by the Free Software Foundation; with the
  7. Invariant Sections being "Free Software" and "Free Software Needs
  8. Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
  9. and with the Back-Cover Texts as in (a) below.
  10. (a) The FSF's Back-Cover Text is: "You are free to copy and modify
  11. this GNU Manual. Buying copies from GNU Press supports the FSF in
  12. developing GNU and promoting software freedom." -->
  13. <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
  14. <head>
  15. <title>Debugging with GDB: Set Catchpoints</title>
  16. <meta name="description" content="Debugging with GDB: Set Catchpoints">
  17. <meta name="keywords" content="Debugging with GDB: Set Catchpoints">
  18. <meta name="resource-type" content="document">
  19. <meta name="distribution" content="global">
  20. <meta name="Generator" content="makeinfo">
  21. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  22. <link href="index.html#Top" rel="start" title="Top">
  23. <link href="Concept-Index.html#Concept-Index" rel="index" title="Concept Index">
  24. <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
  25. <link href="Breakpoints.html#Breakpoints" rel="up" title="Breakpoints">
  26. <link href="Delete-Breaks.html#Delete-Breaks" rel="next" title="Delete Breaks">
  27. <link href="Set-Watchpoints.html#Set-Watchpoints" rel="prev" title="Set Watchpoints">
  28. <style type="text/css">
  29. <!--
  30. a.summary-letter {text-decoration: none}
  31. blockquote.smallquotation {font-size: smaller}
  32. div.display {margin-left: 3.2em}
  33. div.example {margin-left: 3.2em}
  34. div.indentedblock {margin-left: 3.2em}
  35. div.lisp {margin-left: 3.2em}
  36. div.smalldisplay {margin-left: 3.2em}
  37. div.smallexample {margin-left: 3.2em}
  38. div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
  39. div.smalllisp {margin-left: 3.2em}
  40. kbd {font-style:oblique}
  41. pre.display {font-family: inherit}
  42. pre.format {font-family: inherit}
  43. pre.menu-comment {font-family: serif}
  44. pre.menu-preformatted {font-family: serif}
  45. pre.smalldisplay {font-family: inherit; font-size: smaller}
  46. pre.smallexample {font-size: smaller}
  47. pre.smallformat {font-family: inherit; font-size: smaller}
  48. pre.smalllisp {font-size: smaller}
  49. span.nocodebreak {white-space:nowrap}
  50. span.nolinebreak {white-space:nowrap}
  51. span.roman {font-family:serif; font-weight:normal}
  52. span.sansserif {font-family:sans-serif; font-weight:normal}
  53. ul.no-bullet {list-style: none}
  54. -->
  55. </style>
  56. </head>
  57. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  58. <a name="Set-Catchpoints"></a>
  59. <div class="header">
  60. <p>
  61. Next: <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="prev">Set Watchpoints</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> &nbsp; [<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>
  62. </div>
  63. <hr>
  64. <a name="Setting-Catchpoints"></a>
  65. <h4 class="subsection">5.1.3 Setting Catchpoints</h4>
  66. <a name="index-catchpoints_002c-setting"></a>
  67. <a name="index-exception-handlers"></a>
  68. <a name="index-event-handling"></a>
  69. <p>You can use <em>catchpoints</em> to cause the debugger to stop for certain
  70. kinds of program events, such as C<tt>++</tt> exceptions or the loading of a
  71. shared library. Use the <code>catch</code> command to set a catchpoint.
  72. </p>
  73. <dl compact="compact">
  74. <dd><a name="index-catch"></a>
  75. </dd>
  76. <dt><code>catch <var>event</var></code></dt>
  77. <dd><p>Stop when <var>event</var> occurs. The <var>event</var> can be any of the following:
  78. </p>
  79. <dl compact="compact">
  80. <dt><code>throw <span class="roman">[</span><var>regexp</var><span class="roman">]</span></code></dt>
  81. <dt><code>rethrow <span class="roman">[</span><var>regexp</var><span class="roman">]</span></code></dt>
  82. <dt><code>catch <span class="roman">[</span><var>regexp</var><span class="roman">]</span></code></dt>
  83. <dd><a name="index-catch-throw"></a>
  84. <a name="index-catch-rethrow"></a>
  85. <a name="index-catch-catch"></a>
  86. <a name="index-stop-on-C_002b_002b-exceptions"></a>
  87. <p>The throwing, re-throwing, or catching of a C<tt>++</tt> exception.
  88. </p>
  89. <p>If <var>regexp</var> is given, then only exceptions whose type matches the
  90. regular expression will be caught.
  91. </p>
  92. <a name="index-_0024_005fexception_002c-convenience-variable"></a>
  93. <p>The convenience variable <code>$_exception</code> is available at an
  94. exception-related catchpoint, on some systems. This holds the
  95. exception being thrown.
  96. </p>
  97. <p>There are currently some limitations to C<tt>++</tt> exception handling in
  98. <small>GDB</small>:
  99. </p>
  100. <ul>
  101. <li> The support for these commands is system-dependent. Currently, only
  102. systems using the &lsquo;<samp>gnu-v3</samp>&rsquo; C<tt>++</tt> ABI (see <a href="ABI.html#ABI">ABI</a>) are
  103. supported.
  104. </li><li> The regular expression feature and the <code>$_exception</code> convenience
  105. variable rely on the presence of some SDT probes in <code>libstdc++</code>.
  106. If these probes are not present, then these features cannot be used.
  107. These probes were first available in the GCC 4.8 release, but whether
  108. or not they are available in your GCC also depends on how it was
  109. built.
  110. </li><li> The <code>$_exception</code> convenience variable is only valid at the
  111. instruction at which an exception-related catchpoint is set.
  112. </li><li> When an exception-related catchpoint is hit, <small>GDB</small> stops at a
  113. location in the system library which implements runtime exception
  114. support for C<tt>++</tt>, usually <code>libstdc++</code>. You can use <code>up</code>
  115. (see <a href="Selection.html#Selection">Selection</a>) to get to your code.
  116. </li><li> If you call a function interactively, <small>GDB</small> normally returns
  117. control to you when the function has finished executing. If the call
  118. raises an exception, however, the call may bypass the mechanism that
  119. returns control to you and cause your program either to abort or to
  120. simply continue running until it hits a breakpoint, catches a signal
  121. that <small>GDB</small> is listening for, or exits. This is the case even if
  122. you set a catchpoint for the exception; catchpoints on exceptions are
  123. disabled within interactive calls. See <a href="Calling.html#Calling">Calling</a>, for information on
  124. controlling this with <code>set unwind-on-terminating-exception</code>.
  125. </li><li> You cannot raise an exception interactively.
  126. </li><li> You cannot install an exception handler interactively.
  127. </li></ul>
  128. </dd>
  129. <dt><code>exception</code></dt>
  130. <dd><a name="index-catch-exception"></a>
  131. <a name="index-Ada-exception-catching"></a>
  132. <a name="index-catch-Ada-exceptions"></a>
  133. <p>An Ada exception being raised. If an exception name is specified
  134. at the end of the command (eg <code>catch exception Program_Error</code>),
  135. the debugger will stop only when this specific exception is raised.
  136. Otherwise, the debugger stops execution when any Ada exception is raised.
  137. </p>
  138. <p>When inserting an exception catchpoint on a user-defined exception whose
  139. name is identical to one of the exceptions defined by the language, the
  140. fully qualified name must be used as the exception name. Otherwise,
  141. <small>GDB</small> will assume that it should stop on the pre-defined exception
  142. rather than the user-defined one. For instance, assuming an exception
  143. called <code>Constraint_Error</code> is defined in package <code>Pck</code>, then
  144. the command to use to catch such exceptions is <kbd>catch exception
  145. Pck.Constraint_Error</kbd>.
  146. </p>
  147. </dd>
  148. <dt><code>handlers</code></dt>
  149. <dd><a name="index-catch-handlers"></a>
  150. <a name="index-Ada-exception-handlers-catching"></a>
  151. <a name="index-catch-Ada-exceptions-when-handled"></a>
  152. <p>An Ada exception being handled. If an exception name is
  153. specified at the end of the command
  154. (eg <kbd>catch handlers Program_Error</kbd>), the debugger will stop
  155. only when this specific exception is handled.
  156. Otherwise, the debugger stops execution when any Ada exception is handled.
  157. </p>
  158. <p>When inserting a handlers catchpoint on a user-defined
  159. exception whose name is identical to one of the exceptions
  160. defined by the language, the fully qualified name must be used
  161. as the exception name. Otherwise, <small>GDB</small> will assume that it
  162. should stop on the pre-defined exception rather than the
  163. user-defined one. For instance, assuming an exception called
  164. <code>Constraint_Error</code> is defined in package <code>Pck</code>, then the
  165. command to use to catch such exceptions handling is
  166. <kbd>catch handlers Pck.Constraint_Error</kbd>.
  167. </p>
  168. </dd>
  169. <dt><code>exception unhandled</code></dt>
  170. <dd><a name="index-catch-exception-unhandled"></a>
  171. <p>An exception that was raised but is not handled by the program.
  172. </p>
  173. </dd>
  174. <dt><code>assert</code></dt>
  175. <dd><a name="index-catch-assert"></a>
  176. <p>A failed Ada assertion.
  177. </p>
  178. </dd>
  179. <dt><code>exec</code></dt>
  180. <dd><a name="index-catch-exec"></a>
  181. <a name="index-break-on-fork_002fexec"></a>
  182. <p>A call to <code>exec</code>.
  183. </p>
  184. <a name="catch-syscall"></a></dd>
  185. <dt><code>syscall</code></dt>
  186. <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> &hellip;</code></dt>
  187. <dd><a name="index-catch-syscall"></a>
  188. <a name="index-break-on-a-system-call_002e"></a>
  189. <p>A call to or return from a system call, a.k.a. <em>syscall</em>. A
  190. syscall is a mechanism for application programs to request a service
  191. from the operating system (OS) or one of the OS system services.
  192. <small>GDB</small> can catch some or all of the syscalls issued by the
  193. debuggee, and show the related information for each syscall. If no
  194. argument is specified, calls to and returns from all system calls
  195. will be caught.
  196. </p>
  197. <p><var>name</var> can be any system call name that is valid for the
  198. underlying OS. Just what syscalls are valid depends on the OS. On
  199. GNU and Unix systems, you can find the full list of valid syscall
  200. names on <samp>/usr/include/asm/unistd.h</samp>.
  201. </p>
  202. <p>Normally, <small>GDB</small> knows in advance which syscalls are valid for
  203. each OS, so you can use the <small>GDB</small> command-line completion
  204. facilities (see <a href="Completion.html#Completion">command completion</a>) to list the
  205. available choices.
  206. </p>
  207. <p>You may also specify the system call numerically. A syscall&rsquo;s
  208. number is the value passed to the OS&rsquo;s syscall dispatcher to
  209. identify the requested service. When you specify the syscall by its
  210. name, <small>GDB</small> uses its database of syscalls to convert the name
  211. into the corresponding numeric code, but using the number directly
  212. may be useful if <small>GDB</small>&rsquo;s database does not have the complete
  213. list of syscalls on your system (e.g., because <small>GDB</small> lags
  214. behind the OS upgrades).
  215. </p>
  216. <p>You may specify a group of related syscalls to be caught at once using
  217. the <code>group:</code> syntax (<code>g:</code> is a shorter equivalent). For
  218. instance, on some platforms <small>GDB</small> allows you to catch all
  219. network related syscalls, by passing the argument <code>group:network</code>
  220. to <code>catch syscall</code>. Note that not all syscall groups are
  221. available in every system. You can use the command completion
  222. facilities (see <a href="Completion.html#Completion">command completion</a>) to list the
  223. syscall groups available on your environment.
  224. </p>
  225. <p>The example below illustrates how this command works if you don&rsquo;t provide
  226. arguments to it:
  227. </p>
  228. <div class="smallexample">
  229. <pre class="smallexample">(gdb) catch syscall
  230. Catchpoint 1 (syscall)
  231. (gdb) r
  232. Starting program: /tmp/catch-syscall
  233. Catchpoint 1 (call to syscall 'close'), \
  234. 0xffffe424 in __kernel_vsyscall ()
  235. (gdb) c
  236. Continuing.
  237. Catchpoint 1 (returned from syscall 'close'), \
  238. 0xffffe424 in __kernel_vsyscall ()
  239. (gdb)
  240. </pre></div>
  241. <p>Here is an example of catching a system call by name:
  242. </p>
  243. <div class="smallexample">
  244. <pre class="smallexample">(gdb) catch syscall chroot
  245. Catchpoint 1 (syscall 'chroot' [61])
  246. (gdb) r
  247. Starting program: /tmp/catch-syscall
  248. Catchpoint 1 (call to syscall 'chroot'), \
  249. 0xffffe424 in __kernel_vsyscall ()
  250. (gdb) c
  251. Continuing.
  252. Catchpoint 1 (returned from syscall 'chroot'), \
  253. 0xffffe424 in __kernel_vsyscall ()
  254. (gdb)
  255. </pre></div>
  256. <p>An example of specifying a system call numerically. In the case
  257. below, the syscall number has a corresponding entry in the XML
  258. file, so <small>GDB</small> finds its name and prints it:
  259. </p>
  260. <div class="smallexample">
  261. <pre class="smallexample">(gdb) catch syscall 252
  262. Catchpoint 1 (syscall(s) 'exit_group')
  263. (gdb) r
  264. Starting program: /tmp/catch-syscall
  265. Catchpoint 1 (call to syscall 'exit_group'), \
  266. 0xffffe424 in __kernel_vsyscall ()
  267. (gdb) c
  268. Continuing.
  269. Program exited normally.
  270. (gdb)
  271. </pre></div>
  272. <p>Here is an example of catching a syscall group:
  273. </p>
  274. <div class="smallexample">
  275. <pre class="smallexample">(gdb) catch syscall group:process
  276. Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7]
  277. 'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190]
  278. 'exit_group' [252] 'waitid' [284] 'unshare' [310])
  279. (gdb) r
  280. Starting program: /tmp/catch-syscall
  281. Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 ()
  282. from /lib64/ld-linux-x86-64.so.2
  283. (gdb) c
  284. Continuing.
  285. </pre></div>
  286. <p>However, there can be situations when there is no corresponding name
  287. in XML file for that syscall number. In this case, <small>GDB</small> prints
  288. a warning message saying that it was not able to find the syscall name,
  289. but the catchpoint will be set anyway. See the example below:
  290. </p>
  291. <div class="smallexample">
  292. <pre class="smallexample">(gdb) catch syscall 764
  293. warning: The number '764' does not represent a known syscall.
  294. Catchpoint 2 (syscall 764)
  295. (gdb)
  296. </pre></div>
  297. <p>If you configure <small>GDB</small> using the &lsquo;<samp>--without-expat</samp>&rsquo; option,
  298. it will not be able to display syscall names. Also, if your
  299. architecture does not have an XML file describing its system calls,
  300. you will not be able to see the syscall names. It is important to
  301. notice that these two features are used for accessing the syscall
  302. name database. In either case, you will see a warning like this:
  303. </p>
  304. <div class="smallexample">
  305. <pre class="smallexample">(gdb) catch syscall
  306. warning: Could not open &quot;syscalls/i386-linux.xml&quot;
  307. warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'.
  308. GDB will not be able to display syscall names.
  309. Catchpoint 1 (syscall)
  310. (gdb)
  311. </pre></div>
  312. <p>Of course, the file name will change depending on your architecture and system.
  313. </p>
  314. <p>Still using the example above, you can also try to catch a syscall by its
  315. number. In this case, you would see something like:
  316. </p>
  317. <div class="smallexample">
  318. <pre class="smallexample">(gdb) catch syscall 252
  319. Catchpoint 1 (syscall(s) 252)
  320. </pre></div>
  321. <p>Again, in this case <small>GDB</small> would not be able to display syscall&rsquo;s names.
  322. </p>
  323. </dd>
  324. <dt><code>fork</code></dt>
  325. <dd><a name="index-catch-fork"></a>
  326. <p>A call to <code>fork</code>.
  327. </p>
  328. </dd>
  329. <dt><code>vfork</code></dt>
  330. <dd><a name="index-catch-vfork"></a>
  331. <p>A call to <code>vfork</code>.
  332. </p>
  333. </dd>
  334. <dt><code>load <span class="roman">[</span>regexp<span class="roman">]</span></code></dt>
  335. <dt><code>unload <span class="roman">[</span>regexp<span class="roman">]</span></code></dt>
  336. <dd><a name="index-catch-load"></a>
  337. <a name="index-catch-unload"></a>
  338. <p>The loading or unloading of a shared library. If <var>regexp</var> is
  339. given, then the catchpoint will stop only if the regular expression
  340. matches one of the affected libraries.
  341. </p>
  342. </dd>
  343. <dt><code>signal <span class="roman">[</span><var>signal</var>&hellip; <span class="roman">|</span> &lsquo;<samp>all</samp>&rsquo;<span class="roman">]</span></code></dt>
  344. <dd><a name="index-catch-signal"></a>
  345. <p>The delivery of a signal.
  346. </p>
  347. <p>With no arguments, this catchpoint will catch any signal that is not
  348. used internally by <small>GDB</small>, specifically, all signals except
  349. &lsquo;<samp>SIGTRAP</samp>&rsquo; and &lsquo;<samp>SIGINT</samp>&rsquo;.
  350. </p>
  351. <p>With the argument &lsquo;<samp>all</samp>&rsquo;, all signals, including those used by
  352. <small>GDB</small>, will be caught. This argument cannot be used with other
  353. signal names.
  354. </p>
  355. <p>Otherwise, the arguments are a list of signal names as given to
  356. <code>handle</code> (see <a href="Signals.html#Signals">Signals</a>). Only signals specified in this list
  357. will be caught.
  358. </p>
  359. <p>One reason that <code>catch signal</code> can be more useful than
  360. <code>handle</code> is that you can attach commands and conditions to the
  361. catchpoint.
  362. </p>
  363. <p>When a signal is caught by a catchpoint, the signal&rsquo;s <code>stop</code> and
  364. <code>print</code> settings, as specified by <code>handle</code>, are ignored.
  365. However, whether the signal is still delivered to the inferior depends
  366. on the <code>pass</code> setting; this can be changed in the catchpoint&rsquo;s
  367. commands.
  368. </p>
  369. </dd>
  370. </dl>
  371. </dd>
  372. <dt><code>tcatch <var>event</var></code></dt>
  373. <dd><a name="index-tcatch"></a>
  374. <p>Set a catchpoint that is enabled only for one stop. The catchpoint is
  375. automatically deleted after the first time the event is caught.
  376. </p>
  377. </dd>
  378. </dl>
  379. <p>Use the <code>info break</code> command to list the current catchpoints.
  380. </p>
  381. <hr>
  382. <div class="header">
  383. <p>
  384. Next: <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="prev">Set Watchpoints</a>, Up: <a href="Breakpoints.html#Breakpoints" accesskey="u" rel="up">Breakpoints</a> &nbsp; [<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>
  385. </div>
  386. </body>
  387. </html>