Setting Breakpoints

In dbx, you can use three commands to set breakpoints:

• stop – If the program arrives at a breakpoint created with a stop command, the program halts. The program cannot resume until you issue another debugging command, such as cont, step, or next.

• when – If the program arrives at a breakpoint created with a when command, the program halts and dbx executes one or more debugging commands, then the program continues unless one of the executed commands is stop.

• trace – A trace displays information about an event in your program, such as a change in the value of a variable. Although a trace’s behavior is different from that of a breakpoint, traces and breakpoints share similar event handlers. If a program arrives at a breakpoint created with a trace command, the program halts and an event-specific trace information line is emitted, then the program continues.

The stop, when, and trace commands all take as an argument an event specification, which describes the event on which the breakpoint is based. Event specifications are discussed in detail in Setting Event Specifications.

To set machine-level breakpoints, use the stopi, wheni, and tracei commands. For more information, see Debugging at the Machine-Instruction Level.

Setting a Breakpoint at a Line of Source Code

You can set a breakpoint at a line number by using the stop at command, where n is a source code line number and filename is an optional program file name qualifier.

(dbx) stop at filename:n

For example:

(dbx) stop at main.cc:3

If the line specified is not an executable line of source code, dbx sets the breakpoint at the next executable line. If there is no executable line, dbx issues an error.

You can determine the line at which you wish to stop by using the file command to set the current file and the list command to list the function in which you wish to stop. Then use the stop at command to set the breakpoint on the source line, as shown in the following example.

(dbx) file t.c
(dbx) list main
10    main(int argc, char *argv[])
11    {
12        char *msg = "hello world\n";
13        printit(msg);
14    }
(dbx) stop at 13

For more information on specifying at an location event, see at Event Specification.

Setting a Breakpoint in a Function

You can set a breakpoint in a function by using the stop in command.

(dbx) stop in function

An in -function breakpoint suspends program execution at the beginning of the first source line in a procedure or function.

dbx should be able to determine which function you are referring to except in the following situations:

• You reference an overloaded function by name only.

• You reference a function with a leading `.

• You reference a function by its linker name (mangled name in C++). In this case, dbx accepts the name if you prefix it with a #. For more information, see Linker Names.

Consider the following set of declarations:

int foo(double);
int foo(int);
int bar();
class x {
   int bar();
};

To stop at a non-member function, the following command sets a breakpoint at the global foo(int):

stop in foo(int)

To set a breakpoint at the member function:

stop in x::bar()

In the following command, dbx cannot determine whether you mean the global function foo(int) or the global function foo(double) and might be forced to display an overloaded menu for clarification.

stop in foo

If you type:

stop in `bar

dbx cannot determine whether you mean the global function bar() or the member function bar() and displays an overload menu.

For more information about specifying an in-function event, see in Event Specification.

Setting Multiple Breakpoints in C++ Programs

You can check for problems related to calls to members of different classes, calls to any members of a given class, or calls to overloaded top-level functions. You can use the keywords, inmember, inclass, infunction, or inobject with a stop, when, or trace command to set multiple breaks in C++ code.

Setting Breakpoints in Member Functions of Different Classes

To set a breakpoint in each of the class-specific variants of a particular member function (same member function name, different classes), use stop inmember.

For example, if the function draw is defined in several different classes, then to place a breakpoint in each function, type:

(dbx) stop inmember draw

For more information about specifying an inmember or inmethod event, see inmember Event Specification.

Setting Breakpoints in All Member Functions of a Class

To set a breakpoint in all member functions of a specific class, use the stop inclass command.

By default, breakpoints are inserted only in the class member functions defined in the class, not those that it might inherit from its base classes. To insert breakpoints in the functions inherited from the base classes also, specify the -recurse option.

The following command sets a breakpoint in all member functions defined in the class shape:

(dbx) stop inclass shape

The following command sets a breakpoint in all member functions defined in the class, and also in functions inherited from the class:

(dbx) stop inclass shape -recurse

For more information on specifying an inclass event, see inclass Event Specification and stop Command.

Due to the large number of breakpoints that might be inserted by stop inclass and other breakpoint selections, be sure to set the dbxenv variable step_events to on to speed up the step and next commands. For more information,see Efficiency Considerations.

Setting Multiple Breakpoints in Nonmember Functions

To set multiple breakpoints in nonmember functions with overloaded names (same name, different type or number of arguments), use the stop infunction command.

For example, if a C++ program has defined two versions of a function named sort(), one that passes an int type argument and the other a float, then the following command would place a breakpoint in both functions:

(dbx) stop infunction sort 

For more information on specifying an infunction event, see infunction Event Specification.

Setting Breakpoints in Objects

Set an in-object breakpoint to check the operations applied to a specific object instance.

Use in-object breakpoints to stop program execution when any method is called on a specific object instance. For example, the following code will only cause a stop when f1->printit() is called:

Foo *f1 = new Foo();
Foo *f2 = new Foo();
 f1->printit();
 f2->printit();

(dbx) stop inobject f1

The address stored in f1 identifies the objects you put a breakpoint on. This implies that this breakpoint can only be created after the object in f1 has been instantiated.

By default, an in-object breakpoint suspends program execution in all nonstatic member functions of the object’s class, including inherited ones. To restrict breakpoints only to the objects class, specify the -norecurse option.

To set a breakpoint in all nonstatic member functions defined in the base class of object foo and in all nonstatic member functions defined in inherited classes of object foo:

(dbx) stop inobject &foo

To set a breakpoint in all nonstatic member functions defined in the class of object foo, but not those defined in inherited classes of object foo:

(dbx) stop inobject &foo -norecurse

For more information on specifying an inobject event, see inobject Event Specification and stop Command.

Setting Data Change Breakpoints (Watchpoints)

You can use data change breakpoints, otherwise known as watchpoints, in dbx to note when the value of a variable or expression has changed.

Stopping Execution When an Address Is Accessed

Use the stop access command to stop execution when a memory address has been accessed:

(dbx) stop access mode address-expression [, byte-size-expression]

mode specifies how the memory was accessed. The valid mode options are:

r

The memory at the specified address has been read.

w

The memory has been written to.

x

The memory has been executed.

mode can also contain either of the following:

a

Stops the process after the access (default).

b

Stops the process before the access.

In both cases the program counter will point at the accessing instruction. The “before” and “after” refer to the side effect.

address-expression is any expression that can be evaluated to produce an address. If you provide a symbolic expression, the size of the region to be watched is automatically deduced. You can override it by specifying byte-size-expression. You can also use nonsymbolic, typeless address expressions in which case, the size is mandatory.

In the following example, the command will stop execution after any of the four bytes after the memory address 0x4762 has been read.

(dbx) stop access r 0x4762, 4

In the following example, execution will stop before the variable speed has be written to:

(dbx) stop access wb &speed

Keep these points in mind when using the stop access command:

• The event occurs when a variable is written to even if it is the same value.

• By default, the event occurs after execution of the instruction that wrote to the variable. You can indicate that you want the event to occur before the instruction is executed by specifying the mode as b.

For more information on specifying an access event, see access Event Specification and stop Command.

Stopping Execution When Variables Change

Use the stop change command to stop program execution if the value of a specified variable has changed:

(dbx) stop change variable

Keep these points in mind when using the stop change command:

• dbx stops the program at the line after the line that caused a change in the value of the specified variable.

• If variable is local to a function, the variable is considered to have changed when the function is first entered and storage for variable is allocated. The same is true with respect to parameters.

• The command does not work with multithreaded applications.

For more information on specifying a change event, see change Event Specification and stop Command.

dbx implements stop change by causing automatic single-stepping together with a check on the value at each step. Stepping skips over library calls if the library was not compiled with the -g option. So, if control flows in the following manner, dbx does not trace the nested user_routine2 because tracing skips the library call and the nested call to user_routine2.

   user_routine calls
      library_routine, which calls
        user_routine2, which changes variable

The change in the value of variable appears to have occurred after the return from the library call, not in the middle of user_routine2.

dbx cannot set a breakpoint for a change in a block local variable (a variable nested in {}). If you try to set a breakpoint or trace in a block local nested variable, dbx issues an error informing you that it cannot perform this operation.

Stopping Execution on a Condition

Use thestop cond command to stop program execution if a conditional statement evaluates to true:

(dbx) stop cond condition

The program stops executing when the condition occurs.

Keep these points in mind when using the stop cond command:

• dbx stops the program at the line after the line that caused the condition to evaluate to true.

• The command does not work with multithreaded applications.

For more information about specifying a condition event, see cond Event Specification and stop Command.