| <html lang="en"> |
| <head> |
| <title>Set Catchpoints - Debugging with GDB</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Debugging with GDB"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Breakpoints.html#Breakpoints" title="Breakpoints"> |
| <link rel="prev" href="Set-Watchpoints.html#Set-Watchpoints" title="Set Watchpoints"> |
| <link rel="next" href="Delete-Breaks.html#Delete-Breaks" title="Delete Breaks"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, |
| 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 |
| Free Software Foundation, Inc. |
| |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the GNU Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being ``Free Software'' and ``Free Software Needs |
| Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' |
| and with the Back-Cover Texts as in (a) below. |
| |
| (a) The FSF's Back-Cover Text is: ``You are free to copy and modify |
| this GNU Manual. Buying copies from GNU Press supports the FSF in |
| developing GNU and promoting software freedom.''--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Set-Catchpoints"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Delete-Breaks.html#Delete-Breaks">Delete Breaks</a>, |
| Previous: <a rel="previous" accesskey="p" href="Set-Watchpoints.html#Set-Watchpoints">Set Watchpoints</a>, |
| Up: <a rel="up" accesskey="u" href="Breakpoints.html#Breakpoints">Breakpoints</a> |
| <hr> |
| </div> |
| |
| <h4 class="subsection">5.1.3 Setting Catchpoints</h4> |
| |
| <p><a name="index-catchpoints_002c-setting-252"></a><a name="index-exception-handlers-253"></a><a name="index-event-handling-254"></a> |
| You can use <dfn>catchpoints</dfn> to cause the debugger to stop for certain |
| kinds of program events, such as C<tt>++</tt> exceptions or the loading of a |
| shared library. Use the <code>catch</code> command to set a catchpoint. |
| |
| |
| <a name="index-catch-255"></a> |
| <dl><dt><code>catch </code><var>event</var><dd>Stop when <var>event</var> occurs. <var>event</var> can be any of the following: |
| <dl> |
| <dt><code>throw</code><dd><a name="index-stop-on-C_0040t_007b_002b_002b_007d-exceptions-256"></a>The throwing of a C<tt>++</tt> exception. |
| |
| <br><dt><code>catch</code><dd>The catching of a C<tt>++</tt> exception. |
| |
| <br><dt><code>exception</code><dd><a name="index-Ada-exception-catching-257"></a><a name="index-catch-Ada-exceptions-258"></a>An Ada exception being raised. If an exception name is specified |
| at the end of the command (eg <code>catch exception Program_Error</code>), |
| the debugger will stop only when this specific exception is raised. |
| Otherwise, the debugger stops execution when any Ada exception is raised. |
| |
| <p>When inserting an exception catchpoint on a user-defined exception whose |
| name is identical to one of the exceptions defined by the language, the |
| fully qualified name must be used as the exception name. Otherwise, |
| <span class="sc">gdb</span> will assume that it should stop on the pre-defined exception |
| rather than the user-defined one. For instance, assuming an exception |
| called <code>Constraint_Error</code> is defined in package <code>Pck</code>, then |
| the command to use to catch such exceptions is <kbd>catch exception |
| Pck.Constraint_Error</kbd>. |
| |
| <br><dt><code>exception unhandled</code><dd>An exception that was raised but is not handled by the program. |
| |
| <br><dt><code>assert</code><dd>A failed Ada assertion. |
| |
| <br><dt><code>exec</code><dd><a name="index-break-on-fork_002fexec-259"></a>A call to <code>exec</code>. This is currently only available for HP-UX |
| and <span class="sc">gnu</span>/Linux. |
| |
| <br><dt><code>syscall</code><dt><code>syscall </code><span class="roman">[</span><var>name</var> <span class="roman">|</span> <var>number</var><span class="roman">]</span><code> ...</code><dd><a name="index-break-on-a-system-call_002e-260"></a>A call to or return from a system call, a.k.a. <dfn>syscall</dfn>. A |
| syscall is a mechanism for application programs to request a service |
| from the operating system (OS) or one of the OS system services. |
| <span class="sc">gdb</span> can catch some or all of the syscalls issued by the |
| debuggee, and show the related information for each syscall. If no |
| argument is specified, calls to and returns from all system calls |
| will be caught. |
| |
| <p><var>name</var> can be any system call name that is valid for the |
| underlying OS. Just what syscalls are valid depends on the OS. On |
| GNU and Unix systems, you can find the full list of valid syscall |
| names on <samp><span class="file">/usr/include/asm/unistd.h</span></samp>. |
| |
| <!-- For MS-Windows, the syscall names and the corresponding numbers --> |
| <!-- can be found, e.g., on this URL: --> |
| <!-- http://www.metasploit.com/users/opcode/syscalls.html --> |
| <!-- but we don't support Windows syscalls yet. --> |
| <p>Normally, <span class="sc">gdb</span> knows in advance which syscalls are valid for |
| each OS, so you can use the <span class="sc">gdb</span> command-line completion |
| facilities (see <a href="Completion.html#Completion">command completion</a>) to list the |
| available choices. |
| |
| <p>You may also specify the system call numerically. A syscall's |
| number is the value passed to the OS's syscall dispatcher to |
| identify the requested service. When you specify the syscall by its |
| name, <span class="sc">gdb</span> uses its database of syscalls to convert the name |
| into the corresponding numeric code, but using the number directly |
| may be useful if <span class="sc">gdb</span>'s database does not have the complete |
| list of syscalls on your system (e.g., because <span class="sc">gdb</span> lags |
| behind the OS upgrades). |
| |
| <p>The example below illustrates how this command works if you don't provide |
| arguments to it: |
| |
| <pre class="smallexample"> (gdb) catch syscall |
| Catchpoint 1 (syscall) |
| (gdb) r |
| Starting program: /tmp/catch-syscall |
| |
| Catchpoint 1 (call to syscall 'close'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) c |
| Continuing. |
| |
| Catchpoint 1 (returned from syscall 'close'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) |
| </pre> |
| <p>Here is an example of catching a system call by name: |
| |
| <pre class="smallexample"> (gdb) catch syscall chroot |
| Catchpoint 1 (syscall 'chroot' [61]) |
| (gdb) r |
| Starting program: /tmp/catch-syscall |
| |
| Catchpoint 1 (call to syscall 'chroot'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) c |
| Continuing. |
| |
| Catchpoint 1 (returned from syscall 'chroot'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) |
| </pre> |
| <p>An example of specifying a system call numerically. In the case |
| below, the syscall number has a corresponding entry in the XML |
| file, so <span class="sc">gdb</span> finds its name and prints it: |
| |
| <pre class="smallexample"> (gdb) catch syscall 252 |
| Catchpoint 1 (syscall(s) 'exit_group') |
| (gdb) r |
| Starting program: /tmp/catch-syscall |
| |
| Catchpoint 1 (call to syscall 'exit_group'), \ |
| 0xffffe424 in __kernel_vsyscall () |
| (gdb) c |
| Continuing. |
| |
| Program exited normally. |
| (gdb) |
| </pre> |
| <p>However, there can be situations when there is no corresponding name |
| in XML file for that syscall number. In this case, <span class="sc">gdb</span> prints |
| a warning message saying that it was not able to find the syscall name, |
| but the catchpoint will be set anyway. See the example below: |
| |
| <pre class="smallexample"> (gdb) catch syscall 764 |
| warning: The number '764' does not represent a known syscall. |
| Catchpoint 2 (syscall 764) |
| (gdb) |
| </pre> |
| <p>If you configure <span class="sc">gdb</span> using the ‘<samp><span class="samp">--without-expat</span></samp>’ option, |
| it will not be able to display syscall names. Also, if your |
| architecture does not have an XML file describing its system calls, |
| you will not be able to see the syscall names. It is important to |
| notice that these two features are used for accessing the syscall |
| name database. In either case, you will see a warning like this: |
| |
| <pre class="smallexample"> (gdb) catch syscall |
| warning: Could not open "syscalls/i386-linux.xml" |
| warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. |
| GDB will not be able to display syscall names. |
| Catchpoint 1 (syscall) |
| (gdb) |
| </pre> |
| <p>Of course, the file name will change depending on your architecture and system. |
| |
| <p>Still using the example above, you can also try to catch a syscall by its |
| number. In this case, you would see something like: |
| |
| <pre class="smallexample"> (gdb) catch syscall 252 |
| Catchpoint 1 (syscall(s) 252) |
| </pre> |
| <p>Again, in this case <span class="sc">gdb</span> would not be able to display syscall's names. |
| |
| <br><dt><code>fork</code><dd>A call to <code>fork</code>. This is currently only available for HP-UX |
| and <span class="sc">gnu</span>/Linux. |
| |
| <br><dt><code>vfork</code><dd>A call to <code>vfork</code>. This is currently only available for HP-UX |
| and <span class="sc">gnu</span>/Linux. |
| |
| </dl> |
| |
| <br><dt><code>tcatch </code><var>event</var><dd>Set a catchpoint that is enabled only for one stop. The catchpoint is |
| automatically deleted after the first time the event is caught. |
| |
| </dl> |
| |
| <p>Use the <code>info break</code> command to list the current catchpoints. |
| |
| <p>There are currently some limitations to C<tt>++</tt> exception handling |
| (<code>catch throw</code> and <code>catch catch</code>) in <span class="sc">gdb</span>: |
| |
| <ul> |
| <li>If you call a function interactively, <span class="sc">gdb</span> normally returns |
| control to you when the function has finished executing. If the call |
| raises an exception, however, the call may bypass the mechanism that |
| returns control to you and cause your program either to abort or to |
| simply continue running until it hits a breakpoint, catches a signal |
| that <span class="sc">gdb</span> is listening for, or exits. This is the case even if |
| you set a catchpoint for the exception; catchpoints on exceptions are |
| disabled within interactive calls. |
| |
| <li>You cannot raise an exception interactively. |
| |
| <li>You cannot install an exception handler interactively. |
| </ul> |
| |
| <p><a name="index-raise-exceptions-261"></a>Sometimes <code>catch</code> is not the best way to debug exception handling: |
| if you need to know exactly where an exception is raised, it is better to |
| stop <em>before</em> the exception handler is called, since that way you |
| can see the stack before any unwinding takes place. If you set a |
| breakpoint in an exception handler instead, it may not be easy to find |
| out where the exception was raised. |
| |
| <p>To stop just before an exception handler is called, you need some |
| knowledge of the implementation. In the case of <span class="sc">gnu</span> C<tt>++</tt>, exceptions are |
| raised by calling a library function named <code>__raise_exception</code> |
| which has the following ANSI C interface: |
| |
| <pre class="smallexample"> /* <var>addr</var> is where the exception identifier is stored. |
| <var>id</var> is the exception identifier. */ |
| void __raise_exception (void **addr, void *id); |
| </pre> |
| <p class="noindent">To make the debugger catch all exceptions before any stack |
| unwinding takes place, set a breakpoint on <code>__raise_exception</code> |
| (see <a href="Breakpoints.html#Breakpoints">Breakpoints; Watchpoints; and Exceptions</a>). |
| |
| <p>With a conditional breakpoint (see <a href="Conditions.html#Conditions">Break Conditions</a>) |
| that depends on the value of <var>id</var>, you can stop your program when |
| a specific exception is raised. You can use multiple conditional |
| breakpoints to stop your program when any of a number of exceptions are |
| raised. |
| |
| </body></html> |
| |
