1GCOV(1) GNU GCOV(1)
2
6 gcov - coverage testing tool
7
9 gcov [--vv⎪----vveerrssiioonn] [--hh⎪----hheellpp]
10 [--bb⎪----bbrraanncchh--pprroobbaabbiilliittiieess] [--cc⎪----bbrraanncchh--ccoouunnttss]
11 [--nn⎪----nnoo--oouuttppuutt] [--ll⎪----lloonngg--ffiillee--nnaammeess]
12 [--ff⎪----ffuunnccttiioonn--ssuummmmaarriieess]
13 [--oo⎪----oobbjjeecctt--ddiirreeccttoorryy directory] sourcefile
14
16 ggccoovv is a test coverage program. Use it in concert with GCC to analyze
17 your programs to help create more efficient, faster running code. You
18 can use ggccoovv as a profiling tool to help discover where your optimiza‐
19 tion efforts will best affect your code. You can also use ggccoovv along
20 with the other profiling tool, ggpprrooff, to assess which parts of your
21 code use the greatest amount of computing time.
22 Profiling tools help you analyze your code's performance. Using a pro‐
24 filer such as ggccoovv or ggpprrooff, you can find out some basic performance
25 statistics, such as:
26 · how often each line of code executes
28 · what lines of code are actually executed
30 · how much computing time each section of code uses
32 Once you know these things about how your code works when compiled, you
34 can look at each module to see which modules should be optimized. ggccoovv
35 helps you determine where to work on optimization.
36 Software developers also use coverage testing in concert with test‐
38 suites, to make sure software is actually good enough for a release.
39 Testsuites can verify that a program works as expected; a coverage pro‐
40 gram tests to see how much of the program is exercised by the test‐
41 suite. Developers can then determine what kinds of test cases need to
42 be added to the testsuites to create both better testing and a better
43 final product.
44 You should compile your code without optimization if you plan to use
46 ggccoovv because the optimization, by combining some lines of code into one
47 function, may not give you as much information as you need to look for
48 `hot spots' where the code is using a great deal of computer time.
49 Likewise, because ggccoovv accumulates statistics by line (at the lowest
50 resolution), it works best with a programming style that places only
51 one statement on each line. If you use complicated macros that expand
52 to loops or to other control structures, the statistics are less help‐
53 ful---they only report on the line where the macro call appears. If
54 your complex macros behave like functions, you can replace them with
55 inline functions to solve this problem.
56 ggccoovv creates a logfile called sourcefile.gcov which indicates how many
58 times each line of a source file sourcefile.c has executed. You can
59 use these logfiles along with ggpprrooff to aid in fine-tuning the perfor‐
60 mance of your programs. ggpprrooff gives timing information you can use
61 along with the information you get from ggccoovv.
62 ggccoovv works only on code compiled with GCC. It is not compatible with
64 any other profiling or test coverage mechanism.
65
67 --hh
68 ----hheellpp
69 Display help about using ggccoovv (on the standard output), and exit
70 without doing any further processing.
71 --vv
73 ----vveerrssiioonn
74 Display the ggccoovv version number (on the standard output), and exit
75 without doing any further processing.
76 --bb
78 ----bbrraanncchh--pprroobbaabbiilliittiieess
79 Write branch frequencies to the output file, and write branch sum‐
80 mary info to the standard output. This option allows you to see
81 how often each branch in your program was taken.
82 --cc
84 ----bbrraanncchh--ccoouunnttss
85 Write branch frequencies as the number of branches taken, rather
86 than the percentage of branches taken.
87 --nn
89 ----nnoo--oouuttppuutt
90 Do not create the ggccoovv output file.
91 --ll
93 ----lloonngg--ffiillee--nnaammeess
94 Create long file names for included source files. For example, if
95 the header file x.h contains code, and was included in the file
96 a.c, then running ggccoovv on the file a.c will produce an output file
97 called a.c.x.h.gcov instead of x.h.gcov. This can be useful if x.h
98 is included in multiple source files.
99 --ff
101 ----ffuunnccttiioonn--ssuummmmaarriieess
102 Output summaries for each function in addition to the file level
103 summary.
104 --oo directory
106 ----oobbjjeecctt--ddiirreeccttoorryy directory
107 The directory where the object files live. Gcov will search for
108 .bb, .bbg, and .da files in this directory.
109 When using ggccoovv, you must first compile your program with two special
111 GCC options: --ffpprrooffiillee--aarrccss --fftteesstt--ccoovveerraaggee. This tells the compiler
112 to generate additional information needed by gcov (basically a flow
113 graph of the program) and also includes additional code in the object
114 files for generating the extra profiling information needed by gcov.
115 These additional files are placed in the directory where the source
116 code is located.
117 Running the program will cause profile output to be generated. For
119 each source file compiled with --ffpprrooffiillee--aarrccss, an accompanying .da file
120 will be placed in the source directory.
121 Running ggccoovv with your program's source file names as arguments will
123 now produce a listing of the code along with frequency of execution for
124 each line. For example, if your program is called tmp.c, this is what
125 you see when you use the basic ggccoovv facility:
126 $ gcc -fprofile-arcs -ftest-coverage tmp.c
128 $ a.out
129 $ gcov tmp.c
130 87.50% of 8 source lines executed in file tmp.c
131 Creating tmp.c.gcov.
132 The file tmp.c.gcov contains output from ggccoovv. Here is a sample:
134 main()
136 {
137 1 int i, total;
138 1 total = 0;
140 11 for (i = 0; i < 10; i++)
142 10 total += i;
143 1 if (total != 45)
145 ###### printf ("Failure\n");
146 else
147 1 printf ("Success\n");
148 1 }
149 When you use the --bb option, your output looks like this:
151 $ gcov -b tmp.c
153 87.50% of 8 source lines executed in file tmp.c
154 80.00% of 5 branches executed in file tmp.c
155 80.00% of 5 branches taken at least once in file tmp.c
156 50.00% of 2 calls executed in file tmp.c
157 Creating tmp.c.gcov.
158 Here is a sample of a resulting tmp.c.gcov file:
160 main()
162 {
163 1 int i, total;
164 1 total = 0;
166 11 for (i = 0; i < 10; i++)
168 branch 0 taken = 91%
169 branch 1 taken = 100%
170 branch 2 taken = 100%
171 10 total += i;
172 1 if (total != 45)
174 branch 0 taken = 100%
175 ###### printf ("Failure\n");
176 call 0 never executed
177 branch 1 never executed
178 else
179 1 printf ("Success\n");
180 call 0 returns = 100%
181 1 }
182 For each basic block, a line is printed after the last line of the
184 basic block describing the branch or call that ends the basic block.
185 There can be multiple branches and calls listed for a single source
186 line if there are multiple basic blocks that end on that line. In this
187 case, the branches and calls are each given a number. There is no sim‐
188 ple way to map these branches and calls back to source constructs. In
189 general, though, the lowest numbered branch or call will correspond to
190 the leftmost construct on the source line.
191 For a branch, if it was executed at least once, then a percentage indi‐
193 cating the number of times the branch was taken divided by the number
194 of times the branch was executed will be printed. Otherwise, the mes‐
195 sage ``never executed'' is printed.
196 For a call, if it was executed at least once, then a percentage indi‐
198 cating the number of times the call returned divided by the number of
199 times the call was executed will be printed. This will usually be
200 100%, but may be less for functions call "exit" or "longjmp", and thus
201 may not return every time they are called.
202 The execution counts are cumulative. If the example program were exe‐
204 cuted again without removing the .da file, the count for the number of
205 times each line in the source was executed would be added to the
206 results of the previous run(s). This is potentially useful in several
207 ways. For example, it could be used to accumulate data over a number
208 of program runs as part of a test verification suite, or to provide
209 more accurate long-term information over a large number of program
210 runs.
211 The data in the .da files is saved immediately before the program
213 exits. For each source file compiled with --ffpprrooffiillee--aarrccss, the profil‐
214 ing code first attempts to read in an existing .da file; if the file
215 doesn't match the executable (differing number of basic block counts)
216 it will ignore the contents of the file. It then adds in the new exe‐
217 cution counts and finally writes the data to the file.
218 UUssiinngg ggccoovv wwiitthh GGCCCC OOppttiimmiizzaattiioonn
220 If you plan to use ggccoovv to help optimize your code, you must first com‐
222 pile your program with two special GCC options: --ffpprrooffiillee--aarrccss --fftteesstt--
223 ccoovveerraaggee. Aside from that, you can use any other GCC options; but if
224 you want to prove that every single line in your program was executed,
225 you should not compile with optimization at the same time. On some
226 machines the optimizer can eliminate some simple code lines by combin‐
227 ing them with other lines. For example, code like this:
228 if (a != b)
230 c = 1;
231 else
232 c = 0;
233 can be compiled into one instruction on some machines. In this case,
235 there is no way for ggccoovv to calculate separate execution counts for
236 each line because there isn't separate code for each line. Hence the
237 ggccoovv output looks like this if you compiled the program with optimiza‐
238 tion:
239 100 if (a != b)
241 100 c = 1;
242 100 else
243 100 c = 0;
244 The output shows that this block of code, combined by optimization,
246 executed 100 times. In one sense this result is correct, because there
247 was only one instruction representing all four of these lines. How‐
248 ever, the output does not indicate how many times the result was 0 and
249 how many times the result was 1.
250
252 gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for gcc.
253
255 Copyright (c) 1996, 1997, 1999, 2000, 2001 Free Software Foundation,
256 Inc.
257 Permission is granted to copy, distribute and/or modify this document
259 under the terms of the GNU Free Documentation License, Version 1.1 or
260 any later version published by the Free Software Foundation; with the
261 Invariant Sections being ``GNU General Public License'' and ``Funding
262 Free Software'', the Front-Cover texts being (a) (see below), and with
263 the Back-Cover Texts being (b) (see below). A copy of the license is
264 included in the gfdl(7) man page.
265 (a) The FSF's Front-Cover Text is:
267 A GNU Manual
269 (b) The FSF's Back-Cover Text is:
271 You have freedom to copy and modify this GNU Manual, like GNU
273 software. Copies published by the Free Software Foundation raise
274 funds for GNU development.
2753rd Berkeley Distribution gcc-3.2.3 GCOV(1)