A compilation unit. More...

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

std::string	as_string () const
	Get the unnormalized file path corresponding to a compilation unit.

int	cmp (const compunit &other) const
	Comparison function for compunit.

std::vector< std::string >	compiler_command_line () const
	Get the native command line used to build a compilation unit.

std::string	compiler_model () const
	Get the name of the compiler model used to build a compilation unit.

std::vector< std::string >	compiler_wall_enable_flags () const
	Get the list of flags that enable all warnings for the compiler that compiled this compilation unit.

std::vector< std::string >	compiler_werror_enable_flags () const
	Get the list of flags that cause the compiler that compiled this compilation unit to treat warnings as errors.

std::vector< std::string >	cs_frontend_command_line () const
	Get the front end command line used to build a compilation unit.

std::string	csonar_front_end_run_id () const
	[CodeSonar only] Get the value used to identify a compilation unit to the hub: this will allow you to construct a hub URL for the Parse Details Log.

std::vector< std::string >	effective_compiler_flags () const
	Get the effective flags for the native build of a compilation unit.

size_t	error_count () const
	Get the number of errors encountered in compiling a compilation unit.

effective_address	get_address_for_section_offset (const std::string &sec_name, csuint32 sec_offset)
	[Binary analyses only] Returns the address that corresponds to the given (section, offset) location in this compilation unit.

ast	get_ast (ast_family family=ast_family::DEFAULT) const
	Get the AST (of the specified ast_family) for a compilation unit.

csuint32	get_group_uid () const
	Get the group to which a compilation unit belongs.

language	get_language () const
	Get the source language of a compilation unit.

sfileinst	get_sfileinst () const
	Get the root source file instance of a compilation unit.

compunit_global_iterator	global_symbols () const
	Get an iterator over the global symbols (symbol) in a compilation unit.

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

cs_hash_t	hash () const
	Get a hash value for a compunit.

csuint32	id () const
	Get the unique identifier of a compilation unit.

bool	is_backend () const
	Check: does a compunit object correspond to a compilation unit generated by the back end to hold #System_Initialization and undefined functions?

bool	is_hidden_binary () const
	[CodeSonar for Binaries only] Check: is a compilation unit an 'offstage binary' (that is, one that is analyzed but not included in results)?

bool	is_library_model () const
	Check: does a compunit object correspond to a compilation unit for a library model shipped with CodeSonar or CodeSurfer?

bool	is_rewriting () const
	Check: does a compunit object correspond to a rewriting compilation unit ?

bool	is_shared () const
	Check: can a compilation unit be shared by multiple projects and analyses?

bool	is_user () const
	Check: does a compunit object correspond to a user-generated compilation unit?

bool	limit_reached () const
	Check: did the front end reach any limits while parsing the specified compilation unit (which may have resulted in missing IR)?

symbol	lookup_symbol (const std::string &name) const
	Get a symbol from the compilation unit by name.

std::string	name () const
	Get the unnormalized file path corresponding to a compilation unit.

std::string	normalized_name () const
	Get the normalized file path corresponding to a compilation unit.

compunit_procedure_iterator	procedures () const
	Get an iterator over the procedures (procedure) in a compilation unit.

std::vector< std::string >	seen_wall_disable_flags () const
	Get the list of flags seen on the native command line that disable a subset of warnings for the compiler that compiled this compilation unit.

std::vector< std::string >	seen_werror_disable_flags () const
	Get the list of flags seen on the native command line that disable a subset of errors or cause warnings to not be treated as errors for the compiler that compiled this compilation unit.

size_t	warning_count () const
	Get the number of warnings encountered in compiling a compilation unit.

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

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

std::ostream &	operator<< (std::ostream &out, const compunit &a)


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

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

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

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

Detailed Description

A compilation unit.

A project is a combination of compilation units (compunit). Each compilation unit has:

a top-level file instance,
a collection of include-file instances, and
command-line flags used for the compilation.

We distinguish between "files" (sfile) and "file instances" (sfileinst) because a given file may be used multiple times in a project.For example, suppose we build a project by observing the compilation of m.c.

gcc -c m.c

Where the project source files are as follows.

/* mainfile.c */
#include "a.h"
#include "b.h"
#define ONE
#include "b.h"
#undef ONE
/* ... */

/* a.h */

/* (no #include statements) */

/* b.h */
#ifdef ONE
#include "a.h"
#else
#include "c.h"
#endif
/* ... */

/* c.h */

/* (no #include statements) */

The project has:

One compilation unit (compunit), representing this observed compilation. The compilation unit's top level file is m.c.
Four source files (sfile): m.c, a.h, b.h, c.h.
Six source file instances (sfileinst):
- One instance of m.c, corresponding to its role as the top level file in the compilation unit.
- Two instances of a.h: one for its inclusion in m.c and one for its inclusion in b.h.
- Two instances of b.h, corresponding to its two inclusions in m.c.
- One instance of c.h, corresponding to its inclusion in b.h.

The following image illustrates the relationships between compilation unit, source files, and source file instances in this project.

diagram of example project

For more information, see the Source Files manual page.

The following are useful for retrieving compilation units.

Class	Methods
procedure	procedure::get_compunit()
sfileinst	sfileinst::get_compunit()
project	project::compunits(), project::ignored_compunits()

Member Function Documentation

◆ as_repr()

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

inline

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

Returns: The string representation.

◆ as_string()

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

inline

Get the unnormalized file path corresponding to a compilation unit.

Returns: The unnormalized file path, if called on a compunit with an associated file path.

Equivalent to name().

◆ cmp()

cs::compunit::cmp ( const compunit & other ) const

inline

Comparison function for compunit.

Parameters

other The compunit 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

this and other will only compare equal if they are the same compunit object.

◆ compiler_command_line()

std::vector< std::string > cs::compunit::compiler_command_line ( ) const

inline

Get the native command line used to build a compilation unit.

Returns: The native command line, as a sequence of strings: one element for each command line token.

Exceptions

result::GENERATED_COMPILATION	if the compilation unit was generated in the back end.
result::ELEMENT_NOT_PRESENT	if native command line information for the compilation unit is not available.

All compilations built from a single native compiler invocation will share the same native command line.

◆ compiler_model()

std::string cs::compunit::compiler_model ( ) const

inline

Get the name of the compiler model used to build a compilation unit.

Returns: The compiler model name.

Exceptions

result::GENERATED_COMPILATION	if the compilation unit was generated in the back end.
result::ELEMENT_NOT_PRESENT	if compiler model information for the compilation unit is not available.

◆ compiler_wall_enable_flags()

std::vector< std::string > cs::compunit::compiler_wall_enable_flags ( ) const

inline

Get the list of flags that enable all warnings for the compiler that compiled this compilation unit.

Returns: The front end command line, as a sequence of strings: one element for each command line token.

Exceptions

result::ELEMENT_NOT_PRESENT if the information is not available.

For example, -Wall in gcc. The compiler model is responsible for populating this list and passing the information to the front-end.

◆ compiler_werror_enable_flags()

std::vector< std::string > cs::compunit::compiler_werror_enable_flags ( ) const

inline

Get the list of flags that cause the compiler that compiled this compilation unit to treat warnings as errors.

Returns: The front end command line, as a sequence of strings: one element for each command line token.

Exceptions

result::ELEMENT_NOT_PRESENT if the information is not available.

For example, -Werror in gcc. The compiler model is responsible for populating this list and passing the information to the front-end.

◆ cs_frontend_command_line()

std::vector< std::string > cs::compunit::cs_frontend_command_line ( ) const

inline

Get the front end command line used to build a compilation unit.

Returns: The front end command line, as a sequence of strings: one element for each command line token.

Exceptions

result::GENERATED_COMPILATION	if the compilation unit was generated in the back end.
result::ELEMENT_NOT_PRESENT	if the information is not available.

For the C/C++ front end, this includes options specified with configuration file parameters EDG_FRONTEND_OPTIONS_PREPEND and EDG_FRONTEND_OPTIONS_APPEND, and excludes CodeSurfer options.

◆ csonar_front_end_run_id()

std::string cs::compunit::csonar_front_end_run_id ( ) const

inline

[CodeSonar only] Get the value used to identify a compilation unit to the hub: this will allow you to construct a hub URL for the Parse Details Log.

Returns: The identifying value.

Exceptions

result::GENERATED_COMPILATION	if the compilation unit was generated in the back end.
result::ELEMENT_NOT_PRESENT	if this information is not available for the compilation unit.

The hub URL for the Parse Details Log for a compilation unit can be constructed from the return value as follows. Let W be the value returned from a successful call to this function; let host:port be the hub location. Then the URL is http://host:port/frontendrun/W.html.

◆ effective_compiler_flags()

std::vector< std::string > cs::compunit::effective_compiler_flags ( ) const

inline

Get the effective flags for the native build of a compilation unit.

Returns: The effective command line flags, as a sequence of strings: one element for each flag.

Exceptions

result::GENERATED_COMPILATION	if the compilation unit was generated in the back end.
result::ELEMENT_NOT_PRESENT	if build flag information for the compilation unit is not available.

This retrieves the effective flags after the content of the command file (the file specified as the value of '@') is inserted; input and output file names are removed; and flags like -c, -o are dropped.

◆ error_count()

size_t cs::compunit::error_count ( ) const

inline

Get the number of errors encountered in compiling a compilation unit.

Returns: The aggregate number of errors for the compilation unit.

Exceptions

result::ERROR_COUNT_UNKNOWN
result::ERROR_COUNT_UNKNOWN_BUT_POSITIVE

◆ get_address_for_section_offset()

effective_address cs::compunit::get_address_for_section_offset	(	const std::string &	sec_name,
		csuint32	sec_offset
	)

inline

[Binary analyses only] Returns the address that corresponds to the given (section, offset) location in this compilation unit.

Parameters

[in]	sec_name	The name of the section containing the address.
[in]	sec_offset	The offset of the address within the section.

Returns: The address corresponding to offset sec_offset in section sec_name.

Exceptions

result::NOT_IMPLEMENTED	if the CodeSonar installation does not include binary analysis functionality.
result::ELEMENT_NOT_PRESENT	if `this` is not a binary compunit, if `sec_name` does not correspond to a section in `this`, or if the offset is beyond the given section's size.
result::TRUNCATED	if more than one section with the specified name and offset is found.

◆ get_ast()

ast cs::compunit::get_ast ( ast_family family = ast_family::DEFAULT ) const

inline

Get the AST (of the specified ast_family) for a compilation unit.

Parameters

[in] family The compilation unit may have multiple ASTs from different families. This specifies which one to get.

Returns: The ast of ast_family family for the compunit.

Exceptions

result::ERROR_INVALID_ARGUMENT	if `family` is not a valid ast_family.
result::ELEMENT_NOT_PRESENT	if the compilation unit has no such AST.

◆ get_group_uid()

csuint32 cs::compunit::get_group_uid ( ) const

inline

Get the group to which a compilation unit belongs.

Returns: The Group UID for the compilation unit.

The Group UID for a compilation unit is determined as follows.

For a C or C++ compilation unit U, the Group UID will always match the compilation unit UID returned by U.id().
For a Java compilation unit U, the Group UID is the first compilation unit UID encountered during the cs-java-scan invocation that produced U. This may be an existing compilation unit UID for a .java file that is being reanalyzed, or a new UID produced for a .java file that does not already have a corresponding compilation unit in the project.
For a C# compilation unit U, the situation is analogous to that for Java: the Group UID is the first compilation unit UID encountered during the cs-dotnet-scan invocation that produced U.

For example, suppose cs-java-scan is invoked on a file J.jar containing two class files: A.class and B.class. Then:

Two compilation units will be produced from this invocation: one for A.class and one for B.class. We will refer to the corresponding compunit objects as UA and UB, respectively.
These two compilation units constitute a group, because they were produced by the same cs-java-scan invocation.
The group UID of the group matches either UA.id() or UB.id(), depending on whether A.class or B.class was encountered first during the cs-java-scan invocation.

Additional notes:

Group UIDs and invocations of cs-java-scan / cs-dotnet-scan / C/C++ compiler are not in one-to-one correspondence in general.
Do not interpret the returned value as a compilation unit identifier, for example by passing it as the argument to project::find_compunit(). Depending on the sequence of events during the CodeSonar project build phase, it may no longer refer to a compilation unit that is present in the project.
For Java and C#, the group UID for a compilation unit can change as the project is built. In particular, if the same artifact is built into the CodeSonar project multiple times via multiple invocations of cs-java-scan or cs-dotnet-scan, the first compilation unit encountered is not necessarily the same each time.

For example, say A.class is encountered first in an earlier invocation of cs-bin-scan on J.jar. Then the group UID for the compilation units corresponding to A.class and B.class will match UA.id(). If A.class is then removed from J.jar and cs-bin-scan is invoked again, B.class will be encountered first (because it is the only class left) and so the group UID for the compilation unit corresponding to B.class is updated to match UB.id().
For C and C++, the group UID of an existing compilation unit does not change, and will always match the compilation unit UID.

◆ get_language()

language cs::compunit::get_language ( ) const

inline

Get the source language of a compilation unit.

Returns: The compilation unit language : identifies the front end used to build the compilation unit and the source language the compilation unit is in.

◆ get_sfileinst()

sfileinst cs::compunit::get_sfileinst ( ) const

inline

Get the root source file instance of a compilation unit.

Returns: The root source file instance (sfileinst). This can be thought of as the root of the include tree for that compilation unit (for example, the .c file containing main).

Exceptions

result::GENERATED_COMPILATION if the compilation unit was generated in the back end.

◆ global_symbols()

compunit_global_iterator cs::compunit::global_symbols ( ) const

inline

Get an iterator over the global symbols (symbol) in a compilation unit.

Returns: The initialized iterator.

◆ handle()

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

inline

Get a handle for this compilation unit.

Returns: The compilation unit's handle.

Use this function to retrieve a handle to a compilation unit (compunit) which can be stored externally and used with project::lookup_compunit_handle() to retrieve the compilation unit 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 "_".

◆ hash()

cs_hash_t cs::compunit::hash ( ) const

inline

Get a hash value for a compunit.

◆ id()

csuint32 cs::compunit::id ( ) const

inline

Get the unique identifier of a compilation unit.

Returns: The unique identifier.

In an incremental analysis, a compilation unit will have the same identifier that it did in the incremental parent if and only if the compilation unit is not recompiled.
If the compilation unit is recompiled, it will have a new unique identifier not previously used for any compilation unit in any incremental ancestor analysis. In all other cases identifiers do not persist between different analyses of the same project (or the same code in a different project).

To get a compilation unit given its ID, use project::find_compunit().

◆ is_backend()

bool cs::compunit::is_backend ( ) const

inline

Check: does a compunit object correspond to a compilation unit generated by the back end to hold #System_Initialization and undefined functions?

Returns: true if the object corresponds to a back end compilation unit, false if it does not.

◆ is_hidden_binary()

bool cs::compunit::is_hidden_binary ( ) const

inline

[CodeSonar for Binaries only] Check: is a compilation unit an 'offstage binary' (that is, one that is analyzed but not included in results)?

Returns: true if the compilation unit is an offstage binary, false if it is not.

Exceptions

result::GENERATED_COMPILATION if the compilation unit was generated in the back end.

◆ is_library_model()

bool cs::compunit::is_library_model ( ) const

inline

Check: does a compunit object correspond to a compilation unit for a library model shipped with CodeSonar or CodeSurfer?

Returns: true if the object corresponds to a library model compilation unit; false if it does not.

◆ is_rewriting()

bool cs::compunit::is_rewriting ( ) const

inline

Check: does a compunit object correspond to a rewriting compilation unit ?

Returns: true if the object corresponds to a rewriting compilation unit, false if it does not.

◆ is_shared()

bool cs::compunit::is_shared ( ) const

inline

Check: can a compilation unit be shared by multiple projects and analyses?

Returns: true if the compilation can be shared, false otherwise.

Exceptions

result::GENERATED_COMPILATION if the compilation unit was generated in the back end.

Only compilation units for library models can be shared by multiple projects and analyses. This function checks whether a specific compilation unit fits into this category (it does not check whether any such sharing is currently occurring).

◆ is_user()

bool cs::compunit::is_user ( ) const

inline

Check: does a compunit object correspond to a user-generated compilation unit?

Returns: true if the object corresponds to a user-generated compilation unit, false otherwise.

This function will return false for the following kinds of compilation units.

Compilation units generated in the back end.
Library models.

◆ limit_reached()

bool cs::compunit::limit_reached ( ) const

inline

Check: did the front end reach any limits while parsing the specified compilation unit (which may have resulted in missing IR)?

Returns

A bool:

true if the front end encountered one or more limits (such as INITIALIZER_LIMIT, CONSTEXPR_CALL_DEPTH_LIMIT, AST_DEPTH_LIMIT) while processing the compilation unit. Part of the compilation unit internal representation (IR) may have been dropped in this case.
false if the front end did not encounter any of these limits while processing the compilation unit

Exceptions

result::GENERATED_COMPILATION if the compilation unit was generated in the back end.

◆ lookup_symbol()

symbol cs::compunit::lookup_symbol ( const std::string & name ) const

inline

Get a symbol from the compilation unit by name.

Parameters

[in] name The name of a symbol, as given by symbol::verbose_name(). Note that this does not necessarily match the code token for the symbol.

Returns: The symbol associated with name.

Exceptions

result::ERROR_SDG_NOT_PRESENT
result::ELEMENT_NOT_PRESENT	if no such symbol exists.

◆ name()

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

inline

Get the unnormalized file path corresponding to a compilation unit.

Returns: The unnormalized file path, if called on a compunit with an associated file path.

Use normalized_name() to get the normalized file path.

◆ normalized_name()

std::string cs::compunit::normalized_name ( ) const

inline

Get the normalized file path corresponding to a compilation unit.

Returns

The normalized file path, if called on a compunit with an associated file path.

Windows: this path is the downcased version of the one output by name(), with backslash directory separators replaced by forward slashes.
Otherwise: this path is the same as the one output by name().

Use name() to get the unnormalized file path.

◆ procedures()

compunit_procedure_iterator cs::compunit::procedures ( ) const

inline

Get an iterator over the procedures (procedure) in a compilation unit.

Returns: The initialized iterator.

◆ seen_wall_disable_flags()

std::vector< std::string > cs::compunit::seen_wall_disable_flags ( ) const

inline

Get the list of flags seen on the native command line that disable a subset of warnings for the compiler that compiled this compilation unit.

Returns: The front end command line, as a sequence of strings: one element for each command line token.

Exceptions

result::ELEMENT_NOT_PRESENT if the information is not available.

For example, -Wno-format-zero-length in gcc. The compiler model is responsible for populating this list and passing the information to the front-end.

◆ seen_werror_disable_flags()

std::vector< std::string > cs::compunit::seen_werror_disable_flags ( ) const

inline

Get the list of flags seen on the native command line that disable a subset of errors or cause warnings to not be treated as errors for the compiler that compiled this compilation unit.

Returns: The front end command line, as a sequence of strings: one element for each command line token.

Exceptions

result::ELEMENT_NOT_PRESENT if the information is not available.

For example, -Wno-error=declaration-missing-parameter-type in gcc. The compiler model is responsible for populating this list and passing the information to the front-end.

◆ warning_count()

size_t cs::compunit::warning_count ( ) const

inline

Get the number of warnings encountered in compiling a compilation unit.

Returns: The aggregate number of warnings for the compilation unit.

Exceptions

result::ERROR_COUNT_UNKNOWN
result::ERROR_COUNT_UNKNOWN_BUT_POSITIVE

Friends And Related Symbol Documentation

◆ operator!=()

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

Parameters

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

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

◆ operator<()

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

Parameters

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

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

◆ operator<<()

std::ostream & operator<<	(	std::ostream &	out,
		const compunit &	a
	)

Parameters

[in]	out	The stream to print to.
[in]	a	The compunit object to print.

Returns: void

◆ operator<=()

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

Parameters

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

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

◆ operator==()

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

Parameters

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

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

◆ operator>()

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

Parameters

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

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

◆ operator>=()

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

Parameters

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

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

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

Public Member Functions

Related Symbols

Detailed Description

Member Function Documentation

◆ as_repr()

◆ as_string()

◆ cmp()

◆ compiler_command_line()

◆ compiler_model()

◆ compiler_wall_enable_flags()

◆ compiler_werror_enable_flags()

◆ cs_frontend_command_line()

◆ csonar_front_end_run_id()

◆ effective_compiler_flags()

◆ error_count()

◆ get_address_for_section_offset()

◆ get_ast()

◆ get_group_uid()

◆ get_language()

◆ get_sfileinst()

◆ global_symbols()

◆ handle()

◆ hash()

◆ id()

◆ is_backend()

◆ is_hidden_binary()

◆ is_library_model()

◆ is_rewriting()

◆ is_shared()

◆ is_user()

◆ limit_reached()

◆ lookup_symbol()

◆ name()

◆ normalized_name()

◆ procedures()

◆ seen_wall_disable_flags()

◆ seen_werror_disable_flags()

◆ warning_count()

Friends And Related Symbol Documentation

◆ operator!=()

◆ operator<()

◆ operator<<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()