1GCOV(1) GNU GCOV(1)
2
6 gcov - coverage testing tool
7
9 gcov [-v⎪--version] [-h⎪--help]
10 [-a⎪--all-blocks]
11 [-b⎪--branch-probabilities]
12 [-c⎪--branch-counts]
13 [-n⎪--no-output]
14 [-l⎪--long-file-names]
15 [-p⎪--preserve-paths]
16 [-f⎪--function-summaries]
17 [-o⎪--object-directory directory⎪file] sourcefile
18 [-u⎪--unconditional-branches]
19
21 gcov is a test coverage program. Use it in concert with GCC to analyze
22 your programs to help create more efficient, faster running code and to
23 discover untested parts of your program. You can use gcov as a profil‐
24 ing tool to help discover where your optimization efforts will best
25 affect your code. You can also use gcov along with the other profiling
26 tool, gprof, to assess which parts of your code use the greatest amount
27 of computing time.
28 Profiling tools help you analyze your code's performance. Using a pro‐
30 filer such as gcov or gprof, you can find out some basic performance
31 statistics, such as:
32 · how often each line of code executes
34 · what lines of code are actually executed
36 · how much computing time each section of code uses
38 Once you know these things about how your code works when compiled, you
40 can look at each module to see which modules should be optimized. gcov
41 helps you determine where to work on optimization.
42 Software developers also use coverage testing in concert with test‐
44 suites, to make sure software is actually good enough for a release.
45 Testsuites can verify that a program works as expected; a coverage pro‐
46 gram tests to see how much of the program is exercised by the test‐
47 suite. Developers can then determine what kinds of test cases need to
48 be added to the testsuites to create both better testing and a better
49 final product.
50 You should compile your code without optimization if you plan to use
52 gcov because the optimization, by combining some lines of code into one
53 function, may not give you as much information as you need to look for
54 `hot spots' where the code is using a great deal of computer time.
55 Likewise, because gcov accumulates statistics by line (at the lowest
56 resolution), it works best with a programming style that places only
57 one statement on each line. If you use complicated macros that expand
58 to loops or to other control structures, the statistics are less help‐
59 ful---they only report on the line where the macro call appears. If
60 your complex macros behave like functions, you can replace them with
61 inline functions to solve this problem.
62 gcov creates a logfile called sourcefile.gcov which indicates how many
64 times each line of a source file sourcefile.c has executed. You can
65 use these logfiles along with gprof to aid in fine-tuning the perfor‐
66 mance of your programs. gprof gives timing information you can use
67 along with the information you get from gcov.
68 gcov works only on code compiled with GCC. It is not compatible with
70 any other profiling or test coverage mechanism.
71
73 -h
74 --help
75 Display help about using gcov (on the standard output), and exit
76 without doing any further processing.
77 -v
79 --version
80 Display the gcov version number (on the standard output), and exit
81 without doing any further processing.
82 -a
84 --all-blocks
85 Write individual execution counts for every basic block. Normally
86 gcov outputs execution counts only for the main blocks of a line.
87 With this option you can determine if blocks within a single line
88 are not being executed.
89 -b
91 --branch-probabilities
92 Write branch frequencies to the output file, and write branch sum‐
93 mary info to the standard output. This option allows you to see
94 how often each branch in your program was taken. Unconditional
95 branches will not be shown, unless the -u option is given.
96 -c
98 --branch-counts
99 Write branch frequencies as the number of branches taken, rather
100 than the percentage of branches taken.
101 -n
103 --no-output
104 Do not create the gcov output file.
105 -l
107 --long-file-names
108 Create long file names for included source files. For example, if
109 the header file x.h contains code, and was included in the file
110 a.c, then running gcov on the file a.c will produce an output file
111 called a.c##x.h.gcov instead of x.h.gcov. This can be useful if
112 x.h is included in multiple source files. If you use the -p
113 option, both the including and included file names will be complete
114 path names.
115 -p
117 --preserve-paths
118 Preserve complete path information in the names of generated .gcov
119 files. Without this option, just the filename component is used.
120 With this option, all directories are used, with / characters
121 translated to # characters, . directory components removed and ..
122 components renamed to ^. This is useful if sourcefiles are in sev‐
123 eral different directories. It also affects the -l option.
124 -f
126 --function-summaries
127 Output summaries for each function in addition to the file level
128 summary.
129 -o directory⎪file
131 --object-directory directory
132 --object-file file
133 Specify either the directory containing the gcov data files, or the
134 object path name. The .gcno, and .gcda data files are searched for
135 using this option. If a directory is specified, the data files are
136 in that directory and named after the source file name, without its
137 extension. If a file is specified here, the data files are named
138 after that file, without its extension. If this option is not sup‐
139 plied, it defaults to the current directory.
140 -u
142 --unconditional-branches
143 When branch probabilities are given, include those of unconditional
144 branches. Unconditional branches are normally not interesting.
145 gcov should be run with the current directory the same as that when you
147 invoked the compiler. Otherwise it will not be able to locate the
148 source files. gcov produces files called mangledname.gcov in the cur‐
149 rent directory. These contain the coverage information of the source
150 file they correspond to. One .gcov file is produced for each source
151 file containing code, which was compiled to produce the data files.
152 The mangledname part of the output file name is usually simply the
153 source file name, but can be something more complicated if the -l or -p
154 options are given. Refer to those options for details.
155 The .gcov files contain the : separated fields along with program
157 source code. The format is
158 <execution_count>:<line_number>:<source line text>
160 Additional block information may succeed each line, when requested by
162 command line option. The execution_count is - for lines containing no
163 code and ##### for lines which were never executed. Some lines of
164 information at the start have line_number of zero.
165 The preamble lines are of the form
167 -:0:<tag>:<value>
169 The ordering and number of these preamble lines will be augmented as
171 gcov development progresses --- do not rely on them remaining
172 unchanged. Use tag to locate a particular preamble line.
173 The additional block information is of the form
175 <tag> <information>
177 The information is human readable, but designed to be simple enough for
179 machine parsing too.
180 When printing percentages, 0% and 100% are only printed when the values
182 are exactly 0% and 100% respectively. Other values which would conven‐
183 tionally be rounded to 0% or 100% are instead printed as the nearest
184 non-boundary value.
185 When using gcov, you must first compile your program with two special
187 GCC options: -fprofile-arcs -ftest-coverage. This tells the compiler
188 to generate additional information needed by gcov (basically a flow
189 graph of the program) and also includes additional code in the object
190 files for generating the extra profiling information needed by gcov.
191 These additional files are placed in the directory where the object
192 file is located.
193 Running the program will cause profile output to be generated. For
195 each source file compiled with -fprofile-arcs, an accompanying .gcda
196 file will be placed in the object file directory.
197 Running gcov with your program's source file names as arguments will
199 now produce a listing of the code along with frequency of execution for
200 each line. For example, if your program is called tmp.c, this is what
201 you see when you use the basic gcov facility:
202 $ gcc -fprofile-arcs -ftest-coverage tmp.c
204 $ a.out
205 $ gcov tmp.c
206 90.00% of 10 source lines executed in file tmp.c
207 Creating tmp.c.gcov.
208 The file tmp.c.gcov contains output from gcov. Here is a sample:
210 -: 0:Source:tmp.c
212 -: 0:Graph:tmp.gcno
213 -: 0:Data:tmp.gcda
214 -: 0:Runs:1
215 -: 0:Programs:1
216 -: 1:#include <stdio.h>
217 -: 2:
218 -: 3:int main (void)
219 1: 4:{
220 1: 5: int i, total;
221 -: 6:
222 1: 7: total = 0;
223 -: 8:
224 11: 9: for (i = 0; i < 10; i++)
225 10: 10: total += i;
226 -: 11:
227 1: 12: if (total != 45)
228 #####: 13: printf ("Failure\n");
229 -: 14: else
230 1: 15: printf ("Success\n");
231 1: 16: return 0;
232 -: 17:}
233 When you use the -a option, you will get individual block counts, and
235 the output looks like this:
236 -: 0:Source:tmp.c
238 -: 0:Graph:tmp.gcno
239 -: 0:Data:tmp.gcda
240 -: 0:Runs:1
241 -: 0:Programs:1
242 -: 1:#include <stdio.h>
243 -: 2:
244 -: 3:int main (void)
245 1: 4:{
246 1: 4-block 0
247 1: 5: int i, total;
248 -: 6:
249 1: 7: total = 0;
250 -: 8:
251 11: 9: for (i = 0; i < 10; i++)
252 11: 9-block 0
253 10: 10: total += i;
254 10: 10-block 0
255 -: 11:
256 1: 12: if (total != 45)
257 1: 12-block 0
258 #####: 13: printf ("Failure\n");
259 $$$$$: 13-block 0
260 -: 14: else
261 1: 15: printf ("Success\n");
262 1: 15-block 0
263 1: 16: return 0;
264 1: 16-block 0
265 -: 17:}
266 In this mode, each basic block is only shown on one line -- the last
268 line of the block. A multi-line block will only contribute to the exe‐
269 cution count of that last line, and other lines will not be shown to
270 contain code, unless previous blocks end on those lines. The total
271 execution count of a line is shown and subsequent lines show the execu‐
272 tion counts for individual blocks that end on that line. After each
273 block, the branch and call counts of the block will be shown, if the -b
274 option is given.
275 Because of the way GCC instruments calls, a call count can be shown
277 after a line with no individual blocks. As you can see, line 13 con‐
278 tains a basic block that was not executed.
279 When you use the -b option, your output looks like this:
281 $ gcov -b tmp.c
283 90.00% of 10 source lines executed in file tmp.c
284 80.00% of 5 branches executed in file tmp.c
285 80.00% of 5 branches taken at least once in file tmp.c
286 50.00% of 2 calls executed in file tmp.c
287 Creating tmp.c.gcov.
288 Here is a sample of a resulting tmp.c.gcov file:
290 -: 0:Source:tmp.c
292 -: 0:Graph:tmp.gcno
293 -: 0:Data:tmp.gcda
294 -: 0:Runs:1
295 -: 0:Programs:1
296 -: 1:#include <stdio.h>
297 -: 2:
298 -: 3:int main (void)
299 function main called 1 returned 1 blocks executed 75%
300 1: 4:{
301 1: 5: int i, total;
302 -: 6:
303 1: 7: total = 0;
304 -: 8:
305 11: 9: for (i = 0; i < 10; i++)
306 branch 0 taken 91% (fallthrough)
307 branch 1 taken 9%
308 10: 10: total += i;
309 -: 11:
310 1: 12: if (total != 45)
311 branch 0 taken 0% (fallthrough)
312 branch 1 taken 100%
313 #####: 13: printf ("Failure\n");
314 call 0 never executed
315 -: 14: else
316 1: 15: printf ("Success\n");
317 call 0 called 1 returned 100%
318 1: 16: return 0;
319 -: 17:}
320 For each function, a line is printed showing how many times the func‐
322 tion is called, how many times it returns and what percentage of the
323 function's blocks were executed.
324 For each basic block, a line is printed after the last line of the
326 basic block describing the branch or call that ends the basic block.
327 There can be multiple branches and calls listed for a single source
328 line if there are multiple basic blocks that end on that line. In this
329 case, the branches and calls are each given a number. There is no sim‐
330 ple way to map these branches and calls back to source constructs. In
331 general, though, the lowest numbered branch or call will correspond to
332 the leftmost construct on the source line.
333 For a branch, if it was executed at least once, then a percentage indi‐
335 cating the number of times the branch was taken divided by the number
336 of times the branch was executed will be printed. Otherwise, the mes‐
337 sage "never executed" is printed.
338 For a call, if it was executed at least once, then a percentage indi‐
340 cating the number of times the call returned divided by the number of
341 times the call was executed will be printed. This will usually be
342 100%, but may be less for functions that call "exit" or "longjmp", and
343 thus may not return every time they are called.
344 The execution counts are cumulative. If the example program were exe‐
346 cuted again without removing the .gcda file, the count for the number
347 of times each line in the source was executed would be added to the
348 results of the previous run(s). This is potentially useful in several
349 ways. For example, it could be used to accumulate data over a number
350 of program runs as part of a test verification suite, or to provide
351 more accurate long-term information over a large number of program
352 runs.
353 The data in the .gcda files is saved immediately before the program
355 exits. For each source file compiled with -fprofile-arcs, the profil‐
356 ing code first attempts to read in an existing .gcda file; if the file
357 doesn't match the executable (differing number of basic block counts)
358 it will ignore the contents of the file. It then adds in the new exe‐
359 cution counts and finally writes the data to the file.
360 Using gcov with GCC Optimization
362 If you plan to use gcov to help optimize your code, you must first com‐
364 pile your program with two special GCC options: -fprofile-arcs
365 -ftest-coverage. Aside from that, you can use any other GCC options;
366 but if you want to prove that every single line in your program was
367 executed, you should not compile with optimization at the same time.
368 On some machines the optimizer can eliminate some simple code lines by
369 combining them with other lines. For example, code like this:
370 if (a != b)
372 c = 1;
373 else
374 c = 0;
375 can be compiled into one instruction on some machines. In this case,
377 there is no way for gcov to calculate separate execution counts for
378 each line because there isn't separate code for each line. Hence the
379 gcov output looks like this if you compiled the program with optimiza‐
380 tion:
381 100: 12:if (a != b)
383 100: 13: c = 1;
384 100: 14:else
385 100: 15: c = 0;
386 The output shows that this block of code, combined by optimization,
388 executed 100 times. In one sense this result is correct, because there
389 was only one instruction representing all four of these lines. How‐
390 ever, the output does not indicate how many times the result was 0 and
391 how many times the result was 1.
392 Inlineable functions can create unexpected line counts. Line counts
394 are shown for the source code of the inlineable function, but what is
395 shown depends on where the function is inlined, or if it is not inlined
396 at all.
397 If the function is not inlined, the compiler must emit an out of line
399 copy of the function, in any object file that needs it. If fileA.o and
400 fileB.o both contain out of line bodies of a particular inlineable
401 function, they will also both contain coverage counts for that func‐
402 tion. When fileA.o and fileB.o are linked together, the linker will,
403 on many systems, select one of those out of line bodies for all calls
404 to that function, and remove or ignore the other. Unfortunately, it
405 will not remove the coverage counters for the unused function body.
406 Hence when instrumented, all but one use of that function will show
407 zero counts.
408 If the function is inlined in several places, the block structure in
410 each location might not be the same. For instance, a condition might
411 now be calculable at compile time in some instances. Because the cov‐
412 erage of all the uses of the inline function will be shown for the same
413 source lines, the line counts themselves might seem inconsistent.
414
416 gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for gcc.
417
419 Copyright (c) 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004, 2005 Free
420 Software Foundation, Inc.
421 Permission is granted to copy, distribute and/or modify this document
423 under the terms of the GNU Free Documentation License, Version 1.2 or
424 any later version published by the Free Software Foundation; with the
425 Invariant Sections being "GNU General Public License" and "Funding Free
426 Software", the Front-Cover texts being (a) (see below), and with the
427 Back-Cover Texts being (b) (see below). A copy of the license is
428 included in the gfdl(7) man page.
429 (a) The FSF's Front-Cover Text is:
431 A GNU Manual
433 (b) The FSF's Back-Cover Text is:
435 You have freedom to copy and modify this GNU Manual, like GNU
437 software. Copies published by the Free Software Foundation raise
438 funds for GNU development.
439gcc-4.1.2 2007-02-14 GCOV(1)