gcov.texi revision 110611
1@c Copyright (C) 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc. 2@c This is part of the GCC manual. 3@c For copying conditions, see the file gcc.texi. 4 5@ignore 6@c man begin COPYRIGHT 7Copyright @copyright{} 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc. 8 9Permission is granted to copy, distribute and/or modify this document 10under the terms of the GNU Free Documentation License, Version 1.1 or 11any later version published by the Free Software Foundation; with the 12Invariant Sections being ``GNU General Public License'' and ``Funding 13Free Software'', the Front-Cover texts being (a) (see below), and with 14the Back-Cover Texts being (b) (see below). A copy of the license is 15included in the gfdl(7) man page. 16 17(a) The FSF's Front-Cover Text is: 18 19 A GNU Manual 20 21(b) The FSF's Back-Cover Text is: 22 23 You have freedom to copy and modify this GNU Manual, like GNU 24 software. Copies published by the Free Software Foundation raise 25 funds for GNU development. 26@c man end 27@c Set file name and title for the man page. 28@setfilename gcov 29@settitle coverage testing tool 30@end ignore 31 32@node Gcov 33@chapter @command{gcov}---a Test Coverage Program 34 35@command{gcov} is a tool you can use in conjunction with GCC to 36test code coverage in your programs. 37 38@menu 39* Gcov Intro:: Introduction to gcov. 40* Invoking Gcov:: How to use gcov. 41* Gcov and Optimization:: Using gcov with GCC optimization. 42* Gcov Data Files:: The files used by gcov. 43@end menu 44 45@node Gcov Intro 46@section Introduction to @command{gcov} 47@c man begin DESCRIPTION 48 49@command{gcov} is a test coverage program. Use it in concert with GCC 50to analyze your programs to help create more efficient, faster 51running code. You can use @command{gcov} as a profiling tool to help 52discover where your optimization efforts will best affect your code. You 53can also use @command{gcov} along with the other profiling tool, 54@command{gprof}, to assess which parts of your code use the greatest amount 55of computing time. 56 57Profiling tools help you analyze your code's performance. Using a 58profiler such as @command{gcov} or @command{gprof}, you can find out some 59basic performance statistics, such as: 60 61@itemize @bullet 62@item 63how often each line of code executes 64 65@item 66what lines of code are actually executed 67 68@item 69how much computing time each section of code uses 70@end itemize 71 72Once you know these things about how your code works when compiled, you 73can look at each module to see which modules should be optimized. 74@command{gcov} helps you determine where to work on optimization. 75 76Software developers also use coverage testing in concert with 77testsuites, to make sure software is actually good enough for a release. 78Testsuites can verify that a program works as expected; a coverage 79program tests to see how much of the program is exercised by the 80testsuite. Developers can then determine what kinds of test cases need 81to be added to the testsuites to create both better testing and a better 82final product. 83 84You should compile your code without optimization if you plan to use 85@command{gcov} because the optimization, by combining some lines of code 86into one function, may not give you as much information as you need to 87look for `hot spots' where the code is using a great deal of computer 88time. Likewise, because @command{gcov} accumulates statistics by line (at 89the lowest resolution), it works best with a programming style that 90places only one statement on each line. If you use complicated macros 91that expand to loops or to other control structures, the statistics are 92less helpful---they only report on the line where the macro call 93appears. If your complex macros behave like functions, you can replace 94them with inline functions to solve this problem. 95 96@command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which 97indicates how many times each line of a source file @file{@var{sourcefile}.c} 98has executed. You can use these logfiles along with @command{gprof} to aid 99in fine-tuning the performance of your programs. @command{gprof} gives 100timing information you can use along with the information you get from 101@command{gcov}. 102 103@command{gcov} works only on code compiled with GCC@. It is not 104compatible with any other profiling or test coverage mechanism. 105 106@c man end 107 108@node Invoking Gcov 109@section Invoking gcov 110 111@smallexample 112gcov @r{[}@var{options}@r{]} @var{sourcefile} 113@end smallexample 114 115@command{gcov} accepts the following options: 116 117@ignore 118@c man begin SYNOPSIS 119gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] 120 [@option{-b}|@option{--branch-probabilities}] [@option{-c}|@option{--branch-counts}] 121 [@option{-n}|@option{--no-output}] [@option{-l}|@option{--long-file-names}] 122 [@option{-f}|@option{--function-summaries}] 123 [@option{-o}|@option{--object-directory} @var{directory}] @var{sourcefile} 124@c man end 125@c man begin SEEALSO 126gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. 127@c man end 128@end ignore 129 130@c man begin OPTIONS 131@table @gcctabopt 132@item -h 133@itemx --help 134Display help about using @command{gcov} (on the standard output), and 135exit without doing any further processing. 136 137@item -v 138@itemx --version 139Display the @command{gcov} version number (on the standard output), 140and exit without doing any further processing. 141 142@item -b 143@itemx --branch-probabilities 144Write branch frequencies to the output file, and write branch summary 145info to the standard output. This option allows you to see how often 146each branch in your program was taken. 147 148@item -c 149@itemx --branch-counts 150Write branch frequencies as the number of branches taken, rather than 151the percentage of branches taken. 152 153@item -n 154@itemx --no-output 155Do not create the @command{gcov} output file. 156 157@item -l 158@itemx --long-file-names 159Create long file names for included source files. For example, if the 160header file @file{x.h} contains code, and was included in the file 161@file{a.c}, then running @command{gcov} on the file @file{a.c} will produce 162an output file called @file{a.c.x.h.gcov} instead of @file{x.h.gcov}. 163This can be useful if @file{x.h} is included in multiple source files. 164 165@item -f 166@itemx --function-summaries 167Output summaries for each function in addition to the file level summary. 168 169@item -o @var{directory} 170@itemx --object-directory @var{directory} 171The directory where the object files live. Gcov will search for @file{.bb}, 172@file{.bbg}, and @file{.da} files in this directory. 173@end table 174 175@need 3000 176When using @command{gcov}, you must first compile your program with two 177special GCC options: @samp{-fprofile-arcs -ftest-coverage}. 178This tells the compiler to generate additional information needed by 179gcov (basically a flow graph of the program) and also includes 180additional code in the object files for generating the extra profiling 181information needed by gcov. These additional files are placed in the 182directory where the source code is located. 183 184Running the program will cause profile output to be generated. For each 185source file compiled with @option{-fprofile-arcs}, an accompanying @file{.da} 186file will be placed in the source directory. 187 188Running @command{gcov} with your program's source file names as arguments 189will now produce a listing of the code along with frequency of execution 190for each line. For example, if your program is called @file{tmp.c}, this 191is what you see when you use the basic @command{gcov} facility: 192 193@smallexample 194$ gcc -fprofile-arcs -ftest-coverage tmp.c 195$ a.out 196$ gcov tmp.c 197 87.50% of 8 source lines executed in file tmp.c 198Creating tmp.c.gcov. 199@end smallexample 200 201The file @file{tmp.c.gcov} contains output from @command{gcov}. 202Here is a sample: 203 204@smallexample 205 main() 206 @{ 207 1 int i, total; 208 209 1 total = 0; 210 211 11 for (i = 0; i < 10; i++) 212 10 total += i; 213 214 1 if (total != 45) 215 ###### printf ("Failure\n"); 216 else 217 1 printf ("Success\n"); 218 1 @} 219@end smallexample 220 221@need 450 222When you use the @option{-b} option, your output looks like this: 223 224@smallexample 225$ gcov -b tmp.c 226 87.50% of 8 source lines executed in file tmp.c 227 80.00% of 5 branches executed in file tmp.c 228 80.00% of 5 branches taken at least once in file tmp.c 229 50.00% of 2 calls executed in file tmp.c 230Creating tmp.c.gcov. 231@end smallexample 232 233Here is a sample of a resulting @file{tmp.c.gcov} file: 234 235@smallexample 236 main() 237 @{ 238 1 int i, total; 239 240 1 total = 0; 241 242 11 for (i = 0; i < 10; i++) 243branch 0 taken = 91% 244branch 1 taken = 100% 245branch 2 taken = 100% 246 10 total += i; 247 248 1 if (total != 45) 249branch 0 taken = 100% 250 ###### printf ("Failure\n"); 251call 0 never executed 252branch 1 never executed 253 else 254 1 printf ("Success\n"); 255call 0 returns = 100% 256 1 @} 257@end smallexample 258 259For each basic block, a line is printed after the last line of the basic 260block describing the branch or call that ends the basic block. There can 261be multiple branches and calls listed for a single source line if there 262are multiple basic blocks that end on that line. In this case, the 263branches and calls are each given a number. There is no simple way to map 264these branches and calls back to source constructs. In general, though, 265the lowest numbered branch or call will correspond to the leftmost construct 266on the source line. 267 268For a branch, if it was executed at least once, then a percentage 269indicating the number of times the branch was taken divided by the 270number of times the branch was executed will be printed. Otherwise, the 271message ``never executed'' is printed. 272 273For a call, if it was executed at least once, then a percentage 274indicating the number of times the call returned divided by the number 275of times the call was executed will be printed. This will usually be 276100%, but may be less for functions call @code{exit} or @code{longjmp}, 277and thus may not return every time they are called. 278 279The execution counts are cumulative. If the example program were 280executed again without removing the @file{.da} file, the count for the 281number of times each line in the source was executed would be added to 282the results of the previous run(s). This is potentially useful in 283several ways. For example, it could be used to accumulate data over a 284number of program runs as part of a test verification suite, or to 285provide more accurate long-term information over a large number of 286program runs. 287 288The data in the @file{.da} files is saved immediately before the program 289exits. For each source file compiled with @option{-fprofile-arcs}, the profiling 290code first attempts to read in an existing @file{.da} file; if the file 291doesn't match the executable (differing number of basic block counts) it 292will ignore the contents of the file. It then adds in the new execution 293counts and finally writes the data to the file. 294 295@node Gcov and Optimization 296@section Using @command{gcov} with GCC Optimization 297 298If you plan to use @command{gcov} to help optimize your code, you must 299first compile your program with two special GCC options: 300@samp{-fprofile-arcs -ftest-coverage}. Aside from that, you can use any 301other GCC options; but if you want to prove that every single line 302in your program was executed, you should not compile with optimization 303at the same time. On some machines the optimizer can eliminate some 304simple code lines by combining them with other lines. For example, code 305like this: 306 307@smallexample 308if (a != b) 309 c = 1; 310else 311 c = 0; 312@end smallexample 313 314@noindent 315can be compiled into one instruction on some machines. In this case, 316there is no way for @command{gcov} to calculate separate execution counts 317for each line because there isn't separate code for each line. Hence 318the @command{gcov} output looks like this if you compiled the program with 319optimization: 320 321@smallexample 322 100 if (a != b) 323 100 c = 1; 324 100 else 325 100 c = 0; 326@end smallexample 327 328The output shows that this block of code, combined by optimization, 329executed 100 times. In one sense this result is correct, because there 330was only one instruction representing all four of these lines. However, 331the output does not indicate how many times the result was 0 and how 332many times the result was 1. 333@c man end 334 335@node Gcov Data Files 336@section Brief description of @command{gcov} data files 337 338@command{gcov} uses three files for doing profiling. The names of these 339files are derived from the original @emph{source} file by substituting 340the file suffix with either @file{.bb}, @file{.bbg}, or @file{.da}. All 341of these files are placed in the same directory as the source file, and 342contain data stored in a platform-independent method. 343 344The @file{.bb} and @file{.bbg} files are generated when the source file 345is compiled with the GCC @option{-ftest-coverage} option. The 346@file{.bb} file contains a list of source files (including headers), 347functions within those files, and line numbers corresponding to each 348basic block in the source file. 349 350The @file{.bb} file format consists of several lists of 4-byte integers 351which correspond to the line numbers of each basic block in the 352file. Each list is terminated by a line number of 0. A line number of @minus{}1 353is used to designate that the source file name (padded to a 4-byte 354boundary and followed by another @minus{}1) follows. In addition, a line number 355of @minus{}2 is used to designate that the name of a function (also padded to a 3564-byte boundary and followed by a @minus{}2) follows. 357 358The @file{.bbg} file is used to reconstruct the program flow graph for 359the source file. It contains a list of the program flow arcs (possible 360branches taken from one basic block to another) for each function which, 361in combination with the @file{.bb} file, enables gcov to reconstruct the 362program flow. 363 364In the @file{.bbg} file, the format is: 365@smallexample 366 number of basic blocks for function #0 (4-byte number) 367 total number of arcs for function #0 (4-byte number) 368 count of arcs in basic block #0 (4-byte number) 369 destination basic block of arc #0 (4-byte number) 370 flag bits (4-byte number) 371 destination basic block of arc #1 (4-byte number) 372 flag bits (4-byte number) 373 @dots{} 374 destination basic block of arc #N (4-byte number) 375 flag bits (4-byte number) 376 count of arcs in basic block #1 (4-byte number) 377 destination basic block of arc #0 (4-byte number) 378 flag bits (4-byte number) 379 @dots{} 380@end smallexample 381 382A @minus{}1 (stored as a 4-byte number) is used to separate each function's 383list of basic blocks, and to verify that the file has been read 384correctly. 385 386The @file{.da} file is generated when a program containing object files 387built with the GCC @option{-fprofile-arcs} option is executed. A 388separate @file{.da} file is created for each source file compiled with 389this option, and the name of the @file{.da} file is stored as an 390absolute pathname in the resulting object file. This path name is 391derived from the source file name by substituting a @file{.da} suffix. 392 393The format of the @file{.da} file is fairly simple. The first 8-byte 394number is the number of counts in the file, followed by the counts 395(stored as 8-byte numbers). Each count corresponds to the number of 396times each arc in the program is executed. The counts are cumulative; 397each time the program is executed, it attempts to combine the existing 398@file{.da} files with the new counts for this invocation of the 399program. It ignores the contents of any @file{.da} files whose number of 400arcs doesn't correspond to the current program, and merely overwrites 401them instead. 402 403All three of these files use the functions in @file{gcov-io.h} to store 404integers; the functions in this header provide a machine-independent 405mechanism for storing and retrieving data from a stream. 406 407