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 pro-
gram. tcov takes source files as arguments and produces an
annotated source listing. 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 executed; 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 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" cov-
erage 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 pro-
duces the file $TCOVDIR/file.d for each source file com-
piled. (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 anno-
tated 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 exe-
cuted 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 per-
form 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 create on file sourcefile.tcov in the
current directory the coverage analysis 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 "-xprofile=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 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 basic block of code.
-n Display table of the line numbers of the n most fre-
quently 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 dif-
ferent 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 com-
piled 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 specifies where the file.d
files will be written. At tcov runtime, it speci-
fies 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 vari-
ables 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.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 (including file extension: alpha.c.tcov )
See also SUN_PROFDATA_DIR and SUN_PROFDATA
environment variables above.
SEE ALSO
acc(1) (on SPARC platforms only), cc(1), CC(1), f77(1) and
f95(1) (on SPARC platforms only), gprof(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 -xa option pro-
duces 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.