5.1.3 Setting Catchpoints
- Stop when event occurs. event can be any of the following:
- The throwing of a C++ exception.
- The catching of a C++ 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_Erroris defined in package
Pck, then the command to use to catch such exceptions is catch exception Pck.Constraint_Error.
- An exception that was raised but is not handled by the program.
- A failed Ada assertion.
- A call to
exec. This is currently only available for HP-UX and gnu/Linux.
syscall[name | number]
- 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 (see command 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).
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' ) (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)
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.
- A call to
fork. This is currently only available for HP-UX and gnu/Linux.
- A call to
vfork. This is currently only available for HP-UX and gnu/Linux.
- Set a catchpoint that is enabled only for one stop. The catchpoint is automatically deleted after the first time the event is caught.
info break command to list the current catchpoints.
There are currently some limitations to C++ exception handling
catch throw and
catch catch) in gdb:
- 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.
- You cannot raise an exception interactively.
- You cannot install an exception handler interactively.
catch 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 before 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.
To stop just before an exception handler is called, you need some
knowledge of the implementation. In the case of gnu C++, exceptions are
raised by calling a library function named
which has the following ANSI C interface:
/* addr is where the exception identifier is stored. id is the exception identifier. */ void __raise_exception (void **addr, void *id);
To make the debugger catch all exceptions before any stack
unwinding takes place, set a breakpoint on
(see Breakpoints; Watchpoints; and Exceptions).
With a conditional breakpoint (see Break Conditions) that depends on the value of id, 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.