gdb: Set Catchpoints
5.1.3 Setting Catchpoints
-------------------------
You can use "catchpoints" to cause the debugger to stop for certain
kinds of program events, such as C++ exceptions or the loading of a
shared library. Use the 'catch' command to set a catchpoint.
'catch EVENT'
Stop when EVENT occurs. The EVENT can be any of the following:
'throw [REGEXP]'
'rethrow [REGEXP]'
'catch [REGEXP]'
The throwing, re-throwing, or catching of a C++ exception.
If REGEXP is given, then only exceptions whose type matches
the regular expression will be caught.
The convenience variable '$_exception' is available at an
exception-related catchpoint, on some systems. This holds the
exception being thrown.
There are currently some limitations to C++ exception handling
in GDB:
* The support for these commands is system-dependent.
Currently, only systems using the 'gnu-v3' C++ ABI (
ABI) are supported.
* The regular expression feature and the '$_exception'
convenience variable rely on the presence of some SDT
probes in 'libstdc++'. 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.
* The '$_exception' convenience variable is only valid at
the instruction at which an exception-related catchpoint
is set.
* When an exception-related catchpoint is hit, GDB stops at
a location in the system library which implements runtime
exception support for C++, usually 'libstdc++'. You can
use 'up' (Selection) to get to your code.
* If you call a function interactively, GDB 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 GDB 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. Calling, for information on controlling
this with 'set unwind-on-terminating-exception'.
* You cannot raise an exception interactively.
* You cannot install an exception handler interactively.
'exception'
An Ada exception being raised. If an exception name is
specified at the end of the command (eg 'catch exception
Program_Error'), the debugger will stop only when this
specific exception is raised. Otherwise, the debugger stops
execution when any Ada exception is raised.
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, GDB will assume that it
should stop on the pre-defined exception rather than the
user-defined one. For instance, assuming an exception called
'Constraint_Error' is defined in package 'Pck', then the
command to use to catch such exceptions is 'catch exception
Pck.Constraint_Error'.
'handlers'
An Ada exception being handled. If an exception name is
specified at the end of the command (eg 'catch handlers
Program_Error'), the debugger will stop only when this
specific exception is handled. Otherwise, the debugger stops
execution when any Ada exception is handled.
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, GDB will assume that it
should stop on the pre-defined exception rather than the
user-defined one. For instance, assuming an exception called
'Constraint_Error' is defined in package 'Pck', then the
command to use to catch such exceptions handling is 'catch
handlers Pck.Constraint_Error'.
'exception unhandled'
An exception that was raised but is not handled by the
program.
'assert'
A failed Ada assertion.
'exec'
A call to 'exec'.
'syscall'
'syscall [NAME | NUMBER | group:GROUPNAME | g:GROUPNAME] ...'
A call to or return from a system call, a.k.a. "syscall". A
syscall is a mechanism for application programs to request a
service from the operating system (OS) or one of the OS system
services. GDB 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.
NAME 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 '/usr/include/asm/unistd.h'.
Normally, GDB knows in advance which syscalls are valid for
each OS, so you can use the GDB command-line completion
facilities (command completion Completion.) to list the
available choices.
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, GDB uses its database of syscalls to convert the
name into the corresponding numeric code, but using the number
directly may be useful if GDB's database does not have the
complete list of syscalls on your system (e.g., because GDB
lags behind the OS upgrades).
You may specify a group of related syscalls to be caught at
once using the 'group:' syntax ('g:' is a shorter equivalent).
For instance, on some platforms GDB allows you to catch all
network related syscalls, by passing the argument
'group:network' to 'catch syscall'. Note that not all syscall
groups are available in every system. You can use the command
completion facilities (command completion Completion.)
to list the syscall groups available on your environment.
The example below illustrates how this command works if you
don't provide arguments to it:
(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)
Here is an example of catching a system call by name:
(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)
An example of specifying a system call numerically. In the
case below, the syscall number has a corresponding entry in
the XML file, so GDB finds its name and prints it:
(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)
Here is an example of catching a syscall group:
(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.
However, there can be situations when there is no
corresponding name in XML file for that syscall number. In
this case, GDB 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:
(gdb) catch syscall 764
warning: The number '764' does not represent a known syscall.
Catchpoint 2 (syscall 764)
(gdb)
If you configure GDB using the '--without-expat' 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:
(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)
Of course, the file name will change depending on your
architecture and system.
Still using the example above, you can also try to catch a
syscall by its number. In this case, you would see something
like:
(gdb) catch syscall 252
Catchpoint 1 (syscall(s) 252)
Again, in this case GDB would not be able to display syscall's
names.
'fork'
A call to 'fork'.
'vfork'
A call to 'vfork'.
'load [regexp]'
'unload [regexp]'
The loading or unloading of a shared library. If REGEXP is
given, then the catchpoint will stop only if the regular
expression matches one of the affected libraries.
'signal [SIGNAL... | 'all']'
The delivery of a signal.
With no arguments, this catchpoint will catch any signal that
is not used internally by GDB, specifically, all signals
except 'SIGTRAP' and 'SIGINT'.
With the argument 'all', all signals, including those used by
GDB, will be caught. This argument cannot be used with other
signal names.
Otherwise, the arguments are a list of signal names as given
to 'handle' (Signals). Only signals specified in this
list will be caught.
One reason that 'catch signal' can be more useful than
'handle' is that you can attach commands and conditions to the
catchpoint.
When a signal is caught by a catchpoint, the signal's 'stop'
and 'print' settings, as specified by 'handle', are ignored.
However, whether the signal is still delivered to the inferior
depends on the 'pass' setting; this can be changed in the
catchpoint's commands.
'tcatch EVENT'
Set a catchpoint that is enabled only for one stop. The catchpoint
is automatically deleted after the first time the event is caught.
Use the 'info break' command to list the current catchpoints.
Info Catalog
gdb: Set Watchpoints
gdb: Breakpoints
gdb: Delete Breaks