Contents

class step_path

Used by the warningclass report() and report_return_warnings() methods that report a warning with a step path, and by step visitors ( step_state ), as added with analysis.add_step_bottom_up_visitor().

The standard use case is as follows.

  1. A user decides to implement a new check that requires a step visitor. They create subclass S of step_state to implement the visitor, and a new warningclass W for the warnings issued by the check.
  2. They define step_state.transition() to perform the appropriate checks on its arguments. These arguments include a step_path object path, which may be examined as part of the checks.
  3. If these checks indicate a warning should be issued, S.transition() calls W.report( path ,…) or W.report_return_warning( path ,…) to report the warning.

Note

See the step_state documentation for an annotated example plug-in.

Example

The step_path methods are not suitable for interactive exploration in the console. The following small plug-in uses a simple step visitor to illustrate them. To see the plug-in in action:

  1. Copy the plug-in code and save as codesonar/plugins/step_path_plugin.py.
  2. Re-run the CodeSonar analysis on apitest.cpp without enabling the interactive Python console (if you run it by mistake, exit from the console so that the analysis can finish running).
  3. Open the Analysis Log page and search for string ‘Call site at’.

Examples for methods on this page correspond to the output for the call site to whoknows() in mymalloc, which will start with a line of the form Call site at (<cs.sfileinst path/to/apitest.cpp>, 6) (where path/to will depend on your working directory).

#      software is retained by CodeSecure, Inc.
#

# step_path_plugin.py
# A simple step visitor that outputs the results of invoking
# cs.step_path.__repr__(), cs.step_path.__str__(), and
# cs.step_path.to_cfg_node_vector() on every call site it reaches.

import cs
 
class callsite_step(cs.step_state):
    def __init__(self):
        super(callsite_step, self).__init__()

    def copy(self):
        return callsite_step()

    def transition(self, srcpt, edgelabel, destpt, tosrc_xform, edge_xform, tosrc_path):
        try:
            fl = srcpt.file_line()
            if srcpt.get_kind()==cs.point_kind.CALL_SITE:
                print('Call site at', fl)
                print('   __hash__:\n', hash(tosrc_path))
                print('   __repr__:\n', repr(tosrc_path))
                print('   __str__:\n', str(tosrc_path))
                print('   to_cfg_node_vector():\n', tosrc_path.to_cfg_node_vector())
        except cs.result as r:
            pass

cs.analysis.add_step_bottom_up_visitor(callsite_step())

step_path Members

Constructor __init__()
Methods __hash__(), __repr__(), __str__(), to_cfg_node_vector()

step_path Details

class cs.step_path

Used by the warningclass report() and report_return_warnings() methods that report a warning with a step path, and by step visitors ( step_state ), as added with analysis.add_step_bottom_up_visitor().

__init__(other)

Copy constructor.

Parameters:other (step_path) – 
>>> step_path(<cs.step_path  [entry] mymalloc(int) -T->
[actual-in] $param_1 = i>)
<cs.step_path  [entry] mymalloc(int) -T->
[actual-in] $param_1 = i>
__hash__()

Get a hash value for a step_path .

Return type:int 
# When step_path_plugin.py is installed, the analysis log for an
# analysis of apitest.cpp will include the following.
[...]
Call site at (<cs.sfileinst C:\cygwin\home\alex\apitest.cpp>, 6)
__hash__:
504170496
[...]
__repr__()

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

Return type:str
Returns:The string representation. 
# When step_path_plugin.py is installed, the analysis log for an
# analysis of apitest.cpp will include the following.
[...]
Call site at (<cs.sfileinst C:\cygwin\home\alex\apitest.cpp>, 6)
[...]
__repr__:
<cs.step_path  [entry] mymalloc(int) -T->
[actual-in] $param_1 = i -T->
[call-site] whoknows(int) -l0->
[actual-out] _Z8whoknowsi$result1>
[...]
__str__()

Get a simple string representation of a step_path object.

Return type:str
Returns:The string representation. 
# When step_path_plugin.py is installed, the analysis log for an
# analysis of apitest.cpp will include the following.
[...]
Call site at (<cs.sfileinst C:\cygwin\home\alex\apitest.cpp>, 6)
[...]
__str__:
[entry] mymalloc(int) -T->
[actual-in] $param_1 = i -T->
[call-site] whoknows(int) -l0->
[actual-out] _Z8whoknowsi$result1
[...]
to_cfg_node_vector()

Get the list of cfg_path_node nodes corresponding to a step_path .

Return type:[cfg_path_node]
Returns:The list of cfg_path_node nodes corresponding to the step path. 
# When step_path_plugin.py is installed, the analysis log for an
# analysis of apitest.cpp will include the following.
[...]
Call site at (<cs.sfileinst C:\cygwin\home\alex\apitest.cpp>, 6)
[...]
to_cfg_node_vector():
(<cs.cfg_path_node <cs.point [entry] mymalloc(int)>, <cs.edge_label T>, , cs.cfg_path_node_flags none>, <cs.cfg_path_node <cs.point [actual-in] $param_1 = i>, <cs.edge_label T>, , cs.cfg_path_node_flags none>, <cs.cfg_path_node <cs.point [call-site] whoknows(int)>, <cs.edge_label l0>, , cs.cfg_path_node_flags none>, <cs.cfg_path_node <cs.point [actual-out] _Z8whoknowsi$result1>, <cs.edge_label >, , cs.cfg_path_node_flags none>)
[...]