Totalview® for HPC Reference Guide : PART I CLI Commands : Chapter 3 CLI Namespace Commands : symbol
symbol
Gets and sets symbol properties
Format 
TV::symbol action [ object-id ] [ other-args ]
Arguments 
action
The action to perform, as follows:
code_unit_by_soid
Returns the containing scope of a line number. For example:
TV::symbol code_unit_by_soid $start_line
commands
Displays the subcommands that you can use. The CLI responds by displaying the subcommands shown here. Do not use additional arguments with this subcommand.
dump
Dumps all properties of the symbol whose soid (symbol object ID) is named. Do not use additional arguments with this command.
get
Returns properties of the symbols whose soids are specified here. The other-args argument names the properties to be returned.
properties
Displays the properties that the CLI can access. Do not use additional arguments with this option. These properties are discussed later in this section.
read_delayed
Only global symbols are initially read; other symbols are only partially read. This command forces complete symbol processing for the compilation units that contain the named symbols.
resolve_final
Performs a sequence of resolve_next operations until the symbol is no longer undiscovered. If you apply this operation to a symbol that is not undiscovered, it returns the symbol itself.
resolve_next
Some symbols only serve to hold a reference to another symbol. For example, a typedef is a reference to the aliased type, or a const-qualified type is a reference to the non-consts qualified type. These reference types are called undiscovered symbols. This operation, when performed on an undiscovered symbol, returns the symbol the type refers to. When this is performed on a symbol, it returns the symbol itself.
rebind
Changes one or more structural properties of a symbol. These operations can crash TotalView or cause it to produce inconsistent results. The properties that you can change are:
address: the new address:
base_name: the new base name. The symbol must be a base name.
line_number: the new line number. The symbol must be a line number symbol.
loader_name: the new loader name and a file name.
scope: the soid of a new scope owner.
type_index: the new type index, in the form <n, m, p>. The symbol must be a type.
set
Sets a symbol’s property. Not all properties can be set. Determine which properties can be set using the writable_properties property. For example,
TV::symbol set $new_upc_type \
type_index $old_idx
writable_properties
Returns a list of writable properties. For example:
TV::symbol writable_properties $symbol_id
object-id
The ID of a symbol.
other-args
Arguments required by the get subcommand.
Description 
The TV::symbol command lets you examine and set the symbol properties and states.
Symbol Properties
Table 1 lists the properties associated with the symbols information that TotalView stores. Not all of this information will be useful when creating transformations. However, it is possible to come across some of these properties and this information will help you decide if you need to use it in your transformation. In general, the properties used in the transformation files that Rogue Wave Software provided will be the ones that you will use.
Table 1: Symbol Properties
Symbol Kind
Has base_ name
Has type_index
Property
 
 
aggregate_type
X
X
array_type
X
X
block
X
 
char_type
X
X
code_type
X
X
ds_ undis­covered_­ type
X
X
enum_type
X
X
file
X
 
float_type
X
X
function_type
X
X
image
X
 
int_type
X
X
label
X
 
linenumber
 
 
loader_symbol
 
 
member
X
 
module
X
 
named_­constant
X
 
namespace
X
 
opaque_type
X
X
pathname_­reference_­symbol
X
 
pointer_type
 
X
qualified_type
X
X
soid_reference_­symbol
X
 
stringchar_type
X
X
subroutine
X
 
typedef
X
X
variable
X
 
void_type
X
X
wchar_type
X
X
 
Figure 1 shows how these symbols are related.
 
Figure 1 – Symbols Architecture
Here are definitions of the properties associated with these symbols.
address_class
contains the location for a variety of objects such as a func, global_var, and a tls_global.
aggregate_kind
One of the following: struct, class, or union.
artificial
A Boolean (0 or 1) value where true indicates that the compiler generated the symbol.
compiler_kind
The compiler or family of compiler used to create the file; for example, gnu, xlc, intel, and so on.
data_addressing
Contains additional operands to get from the base of an object to its data; for example, a Fortran by-desc array contains a descriptor data structure. The variable points to the descriptor. If you do an addc operation on the descriptor, you can then do an indirect operation to locate the data.
 
Figure 2 – Data Addressing
delayed_symbol
Indicates if a symbol has been full or partially read-in. The following constants are or’d and returned: skim, index, line, and full.
demangler
The name of demangler used by your compiler.
element_addressing
The location containing additional operands that let you go from the data’s base location to an element.
enumerators
Name of the enumerator tags. For example, if you have something like enum[R,G,B], the tags would be R, G, and B.
external_name
When used in data types, it translates the object structure to the type name for the language. For example, if you have a pointer that points to an int, the external name is int *.
full_pathname
This is the # separated static path to the variable; for example, ##image#file#externalname....
id
The internal object handle for the symbol. These symbols always take the form number|number.
index_type_index
The array type’s index type_index; for example, this indicates if the index is a 16-, 32-, 64-bit, and so on.
inheritance
For C++ variables, this string is as follows: [ virtual ] [ { private | protected | public } ] [ base class ]
is_argument
A true/false value indicating if a variable was a parameter (dummy variable) passed into the function.
kind
One of the symbol types listed in the first column of the previous table.
language
A string containing a value such as C, C++, or Fortran.
length
The byte size of the object. For example, this might represent the size of an array or a subroutine.
location
The location in memory where an object’s storage begins.
logical_scope_owner
The current scope’s owner as defined by the language’s rules.
 
Figure 3 – Logical Scope Owner
lookup_scope
This is a pathname reference symbol that refers to the scope in which to look up a pathname.
lower_bound
The location containing the array’s lower bound. This is a numeric value, not the location of the first array item.
ordinal
The order in which a member or variable occurred within a scope.
qualification
A qualifier to a data type such as const or volatile. These can be chained together if there is more than one qualifier.
Figure 4 – Qualification
resolved_symbol_id
The soid to lookup in a soid reference symbol.
resolved_­symbol_­pathname
The pathname to lookup in a Fortran reference symbol.
return_type_index
The data type of the value returned by a function.
scope_owner
The ID of the symbol’s scope owner. (This is illustrated by the figure within the logical_scope_owner definition.)
static_chain
The location of a static link for nested subroutines.
static_chain_height
For nested subroutines, this indicates the nesting level.
stride_bound
Location of the value indicating an array’s stride.
submembers
If you have an array of aggregates or pointers and you have already dived on it, this property gives you a list of {name type} tuples where name is the name of the member of the array (or * if it's an array of pointers), and type is the soid of the type that should be used to dive in all into that field.
target_type_index
The type of the following entities: array, ds_undiscovered_type, pointer, and typedef.
type_index
One of the following: member, variable, or named_constant.
upper_bound
The location of the value indicating an array’s upper bound or extent.
validator
The name of an array or pointer validator. This looks at an array descriptor or pointer to determine if it is allocated and associated.
value
For enumerators, this indicates the item’s value in hexadecimal bytes.
value_size
For enumerators, this indicates the length in bytes
Symbol Namespaces
The symbols described in the previous section all reside within namespaces. Like symbols, namespaces also have properties. Table 1 lists the properties associated with a namespace. Figure 5 illustrates how these namespaces are related.
Table 2: Namespace Properties
Symbol Namespaces
Properties
 
block_symname
 
c_global_symname
 
 
c_local_symname
 
c_type_symname
cplus_global_symname
 
 
 
cplus_local_symname
 
 
cplus_type_symname
 
 
 
 
file_symname
 
 
fortran_global_symname
 
 
 
fortran_local_symname
 
 
 
fortran_type_symname
 
image_symname
 
label_symname
 
linenumber_symname
 
loader_symname
module_symname
 
type_symname
 
 
Figure 5 – Namespace Architecture
 
Many of the following properties are used in more than one namespace. The explanations for these properties will assume a limited context as their use is similar. Some of these definitions assume that you’re are looking at the following function prototype:
void c::foo<int>(int &)
base_name
The name of the function; for example, foo.
cplus_class_name
The C++ class name; for example, c.
cplus_local_name
Not used.
cplus_overload_list
The function’s signature; for example, int &.
cplus_template_types
The template used to instantiate the function; for example: <int>.
cplus_type_name
The data type of the returned value; for example, void.
directory_hint
The directory to which you were attached when you started TotalView.
directory_path
Your file’s pathname as it is named within your program.
fortran_module_name
The name of your module. Typically, this looks like module‘var or module‘subr‘var.
fortran_parent_function_name
The parent of the subroutine. For example, the parent is module in a reference such as module‘subr. If you have an inner subroutine, the parent is the outer subroutine.
linenumber
The line number at which something occurred.
loader_file_path
The file’s pathname.
loader_name
The mangled name.
member_name
In a library, you might have an object reference; for example, libC.a(foo.so). foo.so is the member name.
node_name
Not used.
type_index
A handle that points to the type definition. Its format is <number,number,number>.