Using the command line interface of debug

Debugging C++ programs

The debugger recognizes programs compiled with the C++ Compilation System (release 2.0 or 3.0) or the C++ translator, cfront (release 2.1 or 3.0.x). It sets %db_lang to C++.

Expressions

When debugging C++ programs, names are shown as they appear in the C++ source and not as they appear in the object file.

When %db_lang is C++, debug accepts a subset of C++ expressions, which includes:

all expressions accepted when the current language is C,
calls to member functions, including virtual member functions, static member functions, and conversion functions,
expressions referencing members of anonymous unions,
calls to overloaded functions,
expressions using type names as typedefs,
expressions using overloaded operator functions, and
expressions accessing class members with an implied "this" pointer, when the process or thread is stopped in a class member function.

Displaying expressions

The print and set commands have the verbose option (-v) that prints the function prototype for any functions debug calls in evaluating the expressions. This is useful for understanding what is happening in expressions using overloaded functions or operators. The -v option to print will also display compiler-generated class members, such as pointers to virtual function tables.

If given a pointer to a base class object with virtual functions, and if debug can determine that the type of the object pointed to is a class derived from the base class, the whatis command displays both the base class and the derived class. The print command also displays the object in terms of the derived type.

Creating events

Breakpoints may be set on:

class member functions, including constructors, destructors, and conversion functions
overloaded operator functions
overloaded functions using the full prototype
overloaded functions without the prototype information. In this case, debug displays a list of the functions, and asks you to pick one or all of the choices.

A stop event may also be created in a specific object and member function combination using the syntax:

   stop pointer->function

   stop object.function1

debug stops the process or thread upon entering the function only if the "this" pointer matches the specified object. If the function is a virtual function, debug sets the breakpoint on the appropriate overriding function.

Exception handling

When an exception is thrown, and again when it is caught, the debugger will, by default, stop the process or thread and display the type of object being thrown. Between the throw point and the end of the catch handler you may examine the thrown object through the debugger variable %eh_object:

   debug> run
   EXCEPTION B * THROWN in p1 [main in eh_types.C]
   63:                              throw bptr;
   debug> whatis %eh_object
   B * (or D *)
   debug> print *%eh_object
   D
   {
       B::b=0
       d=17
   }

You may use the exception command to tell the debugger to ignore exceptions when they are thrown and/or caught. exception -i will tell the debugger to ignore exception throws or catches for the current process or thread only:

   debug> exception -i throw

exception -d -i will tell the debugger to ignore exception throws or catches for any processes subsequently created or grabbed:

   debug> exception -d -i catch

Issuing the command again without the -i option reestablishes the default behavior. Typing exception command without either throw or catch will cause it list the default behavior:

   debug> exception -d
   Default Exception Disposition
   throw   stopped
   catch   ignored
   debug> exception
   Exception Disposition for p1, program a.out
   throw   ignored
   catch   stopped

You may also create an event to take action when an exception of a specific type is thrown or caught. The type given may be any valid C++ type, and the actions will apply for any assignment-compatible object, as specified by the C++ language definition. Exception events will take place for matching types even if the default behavior is to ignore exceptions:

   debug> exception -i throw catch
   debug> exception throw const char * { print %eh_object }
   EVENT [1] assigned
   debug> run
   EXCEPTION char * THROWN in p1 [main in eh.C]
   7:                      throw "an exception!";
   "an exception!"

The ellipsis notation (``...'') may also be used to create an event to take place for any exception:

   debug> exception throw catch ... { print %eh_object }
   EVENT [2] assigned

There are several aspects of the debugger's behavior you should be aware of when dealing with a program using exceptions:

If an exception is thrown while an expression is being evaluated, the debugger will abort the expression evaluation. Any side effects of the expression, such as objects created on the stack, will be left in an indeterminate state.
When the debugger stops the process or thread on a throw or catch, the debugger will display the source for the throw-point or the catch handler, even though the process or thread is actually stopped in the runtime library code that manages exceptions. You will see that the current frame is not the frame on the top of the stack if you do a stack trace:
```
   debug> run
   EXCEPTION int  THROWN in p1 [main in eh_types.C]
   41:                             case 0: throw 17;
   debug> stack
   Stack Trace for p1, Program eh_types
    [0] debug_notifier(void)(presumed: 0xbfffdbd0, 0x8314938, 0)   [0x8048bcc]
    [1] __throw(presumed: 0xbfffdbd0, 0x8314938, 0)        [0x8049609]
   *[2] main(0x1, 0x804780c, 0x8047814)    [eh_types.C@41]
    [3] _start()   [0x80484c8]
```
If you go on to step at the instruction level you will continue executing the library code, not the code in the throwing function or catch handler. This is the only instance where the debugger automatically sets the current frame to something other than the top of the stack, but the event notification and commands such as list and symbols will therefore display information that you would presumably find more interesting.
The command run -r (for run to return) has no meaning in a function stopped at a throw-point. When you start the process or thread running again, control will be transferred to catch handler (or, depending on the circumstances, to the library functions terminate or unexpected) and the normal function return mechanism will be bypassed.

Creating a process will fail if an exception is thrown in a static constructor before the starting address (normally main). You may avoid this problem by telling the debugger to stop the process at an earlier point, such as _start or the failing constructor, and debugging as usual from there:

   debug> create a.out
   Error: Cannot handle exception during process startup: p1
   Error: Create failed: all resulting processes killed
   debug> create -l _start a.out
   New program a.out (process p1) created
   HALTED p1 [_start]
           0x8048510 (_start+0:)   	 pushl    $0x0
   debug> run
   EXCEPTION char * THROWN in p1 [A::A(void) in terminate.C]
   9:	A::A() { throw "in ctor\n"; }

In some cases, a program will terminate in the middle of throwing an exception and the debugger will not be able to tell you that an exception was thrown. This will happen when a throw-expression with no operand attempts to rethrow an exception and no exception is being handled, or when the evaluation of the object to be thrown causes another throw (as in an exception in a copy constructor). In either of these cases, creating a stop event on std::terminate will allow you to find the offending throw-point.

Templates

The name of a template function includes information about the template parameters and return type as well as function parameters. Since the function name generated by the compiler is usually not immediately obvious, the functions command may be used to display all or a subset of the functions available. For example, given the following program:

   main.c:
   	#include <stdlib.h>
   	#include "f_templ.h"
   
   	main(int argc, char **argv)
   	{
   		if (argc > 1)
   			fx(argv[1]);
   		exit(0);
   	}
   

   f_templ.h:
   	template <class T> void fx(T);
   

   f_templ.c:
   	#include <stream.h>
   

   	template <class T> void fx(T t)
   	{
   		cout << t << '\n';
   	}

The functions command will display the full signature for all instantiations of fx:

       debug> functions fx*
       fx<T1>(T1) [with T1=char *, return type=void]
       fx<T1>(T1) [with T1=int, return type=void]

You may sweep out the full name displayed by the functions command to use wherever a location is expected:

       debug> stop fx<T1>(T1) [with T1=char *, return type=void]
       EVENT [1] assigned

or use just the portion of the name up to the beginning of the functions argument list (the first top-level open parenthesis):

   debug> stop fx<T1>
   fx<T1> is overloaded. Enter the number of the function to use, or 0 (zero) to cancel:
   1  fx<T1>(T1) [with T1=char *, return type=void]
   2  fx<T1>(T1) [with T1=int, return type=void]
   3  All of the above
   >1
   EVENT [2] assigned

or use the name without the template argument list:

   debug> stop fx
   fx is overloaded. Enter the number of the function to use, or 0 (zero) to cancel:
   1  fx<T1>(T1) [with T1=char *, return type=void]
   2  fx<T1>(T1) [with T1=int, return type=void]
   3  All of the above
   >1
   EVENT [3] assigned