1117395Skan@c Copyright (C) 1996, 1997, 1999, 2000, 2001, 2169689Skan@c 2002, 2003, 2004, 2005 Free Software Foundation, Inc. 390075Sobrien@c This is part of the GCC manual. 490075Sobrien@c For copying conditions, see the file gcc.texi. 590075Sobrien 690075Sobrien@ignore 790075Sobrien@c man begin COPYRIGHT 8169689SkanCopyright @copyright{} 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004, 2005 9117395SkanFree Software Foundation, Inc. 1090075Sobrien 1190075SobrienPermission is granted to copy, distribute and/or modify this document 12117395Skanunder the terms of the GNU Free Documentation License, Version 1.2 or 1390075Sobrienany later version published by the Free Software Foundation; with the 1490075SobrienInvariant Sections being ``GNU General Public License'' and ``Funding 1590075SobrienFree Software'', the Front-Cover texts being (a) (see below), and with 1690075Sobrienthe Back-Cover Texts being (b) (see below). A copy of the license is 1790075Sobrienincluded in the gfdl(7) man page. 1890075Sobrien 1990075Sobrien(a) The FSF's Front-Cover Text is: 2090075Sobrien 2190075Sobrien A GNU Manual 2290075Sobrien 2390075Sobrien(b) The FSF's Back-Cover Text is: 2490075Sobrien 2590075Sobrien You have freedom to copy and modify this GNU Manual, like GNU 2690075Sobrien software. Copies published by the Free Software Foundation raise 2790075Sobrien funds for GNU development. 2890075Sobrien@c man end 2990075Sobrien@c Set file name and title for the man page. 3090075Sobrien@setfilename gcov 3190075Sobrien@settitle coverage testing tool 3290075Sobrien@end ignore 3390075Sobrien 3490075Sobrien@node Gcov 35110611Skan@chapter @command{gcov}---a Test Coverage Program 3690075Sobrien 3790075Sobrien@command{gcov} is a tool you can use in conjunction with GCC to 3890075Sobrientest code coverage in your programs. 3990075Sobrien 4090075Sobrien@menu 4190075Sobrien* Gcov Intro:: Introduction to gcov. 4290075Sobrien* Invoking Gcov:: How to use gcov. 4390075Sobrien* Gcov and Optimization:: Using gcov with GCC optimization. 4490075Sobrien* Gcov Data Files:: The files used by gcov. 45169689Skan* Cross-profiling:: Data file relocation. 4690075Sobrien@end menu 4790075Sobrien 4890075Sobrien@node Gcov Intro 4990075Sobrien@section Introduction to @command{gcov} 5090075Sobrien@c man begin DESCRIPTION 5190075Sobrien 5290075Sobrien@command{gcov} is a test coverage program. Use it in concert with GCC 53117395Skanto analyze your programs to help create more efficient, faster running 54117395Skancode and to discover untested parts of your program. You can use 55117395Skan@command{gcov} as a profiling tool to help discover where your 56117395Skanoptimization efforts will best affect your code. You can also use 57117395Skan@command{gcov} along with the other profiling tool, @command{gprof}, to 58117395Skanassess which parts of your code use the greatest amount of computing 59117395Skantime. 6090075Sobrien 6190075SobrienProfiling tools help you analyze your code's performance. Using a 6290075Sobrienprofiler such as @command{gcov} or @command{gprof}, you can find out some 6390075Sobrienbasic performance statistics, such as: 6490075Sobrien 6590075Sobrien@itemize @bullet 6690075Sobrien@item 6790075Sobrienhow often each line of code executes 6890075Sobrien 6990075Sobrien@item 7090075Sobrienwhat lines of code are actually executed 7190075Sobrien 7290075Sobrien@item 7390075Sobrienhow much computing time each section of code uses 7490075Sobrien@end itemize 7590075Sobrien 7690075SobrienOnce you know these things about how your code works when compiled, you 7790075Sobriencan look at each module to see which modules should be optimized. 7890075Sobrien@command{gcov} helps you determine where to work on optimization. 7990075Sobrien 8090075SobrienSoftware developers also use coverage testing in concert with 8190075Sobrientestsuites, to make sure software is actually good enough for a release. 8290075SobrienTestsuites can verify that a program works as expected; a coverage 8390075Sobrienprogram tests to see how much of the program is exercised by the 8490075Sobrientestsuite. Developers can then determine what kinds of test cases need 8590075Sobriento be added to the testsuites to create both better testing and a better 8690075Sobrienfinal product. 8790075Sobrien 8890075SobrienYou should compile your code without optimization if you plan to use 8990075Sobrien@command{gcov} because the optimization, by combining some lines of code 9090075Sobrieninto one function, may not give you as much information as you need to 9190075Sobrienlook for `hot spots' where the code is using a great deal of computer 9290075Sobrientime. Likewise, because @command{gcov} accumulates statistics by line (at 9390075Sobrienthe lowest resolution), it works best with a programming style that 9490075Sobrienplaces only one statement on each line. If you use complicated macros 9590075Sobrienthat expand to loops or to other control structures, the statistics are 9690075Sobrienless helpful---they only report on the line where the macro call 9790075Sobrienappears. If your complex macros behave like functions, you can replace 9890075Sobrienthem with inline functions to solve this problem. 9990075Sobrien 10090075Sobrien@command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which 10190075Sobrienindicates how many times each line of a source file @file{@var{sourcefile}.c} 10290075Sobrienhas executed. You can use these logfiles along with @command{gprof} to aid 10390075Sobrienin fine-tuning the performance of your programs. @command{gprof} gives 10490075Sobrientiming information you can use along with the information you get from 10590075Sobrien@command{gcov}. 10690075Sobrien 10790075Sobrien@command{gcov} works only on code compiled with GCC@. It is not 10890075Sobriencompatible with any other profiling or test coverage mechanism. 10990075Sobrien 11090075Sobrien@c man end 11190075Sobrien 11290075Sobrien@node Invoking Gcov 113169689Skan@section Invoking @command{gcov} 11490075Sobrien 11590075Sobrien@smallexample 11690075Sobriengcov @r{[}@var{options}@r{]} @var{sourcefile} 11790075Sobrien@end smallexample 11890075Sobrien 11990075Sobrien@command{gcov} accepts the following options: 12090075Sobrien 12190075Sobrien@ignore 12290075Sobrien@c man begin SYNOPSIS 12390075Sobriengcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] 124132718Skan [@option{-a}|@option{--all-blocks}] 125117395Skan [@option{-b}|@option{--branch-probabilities}] 126117395Skan [@option{-c}|@option{--branch-counts}] 127117395Skan [@option{-n}|@option{--no-output}] 128117395Skan [@option{-l}|@option{--long-file-names}] 129117395Skan [@option{-p}|@option{--preserve-paths}] 13090075Sobrien [@option{-f}|@option{--function-summaries}] 131117395Skan [@option{-o}|@option{--object-directory} @var{directory|file}] @var{sourcefile} 132132718Skan [@option{-u}|@option{--unconditional-branches}] 13390075Sobrien@c man end 13490075Sobrien@c man begin SEEALSO 13590075Sobriengpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. 13690075Sobrien@c man end 13790075Sobrien@end ignore 13890075Sobrien 13990075Sobrien@c man begin OPTIONS 14090075Sobrien@table @gcctabopt 14190075Sobrien@item -h 14290075Sobrien@itemx --help 14390075SobrienDisplay help about using @command{gcov} (on the standard output), and 14490075Sobrienexit without doing any further processing. 14590075Sobrien 14690075Sobrien@item -v 14790075Sobrien@itemx --version 14890075SobrienDisplay the @command{gcov} version number (on the standard output), 14990075Sobrienand exit without doing any further processing. 15090075Sobrien 151132718Skan@item -a 152132718Skan@itemx --all-blocks 153169689SkanWrite individual execution counts for every basic block. Normally gcov 154169689Skanoutputs execution counts only for the main blocks of a line. With this 155132718Skanoption you can determine if blocks within a single line are not being 156132718Skanexecuted. 157132718Skan 15890075Sobrien@item -b 15990075Sobrien@itemx --branch-probabilities 16090075SobrienWrite branch frequencies to the output file, and write branch summary 16190075Sobrieninfo to the standard output. This option allows you to see how often 162169689Skaneach branch in your program was taken. Unconditional branches will not 163132718Skanbe shown, unless the @option{-u} option is given. 16490075Sobrien 16590075Sobrien@item -c 16690075Sobrien@itemx --branch-counts 16790075SobrienWrite branch frequencies as the number of branches taken, rather than 16890075Sobrienthe percentage of branches taken. 16990075Sobrien 17090075Sobrien@item -n 17190075Sobrien@itemx --no-output 17290075SobrienDo not create the @command{gcov} output file. 17390075Sobrien 17490075Sobrien@item -l 17590075Sobrien@itemx --long-file-names 17690075SobrienCreate long file names for included source files. For example, if the 17790075Sobrienheader file @file{x.h} contains code, and was included in the file 17890075Sobrien@file{a.c}, then running @command{gcov} on the file @file{a.c} will produce 179117395Skanan output file called @file{a.c##x.h.gcov} instead of @file{x.h.gcov}. 180132718SkanThis can be useful if @file{x.h} is included in multiple source 181169689Skanfiles. If you use the @samp{-p} option, both the including and 182132718Skanincluded file names will be complete path names. 18390075Sobrien 184117395Skan@item -p 185117395Skan@itemx --preserve-paths 186117395SkanPreserve complete path information in the names of generated 187169689Skan@file{.gcov} files. Without this option, just the filename component is 188169689Skanused. With this option, all directories are used, with @samp{/} characters 189169689Skantranslated to @samp{#} characters, @file{.} directory components 190169689Skanremoved and @file{..} 191169689Skancomponents renamed to @samp{^}. This is useful if sourcefiles are in several 192169689Skandifferent directories. It also affects the @samp{-l} option. 193117395Skan 19490075Sobrien@item -f 19590075Sobrien@itemx --function-summaries 19690075SobrienOutput summaries for each function in addition to the file level summary. 19790075Sobrien 198117395Skan@item -o @var{directory|file} 19990075Sobrien@itemx --object-directory @var{directory} 200117395Skan@itemx --object-file @var{file} 201117395SkanSpecify either the directory containing the gcov data files, or the 202169689Skanobject path name. The @file{.gcno}, and 203169689Skan@file{.gcda} data files are searched for using this option. If a directory 204117395Skanis specified, the data files are in that directory and named after the 205169689Skansource file name, without its extension. If a file is specified here, 206169689Skanthe data files are named after that file, without its extension. If this 207117395Skanoption is not supplied, it defaults to the current directory. 208117395Skan 209132718Skan@item -u 210132718Skan@itemx --unconditional-branches 211169689SkanWhen branch probabilities are given, include those of unconditional branches. 212132718SkanUnconditional branches are normally not interesting. 213132718Skan 21490075Sobrien@end table 21590075Sobrien 216132718Skan@command{gcov} should be run with the current directory the same as that 217169689Skanwhen you invoked the compiler. Otherwise it will not be able to locate 218169689Skanthe source files. @command{gcov} produces files called 219169689Skan@file{@var{mangledname}.gcov} in the current directory. These contain 220132718Skanthe coverage information of the source file they correspond to. 221132718SkanOne @file{.gcov} file is produced for each source file containing code, 222169689Skanwhich was compiled to produce the data files. The @var{mangledname} part 223132718Skanof the output file name is usually simply the source file name, but can 224132718Skanbe something more complicated if the @samp{-l} or @samp{-p} options are 225169689Skangiven. Refer to those options for details. 226117395Skan 227169689SkanThe @file{.gcov} files contain the @samp{:} separated fields along with 228169689Skanprogram source code. The format is 229132718Skan 230117395Skan@smallexample 231117395Skan@var{execution_count}:@var{line_number}:@var{source line text} 232117395Skan@end smallexample 233117395Skan 234117395SkanAdditional block information may succeed each line, when requested by 235169689Skancommand line option. The @var{execution_count} is @samp{-} for lines 236169689Skancontaining no code and @samp{#####} for lines which were never executed. 237169689SkanSome lines of information at the start have @var{line_number} of zero. 238117395Skan 239169689SkanThe preamble lines are of the form 240169689Skan 241169689Skan@smallexample 242169689Skan-:0:@var{tag}:@var{value} 243169689Skan@end smallexample 244169689Skan 245169689SkanThe ordering and number of these preamble lines will be augmented as 246169689Skan@command{gcov} development progresses --- do not rely on them remaining 247169689Skanunchanged. Use @var{tag} to locate a particular preamble line. 248169689Skan 249169689SkanThe additional block information is of the form 250169689Skan 251169689Skan@smallexample 252169689Skan@var{tag} @var{information} 253169689Skan@end smallexample 254169689Skan 255169689SkanThe @var{information} is human readable, but designed to be simple 256169689Skanenough for machine parsing too. 257169689Skan 258117395SkanWhen printing percentages, 0% and 100% are only printed when the values 259169689Skanare @emph{exactly} 0% and 100% respectively. Other values which would 260117395Skanconventionally be rounded to 0% or 100% are instead printed as the 261117395Skannearest non-boundary value. 262117395Skan 26390075SobrienWhen using @command{gcov}, you must first compile your program with two 26490075Sobrienspecial GCC options: @samp{-fprofile-arcs -ftest-coverage}. 26590075SobrienThis tells the compiler to generate additional information needed by 26690075Sobriengcov (basically a flow graph of the program) and also includes 26790075Sobrienadditional code in the object files for generating the extra profiling 26890075Sobrieninformation needed by gcov. These additional files are placed in the 269117395Skandirectory where the object file is located. 27090075Sobrien 27190075SobrienRunning the program will cause profile output to be generated. For each 272132718Skansource file compiled with @option{-fprofile-arcs}, an accompanying 273132718Skan@file{.gcda} file will be placed in the object file directory. 27490075Sobrien 27590075SobrienRunning @command{gcov} with your program's source file names as arguments 27690075Sobrienwill now produce a listing of the code along with frequency of execution 27790075Sobrienfor each line. For example, if your program is called @file{tmp.c}, this 27890075Sobrienis what you see when you use the basic @command{gcov} facility: 27990075Sobrien 28090075Sobrien@smallexample 28190075Sobrien$ gcc -fprofile-arcs -ftest-coverage tmp.c 28290075Sobrien$ a.out 28390075Sobrien$ gcov tmp.c 284117395Skan90.00% of 10 source lines executed in file tmp.c 28590075SobrienCreating tmp.c.gcov. 28690075Sobrien@end smallexample 28790075Sobrien 28890075SobrienThe file @file{tmp.c.gcov} contains output from @command{gcov}. 28990075SobrienHere is a sample: 29090075Sobrien 29190075Sobrien@smallexample 292117395Skan -: 0:Source:tmp.c 293132718Skan -: 0:Graph:tmp.gcno 294132718Skan -: 0:Data:tmp.gcda 295132718Skan -: 0:Runs:1 296132718Skan -: 0:Programs:1 297117395Skan -: 1:#include <stdio.h> 298117395Skan -: 2: 299117395Skan -: 3:int main (void) 300117395Skan 1: 4:@{ 301117395Skan 1: 5: int i, total; 302132718Skan -: 6: 303117395Skan 1: 7: total = 0; 304132718Skan -: 8: 305117395Skan 11: 9: for (i = 0; i < 10; i++) 306117395Skan 10: 10: total += i; 307132718Skan -: 11: 308117395Skan 1: 12: if (total != 45) 309117395Skan #####: 13: printf ("Failure\n"); 310117395Skan -: 14: else 311117395Skan 1: 15: printf ("Success\n"); 312117395Skan 1: 16: return 0; 313132718Skan -: 17:@} 31490075Sobrien@end smallexample 31590075Sobrien 316132718SkanWhen you use the @option{-a} option, you will get individual block 317132718Skancounts, and the output looks like this: 318132718Skan 319132718Skan@smallexample 320132718Skan -: 0:Source:tmp.c 321132718Skan -: 0:Graph:tmp.gcno 322132718Skan -: 0:Data:tmp.gcda 323132718Skan -: 0:Runs:1 324132718Skan -: 0:Programs:1 325132718Skan -: 1:#include <stdio.h> 326132718Skan -: 2: 327132718Skan -: 3:int main (void) 328132718Skan 1: 4:@{ 329132718Skan 1: 4-block 0 330132718Skan 1: 5: int i, total; 331132718Skan -: 6: 332132718Skan 1: 7: total = 0; 333132718Skan -: 8: 334132718Skan 11: 9: for (i = 0; i < 10; i++) 335132718Skan 11: 9-block 0 336132718Skan 10: 10: total += i; 337132718Skan 10: 10-block 0 338132718Skan -: 11: 339132718Skan 1: 12: if (total != 45) 340132718Skan 1: 12-block 0 341132718Skan #####: 13: printf ("Failure\n"); 342132718Skan $$$$$: 13-block 0 343132718Skan -: 14: else 344132718Skan 1: 15: printf ("Success\n"); 345132718Skan 1: 15-block 0 346132718Skan 1: 16: return 0; 347132718Skan 1: 16-block 0 348132718Skan -: 17:@} 349132718Skan@end smallexample 350132718Skan 351132718SkanIn this mode, each basic block is only shown on one line -- the last 352169689Skanline of the block. A multi-line block will only contribute to the 353132718Skanexecution count of that last line, and other lines will not be shown 354132718Skanto contain code, unless previous blocks end on those lines. 355132718SkanThe total execution count of a line is shown and subsequent lines show 356169689Skanthe execution counts for individual blocks that end on that line. After each 357132718Skanblock, the branch and call counts of the block will be shown, if the 358132718Skan@option{-b} option is given. 359132718Skan 360132718SkanBecause of the way GCC instruments calls, a call count can be shown 361132718Skanafter a line with no individual blocks. 362132718SkanAs you can see, line 13 contains a basic block that was not executed. 363132718Skan 36490075Sobrien@need 450 36590075SobrienWhen you use the @option{-b} option, your output looks like this: 36690075Sobrien 36790075Sobrien@smallexample 36890075Sobrien$ gcov -b tmp.c 369117395Skan90.00% of 10 source lines executed in file tmp.c 370117395Skan80.00% of 5 branches executed in file tmp.c 371117395Skan80.00% of 5 branches taken at least once in file tmp.c 372117395Skan50.00% of 2 calls executed in file tmp.c 37390075SobrienCreating tmp.c.gcov. 37490075Sobrien@end smallexample 37590075Sobrien 37690075SobrienHere is a sample of a resulting @file{tmp.c.gcov} file: 37790075Sobrien 37890075Sobrien@smallexample 379117395Skan -: 0:Source:tmp.c 380132718Skan -: 0:Graph:tmp.gcno 381132718Skan -: 0:Data:tmp.gcda 382132718Skan -: 0:Runs:1 383132718Skan -: 0:Programs:1 384117395Skan -: 1:#include <stdio.h> 385117395Skan -: 2: 386117395Skan -: 3:int main (void) 387132718Skanfunction main called 1 returned 1 blocks executed 75% 388117395Skan 1: 4:@{ 389117395Skan 1: 5: int i, total; 390132718Skan -: 6: 391117395Skan 1: 7: total = 0; 392132718Skan -: 8: 393117395Skan 11: 9: for (i = 0; i < 10; i++) 394132718Skanbranch 0 taken 91% (fallthrough) 395132718Skanbranch 1 taken 9% 396117395Skan 10: 10: total += i; 397132718Skan -: 11: 398117395Skan 1: 12: if (total != 45) 399132718Skanbranch 0 taken 0% (fallthrough) 400132718Skanbranch 1 taken 100% 401117395Skan #####: 13: printf ("Failure\n"); 402132718Skancall 0 never executed 403117395Skan -: 14: else 404117395Skan 1: 15: printf ("Success\n"); 405132718Skancall 0 called 1 returned 100% 406117395Skan 1: 16: return 0; 407132718Skan -: 17:@} 40890075Sobrien@end smallexample 40990075Sobrien 410169689SkanFor each function, a line is printed showing how many times the function 411169689Skanis called, how many times it returns and what percentage of the 412169689Skanfunction's blocks were executed. 413169689Skan 41490075SobrienFor each basic block, a line is printed after the last line of the basic 41590075Sobrienblock describing the branch or call that ends the basic block. There can 41690075Sobrienbe multiple branches and calls listed for a single source line if there 41790075Sobrienare multiple basic blocks that end on that line. In this case, the 41890075Sobrienbranches and calls are each given a number. There is no simple way to map 41990075Sobrienthese branches and calls back to source constructs. In general, though, 42090075Sobrienthe lowest numbered branch or call will correspond to the leftmost construct 42190075Sobrienon the source line. 42290075Sobrien 42390075SobrienFor a branch, if it was executed at least once, then a percentage 42490075Sobrienindicating the number of times the branch was taken divided by the 42590075Sobriennumber of times the branch was executed will be printed. Otherwise, the 42690075Sobrienmessage ``never executed'' is printed. 42790075Sobrien 42890075SobrienFor a call, if it was executed at least once, then a percentage 42990075Sobrienindicating the number of times the call returned divided by the number 43090075Sobrienof times the call was executed will be printed. This will usually be 431169689Skan100%, but may be less for functions that call @code{exit} or @code{longjmp}, 43290075Sobrienand thus may not return every time they are called. 43390075Sobrien 43490075SobrienThe execution counts are cumulative. If the example program were 435132718Skanexecuted again without removing the @file{.gcda} file, the count for the 43690075Sobriennumber of times each line in the source was executed would be added to 43790075Sobrienthe results of the previous run(s). This is potentially useful in 43890075Sobrienseveral ways. For example, it could be used to accumulate data over a 43990075Sobriennumber of program runs as part of a test verification suite, or to 44090075Sobrienprovide more accurate long-term information over a large number of 44190075Sobrienprogram runs. 44290075Sobrien 443132718SkanThe data in the @file{.gcda} files is saved immediately before the program 444117395Skanexits. For each source file compiled with @option{-fprofile-arcs}, the 445132718Skanprofiling code first attempts to read in an existing @file{.gcda} file; if 446117395Skanthe file doesn't match the executable (differing number of basic block 447117395Skancounts) it will ignore the contents of the file. It then adds in the 448117395Skannew execution counts and finally writes the data to the file. 44990075Sobrien 45090075Sobrien@node Gcov and Optimization 45190075Sobrien@section Using @command{gcov} with GCC Optimization 45290075Sobrien 45390075SobrienIf you plan to use @command{gcov} to help optimize your code, you must 45490075Sobrienfirst compile your program with two special GCC options: 45590075Sobrien@samp{-fprofile-arcs -ftest-coverage}. Aside from that, you can use any 45690075Sobrienother GCC options; but if you want to prove that every single line 45790075Sobrienin your program was executed, you should not compile with optimization 45890075Sobrienat the same time. On some machines the optimizer can eliminate some 45990075Sobriensimple code lines by combining them with other lines. For example, code 46090075Sobrienlike this: 46190075Sobrien 46290075Sobrien@smallexample 46390075Sobrienif (a != b) 46490075Sobrien c = 1; 46590075Sobrienelse 46690075Sobrien c = 0; 46790075Sobrien@end smallexample 46890075Sobrien 46990075Sobrien@noindent 47090075Sobriencan be compiled into one instruction on some machines. In this case, 47190075Sobrienthere is no way for @command{gcov} to calculate separate execution counts 47290075Sobrienfor each line because there isn't separate code for each line. Hence 47390075Sobrienthe @command{gcov} output looks like this if you compiled the program with 47490075Sobrienoptimization: 47590075Sobrien 47690075Sobrien@smallexample 477117395Skan 100: 12:if (a != b) 478117395Skan 100: 13: c = 1; 479117395Skan 100: 14:else 480117395Skan 100: 15: c = 0; 48190075Sobrien@end smallexample 48290075Sobrien 48390075SobrienThe output shows that this block of code, combined by optimization, 48490075Sobrienexecuted 100 times. In one sense this result is correct, because there 48590075Sobrienwas only one instruction representing all four of these lines. However, 48690075Sobrienthe output does not indicate how many times the result was 0 and how 48790075Sobrienmany times the result was 1. 48890075Sobrien 489132718SkanInlineable functions can create unexpected line counts. Line counts are 490132718Skanshown for the source code of the inlineable function, but what is shown 491132718Skandepends on where the function is inlined, or if it is not inlined at all. 49290075Sobrien 493132718SkanIf the function is not inlined, the compiler must emit an out of line 494132718Skancopy of the function, in any object file that needs it. If 495132718Skan@file{fileA.o} and @file{fileB.o} both contain out of line bodies of a 496132718Skanparticular inlineable function, they will also both contain coverage 497132718Skancounts for that function. When @file{fileA.o} and @file{fileB.o} are 498132718Skanlinked together, the linker will, on many systems, select one of those 499132718Skanout of line bodies for all calls to that function, and remove or ignore 500132718Skanthe other. Unfortunately, it will not remove the coverage counters for 501132718Skanthe unused function body. Hence when instrumented, all but one use of 502132718Skanthat function will show zero counts. 50390075Sobrien 504132718SkanIf the function is inlined in several places, the block structure in 505132718Skaneach location might not be the same. For instance, a condition might 506132718Skannow be calculable at compile time in some instances. Because the 507132718Skancoverage of all the uses of the inline function will be shown for the 508132718Skansame source lines, the line counts themselves might seem inconsistent. 50990075Sobrien 510132718Skan@c man end 51190075Sobrien 512132718Skan@node Gcov Data Files 513132718Skan@section Brief description of @command{gcov} data files 51490075Sobrien 515132718Skan@command{gcov} uses two files for profiling. The names of these files 516132718Skanare derived from the original @emph{object} file by substituting the 517132718Skanfile suffix with either @file{.gcno}, or @file{.gcda}. All of these files 518132718Skanare placed in the same directory as the object file, and contain data 519132718Skanstored in a platform-independent format. 52090075Sobrien 521132718SkanThe @file{.gcno} file is generated when the source file is compiled with 522132718Skanthe GCC @option{-ftest-coverage} option. It contains information to 523132718Skanreconstruct the basic block graphs and assign source line numbers to 524132718Skanblocks. 52590075Sobrien 526132718SkanThe @file{.gcda} file is generated when a program containing object files 52790075Sobrienbuilt with the GCC @option{-fprofile-arcs} option is executed. A 528132718Skanseparate @file{.gcda} file is created for each object file compiled with 529169689Skanthis option. It contains arc transition counts, and some summary 530132718Skaninformation. 53190075Sobrien 532132718SkanThe full details of the file format is specified in @file{gcov-io.h}, 533132718Skanand functions provided in that header file should be used to access the 534132718Skancoverage files. 535169689Skan 536169689Skan@node Cross-profiling 537169689Skan@section Data file relocation to support cross-profiling 538169689Skan 539169689SkanRunning the program will cause profile output to be generated. For each 540169689Skansource file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda} 541169689Skanfile will be placed in the object file directory. That implicitly requires 542169689Skanrunning the program on the same system as it was built or having the same 543169689Skanabsolute directory structure on the target system. The program will try 544169689Skanto create the needed directory structure, if it is not already present. 545169689Skan 546169689SkanTo support cross-profiling, a program compiled with @option{-fprofile-arcs} 547169689Skancan relocate the data files based on two environment variables: 548169689Skan 549169689Skan@itemize @bullet 550169689Skan@item 551169689SkanGCOV_PREFIX contains the prefix to add to the absolute paths 552169689Skanin the object file. Prefix must be absolute as well, otherwise its 553169689Skanvalue is ignored. The default is no prefix. 554169689Skan 555169689Skan@item 556169689SkanGCOV_PREFIX_STRIP indicates the how many initial directory names to strip off 557169689Skanthe hardwired absolute paths. Default value is 0. 558169689Skan 559169689Skan@emph{Note:} GCOV_PREFIX_STRIP has no effect if GCOV_PREFIX is undefined, empty 560169689Skanor non-absolute. 561169689Skan@end itemize 562169689Skan 563169689SkanFor example, if the object file @file{/user/build/foo.o} was built with 564169689Skan@option{-fprofile-arcs}, the final executable will try to create the data file 565169689Skan@file{/user/build/foo.gcda} when running on the target system. This will 566169689Skanfail if the corresponding directory does not exist and it is unable to create 567169689Skanit. This can be overcome by, for example, setting the environment as 568169689Skan@samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}. Such a 569169689Skansetting will name the data file @file{/target/run/build/foo.gcda}. 570169689Skan 571169689SkanYou must move the data files to the expected directory tree in order to 572169689Skanuse them for profile directed optimizations (@option{--use-profile}), or to 573169689Skanuse the @command{gcov} tool. 574