`cs` Class Reference¶

Classes in `cs` Namespace¶

Class	Description
`access_path`	An access path describes a memory location as a sequence of steps from some base `symbol` , with each step represented by a `access_path` object.
`analysis`	Manages the warning classes ( `warningclass` ) and visitors (see Visitor Decorators) for the analysis.
`analysis_mode`	Enumeration class describing the mode of a CodeSonar analysis process.
`ast`	An Abstract Syntax Tree (AST).
`ast_class`	Enumeration class for AST classes.
`ast_family`	Enumeration class for AST family.
`ast_field`	A field (child or attribute) of an Abstract Syntax Tree (class `ast` ).
`ast_field_not_found_error`	Describe an error where an `ast_field` lookup failed.
`ast_field_type`	Enumeration class for AST field (child or attribute; `ast_field` ) types.
`ast_iterator`	Iterator over the Abstract Syntax Trees (ASTs, `ast` ) in the tree rooted at a particular `ast` .
`ast_ordinal`	Enumeration class for AST ordinals: used to designate a field ( `ast_field` ) of an `ast` .
`ast_pattern`	An AST Pattern.
`ast_pattern_compilation_error`	Describe an error in compiling an `ast_pattern` .
`ast_traverse_directives`	Flag class: specifies behavior during traversal with an `ast_iterator` .
`ast_traverse_flags`	Flag class: specifies what kind of traversal an `ast_iterator` will carry out.
`cfg_edge_set`	A set of ( `point` , `edge_label` ).
`cfg_edge_set_iterator`	Iterator over the ( `point` , `edge_label` ) elements of a `cfg_edge_set` .
`cfg_path_node`	A node on a CFG path.
`cfg_path_node_flags`	Flag class: characterizes a `cfg_path_node` .
`compunit`	A compilation unit.
`compunit_global_iterator`	Iterator over the global symbols ( `symbol` ) in a compilation unit ( `compunit` ).
`compunit_metricclass`	A `compunit` granularity metric class.
`compunit_metricclass_iterator`	Iterator over the compunit-granularity metric classes ( `compunit_metricclass` ) managed by a `compunit_metricclass_manager` .
`compunit_metricclass_manager`	Manages the `compunit` granularity metric classes ( `compunit_metricclass` ) associated with an analysis.
`compunit_procedure_iterator`	Iterator over the procedures ( `procedure` ) in a compilation unit ( `compunit` ).
`csurf_info`	Information about the CodeSurfer installation.
`directory`	A directory.
`directory_children_iterator`	Iterator over the immediate subdirectories ( `directory` ) of a directory ( `directory` ).
`directory_files_iterator`	Iterator over the files ( `sfile` ) immediately contained in a directory ( `directory` ).
`edge_label`	Denotes the conditions under which control can flow along an edge: a component of a ( `point` , `edge_label` ).
`func_attrs`	Flag class: describes the attributes of a `symbol` of kind `symbol_kind.FUNCTION`.
`int_pair_set`	Used to store pairs of integers, each of which represents a range of locations in a source file.
`int_pair_set_iterator`	Iterator over the (int, int) elements of a `int_pair_set` .
`int_pairs_to_points_map`	A map `int_pair_set` -> `point_set` , where each entry represents the mapping from a source position to the set of points at that source position.
`language`	Enumeration class: identifies the source language the compilation unit is in.
`line_counts`	A collection of line count statistics.
`locations_node`	Used by `warningclass` `report()` and `report_return_warnings()` methods that report a warning with a list of code locations.
`locations_node_flags`	Flag class: describes properties of a `locations_node` .
`metricclass_flags`	Flag class: characterizes a metric class ( `procedure_metricclass` , `sfile_metricclass` , `compunit_metricclass` , `project_metricclass` ).
`multiprocess_mode`	Enumeration class describing the multiprocess mode of a CodeSonar analysis process.
`object_pager`	Management for IO buffering.
`point`	A single program point.
`point_adjusted_callees_iterator`	An iterator over the callee procedures ( `procedure` ) from a specific point, taking into account any translations incurred by `csonar_replace_*()` calls and the FUNCTION_MAP configuration file variable.
`point_adjusted_callees_no_reroute_iterator`	An iterator over the callee procedures ( `procedure` ) from a specific point, ignoring any translations incurred by `csonar_replace_*()` calls and the FUNCTION_MAP configuration file variable.
`point_kind`	Enumeration class: program point ( `point` ) kind.
`point_set`	A set of points ( `point` ).
`point_set_iterator`	Iterator over the `point` elements of a `point_set` .
`point_syntax_element`	Enumeration class: the element of source code statement from which a `point` was generated.
`point_syntax_kind`	Enumeration class: the syntax kind associated with a program point ( `point` ), indicating the kind of source code statement from which the point was generated.
`procedure`	A single procedure/function/method.
`procedure_adjusted_callers_iterator`	An iterator over the direct and indirect call sites ( `point` of kind `point_kind.CALL_SITE` or `point_kind.INDIRECT_CALL`) whose target is a particular procedure, taking into account any translations incurred by `csonar_replace_*()` calls and the FUNCTION_MAP configuration file variable.
`procedure_call_sites_flags`	Flag class: specifies call site types.
`procedure_call_sites_iterator`	Iterator over the call sites ( `point` of kind `point_kind.CALL_SITE`) in a procedure.
`procedure_callers_iterator`	Iterator over the call sites ( `point` of kind `point_kind.CALL_SITE`) whose target is a particular procedure.
`procedure_kind`	Enumeration class: the “kind” of a `procedure` .
`procedure_locals_iterator`	Iterator over the local variables ( `symbol` ) that are declared in a procedure.
`procedure_metricclass`	A `procedure` granularity metric class.
`procedure_metricclass_iterator`	Iterator over the procedure-granularity metric classes ( `procedure_metricclass` ) managed by a `procedure_metricclass_manager` .
`procedure_metricclass_manager`	Manages the `procedure` granularity metric classes ( `procedure_metricclass` ) associated with an analysis.
`project`	A CodeSonar or CodeSurfer project.
`project_compunits_iterator`	Iterator over all the compilation units ( `compunit` ) in a `project` .
`project_metricclass`	A `project` granularity metric class.
`project_metricclass_iterator`	Iterator over the project-granularity metric classes ( `project_metricclass` ) managed by a `project_metricclass_manager` .
`project_metricclass_manager`	Manages the `project` granularity metric classes ( `project_metricclass` ) associated with an analysis.
`project_procedures_iterator`	Iterator over all the procedures ( `procedure` ) in a `project` .
`project_root_directories_iterator`	Iterator over the set of root directories( `directory` ) in a project (deduced by inspecting all source file paths in the project).
`project_sfiles_iterator`	Iterator over all the source files ( `sfile` ) in a `project` .
`report_flags`	Flag class used by a number of `warningclass` `report`() and `report_return_warning()` methods.
`result`	The result of an API operation.
`set_kind`	Enumeration class: the kind of a set.
`sfile`	A source file.
`sfile_instance_iterator`	Iterator over the instances ( `sfileinst` ) of a source file ( `sfile` ).
`sfile_metricclass`	A `sfile` granularity metric class.
`sfile_metricclass_iterator`	Iterator over the sfile-granularity metric classes ( `sfile_metricclass` ) managed by a `sfile_metricclass_manager` .
`sfile_metricclass_manager`	Manages the `sfile` granularity metric classes ( `sfile_metricclass` ) associated with an analysis.
`sfileinst`	A source file instance.
`sfileinst_children_iterator`	Iterator over the include-tree children ( `sfileinst` ) of a source file instance.
`sfileinst_color_map_iterator`	Iterator over the spans (((int, int), (int,int))) of a specific `syntax_kind` within a source file instance ( `sfileinst` ).
`sfileinst_range`	A range of (contiguous) locations in a single source file instance.
`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()`.
`step_state`	Abstract base class for step visitors, as added with `analysis.add_step_bottom_up_visitor()`: subclass to define your own step visitors.
`step_xform`	A program state transform along a path in the CFG.
`symbol`	A function or variable.
`symbol_kind`	Enumeration class: the kind of a `symbol` .
`symbol_set`	A set of symbols ( `symbol` ).
`symbol_set_iterator`	Iterator over the `symbol` elements of a `symbol_set` .
`symbol_universe_iterator`	Iterator over all the symbols ( `symbol` ) in a `project` .
`syntax_kind`	Enumeration class: the kind of a span within a source file instance ( `sfileinst` ).
`sysinfo`	Information about the local system.
`var_attrs`	Flag class: describes the attributes of a `symbol` of any kind EXCEPT `symbol_kind.FUNCTION`.
`warning`	A warning instance.
`warning_retraction_info`	Describes the cases in which a warning instance should be retracted.
`warning_significance`	Enumeration class describing the significance setting for a warning class.
`warningclass`	A warning class.
`warningclass_flags`	Flag class: describes properties of a `warningclass` .
`xform_expr`	Specifies parts of a query expression for `step_xform.query()` or `step_xform.query_bounds()`.
`xform_expr_mode`	Enumeration class: the evaluation mode for an `xform_expr` .
`xform_operator`	Enumeration class: an operator that can be used in a transform query with `step_xform.query()`.
`xform_query_bounds_result`	The return type of `step_xform.query_bounds()`
`xform_query_result`	Enumeration class: the possible outcomes of a transform query with `step_xform.query()`.
`xr_def_iter_flags`	Flag class: properties for an `xr_definition_iterator` .
`xr_definition_iterator`	Iterator over the definitions ( `xr_tuple` ) of a token.
`xr_file_query`	A collection of filters used to restrict a `xr_query` .
`xr_homonym_iterator`	Iterator over the homonyms ( `xr_tuple` ) of a token.
`xr_intra_definition_iterator`	Iterator over the definitions ( `xr_tuple` ) of a token.
`xr_kind`	Enumeration class: describes the kind of a (non-keyword) token.
`xr_kind_role`	Enumeration class: describes a valid token kind-role (kind-usage) pair.
`xr_occ_iter_flags`	Flag class: properties for `xr_occurrence_iterator` and `xr_homonym_iterator` iterators.
`xr_occurrence_iterator`	Iterator over the occurrences ( `xr_tuple` ) of a token.
`xr_query`	Fully specifies a cross-referencing query over the tokens in an analyzed project.
`xr_query_flags`	Flag class: additional properties for an `xr_query` .
`xr_query_iterator`	Iterator over the results ( `xr_tuple` ) of an `xr_query` .
`xr_role`	Enumeration class: describes the role that a token is playing at a particular occurrence of that token.
`xr_tuple`	Describes an occurrence of a token in a particular kind-role and the definition corresponding to that occurrence.
`xtype_render_style`	Flag class for selecting type rendering styles.

cs.string_hash(str)¶

Hash a string.

Parameters:	s (`str`) – The string to hash.
Return type:	int
Returns:	A hash of `s`, as an `int`.

>>> string_hash('bar')
5645464789443595960

cs.xmldecode(s)¶

XML-decode a string.

Parameters:	s (`str`) – The string to decode.
Return type:	str
Returns:	The XML-decoded form of `s`.

cs.xmlencode(s[, use_private_use_area=True])¶

XML-encode a string.

Parameters:	s (`str`) – The string to encode. use_private_use_area (bool) – Specifies how bytes 128 and higher should be handled. If `True`, they are escaped as code point `0xe000 + byte` (appearing in the XML as. `&#xe080..&#xe0ff`). If `False`, they appear as-is in the XML. XML parsers will reject this XML if they do not use a character encoding matching the data.
Return type:	str
Returns:	The XML-encoded form of `s`.

The CodeSonar hub expects XML to have been encoded with use_private_use_area=True.

cs.xr_namehash(str)¶

Hash a token name.

Parameters:	s (`str`) – The token name to hash.
Return type:	int
Returns:	A hash of `s`, as an `int`.

>>> xr_namehash('foo')
12120978783516715158

Example Program¶

All examples in the API Reference were executed against the example program shown below.

apitest.h:

extern "C" void *undef_func(unsigned);

apitest.cpp:

// apitest.cpp
#include "apitest.h"
int *mymalloc(int i)
{
    int *whoknows(int);
    return (int*)whoknows(i);
}

int bar(int i, void *j, int k) throw(int)
{
    if(i == 0)
        throw i;
    i = i++;
    int x = bar((int)1.5, 0, 2);
    int *p = mymalloc(10);
    switch( i )
    {
    case 0:
        i = __LINE__; break;
    case 1:
        i = __LINE__; break;
    case 2:
        i = __LINE__; break;
    default:
        i = __LINE__; break;
    }
    *p = x;
    return i + 1;
}

extern "C"
const char * foo(void)
{
    struct { int i; int j; } s;
    int a = bar(5, (void*)foo, 100+5);
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* seed this test with warnings that will have a /fetch_more_ellipsis/ */
    /* so that the spider_all_types can better find it during the test */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    /* BZ:61291 */
    int b = bar(5, (void*)foo, 100+5);
    int *p = mymalloc(20);
    *p = b;
    try{
        int j = bar(5, (void*)foo, 100+5);
        s.j = j;
    }catch(...)
    {
        return "foo";
    }
    return "bar";
}

Experiment with the Example Program¶

You can use the plug-in Python console to try out the code examples in the API documentation, as well as to carry out any other investigations you are interested in.

Note

Some of the examples are automatically generated and rely on element orderings within the program internal representation (IR) constructed by the CodeSonar analysis. These orderings depend to some degree on your local development environment, so examples that rely on them may have different behavior to that shown if you copy and paste to try them yourself.

If you encounter this issue with an API method that you want to experiment with in the Python interpreter, a useful technique is to iterate over all elements of the appropriate type in the program and apply the method to all of them, or to all of them that meet the conditions for applicability.

Note also that some API methods are not suitable for executing in the Python console because they have no meaning once the analysis phase has finished. Their code examples are labeled accordingly.

Copy the code samples above into files apitest.h and apitest.cpp in a suitable working directory.
Build and analyze a CodeSonar project based on apitest.cpp, specifying -preset python_debug_console to enable the Python console plug-in. Use the command line below, replacing ‘host:port’ with your hub location.
```
codesonar analyze apitest -preset python_debug_console -foreground host:port -clean gcc -m32 -c apitest.cpp
```
Running in foreground mode ensures that the analysis process is connected to the console from which you run the command.
Once the Python console starts, import the cs module.
```
>>>  from cs import *
```

You can now experiment with the Python API.

`cs` Class Reference¶

Classes in `cs` Namespace¶

Namespace-Level Functions for `cs`¶

Example Program¶

Experiment with the Example Program¶

This Page

Table of Contents

Previous topic

Next topic

cs Class Reference¶

Classes in cs Namespace¶

Namespace-Level Functions for cs¶

Example Program¶

Experiment with the Example Program¶

`cs` Class Reference¶

Classes in `cs` Namespace¶

Namespace-Level Functions for `cs`¶