tcov(1)tcov(1)NAMEtcov - source code test coverage analysis and statement-by-statement
profile
SYNOPSIStcov [ -a ] [ -n ] [ -o filename ] [ -p oldpath newpath ]
[ -x dir ] files ...
DESCRIPTIONtcov produces a test coverage analysis of a compiled program. tcov
takes source files as arguments and produces an annotated source list‐
ing. Each basic block of code (or each line if the -a option to tcov
is specified) is prefixed with the number of times it has been exe‐
cuted; lines that have not been executed are prefixed with "#####". A
basic block is a contiguous section of code that has no branches: each
statement in a basic block is executed the same number of times.
To use tcov, programs must be compiled with -xprofile=tcov or -xa com‐
piler 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 nor‐
mally 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 -xpro‐
file=tcov. When the program is run, coverage data is stored in pro‐
gram.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..
After running the program, annotated source files can be created with
the command: tcov-x dir sourcefile ... over each source file to cre‐
ate on file sourcefile.tcov in the current directory the coverage anal‐
ysis merged with its source file. A separate .tcov file is created for
each source file. dir is the directory containing test coverage data
created as a result of executing the program compiled with the "-xpro‐
file=tcov" option.
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 respec‐
tively. (See ENVIRONMENT below).
Each subsequent run accumulates more coverage data into the pro‐
gram.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 basic block of code.
-n Display table of the line numbers of the n most frequently exe‐
cuted 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 dif‐
ferent path when you run tcov than they had when you compiled
them. This frequently happens because you are using two differ‐
ent 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 -xa 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 spec‐
ifies where the file.d files will be written. At tcov run‐
time, 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_PROF‐
DATA_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 cover‐
age 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.tcov output 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 (includ‐
ing file extension: alpha.c.tcov )
See also SUN_PROFDATA_DIR and SUN_PROFDATA environment vari‐
ables above.
SEE ALSOcc(1), CC(1), f95(1)gprof(1), prof(1), and 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 -xa option produces unpre‐
dictable 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 cov‐
erage information to be saved in the .d file.
October 1997 tcov(1)
