|
CodeSonar C++ API
|
A single program point. More...
Public Member Functions | |
| point | actual_in (size_t _rank) const |
| Get the actual-in, having the specified rank, associated with a call site point. | |
| point | actual_out (size_t _rank) const |
| Get the actual-out, having the specified rank, associated with a call site point. | |
| point_set | actual_to_formals () const |
| Get the formal-in points associated with an actual-in point. | |
| point_set | actuals_in () const |
| Get the actual-in and global-actual-in points associated with a call site point. | |
| std::vector< point > | actuals_in_as_list () const |
| Get the actual-in and global-actual-in points associated with a call site point. | |
| point_set | actuals_out () const |
| Get the actual-out and global-actual-out points associated with a call site point. | |
| std::vector< point > | actuals_out_as_list () const |
| Get the actual-out points associated with a call site point. | |
| procedure | adjusted_callee () const |
Get the callee procedure of a call site point, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable. | |
| procedure | adjusted_callee_no_reroute () const |
Get the callee procedure of a call site point, ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable. | |
| point_adjusted_callees_iterator | adjusted_callees () const |
Get an iterator over the callee procedures (procedure) from a point, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable. | |
| point_adjusted_callees_no_reroute_iterator | adjusted_callees_no_reroute () const |
Get an iterator over the callee procedures (procedure) from a point, ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable. | |
| std::string | as_repr () const |
| Get a representation of a point object that includes information useful for debugging. | |
| std::string | as_string () const |
| Get a string representation of a point containing information useful for debugging. | |
| point | call_site () const |
| Get the call site of a subordinate point. | |
| procedure | callee () const |
| Get the callee procedure associated with a call-site point. | |
| cfg_edge_set | cfg_inter_targets () const |
| Get the inter-procedural successors of a point. | |
| cfg_edge_set | cfg_targets () const |
| Get the intra-procedural successors of a point. | |
| std::string | characters (size_t limit=SIZE_MAX) const |
| Get a string representation of a point. | |
| sfileinst_int_pair_set_pair | charpos () const |
| Get the character positions (in the source code) for a point. | |
| int | cmp (const point &other) const |
| Comparison function for point. | |
| csuint64 | condition_number () const |
| [CodeSonar only] Get the condition number of a point. | |
| symbol_vector | csonar_enum_killed () const |
| Get the list of killed symbols (symbol) for a point, computing the list on-demand. | |
| symbol_vector | csonar_enum_referenced () const |
| Get the list of referenced symbols (symbol) for a point, computing the list on-demand. | |
| symbol_vector | csonar_enum_used () const |
| Get the list of used symbols (symbol) for a point, computing the list on-demand. | |
| sfileinst_line_pair | file_line () const |
| Get the file instance and (smallest offset) line for a point. | |
| effective_address | get_address () const |
| [Binary analyses only] Get the effective address of a point, if it has one. | |
| effective_address | get_affiliated_address () const |
| [Binary analyses only] Get the effective address affiliated with a point, if there is one. | |
| ast | get_ast (ast_family fam=ast_family::DEFAULT) const |
| Get the AST associated with a point. | |
| point_kind | get_kind () const |
| Get a point's kind. | |
| procedure | get_procedure () const |
| Get the procedure containing a point. | |
| point_syntax_element | get_syntax_element () const |
| Get a point's syntax element. | |
| point_syntax_kind | get_syntax_kind () const |
| Get a point's syntax kind. | |
| std::string | handle () const |
| Get a handle for this point. | |
| bool | has_ast (ast_family fam=ast_family::DEFAULT) const |
| Check: does a point have an associated AST (ast) of the specified family (ast_family)? | |
| cs_hash_t | hash () const |
| Get a hash value for a point. | |
| csint64 | id () const |
| Get a point's unique identifier. | |
| bool | is_implicit_actual_in () const |
| Check: is a point an actual-in that is implicitly generated? | |
| bool | is_inside_macro () const |
| Check: is a point entirely contained inside a macro? | |
| size_t | rank () const |
| Get the rank of a point. | |
| point | solitary_cfg_target () const |
| Get the CFG successor of a point that has exactly one successor CFG edge. | |
| std::string | source_pp () const |
| [CodeSonar only] Get a string containing a pretty printed version of an actual-in, expression, call-site, or control-point point. | |
| int | stable_cmp (const point &other) const |
| Compare with another point, with stable results across sufficiently-similar analyses. | |
| csuint64 | stable_hash () const |
| Get a hash value for a point, with stable results across sufficiently-similar analyses. | |
Related Symbols | |
(Note that these are not member symbols.) | |
| bool | operator!= (const point &a, const point &b) |
| Inequality operator for point. | |
| bool | operator< (const point &a, const point &b) |
| Less-than operator for point. | |
| std::ostream & | operator<< (std::ostream &out, const point &a) |
| bool | operator<= (const point &a, const point &b) |
| Less-than-or-equal operator for point. | |
| bool | operator== (const point &a, const point &b) |
| Equality operator for point. | |
| bool | operator> (const point &a, const point &b) |
| Greater-than operator for point. | |
| bool | operator>= (const point &a, const point &b) |
| Greater-than-or-equal operator for point. | |
A single program point.
The point class corresponds to the PDG_VERTEX abstraction.
Internal representation for points is available for C/C++ and binary analyses only. For C# and Java analyses, plug-ins that rely on point properties and relationships will generally not produce useful information.
|
inline |
Get the actual-in, having the specified rank, associated with a call site point.
| [in] | _rank | The (1-based) index of the actual-in to retrieve. |
| result::ERROR_NOT_A_CALL_SITE | if the point does not represent a call site. |
| result::ERROR_INVALID_ARGUMENT | if _rank is 0. |
| result::ELEMENT_NOT_PRESENT | if there is no actual-in whose rank is _rank. |
|
inline |
Get the actual-out, having the specified rank, associated with a call site point.
| [in] | _rank | The (1-based) index of the actual-out to retrieve. |
| result::ERROR_NOT_A_CALL_SITE | if the point does not represent a call site. |
| result::ERROR_INVALID_ARGUMENT | if _rank is 0. |
| result::ELEMENT_NOT_PRESENT | if there is no actual-out whose rank is _rank. |
In most languages (including C and C++), only an actual-out of rank 1 can exist. It corresponds to the return value of a function.
|
inline |
Get the formal-in points associated with an actual-in point.
| result::ERROR_SDG_NOT_PRESENT | |
| result::ERROR_NOT_AN_ACTUAL_IN | if the point is not an actual-in. |
| result::ELEMENT_NOT_PRESENT | if there is no call site associated with the point. |
| result::ERROR_NOT_A_CALL_SITE | if the call site associated with the point is an indirect call. |
| result::PDG_IS_UNDEFINED | if the call site associated with the point is an undefined function. |
The modeling of GNU extension __builtin_apply leads to the possibility that more than one formal can be associated with a given actual. In this case, the returned point_set will contain several formals.
|
inline |
Get the actual-in and global-actual-in points associated with a call site point.
| result::ERROR_NOT_A_CALL_SITE | if the point does not represent a call site. |
|
inline |
Get the actual-in and global-actual-in points associated with a call site point.
| result::ERROR_NOT_A_CALL_SITE | if the point does not represent a call site. |
|
inline |
Get the actual-out and global-actual-out points associated with a call site point.
| result::ERROR_NOT_A_CALL_SITE | if the point does not represent a call site. |
|
inline |
Get the actual-out points associated with a call site point.
| result::ERROR_NOT_A_CALL_SITE | if the point does not represent a call site. |
|
inline |
Get the callee procedure of a call site point, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
| result::ERROR_NOT_A_CALL_SITE | if the point is not a call site. |
| result::NO_SUCH_PDG | if v is a call site but its callee procedure cannot be determined. |
| result::ELEMENT_NOT_PRESENT | if the point is a call site with more than one callee procedure. No procedure will be returned in this case: to traverse all callees, use the point_adjusted_callees_iterator returned by adjusted_callees(). |
| result::ERROR_INVALID_PHASE_FOR_OPERATION | if called before the beginning of the bottom-up phase. |
Redirection resolution is completed in the pointer analysis phase, so this function must be called in the bottom-up phase or later.
A direct call site (that is, a point of kind point_kind::CALL_SITE will always have exactly one callee.
An indirect call site (a kind point_kind::INDIRECT_CALL) can have zero or more callees. This function will only successfully retrieve a callee if the analysis identifies exactly one callee.
Use the point_adjusted_callees_iterator returned by adjusted_callees() to iterate over all callees of a point, taking into account translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
|
inline |
Get the callee procedure of a call site point, ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
| result::ERROR_NOT_A_CALL_SITE | |
| result::NO_SUCH_PDG | |
| result::ELEMENT_NOT_PRESENT | if the point is a call site with more than one callee procedure. No procedure will be returned in this case: to traverse all callees, use the point_adjusted_callees_no_reroute_iterator returned by adjusted_callees_no_reroute(). |
A direct call site (that is, a point of kind point_kind::CALL_SITE will always have exactly one callee.
An indirect call site (a kind point_kind::INDIRECT_CALL) can have zero or more callees. This function will only successfully retrieve a callee if the analysis identifies exactly one callee. Indirect call resolution takes place in the pointer analysis phase, so results for indirect call sites will be best if this function is called in the bottom-up phase or later.
Use the point_adjusted_callees_no_reroute_iterator returned by adjusted_callees_no_reroute() to iterate over all callees of a point, ignoring translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
|
inline |
Get an iterator over the callee procedures (procedure) from a point, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
A direct call site (that is, a point of kind point_kind::CALL_SITE) will always have exactly one callee. As an alternative to setting up an iterator, you can use adjusted_callee() to retrieve the callee, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
An indirect call site (point of kind point_kind::INDIRECT_CALL) can have zero or more callees.
|
inline |
Get an iterator over the callee procedures (procedure) from a point, ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
A direct call site (that is, a point of kind point_kind::CALL_SITE) will always have exactly one callee. As an alternative to setting up an iterator, you can use adjusted_callee_no_reroute() to retrieve the callee, ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
An indirect call site (point of kind point_kind::INDIRECT_CALL) can have zero or more callees.
|
inline |
Get a representation of a point object that includes information useful for debugging.
|
inline |
Get a string representation of a point containing information useful for debugging.
|
inline |
Get the call site of a subordinate point.
A subordinate point is one whose kind is one of the following.
| result::ELEMENT_NOT_PRESENT | if no corresponding call site exists: either the point is not of an a suitable kind, or it is an indirect-call with no corresponding call site. |
|
inline |
Get the callee procedure associated with a call-site point.
| result::ERROR_SDG_NOT_PRESENT | if no project is loaded. |
| result::ERROR_NOT_A_CALL_SITE | if the point does not represent a call site. |
| result::ELEMENT_NOT_PRESENT | if the point represents a call site, but there is no associated callee. |
|
inline |
Get the inter-procedural successors of a point.
| result::ERROR_SDG_NOT_PRESENT | if no project is loaded. |
| result::ERROR_NO_DEPENDENCES | [CodeSonar only] if the kind of this is one of point_kind::EXIT, point_kind::CALL_SITE, point_kind::INDIRECT_CALL, point_kind::ACTUAL_IN. This affects only CodeSonar: CodeSurfer retains more dependence information. |
See CFG Edges for more information.
|
inline |
Get the intra-procedural successors of a point.
| result::ERROR_SDG_NOT_PRESENT | if no project is loaded. |
See CFG Edges for more information.
|
inline |
Get a string representation of a point.
| [in] | limit | The maximum length of the retrieved representation. Specify SIZE_MAX for no limit. |
| result::ELEMENT_NOT_PRESENT | if there is no position information associated with the point. |
|
inline |
Get the character positions (in the source code) for a point.
| result::NO_POSITION | if this does not have a position in any file in the project |
|
inline |
|
inline |
[CodeSonar only] Get the condition number of a point.
Each group of points in the same conditional will share the same condition number. The value has no meaning, beyond grouping vertices by conditional. A conditional is defined as the predicate of one if statement or loop. Multiple vertices can arise from one conditional because normalizations decompose a single if statement into many vertices in the presence of language features such as short-circuiting connectives.
|
inline |
|
inline |
|
inline |
|
inline |
Get the file instance and (smallest offset) line for a point.
| result::NO_POSITION | if the point does not have a position in any file instance in the project. |
|
inline |
[Binary analyses only] Get the effective address of a point, if it has one.
| result::NOT_IMPLEMENTED | if the CodeSonar installation does not include binary analysis functionality. |
| result::ELEMENT_NOT_PRESENT | if the point does not have an effective address, either because it is not a machine-code point or because it is not directly assocated with an instruction. |
This function typically only associates an address with the "first" point of an instruction. For example, call instructions get expanded to several points: an expression or control point, the actual call-site vertex, potentially multiple actual-ins, and potentially multiple actual-outs. Only the expression/control point will have an address per this function.
See get_affiliated_address() for a version of this function that tries harder to find a sensible address. In the case of the call-site vertex, all points will have an "affiliated" address that agrees with that of the expression/control point.
The mapping between addresses and points is still not quite one-to-one however, because of procedure cloning and other issues; multiple vertices can have the same address.
|
inline |
[Binary analyses only] Get the effective address affiliated with a point, if there is one.
| result::NOT_IMPLEMENTED | if the CodeSonar installation does not include binary analysis functionality. |
| result::ELEMENT_NOT_PRESENT | if the point does not have an effective address, either because it is not a machine-code point or because it is an exit point. |
See get_address() for a discussion of what "affiliated" means.
|
inline |
Get the AST associated with a point.
| [in] | fam | Points may be associated with multiple ASTs. This specifies which one to get. |
fam that is associated with the point.| result::ERROR_SDG_NOT_PRESENT | if no project is loaded |
| result::ELEMENT_NOT_PRESENT | if the point does not have an associated AST of family fam. This includes the case where the project was not built to include ASTs of family fam, and the case where fam is ast_family::C_UNNORMALIZED |
|
inline |
Get a point's kind.
|
inline |
|
inline |
Get a point's syntax element.
|
inline |
Get a point's syntax kind.
|
inline |
Get a handle for this point.
Use this function to retrieve a handle to the point which can be stored externally and used with project::lookup_point_handle() to retrieve the point 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 "_".
|
inline |
Check: does a point have an associated AST (ast) of the specified family (ast_family)?
| [in] | fam | Points may be associated with multiple ASTs. This specifies which one to check for. Each language dependent AST header file will define its AST families. |
true if the point has an associated AST whose family is fam, false otherwise.
|
inline |
Get a hash value for a point.
|
inline |
Get a point's unique identifier.
To get a point given its ID, use procedure::retrieve_point().
|
inline |
Check: is a point an actual-in that is implicitly generated?
true if called on a point that is an actual-in and is implicit. false otherwiseAn implicit actual-in can occur in C++ code where the callee returns a non-trivial C++ object. For example:
will have two actual-ins, where the first is implicit:
Note that default arguments are not considered implicit, despite also not being being written at the call site.
|
inline |
Check: is a point entirely contained inside a macro?
true if called on a point that lies entirely inside a C or C++ macro expansion. false otherwise, including the case where only part of the point is inside a macro expansion.This function will return false if called on a point for which only only part is inside a macro expansion, such as the point corresponding to the assignment "p = NULL".
|
inline |
Get the rank of a point.
Rank starts at 1, with globals coming first, followed by non-globals. For non-globals, rank shows the order they appear in the source.
| result::VERTEX_HAS_NO_RANK | if the point is not a {formal,actual}-{in,out} or global-{formal,actual}-{in,out}: these are the only points that have rank. |
|
inline |
Get the CFG successor of a point that has exactly one successor CFG edge.
| result::ERROR_SDG_NOT_PRESENT | |
| result::PDG_VERTEX_HAS_ZERO_OR_MULTIPLE_SUCCESSORS | if the point does not have exactly one successor CFG edge (this includes the case where it has one CFG successor but multiple CFG edges to that successor). |
See CFG Edges for more information.
|
inline |
[CodeSonar only] Get a string containing a pretty printed version of an actual-in, expression, call-site, or control-point point.
| result::ERROR_INVALID_ARGUMENT | if called on a point that is not an actual-in, expression, call-site, or control-point. |
| result::ELEMENT_NOT_PRESENT | if the point does not have the necessary information associated with it. |
|
inline |
Compare with another point, with stable results across sufficiently-similar analyses.
| [in] | other | The point to compare against. |
this considered less than other this and other are the same objectthis 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 point 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.
|
inline |
Get a hash value for a point, with stable results across sufficiently-similar analyses.
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 point object in A1, and v2 be the point 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.
Inequality operator for point.
false if a and b are equal according to point::cmp(), true otherwise. Less-than operator for point.
true if a < b according to point::cmp() , false otherwise.
|
related |
Less-than-or-equal operator for point.
true if a <= b according to point::cmp() , false otherwise. Equality operator for point.
true if a and b are equal according to point::cmp(), false otherwise. Greater-than operator for point.
true if a > b according to point::cmp() , false otherwise. Greater-than-or-equal operator for point.
true if a >= b according to point::cmp() , false otherwise.