1220 lines
36 KiB
HTML
1220 lines
36 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of GCOV</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>GCOV</H1>
|
|
Section: GNU (1)<BR>Updated: 2020-03-12<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
gcov - coverage testing tool
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
gcov [<B>-v</B>|<B>--version</B>] [<B>-h</B>|<B>--help</B>]
|
|
<BR> [<B>-a</B>|<B>--all-blocks</B>]
|
|
<BR> [<B>-b</B>|<B>--branch-probabilities</B>]
|
|
<BR> [<B>-c</B>|<B>--branch-counts</B>]
|
|
<BR> [<B>-d</B>|<B>--display-progress</B>]
|
|
<BR> [<B>-f</B>|<B>--function-summaries</B>]
|
|
<BR> [<B>-i</B>|<B>--json-format</B>]
|
|
<BR> [<B>-j</B>|<B>--human-readable</B>]
|
|
<BR> [<B>-k</B>|<B>--use-colors</B>]
|
|
<BR> [<B>-l</B>|<B>--long-file-names</B>]
|
|
<BR> [<B>-m</B>|<B>--demangled-names</B>]
|
|
<BR> [<B>-n</B>|<B>--no-output</B>]
|
|
<BR> [<B>-o</B>|<B>--object-directory</B> <I>directory|file</I>]
|
|
<BR> [<B>-p</B>|<B>--preserve-paths</B>]
|
|
<BR> [<B>-q</B>|<B>--use-hotness-colors</B>]
|
|
<BR> [<B>-r</B>|<B>--relative-only</B>]
|
|
<BR> [<B>-s</B>|<B>--source-prefix</B> <I>directory</I>]
|
|
<BR> [<B>-t</B>|<B>--stdout</B>]
|
|
<BR> [<B>-u</B>|<B>--unconditional-branches</B>]
|
|
<BR> [<B>-x</B>|<B>--hash-filenames</B>]
|
|
<BR> <I>files</I>
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
<B>gcov</B> is a test coverage program. Use it in concert with <FONT SIZE="-1">GCC</FONT>
|
|
to analyze your programs to help create more efficient, faster running
|
|
code and to discover untested parts of your program. You can use
|
|
<B>gcov</B> as a profiling tool to help discover where your
|
|
optimization efforts will best affect your code. You can also use
|
|
<B>gcov</B> along with the other profiling tool, <B>gprof</B>, to
|
|
assess which parts of your code use the greatest amount of computing
|
|
time.
|
|
<P>
|
|
|
|
Profiling tools help you analyze your code's performance. Using a
|
|
profiler such as <B>gcov</B> or <B>gprof</B>, you can find out some
|
|
basic performance statistics, such as:
|
|
<DL COMPACT>
|
|
<DT id="1">*<DD>
|
|
how often each line of code executes
|
|
<DT id="2">*<DD>
|
|
what lines of code are actually executed
|
|
<DT id="3">*<DD>
|
|
how much computing time each section of code uses
|
|
</DL>
|
|
<P>
|
|
|
|
Once you know these things about how your code works when compiled, you
|
|
can look at each module to see which modules should be optimized.
|
|
<B>gcov</B> helps you determine where to work on optimization.
|
|
<P>
|
|
|
|
Software developers also use coverage testing in concert with
|
|
testsuites, to make sure software is actually good enough for a release.
|
|
Testsuites can verify that a program works as expected; a coverage
|
|
program tests to see how much of the program is exercised by the
|
|
testsuite. Developers can then determine what kinds of test cases need
|
|
to be added to the testsuites to create both better testing and a better
|
|
final product.
|
|
<P>
|
|
|
|
You should compile your code without optimization if you plan to use
|
|
<B>gcov</B> because the optimization, by combining some lines of code
|
|
into one function, may not give you as much information as you need to
|
|
look for `hot spots' where the code is using a great deal of computer
|
|
time. Likewise, because <B>gcov</B> accumulates statistics by line (at
|
|
the lowest resolution), it works best with a programming style that
|
|
places only one statement on each line. If you use complicated macros
|
|
that expand to loops or to other control structures, the statistics are
|
|
less helpful---they only report on the line where the macro call
|
|
appears. If your complex macros behave like functions, you can replace
|
|
them with inline functions to solve this problem.
|
|
<P>
|
|
|
|
<B>gcov</B> creates a logfile called <I>sourcefile.gcov</I> which
|
|
indicates how many times each line of a source file <I>sourcefile.c</I>
|
|
has executed. You can use these logfiles along with <B>gprof</B> to aid
|
|
in fine-tuning the performance of your programs. <B>gprof</B> gives
|
|
timing information you can use along with the information you get from
|
|
<B>gcov</B>.
|
|
<P>
|
|
|
|
<B>gcov</B> works only on code compiled with <FONT SIZE="-1">GCC.</FONT> It is not
|
|
compatible with any other profiling or test coverage mechanism.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
|
|
|
|
<DL COMPACT>
|
|
<DT id="4"><B>-a</B><DD>
|
|
|
|
|
|
|
|
<DT id="5"><B>--all-blocks</B><DD>
|
|
|
|
|
|
|
|
Write individual execution counts for every basic block. Normally gcov
|
|
outputs execution counts only for the main blocks of a line. With this
|
|
option you can determine if blocks within a single line are not being
|
|
executed.
|
|
<DT id="6"><B>-b</B><DD>
|
|
|
|
|
|
|
|
<DT id="7"><B>--branch-probabilities</B><DD>
|
|
|
|
|
|
|
|
Write branch frequencies to the output file, and write branch summary
|
|
info to the standard output. This option allows you to see how often
|
|
each branch in your program was taken. Unconditional branches will not
|
|
be shown, unless the <B>-u</B> option is given.
|
|
<DT id="8"><B>-c</B><DD>
|
|
|
|
|
|
|
|
<DT id="9"><B>--branch-counts</B><DD>
|
|
|
|
|
|
|
|
Write branch frequencies as the number of branches taken, rather than
|
|
the percentage of branches taken.
|
|
<DT id="10"><B>-d</B><DD>
|
|
|
|
|
|
|
|
<DT id="11"><B>--display-progress</B><DD>
|
|
|
|
|
|
|
|
Display the progress on the standard output.
|
|
<DT id="12"><B>-f</B><DD>
|
|
|
|
|
|
|
|
<DT id="13"><B>--function-summaries</B><DD>
|
|
|
|
|
|
|
|
Output summaries for each function in addition to the file level summary.
|
|
<DT id="14"><B>-h</B><DD>
|
|
|
|
|
|
|
|
<DT id="15"><B>--help</B><DD>
|
|
|
|
|
|
|
|
Display help about using <B>gcov</B> (on the standard output), and
|
|
exit without doing any further processing.
|
|
<DT id="16"><B>-i</B><DD>
|
|
|
|
|
|
|
|
<DT id="17"><B>--json-format</B><DD>
|
|
|
|
|
|
|
|
Output gcov file in an easy-to-parse <FONT SIZE="-1">JSON</FONT> intermediate format
|
|
which does not require source code for generation. The <FONT SIZE="-1">JSON</FONT>
|
|
file is compressed with gzip compression algorithm
|
|
and the files have <I>.gcov.json.gz</I> extension.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Structure of the <FONT SIZE="-1">JSON</FONT> is following:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
{
|
|
"current_working_directory": <current_working_directory>,
|
|
"data_file": <data_file>,
|
|
"format_version": <format_version>,
|
|
"gcc_version": <gcc_version>
|
|
"files": [<file>]
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Fields of the root element have following semantics:
|
|
<DL COMPACT><DT id="18"><DD>
|
|
<DL COMPACT>
|
|
<DT id="19">*<DD>
|
|
<I>current_working_directory</I>: working directory where
|
|
a compilation unit was compiled
|
|
<DT id="20">*<DD>
|
|
<I>data_file</I>: name of the data file (<FONT SIZE="-1">GCDA</FONT>)
|
|
<DT id="21">*<DD>
|
|
<I>format_version</I>: semantic version of the format
|
|
<DT id="22">*<DD>
|
|
<I>gcc_version</I>: version of the <FONT SIZE="-1">GCC</FONT> compiler
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="23"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Each <I>file</I> has the following form:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
{
|
|
"file": <file_name>,
|
|
"functions": [<function>],
|
|
"lines": [<line>]
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Fields of the <I>file</I> element have following semantics:
|
|
<DL COMPACT>
|
|
<DT id="24">*<DD>
|
|
<I>file_name</I>: name of the source file
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="25"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Each <I>function</I> has the following form:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
{
|
|
"blocks": <blocks>,
|
|
"blocks_executed": <blocks_executed>,
|
|
"demangled_name": "<demangled_name>,
|
|
"end_column": <end_column>,
|
|
"end_line": <end_line>,
|
|
"execution_count": <execution_count>,
|
|
"name": <name>,
|
|
"start_column": <start_column>
|
|
"start_line": <start_line>
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Fields of the <I>function</I> element have following semantics:
|
|
<DL COMPACT>
|
|
<DT id="26">*<DD>
|
|
<I>blocks</I>: number of blocks that are in the function
|
|
<DT id="27">*<DD>
|
|
<I>blocks_executed</I>: number of executed blocks of the function
|
|
<DT id="28">*<DD>
|
|
<I>demangled_name</I>: demangled name of the function
|
|
<DT id="29">*<DD>
|
|
<I>end_column</I>: column in the source file where the function ends
|
|
<DT id="30">*<DD>
|
|
<I>end_line</I>: line in the source file where the function ends
|
|
<DT id="31">*<DD>
|
|
<I>execution_count</I>: number of executions of the function
|
|
<DT id="32">*<DD>
|
|
<I>name</I>: name of the function
|
|
<DT id="33">*<DD>
|
|
<I>start_column</I>: column in the source file where the function begins
|
|
<DT id="34">*<DD>
|
|
<I>start_line</I>: line in the source file where the function begins
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="35"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that line numbers and column numbers number from 1. In the current
|
|
implementation, <I>start_line</I> and <I>start_column</I> do not include
|
|
any template parameters and the leading return type but that
|
|
this is likely to be fixed in the future.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Each <I>line</I> has the following form:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
{
|
|
"branches": [<branch>],
|
|
"count": <count>,
|
|
"line_number": <line_number>,
|
|
"unexecuted_block": <unexecuted_block>
|
|
"function_name": <function_name>,
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Branches are present only with <I>-b</I> option.
|
|
Fields of the <I>line</I> element have following semantics:
|
|
<DL COMPACT>
|
|
<DT id="36">*<DD>
|
|
<I>count</I>: number of executions of the line
|
|
<DT id="37">*<DD>
|
|
<I>line_number</I>: line number
|
|
<DT id="38">*<DD>
|
|
<I>unexecuted_block</I>: flag whether the line contains an unexecuted block
|
|
(not all statements on the line are executed)
|
|
<DT id="39">*<DD>
|
|
<I>function_name</I>: a name of a function this <I>line</I> belongs to
|
|
(for a line with an inlined statements can be not set)
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="40"><DD>
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Each <I>branch</I> has the following form:
|
|
|
|
|
|
<P>
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
{
|
|
"count": <count>,
|
|
"fallthrough": <fallthrough>,
|
|
"throw": <throw>
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Fields of the <I>branch</I> element have following semantics:
|
|
<DL COMPACT>
|
|
<DT id="41">*<DD>
|
|
<I>count</I>: number of executions of the branch
|
|
<DT id="42">*<DD>
|
|
<I>fallthrough</I>: true when the branch is a fall through branch
|
|
<DT id="43">*<DD>
|
|
<I>throw</I>: true when the branch is an exceptional branch
|
|
</DL>
|
|
</DL>
|
|
|
|
<DL COMPACT><DT id="44"><DD>
|
|
</DL>
|
|
|
|
<DT id="45"><B>-j</B><DD>
|
|
|
|
|
|
|
|
<DT id="46"><B>--human-readable</B><DD>
|
|
|
|
|
|
|
|
Write counts in human readable format (like 24.6k).
|
|
<DT id="47"><B>-k</B><DD>
|
|
|
|
|
|
|
|
<DT id="48"><B>--use-colors</B><DD>
|
|
|
|
|
|
|
|
Use colors for lines of code that have zero coverage. We use red color for
|
|
non-exceptional lines and cyan for exceptional. Same colors are used for
|
|
basic blocks with <B>-a</B> option.
|
|
<DT id="49"><B>-l</B><DD>
|
|
|
|
|
|
|
|
<DT id="50"><B>--long-file-names</B><DD>
|
|
|
|
|
|
|
|
Create long file names for included source files. For example, if the
|
|
header file <I>x.h</I> contains code, and was included in the file
|
|
<I>a.c</I>, then running <B>gcov</B> on the file <I>a.c</I> will
|
|
produce an output file called <I>a.c##x.h.gcov</I> instead of
|
|
<I>x.h.gcov</I>. This can be useful if <I>x.h</I> is included in
|
|
multiple source files and you want to see the individual
|
|
contributions. If you use the <B>-p</B> option, both the including
|
|
and included file names will be complete path names.
|
|
<DT id="51"><B>-m</B><DD>
|
|
|
|
|
|
|
|
<DT id="52"><B>--demangled-names</B><DD>
|
|
|
|
|
|
|
|
Display demangled function names in output. The default is to show
|
|
mangled function names.
|
|
<DT id="53"><B>-n</B><DD>
|
|
|
|
|
|
|
|
<DT id="54"><B>--no-output</B><DD>
|
|
|
|
|
|
|
|
Do not create the <B>gcov</B> output file.
|
|
<DT id="55"><B>-o</B> <I>directory|file</I><DD>
|
|
|
|
|
|
|
|
<DT id="56"><B>--object-directory</B> <I>directory</I><DD>
|
|
|
|
|
|
<DT id="57"><B>--object-file</B> <I>file</I><DD>
|
|
|
|
|
|
|
|
Specify either the directory containing the gcov data files, or the
|
|
object path name. The <I>.gcno</I>, and
|
|
<I>.gcda</I> data files are searched for using this option. If a directory
|
|
is specified, the data files are in that directory and named after the
|
|
input file name, without its extension. If a file is specified here,
|
|
the data files are named after that file, without its extension.
|
|
<DT id="58"><B>-p</B><DD>
|
|
|
|
|
|
|
|
<DT id="59"><B>--preserve-paths</B><DD>
|
|
|
|
|
|
|
|
Preserve complete path information in the names of generated
|
|
<I>.gcov</I> files. Without this option, just the filename component is
|
|
used. With this option, all directories are used, with <B>/</B> characters
|
|
translated to <B>#</B> characters, <I>.</I> directory components
|
|
removed and unremoveable <I>..</I>
|
|
components renamed to <B>^</B>. This is useful if sourcefiles are in several
|
|
different directories.
|
|
<DT id="60"><B>-q</B><DD>
|
|
|
|
|
|
|
|
<DT id="61"><B>--use-hotness-colors</B><DD>
|
|
|
|
|
|
|
|
Emit perf-like colored output for hot lines. Legend of the color scale
|
|
is printed at the very beginning of the output file.
|
|
<DT id="62"><B>-r</B><DD>
|
|
|
|
|
|
|
|
<DT id="63"><B>--relative-only</B><DD>
|
|
|
|
|
|
|
|
Only output information about source files with a relative pathname
|
|
(after source prefix elision). Absolute paths are usually system
|
|
header files and coverage of any inline functions therein is normally
|
|
uninteresting.
|
|
<DT id="64"><B>-s</B> <I>directory</I><DD>
|
|
|
|
|
|
|
|
<DT id="65"><B>--source-prefix</B> <I>directory</I><DD>
|
|
|
|
|
|
|
|
A prefix for source file names to remove when generating the output
|
|
coverage files. This option is useful when building in a separate
|
|
directory, and the pathname to the source directory is not wanted when
|
|
determining the output file names. Note that this prefix detection is
|
|
applied before determining whether the source file is absolute.
|
|
<DT id="66"><B>-t</B><DD>
|
|
|
|
|
|
|
|
<DT id="67"><B>--stdout</B><DD>
|
|
|
|
|
|
|
|
Output to standard output instead of output files.
|
|
<DT id="68"><B>-u</B><DD>
|
|
|
|
|
|
|
|
<DT id="69"><B>--unconditional-branches</B><DD>
|
|
|
|
|
|
|
|
When branch probabilities are given, include those of unconditional branches.
|
|
Unconditional branches are normally not interesting.
|
|
<DT id="70"><B>-v</B><DD>
|
|
|
|
|
|
|
|
<DT id="71"><B>--version</B><DD>
|
|
|
|
|
|
|
|
Display the <B>gcov</B> version number (on the standard output),
|
|
and exit without doing any further processing.
|
|
<DT id="72"><B>-w</B><DD>
|
|
|
|
|
|
|
|
<DT id="73"><B>--verbose</B><DD>
|
|
|
|
|
|
|
|
Print verbose informations related to basic blocks and arcs.
|
|
<DT id="74"><B>-x</B><DD>
|
|
|
|
|
|
|
|
<DT id="75"><B>--hash-filenames</B><DD>
|
|
|
|
|
|
|
|
When using <I>--preserve-paths</I>,
|
|
gcov uses the full pathname of the source files to create
|
|
an output filename. This can lead to long filenames that can overflow
|
|
filesystem limits. This option creates names of the form
|
|
<I>source-file##md5.gcov</I>,
|
|
where the <I>source-file</I> component is the final filename part and
|
|
the <I>md5</I> component is calculated from the full mangled name that
|
|
would have been used otherwise. The option is an alternative
|
|
to the <I>--preserve-paths</I> on systems which have a filesystem limit.
|
|
</DL>
|
|
<P>
|
|
|
|
<B>gcov</B> should be run with the current directory the same as that
|
|
when you invoked the compiler. Otherwise it will not be able to locate
|
|
the source files. <B>gcov</B> produces files called
|
|
<I>mangledname.gcov</I> in the current directory. These contain
|
|
the coverage information of the source file they correspond to.
|
|
One <I>.gcov</I> file is produced for each source (or header) file
|
|
containing code,
|
|
which was compiled to produce the data files. The <I>mangledname</I> part
|
|
of the output file name is usually simply the source file name, but can
|
|
be something more complicated if the <B>-l</B> or <B>-p</B> options are
|
|
given. Refer to those options for details.
|
|
<P>
|
|
|
|
If you invoke <B>gcov</B> with multiple input files, the
|
|
contributions from each input file are summed. Typically you would
|
|
invoke it with the same list of files as the final link of your executable.
|
|
<P>
|
|
|
|
The <I>.gcov</I> files contain the <B>:</B> separated fields along with
|
|
program source code. The format is
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
<execution_count>:<line_number>:<source line text>
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Additional block information may succeed each line, when requested by
|
|
command line option. The <I>execution_count</I> is <B>-</B> for lines
|
|
containing no code. Unexecuted lines are marked <B>#####</B> or
|
|
<B>=====</B>, depending on whether they are reachable by
|
|
non-exceptional paths or only exceptional paths such as C<FONT SIZE="-2">++</FONT> exception
|
|
handlers, respectively. Given the <B>-a</B> option, unexecuted blocks are
|
|
marked <B>$$$$$</B> or <B>%%%%%</B>, depending on whether a basic block
|
|
is reachable via non-exceptional or exceptional paths.
|
|
Executed basic blocks having a statement with zero <I>execution_count</I>
|
|
end with <B>*</B> character and are colored with magenta color with
|
|
the <B>-k</B> option. This functionality is not supported in Ada.
|
|
<P>
|
|
|
|
Note that <FONT SIZE="-1">GCC</FONT> can completely remove the bodies of functions that are
|
|
not needed --- for instance if they are inlined everywhere. Such functions
|
|
are marked with <B>-</B>, which can be confusing.
|
|
Use the <B>-fkeep-inline-functions</B> and <B>-fkeep-static-functions</B>
|
|
options to retain these functions and
|
|
allow gcov to properly show their <I>execution_count</I>.
|
|
<P>
|
|
|
|
Some lines of information at the start have <I>line_number</I> of zero.
|
|
These preamble lines are of the form
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
-:0:<tag>:<value>
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The ordering and number of these preamble lines will be augmented as
|
|
<B>gcov</B> development progresses --- do not rely on them remaining
|
|
unchanged. Use <I>tag</I> to locate a particular preamble line.
|
|
<P>
|
|
|
|
The additional block information is of the form
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
<tag> <information>
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The <I>information</I> is human readable, but designed to be simple
|
|
enough for machine parsing too.
|
|
<P>
|
|
|
|
When printing percentages, 0% and 100% are only printed when the values
|
|
are <I>exactly</I> 0% and 100% respectively. Other values which would
|
|
conventionally be rounded to 0% or 100% are instead printed as the
|
|
nearest non-boundary value.
|
|
<P>
|
|
|
|
When using <B>gcov</B>, you must first compile your program
|
|
with a special <FONT SIZE="-1">GCC</FONT> option <B>--coverage</B>.
|
|
This tells the compiler to generate additional information needed by
|
|
gcov (basically a flow graph of the program) and also includes
|
|
additional code in the object files for generating the extra profiling
|
|
information needed by gcov. These additional files are placed in the
|
|
directory where the object file is located.
|
|
<P>
|
|
|
|
Running the program will cause profile output to be generated. For each
|
|
source file compiled with <B>-fprofile-arcs</B>, an accompanying
|
|
<I>.gcda</I> file will be placed in the object file directory.
|
|
<P>
|
|
|
|
Running <B>gcov</B> with your program's source file names as arguments
|
|
will now produce a listing of the code along with frequency of execution
|
|
for each line. For example, if your program is called <I>tmp.cpp</I>, this
|
|
is what you see when you use the basic <B>gcov</B> facility:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
$ g++ --coverage tmp.cpp
|
|
$ a.out
|
|
$ gcov tmp.cpp -m
|
|
File 'tmp.cpp'
|
|
Lines executed:92.86% of 14
|
|
Creating 'tmp.cpp.gcov'
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The file <I>tmp.cpp.gcov</I> contains output from <B>gcov</B>.
|
|
Here is a sample:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
-: 0:Source:tmp.cpp
|
|
-: 0:Working directory:/home/gcc/testcase
|
|
-: 0:Graph:tmp.gcno
|
|
-: 0:Data:tmp.gcda
|
|
-: 0:Runs:1
|
|
-: 0:Programs:1
|
|
-: 1:#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
|
|
-: 2:
|
|
-: 3:template<class T>
|
|
-: 4:class Foo
|
|
-: 5:{
|
|
-: 6: public:
|
|
1*: 7: Foo(): b (1000) {}
|
|
------------------
|
|
Foo<char>::Foo():
|
|
#####: 7: Foo(): b (1000) {}
|
|
------------------
|
|
Foo<int>::Foo():
|
|
1: 7: Foo(): b (1000) {}
|
|
------------------
|
|
2*: 8: void inc () { b++; }
|
|
------------------
|
|
Foo<char>::inc():
|
|
#####: 8: void inc () { b++; }
|
|
------------------
|
|
Foo<int>::inc():
|
|
2: 8: void inc () { b++; }
|
|
------------------
|
|
-: 9:
|
|
-: 10: private:
|
|
-: 11: int b;
|
|
-: 12:};
|
|
-: 13:
|
|
-: 14:template class Foo<int>;
|
|
-: 15:template class Foo<char>;
|
|
-: 16:
|
|
-: 17:int
|
|
1: 18:main (void)
|
|
-: 19:{
|
|
-: 20: int i, total;
|
|
1: 21: Foo<int> counter;
|
|
-: 22:
|
|
1: 23: counter.inc();
|
|
1: 24: counter.inc();
|
|
1: 25: total = 0;
|
|
-: 26:
|
|
11: 27: for (i = 0; i < 10; i++)
|
|
10: 28: total += i;
|
|
-: 29:
|
|
1*: 30: int v = total > 100 ? 1 : 2;
|
|
-: 31:
|
|
1: 32: if (total != 45)
|
|
#####: 33: printf ("Failure\n");
|
|
-: 34: else
|
|
1: 35: printf ("Success\n");
|
|
1: 36: return 0;
|
|
-: 37:}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
Note that line 7 is shown in the report multiple times. First occurrence
|
|
presents total number of execution of the line and the next two belong
|
|
to instances of class Foo constructors. As you can also see, line 30 contains
|
|
some unexecuted basic blocks and thus execution count has asterisk symbol.
|
|
<P>
|
|
|
|
When you use the <B>-a</B> option, you will get individual block
|
|
counts, and the output looks like this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
-: 0:Source:tmp.cpp
|
|
-: 0:Working directory:/home/gcc/testcase
|
|
-: 0:Graph:tmp.gcno
|
|
-: 0:Data:tmp.gcda
|
|
-: 0:Runs:1
|
|
-: 0:Programs:1
|
|
-: 1:#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
|
|
-: 2:
|
|
-: 3:template<class T>
|
|
-: 4:class Foo
|
|
-: 5:{
|
|
-: 6: public:
|
|
1*: 7: Foo(): b (1000) {}
|
|
------------------
|
|
Foo<char>::Foo():
|
|
#####: 7: Foo(): b (1000) {}
|
|
------------------
|
|
Foo<int>::Foo():
|
|
1: 7: Foo(): b (1000) {}
|
|
------------------
|
|
2*: 8: void inc () { b++; }
|
|
------------------
|
|
Foo<char>::inc():
|
|
#####: 8: void inc () { b++; }
|
|
------------------
|
|
Foo<int>::inc():
|
|
2: 8: void inc () { b++; }
|
|
------------------
|
|
-: 9:
|
|
-: 10: private:
|
|
-: 11: int b;
|
|
-: 12:};
|
|
-: 13:
|
|
-: 14:template class Foo<int>;
|
|
-: 15:template class Foo<char>;
|
|
-: 16:
|
|
-: 17:int
|
|
1: 18:main (void)
|
|
-: 19:{
|
|
-: 20: int i, total;
|
|
1: 21: Foo<int> counter;
|
|
1: 21-block 0
|
|
-: 22:
|
|
1: 23: counter.inc();
|
|
1: 23-block 0
|
|
1: 24: counter.inc();
|
|
1: 24-block 0
|
|
1: 25: total = 0;
|
|
-: 26:
|
|
11: 27: for (i = 0; i < 10; i++)
|
|
1: 27-block 0
|
|
11: 27-block 1
|
|
10: 28: total += i;
|
|
10: 28-block 0
|
|
-: 29:
|
|
1*: 30: int v = total > 100 ? 1 : 2;
|
|
1: 30-block 0
|
|
%%%%%: 30-block 1
|
|
1: 30-block 2
|
|
-: 31:
|
|
1: 32: if (total != 45)
|
|
1: 32-block 0
|
|
#####: 33: printf ("Failure\n");
|
|
%%%%%: 33-block 0
|
|
-: 34: else
|
|
1: 35: printf ("Success\n");
|
|
1: 35-block 0
|
|
1: 36: return 0;
|
|
1: 36-block 0
|
|
-: 37:}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
In this mode, each basic block is only shown on one line --- the last
|
|
line of the block. A multi-line block will only contribute to the
|
|
execution count of that last line, and other lines will not be shown
|
|
to contain code, unless previous blocks end on those lines.
|
|
The total execution count of a line is shown and subsequent lines show
|
|
the execution counts for individual blocks that end on that line. After each
|
|
block, the branch and call counts of the block will be shown, if the
|
|
<B>-b</B> option is given.
|
|
<P>
|
|
|
|
Because of the way <FONT SIZE="-1">GCC</FONT> instruments calls, a call count can be shown
|
|
after a line with no individual blocks.
|
|
As you can see, line 33 contains a basic block that was not executed.
|
|
<P>
|
|
|
|
When you use the <B>-b</B> option, your output looks like this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
-: 0:Source:tmp.cpp
|
|
-: 0:Working directory:/home/gcc/testcase
|
|
-: 0:Graph:tmp.gcno
|
|
-: 0:Data:tmp.gcda
|
|
-: 0:Runs:1
|
|
-: 0:Programs:1
|
|
-: 1:#include <<A HREF="file:///usr/include/stdio.h">stdio.h</A>>
|
|
-: 2:
|
|
-: 3:template<class T>
|
|
-: 4:class Foo
|
|
-: 5:{
|
|
-: 6: public:
|
|
1*: 7: Foo(): b (1000) {}
|
|
------------------
|
|
Foo<char>::Foo():
|
|
function Foo<char>::Foo() called 0 returned 0% blocks executed 0%
|
|
#####: 7: Foo(): b (1000) {}
|
|
------------------
|
|
Foo<int>::Foo():
|
|
function Foo<int>::Foo() called 1 returned 100% blocks executed 100%
|
|
1: 7: Foo(): b (1000) {}
|
|
------------------
|
|
2*: 8: void inc () { b++; }
|
|
------------------
|
|
Foo<char>::inc():
|
|
function Foo<char>::inc() called 0 returned 0% blocks executed 0%
|
|
#####: 8: void inc () { b++; }
|
|
------------------
|
|
Foo<int>::inc():
|
|
function Foo<int>::inc() called 2 returned 100% blocks executed 100%
|
|
2: 8: void inc () { b++; }
|
|
------------------
|
|
-: 9:
|
|
-: 10: private:
|
|
-: 11: int b;
|
|
-: 12:};
|
|
-: 13:
|
|
-: 14:template class Foo<int>;
|
|
-: 15:template class Foo<char>;
|
|
-: 16:
|
|
-: 17:int
|
|
function main called 1 returned 100% blocks executed 81%
|
|
1: 18:main (void)
|
|
-: 19:{
|
|
-: 20: int i, total;
|
|
1: 21: Foo<int> counter;
|
|
call 0 returned 100%
|
|
branch 1 taken 100% (fallthrough)
|
|
branch 2 taken 0% (throw)
|
|
-: 22:
|
|
1: 23: counter.inc();
|
|
call 0 returned 100%
|
|
branch 1 taken 100% (fallthrough)
|
|
branch 2 taken 0% (throw)
|
|
1: 24: counter.inc();
|
|
call 0 returned 100%
|
|
branch 1 taken 100% (fallthrough)
|
|
branch 2 taken 0% (throw)
|
|
1: 25: total = 0;
|
|
-: 26:
|
|
11: 27: for (i = 0; i < 10; i++)
|
|
branch 0 taken 91% (fallthrough)
|
|
branch 1 taken 9%
|
|
10: 28: total += i;
|
|
-: 29:
|
|
1*: 30: int v = total > 100 ? 1 : 2;
|
|
branch 0 taken 0% (fallthrough)
|
|
branch 1 taken 100%
|
|
-: 31:
|
|
1: 32: if (total != 45)
|
|
branch 0 taken 0% (fallthrough)
|
|
branch 1 taken 100%
|
|
#####: 33: printf ("Failure\n");
|
|
call 0 never executed
|
|
branch 1 never executed
|
|
branch 2 never executed
|
|
-: 34: else
|
|
1: 35: printf ("Success\n");
|
|
call 0 returned 100%
|
|
branch 1 taken 100% (fallthrough)
|
|
branch 2 taken 0% (throw)
|
|
1: 36: return 0;
|
|
-: 37:}
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
For each function, a line is printed showing how many times the function
|
|
is called, how many times it returns and what percentage of the
|
|
function's blocks were executed.
|
|
<P>
|
|
|
|
For each basic block, a line is printed after the last line of the basic
|
|
block describing the branch or call that ends the basic block. There can
|
|
be multiple branches and calls listed for a single source line if there
|
|
are multiple basic blocks that end on that line. In this case, the
|
|
branches and calls are each given a number. There is no simple way to map
|
|
these branches and calls back to source constructs. In general, though,
|
|
the lowest numbered branch or call will correspond to the leftmost construct
|
|
on the source line.
|
|
<P>
|
|
|
|
For a branch, if it was executed at least once, then a percentage
|
|
indicating the number of times the branch was taken divided by the
|
|
number of times the branch was executed will be printed. Otherwise, the
|
|
message ``never executed'' is printed.
|
|
<P>
|
|
|
|
For a call, if it was executed at least once, then a percentage
|
|
indicating the number of times the call returned divided by the number
|
|
of times the call was executed will be printed. This will usually be
|
|
100%, but may be less for functions that call <TT>"exit"</TT> or <TT>"longjmp"</TT>,
|
|
and thus may not return every time they are called.
|
|
<P>
|
|
|
|
The execution counts are cumulative. If the example program were
|
|
executed again without removing the <I>.gcda</I> file, the count for the
|
|
number of times each line in the source was executed would be added to
|
|
the results of the previous run(s). This is potentially useful in
|
|
several ways. For example, it could be used to accumulate data over a
|
|
number of program runs as part of a test verification suite, or to
|
|
provide more accurate long-term information over a large number of
|
|
program runs.
|
|
<P>
|
|
|
|
The data in the <I>.gcda</I> files is saved immediately before the program
|
|
exits. For each source file compiled with <B>-fprofile-arcs</B>, the
|
|
profiling code first attempts to read in an existing <I>.gcda</I> file; if
|
|
the file doesn't match the executable (differing number of basic block
|
|
counts) it will ignore the contents of the file. It then adds in the
|
|
new execution counts and finally writes the data to the file.
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Using <B>gcov</B> with <FONT SIZE="-1">GCC</FONT> Optimization</H3>
|
|
|
|
|
|
|
|
If you plan to use <B>gcov</B> to help optimize your code, you must
|
|
first compile your program with a special <FONT SIZE="-1">GCC</FONT> option
|
|
<B>--coverage</B>. Aside from that, you can use any
|
|
other <FONT SIZE="-1">GCC</FONT> options; but if you want to prove that every single line
|
|
in your program was executed, you should not compile with optimization
|
|
at the same time. On some machines the optimizer can eliminate some
|
|
simple code lines by combining them with other lines. For example, code
|
|
like this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
if (a != b)
|
|
c = 1;
|
|
else
|
|
c = 0;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
can be compiled into one instruction on some machines. In this case,
|
|
there is no way for <B>gcov</B> to calculate separate execution counts
|
|
for each line because there isn't separate code for each line. Hence
|
|
the <B>gcov</B> output looks like this if you compiled the program with
|
|
optimization:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
100: 12:if (a != b)
|
|
100: 13: c = 1;
|
|
100: 14:else
|
|
100: 15: c = 0;
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
The output shows that this block of code, combined by optimization,
|
|
executed 100 times. In one sense this result is correct, because there
|
|
was only one instruction representing all four of these lines. However,
|
|
the output does not indicate how many times the result was 0 and how
|
|
many times the result was 1.
|
|
<P>
|
|
|
|
Inlineable functions can create unexpected line counts. Line counts are
|
|
shown for the source code of the inlineable function, but what is shown
|
|
depends on where the function is inlined, or if it is not inlined at all.
|
|
<P>
|
|
|
|
If the function is not inlined, the compiler must emit an out of line
|
|
copy of the function, in any object file that needs it. If
|
|
<I>fileA.o</I> and <I>fileB.o</I> both contain out of line bodies of a
|
|
particular inlineable function, they will also both contain coverage
|
|
counts for that function. When <I>fileA.o</I> and <I>fileB.o</I> are
|
|
linked together, the linker will, on many systems, select one of those
|
|
out of line bodies for all calls to that function, and remove or ignore
|
|
the other. Unfortunately, it will not remove the coverage counters for
|
|
the unused function body. Hence when instrumented, all but one use of
|
|
that function will show zero counts.
|
|
<P>
|
|
|
|
If the function is inlined in several places, the block structure in
|
|
each location might not be the same. For instance, a condition might
|
|
now be calculable at compile time in some instances. Because the
|
|
coverage of all the uses of the inline function will be shown for the
|
|
same source lines, the line counts themselves might seem inconsistent.
|
|
<P>
|
|
|
|
Long-running applications can use the <TT>"__gcov_reset"</TT> and <TT>"__gcov_dump"</TT>
|
|
facilities to restrict profile collection to the program region of
|
|
interest. Calling <TT>"__gcov_reset(void)"</TT> will clear all profile counters
|
|
to zero, and calling <TT>"__gcov_dump(void)"</TT> will cause the profile information
|
|
collected at that point to be dumped to <I>.gcda</I> output files.
|
|
Instrumented applications use a static destructor with priority 99
|
|
to invoke the <TT>"__gcov_dump"</TT> function. Thus <TT>"__gcov_dump"</TT>
|
|
is executed after all user defined static destructors,
|
|
as well as handlers registered with <TT>"atexit"</TT>.
|
|
If an executable loads a dynamic shared object via dlopen functionality,
|
|
<B>-Wl,--dynamic-list-data</B> is needed to dump all profile data.
|
|
<P>
|
|
|
|
Profiling run-time library reports various errors related to profile
|
|
manipulation and profile saving. Errors are printed into standard error output
|
|
or <B></B><FONT SIZE="-1"><B>GCOV_ERROR_FILE</B></FONT><B></B> file, if environment variable is used.
|
|
In order to terminate immediately after an errors occurs
|
|
set <B></B><FONT SIZE="-1"><B>GCOV_EXIT_AT_ERROR</B></FONT><B></B> environment variable.
|
|
That can help users to find profile clashing which leads
|
|
to a misleading profile.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+gpl">gpl</A></B>(7), <B><A HREF="/cgi-bin/man/man2html?7+gfdl">gfdl</A></B>(7), <B><A HREF="/cgi-bin/man/man2html?7+fsf-funding">fsf-funding</A></B>(7), <B><A HREF="/cgi-bin/man/man2html?1+gcc">gcc</A></B>(1) and the Info entry for <I>gcc</I>.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
|
|
|
|
Copyright (c) 1996-2019 Free Software Foundation, Inc.
|
|
<P>
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the <FONT SIZE="-1">GNU</FONT> Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being ``<FONT SIZE="-1">GNU</FONT> General Public License'' and ``Funding
|
|
Free Software'', the Front-Cover texts being (a) (see below), and with
|
|
the Back-Cover Texts being (b) (see below). A copy of the license is
|
|
included in the <B><A HREF="/cgi-bin/man/man2html?7+gfdl">gfdl</A></B>(7) man page.
|
|
<P>
|
|
|
|
(a) The <FONT SIZE="-1">FSF</FONT>'s Front-Cover Text is:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
A GNU Manual
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
(b) The <FONT SIZE="-1">FSF</FONT>'s Back-Cover Text is:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
You have freedom to copy and modify this GNU Manual, like GNU
|
|
software. Copies published by the Free Software Foundation raise
|
|
funds for GNU development.
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="76"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="77"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="78"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="79"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DL>
|
|
<DT id="80"><A HREF="#lbAF">Using <B>gcov</B> with <FONT SIZE="-1">GCC</FONT> Optimization</A><DD>
|
|
</DL>
|
|
<DT id="81"><A HREF="#lbAG">SEE ALSO</A><DD>
|
|
<DT id="82"><A HREF="#lbAH">COPYRIGHT</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:29 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|