| gcov.1 (110611) | gcov.1 (162509) |
|---|---|
| 1.\" Automatically generated by Pod::Man version 1.15 2.\" Wed Feb 5 03:13:55 2003 | 1.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 |
| 3.\" 4.\" Standard preamble: | 2.\" 3.\" Standard preamble: |
| 5.\" ====================================================================== | 4.\" ======================================================================== |
| 6.de Sh \" Subsection heading 7.br 8.if t .Sp 9.ne 5 10.PP 11\fB\\$1\fR 12.PP 13.. 14.de Sp \" Vertical space (when we can't use .PP) 15.if t .sp .5v 16.if n .sp 17.. | 5.de Sh \" Subsection heading 6.br 7.if t .Sp 8.ne 5 9.PP 10\fB\\$1\fR 11.PP 12.. 13.de Sp \" Vertical space (when we can't use .PP) 14.if t .sp .5v 15.if n .sp 16.. |
| 18.de Ip \" List item 19.br 20.ie \\n(.$>=3 .ne \\$3 21.el .ne 3 22.IP "\\$1" \\$2 23.. | |
| 24.de Vb \" Begin verbatim text 25.ft CW 26.nf 27.ne \\$1 28.. 29.de Ve \" End verbatim text 30.ft R | 17.de Vb \" Begin verbatim text 18.ft CW 19.nf 20.ne \\$1 21.. 22.de Ve \" End verbatim text 23.ft R |
| 31 | |
| 32.fi 33.. 34.\" Set up some character translations and predefined strings. \*(-- will 35.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left 36.\" double quote, and \*(R" will give a right double quote. | will give a | 24.fi 25.. 26.\" Set up some character translations and predefined strings. \*(-- will 27.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left 28.\" double quote, and \*(R" will give a right double quote. | will give a |
| 37.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used 38.\" to do unbreakable dashes and therefore won't be available. \*(C` and 39.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> | 29.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to 30.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' 31.\" expand to `' in nroff, nothing in troff, for use with C<>. |
| 40.tr \(*W-|\(bv\*(Tr 41.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 42.ie n \{\ 43. ds -- \(*W- 44. ds PI pi 45. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch 46. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch 47. ds L" "" 48. ds R" "" 49. ds C` "" 50. ds C' "" 51'br\} 52.el\{\ 53. ds -- \|\(em\| 54. ds PI \(*p 55. ds L" `` 56. ds R" '' 57'br\} 58.\" | 32.tr \(*W-|\(bv\*(Tr 33.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' 34.ie n \{\ 35. ds -- \(*W- 36. ds PI pi 37. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch 38. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch 39. ds L" "" 40. ds R" "" 41. ds C` "" 42. ds C' "" 43'br\} 44.el\{\ 45. ds -- \|\(em\| 46. ds PI \(*p 47. ds L" `` 48. ds R" '' 49'br\} 50.\" |
| 59.\" If the F register is turned on, we'll generate index entries on stderr 60.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and 61.\" index entries marked with X<> in POD. Of course, you'll have to process 62.\" the output yourself in some meaningful fashion. | 51.\" If the F register is turned on, we'll generate index entries on stderr for 52.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index 53.\" entries marked with X<> in POD. Of course, you'll have to process the 54.\" output yourself in some meaningful fashion. |
| 63.if \nF \{\ 64. de IX 65. tm Index:\\$1\t\\n%\t"\\$2" 66.. 67. nr % 0 68. rr F 69.\} 70.\" | 55.if \nF \{\ 56. de IX 57. tm Index:\\$1\t\\n%\t"\\$2" 58.. 59. nr % 0 60. rr F 61.\} 62.\" |
| 71.\" For nroff, turn off justification. Always turn off hyphenation; it 72.\" makes way too many mistakes in technical documents. | 63.\" For nroff, turn off justification. Always turn off hyphenation; it makes 64.\" way too many mistakes in technical documents. |
| 73.hy 0 74.if n .na 75.\" 76.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 77.\" Fear. Run. Save yourself. No user-serviceable parts. | 65.hy 0 66.if n .na 67.\" 68.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 69.\" Fear. Run. Save yourself. No user-serviceable parts. |
| 78.bd B 3 | |
| 79. \" fudge factors for nroff and troff 80.if n \{\ 81. ds #H 0 82. ds #V .8m 83. ds #F .3m 84. ds #[ \f1 85. ds #] \fP 86.\} --- 43 unchanged lines hidden (view full) --- 130. ds d- d\h'-1'\(ga 131. ds D- D\h'-1'\(hy 132. ds th \o'bp' 133. ds Th \o'LP' 134. ds ae ae 135. ds Ae AE 136.\} 137.rm #[ #] #H #V #F C | 70. \" fudge factors for nroff and troff 71.if n \{\ 72. ds #H 0 73. ds #V .8m 74. ds #F .3m 75. ds #[ \f1 76. ds #] \fP 77.\} --- 43 unchanged lines hidden (view full) --- 121. ds d- d\h'-1'\(ga 122. ds D- D\h'-1'\(hy 123. ds th \o'bp' 124. ds Th \o'LP' 125. ds ae ae 126. ds Ae AE 127.\} 128.rm #[ #] #H #V #F C |
| 138.\" ====================================================================== | 129.\" ======================================================================== |
| 139.\" 140.IX Title "GCOV 1" | 130.\" 131.IX Title "GCOV 1" |
| 141.TH GCOV 1 "gcc-3.2.2" "2003-02-05" "GNU" 142.UC | 132.TH GCOV 1 "2006-03-06" "gcc-3.4.6" "GNU" |
| 143.SH "NAME" 144gcov \- coverage testing tool 145.SH "SYNOPSIS" 146.IX Header "SYNOPSIS" | 133.SH "NAME" 134gcov \- coverage testing tool 135.SH "SYNOPSIS" 136.IX Header "SYNOPSIS" |
| 147gcov [\fB\-v\fR|\fB\*(--version\fR] [\fB\-h\fR|\fB\*(--help\fR] 148 [\fB\-b\fR|\fB\*(--branch-probabilities\fR] [\fB\-c\fR|\fB\*(--branch-counts\fR] 149 [\fB\-n\fR|\fB\*(--no-output\fR] [\fB\-l\fR|\fB\*(--long-file-names\fR] 150 [\fB\-f\fR|\fB\*(--function-summaries\fR] 151 [\fB\-o\fR|\fB\*(--object-directory\fR \fIdirectory\fR] \fIsourcefile\fR | 137gcov [\fB\-v\fR|\fB\-\-version\fR] [\fB\-h\fR|\fB\-\-help\fR] 138 [\fB\-a\fR|\fB\-\-all\-blocks\fR] 139 [\fB\-b\fR|\fB\-\-branch\-probabilities\fR] 140 [\fB\-c\fR|\fB\-\-branch\-counts\fR] 141 [\fB\-n\fR|\fB\-\-no\-output\fR] 142 [\fB\-l\fR|\fB\-\-long\-file\-names\fR] 143 [\fB\-p\fR|\fB\-\-preserve\-paths\fR] 144 [\fB\-f\fR|\fB\-\-function\-summaries\fR] 145 [\fB\-o\fR|\fB\-\-object\-directory\fR \fIdirectory|file\fR] \fIsourcefile\fR 146 [\fB\-u\fR|\fB\-\-unconditional\-branches\fR] |
| 152.SH "DESCRIPTION" 153.IX Header "DESCRIPTION" 154\&\fBgcov\fR is a test coverage program. Use it in concert with \s-1GCC\s0 | 147.SH "DESCRIPTION" 148.IX Header "DESCRIPTION" 149\&\fBgcov\fR is a test coverage program. Use it in concert with \s-1GCC\s0 |
| 155to analyze your programs to help create more efficient, faster 156running code. You can use \fBgcov\fR as a profiling tool to help 157discover where your optimization efforts will best affect your code. You 158can also use \fBgcov\fR along with the other profiling tool, 159\&\fBgprof\fR, to assess which parts of your code use the greatest amount 160of computing time. | 150to analyze your programs to help create more efficient, faster running 151code and to discover untested parts of your program. You can use 152\&\fBgcov\fR as a profiling tool to help discover where your 153optimization efforts will best affect your code. You can also use 154\&\fBgcov\fR along with the other profiling tool, \fBgprof\fR, to 155assess which parts of your code use the greatest amount of computing 156time. |
| 161.PP 162Profiling tools help you analyze your code's performance. Using a 163profiler such as \fBgcov\fR or \fBgprof\fR, you can find out some 164basic performance statistics, such as: | 157.PP 158Profiling tools help you analyze your code's performance. Using a 159profiler such as \fBgcov\fR or \fBgprof\fR, you can find out some 160basic performance statistics, such as: |
| 165.Ip "\(bu" 4 | 161.IP "\(bu" 4 |
| 166how often each line of code executes | 162how often each line of code executes |
| 167.Ip "\(bu" 4 | 163.IP "\(bu" 4 |
| 168what lines of code are actually executed | 164what lines of code are actually executed |
| 169.Ip "\(bu" 4 | 165.IP "\(bu" 4 |
| 170how much computing time each section of code uses 171.PP 172Once you know these things about how your code works when compiled, you 173can look at each module to see which modules should be optimized. 174\&\fBgcov\fR helps you determine where to work on optimization. 175.PP 176Software developers also use coverage testing in concert with 177testsuites, to make sure software is actually good enough for a release. --- 21 unchanged lines hidden (view full) --- 199in fine-tuning the performance of your programs. \fBgprof\fR gives 200timing information you can use along with the information you get from 201\&\fBgcov\fR. 202.PP 203\&\fBgcov\fR works only on code compiled with \s-1GCC\s0. It is not 204compatible with any other profiling or test coverage mechanism. 205.SH "OPTIONS" 206.IX Header "OPTIONS" | 166how much computing time each section of code uses 167.PP 168Once you know these things about how your code works when compiled, you 169can look at each module to see which modules should be optimized. 170\&\fBgcov\fR helps you determine where to work on optimization. 171.PP 172Software developers also use coverage testing in concert with 173testsuites, to make sure software is actually good enough for a release. --- 21 unchanged lines hidden (view full) --- 195in fine-tuning the performance of your programs. \fBgprof\fR gives 196timing information you can use along with the information you get from 197\&\fBgcov\fR. 198.PP 199\&\fBgcov\fR works only on code compiled with \s-1GCC\s0. It is not 200compatible with any other profiling or test coverage mechanism. 201.SH "OPTIONS" 202.IX Header "OPTIONS" |
| 207.Ip "\fB\-h\fR" 4 | 203.IP "\fB\-h\fR" 4 |
| 208.IX Item "-h" 209.PD 0 | 204.IX Item "-h" 205.PD 0 |
| 210.Ip "\fB\*(--help\fR" 4 211.IX Item "help" | 206.IP "\fB\-\-help\fR" 4 207.IX Item "--help" |
| 212.PD 213Display help about using \fBgcov\fR (on the standard output), and 214exit without doing any further processing. | 208.PD 209Display help about using \fBgcov\fR (on the standard output), and 210exit without doing any further processing. |
| 215.Ip "\fB\-v\fR" 4 | 211.IP "\fB\-v\fR" 4 |
| 216.IX Item "-v" 217.PD 0 | 212.IX Item "-v" 213.PD 0 |
| 218.Ip "\fB\*(--version\fR" 4 219.IX Item "version" | 214.IP "\fB\-\-version\fR" 4 215.IX Item "--version" |
| 220.PD 221Display the \fBgcov\fR version number (on the standard output), 222and exit without doing any further processing. | 216.PD 217Display the \fBgcov\fR version number (on the standard output), 218and exit without doing any further processing. |
| 223.Ip "\fB\-b\fR" 4 | 219.IP "\fB\-a\fR" 4 220.IX Item "-a" 221.PD 0 222.IP "\fB\-\-all\-blocks\fR" 4 223.IX Item "--all-blocks" 224.PD 225Write individual execution counts for every basic block. Normally gcov 226outputs execution counts only for the main blocks of a line. With this 227option you can determine if blocks within a single line are not being 228executed. 229.IP "\fB\-b\fR" 4 |
| 224.IX Item "-b" 225.PD 0 | 230.IX Item "-b" 231.PD 0 |
| 226.Ip "\fB\*(--branch-probabilities\fR" 4 227.IX Item "branch-probabilities" | 232.IP "\fB\-\-branch\-probabilities\fR" 4 233.IX Item "--branch-probabilities" |
| 228.PD 229Write branch frequencies to the output file, and write branch summary 230info to the standard output. This option allows you to see how often | 234.PD 235Write branch frequencies to the output file, and write branch summary 236info to the standard output. This option allows you to see how often |
| 231each branch in your program was taken. 232.Ip "\fB\-c\fR" 4 | 237each branch in your program was taken. Unconditional branches will not 238be shown, unless the \fB\-u\fR option is given. 239.IP "\fB\-c\fR" 4 |
| 233.IX Item "-c" 234.PD 0 | 240.IX Item "-c" 241.PD 0 |
| 235.Ip "\fB\*(--branch-counts\fR" 4 236.IX Item "branch-counts" | 242.IP "\fB\-\-branch\-counts\fR" 4 243.IX Item "--branch-counts" |
| 237.PD 238Write branch frequencies as the number of branches taken, rather than 239the percentage of branches taken. | 244.PD 245Write branch frequencies as the number of branches taken, rather than 246the percentage of branches taken. |
| 240.Ip "\fB\-n\fR" 4 | 247.IP "\fB\-n\fR" 4 |
| 241.IX Item "-n" 242.PD 0 | 248.IX Item "-n" 249.PD 0 |
| 243.Ip "\fB\*(--no-output\fR" 4 244.IX Item "no-output" | 250.IP "\fB\-\-no\-output\fR" 4 251.IX Item "--no-output" |
| 245.PD 246Do not create the \fBgcov\fR output file. | 252.PD 253Do not create the \fBgcov\fR output file. |
| 247.Ip "\fB\-l\fR" 4 | 254.IP "\fB\-l\fR" 4 |
| 248.IX Item "-l" 249.PD 0 | 255.IX Item "-l" 256.PD 0 |
| 250.Ip "\fB\*(--long-file-names\fR" 4 251.IX Item "long-file-names" | 257.IP "\fB\-\-long\-file\-names\fR" 4 258.IX Item "--long-file-names" |
| 252.PD 253Create long file names for included source files. For example, if the 254header file \fIx.h\fR contains code, and was included in the file 255\&\fIa.c\fR, then running \fBgcov\fR on the file \fIa.c\fR will produce | 259.PD 260Create long file names for included source files. For example, if the 261header file \fIx.h\fR contains code, and was included in the file 262\&\fIa.c\fR, then running \fBgcov\fR on the file \fIa.c\fR will produce |
| 256an output file called \fIa.c.x.h.gcov\fR instead of \fIx.h.gcov\fR. 257This can be useful if \fIx.h\fR is included in multiple source files. 258.Ip "\fB\-f\fR" 4 | 263an output file called \fIa.c##x.h.gcov\fR instead of \fIx.h.gcov\fR. 264This can be useful if \fIx.h\fR is included in multiple source 265files. If you uses the \fB\-p\fR option, both the including and 266included file names will be complete path names. 267.IP "\fB\-p\fR" 4 268.IX Item "-p" 269.PD 0 270.IP "\fB\-\-preserve\-paths\fR" 4 271.IX Item "--preserve-paths" 272.PD 273Preserve complete path information in the names of generated 274\&\fI.gcov\fR files. Without this option, just the filename component is 275used. With this option, all directories are used, with '/' characters 276translated to '#' characters, '.' directory components removed and '..' 277components renamed to '^'. This is useful if sourcefiles are in several 278different directories. It also affects the \fB\-l\fR option. 279.IP "\fB\-f\fR" 4 |
| 259.IX Item "-f" 260.PD 0 | 280.IX Item "-f" 281.PD 0 |
| 261.Ip "\fB\*(--function-summaries\fR" 4 262.IX Item "function-summaries" | 282.IP "\fB\-\-function\-summaries\fR" 4 283.IX Item "--function-summaries" |
| 263.PD 264Output summaries for each function in addition to the file level summary. | 284.PD 285Output summaries for each function in addition to the file level summary. |
| 265.Ip "\fB\-o\fR \fIdirectory\fR" 4 266.IX Item "-o directory" | 286.IP "\fB\-o\fR \fIdirectory|file\fR" 4 287.IX Item "-o directory|file" |
| 267.PD 0 | 288.PD 0 |
| 268.Ip "\fB\*(--object-directory\fR \fIdirectory\fR" 4 269.IX Item "object-directory directory" | 289.IP "\fB\-\-object\-directory\fR \fIdirectory\fR" 4 290.IX Item "--object-directory directory" 291.IP "\fB\-\-object\-file\fR \fIfile\fR" 4 292.IX Item "--object-file file" |
| 270.PD | 293.PD |
| 271The directory where the object files live. Gcov will search for \fI.bb\fR, 272\&\fI.bbg\fR, and \fI.da\fR files in this directory. | 294Specify either the directory containing the gcov data files, or the 295object path name. The \fI.gcno\fR, and 296\&\fI.gcda\fR data files are searched for using this option. If a directory 297is specified, the data files are in that directory and named after the 298source file name, without its extension. If a file is specified here, 299the data files are named after that file, without its extension. If this 300option is not supplied, it defaults to the current directory. 301.IP "\fB\-u\fR" 4 302.IX Item "-u" 303.PD 0 304.IP "\fB\-\-unconditional\-branches\fR" 4 305.IX Item "--unconditional-branches" 306.PD 307When branch counts are given, include those of unconditional branches. 308Unconditional branches are normally not interesting. |
| 273.PP | 309.PP |
| 310\&\fBgcov\fR should be run with the current directory the same as that 311when you invoked the compiler. Otherwise it will not be able to locate 312the source files. \fBgcov\fR produces files called 313\&\fI\fImangledname\fI.gcov\fR in the current directory. These contain 314the coverage information of the source file they correspond to. 315One \fI.gcov\fR file is produced for each source file containing code, 316which was compiled to produce the data files. The \fImangledname\fR part 317of the output file name is usually simply the source file name, but can 318be something more complicated if the \fB\-l\fR or \fB\-p\fR options are 319given. Refer to those options for details. 320.PP 321The \fI.gcov\fR files contain the ':' separated fields along with 322program source code. The format is 323.PP 324.Vb 1 325\& <execution_count>:<line_number>:<source line text> 326.Ve 327.PP 328Additional block information may succeed each line, when requested by 329command line option. The \fIexecution_count\fR is \fB\-\fR for lines 330containing no code and \fB#####\fR for lines which were never 331executed. Some lines of information at the start have \fIline_number\fR 332of zero. 333.PP 334When printing percentages, 0% and 100% are only printed when the values 335are \fIexactly\fR 0% and 100% respectively. Other values which would 336conventionally be rounded to 0% or 100% are instead printed as the 337nearest non-boundary value. 338.PP |
|
| 274When using \fBgcov\fR, you must first compile your program with two | 339When using \fBgcov\fR, you must first compile your program with two |
| 275special \s-1GCC\s0 options: \fB\-fprofile-arcs \-ftest-coverage\fR. | 340special \s-1GCC\s0 options: \fB\-fprofile\-arcs \-ftest\-coverage\fR. |
| 276This tells the compiler to generate additional information needed by 277gcov (basically a flow graph of the program) and also includes 278additional code in the object files for generating the extra profiling 279information needed by gcov. These additional files are placed in the | 341This tells the compiler to generate additional information needed by 342gcov (basically a flow graph of the program) and also includes 343additional code in the object files for generating the extra profiling 344information needed by gcov. These additional files are placed in the |
| 280directory where the source code is located. | 345directory where the object file is located. |
| 281.PP 282Running the program will cause profile output to be generated. For each | 346.PP 347Running the program will cause profile output to be generated. For each |
| 283source file compiled with \fB\-fprofile-arcs\fR, an accompanying \fI.da\fR 284file will be placed in the source directory. | 348source file compiled with \fB\-fprofile\-arcs\fR, an accompanying 349\&\fI.gcda\fR file will be placed in the object file directory. |
| 285.PP 286Running \fBgcov\fR with your program's source file names as arguments 287will now produce a listing of the code along with frequency of execution 288for each line. For example, if your program is called \fItmp.c\fR, this 289is what you see when you use the basic \fBgcov\fR facility: 290.PP 291.Vb 5 292\& $ gcc -fprofile-arcs -ftest-coverage tmp.c 293\& $ a.out 294\& $ gcov tmp.c | 350.PP 351Running \fBgcov\fR with your program's source file names as arguments 352will now produce a listing of the code along with frequency of execution 353for each line. For example, if your program is called \fItmp.c\fR, this 354is what you see when you use the basic \fBgcov\fR facility: 355.PP 356.Vb 5 357\& $ gcc -fprofile-arcs -ftest-coverage tmp.c 358\& $ a.out 359\& $ gcov tmp.c |
| 295\& 87.50% of 8 source lines executed in file tmp.c | 360\& 90.00% of 10 source lines executed in file tmp.c |
| 296\& Creating tmp.c.gcov. 297.Ve | 361\& Creating tmp.c.gcov. 362.Ve |
| 363.PP |
|
| 298The file \fItmp.c.gcov\fR contains output from \fBgcov\fR. 299Here is a sample: 300.PP | 364The file \fItmp.c.gcov\fR contains output from \fBgcov\fR. 365Here is a sample: 366.PP |
| 301.Vb 3 302\& main() 303\& { 304\& 1 int i, total; | 367.Vb 23 368\& -: 0:Source:tmp.c 369\& -: 0:Graph:tmp.gcno 370\& -: 0:Data:tmp.gcda 371\& -: 0:Runs:1 372\& -: 0:Programs:1 373\& -: 1:#include <stdio.h> 374\& -: 2: 375\& -: 3:int main (void) 376\& function main called 1 returned 1 blocks executed 75% 377\& 1: 4:{ 378\& 1: 5: int i, total; 379\& -: 6: 380\& 1: 7: total = 0; 381\& -: 8: 382\& 11: 9: for (i = 0; i < 10; i++) 383\& 10: 10: total += i; 384\& -: 11: 385\& 1: 12: if (total != 45) 386\& #####: 13: printf ("Failure\en"); 387\& -: 14: else 388\& 1: 15: printf ("Success\en"); 389\& 1: 16: return 0; 390\& -: 17:} |
| 305.Ve | 391.Ve |
| 306.Vb 1 307\& 1 total = 0; | 392.PP 393When you use the \fB\-a\fR option, you will get individual block 394counts, and the output looks like this: 395.PP 396.Vb 30 397\& -: 0:Source:tmp.c 398\& -: 0:Graph:tmp.gcno 399\& -: 0:Data:tmp.gcda 400\& -: 0:Runs:1 401\& -: 0:Programs:1 402\& -: 1:#include <stdio.h> 403\& -: 2: 404\& -: 3:int main (void) 405\& function main called 1 returned 1 blocks executed 75% 406\& 1: 4:{ 407\& 1: 4-block 0 408\& 1: 5: int i, total; 409\& -: 6: 410\& 1: 7: total = 0; 411\& -: 8: 412\& 11: 9: for (i = 0; i < 10; i++) 413\& 11: 9-block 0 414\& 10: 10: total += i; 415\& 10: 10-block 0 416\& -: 11: 417\& 1: 12: if (total != 45) 418\& 1: 12-block 0 419\& #####: 13: printf ("Failure\en"); 420\& $$$$$: 13-block 0 421\& -: 14: else 422\& 1: 15: printf ("Success\en"); 423\& 1: 15-block 0 424\& 1: 16: return 0; 425\& 1: 16-block 0 426\& -: 17:} |
| 308.Ve | 427.Ve |
| 309.Vb 2 310\& 11 for (i = 0; i < 10; i++) 311\& 10 total += i; 312.Ve 313.Vb 5 314\& 1 if (total != 45) 315\& ###### printf ("Failure\en"); 316\& else 317\& 1 printf ("Success\en"); 318\& 1 } 319.Ve | 428.PP 429In this mode, each basic block is only shown on one line \*(-- the last 430line of the block. A multi-line block will only contribute to the 431execution count of that last line, and other lines will not be shown 432to contain code, unless previous blocks end on those lines. 433The total execution count of a line is shown and subsequent lines show 434the execution counts for individual blocks that end on that line. After each 435block, the branch and call counts of the block will be shown, if the 436\&\fB\-b\fR option is given. 437.PP 438Because of the way \s-1GCC\s0 instruments calls, a call count can be shown 439after a line with no individual blocks. 440As you can see, line 13 contains a basic block that was not executed. 441.PP |
| 320When you use the \fB\-b\fR option, your output looks like this: 321.PP 322.Vb 6 323\& $ gcov -b tmp.c | 442When you use the \fB\-b\fR option, your output looks like this: 443.PP 444.Vb 6 445\& $ gcov -b tmp.c |
| 324\& 87.50% of 8 source lines executed in file tmp.c 325\& 80.00% of 5 branches executed in file tmp.c 326\& 80.00% of 5 branches taken at least once in file tmp.c 327\& 50.00% of 2 calls executed in file tmp.c | 446\& 90.00% of 10 source lines executed in file tmp.c 447\& 80.00% of 5 branches executed in file tmp.c 448\& 80.00% of 5 branches taken at least once in file tmp.c 449\& 50.00% of 2 calls executed in file tmp.c |
| 328\& Creating tmp.c.gcov. 329.Ve | 450\& Creating tmp.c.gcov. 451.Ve |
| 452.PP |
|
| 330Here is a sample of a resulting \fItmp.c.gcov\fR file: 331.PP | 453Here is a sample of a resulting \fItmp.c.gcov\fR file: 454.PP |
| 332.Vb 3 333\& main() 334\& { 335\& 1 int i, total; | 455.Vb 29 456\& -: 0:Source:tmp.c 457\& -: 0:Graph:tmp.gcno 458\& -: 0:Data:tmp.gcda 459\& -: 0:Runs:1 460\& -: 0:Programs:1 461\& -: 1:#include <stdio.h> 462\& -: 2: 463\& -: 3:int main (void) 464\& function main called 1 returned 1 blocks executed 75% 465\& 1: 4:{ 466\& 1: 5: int i, total; 467\& -: 6: 468\& 1: 7: total = 0; 469\& -: 8: 470\& 11: 9: for (i = 0; i < 10; i++) 471\& branch 0 taken 91% (fallthrough) 472\& branch 1 taken 9% 473\& 10: 10: total += i; 474\& -: 11: 475\& 1: 12: if (total != 45) 476\& branch 0 taken 0% (fallthrough) 477\& branch 1 taken 100% 478\& #####: 13: printf ("Failure\en"); 479\& call 0 never executed 480\& -: 14: else 481\& 1: 15: printf ("Success\en"); 482\& call 0 called 1 returned 100% 483\& 1: 16: return 0; 484\& -: 17:} |
| 336.Ve | 485.Ve |
| 337.Vb 1 338\& 1 total = 0; 339.Ve 340.Vb 5 341\& 11 for (i = 0; i < 10; i++) 342\& branch 0 taken = 91% 343\& branch 1 taken = 100% 344\& branch 2 taken = 100% 345\& 10 total += i; 346.Ve 347.Vb 9 348\& 1 if (total != 45) 349\& branch 0 taken = 100% 350\& ###### printf ("Failure\en"); 351\& call 0 never executed 352\& branch 1 never executed 353\& else 354\& 1 printf ("Success\en"); 355\& call 0 returns = 100% 356\& 1 } 357.Ve | 486.PP |
| 358For each basic block, a line is printed after the last line of the basic 359block describing the branch or call that ends the basic block. There can 360be multiple branches and calls listed for a single source line if there 361are multiple basic blocks that end on that line. In this case, the 362branches and calls are each given a number. There is no simple way to map 363these branches and calls back to source constructs. In general, though, 364the lowest numbered branch or call will correspond to the leftmost construct 365on the source line. --- 5 unchanged lines hidden (view full) --- 371.PP 372For a call, if it was executed at least once, then a percentage 373indicating the number of times the call returned divided by the number 374of times the call was executed will be printed. This will usually be 375100%, but may be less for functions call \f(CW\*(C`exit\*(C'\fR or \f(CW\*(C`longjmp\*(C'\fR, 376and thus may not return every time they are called. 377.PP 378The execution counts are cumulative. If the example program were | 487For each basic block, a line is printed after the last line of the basic 488block describing the branch or call that ends the basic block. There can 489be multiple branches and calls listed for a single source line if there 490are multiple basic blocks that end on that line. In this case, the 491branches and calls are each given a number. There is no simple way to map 492these branches and calls back to source constructs. In general, though, 493the lowest numbered branch or call will correspond to the leftmost construct 494on the source line. --- 5 unchanged lines hidden (view full) --- 500.PP 501For a call, if it was executed at least once, then a percentage 502indicating the number of times the call returned divided by the number 503of times the call was executed will be printed. This will usually be 504100%, but may be less for functions call \f(CW\*(C`exit\*(C'\fR or \f(CW\*(C`longjmp\*(C'\fR, 505and thus may not return every time they are called. 506.PP 507The execution counts are cumulative. If the example program were |
| 379executed again without removing the \fI.da\fR file, the count for the | 508executed again without removing the \fI.gcda\fR file, the count for the |
| 380number of times each line in the source was executed would be added to | 509number of times each line in the source was executed would be added to |
| 381the results of the previous \fIrun\fR\|(s). This is potentially useful in | 510the results of the previous run(s). This is potentially useful in |
| 382several ways. For example, it could be used to accumulate data over a 383number of program runs as part of a test verification suite, or to 384provide more accurate long-term information over a large number of 385program runs. 386.PP | 511several ways. For example, it could be used to accumulate data over a 512number of program runs as part of a test verification suite, or to 513provide more accurate long-term information over a large number of 514program runs. 515.PP |
| 387The data in the \fI.da\fR files is saved immediately before the program 388exits. For each source file compiled with \fB\-fprofile-arcs\fR, the profiling 389code first attempts to read in an existing \fI.da\fR file; if the file 390doesn't match the executable (differing number of basic block counts) it 391will ignore the contents of the file. It then adds in the new execution 392counts and finally writes the data to the file. | 516The data in the \fI.gcda\fR files is saved immediately before the program 517exits. For each source file compiled with \fB\-fprofile\-arcs\fR, the 518profiling code first attempts to read in an existing \fI.gcda\fR file; if 519the file doesn't match the executable (differing number of basic block 520counts) it will ignore the contents of the file. It then adds in the 521new execution counts and finally writes the data to the file. |
| 393.Sh "Using \fBgcov\fP with \s-1GCC\s0 Optimization" 394.IX Subsection "Using gcov with GCC Optimization" 395If you plan to use \fBgcov\fR to help optimize your code, you must 396first compile your program with two special \s-1GCC\s0 options: | 522.Sh "Using \fBgcov\fP with \s-1GCC\s0 Optimization" 523.IX Subsection "Using gcov with GCC Optimization" 524If you plan to use \fBgcov\fR to help optimize your code, you must 525first compile your program with two special \s-1GCC\s0 options: |
| 397\&\fB\-fprofile-arcs \-ftest-coverage\fR. Aside from that, you can use any | 526\&\fB\-fprofile\-arcs \-ftest\-coverage\fR. Aside from that, you can use any |
| 398other \s-1GCC\s0 options; but if you want to prove that every single line 399in your program was executed, you should not compile with optimization 400at the same time. On some machines the optimizer can eliminate some 401simple code lines by combining them with other lines. For example, code 402like this: 403.PP 404.Vb 4 405\& if (a != b) 406\& c = 1; 407\& else 408\& c = 0; 409.Ve | 527other \s-1GCC\s0 options; but if you want to prove that every single line 528in your program was executed, you should not compile with optimization 529at the same time. On some machines the optimizer can eliminate some 530simple code lines by combining them with other lines. For example, code 531like this: 532.PP 533.Vb 4 534\& if (a != b) 535\& c = 1; 536\& else 537\& c = 0; 538.Ve |
| 539.PP |
|
| 410can be compiled into one instruction on some machines. In this case, 411there is no way for \fBgcov\fR to calculate separate execution counts 412for each line because there isn't separate code for each line. Hence 413the \fBgcov\fR output looks like this if you compiled the program with 414optimization: 415.PP 416.Vb 4 | 540can be compiled into one instruction on some machines. In this case, 541there is no way for \fBgcov\fR to calculate separate execution counts 542for each line because there isn't separate code for each line. Hence 543the \fBgcov\fR output looks like this if you compiled the program with 544optimization: 545.PP 546.Vb 4 |
| 417\& 100 if (a != b) 418\& 100 c = 1; 419\& 100 else 420\& 100 c = 0; | 547\& 100: 12:if (a != b) 548\& 100: 13: c = 1; 549\& 100: 14:else 550\& 100: 15: c = 0; |
| 421.Ve | 551.Ve |
| 552.PP |
|
| 422The output shows that this block of code, combined by optimization, 423executed 100 times. In one sense this result is correct, because there 424was only one instruction representing all four of these lines. However, 425the output does not indicate how many times the result was 0 and how 426many times the result was 1. | 553The output shows that this block of code, combined by optimization, 554executed 100 times. In one sense this result is correct, because there 555was only one instruction representing all four of these lines. However, 556the output does not indicate how many times the result was 0 and how 557many times the result was 1. |
| 558.PP 559Inlineable functions can create unexpected line counts. Line counts are 560shown for the source code of the inlineable function, but what is shown 561depends on where the function is inlined, or if it is not inlined at all. 562.PP 563If the function is not inlined, the compiler must emit an out of line 564copy of the function, in any object file that needs it. If 565\&\fIfileA.o\fR and \fIfileB.o\fR both contain out of line bodies of a 566particular inlineable function, they will also both contain coverage 567counts for that function. When \fIfileA.o\fR and \fIfileB.o\fR are 568linked together, the linker will, on many systems, select one of those 569out of line bodies for all calls to that function, and remove or ignore 570the other. Unfortunately, it will not remove the coverage counters for 571the unused function body. Hence when instrumented, all but one use of 572that function will show zero counts. 573.PP 574If the function is inlined in several places, the block structure in 575each location might not be the same. For instance, a condition might 576now be calculable at compile time in some instances. Because the 577coverage of all the uses of the inline function will be shown for the 578same source lines, the line counts themselves might seem inconsistent. |
|
| 427.SH "SEE ALSO" 428.IX Header "SEE ALSO" | 579.SH "SEE ALSO" 580.IX Header "SEE ALSO" |
| 429\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf-funding\fR\|(7), \fIgcc\fR\|(1) and the Info entry for \fIgcc\fR. | 581\&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), \fIgcc\fR\|(1) and the Info entry for \fIgcc\fR. |
| 430.SH "COPYRIGHT" 431.IX Header "COPYRIGHT" | 582.SH "COPYRIGHT" 583.IX Header "COPYRIGHT" |
| 432Copyright (c) 1996, 1997, 1999, 2000, 2001 Free Software Foundation, Inc. | 584Copyright (c) 1996, 1997, 1999, 2000, 2001, 2002, 2003 585Free Software Foundation, Inc. |
| 433.PP 434Permission is granted to copy, distribute and/or modify this document | 586.PP 587Permission is granted to copy, distribute and/or modify this document |
| 435under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 or | 588under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.2 or |
| 436any later version published by the Free Software Foundation; with the 437Invariant Sections being ``\s-1GNU\s0 General Public License'' and ``Funding 438Free Software'', the Front-Cover texts being (a) (see below), and with 439the Back-Cover Texts being (b) (see below). A copy of the license is 440included in the \fIgfdl\fR\|(7) man page. 441.PP 442(a) The \s-1FSF\s0's Front-Cover Text is: 443.PP 444.Vb 1 445\& A GNU Manual 446.Ve | 589any later version published by the Free Software Foundation; with the 590Invariant Sections being ``\s-1GNU\s0 General Public License'' and ``Funding 591Free Software'', the Front-Cover texts being (a) (see below), and with 592the Back-Cover Texts being (b) (see below). A copy of the license is 593included in the \fIgfdl\fR\|(7) man page. 594.PP 595(a) The \s-1FSF\s0's Front-Cover Text is: 596.PP 597.Vb 1 598\& A GNU Manual 599.Ve |
| 600.PP |
|
| 447(b) The \s-1FSF\s0's Back-Cover Text is: 448.PP 449.Vb 3 450\& You have freedom to copy and modify this GNU Manual, like GNU 451\& software. Copies published by the Free Software Foundation raise 452\& funds for GNU development. 453.Ve | 601(b) The \s-1FSF\s0's Back-Cover Text is: 602.PP 603.Vb 3 604\& You have freedom to copy and modify this GNU Manual, like GNU 605\& software. Copies published by the Free Software Foundation raise 606\& funds for GNU development. 607.Ve |