Contents

• class symbol
  • symbol Members
  • symbol Details

class symbol

A function or variable.

The symbol class corresponds to the ABS_LOC abstraction.

• Every symbol has a symbol_kind .
• Collections of symbols are represented as symbol_set , with traversal provided by symbol_set_iterator .

Internal representation for symbols is available for C/C++ and binary analyses only. For C# and Java analyses, plug-ins that rely on symbol properties and relationships will generally not produce useful information.

symbol Members

Constructors

none

Methods

__cmp__(), __eq__(), __ge__(), __gt__(), __hash__(), __le__(), __lt__(), __ne__(), __repr__(), __str__(), as_procedure(), extern_only(), file_line(), get_ast(), get_compunit(), get_func_attrs(), get_kind(), get_procedure(), get_type(), get_var_attrs(), handle(), has_ast(), has_type(), is_file_static(), is_formal(), is_function(), is_global(), is_heap(), is_local(), is_local_static(), is_static_function(), is_string(), name(), represented_string(), source_compunit(), stable_cmp(), stable_hash(), temp_source(), verbose_name()

symbol Details

class cs.symbol

A function or variable.

__cmp__(other)

Comparison function for symbol .

Parameters:other (symbol) – The symbol object to compare against. Return type:int Returns:An integer N such that:

• N==0 if the two objects compare equal
• N<0 if self < other
• N>0 if self > other

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym2 = next(syms)
>>> sym2
<cs.symbol foo>
>>> sym1.__cmp__(sym2)
1

__eq__(b)

Equality operator for symbol .

Parameters:b (symbol) – The symbol to compare against. Return type:bool Returns:True if self and b compare equal, False otherwise.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym2 = next(syms)
>>> sym2
<cs.symbol foo>
>>> sym1 == sym2
False

__ge__(b)

Greater-than-or-equal operator for symbol .

Parameters:b (symbol) – The symbol to compare against. Return type:bool Returns:True if self >= b , False otherwise.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym2 = next(syms)
>>> sym2
<cs.symbol foo>
>>> sym1 >= sym2
True

__gt__(b)

Greater-than operator for symbol .

Parameters:b (symbol) – The symbol to compare against. Return type:bool Returns:True if self > b , False otherwise.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym2 = next(syms)
>>> sym2
<cs.symbol foo>
>>> sym1 > sym2
True

__hash__()

Get a hash value for a symbol .

Return type:int

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> hash(sym1)
378599092

__le__(b)

Less-than-or-equal operator for symbol .

Parameters:b (symbol) – The symbol to compare against. Return type:bool Returns:True if self <= b , False otherwise.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym2 = next(syms)
>>> sym2
<cs.symbol foo>
>>> sym1 <= sym2
False

__lt__(b)

Less-than operator for symbol .

Parameters:b (symbol) – The symbol to compare against. Return type:bool Returns:True if self < b , False otherwise.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym2 = next(syms)
>>> sym2
<cs.symbol foo>
>>> sym1 < sym2
False

__ne__(b)

Inequality operator for symbol .

Parameters:b (symbol) – The symbol to compare against. Return type:bool Returns:False if self and b compare equal, True otherwise.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym2 = next(syms)
>>> sym2
<cs.symbol foo>
>>> sym1 != sym2
True

__repr__()

Get a representation of a symbol object that includes information useful for debugging.

Return type:str Returns:The string representation.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> repr(sym1)
'<cs.symbol #File_Initialization>'

__str__()

Get a simple string representation of a symbol object.

Return type:str Returns:The string representation.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> str(sym1)
'#File_Initialization'

as_procedure()

Get the procedure corresponding to a function symbol.

Return type:

procedure

Returns:

The procedure

Raises:

• result.ABS_LOC_NOT_FUNCTION
• result.ERROR_SDG_NOT_PRESENT

>>> foosym = next(s for s in project.current().symbols()
...               if s.name() == 'foo')
>>> foosym
<cs.symbol foo>
>>> foosym.as_procedure()
<cs.procedure foo>

extern_only()

Check: does the symbol have only non-storage-allocating declarations?

Return type:bool Returns:True if the symbol has no storage-allocating declarations, False if it has one or more storage-allocating declarations.

>>> foosym = next(s for s in project.current().symbols()
...               if s.name() == 'foo')
>>> foosym.extern_only()

file_line()

Get the file instance and line of the smallest offset of a declaration point for a symbol.

Return type:(sfileinst, int) Returns:The file instance and line of the declaration point. Raises:result.NO_POSITION if no declaration point can be located.

>>> foosym = next(s for s in project.current().symbols()
...               if s.name() == 'foo')
>>> foosym.file_line()
(<cs.sfileinst C:\alex\test\apitest.cpp>, 32)

get_ast([family =  ast_family.DEFAULT])

Get an AST from a symbol.

Parameters:

family (ast_family) – (optional) Symbols may be associated with multiple ASTs. This specifies which one to get.

Return type:

ast

Returns:

The AST ( ast ) that is associated with the symbol and whose family is family.

Raises:

• result.ELEMENT_NOT_PRESENT if there is no such AST.
• result.ERROR_INVALID_ARGUMENT if family is not a valid ast_family .

Note that a symbol may have multiple ASTs of the same family. If so, one of them will be returned. For a single analysis with fixed symbol s and ast_family f, calls to s.get_ast(f) will always return the same AST.

To check whether the symbol has at least one associated AST of the required family, use symbol.has_ast().

>>> foosym = next(s for s in project.current().symbols()
...               if s.name() == 'foo')
>>> foosym.get_ast(ast_family.C_NORMALIZED)
<cs.ast [c:routine] foo>

>>> foosym = next(s for s in project.current().symbols()
...               if s.name() == 'foo')
>>> foosym.get_ast()
<cs.ast [c:routine] foo>

get_compunit()

Get the compilation unit to which a symbol is scoped.

Return type:compunit Returns:The compilation unit ( compunit ) to which the symbol is scoped. Raises:result.ABS_LOC_IS_GLOBAL if the symbol represents a global.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.get_compunit()
<cs.compunit C:\alex\test\apitest.cpp>

get_func_attrs()

Get the attributes associated with a function symbol.

Return type:func_attrs Returns:The symbol attributes ( func_attrs ). Raises:result.ERROR_INVALID_ARGUMENT if the symbol does not have kind symbol_kind.FUNCTION.

>>> foosym = next(s for s in project.current().symbols()
...               if s.name() == 'foo')
>>> foosym.get_func_attrs()
<cs.func_attrs none>

get_kind()

Get the symbol_kind of a symbol.

Return type:

symbol_kind

Returns:

The symbol_kind .

Raises:

• result.ERROR_UNKNOWN_ABS_LOC_KIND
• result.ERROR_SDG_NOT_PRESENT

>>> foosym = next(s for s in project.current().symbols()
...               if s.name() == 'foo')
>>> foosym.get_kind()
<cs.symbol_kind function>

get_procedure()

Get the procedure to which a local or local-static symbol is scoped.

Return type:procedure Returns:The procedure to which the symbol is scoped. Raises:result.ABS_LOC_HAS_NO_PDG if the symbol is not local or local-static.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.get_procedure()
<cs.procedure mymalloc>

get_type([family =  ast_family.DEFAULT])

Get the type AST that is associated with a symbol .

Parameters:

family (ast_family) – (optional) Symbols may be associated with multiple type ASTs. This specifies which one to get. Each language dependent AST header file will define its AST families.

Return type:

ast

Returns:

The retrieved type AST ( ast ).

Raises:

• result.ELEMENT_NOT_PRESENT if the symbol has no associated type AST whose family is family.
• result.ERROR_INVALID_ARGUMENT if family is not a valid ast_family .

Note that a symbol may have multiple type ASTs of the same family. If so, one of them will be returned. For a single analysis with fixed symbol s and ast_family f, calls to s.get_type(f) will always return the same AST.

To check whether the symbol has at least one associated type AST of the required family, use symbol.has_type().

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.get_type(ast_family.C_NORMALIZED)
<cs.ast [c:integer] int>

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.get_type()
<cs.ast [c:integer] int>

get_var_attrs()

Get the attributes associated with a non-function symbol.

Return type:var_attrs Returns:The symbol attributes ( var_attrs ). Raises:result.ERROR_INVALID_ARGUMENT if the symbol has kind symbol_kind.FUNCTION.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.get_var_attrs()
<cs.var_attrs none>

handle()

Get a handle for this symbol .

Return type:str Returns:The symbol’s handle.

Use this function to retrieve a handle to the symbol which can be stored externally and used with project.lookup_symbol_handle() to retrieve the symbol when needed. This handle is valid only for the analysis it was generated from. If you rebuild the project, the handle will no longer be valid.

A handle is a string consisting of letters (upper and lower case) and numbers, and could also include the following characters: “+”, “=”, and “_”.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.handle()
'AOCXgAGCgICAAgc='

has_ast([family =  ast_family.DEFAULT])

Check: does a symbol have an associated AST ( ast ) of the specified family ( ast_family )?

Parameters:family (ast_family) – (optional) Symbols may be associated with multiple ASTs. This specifies which one to check for. Each language dependent AST header file will define its AST families. Return type:bool Returns:True if the symbol has at least one associated AST whose family is ast_family, False otherwise.

If this returns True, you can retrieve the AST (or one of them, if the symbol has more than one AST of the same family) with symbol.get_ast().

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.has_ast(ast_family.C_UNNORMALIZED)
False

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.has_ast()
True

has_type([family =  ast_family.DEFAULT])

Check: does a symbol have an associated type AST?

Parameters:family (ast_family) – (optional) Symbols may be associated with multiple type ASTs. This specifies which one to check for. Each language dependent AST header file will define its AST families. Return type:bool Returns:True if the symbol has at least one associated type AST whose family is family, False otherwise.

If this returns True, you can retrieve the type AST (or one of them, if the symbol has more than one type AST of the same family) with symbol.get_type().

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.has_type(ast_family.C_NORMALIZED)
True

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.has_type()
True

is_file_static()

Check: does the symbol represent a file static variable?

Return type:bool Returns:True if the symbol represents a file static variable, False otherwise.

>>> v0 = project.current()
>>> v1 = v0.lookup_symbol('foo')
>>> v1.is_file_static()
False

is_formal()

Check: does the symbol represent a formal parameter?

Return type:bool Returns:True if the symbol represents a formal parameter, False otherwise.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.is_formal()
True

is_function()

Check: does the symbol represent a function?

Return type:bool Returns:True if the symbol represents a function, False otherwise.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.is_function()
False

is_global()

Check: does the symbol represent a global variable?

Return type:bool Returns:True if the symbol represents a global variable, False otherwise.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.is_global()
False

is_heap()

Check: does the symbol represent a heap variable?

Return type:bool Returns:True if the symbol represents a heap variable, False otherwise.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.is_heap()
False

is_local()

Check: does the symbol represent a local?

Return type:bool Returns:True if the symbol represents a non-static variable local to a procedure, False otherwise.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.is_local()
True

is_local_static()

Check: does the symbol represent a static variable local to a procedure?

Return type:bool Returns:True if the symbol represents a static variable local to a procedure variable, False otherwise.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.is_local_static()
False

is_static_function()

Check: does the symbol represent a static function?

Return type:bool Returns:True if the symbol represents a static function, False otherwise.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.is_static_function()
False

is_string()

Check: does the symbol represent a string literal?

Return type:bool Returns:True if the symbol represents a string literal, False otherwise.

If this function returns True, you can recover the string literal with symbol.represented_string().

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.is_string()
False

name()

Get the name of a symbol.

Return type:str Returns:A string containing the symbol name.

>>> isym = next(s for s in project.current().symbols()
...             if s.name() =='i')
>>> isym.name()
'i'

represented_string()

For a symbol that represents a string literal, get the string.

Return type:str Returns:The string. Raises:result.NO_REPRESENTED_STRING

To test whether a symbol represents a string literal, use symbol.is_string().

>>> strsym = next(s for s in project.current().symbols()
...               if s.get_kind() == symbol_kind.STRING)
>>> strsym.represented_string()
'bar'

source_compunit()

Get the compilation unit containing the declaration point for a symbol.

Return type:compunit Returns:The compilation unit ( compunit ). Raises:result.ELEMENT_NOT_PRESENT if no declaration point can be located.

This function is deprecated. Use symbol.file_line() instead.

>>> strsym = next(s for s in project.current().symbols()
...               if s.get_kind() == symbol_kind.STRING)
>>> strsym.source_compunit()
<cs.compunit C:\alex\test\apitest.cpp>

stable_cmp(other)

Compare with another point , with stable results across sufficiently-similar analyses.

Parameters:other (symbol) – The point to compare against. Return type:int Returns:An integer N, such that:

• N<0 if self considered less than other
• N==0 if self and other are the same object
• N>0 if self considered greater than other

The comparison is stable in the following sense. Suppose there are two analyses A1 and A2 generated with exactly the same inputs (including identical analyzed code, underlying build commands and ordering, command line and configuration settings, increment order and contents). Let a1 and b1 be two symbol objects in A1, and a2 and b2 be the symbol objects in A2 that correspond to a1 and b1 respectively. Then a1.stable_cmp(b1)==a2.stable_cmp(b2).

If you don’t need comparison relationships to be stable across analyses, use symbol.__cmp__(): it has better performance.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym2 = next(syms)
>>> sym2
<cs.symbol foo>
>>> sym1.stable_cmp(sym2)
1

stable_hash()

Get a hash value for a symbol, with stable results across sufficiently-similar analyses.

Return type:int Returns:The computed hash value.

This hash value is stable in the following sense. Suppose there are two analyses A1 and A2 generated with exactly the same inputs (including identical analyzed code, underlying build commands and ordering, command line and configuration settings, increment order and contents). Let v1 be a symbol object in A1, and v2 be the symbol object in A2 that corresponds to v1. Then v1.stable_hash()==v2.stable_hash().

If you don’t need hash values to be stable across analyses, use symbol.__hash__(): it has better performance.

>>> syms = project.current().symbols()
>>> sym1 = next(syms)
>>> sym1
<cs.symbol #File_Initialization>
>>> sym1.stable_hash()
4008395780

temp_source()

If a symbol represents a temporary variable, get its pretty-printed unnnormalized C/C++ AST.

Return type:

str

Returns:

A string containing the pretty-printed unnormalized C/C++ AST for the symbol.

Raises:

• result.ERROR_INVALID_ARGUMENT if the symbol kind is not symbol_kind.INTERMEDIATE (expression temporary) or symbol_kind.RESULT (actual-out argument).
• result.ELEMENT_NOT_PRESENT if a pretty-printed version of the AST is not available.

>>> tmpsym = next(s for s in project.current().symbols()
...               if s.get_kind() == symbol_kind.INTERMEDIATE)
>>> tmpsym.temp_source()
'(int *)whoknows(i)'

verbose_name()

Get the verbose name of a symbol.

Return type:str Returns:A string containing the verbose symbol name.

The verbose name may include implementation-defined decorations for making the name unique, which may change in future versions.

>>> tmpsym = next(s for s in project.current().symbols()
...               if s.get_kind() == symbol_kind.INTERMEDIATE)
>>> tmpsym.verbose_name()
'$temp1-9'