|
CodeSonar C++ API
|
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< point > | call_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< point > | formal_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< point > | formal_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. | |
A single procedure/function/method.
The procedure class corresponds to the PDG abstraction.
The following are useful for retrieving procedures.
|
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.
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.
|
inline |
Get a representation of a procedure object that includes information useful for debugging.
|
inline |
Get a simple string representation of a procedure object.
|
inline |
Get the basename of a procedure.
The basename of a procedure is defined with respect to the friendly name (as returned by name()) as follows.
ClassName::MethodName, the basename is MethodName.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.
|
inline |
Get an iterator over the call sites in a procedure.
| flags | procedure_call_sites_flags characterizing the kinds of call sites to iterate over. |
flags.flags includes procedure_call_sites_flags::DIRECT, the iterator will include all points (point) in the procedure whose kind is point_kind::CALL_SITE.flags includes procedure_call_sites_flags::INDIRECT, the iterator will include all points (point) in the procedure whose kind is point_kind::INDIRECT_CALL.flags contains only procedure_call_sites_flags::NONE, the iterator will be empty.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.
|
inline |
Get the number of call sites in a procedure.
| flags | procedure_call_sites_flags characterizing the kinds of call sites to count. |
flags.flags includes procedure_call_sites_flags::DIRECT, the count will include all points (point) in the procedure whose kind is point_kind::CALL_SITE.flags includes procedure_call_sites_flags::INDIRECT, the count will include all points (point) in the procedure whose kind is point_kind::INDIRECT_CALL.flags contains only procedure_call_sites_flags::NONE, the count will be zero (0).For a fixed procedure P and procedure_call_sites_flags F, P.call_sites_count(F) will match:
P.call_sites(F).P.call_sites_vector().
|
inline |
Get a std::vector of the call sites in a procedure.
| [in] | flags | procedure_call_sites_flags indicating what kinds of call sites are of interest. |
flags.flags includes procedure_call_sites_flags::DIRECT, the return value will include all points (point) in the procedure whose kind is point_kind::CALL_SITE.flags includes procedure_call_sites_flags::INDIRECT, the return value will include all points (point) in the procedure whose kind is point_kind::INDIRECT_CALL.flags contains only procedure_call_sites_flags::NONE, the return value will be an empty std::vector.| result::PDG_IS_UNDEFINED | if 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.
|
inline |
Get an iterator over the direct call sites (point of kind point_kind::CALL_SITE) whose target is this.
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.
|
inline |
Get the number of direct callers of a procedure.
this.For a procedure P, P.callers_count() will match the iteration count of the iterator returned by P.callers().
|
inline |
|
inline |
[Binary analyses only] Get the demangled user-friendly name of a procedure.
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.
| result::NOT_IMPLEMENTED | if the CodeSonar installation does not include binary analysis functionality. |
|
inline |
Get the entry point of a procedure.
| result::PDG_IS_UNDEFINED | if the procedure has kind procedure_kind::UNDEFINED. |
|
inline |
Get the exit point of a procedure.
| result::PDG_IS_UNDEFINED | if 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.
|
inline |
Get the file instance and (smallest offset) line of the entry point for a procedure.
| result::NO_POSITION | if the procedure has kind procedure_kind::UNDEFINED or its entry point does not have a position. |
|
inline |
[Binary analyses only] Get the procedure local containing the given stack offset.
| off | The stack offset to look up. |
off.| result::NOT_IMPLEMENTED | if the CodeSonar installation does not include binary analysis functionality. |
| result::ELEMENT_NOT_PRESENT | if no symbol is found at offset off. This can occur if the project is not a binary project, or if off is "invalid". |
|
inline |
[Binary analyses only] Get the procedure local with the given stack offset.
| off | The stack offset to look up. |
off.| result::NOT_IMPLEMENTED | if the CodeSonar installation does not include binary analysis functionality. |
| result::ELEMENT_NOT_PRESENT | if no symbol is found at offset off. This can occur if the project is not a binary project, or if off is "invalid". |
|
inline |
Get the point corresponding to the formal-in with the specified rank.
| [in] | rank | The rank of the desired parameter. |
rank.Rank starts at 1, with globals coming first, followed by non-globals. Note that only non-globals can be retrieved by this function.
| result::ELEMENT_NOT_PRESENT | if the procedure has no formal-in parameter with the specified rank. |
| result::ERROR_INVALID_ARGUMENT | if rank is negative. |
| result::PDG_IS_UNDEFINED | if this has kind procedure_kind::UNDEFINED. |
|
inline |
Get the formal-in and global-formal-in points of a procedure.
| result::PDG_IS_UNDEFINED | if the procedure has kind procedure_kind::UNDEFINED. |
Methods formal_ins() and formal_ins_vector() retrieve different sets:
|
inline |
Get a std::vector containing the formal-in points of a procedure.
| result::PDG_IS_UNDEFINED | if the procedure has kind procedure_kind::UNDEFINED. |
Methods formal_ins() and formal_ins_vector() retrieve different sets:
|
inline |
Get the formal-out and global-formal-out points of a procedure.
| result::PDG_IS_UNDEFINED | if the procedure has kind procedure_kind::UNDEFINED. |
Methods formal_outs() and formal_outs_vector() retrieve different sets:
|
inline |
Get the formal-out points of a procedure.
| result::PDG_IS_UNDEFINED | if the procedure has kind procedure_kind::UNDEFINED. |
Methods formal_outs() and formal_outs_vector() retrieve different sets:
|
inline |
[Binary analyses only] Get the effective address of a procedure, if there is one.
| result::NOT_IMPLEMENTED | if the CodeSonar installation does not include binary analysis functionality. |
| result::ELEMENT_NOT_PRESENT | if 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.
|
inline |
Retrieve the AST for a procedure.
| [in] | family | Procedures may be associated with multiple ASTs. This specifies which one to get. |
family that is associated with the procedure.| result::ELEMENT_NOT_PRESENT | if no AST of the specified family is associated with the procedure. |
| result::ERROR_INVALID_ARGUMENT | if family is not a valid ast_family. |
|
inline |
Get the compilation unit containing a procedure.
|
inline |
|
inline |
|
inline |
Get a handle for this procedure.
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 "_".
|
inline |
Check: does a procedure have a formal vararg parameter?
true if the procedure has a formal vararg parameter; false otherwise.
|
inline |
Get a hash value for a procedure.
|
inline |
Get the unique identifier of a procedure.
To get a procedure given its ID, use project::find_procedure(csint64).
|
inline |
Get an iterator over the local variables (symbol) that are declared in a procedure.
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.
|
inline |
Get the user-friendly name of a procedure.
For C++ methods, the returned user-friendly name will be of the form ClassName::MethodName.
Use this method only to retrieve user-friendly procedure names for display.
|
inline |
Get all the points in a procedure.
| result::PDG_IS_UNDEFINED | if the procedure has kind procedure_kind::UNDEFINED. |
|
inline |
Get the preexit point of a procedure.
| result::PDG_IS_UNDEFINED | if 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.
|
inline |
Check: is a procedure reachable from the reachability roots specified with configuration file parameter REACHABILITY_ROOTS?
true if the procedure is reachable from the reachability roots, false if it is not reachable.| result::ELEMENT_NOT_PRESENT | if 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_OPERATION | if this method was called before the beginning of the serial depth-first traversal. |
|
inline |
Get a point from a procedure by ID.
| [in] | _id | The identifier of the desired point. |
_id.To get a point's ID, use point::id().
| result::PDG_IS_UNDEFINED | if the procedure has kind procedure_kind::UNDEFINED. |
| result::NO_SUCH_PDG_VERTEX | if there is no point in the procedure whose ID is _id. |
|
inline |
Compare with another procedure, with stable results across sufficiently-similar analyses.
| [in] | other | The procedure 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 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.
|
inline |
Get a hash value for a procedure, 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 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.
|
inline |
Get the name of a procedure.
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".
Inequality operator for procedure.
false if a and b are equal according to procedure::cmp(), true otherwise. Less-than operator for procedure.
true if a < b according to procedure::cmp() , false otherwise.
|
related |
Less-than-or-equal operator for procedure.
true if a <= b according to procedure::cmp() , false otherwise. Equality operator for procedure.
true if a and b are equal according to procedure::cmp(), false otherwise. Greater-than operator for procedure.
true if a > b according to procedure::cmp() , false otherwise. Greater-than-or-equal operator for procedure.
true if a >= b according to procedure::cmp() , false otherwise.