A CodeSonar or CodeSurfer project. More...

Public Member Functions
std::string	as_repr () const
	Get a representation of a project object that includes information useful for debugging.

std::string	as_string () const
	Get a simple string representation of a project object.

int	cmp (const project &other) const
	Comparison function for project, with respect to a stable overall ordering.

project_compunits_iterator	compunits () const
	Get an iterator over all the compilation units (compunit) in a project.

std::vector< compunit >	compunits_vector () const
	Get the compilation units contributing to a project.

size_t	error_count (bool including_ignored=false) const
	Get the number of errors encountered in compiling the files in a project.

bool	file_is_newer (const std::string &fn) const
	Check: is a file newer than the rest of the project?

ast	find_ast_by_address (effective_address ea) const
	[Binary analyses only] Get the AST with the specified effective address.

compunit	find_compunit (csuint32 id) const
	Retrieve the compilation unit with the specified unique ID.

symbol_set	find_containing_symbols_by_address (effective_address ea) const
	[Binary analyses only] Get the symbols that contain the specified effective address.

sfileinst_line_pair	find_file_line_by_address (effective_address ea) const
	[Binary analyses only] Get the file instance and line for the specified effective address.

point_set	find_points_by_address (effective_address ea) const
	[Binary analyses only] Get the points with the specified effective address.

procedure	find_procedure (const std::string &procname) const
	Retrieve the procedure with the specified verbose name.

procedure	find_procedure (csint64 id) const
	Retrieve the procedure with the specified unique ID.

procedure	find_procedure_by_address (effective_address ea) const
	[Binary analyses only] Get the procedure with the specified effective address.

symbol_set	find_symbols_by_address (effective_address ea) const
	[Binary analyses only] Get the symbols with the specified effective address.

std::string	get_data_bytes_by_address (effective_address ea, size_t num_bytes)
	[Binary analyses only] Get the underlying data bytes for the specified effective address.

csuint16	get_uint16_by_address (effective_address ea)
	[Binary analysis only] Read an endian-correct 16 bit unsigned integer value from the specified effective address.

csuint32	get_uint32_by_address (effective_address ea)
	[Binary analysis only] Read an endian-correct 32-bit unsigned integer value from the specified effective address.

csuint64	get_uint64_by_address (effective_address ea)
	[Binary analysis only] Read an endian-correct 64-bit unsigned integer value from the specified effective address.

csuint8	get_uint8_by_address (effective_address ea)
	[Binary analysis only] Read an 8-bit unsigned integer value from the specified effective address.

amc_analysis	get_vsa_results ()
	[Binary analyses only] Get the results of Value Set Analysis (VSA).

std::string	handle () const
	Get a handle for this project.

bool	has_unnormalized_c_asts () const
	Check: was the project built to retain unnormalized C/C++ ASTs?

cs_hash_t	hash () const
	Hash function for project.

std::vector< compunit >	ignored_compunits () const
	Get a std::vector of the compilation units that are dropped from the build.

bool	incremental_capable () const
	Check: was `INCREMENTAL_BUILD`=Yes specified in the configuration file?

bool	is_read_only () const
	Check: is the project read-only?

compunit	lookup_compunit_handle (const std::string &compunit_handle) const
	Get a compunit from a handle.

point	lookup_point_handle (const std::string &point_handle) const
	Get a point from a handle.

procedure	lookup_procedure_handle (const std::string &proc_handle) const
	Get a procedure from a handle.

symbol	lookup_register_symbol (const std::string &regname) const
	[Binary analyses only] Retrieve a register (including flag) symbol by name.

sfile	lookup_sfile_handle (const std::string &sfile_handle) const
	Get a sfile from a handle.

sfileinst	lookup_sfileinst_handle (const std::string &sfileinst_handle) const
	Get a sfileinst from a handle.

symbol	lookup_symbol (const std::string &symname) const
	Retrieve a symbol by verbose name.

symbol	lookup_symbol_handle (const std::string &symbol_handle) const
	Get a symbol from a handle.

std::string	name () const
	Get the name of a project.

symbol	param_symbol (size_t num) const
	Retrieve `$param_NUM`: the symbol representing the NUM'th formal parameter.

std::string	prj_files_directory () const
	Get the absolute file system path for the project analysis directory (pfilesname.prj_files) for a project.

project_procedures_iterator	procedures () const
	Get an iterator over all the procedures (procedure) in a project.

std::vector< procedure >	procedures_vector () const
	Get the procedures defined in a project.

project_root_directories_iterator	root_directories () const
	Get an iterator over the set of root directories (directory) deduced by inspecting all source file paths in the project.

size_t	root_directory_count () const
	Get the number of root directories in the project.

amc_analysis	run_multiinterval_analysis (procedure_name_to_model_vector const &fn_to_model_str)
	[Binary analyses only] Run multiinterval analysis.

project_sfiles_iterator	sfiles () const
	Get an iterator over all the source files (sfile) in a project.

symbol_universe_iterator	symbols () const
	Get an iterator over the symbols (symbol) in a project.

xr_query_iterator	token_search (const xr_query &q) const
	Execute the specified cross-reference query over the tokens in a project.

size_t	warning_count (bool including_ignored=false) const
	Get the number of compiler warnings encountered in compiling the files in a project.

std::string	xtype_to_c_decl (ast xtype_ast, const std::string id, csuint32 struct_depth, xtype_render_style style, const std::string prefix, const std::string indent) const
	[Binary analyses only] Given an ast which is an xtype abstract type, render the type as a C declaration.

Static Public Member Functions
static project	current ()
	Get the currently-loaded project.

static bool	is_loaded ()
	Check: is a project currently loaded?

static project	lookup_project_handle (const std::string &project_handle)
	Get a project from a handle.

Related Symbols
(Note that these are not member symbols.)
bool	operator!= (const project &a, const project &b)
	Inequality operator for project.

bool	operator< (const project &a, const project &b)
	Less-than operator for project.

bool	operator<= (const project &a, const project &b)
	Less-than-or-equal operator for project.

bool	operator== (const project &a, const project &b)
	Equality operator for project.

bool	operator> (const project &a, const project &b)
	Greater-than operator for project.

bool	operator>= (const project &a, const project &b)
	Greater-than-or-equal operator for project.

Detailed Description

A CodeSonar or CodeSurfer project.

The project class corresponds to the SDG abstraction.

Get the currently-loaded project with project::current().

Member Function Documentation

◆ as_repr()

std::string cs::project::as_repr ( ) const

inline

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

Returns: The string representation.

◆ as_string()

std::string cs::project::as_string ( ) const

inline

Get a simple string representation of a project object.

Returns: The string representation.

◆ cmp()

int cs::project::cmp ( const project & other ) const

inline

Comparison function for project, with respect to a stable overall ordering.

Parameters

other The project object to compare against.

Returns

An integer N such that:

N==0 if the two objects compare equal
N<0 if this < other
N>0 if this > other

◆ compunits()

project_compunits_iterator cs::project::compunits ( ) const

inline

Get an iterator over all the compilation units (compunit) in a project.

Returns: The initialized project_compunits_iterator.

◆ compunits_vector()

std::vector< compunit > cs::project::compunits_vector ( ) const

inline

Get the compilation units contributing to a project.

Returns: A std::vector of the compilation units (compunit) contributing to the project.

◆ current()

static project cs::project::current ( )

inlinestatic

Get the currently-loaded project.

Returns: The project.

Exceptions

result::ERROR_SDG_NOT_PRESENT if no project is currently loaded.

◆ error_count()

size_t cs::project::error_count ( bool including_ignored = false ) const

inline

Get the number of errors encountered in compiling the files in a project.

Parameters

[in] including_ignored true to include errors in compilations that are dropped from the build, false to exclude those errors.

Returns: The total number of errors (summing over all compilation units, subject to including_ignored).

Exceptions

result::ERROR_COUNT_UNKNOWN_BUT_POSITIVE	if there is at least one compiler error but the total number is not known.
result::ERROR_COUNT_UNKNOWN	if the number of compiler errors is completely unknown.

◆ file_is_newer()

bool cs::project::file_is_newer ( const std::string & fn ) const

inline

Check: is a file newer than the rest of the project?

Parameters

[in] fn The pathname of the file to check.

Returns: true if the file at fn is newer than the rest of the project, false otherwise.

Exceptions

result::ERROR_IO_STAT if fn cannot be found.

◆ find_ast_by_address()

ast cs::project::find_ast_by_address ( effective_address ea ) const

inline

[Binary analyses only] Get the AST with the specified effective address.

Parameters

[in] ea The address to look up.

Returns: The procedure whose effective address is ea.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENT	if no AST with effective address `ea` is found. This can occur if the project is not a binary project, or if `ea` is "invalid".
result::TRUNCATED	if more than one AST was found at the given EA, in which case an arbitrary AST from the list is returned, with a preference for data ASTs over instruction ASTs.

◆ find_compunit()

compunit cs::project::find_compunit ( csuint32 id ) const

inline

Retrieve the compilation unit with the specified unique ID.

Parameters

[in] id The compilation unit ID.

Returns: The compunit found whose unique ID is id.

To get a compilation unit's ID, use compunit::id().

Exceptions

result::ERROR_UID_NOT_FOUND if no such compilation unit exists.

◆ find_containing_symbols_by_address()

symbol_set cs::project::find_containing_symbols_by_address ( effective_address ea ) const

inline

[Binary analyses only] Get the symbols that contain the specified effective address.

Parameters

[in] ea The address to look up.

Returns: A symbol_set containing the symbols (symbol) that contain the effective address ea.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENT	if no symbols containing effective address `ea` are found. This can occur if the project is not a binary project, or if `ea` is "invalid".

There can be multiple symbols containing the same effective address in different modules.

◆ find_file_line_by_address()

sfileinst_line_pair cs::project::find_file_line_by_address ( effective_address ea ) const

inline

[Binary analyses only] Get the file instance and line for the specified effective address.

Parameters

[in] ea The address to look up.

Returns: The file instance of the binary file containing the given effective address and the line in the disassembly listing that corresponds to that address.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENT	if no binary file containing effective address `ea` is found. This can occur if the project is not a binary project, or if `ea` is outside the range of any binary file.
result::TRUNCATED	if more than one file with effective address `ea` is found. One of the files is returned.

There can be multiple points with the same effective address in different modules.

◆ find_points_by_address()

point_set cs::project::find_points_by_address ( effective_address ea ) const

inline

[Binary analyses only] Get the points with the specified effective address.

Parameters

[in] ea The address to look up.

Returns: A point_set containing the points (point) whose effective address is ea.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENT	if no points with effective address `ea` are found. This can occur if the project is not a binary project, or if `ea` is "invalid".

There can be multiple points with the same effective address in different modules.

◆ find_procedure() [1/2]

procedure cs::project::find_procedure ( const std::string & procname ) const

inline

Retrieve the procedure with the specified verbose name.

Parameters

[in] procname The procedure's verbose name as returned by procedure::verbose_name().

Returns: The first procedure found whose verbose name is procname.

Exceptions

result::PDG_NOT_FOUND if no such procedure exists.

It is possible for a project to have multiple procedures whose name is procname. For example, two compilation units may each have a static function called procname. In this case, find_procedure() will return the first one it encounters.

◆ find_procedure() [2/2]

procedure cs::project::find_procedure ( csint64 id ) const

inline

Retrieve the procedure with the specified unique ID.

Parameters

[in] id The procedure ID.

Returns: The procedure found whose unique ID is id.

To get a procedure's ID, use procedure::id().

Exceptions

result::NO_SUCH_PDG if no such procedure exists.

◆ find_procedure_by_address()

procedure cs::project::find_procedure_by_address ( effective_address ea ) const

inline

[Binary analyses only] Get the procedure with the specified effective address.

Parameters

[in] ea The address to look up.

Returns: The procedure whose effective address is ea.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENT	if no procedure with effective address `ea` is found. This can occur if the project is not a binary project, or if `ea` is "invalid".
result::TRUNCATED	if more than one procedure with effective address `ea` is found. One of the procedures is returned.

There can be multiple points with the same effective address in different modules.

◆ find_symbols_by_address()

symbol_set cs::project::find_symbols_by_address ( effective_address ea ) const

inline

[Binary analyses only] Get the symbols with the specified effective address.

Parameters

[in] ea The address to look up.

Returns: A symbol_set containing the symbols (symbol) whose effective address is ea.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENT	if no symbols with effective address `ea` are found. This can occur if the project is not a binary project, or if `ea` is "invalid".

There can be multiple symbols with the same effective address in different modules.

◆ get_data_bytes_by_address()

std::string cs::project::get_data_bytes_by_address	(	effective_address	ea,
		size_t	num_bytes
	)

inline

[Binary analyses only] Get the underlying data bytes for the specified effective address.

Parameters

[in]	ea	The address to look up.
[in]	num_bytes	Upper bound on the number of bytes to retrieve.

Returns: The data bytes read from ea, subject to the limit imposed by num_bytes.

Exceptions

result::ERROR_PARAMETER_TOO_LARGE	if `num_bytes` is unreasonably large.
result::MODULE_IR_NOT_AVAILABLE	if no IR is found for `ea`, or more than one IR is found for `ea`.

Note that the number of bytes returned may be smaller than the upper bound num_bytes. This would be the case if the request would extend beyond a section boundary. Zero bytes will be returned if ea is not a valid effective address in this project.

◆ get_uint16_by_address()

csuint16 cs::project::get_uint16_by_address ( effective_address ea )

inline

[Binary analysis only] Read an endian-correct 16 bit unsigned integer value from the specified effective address.

Parameters

[in] ea The address to look up.

Returns: The csuint16 read from ea.

Exceptions

result::MODULE_IR_NOT_AVAILABLE	if no IR is found for `ea`, or more than one IR is found for `ea`.
result::ERROR_INVALID_ARGUMENT	if `ea` is not a valid effective address in this project, or if reading 16 bits from `ea` would cross a section boundary.

◆ get_uint32_by_address()

csuint32 cs::project::get_uint32_by_address ( effective_address ea )

inline

[Binary analysis only] Read an endian-correct 32-bit unsigned integer value from the specified effective address.

Parameters

[in] ea The address to look up.

Returns: The csuint32 read from ea.

Exceptions

result::MODULE_IR_NOT_AVAILABLE	if no IR is found for `ea`, or more than one IR is found for `ea`.
result::ERROR_INVALID_ARGUMENT	if `ea` is not a valid effective address in this project, or if reading 32 bits from `ea` would cross a section boundary.

◆ get_uint64_by_address()

csuint64 cs::project::get_uint64_by_address ( effective_address ea )

inline

[Binary analysis only] Read an endian-correct 64-bit unsigned integer value from the specified effective address.

Parameters

[in] ea The address to look up.

Returns: The csuint64 read from ea.

Exceptions

result::MODULE_IR_NOT_AVAILABLE	if no IR is found for `ea`, or more than one IR is found for `ea`.
result::ERROR_INVALID_ARGUMENT	if `ea` is not a valid effective address in this project, or if the requested read would cross a section boundary.

◆ get_uint8_by_address()

csuint8 cs::project::get_uint8_by_address ( effective_address ea )

inline

[Binary analysis only] Read an 8-bit unsigned integer value from the specified effective address.

Parameters

[in] ea The address to look up.

Returns: The csuint8 read from ea.

Exceptions

result::MODULE_IR_NOT_AVAILABLE	if no IR is found for `ea`, or more than one IR is found for `ea`.
result::ERROR_INVALID_ARGUMENT	if `ea` is not a valid effective address in this project.

◆ get_vsa_results()

amc_analysis cs::project::get_vsa_results ( )

inline

[Binary analyses only] Get the results of Value Set Analysis (VSA).

Returns: The VSA results for the project.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality, of if the project is only source.
result::ERROR_ANALYSIS_NOT_RUN	if VSA was not enabled in the front end.

◆ handle()

std::string cs::project::handle ( ) const

inline

Get a handle for this project.

Returns: The project's handle.

Use this function to retrieve a handle to the project which can be stored externally and used with lookup_project_handle() to retrieve the project when needed. This handle is valid only for the analysis it was generated from. If you rebuild the project, the handle will no longer be valid.

A handle is a std::string consisting of letters (upper and lower case( and numbers, and could also include the following characters: "+", "=", and "_".

◆ has_unnormalized_c_asts()

bool cs::project::has_unnormalized_c_asts ( ) const

inline

Check: was the project built to retain unnormalized C/C++ ASTs?

Returns: true if the project was built to retain unnormalized C/C++ ASTs, false otherwise.

Unnormalized C/C++ ASTs are retained if the project is built with RETAIN_UNNORMALIZED_C_AST=Yes. If this returns false, the following methods will not be able to retrieve ASTs (ast) whose family is ast_family::C_UNNORMALIZED.

◆ hash()

cs_hash_t cs::project::hash ( ) const

inline

Hash function for project.

Returns: The hash value.

◆ ignored_compunits()

std::vector< compunit > cs::project::ignored_compunits ( ) const

inline

Get a std::vector of the compilation units that are dropped from the build.

Returns: A std::vector of the compilation units (compunit) that are dropped from the build.

◆ incremental_capable()

bool cs::project::incremental_capable ( ) const

inline

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

Returns: true if INCREMENTAL_BUILD=Yes, false otherwise.

◆ is_loaded()

static bool cs::project::is_loaded ( )

inlinestatic

Check: is a project currently loaded?

Returns: true if a project is currently loaded, false otherwise.

◆ is_read_only()

bool cs::project::is_read_only ( ) const

inline

Check: is the project read-only?

Returns: true if the project is read-only, false otherwise.

◆ lookup_compunit_handle()

compunit cs::project::lookup_compunit_handle ( const std::string & compunit_handle ) const

inline

Get a compunit from a handle.

Parameters

[in] compunit_handle The compunit's handle, as returned by compunit::handle().

Returns: The compunit corresponding to compunit_handle.

Use this function to retrieve a compunit based on a handle: a string generated by compunit::handle() that uniquely identifies the compunit. The handle can be stored externally and this method can be used to retrieve the compunit whenever needed.

Exceptions

result::ERROR_INVALID_ARGUMENT	if the handle parameter is not a valid handle or does not match a compunit.
result::ERROR_IO_READ_PAST_EOF	if the handle parameter is too short to be a valid handle.
result::ERROR_INVALID_ARGUMENT	if `compunit_handle` is not a valid handle for a compilation unit in the project.

◆ lookup_point_handle()

point cs::project::lookup_point_handle ( const std::string & point_handle ) const

inline

Get a point from a handle.

Parameters

[in] point_handle The point's handle, as returned by point::handle().

Returns: The point corresponding to point_handle.

Use this function to retrieve a point based on a handle: a string generated by point::handle() that uniquely identifies the point. The handle can be stored externally and this method can be used to retrieve the point whenever needed.

Exceptions

result::ERROR_INVALID_ARGUMENT	if the handle parameter is not a valid handle or does not match a point.
result::ERROR_IO_READ_PAST_EOF	if the handle parameter is too short to be a valid handle.
result::ERROR_SDG_NOT_PRESENT	if there is no current System Dependence Graph.
result::ELEMENT_NOT_PRESENT	if there is no point matching the `point_handle`.
result::ERROR_INVALID_ARGUMENT	if `point_handle` is not a valid handle for a point in the project.

◆ lookup_procedure_handle()

procedure cs::project::lookup_procedure_handle ( const std::string & proc_handle ) const

inline

Get a procedure from a handle.

Parameters

[in] proc_handle The procedure's handle, as returned by procedure::handle().

Returns: The procedure corresponding to proc_handle.

Use this function to retrieve a procedure based on a handle: a string generated by procedure::handle() that uniquely identifies the procedure. The handle can be stored externally and this method can be used to retrieve the procedure whenever needed.

Exceptions

result::ERROR_INVALID_ARGUMENT	if the handle parameter is not a valid handle or does not match a procedure.
result::ERROR_IO_READ_PAST_EOF	if the handle parameter is too short to be a valid handle.
result::ERROR_SDG_NOT_PRESENT	if there is no current System Dependence Graph.
result::ELEMENT_NOT_PRESENT	if there is no procedure matching `proc_handle`.
result::ERROR_INVALID_ARGUMENT	if `procedure_handle` is not a valid handle for a procedure in the project.

◆ lookup_project_handle()

static project cs::project::lookup_project_handle ( const std::string & project_handle )

inlinestatic

Get a project from a handle.

Parameters

[in] project_handle The project's handle, as returned by project::handle().

Returns: The project corresponding to project_handle.

Use this function to retrieve a project based on a handle, a string generated by project::handle() that uniquely identifies the project. The handle can be stored externally and this method can be used to retrieve the project whenever needed.

Exceptions

result::ELEMENT_NOT_PRESENT	if there is no project matching `project_handle`.
result::ELEMENT_NOT_PRESENT	if the specified `project_handle` is not the handle of the current project.

◆ lookup_register_symbol()

symbol cs::project::lookup_register_symbol ( const std::string & regname ) const

inline

[Binary analyses only] Retrieve a register (including flag) symbol by name.

Parameters

[in]

regname

The friendly name (symbol::name()) of the register.

For flags, include the name of the containing status register. For example (IA32) "ef.zf"
Do not include name decoration elements that are present in the register's verbose name (symbol::verbose_name()).
Some ISAs use upper case register names and others use lower case. The caller is responsible for ensuring the correct case.

Returns: The symbol.

Exceptions

result::ELEMENT_NOT_PRESENT if there is no register symbol associated with regname.

This method allows you to retrieve a register symbol by name without having to produce the verbose name (symbol::verbose_name()) that is required by project::lookup_symbol(). In particular, you do not need to determine and apply the register-specific decoration elements that are included in the verbose name.

The context generally determines whether or not a name is expected to belong to a register, and thus whether or not this method should be used for lookup. In cases of uncertainty, try calling this this method first, then trying project::lookup_symbol() if it is unsuccessful.

◆ lookup_sfile_handle()

sfile cs::project::lookup_sfile_handle ( const std::string & sfile_handle ) const

inline

Get a sfile from a handle.

Parameters

[in] sfile_handle The sfile's handle, as returned by sfile::handle().

Returns: The sfile corresponding to sfile_handle.

Use this function to retrieve a sfile based on a handle: a string generated by sfile::handle() that uniquely identifies the sfile. The handle can be stored externally and this method can be used to retrieve the sfile whenever needed.

Exceptions

result::ERROR_INVALID_ARGUMENT	if the handle parameter is not a valid handle or does not match an sfile.
result::ERROR_IO_READ_PAST_EOF	if the handle parameter is too short to be a valid handle.
result::ERROR_INVALID_ARGUMENT	if `sfile_handle` is not a valid handle for a source file in the project.

◆ lookup_sfileinst_handle()

sfileinst cs::project::lookup_sfileinst_handle ( const std::string & sfileinst_handle ) const

inline

Get a sfileinst from a handle.

Parameters

[in] sfileinst_handle The sfileinst's handle, as returned by sfileinst::handle().

Returns: The sfileinst corresponding to sfileinst_handle.

Use this function to retrieve an sfileinst based on a handle: a string generated by sfileinst::handle() that uniquely identifies the sfileinst. The handle can be stored externally and this method can be used to retrieve the sfileinst whenever needed.

Exceptions

result::ERROR_INVALID_ARGUMENT	if the handle parameter is not a valid handle or does not match an sfileinst.
result::ERROR_IO_READ_PAST_EOF	if the handle parameter is too short to be a valid handle.
result::ERROR_SDG_NOT_PRESENT	if there is no current System Dependence Graph.
result::ELEMENT_NOT_PRESENT	if there is no sfileinst matching `sfileinst_handle`.
result::ERROR_INVALID_ARGUMENT	if `sfileinst_handle` is not a valid handle for a source file instance in the project.

◆ lookup_symbol()

symbol cs::project::lookup_symbol ( const std::string & symname ) const

inline

Retrieve a symbol by verbose name.

Parameters

[in] symname The symbol's verbose name, as returned by symbol::verbose_name().

Returns: The symbol.

Exceptions

result::ELEMENT_NOT_PRESENT if there is no symbol associated with symname.

◆ lookup_symbol_handle()

symbol cs::project::lookup_symbol_handle ( const std::string & symbol_handle ) const

inline

Get a symbol from a handle.

Parameters

[in] symbol_handle The symbol's handle, as returned by symbol::handle().

Returns: The symbol corresponding to symbol_handle.

Use this function to retrieve a symbol based on a handle: a string generated by symbol::handle() that uniquely identifies the symbol. The handle can be stored externally and this method can be used to retrieve the symbol whenever needed.

Exceptions

result::ERROR_INVALID_ARGUMENT	if the handle parameter is not a valid handle or does not match a symbol.
result::ERROR_IO_READ_PAST_EOF	if the handle parameter is too short to be a valid handle.
result::ERROR_SDG_NOT_PRESENT	if there is no current System Dependence Graph.
result::ELEMENT_NOT_PRESENT	if the search for the procedure containing this symbol fails.
result::ERROR_INVALID_ARGUMENT	if `symbol_handle` is not a valid handle for a symbol in the project.

◆ name()

std::string cs::project::name ( ) const

inline

Get the name of a project.

Returns: The project name (a std::string).

◆ param_symbol()

symbol cs::project::param_symbol ( size_t num ) const

inline

Retrieve $param_NUM: the symbol representing the NUM'th formal parameter.

Parameters

[in] num The number of the parameter to be retrieved (counting from the left, starting from 1).

Returns: The $param_num symbol.

Exceptions

result::ELEMENT_NOT_PRESENT if $param_NUM does not exist.

The $param_n symbols have global scope, no type, and do not belong to any specific function.

◆ prj_files_directory()

std::string cs::project::prj_files_directory ( ) const

inline

Get the absolute file system path for the project analysis directory (pfilesname.prj_files) for a project.

Returns: The file system path of the .prj_files directory (a std::string).

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 master process (analysis master or daemon master). 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.

◆ procedures()

project_procedures_iterator cs::project::procedures ( ) const

inline

Get an iterator over all the procedures (procedure) in a project.

Returns: The initialized project_procedures_iterator.

◆ procedures_vector()

std::vector< procedure > cs::project::procedures_vector ( ) const

inline

Get the procedures defined in a project.

Returns: A std::vector of the procedures (procedure) defined in the project.

◆ root_directories()

project_root_directories_iterator cs::project::root_directories ( ) const

inline

Get an iterator over the set of root directories (directory) deduced by inspecting all source file paths in the project.

Returns: The initialized project_root_directories_iterator.

◆ root_directory_count()

size_t cs::project::root_directory_count ( ) const

inline

Get the number of root directories in the project.

Returns: The number of root directories in the project.

◆ run_multiinterval_analysis()

amc_analysis cs::project::run_multiinterval_analysis ( procedure_name_to_model_vector const & fn_to_model_str )

inline

[Binary analyses only] Run multiinterval analysis.

Parameters

[in]

fn_to_model_str

A procedure_name_to_model_vector representing a map from a function name or call address to the way that function should be modeled.

For each pair (f, model):
- f is either the name of the function that will be modeled or the address of a specific call. It can also be an edge to model, in the form "address->address", where address is of the form 0x1234 or 5678. (In the latter case, it will be interpreted in decimal.)
- model is is a string of the form '$ret(range(low,hi))' or '$ret(range(low,hi,stride))'; this specifies that the modeled function should return the given strided interval. (For the first version, the stride is 1.) The model can also be $stop.
A function may be specified more than once; the join of all models will be used for that function's effect.

Returns: The analysis results.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENT	if the analysis could not find an entry point.
result::ERROR_INVALID_ARGUMENT	if one or more strings in `fn_to_model_str` is not of an appropriate form

◆ sfiles()

project_sfiles_iterator cs::project::sfiles ( ) const

inline

Get an iterator over all the source files (sfile) in a project.

Returns: The initialized project_sfiles_iterator.

◆ symbols()

symbol_universe_iterator cs::project::symbols ( ) const

inline

Get an iterator over the symbols (symbol) in a project.

Returns: The initialized symbol_universe_iterator.

◆ token_search()

xr_query_iterator cs::project::token_search ( const xr_query & q ) const

inline

Execute the specified cross-reference query over the tokens in a project.

Parameters

[in] q An xr_query that fully specifies the search conditions.

Returns: An xr_query_iterator over the query results (xr_tuple).

◆ warning_count()

size_t cs::project::warning_count ( bool including_ignored = false ) const

inline

Get the number of compiler warnings encountered in compiling the files in a project.

Parameters

[in] including_ignored true to include warnings in compilations that are dropped from the build, false to exclude those warnings.

Returns: The total number of warnings (summing over all compilation units, subject to including_ignored).

Exceptions

result::ERROR_COUNT_UNKNOWN_BUT_POSITIVE	if there is at least one compiler warning but the total number is not known.
result::ERROR_COUNT_UNKNOWN	if the number of compiler warnings is completely unknown.

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

◆ xtype_to_c_decl()

std::string cs::project::xtype_to_c_decl	(	ast	xtype_ast,
		const std::string	id,
		csuint32	struct_depth,
		xtype_render_style	style,
		const std::string	prefix,
		const std::string	indent
	)		const

inline

[Binary analyses only] Given an ast which is an xtype abstract type, render the type as a C declaration.

Parameters

[in]	xtype_ast	The ast to be rendered.
[in]	id	A string to be used in the rendering as the declared identifier.
[in]	struct_depth	The depth of nesting to include in the rendering.
[in]	style	The form of the rendering to use.
[in]	prefix	A string to use at the start of each rendered line.
[in]	indent	A string to use for each indentation level on each line, after prefix and before the rendered content.

Returns: The std::string representation of xtype_ast.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ERROR_INVALID_ARGUMENT	if `xtype_ast` is not of the correct class (xtype abstract type).

Friends And Related Symbol Documentation

◆ operator!=()

bool operator!=	(	const project &	a,
		const project &	b
	)

Parameters

[in]	a	The project to compare.
[in]	b	The project to compare against.

Returns: false if a and b are equal according to project::cmp(), true otherwise.

◆ operator<()

bool operator<	(	const project &	a,
		const project &	b
	)

Parameters

[in]	a	The project to compare.
[in]	b	The project to compare against.

Returns: true if a < b according to project::cmp() , false otherwise.

◆ operator<=()

bool operator<=	(	const project &	a,
		const project &	b
	)

Parameters

[in]	a	The project to compare.
[in]	b	The project to compare against.

Returns: true if a <= b according to project::cmp() , false otherwise.

◆ operator==()

bool operator==	(	const project &	a,
		const project &	b
	)

Parameters

[in]	a	The project to compare.
[in]	b	The project to compare against.

Returns: true if a and b are equal according to project::cmp(), false otherwise.

◆ operator>()

bool operator>	(	const project &	a,
		const project &	b
	)

Parameters

[in]	a	The project to compare.
[in]	b	The project to compare against.

Returns: true if a > b according to project::cmp() , false otherwise.

◆ operator>=()

bool operator>=	(	const project &	a,
		const project &	b
	)

Parameters

[in]	a	The project to compare.
[in]	b	The project to compare against.

Returns: true if a >= b according to project::cmp() , false otherwise.

The documentation for this class was generated from the following file:

cs_project.hpp

Public Member Functions

Static Public Member Functions

Related Symbols

Detailed Description

Member Function Documentation

◆ as_repr()

◆ as_string()

◆ cmp()

◆ compunits()

◆ compunits_vector()

◆ current()

◆ error_count()

◆ file_is_newer()

◆ find_ast_by_address()

◆ find_compunit()

◆ find_containing_symbols_by_address()

◆ find_file_line_by_address()

◆ find_points_by_address()

◆ find_procedure() [1/2]

◆ find_procedure() [2/2]

◆ find_procedure_by_address()

◆ find_symbols_by_address()

◆ get_data_bytes_by_address()

◆ get_uint16_by_address()

◆ get_uint32_by_address()

◆ get_uint64_by_address()

◆ get_uint8_by_address()

◆ get_vsa_results()

◆ handle()

◆ has_unnormalized_c_asts()

◆ hash()

◆ ignored_compunits()

◆ incremental_capable()

◆ is_loaded()

◆ is_read_only()

◆ lookup_compunit_handle()

◆ lookup_point_handle()

◆ lookup_procedure_handle()

◆ lookup_project_handle()

◆ lookup_register_symbol()

◆ lookup_sfile_handle()

◆ lookup_sfileinst_handle()

◆ lookup_symbol()

◆ lookup_symbol_handle()

◆ name()

◆ param_symbol()

◆ prj_files_directory()

◆ procedures()

◆ procedures_vector()

◆ root_directories()

◆ root_directory_count()

◆ run_multiinterval_analysis()

◆ sfiles()

◆ symbols()

◆ token_search()

◆ warning_count()

◆ xtype_to_c_decl()

Friends And Related Symbol Documentation

◆ operator!=()

◆ operator<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()