Contents

class xform_query_bounds_result

The return type of step_xform.query_bounds()

Example

The xform_query_bounds_result and step_xform 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_xform_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.
#

# This plug-in is provided to illustrate the 'step_xform' and
# 'xform_query_bounds' API classes. It does not issue any warnings;
# its only role is to write the results of various step_xform
# operations into the analysis log.

import cs

class step_xform_illustrator(cs.step_state):

    def __init__(self):
        super(step_xform_illustrator,self).__init__()

    def copy(self):
        return step_xform_illustrator()

    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('---')
                print('Call site at', fl)
                print('Basic step_xform representations')
                print(' - hash(tosrc_xform) = ', hash(tosrc_xform))
                print(' - repr(tosrc_xform) = ', repr(tosrc_xform))
                print(' - str(tosrc_xform) = ', str(tosrc_xform))

                print('Performing a trivial xform_query equivalent to 5==5')
                xfq_result = edge_xform.query(cs.xform_expr(5),
                                              cs.xform_operator.EQUAL,
                                              cs.xform_expr(5))
                print(' - step_xform.query() result:', xfq_result)

                print('Getting bounds on a trivial xform_expr equivalent to 5')
                xfq_bounds_result = edge_xform.query_bounds(cs.xform_expr(5))
                print(' - repr(xfq_bounds_result) = ', repr(xfq_bounds_result))
                print(' - str(xfq_bounds_result) = ', str(xfq_bounds_result))
                print(' - xfq_bounds_result.feasible() = ', xfq_bounds_result.feasible())
                print(' - xfq_bounds_result.get_lower() = ', xfq_bounds_result.get_lower())
                print(' - xfq_bounds_result.get_lower_suspect() = ', xfq_bounds_result.get_lower_suspect())
                print(' - xfq_bounds_result.get_upper() = ', xfq_bounds_result.get_upper())
                print(' - xfq_bounds_result.get_upper_suspect() = ', xfq_bounds_result.get_upper_suspect())
                print(' - xfq_bounds_result.has_lower() = ', xfq_bounds_result.has_lower())
                print(' - xfq_bounds_result.has_upper() = ', xfq_bounds_result.has_upper())
                print(' - xfq_bounds_result.modified() = ', xfq_bounds_result.modified())

        except cs.result as r:
            pass

# We defined step_xform_illustrator.__init__ to suitably initialize the state, so
# just pass a new instance to cs.analysis.add_step_bottom_up_visitor()

cs.analysis.add_step_bottom_up_visitor(step_xform_illustrator())

xform_query_bounds_result Members

Constructors none
Methods __repr__(), __str__(), feasible(), get_lower(), get_lower_suspect(), get_upper(), get_upper_suspect(), has_lower(), has_upper(), modified()

xform_query_bounds_result Details

class cs.xform_query_bounds_result

The return type of step_xform.query_bounds()

__repr__()

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

Return type:str
Returns:The string representation. 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = project.current()
>>> v1 = v0.procedures_vector()
>>> v2 = v1[2].local_symbols()
>>> v3 = v2.__next__()
>>> v4 = xform_expr(v3)
>>> v5 = <cs.step_xform ...>.query_bounds(v4)
>>> repr(v5)
'<cs.xform_query_bounds_result (-inf, +inf)>'
__str__()

Get a simple string representation of a xform_query_bounds_result object.

Return type:str
Returns:The string representation. 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = project.current()
>>> v1 = v0.procedures_vector()
>>> v2 = v1[2].local_symbols()
>>> v3 = v2.__next__()
>>> v4 = xform_expr(v3)
>>> v5 = <cs.step_xform ...>.query_bounds(v4)
>>> str(v5)
'(-inf, +inf)'
feasible()

Check: was the query executed on a feasible step_xform object?

Return type:bool
Returns:True if the query was executed on a feasible step_xform object, False otherwise. 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = xform_expr(17, 12)
>>> v1 = <cs.step_xform ...>.query_bounds(v0)
>>> v1.feasible()
True
get_lower()

Get the lower bound determined by the query.

Return type:int
Returns:The lower bound determined by the query.
Raises:result.NO_LOWER_BOUND 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = xform_expr(63)
>>> v1 = <cs.step_xform ...>.query_bounds(v0)
>>> v1.get_lower()
63
get_lower_suspect()

Check: is the lower bound suspected?

Return type:bool
Returns:True if the query suspected the lower bound, False otherwise. 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = xform_expr(128)
>>> v1 = <cs.step_xform ...>.query_bounds(v0)
>>> v1.get_lower_suspect()
False
get_upper()

Get the upper bound determined by the query.

Return type:int
Returns:The upper bound determined by the query.
Raises:result.NO_UPPER_BOUND 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = xform_expr(17, 12)
>>> v1 = <cs.step_xform ...>.query_bounds(v0)
>>> v1.get_upper()
1
get_upper_suspect()

Check: is the upper bound suspected?

Return type:bool
Returns:True if the query suspected the upper bound, False otherwise. 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = project.current()
>>> v1 = v0.procedures_vector()
>>> v2 = v1[2].local_symbols()
>>> v3 = v2.__next__()
>>> v4 = xform_expr(v3)
>>> v5 = <cs.step_xform ...>.query_bounds(v4)
>>> v5.get_upper_suspect()
False
has_lower()

Check: did the query determine a lower bound?

Return type:bool
Returns:True if the query determined a lower bound, False otherwise. 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = xform_expr(128)
>>> v1 = <cs.step_xform ...>.query_bounds(v0)
>>> v1.has_lower()
True
has_upper()

Check: did the query determine an upper bound?

Return type:bool
Returns:True if the query determined an upper bound, False otherwise. 
---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = xform_expr(17, 12)
>>> v1 = <cs.step_xform ...>.query_bounds(v0)
>>> v1.has_upper()
True
modified()

Check: was step_xform.query_bounds() executed on a step_xform object that represented a modification to the symbol of interest?

Return type:bool
Returns:True if self was returned from a step_xform.query_bounds() invocation S.query_bounds(e) where step_xform object S describes a transformation that modifies the symbol referenced by xform_expr e, False otherwise.

The returned value is only meaningful if step_xform.query_bounds() was executed with an xform_expr argument e whose xform_expr_mode is one of { xform_expr_mode.POST, xform_expr_mode.POST_DEREFS_PRE, xform_expr_mode.POST_DEREFS_PRE_STRICT, xform_expr_mode.POST_STRICT }. In particular, it is not meaningful if e is constant-valued, since all constant-valued xform_expr objects are created with xform_expr_mode.PRE.

The example plug-in calls step_xform.query_bounds()with a constant-valued xform_expr argument. Constant-valued xform_expr objects always have xform_expr_mode.PRE, so invoking step_state.modified()on the returned value does not produce a meaningful result.

---
Call site at (<cs.sfileinst C:\alex\test\apitest.cpp>, 6)
Basic step_xform representations
 - hash(tosrc_xform) =  1922401584
 - repr(tosrc_xform) =  <cs.step_xform ...>
 - str(tosrc_xform) =  <cs.step_xform ...>
Performing a trivial xform_query equivalent to 5==5
 - step_xform.query() result: redundant
Getting bounds on a trivial xform_expr equivalent to 5
 - repr(xfq_bounds_result) =  <cs.xform_query_bounds_result [5, 5]>
 - str(xfq_bounds_result) =  [5, 5]
 - xfq_bounds_result.feasible() =  True
 - xfq_bounds_result.get_lower() =  5
 - xfq_bounds_result.get_lower_suspect() =  False
 - xfq_bounds_result.get_upper() =  5
 - xfq_bounds_result.get_upper_suspect() =  False
 - xfq_bounds_result.has_lower() =  True
 - xfq_bounds_result.has_upper() =  True
 - xfq_bounds_result.modified() =  True

>>> v0 = xform_expr(17, 12)
>>> v1 = <cs.step_xform ...>.query_bounds(v0)
>>> v1.modified()
True