The way you describe a scope is similar to the way you specify a file. The scopes in a program form a tree, with the outermost scope (which is your program) as the root. At the next level are executable files and dynamic libraries; further down are compilation units (source files), procedures, modules, and other scoping units (for example, blocks) supported by the programming language. Qualifying a symbol is equivalent to describing the path to a file in UNIX file systems.
A symbol is fully scoped when you name all levels of its tree. The following example shows how to scope a symbol and also indicates parts that are optional:
The pound sign (#) separates elements of the fully qualified name.
|
Because of the number of different types of elements that can appear in your program, a complete description of what can appear and their possible order is complicated and unreadable. In contrast, after you see a name in the Stack Frame Pane, it is easy to read a variable’s scoped name.
|
|
You do not need to qualify file names with a full path, and you do not need to use all levels in a symbol’s scoping tree. TotalView conventions here are similar to the way UNIX displays file names.
|
|
|
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 in the root directory). If you omit the executable or library component, the qualified symbol doesn’t begin with #.
|
|
|
Because programming languages typically do not let you name blocks, that portion of the qualifier is specified using the symbols $b followed by a number that indicates which block. For example, the first unnamed block is named $b1, the second is $b2, and so on.
|
You can omit any part of the scope specification that TotalView doesn’t need 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 could identify variable x in procedure bar in executable foo. If bar were not unique in 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 in 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 that occur in the same file. In this case, you need to enter bar.c#b1#x to identify the scope that corresponds to the outer level of the file (that is, the scope that contains line 1 of the file).