NAME
uncover - Code Coverage Tool
SYNOPSIS
uncover
[-?] [-h] [-c] [-d dir] [-m {on|off}] [-o
output_binary_file] [-v] [-V] target
where target is the binary file for which the code cov-
erage data is to be generated.
uncover
[-?] [-h] [-a] [-c] [-e {on|off}] [-H dir] [-n] [-t
file] [-v] [-V] target.uc
where target.uc is the directory where the code cover-
age data is generated and stored.
DESCRIPTION
uncover is a command line tool to measure code coverage of
the user applications. This tool can display information on
areas of the application being exercised during testing. The
coverage information reported by this tool could be at a
function, statement, basic block, or instruction level.
Measurements are done by first instrumenting the binaries,
then executing the binaries. After execution, the user can
query the coverage data based on the execution. The user can
execute the binaries multiple times, and the coverage data
will be the accumulation of these multiple executions.
uncover can be used with binaries generated by the Oracle
Solaris Studio 12.2 and Oracle Solaris 12.3 compilers for C,
C++, and Fortran, as well as the GCC for SPARC Systems,
hereafter referred to as 'gccfss'.
uncover works with any binary built with Oracle Solaris Stu-
dio compilers, but works best with binaries built with no
optimization option. (Previous releases of uncover required
at least the -O1 optimization level.) If your binary is
built with an optimization option, uncover results will be
better with lower optimization levels (-O1 or -O2). uncover
derives the source line level coverage by relating the
instructions to line numbers using the debug information
generated when the binary is built with the -g option. At
optimization levels -O3 and higher, the compiler might
delete some code that might never be executed or is redun-
dant, which might result in no binary instructions for some
source code lines. In such cases, no coverage information
will be reported for those lines. See the Discover and
Uncover User's Guide for more information.
OPTIONS
uncover accepts the following options:
-? or -h
Output the help message.
-a Write error data to binary_name.analyze/coverage direc-
tory for use by the Code Analyzer.
-c
Turn on reporting of execution counts for instructions,
blocks, and functions. By default only information on which
code is covered or not covered is reported. Specify this
option both when instrumenting your binary and when generat-
ing the coverage report.
-d dir
Create coverage data inside the specified directory dir. If
not specified, the current working directory is used. The
coverage data directory will be named target.uc underneath
the directory dir.
-e {on|off}
Turn on or off the invocation of the Performance Analyzer.
Default is on.
-H dir
Display the coverage data in HTML format inside dir. When
specified, the default browser will be invoked to display
the coverage data stored in dir.
-m {on|off}
When instrumenting your program, turns thread-safe profiling
on and off. Default is on. Use this option in combination
with the -c runtime option. If you instrument a binary that
uses threads with -m off, the binary fails at runtime and a
message is displayed asking you to reinstrument the binary
with -m on.
-n
Do not start the GUI viewer to display the coverage data.
When both -n and -H options are absent, the Studio Perfor-
mance Analyzer will be invoked to display the coverage data.
-o output_binary_file
Write the instrumented binary file to output_binary_file.
The default is to overwrite the input binary file with the
instrumented file.
-t file
Display the coverage data in ASCII text in the file file.
-v
Turn on the verbose mode, showing detailed info on steps of
the command.
-V
Print the current version.
Example #1
This example will instrument the binary a.out, next execute
the binary, and finally display the coverage data of a.out
stored in a.out.uc by invoking the Performance Analyzer.
% uncover a.out
% a.out
% uncover a.out.uc
NOTE: You only need to instrument the binary of interest
once.
Example #2
Similar to example #1, but the coverage data directory
a.out.uc is generated underneath the directory abc.
% uncover -d abc a.out
% a.out
% uncover abc/a.out.uc
Example #3
Similar to example #1, but the binary was executed three
times. The coverage data to be displayed are in HTML format
inside the directory a.out.html. The default browser will be
invoked to display this data.
% uncover a.out
% a.out; a.out; a.out
% uncover -H a.out.html a.out.uc
Example #4
The following is an example of an ASCII coverage report gen-
erated by Uncover:
% uncover -t unc.report a.out.uc
Creating experiment database a.out.er ...
% cat unc.report
UNCOVER Code Coverage
Total Functions: 6
Covered Functions: 3
Function Coverage: 50.0%
Total Executable Source Lines (Excludes redundant code removed by compiler): 38
Source Line Coverage: 57.9%
Total Basic Blocks: 19
Covered Basic Blocks: 11
Basic Block Coverage: 57.9%
Total Basic Block Executions: 11
Average Executions per Basic Block: 0.58
Total Instructions: 149
Covered Instructions: 75
Instruction Coverage: 50.3%
Total Instruction Executions: 75
Average Executions per Instruction: 0.50
Number of times this program was executed: 1
Functions sorted by metric: Exclusive Uncoverage
Excl. Excl. Excl. Excl. Excl. Name
Uncoverage Function Instr Block Instr
Count Exec Covered % Covered %
172 3 75 238 225 <Total>
80 0 0 0 0 t3
60 0 0 0 0 bar
32 0 0 0 0 t2
0 1 16 75 45 foo
0 1 51 63 80 main
0 1 8 100 100 t1
Instruction frequency data from experiment a.out.er
Instruction frequencies of /export/home1/uncover.demo/a.out.uc/a.out
Instruction Executed ()
TOTAL 75 (100.0)
float ops 0 ( 0.0)
float ld st 0 ( 0.0)
load store 12 ( 16.0)
load 8 ( 10.7)
store 4 ( 5.3)
-------------------------------------------
Instruction Executed () Annulled In Delay Slot
TOTAL 75 (100.0)
call 13 ( 17.3) 0 0
add 9 ( 12.0) 0 5
sethi 9 ( 12.0) 1 3
nop 7 ( 9.3) 0 7
br 6 ( 8.0) 0 0
lduw 6 ( 8.0) 0 0
or 5 ( 6.7) 0 2
subcc 5 ( 6.7) 0 0
stw 3 ( 4.0) 0 0
save 3 ( 4.0) 0 0
jmpl 3 ( 4.0) 0 0
restore 3 ( 4.0) 0 3
ldsb 2 ( 2.7) 0 1
stb 1 ( 1.3) 0 0
============================================================
SEE ALSO
CC(1), cc(1), f95(1), gcc(1), g++(1).