JavaScript is not currently enabled, but is required for full CodeSonar manual search and browse functionality.

If you are viewing this file in your hub's Web GUI, enable JavaScript in your browser: you will also need it for GUI functionality.

If you opened this file directly from disk, your browser may be directly suppressing JavaScript functionality: certain browsers perform this suppression on local files (but not files delivered by web servers) for security reasons.

CodeSonar® 9.2p0 CONFIDENTIAL CodeSecure Inc
C and C++
Binaries

csonar_plugin.h : Visitors, Warnings, Metrics

C functions and types for visitors, warnings, and metrics.

CodeSonar plug-in modules can define checks to do virtually anything. CodeSonar plug-ins interface with CodeSonar by registering various visitors with the system.

Links

Defines

#define CSONAR_PLUGIN_H
#define CSONAR_EXPORT CS_DLLIMPORT
#define CSONAR_EXPORT_VARIABLE_DECL extern CS_DLLIMPORT
#define CSONAR_PLUGIN_EXPORT CS_DLLEXPORT
#define CSONAR_EXPORT_VARIABLE_DEF ( INVALID, INVALID )
#define CS_WARNING_ID_STATIC_NULL { CSUINT64_ZERO, 0, 0 } Use to initialize a cs_warning_id variable.
#define CS_WARNING_RETRACTION_INFO_STATIC_NULL { 0, 0, 0, NULL, NULL, NULL } Use to initialize a cs_warning_retraction_info_t variable.
#define cs_baserank_from_manifest -10000.0

Types

typedef cs_warningclass_t
Definition typedef struct _WARNINGCLASS * cs_warningclass_t
Notes A warning class.
typedef cs_report_flags
Definition typedef csuint32 cs_report_flags
Notes For use with csonar_report_warning(), csonar_report_location_warning(), and csonar_report_location_warning_in_pdg().

Values for cs_report_flags are defined in an anonymous enum, which this documentation will refer to as anonymous_cs_report_flags_enum.

typedef cs_cfg_path_node_flags
Definition typedef csuint32 cs_cfg_path_node_flags
Notes For use with cs_cfg_path_node_t, which in turn is used with csonar_report_path_warning().

Values for cs_cfg_path_node_flags are defined in an anonymous enum, which this documentation will refer to as anonymous_cs_cfg_path_node_flags_enum.

typedef cs_locations_node_flags
Definition typedef csuint32 cs_locations_node_flags
Notes For use with cs_locations_node_t, which in turn is used with csonar_report_locations_warning() and csonar_report_locations_warning_in_pdg().

Values for cs_locations_node_flags are defined in an anonymous enum, which this documentation will refer to as anonymous_cs_locations_node_flags_enum.

typedef cs_metric_class_iterator
Definition typedef cs_metric_iterator cs_metric_class_iterator
Notes An iterator over the metric classes at a specified granularity.

Used by:

API clients should never directly access the fields of this type. This is only exported so that clients may stack allocate these things. Future versions of the API reserve the right to change the definition of this iterator type.

typedef cs_metricclass_t
Definition typedef struct _cs_metricclass_t * cs_metricclass_t
Notes A metric class.
typedef cs_metricclass_flags
Definition typedef csuint32 cs_metricclass_flags
Notes Flags for declaring a new metric class (cs_metricclass_t).

Used by

Values for cs_metricclass_flags are defined in an anonymous enum, which this documentation will refer to as anonymous_cs_metricclass_flags_enum.

typedef cs_cfg_path_node_t
Definition typedef struct cs_cfg_path_node_t cs_cfg_path_node_t
Notes A node on a CFG path.
typedef cs_locations_node_t
Definition typedef struct cs_locations_node_t cs_locations_node_t
Notes A node on a list of warning locations.
typedef cs_warning_id
Definition typedef struct cs_warning_id cs_warning_id
Notes A unique identifier for a warning instance.
typedef cs_warning_retraction_info_t
Definition typedef struct cs_warning_retraction_info_t cs_warning_retraction_info_t
Notes Describes the cases in which a warning instance should be retracted.
typedef csonar_pdg_list
Definition typedef struct __csonar_pdg_list csonar_pdg_list
Notes Fields of this type are private and may change in future versions.
typedef csonar_pdg_callers_iter
Definition typedef struct __csonar_pdg_callers_iter csonar_pdg_callers_iter
Notes Fields of this type are private and may change in future versions.
typedef cs_langs_t
Definition typedef const cs_language * cs_langs_t
Notes A list of languages.
  • The last item in the list should always be csl_null.
  • Variables of this type should usually be declared static.

Example 1: Matches C and C++. 

static const cs_language c_and_cpp[] = { csl_edgcp_c, csl_edgcp_cpp, csl_null };

Example 2: Matches all languages. 

static const cs_language c_and_cpp[] = { csl_wildcard, csl_null };
typedef cs_visitor_ctx_t
Definition typedef void * cs_visitor_ctx_t
Notes A user-supplied context, specified when adding visitors.

The context is passed along to the visitor when the visitor is invoked. CodeSonar will never dereference or attempt to interpret values of this type.

typedef cs_thunk_t
Definition typedef void(* cs_thunk_t)(cs_visitor_ctx_t)
Notes A function pointer for use in program visitors.

Program visitors are added by:
typedef cs_uid_visitor_t
Definition typedef void(* cs_uid_visitor_t)(cs_uid, cs_visitor_ctx_t)
Notes A function pointer for use in compilation unit visitors.

Compilation unit visitors are added by:
typedef cs_pdg_visitor_t
Definition typedef void(* cs_pdg_visitor_t)(cs_pdg, cs_visitor_ctx_t)
Notes A function pointer for use in procedure (cs_pdg) visitors.

Procedure visitors are added by
typedef cs_pdg_vertex_visitor_t
Definition typedef void(* cs_pdg_vertex_visitor_t)(cs_pdg_vertex, cs_visitor_ctx_t)
Notes A function pointer for use in point (cs_pdg_vertex) visitors.

Point visitors are added by
typedef cs_abs_loc_visitor_t
Definition typedef void(* cs_abs_loc_visitor_t)(cs_abs_loc, cs_visitor_ctx_t)
Notes A function pointer for use in symbol (cs_abs_loc) visitors.

Symbol visitors are added by
typedef cs_sfi_visitor_t
Definition typedef void(* cs_sfi_visitor_t)(cs_sfid, cs_visitor_ctx_t)
Notes A function pointer for use in source file and source file instance visitors.

Source file visitors are added by

Source file instance visitors are added by

The distinction between a source file visitor and a source file instance visitor is that a source file visitor is only applied to one instance per file (when the file language is suitable): the first instance encountered in the relevant traversal phase.

typedef cs_listing_transformer_t
Definition typedef cs_string(* cs_listing_transformer_t)(cs_sfid, cs_line, cs_const_string, cs_visitor_ctx_t)
typedef cs_info_window_items_t
Definition typedef struct _CS_INFO_WINDOW_ITEMS_T * cs_info_window_items_t
typedef cs_step_user_state_t
Definition typedef void * cs_step_user_state_t
Notes A user-defined state type.

CodeSonar will never attempt to dereference this type; it is treated opaquely.

typedef cs_step_csonar_xform_t
Definition typedef const struct _WEIGHT ** cs_step_csonar_xform_t
Notes A program state transform along a path in the CFG.
typedef cs_step_path_t
Definition typedef struct _RPATH_NODE * cs_step_path_t
Notes A path through the CFG.
typedef cs_step_visitor_dispatch_t
Definition typedef struct cs_step_visitor_dispatch_t cs_step_visitor_dispatch_t
Notes Encapsulates all information about a step visitor.
typedef cs_const_step_visitor_dispatch_t
Definition typedef const cs_step_visitor_dispatch_t cs_const_step_visitor_dispatch_t
Notes The const form of cs_step_visitor_dispatch_t.
typedef csonar_analysis_mode
Definition typedef enum csonar_analysis_mode csonar_analysis_mode
Notes The possible modes of a CodeSonar analysis process: the possible return values for csonar_get_analysis_mode().
typedef csonar_multiprocess_mode
Definition typedef enum csonar_multiprocess_mode csonar_multiprocess_mode
Notes The possible multiprocess modes of a CodeSonar analysis process: the possible return values for csonar_get_multiprocess_mode().

See Parallelism in CodeSonar: Analysis for more information.

typedef csonar_warningclass_flags
Definition typedef csuint32 csonar_warningclass_flags
Notes Flags for creating a new warning class.

Values for csonar_warningclass_flags are defined in an anonymous enum, which this documentation will refer to as anonymous_csonar_warningclass_flags_enum.

typedef csonar_pdg_callees_iter
Definition typedef struct csonar_pdg_callees_iter csonar_pdg_callees_iter
Notes An iterator over the callee procedures (cs_pdg) from a specific point (cs_pdg_vertex), taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.

Used by

A direct call site (that is, a cs_pdg_vertex of kind cs_vertex_kind_call_site) will always have exactly one callee. As an alternative to setting up an iterator, you can use csonar_pdg_vertex_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 (a cs_pdg_vertex of kind cs_vertex_kind_indirect_call) can have zero or more callees.

typedef csonar_pdg_callees_no_reroute_iter
Definition typedef struct csonar_pdg_callees_no_reroute_iter csonar_pdg_callees_no_reroute_iter
Notes An iterator over the callee procedures (cs_pdg) from a specific point (cs_pdg_vertex), ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.

Used by

A direct call site (that is, a cs_pdg_vertex of kind cs_vertex_kind_call_site) will always have exactly one callee. As an alternative to setting up an iterator, you can use csonar_pdg_vertex_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 (a cs_pdg_vertex of kind cs_vertex_kind_indirect_call) can have zero or more callees.

typedef cs_access_path_operator
Definition typedef enum cs_access_path_operator cs_access_path_operator
Notes Operators that can occur on an access path (cs_access_path).
typedef cs_access_path
Definition typedef struct cs_access_path_struct cs_access_path
Notes Stores information about a step on an access path; generally occurs in a list.

For example, suppose we have the following declarations: 

char *p;
char **pp;
char A[10];
float f;
struct mys {
   int i;
   double d;
   };
struct mys s;
struct mys *sp;
Then to describe...
  • f, use 
    cs_abs_loc base = the_cs_abs_loc_for_f;
cs_access_path ap[] = { { CSAPOP_TERMINATOR } };
  • p[4], use 
    cs_abs_loc base = the_cs_abs_loc_for_p;
cs_access_path ap[] = {
                        { CSAPOP_OFFSET_IN_BITS, {32} },
                        { CSAPOP_STAR },
                        { CSAPOP_TERMINATOR }
                      };
    (32 is 4*8, and a char is 8 bits)
  • &p, use 
    cs_abs_loc base = the_cs_abs_loc_for_p;
cs_access_path ap[] = {
                        { CSAPOP_ADDR },
                        { CSAPOP_TERMINATOR }
                      };
  • (*pp)[4], use 
    cs_abs_loc base = the_cs_abs_loc_for_pp;
cs_access_path ap[] = {
                        { CSAPOP_OFFSET_IN_BITS, {32} },
                        { CSAPOP_STAR },
                        { CSAPOP_STAR },
                        { CSAPOP_TERMINATOR }
                      };
    (32 is 4*8, and a char is 8 bits)
  • *(pp[4]), use 
    cs_abs_loc base = the_cs_abs_loc_for_pp;
cs_access_path ap[] = {
                        { CSAPOP_STAR },
                        { CSAPOP_OFFSET_IN_BITS, {128} },
                        { CSAPOP_STAR },
                        { CSAPOP_TERMINATOR }
                      };
    (assuming 32-bit pointers - 4*32 = 128 )
  • A[5], use 
    cs_abs_loc base = the_cs_abs_loc_for_A;
cs_access_path ap[] = {
                        { CSAPOP_OFFSET_IN_BITS, {40} },
                        { CSAPOP_TERMINATOR }
                      };
    (40 is 5*8, and a char is 8 bits)
  • s.d, use 
    cs_abs_loc base = the_cs_abs_loc_for_s;
cs_access_path ap[] = {
                        { CSAPOP_OFFSET_IN_BITS, {32} },
                        { CSAPOP_TERMINATOR }
                      };
    (the d field is offset 32 bits from the start of s, assuming 32-bit integers)
  • ps->d, use 
    cs_abs_loc base = the_cs_abs_loc_for_ps;
cs_access_path ap[] = {
                        { CSAPOP_OFFSET_IN_BITS, {32} },
                        { CSAPOP_STAR }
                        { CSAPOP_TERMINATOR }
                      };
    (the d field is offset 32 bits from the start of *ps, assuming 32-bit integers)

Note that CSAPOP_ADDR can only ever occur in a two element list: {{CSAPOP_ADDR}, {CSAPOP_TERMINATOR}}. No other access paths containing the address operator correspond to legal expressions.

typedef cs_const_access_path
Definition typedef const cs_access_path cs_const_access_path
Notes The const form of cs_access_path.
typedef cs_xform_expr
Definition typedef struct cs_xform_expr cs_xform_expr
Notes Used to specify parts of a query expression for csonar_xform_query().
typedef cs_rpc_handler_fn_t
Definition typedef cs_result(* cs_rpc_handler_fn_t)(cs_const_string, cs_string *, void *)
Notes A function pointer for use in remote procedure call (RPC) handling.

Used by csonar_register_rpc_handler().

enum anonymous_cs_report_flags_enum
Definition typedef enum {
csrf_none = = 0x0, Use this if you don't want any other flags.
csrf_already_xml_encoded = = 1 << csrf_already_xml_encoded_pos, Special characters such as '<' and '>' are already XML-escaped in the 'problem' string.
csrf_dont_mark_contributing = = 1 << csrf_dont_mark_contributing_pos, This location should not be additionally highlighted in the code listing.

(Note that in some cases CodeSonar will have independently determined that the location shouldn't be additionally highlighted.)

csrf_all = = (1 << csrf_pos_count) - 1
} anonymous_cs_report_flags_enum
Notes This is an anonymous enumeration containing values for cs_report_flags - the anonymous_cs_report_flags_enum label is provided only for ease of reference within this documentation.
enum anonymous_cs_cfg_path_node_flags_enum
Definition typedef enum {
cscpnf_none = = 0x0, Use this if you don't want any other flags.
cscpnf_already_xml_encoded = = csrf_already_xml_encoded, Special characters such as '<' and '>' are already XML-escaped in the 'problem' string.
cscpnf_dont_mark_contributing = = csrf_dont_mark_contributing, This location should not be additionally highlighted in the code listing.

(Note that in some cases CodeSonar will have independently determined that the location shouldn't be additionally highlighted.)

cscpnf_endbox = = 1 << cscpnf_endbox_pos, The GUI should display an end box at this location (rather than an event box):
  • Warning class name instead of event id.
  • "Show: All events | Only primary events" links.
cscpnf_primary = = 1 << cscpnf_primary_pos, The event at this location is a "primary event" and should be displayed by default in the GUI Warning Report.

Do not set this flag if you are setting cscpnf_endbox. (End boxes are always displayed.)

cscpnf_contributes = = 1 << cscpnf_contributes_pos, This vertex contributes to a warning path.

By default, code excerpts in warning reports are expanded to show contributing vertices.

cscpnf_new_path = = 1 << cscpnf_new_path_pos, If the path passed to csonar_report_path_warning() actually contains multiple paths, the first node of each path should have this flag set.

This can be used for concurrency bugs where the code involved may not be in a single path.

cscpnf_all = = (1 << cscpnf_pos_count) - 1
} anonymous_cs_cfg_path_node_flags_enum
Notes This is an anonymous enumeration containing values for cs_cfg_path_node_flags - the anonymous_cs_cfg_path_node_flags_enum label is provided only for ease of reference within this documentation.
enum anonymous_cs_locations_node_flags_enum
Definition typedef enum {
cslnf_none = = 0x0, Use this if you don't want any other flags.
cslnf_already_xml_encoded = = csrf_already_xml_encoded, Special characters such as '<' and '>' are already XML-escaped in the 'problem' string.
cslnf_dont_mark_contributing = = csrf_dont_mark_contributing, This location should not be additionally highlighted in the code listing.

This removes any additional marking CodeSonar may place on this particular event.

cslnf_endbox = = 1 << cslnf_endbox_pos, The GUI should display an end box at this location (rather than an event box):
  • Warning class name instead of event id.
  • "Show: All events | Only primary events" links.
cslnf_primary = = 1 << cslnf_primary_pos, The event at this location is a "primary event" and should be displayed by default in the GUI Warning Report.

Do not set this flag if you are setting cslnf_endbox. (End boxes are always displayed.)

cslnf_style0 = = 1 << cslnf_style0_pos, This location should be shown in the "style 0" style, which looks identical to "on_path".
cslnf_style1 = = 1 << cslnf_style1_pos, This location should be shown in the alternate "style 1" style.
cslnf_style2 = = 1 << cslnf_style2_pos, This location should be shown in the alternate "style 2" style.
cslnf_style3 = = 1 << cslnf_style3_pos, This location should be shown in the alternate "style 3" style.
cslnf_alternate_interesting = = 1 << cslnf_alternate_interesting_pos, This location should be shown in the "alternate interesting" style, which is less eye-catching than the "super interesting" style used for actual errors.

This style would typically be used for critical supporting evidence for a warning that is not believed to, itself, be incorrect.

cslnf_interpolate_style = = 1 << cslnf_interpolate_style_pos, Heuristically apply the specified display style to text between and around the actual events.
cslnf_apply_style_to_line = = 1 << cslnf_apply_style_to_line_pos, Apply the specified display style to the entirety of any line that contains that, and only that, style.
cslnf_all = = (1 << cslnf_pos_count) - 1
} anonymous_cs_locations_node_flags_enum
Notes This is an anonymous enumeration containing values for cs_locations_node_flags - the anonymous_cs_locations_node_flags_enum label is provided only for ease of reference within this documentation.
enum anonymous_cs_metricclass_flags_enum
Definition typedef enum {
csmetric_flags_none = = 0, Default - no special behavior.
csmetric_flags_auto = = 1, Automatically compute values for this metric.

If this flag is not set, values for the metric must be explicitly reported using the appropriate csonar_report_metric_* function.

csmetric_flags_post_analysis = = 2, This metric relies on data from the analysis and should not be computed until after the analysis has completed.

Its value will therefore not be available until after the analysis has completed.

Post-analysis metrics can be reported at any point between the start of the bottom-up traversal and the transition to daemon mode.

Analysis-phase metrics (those where csmetric_flags_post_analysis is not set) can be reported at any point during the serial depth-first traversal, or by a bottom-up program visitor.

csmetric_flags_all = = 0x3
} anonymous_cs_metricclass_flags_enum
Notes This is an anonymous enumeration containing values for cs_metricclass_flags - the anonymous_cs_metricclass_flags_enum label is provided only for ease of reference within this documentation.

csmetric_flags_auto and csmetric_flags_post_analysis interact as follows.

  • Both csmetric_flags_auto and csmetric_flags_post_analysis: CodeSonar will automatically compute values for the metric after the main analysis phase has completed.
  • csmetric_flags_post_analysis only: a csonar_report_metric_* function must be used to report metric values, but can only be invoked from post-analysis visitors.
  • csmetric_flags_auto only: CodeSonar will automatically compute values for the metric during the main analysis phase.
  • Neither: a csonar_report_metric_* function must be used to report metric values, but can only be invoked from analysis-phase visitors.

The CS_ERROR_INVALID_PHASE_FOR_OPERATION documentation has lists of the csonar_add_*_visitor() functions associated with the different phases.

enum csonar_analysis_mode
Definition typedef enum {
csam_initializing , The CodeSonar process always starts in this state.

If this value is returned by csonar_get_analysis_mode(), it means that the function call occurred too early to get useful information.

csam_normal , Indicates a nonincremental analysis (INCREMENTAL_BUILD=No) or base analysis (INCREMENTAL_BUILD=Yes and no parent analysis).
csam_incremental , Indicates an incremental analysis: only new and otherwise-affected parts of the program are being analyzed; state associated with no-longer-present bits of the program may be deleted.
csam_daemon , Indicates that the CodeSonar process is not analyzing anything - it is only running to service requests from the hub (for example, requests for source code listings).
csam_count
} csonar_analysis_mode
Notes The possible modes of a CodeSonar analysis process: the possible return values for csonar_get_analysis_mode().
enum csonar_multiprocess_mode
Definition typedef enum {
csmm_initializing , Every CodeSonar process always starts in this state.

If this value is returned by csonar_get_multiprocess_mode(), it means that the function call occurred too early to get useful information.

csmm_serial , Indicates that CodeSonar is running in serial mode (and therefore there is only one analysis process - the current one).
csmm_master , Indicates that CodeSonar is running in parallel mode, and the current process is the analysis master or daemon master.
csmm_deep_parse_master = = csmm_master,
csmm_slave , Indicates that CodeSonar is running in parallel mode, and the current process is an analysis slave or daemon slave.
csmm_count
} csonar_multiprocess_mode
Notes The possible multiprocess modes of a CodeSonar analysis process: the possible return values for csonar_get_multiprocess_mode().

See Parallelism in CodeSonar: Analysis for more information.

enum anonymous_csonar_warningclass_flags_enum
Definition typedef enum {
csonar_bcf_none = = 0x0, Use this if you don't want any other flags.
csonar_bcf_warning_point_is_start_point = = 0x1, The start point of the path is most interesting (not the end point).
csonar_bcf_show_entire_procedure = = 0x2, If any part of a procedure appears on a path, show the entire procedure in the warning report.
csonar_bcf_pad_above = = 0x4, In the warning report, pad before ("above") the beginning of the warning proper with additional lines of code.
csonar_bcf_pad_below = = 0x8, In the warning report, pad after ("below") the end of the warning proper with additional lines of code.
csonar_bcf_padding = = csonar_bcf_pad_above | csonar_bcf_pad_below, In the warning report, pad before and after the path with additional lines of code.
csonar_bcf_force_path = = 0x10, Warnings of this class will always be treated as "pathy", even if they are reported using a function that would otherwise indicate a pathless warning.

This affects various presentation heuristics for the displayed warning. The main application of this flag is for importing warnings from other tools where a list of locations is known to actually represent a path.

csonar_bcf_all = = 0x1f
} anonymous_csonar_warningclass_flags_enum
Notes This is an anonymous enumeration containing values for csonar_warningclass_flags - the anonymous_csonar_warningclass_flags_enum label is provided only for ease of reference within this documentation.
enum cs_access_path_operator
Definition typedef enum {
CSAPOP_TERMINATOR , end of list marker
CSAPOP_ADDR , & operator
CSAPOP_STAR , * operator
CSAPOP_OFFSET_IN_BITS , [] operator, but always counted in bits
CSAPOP_COUNT
} cs_access_path_operator
Notes Operators that can occur on an access path (cs_access_path).
enum cs_xform_query_result
Definition typedef enum {
csxqr_impossible , The query evaluates to FALSE.

There are two possible cases:

  • Case 1: the query evaluates to FALSE because of preconditions that arise from:
  • Case 2: the query evaluates to FALSE for any other reason.

We use the term "suspect" to describe case 1.

If some query Q has outcome csxqr_impossible and you need to distinguish between the two cases, proceed as follows.

  1. Create a new query R that is the inverse of Q.
  2. Execute query R and look at the outcome.
csxqr_redundant , The query definitely evaluates to TRUE.
csxqr_redundant_suspect , The query evaluates to TRUE, but is implied by preconditions that arise from:
csxqr_ok , The query could evaluate to either TRUE or FALSE: there is no reason to believe definitely one or the other.
csxqr_lhs_unmodified , The query's lhs cs_xform_expr had mode csxem_post_strict or csxem_post_derefs_pre_strict, but the value of lhs was the same at the beginning and end of the transformation described by the cs_step_csonar_xform_t.
csxqr_rhs_unmodified , The query's rhs cs_xform_expr had mode csxem_post_strict or csxem_post_derefs_pre_strict, but the value of rhs was the same at the beginning and end of the transformation described by the cs_step_csonar_xform_t.
csxqr_count
} cs_xform_query_result
Notes The possible outcomes of a transform query with csonar_xform_query().
enum cs_xform_expr_mode
Definition typedef enum {
csxem_pre , The expression should be evaluated using values of variables at the beginning of the transformation.

This can be useful for reasoning about constraints imposed on the original values later in the path (implied by 'if' statements for example).

(C API only: This is the recommended setting for constant-valued cs_xform_expr (ax+b)/c with a==0.)

csxem_post , The expression should be evaluated using values of variables at the end of the transformation.

If the value of the expression is not modified in the transformation, the evaluated expression will be the same as it would have been with csxem_pre.

csxem_post_derefs_pre , The expression is evaluated as follows.

Let A be the memory location whose attribute x is used in the expression.

  • Address A is computed using the values of variables at the beginning of the transformation.
  • The expression is evaluated by taking the value of attribute x at address A at the end of the transformation.

If the value of the expression is not modified in the transformation, the evaluated expression will be the same as it would have been with csxem_pre.

csxem_post_strict , The expression should be evaluated using values of variables at the end of the transformation.

If the value of the expression is not modified in the transformation, the query fails (as distinct from csxem_post, where the query proceeds).

csxem_post_derefs_pre_strict , The expression is evaluated as specified for csxem_post_derefs_pre.

If the value of the expression is not modified in the transformation, the query fails (as distinct from csxem_post_derefs_pre, where the query proceeds).

csxem_count
} cs_xform_expr_mode
Notes Modes of evaluating a cs_xform_expr.

Note that constants a, b, and c cannot be modified by a tranformation, so the value of a cs_xform_expr representing an expression of the form (ax+b)/c can only change if x changes. There are two possible cases:

  • The memory location for which attribute x is extracted has changed. This can occur if the contents of locations along the access path (including the base cs_abs_loc) have changed.
  • The memory location is the same, but the value of attribute x is modified by the transformation.

Example:

int *p;
void f(){
    if( *p == 1 ){
        int i = 2;
        int j = 3;
        j = 4;
        *p = 5;
        *p = 6;
        p = &i;
        p = &j;
        return;
    }
}

If you were to query about the value of *p using the cs_step_csonar_xform_t covering the path from the start of the function to the return statement, here are the different values that would be observed for the different modes:
enum cs_xform_operator
Definition typedef enum {
csxfo_equal , the == operator
csxfo_not_equal , the != operator
csxfo_greater_than_or_equal , the >= operator
csxfo_less_than_or_equal , the <= operator
csxfo_count
} cs_xform_operator
Notes The operators that can be used in a transform query with csonar_xform_query().

On Separate Pages

struct cs_cfg_path_node_t
struct cs_locations_node_t
struct cs_warning_id
struct cs_warning_retraction_info_t
struct __csonar_pdg_list
struct __csonar_pdg_callers_iter
struct cs_step_visitor_dispatch_t
struct csonar_pdg_callees_iter
struct csonar_pdg_callees_no_reroute_iter
struct cs_access_path_struct
union cs_access_path_struct::variant_union
struct cs_xform_expr

Functions

csonar_analysis_mode csonar_get_analysis_mode ( )
Get the analysis mode for the CodeSonar process in which the plug-in is running.
cs_const_string csonar_analysis_mode_name ( csonar_analysis_mode m )
Get the name of a csonar_analysis_mode.
csonar_multiprocess_mode csonar_get_multiprocess_mode ( )
Get the multiprocess mode for the CodeSonar process in which the plug-in is running.
cs_const_string csonar_multiprocess_mode_name ( csonar_multiprocess_mode m )
Get the name of a csonar_multiprocess_mode.
cs_result csonar_add_setup_visitor ( cs_langs_t langs, cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th as a setup visitor for programs whose languages appear in langs.
cs_result csonar_add_program_visitor ( cs_langs_t langs, cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th as a serial depth-first program visitor for programs whose languages appear in langs.
cs_result csonar_add_uid_visitor ( cs_langs_t langs, cs_uid_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase visitor for compilation units (cs_uid) whose languages appear in langs.
cs_result csonar_add_pdg_visitor ( cs_langs_t langs, cs_pdg_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
cs_result csonar_add_abs_loc_visitor ( cs_langs_t langs, cs_abs_loc_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase visitor for symbols (cs_abs_loc) in compilation units whose languages appear in langs.
cs_result csonar_add_pdg_vertex_visitor ( cs_langs_t langs, cs_pdg_vertex_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase visitor for points (cs_pdg_vertex) in compilation units whose languages appear in langs.
cs_result csonar_add_pdg_finish_visitor ( cs_langs_t langs, cs_pdg_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase finish visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
cs_result csonar_add_sf_visitor ( cs_langs_t langs, cs_sfi_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase visitor for files in compilation units whose languages appear in langs.
cs_result csonar_add_sfi_visitor ( cs_langs_t langs, cs_sfi_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase visitor for file instances in compilation units whose languages appear in langs.
cs_result csonar_add_sfi_finish_visitor ( cs_langs_t langs, cs_sfi_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase visitor for file instances in compilation units whose languages appear in langs.
cs_result csonar_add_sf_finish_visitor ( cs_langs_t langs, cs_sfi_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase finish visitor for files in compilation units whose languages appear in langs.
cs_result csonar_add_uid_finish_visitor ( cs_langs_t langs, cs_uid_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a serial depth-first phase finish visitor for compilation units (cs_uid) whose languages appear in langs.
cs_result csonar_add_program_finish_visitor ( cs_langs_t langs, cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th as a serial depth-first program finish visitor for programs whose languages appear in langs.
cs_result csonar_add_program_parallel_visitor ( cs_langs_t langs, cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th as a parallel depth-first program visitor for programs whose languages appear in langs.
cs_result csonar_add_uid_parallel_visitor ( cs_langs_t langs, cs_uid_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase visitor for compilation units (cs_uid) whose languages appear in langs.
cs_result csonar_add_pdg_parallel_visitor ( cs_langs_t langs, cs_pdg_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
cs_result csonar_add_abs_loc_parallel_visitor ( cs_langs_t langs, cs_abs_loc_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase visitor for symbols (cs_abs_loc) in compilation units whose languages appear in langs.
cs_result csonar_add_pdg_vertex_parallel_visitor ( cs_langs_t langs, cs_pdg_vertex_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase visitor for points (cs_pdg_vertex) in compilation units whose languages appear in langs.
cs_result csonar_add_pdg_parallel_finish_visitor ( cs_langs_t langs, cs_pdg_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase finish visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
cs_result csonar_add_sf_parallel_visitor ( cs_langs_t langs, cs_sfi_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase visitor for files in compilation units whose languages appear in langs.
cs_result csonar_add_sfi_parallel_visitor ( cs_langs_t langs, cs_sfi_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase visitor for file instances in compilation units whose languages appear in langs.
cs_result csonar_add_sfi_parallel_finish_visitor ( cs_langs_t langs, cs_sfi_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase visitor for file instances in compilation units whose languages appear in langs.
cs_result csonar_add_sf_parallel_finish_visitor ( cs_langs_t langs, cs_sfi_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase finish visitor for files in compilation units whose languages appear in langs.
cs_result csonar_add_uid_parallel_finish_visitor ( cs_langs_t langs, cs_uid_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a parallel depth-first phase finish visitor for compilation units (cs_uid) whose languages appear in langs.
cs_result csonar_add_program_parallel_finish_visitor ( cs_langs_t langs, cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th as a parallel depth-first program finish visitor for programs whose languages appear in langs.
cs_result csonar_add_program_bottom_up_visitor ( cs_langs_t langs, cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th as a bottom-up program visitor for programs whose languages appear in langs.
cs_result csonar_add_pdg_bottom_up_visitor ( cs_langs_t langs, cs_pdg_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a bottom-up phase visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
cs_result csonar_add_pdg_vertex_bottom_up_visitor ( cs_langs_t langs, cs_pdg_vertex_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a bottom-up phase visitor for points (cs_pdg_vertex) in compilation units whose languages appear in langs.
cs_result csonar_add_step_bottom_up_visitor ( cs_langs_t langs, cs_const_step_visitor_dispatch_t * vis, cs_visitor_ctx_t ctx )
Add vis as a bottom-up phase visitor for CFG edges as they are stepped over by the analysis.
cs_result csonar_add_pdg_bottom_up_finish_visitor ( cs_langs_t langs, cs_pdg_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a bottom-up phase finish visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
cs_result csonar_add_program_bottom_up_finish_visitor ( cs_langs_t langs, cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th as a bottom-up program finish visitor for programs whose languages appear in langs.
cs_result csonar_add_program_drop_visitor ( cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th to the list of program drop visitors, which are invoked at the beginning of the drop phase.
cs_result csonar_add_uid_drop_visitor ( cs_uid_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a drop phase compilation unit visitor.
cs_result csonar_add_pdg_drop_visitor ( cs_pdg_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a drop phase procedure (cs_pdg) visitor.
cs_result csonar_add_global_abs_loc_drop_visitor ( cs_abs_loc_visitor_t vis, cs_visitor_ctx_t ctx )
Add vis as a drop phase visitor for global symbols (cs_abs_loc).
cs_result csonar_add_program_drop_finish_visitor ( cs_thunk_t th, cs_visitor_ctx_t ctx )
Add th to the list of program drop finish visitors, which are invoked at the end of the drop phase.
cs_result csonar_add_cache_cleanup_visitor ( cs_thunk_t vis, cs_visitor_ctx_t ctx )
Add vis as a cache-cleanup visitor.
cs_warningclass_t csonar_create_warningclass ( cs_const_string wc_name, cs_const_string wc_categories, double base_rank, csonar_warningclass_flags flags, csonar_warning_significance wc_significance )
Create and return a new warning class.
cs_result csonar_create_warningclass_ex ( const char * wc_name, const char * wc_categories, double base_rank, csonar_warningclass_flags flags, csonar_warning_significance wc_significance, cs_warningclass_t * out )
Create a new warning class.
csuint32 csonar_warningclass_id ( cs_warningclass_t wc )
Get the ID of a cs_warningclass_t, as a csuint32.
cs_result csonar_warningclass_lookup ( csuint32 class_id, cs_warningclass_t * out )
Get the cs_warningclass_t with the specified ID.
cs_result csonar_warningclass_lookup_by_name ( cs_const_string class_name, cs_warningclass_t * out )
Get the cs_warningclass_t with the specified name.
cs_boolean csonar_warningclass_always_discarded ( cs_warningclass_t wc )
Check: are WARNING_FILTER settings such that instances of the specified warning class will always be ignored?
cs_boolean csonar_warningclass_allowed ( cs_warningclass_t wc )
Check: are WARNING_FILTER settings such that reported instances of the specified warning class will be submitted to the hub?
cs_const_string csonar_warningclass_name ( cs_warningclass_t wc )
Get the name of the specified warning class.
cs_result csonar_report_warning ( cs_pdg_vertex v, cs_warningclass_t wc, cs_const_string problem, cs_report_flags report_flags, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Issue a warning at a cs_pdg_vertex.
cs_result csonar_report_path_warning ( const cs_cfg_path_node_t * warning_path, cs_size_t len, cs_warningclass_t wc, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Report a warning with a path.
cs_result csonar_report_step_path_warning ( cs_step_path_t warning_path, cs_warningclass_t wc, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Report a warning with a step path.
cs_result csonar_report_location_warning ( cs_sfid warning_file, cs_line warning_line, cs_warningclass_t wc, cs_const_string prob, cs_report_flags report_flags, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Issue a warning at a source line.
cs_result csonar_report_location_span_warning ( cs_sfid warning_file, cs_line warning_start_line, cs_line warning_end_line, cs_column start_col, cs_column end_col, cs_warningclass_t wc, cs_const_string prob, cs_report_flags report_flags, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Issue a warning with a code span location.
cs_result csonar_report_location_warning_in_pdg ( cs_sfid warning_file, cs_line warning_line, cs_pdg proc, cs_warningclass_t wc, cs_const_string prob, cs_report_flags report_flags, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Issue a warning at a source line in a specified procedure.
cs_result csonar_report_location_span_warning_in_pdg ( cs_sfid warning_file, cs_line warning_start_line, cs_line warning_end_line, cs_column start_col, cs_column end_col, cs_pdg proc, cs_warningclass_t wc, cs_const_string prob, cs_report_flags report_flags, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Issue a warning at a span in a specified procedure.
cs_result csonar_report_locations_warning ( const cs_locations_node_t * warning_locs, cs_size_t num_locs, cs_warningclass_t wc, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Issue a warning for a list of code locations.
cs_result csonar_report_locations_warning_in_pdg ( cs_pdg proc, const cs_locations_node_t * warning_locs, cs_size_t num_locs, cs_warningclass_t wc, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Issue a warning for a list of code locations in a specified procedure.
cs_result csonar_report_file_warning ( cs_sfid warning_file, cs_warningclass_t wc, cs_const_string prob, cs_report_flags report_flags, const cs_warning_retraction_info_t * ri, cs_warning_id * id )
Issue a warning associated with a particular source file instance, as opposed to a specific source location or set of locations.
cs_result csonar_report_analysis_warning ( cs_warningclass_t wc, cs_const_string problem, cs_report_flags report_flags, cs_warning_id * id )
Issue a warning with no association to a file or procedure.
cs_result csonar_retract_warning ( const cs_warning_id * id )
Manually retract a warning instance.
cs_result csonar_pdg_vertex_position ( cs_pdg_vertex v, cs_sfid * vertex_file, cs_line * vertex_line )
Get the starting file instance and line of a cs_pdg_vertex.
cs_result csonar_pdg_vertex_callee ( cs_pdg_vertex v, cs_pdg * pdg )
Get the callee cs_pdg of a call site cs_pdg_vertex, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
cs_result csonar_pdg_vertex_callee_no_reroute ( cs_pdg_vertex v, cs_pdg * pdg )
Get the callee cs_pdg of a call site cs_pdg_vertex, ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
cs_result csonar_pdg_vertex_callees_iter_first ( cs_pdg_vertex v, cs_pdg * callee_pdg, csonar_pdg_callees_iter * itr )
Open a cs_pdg_callees_iter iterator for traversing the callees from a specified point (cs_pdg_vertex), taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable, and retrieve the first callee cs_pdg from the iterator.
cs_result csonar_pdg_vertex_callees_iter_next ( cs_pdg * callee_pdg, csonar_pdg_callees_iter * itr )
Advance the provided csonar_pdg_callees_iter iterator and retrieve the next element.
cs_result csonar_pdg_vertex_callees_iter_close ( csonar_pdg_callees_iter * itr )
Close a csonar_pdg_callees_iter iterator.
cs_result csonar_pdg_vertex_callees_no_reroute_iter_first ( cs_pdg_vertex v, cs_pdg * callee_pdg, csonar_pdg_callees_no_reroute_iter * itr )
Open a csonar_pdg_callees_no_reroute_iter iterator for traversing the callees from a specified point (cs_pdg_vertex), ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable, and retrieve the first callee cs_pdg from the iterator.
cs_result csonar_pdg_vertex_callees_no_reroute_iter_next ( cs_pdg * callee_pdg, csonar_pdg_callees_no_reroute_iter * itr )
Advance the provided csonar_pdg_callees_no_reroute_iter iterator and retrieve the next element.
cs_result csonar_pdg_vertex_callees_no_reroute_iter_close ( csonar_pdg_callees_no_reroute_iter * itr )
Close a csonar_pdg_callees_no_reroute_iter iterator.
cs_result csonar_pdg_callers_iter_first ( cs_pdg pdg, cs_pdg_vertex * calling_site, csonar_pdg_callers_iter * itr )
Open a cs_pdg_callers_iter iterator for traversing the call sites to a specified procedure (cs_pdg), and retrieve the first call site (cs_pdg_vertex) from the iterator.
cs_result csonar_pdg_callers_iter_next ( cs_pdg_vertex * calling_site, csonar_pdg_callers_iter * itr )
Advance the provided cs_pdg_callers_iter iterator and retrieve the next element.
cs_result csonar_pdg_callers_iter_close ( csonar_pdg_callers_iter * itr )
Close a cs_pdg_callers_iter iterator.
cs_result csonar_step_path_to_list ( cs_step_path_t rpath, cs_cfg_path_node_t path_list[], cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Retrieve the list of cs_cfg_path_node_t nodes corresponding to a cs_step_path_t.
cs_result csonar_step_path_to_string ( cs_step_path_t rpath, cs_string out_string, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get a textual representation of a cs_step_path_t.
cs_step_path_t csonar_step_path_copy ( cs_step_path_t rpath )
Copy a step path (cs_step_path_t).
void csonar_step_path_destroy ( cs_step_path_t rpath )
Destroy a step path (cs_step_path_t) that was created by csonar_step_path_copy().
cs_result csonar_pdg_vertex_to_string ( cs_pdg_vertex v, cs_string out_string, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get a textual representation of a cs_pdg_vertex.
cs_const_string csonar_access_path_operator_name ( cs_access_path_operator op )
Get the name of a cs_access_path_operator.
cs_const_string csonar_xform_expr_mode_name ( cs_xform_expr_mode m )
Get the name of a cs_xform_expr_mode.
cs_const_string csonar_xform_query_result_name ( cs_xform_query_result r )
Get the name of a cs_xform_query_result.
cs_result csonar_xform_expr_validate ( const cs_xform_expr * expr )
Check whether a cs_xform_expr is well-formed.
cs_result csonar_xform_expr_to_string ( const cs_xform_expr * expr, cs_string out_string, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get a textual representation of a cs_xform_expr.
cs_const_string csonar_xform_operator_name ( cs_xform_operator op )
Get the name of a cs_xform_operator.
cs_result csonar_xform_query ( cs_step_csonar_xform_t s, const cs_xform_expr * lhs, cs_xform_operator op, const cs_xform_expr * rhs, cs_xform_query_result * out_result )
Allows users to issue queries with respect to a program state transformation.
cs_result csonar_xform_query_bounds ( cs_step_csonar_xform_t s, const cs_xform_expr * expr, csint32 * lb, cs_boolean * lb_suspect, csint32 * ub, cs_boolean * ub_suspect )
Get bounds on an expression.
cs_boolean csonar_metricclass_always_discarded ( cs_metricclass_t mc )
Check: are METRIC_FILTER settings such that instances of the specified warning class will always be ignored?
cs_boolean csonar_metricclass_allowed ( cs_metricclass_t mc )
Check: are METRIC_FILTER settings such that reported instances of the specified metric class will be submitted to the hub?
cs_result csonar_report_metric_analysis ( cs_metricclass_t mt, double val )
Report an analysis granularity metric value to the hub.
cs_result csonar_report_metric_compunit ( cs_metricclass_t mt, double val, cs_uid uid )
Report a compilation unit granularity metric value to the hub.
cs_result csonar_report_metric_file ( cs_metricclass_t mt, double val, cs_sf sf )
Report a file granularity metric value to the hub.
cs_result csonar_report_metric_procedure ( cs_metricclass_t mt, double val, cs_pdg pdg )
Report a procedure granularity metric value.
cs_metric_granularity csonar_metric_get_granularity ( cs_metricclass_t mc )
Get the granularity of a cs_metricclass_t.
cs_const_string csonar_metric_tag ( cs_metricclass_t mc )
Get the tag (short string identifier) of a cs_metricclass_t.
cs_const_string csonar_metric_description ( cs_metricclass_t mc )
Get the description of a cs_metricclass_t.
cs_hash_t csonar_metric_hash ( cs_metricclass_t mc )
Hash function for cs_metricclass_t.
int csonar_metric_compare ( cs_metricclass_t mc1, cs_metricclass_t mc2 )
Compare two cs_metricclass_t values.
cs_boolean csonar_metric_equal ( cs_metricclass_t mc1, cs_metricclass_t mc2 )
Compare two cs_metricclass_t values for equality.
cs_result csonar_metric_getvalue_analysis ( cs_metricclass_t mt, double * mval )
Get the value of an analysis granularity metric.
cs_result csonar_metric_getvalue_compunit ( cs_metricclass_t mt, cs_uid uid, double * mval )
Get the value of a compilation unit granularity metric.
cs_result csonar_metric_getvalue_file ( cs_metricclass_t mt, cs_sf sf, double * mval )
Get the value of a file granularity metric.
cs_result csonar_metric_getvalue_procedure ( cs_metricclass_t mt, cs_pdg pdg, double * mval )
Get the value of a procedure granularity metric.
cs_result csonar_metric_create_class_analysis ( cs_const_string metrictag, cs_const_string desc, cs_metric_calc_analysis_fn_t fn, cs_metricclass_flags flags, const void * ctx, cs_metricclass_t * metricclass )
Create a new analysis granularity metric class.
cs_result csonar_metric_create_class_compunit ( cs_const_string metrictag, cs_const_string desc, cs_metric_calc_compunit_fn_t fn, cs_metricclass_flags flags, const void * ctx, cs_metricclass_t * metricclass )
Create a new compilation unit granularity metric class.
cs_result csonar_metric_create_class_file ( cs_const_string metrictag, cs_const_string desc, cs_metric_calc_file_fn_t fn, cs_metricclass_flags flags, const void * ctx, cs_metricclass_t * metricclass )
Create a new file granularity metric class.
cs_result csonar_metric_create_class_procedure ( cs_const_string metrictag, cs_const_string desc, cs_metric_calc_procedure_fn_t fn, cs_metricclass_flags flags, const void * ctx, cs_metricclass_t * metricclass )
Create a new procedure granularity metric class.
cs_result csonar_metric_get_class ( cs_const_string metrictag, cs_metric_granularity gran, cs_metricclass_t * metricclass )
Get the metric class object with the specified tag and granularity.
cs_result csonar_metric_class_iter_first ( cs_metric_granularity gran, cs_metricclass_t * metricclass, cs_metric_class_iterator * itr )
Open a cs_metric_class_iterator for traversing the metric classes with the specified granularity, and retrieve the first cs_metricclass_t from the iterator.
cs_result csonar_metric_class_iter_next ( cs_metricclass_t * metricclass, cs_metric_class_iterator * itr )
Advance the provided cs_metric_class_iterator and retrieve the next element.
cs_result csonar_metric_class_iter_close ( cs_metric_class_iterator * itr )
Close a metric class iterator.
cs_result csonar_metric_retract_procedure ( cs_metricclass_t metricclass, cs_pdg pdg )
Retract a metric value for the given class/procedure combination.
cs_result csonar_metric_retract_file ( cs_metricclass_t metricclass, cs_sf sf )
Retract a metric value for the given class/source file combination.
cs_result csonar_metric_retract_compunit ( cs_metricclass_t metricclass, cs_uid uid )
Retract a metric value for the given class/compilation unit combination.
cs_metricclass_flags csonar_metric_flags ( cs_metricclass_t metricclass )
Retrieve the flags for a cs_metricclass_t.
cs_result csonar_file_is_system_include ( cs_sfid f, cs_boolean * res )
Check whether the specified file is located in a system directory.
cs_result csonar_binary_backend_option ( cs_const_string inkey, cs_const_string * val )
[CodeSonar for Binaries only] Get the value associated with the key in the BINARY_BACKEND_OPTIONS configuration file setting.
cs_const_string csonar_warning_significance_name ( csonar_warning_significance s )
Get the name of a csonar_warning_significance.
cs_result csonar_warning_significance_lookup ( cs_const_string sig_name, csonar_warning_significance * sig )
Get the csonar_warning_significance with the specified name.
cs_result csonar_pdg_vertex_enum_used ( cs_pdg_vertex pdgv, cs_abs_loc abslocs[], cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get the list of used symbols (cs_abs_loc) for a point (cs_pdg_vertex), computing the list on-demand.
cs_result csonar_pdg_vertex_enum_killed ( cs_pdg_vertex pdgv, cs_abs_loc abslocs[], cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get the list of killed symbols (cs_abs_loc) for a point (cs_pdg_vertex), computing the list on-demand.
cs_result csonar_register_rpc_handler ( cs_const_string message_name, cs_rpc_handler_fn_t handler, void * ctx )
Register a remote procedure call (RPC) handler that will respond to request from the CodeSonar hub.
cs_string csonar_rpc_response_alloc ( cs_size_t s )
Allocates memory for the response that is sent back to the hub after processing an RPC request.
cs_result csonar_pdg_vertex_enum_referenced ( cs_pdg_vertex pdgv, cs_abs_loc abslocs[], cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get the list of referenced symbols (cs_abs_loc) for a point (cs_pdg_vertex), computing the list on-demand.
cs_result csonar_sf_get_pdgs_for_procedure ( cs_sf sf, cs_line line_num, const cs_hash_t * friendly_name_hash, cs_boolean closest_prior, cs_pdg * pdg_list, cs_size_t capacity_bytes, cs_size_t * bytes_needed )
Get all instances (cs_pdg) of a procedure (specified by its source file, line, and friendly-name hash).
cs_result csonar_pdg_reachable ( cs_pdg pdg, cs_boolean * out_result )
Check: is a cs_pdg reachable from the reachability roots specified with configuration file parameter REACHABILITY_ROOTS?

Function Descriptions

Function csonar_get_analysis_mode
csonar_analysis_mode csonar_get_analysis_mode ( )
Get the analysis mode for the CodeSonar process in which the plug-in is running.
Returns The csonar_analysis_mode corresponding to the current mode of the CodeSonar process.
Function csonar_analysis_mode_name
cs_const_string csonar_analysis_mode_name (
Get the name of a csonar_analysis_mode.
Parameters
m [in] The csonar_analysis_mode of interest.
Returns The name of m, as a cs_const_string.
Function csonar_get_multiprocess_mode
csonar_multiprocess_mode csonar_get_multiprocess_mode ( )
Get the multiprocess mode for the CodeSonar process in which the plug-in is running.
Returns The csonar_multiprocess_mode corresponding to the current mode of the CodeSonar process.
Notes See Parallelism in CodeSonar: Analysis for more information.
Function csonar_multiprocess_mode_name
cs_const_string csonar_multiprocess_mode_name (
Get the name of a csonar_multiprocess_mode.
Parameters
m [in] The csonar_multiprocess_mode of interest.
Returns The name of m, as a cs_const_string.
Function csonar_add_setup_visitor
cs_result csonar_add_setup_visitor (
Add th as a setup visitor for programs whose languages appear in langs.
Parameters
langs [in] A list of languages; th will only be applied to programs whose languages appear on this list.
th [in] The cs_thunk_t to add to the program visitor list.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_program_visitor
cs_result csonar_add_program_visitor (
Add th as a serial depth-first program visitor for programs whose languages appear in langs.
Parameters
langs [in] A list of languages; th will only be applied to programs whose languages appear on this list.
th [in] The cs_thunk_t to add to the program visitor list.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes During analysis, th will be applied to the program after any program setup visitors are applied, but before the beginning of the serial depth-first analysis phase.
Function csonar_add_uid_visitor
cs_result csonar_add_uid_visitor (
Add vis as a serial depth-first phase visitor for compilation units (cs_uid) whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to compilation units whose languages appear in this list.
vis [in] The cs_uid_visitor_t to add to the serial depth-first phase visitor list for compilation units.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_pdg_visitor
cs_result csonar_add_pdg_visitor (
Add vis as a serial depth-first phase visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to procedures in compilation units whose languages appear in this list.
vis [in] The cs_pdg_visitor_t to add to the serial depth-first phase visitor list for procedures.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_abs_loc_visitor
cs_result csonar_add_abs_loc_visitor (
Add vis as a serial depth-first phase visitor for symbols (cs_abs_loc) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to symbols in compilation units whose languages appear in this list.
vis [in] The cs_abs_loc_visitor_t to add to the serial depth-first phase visitor list for symbols.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes During the serial depth-first analysis phase, vis will be applied to symbols (cs_abs_loc) in the project that are contained in a compilation unit whose language appears in langs.
  • In base analyses, it will be applied to every such symbol in the project.
  • In incremental analyses, it will be applied only to symbols contained in compilation units compiled in the increment.
Function csonar_add_pdg_vertex_visitor
cs_result csonar_add_pdg_vertex_visitor (
Add vis as a serial depth-first phase visitor for points (cs_pdg_vertex) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to points in compilation units whose languages appear in this list.
vis [in] The cs_pdg_vertex_visitor_t to add to the serial depth-first phase visitor list for points.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_pdg_finish_visitor
cs_result csonar_add_pdg_finish_visitor (
Add vis as a serial depth-first phase finish visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to procedures in compilation units whose languages appear in this list.
vis [in] The cs_pdg_visitor_t to add to the serial depth-first phase finish visitor list for procedures.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_sf_visitor
cs_result csonar_add_sf_visitor (
Add vis as a serial depth-first phase visitor for files in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to files in compilation units whose languages appear in this list.
vis [in] The cs_sfi_visitor_t to add to the serial depth-first phase visitor list for files.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes A source file visitor is like a source file instance visitor except that it is only applied to the first instance encountered for each source file during the depth-first traversal of the file include tree. It is therefore possible for the visitor to be applied to the SFID for one or more file instances included by instance S but not to the SFID for S itself.
Function csonar_add_sfi_visitor
cs_result csonar_add_sfi_visitor (
Add vis as a serial depth-first phase visitor for file instances in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to file instances in compilation units whose languages appear in this list.
vis [in] The cs_sfi_visitor_t to add to the serial depth-first phase visitor list for file instances.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes For each qualifying file in the program, vis will be applied to every instance of the file encountered during the depth-first traversal of the file include tree.
Function csonar_add_sfi_finish_visitor
cs_result csonar_add_sfi_finish_visitor (
Add vis as a serial depth-first phase visitor for file instances in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to file instances in compilation units whose languages appear in this list.
vis [in] The cs_sfi_visitor_t to add to the serial depth-first phase visitor list for file instances.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes For each qualifying file in the program, vis will be applied to every instance of the file encountered during the depth-first traversal of the file include tree.
Function csonar_add_sf_finish_visitor
cs_result csonar_add_sf_finish_visitor (
Add vis as a serial depth-first phase finish visitor for files in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to files in compilation units whose languages appear in this list.
vis [in] The cs_sfi_visitor_t to add to the serial depth-first phase finish visitor list for files.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes For each qualifying file in the program, vis will only be applied to the first instance of the file encountered during the depth-first traversal of the file include tree.
Function csonar_add_uid_finish_visitor
cs_result csonar_add_uid_finish_visitor (
Add vis as a serial depth-first phase finish visitor for compilation units (cs_uid) whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to compilation units whose languages appear in this list.
vis [in] The cs_uid_visitor_t to add to the serial depth-first phase finish visitor list for compilation units.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_program_finish_visitor
cs_result csonar_add_program_finish_visitor (
Add th as a serial depth-first program finish visitor for programs whose languages appear in langs.
Parameters
langs [in] A list of languages; th will only be applied to programs whose languages appear on this list.
th [in] The cs_thunk_t to add to the program finish visitor list.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes th will be applied to the program after the end of the serial depth-first phase, but before the beginning of the parallel depth-first phase.
Function csonar_add_program_parallel_visitor
cs_result csonar_add_program_parallel_visitor (
Add th as a parallel depth-first program visitor for programs whose languages appear in langs.
Parameters
langs [in] A list of languages; th will only be applied to programs whose languages appear on this list.
th [in] The cs_thunk_t to add to the parallel depth-first phase program visitor list.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes During analysis, th will be applied to the program after the serial depth-first analysis phase ends and any program finish visitors are applied, but before the beginning of the parallel depth-first analysis phase.
Function csonar_add_uid_parallel_visitor
cs_result csonar_add_uid_parallel_visitor (
Add vis as a parallel depth-first phase visitor for compilation units (cs_uid) whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to compilation units whose languages appear in this list.
vis [in] The cs_uid_visitor_t to add to the parallel depth-first phase visitor list for compilation units.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_pdg_parallel_visitor
cs_result csonar_add_pdg_parallel_visitor (
Add vis as a parallel depth-first phase visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to procedures in compilation units whose languages appear in this list.
vis [in] The cs_pdg_visitor_t to add to the depth-first phase visitor list for procedures.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_abs_loc_parallel_visitor
cs_result csonar_add_abs_loc_parallel_visitor (
Add vis as a parallel depth-first phase visitor for symbols (cs_abs_loc) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to symbols in compilation units whose languages appear in this list.
vis [in] The cs_abs_loc_visitor_t to add to the parallel depth-first phase visitor list for symbols.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes During the parallel depth-first analysis phase, vis will be applied to symbols (cs_abs_loc) in the project that are contained in a compilation unit whose language appears in langs.
  • In base analyses, it will be applied to every such symbol in the project.
  • In incremental analyses, it will be applied only to symbols contained in compilation units compiled in the increment.
Function csonar_add_pdg_vertex_parallel_visitor
cs_result csonar_add_pdg_vertex_parallel_visitor (
Add vis as a parallel depth-first phase visitor for points (cs_pdg_vertex) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to points in compilation units whose languages appear in this list.
vis [in] The cs_pdg_vertex_visitor_t to add to the parallel depth-first phase visitor list for points.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_pdg_parallel_finish_visitor
cs_result csonar_add_pdg_parallel_finish_visitor (
Add vis as a parallel depth-first phase finish visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to procedures in compilation units whose languages appear in this list.
vis [in] The cs_pdg_visitor_t to add to the parallel depth-first phase finish visitor list for procedures.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_sf_parallel_visitor
cs_result csonar_add_sf_parallel_visitor (
Add vis as a parallel depth-first phase visitor for files in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to files in compilation units whose languages appear in this list.
vis [in] The cs_sfi_visitor_t to add to the parallel depth-first phase visitor list for files.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes A source file visitor is like a source file instance visitor except that it is only applied to the first instance encountered for each source file during the depth-first traversal of the file include tree. It is therefore possible for the visitor to be applied to the SFID for one or more file instances included by instance S but not to the SFID for S itself.
Function csonar_add_sfi_parallel_visitor
cs_result csonar_add_sfi_parallel_visitor (
Add vis as a parallel depth-first phase visitor for file instances in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to file instances in compilation units whose languages appear in this list.
vis [in] The cs_sfi_visitor_t to add to the parallel depth-first phase visitor list for file instances.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes For each qualifying file in the program, vis will be applied to every instance of the file encountered during the depth-first traversal of the file include tree.
Function csonar_add_sfi_parallel_finish_visitor
cs_result csonar_add_sfi_parallel_finish_visitor (
Add vis as a parallel depth-first phase visitor for file instances in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to file instances in compilation units whose languages appear in this list.
vis [in] The cs_sfi_visitor_t to add to the parallel depth-first phase finish visitor list for file instances.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes For each qualifying file in the program, vis will be applied to every instance of the file encountered during the depth-first traversal of the file include tree.
Function csonar_add_sf_parallel_finish_visitor
cs_result csonar_add_sf_parallel_finish_visitor (
Add vis as a parallel depth-first phase finish visitor for files in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to files in compilation units whose languages appear in this list.
vis [in] The cs_sfi_visitor_t to add to the parallel depth-first phase finish visitor list for files.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes For each qualifying file in the program, vis will only be applied to the first instance of the file encountered during the depth-first traversal of the file include tree.
Function csonar_add_uid_parallel_finish_visitor
cs_result csonar_add_uid_parallel_finish_visitor (
Add vis as a parallel depth-first phase finish visitor for compilation units (cs_uid) whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to compilation units whose languages appear in this list.
vis [in] The cs_uid_visitor_t to add to the parallel depth-first phase finish visitor list for compilation units.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_program_parallel_finish_visitor
cs_result csonar_add_program_parallel_finish_visitor (
Add th as a parallel depth-first program finish visitor for programs whose languages appear in langs.
Parameters
langs [in] A list of languages; th will only be applied to programs whose languages appear on this list.
th [in] The cs_thunk_t to add to the program visitor list.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes th will be applied to the program after the parallel depth-first phase has finished, but before the beginning of the pointer analysis phase.
Function csonar_add_program_bottom_up_visitor
cs_result csonar_add_program_bottom_up_visitor (
Add th as a bottom-up program visitor for programs whose languages appear in langs.
Parameters
langs [in] A list of languages; th will only be applied to programs whose languages appear in this list.
th [in] The cs_thunk_t to add to the program bottom-up phase visitor list.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes th will be applied to the program after the end of the pointer analysis phase, but before the beginning of the bottom-up phase.
Function csonar_add_pdg_bottom_up_visitor
cs_result csonar_add_pdg_bottom_up_visitor (
Add vis as a bottom-up phase visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to procedures in compilation units whose languages appear in this list.
vis [in] The cs_pdg_visitor_t to add to the list of bottom-up phase visitors for procedures.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_pdg_vertex_bottom_up_visitor
cs_result csonar_add_pdg_vertex_bottom_up_visitor (
Add vis as a bottom-up phase visitor for points (cs_pdg_vertex) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to points in compilation units whose languages appear in this list.
vis [in] The cs_pdg_visitor_t to add to the list of bottom-up phase visitors for points.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_step_bottom_up_visitor
cs_result csonar_add_step_bottom_up_visitor (
Add vis as a bottom-up phase visitor for CFG edges as they are stepped over by the analysis.
Parameters
langs [in] A list of languages; vis will only be applied to CFG edges in compilation units whose languages appear in this list.
vis [in] The cs_step_visitor_dispatch_t to add to the list of bottom-up phase visitors for CFG edges.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes A single edge may be visited many times.

See Plug-In Tutorial: Part Two for an example using a step visitor.

Function csonar_add_pdg_bottom_up_finish_visitor
cs_result csonar_add_pdg_bottom_up_finish_visitor (
Add vis as a bottom-up phase finish visitor for procedures (cs_pdg) in compilation units whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to procedures in compilation units whose languages appear in this list.
vis [in] The cs_pdg_visitor_t to add to the list of bottom-up phase finish visitors for procedures.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Function csonar_add_program_bottom_up_finish_visitor
cs_result csonar_add_program_bottom_up_finish_visitor (
Add th as a bottom-up program finish visitor for programs whose languages appear in langs.
Parameters
langs [in] A list of languages; vis will only be applied to programs whose languages appear in this list.
th [in] The cs_thunk_t to add to the list of program finish visitors.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes th will be applied to the program after the end of the bottom-up analysis phase. At this point, all traversal has finished.
Function csonar_add_program_drop_visitor
cs_result csonar_add_program_drop_visitor (
Add th to the list of program drop visitors, which are invoked at the beginning of the drop phase.
Parameters
th [in] The cs_thunk_t to add to the list of program drop visitors.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes Program drop visitors are called at the beginning of the drop phase if anything in the project has been dropped.

Use a program drop visitor when you need to clean up state that you have saved for dropped project components and cannot handle the cleanup with one of the smaller-scope drop visitors.

th must not call any API functions other than the following: cs_pdg_equal(), cs_pdg_hash(), cs_uid_equal(), cs_uid_hash(), cs_abs_loc_equal(), cs_abs_loc_hash().

Function csonar_add_uid_drop_visitor
cs_result csonar_add_uid_drop_visitor (
Add vis as a drop phase compilation unit visitor.
Parameters
vis [in] The cs_uid_visitor_t to add to the list of compilation unit drop visitors.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes A compilation unit will be visited in the drop phase if any of the following are true:
  • the compilation unit has been dropped
  • a file static in the compilation unit has been dropped
  • the compilation unit include tree has changed

Use a compilation unit drop visitor to clean up any state you have saved for:

  • the compilation unit
  • any file instances in the compilation unit
  • any ASTs (cs_ast) in the compilation unit
  • any component you can clean up with a procedure drop visitor: see csonar_add_pdg_drop_visitor().

See csonar_add_program_drop_visitor() for the list of API functions that can be used in drop visitors.

Function csonar_add_pdg_drop_visitor
cs_result csonar_add_pdg_drop_visitor (
Add vis as a drop phase procedure (cs_pdg) visitor.
Parameters
vis [in] The cs_pdg_visitor_t to add to the list of procedure drop visitors.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes A procedure cs_pdg) will be visited in the drop phase if any of the following are true:
  • the procedure has been dropped
  • a function static variable in the procedure has been dropped
  • a point (cs_pdg_vertex) in the procedure has been dropped

Use a procedure drop visitor to clean up any state that you have saved for:

See csonar_add_program_drop_visitor() for the list of API functions that can be used in drop visitors.

Function csonar_add_global_abs_loc_drop_visitor
cs_result csonar_add_global_abs_loc_drop_visitor (
Add vis as a drop phase visitor for global symbols (cs_abs_loc).
Parameters
vis [in] The cs_abs_loc_visitor_t to add to the list of drop visitors for global symbols.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes A global symbol (cs_abs_loc) will be visited in the drop phase if it has been dropped.

Use a global symbol drop visitor to clean up any state that you have saved for:

  • the symbol

See csonar_add_program_drop_visitor() for the list of API functions that can be used in drop visitors.

Function csonar_add_program_drop_finish_visitor
cs_result csonar_add_program_drop_finish_visitor (
Add th to the list of program drop finish visitors, which are invoked at the end of the drop phase.
Parameters
th [in] The cs_thunk_t to add to the list of program drop visitors.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes Program drop finish visitors are called at the end of the drop phase if anything in the project has been dropped.

Use a program drop finish visitor when you need to clean up state that you have saved for dropped project components and cannot handle the cleanup with one of the smaller-scope drop visitors.

See csonar_add_program_drop_visitor() for the list of API functions that can be used in drop visitors.

Function csonar_add_cache_cleanup_visitor
cs_result csonar_add_cache_cleanup_visitor (
Add vis as a cache-cleanup visitor.
Parameters
vis [in] The cs_thunk_t to add to the list of cache-cleanup visitors.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns A cs_result:
Notes Cache-cleanup visitors are invoked periodically as the analysis progresses.
Function csonar_create_warningclass
cs_warningclass_t csonar_create_warningclass (
Create and return a new warning class.
Parameters
wc_name [in] The name for the new warning class. Do not specify a name containing the '$' character: behavior is undefined in this case.
wc_categories [in] The categories for the class, as a semicolon-separated list of items, such as: "CWE:124;LANG.MEM.BO". Can be NULL.
base_rank [in] A value that will be used as a starting point for calculating the rank for warnings of this class, which in turn will determine where those warnings appear in the recommended review order. Warnings from built in warning classes have ranks in the range 1 (most important) to 100 (least important).
flags [in] csonar_warningclass_flags describing the desired properties of the new warning class.
wc_significance [in] The significance setting for the class.
Returns The new class, as a cs_warningclass_t.
Notes Creates and returns a new warning class called wc_name, with properties determined by flags. This procedure should be called by setup visitors only and cannot be called by other visitors.

If there are multiple calls to csonar_create_warningclass() or csonar_create_warningclass_ex() with the same wc_name, the second and subsequent calls will ignore all other parameters and just return the cs_warningclass_t created by the first call.

Function csonar_create_warningclass_ex
cs_result csonar_create_warningclass_ex (
Create a new warning class.
Parameters
wc_name [in] The name for the new warning class. Do not specify a name containing the '$' character: behavior is undefined in this case.
wc_categories [in] The categories for the class, as a semicolon-separated list of items, such as: "CWE:124;LANG.MEM.BO". Can be NULL.
base_rank [in] A value that will be used as a starting point for calculating the rank for warnings of this class, which in turn will determine where those warnings appear in the recommended review order. Warnings from built in warning classes have ranks in the range 1 (most important) to 100 (least important).
flags [in] csonar_warningclass_flags describing the desired properties of the new warning class.
wc_significance [in] The significance setting for the class.
out [out] On success, the function will populate this with a cs_warningclass_t. Cannot be NULL.
Returns A cs_result:
Notes Creates and returns a new warning class called wc_name, with properties determined by flags. This procedure should be called by setup visitors only and cannot be called by other visitors.

If there are multiple calls to csonar_create_warningclass() or csonar_create_warningclass_ex() with the same wc_name, the second and subsequent calls will ignore all other parameters and just return the cs_warningclass_t created by the first call.

Function csonar_warningclass_id
csuint32 csonar_warningclass_id (
Get the ID of a cs_warningclass_t, as a csuint32.
Parameters
wc [in] The cs_warningclass_t whose ID is required.
Returns The ID of wc, as a csuint32.
Notes A single warning class may have different ID values in different analyses.

To get a cs_warningclass_t given its ID, use csonar_warningclass_lookup().

Function csonar_warningclass_lookup
cs_result csonar_warningclass_lookup (
Get the cs_warningclass_t with the specified ID.
Parameters
class_id [in] The csuint32 identifying the warning class.
out [in] The cs_warningclass_t whose ID is class_id, if any.
Returns A cs_result:
Notes To get the ID of a cs_warningclass_t, use csonar_warningclass_id().
Function csonar_warningclass_lookup_by_name
cs_result csonar_warningclass_lookup_by_name (
Get the cs_warningclass_t with the specified name.
Parameters
class_name [in] The name of the desired warning class.
out [in] The cs_warningclass_t whose name if class_name, if any.
Returns A cs_result:
Function csonar_warningclass_always_discarded
cs_boolean csonar_warningclass_always_discarded (
Check: are WARNING_FILTER settings such that instances of the specified warning class will always be ignored?
Parameters
wc [in] The warning class.
Returns cs_true if all instances of wc are being discarded, cs_false otherwise.
Notes If you have defined a custom warning class C in a plug-in, you can use a test based on csonar_warningclass_always_discarded(C) to avoid unnecessary work in the case where C is ignored.

This is the complement of csonar_warningclass_allowed().

Function csonar_warningclass_allowed
cs_boolean csonar_warningclass_allowed (
Check: are WARNING_FILTER settings such that reported instances of the specified warning class will be submitted to the hub?
Parameters
wc [in] The warning class.
Returns cs_true if reported instances of wc will be submitted to the hub, cs_false otherwise.
Notes If you have defined a custom warning class C in a plug-in, you can use a test based on csonar_warningclass_allowed(C) to avoid unnecessary work in the case where C is ignored.

This is the complement of csonar_warningclass_always_discarded().

Function csonar_warningclass_name
cs_const_string csonar_warningclass_name (
Get the name of the specified warning class.
Parameters
wc [in] The warning class.
Returns The name of wc, as a cs_const_string.
Function csonar_report_warning
cs_result csonar_report_warning (
Issue a warning at a cs_pdg_vertex.
Parameters
v [in] The vertex where the warning occurs.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
problem [in] A very short explanation of why the warning has been issued.
report_flags [in] cs_report_flags that characterize the report.
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing v is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id so that you can use it with csonar_retract_warning().

This will create a warning consisting of a single event, and that event will be an end box.

Function csonar_report_path_warning
cs_result csonar_report_path_warning (
Report a warning with a path.
Parameters
warning_path [in] A pointer to the path associated with the warning, with each point on the path described by a cs_cfg_path_node_t node.
len [in] The number of cs_cfg_path_node_t nodes in warning_path.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing the first point in warning_path is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id so that you can use it with csonar_retract_warning().
Function csonar_report_step_path_warning
cs_result csonar_report_step_path_warning (
Report a warning with a step path.
Parameters
warning_path [in] A pointer to the path associated with the warning. Step visitor functions are supplied with paths leading from the entry point to the current point at each call to the transition function.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing the first point in warning_path is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id so that you can use it with csonar_retract_warning().

This will create a warning consisting of a single event, and that event will be an end box.

Function csonar_report_location_warning
cs_result csonar_report_location_warning (
Issue a warning at a source line.
Parameters
warning_file [in] The cs_sfid of the source file instance containing the warning.
warning_line [in] The line in warning_file where the warning occurs
wc [in] The warning class, which should have been created by csonar_create_warningclass().
prob [in] A very short explanation of why the warning has been issued.
report_flags [in] cs_report_flags that characterize the report.
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing warning_file is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id so that you can use it with csonar_retract_warning().

This will create a warning consisting of a single event, and that event will be an end box.

This function does not specify a procedure for the warning. If you wish to specify a procedure, use csonar_report_location_warning_in_pdg().

Function csonar_report_location_span_warning
cs_result csonar_report_location_span_warning (
Issue a warning with a code span location.
Parameters
warning_file [in] The cs_sfid of the source file instance containing the warning.
warning_start_line [in] The line in warning_file where the warning starts.
warning_end_line [in] The line in warning_file where the warning ends; equal to warning_start_line or 0 indicates a single-line warning.
start_col [in] The column of warning_start_line at which the warning starts.
end_col [in] The column of warning_end_line at which the warning ends.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
prob [in] A very short explanation of why the warning has been issued.
report_flags [in] cs_report_flags that characterize the report.
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing warning_file is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id so that you can use it with csonar_retract_warning().

This will create a warning consisting of a single event, and that event will be an end box.

This function does not specify a procedure for the warning. If you wish to specify a procedure, use csonar_report_location_span_warning_in_pdg().

Function csonar_report_location_warning_in_pdg
cs_result csonar_report_location_warning_in_pdg (
Issue a warning at a source line in a specified procedure.
Parameters
warning_file [in] The cs_sfid of the source file instance containing the warning.
warning_line [in] The line in warning_file where the warning occurs
proc [in] The procedure in which the warning occurs.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
prob [in] A very short explanation of why the warning has been issued.
report_flags [in] cs_report_flags that characterize the report.
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing warning_file is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id so that you can use it with csonar_retract_warning().

This will create a warning consisting of a single event, and that event will be an end box.

If you do not wish to specify a procedure, use csonar_report_location_warning().

Function csonar_report_location_span_warning_in_pdg
cs_result csonar_report_location_span_warning_in_pdg (
Issue a warning at a span in a specified procedure.
Parameters
warning_file [in] The cs_sfid of the source file instance containing the warning.
warning_start_line [in] The line in warning_file where the warning starts
warning_end_line [in] The line in warning_file where the warning ends; either equal to warning_start_line or 0 indicates a single-line warning.
start_col [in] The column of warning_start_line at which the warning starts.
end_col [in] The column of warning_end_line at which the warning ends.
proc [in] The procedure in which the warning occurs.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
prob [in] A very short explanation of why the warning has been issued.
report_flags [in] cs_report_flags that characterize the report.
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing warning_file is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id so that you can use it with csonar_retract_warning().

This will create a warning consisting of a single event, and that event will be an end box.

If you do not wish to specify a procedure, use csonar_report_location_warning().

Function csonar_report_locations_warning
cs_result csonar_report_locations_warning (
Issue a warning for a list of code locations.
Parameters
warning_locs [in] A pointer to a list of locations corresponding to the path, with each location described by a cs_locations_node_t node.
num_locs [in] The number of cs_locations_node_t nodes in warning_locs.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing the first location in warning_locs is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id by this function so that you can use it with csonar_retract_warning().

This function does not specify a procedure for the warning. If you wish to specify a procedure, use csonar_report_locations_warning_in_pdg().

Function csonar_report_locations_warning_in_pdg
cs_result csonar_report_locations_warning_in_pdg (
Issue a warning for a list of code locations in a specified procedure.
Parameters
proc [in] The procedure in which the warning occurs.
warning_locs [in] A pointer to a list of locations corresponding to the path, with each location described by a cs_locations_node_t node.
num_locs [in] The number of cs_locations_node_t nodes in warning_locs.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing the first location in warning_locs is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns A cs_result:
Notes If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id by this function so that you can use it with csonar_retract_warning().

If you do not wish to specify a procedure for the warning, use csonar_report_locations_warning().

Function csonar_report_file_warning
cs_result csonar_report_file_warning (
Issue a warning associated with a particular source file instance, as opposed to a specific source location or set of locations.
Parameters
warning_file [in] The cs_sfid of the source file instance associated with the warning.
wc [in] The warning class, which should have been created by csonar_create_warningclass().
prob [in] A very short explanation of why the warning has been issued.
report_flags [in] cs_report_flags that characterize the report.
ri [in] Retraction information for the warning instance being reported. All fields must be populated appropriately before this function is called. Can be NULL, in which case the warning instance will be automatically retracted iff the compilation unit containing warning_file is modified between incremental analyses.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns
Notes The warning description box will be displayed at line 1 of the file identified by warning_file.

If there are cases in which you will manually retract the warning instance, make sure you keep the value written to id by this function so that you can use it with csonar_retract_warning().

Function csonar_report_analysis_warning
cs_result csonar_report_analysis_warning (
Issue a warning with no association to a file or procedure.
Parameters
wc [in] The warning class, which should have been created by csonar_create_warningclass().
problem [in] A very short explanation of why the warning has been issued.
report_flags [in] cs_report_flags that characterize the report.
id [out] On success, the function will populate this with the cs_warning_id of the issued warning. Can be NULL, if you won't need this information.
Returns
Notes The warning description box will be displayed at line 1 of the file identified by warning_file.

Warnings reported via this method will always be retracted during an incremental build, since the warning is against the entire analysis.

Function csonar_retract_warning
cs_result csonar_retract_warning (
Manually retract a warning instance.
Parameters
id [in] The cs_warning_id corresponding to the warning instance to be retracted.
Returns A cs_result:
  • CS_ELEMENT_NOT_PRESENT if there is no warning instance corresponding to id in the current analysis or any of its incremental ancestors.
  • CS_SUCCESS on success.
Notes Call this function in a drop phase visitor to manually retract a warning instance. Support for calling this function from visitors in other analysis phases is experimental and may be removed in future versions.

The id value will have been recovered originally from the cs_warning_id value written by the function that reported the warning: one of
Function csonar_pdg_vertex_position
cs_result csonar_pdg_vertex_position (
Get the starting file instance and line of a cs_pdg_vertex.
Parameters
v [in] The cs_pdg_vertex whose position is desired.
vertex_file [out] The cs_sfid of the file instance in which the vertex occurs.
vertex_line [out] The lowest valued line number that the vertex occupies.
Returns A cs_result:
Notes Finds the file instance and line in that file instance containing v.
  • If v occurs in several lines of the file instance, chooses the lowest-numbered one.
  • If v occurs in several file instances, chooses one arbitrarily.
Function csonar_pdg_vertex_callee
cs_result csonar_pdg_vertex_callee (
Get the callee cs_pdg of a call site cs_pdg_vertex, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
Parameters
v [in] The call site cs_pdg_vertex for which to find the callee cs_pdg.
pdg [out] The cs_pdg for v's callee.
Returns A cs_result:
Time-Complexity O(n), where n is the number of call sites in the caller function.
Notes 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 cs_pdg_vertex of kind cs_vertex_kind_call_site) will always have exactly one callee.

An indirect call site (a cs_pdg_vertex of kind cs_vertex_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 a csonar_pdg_callees_iter iterator to iterate over all callees of a cs_pdg_vertex, taking into account translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.

Function csonar_pdg_vertex_callee_no_reroute
cs_result csonar_pdg_vertex_callee_no_reroute (
Get the callee cs_pdg of a call site cs_pdg_vertex, ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
Parameters
v [in] The call site cs_pdg_vertex for which to find the callee cs_pdg.
pdg [out] The cs_pdg for v's callee.
Returns A cs_result:
Time-Complexity O(n), where n is the number of call sites in the caller function. A direct call site (that is, a cs_pdg_vertex of kind cs_vertex_kind_call_site) will always have exactly one callee.
Notes An indirect call site (a cs_pdg_vertex of kind cs_vertex_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 a csonar_pdg_callees_no_reroute_iter iterator to iterate over all callees of a cs_pdg_vertex, ignoring translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.

Function csonar_pdg_vertex_callees_iter_first
cs_result csonar_pdg_vertex_callees_iter_first (
Open a cs_pdg_callees_iter iterator for traversing the callees from a specified point (cs_pdg_vertex), taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable, and retrieve the first callee cs_pdg from the iterator.
Parameters
v [in] The cs_pdg_vertex of interest.
callee_pdg [out] The first cs_pdg retrieved from itr.
itr [inout] A csonar_pdg_callees_iter opened to traverse the callees of v, taking into account any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
Returns A cs_result:
Notes This function opens itr, which is required by csonar_pdg_vertex_callees_iter_next(). Use csonar_pdg_vertex_callees_iter_close() to close itr.

Indirect call resolution takes place in the pointer analysis phase, so results for indirect call sites will be best if traversal takes place in the bottom-up phase or later. For both direct and indirect call sites, traversal will fail if it is attempted before the beginning of the serial depth-first phase.

Function csonar_pdg_vertex_callees_iter_next
cs_result csonar_pdg_vertex_callees_iter_next (
Advance the provided csonar_pdg_callees_iter iterator and retrieve the next element.
Parameters
callee_pdg [out] The next cs_pdg retrieved from itr.
itr [inout] The iterator from which to retrieve callee_pdg.
Returns A cs_result:
Notes Use csonar_pdg_vertex_callees_iter_close() to close itr when iteration is complete.
Function csonar_pdg_vertex_callees_iter_close
cs_result csonar_pdg_vertex_callees_iter_close (
Close a csonar_pdg_callees_iter iterator.
Parameters
itr [inout] The iterator from to close.
Returns A cs_result:
Function csonar_pdg_vertex_callees_no_reroute_iter_first
cs_result csonar_pdg_vertex_callees_no_reroute_iter_first (
Open a csonar_pdg_callees_no_reroute_iter iterator for traversing the callees from a specified point (cs_pdg_vertex), ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable, and retrieve the first callee cs_pdg from the iterator.
Parameters
v [in] The cs_pdg_vertex of interest.
callee_pdg [out] The first cs_pdg retrieved from itr.
itr [inout] A csonar_pdg_callees_no_reroute_iter opened to traverse the callees of v, ignoring any translations incurred by csonar_replace_*() calls and the FUNCTION_MAP configuration file variable.
Returns A cs_result:
Notes This function opens itr, which is required by csonar_pdg_vertex_callees_no_reroute_iter_next(). Use csonar_pdg_vertex_callees_no_reroute_iter_close() to close itr.

Indirect call resolution takes place in the pointer analysis phase, so results for indirect call sites will be best if traversal takes place in the bottom-up phase or later. For both direct and indirect call sites, traversal will fail if it is attempted before the beginning of the serial depth-first phase.

Function csonar_pdg_vertex_callees_no_reroute_iter_next
cs_result csonar_pdg_vertex_callees_no_reroute_iter_next (
Advance the provided csonar_pdg_callees_no_reroute_iter iterator and retrieve the next element.
Parameters
callee_pdg [out] The next cs_pdg retrieved from itr.
itr [inout] The iterator from which to retrieve callee_pdg.
Returns A cs_result:
Notes Use csonar_pdg_vertex_callees_no_reroute_iter_close() to close itr when iteration is complete.
Function csonar_pdg_vertex_callees_no_reroute_iter_close
cs_result csonar_pdg_vertex_callees_no_reroute_iter_close (
Close a csonar_pdg_callees_no_reroute_iter iterator.
Parameters
itr [inout] The iterator from to close.
Returns A cs_result:
Function csonar_pdg_callers_iter_first
cs_result csonar_pdg_callers_iter_first (
Open a cs_pdg_callers_iter iterator for traversing the call sites to a specified procedure (cs_pdg), and retrieve the first call site (cs_pdg_vertex) from the iterator.
Parameters
pdg [in] The cs_pdg for which to retrieve calling site.
calling_site [out] The cs_pdg_vertex corresponding to the first call site to pdg.
itr [out] A cs_pdg_callers_iter iterator opened to traverse the call sites to pdg.
Returns A cs_result:
Notes For a fixed project build and cs_pdg, the iteration order is deterministic but does not correspond to the execution order or source file location of the call sites.

This function opens itr, which is required by csonar_pdg_callers_iter_next(). Use csonar_pdg_callers_iter_close() to close itr.

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.

Function csonar_pdg_callers_iter_next
cs_result csonar_pdg_callers_iter_next (
Advance the provided cs_pdg_callers_iter iterator and retrieve the next element.
Parameters
calling_site [out] The cs_pdg_vertex corresponding to the next call site retrieved from itr.
itr [out] The cs_pdg_callers_iter iterator from which to retrieve the next call site.
Returns A cs_result:
Notes Use csonar_pdg_callers_iter_close() to close itr when traversal is finished.
Function csonar_pdg_callers_iter_close
cs_result csonar_pdg_callers_iter_close (
Close a cs_pdg_callers_iter iterator.
Parameters
itr [out] The cs_pdg_callers_iter iterator to close.
Returns CS_SUCCESS on successful close.
Function csonar_step_path_to_list
cs_result csonar_step_path_to_list (
Retrieve the list of cs_cfg_path_node_t nodes corresponding to a cs_step_path_t.
Parameters
rpath [in] The cs_step_path_t for which to obtain the list version.
path_list [out] A user-allocated buffer to be populated with the list of cs_cfg_path_node_t nodes.
capacity_bytes [in] The capacity of path_list, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire list version of rpath.
Returns A cs_result:
  • CS_TRUNCATED if path_list is not large enough to hold the entire list version of rpath,
  • CS_SUCCESS otherwise.
Notes Retrieve the list of cs_cfg_path_node_t nodes corresponding to rpath and write it to path_list. If path_list is not large enough, the list is truncated to fit into path_list.
Function csonar_step_path_to_string
cs_result csonar_step_path_to_string (
Get a textual representation of a cs_step_path_t.
Parameters
rpath [in] The cs_step_path_t for which to obtain the textual representation.
out_string [out] A user-allocated buffer to be populated with the textual representation.
capacity_bytes [in] The capacity of out_string, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire string.
Returns A cs_result:
Notes Retrieve the textual representation of rpath and write it to out_string. If out_string is not large enough, the representation is truncated to fit into out_string.
Function csonar_step_path_copy
cs_step_path_t csonar_step_path_copy (
Copy a step path (cs_step_path_t).
Parameters
rpath [in] The cs_step_path_t to copy.
Returns A copy of rpath.
Notes The returned object must be destroyed using csonar_step_path_destroy() to avoid leaks.
Function csonar_step_path_destroy
void csonar_step_path_destroy (
Destroy a step path (cs_step_path_t) that was created by csonar_step_path_copy().
Parameters
rpath [inout] The cs_step_path_t to destroy.
Returns void
Function csonar_pdg_vertex_to_string
cs_result csonar_pdg_vertex_to_string (
Get a textual representation of a cs_pdg_vertex.
Parameters
v [in] The cs_pdg_vertex for which to obtain the textual representation.
out_string [out] A user-allocated buffer to be populated with the textual representation.
capacity_bytes [in] The capacity of out_string, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire string.
Returns A cs_result:
Notes Retrieve the textual representation of v and write it to out_string. If out_string is not large enough, the representation is truncated to fit into out_string.
Function csonar_access_path_operator_name
cs_const_string csonar_access_path_operator_name (
Get the name of a cs_access_path_operator.
Parameters
op [in] The cs_access_path_operator of interest.
Returns The name of op.
Function csonar_xform_expr_mode_name
cs_const_string csonar_xform_expr_mode_name (
Get the name of a cs_xform_expr_mode.
Parameters
m [in] The cs_xform_expr_mode of interest.
Returns The name of m, as a cs_const_string.
Function csonar_xform_query_result_name
cs_const_string csonar_xform_query_result_name (
Get the name of a cs_xform_query_result.
Parameters
r [in] The cs_xform_query_result of interest.
Returns The name of r.
Function csonar_xform_expr_validate
cs_result csonar_xform_expr_validate (
Check whether a cs_xform_expr is well-formed.
Parameters
expr [in] The expression to validate
Returns A cs_result:
Function csonar_xform_expr_to_string
cs_result csonar_xform_expr_to_string (
Get a textual representation of a cs_xform_expr.
Parameters
expr [in] The cs_xform_expr for which to obtain the textual representation.
out_string [out] A user-allocated buffer to be populated with the textual representation.
capacity_bytes [in] The capacity of out_string, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire string.
Returns A cs_result:
Notes Retrieve the textual representation of expr and write it to out_string. If out_string is not large enough, the representation is truncated to fit into out_string.
Function csonar_xform_operator_name
cs_const_string csonar_xform_operator_name (
Get the name of a cs_xform_operator.
Parameters
op [in] The cs_xform_operator of interest.
Returns The name of op.
Function csonar_xform_query
cs_result csonar_xform_query (
Allows users to issue queries with respect to a program state transformation.
Parameters
s [in] The transform for which the query is taking place.
lhs [in] The left hand side of the query expression.
op [in] The operator in the query expression.
rhs [in] The right hand side of the query expression.
out_result [out] The answer to the query. Only set when returning CS_SUCCESS.
Returns A cs_result:
Function csonar_xform_query_bounds
cs_result csonar_xform_query_bounds (
Get bounds on an expression.
Parameters
s [in] the transform to query for bounds.
expr [in] The query expression.
lb [out] the lower bound on expr.
lb_suspect [out] the lower bound is suspect because it is merely implied by a control flow decision that may or may not be feasible if more program context is taken into account. See csxqr_redundant_suspect for more details on "suspect".
ub [out] the upper bound on expr.
ub_suspect [out] the upper bound is suspect because it is merely implied by a control flow decision that may or may not be feasible if more program context is taken into account. See csxqr_redundant_suspect for more details on "suspect".
Returns A cs_result:
Function csonar_metricclass_always_discarded
cs_boolean csonar_metricclass_always_discarded (
Check: are METRIC_FILTER settings such that instances of the specified warning class will always be ignored?
Parameters
wc [in] The metric class.
Returns cs_true if all instances of mc are being discarded, cs_false otherwise.
Notes If you have defined a custom warning class C in a plug-in, you can use a test based on csonar_metricclass_always_discarded(C) to avoid unnecessary work in the case where C is ignored.

This is the complement of csonar_metricclass_allowed().

Function csonar_metricclass_allowed
cs_boolean csonar_metricclass_allowed (
Check: are METRIC_FILTER settings such that reported instances of the specified metric class will be submitted to the hub?
Parameters
mc [in] The metric class.
Returns cs_true if reported instances of mc will be submitted to the hub, cs_false otherwise.
Notes If you have defined a custom warning class C in a plug-in, you can use a test based on csonar_metricclass_allowed(C) to avoid unnecessary work in the case where C is ignored.

This is the complement of csonar_metricclass_always_discarded().

Function csonar_report_metric_analysis
cs_result csonar_report_metric_analysis (
Report an analysis granularity metric value to the hub.
Parameters
mt [in] A metric class object previously created with csonar_metric_create_class_analysis() or retrieved with csonar_metric_get_class().
val [in] The value to report.
Returns A cs_result:
Notes You do not need to call this method if mt was created with the csmetric_flags_auto flag. In that case, CodeSonar will automatically report the values calculated using the cs_metric_calc_analysis_fn_t provided to csonar_metric_create_class_analysis() when mt was created.
Function csonar_report_metric_compunit
cs_result csonar_report_metric_compunit (
Report a compilation unit granularity metric value to the hub.
Parameters
mt [in] A metric class object previously created with csonar_metric_create_class_compunit() or retrieved with csonar_metric_get_class().
val [in] The value to report.
uid [in] The cs_uid of the compilation unit the metric is associated with.
Returns A cs_result:
Notes You do not need to call this method if mt was created with the csmetric_flags_auto flag. In that case, CodeSonar will automatically report the values calculated using the cs_metric_calc_compunit_fn_t provided to csonar_metric_create_class_compunit() when mt was created.
Function csonar_report_metric_file
cs_result csonar_report_metric_file (
Report a file granularity metric value to the hub.
Parameters
mt [in] A metric class object previously created with csonar_metric_create_class_file() or retrieved with csonar_metric_get_class().
val [in] The value to report.
sf [in] The file with which val is associated.
Returns A cs_result:
Notes You do not need to call this method if mt was created with the csmetric_flags_auto flag. In that case, CodeSonar will automatically report the values calculated using the cs_metric_calc_file_fn_t provided to csonar_metric_create_class_file() when mt was created.
Function csonar_report_metric_procedure
cs_result csonar_report_metric_procedure (
Report a procedure granularity metric value.
Parameters
mt [in] A metric class object previously created with csonar_metric_create_class_procedure() or retrieved with csonar_metric_get_class().
val [in] The value to report.
pdg [in] The procedure to report against.
Returns A cs_result:
Notes You do not need to call this method if mt was created with the csmetric_flags_auto flag. In that case, CodeSonar will automatically report the values calculated using the cs_metric_calc_procedure_fn_t provided to csonar_metric_create_class_procedure() when mt was created.
Function csonar_metric_get_granularity
cs_metric_granularity csonar_metric_get_granularity (
Get the granularity of a cs_metricclass_t.
Parameters
mc [in] The cs_metricclass_t.
Returns The granularity of mc, as a cs_metric_granularity.
Function csonar_metric_tag
cs_const_string csonar_metric_tag (
Get the tag (short string identifier) of a cs_metricclass_t.
Parameters
mc [in] The cs_metricclass_t.
Returns The tag (short name) of mc, as a cs_const_string.
Function csonar_metric_description
cs_const_string csonar_metric_description (
Get the description of a cs_metricclass_t.
Parameters
mc [in] The cs_metricclass_t.
Returns The description of mc, as a cs_const_string.
Function csonar_metric_hash
cs_hash_t csonar_metric_hash (
Hash function for cs_metricclass_t.
Parameters
mc [in] A cs_metricclass_t to hash.
Returns A hash of mc.
Function csonar_metric_compare
int csonar_metric_compare (
Compare two cs_metricclass_t values.
Parameters
mc1 [in] First argument to comparison.
mc2 [in] Second argument to comparison.
Returns
  • -1 if mc1 is considered less than mc2.
  • 0 if mc1 is considered equal to mc2.
  • 1 if mc1 is considered greater than mc2.
Notes This function is provided so cs_metricclass_t values can be stored in ordered containers. It is not based on any user-perceivable order of cs_metricclass_t.
Function csonar_metric_equal
cs_boolean csonar_metric_equal (
Compare two cs_metricclass_t values for equality.
Parameters
mc1 [in] First argument to equality test.
mc2 [in] Second argument to equality test.
Returns cs_true if mc1 and mc2 are the same cs_metricclass_t; cs_false if not.
Function csonar_metric_getvalue_analysis
cs_result csonar_metric_getvalue_analysis (
Get the value of an analysis granularity metric.
Parameters
mt [in] A metric class object created with csonar_metric_create_class_analysis() or retrieved with csonar_metric_get_class().
mval [out] The metric value for the current analysis.
Returns A cs_result:
Function csonar_metric_getvalue_compunit
cs_result csonar_metric_getvalue_compunit (
Get the value of a compilation unit granularity metric.
Parameters
mt [in] A metric class object created with csonar_metric_create_class_compunit() or retrieved with csonar_metric_get_class().
uid [in] The cs_uid of the compilation unit.
mval [out] The metric value for the compilation unit.
Returns A cs_result:
Function csonar_metric_getvalue_file
cs_result csonar_metric_getvalue_file (
Get the value of a file granularity metric.
Parameters
mt [in] A metric class object created with csonar_metric_create_class_file() or retrieved with csonar_metric_get_class().
sf [in] The cs_sf of the file. (This can be derived from any instance; mval will always be the value computed for the representative instance.)
mval [out] The metric value for the representative instance of the file.
Returns A cs_result:
Function csonar_metric_getvalue_procedure
cs_result csonar_metric_getvalue_procedure (
Get the value of a procedure granularity metric.
Parameters
mt [in] A metric class object created with csonar_metric_create_class_procedure() or retrieved with csonar_metric_get_class().
pdg [in] The cs_pdg of the procedure. Must have kind cs_pdg_kind_user_defined.
mval [out] The metric value for the specified procedure.
Returns A cs_result:
Function csonar_metric_create_class_analysis
cs_result csonar_metric_create_class_analysis (
Create a new analysis granularity metric class.
Parameters
metrictag [in] Tag (short string identifier) that will, in combination with granularity, uniquely identify this metric class. The tag must:
  • Start with characters matching [a-zA-Z]
  • Only contain characters matching [a-zA-Z][0-9] _-
  • Have length <= 15 characters
desc [in] A human-readable description of the metric. The description must:
  • Only contain characters matching [a-zA-Z][0-9] _-
  • Have length <= 35 characters
fn [in] The calculation function that computes the metric's value.
flags [in] The cs_metricclass_flags describing the new metric.
ctx [in] Context for computing the metric. This will be passed to the calculation function whenever it is called. Can be NULL if no such information is required.
metricclass [out] The newly created metric class object.
Returns A cs_result:
Notes This procedure should be called by setup visitors only and cannot be called by other visitors.
Function csonar_metric_create_class_compunit
cs_result csonar_metric_create_class_compunit (
Create a new compilation unit granularity metric class.
Parameters
metrictag [in] Short tag that, along with granularity, will uniquely identify this metric class. The tag must:
  • Start with characters matching [a-zA-Z]
  • Only contain characters matching [a-zA-Z][0-9] _-
  • Have length <= 15 characters
desc [in] A human-readable description of the metric. The description must:
  • Only contain characters matching [a-zA-Z][0-9] _-
  • Have length <= 35 characters
fn [in] The calculation function that computes the metric's value.
flags [in] The cs_metricclass_flags describing the new metric.
ctx [in] Context for computing the metric. This will be passed to the calculation function whenever it is called. Can be NULL if no such information is required.
metricclass [out] The newly created metric class object.
Returns A cs_result:
Notes This procedure should be called by setup visitors only and cannot be called by other visitors.
Function csonar_metric_create_class_file
cs_result csonar_metric_create_class_file (
Create a new file granularity metric class.
Parameters
metrictag [in] Short tag that, along with granularity, will uniquely identify this metric class. The tag must:
  • Start with characters matching [a-zA-Z]
  • Only contain characters matching [a-zA-Z][0-9] _-
  • Have length <= 15 characters
desc [in] A human-readable description of the metric. The description must:
  • Only contain characters matching [a-zA-Z][0-9] _-
  • Have length <= 35 characters
fn [in] The calculation function that computes the metric's value.
flags [in] The cs_metricclass_flags describing the new metric.
ctx [in] Context for computing the metric. This will be passed to the calculation function whenever it is called. Can be NULL if no such information is required.
metricclass [out] The newly created metric class object.
Returns A cs_result:
Notes This procedure should be called by setup visitors only and cannot be called by other visitors.
Function csonar_metric_create_class_procedure
cs_result csonar_metric_create_class_procedure (
Create a new procedure granularity metric class.
Parameters
metrictag [in] Short tag that, along with granularity, will uniquely identify this metric class. The tag must:
  • Start with characters matching [a-zA-Z]
  • Only contain characters matching [a-zA-Z][0-9] _-
  • Have length <= 15 characters
desc [in] A human-readable description of the metric. The description must:
  • Only contain characters matching [a-zA-Z][0-9] _-
  • Have length <= 35 characters
fn [in] The calculation function that computes the metric's value.
flags [in] The cs_metricclass_flags describing the new metric.
ctx [in] Context for computing the metric. This will be passed to the calculation function whenever it is called. Can be NULL if no such information is required.
metricclass [out] The metric class object.
Returns A cs_result:
Notes This procedure should be called by setup visitors only and cannot be called by other visitors.
Function csonar_metric_get_class
cs_result csonar_metric_get_class (
Get the metric class object with the specified tag and granularity.
Parameters
metrictag [in] Metric tag (short string identifier).
gran [in] Metric granularity.
metricclass [out] The retrieved metric class, as a cs_metricclass_t.
Returns A cs_result:
Function csonar_metric_class_iter_first
cs_result csonar_metric_class_iter_first (
Open a cs_metric_class_iterator for traversing the metric classes with the specified granularity, and retrieve the first cs_metricclass_t from the iterator.
Parameters
gran [in] The granularity of interest. Set to csmetric_invalid to iterate over all metric classes of all granularities.
metricclass [out] The first metric class object retrieved from itr.
itr [in] A cs_metric_class_iterator opened to traverse the metric classes with granularity gran.
Returns A cs_result:
Function csonar_metric_class_iter_next
cs_result csonar_metric_class_iter_next (
Advance the provided cs_metric_class_iterator and retrieve the next element.
Parameters
metricclass [out] The next metric class retrieved from itr.
itr [inout] The iterator from which to retrieve metricclass.
Returns A cs_result:
Function csonar_metric_class_iter_close
cs_result csonar_metric_class_iter_close (
Close a metric class iterator.
Parameters
itr [in] The cs_metric_class_iterator to close.
Returns CS_SUCCESS on successful close.
Function csonar_metric_retract_procedure
cs_result csonar_metric_retract_procedure (
Retract a metric value for the given class/procedure combination.
Parameters
metricclass [in] The metric class for which to retract the value. Must have procedure granularity.
pdg [in] The cs_pdg specifying which procedure to retract the metric value for.
Returns A cs_result:
Notes In typical usage, csonar_metric_retract_procedure() is called during the drop traversal (that is, by a visitor added with one of the csonar_add_*_drop_visitor() functions).
Function csonar_metric_retract_file
cs_result csonar_metric_retract_file (
Retract a metric value for the given class/source file combination.
Parameters
metricclass [in] The metric class for which to retract the value. Must have file granularity.
sf [in] The cs_sf specifying which source file to retract the metric value for.
Returns A cs_result:
Notes In typical usage, csonar_metric_retract_file() is called during the drop traversal (that is, by a visitor added with one of the csonar_add_*_drop_visitor() functions).
Function csonar_metric_retract_compunit
cs_result csonar_metric_retract_compunit (
Retract a metric value for the given class/compilation unit combination.
Parameters
metricclass [in] The metric class for which to retract the value. Must have compilation unit granularity.
uid [in] The cs_uid specifying which compilation unit to retract the metric value for.
Returns A cs_result:
Notes In typical usage, csonar_metric_retract_compunit() is called during the drop traversal (that is, by a visitor added with one of the csonar_add_*_drop_visitor() functions).
Function csonar_metric_flags
cs_metricclass_flags csonar_metric_flags (
Retrieve the flags for a cs_metricclass_t.
Parameters
metricclass [in] The cs_metricclass_t to retrieve the flags from.
Returns The cs_metricclass_flags value for metricclass.
Function csonar_file_is_system_include
cs_result csonar_file_is_system_include (
Check whether the specified file is located in a system directory.
Parameters
f [in] The cs_sfid for the file to be checked.
res [out] Set to cs_true if f is located in a system directory; cs_false otherwise.
Returns CS_SUCCESS on success.
Notes A file is considered to be located in a system directory if and only if its path matches a SYSTEM_INCLUDE_PATHS rule.

This function may clobber or free the buffer returned by many cs_*_string() functions.

Function csonar_binary_backend_option
cs_result csonar_binary_backend_option (
[CodeSonar for Binaries only] Get the value associated with the key in the BINARY_BACKEND_OPTIONS configuration file setting.
Parameters
inkey [in] The key whose associated value is to be obtained, as a cs_const_string
val [out] Set to point to a cs_const_string containing the associated value.
Returns A cs_result:
Function csonar_warning_significance_name
cs_const_string csonar_warning_significance_name (
Get the name of a csonar_warning_significance.
Parameters
s [in] The csonar_warning_significance whose name is required.
Returns The name of s.
Function csonar_warning_significance_lookup
cs_result csonar_warning_significance_lookup (
Get the csonar_warning_significance with the specified name.
Parameters
sig_name [in] The name to look up.
sig [out] The csonar_warning_significance whose name is sig_name.
Returns A cs_result:
Function csonar_pdg_vertex_enum_used
cs_result csonar_pdg_vertex_enum_used (
Get the list of used symbols (cs_abs_loc) for a point (cs_pdg_vertex), computing the list on-demand.
Parameters
pdgv [in] The cs_pdg_vertex for which the list is to be returned.
abslocs [in] A user-allocated buffer to be populated the list of cs_abs_loc values.
capacity_bytes [in] The capacity of abslocs, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire list.
Returns A cs_result:
Notes Retrieve the used cs_abs_loc for the vertex and write them to abslocs. If abslocs is not large enough, the list is truncated to fit into abslocs. The list is generated on-demand and will be recomputed if the same cs_pdg_vertex is presented again.
Function csonar_pdg_vertex_enum_killed
cs_result csonar_pdg_vertex_enum_killed (
Get the list of killed symbols (cs_abs_loc) for a point (cs_pdg_vertex), computing the list on-demand.
Parameters
pdgv [in] The cs_pdg_vertex for which the list is to be returned.
abslocs [in] A user-allocated buffer to be populated the list of cs_abs_loc values.
capacity_bytes [in] The capacity of abslocs, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire list.
Returns A cs_result:
Notes Retrieve the killed cs_abs_loc for the vertex and write them to abslocs. If abslocs is not large enough, the list is truncated to fit into abslocs. The list is generated on-demand and will be recomputed if the same cs_pdg_vertex is presented again.
Function csonar_register_rpc_handler
cs_result csonar_register_rpc_handler (
Register a remote procedure call (RPC) handler that will respond to request from the CodeSonar hub.
Parameters
message_name [in] The message name to respond to. Registering a handler for message_name "foo" means it will respond to requests on the URL hub_host:port/command/custom/foo/.
handler [in] The callback function to execute when a message is received.
ctx [in] Any context information that will be required by the visitor. Can be NULL if no such information is required.
Returns
Notes The handler receives a string which contains the RPC message. This string is a stringified JSON object of the HTTP GET variables. The onus is on the cs_rpc_handler_fn_t to perform any JSON decoding from the message string.
Function csonar_rpc_response_alloc
cs_string csonar_rpc_response_alloc (
Allocates memory for the response that is sent back to the hub after processing an RPC request.
Parameters
s [in] size of the result
Function csonar_pdg_vertex_enum_referenced
cs_result csonar_pdg_vertex_enum_referenced (
Get the list of referenced symbols (cs_abs_loc) for a point (cs_pdg_vertex), computing the list on-demand.
Parameters
pdgv [in] The cs_pdg_vertex for which the list is to be returned.
abslocs [in] A user-allocated buffer to be populated the list of cs_abs_loc values.
capacity_bytes [in] The capacity of abslocs, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire list.
Returns A cs_result:
Notes Retrieve the referenced cs_abs_loc for the vertex and write them to abslocs. If abslocs is not large enough, the list is truncated to fit into abslocs. The list is generated on-demand and will be recomputed if the same cs_pdg_vertex is presented again.
Function csonar_sf_get_pdgs_for_procedure
cs_result csonar_sf_get_pdgs_for_procedure (
Get all instances (cs_pdg) of a procedure (specified by its source file, line, and friendly-name hash).
Parameters
sf [in] The source file containing the procedure of interest.
line_num [in] The source file line number on which the procedure definition starts.
friendly_name_hash [in] The hash (cs_string_hash()) of the procedure friendly name (cs_pdg_friendly_name()). Set to NULL to retrieve all procedures whose definitions begin at line_num in sf.
closest_prior [in] Specifies how the function should behave if there are no cs_pdg matching friendly_name_hash on line_num of sf.
  • cs_true: finds the highest line L<=line_num in sf such that the definition of at least one cs_pdg matching friendly_name_hash begins on L, and gets the matches from that line. If there is no such line L, the result list is empty.
  • cs_false : the result list is empty.
  • If there is at least one suitable cs_pdg on line_num of sf, this parameter has no effect.
pdg_list [in] A user-allocated array to be populated with the procedures (cs_pdg) found at the line_num in sf.
capacity_bytes [in] The capacity of pdg_list, measured in bytes.
bytes_needed [out] The number of bytes required to store the entire list.
Returns A cs_result:
Function csonar_pdg_reachable
cs_result csonar_pdg_reachable (
Check: is a cs_pdg reachable from the reachability roots specified with configuration file parameter REACHABILITY_ROOTS?
Parameters
pdg [in] The cs_pdg of interest.
out_result [out] cs_true if pdg is reachable from the reachability roots, cs_false if it is not reachable. Undefined if the return value is anything but CS_SUCCESS.
Returns A cs_result:
 

To report problems with this documentation, please visit https://support.codesecure.com/.