Get the Information

This chapter explains how to extract some information from the analyzed project using the tis-info plug-in and other external scripts. The tis-info plug-in provides options to generate textual files containing information about functions, variables, properties and statements. Filters can be used to extract specific information from the these files.

Some pieces of information are purely syntactic while some others are of semantic nature. The semantic information is only available if the project which was used to generate the files holds the value analysis results.

For an exact and up-to-date description of each generated piece of information, please refer to the tis-info Manual.

Generate the CSV Files

The tis-info plug-in can be used to generate CSV files. The main options allow us to extract the information concerning:

  • functions: -info-csv-functions functions.csv
  • variables: -info-csv-variables variables.csv
  • properties: -info-csv-properties properties.csv
  • statements: -info-csv-statements statements.csv

For instance, in order to get the information about functions from a previously saved project project.state, the command line would be:

tis-analyzer -load project.state -info-csv-functions functions.csv

As mentioned before, the kind of obtained information (i.e. either purely syntactic or also semantic) will depend on whether the saved project includes the value analysis results or not.

In the generated CSV files, the information about each element is printed on a single line (with comma separated fields). Hence, the files can be opened in a spreadsheet tool for easy selection of elements. Moreover, this format can be easily grepped (i.e. filtered using the grep utility), for instance, the following command returns all the information about the function funname:

grep funname functions.csv

In order to filter on a specified column, the awk tool is also very practical. For instance, the following command returns only the lines where the word valid appears in the fifth column:

awk -F, '! ($5~"valid") {print}' properties.cvs

Also, awk can be used to easily extract only some of the columns:

awk -F, '{print $4 $5}' properties.cvs

Information about the Functions

The generated file functions.csv provides information about the functions. It contains the list of both defined and declared functions appearing in the analyzed source code, including their locations, whether they are called or not, are they reachable in the analyzed context, etc. The most useful piece of information here concerns the coverage and it is detailed just below.

Information about the Coverage

Coverage from a Single Analysis

The coverage of each function can be found in the appropriate column of the functions.csv file. Note, that this information is semantic of nature and thus only available if the value analysis results have been computed.

At this point, the internal functions are usually not interesting and they can be filtered out with:

grep -v TIS_KERNEL_SHARE

The easiest approach then might be to check first the completely unreachable functions:

grep ", unreachable,"

And the completely covered ones:

grep -v ", unreachable," | grep -v "100.0%"

Then the GUI can be used to explore the dead code of the functions that are not totally covered in order to verify if this is intended or not.

Coverage from Several Analyses

If the information about the code coverage comes from several separate analyses, the generated functions.csv file is not sufficient anymore to measure the real coverage of functions, since it represents only the results extracted from only one project out of many. Because of this issue, the tis-aggregate tool provides a coverage command to extract all the relevant information from the functions.csv files and compile it into overall coverage results that can be presented in the CSV format:

tis-aggregate coverage project.aggreg  >  coverage.csv

Here, project.aggreg is a file that gives the base name of the analyses to consider. For instance:

path_1/proj_1
path_2/proj_2
...
path_n/proj_n

The tool then process information from the path_i/proj_i_functions.csv files.

This tool also provides some more options, such as presenting the results in HTML format (see the Tis-aggregate Manual).

Information about the Properties

The location and status of each property can be found in the properties.csv file. If the names given to the user annotations follow some naming conventions (see Naming the Annotations), it is quite easy to use grep to extract more precise information that file.

For instance, if the names of the annotations that should be proved by the WP plug-in all have a _wp suffix, it is easy to check if they are all verified with the following command:

grep "_wp," properties.csv | grep -v ", valid$"

Information about the Statements

The generated file statements.csv provides information about certain kinds of statements in the analyzed program.

For instance, it contains information about the function calls, in particular whether a specific call is direct or not. Moreover, if an indirect call has been encountered during the value analysis, it provides the list of all the possibly called functions. Extracting this information can be done with:

grep ", call," statements.csv | grep -v DIRECT

Some useful information concerning the condition values can also be found here. Especially, whether a condition happens to be always true or always false. This kind of situations is often also observable through the dead code, although not in all cases, since an if condition might be always true, but may have no else branch (which, obviously, would be dead if it existed).

Information about the Variables

The information about all the variables is available in the variables.csv generated file. The exception are the global variables which are not accessed or modified, since they are removed from the analysis results. This information can also be used, for instance, to easily find the location of the definition of a variable or to list all the static or volatile variables.