493 lines
20 KiB
HTML
493 lines
20 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html>
|
|
<!-- Copyright (C) 1988-2016 Free Software Foundation, Inc.
|
|
|
|
Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.3 or
|
|
any later version published by the Free Software Foundation; with the
|
|
Invariant Sections being "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 section entitled
|
|
"GNU Free Documentation License".
|
|
|
|
(a) The FSF's Front-Cover Text is:
|
|
|
|
A GNU Manual
|
|
|
|
(b) The FSF's Back-Cover Text is:
|
|
|
|
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. -->
|
|
<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
|
|
<head>
|
|
<title>Using the GNU Compiler Collection (GCC): Invoking Gcov</title>
|
|
|
|
<meta name="description" content="Using the GNU Compiler Collection (GCC): Invoking Gcov">
|
|
<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Invoking Gcov">
|
|
<meta name="resource-type" content="document">
|
|
<meta name="distribution" content="global">
|
|
<meta name="Generator" content="makeinfo">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<link href="index.html#Top" rel="start" title="Top">
|
|
<link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
|
|
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
|
|
<link href="Gcov.html#Gcov" rel="up" title="Gcov">
|
|
<link href="Gcov-and-Optimization.html#Gcov-and-Optimization" rel="next" title="Gcov and Optimization">
|
|
<link href="Gcov-Intro.html#Gcov-Intro" rel="prev" title="Gcov Intro">
|
|
<style type="text/css">
|
|
<!--
|
|
a.summary-letter {text-decoration: none}
|
|
blockquote.smallquotation {font-size: smaller}
|
|
div.display {margin-left: 3.2em}
|
|
div.example {margin-left: 3.2em}
|
|
div.indentedblock {margin-left: 3.2em}
|
|
div.lisp {margin-left: 3.2em}
|
|
div.smalldisplay {margin-left: 3.2em}
|
|
div.smallexample {margin-left: 3.2em}
|
|
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
|
|
div.smalllisp {margin-left: 3.2em}
|
|
kbd {font-style:oblique}
|
|
pre.display {font-family: inherit}
|
|
pre.format {font-family: inherit}
|
|
pre.menu-comment {font-family: serif}
|
|
pre.menu-preformatted {font-family: serif}
|
|
pre.smalldisplay {font-family: inherit; font-size: smaller}
|
|
pre.smallexample {font-size: smaller}
|
|
pre.smallformat {font-family: inherit; font-size: smaller}
|
|
pre.smalllisp {font-size: smaller}
|
|
span.nocodebreak {white-space:nowrap}
|
|
span.nolinebreak {white-space:nowrap}
|
|
span.roman {font-family:serif; font-weight:normal}
|
|
span.sansserif {font-family:sans-serif; font-weight:normal}
|
|
ul.no-bullet {list-style: none}
|
|
-->
|
|
</style>
|
|
|
|
|
|
</head>
|
|
|
|
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
|
|
<a name="Invoking-Gcov"></a>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Gcov-and-Optimization.html#Gcov-and-Optimization" accesskey="n" rel="next">Gcov and Optimization</a>, Previous: <a href="Gcov-Intro.html#Gcov-Intro" accesskey="p" rel="prev">Gcov Intro</a>, Up: <a href="Gcov.html#Gcov" accesskey="u" rel="up">Gcov</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
<hr>
|
|
<a name="Invoking-gcov"></a>
|
|
<h3 class="section">10.2 Invoking <code>gcov</code></h3>
|
|
|
|
<div class="smallexample">
|
|
<pre class="smallexample">gcov <span class="roman">[</span><var>options</var><span class="roman">]</span> <var>files</var>
|
|
</pre></div>
|
|
|
|
<p><code>gcov</code> accepts the following options:
|
|
</p>
|
|
|
|
<dl compact="compact">
|
|
<dt><code>-h</code></dt>
|
|
<dt><code>--help</code></dt>
|
|
<dd><p>Display help about using <code>gcov</code> (on the standard output), and
|
|
exit without doing any further processing.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-v</code></dt>
|
|
<dt><code>--version</code></dt>
|
|
<dd><p>Display the <code>gcov</code> version number (on the standard output),
|
|
and exit without doing any further processing.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-a</code></dt>
|
|
<dt><code>--all-blocks</code></dt>
|
|
<dd><p>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.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-b</code></dt>
|
|
<dt><code>--branch-probabilities</code></dt>
|
|
<dd><p>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 <samp>-u</samp> option is given.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-c</code></dt>
|
|
<dt><code>--branch-counts</code></dt>
|
|
<dd><p>Write branch frequencies as the number of branches taken, rather than
|
|
the percentage of branches taken.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-n</code></dt>
|
|
<dt><code>--no-output</code></dt>
|
|
<dd><p>Do not create the <code>gcov</code> output file.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-l</code></dt>
|
|
<dt><code>--long-file-names</code></dt>
|
|
<dd><p>Create long file names for included source files. For example, if the
|
|
header file <samp>x.h</samp> contains code, and was included in the file
|
|
<samp>a.c</samp>, then running <code>gcov</code> on the file <samp>a.c</samp> will
|
|
produce an output file called <samp>a.c##x.h.gcov</samp> instead of
|
|
<samp>x.h.gcov</samp>. This can be useful if <samp>x.h</samp> is included in
|
|
multiple source files and you want to see the individual
|
|
contributions. If you use the ‘<samp>-p</samp>’ option, both the including
|
|
and included file names will be complete path names.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-p</code></dt>
|
|
<dt><code>--preserve-paths</code></dt>
|
|
<dd><p>Preserve complete path information in the names of generated
|
|
<samp>.gcov</samp> files. Without this option, just the filename component is
|
|
used. With this option, all directories are used, with ‘<samp>/</samp>’ characters
|
|
translated to ‘<samp>#</samp>’ characters, <samp>.</samp> directory components
|
|
removed and unremoveable <samp>..</samp>
|
|
components renamed to ‘<samp>^</samp>’. This is useful if sourcefiles are in several
|
|
different directories.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-r</code></dt>
|
|
<dt><code>--relative-only</code></dt>
|
|
<dd><p>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.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-f</code></dt>
|
|
<dt><code>--function-summaries</code></dt>
|
|
<dd><p>Output summaries for each function in addition to the file level summary.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-o <var>directory|file</var></code></dt>
|
|
<dt><code>--object-directory <var>directory</var></code></dt>
|
|
<dt><code>--object-file <var>file</var></code></dt>
|
|
<dd><p>Specify either the directory containing the gcov data files, or the
|
|
object path name. The <samp>.gcno</samp>, and
|
|
<samp>.gcda</samp> 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.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-s <var>directory</var></code></dt>
|
|
<dt><code>--source-prefix <var>directory</var></code></dt>
|
|
<dd><p>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.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-u</code></dt>
|
|
<dt><code>--unconditional-branches</code></dt>
|
|
<dd><p>When branch probabilities are given, include those of unconditional branches.
|
|
Unconditional branches are normally not interesting.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-d</code></dt>
|
|
<dt><code>--display-progress</code></dt>
|
|
<dd><p>Display the progress on the standard output.
|
|
</p>
|
|
</dd>
|
|
<dt><code>-i</code></dt>
|
|
<dt><code>--intermediate-format</code></dt>
|
|
<dd><p>Output gcov file in an easy-to-parse intermediate text format that can
|
|
be used by <code>lcov</code> or other tools. The output is a single
|
|
<samp>.gcov</samp> file per <samp>.gcda</samp> file. No source code is required.
|
|
</p>
|
|
<p>The format of the intermediate <samp>.gcov</samp> file is plain text with
|
|
one entry per line
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample">file:<var>source_file_name</var>
|
|
function:<var>line_number</var>,<var>execution_count</var>,<var>function_name</var>
|
|
lcount:<var>line number</var>,<var>execution_count</var>
|
|
branch:<var>line_number</var>,<var>branch_coverage_type</var>
|
|
|
|
Where the <var>branch_coverage_type</var> is
|
|
notexec (Branch not executed)
|
|
taken (Branch executed and taken)
|
|
nottaken (Branch executed, but not taken)
|
|
|
|
There can be multiple <var>file</var> entries in an intermediate gcov
|
|
file. All entries following a <var>file</var> pertain to that source file
|
|
until the next <var>file</var> entry.
|
|
</pre></div>
|
|
|
|
<p>Here is a sample when <samp>-i</samp> is used in conjunction with <samp>-b</samp> option:
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample">file:array.cc
|
|
function:11,1,_Z3sumRKSt6vectorIPiSaIS0_EE
|
|
function:22,1,main
|
|
lcount:11,1
|
|
lcount:12,1
|
|
lcount:14,1
|
|
branch:14,taken
|
|
lcount:26,1
|
|
branch:28,nottaken
|
|
</pre></div>
|
|
|
|
</dd>
|
|
<dt><code>-m</code></dt>
|
|
<dt><code>--demangled-names</code></dt>
|
|
<dd><p>Display demangled function names in output. The default is to show
|
|
mangled function names.
|
|
</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<p><code>gcov</code> 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. <code>gcov</code> produces files called
|
|
<samp><var>mangledname</var>.gcov</samp> in the current directory. These contain
|
|
the coverage information of the source file they correspond to.
|
|
One <samp>.gcov</samp> file is produced for each source (or header) file
|
|
containing code,
|
|
which was compiled to produce the data files. The <var>mangledname</var> part
|
|
of the output file name is usually simply the source file name, but can
|
|
be something more complicated if the ‘<samp>-l</samp>’ or ‘<samp>-p</samp>’ options are
|
|
given. Refer to those options for details.
|
|
</p>
|
|
<p>If you invoke <code>gcov</code> 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>
|
|
<p>The <samp>.gcov</samp> files contain the ‘<samp>:</samp>’ separated fields along with
|
|
program source code. The format is
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample"><var>execution_count</var>:<var>line_number</var>:<var>source line text</var>
|
|
</pre></div>
|
|
|
|
<p>Additional block information may succeed each line, when requested by
|
|
command line option. The <var>execution_count</var> is ‘<samp>-</samp>’ for lines
|
|
containing no code. Unexecuted lines are marked ‘<samp>#####</samp>’ or
|
|
‘<samp>====</samp>’, depending on whether they are reachable by
|
|
non-exceptional paths or only exceptional paths such as C++ exception
|
|
handlers, respectively.
|
|
</p>
|
|
<p>Some lines of information at the start have <var>line_number</var> of zero.
|
|
These preamble lines are of the form
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample">-:0:<var>tag</var>:<var>value</var>
|
|
</pre></div>
|
|
|
|
<p>The ordering and number of these preamble lines will be augmented as
|
|
<code>gcov</code> development progresses — do not rely on them remaining
|
|
unchanged. Use <var>tag</var> to locate a particular preamble line.
|
|
</p>
|
|
<p>The additional block information is of the form
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample"><var>tag</var> <var>information</var>
|
|
</pre></div>
|
|
|
|
<p>The <var>information</var> is human readable, but designed to be simple
|
|
enough for machine parsing too.
|
|
</p>
|
|
<p>When printing percentages, 0% and 100% are only printed when the values
|
|
are <em>exactly</em> 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>
|
|
<p>When using <code>gcov</code>, you must first compile your program with two
|
|
special GCC options: ‘<samp>-fprofile-arcs -ftest-coverage</samp>’.
|
|
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>
|
|
<p>Running the program will cause profile output to be generated. For each
|
|
source file compiled with <samp>-fprofile-arcs</samp>, an accompanying
|
|
<samp>.gcda</samp> file will be placed in the object file directory.
|
|
</p>
|
|
<p>Running <code>gcov</code> 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 <samp>tmp.c</samp>, this
|
|
is what you see when you use the basic <code>gcov</code> facility:
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample">$ gcc -fprofile-arcs -ftest-coverage tmp.c
|
|
$ a.out
|
|
$ gcov tmp.c
|
|
90.00% of 10 source lines executed in file tmp.c
|
|
Creating tmp.c.gcov.
|
|
</pre></div>
|
|
|
|
<p>The file <samp>tmp.c.gcov</samp> contains output from <code>gcov</code>.
|
|
Here is a sample:
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample"> -: 0:Source:tmp.c
|
|
-: 0:Graph:tmp.gcno
|
|
-: 0:Data:tmp.gcda
|
|
-: 0:Runs:1
|
|
-: 0:Programs:1
|
|
-: 1:#include <stdio.h>
|
|
-: 2:
|
|
-: 3:int main (void)
|
|
1: 4:{
|
|
1: 5: int i, total;
|
|
-: 6:
|
|
1: 7: total = 0;
|
|
-: 8:
|
|
11: 9: for (i = 0; i < 10; i++)
|
|
10: 10: total += i;
|
|
-: 11:
|
|
1: 12: if (total != 45)
|
|
#####: 13: printf ("Failure\n");
|
|
-: 14: else
|
|
1: 15: printf ("Success\n");
|
|
1: 16: return 0;
|
|
-: 17:}
|
|
</pre></div>
|
|
|
|
<p>When you use the <samp>-a</samp> option, you will get individual block
|
|
counts, and the output looks like this:
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample"> -: 0:Source:tmp.c
|
|
-: 0:Graph:tmp.gcno
|
|
-: 0:Data:tmp.gcda
|
|
-: 0:Runs:1
|
|
-: 0:Programs:1
|
|
-: 1:#include <stdio.h>
|
|
-: 2:
|
|
-: 3:int main (void)
|
|
1: 4:{
|
|
1: 4-block 0
|
|
1: 5: int i, total;
|
|
-: 6:
|
|
1: 7: total = 0;
|
|
-: 8:
|
|
11: 9: for (i = 0; i < 10; i++)
|
|
11: 9-block 0
|
|
10: 10: total += i;
|
|
10: 10-block 0
|
|
-: 11:
|
|
1: 12: if (total != 45)
|
|
1: 12-block 0
|
|
#####: 13: printf ("Failure\n");
|
|
$$$$$: 13-block 0
|
|
-: 14: else
|
|
1: 15: printf ("Success\n");
|
|
1: 15-block 0
|
|
1: 16: return 0;
|
|
1: 16-block 0
|
|
-: 17:}
|
|
</pre></div>
|
|
|
|
<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
|
|
<samp>-b</samp> option is given.
|
|
</p>
|
|
<p>Because of the way GCC instruments calls, a call count can be shown
|
|
after a line with no individual blocks.
|
|
As you can see, line 13 contains a basic block that was not executed.
|
|
</p>
|
|
<p>When you use the <samp>-b</samp> option, your output looks like this:
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample">$ gcov -b tmp.c
|
|
90.00% of 10 source lines executed in file tmp.c
|
|
80.00% of 5 branches executed in file tmp.c
|
|
80.00% of 5 branches taken at least once in file tmp.c
|
|
50.00% of 2 calls executed in file tmp.c
|
|
Creating tmp.c.gcov.
|
|
</pre></div>
|
|
|
|
<p>Here is a sample of a resulting <samp>tmp.c.gcov</samp> file:
|
|
</p>
|
|
<div class="smallexample">
|
|
<pre class="smallexample"> -: 0:Source:tmp.c
|
|
-: 0:Graph:tmp.gcno
|
|
-: 0:Data:tmp.gcda
|
|
-: 0:Runs:1
|
|
-: 0:Programs:1
|
|
-: 1:#include <stdio.h>
|
|
-: 2:
|
|
-: 3:int main (void)
|
|
function main called 1 returned 1 blocks executed 75%
|
|
1: 4:{
|
|
1: 5: int i, total;
|
|
-: 6:
|
|
1: 7: total = 0;
|
|
-: 8:
|
|
11: 9: for (i = 0; i < 10; i++)
|
|
branch 0 taken 91% (fallthrough)
|
|
branch 1 taken 9%
|
|
10: 10: total += i;
|
|
-: 11:
|
|
1: 12: if (total != 45)
|
|
branch 0 taken 0% (fallthrough)
|
|
branch 1 taken 100%
|
|
#####: 13: printf ("Failure\n");
|
|
call 0 never executed
|
|
-: 14: else
|
|
1: 15: printf ("Success\n");
|
|
call 0 called 1 returned 100%
|
|
1: 16: return 0;
|
|
-: 17:}
|
|
</pre></div>
|
|
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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 <code>exit</code> or <code>longjmp</code>,
|
|
and thus may not return every time they are called.
|
|
</p>
|
|
<p>The execution counts are cumulative. If the example program were
|
|
executed again without removing the <samp>.gcda</samp> 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>
|
|
<p>The data in the <samp>.gcda</samp> files is saved immediately before the program
|
|
exits. For each source file compiled with <samp>-fprofile-arcs</samp>, the
|
|
profiling code first attempts to read in an existing <samp>.gcda</samp> 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.
|
|
</p>
|
|
<hr>
|
|
<div class="header">
|
|
<p>
|
|
Next: <a href="Gcov-and-Optimization.html#Gcov-and-Optimization" accesskey="n" rel="next">Gcov and Optimization</a>, Previous: <a href="Gcov-Intro.html#Gcov-Intro" accesskey="p" rel="prev">Gcov Intro</a>, Up: <a href="Gcov.html#Gcov" accesskey="u" rel="up">Gcov</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
|
|
</div>
|
|
|
|
|
|
|
|
</body>
|
|
</html>
|