Tcov

tcov

Developer(s)	Oracle Corporation
Operating system	Solaris
Platform	SPARC
Type	Code coverage
License	Free for download and use as described in the Sun Studio product license.
Website	developers.sun.com

Tcov is a source code coverage analysis and statement-by-statement profiling tool for software written in Fortran, C and C++. Tcov generates exact counts of the number of times each statement in a program is executed and annotates source code to add instrumentation. It is a standard utility, provided free of cost with Sun Studio software.

The tcov utility gives information on how often a program executes segments of code. It produces a copy of the source file, annotated with execution frequencies. The code can be annotated at the basic block level or the source line level. As the statements in a basic block are executed the same number of times, a count of basic block executions equals number of times each statement in the block is executed. The tcov utility does not produce any time-based data.

Description

tcov produces a test coverage analysis of a compiled program. tcov takes source files as arguments and produces an annotated source listing. Each basic block of code (or each line if the particular option to tcov is specified) is prefixed with the number of times it has been executed; lines that have not been executed are prefixed with "#####".

The tcov utility also places a summary at the end of the annotated program listing. The statistics for the most frequently executed basic blocks are listed in order of execution frequency. The line number is the number of the first line in the block.

There are two implementations of tcov:

• Old Style coverage analysis: In this implementation, also known as tcov original, the compiler creates a coverage data file with the suffix .d for each object file. When program completes, the coverage data files are updated.
• New Style coverage analysis: In this implementation, also known as tcov enhanced, no additional files are created at compile time. Instead, directory is created to store the profile data, and a single coverage data file called tcovd is created in that directory.

Enhanced coverage analysis overcomes some of the shortcomings of the original analysis tool, such as:

• Provides more complete support for C++.
• Supports code found in #include header files and corrects a flaw that obscured coverage numbers for template classes and functions.
• More efficient runtime than the original tcov runtime.
• Supported for all the platforms that the compilers support.

Implementation

To generate annotated source code, following three steps are required:

• Code compilation with appropriate compiler option
• Program execution to accumulate profile data
• tcov command execution to generate annotated files

Each subsequent run accumulates more coverage data into the profile data file. Data for each object file is zeroed out the first time the program is executed after recompilation. Data for the entire program is zeroed by removing the tcovd file.

The above steps are explained for both original and enhanced tcov below:

Old Style coverage analysis

Source code is compiled with -xa option for C program and -a option for Fortran and C++ programs. The compiler creates a coverage data file with the suffix .d for each object file. The coverage data file is created in the directory specified by the environment variable TCOVDIR. If TCOVDIR is not set, the coverage data file is created in the current directory. The above instrumented build is run and at program completion, the .d files are updated. Finally, tcov command is run to generate the annotated source files. The syntax of the tcov command is as follows:

tcov options source-file-list

Here, source-file-list is a list of the source code filenames. For a list of options, The default output of tcov is a set of files, each with the suffix .tcov, which can be changed with the -o filename option.

A program compiled for code coverage analysis can be run multiple times (with potentially varying input); tcov can be used on the program after each run to compare behavior.

New Style coverage analysis

Source code is compiled with -xprofile=tcov option. Unlike original mode, enhanced tcov doesn't generate any files at compile time. The above instrumented build is run and at program completion, a directory is created to store the profile data, and a single coverage data file called tcovd is created in that directory. tcovd holds the information about the line numbers, and the execution count. It is a plain text file. By default, the directory is created in the location where program is run, and it is named after executable and suffixed by .profile. The directory is also known as the profile bucket. The location of profile bucket can be overridden by setting SUN_PROFDATA_DIR or SUN_PROFDATA environment variables. Finally, tcov command is run to generate the annotated source files. The syntax of the tcov command is same as for original command, except for the mandatory -x option.

tcov options -x profilebucket source-file-list

The only difference in command from original tcov is the mandatory addition is of -x dir option to denote enhanced tcov.

Example

The following program, written in C programming language, loops overs the integers 1 to 9 and tests their divisibility with the modulus (%) operator.

#include <stdio.h>

int
main (void)
{
  int i;

  for (i = 1; i < 10; i++)
    {
      if (i % 3 == 0)
        printf ("%d is divisible by 3\n", i);
      if (i % 11 == 0)
        printf ("%d is divisible by 11\n", i);
    }

  return 0;
}

To enable coverage testing the program must be compiled with the following options:

for old style code coverage,

cc -xa cov.c

and for new style code coverage,

cc -xprofile=tcov -o cov cov.c

where cov.c is the name of the program file. This creates an instrumented executable which contains additional instructions that record the number of times each line of the program is executed. -o option is used to set the name of the executable. The executable must then be run to create the coverage data. The creation and location of this file is different for old- and new- style code analysis. In old style analysis, this file with extension .d, created after compilation, either in TCOVDIR directory or current one, is updated with coverage data. In new style analysis, coverage data file, with name tcovd, is created in <executable name>.profile directory. This data can be analyzed using the tcov command and the name of a source file:

for old style code coverage,

tcov cov.c

and for new style code coverage,

tcov -x cov.profile cov.c

the addition argument in new style analysis is profile bucket. The tcov command produces an annotated version of the original source file, with the file extension ‘.tcov’, containing counts of the number of times each line was executed:

        #include <stdio.h>

        int
        main (void)
        {
     1    int i;

    10    for (i = 1; i < 10; i++)
            {
     9        if (i % 3 == 0)
     3          printf ("%d is divisible by 3\n", i);
     9        if (i % 11 == 0)
######          printf ("%d is divisible by 11\n", i);
     9      }

     1    return 0;
     1  }

The tcov utility also places a summary at the end of the annotated program listing. The statistics for the most frequently executed basic blocks are listed in order of execution frequency. The line number is the number of the first line in the block.

Command line options

Tcov command line utility supports following options while generating annotated files from profile data:

• -a: Display an execution count for each statement. If this option is not specified, then execution count is shown only for the leader of a code block.
• -n: Display table of the line numbers of the n most frequently executed statements and their execution counts.
• -o filename: Direct the output to filename instead of file.tcov. This option can be utilized to direct output to standard output by specifying -.
• -x dir: This is supported in new style coverage analysis. If this option is not specified, old style tcov coverage is assumed.

See also

• Sun Studio, compiler suite that provides Tcov
• Common Development and Distribution License
• Code coverage
• Gcov, code coverage tool provided by GCC