CodeSonar C++ API
Public Member Functions | Related Symbols | List of all members
cs::procedure Class Reference

A single procedure/function/method. More...

Public Member Functions

procedure_adjusted_callers_iterator  adjusted_callers () const
 Get an iterator over the call sites (point of kind point_kind::CALL_SITE or point_kind::INDIRECT_CALL) to a procedure, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
 
std::string as_repr () const
 Get a representation of a procedure object that includes information useful for debugging.
 
std::string as_string () const
 Get a simple string representation of a procedure object.
 
std::string basename () const
 Get the basename of a procedure.
 
procedure_call_sites_iterator call_sites (procedure_call_sites_flags flags=procedure_call_sites_flags::DIRECT) const
 Get an iterator over the call sites in a procedure.
 
size_t call_sites_count (procedure_call_sites_flags flags=procedure_call_sites_flags::DIRECT) const
 Get the number of call sites in a procedure.
 
std::vector< pointcall_sites_vector (procedure_call_sites_flags flags=procedure_call_sites_flags::DIRECT) const
 Get a std::vector of the call sites in a procedure.
 
procedure_callers_iterator callers () const
 Get an iterator over the direct call sites (point of kind point_kind::CALL_SITE) whose target is this.
 
size_t callers_count () const
 Get the number of direct callers of a procedure.
 
int cmp (const procedure &other) const
 Comparison function for procedure.
 
std::string demangled_name () const
 [Binary analyses only] Get the demangled user-friendly name of a procedure.
 
point entry_point () const
 Get the entry point of a procedure.
 
point exit_point () const
 Get the exit point of a procedure.
 
sfileinst_line_pair file_line () const
 Get the file instance and (smallest offset) line of the entry point for a procedure.
 
symbol find_containing_symbol_by_offset (csint32 off) const
 [Binary analyses only] Get the procedure local containing the given stack offset.
 
symbol find_symbol_by_offset (csint32 off) const
 [Binary analyses only] Get the procedure local with the given stack offset.
 
point formal_in (size_t rank)
 Get the point corresponding to the formal-in with the specified rank.
 
point_set formal_ins () const
 Get the formal-in and global-formal-in points of a procedure.
 
std::vector< pointformal_ins_vector () const
 Get a std::vector containing the formal-in points of a procedure.
 
point_set formal_outs () const
 Get the formal-out and global-formal-out points of a procedure.
 
std::vector< pointformal_outs_vector () const
 Get the formal-out points of a procedure.
 
effective_address get_address () const
 [Binary analyses only] Get the effective address of a procedure, if there is one.
 
ast get_ast (ast_family family=ast_family::DEFAULT) const
 Retrieve the AST for a procedure.
 
compunit get_compunit () const
 Get the compilation unit containing a procedure.
 
procedure_kind get_kind () const
 Retrieve the procedure_kind of a procedure.
 
symbol get_symbol () const
 Get the symbol for a procedure.
 
std::string handle () const
 Get a handle for this procedure.
 
bool has_vararg () const
 Check: does a procedure have a formal vararg parameter?
 
cs_hash_t hash () const
 Get a hash value for a procedure.
 
csint64 id () const
 Get the unique identifier of a procedure.
 
procedure_locals_iterator local_symbols () const
 Get an iterator over the local variables (symbol) that are declared in a procedure.
 
std::string name () const
 Get the user-friendly name of a procedure.
 
point_set points () const
 Get all the points in a procedure.
 
point preexit_point () const
 Get the preexit point of a procedure.
 
bool reachable () const
 Check: is a procedure reachable from the reachability roots specified with configuration file parameter REACHABILITY_ROOTS?
 
point retrieve_point (csint64 _id) const
 Get a point from a procedure by ID.
 
int stable_cmp (const procedure &other) const
 Compare with another procedure, with stable results across sufficiently-similar analyses.
 
csuint64 stable_hash () const
 Get a hash value for a procedure, with stable results across sufficiently-similar analyses.
 
std::string verbose_name () const
 Get the name of a procedure.
 

Related Symbols

(Note that these are not member symbols.)

bool operator!= (const procedure &a, const procedure &b)
 Inequality operator for procedure.
 
bool operator< (const procedure &a, const procedure &b)
 Less-than operator for procedure.
 
std::ostream & operator<< (std::ostream &out, const procedure &a)
 
 
bool operator<= (const procedure &a, const procedure &b)
 Less-than-or-equal operator for procedure.
 
bool operator== (const procedure &a, const procedure &b)
 Equality operator for procedure.
 
bool operator> (const procedure &a, const procedure &b)
 Greater-than operator for procedure.
 
bool operator>= (const procedure &a, const procedure &b)
 Greater-than-or-equal operator for procedure.
 

Detailed Description

A single procedure/function/method.

The procedure class corresponds to the PDG abstraction.

The following are useful for retrieving procedures.

Class Methods
compunit compunit::procedures()
point point::callee(), point::get_procedure()
project project::find_procedure(), project::procedures(), project::procedures_vector()
sfile sfile::procedures_on_line()

Member Function Documentation

◆ adjusted_callers()

procedure_adjusted_callers_iterator cs::procedure::adjusted_callers ( ) const
inline

Get an iterator over the call sites (point of kind point_kind::CALL_SITE or point_kind::INDIRECT_CALL) to a procedure, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.

Returns
The initialized procedure_adjusted_callers_iterator.

For a fixed project build and procedure, the iteration order is deterministic but does not correspond to the execution order or source file location of the call sites.

Indirect call resolution takes place in the pointer analysis phase, so results for indirect calls will be best if traversal takes place in the bottom-up phase or later. For both direct and indirect calls, traversal will fail if it is attempted before the beginning of the serial depth-first phase.

◆ as_repr()

std::string cs::procedure::as_repr ( ) const
inline

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

Returns
The string representation.

◆ as_string()

std::string cs::procedure::as_string ( ) const
inline

Get a simple string representation of a procedure object.

Returns
The string representation.

◆ basename()

std::string cs::procedure::basename ( ) const
inline

Get the basename of a procedure.

Returns
The procedure's basename.

The basename of a procedure is defined with respect to the friendly name (as returned by name()) as follows.

  • If the friendly name contains one or more scope resolution operators "::", the basename is the method name component (i.e., rightmost token). For example, if the friendly name is ClassName::MethodName, the basename is MethodName.
  • Otherwise, the basename is the same as the friendly name.

When cross-referencing queries (xr_query) are executed, the specified tokens are compared against procedure basenames, and query results (xr_tuple) from procedure name matches contain a hash of this basename. Therefore, use basename() to extract any procedure name that you want to use as a xr_query token or compare against query results.

  • Use the name obtained by name() to retrieve user-friendly procedure names for display.
  • Use the name obtained by verbose_name() for all other purposes.

◆ call_sites()

Get an iterator over the call sites in a procedure.

Parameters
flagsprocedure_call_sites_flags characterizing the kinds of call sites to iterate over.
Returns
The initialized iterator over the call sites in the procedure whose kinds are as specified by flags.

For a fixed project build and procedure, the iteration order is deterministic but does not correspond to the execution order or source file location of the call sites.

◆ call_sites_count()

size_t cs::procedure::call_sites_count ( procedure_call_sites_flags  flags = procedure_call_sites_flags::DIRECT) const
inline

Get the number of call sites in a procedure.

Parameters
flagsprocedure_call_sites_flags characterizing the kinds of call sites to count.
Returns
The number of call sites in the procedure whose kinds are as specified by flags.

For a fixed procedure P and procedure_call_sites_flags F, P.call_sites_count(F) will match:

  • The iteration count of the iterator returned by P.call_sites(F).
  • The number of items in the std::vector returned by P.call_sites_vector().

◆ call_sites_vector()

std::vector< point > cs::procedure::call_sites_vector ( procedure_call_sites_flags  flags = procedure_call_sites_flags::DIRECT) const
inline

Get a std::vector of the call sites in a procedure.

Parameters
[in]flagsprocedure_call_sites_flags indicating what kinds of call sites are of interest.
Returns
The call sites in the procedure whose kinds are as specified by flags.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

For a fixed procedure P and procedure_call_sites_flags F, the length of P.call_sites_vector(F) will match the value returned by P.call_sites_count(F).

Use call_sites() to get an iterator over the call sites.

◆ callers()

procedure_callers_iterator cs::procedure::callers ( ) const
inline

Get an iterator over the direct call sites (point of kind point_kind::CALL_SITE) whose target is this.

Returns
The initialized iterator.

For a fixed project build and procedure, the iteration order is deterministic but does not correspond to the execution order or source file location of the call sites.

◆ callers_count()

size_t cs::procedure::callers_count ( ) const
inline

Get the number of direct callers of a procedure.

Returns
The number of direct call sites (point of kind point_kind::CALL_SITE) whose target is this.

For a procedure P, P.callers_count() will match the iteration count of the iterator returned by P.callers().

◆ cmp()

cs::procedure::cmp ( const procedure other) const
inline

Comparison function for procedure.

Parameters
otherThe procedure 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 procedure object.

◆ demangled_name()

std::string cs::procedure::demangled_name ( ) const
inline

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

Returns
The procedure's demangled user-friendly name.

In a mixed-mode project (source and binary together) this will return the demangled name for source (C/C++) procedures - closer to the "verbose" name than the friendly name.

Exceptions
result::NOT_IMPLEMENTEDif the CodeSonar installation does not include binary analysis functionality.

◆ entry_point()

point cs::procedure::entry_point ( ) const
inline

Get the entry point of a procedure.

Returns
The entry point (whose point_kind is point_kind::ENTRY) for the procedure.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

◆ exit_point()

point cs::procedure::exit_point ( ) const
inline

Get the exit point of a procedure.

Returns
The exit point (whose point_kind is point_kind::EXIT) for the procedure.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

The exit point has no incoming or outgoing control dependences or data dependences. It is part of the CFG.

◆ file_line()

sfileinst_line_pair cs::procedure::file_line ( ) const
inline

Get the file instance and (smallest offset) line of the entry point for a procedure.

Returns
A pair encoding the source file instance containing the procedure entry point and the (smallest offset) line on which the entry point occurs in that source file instance.
Exceptions
result::NO_POSITIONif the procedure has kind procedure_kind::UNDEFINED or its entry point does not have a position.

◆ find_containing_symbol_by_offset()

symbol cs::procedure::find_containing_symbol_by_offset ( csint32  off) const
inline

[Binary analyses only] Get the procedure local containing the given stack offset.

Parameters
offThe stack offset to look up.
Returns
The symbol in the procedure that contains stack offset off.
Exceptions
result::NOT_IMPLEMENTEDif the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENTif no symbol is found at offset off. This can occur if the project is not a binary project, or if off is "invalid".

◆ find_symbol_by_offset()

symbol cs::procedure::find_symbol_by_offset ( csint32  off) const
inline

[Binary analyses only] Get the procedure local with the given stack offset.

Parameters
offThe stack offset to look up.
Returns
The symbol in the procedure whose stack offset is off.
Exceptions
result::NOT_IMPLEMENTEDif the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENTif no symbol is found at offset off. This can occur if the project is not a binary project, or if off is "invalid".

◆ formal_in()

point cs::procedure::formal_in ( size_t  rank)
inline

Get the point corresponding to the formal-in with the specified rank.

Parameters
[in]rankThe rank of the desired parameter.
Returns
The point corresponding to the formal-in parameter whose rank is rank.

Rank starts at 1, with globals coming first, followed by non-globals. Note that only non-globals can be retrieved by this function.

Exceptions
result::ELEMENT_NOT_PRESENTif the procedure has no formal-in parameter with the specified rank.
result::ERROR_INVALID_ARGUMENTif rank is negative.
result::PDG_IS_UNDEFINEDif this has kind procedure_kind::UNDEFINED.

◆ formal_ins()

point_set cs::procedure::formal_ins ( ) const
inline

Get the formal-in and global-formal-in points of a procedure.

Returns
The procedure's formal-ins (point of kind point_kind::FORMAL_IN) and global-formal-ins (point of kind point_kind::GLOBAL_FORMAL_IN), as a point_set.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

Methods formal_ins() and formal_ins_vector() retrieve different sets:

◆ formal_ins_vector()

std::vector< point > cs::procedure::formal_ins_vector ( ) const
inline

Get a std::vector containing the formal-in points of a procedure.

Returns
A std::vector containing the procedure's formal-ins (point of kind point_kind::FORMAL_IN), in the order in which they occur in the code.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

Methods formal_ins() and formal_ins_vector() retrieve different sets:

◆ formal_outs()

point_set cs::procedure::formal_outs ( ) const
inline

Get the formal-out and global-formal-out points of a procedure.

Returns
The procedure's formal-outs (point of kind point_kind::FORMAL_OUT) and global-formal-outs (point of kind point_kind::GLOBAL_FORMAL_OUT), as a point_set.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

Methods formal_outs() and formal_outs_vector() retrieve different sets:

◆ formal_outs_vector()

std::vector< point > cs::procedure::formal_outs_vector ( ) const
inline

Get the formal-out points of a procedure.

Returns
A std::vector of listing the formal-out parameters (point of kind point_kind::FORMAL_OUT), in the order in which they occur in the code.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

Methods formal_outs() and formal_outs_vector() retrieve different sets:

◆ get_address()

effective_address cs::procedure::get_address ( ) const
inline

[Binary analyses only] Get the effective address of a procedure, if there is one.

Returns
The procedure's effective address.
Exceptions
result::NOT_IMPLEMENTEDif the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENTif the procedure does not have an effective address, possibly because it is not a machine-code procedure.

This function typically associates an address with the "first" point of a procedure, generally the entry point.

The mapping between addresses and procedures is still not quite one-to-one, however, because of procedure cloning; multiple procedures can have the same address.

◆ get_ast()

ast cs::procedure::get_ast ( ast_family  family = ast_family::DEFAULT) const
inline

Retrieve the AST for a procedure.


Parameters
[in]familyProcedures may be associated with multiple ASTs. This specifies which one to get.
Returns
The ast of ast_family family that is associated with the procedure.
Exceptions
result::ELEMENT_NOT_PRESENTif no AST of the specified family is associated with the procedure.
result::ERROR_INVALID_ARGUMENTif family is not a valid ast_family.

◆ get_compunit()

compunit cs::procedure::get_compunit ( ) const
inline

Get the compilation unit containing a procedure.

Returns
The compilation unit (compunit).

◆ get_kind()

procedure_kind cs::procedure::get_kind ( ) const
inline

Retrieve the procedure_kind of a procedure.


Returns
The procedure's procedure_kind.

◆ get_symbol()

symbol cs::procedure::get_symbol ( ) const
inline

Get the symbol for a procedure.

Returns
The symbol.

◆ handle()

std::string cs::procedure::handle ( ) const
inline

Get a handle for this procedure.

Returns
The procedure's handle.

Use this function to retrieve a handle to the procedure which can be stored externally and used with project::lookup_procedure_handle() to retrieve the procedure 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_vararg()

bool cs::procedure::has_vararg ( ) const
inline

Check: does a procedure have a formal vararg parameter?

Returns
true if the procedure has a formal vararg parameter; false otherwise.

◆ hash()

cs_hash_t cs::procedure::hash ( ) const
inline

Get a hash value for a procedure.

◆ id()

csint64 cs::procedure::id ( ) const
inline

Get the unique identifier of a procedure.

Returns
The unique identifier.
  • In an incremental analysis, a procedure will have the same identifier that it did in the incremental parent if and only if the containing compilation unit is not recompiled. If the containing compilation unit is recompiled, the procedure will have a new unique identifier not previously used for any procedure in any incremental ancestor analysis.
  • In all other cases identifiers do not persist between different analyses of the same project (or the same code in a different project).

To get a procedure given its ID, use project::find_procedure(csint64).

◆ local_symbols()

procedure_locals_iterator cs::procedure::local_symbols ( ) const
inline

Get an iterator over the local variables (symbol) that are declared in a procedure.

Returns
The initialized iterator.

To iterate over nonlocal variables for a compilation unit, use the iterator returned by compunit::global_symbols(). Note that neither a compilation unit globals iterator nor a procedure locals iterator will access symbols of kind symbol_kind::PARAM. To iterate over these, call project::param_symbol() with increasing num argument until you get a result::ELEMENT_NOT_PRESENT error.

◆ name()

std::string cs::procedure::name ( ) const
inline

Get the user-friendly name of a procedure.

Returns
The procedure's user-friendly name.

For C++ methods, the returned user-friendly name will be of the form ClassName::MethodName.

  • Namespace::ClassName::MethodName if the class is a member of a namespace.
  • Class1Name::ClassName::MethodName if the class is nested inside another class.
  • (etc)

Use this method only to retrieve user-friendly procedure names for display.

  • Use the name obtained by basename() to obtain procedure name tokens to use in cross-referencing queries (xr_query).
  • Use the name obtained by verbose_name() for all other purposes.

◆ points()

point_set cs::procedure::points ( ) const
inline

Get all the points in a procedure.

Returns
A point_set containing all the points (point) in the procedure.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

◆ preexit_point()

point cs::procedure::preexit_point ( ) const
inline

Get the preexit point of a procedure.

Returns
The preexit point (whose point_kind is point_kind::PREEXIT) for the procedure.
Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.

The preexit point has no incoming or outgoing control dependences or data dependences. It is part of the CFG.

◆ reachable()

bool cs::procedure::reachable ( ) const
inline

Check: is a procedure reachable from the reachability roots specified with configuration file parameter REACHABILITY_ROOTS?

Returns
true if the procedure is reachable from the reachability roots, false if it is not reachable.
Exceptions
result::ELEMENT_NOT_PRESENTif no reachability roots were specified with configuration file parameter REACHABILITY_ROOTS. (Note that the main analysis handles this case by treating all procedures as reachable.)
result::ERROR_INVALID_PHASE_FOR_OPERATIONif this method was called before the beginning of the serial depth-first traversal.

◆ retrieve_point()

point cs::procedure::retrieve_point ( csint64  _id) const
inline

Get a point from a procedure by ID.

Parameters
[in]_idThe identifier of the desired point.
Returns
The point whose ID is _id.

To get a point's ID, use point::id().

Exceptions
result::PDG_IS_UNDEFINEDif the procedure has kind procedure_kind::UNDEFINED.
result::NO_SUCH_PDG_VERTEXif there is no point in the procedure whose ID is _id.

◆ stable_cmp()

int cs::procedure::stable_cmp ( const procedure other) const
inline

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

Parameters
[in]otherThe procedure 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 procedure objects in A1, and a2 and b2 be the point 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::procedure::stable_hash ( ) const
inline

Get a hash value for a procedure, 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 procedure object in A1, and v2 be the procedure 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.

◆ verbose_name()

std::string cs::procedure::verbose_name ( ) const
inline

Get the name of a procedure.

Returns
The procedure name.

See also name(), basename().

In some cases, a single procedure P will have markedly different values for P.name() and P.verbose_name(). For example, consider the following program. Let F be the procedure for function foo(), then F.name() is "foo", but F.verbose_name() is "bar".

void foo() asm("bar");
void foo() {
printf("1234");
}
int main() {
foo();
}

Friends And Related Symbol Documentation

◆ operator!=()

bool operator!= ( const procedure a,
const procedure b 
)
related

Inequality operator for procedure.

Parameters
[in]aThe procedure to compare.
[in]bThe procedure to compare against.
Returns
false if a and b are equal according to procedure::cmp(), true otherwise.

◆ operator<()

bool operator< ( const procedure a,
const procedure b 
)
related

Less-than operator for procedure.

Parameters
[in]aThe procedure to compare.
[in]bThe procedure to compare against.
Returns
true if a < b according to procedure::cmp() , false otherwise.

◆ operator<<()

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


Print a representation of a procedure object to the specified stream.

Parameters
[in]outThe stream to print to.
[in]aThe procedure object to print.
Returns
void

◆ operator<=()

bool operator<= ( const procedure a,
const procedure b 
)
related

Less-than-or-equal operator for procedure.

Parameters
[in]aThe procedure to compare.
[in]bThe procedure to compare against.
Returns
true if a <= b according to procedure::cmp() , false otherwise.

◆ operator==()

bool operator== ( const procedure a,
const procedure b 
)
related

Equality operator for procedure.

Parameters
[in]aThe procedure to compare.
[in]bThe procedure to compare against.
Returns
true if a and b are equal according to procedure::cmp(), false otherwise.

◆ operator>()

bool operator> ( const procedure a,
const procedure b 
)
related

Greater-than operator for procedure.

Parameters
[in]aThe procedure to compare.
[in]bThe procedure to compare against.
Returns
true if a > b according to procedure::cmp() , false otherwise.

◆ operator>=()

bool operator>= ( const procedure a,
const procedure b 
)
related

Greater-than-or-equal operator for procedure.

Parameters
[in]aThe procedure to compare.
[in]bThe procedure to compare against.
Returns
true if a >= b according to procedure::cmp() , false otherwise.

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