dbreak
Defines a breakpoint
Format
Creates a breakpoint at a source location
dbreak breakpoint-expr [ -p | -g | -t ] [ [ -l lang ] -e expr ] [ -pending ]
Creates a breakpoint at an address
dbreak -address addr [ -p | -g | -t] [ [ -l lang ] -e expr ] [ -pending ]
Arguments
breakpoint-expr
This argument can be entered in more than one way, usually using a line number or a pathname containing a file name, function name, and line number, each separated by # characters (for example, file#line). For more information, see “Qualifying Symbol Names” in Chapter 13 of the TotalView User Guide.
Breakpoint expressions are discussed later in this section.
-address addr
The breakpoint location specified as an absolute address in the address space of the program.
-p
Stops the process that hit this breakpoint. You can set this option as the default by setting the STOP_ALL variable to process. See
dset for more information.
-g
Stops all processes in the process’s control group when execution reaches the breakpoint. You can set this option as the default by setting the STOP_ALL variable to group.See
dset for more information.
-t
Stops the thread that hit this breakpoint. You can set this option as the default by setting the STOP_ALL variable to thread. See
dset for more information.
-l lang
Sets the programming language used when you are entering expression expr. Enter either: c, c++, f7, f9, or asm (for C, C++, FORTRAN 77, Fortran 9x, and assembler, respectively). If you do not specify a language, TotalView assumes the language in which the routine at the breakpoint was written.
-e expr
When the breakpoint is hit, TotalView evaluates expression expr in the context of the thread that hit the breakpoint. The language statements and operators you can use are described in “Chapter 16, Setting Action Points”, of the TotalView User Guide.
-pending
If TotalView cannot find a location to set the breakpoint, adding this option creates the breakpoint anyway. As shared libraries are read, TotalView checks to see if it can be set in the newly loaded library.
Description
The dbreak command defines a breakpoint or evaluation point triggered when execution arrives at the specified location, stopping each thread that arrives at a breakpoint. This command returns the ID of the new breakpoint. If a line does not contain an executable statement, the CLI cannot set a breakpoint.
If you try to set a breakpoint at a line at which TotalView cannot stop execution, it sets one at the nearest following line where it can halt execution.
Specifying a procedure name without a line number sets an action point at the beginning of the procedure. If you do not name a file, the default is the file associated with the current source location.
The -pending Option
If, after evaluating the breakpoint expression, TotalView determines the location represented by the expression does not exist, it can still set a breakpoint if you use the -pending option. This option checks shared libraries that are subsequently loaded to see if a breakpoint can be set. If a location is found, it is set. Stated in a different way, TotalView normally creates and sets a breakpoint at the same time. The option tells it to separate these two actions.
When the displaying information on a breakpoint’s status, the CLI displays the location where execution actually stops.
A stop group Breakpoint
If the CLI encounters a stop group breakpoint, it suspends each process in the group as well as the process that contains the triggering thread. The CLI then shows the identifier of the triggering thread, the breakpoint location, and the action point identifier.
Default Focus Width
TotalView determines the default focus width based on the setting of the
SHARE_ACTION_POINT variable. If set to
true, the default is group. Otherwise, it is process.
Breakpoint Expressions
Breakpoint expressions, also called breakpoint specifications, are used in both breakpoints and barrier points, so this discussion is relevant to both.
One possibly confusing aspect of using expressions is that their syntax differs from that of Tcl. This is because you need to embed code written in Fortran, C, or assembler in Tcl commands. In addition, your expressions often include TotalView built-in functions. For example, if you want to use the TotalView $tid built-in function, you need to type it as \$tid.
A breakpoint expression can evaluate to more than one source line. If the expression evaluates to a function that has multiple overloaded implementations, TotalView sets a breakpoint on each of the overloaded functions.
Set a breakpoint at the line specified by breakpoint-expr or the absolute address addr. You can enter a breakpoint expression that are sets of addresses at which the breakpoint is placed, and are as follows:
• [[##image#]filename#]line_number
Indicates all addresses at this line number.
• A function signature; this can be a partial signature.
Indicates all addresses that are the addresses of functions matching signature. If parts of a function signature are missing, this expression can match more than one signature. For example, “f” matches “f(void)” and “A::f(int)“. You cannot specify a return type in a signature.
• class class_name
Specifies that the breakpoint should be planted in all member functions of class class_name.
• virtual class::signature
Specifies that the breakpoint should be planted in all virtual member functions that match signature and are in the class or derived from the class.
Command alias
Alias | Definition | Description |
b | break | Sets a breakpoint |
bt | {dbreak t} | Sets a breakpoint only on the thread of interest |
Examples
For all examples, assume that the current process set is d2.< when the breakpoint is defined.
dbreak 12
Suspends process 2 when it reaches line 12. However, if the STOP_ALL variable is set to group, all other processes in the group are stopped. In addition, if SHARE_ACTION_POINT is true, the breakpoint is placed in every process in the group.
dbreak -address 0x1000764
Suspends process 2 when execution reaches address 0x1000764.
b 12 -g
Suspends all processes in the current control group when execution reaches line 12.
dbreak 57 -l f9 -e {goto $63}
Causes the thread that reaches the breakpoint to transfer to line 63. The host language for this statement is Fortran 90 or Fortran 95.
dfocus p3 b 57 -e {goto $63}
In process 3, sets the same evaluation point as the previous example.