Merge branch 'master' of ssh://crater.dragonflybsd.org/repository/git/dragonfly
[dragonfly.git] / contrib / gcc-3.4 / gcc / doc / gcov.texi
CommitLineData
003757ed
MD
1@c Copyright (C) 1996, 1997, 1999, 2000, 2001,
2@c 2002, 2003, 2004 Free Software Foundation, Inc.
3@c This is part of the GCC manual.
4@c For copying conditions, see the file gcc.texi.
5
6@ignore
7@c man begin COPYRIGHT
8Copyright @copyright{} 1996, 1997, 1999, 2000, 2001, 2002, 2003
9Free Software Foundation, Inc.
10
11Permission is granted to copy, distribute and/or modify this document
12under the terms of the GNU Free Documentation License, Version 1.2 or
13any later version published by the Free Software Foundation; with the
14Invariant Sections being ``GNU General Public License'' and ``Funding
15Free Software'', the Front-Cover texts being (a) (see below), and with
16the Back-Cover Texts being (b) (see below). A copy of the license is
17included in the gfdl(7) man page.
18
19(a) The FSF's Front-Cover Text is:
20
21 A GNU Manual
22
23(b) The FSF's Back-Cover Text is:
24
25 You have freedom to copy and modify this GNU Manual, like GNU
26 software. Copies published by the Free Software Foundation raise
27 funds for GNU development.
28@c man end
29@c Set file name and title for the man page.
30@setfilename gcov
31@settitle coverage testing tool
32@end ignore
33
34@node Gcov
35@chapter @command{gcov}---a Test Coverage Program
36
37@command{gcov} is a tool you can use in conjunction with GCC to
38test code coverage in your programs.
39
40@menu
41* Gcov Intro:: Introduction to gcov.
42* Invoking Gcov:: How to use gcov.
43* Gcov and Optimization:: Using gcov with GCC optimization.
44* Gcov Data Files:: The files used by gcov.
45@end menu
46
47@node Gcov Intro
48@section Introduction to @command{gcov}
49@c man begin DESCRIPTION
50
51@command{gcov} is a test coverage program. Use it in concert with GCC
52to analyze your programs to help create more efficient, faster running
53code and to discover untested parts of your program. You can use
54@command{gcov} as a profiling tool to help discover where your
55optimization efforts will best affect your code. You can also use
56@command{gcov} along with the other profiling tool, @command{gprof}, to
57assess which parts of your code use the greatest amount of computing
58time.
59
60Profiling tools help you analyze your code's performance. Using a
61profiler such as @command{gcov} or @command{gprof}, you can find out some
62basic performance statistics, such as:
63
64@itemize @bullet
65@item
66how often each line of code executes
67
68@item
69what lines of code are actually executed
70
71@item
72how much computing time each section of code uses
73@end itemize
74
75Once you know these things about how your code works when compiled, you
76can look at each module to see which modules should be optimized.
77@command{gcov} helps you determine where to work on optimization.
78
79Software developers also use coverage testing in concert with
80testsuites, to make sure software is actually good enough for a release.
81Testsuites can verify that a program works as expected; a coverage
82program tests to see how much of the program is exercised by the
83testsuite. Developers can then determine what kinds of test cases need
84to be added to the testsuites to create both better testing and a better
85final product.
86
87You should compile your code without optimization if you plan to use
88@command{gcov} because the optimization, by combining some lines of code
89into one function, may not give you as much information as you need to
90look for `hot spots' where the code is using a great deal of computer
91time. Likewise, because @command{gcov} accumulates statistics by line (at
92the lowest resolution), it works best with a programming style that
93places only one statement on each line. If you use complicated macros
94that expand to loops or to other control structures, the statistics are
95less helpful---they only report on the line where the macro call
96appears. If your complex macros behave like functions, you can replace
97them with inline functions to solve this problem.
98
99@command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which
100indicates how many times each line of a source file @file{@var{sourcefile}.c}
101has executed. You can use these logfiles along with @command{gprof} to aid
102in fine-tuning the performance of your programs. @command{gprof} gives
103timing information you can use along with the information you get from
104@command{gcov}.
105
106@command{gcov} works only on code compiled with GCC@. It is not
107compatible with any other profiling or test coverage mechanism.
108
109@c man end
110
111@node Invoking Gcov
112@section Invoking gcov
113
114@smallexample
115gcov @r{[}@var{options}@r{]} @var{sourcefile}
116@end smallexample
117
118@command{gcov} accepts the following options:
119
120@ignore
121@c man begin SYNOPSIS
122gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}]
123 [@option{-a}|@option{--all-blocks}]
124 [@option{-b}|@option{--branch-probabilities}]
125 [@option{-c}|@option{--branch-counts}]
126 [@option{-n}|@option{--no-output}]
127 [@option{-l}|@option{--long-file-names}]
128 [@option{-p}|@option{--preserve-paths}]
129 [@option{-f}|@option{--function-summaries}]
130 [@option{-o}|@option{--object-directory} @var{directory|file}] @var{sourcefile}
131 [@option{-u}|@option{--unconditional-branches}]
132@c man end
133@c man begin SEEALSO
134gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}.
135@c man end
136@end ignore
137
138@c man begin OPTIONS
139@table @gcctabopt
140@item -h
141@itemx --help
142Display help about using @command{gcov} (on the standard output), and
143exit without doing any further processing.
144
145@item -v
146@itemx --version
147Display the @command{gcov} version number (on the standard output),
148and exit without doing any further processing.
149
150@item -a
151@itemx --all-blocks
152Write individual execution counts for every basic block. Normally gcov
153outputs execution counts only for the main blocks of a line. With this
154option you can determine if blocks within a single line are not being
155executed.
156
157@item -b
158@itemx --branch-probabilities
159Write branch frequencies to the output file, and write branch summary
160info to the standard output. This option allows you to see how often
161each branch in your program was taken. Unconditional branches will not
162be shown, unless the @option{-u} option is given.
163
164@item -c
165@itemx --branch-counts
166Write branch frequencies as the number of branches taken, rather than
167the percentage of branches taken.
168
169@item -n
170@itemx --no-output
171Do not create the @command{gcov} output file.
172
173@item -l
174@itemx --long-file-names
175Create long file names for included source files. For example, if the
176header file @file{x.h} contains code, and was included in the file
177@file{a.c}, then running @command{gcov} on the file @file{a.c} will produce
178an output file called @file{a.c##x.h.gcov} instead of @file{x.h.gcov}.
179This can be useful if @file{x.h} is included in multiple source
180files. If you uses the @samp{-p} option, both the including and
181included file names will be complete path names.
182
183@item -p
184@itemx --preserve-paths
185Preserve complete path information in the names of generated
186@file{.gcov} files. Without this option, just the filename component is
187used. With this option, all directories are used, with '/' characters
188translated to '#' characters, '.' directory components removed and '..'
189components renamed to '^'. This is useful if sourcefiles are in several
190different directories. It also affects the @samp{-l} option.
191
192@item -f
193@itemx --function-summaries
194Output summaries for each function in addition to the file level summary.
195
196@item -o @var{directory|file}
197@itemx --object-directory @var{directory}
198@itemx --object-file @var{file}
199Specify either the directory containing the gcov data files, or the
200object path name. The @file{.gcno}, and
201@file{.gcda} data files are searched for using this option. If a directory
202is specified, the data files are in that directory and named after the
203source file name, without its extension. If a file is specified here,
204the data files are named after that file, without its extension. If this
205option is not supplied, it defaults to the current directory.
206
207@item -u
208@itemx --unconditional-branches
209When branch counts are given, include those of unconditional branches.
210Unconditional branches are normally not interesting.
211
212@end table
213
214@command{gcov} should be run with the current directory the same as that
215when you invoked the compiler. Otherwise it will not be able to locate
216the source files. @command{gcov} produces files called
217@file{@var{mangledname}.gcov} in the current directory. These contain
218the coverage information of the source file they correspond to.
219One @file{.gcov} file is produced for each source file containing code,
220which was compiled to produce the data files. The @var{mangledname} part
221of the output file name is usually simply the source file name, but can
222be something more complicated if the @samp{-l} or @samp{-p} options are
223given. Refer to those options for details.
224
225The @file{.gcov} files contain the ':' separated fields along with
226program source code. The format is
227
228@smallexample
229@var{execution_count}:@var{line_number}:@var{source line text}
230@end smallexample
231
232Additional block information may succeed each line, when requested by
233command line option. The @var{execution_count} is @samp{-} for lines
234containing no code and @samp{#####} for lines which were never
235executed. Some lines of information at the start have @var{line_number}
236of zero.
237
238When printing percentages, 0% and 100% are only printed when the values
239are @emph{exactly} 0% and 100% respectively. Other values which would
240conventionally be rounded to 0% or 100% are instead printed as the
241nearest non-boundary value.
242
243When using @command{gcov}, you must first compile your program with two
244special GCC options: @samp{-fprofile-arcs -ftest-coverage}.
245This tells the compiler to generate additional information needed by
246gcov (basically a flow graph of the program) and also includes
247additional code in the object files for generating the extra profiling
248information needed by gcov. These additional files are placed in the
249directory where the object file is located.
250
251Running the program will cause profile output to be generated. For each
252source file compiled with @option{-fprofile-arcs}, an accompanying
253@file{.gcda} file will be placed in the object file directory.
254
255Running @command{gcov} with your program's source file names as arguments
256will now produce a listing of the code along with frequency of execution
257for each line. For example, if your program is called @file{tmp.c}, this
258is what you see when you use the basic @command{gcov} facility:
259
260@smallexample
261$ gcc -fprofile-arcs -ftest-coverage tmp.c
262$ a.out
263$ gcov tmp.c
26490.00% of 10 source lines executed in file tmp.c
265Creating tmp.c.gcov.
266@end smallexample
267
268The file @file{tmp.c.gcov} contains output from @command{gcov}.
269Here is a sample:
270
271@smallexample
272 -: 0:Source:tmp.c
273 -: 0:Graph:tmp.gcno
274 -: 0:Data:tmp.gcda
275 -: 0:Runs:1
276 -: 0:Programs:1
277 -: 1:#include <stdio.h>
278 -: 2:
279 -: 3:int main (void)
280function main called 1 returned 1 blocks executed 75%
281 1: 4:@{
282 1: 5: int i, total;
283 -: 6:
284 1: 7: total = 0;
285 -: 8:
286 11: 9: for (i = 0; i < 10; i++)
287 10: 10: total += i;
288 -: 11:
289 1: 12: if (total != 45)
290 #####: 13: printf ("Failure\n");
291 -: 14: else
292 1: 15: printf ("Success\n");
293 1: 16: return 0;
294 -: 17:@}
295@end smallexample
296
297When you use the @option{-a} option, you will get individual block
298counts, and the output looks like this:
299
300@smallexample
301 -: 0:Source:tmp.c
302 -: 0:Graph:tmp.gcno
303 -: 0:Data:tmp.gcda
304 -: 0:Runs:1
305 -: 0:Programs:1
306 -: 1:#include <stdio.h>
307 -: 2:
308 -: 3:int main (void)
309function main called 1 returned 1 blocks executed 75%
310 1: 4:@{
311 1: 4-block 0
312 1: 5: int i, total;
313 -: 6:
314 1: 7: total = 0;
315 -: 8:
316 11: 9: for (i = 0; i < 10; i++)
317 11: 9-block 0
318 10: 10: total += i;
319 10: 10-block 0
320 -: 11:
321 1: 12: if (total != 45)
322 1: 12-block 0
323 #####: 13: printf ("Failure\n");
324 $$$$$: 13-block 0
325 -: 14: else
326 1: 15: printf ("Success\n");
327 1: 15-block 0
328 1: 16: return 0;
329 1: 16-block 0
330 -: 17:@}
331@end smallexample
332
333In this mode, each basic block is only shown on one line -- the last
334line of the block. A multi-line block will only contribute to the
335execution count of that last line, and other lines will not be shown
336to contain code, unless previous blocks end on those lines.
337The total execution count of a line is shown and subsequent lines show
338the execution counts for individual blocks that end on that line. After each
339block, the branch and call counts of the block will be shown, if the
340@option{-b} option is given.
341
342Because of the way GCC instruments calls, a call count can be shown
343after a line with no individual blocks.
344As you can see, line 13 contains a basic block that was not executed.
345
346@need 450
347When you use the @option{-b} option, your output looks like this:
348
349@smallexample
350$ gcov -b tmp.c
35190.00% of 10 source lines executed in file tmp.c
35280.00% of 5 branches executed in file tmp.c
35380.00% of 5 branches taken at least once in file tmp.c
35450.00% of 2 calls executed in file tmp.c
355Creating tmp.c.gcov.
356@end smallexample
357
358Here is a sample of a resulting @file{tmp.c.gcov} file:
359
360@smallexample
361 -: 0:Source:tmp.c
362 -: 0:Graph:tmp.gcno
363 -: 0:Data:tmp.gcda
364 -: 0:Runs:1
365 -: 0:Programs:1
366 -: 1:#include <stdio.h>
367 -: 2:
368 -: 3:int main (void)
369function main called 1 returned 1 blocks executed 75%
370 1: 4:@{
371 1: 5: int i, total;
372 -: 6:
373 1: 7: total = 0;
374 -: 8:
375 11: 9: for (i = 0; i < 10; i++)
376branch 0 taken 91% (fallthrough)
377branch 1 taken 9%
378 10: 10: total += i;
379 -: 11:
380 1: 12: if (total != 45)
381branch 0 taken 0% (fallthrough)
382branch 1 taken 100%
383 #####: 13: printf ("Failure\n");
384call 0 never executed
385 -: 14: else
386 1: 15: printf ("Success\n");
387call 0 called 1 returned 100%
388 1: 16: return 0;
389 -: 17:@}
390@end smallexample
391
392For each basic block, a line is printed after the last line of the basic
393block describing the branch or call that ends the basic block. There can
394be multiple branches and calls listed for a single source line if there
395are multiple basic blocks that end on that line. In this case, the
396branches and calls are each given a number. There is no simple way to map
397these branches and calls back to source constructs. In general, though,
398the lowest numbered branch or call will correspond to the leftmost construct
399on the source line.
400
401For a branch, if it was executed at least once, then a percentage
402indicating the number of times the branch was taken divided by the
403number of times the branch was executed will be printed. Otherwise, the
404message ``never executed'' is printed.
405
406For a call, if it was executed at least once, then a percentage
407indicating the number of times the call returned divided by the number
408of times the call was executed will be printed. This will usually be
409100%, but may be less for functions call @code{exit} or @code{longjmp},
410and thus may not return every time they are called.
411
412The execution counts are cumulative. If the example program were
413executed again without removing the @file{.gcda} file, the count for the
414number of times each line in the source was executed would be added to
415the results of the previous run(s). This is potentially useful in
416several ways. For example, it could be used to accumulate data over a
417number of program runs as part of a test verification suite, or to
418provide more accurate long-term information over a large number of
419program runs.
420
421The data in the @file{.gcda} files is saved immediately before the program
422exits. For each source file compiled with @option{-fprofile-arcs}, the
423profiling code first attempts to read in an existing @file{.gcda} file; if
424the file doesn't match the executable (differing number of basic block
425counts) it will ignore the contents of the file. It then adds in the
426new execution counts and finally writes the data to the file.
427
428@node Gcov and Optimization
429@section Using @command{gcov} with GCC Optimization
430
431If you plan to use @command{gcov} to help optimize your code, you must
432first compile your program with two special GCC options:
433@samp{-fprofile-arcs -ftest-coverage}. Aside from that, you can use any
434other GCC options; but if you want to prove that every single line
435in your program was executed, you should not compile with optimization
436at the same time. On some machines the optimizer can eliminate some
437simple code lines by combining them with other lines. For example, code
438like this:
439
440@smallexample
441if (a != b)
442 c = 1;
443else
444 c = 0;
445@end smallexample
446
447@noindent
448can be compiled into one instruction on some machines. In this case,
449there is no way for @command{gcov} to calculate separate execution counts
450for each line because there isn't separate code for each line. Hence
451the @command{gcov} output looks like this if you compiled the program with
452optimization:
453
454@smallexample
455 100: 12:if (a != b)
456 100: 13: c = 1;
457 100: 14:else
458 100: 15: c = 0;
459@end smallexample
460
461The output shows that this block of code, combined by optimization,
462executed 100 times. In one sense this result is correct, because there
463was only one instruction representing all four of these lines. However,
464the output does not indicate how many times the result was 0 and how
465many times the result was 1.
466
467Inlineable functions can create unexpected line counts. Line counts are
468shown for the source code of the inlineable function, but what is shown
469depends on where the function is inlined, or if it is not inlined at all.
470
471If the function is not inlined, the compiler must emit an out of line
472copy of the function, in any object file that needs it. If
473@file{fileA.o} and @file{fileB.o} both contain out of line bodies of a
474particular inlineable function, they will also both contain coverage
475counts for that function. When @file{fileA.o} and @file{fileB.o} are
476linked together, the linker will, on many systems, select one of those
477out of line bodies for all calls to that function, and remove or ignore
478the other. Unfortunately, it will not remove the coverage counters for
479the unused function body. Hence when instrumented, all but one use of
480that function will show zero counts.
481
482If the function is inlined in several places, the block structure in
483each location might not be the same. For instance, a condition might
484now be calculable at compile time in some instances. Because the
485coverage of all the uses of the inline function will be shown for the
486same source lines, the line counts themselves might seem inconsistent.
487
488@c man end
489
490@node Gcov Data Files
491@section Brief description of @command{gcov} data files
492
493@command{gcov} uses two files for profiling. The names of these files
494are derived from the original @emph{object} file by substituting the
495file suffix with either @file{.gcno}, or @file{.gcda}. All of these files
496are placed in the same directory as the object file, and contain data
497stored in a platform-independent format.
498
499The @file{.gcno} file is generated when the source file is compiled with
500the GCC @option{-ftest-coverage} option. It contains information to
501reconstruct the basic block graphs and assign source line numbers to
502blocks.
503
504The @file{.gcda} file is generated when a program containing object files
505built with the GCC @option{-fprofile-arcs} option is executed. A
506separate @file{.gcda} file is created for each object file compiled with
507this option. It contains arc transition counts, and some summary
508information.
509
510The full details of the file format is specified in @file{gcov-io.h},
511and functions provided in that header file should be used to access the
512coverage files.