326 lines
18 KiB
HTML
326 lines
18 KiB
HTML
|
<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-2019 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>
|
||
|
|
</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-284"></a><a name="index-exception-handlers-285"></a><a name="index-event-handling-286"></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-287"></a>
|
||
|
|
<dl><dt><code>catch </code><var>event</var><dd>Stop when <var>event</var> occurs. The <var>event</var> can be any of the following:
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><code>throw </code><span class="roman">[</span><var>regexp</var><span class="roman">]</span><dt><code>rethrow </code><span class="roman">[</span><var>regexp</var><span class="roman">]</span><dt><code>catch </code><span class="roman">[</span><var>regexp</var><span class="roman">]</span><dd><a name="index-catch-throw-288"></a><a name="index-catch-rethrow-289"></a><a name="index-catch-catch-290"></a><a name="index-stop-on-C_0040t_007b_002b_002b_007d-exceptions-291"></a>The throwing, re-throwing, or catching of a C<tt>++</tt> exception.
|
||
|
|
|
||
|
|
<p>If <var>regexp</var> is given, then only exceptions whose type matches the
|
||
|
|
regular expression will be caught.
|
||
|
|
|
||
|
|
<p><a name="index-g_t_0024_005fexception_0040r_007b_002c-convenience-variable_007d-292"></a>The convenience variable <code>$_exception</code> is available at an
|
||
|
|
exception-related catchpoint, on some systems. This holds the
|
||
|
|
exception being thrown.
|
||
|
|
|
||
|
|
<p>There are currently some limitations to C<tt>++</tt> exception handling in
|
||
|
|
<span class="sc">gdb</span>:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The support for these commands is system-dependent. Currently, only
|
||
|
|
systems using the ‘<samp><span class="samp">gnu-v3</span></samp>’ C<tt>++</tt> ABI (see <a href="ABI.html#ABI">ABI</a>) are
|
||
|
|
supported.
|
||
|
|
|
||
|
|
<li>The regular expression feature and the <code>$_exception</code> convenience
|
||
|
|
variable rely on the presence of some SDT probes in <code>libstdc++</code>.
|
||
|
|
If these probes are not present, then these features cannot be used.
|
||
|
|
These probes were first available in the GCC 4.8 release, but whether
|
||
|
|
or not they are available in your GCC also depends on how it was
|
||
|
|
built.
|
||
|
|
|
||
|
|
<li>The <code>$_exception</code> convenience variable is only valid at the
|
||
|
|
instruction at which an exception-related catchpoint is set.
|
||
|
|
|
||
|
|
<li>When an exception-related catchpoint is hit, <span class="sc">gdb</span> stops at a
|
||
|
|
location in the system library which implements runtime exception
|
||
|
|
support for C<tt>++</tt>, usually <code>libstdc++</code>. You can use <code>up</code>
|
||
|
|
(see <a href="Selection.html#Selection">Selection</a>) to get to your code.
|
||
|
|
|
||
|
|
<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. See <a href="Calling.html#Calling">Calling</a>, for information on
|
||
|
|
controlling this with <code>set unwind-on-terminating-exception</code>.
|
||
|
|
|
||
|
|
<li>You cannot raise an exception interactively.
|
||
|
|
|
||
|
|
<li>You cannot install an exception handler interactively.
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<br><dt><code>exception</code><dd><a name="index-catch-exception-293"></a><a name="index-Ada-exception-catching-294"></a><a name="index-catch-Ada-exceptions-295"></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>handlers</code><dd><a name="index-catch-handlers-296"></a><a name="index-Ada-exception-handlers-catching-297"></a><a name="index-catch-Ada-exceptions-when-handled-298"></a>An Ada exception being handled. If an exception name is
|
||
|
|
specified at the end of the command
|
||
|
|
(eg <kbd>catch handlers Program_Error</kbd>), the debugger will stop
|
||
|
|
only when this specific exception is handled.
|
||
|
|
Otherwise, the debugger stops execution when any Ada exception is handled.
|
||
|
|
|
||
|
|
<p>When inserting a handlers 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 handling is
|
||
|
|
<kbd>catch handlers Pck.Constraint_Error</kbd>.
|
||
|
|
|
||
|
|
<br><dt><code>exception unhandled</code><dd><a name="index-catch-exception-unhandled-299"></a>An exception that was raised but is not handled by the program.
|
||
|
|
|
||
|
|
<br><dt><code>assert</code><dd><a name="index-catch-assert-300"></a>A failed Ada assertion.
|
||
|
|
|
||
|
|
<br><dt><code>exec</code><dd><a name="index-catch-exec-301"></a><a name="index-break-on-fork_002fexec-302"></a>A call to <code>exec</code>.
|
||
|
|
|
||
|
|
<p><a name="catch-syscall"></a><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> <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> ...</code><dd><a name="index-catch-syscall-303"></a><a name="index-break-on-a-system-call_002e-304"></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>You may specify a group of related syscalls to be caught at once using
|
||
|
|
the <code>group:</code> syntax (<code>g:</code> is a shorter equivalent). For
|
||
|
|
instance, on some platforms <span class="sc">gdb</span> allows you to catch all
|
||
|
|
network related syscalls, by passing the argument <code>group:network</code>
|
||
|
|
to <code>catch syscall</code>. Note that not all syscall groups are
|
||
|
|
available in every system. You can use the command completion
|
||
|
|
facilities (see <a href="Completion.html#Completion">command completion</a>) to list the
|
||
|
|
syscall groups available on your environment.
|
||
|
|
|
||
|
|
<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>Here is an example of catching a syscall group:
|
||
|
|
|
||
|
|
<pre class="smallexample"> (gdb) catch syscall group:process
|
||
|
|
Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7]
|
||
|
|
'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190]
|
||
|
|
'exit_group' [252] 'waitid' [284] 'unshare' [310])
|
||
|
|
(gdb) r
|
||
|
|
Starting program: /tmp/catch-syscall
|
||
|
|
|
||
|
|
Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 ()
|
||
|
|
from /lib64/ld-linux-x86-64.so.2
|
||
|
|
|
||
|
|
(gdb) c
|
||
|
|
Continuing.
|
||
|
|
</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 name="index-catch-fork-305"></a>A call to <code>fork</code>.
|
||
|
|
|
||
|
|
<br><dt><code>vfork</code><dd><a name="index-catch-vfork-306"></a>A call to <code>vfork</code>.
|
||
|
|
|
||
|
|
<br><dt><code>load </code><span class="roman">[</span><code>regexp</code><span class="roman">]</span><dt><code>unload </code><span class="roman">[</span><code>regexp</code><span class="roman">]</span><dd><a name="index-catch-load-307"></a><a name="index-catch-unload-308"></a>The loading or unloading of a shared library. If <var>regexp</var> is
|
||
|
|
given, then the catchpoint will stop only if the regular expression
|
||
|
|
matches one of the affected libraries.
|
||
|
|
|
||
|
|
<br><dt><code>signal </code><span class="roman">[</span><var>signal</var><code>... </code><span class="roman">|</span><code> ‘</code><samp><span class="samp">all</span></samp><code>’</code><span class="roman">]</span><dd><a name="index-catch-signal-309"></a>The delivery of a signal.
|
||
|
|
|
||
|
|
<p>With no arguments, this catchpoint will catch any signal that is not
|
||
|
|
used internally by <span class="sc">gdb</span>, specifically, all signals except
|
||
|
|
‘<samp><span class="samp">SIGTRAP</span></samp>’ and ‘<samp><span class="samp">SIGINT</span></samp>’.
|
||
|
|
|
||
|
|
<p>With the argument ‘<samp><span class="samp">all</span></samp>’, all signals, including those used by
|
||
|
|
<span class="sc">gdb</span>, will be caught. This argument cannot be used with other
|
||
|
|
signal names.
|
||
|
|
|
||
|
|
<p>Otherwise, the arguments are a list of signal names as given to
|
||
|
|
<code>handle</code> (see <a href="Signals.html#Signals">Signals</a>). Only signals specified in this list
|
||
|
|
will be caught.
|
||
|
|
|
||
|
|
<p>One reason that <code>catch signal</code> can be more useful than
|
||
|
|
<code>handle</code> is that you can attach commands and conditions to the
|
||
|
|
catchpoint.
|
||
|
|
|
||
|
|
<p>When a signal is caught by a catchpoint, the signal's <code>stop</code> and
|
||
|
|
<code>print</code> settings, as specified by <code>handle</code>, are ignored.
|
||
|
|
However, whether the signal is still delivered to the inferior depends
|
||
|
|
on the <code>pass</code> setting; this can be changed in the catchpoint's
|
||
|
|
commands.
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
|
||
|
|
<br><dt><code>tcatch </code><var>event</var><dd><a name="index-tcatch-310"></a>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.
|
||
|
|
|
||
|
|
</body></html>
|
||
|
|
|