A function or variable. More...

Public Member Functions
procedure	as_procedure () const
	Get the procedure corresponding to a function symbol.

std::string	as_repr () const
	Get a representation of a symbol object that includes information useful for debugging.

std::string	as_string () const
	Get a simple string representation of a symbol object.

int	cmp (const symbol &other) const
	Comparison function for symbol.

std::string	demangled_name () const
	[Binary analyses only] Get the demangled user-friendly name of a symbol.

bool	extern_only () const
	Check: does the symbol have only non-storage-allocating declarations?

sfileinst_line_pair	file_line () const
	Get the file instance and line of the smallest offset of a declaration point for a symbol.

ast	get_ast (ast_family family=ast_family::DEFAULT) const
	Get an AST from a symbol.

compunit	get_compunit () const
	Get the compilation unit to which a symbol is scoped.

func_attrs	get_func_attrs () const
	Get the attributes associated with a function symbol.

symbol_kind	get_kind () const
	Get the symbol_kind of a symbol.

procedure	get_procedure () const
	Get the procedure to which a local or local-static symbol is scoped.

ast	get_type (ast_family family=ast_family::DEFAULT) const
	Get the type AST that is associated with a symbol.

var_attrs	get_var_attrs () const
	Get the attributes associated with a non-function symbol.

std::string	handle () const
	Get a handle for this symbol.

bool	has_ast (ast_family family=ast_family::DEFAULT) const
	Check: does a symbol have an associated AST (ast) of the specified family (ast_family)?

bool	has_type (ast_family family=ast_family::DEFAULT) const
	Check: does a symbol have an associated type AST?

cs_hash_t	hash () const
	Get a hash value for a symbol.

bool	is_file_static () const
	Check: does the symbol represent a file static variable?

bool	is_formal () const
	Check: does the symbol represent a formal parameter?

bool	is_function () const
	Check: does the symbol represent a function?

bool	is_global () const
	Check: does the symbol represent a global variable?

bool	is_heap () const
	Check: does the symbol represent a heap variable?

bool	is_local () const
	Check: does the symbol represent a local?

bool	is_local_static () const
	Check: does the symbol represent a static variable local to a procedure?

bool	is_static_function () const
	Check: does the symbol represent a static function?

bool	is_string () const
	Check: does the symbol represent a string literal?

std::string	name () const
	Get the name of a symbol.

std::string	represented_string () const
	For a symbol that represents a string literal, get the string.

compunit	source_compunit () const
	Get the compilation unit containing the declaration point for a symbol.

int	stable_cmp (const symbol &other) const
	Compare with another point, with stable results across sufficiently-similar analyses.

csuint64	stable_hash () const
	Get a hash value for a symbol, with stable results across sufficiently-similar analyses.

std::string	temp_source () const
	If a symbol represents a temporary variable, get its pretty-printed unnnormalized C/C++ AST.

std::string	verbose_name () const
	Get the verbose name of a symbol.

Related Symbols
(Note that these are not member symbols.)
bool	operator!= (const symbol &a, const symbol &b)
	Inequality operator for symbol.

bool	operator< (const symbol &a, const symbol &b)
	Less-than operator for symbol.

std::ostream &	operator<< (std::ostream &out, const symbol &a)


bool	operator<= (const symbol &a, const symbol &b)
	Less-than-or-equal operator for symbol.

bool	operator== (const symbol &a, const symbol &b)
	Equality operator for symbol.

bool	operator> (const symbol &a, const symbol &b)
	Greater-than operator for symbol.

bool	operator>= (const symbol &a, const symbol &b)
	Greater-than-or-equal operator for symbol.

Detailed Description

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.

Member Function Documentation

◆ as_procedure()

procedure cs::symbol::as_procedure ( ) const

inline

Get the procedure corresponding to a function symbol.

Returns: The procedure

Exceptions

result::ERROR_SDG_NOT_PRESENT
result::ABS_LOC_NOT_FUNCTION

◆ as_repr()

std::string cs::symbol::as_repr ( ) const

inline

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

Returns: The string representation.

◆ as_string()

std::string cs::symbol::as_string ( ) const

inline

Get a simple string representation of a symbol object.

Returns: The string representation.

◆ cmp()

cs::symbol::cmp ( const symbol & other ) const

inline

Comparison function for symbol.

Parameters

other The symbol object to compare against.

Returns

An integer N such that:

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

this and other will only compare equal if they are the same symbol object.

◆ demangled_name()

std::string cs::symbol::demangled_name ( ) const

inline

[Binary analyses only] Get the demangled user-friendly name of a symbol.

In a mixed-mode project (source and binary together) this will return the demangled name for source (C/C++) symbols also (same as cs.symbol.name()).

Returns: The symbol's demangled user-friendly name.

Exceptions

result::NOT_IMPLEMENTED if the CodeSonar installation does not include binary analysis functionality.

◆ extern_only()

bool cs::symbol::extern_only ( ) const

inline

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

Returns: true if the symbol has no storage-allocating declarations, false if it has one or more storage-allocating declarations.

◆ file_line()

sfileinst_line_pair cs::symbol::file_line ( ) const

inline

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

Returns: The file instance and line of the declaration point.

Exceptions

result::NO_POSITION if no declaration point can be located.

◆ get_ast()

ast cs::symbol::get_ast ( ast_family family = ast_family::DEFAULT ) const

inline

Get an AST from a symbol.

Parameters

[in] family Symbols may be associated with multiple ASTs. This specifies which one to get.

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

Exceptions

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 has_ast().

◆ get_compunit()

compunit cs::symbol::get_compunit ( ) const

inline

Get the compilation unit to which a symbol is scoped.

Returns: The compilation unit (compunit) to which the symbol is scoped.

Exceptions

result::ABS_LOC_IS_GLOBAL if the symbol represents a global.

◆ get_func_attrs()

func_attrs cs::symbol::get_func_attrs ( ) const

inline

Get the attributes associated with a function symbol.

Returns: The symbol attributes (func_attrs).

Exceptions

result::ERROR_INVALID_ARGUMENT if the symbol does not have kind symbol_kind::FUNCTION.

◆ get_kind()

symbol_kind cs::symbol::get_kind ( ) const

inline

Get the symbol_kind of a symbol.

Returns: The symbol_kind.

Exceptions

result::ERROR_SDG_NOT_PRESENT
result::ERROR_UNKNOWN_ABS_LOC_KIND

◆ get_procedure()

procedure cs::symbol::get_procedure ( ) const

inline

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

Returns: The procedure to which the symbol is scoped.

Exceptions

result::ABS_LOC_HAS_NO_PDG if the symbol is not local or local-static.

See also: as_procedure().

◆ get_type()

ast cs::symbol::get_type ( ast_family family = ast_family::DEFAULT ) const

inline

Get the type AST that is associated with a symbol.

Parameters

[in] family 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.

Returns: The retrieved type AST (ast).

Exceptions

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 has_type().

◆ get_var_attrs()

var_attrs cs::symbol::get_var_attrs ( ) const

inline

Get the attributes associated with a non-function symbol.

Returns: The symbol attributes (var_attrs).

Exceptions

result::ERROR_INVALID_ARGUMENT if the symbol has kind symbol_kind::FUNCTION.

◆ handle()

std::string cs::symbol::handle ( ) const

inline

Get a handle for this symbol.

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 std::string consisting of letters (upper and lower case) and numbers, and could also include the following characters: "+", "=", and "_".

◆ has_ast()

bool cs::symbol::has_ast ( ast_family family = ast_family::DEFAULT ) const

inline

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

Parameters

[in] family 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.

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 get_ast().

◆ has_type()

bool cs::symbol::has_type ( ast_family family = ast_family::DEFAULT ) const

inline

Check: does a symbol have an associated type AST?

Parameters

[in] family 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.

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 get_type().

◆ hash()

cs_hash_t cs::symbol::hash ( ) const

inline

Get a hash value for a symbol.

◆ is_file_static()

bool cs::symbol::is_file_static ( ) const

inline

Check: does the symbol represent a file static variable?

Returns: true if the symbol represents a file static variable, false otherwise.

◆ is_formal()

bool cs::symbol::is_formal ( ) const

inline

Check: does the symbol represent a formal parameter?

Returns: true if the symbol represents a formal parameter, false otherwise.

◆ is_function()

bool cs::symbol::is_function ( ) const

inline

Check: does the symbol represent a function?

Returns: true if the symbol represents a function, false otherwise.

◆ is_global()

bool cs::symbol::is_global ( ) const

inline

Check: does the symbol represent a global variable?

Returns: true if the symbol represents a global variable, false otherwise.

◆ is_heap()

bool cs::symbol::is_heap ( ) const

inline

Check: does the symbol represent a heap variable?

Returns: true if the symbol represents a heap variable, false otherwise.

◆ is_local()

bool cs::symbol::is_local ( ) const

inline

Check: does the symbol represent a local?

Returns: true if the symbol represents a non-static variable local to a procedure, false otherwise.

◆ is_local_static()

bool cs::symbol::is_local_static ( ) const

inline

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

Returns: true if the symbol represents a static variable local to a procedure variable, false otherwise.

◆ is_static_function()

bool cs::symbol::is_static_function ( ) const

inline

Check: does the symbol represent a static function?

Returns: true if the symbol represents a static function, false otherwise.

◆ is_string()

bool cs::symbol::is_string ( ) const

inline

Check: does the symbol represent a string literal?

Returns: true if the symbol represents a string literal, false otherwise.

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

◆ name()

std::string cs::symbol::name ( ) const

inline

Get the name of a symbol.

Returns: A std::string containing the symbol name.

◆ represented_string()

std::string cs::symbol::represented_string ( ) const

inline

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

Returns: The std::string.

Exceptions

result::NO_REPRESENTED_STRING

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

◆ source_compunit()

compunit cs::symbol::source_compunit ( ) const

inline

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

Returns: The compilation unit (compunit).

Exceptions

result::ELEMENT_NOT_PRESENT if no declaration point can be located.

This function is deprecated. Use file_line() instead.

◆ stable_cmp()

int cs::symbol::stable_cmp ( const symbol & other ) const

inline

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

Parameters

[in] other The point to compare against.

Returns

An integer N, such that:

N<0 if this considered less than other
N==0 if this and other are the same object
N>0 if this 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 cmp(): it has better performance.

◆ stable_hash()

csuint64 cs::symbol::stable_hash ( ) const

inline

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

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 hash(): it has better performance.

◆ temp_source()

std::string cs::symbol::temp_source ( ) const

inline

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

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

Exceptions

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.

◆ verbose_name()

std::string cs::symbol::verbose_name ( ) const

inline

Get the verbose name of a symbol.

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

Returns: A std::string containing the verbose symbol name.

Friends And Related Symbol Documentation

◆ operator!=()

bool operator!=	(	const symbol &	a,
		const symbol &	b
	)

Parameters

[in]	a	The symbol to compare.
[in]	b	The symbol to compare against.

Returns: false if a and b are equal according to symbol::cmp(), true otherwise.

◆ operator<()

bool operator<	(	const symbol &	a,
		const symbol &	b
	)

Parameters

[in]	a	The symbol to compare.
[in]	b	The symbol to compare against.

Returns: true if a < b according to symbol::cmp() , false otherwise.

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	out,
		const symbol &	a
	)

Parameters

[in]	out	The stream to print to.
[in]	a	The symbol object to print.

Returns: void

◆ operator<=()

bool operator<=	(	const symbol &	a,
		const symbol &	b
	)

Parameters

[in]	a	The symbol to compare.
[in]	b	The symbol to compare against.

Returns: true if a <= b according to symbol::cmp() , false otherwise.

◆ operator==()

bool operator==	(	const symbol &	a,
		const symbol &	b
	)

Parameters

[in]	a	The symbol to compare.
[in]	b	The symbol to compare against.

Returns: true if a and b are equal according to symbol::cmp(), false otherwise.

◆ operator>()

bool operator>	(	const symbol &	a,
		const symbol &	b
	)

Parameters

[in]	a	The symbol to compare.
[in]	b	The symbol to compare against.

Returns: true if a > b according to symbol::cmp() , false otherwise.

◆ operator>=()

bool operator>=	(	const symbol &	a,
		const symbol &	b
	)

Parameters

[in]	a	The symbol to compare.
[in]	b	The symbol to compare against.

Returns: true if a >= b according to symbol::cmp() , false otherwise.

The documentation for this class was generated from the following files:

Public Member Functions

Related Symbols

Detailed Description

Member Function Documentation

◆ as_procedure()

◆ as_repr()

◆ as_string()

◆ cmp()

◆ demangled_name()

◆ 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()

◆ hash()

◆ 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()

Friends And Related Symbol Documentation

◆ operator!=()

◆ operator<()

◆ operator<<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()