dbreak
Defines a breakpoint
Format
Creates a breakpoint at a source location
dbreak breakpoint-expr [ -p| -g | -t ] [ [ -llang ] -e expr ] [ -pending ]
Creates a breakpoint at an absolute 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”.
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.
-llang
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. See Breakpoint Expressions.
-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 allows a breakpoint to be created when the breakpoint expression does not currently match any program locations. For example, a common use case is to create a pending function breakpoint with a breakpoint expression that matches the name of a function that will be loaded at runtime via dlopen(), CUDA kernel launch, or anything that dynamically loads executable code.
When displaying information on a pending breakpoint’s status, TotalView displays the breakpoint expression followed by "(pending)" indicating that the breakpoint currently contains no valid addresses.
Note that using this option doesn’t catch typos or errors in the user's input. For example, if you want to set a breakpoint on a function foo, but you typed voo instead, a pending breakpoint is immediately created for the function voo, which would not be your intention.
To set dbreak to always use the -pending option, use the TV::default_breakpoints_pending state variable.
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 $tidbuilt-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_numberIndicates 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_nameSpecifies that the breakpoint should be planted in all member functions of class class_name.
virtual class::signatureSpecifies 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.
Related Topics
