Description: Source Files

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.2p0

CONFIDENTIAL

CodeSecure Inc

C and C++

Binaries

Java

Description: Source Files

API functions provide access to information in project source files.

Language Module Support: Internal representation for compilation units, source files, and source file instances is available for C/C++, binary, C#, and Java analyses.

General Information Structure
Available Information
Links

General Information Structure

A project is a combination of compilation units. 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" and "file instances" because a given file may have multiple roles in a project. The top-level file instances and the include-file instances of a project are collectively known as source-file instances.

The following table summarizes the information stored about each compilation unit.

each...	...has an associated...	...that...
compilation unit	unique identifier (UID)	is assigned when the unit is (re)compiled
compilation unit	include tree	represents the inclusion relations among the file instances
source file	unique source-file identifier (SF)	is generated as needed and only remains valid for the duration of the browsing session.
	unnormalized file path	identifies its location in the file system
	normalized file path	is generated from the unnormalized file path as follows. Windows: normalized file path is the downcased version of the unnormalized file path, with backslash directory separators replaced by forward slashes. Mac: normalized file path is the downcased version of the unnormalized file path. Otherwise: normalized file path is the same as the unnormalized file path.
	directory	directly contains the source file
source file instance	unique source-file-instance identifier (SFID)	is generated as needed and only remains valid for the duration of the browsing session.
source file instance	include path	identifies its location in a compilation unit's include tree.
character in a source file	line and column	specifies its location within the file
character in a source file instance	offset	specifies its location within the compilation unit

Example

Suppose we build a project based on observing the following compilation:

gcc -c m.c

where the project source files are as follows.

/* m.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, representing the observed compilation of m.c.
Four source files: m.c, a.h, b.h, c.h.
Six source file instances:
- One instance of m.c: the top level file instance 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.

diagram showing example project structure

In a project with multiple compilation units, a single source file could have instances in more than one compilation unit.

Available Information

API functions provide access to compilation unit information as follows:

Given:	Return:
UID	Unnormalized file path and normalized file path for the unit's top-level file. Line count for the unit's top-level file. Language the unit is in. Number of compiler warnings and errors generated for the unit.
UID + include path	SFID for the corresponding include file instance.
UID + offset	SFID + line: the file instance, and line in that file instance, in which the character with the specified offset in the unit occurs. SFID + line + column: the file instance, and line and column in that file instance, in which the character with the specified offset in the unit occurs.
UID + offset1 + offset2	SFID1 + line1 + column1 + SFID2 + line2 + column2: file instances and line/column locations for two offsets at once (for example, for a character range).
SF	Directory for the file.
SFID	Include path for the file instance. Unnormalized file path and normalized file path for the file.
SFID + line	offset of the first character of the corresponding line in the unit to which the file instance belongs. offset1 + offset2: the offsets of the first and last characters of the corresponding line in the unit to which the file instance belongs.

Links

By API language:

C++	classes compunit, sfile , and sfileinst
Python	classes compunit, sfile , and sfileinst
C	Header cs_source_files.h provides functions and types for source files, file instances, and compilation units.