Qualifying Symbol Names

The syntax for qualifying a symbol with a scope closely resembles that for specifying a source location. The scopes within a program form a tree, with the outermost scope as the root. At the next level are executable files and dynamic libraries; further down are compilation units (source files), procedures, and other scoping units (for example, blocks) supported by the programming language. Qualifying a symbol is equivalent to specifying which scope it is in, or describing the path to a node in the tree. This is similar to describing the path to a file in a tree-structured file system.

A symbol is fully qualified in terms of its scope when all levels of the tree are included:

    [#executable-or-lib#][file#][procedure-or-line#]symbol

In this definition, the pound sign (#) is a separator character.

TotalView interprets the components of the symbol name as follows:

• Just as file names need not be qualified with a full path, you can qualify a symbol's scope without including all levels in the tree.
   
• If a qualified symbol begins with #, the name that follows indicates the name of the executable or shared library (just as an absolute file path begins with a directory immediately within the root directory). If the executable or library component is omitted, the qualified symbol does not begin with #.
   
• The source file's name may appear after the (possibly omitted) executable or shared library.
   
• Because programming languages typically do not let you name blocks, that portion of the qualifier is specified as a line number within the block.
   
• The procedure name or block component (represented by a line number from that block) may appear after the (possibly omitted) source file name. This component is followed by #.
   
• The symbol name follows the (possibly omitted) procedure or block name. Since qualified symbols often appear in the context of an expression, the final symbol name could be followed by a dot (.), plus the name of a field from a class, union, or structure.

You can omit any part of the scope specification that is not needed to uniquely identify the symbol. Thus, foo#x identifies the symbol x in the procedure foo. In contrast, #foo#x identifies either procedure x in executable foo or variable x in a scope from that executable.

Similarly, #foo#bar#x identifies variable x in procedure bar in executable foo. If bar were not unique within that executable, the name would be ambiguous unless you further qualified it by providing a file name. Ambiguities can also occur if a file-level variable (common in C programs) has the same name as variables declared within functions in that file. For instance, bar.c#x refers to a file-level variable, but the name can be ambiguous when there are different definitions of x embedded in functions occurring in the same file. In this case, you would need to say bar.c#1#x to identify the scope that corresponds to the "outer level" of the file (that is, the scope containing line 1 of the file).

You can use the dwhat command to determine if an unqualified or partially qualified symbol name is ambiguous.