| <html lang="en"> |
| <head> |
| <title>Invoking Gcov - Using the GNU Compiler Collection (GCC)</title> |
| <meta http-equiv="Content-Type" content="text/html"> |
| <meta name="description" content="Using the GNU Compiler Collection (GCC)"> |
| <meta name="generator" content="makeinfo 4.13"> |
| <link title="Top" rel="start" href="index.html#Top"> |
| <link rel="up" href="Gcov.html#Gcov" title="Gcov"> |
| <link rel="prev" href="Gcov-Intro.html#Gcov-Intro" title="Gcov Intro"> |
| <link rel="next" href="Gcov-and-Optimization.html#Gcov-and-Optimization" title="Gcov and Optimization"> |
| <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> |
| <!-- |
| Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 1998, |
| 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, |
| 2008 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.2 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.--> |
| <meta http-equiv="Content-Style-Type" content="text/css"> |
| <style type="text/css"><!-- |
| pre.display { font-family:inherit } |
| pre.format { font-family:inherit } |
| pre.smalldisplay { font-family:inherit; font-size:smaller } |
| pre.smallformat { font-family:inherit; font-size:smaller } |
| pre.smallexample { font-size:smaller } |
| pre.smalllisp { font-size:smaller } |
| span.sc { font-variant:small-caps } |
| span.roman { font-family:serif; font-weight:normal; } |
| span.sansserif { font-family:sans-serif; font-weight:normal; } |
| --></style> |
| <link rel="stylesheet" type="text/css" href="../cs.css"> |
| </head> |
| <body> |
| <div class="node"> |
| <a name="Invoking-Gcov"></a> |
| <p> |
| Next: <a rel="next" accesskey="n" href="Gcov-and-Optimization.html#Gcov-and-Optimization">Gcov and Optimization</a>, |
| Previous: <a rel="previous" accesskey="p" href="Gcov-Intro.html#Gcov-Intro">Gcov Intro</a>, |
| Up: <a rel="up" accesskey="u" href="Gcov.html#Gcov">Gcov</a> |
| <hr> |
| </div> |
| |
| <h3 class="section">10.2 Invoking <samp><span class="command">gcov</span></samp></h3> |
| |
| <pre class="smallexample"> gcov <span class="roman">[</span><var>options</var><span class="roman">]</span> <var>sourcefiles</var> |
| </pre> |
| <p><samp><span class="command">gcov</span></samp> accepts the following options: |
| |
| <!-- man begin OPTIONS --> |
| <dl> |
| <dt><code>-h</code><dt><code>--help</code><dd>Display help about using <samp><span class="command">gcov</span></samp> (on the standard output), and |
| exit without doing any further processing. |
| |
| <br><dt><code>-v</code><dt><code>--version</code><dd>Display the <samp><span class="command">gcov</span></samp> version number (on the standard output), |
| and exit without doing any further processing. |
| |
| <br><dt><code>-a</code><dt><code>--all-blocks</code><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. |
| |
| <br><dt><code>-b</code><dt><code>--branch-probabilities</code><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 <samp><span class="option">-u</span></samp> option is given. |
| |
| <br><dt><code>-c</code><dt><code>--branch-counts</code><dd>Write branch frequencies as the number of branches taken, rather than |
| the percentage of branches taken. |
| |
| <br><dt><code>-n</code><dt><code>--no-output</code><dd>Do not create the <samp><span class="command">gcov</span></samp> output file. |
| |
| <br><dt><code>-l</code><dt><code>--long-file-names</code><dd>Create long file names for included source files. For example, if the |
| header file <samp><span class="file">x.h</span></samp> contains code, and was included in the file |
| <samp><span class="file">a.c</span></samp>, then running <samp><span class="command">gcov</span></samp> on the file <samp><span class="file">a.c</span></samp> will produce |
| an output file called <samp><span class="file">a.c##x.h.gcov</span></samp> instead of <samp><span class="file">x.h.gcov</span></samp>. |
| This can be useful if <samp><span class="file">x.h</span></samp> is included in multiple source |
| files. If you use the ‘<samp><span class="samp">-p</span></samp>’ option, both the including and |
| included file names will be complete path names. |
| |
| <br><dt><code>-p</code><dt><code>--preserve-paths</code><dd>Preserve complete path information in the names of generated |
| <samp><span class="file">.gcov</span></samp> files. Without this option, just the filename component is |
| used. With this option, all directories are used, with ‘<samp><span class="samp">/</span></samp>’ characters |
| translated to ‘<samp><span class="samp">#</span></samp>’ characters, <samp><span class="file">.</span></samp> directory components |
| removed and <samp><span class="file">..</span></samp> |
| components renamed to ‘<samp><span class="samp">^</span></samp>’. This is useful if sourcefiles are in several |
| different directories. It also affects the ‘<samp><span class="samp">-l</span></samp>’ option. |
| |
| <br><dt><code>-f</code><dt><code>--function-summaries</code><dd>Output summaries for each function in addition to the file level summary. |
| |
| <br><dt><code>-o </code><var>directory|file</var><dt><code>--object-directory </code><var>directory</var><dt><code>--object-file </code><var>file</var><dd>Specify either the directory containing the gcov data files, or the |
| object path name. The <samp><span class="file">.gcno</span></samp>, and |
| <samp><span class="file">.gcda</span></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 |
| source file name, without its extension. If a file is specified here, |
| the data files are named after that file, without its extension. If this |
| option is not supplied, it defaults to the current directory. |
| |
| <br><dt><code>-u</code><dt><code>--unconditional-branches</code><dd>When branch probabilities are given, include those of unconditional branches. |
| Unconditional branches are normally not interesting. |
| |
| </dl> |
| |
| <p><samp><span class="command">gcov</span></samp> 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. <samp><span class="command">gcov</span></samp> produces files called |
| <samp><var>mangledname</var><span class="file">.gcov</span></samp> in the current directory. These contain |
| the coverage information of the source file they correspond to. |
| One <samp><span class="file">.gcov</span></samp> file is produced for each source 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><span class="samp">-l</span></samp>’ or ‘<samp><span class="samp">-p</span></samp>’ options are |
| given. Refer to those options for details. |
| |
| <p>The <samp><span class="file">.gcov</span></samp> files contain the ‘<samp><span class="samp">:</span></samp>’ separated fields along with |
| program source code. The format is |
| |
| <pre class="smallexample"> <var>execution_count</var>:<var>line_number</var>:<var>source line text</var> |
| </pre> |
| <p>Additional block information may succeed each line, when requested by |
| command line option. The <var>execution_count</var> is ‘<samp><span class="samp">-</span></samp>’ for lines |
| containing no code and ‘<samp><span class="samp">#####</span></samp>’ for lines which were never executed. |
| Some lines of information at the start have <var>line_number</var> of zero. |
| |
| <p>The preamble lines are of the form |
| |
| <pre class="smallexample"> -:0:<var>tag</var>:<var>value</var> |
| </pre> |
| <p>The ordering and number of these preamble lines will be augmented as |
| <samp><span class="command">gcov</span></samp> development progresses — do not rely on them remaining |
| unchanged. Use <var>tag</var> to locate a particular preamble line. |
| |
| <p>The additional block information is of the form |
| |
| <pre class="smallexample"> <var>tag</var> <var>information</var> |
| </pre> |
| <p>The <var>information</var> 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 <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>When using <samp><span class="command">gcov</span></samp>, you must first compile your program with two |
| special GCC options: ‘<samp><span class="samp">-fprofile-arcs -ftest-coverage</span></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>Running the program will cause profile output to be generated. For each |
| source file compiled with <samp><span class="option">-fprofile-arcs</span></samp>, an accompanying |
| <samp><span class="file">.gcda</span></samp> file will be placed in the object file directory. |
| |
| <p>Running <samp><span class="command">gcov</span></samp> 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><span class="file">tmp.c</span></samp>, this |
| is what you see when you use the basic <samp><span class="command">gcov</span></samp> facility: |
| |
| <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> |
| <p>The file <samp><span class="file">tmp.c.gcov</span></samp> contains output from <samp><span class="command">gcov</span></samp>. |
| Here is a sample: |
| |
| <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> |
| <p>When you use the <samp><span class="option">-a</span></samp> option, you will get individual block |
| counts, and the output looks like this: |
| |
| <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> |
| <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><span class="option">-b</span></samp> option is given. |
| |
| <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>When you use the <samp><span class="option">-b</span></samp> option, your output looks like this: |
| |
| <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> |
| <p>Here is a sample of a resulting <samp><span class="file">tmp.c.gcov</span></samp> file: |
| |
| <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> |
| <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 <code>exit</code> or <code>longjmp</code>, |
| 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 <samp><span class="file">.gcda</span></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>The data in the <samp><span class="file">.gcda</span></samp> files is saved immediately before the program |
| exits. For each source file compiled with <samp><span class="option">-fprofile-arcs</span></samp>, the |
| profiling code first attempts to read in an existing <samp><span class="file">.gcda</span></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. |
| |
| </body></html> |
| |
