dwhere

Displays the current execution location and call stack

Format: 

Displays locations in the call stack

dwhere [ -level level-num ] [ num-levels ] [ -args ] [ -locals ] [ -registers ]
[ -noshow_pc ][ -noshow_fp ][ -show_image ][-group_by property ]

Displays all locations in the call stack

dwhere -all [ -args ] [ -locals ] [-registers ]
[ -noshow_pc ][ -noshow_fp ][ -show_image ]

Arguments: 

-all

Shows all levels of the call stack. This is the default.

-level level-num

Sets the level at which dwhere starts displaying information.

num-levels

Restricts output to this number of levels of the call stack. By default, all levels are shown.

-args

Displays argument names and values in addition to program location information. By default, the arguments are not shown.

-locals

Displays each frame’s local variables. By default, the local variable information is not shown.

-noshow_pc

Does not show the PC. By default, the PC value is shown.

-noshow_fp

Does not show the FP. By default, the FP value is shown.

-registers

Displays each frame’s registers. By default, the register information is not shown.

-show_image

Shows the executable name as well as the file name. By default, dwhere displays the associated image information if the source line cannot be found.

-group_by property

Aggregates stack backtraces of the focus threads, outputting a compressed ptlist that identifies the processes and threads containing equivalent stack frames in the backtrace. For information on the ptlist syntax, see Compressed List Syntax (ptlist).

This option requires a property argument to control the “equivalence” relationship of stack frames across the threads. See The -group_by Option for more information.

Description: 

The dwhere command prints the current execution locations and the call stacks—or sequences of procedure calls—that led to that point. The CLI shows information for threads in the current focus; the default shows information at the thread level.

Arguments control the amount of command output in two ways:

The num-levels argument determines how many levels of the call stacks are displayed, counting from the uppermost (most recent) level. Without this argument, the CLI shows all levels in the call stack, which is the default.

The -a option displays procedure argument names and values for each stack level.

A dwhere command with no arguments or options displays the call stacks for all threads in the target set.

The MAX_LEVELS variable contains the default maximum number of levels displayed when you do not use the num-levels argument.

Output is generated for each thread in the target focus. The output is printed directly to the console.

The -group_by Option

The -group_by option requires a property argument, which controls the “equivalence” relationship of stack frames across the threads. When you use the -group_by option, dwhere aggregates the stack frames of each of the focus threads, forming a tree of equivalent stack frames.

Starting at the base of the stack (closest to main() or the thread's start function), the dwhere command assigns each frame a distance from a synthetic root frame indicated by /. Two frames are equivalent only if all of the following apply:

Their distance from the root is equal.

They have the same parent frame.

The selected property of frames is equivalent.

The following property values are supported, with their abbreviations in parentheses:

function (f): Equivalence based on the name of the function containing the PC for the frame.

function+line (f+l): Equivalence based on the name of the function and the file and line number containing the PC for the frame.

function+offset (f+o): Equivalence based on the name of the function containing the PC for the frame and offset from the beginning of the function to the PC for the frame.

function+pc (f+pc): Equivalence based on the PC value for the frame.

Looking at backtraces purely by the function property is the most coarse grained grouping of threads. Choosing a more fine grained grouping, such as a line number within the function, provides more detail about where in the code a given thread is executing, but it may also result in a much larger set of equivalent frames.

The dwhere command displays the current execution location(s) and the backtrace(s) for the threads in the current focus. If backtraces for multiple threads are requested, the stack displays are aggregated.

Lines denoting evaluation frames for compiled expressions or interpreted function calls are labeled with a suspended evaluation id. This id can be used to manipulate suspended evaluations with dflush and TV::expr.

Command alias: 

 

Alias	Definition	Description
w	dwhere	Displays the current location in the call stack

Examples: 

dwhere

Displays the call stacks for all threads in the current focus.

dfocus 2.1 dwhere 1

Displays just the most recent level of the call stack corresponding to thread 1 in process 2. This shows just the immediate execution location of a thread or threads.

f p1.< w 5

Displays the most recent five levels of the call stacks for all threads involved in process 1. If the depth of any call stack is less than five levels, all of its levels are shown.

This command is a slightly more complicated way of saying f p1 w 5 because specifying a process width tells the dwhere command to ignore the thread indicator.

w 1 -a

Displays the current execution locations (one level only) of threads in the current focus, together with the names and values of any arguments that were passed into the current process.