Name Cross-References

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

Description: Name Cross-References

The name cross-referencing infrastructure in CodeSonar provides extensive functionality for code navigation and searching. Applications include code search, the source code information window, and a cross-reference API.

Introduction
Terminology
Uses
Availability
More Name Cross-References Sections

Introduction

The CodeSonar cross-referencing infrastructure tracks all tokens in analyzed source code, with the following exceptions.

Reserved words in the source language, such as double and while, are not tracked. Exclusion is based on the source language for each compilation unit: tokens that are reserved words in C++ but not in C will be tracked in C compilation units (only).
String literals are tracked as a single token: their contents are not further tokenized.
The contents of comments are not tracked.
Tokens that appear in source files but are removed by the preprocessor in all source file instances are not tracked.
For Java and C# code, only tokens that originate in user code are tracked. Tokens that are defined in the respective language runtimes are not tracked.
For example:
```
// Java 
// - 'myarr' and 'arrLen' are tracked 
// - 'length' is not
int[] myarr = null;
int arrLen = 0;
// ...
arrLen = myarr.length;
```

In the remainder of this section we first introduce some terminology, then describe the cross-referencing information computed by CodeSonar and the various mechanisms provided for accessing that information.

Terminology

We use the following terminology.

token

References to tokens in discussions of name cross-reference should generally be understood to refer to the set of tracked tokens described in the introduction.

named entity

Any program element that has a name (which is a token). For example, individual variables, functions, and types can be (and generally are) named entities. CodeSonar cross-referencing tracks these names, distinguishing different entities with the same name and different occurrences of the same entity.

definition

A statement in which a named entity is defined.

occurrence

A single appearance of a token in source code.

occurrence tuple

A collection of information describing a single occurrence. Occurrence tuple properties are described in full below. These properties include details of the definition that the occurrence can be traced back to, the entity name and kind, the occurence location, and the usage of the entity in the occurrence.

kind

Categorizes an entity. The range of kinds associated with C and C++ programs includes type, namespace, function, variable, and so on. While an entity may have multiple different usages throughout a program, its kind is fixed.

usage

A property of an occurrence of an entity: describes the role the entity is undertaking in that context. For example, a variable may be written to in one occurrence, read from in another, used as a template argument in yet another, and so on. Entities of different kinds have different sets of possible usages.

kind-usage

A (valid) pair of kind and usage values. For descriptions and examples of all valid kind-usage pairs, see C and C++ Kinds and Usages.

Properties

The properties of an occurrence tuple are as follows.

Name
( Code Search Language field-name, if any)

Description

Token Name

The token that is occurring.

Kind
( kind)

Each named entity has a kind, which categorizes it. The range of kinds associated with C and C++ programs includes type, namespace, function, variable, and so on.

Usage
( usage)

Each occurrence of a named entity represents some usage of that entity: for example, reading from it, writing to it, using it as an argument to sizeof(), and so on.

File

The source file containing the token occurrence. The GUI and code search language provide direct access to several File properties:

File property	field-name	GUI Label
Directory	directory	Directory
File	file	File
File Path	path	Path

(For other properties of the source file, refer to the corresponding Source Listing page or issue an SQL query.)

Line
( occ_line)

The location in File of the token occurrence.

Definition File

The source file containing the token's definition. There may be multiple corresponding definitions, in which case there will be a separate tuple for each definition. The GUI and code search language provide direct access to several Definition File properties:

Definition File property	field-name	GUI Label
Directory	def_directory	Definition Directory
File	def_file	Definition File
File Path	def_path	Definition Path

(For other properties of the source file, refer to the corresponding Source Listing page or issue an SQL query.)

Definition Line
( def_line)

The location in Definition File of the token's definition.

Code

The contents of Line in File.

Uses

The CodeSonar web GUI provides name cross-reference information in several contexts.

The information window in warning reports and source listings provides cross-referencing information about a selected occurrence.
For searches in the code domain, queries specify desired properties of an occurrence tuple.
The cross-reference API provides programmatic access to name cross-reference infrastructure and information.

Availability

For space reasons, the CodeSonar analysis stores cross-referencing information for a project in the project analysis directory ( pfilesname.prj_files/), removing any previously-stored cross-referencing information before storing the new information. No cross-referencing information is stored on the hub.

For local-managed analyses, the CodeSonar build directory and analysis directory are the same directory.
If there are multiple analyses of the same project with the same build directory, the build directory and thus the analysis directory are reused.
For remote-managed analyses, the CodeSonar build directory is copied to a separate analysis directory at the beginning of the analysis phase.
There can be multiple analyses of the same build directory, but the analysis directory for each of these analyses will be distinct. In particular, the parent directory for each analysis directory is named with the analysis ID.

When an analysis A is local-managed, its build directory and analysis directory are the same directory. If there is a subsequent analysis B with the same build/analysis directory, the previous files will be overwritten and the hub will only be able to interact with cross-referencing information for analysis B unless the analysis is branched or deleted, or project analysis directory for A is restored from backup.

When an analysis A is remote-managed, its analysis directory is always unique and cannot be affected by future analyses. When such an analysis transitions to daemon mode, the hub will be able to interact with the cross-referencing information for analysis A even if there have been subsequent analyses of the same project.
If you want to take advantage of this behavior, specify the -remote or -remote-archive option in your build/analysis command.

For detailed description of the availability issues, see Procedures: Availability - the situation for cross-references is analogous.

More Name Cross-References Sections

API: Name Cross-References
C and C++ Kind-Usage Pairs
Code Search Language