uncover(1)uncover(1)NAMEuncover - Code Coverage Tool
SYNOPSISuncover
[-?] [-h] [-c] [-d dir] [-m {on|off}] [-o output_binary_file]
[-v] [-V] target
where target is the binary file for which the code coverage 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 coverage data is
generated and stored.
DESCRIPTIONuncover is a command line tool to measure code coverage of the user
applications. This tool can display information on areas of the appli‐
cation 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 execut‐
ing 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 Stu‐
dio 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 Studio compil‐
ers, 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 instruc‐
tions 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 exe‐
cuted or is redundant, 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.
OPTIONSuncover accepts the following options:
-? or -h
Output the help message.
-a Write error data to binary_name.analyze/coverage directory 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
generating 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 spec‐
ified, the default browser will be invoked to display the cover‐
age 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 dis‐
played 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 Performance Ana‐
lyzer 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 instru‐
mented 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.
EXAMPLES
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 gen‐
erated 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 generated 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 ALSOCC(1), cc(1), f95(1), gcc(1), g++(1).
August 2011 uncover(1)
