NAME

tcov − construct test coverage analysis and statement-by-statement profile

SYNOPSIS

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

MT-Level

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

DESCRIPTION

This man page describes the updated tcov program called TCOV Enhanced. For a description of the original version of tcov, see the "Performance Profiling Tools" manual.  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 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 "#####". 

Without the -x option, tcov uses the corresponding file.d.  This is created at compile time when the −a flag is used in C++, pascal, and fortran, or the −xa option for C.  By default, the compilers create file.d in the same directory that the source file is located in.  The directory that file.d is created in can be overridden at compile time with the TCOVDIR environment variable (the location of file.d cannot be overridden at run time when you use the −xa or −a flags).  Each time the program is executed, test coverage information is accumulated in file.d.  The data for each object file is zeroed out the next time the corresponding source file is compiled. 

With the -x option, tcov uses the myprog.profile/tcovd file as data.  This file is created the first time a program that has object files compiled with the -xprofile=tcov flag is executed.  The value of myprog is the base name of the executable. 

By default, the name of the directory the tcov file is stored in is derived from the name of the executable.  Furthermore, that directory is created in the directory the executable was run in (the original tcov created the .d files in the directory the modules were compiled in). 

The name of the directory the tcovd file is stored in is also known as the "profile bucket". The profile bucket can be overridden by using the SUN_PROFDATA environment variable.  One case this might be useful for is if the name of the executable is not the same as the value in argv[0] (for example, the invocation of the executable was through a symbolic link with a different name). 

You can also override the directory the profile bucket is created in.  To specify a location different than the run directory, specify the path using the SUN_PROFDATA_DIR environment variable.  Note that either absolute or relative pathnames can be specified in this variable.  Relative pathnames are relative to the program’s current working directory. 

TCOVDIR is supported as a synonym for SUN_PROFDATA_DIR for the sake of backwards compatibility.  Any setting of SUN_PROFDATA_DIR causes TCOVDIR to be ignored.  If both SUN_PROFDATA_DIR and TCOVDIR are set, a warning is issued when the profile bucket is being generated.  It is used at runtime by a program compiled with -xprofile=tcov and it is used by the TCOV command. 

Each subsequent run accumulates more coverage data into the myprog.tcovd file.  Data for each object file is zeroed out the first time the program is executed after the corresponding source file has been recompiled.  Data for the entire program is zeroed out by removing the myprog.tcovd file. 

By default, the output is written to ./file.c.tcov, where "c" designates the compiler being used.  The directory to which this file is written can be overridden by using TCOVDIR.  Note that leading directory names are stripped from each source-file argument before the .cov file name is generated.  Alternatively, the output can be redirected by using the −o option. 

Note: the profile produced includes only the number of times each statement was executed, not execution times; to obtain times for routines use gprof(1) or prof(1). 

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 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 myprog
This option turns on the new tcov processing (specified by the -xprofile=tcov compiler flag) and also provides the name of the executable that is being analyzed.  If the TCOVDIR environment variable is not set, then with the argument of /foo/bar, tcov uses the coverage file in /foo/bar.profile/bar.tcovd.  If the TCOVDIR environment variable is set, then tcov uses the coverage file of $TCOVDIR/bar.tcovd. 

EXAMPLES

ENVIRONMENT

TCOVDIR
Without the −x option: if the TCOVDIR environment variable is set at compile time, it specifies the location of the file.d.  If it is set at tcov runtime, it specifies the location of file.d and file.tcov.  It has no effect at program runtime. 

With the −x option:  if the TCOVDIR environment variable is set at program runtime, then the a.out.tcovd is directed into that directory.  If it is set at tcov runtime, it  specifies the location of a.out.tcovd and file.tcov.  It has no effect at compile time. 

TCOVEXE
When set at runtime with the -xprofile=tcov option, this will specify the a.out name portion of the profiling data file.  That is, if the variable is set to myprog then the profile data will be stored in myprog.profile/myprog.tcovd (or if the TCOVDIR environment variable is set it will go into $TCOVDIR/myprog.tcovd). 

FILES

Without -x flag:
file.d input test coverage data file
file.tcovoutput test coverage analysis listing file

With -x flag:
myprog.profile/myprog.tcovd input test coverage data file
file.c.tcov output test coverage analysis listing file
See the use of the TCOVDIR and TCOVEXE environment variables for how these names can change.
bb_link.o entry and exit routines for test coverage analysis

SEE ALSO

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

DIAGNOSTICS

premature end of file
Issued for routines containing no statements.

NOTES

The count of basic blocks cannot exceed the value represented by an unsigned int. 

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

BUGS

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

SunOS 4.2  —  Last change: June 1996