tcov - source code test coverage analysis and source line profile
tcov [ -a ] [ -n ] [ -o filename ] [ -p oldpath newpath ]
-x profile_directory source_files ...
tcov 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 executed 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 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 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.
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.
Display table of the line numbers of the n most frequently executed source lines and their execution counts.
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).
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.
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 containing test coverage data. Typically, this will be program.profile/ where program is the name of the compiled executable file. (For example, a.out.profile).
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.tcovExample 2 Create a profile directory in the current working directory.
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
Same as SUN_PROFDATA_DIR below.
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.
If SUN_PROFDATA is set, its value specifies the name of the profile directory of a program compiled 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.
name of profile directory of program compiled without specifying a profile directory at compilation time
test coverage listing file; includes source file suffix, for example: alpha.c.tcov
See also SUN_PROFDATA_DIR and SUN_PROFDATA environment variables above.
cc (1) , CC (1) , f95 (1) gprof (1) , prof (1) , exit (2)
Issued for source files for which the specified profile directory contains no data.
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) .