NAME

tcov − source code test coverage analysis and statement-by-statement profile

SYNOPSIS

tcov [ −a ] [ −n ] [ −o filename ] [ −p oldpath newpath ] [ −x dir ] files ...

DESCRIPTION

tcov produces a test coverage analysis of a compiled program.  tcov takes source files as arguments and produces an annotated source listing.  Each straight-line (basic block) segment of code (or each line if the -a 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 "#####". 

To use tcov, programs must be compiled with -xprofile=tcov or −xa compiler options. 

There are two implementations of tcov coverage analysis.  Compiling with the −xa option prepares the object code for the original "old style" coverage analysis. 

Compiling with the -xprofile=tcov compiler option and using the tcov -x dir option invokes the enhanced "new style" coverage analysis. 

In either case, the output is a copy of the source files annotated with statement execution counts in the margin. 

"Old Style" tcov Coverage Analysis:
Compile the program with the −xa compiler option.  This produces the file $TCOVDIR/file.d for each source file compiled.  (If environment variable TCOVDIR is not set, the .d files are stored in the current directory.) 

Run the program.  At program completion (the program must complete normally to produce the coverage analysis) the .d files are updated. To view the coverage analysis merged with the source files, run tcov on the source files. The annotated analysis file corresponding to each compiled source file is named $TCOVDIR/file.tcov. 

The output produced by tcov shows the number of times each statement or statement group was actually executed in this run.  With the tcov option -a, statements that were not executed are marked with ####-> to the left of the statement. 

"New Style" Enhanced tcov Analysis:
The preferred way to use tcov is to compile the program with -xprofile=tcov.  When the program is run, coverage data is stored in program.profile/tcovd, where program is the name of the executable file. (If the executable were the file a.out, the file a.out.profile/tcovd would be created.) 

Note that if compilation and linking are done in separate steps, include the same -xprofile option on the link step as appeared on the compile step, and use the compiler to perform the linking, not ld.. 

Run tcov -x dir file ... over each source file to create on file file.tcov in the current directory the coverage analysis merged with its source file. A separate .tcov file is created for each source file. 

Environment variables SUN_PROFDATA and SUN_PROFDATA_DIR can be used to specify where the intermediary data collection files are saved. These are the ∗.d and ∗.tcovd files created by old and new style tcov respectively. (See ENVIRONMENT below). 

Each subsequent run accumulates more coverage data into the program.profile/tcovd 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. 

OPTIONS

−a Display an execution count for each statement; if -a is not specified, an execution count is displayed only for the first statement of each straight-line (basic block) segment of code. 

−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.  If filename is "−", then direct the output to the standard output instead of file.tcov.  This option overrides any directory specified in the TCOVDIR environment variable (see ENVIRONMENT below). 

−p originalpath newpath
The -x option can get confused when the source files have a different path when you run tcov than they had when you compiled them.  This frequently happens because you are using two different machines that have different mount points for the same directory.  This option allows you to tell tcov that all source files that had a path prefix of originalpath at compile time, now have a path prefix of newpath at tcov runtime.  You may specify as many -p options as you wish. 

−x dir
"New style" tcov coverage analysis.  The source files must be compiled with the -xprofile=tcov compiler flag.  dir is the name of the directory where the coverage data is stored. Typically, this will be program.profile/ where program is the name of the compiled executable file. (For example, a.out.profile ).  If -x dir is not specified, "old style" tcov coverage is assumed. 

EXAMPLES

Old style tcov:

     demo% cc -o myprog -a alpha.c beta.c gamma.c
     demo% myprog      program execution
     demo% tcov -a alpha.c beta.c gamma.c
     demo% cat alpha.tcov beta.tcov gamma.tcov

New enhanced tcov:

     demo% cc -o myprog -xprofile=tcov alpha.c beta.c gamma.c
     demo% myprog      program execution
     demo% tcov -x myprog.profile alpha.c beta.c gamma.c
     demo% cat alpha.c.tcov beta.c.tcov gamma.c.tcov

ENVIRONMENT

TCOVDIR
"Old style" coverage analysis (without the −x option). If the TCOVDIR environment variable is set at compile time, it specifies where the file.d files will be written.  At tcov runtime, it specifies where to find the file.d and to write the file.tcov coverage analysis files.  It has no effect at the user-program’s runtime. 

"New style" coverage analysis (with the −x option).  Same as SUN_PROFDATA_DIR below. 

SUN_PROFDATA_DIR/SUN_PROFDATA
"New style" coverage analysis.  With these variables set, tcov writes performance coverage data to files in $SUN_PROFDATA_DIR/$SUN_PROFDATA/.  If set, $SUN_PROFDATA is used as the name of the directory read by tcov instead of program.profile.  In this case, the appropriate tcov command would be:

    demo% tcov -x $SUN_PROFDATA source_files...

If SUN_PROFDATA_DIR is set, it will look there for the coverage files, and not the current directory.  If both TCOVDIR and SUN_PROFDATA_DIR are set, a warning is issued and SUN_PROFDATA_DIR is used. 

FILES

Without -x flag (old style tcov):
file.d input test coverage data file created by compiler for each compiled source file
file.tcovoutput test coverage analysis listing file

With -x flag ( new style tcov):
myprog.profile/tcovd input test coverage data file
file.tcov output test coverage analysis listing file (including file extension: alpha.c.tcov )
See also SUN_PROFDATA_DIR and SUN_PROFDATA environment variables above. 

SEE ALSO

acc(1) cc(1), CC(1), f77(1), gprof(1), pc(1), prof(1), exit(2)

DIAGNOSTICS

premature end of file
Issued for routines containing no statements.

BUGS

Multiprocessor/Multithreaded programs with tcov:
Running an MP/MT program compiled with the -a (or -xa) option produces unpredictable behavior.  The
-xprofile=tcov option may be used with MP/MT programs, but the output of tcov is valid only for a zero or non-zero value.  The actual count may be incorrect. 

tcov does not support files which contain #line or #file directives. 

The analyzed program must call exit(2) or return normally for the coverage information to be saved in the .d file. 

SunOS 5.0  —  Last change: 13 Oct 1997