| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> |
| <html> |
| <!-- Copyright (C) 1988-2015 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> |
