dstacktransform
Maintains rules that change the displayed stack frames
Format
Enables or disables the stack transform facility.
dstacktransform [enable | disableid | transform_name ]
Prints the current state of rules and transforms.
dstacktransform [list]
Prints the enabled/disabled state of the stack transform facility.
dstacktransform [status]
Removes the rule with the given id from the stack transform facility.
dstacktransform [remove id]
Adds a new transform.
dstacktransform add [-name | -n string] [-implementation | -ipath ]
Adds a new transform rule.
dstacktransform add [-filter test_function_list] [-transform | -t name] [-operation | -o operation_name [-position | -p integer ] [-before | -b integer ]
Arguments
id
A rule’s ID number.
transform_name
A transform’s name.
-filter | -f test_function_list
Required argument for all rules. Its value test_function_list is a comma-separated list of filter functions.
-implementation | -i path
The path of a script or shared library that supports the modify operation.
NOTE: This is not implemented in the current release. The only implemented transforms are provided by the debugger and are listed as built-in using dstacktransform list.
-name | -n string
A transform’s name.
-transform | -t name
Indicates the transform name that provides the implementation of the modify operation. This name can also be used to enable and disable groups of rules.
-operation | -o operation_name
The action to be invoked if the filter matches the current frame. The allowed operations are remove, modify, and next:
remove: Hides the current stack frame.
modify: Invokes a transform function to change the name and behavior of the stack frame. Currently, user transforms cannot use the modify operation.
next: Ends processing of the current stack frame without changes. Rules lower in the transform list are not evaluated, and processing the stack continues with the next stack frame.
The default is remove, which is used if no -operation option is provided.
-position | -p integer
Puts the new rule at the given ordinal position in the transform's list of rules.
-before |-b integer
Puts the new rule before the rule with the given id. If no -position or -beforeoption is given, the new rule is placed at the end of the transform's rule list.
Description
The stack transform facility (STF) maintains a list of rules that modify the list of stack frames shown in the stack trace view and the dwhere command. These rules are tested, starting at the top of the list, until a rule passes the tests and is applied. The various subcommands of dstacktransform maintain the list of rules.
Each rule has a filter that runs one or more tests on elements of each stack frame. Some tests compare the function name or image path with a regular expression. Other tests look for a loader symbol in the image associated with the frame. If the tests pass, an operation is run that controls the application of rules or modifies the stack by adding, removing, or re-writing one or more frames on the stack. If the tests pass and an operation is run, no further action is taken on that frame and processing continues to the next stack frame.
Rules can refer to transforms. Transforms contain code that is run when modify operations are invoked by rules.
NOTE: Currently, you cannot load your own transforms, and the debugger supplies a default transform for Python frames. Although you can define new transforms without implementing code, these are useful only to group a number of rules under a common name for enabling and disabling.
About a Rule’s Filter
The -filter or -fargument is required for all rules. The value of the filter is a comma-separated list of filter functions. Each function can be one of:
function(<regular_expression>): This matches the function name in the stack frame against the given regular expression.
image(<regular_expression>): This matches the image path in the stack frame against the given regular expression.
symbol(<string>): Looks for the string in the list of loader symbols defined in the image associated with the stack frame.
All the filter functions must match for a rule's operation to be invoked.
NOTE: The TCL interpreter that reads these commands will try to interpret common regular expression syntax. For example, TCL considers text inside square brackets as a function to be evaluated. To prevent TCL from trying to evaluate regular expression character sets as functions, surround either the regular expression or the entire filter function in double-quotes " or curly braces {}.
About a Rule’s ID
When a rule is created, it is assigned a unique id by the debugger. This id is returned by the dstacktransform addcommand. Use this id to manage the rule, for instance, to disable it:
> set id [dstacktransform add -filter "function('_start')"]
> dstacktransform disable $id
The List Subcommand
The list subcommand prints the current state of rules and transforms. The rules are applied to each stack frame in the order shown in the list.
This example adds a rule and then prints the list of rules followed by the list of transforms:
> sta -f function('_init') -p 1
4
> dstacktransform list
Transformation Status: Enabled
Rules
ID Transform Operation Filter
4 remove function('_init')
1 RW_Python modify function('PyEval_EvalFrameEx')
2 RW_Python remove symbol('Py_DebugFlag')
Transforms
Name Implementation
RW_Python <built-in>
Command alias
Alias | Definition | Description |
|---|
ste | dstacktransform enable | Enables the stack transform facility. |
std | dstacktransform disable | Disables the stack transform facility. |
sta | dstacktransform add | Adds a new transform or rule. |
str | dstacktransform remove | Removes a transform. |
stl | dstacktransform list | Prints the current rules and transforms and their states. |
sts | dstacktransform status | Prints the enabled/disabled state of the stack transform facility. |
Examples
dstacktransform enable 10
ste 10
Enables the rule identified by the id 10.
dstacktransform disable 10
std 10
Disables the rule identified by the id 10.
dstacktransform add -t MY_PYTHON -f "function('_start')" -o remove -p 0
Adds a new rule associated with the MY_PYTHON transform. The rule has a filter named function('_start'), which tries to match the pattern _start with the function name in the current stack frame. If they match, the frame is removed. This new rule is placed at the top of the list of rules.
After adding the rule above, enter dstacktransform list to view it and other rules:
> dstacktransform list
Transformation Status: Enabled
Rules
ID Transform Operation Filter
5 MY_PYTHON remove function('_start')
4 remove function('_init')
1 RW_Python modify function('PyEval_EvalFrameEx'),symbol('Py_DebugFlag')
2 RW_Python remove symbol('Py_DebugFlag')
3 RW_Python remove function('wrap'),symbol('SWIG_globals')
Transforms
Name Implementation
RW_Python <built-in>
Related Topics
Transforming the Stack
