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	aggregate_kind artificial external_name	full_pathname id kind	length logical_scope_owner scope_owner
array_type	X	X	artificial data_addressing element_addressing external_name full_pathname id	index_type_index kind logical_scope_owner lower_bound scope_owner stride_bound	submembers target_type_index upper_bound validator
block	X		address_class artificial full_pathname	id kind length	location logical_scope_owner scope_owner
char_type	X	X	artificial external_name full_pathname	id kind logical_scope_owner	scope_owner target_type_index
code_type	X	X	artificial external_name full_pathname	id kind logical_scope_owner	scope_owner
common	X		address_class artificial full_pathname	id kind location	logical_scope_owner scope_owner
ds_ undis­covered_­ type	X	X	artificial full_pathname id	kind logical_scope_owner scope_owner	target_type_index
enum_type	X	X	artificial enumerators external_name	full_pathname id kind	logical_scope_owner scope_owner value_size
error_type	X	X	artificial external_name full_pathname	id kind length	logical_scope_owner scope_owner
file	X		artificial compiler_kind delayed_symbol demangler	full_pathname id kind language	logical_scope_owner scope_owner
float_type	X	X	artificial external_name full_pathname	id kind length	logical_scope_owner scope_owner
function_type	X	X	artificial external_name full_pathname	id kind logical_scope_owner	scope_owner
image	X		artificial full_pathname	id	kind
int_type	X	X	artificial external_name full_pathname	id kind length	logical_scope_owner scope_owner
label	X		address_class artificial full_pathname	id kind location	logical_scope_owner scope_owner
linenumber			address_class artificial full_pathname	id kind location	logical_scope_owner scope_owner
loader_symbol			address_class artificial full_pathname	id kind length	location logical_scope_owner scope_owner
member	X		address_class artificial full_pathname id	inheritance kind location logical_scope_owner	ordinal scope_owner type_index
module	X		artificial full_pathname	id kind	logical_scope_owner scope_owner
named_­constant	X		artificial full_pathname id	kind length logical_scope_owner	scope_owner type_index value
namespace	X		artificial full_pathname	id kind	logical_scope_owner scope_owner
opaque_type	X	X	artificial external_name full_pathname	id kind logical_scope_owner	scope_owner
pathname_­reference_­symbol	X		artificial id full_pathname	kind lookup_scope logical_scope_owner	resolved_­symbol_­pathname scope_owner
pointer_type		X	artificial external_name full_pathname id	kind length logical_scope_owner scope_owner	target_type_index validator
qualified_type	X	X	artificial external_name full_pathname	id kind logical_scope_owner	qualification scope_owner target_type_index
soid_reference_­symbol	X		artificial full_pathname id	kind logical_scope_owner resolved_symbol_id	scope_owner
stringchar_type	X	X	artificial external_name full_pathname	id kind logical_scope_owner	scope_owner target_type_index
subroutine	X		address_class artificial full_pathname id	kind length location logical_scope_owner	return_type_index scope_owner static_chain static_chain_height
typedef	X	X	artificial external_name full_pathname	id kind length	logical_scope_owner scope_owner target_type_index
variable	X		address_class artificial full_pathname id	is_argument kind location logical_scope_owner	ordinal scope_owner type_index
void_type	X	X	artificial external_name full_pathname	id kind length	logical_scope_owner scope_owner
wchar_type	X	X	artificial external_name full_pathname	id kind logical_scope_owner	scope_owner target_type_index

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 2 lists the properties associated with a namespace. Figure 5 illustrates how these namespaces are related.

Table 2: Namespace Properties

Symbol Namespaces	Properties
block_symname	base_name
c_global_symname	base_name	loader_name
	loader_file_path
c_local_symname	base_name
c_type_symname	base_name	type_index
cplus_global_symname	base_name	cplus_template_types
	cplus_class_name	cplus_type_name
	cplus_local_name	loader_file_path
	cplus_overload_list	loader_name
cplus_local_symname	base_name	cplus_overload_list
	cplus_class_name	cplus_template_types
	cplus_local_name	cplus_type_name
cplus_type_symname	base_name	cplus_template_types
	cplus_class_name	cplus_type_name
	cplus_local_name	type_index
	cplus_overload_list
file_symname	base_name	directory_path
	directory_hint
fortran_global_symname	base_name	loader_file_path
	fortran_module_name	loader_name
	fortran_parent_function_name
fortran_local_symname	base_name fortran_parent_function_name
	fortran_module_name
fortran_type_symname	base_name	fortran_parent_function_name
	fortran_module_name	type_index
image_symname	base_name	member_name
	directory_path	node_name
label_symname	base_name
linenumber_symname	linenumber
loader_symname	loader_file_path	loader_name
module_symname	base_name
type_symname	type_index

 

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>.