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 27 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 Perforce Software provided will be the ones that you will use.
|
Symbol Kind |
Has base_ name |
Has type_index |
Property |
|
|
|
aggregate_type |
X |
X |
|||
|
array_type |
X |
X |
artificial
|
index_type_index
|
|
|
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 |
|
return_type_index
|
||
|
typedef |
X |
X |
|||
|
variable |
X |
|
|||
|
void_type |
X |
X |
|||
|
wchar_type |
X |
X |
How these symbols are related
Figure 203 shows how these symbols are related.
Figure 203. Symbols Architecture
Definitions of the properties associated with these symbols
contains the location for a variety of objects such as a func, global_var, and a tls_global.
One of the following: struct, class, or union.
A Boolean (0 or 1) value where true indicates that the compiler generated the symbol.
The compiler or family of compiler used to create the file; for example, gnu, xlc, intel, and so on.
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 204. Data Addressing
Indicates if a symbol has been full or partially read-in. The following constants are or’d and returned: skim, index, line, and full.
The name of demangler used by your compiler.
The location containing additional operands that let you go from the data’s base location to an element.
Name of the enumerator tags. For example, if you have something like enum[R,G,B], the tags would be R, G, and B.
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 *.
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.
The array type’s index type_index; for example, this indicates if the index is a 16-, 32-, 64-bit, and so on.
For C++ variables, this string is as follows: [ virtual ] [ { private | protected | public } ] [ base class ]
A true/false value indicating if a variable was a parameter (dummy variable) passed into the function.
One of the symbol types listed in the first column of the previous table.
A string containing a value such as C, C++, or Fortran.
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.
The current scope’s owner as defined by the language’s rules.
Figure 205. Logical Scope Owner
This is a pathname reference symbol that refers to the scope in which to look up a pathname.
The location containing the array’s lower bound. This is a numeric value, not the location of the first array item.
The order in which a member or variable occurred within a scope.
A qualifier to a data type such as const or volatile. These can be chained together if there is more than one qualifier.
Figure 206. Qualification
The soid to lookup in a soid reference symbol.
The pathname to lookup in a Fortran reference symbol.
The data type of the value returned by a function.
The ID of the symbol’s scope owner. (This is illustrated by the figure within the logical_scope_owner definition.)
The location of a static link for nested subroutines.
For nested subroutines, this indicates the nesting level.
Location of the value indicating an array’s stride.
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.
The type of the following entities: array, ds_undiscovered_type, pointer, and typedef.
One of the following: member, variable, or named_constant.
The location of the value indicating an array’s upper bound or extent.
The name of an array or pointer validator. This looks at an array descriptor or pointer to determine if it is allocated and associated.
For enumerators, this indicates the item’s value in hexadecimal bytes.
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 28 lists the properties associated with a namespace. Figure 207 illustrates how these namespaces are related.
|
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 |
|
How these symbols are related
Figure 207. Namespace Architecture
Definitions of the properties associated with these symbols
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 looking at the following function prototype:
void c::foo<int>(int &)
The name of the function; for example, foo.
The C++ class name; for example, c.
Not used.
The function’s signature; for example, int &.
The template used to instantiate the function; for example: <int>.
The data type of the returned value; for example, void.
The directory to which you were attached when you started TotalView.
Your file’s pathname as it is named within your program.
The name of your module. Typically, this looks like module‘var or module‘subr‘var.
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.
The line number at which something occurred.
The file’s pathname.
The mangled name.
In a library, you might have an object reference; for example, libC.a(foo.so). foo.so is the member name.
Not used.
type_index
A handle that points to the type definition. Its format is <number,number,number>.