1*ec02198aSmrg@c Copyright (C) 1996-2020 Free Software Foundation, Inc. 210d565efSmrg@c This is part of the GCC manual. 310d565efSmrg@c For copying conditions, see the file gcc.texi. 410d565efSmrg 510d565efSmrg@ignore 610d565efSmrg@c man begin COPYRIGHT 7*ec02198aSmrgCopyright @copyright{} 1996-2020 Free Software Foundation, Inc. 810d565efSmrg 910d565efSmrgPermission is granted to copy, distribute and/or modify this document 1010d565efSmrgunder the terms of the GNU Free Documentation License, Version 1.3 or 1110d565efSmrgany later version published by the Free Software Foundation; with the 1210d565efSmrgInvariant Sections being ``GNU General Public License'' and ``Funding 1310d565efSmrgFree Software'', the Front-Cover texts being (a) (see below), and with 1410d565efSmrgthe Back-Cover Texts being (b) (see below). A copy of the license is 1510d565efSmrgincluded in the gfdl(7) man page. 1610d565efSmrg 1710d565efSmrg(a) The FSF's Front-Cover Text is: 1810d565efSmrg 1910d565efSmrg A GNU Manual 2010d565efSmrg 2110d565efSmrg(b) The FSF's Back-Cover Text is: 2210d565efSmrg 2310d565efSmrg You have freedom to copy and modify this GNU Manual, like GNU 2410d565efSmrg software. Copies published by the Free Software Foundation raise 2510d565efSmrg funds for GNU development. 2610d565efSmrg@c man end 2710d565efSmrg@c Set file name and title for the man page. 2810d565efSmrg@setfilename gcov 2910d565efSmrg@settitle coverage testing tool 3010d565efSmrg@end ignore 3110d565efSmrg 3210d565efSmrg@node Gcov 3310d565efSmrg@chapter @command{gcov}---a Test Coverage Program 3410d565efSmrg 3510d565efSmrg@command{gcov} is a tool you can use in conjunction with GCC to 3610d565efSmrgtest code coverage in your programs. 3710d565efSmrg 3810d565efSmrg@menu 3910d565efSmrg* Gcov Intro:: Introduction to gcov. 4010d565efSmrg* Invoking Gcov:: How to use gcov. 4110d565efSmrg* Gcov and Optimization:: Using gcov with GCC optimization. 4210d565efSmrg* Gcov Data Files:: The files used by gcov. 4310d565efSmrg* Cross-profiling:: Data file relocation. 4410d565efSmrg@end menu 4510d565efSmrg 4610d565efSmrg@node Gcov Intro 4710d565efSmrg@section Introduction to @command{gcov} 4810d565efSmrg@c man begin DESCRIPTION 4910d565efSmrg 5010d565efSmrg@command{gcov} is a test coverage program. Use it in concert with GCC 5110d565efSmrgto analyze your programs to help create more efficient, faster running 5210d565efSmrgcode and to discover untested parts of your program. You can use 5310d565efSmrg@command{gcov} as a profiling tool to help discover where your 5410d565efSmrgoptimization efforts will best affect your code. You can also use 5510d565efSmrg@command{gcov} along with the other profiling tool, @command{gprof}, to 5610d565efSmrgassess which parts of your code use the greatest amount of computing 5710d565efSmrgtime. 5810d565efSmrg 5910d565efSmrgProfiling tools help you analyze your code's performance. Using a 6010d565efSmrgprofiler such as @command{gcov} or @command{gprof}, you can find out some 6110d565efSmrgbasic performance statistics, such as: 6210d565efSmrg 6310d565efSmrg@itemize @bullet 6410d565efSmrg@item 6510d565efSmrghow often each line of code executes 6610d565efSmrg 6710d565efSmrg@item 6810d565efSmrgwhat lines of code are actually executed 6910d565efSmrg 7010d565efSmrg@item 7110d565efSmrghow much computing time each section of code uses 7210d565efSmrg@end itemize 7310d565efSmrg 7410d565efSmrgOnce you know these things about how your code works when compiled, you 7510d565efSmrgcan look at each module to see which modules should be optimized. 7610d565efSmrg@command{gcov} helps you determine where to work on optimization. 7710d565efSmrg 7810d565efSmrgSoftware developers also use coverage testing in concert with 7910d565efSmrgtestsuites, to make sure software is actually good enough for a release. 8010d565efSmrgTestsuites can verify that a program works as expected; a coverage 8110d565efSmrgprogram tests to see how much of the program is exercised by the 8210d565efSmrgtestsuite. Developers can then determine what kinds of test cases need 8310d565efSmrgto be added to the testsuites to create both better testing and a better 8410d565efSmrgfinal product. 8510d565efSmrg 8610d565efSmrgYou should compile your code without optimization if you plan to use 8710d565efSmrg@command{gcov} because the optimization, by combining some lines of code 8810d565efSmrginto one function, may not give you as much information as you need to 8910d565efSmrglook for `hot spots' where the code is using a great deal of computer 9010d565efSmrgtime. Likewise, because @command{gcov} accumulates statistics by line (at 9110d565efSmrgthe lowest resolution), it works best with a programming style that 9210d565efSmrgplaces only one statement on each line. If you use complicated macros 9310d565efSmrgthat expand to loops or to other control structures, the statistics are 9410d565efSmrgless helpful---they only report on the line where the macro call 9510d565efSmrgappears. If your complex macros behave like functions, you can replace 9610d565efSmrgthem with inline functions to solve this problem. 9710d565efSmrg 9810d565efSmrg@command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which 9910d565efSmrgindicates how many times each line of a source file @file{@var{sourcefile}.c} 10010d565efSmrghas executed. You can use these logfiles along with @command{gprof} to aid 10110d565efSmrgin fine-tuning the performance of your programs. @command{gprof} gives 10210d565efSmrgtiming information you can use along with the information you get from 10310d565efSmrg@command{gcov}. 10410d565efSmrg 10510d565efSmrg@command{gcov} works only on code compiled with GCC@. It is not 10610d565efSmrgcompatible with any other profiling or test coverage mechanism. 10710d565efSmrg 10810d565efSmrg@c man end 10910d565efSmrg 11010d565efSmrg@node Invoking Gcov 11110d565efSmrg@section Invoking @command{gcov} 11210d565efSmrg 11310d565efSmrg@smallexample 11410d565efSmrggcov @r{[}@var{options}@r{]} @var{files} 11510d565efSmrg@end smallexample 11610d565efSmrg 11710d565efSmrg@command{gcov} accepts the following options: 11810d565efSmrg 11910d565efSmrg@ignore 12010d565efSmrg@c man begin SYNOPSIS 12110d565efSmrggcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] 12210d565efSmrg [@option{-a}|@option{--all-blocks}] 12310d565efSmrg [@option{-b}|@option{--branch-probabilities}] 12410d565efSmrg [@option{-c}|@option{--branch-counts}] 12510d565efSmrg [@option{-d}|@option{--display-progress}] 12610d565efSmrg [@option{-f}|@option{--function-summaries}] 1270fc04c29Smrg [@option{-i}|@option{--json-format}] 128c7a68eb7Smrg [@option{-j}|@option{--human-readable}] 129c7a68eb7Smrg [@option{-k}|@option{--use-colors}] 13010d565efSmrg [@option{-l}|@option{--long-file-names}] 13110d565efSmrg [@option{-m}|@option{--demangled-names}] 13210d565efSmrg [@option{-n}|@option{--no-output}] 13310d565efSmrg [@option{-o}|@option{--object-directory} @var{directory|file}] 13410d565efSmrg [@option{-p}|@option{--preserve-paths}] 1350fc04c29Smrg [@option{-q}|@option{--use-hotness-colors}] 13610d565efSmrg [@option{-r}|@option{--relative-only}] 13710d565efSmrg [@option{-s}|@option{--source-prefix} @var{directory}] 1380fc04c29Smrg [@option{-t}|@option{--stdout}] 13910d565efSmrg [@option{-u}|@option{--unconditional-branches}] 14010d565efSmrg [@option{-x}|@option{--hash-filenames}] 14110d565efSmrg @var{files} 14210d565efSmrg@c man end 14310d565efSmrg@c man begin SEEALSO 14410d565efSmrggpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. 14510d565efSmrg@c man end 14610d565efSmrg@end ignore 14710d565efSmrg 14810d565efSmrg@c man begin OPTIONS 14910d565efSmrg@table @gcctabopt 15010d565efSmrg 15110d565efSmrg@item -a 15210d565efSmrg@itemx --all-blocks 15310d565efSmrgWrite individual execution counts for every basic block. Normally gcov 15410d565efSmrgoutputs execution counts only for the main blocks of a line. With this 15510d565efSmrgoption you can determine if blocks within a single line are not being 15610d565efSmrgexecuted. 15710d565efSmrg 15810d565efSmrg@item -b 15910d565efSmrg@itemx --branch-probabilities 16010d565efSmrgWrite branch frequencies to the output file, and write branch summary 16110d565efSmrginfo to the standard output. This option allows you to see how often 16210d565efSmrgeach branch in your program was taken. Unconditional branches will not 16310d565efSmrgbe shown, unless the @option{-u} option is given. 16410d565efSmrg 16510d565efSmrg@item -c 16610d565efSmrg@itemx --branch-counts 16710d565efSmrgWrite branch frequencies as the number of branches taken, rather than 16810d565efSmrgthe percentage of branches taken. 16910d565efSmrg 17010d565efSmrg@item -d 17110d565efSmrg@itemx --display-progress 17210d565efSmrgDisplay the progress on the standard output. 17310d565efSmrg 17410d565efSmrg@item -f 17510d565efSmrg@itemx --function-summaries 17610d565efSmrgOutput summaries for each function in addition to the file level summary. 17710d565efSmrg 17810d565efSmrg@item -h 17910d565efSmrg@itemx --help 18010d565efSmrgDisplay help about using @command{gcov} (on the standard output), and 18110d565efSmrgexit without doing any further processing. 18210d565efSmrg 18310d565efSmrg@item -i 1840fc04c29Smrg@itemx --json-format 1850fc04c29SmrgOutput gcov file in an easy-to-parse JSON intermediate format 1860fc04c29Smrgwhich does not require source code for generation. The JSON 1870fc04c29Smrgfile is compressed with gzip compression algorithm 1880fc04c29Smrgand the files have @file{.gcov.json.gz} extension. 18910d565efSmrg 1900fc04c29SmrgStructure of the JSON is following: 19110d565efSmrg 19210d565efSmrg@smallexample 1930fc04c29Smrg@{ 1940fc04c29Smrg "current_working_directory": @var{current_working_directory}, 1950fc04c29Smrg "data_file": @var{data_file}, 1960fc04c29Smrg "format_version": @var{format_version}, 1970fc04c29Smrg "gcc_version": @var{gcc_version} 1980fc04c29Smrg "files": [@var{file}] 1990fc04c29Smrg@} 200c7a68eb7Smrg@end smallexample 20110d565efSmrg 2020fc04c29SmrgFields of the root element have following semantics: 20310d565efSmrg 2040fc04c29Smrg@itemize @bullet 2050fc04c29Smrg@item 2060fc04c29Smrg@var{current_working_directory}: working directory where 2070fc04c29Smrga compilation unit was compiled 2080fc04c29Smrg 2090fc04c29Smrg@item 2100fc04c29Smrg@var{data_file}: name of the data file (GCDA) 2110fc04c29Smrg 2120fc04c29Smrg@item 2130fc04c29Smrg@var{format_version}: semantic version of the format 2140fc04c29Smrg 2150fc04c29Smrg@item 2160fc04c29Smrg@var{gcc_version}: version of the GCC compiler 2170fc04c29Smrg@end itemize 2180fc04c29Smrg 2190fc04c29SmrgEach @var{file} has the following form: 22010d565efSmrg 22110d565efSmrg@smallexample 2220fc04c29Smrg@{ 2230fc04c29Smrg "file": @var{file_name}, 2240fc04c29Smrg "functions": [@var{function}], 2250fc04c29Smrg "lines": [@var{line}] 2260fc04c29Smrg@} 22710d565efSmrg@end smallexample 22810d565efSmrg 2290fc04c29SmrgFields of the @var{file} element have following semantics: 2300fc04c29Smrg 2310fc04c29Smrg@itemize @bullet 2320fc04c29Smrg@item 2330fc04c29Smrg@var{file_name}: name of the source file 2340fc04c29Smrg@end itemize 2350fc04c29Smrg 2360fc04c29SmrgEach @var{function} has the following form: 2370fc04c29Smrg 2380fc04c29Smrg@smallexample 2390fc04c29Smrg@{ 2400fc04c29Smrg "blocks": @var{blocks}, 2410fc04c29Smrg "blocks_executed": @var{blocks_executed}, 2420fc04c29Smrg "demangled_name": "@var{demangled_name}, 2430fc04c29Smrg "end_column": @var{end_column}, 2440fc04c29Smrg "end_line": @var{end_line}, 2450fc04c29Smrg "execution_count": @var{execution_count}, 2460fc04c29Smrg "name": @var{name}, 2470fc04c29Smrg "start_column": @var{start_column} 2480fc04c29Smrg "start_line": @var{start_line} 2490fc04c29Smrg@} 2500fc04c29Smrg@end smallexample 2510fc04c29Smrg 2520fc04c29SmrgFields of the @var{function} element have following semantics: 2530fc04c29Smrg 2540fc04c29Smrg@itemize @bullet 2550fc04c29Smrg@item 2560fc04c29Smrg@var{blocks}: number of blocks that are in the function 2570fc04c29Smrg 2580fc04c29Smrg@item 2590fc04c29Smrg@var{blocks_executed}: number of executed blocks of the function 2600fc04c29Smrg 2610fc04c29Smrg@item 2620fc04c29Smrg@var{demangled_name}: demangled name of the function 2630fc04c29Smrg 2640fc04c29Smrg@item 2650fc04c29Smrg@var{end_column}: column in the source file where the function ends 2660fc04c29Smrg 2670fc04c29Smrg@item 2680fc04c29Smrg@var{end_line}: line in the source file where the function ends 2690fc04c29Smrg 2700fc04c29Smrg@item 2710fc04c29Smrg@var{execution_count}: number of executions of the function 2720fc04c29Smrg 2730fc04c29Smrg@item 2740fc04c29Smrg@var{name}: name of the function 2750fc04c29Smrg 2760fc04c29Smrg@item 2770fc04c29Smrg@var{start_column}: column in the source file where the function begins 2780fc04c29Smrg 2790fc04c29Smrg@item 2800fc04c29Smrg@var{start_line}: line in the source file where the function begins 2810fc04c29Smrg@end itemize 2820fc04c29Smrg 2830fc04c29SmrgNote that line numbers and column numbers number from 1. In the current 2840fc04c29Smrgimplementation, @var{start_line} and @var{start_column} do not include 2850fc04c29Smrgany template parameters and the leading return type but that 2860fc04c29Smrgthis is likely to be fixed in the future. 2870fc04c29Smrg 2880fc04c29SmrgEach @var{line} has the following form: 2890fc04c29Smrg 2900fc04c29Smrg@smallexample 2910fc04c29Smrg@{ 2920fc04c29Smrg "branches": [@var{branch}], 2930fc04c29Smrg "count": @var{count}, 2940fc04c29Smrg "line_number": @var{line_number}, 2950fc04c29Smrg "unexecuted_block": @var{unexecuted_block} 2960fc04c29Smrg "function_name": @var{function_name}, 2970fc04c29Smrg@} 2980fc04c29Smrg@end smallexample 2990fc04c29Smrg 3000fc04c29SmrgBranches are present only with @var{-b} option. 3010fc04c29SmrgFields of the @var{line} element have following semantics: 3020fc04c29Smrg 3030fc04c29Smrg@itemize @bullet 3040fc04c29Smrg@item 3050fc04c29Smrg@var{count}: number of executions of the line 3060fc04c29Smrg 3070fc04c29Smrg@item 3080fc04c29Smrg@var{line_number}: line number 3090fc04c29Smrg 3100fc04c29Smrg@item 3110fc04c29Smrg@var{unexecuted_block}: flag whether the line contains an unexecuted block 3120fc04c29Smrg(not all statements on the line are executed) 3130fc04c29Smrg 3140fc04c29Smrg@item 3150fc04c29Smrg@var{function_name}: a name of a function this @var{line} belongs to 3160fc04c29Smrg(for a line with an inlined statements can be not set) 3170fc04c29Smrg@end itemize 3180fc04c29Smrg 3190fc04c29SmrgEach @var{branch} has the following form: 3200fc04c29Smrg 3210fc04c29Smrg@smallexample 3220fc04c29Smrg@{ 3230fc04c29Smrg "count": @var{count}, 3240fc04c29Smrg "fallthrough": @var{fallthrough}, 3250fc04c29Smrg "throw": @var{throw} 3260fc04c29Smrg@} 3270fc04c29Smrg@end smallexample 3280fc04c29Smrg 3290fc04c29SmrgFields of the @var{branch} element have following semantics: 3300fc04c29Smrg 3310fc04c29Smrg@itemize @bullet 3320fc04c29Smrg@item 3330fc04c29Smrg@var{count}: number of executions of the branch 3340fc04c29Smrg 3350fc04c29Smrg@item 3360fc04c29Smrg@var{fallthrough}: true when the branch is a fall through branch 3370fc04c29Smrg 3380fc04c29Smrg@item 3390fc04c29Smrg@var{throw}: true when the branch is an exceptional branch 3400fc04c29Smrg@end itemize 3410fc04c29Smrg 342c7a68eb7Smrg@item -j 343c7a68eb7Smrg@itemx --human-readable 3440fc04c29SmrgWrite counts in human readable format (like 24.6k). 345c7a68eb7Smrg 346c7a68eb7Smrg@item -k 347c7a68eb7Smrg@itemx --use-colors 348c7a68eb7Smrg 349c7a68eb7SmrgUse colors for lines of code that have zero coverage. We use red color for 350c7a68eb7Smrgnon-exceptional lines and cyan for exceptional. Same colors are used for 351c7a68eb7Smrgbasic blocks with @option{-a} option. 352c7a68eb7Smrg 35310d565efSmrg@item -l 35410d565efSmrg@itemx --long-file-names 35510d565efSmrgCreate long file names for included source files. For example, if the 35610d565efSmrgheader file @file{x.h} contains code, and was included in the file 35710d565efSmrg@file{a.c}, then running @command{gcov} on the file @file{a.c} will 35810d565efSmrgproduce an output file called @file{a.c##x.h.gcov} instead of 35910d565efSmrg@file{x.h.gcov}. This can be useful if @file{x.h} is included in 36010d565efSmrgmultiple source files and you want to see the individual 36110d565efSmrgcontributions. If you use the @samp{-p} option, both the including 36210d565efSmrgand included file names will be complete path names. 36310d565efSmrg 36410d565efSmrg@item -m 36510d565efSmrg@itemx --demangled-names 36610d565efSmrgDisplay demangled function names in output. The default is to show 36710d565efSmrgmangled function names. 36810d565efSmrg 36910d565efSmrg@item -n 37010d565efSmrg@itemx --no-output 37110d565efSmrgDo not create the @command{gcov} output file. 37210d565efSmrg 37310d565efSmrg@item -o @var{directory|file} 37410d565efSmrg@itemx --object-directory @var{directory} 37510d565efSmrg@itemx --object-file @var{file} 37610d565efSmrgSpecify either the directory containing the gcov data files, or the 37710d565efSmrgobject path name. The @file{.gcno}, and 37810d565efSmrg@file{.gcda} data files are searched for using this option. If a directory 37910d565efSmrgis specified, the data files are in that directory and named after the 38010d565efSmrginput file name, without its extension. If a file is specified here, 38110d565efSmrgthe data files are named after that file, without its extension. 38210d565efSmrg 38310d565efSmrg@item -p 38410d565efSmrg@itemx --preserve-paths 38510d565efSmrgPreserve complete path information in the names of generated 38610d565efSmrg@file{.gcov} files. Without this option, just the filename component is 38710d565efSmrgused. With this option, all directories are used, with @samp{/} characters 38810d565efSmrgtranslated to @samp{#} characters, @file{.} directory components 38910d565efSmrgremoved and unremoveable @file{..} 39010d565efSmrgcomponents renamed to @samp{^}. This is useful if sourcefiles are in several 39110d565efSmrgdifferent directories. 39210d565efSmrg 3930fc04c29Smrg@item -q 3940fc04c29Smrg@itemx --use-hotness-colors 3950fc04c29Smrg 3960fc04c29SmrgEmit perf-like colored output for hot lines. Legend of the color scale 3970fc04c29Smrgis printed at the very beginning of the output file. 3980fc04c29Smrg 39910d565efSmrg@item -r 40010d565efSmrg@itemx --relative-only 40110d565efSmrgOnly output information about source files with a relative pathname 40210d565efSmrg(after source prefix elision). Absolute paths are usually system 40310d565efSmrgheader files and coverage of any inline functions therein is normally 40410d565efSmrguninteresting. 40510d565efSmrg 40610d565efSmrg@item -s @var{directory} 40710d565efSmrg@itemx --source-prefix @var{directory} 40810d565efSmrgA prefix for source file names to remove when generating the output 40910d565efSmrgcoverage files. This option is useful when building in a separate 41010d565efSmrgdirectory, and the pathname to the source directory is not wanted when 41110d565efSmrgdetermining the output file names. Note that this prefix detection is 41210d565efSmrgapplied before determining whether the source file is absolute. 41310d565efSmrg 4140fc04c29Smrg@item -t 4150fc04c29Smrg@itemx --stdout 4160fc04c29SmrgOutput to standard output instead of output files. 4170fc04c29Smrg 41810d565efSmrg@item -u 41910d565efSmrg@itemx --unconditional-branches 42010d565efSmrgWhen branch probabilities are given, include those of unconditional branches. 42110d565efSmrgUnconditional branches are normally not interesting. 42210d565efSmrg 42310d565efSmrg@item -v 42410d565efSmrg@itemx --version 42510d565efSmrgDisplay the @command{gcov} version number (on the standard output), 42610d565efSmrgand exit without doing any further processing. 42710d565efSmrg 42810d565efSmrg@item -w 42910d565efSmrg@itemx --verbose 43010d565efSmrgPrint verbose informations related to basic blocks and arcs. 43110d565efSmrg 43210d565efSmrg@item -x 43310d565efSmrg@itemx --hash-filenames 4340fc04c29SmrgWhen using @var{--preserve-paths}, 4350fc04c29Smrggcov uses the full pathname of the source files to create 43610d565efSmrgan output filename. This can lead to long filenames that can overflow 43710d565efSmrgfilesystem limits. This option creates names of the form 43810d565efSmrg@file{@var{source-file}##@var{md5}.gcov}, 43910d565efSmrgwhere the @var{source-file} component is the final filename part and 44010d565efSmrgthe @var{md5} component is calculated from the full mangled name that 4410fc04c29Smrgwould have been used otherwise. The option is an alternative 4420fc04c29Smrgto the @var{--preserve-paths} on systems which have a filesystem limit. 44310d565efSmrg 44410d565efSmrg@end table 44510d565efSmrg 44610d565efSmrg@command{gcov} should be run with the current directory the same as that 44710d565efSmrgwhen you invoked the compiler. Otherwise it will not be able to locate 44810d565efSmrgthe source files. @command{gcov} produces files called 44910d565efSmrg@file{@var{mangledname}.gcov} in the current directory. These contain 45010d565efSmrgthe coverage information of the source file they correspond to. 45110d565efSmrgOne @file{.gcov} file is produced for each source (or header) file 45210d565efSmrgcontaining code, 45310d565efSmrgwhich was compiled to produce the data files. The @var{mangledname} part 45410d565efSmrgof the output file name is usually simply the source file name, but can 45510d565efSmrgbe something more complicated if the @samp{-l} or @samp{-p} options are 45610d565efSmrggiven. Refer to those options for details. 45710d565efSmrg 45810d565efSmrgIf you invoke @command{gcov} with multiple input files, the 45910d565efSmrgcontributions from each input file are summed. Typically you would 46010d565efSmrginvoke it with the same list of files as the final link of your executable. 46110d565efSmrg 46210d565efSmrgThe @file{.gcov} files contain the @samp{:} separated fields along with 46310d565efSmrgprogram source code. The format is 46410d565efSmrg 46510d565efSmrg@smallexample 46610d565efSmrg@var{execution_count}:@var{line_number}:@var{source line text} 46710d565efSmrg@end smallexample 46810d565efSmrg 46910d565efSmrgAdditional block information may succeed each line, when requested by 47010d565efSmrgcommand line option. The @var{execution_count} is @samp{-} for lines 47110d565efSmrgcontaining no code. Unexecuted lines are marked @samp{#####} or 47210d565efSmrg@samp{=====}, depending on whether they are reachable by 47310d565efSmrgnon-exceptional paths or only exceptional paths such as C++ exception 4740fc04c29Smrghandlers, respectively. Given the @samp{-a} option, unexecuted blocks are 47510d565efSmrgmarked @samp{$$$$$} or @samp{%%%%%}, depending on whether a basic block 47610d565efSmrgis reachable via non-exceptional or exceptional paths. 477c7a68eb7SmrgExecuted basic blocks having a statement with zero @var{execution_count} 4780fc04c29Smrgend with @samp{*} character and are colored with magenta color with 4790fc04c29Smrgthe @option{-k} option. This functionality is not supported in Ada. 48010d565efSmrg 48110d565efSmrgNote that GCC can completely remove the bodies of functions that are 48210d565efSmrgnot needed -- for instance if they are inlined everywhere. Such functions 48310d565efSmrgare marked with @samp{-}, which can be confusing. 48410d565efSmrgUse the @option{-fkeep-inline-functions} and @option{-fkeep-static-functions} 48510d565efSmrgoptions to retain these functions and 48610d565efSmrgallow gcov to properly show their @var{execution_count}. 48710d565efSmrg 48810d565efSmrgSome lines of information at the start have @var{line_number} of zero. 48910d565efSmrgThese preamble lines are of the form 49010d565efSmrg 49110d565efSmrg@smallexample 49210d565efSmrg-:0:@var{tag}:@var{value} 49310d565efSmrg@end smallexample 49410d565efSmrg 49510d565efSmrgThe ordering and number of these preamble lines will be augmented as 49610d565efSmrg@command{gcov} development progresses --- do not rely on them remaining 49710d565efSmrgunchanged. Use @var{tag} to locate a particular preamble line. 49810d565efSmrg 49910d565efSmrgThe additional block information is of the form 50010d565efSmrg 50110d565efSmrg@smallexample 50210d565efSmrg@var{tag} @var{information} 50310d565efSmrg@end smallexample 50410d565efSmrg 50510d565efSmrgThe @var{information} is human readable, but designed to be simple 50610d565efSmrgenough for machine parsing too. 50710d565efSmrg 50810d565efSmrgWhen printing percentages, 0% and 100% are only printed when the values 50910d565efSmrgare @emph{exactly} 0% and 100% respectively. Other values which would 51010d565efSmrgconventionally be rounded to 0% or 100% are instead printed as the 51110d565efSmrgnearest non-boundary value. 51210d565efSmrg 5130fc04c29SmrgWhen using @command{gcov}, you must first compile your program 5140fc04c29Smrgwith a special GCC option @samp{--coverage}. 51510d565efSmrgThis tells the compiler to generate additional information needed by 51610d565efSmrggcov (basically a flow graph of the program) and also includes 51710d565efSmrgadditional code in the object files for generating the extra profiling 51810d565efSmrginformation needed by gcov. These additional files are placed in the 51910d565efSmrgdirectory where the object file is located. 52010d565efSmrg 52110d565efSmrgRunning the program will cause profile output to be generated. For each 52210d565efSmrgsource file compiled with @option{-fprofile-arcs}, an accompanying 52310d565efSmrg@file{.gcda} file will be placed in the object file directory. 52410d565efSmrg 52510d565efSmrgRunning @command{gcov} with your program's source file names as arguments 52610d565efSmrgwill now produce a listing of the code along with frequency of execution 527c7a68eb7Smrgfor each line. For example, if your program is called @file{tmp.cpp}, this 52810d565efSmrgis what you see when you use the basic @command{gcov} facility: 52910d565efSmrg 53010d565efSmrg@smallexample 5310fc04c29Smrg$ g++ --coverage tmp.cpp 53210d565efSmrg$ a.out 533c7a68eb7Smrg$ gcov tmp.cpp -m 534c7a68eb7SmrgFile 'tmp.cpp' 535c7a68eb7SmrgLines executed:92.86% of 14 536c7a68eb7SmrgCreating 'tmp.cpp.gcov' 53710d565efSmrg@end smallexample 53810d565efSmrg 539c7a68eb7SmrgThe file @file{tmp.cpp.gcov} contains output from @command{gcov}. 54010d565efSmrgHere is a sample: 54110d565efSmrg 54210d565efSmrg@smallexample 543c7a68eb7Smrg -: 0:Source:tmp.cpp 5440fc04c29Smrg -: 0:Working directory:/home/gcc/testcase 54510d565efSmrg -: 0:Graph:tmp.gcno 54610d565efSmrg -: 0:Data:tmp.gcda 54710d565efSmrg -: 0:Runs:1 54810d565efSmrg -: 0:Programs:1 54910d565efSmrg -: 1:#include <stdio.h> 55010d565efSmrg -: 2: 551c7a68eb7Smrg -: 3:template<class T> 552c7a68eb7Smrg -: 4:class Foo 553c7a68eb7Smrg -: 5:@{ 554c7a68eb7Smrg -: 6: public: 555c7a68eb7Smrg 1*: 7: Foo(): b (1000) @{@} 556c7a68eb7Smrg------------------ 557c7a68eb7SmrgFoo<char>::Foo(): 558c7a68eb7Smrg #####: 7: Foo(): b (1000) @{@} 559c7a68eb7Smrg------------------ 560c7a68eb7SmrgFoo<int>::Foo(): 561c7a68eb7Smrg 1: 7: Foo(): b (1000) @{@} 562c7a68eb7Smrg------------------ 563c7a68eb7Smrg 2*: 8: void inc () @{ b++; @} 564c7a68eb7Smrg------------------ 565c7a68eb7SmrgFoo<char>::inc(): 566c7a68eb7Smrg #####: 8: void inc () @{ b++; @} 567c7a68eb7Smrg------------------ 568c7a68eb7SmrgFoo<int>::inc(): 569c7a68eb7Smrg 2: 8: void inc () @{ b++; @} 570c7a68eb7Smrg------------------ 571c7a68eb7Smrg -: 9: 572c7a68eb7Smrg -: 10: private: 573c7a68eb7Smrg -: 11: int b; 574c7a68eb7Smrg -: 12:@}; 575c7a68eb7Smrg -: 13: 576c7a68eb7Smrg -: 14:template class Foo<int>; 577c7a68eb7Smrg -: 15:template class Foo<char>; 578c7a68eb7Smrg -: 16: 579c7a68eb7Smrg -: 17:int 580c7a68eb7Smrg 1: 18:main (void) 581c7a68eb7Smrg -: 19:@{ 582c7a68eb7Smrg -: 20: int i, total; 583c7a68eb7Smrg 1: 21: Foo<int> counter; 584c7a68eb7Smrg -: 22: 585c7a68eb7Smrg 1: 23: counter.inc(); 586c7a68eb7Smrg 1: 24: counter.inc(); 587c7a68eb7Smrg 1: 25: total = 0; 588c7a68eb7Smrg -: 26: 589c7a68eb7Smrg 11: 27: for (i = 0; i < 10; i++) 590c7a68eb7Smrg 10: 28: total += i; 591c7a68eb7Smrg -: 29: 592c7a68eb7Smrg 1*: 30: int v = total > 100 ? 1 : 2; 593c7a68eb7Smrg -: 31: 594c7a68eb7Smrg 1: 32: if (total != 45) 595c7a68eb7Smrg #####: 33: printf ("Failure\n"); 596c7a68eb7Smrg -: 34: else 597c7a68eb7Smrg 1: 35: printf ("Success\n"); 598c7a68eb7Smrg 1: 36: return 0; 599c7a68eb7Smrg -: 37:@} 60010d565efSmrg@end smallexample 60110d565efSmrg 602c7a68eb7SmrgNote that line 7 is shown in the report multiple times. First occurrence 603c7a68eb7Smrgpresents total number of execution of the line and the next two belong 604c7a68eb7Smrgto instances of class Foo constructors. As you can also see, line 30 contains 605c7a68eb7Smrgsome unexecuted basic blocks and thus execution count has asterisk symbol. 606c7a68eb7Smrg 60710d565efSmrgWhen you use the @option{-a} option, you will get individual block 60810d565efSmrgcounts, and the output looks like this: 60910d565efSmrg 61010d565efSmrg@smallexample 611c7a68eb7Smrg -: 0:Source:tmp.cpp 6120fc04c29Smrg -: 0:Working directory:/home/gcc/testcase 61310d565efSmrg -: 0:Graph:tmp.gcno 61410d565efSmrg -: 0:Data:tmp.gcda 61510d565efSmrg -: 0:Runs:1 61610d565efSmrg -: 0:Programs:1 61710d565efSmrg -: 1:#include <stdio.h> 61810d565efSmrg -: 2: 619c7a68eb7Smrg -: 3:template<class T> 620c7a68eb7Smrg -: 4:class Foo 621c7a68eb7Smrg -: 5:@{ 622c7a68eb7Smrg -: 6: public: 623c7a68eb7Smrg 1*: 7: Foo(): b (1000) @{@} 624c7a68eb7Smrg------------------ 625c7a68eb7SmrgFoo<char>::Foo(): 626c7a68eb7Smrg #####: 7: Foo(): b (1000) @{@} 627c7a68eb7Smrg------------------ 628c7a68eb7SmrgFoo<int>::Foo(): 629c7a68eb7Smrg 1: 7: Foo(): b (1000) @{@} 630c7a68eb7Smrg------------------ 631c7a68eb7Smrg 2*: 8: void inc () @{ b++; @} 632c7a68eb7Smrg------------------ 633c7a68eb7SmrgFoo<char>::inc(): 634c7a68eb7Smrg #####: 8: void inc () @{ b++; @} 635c7a68eb7Smrg------------------ 636c7a68eb7SmrgFoo<int>::inc(): 637c7a68eb7Smrg 2: 8: void inc () @{ b++; @} 638c7a68eb7Smrg------------------ 639c7a68eb7Smrg -: 9: 640c7a68eb7Smrg -: 10: private: 641c7a68eb7Smrg -: 11: int b; 642c7a68eb7Smrg -: 12:@}; 643c7a68eb7Smrg -: 13: 644c7a68eb7Smrg -: 14:template class Foo<int>; 645c7a68eb7Smrg -: 15:template class Foo<char>; 646c7a68eb7Smrg -: 16: 647c7a68eb7Smrg -: 17:int 648c7a68eb7Smrg 1: 18:main (void) 649c7a68eb7Smrg -: 19:@{ 650c7a68eb7Smrg -: 20: int i, total; 651c7a68eb7Smrg 1: 21: Foo<int> counter; 652c7a68eb7Smrg 1: 21-block 0 653c7a68eb7Smrg -: 22: 654c7a68eb7Smrg 1: 23: counter.inc(); 655c7a68eb7Smrg 1: 23-block 0 656c7a68eb7Smrg 1: 24: counter.inc(); 657c7a68eb7Smrg 1: 24-block 0 658c7a68eb7Smrg 1: 25: total = 0; 659c7a68eb7Smrg -: 26: 660c7a68eb7Smrg 11: 27: for (i = 0; i < 10; i++) 661c7a68eb7Smrg 1: 27-block 0 662c7a68eb7Smrg 11: 27-block 1 663c7a68eb7Smrg 10: 28: total += i; 664c7a68eb7Smrg 10: 28-block 0 665c7a68eb7Smrg -: 29: 666c7a68eb7Smrg 1*: 30: int v = total > 100 ? 1 : 2; 667c7a68eb7Smrg 1: 30-block 0 668c7a68eb7Smrg %%%%%: 30-block 1 669c7a68eb7Smrg 1: 30-block 2 670c7a68eb7Smrg -: 31: 671c7a68eb7Smrg 1: 32: if (total != 45) 672c7a68eb7Smrg 1: 32-block 0 673c7a68eb7Smrg #####: 33: printf ("Failure\n"); 674c7a68eb7Smrg %%%%%: 33-block 0 675c7a68eb7Smrg -: 34: else 676c7a68eb7Smrg 1: 35: printf ("Success\n"); 677c7a68eb7Smrg 1: 35-block 0 678c7a68eb7Smrg 1: 36: return 0; 679c7a68eb7Smrg 1: 36-block 0 680c7a68eb7Smrg -: 37:@} 68110d565efSmrg@end smallexample 68210d565efSmrg 68310d565efSmrgIn this mode, each basic block is only shown on one line -- the last 68410d565efSmrgline of the block. A multi-line block will only contribute to the 68510d565efSmrgexecution count of that last line, and other lines will not be shown 68610d565efSmrgto contain code, unless previous blocks end on those lines. 68710d565efSmrgThe total execution count of a line is shown and subsequent lines show 68810d565efSmrgthe execution counts for individual blocks that end on that line. After each 68910d565efSmrgblock, the branch and call counts of the block will be shown, if the 69010d565efSmrg@option{-b} option is given. 69110d565efSmrg 69210d565efSmrgBecause of the way GCC instruments calls, a call count can be shown 69310d565efSmrgafter a line with no individual blocks. 694c7a68eb7SmrgAs you can see, line 33 contains a basic block that was not executed. 69510d565efSmrg 69610d565efSmrg@need 450 69710d565efSmrgWhen you use the @option{-b} option, your output looks like this: 69810d565efSmrg 69910d565efSmrg@smallexample 700c7a68eb7Smrg -: 0:Source:tmp.cpp 7010fc04c29Smrg -: 0:Working directory:/home/gcc/testcase 70210d565efSmrg -: 0:Graph:tmp.gcno 70310d565efSmrg -: 0:Data:tmp.gcda 70410d565efSmrg -: 0:Runs:1 70510d565efSmrg -: 0:Programs:1 70610d565efSmrg -: 1:#include <stdio.h> 70710d565efSmrg -: 2: 708c7a68eb7Smrg -: 3:template<class T> 709c7a68eb7Smrg -: 4:class Foo 710c7a68eb7Smrg -: 5:@{ 711c7a68eb7Smrg -: 6: public: 712c7a68eb7Smrg 1*: 7: Foo(): b (1000) @{@} 713c7a68eb7Smrg------------------ 714c7a68eb7SmrgFoo<char>::Foo(): 715c7a68eb7Smrgfunction Foo<char>::Foo() called 0 returned 0% blocks executed 0% 716c7a68eb7Smrg #####: 7: Foo(): b (1000) @{@} 717c7a68eb7Smrg------------------ 718c7a68eb7SmrgFoo<int>::Foo(): 719c7a68eb7Smrgfunction Foo<int>::Foo() called 1 returned 100% blocks executed 100% 720c7a68eb7Smrg 1: 7: Foo(): b (1000) @{@} 721c7a68eb7Smrg------------------ 722c7a68eb7Smrg 2*: 8: void inc () @{ b++; @} 723c7a68eb7Smrg------------------ 724c7a68eb7SmrgFoo<char>::inc(): 725c7a68eb7Smrgfunction Foo<char>::inc() called 0 returned 0% blocks executed 0% 726c7a68eb7Smrg #####: 8: void inc () @{ b++; @} 727c7a68eb7Smrg------------------ 728c7a68eb7SmrgFoo<int>::inc(): 729c7a68eb7Smrgfunction Foo<int>::inc() called 2 returned 100% blocks executed 100% 730c7a68eb7Smrg 2: 8: void inc () @{ b++; @} 731c7a68eb7Smrg------------------ 732c7a68eb7Smrg -: 9: 733c7a68eb7Smrg -: 10: private: 734c7a68eb7Smrg -: 11: int b; 735c7a68eb7Smrg -: 12:@}; 736c7a68eb7Smrg -: 13: 737c7a68eb7Smrg -: 14:template class Foo<int>; 738c7a68eb7Smrg -: 15:template class Foo<char>; 739c7a68eb7Smrg -: 16: 740c7a68eb7Smrg -: 17:int 741c7a68eb7Smrgfunction main called 1 returned 100% blocks executed 81% 742c7a68eb7Smrg 1: 18:main (void) 743c7a68eb7Smrg -: 19:@{ 744c7a68eb7Smrg -: 20: int i, total; 745c7a68eb7Smrg 1: 21: Foo<int> counter; 746c7a68eb7Smrgcall 0 returned 100% 747c7a68eb7Smrgbranch 1 taken 100% (fallthrough) 748c7a68eb7Smrgbranch 2 taken 0% (throw) 749c7a68eb7Smrg -: 22: 750c7a68eb7Smrg 1: 23: counter.inc(); 751c7a68eb7Smrgcall 0 returned 100% 752c7a68eb7Smrgbranch 1 taken 100% (fallthrough) 753c7a68eb7Smrgbranch 2 taken 0% (throw) 754c7a68eb7Smrg 1: 24: counter.inc(); 755c7a68eb7Smrgcall 0 returned 100% 756c7a68eb7Smrgbranch 1 taken 100% (fallthrough) 757c7a68eb7Smrgbranch 2 taken 0% (throw) 758c7a68eb7Smrg 1: 25: total = 0; 759c7a68eb7Smrg -: 26: 760c7a68eb7Smrg 11: 27: for (i = 0; i < 10; i++) 76110d565efSmrgbranch 0 taken 91% (fallthrough) 76210d565efSmrgbranch 1 taken 9% 763c7a68eb7Smrg 10: 28: total += i; 764c7a68eb7Smrg -: 29: 765c7a68eb7Smrg 1*: 30: int v = total > 100 ? 1 : 2; 76610d565efSmrgbranch 0 taken 0% (fallthrough) 76710d565efSmrgbranch 1 taken 100% 768c7a68eb7Smrg -: 31: 769c7a68eb7Smrg 1: 32: if (total != 45) 770c7a68eb7Smrgbranch 0 taken 0% (fallthrough) 771c7a68eb7Smrgbranch 1 taken 100% 772c7a68eb7Smrg #####: 33: printf ("Failure\n"); 77310d565efSmrgcall 0 never executed 774c7a68eb7Smrgbranch 1 never executed 775c7a68eb7Smrgbranch 2 never executed 776c7a68eb7Smrg -: 34: else 777c7a68eb7Smrg 1: 35: printf ("Success\n"); 778c7a68eb7Smrgcall 0 returned 100% 779c7a68eb7Smrgbranch 1 taken 100% (fallthrough) 780c7a68eb7Smrgbranch 2 taken 0% (throw) 781c7a68eb7Smrg 1: 36: return 0; 782c7a68eb7Smrg -: 37:@} 78310d565efSmrg@end smallexample 78410d565efSmrg 78510d565efSmrgFor each function, a line is printed showing how many times the function 78610d565efSmrgis called, how many times it returns and what percentage of the 78710d565efSmrgfunction's blocks were executed. 78810d565efSmrg 78910d565efSmrgFor each basic block, a line is printed after the last line of the basic 79010d565efSmrgblock describing the branch or call that ends the basic block. There can 79110d565efSmrgbe multiple branches and calls listed for a single source line if there 79210d565efSmrgare multiple basic blocks that end on that line. In this case, the 79310d565efSmrgbranches and calls are each given a number. There is no simple way to map 79410d565efSmrgthese branches and calls back to source constructs. In general, though, 79510d565efSmrgthe lowest numbered branch or call will correspond to the leftmost construct 79610d565efSmrgon the source line. 79710d565efSmrg 79810d565efSmrgFor a branch, if it was executed at least once, then a percentage 79910d565efSmrgindicating the number of times the branch was taken divided by the 80010d565efSmrgnumber of times the branch was executed will be printed. Otherwise, the 80110d565efSmrgmessage ``never executed'' is printed. 80210d565efSmrg 80310d565efSmrgFor a call, if it was executed at least once, then a percentage 80410d565efSmrgindicating the number of times the call returned divided by the number 80510d565efSmrgof times the call was executed will be printed. This will usually be 80610d565efSmrg100%, but may be less for functions that call @code{exit} or @code{longjmp}, 80710d565efSmrgand thus may not return every time they are called. 80810d565efSmrg 80910d565efSmrgThe execution counts are cumulative. If the example program were 81010d565efSmrgexecuted again without removing the @file{.gcda} file, the count for the 81110d565efSmrgnumber of times each line in the source was executed would be added to 81210d565efSmrgthe results of the previous run(s). This is potentially useful in 81310d565efSmrgseveral ways. For example, it could be used to accumulate data over a 81410d565efSmrgnumber of program runs as part of a test verification suite, or to 81510d565efSmrgprovide more accurate long-term information over a large number of 81610d565efSmrgprogram runs. 81710d565efSmrg 81810d565efSmrgThe data in the @file{.gcda} files is saved immediately before the program 81910d565efSmrgexits. For each source file compiled with @option{-fprofile-arcs}, the 82010d565efSmrgprofiling code first attempts to read in an existing @file{.gcda} file; if 82110d565efSmrgthe file doesn't match the executable (differing number of basic block 82210d565efSmrgcounts) it will ignore the contents of the file. It then adds in the 82310d565efSmrgnew execution counts and finally writes the data to the file. 82410d565efSmrg 82510d565efSmrg@node Gcov and Optimization 82610d565efSmrg@section Using @command{gcov} with GCC Optimization 82710d565efSmrg 82810d565efSmrgIf you plan to use @command{gcov} to help optimize your code, you must 8290fc04c29Smrgfirst compile your program with a special GCC option 8300fc04c29Smrg@samp{--coverage}. Aside from that, you can use any 83110d565efSmrgother GCC options; but if you want to prove that every single line 83210d565efSmrgin your program was executed, you should not compile with optimization 83310d565efSmrgat the same time. On some machines the optimizer can eliminate some 83410d565efSmrgsimple code lines by combining them with other lines. For example, code 83510d565efSmrglike this: 83610d565efSmrg 83710d565efSmrg@smallexample 83810d565efSmrgif (a != b) 83910d565efSmrg c = 1; 84010d565efSmrgelse 84110d565efSmrg c = 0; 84210d565efSmrg@end smallexample 84310d565efSmrg 84410d565efSmrg@noindent 84510d565efSmrgcan be compiled into one instruction on some machines. In this case, 84610d565efSmrgthere is no way for @command{gcov} to calculate separate execution counts 84710d565efSmrgfor each line because there isn't separate code for each line. Hence 84810d565efSmrgthe @command{gcov} output looks like this if you compiled the program with 84910d565efSmrgoptimization: 85010d565efSmrg 85110d565efSmrg@smallexample 85210d565efSmrg 100: 12:if (a != b) 85310d565efSmrg 100: 13: c = 1; 85410d565efSmrg 100: 14:else 85510d565efSmrg 100: 15: c = 0; 85610d565efSmrg@end smallexample 85710d565efSmrg 85810d565efSmrgThe output shows that this block of code, combined by optimization, 85910d565efSmrgexecuted 100 times. In one sense this result is correct, because there 86010d565efSmrgwas only one instruction representing all four of these lines. However, 86110d565efSmrgthe output does not indicate how many times the result was 0 and how 86210d565efSmrgmany times the result was 1. 86310d565efSmrg 86410d565efSmrgInlineable functions can create unexpected line counts. Line counts are 86510d565efSmrgshown for the source code of the inlineable function, but what is shown 86610d565efSmrgdepends on where the function is inlined, or if it is not inlined at all. 86710d565efSmrg 86810d565efSmrgIf the function is not inlined, the compiler must emit an out of line 86910d565efSmrgcopy of the function, in any object file that needs it. If 87010d565efSmrg@file{fileA.o} and @file{fileB.o} both contain out of line bodies of a 87110d565efSmrgparticular inlineable function, they will also both contain coverage 87210d565efSmrgcounts for that function. When @file{fileA.o} and @file{fileB.o} are 87310d565efSmrglinked together, the linker will, on many systems, select one of those 87410d565efSmrgout of line bodies for all calls to that function, and remove or ignore 87510d565efSmrgthe other. Unfortunately, it will not remove the coverage counters for 87610d565efSmrgthe unused function body. Hence when instrumented, all but one use of 87710d565efSmrgthat function will show zero counts. 87810d565efSmrg 87910d565efSmrgIf the function is inlined in several places, the block structure in 88010d565efSmrgeach location might not be the same. For instance, a condition might 88110d565efSmrgnow be calculable at compile time in some instances. Because the 88210d565efSmrgcoverage of all the uses of the inline function will be shown for the 88310d565efSmrgsame source lines, the line counts themselves might seem inconsistent. 88410d565efSmrg 88510d565efSmrgLong-running applications can use the @code{__gcov_reset} and @code{__gcov_dump} 88610d565efSmrgfacilities to restrict profile collection to the program region of 88710d565efSmrginterest. Calling @code{__gcov_reset(void)} will clear all profile counters 88810d565efSmrgto zero, and calling @code{__gcov_dump(void)} will cause the profile information 88910d565efSmrgcollected at that point to be dumped to @file{.gcda} output files. 89010d565efSmrgInstrumented applications use a static destructor with priority 99 89110d565efSmrgto invoke the @code{__gcov_dump} function. Thus @code{__gcov_dump} 89210d565efSmrgis executed after all user defined static destructors, 89310d565efSmrgas well as handlers registered with @code{atexit}. 89410d565efSmrgIf an executable loads a dynamic shared object via dlopen functionality, 89510d565efSmrg@option{-Wl,--dynamic-list-data} is needed to dump all profile data. 89610d565efSmrg 8970fc04c29SmrgProfiling run-time library reports various errors related to profile 8980fc04c29Smrgmanipulation and profile saving. Errors are printed into standard error output 8990fc04c29Smrgor @samp{GCOV_ERROR_FILE} file, if environment variable is used. 9000fc04c29SmrgIn order to terminate immediately after an errors occurs 9010fc04c29Smrgset @samp{GCOV_EXIT_AT_ERROR} environment variable. 9020fc04c29SmrgThat can help users to find profile clashing which leads 9030fc04c29Smrgto a misleading profile. 9040fc04c29Smrg 90510d565efSmrg@c man end 90610d565efSmrg 90710d565efSmrg@node Gcov Data Files 90810d565efSmrg@section Brief Description of @command{gcov} Data Files 90910d565efSmrg 91010d565efSmrg@command{gcov} uses two files for profiling. The names of these files 91110d565efSmrgare derived from the original @emph{object} file by substituting the 91210d565efSmrgfile suffix with either @file{.gcno}, or @file{.gcda}. The files 91310d565efSmrgcontain coverage and profile data stored in a platform-independent format. 91410d565efSmrgThe @file{.gcno} files are placed in the same directory as the object 91510d565efSmrgfile. By default, the @file{.gcda} files are also stored in the same 91610d565efSmrgdirectory as the object file, but the GCC @option{-fprofile-dir} option 91710d565efSmrgmay be used to store the @file{.gcda} files in a separate directory. 91810d565efSmrg 91910d565efSmrgThe @file{.gcno} notes file is generated when the source file is compiled 92010d565efSmrgwith the GCC @option{-ftest-coverage} option. It contains information to 92110d565efSmrgreconstruct the basic block graphs and assign source line numbers to 92210d565efSmrgblocks. 92310d565efSmrg 92410d565efSmrgThe @file{.gcda} count data file is generated when a program containing 92510d565efSmrgobject files built with the GCC @option{-fprofile-arcs} option is executed. 92610d565efSmrgA separate @file{.gcda} file is created for each object file compiled with 92710d565efSmrgthis option. It contains arc transition counts, value profile counts, and 92810d565efSmrgsome summary information. 92910d565efSmrg 930c7a68eb7SmrgIt is not recommended to access the coverage files directly. 931c7a68eb7SmrgConsumers should use the intermediate format that is provided 9320fc04c29Smrgby @command{gcov} tool via @option{--json-format} option. 93310d565efSmrg 93410d565efSmrg@node Cross-profiling 93510d565efSmrg@section Data File Relocation to Support Cross-Profiling 93610d565efSmrg 93710d565efSmrgRunning the program will cause profile output to be generated. For each 93810d565efSmrgsource file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda} 93910d565efSmrgfile will be placed in the object file directory. That implicitly requires 94010d565efSmrgrunning the program on the same system as it was built or having the same 94110d565efSmrgabsolute directory structure on the target system. The program will try 94210d565efSmrgto create the needed directory structure, if it is not already present. 94310d565efSmrg 94410d565efSmrgTo support cross-profiling, a program compiled with @option{-fprofile-arcs} 94510d565efSmrgcan relocate the data files based on two environment variables: 94610d565efSmrg 94710d565efSmrg@itemize @bullet 94810d565efSmrg@item 94910d565efSmrgGCOV_PREFIX contains the prefix to add to the absolute paths 95010d565efSmrgin the object file. Prefix can be absolute, or relative. The 95110d565efSmrgdefault is no prefix. 95210d565efSmrg 95310d565efSmrg@item 95410d565efSmrgGCOV_PREFIX_STRIP indicates the how many initial directory names to strip off 95510d565efSmrgthe hardwired absolute paths. Default value is 0. 95610d565efSmrg 95710d565efSmrg@emph{Note:} If GCOV_PREFIX_STRIP is set without GCOV_PREFIX is undefined, 95810d565efSmrg then a relative path is made out of the hardwired absolute paths. 95910d565efSmrg@end itemize 96010d565efSmrg 96110d565efSmrgFor example, if the object file @file{/user/build/foo.o} was built with 96210d565efSmrg@option{-fprofile-arcs}, the final executable will try to create the data file 96310d565efSmrg@file{/user/build/foo.gcda} when running on the target system. This will 96410d565efSmrgfail if the corresponding directory does not exist and it is unable to create 96510d565efSmrgit. This can be overcome by, for example, setting the environment as 96610d565efSmrg@samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}. Such a 96710d565efSmrgsetting will name the data file @file{/target/run/build/foo.gcda}. 96810d565efSmrg 96910d565efSmrgYou must move the data files to the expected directory tree in order to 97010d565efSmrguse them for profile directed optimizations (@option{-fprofile-use}), or to 97110d565efSmrguse the @command{gcov} tool. 972