NAME
tcov - source code test coverage analysis and source line
profile
SYNOPSIS
tcov [ -a ] [ -n ] [ -o filename ] [ -p oldpath newpath ]
-x profile_directory source_files ...
DESCRIPTION
tcov analyzes test coverage of compiled programs. tcov takes
source files as arguments and produces test coverage list-
ings 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 speci-
fied) 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 directory, which
is either created at compilation time or the first time that
the program is executed, depending on whether the optional
argument 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_PROFDATA_REPLACE. Details
on SUN_PROFDATA_REPLACE can be found in the manual 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 direc-
tory and one or more source files. tcov creates a test cov-
erage 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 fre-
quently executed 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 vari-
ables TCOVDIR or SUN_PROFDATA_DIR (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 profile_directory
This option specifies a profile directory containing
test coverage data accumulated by running a program
compiled with the -xprofile=tcov compiler flag.
profile_directory is the name of the directory con-
taining 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 current
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 com-
piled using -xprofile=collect 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 basename.
Setting SUN_PROFDATA has no effect on tcov itself.
FILES
program.profile
name of profile directory of program compiled
without specifying a profile directory at compila-
tion 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 environ-
ment variables above.
SEE ALSO
cc(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
directory contains no data.
NOTE
Programs that do not call exit(), return from main(), or use
asynchronous profile collection will not accumulate test
coverage data. Asynchronous profile collection is discussed
in the manual pages for cc(1), CC(1), and f95(1).