1<html lang="en"> 2<head> 3<title>Invoking Gcov - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Gcov.html#Gcov" title="Gcov"> 9<link rel="prev" href="Gcov-Intro.html#Gcov-Intro" title="Gcov Intro"> 10<link rel="next" href="Gcov-and-Optimization.html#Gcov-and-Optimization" title="Gcov and Optimization"> 11<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 12<!-- 13Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 141998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 152010 Free Software Foundation, Inc. 16 17Permission is granted to copy, distribute and/or modify this document 18under the terms of the GNU Free Documentation License, Version 1.3 or 19any later version published by the Free Software Foundation; with the 20Invariant Sections being ``Funding Free Software'', the Front-Cover 21Texts being (a) (see below), and with the Back-Cover Texts being (b) 22(see below). A copy of the license is included in the section entitled 23``GNU Free Documentation License''. 24 25(a) The FSF's Front-Cover Text is: 26 27 A GNU Manual 28 29(b) The FSF's Back-Cover Text is: 30 31 You have freedom to copy and modify this GNU Manual, like GNU 32 software. Copies published by the Free Software Foundation raise 33 funds for GNU development.--> 34<meta http-equiv="Content-Style-Type" content="text/css"> 35<style type="text/css"><!-- 36 pre.display { font-family:inherit } 37 pre.format { font-family:inherit } 38 pre.smalldisplay { font-family:inherit; font-size:smaller } 39 pre.smallformat { font-family:inherit; font-size:smaller } 40 pre.smallexample { font-size:smaller } 41 pre.smalllisp { font-size:smaller } 42 span.sc { font-variant:small-caps } 43 span.roman { font-family:serif; font-weight:normal; } 44 span.sansserif { font-family:sans-serif; font-weight:normal; } 45--></style> 46<link rel="stylesheet" type="text/css" href="../cs.css"> 47</head> 48<body> 49<div class="node"> 50<a name="Invoking-Gcov"></a> 51<p> 52Next: <a rel="next" accesskey="n" href="Gcov-and-Optimization.html#Gcov-and-Optimization">Gcov and Optimization</a>, 53Previous: <a rel="previous" accesskey="p" href="Gcov-Intro.html#Gcov-Intro">Gcov Intro</a>, 54Up: <a rel="up" accesskey="u" href="Gcov.html#Gcov">Gcov</a> 55<hr> 56</div> 57 58<h3 class="section">10.2 Invoking <samp><span class="command">gcov</span></samp></h3> 59 60<pre class="smallexample"> gcov <span class="roman">[</span><var>options</var><span class="roman">]</span> <var>sourcefiles</var> 61</pre> 62 <p><samp><span class="command">gcov</span></samp> accepts the following options: 63 64<!-- man begin OPTIONS --> 65 <dl> 66<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 67exit without doing any further processing. 68 69 <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), 70and exit without doing any further processing. 71 72 <br><dt><code>-a</code><dt><code>--all-blocks</code><dd>Write individual execution counts for every basic block. Normally gcov 73outputs execution counts only for the main blocks of a line. With this 74option you can determine if blocks within a single line are not being 75executed. 76 77 <br><dt><code>-b</code><dt><code>--branch-probabilities</code><dd>Write branch frequencies to the output file, and write branch summary 78info to the standard output. This option allows you to see how often 79each branch in your program was taken. Unconditional branches will not 80be shown, unless the <samp><span class="option">-u</span></samp> option is given. 81 82 <br><dt><code>-c</code><dt><code>--branch-counts</code><dd>Write branch frequencies as the number of branches taken, rather than 83the percentage of branches taken. 84 85 <br><dt><code>-n</code><dt><code>--no-output</code><dd>Do not create the <samp><span class="command">gcov</span></samp> output file. 86 87 <br><dt><code>-l</code><dt><code>--long-file-names</code><dd>Create long file names for included source files. For example, if the 88header file <samp><span class="file">x.h</span></samp> contains code, and was included in the file 89<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 90an 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>. 91This can be useful if <samp><span class="file">x.h</span></samp> is included in multiple source 92files. If you use the ‘<samp><span class="samp">-p</span></samp>’ option, both the including and 93included file names will be complete path names. 94 95 <br><dt><code>-p</code><dt><code>--preserve-paths</code><dd>Preserve complete path information in the names of generated 96<samp><span class="file">.gcov</span></samp> files. Without this option, just the filename component is 97used. With this option, all directories are used, with ‘<samp><span class="samp">/</span></samp>’ characters 98translated to ‘<samp><span class="samp">#</span></samp>’ characters, <samp><span class="file">.</span></samp> directory components 99removed and <samp><span class="file">..</span></samp> 100components renamed to ‘<samp><span class="samp">^</span></samp>’. This is useful if sourcefiles are in several 101different directories. It also affects the ‘<samp><span class="samp">-l</span></samp>’ option. 102 103 <br><dt><code>-f</code><dt><code>--function-summaries</code><dd>Output summaries for each function in addition to the file level summary. 104 105 <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 106object path name. The <samp><span class="file">.gcno</span></samp>, and 107<samp><span class="file">.gcda</span></samp> data files are searched for using this option. If a directory 108is specified, the data files are in that directory and named after the 109source file name, without its extension. If a file is specified here, 110the data files are named after that file, without its extension. If this 111option is not supplied, it defaults to the current directory. 112 113 <br><dt><code>-u</code><dt><code>--unconditional-branches</code><dd>When branch probabilities are given, include those of unconditional branches. 114Unconditional branches are normally not interesting. 115 116 <br><dt><code>-d</code><dt><code>--display-progress</code><dd>Display the progress on the standard output. 117 118 </dl> 119 120 <p><samp><span class="command">gcov</span></samp> should be run with the current directory the same as that 121when you invoked the compiler. Otherwise it will not be able to locate 122the source files. <samp><span class="command">gcov</span></samp> produces files called 123<samp><var>mangledname</var><span class="file">.gcov</span></samp> in the current directory. These contain 124the coverage information of the source file they correspond to. 125One <samp><span class="file">.gcov</span></samp> file is produced for each source file containing code, 126which was compiled to produce the data files. The <var>mangledname</var> part 127of the output file name is usually simply the source file name, but can 128be something more complicated if the ‘<samp><span class="samp">-l</span></samp>’ or ‘<samp><span class="samp">-p</span></samp>’ options are 129given. Refer to those options for details. 130 131 <p>The <samp><span class="file">.gcov</span></samp> files contain the ‘<samp><span class="samp">:</span></samp>’ separated fields along with 132program source code. The format is 133 134<pre class="smallexample"> <var>execution_count</var>:<var>line_number</var>:<var>source line text</var> 135</pre> 136 <p>Additional block information may succeed each line, when requested by 137command line option. The <var>execution_count</var> is ‘<samp><span class="samp">-</span></samp>’ for lines 138containing no code and ‘<samp><span class="samp">#####</span></samp>’ for lines which were never executed. 139Some lines of information at the start have <var>line_number</var> of zero. 140 141 <p>The preamble lines are of the form 142 143<pre class="smallexample"> -:0:<var>tag</var>:<var>value</var> 144</pre> 145 <p>The ordering and number of these preamble lines will be augmented as 146<samp><span class="command">gcov</span></samp> development progresses — do not rely on them remaining 147unchanged. Use <var>tag</var> to locate a particular preamble line. 148 149 <p>The additional block information is of the form 150 151<pre class="smallexample"> <var>tag</var> <var>information</var> 152</pre> 153 <p>The <var>information</var> is human readable, but designed to be simple 154enough for machine parsing too. 155 156 <p>When printing percentages, 0% and 100% are only printed when the values 157are <em>exactly</em> 0% and 100% respectively. Other values which would 158conventionally be rounded to 0% or 100% are instead printed as the 159nearest non-boundary value. 160 161 <p>When using <samp><span class="command">gcov</span></samp>, you must first compile your program with two 162special GCC options: ‘<samp><span class="samp">-fprofile-arcs -ftest-coverage</span></samp>’. 163This tells the compiler to generate additional information needed by 164gcov (basically a flow graph of the program) and also includes 165additional code in the object files for generating the extra profiling 166information needed by gcov. These additional files are placed in the 167directory where the object file is located. 168 169 <p>Running the program will cause profile output to be generated. For each 170source file compiled with <samp><span class="option">-fprofile-arcs</span></samp>, an accompanying 171<samp><span class="file">.gcda</span></samp> file will be placed in the object file directory. 172 173 <p>Running <samp><span class="command">gcov</span></samp> with your program's source file names as arguments 174will now produce a listing of the code along with frequency of execution 175for each line. For example, if your program is called <samp><span class="file">tmp.c</span></samp>, this 176is what you see when you use the basic <samp><span class="command">gcov</span></samp> facility: 177 178<pre class="smallexample"> $ gcc -fprofile-arcs -ftest-coverage tmp.c 179 $ a.out 180 $ gcov tmp.c 181 90.00% of 10 source lines executed in file tmp.c 182 Creating tmp.c.gcov. 183</pre> 184 <p>The file <samp><span class="file">tmp.c.gcov</span></samp> contains output from <samp><span class="command">gcov</span></samp>. 185Here is a sample: 186 187<pre class="smallexample"> -: 0:Source:tmp.c 188 -: 0:Graph:tmp.gcno 189 -: 0:Data:tmp.gcda 190 -: 0:Runs:1 191 -: 0:Programs:1 192 -: 1:#include <stdio.h> 193 -: 2: 194 -: 3:int main (void) 195 1: 4:{ 196 1: 5: int i, total; 197 -: 6: 198 1: 7: total = 0; 199 -: 8: 200 11: 9: for (i = 0; i < 10; i++) 201 10: 10: total += i; 202 -: 11: 203 1: 12: if (total != 45) 204 #####: 13: printf ("Failure\n"); 205 -: 14: else 206 1: 15: printf ("Success\n"); 207 1: 16: return 0; 208 -: 17:} 209</pre> 210 <p>When you use the <samp><span class="option">-a</span></samp> option, you will get individual block 211counts, and the output looks like this: 212 213<pre class="smallexample"> -: 0:Source:tmp.c 214 -: 0:Graph:tmp.gcno 215 -: 0:Data:tmp.gcda 216 -: 0:Runs:1 217 -: 0:Programs:1 218 -: 1:#include <stdio.h> 219 -: 2: 220 -: 3:int main (void) 221 1: 4:{ 222 1: 4-block 0 223 1: 5: int i, total; 224 -: 6: 225 1: 7: total = 0; 226 -: 8: 227 11: 9: for (i = 0; i < 10; i++) 228 11: 9-block 0 229 10: 10: total += i; 230 10: 10-block 0 231 -: 11: 232 1: 12: if (total != 45) 233 1: 12-block 0 234 #####: 13: printf ("Failure\n"); 235 $$$$$: 13-block 0 236 -: 14: else 237 1: 15: printf ("Success\n"); 238 1: 15-block 0 239 1: 16: return 0; 240 1: 16-block 0 241 -: 17:} 242</pre> 243 <p>In this mode, each basic block is only shown on one line – the last 244line of the block. A multi-line block will only contribute to the 245execution count of that last line, and other lines will not be shown 246to contain code, unless previous blocks end on those lines. 247The total execution count of a line is shown and subsequent lines show 248the execution counts for individual blocks that end on that line. After each 249block, the branch and call counts of the block will be shown, if the 250<samp><span class="option">-b</span></samp> option is given. 251 252 <p>Because of the way GCC instruments calls, a call count can be shown 253after a line with no individual blocks. 254As you can see, line 13 contains a basic block that was not executed. 255 256 <p>When you use the <samp><span class="option">-b</span></samp> option, your output looks like this: 257 258<pre class="smallexample"> $ gcov -b tmp.c 259 90.00% of 10 source lines executed in file tmp.c 260 80.00% of 5 branches executed in file tmp.c 261 80.00% of 5 branches taken at least once in file tmp.c 262 50.00% of 2 calls executed in file tmp.c 263 Creating tmp.c.gcov. 264</pre> 265 <p>Here is a sample of a resulting <samp><span class="file">tmp.c.gcov</span></samp> file: 266 267<pre class="smallexample"> -: 0:Source:tmp.c 268 -: 0:Graph:tmp.gcno 269 -: 0:Data:tmp.gcda 270 -: 0:Runs:1 271 -: 0:Programs:1 272 -: 1:#include <stdio.h> 273 -: 2: 274 -: 3:int main (void) 275 function main called 1 returned 1 blocks executed 75% 276 1: 4:{ 277 1: 5: int i, total; 278 -: 6: 279 1: 7: total = 0; 280 -: 8: 281 11: 9: for (i = 0; i < 10; i++) 282 branch 0 taken 91% (fallthrough) 283 branch 1 taken 9% 284 10: 10: total += i; 285 -: 11: 286 1: 12: if (total != 45) 287 branch 0 taken 0% (fallthrough) 288 branch 1 taken 100% 289 #####: 13: printf ("Failure\n"); 290 call 0 never executed 291 -: 14: else 292 1: 15: printf ("Success\n"); 293 call 0 called 1 returned 100% 294 1: 16: return 0; 295 -: 17:} 296</pre> 297 <p>For each function, a line is printed showing how many times the function 298is called, how many times it returns and what percentage of the 299function's blocks were executed. 300 301 <p>For each basic block, a line is printed after the last line of the basic 302block describing the branch or call that ends the basic block. There can 303be multiple branches and calls listed for a single source line if there 304are multiple basic blocks that end on that line. In this case, the 305branches and calls are each given a number. There is no simple way to map 306these branches and calls back to source constructs. In general, though, 307the lowest numbered branch or call will correspond to the leftmost construct 308on the source line. 309 310 <p>For a branch, if it was executed at least once, then a percentage 311indicating the number of times the branch was taken divided by the 312number of times the branch was executed will be printed. Otherwise, the 313message “never executed” is printed. 314 315 <p>For a call, if it was executed at least once, then a percentage 316indicating the number of times the call returned divided by the number 317of times the call was executed will be printed. This will usually be 318100%, but may be less for functions that call <code>exit</code> or <code>longjmp</code>, 319and thus may not return every time they are called. 320 321 <p>The execution counts are cumulative. If the example program were 322executed again without removing the <samp><span class="file">.gcda</span></samp> file, the count for the 323number of times each line in the source was executed would be added to 324the results of the previous run(s). This is potentially useful in 325several ways. For example, it could be used to accumulate data over a 326number of program runs as part of a test verification suite, or to 327provide more accurate long-term information over a large number of 328program runs. 329 330 <p>The data in the <samp><span class="file">.gcda</span></samp> files is saved immediately before the program 331exits. For each source file compiled with <samp><span class="option">-fprofile-arcs</span></samp>, the 332profiling code first attempts to read in an existing <samp><span class="file">.gcda</span></samp> file; if 333the file doesn't match the executable (differing number of basic block 334counts) it will ignore the contents of the file. It then adds in the 335new execution counts and finally writes the data to the file. 336 337 </body></html> 338 339