| .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) |
| .\" |
| .\" Standard preamble: |
| .\" ======================================================================== |
| .de Sp \" Vertical space (when we can't use .PP) |
| .if t .sp .5v |
| .if n .sp |
| .. |
| .de Vb \" Begin verbatim text |
| .ft CW |
| .nf |
| .ne \\$1 |
| .. |
| .de Ve \" End verbatim text |
| .ft R |
| .fi |
| .. |
| .\" Set up some character translations and predefined strings. \*(-- will |
| .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
| .\" give a nicer C++. Capital omega is used to do unbreakable dashes and |
| .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, |
| .\" nothing in troff, for use with C<>. |
| .tr \(*W- |
| .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| .ie n \{\ |
| . ds -- \(*W- |
| . ds PI pi |
| . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| . ds L" "" |
| . ds R" "" |
| . ds C` "" |
| . ds C' "" |
| 'br\} |
| .el\{\ |
| . ds -- \|\(em\| |
| . ds PI \(*p |
| . ds L" `` |
| . ds R" '' |
| 'br\} |
| .\" |
| .\" Escape single quotes in literal strings from groff's Unicode transform. |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" |
| .\" If the F register is turned on, we'll generate index entries on stderr for |
| .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| .\" entries marked with X<> in POD. Of course, you'll have to process the |
| .\" output yourself in some meaningful fashion. |
| .ie \nF \{\ |
| . de IX |
| . tm Index:\\$1\t\\n%\t"\\$2" |
| .. |
| . nr % 0 |
| . rr F |
| .\} |
| .el \{\ |
| . de IX |
| .. |
| .\} |
| .\" |
| .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| .\" Fear. Run. Save yourself. No user-serviceable parts. |
| . \" fudge factors for nroff and troff |
| .if n \{\ |
| . ds #H 0 |
| . ds #V .8m |
| . ds #F .3m |
| . ds #[ \f1 |
| . ds #] \fP |
| .\} |
| .if t \{\ |
| . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| . ds #V .6m |
| . ds #F 0 |
| . ds #[ \& |
| . ds #] \& |
| .\} |
| . \" simple accents for nroff and troff |
| .if n \{\ |
| . ds ' \& |
| . ds ` \& |
| . ds ^ \& |
| . ds , \& |
| . ds ~ ~ |
| . ds / |
| .\} |
| .if t \{\ |
| . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| .\} |
| . \" troff and (daisy-wheel) nroff accents |
| .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| .ds ae a\h'-(\w'a'u*4/10)'e |
| .ds Ae A\h'-(\w'A'u*4/10)'E |
| . \" corrections for vroff |
| .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| . \" for low resolution devices (crt and lpr) |
| .if \n(.H>23 .if \n(.V>19 \ |
| \{\ |
| . ds : e |
| . ds 8 ss |
| . ds o a |
| . ds d- d\h'-1'\(ga |
| . ds D- D\h'-1'\(hy |
| . ds th \o'bp' |
| . ds Th \o'LP' |
| . ds ae ae |
| . ds Ae AE |
| .\} |
| .rm #[ #] #H #V #F C |
| .\" ======================================================================== |
| .\" |
| .IX Title "GCOV 1" |
| .TH GCOV 1 "2013-05-06" "gcc-4.8.1" "GNU" |
| .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| .\" way too many mistakes in technical documents. |
| .if n .ad l |
| .nh |
| .SH "NAME" |
| gcov \- coverage testing tool |
| .SH "SYNOPSIS" |
| .IX Header "SYNOPSIS" |
| gcov [\fB\-v\fR|\fB\-\-version\fR] [\fB\-h\fR|\fB\-\-help\fR] |
| [\fB\-a\fR|\fB\-\-all\-blocks\fR] |
| [\fB\-b\fR|\fB\-\-branch\-probabilities\fR] |
| [\fB\-c\fR|\fB\-\-branch\-counts\fR] |
| [\fB\-u\fR|\fB\-\-unconditional\-branches\fR] |
| [\fB\-n\fR|\fB\-\-no\-output\fR] |
| [\fB\-l\fR|\fB\-\-long\-file\-names\fR] |
| [\fB\-p\fR|\fB\-\-preserve\-paths\fR] |
| [\fB\-r\fR|\fB\-\-relative\-only\fR] |
| [\fB\-f\fR|\fB\-\-function\-summaries\fR] |
| [\fB\-o\fR|\fB\-\-object\-directory\fR \fIdirectory|file\fR] |
| [\fB\-s\fR|\fB\-\-source\-prefix\fR \fIdirectory\fR] |
| [\fB\-d\fR|\fB\-\-display\-progress\fR] |
| \fIfiles\fR |
| .SH "DESCRIPTION" |
| .IX Header "DESCRIPTION" |
| \&\fBgcov\fR is a test coverage program. Use it in concert with \s-1GCC\s0 |
| to analyze your programs to help create more efficient, faster running |
| code and to discover untested parts of your program. You can use |
| \&\fBgcov\fR as a profiling tool to help discover where your |
| optimization efforts will best affect your code. You can also use |
| \&\fBgcov\fR along with the other profiling tool, \fBgprof\fR, to |
| assess which parts of your code use the greatest amount of computing |
| time. |
| .PP |
| Profiling tools help you analyze your code's performance. Using a |
| profiler such as \fBgcov\fR or \fBgprof\fR, you can find out some |
| basic performance statistics, such as: |
| .IP "\(bu" 4 |
| how often each line of code executes |
| .IP "\(bu" 4 |
| what lines of code are actually executed |
| .IP "\(bu" 4 |
| how much computing time each section of code uses |
| .PP |
| Once you know these things about how your code works when compiled, you |
| can look at each module to see which modules should be optimized. |
| \&\fBgcov\fR helps you determine where to work on optimization. |
| .PP |
| Software developers also use coverage testing in concert with |
| testsuites, to make sure software is actually good enough for a release. |
| Testsuites can verify that a program works as expected; a coverage |
| program tests to see how much of the program is exercised by the |
| testsuite. Developers can then determine what kinds of test cases need |
| to be added to the testsuites to create both better testing and a better |
| final product. |
| .PP |
| You should compile your code without optimization if you plan to use |
| \&\fBgcov\fR because the optimization, by combining some lines of code |
| into one function, may not give you as much information as you need to |
| look for `hot spots' where the code is using a great deal of computer |
| time. Likewise, because \fBgcov\fR accumulates statistics by line (at |
| the lowest resolution), it works best with a programming style that |
| places only one statement on each line. If you use complicated macros |
| that expand to loops or to other control structures, the statistics are |
| less helpful\-\-\-they only report on the line where the macro call |
| appears. If your complex macros behave like functions, you can replace |
| them with inline functions to solve this problem. |
| .PP |
| \&\fBgcov\fR creates a logfile called \fI\fIsourcefile\fI.gcov\fR which |
| indicates how many times each line of a source file \fI\fIsourcefile\fI.c\fR |
| has executed. You can use these logfiles along with \fBgprof\fR to aid |
| in fine-tuning the performance of your programs. \fBgprof\fR gives |
| timing information you can use along with the information you get from |
| \&\fBgcov\fR. |
| .PP |
| \&\fBgcov\fR works only on code compiled with \s-1GCC\s0. It is not |
| compatible with any other profiling or test coverage mechanism. |
| .SH "OPTIONS" |
| .IX Header "OPTIONS" |
| .IP "\fB\-h\fR" 4 |
| .IX Item "-h" |
| .PD 0 |
| .IP "\fB\-\-help\fR" 4 |
| .IX Item "--help" |
| .PD |
| Display help about using \fBgcov\fR (on the standard output), and |
| exit without doing any further processing. |
| .IP "\fB\-v\fR" 4 |
| .IX Item "-v" |
| .PD 0 |
| .IP "\fB\-\-version\fR" 4 |
| .IX Item "--version" |
| .PD |
| Display the \fBgcov\fR version number (on the standard output), |
| and exit without doing any further processing. |
| .IP "\fB\-a\fR" 4 |
| .IX Item "-a" |
| .PD 0 |
| .IP "\fB\-\-all\-blocks\fR" 4 |
| .IX Item "--all-blocks" |
| .PD |
| Write individual execution counts for every basic block. Normally gcov |
| outputs execution counts only for the main blocks of a line. With this |
| option you can determine if blocks within a single line are not being |
| executed. |
| .IP "\fB\-b\fR" 4 |
| .IX Item "-b" |
| .PD 0 |
| .IP "\fB\-\-branch\-probabilities\fR" 4 |
| .IX Item "--branch-probabilities" |
| .PD |
| Write branch frequencies to the output file, and write branch summary |
| info to the standard output. This option allows you to see how often |
| each branch in your program was taken. Unconditional branches will not |
| be shown, unless the \fB\-u\fR option is given. |
| .IP "\fB\-c\fR" 4 |
| .IX Item "-c" |
| .PD 0 |
| .IP "\fB\-\-branch\-counts\fR" 4 |
| .IX Item "--branch-counts" |
| .PD |
| Write branch frequencies as the number of branches taken, rather than |
| the percentage of branches taken. |
| .IP "\fB\-n\fR" 4 |
| .IX Item "-n" |
| .PD 0 |
| .IP "\fB\-\-no\-output\fR" 4 |
| .IX Item "--no-output" |
| .PD |
| Do not create the \fBgcov\fR output file. |
| .IP "\fB\-l\fR" 4 |
| .IX Item "-l" |
| .PD 0 |
| .IP "\fB\-\-long\-file\-names\fR" 4 |
| .IX Item "--long-file-names" |
| .PD |
| Create long file names for included source files. For example, if the |
| header file \fIx.h\fR contains code, and was included in the file |
| \&\fIa.c\fR, then running \fBgcov\fR on the file \fIa.c\fR will |
| produce an output file called \fIa.c##x.h.gcov\fR instead of |
| \&\fIx.h.gcov\fR. This can be useful if \fIx.h\fR is included in |
| multiple source files and you want to see the individual |
| contributions. If you use the \fB\-p\fR option, both the including |
| and included file names will be complete path names. |
| .IP "\fB\-p\fR" 4 |
| .IX Item "-p" |
| .PD 0 |
| .IP "\fB\-\-preserve\-paths\fR" 4 |
| .IX Item "--preserve-paths" |
| .PD |
| Preserve complete path information in the names of generated |
| \&\fI.gcov\fR files. Without this option, just the filename component is |
| used. With this option, all directories are used, with \fB/\fR characters |
| translated to \fB#\fR characters, \fI.\fR directory components |
| removed and unremoveable \fI..\fR |
| components renamed to \fB^\fR. This is useful if sourcefiles are in several |
| different directories. |
| .IP "\fB\-r\fR" 4 |
| .IX Item "-r" |
| .PD 0 |
| .IP "\fB\-\-relative\-only\fR" 4 |
| .IX Item "--relative-only" |
| .PD |
| Only output information about source files with a relative pathname |
| (after source prefix elision). Absolute paths are usually system |
| header files and coverage of any inline functions therein is normally |
| uninteresting. |
| .IP "\fB\-f\fR" 4 |
| .IX Item "-f" |
| .PD 0 |
| .IP "\fB\-\-function\-summaries\fR" 4 |
| .IX Item "--function-summaries" |
| .PD |
| Output summaries for each function in addition to the file level summary. |
| .IP "\fB\-o\fR \fIdirectory|file\fR" 4 |
| .IX Item "-o directory|file" |
| .PD 0 |
| .IP "\fB\-\-object\-directory\fR \fIdirectory\fR" 4 |
| .IX Item "--object-directory directory" |
| .IP "\fB\-\-object\-file\fR \fIfile\fR" 4 |
| .IX Item "--object-file file" |
| .PD |
| Specify either the directory containing the gcov data files, or the |
| object path name. The \fI.gcno\fR, and |
| \&\fI.gcda\fR data files are searched for using this option. If a directory |
| is specified, the data files are in that directory and named after the |
| input file name, without its extension. If a file is specified here, |
| the data files are named after that file, without its extension. |
| .IP "\fB\-s\fR \fIdirectory\fR" 4 |
| .IX Item "-s directory" |
| .PD 0 |
| .IP "\fB\-\-source\-prefix\fR \fIdirectory\fR" 4 |
| .IX Item "--source-prefix directory" |
| .PD |
| A prefix for source file names to remove when generating the output |
| coverage files. This option is useful when building in a separate |
| directory, and the pathname to the source directory is not wanted when |
| determining the output file names. Note that this prefix detection is |
| applied before determining whether the source file is absolute. |
| .IP "\fB\-u\fR" 4 |
| .IX Item "-u" |
| .PD 0 |
| .IP "\fB\-\-unconditional\-branches\fR" 4 |
| .IX Item "--unconditional-branches" |
| .PD |
| When branch probabilities are given, include those of unconditional branches. |
| Unconditional branches are normally not interesting. |
| .IP "\fB\-d\fR" 4 |
| .IX Item "-d" |
| .PD 0 |
| .IP "\fB\-\-display\-progress\fR" 4 |
| .IX Item "--display-progress" |
| .PD |
| Display the progress on the standard output. |
| .PP |
| \&\fBgcov\fR should be run with the current directory the same as that |
| when you invoked the compiler. Otherwise it will not be able to locate |
| the source files. \fBgcov\fR produces files called |
| \&\fI\fImangledname\fI.gcov\fR in the current directory. These contain |
| the coverage information of the source file they correspond to. |
| One \fI.gcov\fR file is produced for each source (or header) file |
| containing code, |
| which was compiled to produce the data files. The \fImangledname\fR part |
| of the output file name is usually simply the source file name, but can |
| be something more complicated if the \fB\-l\fR or \fB\-p\fR options are |
| given. Refer to those options for details. |
| .PP |
| If you invoke \fBgcov\fR with multiple input files, the |
| contributions from each input file are summed. Typically you would |
| invoke it with the same list of files as the final link of your executable. |
| .PP |
| The \fI.gcov\fR files contain the \fB:\fR separated fields along with |
| program source code. The format is |
| .PP |
| .Vb 1 |
| \& <execution_count>:<line_number>:<source line text> |
| .Ve |
| .PP |
| Additional block information may succeed each line, when requested by |
| command line option. The \fIexecution_count\fR is \fB\-\fR for lines |
| containing no code. Unexecuted lines are marked \fB#####\fR or |
| \&\fB====\fR, depending on whether they are reachable by |
| non-exceptional paths or only exceptional paths such as \*(C+ exception |
| handlers, respectively. |
| .PP |
| Some lines of information at the start have \fIline_number\fR of zero. |
| These preamble lines are of the form |
| .PP |
| .Vb 1 |
| \& \-:0:<tag>:<value> |
| .Ve |
| .PP |
| The ordering and number of these preamble lines will be augmented as |
| \&\fBgcov\fR development progresses \-\-\- do not rely on them remaining |
| unchanged. Use \fItag\fR to locate a particular preamble line. |
| .PP |
| The additional block information is of the form |
| .PP |
| .Vb 1 |
| \& <tag> <information> |
| .Ve |
| .PP |
| The \fIinformation\fR is human readable, but designed to be simple |
| enough for machine parsing too. |
| .PP |
| When printing percentages, 0% and 100% are only printed when the values |
| are \fIexactly\fR 0% and 100% respectively. Other values which would |
| conventionally be rounded to 0% or 100% are instead printed as the |
| nearest non-boundary value. |
| .PP |
| When using \fBgcov\fR, you must first compile your program with two |
| special \s-1GCC\s0 options: \fB\-fprofile\-arcs \-ftest\-coverage\fR. |
| This tells the compiler to generate additional information needed by |
| gcov (basically a flow graph of the program) and also includes |
| additional code in the object files for generating the extra profiling |
| information needed by gcov. These additional files are placed in the |
| directory where the object file is located. |
| .PP |
| Running the program will cause profile output to be generated. For each |
| source file compiled with \fB\-fprofile\-arcs\fR, an accompanying |
| \&\fI.gcda\fR file will be placed in the object file directory. |
| .PP |
| Running \fBgcov\fR with your program's source file names as arguments |
| will now produce a listing of the code along with frequency of execution |
| for each line. For example, if your program is called \fItmp.c\fR, this |
| is what you see when you use the basic \fBgcov\fR facility: |
| .PP |
| .Vb 5 |
| \& $ gcc \-fprofile\-arcs \-ftest\-coverage tmp.c |
| \& $ a.out |
| \& $ gcov tmp.c |
| \& 90.00% of 10 source lines executed in file tmp.c |
| \& Creating tmp.c.gcov. |
| .Ve |
| .PP |
| The file \fItmp.c.gcov\fR contains output from \fBgcov\fR. |
| Here is a sample: |
| .PP |
| .Vb 10 |
| \& \-: 0:Source:tmp.c |
| \& \-: 0:Graph:tmp.gcno |
| \& \-: 0:Data:tmp.gcda |
| \& \-: 0:Runs:1 |
| \& \-: 0:Programs:1 |
| \& \-: 1:#include <stdio.h> |
| \& \-: 2: |
| \& \-: 3:int main (void) |
| \& 1: 4:{ |
| \& 1: 5: int i, total; |
| \& \-: 6: |
| \& 1: 7: total = 0; |
| \& \-: 8: |
| \& 11: 9: for (i = 0; i < 10; i++) |
| \& 10: 10: total += i; |
| \& \-: 11: |
| \& 1: 12: if (total != 45) |
| \& #####: 13: printf ("Failure\en"); |
| \& \-: 14: else |
| \& 1: 15: printf ("Success\en"); |
| \& 1: 16: return 0; |
| \& \-: 17:} |
| .Ve |
| .PP |
| When you use the \fB\-a\fR option, you will get individual block |
| counts, and the output looks like this: |
| .PP |
| .Vb 10 |
| \& \-: 0:Source:tmp.c |
| \& \-: 0:Graph:tmp.gcno |
| \& \-: 0:Data:tmp.gcda |
| \& \-: 0:Runs:1 |
| \& \-: 0:Programs:1 |
| \& \-: 1:#include <stdio.h> |
| \& \-: 2: |
| \& \-: 3:int main (void) |
| \& 1: 4:{ |
| \& 1: 4\-block 0 |
| \& 1: 5: int i, total; |
| \& \-: 6: |
| \& 1: 7: total = 0; |
| \& \-: 8: |
| \& 11: 9: for (i = 0; i < 10; i++) |
| \& 11: 9\-block 0 |
| \& 10: 10: total += i; |
| \& 10: 10\-block 0 |
| \& \-: 11: |
| \& 1: 12: if (total != 45) |
| \& 1: 12\-block 0 |
| \& #####: 13: printf ("Failure\en"); |
| \& $$$$$: 13\-block 0 |
| \& \-: 14: else |
| \& 1: 15: printf ("Success\en"); |
| \& 1: 15\-block 0 |
| \& 1: 16: return 0; |
| \& 1: 16\-block 0 |
| \& \-: 17:} |
| .Ve |
| .PP |
| In this mode, each basic block is only shown on one line \*(-- the last |
| line of the block. A multi-line block will only contribute to the |
| execution count of that last line, and other lines will not be shown |
| to contain code, unless previous blocks end on those lines. |
| The total execution count of a line is shown and subsequent lines show |
| the execution counts for individual blocks that end on that line. After each |
| block, the branch and call counts of the block will be shown, if the |
| \&\fB\-b\fR option is given. |
| .PP |
| Because of the way \s-1GCC\s0 instruments calls, a call count can be shown |
| after a line with no individual blocks. |
| As you can see, line 13 contains a basic block that was not executed. |
| .PP |
| When you use the \fB\-b\fR option, your output looks like this: |
| .PP |
| .Vb 6 |
| \& $ gcov \-b tmp.c |
| \& 90.00% of 10 source lines executed in file tmp.c |
| \& 80.00% of 5 branches executed in file tmp.c |
| \& 80.00% of 5 branches taken at least once in file tmp.c |
| \& 50.00% of 2 calls executed in file tmp.c |
| \& Creating tmp.c.gcov. |
| .Ve |
| .PP |
| Here is a sample of a resulting \fItmp.c.gcov\fR file: |
| .PP |
| .Vb 10 |
| \& \-: 0:Source:tmp.c |
| \& \-: 0:Graph:tmp.gcno |
| \& \-: 0:Data:tmp.gcda |
| \& \-: 0:Runs:1 |
| \& \-: 0:Programs:1 |
| \& \-: 1:#include <stdio.h> |
| \& \-: 2: |
| \& \-: 3:int main (void) |
| \& function main called 1 returned 1 blocks executed 75% |
| \& 1: 4:{ |
| \& 1: 5: int i, total; |
| \& \-: 6: |
| \& 1: 7: total = 0; |
| \& \-: 8: |
| \& 11: 9: for (i = 0; i < 10; i++) |
| \& branch 0 taken 91% (fallthrough) |
| \& branch 1 taken 9% |
| \& 10: 10: total += i; |
| \& \-: 11: |
| \& 1: 12: if (total != 45) |
| \& branch 0 taken 0% (fallthrough) |
| \& branch 1 taken 100% |
| \& #####: 13: printf ("Failure\en"); |
| \& call 0 never executed |
| \& \-: 14: else |
| \& 1: 15: printf ("Success\en"); |
| \& call 0 called 1 returned 100% |
| \& 1: 16: return 0; |
| \& \-: 17:} |
| .Ve |
| .PP |
| For each function, a line is printed showing how many times the function |
| is called, how many times it returns and what percentage of the |
| function's blocks were executed. |
| .PP |
| For each basic block, a line is printed after the last line of the basic |
| block describing the branch or call that ends the basic block. There can |
| be multiple branches and calls listed for a single source line if there |
| are multiple basic blocks that end on that line. In this case, the |
| branches and calls are each given a number. There is no simple way to map |
| these branches and calls back to source constructs. In general, though, |
| the lowest numbered branch or call will correspond to the leftmost construct |
| on the source line. |
| .PP |
| For a branch, if it was executed at least once, then a percentage |
| indicating the number of times the branch was taken divided by the |
| number of times the branch was executed will be printed. Otherwise, the |
| message \*(L"never executed\*(R" is printed. |
| .PP |
| For a call, if it was executed at least once, then a percentage |
| indicating the number of times the call returned divided by the number |
| of times the call was executed will be printed. This will usually be |
| 100%, but may be less for functions that call \f(CW\*(C`exit\*(C'\fR or \f(CW\*(C`longjmp\*(C'\fR, |
| and thus may not return every time they are called. |
| .PP |
| The execution counts are cumulative. If the example program were |
| executed again without removing the \fI.gcda\fR file, the count for the |
| number of times each line in the source was executed would be added to |
| the results of the previous run(s). This is potentially useful in |
| several ways. For example, it could be used to accumulate data over a |
| number of program runs as part of a test verification suite, or to |
| provide more accurate long-term information over a large number of |
| program runs. |
| .PP |
| The data in the \fI.gcda\fR files is saved immediately before the program |
| exits. For each source file compiled with \fB\-fprofile\-arcs\fR, the |
| profiling code first attempts to read in an existing \fI.gcda\fR file; if |
| the file doesn't match the executable (differing number of basic block |
| counts) it will ignore the contents of the file. It then adds in the |
| new execution counts and finally writes the data to the file. |
| .SS "Using \fBgcov\fP with \s-1GCC\s0 Optimization" |
| .IX Subsection "Using gcov with GCC Optimization" |
| If you plan to use \fBgcov\fR to help optimize your code, you must |
| first compile your program with two special \s-1GCC\s0 options: |
| \&\fB\-fprofile\-arcs \-ftest\-coverage\fR. Aside from that, you can use any |
| other \s-1GCC\s0 options; but if you want to prove that every single line |
| in your program was executed, you should not compile with optimization |
| at the same time. On some machines the optimizer can eliminate some |
| simple code lines by combining them with other lines. For example, code |
| like this: |
| .PP |
| .Vb 4 |
| \& if (a != b) |
| \& c = 1; |
| \& else |
| \& c = 0; |
| .Ve |
| .PP |
| can be compiled into one instruction on some machines. In this case, |
| there is no way for \fBgcov\fR to calculate separate execution counts |
| for each line because there isn't separate code for each line. Hence |
| the \fBgcov\fR output looks like this if you compiled the program with |
| optimization: |
| .PP |
| .Vb 4 |
| \& 100: 12:if (a != b) |
| \& 100: 13: c = 1; |
| \& 100: 14:else |
| \& 100: 15: c = 0; |
| .Ve |
| .PP |
| The output shows that this block of code, combined by optimization, |
| executed 100 times. In one sense this result is correct, because there |
| was only one instruction representing all four of these lines. However, |
| the output does not indicate how many times the result was 0 and how |
| many times the result was 1. |
| .PP |
| Inlineable functions can create unexpected line counts. Line counts are |
| shown for the source code of the inlineable function, but what is shown |
| depends on where the function is inlined, or if it is not inlined at all. |
| .PP |
| If the function is not inlined, the compiler must emit an out of line |
| copy of the function, in any object file that needs it. If |
| \&\fIfileA.o\fR and \fIfileB.o\fR both contain out of line bodies of a |
| particular inlineable function, they will also both contain coverage |
| counts for that function. When \fIfileA.o\fR and \fIfileB.o\fR are |
| linked together, the linker will, on many systems, select one of those |
| out of line bodies for all calls to that function, and remove or ignore |
| the other. Unfortunately, it will not remove the coverage counters for |
| the unused function body. Hence when instrumented, all but one use of |
| that function will show zero counts. |
| .PP |
| If the function is inlined in several places, the block structure in |
| each location might not be the same. For instance, a condition might |
| now be calculable at compile time in some instances. Because the |
| coverage of all the uses of the inline function will be shown for the |
| same source lines, the line counts themselves might seem inconsistent. |
| .PP |
| Long-running applications can use the \f(CW\*(C`_gcov_reset\*(C'\fR and \f(CW\*(C`_gcov_dump\*(C'\fR |
| facilities to restrict profile collection to the program region of |
| interest. Calling \f(CW\*(C`_gcov_reset(void)\*(C'\fR will clear all profile counters |
| to zero, and calling \f(CW\*(C`_gcov_dump(void)\*(C'\fR will cause the profile information |
| collected at that point to be dumped to \fI.gcda\fR output files. |
| .SH "SEE ALSO" |
| .IX Header "SEE ALSO" |
| \&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), \fIgcc\fR\|(1) and the Info entry for \fIgcc\fR. |
| .SH "COPYRIGHT" |
| .IX Header "COPYRIGHT" |
| Copyright (c) 1996\-2013 Free Software Foundation, Inc. |
| .PP |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or |
| any later version published by the Free Software Foundation; with the |
| Invariant Sections being \*(L"\s-1GNU\s0 General Public License\*(R" and \*(L"Funding |
| Free Software\*(R", the Front-Cover texts being (a) (see below), and with |
| the Back-Cover Texts being (b) (see below). A copy of the license is |
| included in the \fIgfdl\fR\|(7) man page. |
| .PP |
| (a) The \s-1FSF\s0's Front-Cover Text is: |
| .PP |
| .Vb 1 |
| \& A GNU Manual |
| .Ve |
| .PP |
| (b) The \s-1FSF\s0's Back-Cover Text is: |
| .PP |
| .Vb 3 |
| \& You have freedom to copy and modify this GNU Manual, like GNU |
| \& software. Copies published by the Free Software Foundation raise |
| \& funds for GNU development. |
| .Ve |
