1GCOV(1)                               GNU                              GCOV(1)
2
3
4

NAME

6       gcov - coverage testing tool
7

SYNOPSIS

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

DESCRIPTION

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
29       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
33       ·   how often each line of code executes
34
35       ·   what lines of code are actually executed
36
37       ·   how much computing time each section of code uses
38
39       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
43       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
51       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
63       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
69       gcov works only on code compiled with GCC.  It is not compatible with
70       any other profiling or test coverage mechanism.
71

OPTIONS

73       -h
74       --help
75           Display help about using gcov (on the standard output), and exit
76           without doing any further processing.
77
78       -v
79       --version
80           Display the gcov version number (on the standard output), and exit
81           without doing any further processing.
82
83       -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
90       -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
97       -c
98       --branch-counts
99           Write branch frequencies as the number of branches taken, rather
100           than the percentage of branches taken.
101
102       -n
103       --no-output
104           Do not create the gcov output file.
105
106       -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
116       -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
125       -f
126       --function-summaries
127           Output summaries for each function in addition to the file level
128           summary.
129
130       -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
141       -u
142       --unconditional-branches
143           When branch probabilities are given, include those of unconditional
144           branches.  Unconditional branches are normally not interesting.
145
146       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
156       The .gcov files contain the : separated fields along with program
157       source code.  The format is
158
159               <execution_count>:<line_number>:<source line text>
160
161       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
166       The preamble lines are of the form
167
168               -:0:<tag>:<value>
169
170       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
174       The additional block information is of the form
175
176               <tag> <information>
177
178       The information is human readable, but designed to be simple enough for
179       machine parsing too.
180
181       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
186       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
194       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
198       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
203               $ 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
209       The file tmp.c.gcov contains output from gcov.  Here is a sample:
210
211                       -:    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
234       When you use the -a option, you will get individual block counts, and
235       the output looks like this:
236
237                       -:    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
267       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
276       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
280       When you use the -b option, your output looks like this:
281
282               $ 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
289       Here is a sample of a resulting tmp.c.gcov file:
290
291                       -:    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
321       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
325       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
334       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
339       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
345       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
354       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
361       Using gcov with GCC Optimization
362
363       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
371               if (a != b)
372                 c = 1;
373               else
374                 c = 0;
375
376       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
382                     100:   12:if (a != b)
383                     100:   13:  c = 1;
384                     100:   14:else
385                     100:   15:  c = 0;
386
387       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
393       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
398       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
409       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

SEE ALSO

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
422       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
430       (a) The FSF's Front-Cover Text is:
431
432            A GNU Manual
433
434       (b) The FSF's Back-Cover Text is:
435
436            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.
439
440
441
442gcc-4.1.2                         2007-09-25                           GCOV(1)
Impressum