dskip
Creates and manages single-stepper skip rules
Format
Create a rule to skip over or through a function
dskip [ over | through ] [ function | -function | -fu ] function-name
Create a rule to skip over or through a file
dskip [ over | through ] [ file | -file | -fi ] filename
Create a rule to skip over or through functions that are also contained in specific source files
dskip [ over | through ] { { -function | -fu } function-name | { -rfunction | -rfu } function-regexp } { { -file | -fi } filename | { -gfile | -gfi } file-glob }
Enable or disable skipping of a list of IDs
dskip [ enable | disable ] [ id ]
Delete a list of skip IDs
dskip delete [ id ]
Print information about a list of skip IDs
dskip info [ id ]
Arguments
function-name
The name of the function for the skip rule. If function-name matches the base name or the fully qualified name of the subroutine symbol, then the rule matches the subroutine. However, if function-name does not match the base name, TotalView attempts to do a partial name match by demangling function-name using the demangler in the subroutine's containing file, or splitting an already demangled name into its components (base name, class name, overload string, etc.). If the base name and the specified name components in function-name match the subroutine's name components, then the rule matches the subroutine. Otherwise, the rule does not match the subroutine.
For example, all of the following function-name strings match the subroutine name EnumS<Color>::EnumS(Color) on Linux: EnumS, EnumS(Color), EnumS<Color>::EnumS, and of course, EnumS<Color>::EnumS(Color). Since the function-name is demangled (if necessary), _ZN5EnumSI5ColorEC1ES0_ (the G++ mangled name of the subroutine) also matches.
function-regexp
The function name regular expression for the skip rule. If function-regexp matches the fully qualified name of the subroutine symbol using Tcl's “advanced” regular expression matching, then the rule matches the subroutine.
Otherwise, the rule does not match the subroutine.
Using a function-regexp can be useful when matching complex C++ function names, matching several functions with one rule, or to accommodate demangling differences across compilers or platforms. For example, the following function-regexp string matches all instances of template<class T> EnumS<T>::EnumS(T):
^EnumS<(.*)>::EnumS\(\1\)
Note that it is best to wrap all Tcl regexp arguments in curly braces to prevent any expansion within the regexp string. For example, create the above rule as follows:
dskip -rfu {^EnumS<(.*)>::EnumS\(\1\)}
filename
The name of the file for the skip rule. If filename matches the base name or the compilation directory joined with the base name of the file symbol, then the rule matches the file.
Otherwise, the rule does not match the file.
For example, the following two filename strings match the file name /user/smith/build/linux/test.cxx:
test.cxx
/user/smith/build/linux/test.cxx
Note the match is performed purely on the contents of the file name strings. No attempt is made to resolve the filename string or the file symbol's name in the file system, for example, via realpath.
file-glob
The file name glob pattern for the skip rule. If file-glob contains a directory path delimiter ('/') and it matches the compilation directory joined with the base name of the file symbol using Tcl's string match, then the rule matches the file. However, if file-glob does not contain a directory path delimiter ('/') and it matches the base name of the file symbol using Tcl's string match, then the rule matches the file. Otherwise, the rule does not match the file.
For example, the following file-glob strings match the file name /user/smith/build/linux/test.cxx:
*.cxx
/user/*
Note the match is performed purely on the file name strings. No attempt is made to resolve the filename string or the file symbol's name in the file system. Also, unlike the shell's glob matching (which does access the file system), the directory path delimiter ('/') matches the glob special characters “*” and “?”.
id
The skip ID or list of skip IDs on which the command operates. If one or more skip IDs are given, at least one skip ID from the list must match an existing rule. However, additional skip IDs that do match an existing rule are ignored. For example, if exactly one skip rule with ID “1” exists, then dskip info 1 2 is not an error, but dskip info 2 is an error.
Description
The dskip command allows you to create and manage single-stepper “skip” rules that modify the way source-level single stepping works. You can add rules that match a function, all functions in a source file, or a specific function in a specific source file. Functions can be matched by the function name or a regular expression (Tcl “regexp”). Files can be matched by the file name or a glob pattern (Tcl “string match”).
When a rule is created its skip ID is returned, which starts at 1, is incremented by 1, and is never reused. The dskip command creates skip over rules by default, unless the through qualifier is specified.
The skip rules allow you to identify functions that you are not interested in debugging. TotalView implements two skip rule variants, over and through, as follows:
1. A matching and enabled skip over rule changes the behavior of all source-level step-into operations, such as the dstep command or the Step button or menu items in the graphical user interface.
A skip over rule tells TotalView to not step into the function, but instead step over the function. Skip over is most useful to avoid stepping into library functions, such as C++ STL code.
For example, consider the code fragment:
10 void MyFunc()
11 {
12 EnumS<Color> v ( Red );
13 if (v == Blue || OtherFunc())
14 std::cout << "Hello, world" << std::endl;
15 }
If a skip over rule existed for EnumS<Color>::EnumS(Color), then a dstep at line 12 would step over the call to the constructor (not into it) and the program would stop at line 13.
2. A matching and enabled skip through rule changes the behavior of all source-level single-stepping operations, such as the dstep and dnext commands or the Step and Next buttons or menu items in the graphical user interface.
A skip through rule tells TotalView to ignore any source-line information for the function, so that single stepping does not stop at source lines within the function. However, if the function being skipped through calls another function, that call is handled according to original single-stepping operation. Skip through is most useful for callback or thunk functions.
For example, consider the code fragment:
20 template<class Func>
21 inline void Callback(Func func)
22 {
23 func();
24 }
30 void MainFunc()
31 {
32 Callback(MyFunc);
33 }
If a skip through rule existed for Callback, then a dstep at line 32 would step through the code in Callback and the program would stop inside MyFunc.
Enabling, Disabling, Deleting, and Printing Skip Rules
The dskip command enable, disable, delete and info subcommands take an optional list of skip IDs.
When a skip rule is disabled, it is completely ignored during single-stepping operations.
The dskip info command is the only command that generates output. It prints details about the specified rules in tabular format with the following column headings:
Column | Description |
|---|---|
Id | The skip rule ID number. |
Enb | Enabled or disabled. |
How | Skip over or skip through. |
Glob | File is a file-glob or filename. |
File | The filename, file-glob, or none. |
RE | Function is a function-regexp or function-name. |
Function | The function-name, function-regexp, or none. |
Name Matching
Each skip rule contains a function name or function regular expression, and/or a file name or file glob pattern. During certain single-stepping operations, TotalView attempts to map program locations to symbol objects in the symbol table for the program, specifically subroutine and file symbols. If the symbols are found, it then attempts to match the names of the symbols against the names, regular expressions, and glob patterns contained within the skip rules.
For example, when executing a source-level step-into operation, if a call instruction is encountered, TotalView maps the address of the function that is being called to a subroutine and file symbol, and attempts to match the symbol names' against the skip rules. If an enabled skip over rule is matched, the call instruction is stepped over instead of stepped into.
The way in which TotalView matches the symbol names against the rules depends on a how the rule was created. Further, the rule might be matched against symbol name variations.
When matching subroutine symbols against function skip rules, TotalView uses either the subroutine symbol's base name or fully qualified name.A fully qualified subroutine name contains any combination namespace, class name, template types, base name, and function signature.
When matching file symbols against file skip rules, TotalView uses either the file symbol's base name or compilation directory joined with the base name.The compilation directory is a canonicalized version of the directory hint and directory path information in the symbol table. For example, if the compiler path was ../../src and the directory hint (the compiler's “pwd”) was /user/smith/build/linux, the compilation directory would be /user/smith/src.
Examples
dskip through function Callback
Skip through functions named “Callback”.
dskip -rfunction {^EnumS<(.*)>::EnumS\(\1\)}
Skip over functions with names that match the regular expression.
dskip file /user/smith/build/linux/test.cxx
Skip over all functions contained in the source file named /user/smith/build/linux/test.cxx.
dskip over -gfile *.cxx
Skip over all functions contained in source files with names that match the file glob pattern, in this case all files with a .cxxextension.
dskip through -rfunction {^EnumS<(.*)>::EnumS\(\1\)} -gfile *.cxx
Skip through functions that match the regular expression that are also contained in source files with a .cxx extension.
