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] sourcefiles
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
24       profiling tool to help discover where your optimization efforts will
25       best affect your code.  You can also use gcov along with the other
26       profiling tool, gprof, to assess which parts of your code use the
27       greatest amount of computing time.
28
29       Profiling tools help you analyze your code's performance.  Using a
30       profiler 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
44       testsuites, to make sure software is actually good enough for a
45       release.  Testsuites can verify that a program works as expected; a
46       coverage program tests to see how much of the program is exercised by
47       the testsuite.  Developers can then determine what kinds of test cases
48       need to be added to the testsuites to create both better testing and a
49       better 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
59       helpful---they only report on the line where the macro call appears.
60       If 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
66       performance of your programs.  gprof gives timing information you can
67       use 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
93           summary 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
123           several 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
139           supplied, 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
149       current directory.  These contain the coverage information of the
150       source file they correspond to.  One .gcov file is produced for each
151       source file containing code, which was compiled to produce the data
152       files.  The mangledname part of the output file name is usually simply
153       the source file name, but can be something more complicated if the -l
154       or -p 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
183       conventionally be rounded to 0% or 100% are instead printed as the
184       nearest 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
269       execution 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
272       execution counts for individual blocks that end on that line.  After
273       each block, the branch and call counts of the block will be shown, if
274       the -b 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
278       contains 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
322       function is called, how many times it returns and what percentage of
323       the 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
330       simple way to map these branches and calls back to source constructs.
331       In general, though, the lowest numbered branch or call will correspond
332       to the leftmost construct on the source line.
333
334       For a branch, if it was executed at least once, then a percentage
335       indicating the number of times the branch was taken divided by the
336       number of times the branch was executed will be printed.  Otherwise,
337       the message "never executed" is printed.
338
339       For a call, if it was executed at least once, then a percentage
340       indicating the number of times the call returned divided by the number
341       of 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
346       executed again without removing the .gcda file, the count for the
347       number of times each line in the source was executed would be added to
348       the results of the previous run(s).  This is potentially useful in
349       several ways.  For example, it could be used to accumulate data over a
350       number of program runs as part of a test verification suite, or to
351       provide more accurate long-term information over a large number of
352       program 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
356       profiling code first attempts to read in an existing .gcda file; if the
357       file doesn't match the executable (differing number of basic block
358       counts) it will ignore the contents of the file.  It then adds in the
359       new execution 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
364       compile 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
380       optimization:
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.
390       However, the output does not indicate how many times the result was 0
391       and 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
402       function.  When fileA.o and fileB.o are linked together, the linker
403       will, on many systems, select one of those out of line bodies for all
404       calls to that function, and remove or ignore the other.  Unfortunately,
405       it 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
412       coverage of all the uses of the inline function will be shown for the
413       same 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,
420       2008  Free 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.5.0                         2010-04-14                           GCOV(1)
Impressum