SDG: cs_sdg.h

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.

If you access the manual through the hub's Web GUI, the functionality will not be suppressed because the hub is a web server.
Alternatively, your browser may allow you to explicitly disable the security setting that suppresses functionality. See the CodeSonar FAQ for more information.

CodeSonar^® 9.0p0 Hot Tips

CONFIDENTIAL

CodeSecure Inc

SDG: cs_sdg.h

Defines a set of SDG operations for CodeSonar.

Links
Defines
Types
Functions
Function Descriptions

Defines

#define CS_SDG_H

Types

typedef cs_filter

Definition	typedef const struct cs_filter_struct * cs_filter
Notes	Specifies how predecessor and sucessor queries traverse a dependence graph.

enum cs_filter_pdg_vertex_directive

Definition

typedef enum {

cs_filter_pdg_vertex_directive_show ,	Include: conditional; Continue: no. The vertex will be included if and only if the traversal filter maps the kind of the containing PDG to cs_filter_pdg_directive_show.
cs_filter_pdg_vertex_directive_skip ,	Include: conditional; Continue: yes. The vertex will be included if and only if both of the following are true. The vertex is adjacent to an opaque PDG (one whose kind is mapped to cs_filter_pdg_directive_opaque in the traversal filter). The kind of the vertex's containing PDG is mapped to cs_filter_pdg_directive_show in the traversal filter. Adjacency is defined as follows. For a predecessor query, a vertex is considered to be adjacent to a PDG if it has an interprocedural predecessor vertex in that PDG. For a successor query, a vertex is considered to be adjacent to a PDG if it has an interprocedural successor vertex in that PDG.
cs_filter_pdg_vertex_directive_stop ,	Include: no; Continue: no.
cs_filter_pdg_vertex_directive_count

} cs_filter_pdg_vertex_directive

Notes

Enumerated type for the vertex_mode array contained within the cs_filter type.

In traversals governed by a filter, the behavior at a PDG_VERTEX v in PDG p depends on two directives:

the cs_filter_pdg_vertex_directive that the filter specifies for v's vertex kind.
the cs_filter_pdg_directive that the filter specifies for p's PDG kind.

enum cs_filter_pdg_directive

Definition

typedef enum {

cs_filter_pdg_directive_show ,	Include vertex: conditional; Continue: conditional. The vertex will be included if and only if one of the following is true. The traversal filter maps the vertex's kind to cs_filter_pdg_vertex_directive_show, or The traversal filter maps the vertex's kind to cs_filter_pdg_vertex_directive_skip AND the vertex is adjacent to an opaque PDG. The traversal will continue if and only if the traversal filter maps the vertex's kind to cs_filter_pdg_vertex_directive_skip.
cs_filter_pdg_directive_skip ,	Include vertex: no; Continue: yes.
cs_filter_pdg_directive_stop ,	Include vertex: no; Continue: no.
cs_filter_pdg_directive_opaque ,	Include vertex: no; Continue: yes. Vertices inside opaque PDGs are never included in results. However, a vertex that is both adjacent to an opaque PDG and contained in a PDG whose kind is mapped to cs_filter_pdg_directive_show will be included if the vertex kind is mapped to cs_filter_pdg_vertex_directive_skip or cs_filter_pdg_vertex_directive_show (as opposed to only if its kind is mapped to cs_filter_pdg_vertex_directive_show).
cs_filter_pdg_directive_count

} cs_filter_pdg_directive

Notes

Enumerated type for the pdg_mode array contained within the cs_filter_struct type.

In traversals governed by a filter, the behavior at a PDG_VERTEX v in PDG p depends on two factors:

the cs_filter_pdg_vertex_directive that the filter specifies for v's vertex kind, and
the cs_filter_pdg_directive that the filter specifies for p's PDG kind.

On Separate Pages

struct cs_sdg_pdgs_iter

struct cs_pdglist_pair

struct cs_filter_struct

Functions

cs_result	cs_sdg_pdgs ( cs_pdg pdg_list[], cs_size_t capacity_bytes, cs_size_t * bytes_needed ) Retrieve a list of the cs_pdg objects defined in the SDG of the current project.
cs_result	cs_sdg_pdgs_iter_first ( cs_pdg * pdg, cs_sdg_pdgs_iter * itr ) Get the first cs_pdg from the SDG of the current project.
cs_result	cs_sdg_pdgs_iter_next ( cs_pdg * pdg, cs_sdg_pdgs_iter * itr ) Get the next cs_pdg from itr.
cs_result	cs_sdg_pdgs_iter_close ( cs_sdg_pdgs_iter * itr ) Close a cs_sdg_pdgs_iter .
cs_result	cs_filter_pdg_directive_name ( cs_filter_pdg_directive directive, cs_const_string * out_string ) Retrieve the name of a cs_filter_pdg_directive.
cs_result	cs_filter_pdg_vertex_directive_name ( cs_filter_pdg_vertex_directive directive, cs_const_string * out_string ) Retrieve the name of a cs_filter_pdg_vertex_directive.
cs_result	cs_sdg_uids ( cs_uid uid_list[], cs_size_t capacity_bytes, cs_size_t * bytes_needed ) Retrieve a list of the compilation units (cs_uid) contributing to the SDG of the current project.
cs_result	cs_sdg_uids_iter_first ( cs_uid * uid, cs_sdg_uids_iter * itr ) Get the first compilation unit cs_uid from the SDG of the current project.
cs_result	cs_sdg_uids_iter_next ( cs_uid * uid, cs_sdg_uids_iter * itr ) Get the next cs_uid from itr.
cs_result	cs_sdg_uids_iter_close ( cs_sdg_uids_iter * itr ) Close a cs_sdg_uids_iter.
cs_result	cs_sdg_sfs_iter_first ( cs_sf * sf, cs_sdg_sfs_iter * itr ) Get the first source file cs_sf from the SDG of the current project.
cs_result	cs_sdg_sfs_iter_next ( cs_sf * sf, cs_sdg_sfs_iter * itr ) Get the next cs_sf from itr.
cs_result	cs_sdg_sfs_iter_close ( cs_sdg_sfs_iter * itr ) Close a cs_sdg_sfs_iter.
cs_result	cs_sdg_ignored_uids ( cs_uid uid_list[], cs_size_t capacity_bytes, cs_size_t * bytes_needed ) Retrieve a list of the compilation units (cs_uid) that are dropped from the build.
cs_result	cs_sdg_compilation_units ( cs_file_path file_path_list[], cs_size_t capacity_bytes, cs_size_t * bytes_needed, cs_size_t * result_cardinality ) Retrieve a list of file-paths of the compilation units contributing to the SDG of the current project.
cs_result	cs_sdg_retrieve_pdg ( csint64 pid, cs_pdg * out_pdg ) Retrieve the cs_pdg corresponding to a given procedure ID.
cs_result	cs_sdg_error_count ( cs_boolean including_ignored, cs_size_t * out_i ) Retrieve the number of errors encountered in compiling the files in the SDG.
cs_result	cs_sdg_warning_count ( cs_boolean including_ignored, cs_size_t * out_i ) Retrieve the number of warnings encountered in compiling the files in the SDG.
cs_boolean	cs_sdg_is_loaded ( ) Check: is a project currently loaded?
cs_boolean	cs_sdg_is_read_only ( ) Check: is the current project read-only?
cs_result	cs_sdg_file_is_newer_than_build ( cs_const_file_path file, cs_boolean * out_b ) Determine if a file is newer than the rest of the project.
cs_result	cs_sdg_retain_unnormalized_c_ast ( cs_boolean * out_b ) Determine whether any of cs_pdg_vertex_ast(), cs_abs_loc_ast(), cs_abs_loc_type(), cs_pdg_ast() or cs_file_ast() can successfully return a cs_ast whose cs_ast_family is csaf_c_unnormalized.
cs_result	cs_project_name ( cs_string prj_name, cs_size_t capacity_bytes, cs_size_t * bytes_needed ) Get the name of the current project.
cs_result	cs_prj_files_directory ( char * dst, cs_size_t capacity_bytes, cs_size_t * bytes_needed ) Get the absolute file system path for the project analysis directory (pfilesname.prj_files) of the currently loaded project.
cs_result	cs_sdg_incremental_capable ( cs_boolean * out_b ) Check: was INCREMENTAL_BUILD=Yes specified in the configuration file?

Function Descriptions

Function cs_sdg_pdgs

cs_result cs_sdg_pdgs (

cs_pdg pdg_list[],
cs_size_t capacity_bytes,
cs_size_t * bytes_needed )

Retrieve a list of the cs_pdg objects defined in the SDG of the current project.

Parameters

pdg_list	[inout]	A user-allocated array to be populated with the cs_pdg objects defined in the SDG of the current project.
capacity_bytes	[in]	The capacity of pdg_list, measured in bytes.
bytes_needed	[out]	The actual number of bytes needed for pdg_list.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_TRUNCATED if pdg_list is not large enough to hold the entire cs_pdg list,
CS_SUCCESS otherwise.

Time-Complexity

O(n), where n is the number of cs_pdg elements in the project.

Notes

Call this function with pdg_list NULL and capacity_bytes 0 (zero) to determine the memory needed to hold all cs_pdg objects defined in the SDG of the current project.

Function cs_sdg_pdgs_iter_first

cs_result cs_sdg_pdgs_iter_first (

cs_pdg * pdg,
cs_sdg_pdgs_iter * itr )

Get the first cs_pdg from the SDG of the current project.

Parameters

pdg	[out]	The first cs_pdg obtained from the SDG of the current project.
itr	[out]	The cs_sdg_pdgs_iter opened to traverse the SDG of the current project.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_OUT_OF_ELEMENTS if the SDG for the current project contains no cs_pdg ,
CS_SUCCESS otherwise.

Notes

This function opens itr, which is required by cs_sdg_pdgs_iter_next(). Use cs_sdg_pdgs_iter_close() to close itr.

Function cs_sdg_pdgs_iter_next

cs_result cs_sdg_pdgs_iter_next (

cs_pdg * pdg,
cs_sdg_pdgs_iter * itr )

Get the next cs_pdg from itr.

Parameters

pdg	[out]	The next cs_pdg.
itr	[inout]	The cs_sdg_pdgs_iter from which to obtain the next cs_pdg .

Returns

CS_SUCCESS if pdg is retrieved successfully;
CS_OUT_OF_ELEMENTS if iteration is complete.

Function cs_sdg_pdgs_iter_close

cs_result cs_sdg_pdgs_iter_close (

cs_sdg_pdgs_iter * itr )

Close a cs_sdg_pdgs_iter .

Parameters

itr

[inout]

The cs_sdg_pdgs_iter to close

Returns

CS_SUCCESS on successful closure

Function cs_filter_pdg_directive_name

cs_result cs_filter_pdg_directive_name (

cs_filter_pdg_directive directive,
cs_const_string * out_string )

Retrieve the name of a cs_filter_pdg_directive.

Parameters

directive	[in]	The cs_filter_pdg_directive for which to find the name.
out_string	[out]	A string representation of the name of directive.

Returns

A cs_result:

CS_ERROR_INVALID_FILTER_PDG_DIRECTIVE if directive is not a valid cs_filter_pdg_directive,
CS_SUCCESS otherwise.

Function cs_filter_pdg_vertex_directive_name

cs_result cs_filter_pdg_vertex_directive_name (

cs_filter_pdg_vertex_directive directive,
cs_const_string * out_string )

Retrieve the name of a cs_filter_pdg_vertex_directive.

Parameters

directive	[in]	The cs_filter_pdg_vertex_directive for which to find the name.
out_string	[out]	A string representation of the name of directive.

Returns

A cs_result:

CS_ERROR_INVALID_FILTER_PDG_VERTEX_DIRECTIVE if directive is not a valid cs_filter_pdg_vertex_directive,
CS_SUCCESS otherwise.

Function cs_sdg_uids

cs_result cs_sdg_uids (

cs_uid uid_list[],
cs_size_t capacity_bytes,
cs_size_t * bytes_needed )

Retrieve a list of the compilation units (cs_uid) contributing to the SDG of the current project.

Parameters

uid_list	[out]	A user-allocated array to be populated with the compilation units (cs_uid) contributing to the SDG of the current project.
capacity_bytes	[in]	The capacity of uid_list, measured in bytes.
bytes_needed	[out]	The number of bytes required to store the entire list of compilation units.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_TRUNCATED if uid_list is not large enough to hold the entire list of compilation units,
CS_SUCCESS otherwise.

Time-Complexity

O(n), where n is the number of compilation units in the current project.

Notes

Call this function with uid_list NULL and capacity_bytes 0 (zero) to determine the memory needed to hold the entire list.

Function cs_sdg_uids_iter_first

cs_result cs_sdg_uids_iter_first (

cs_uid * uid,
cs_sdg_uids_iter * itr )

Get the first compilation unit cs_uid from the SDG of the current project.

Parameters

uid	[out]	The first compilation unit cs_uid obtained from the SDG of the current project.
itr	[out]	The cs_sdg_uids_iter iterator opened to traverse the SDG of the current project.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_SUCCESS otherwise.
CS_OUT_OF_ELEMENTS if there are no cs_uid objects left to retrieve (iteration is complete).

Function cs_sdg_uids_iter_next

cs_result cs_sdg_uids_iter_next (

cs_uid * uid,
cs_sdg_uids_iter * itr )

Get the next cs_uid from itr.

Parameters

uid	[out]	The next cs_uid.
itr	[out]	The cs_sdg_uids_iter from which to obtain the next cs_uid.

Returns

A cs_result:

CS_SUCCESS if uid is retrieved successfully,
CS_OUT_OF_ELEMENTS if there are no cs_uid objects left to retrieve (iteration is complete).

Function cs_sdg_uids_iter_close

cs_result cs_sdg_uids_iter_close (

cs_sdg_uids_iter * itr )

Close a cs_sdg_uids_iter.

Parameters

itr

[out]

The cs_sdg_uids_iter to close.

Returns

CS_SUCCESS on successful closure.

Function cs_sdg_sfs_iter_first

cs_result cs_sdg_sfs_iter_first (

cs_sf * sf,
cs_sdg_sfs_iter * itr )

Get the first source file cs_sf from the SDG of the current project.

Parameters

sf	[out]	The first source file cs_sf obtained from the SDG of the current project.
itr	[out]	The cs_sdg_sfs_iter iterator opened to traverse the SDG of the current project.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_SUCCESS otherwise.
CS_OUT_OF_ELEMENTS if there are no source files (cs_sf) left to retrieve (iteration is complete).

Function cs_sdg_sfs_iter_next

cs_result cs_sdg_sfs_iter_next (

cs_sf * sf,
cs_sdg_sfs_iter * itr )

Get the next cs_sf from itr.

Parameters

sf	[out]	The next cs_sf.
itr	[out]	The cs_sdg_sfs_iter from which to obtain the next cs_sf.

Returns

A cs_result:

CS_SUCCESS if sf is retrieved successfully,
CS_OUT_OF_ELEMENTS if there are no source files (cs_sf) left to retrieve (iteration is complete).

Function cs_sdg_sfs_iter_close

cs_result cs_sdg_sfs_iter_close (

cs_sdg_sfs_iter * itr )

Close a cs_sdg_sfs_iter.

Parameters

itr

[out]

The cs_sdg_sfs_iter to close.

Returns

CS_SUCCESS on successful closure.

Function cs_sdg_ignored_uids

cs_result cs_sdg_ignored_uids (

cs_uid uid_list[],
cs_size_t capacity_bytes,
cs_size_t * bytes_needed )

Retrieve a list of the compilation units (cs_uid) that are dropped from the build.

Parameters

uid_list	[out]	A user-allocated array to be populated with the compilation units (cs_uid) that are dropped from the build.
capacity_bytes	[in]	The capacity of uid_list, measured in bytes.
bytes_needed	[out]	The number of bytes required to store the entire list of compilation units.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_TRUNCATED if uid_list is not large enough to hold the entire list of compilation units,
CS_SUCCESS otherwise.

Time-Complexity

O(n), where n is the number of compilation units in the current project.

Notes

Call this function with uid_list NULL and capacity_bytes 0 (zero) to determine the memory needed to hold the entire list.

Function cs_sdg_compilation_units

cs_result cs_sdg_compilation_units (

cs_file_path file_path_list[],
cs_size_t capacity_bytes,
cs_size_t * bytes_needed,
cs_size_t * result_cardinality )

Retrieve a list of file-paths of the compilation units contributing to the SDG of the current project.

Parameters

file_path_list	[out]	The user-allocated array to be populated with the file paths of the compilation units contributing to the SDG of the current project.
capacity_bytes	[in]	The capacity of file_path_list, measured in bytes.
bytes_needed	[out]	The number of bytes required to store the entire list of compilation unit file paths.
result_cardinality	[out]	The number of compilation units in file_path_list.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_TRUNCATED if file_path_list is not large enough to hold the entire list of compilation unit file paths (and so the list was truncated),
CS_SUCCESS otherwise.

Time-Complexity

O(n), where n is the number of compilation units in the current project.

Notes

Call this function with file_path_list NULL and capacity_bytes 0 (zero) to determine the memory needed to hold the entire list.

Function cs_sdg_retrieve_pdg

cs_result cs_sdg_retrieve_pdg (

csint64 pid,
cs_pdg * out_pdg )

Retrieve the cs_pdg corresponding to a given procedure ID.

Parameters

pid	[in]	The unique cs_integer for which the cs_pdg is to be obtained.
out_pdg	[out]	The cs_pdg corresponding to pid.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded.
CS_NO_SUCH_PDG if there is no cs_pdg in the project that corresponds to pid.
CS_SUCCESS otherwise.

Notes

To get the unique identifier of a cs_pdg, use cs_pdg_procedure_id().

Function cs_sdg_error_count

cs_result cs_sdg_error_count (

cs_boolean including_ignored,
cs_size_t * out_i )

Retrieve the number of errors encountered in compiling the files in the SDG.

Parameters

including_ignored	[in]	Specify cs_true to include the counts for compilations that are dropped from the build, cs_false to exclude them.
out_i	[out]	The total number of errors (summing over all compilation units, subject to including_ignored).

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_ERROR_COUNT_UNKNOWN_BUT_POSITIVE if the error count of at least one compilation unit was an indefinite positive number,
CS_ERROR_COUNT_UNKNOWN if the error count of at least one compilation unit was completely unknown,
CS_SUCCESS otherwise.

Notes

out_i is populated with a lower bound on the number of errors that must have occurred even when CS_ERROR_COUNT_UNKNOWN_BUT_POSITIVE or CS_ERROR_COUNT_UNKNOWN is returned.

Function cs_sdg_warning_count

cs_result cs_sdg_warning_count (

cs_boolean including_ignored,
cs_size_t * out_i )

Retrieve the number of warnings encountered in compiling the files in the SDG.

Parameters

including_ignored	[in]	Specify cs_true to include the counts for compilations that are dropped from the build, cs_false to exclude them.
out_i	[out]	The total number of warnings (summing over all compilation units, subject to including_ignored).

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_ERROR_COUNT_UNKNOWN_BUT_POSITIVE if the warning count of at least one compilation unit was an indefinite positive number,
CS_ERROR_COUNT_UNKNOWN if the warning count of at least one compilation unit was completely unknown,
CS_SUCCESS otherwise.

Notes

out_i is populated with a lower bound on the number of warnings that must have occurred even when CS_ERROR_COUNT_UNKNOWN_BUT_POSITIVE or CS_ERROR_COUNT_UNKNOWN is returned.

Note that this method retrieves the number of compiler warnings: it is not related to CodeSonar warnings.

Function cs_sdg_is_loaded

cs_boolean cs_sdg_is_loaded ( )

Check: is a project currently loaded?

Returns	cs_true if a project is loaded; cs_false if not.

Function cs_sdg_is_read_only

cs_boolean cs_sdg_is_read_only ( )

Check: is the current project read-only?

Returns	cs_true if the current project is read-only; cs_false if not.

Function cs_sdg_file_is_newer_than_build

cs_result cs_sdg_file_is_newer_than_build (

cs_const_file_path file,
cs_boolean * out_b )

Determine if a file is newer than the rest of the project.

Parameters

file	[in]	The file to check.
out_b	[out]	cs_true if file is newer than the project; cs_false otherwise.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_ERROR_IO_STAT if file cannot be found,
CS_SUCCESS otherwise.

Function cs_sdg_retain_unnormalized_c_ast

cs_result cs_sdg_retain_unnormalized_c_ast (

cs_boolean * out_b )

Determine whether any of cs_pdg_vertex_ast(), cs_abs_loc_ast(), cs_abs_loc_type(), cs_pdg_ast() or cs_file_ast() can successfully return a cs_ast whose cs_ast_family is csaf_c_unnormalized.

Parameters

out_b

[out]

cs_true if unnormalized C/C++ ASTs were retained; cs_false otherwise.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_SUCCESS otherwise.

Function cs_project_name

cs_result cs_project_name (

cs_string prj_name,
cs_size_t capacity_bytes,
cs_size_t * bytes_needed )

Get the name of the current project.

Parameters

prj_name	[out]	A user-allocated buffer to be populated with the name of the project.
capacity_bytes	[in]	The capacity of prj_name, measured in bytes.
bytes_needed	[out]	The number of bytes required to store the project name.

Returns

A cs_result:

CS_TRUNCATED if prj_name is not large enough to hold the entire project name (and so the project name is truncated),
CS_SUCCESS otherwise.

Function cs_prj_files_directory

cs_result cs_prj_files_directory (

char * dst,
cs_size_t capacity_bytes,
cs_size_t * bytes_needed )

Get the absolute file system path for the project analysis directory (pfilesname.prj_files) of the currently loaded project.

Parameters

dst	[out]	A user-allocated buffer to be populated with the file system path of the .prj_files directory.
capacity_bytes	[in]	The capacity of dst, measured in bytes.
bytes_needed	[out]	The number of bytes required to store the file system path.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_TRUNCATED if dst is not large enough to hold the entire file system path (and so the file system path is truncated),
CS_SUCCESS otherwise.

Notes

If called from within a slave process of a distributed analysis, this function can return a file system path that only exists on the computer running the analysis master process (or daemon master process, if called after the analysis has transitioned to daemon mode to service hub requests). Even if the two processes are on the same machine, the slave may be running as a different user and may not have permission to access the directory.

Function cs_sdg_incremental_capable

cs_result cs_sdg_incremental_capable (

cs_boolean * out_b )

Check: was INCREMENTAL_BUILD=Yes specified in the configuration file?

Parameters

out_b

[out]

cs_true if INCREMENTAL_BUILD=Yes; cs_false otherwise.

Returns

A cs_result:

CS_ERROR_SDG_NOT_PRESENT if no project is loaded,
CS_SUCCESS otherwise.

SDG: cs_sdg.h

Links

Defines

Types

On Separate Pages

Functions

Function Descriptions