tcov(1)tcov(1)NAMEtcov - source code test coverage analysis and source line profile
SYNOPSIStcov [ -a ] [ -n ] [ -o filename ] [ -p oldpath newpath ]
-x profile_directory source_files ...
DESCRIPTIONtcov analyzes test coverage of compiled programs. tcov takes source
files as arguments and produces test coverage listings annotated with
execution counts as output. Execution counts in test coverage listings
are associated with "basic blocks" of compiled code, where a "basic
block" is a sequence of consecutive instructions that are always exe‐
cuted from start to finish.
Each source line beginning a new basic block of compiled code (or each
source line if the tcov option -a is specified) is prefixed in the test
coverage listing with the number of times that the source line's first
basic block has been executed. Source lines beginning a basic block
that has not been executed are prefixed in the listing with "#####".
To use tcov, one or more programs must be compiled and linked with the
compiler option -xprofile=tcov[:profile_directory], where the optional
profile_directory specifies the UNIX pathname of a directory in which
profile data are to be stored at execution time. If compilation and
linking are done in separate steps, the program should be linked using
the same -xprofile option used in the compilation step; ld should not
be used directly.
Each time a program compiled with -xprofile=tcov[:profile_directory] is
executed, execution profile counters are updated in a profile direc‐
tory, which is either created at compilation time or the first time
that the program is executed, depending on whether the optional argu‐
ment profile_directory was specified at compilation time.
When a change in an object file is detected at execution time, profile
counters for the changed object file are reset to 0. The extent of the
set of profile counters reset to 0 upon detection of a changed object
file can be modified using the environment variable SUN_PROF‐
DATA_REPLACE. Details on SUN_PROFDATA_REPLACE can be found in the man‐
ual pages for cc(1), CC(1), or f95(1).
After a program compiled with -xprofile=tcov[:profile_directory] has
been executed at least once, tcov can be run with a specified profile
directory and one or more source files. tcov creates a test coverage
listing annotated with execution counts for each source file, using
data from the profile directory. The test coverage listing is written
to a file named source_file.tcov, where source_file is the source
file's UNIX basename.
The location of a profile directory containing valid profile data must
be specified using the tcov-x profile_directory option, optionally
qualified by setting the environment variable SUN_PROFDATA_DIR. See
ENVIRONMENT below.
OPTIONS-a Display an execution count for each source line; if -a is not
specified, an execution count is displayed only for the first
source line of each basic block of code.
-n Display table of the line numbers of the n most frequently exe‐
cuted source lines 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 by
either of the environment variables TCOVDIR or SUN_PROFDATA_DIR
(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 profile_directory
This option specifies a profile directory containing test cover‐
age data accumulated by running a program compiled with the
-xprofile=tcov compiler flag. profile_directory is the name of
the directory containing test coverage data. Typically, this
will be program.profile/ where program is the name of the com‐
piled executable file. (For example, a.out.profile).
EXAMPLES
The following example creates a profile directory named
/var/demo/data.profile when the program a.out is compiled:
demo% cc -xprofile=tcov:/var/demo/data.profile alpha.c beta.c gamma.c
demo% ./a.out
demo% tcov-x /var/demo/data.profile alpha.c beta.c gamma.c
demo% cat alpha.c.tcov beta.c.tcov gamma.c.tcov
The following example creates a profile directory named
a.out.profile in the current working directory when the
program a.out is run for the first time:
demo% cc -xprofile=tcov alpha.c beta.c gamma.c
demo% ./a.out
demo% tcov-x a.out.profile alpha.c beta.c gamma.c
demo% cat alpha.c.tcov beta.c.tcov gamma.c.tcov
ENVIRONMENT
TCOVDIR Same as SUN_PROFDATA_DIR below.
SUN_PROFDATA_DIR
If SUN_PROFDATA_DIR is set, its value specifies the UNIX
pathname of the directory where tcov looks for the profile
directory and writes test coverage listing files. If
SUN_PROFDATA_DIR is not set, tcov looks for the profile
directory and writes test coverage listing files in the cur‐
rent working directory.
If both TCOVDIR and SUN_PROFDATA_DIR are set, a warning is
issued and SUN_PROFDATA_DIR is used.
SUN_PROFDATA
If SUN_PROFDATA is set, its value specifies the name of the
profile directory of a program compiled using -xprofile=col‐
lect or -xprofile=tcov without a specified profile directory.
If SUN_PROFDATA is not set, the name of the profile directory
is program.profile, where program is the program's UNIX base‐
name.
Setting SUN_PROFDATA has no effect on tcov itself.
FILES
program.profile
name of profile directory of program compiled without speci‐
fying a profile directory at compilation time
source_file.tcov
test coverage listing file; includes source file suffix, for
example: alpha.c.tcov
See also SUN_PROFDATA_DIR and SUN_PROFDATA environment variables
above.SEE ALSOcc(1), CC(1), f95(1)gprof(1), prof(1), and exit(2)DIAGNOSTICS
"no data for source file in profile_directory"
Issued for source files for which the specified profile direc‐
tory contains no data.
NOTE
Programs that do not call exit(), return from main(), or use asynchro‐
nous profile collection will not accumulate test coverage data. Asyn‐
chronous profile collection is discussed in the manual pages for cc(1),
CC(1), and f95(1).
May 2010 tcov(1)
