|
1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14 |
|
2 .\" |
|
3 .\" Standard preamble: |
|
4 .\" ======================================================================== |
|
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 .. |
|
17 .de Vb \" Begin verbatim text |
|
18 .ft CW |
|
19 .nf |
|
20 .ne \\$1 |
|
21 .. |
|
22 .de Ve \" End verbatim text |
|
23 .ft R |
|
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 |
|
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<>. |
|
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 .\" |
|
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. |
|
55 .if \nF \{\ |
|
56 . de IX |
|
57 . tm Index:\\$1\t\\n%\t"\\$2" |
|
58 .. |
|
59 . nr % 0 |
|
60 . rr F |
|
61 .\} |
|
62 .\" |
|
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
|
64 .\" way too many mistakes in technical documents. |
|
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. |
|
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 .\} |
|
78 .if t \{\ |
|
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
|
80 . ds #V .6m |
|
81 . ds #F 0 |
|
82 . ds #[ \& |
|
83 . ds #] \& |
|
84 .\} |
|
85 . \" simple accents for nroff and troff |
|
86 .if n \{\ |
|
87 . ds ' \& |
|
88 . ds ` \& |
|
89 . ds ^ \& |
|
90 . ds , \& |
|
91 . ds ~ ~ |
|
92 . ds / |
|
93 .\} |
|
94 .if t \{\ |
|
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
|
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
|
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
|
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
|
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
|
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
|
101 .\} |
|
102 . \" troff and (daisy-wheel) nroff accents |
|
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
|
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
|
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
|
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
|
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
|
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
|
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
|
110 .ds ae a\h'-(\w'a'u*4/10)'e |
|
111 .ds Ae A\h'-(\w'A'u*4/10)'E |
|
112 . \" corrections for vroff |
|
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
|
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
|
115 . \" for low resolution devices (crt and lpr) |
|
116 .if \n(.H>23 .if \n(.V>19 \ |
|
117 \{\ |
|
118 . ds : e |
|
119 . ds 8 ss |
|
120 . ds o a |
|
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 |
|
129 .\" ======================================================================== |
|
130 .\" |
|
131 .IX Title "GCOV 1" |
|
132 .TH GCOV 1 "2005-12-01" "gcc-3.4.5" "GNU" |
|
133 .SH "NAME" |
|
134 gcov \- coverage testing tool |
|
135 .SH "SYNOPSIS" |
|
136 .IX Header "SYNOPSIS" |
|
137 gcov [\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] |
|
147 .SH "DESCRIPTION" |
|
148 .IX Header "DESCRIPTION" |
|
149 \&\fBgcov\fR is a test coverage program. Use it in concert with \s-1GCC\s0 |
|
150 to analyze your programs to help create more efficient, faster running |
|
151 code and to discover untested parts of your program. You can use |
|
152 \&\fBgcov\fR as a profiling tool to help discover where your |
|
153 optimization efforts will best affect your code. You can also use |
|
154 \&\fBgcov\fR along with the other profiling tool, \fBgprof\fR, to |
|
155 assess which parts of your code use the greatest amount of computing |
|
156 time. |
|
157 .PP |
|
158 Profiling tools help you analyze your code's performance. Using a |
|
159 profiler such as \fBgcov\fR or \fBgprof\fR, you can find out some |
|
160 basic performance statistics, such as: |
|
161 .IP "\(bu" 4 |
|
162 how often each line of code executes |
|
163 .IP "\(bu" 4 |
|
164 what lines of code are actually executed |
|
165 .IP "\(bu" 4 |
|
166 how much computing time each section of code uses |
|
167 .PP |
|
168 Once you know these things about how your code works when compiled, you |
|
169 can look at each module to see which modules should be optimized. |
|
170 \&\fBgcov\fR helps you determine where to work on optimization. |
|
171 .PP |
|
172 Software developers also use coverage testing in concert with |
|
173 testsuites, to make sure software is actually good enough for a release. |
|
174 Testsuites can verify that a program works as expected; a coverage |
|
175 program tests to see how much of the program is exercised by the |
|
176 testsuite. Developers can then determine what kinds of test cases need |
|
177 to be added to the testsuites to create both better testing and a better |
|
178 final product. |
|
179 .PP |
|
180 You should compile your code without optimization if you plan to use |
|
181 \&\fBgcov\fR because the optimization, by combining some lines of code |
|
182 into one function, may not give you as much information as you need to |
|
183 look for `hot spots' where the code is using a great deal of computer |
|
184 time. Likewise, because \fBgcov\fR accumulates statistics by line (at |
|
185 the lowest resolution), it works best with a programming style that |
|
186 places only one statement on each line. If you use complicated macros |
|
187 that expand to loops or to other control structures, the statistics are |
|
188 less helpful\-\-\-they only report on the line where the macro call |
|
189 appears. If your complex macros behave like functions, you can replace |
|
190 them with inline functions to solve this problem. |
|
191 .PP |
|
192 \&\fBgcov\fR creates a logfile called \fI\fIsourcefile\fI.gcov\fR which |
|
193 indicates how many times each line of a source file \fI\fIsourcefile\fI.c\fR |
|
194 has executed. You can use these logfiles along with \fBgprof\fR to aid |
|
195 in fine-tuning the performance of your programs. \fBgprof\fR gives |
|
196 timing 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 |
|
200 compatible with any other profiling or test coverage mechanism. |
|
201 .SH "OPTIONS" |
|
202 .IX Header "OPTIONS" |
|
203 .IP "\fB\-h\fR" 4 |
|
204 .IX Item "-h" |
|
205 .PD 0 |
|
206 .IP "\fB\-\-help\fR" 4 |
|
207 .IX Item "--help" |
|
208 .PD |
|
209 Display help about using \fBgcov\fR (on the standard output), and |
|
210 exit without doing any further processing. |
|
211 .IP "\fB\-v\fR" 4 |
|
212 .IX Item "-v" |
|
213 .PD 0 |
|
214 .IP "\fB\-\-version\fR" 4 |
|
215 .IX Item "--version" |
|
216 .PD |
|
217 Display the \fBgcov\fR version number (on the standard output), |
|
218 and exit without doing any further processing. |
|
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 |
|
225 Write individual execution counts for every basic block. Normally gcov |
|
226 outputs execution counts only for the main blocks of a line. With this |
|
227 option you can determine if blocks within a single line are not being |
|
228 executed. |
|
229 .IP "\fB\-b\fR" 4 |
|
230 .IX Item "-b" |
|
231 .PD 0 |
|
232 .IP "\fB\-\-branch\-probabilities\fR" 4 |
|
233 .IX Item "--branch-probabilities" |
|
234 .PD |
|
235 Write branch frequencies to the output file, and write branch summary |
|
236 info to the standard output. This option allows you to see how often |
|
237 each branch in your program was taken. Unconditional branches will not |
|
238 be shown, unless the \fB\-u\fR option is given. |
|
239 .IP "\fB\-c\fR" 4 |
|
240 .IX Item "-c" |
|
241 .PD 0 |
|
242 .IP "\fB\-\-branch\-counts\fR" 4 |
|
243 .IX Item "--branch-counts" |
|
244 .PD |
|
245 Write branch frequencies as the number of branches taken, rather than |
|
246 the percentage of branches taken. |
|
247 .IP "\fB\-n\fR" 4 |
|
248 .IX Item "-n" |
|
249 .PD 0 |
|
250 .IP "\fB\-\-no\-output\fR" 4 |
|
251 .IX Item "--no-output" |
|
252 .PD |
|
253 Do not create the \fBgcov\fR output file. |
|
254 .IP "\fB\-l\fR" 4 |
|
255 .IX Item "-l" |
|
256 .PD 0 |
|
257 .IP "\fB\-\-long\-file\-names\fR" 4 |
|
258 .IX Item "--long-file-names" |
|
259 .PD |
|
260 Create long file names for included source files. For example, if the |
|
261 header 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 |
|
263 an output file called \fIa.c##x.h.gcov\fR instead of \fIx.h.gcov\fR. |
|
264 This can be useful if \fIx.h\fR is included in multiple source |
|
265 files. If you uses the \fB\-p\fR option, both the including and |
|
266 included 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 |
|
273 Preserve complete path information in the names of generated |
|
274 \&\fI.gcov\fR files. Without this option, just the filename component is |
|
275 used. With this option, all directories are used, with '/' characters |
|
276 translated to '#' characters, '.' directory components removed and '..' |
|
277 components renamed to '^'. This is useful if sourcefiles are in several |
|
278 different directories. It also affects the \fB\-l\fR option. |
|
279 .IP "\fB\-f\fR" 4 |
|
280 .IX Item "-f" |
|
281 .PD 0 |
|
282 .IP "\fB\-\-function\-summaries\fR" 4 |
|
283 .IX Item "--function-summaries" |
|
284 .PD |
|
285 Output summaries for each function in addition to the file level summary. |
|
286 .IP "\fB\-o\fR \fIdirectory|file\fR" 4 |
|
287 .IX Item "-o directory|file" |
|
288 .PD 0 |
|
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" |
|
293 .PD |
|
294 Specify either the directory containing the gcov data files, or the |
|
295 object path name. The \fI.gcno\fR, and |
|
296 \&\fI.gcda\fR data files are searched for using this option. If a directory |
|
297 is specified, the data files are in that directory and named after the |
|
298 source file name, without its extension. If a file is specified here, |
|
299 the data files are named after that file, without its extension. If this |
|
300 option 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 |
|
307 When branch counts are given, include those of unconditional branches. |
|
308 Unconditional branches are normally not interesting. |
|
309 .PP |
|
310 \&\fBgcov\fR should be run with the current directory the same as that |
|
311 when you invoked the compiler. Otherwise it will not be able to locate |
|
312 the source files. \fBgcov\fR produces files called |
|
313 \&\fI\fImangledname\fI.gcov\fR in the current directory. These contain |
|
314 the coverage information of the source file they correspond to. |
|
315 One \fI.gcov\fR file is produced for each source file containing code, |
|
316 which was compiled to produce the data files. The \fImangledname\fR part |
|
317 of the output file name is usually simply the source file name, but can |
|
318 be something more complicated if the \fB\-l\fR or \fB\-p\fR options are |
|
319 given. Refer to those options for details. |
|
320 .PP |
|
321 The \fI.gcov\fR files contain the ':' separated fields along with |
|
322 program source code. The format is |
|
323 .PP |
|
324 .Vb 1 |
|
325 \& <execution_count>:<line_number>:<source line text> |
|
326 .Ve |
|
327 .PP |
|
328 Additional block information may succeed each line, when requested by |
|
329 command line option. The \fIexecution_count\fR is \fB\-\fR for lines |
|
330 containing no code and \fB#####\fR for lines which were never |
|
331 executed. Some lines of information at the start have \fIline_number\fR |
|
332 of zero. |
|
333 .PP |
|
334 When printing percentages, 0% and 100% are only printed when the values |
|
335 are \fIexactly\fR 0% and 100% respectively. Other values which would |
|
336 conventionally be rounded to 0% or 100% are instead printed as the |
|
337 nearest non-boundary value. |
|
338 .PP |
|
339 When using \fBgcov\fR, you must first compile your program with two |
|
340 special \s-1GCC\s0 options: \fB\-fprofile\-arcs \-ftest\-coverage\fR. |
|
341 This tells the compiler to generate additional information needed by |
|
342 gcov (basically a flow graph of the program) and also includes |
|
343 additional code in the object files for generating the extra profiling |
|
344 information needed by gcov. These additional files are placed in the |
|
345 directory where the object file is located. |
|
346 .PP |
|
347 Running the program will cause profile output to be generated. For each |
|
348 source file compiled with \fB\-fprofile\-arcs\fR, an accompanying |
|
349 \&\fI.gcda\fR file will be placed in the object file directory. |
|
350 .PP |
|
351 Running \fBgcov\fR with your program's source file names as arguments |
|
352 will now produce a listing of the code along with frequency of execution |
|
353 for each line. For example, if your program is called \fItmp.c\fR, this |
|
354 is 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 |
|
360 \& 90.00% of 10 source lines executed in file tmp.c |
|
361 \& Creating tmp.c.gcov. |
|
362 .Ve |
|
363 .PP |
|
364 The file \fItmp.c.gcov\fR contains output from \fBgcov\fR. |
|
365 Here is a sample: |
|
366 .PP |
|
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:} |
|
391 .Ve |
|
392 .PP |
|
393 When you use the \fB\-a\fR option, you will get individual block |
|
394 counts, 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:} |
|
427 .Ve |
|
428 .PP |
|
429 In this mode, each basic block is only shown on one line \*(-- the last |
|
430 line of the block. A multi-line block will only contribute to the |
|
431 execution count of that last line, and other lines will not be shown |
|
432 to contain code, unless previous blocks end on those lines. |
|
433 The total execution count of a line is shown and subsequent lines show |
|
434 the execution counts for individual blocks that end on that line. After each |
|
435 block, the branch and call counts of the block will be shown, if the |
|
436 \&\fB\-b\fR option is given. |
|
437 .PP |
|
438 Because of the way \s-1GCC\s0 instruments calls, a call count can be shown |
|
439 after a line with no individual blocks. |
|
440 As you can see, line 13 contains a basic block that was not executed. |
|
441 .PP |
|
442 When you use the \fB\-b\fR option, your output looks like this: |
|
443 .PP |
|
444 .Vb 6 |
|
445 \& $ gcov -b 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 |
|
450 \& Creating tmp.c.gcov. |
|
451 .Ve |
|
452 .PP |
|
453 Here is a sample of a resulting \fItmp.c.gcov\fR file: |
|
454 .PP |
|
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:} |
|
485 .Ve |
|
486 .PP |
|
487 For each basic block, a line is printed after the last line of the basic |
|
488 block describing the branch or call that ends the basic block. There can |
|
489 be multiple branches and calls listed for a single source line if there |
|
490 are multiple basic blocks that end on that line. In this case, the |
|
491 branches and calls are each given a number. There is no simple way to map |
|
492 these branches and calls back to source constructs. In general, though, |
|
493 the lowest numbered branch or call will correspond to the leftmost construct |
|
494 on the source line. |
|
495 .PP |
|
496 For a branch, if it was executed at least once, then a percentage |
|
497 indicating the number of times the branch was taken divided by the |
|
498 number of times the branch was executed will be printed. Otherwise, the |
|
499 message ``never executed'' is printed. |
|
500 .PP |
|
501 For a call, if it was executed at least once, then a percentage |
|
502 indicating the number of times the call returned divided by the number |
|
503 of times the call was executed will be printed. This will usually be |
|
504 100%, but may be less for functions call \f(CW\*(C`exit\*(C'\fR or \f(CW\*(C`longjmp\*(C'\fR, |
|
505 and thus may not return every time they are called. |
|
506 .PP |
|
507 The execution counts are cumulative. If the example program were |
|
508 executed again without removing the \fI.gcda\fR file, the count for the |
|
509 number of times each line in the source was executed would be added to |
|
510 the results of the previous run(s). This is potentially useful in |
|
511 several ways. For example, it could be used to accumulate data over a |
|
512 number of program runs as part of a test verification suite, or to |
|
513 provide more accurate long-term information over a large number of |
|
514 program runs. |
|
515 .PP |
|
516 The data in the \fI.gcda\fR files is saved immediately before the program |
|
517 exits. For each source file compiled with \fB\-fprofile\-arcs\fR, the |
|
518 profiling code first attempts to read in an existing \fI.gcda\fR file; if |
|
519 the file doesn't match the executable (differing number of basic block |
|
520 counts) it will ignore the contents of the file. It then adds in the |
|
521 new execution counts and finally writes the data to the file. |
|
522 .Sh "Using \fBgcov\fP with \s-1GCC\s0 Optimization" |
|
523 .IX Subsection "Using gcov with GCC Optimization" |
|
524 If you plan to use \fBgcov\fR to help optimize your code, you must |
|
525 first compile your program with two special \s-1GCC\s0 options: |
|
526 \&\fB\-fprofile\-arcs \-ftest\-coverage\fR. Aside from that, you can use any |
|
527 other \s-1GCC\s0 options; but if you want to prove that every single line |
|
528 in your program was executed, you should not compile with optimization |
|
529 at the same time. On some machines the optimizer can eliminate some |
|
530 simple code lines by combining them with other lines. For example, code |
|
531 like this: |
|
532 .PP |
|
533 .Vb 4 |
|
534 \& if (a != b) |
|
535 \& c = 1; |
|
536 \& else |
|
537 \& c = 0; |
|
538 .Ve |
|
539 .PP |
|
540 can be compiled into one instruction on some machines. In this case, |
|
541 there is no way for \fBgcov\fR to calculate separate execution counts |
|
542 for each line because there isn't separate code for each line. Hence |
|
543 the \fBgcov\fR output looks like this if you compiled the program with |
|
544 optimization: |
|
545 .PP |
|
546 .Vb 4 |
|
547 \& 100: 12:if (a != b) |
|
548 \& 100: 13: c = 1; |
|
549 \& 100: 14:else |
|
550 \& 100: 15: c = 0; |
|
551 .Ve |
|
552 .PP |
|
553 The output shows that this block of code, combined by optimization, |
|
554 executed 100 times. In one sense this result is correct, because there |
|
555 was only one instruction representing all four of these lines. However, |
|
556 the output does not indicate how many times the result was 0 and how |
|
557 many times the result was 1. |
|
558 .PP |
|
559 Inlineable functions can create unexpected line counts. Line counts are |
|
560 shown for the source code of the inlineable function, but what is shown |
|
561 depends on where the function is inlined, or if it is not inlined at all. |
|
562 .PP |
|
563 If the function is not inlined, the compiler must emit an out of line |
|
564 copy 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 |
|
566 particular inlineable function, they will also both contain coverage |
|
567 counts for that function. When \fIfileA.o\fR and \fIfileB.o\fR are |
|
568 linked together, the linker will, on many systems, select one of those |
|
569 out of line bodies for all calls to that function, and remove or ignore |
|
570 the other. Unfortunately, it will not remove the coverage counters for |
|
571 the unused function body. Hence when instrumented, all but one use of |
|
572 that function will show zero counts. |
|
573 .PP |
|
574 If the function is inlined in several places, the block structure in |
|
575 each location might not be the same. For instance, a condition might |
|
576 now be calculable at compile time in some instances. Because the |
|
577 coverage of all the uses of the inline function will be shown for the |
|
578 same source lines, the line counts themselves might seem inconsistent. |
|
579 .SH "SEE ALSO" |
|
580 .IX Header "SEE ALSO" |
|
581 \&\fIgpl\fR\|(7), \fIgfdl\fR\|(7), \fIfsf\-funding\fR\|(7), \fIgcc\fR\|(1) and the Info entry for \fIgcc\fR. |
|
582 .SH "COPYRIGHT" |
|
583 .IX Header "COPYRIGHT" |
|
584 Copyright (c) 1996, 1997, 1999, 2000, 2001, 2002, 2003 |
|
585 Free Software Foundation, Inc. |
|
586 .PP |
|
587 Permission is granted to copy, distribute and/or modify this document |
|
588 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.2 or |
|
589 any later version published by the Free Software Foundation; with the |
|
590 Invariant Sections being ``\s-1GNU\s0 General Public License'' and ``Funding |
|
591 Free Software'', the Front-Cover texts being (a) (see below), and with |
|
592 the Back-Cover Texts being (b) (see below). A copy of the license is |
|
593 included 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 |
|
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 |