]>
Commit | Line | Data |
---|---|---|
cbe34bb5 | 1 | @c Copyright (C) 1996-2017 Free Software Foundation, Inc. |
2be7973e DE |
2 | @c This is part of the GCC manual. |
3 | @c For copying conditions, see the file gcc.texi. | |
4 | ||
c01a508e JM |
5 | @ignore |
6 | @c man begin COPYRIGHT | |
c1a9c369 | 7 | Copyright @copyright{} 1996-2017 Free Software Foundation, Inc. |
c01a508e | 8 | |
77bd67cb | 9 | Permission is granted to copy, distribute and/or modify this document |
07a67d6a | 10 | under the terms of the GNU Free Documentation License, Version 1.3 or |
77bd67cb JM |
11 | any later version published by the Free Software Foundation; with the |
12 | Invariant Sections being ``GNU General Public License'' and ``Funding | |
13 | Free Software'', the Front-Cover texts being (a) (see below), and with | |
14 | the Back-Cover Texts being (b) (see below). A copy of the license is | |
15 | included in the gfdl(7) man page. | |
16 | ||
17 | (a) The FSF's Front-Cover Text is: | |
18 | ||
19 | A GNU Manual | |
20 | ||
21 | (b) The FSF's Back-Cover Text is: | |
22 | ||
23 | You have freedom to copy and modify this GNU Manual, like GNU | |
24 | software. Copies published by the Free Software Foundation raise | |
25 | funds for GNU development. | |
c01a508e JM |
26 | @c man end |
27 | @c Set file name and title for the man page. | |
28 | @setfilename gcov | |
29 | @settitle coverage testing tool | |
30 | @end ignore | |
31 | ||
2be7973e | 32 | @node Gcov |
2d1d9215 | 33 | @chapter @command{gcov}---a Test Coverage Program |
2be7973e | 34 | |
f0523f02 | 35 | @command{gcov} is a tool you can use in conjunction with GCC to |
2be7973e DE |
36 | test code coverage in your programs. |
37 | ||
2be7973e | 38 | @menu |
6ccde948 RW |
39 | * Gcov Intro:: Introduction to gcov. |
40 | * Invoking Gcov:: How to use gcov. | |
2be7973e DE |
41 | * Gcov and Optimization:: Using gcov with GCC optimization. |
42 | * Gcov Data Files:: The files used by gcov. | |
992f396f | 43 | * Cross-profiling:: Data file relocation. |
2be7973e DE |
44 | @end menu |
45 | ||
46 | @node Gcov Intro | |
c50174e7 | 47 | @section Introduction to @command{gcov} |
c01a508e | 48 | @c man begin DESCRIPTION |
2be7973e | 49 | |
f0523f02 | 50 | @command{gcov} is a test coverage program. Use it in concert with GCC |
37b8715b NS |
51 | to analyze your programs to help create more efficient, faster running |
52 | code and to discover untested parts of your program. You can use | |
53 | @command{gcov} as a profiling tool to help discover where your | |
54 | optimization efforts will best affect your code. You can also use | |
55 | @command{gcov} along with the other profiling tool, @command{gprof}, to | |
56 | assess which parts of your code use the greatest amount of computing | |
57 | time. | |
2be7973e DE |
58 | |
59 | Profiling tools help you analyze your code's performance. Using a | |
c50174e7 | 60 | profiler such as @command{gcov} or @command{gprof}, you can find out some |
2be7973e DE |
61 | basic performance statistics, such as: |
62 | ||
63 | @itemize @bullet | |
64 | @item | |
65 | how often each line of code executes | |
66 | ||
67 | @item | |
68 | what lines of code are actually executed | |
69 | ||
70 | @item | |
71 | how much computing time each section of code uses | |
72 | @end itemize | |
73 | ||
74 | Once you know these things about how your code works when compiled, you | |
75 | can look at each module to see which modules should be optimized. | |
c50174e7 | 76 | @command{gcov} helps you determine where to work on optimization. |
2be7973e DE |
77 | |
78 | Software developers also use coverage testing in concert with | |
79 | testsuites, to make sure software is actually good enough for a release. | |
80 | Testsuites can verify that a program works as expected; a coverage | |
81 | program tests to see how much of the program is exercised by the | |
82 | testsuite. Developers can then determine what kinds of test cases need | |
83 | to be added to the testsuites to create both better testing and a better | |
84 | final product. | |
85 | ||
86 | You should compile your code without optimization if you plan to use | |
c50174e7 | 87 | @command{gcov} because the optimization, by combining some lines of code |
2be7973e DE |
88 | into one function, may not give you as much information as you need to |
89 | look for `hot spots' where the code is using a great deal of computer | |
c50174e7 | 90 | time. Likewise, because @command{gcov} accumulates statistics by line (at |
2be7973e DE |
91 | the lowest resolution), it works best with a programming style that |
92 | places only one statement on each line. If you use complicated macros | |
93 | that expand to loops or to other control structures, the statistics are | |
94 | less helpful---they only report on the line where the macro call | |
95 | appears. If your complex macros behave like functions, you can replace | |
96 | them with inline functions to solve this problem. | |
97 | ||
c50174e7 | 98 | @command{gcov} creates a logfile called @file{@var{sourcefile}.gcov} which |
2be7973e | 99 | indicates how many times each line of a source file @file{@var{sourcefile}.c} |
c50174e7 JM |
100 | has executed. You can use these logfiles along with @command{gprof} to aid |
101 | in fine-tuning the performance of your programs. @command{gprof} gives | |
2be7973e | 102 | timing information you can use along with the information you get from |
c50174e7 | 103 | @command{gcov}. |
2be7973e | 104 | |
161d7b59 | 105 | @command{gcov} works only on code compiled with GCC@. It is not |
2be7973e DE |
106 | compatible with any other profiling or test coverage mechanism. |
107 | ||
c01a508e JM |
108 | @c man end |
109 | ||
2be7973e | 110 | @node Invoking Gcov |
4afc7adf | 111 | @section Invoking @command{gcov} |
2be7973e DE |
112 | |
113 | @smallexample | |
eeabee0a | 114 | gcov @r{[}@var{options}@r{]} @var{files} |
2be7973e DE |
115 | @end smallexample |
116 | ||
5735c3ea JM |
117 | @command{gcov} accepts the following options: |
118 | ||
c01a508e JM |
119 | @ignore |
120 | @c man begin SYNOPSIS | |
5735c3ea | 121 | gcov [@option{-v}|@option{--version}] [@option{-h}|@option{--help}] |
27283c73 | 122 | [@option{-a}|@option{--all-blocks}] |
37b8715b NS |
123 | [@option{-b}|@option{--branch-probabilities}] |
124 | [@option{-c}|@option{--branch-counts}] | |
fc8a650e SS |
125 | [@option{-d}|@option{--display-progress}] |
126 | [@option{-f}|@option{--function-summaries}] | |
127 | [@option{-i}|@option{--intermediate-format}] | |
28f4a4a8 | 128 | [@option{-k}|@option{--use-colors}] |
37b8715b | 129 | [@option{-l}|@option{--long-file-names}] |
fc8a650e SS |
130 | [@option{-m}|@option{--demangled-names}] |
131 | [@option{-n}|@option{--no-output}] | |
132 | [@option{-o}|@option{--object-directory} @var{directory|file}] | |
37b8715b | 133 | [@option{-p}|@option{--preserve-paths}] |
1bec9caa | 134 | [@option{-r}|@option{--relative-only}] |
1bec9caa | 135 | [@option{-s}|@option{--source-prefix} @var{directory}] |
fc8a650e | 136 | [@option{-u}|@option{--unconditional-branches}] |
75cc66f2 | 137 | [@option{-x}|@option{--hash-filenames}] |
1bec9caa | 138 | @var{files} |
c01a508e JM |
139 | @c man end |
140 | @c man begin SEEALSO | |
77bd67cb | 141 | gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}. |
c01a508e JM |
142 | @c man end |
143 | @end ignore | |
144 | ||
145 | @c man begin OPTIONS | |
c50174e7 | 146 | @table @gcctabopt |
5735c3ea | 147 | |
27283c73 NS |
148 | @item -a |
149 | @itemx --all-blocks | |
8a36672b JM |
150 | Write individual execution counts for every basic block. Normally gcov |
151 | outputs execution counts only for the main blocks of a line. With this | |
27283c73 | 152 | option you can determine if blocks within a single line are not being |
10b7602f | 153 | executed. |
27283c73 | 154 | |
c01a508e | 155 | @item -b |
5735c3ea | 156 | @itemx --branch-probabilities |
2be7973e DE |
157 | Write branch frequencies to the output file, and write branch summary |
158 | info to the standard output. This option allows you to see how often | |
8a36672b | 159 | each branch in your program was taken. Unconditional branches will not |
27283c73 | 160 | be shown, unless the @option{-u} option is given. |
2be7973e | 161 | |
8bfa6fc5 | 162 | @item -c |
5735c3ea | 163 | @itemx --branch-counts |
ebb48a4d | 164 | Write branch frequencies as the number of branches taken, rather than |
8bfa6fc5 CP |
165 | the percentage of branches taken. |
166 | ||
2f360676 ML |
167 | @item -d |
168 | @itemx --display-progress | |
169 | Display the progress on the standard output. | |
1bec9caa | 170 | |
2be7973e | 171 | @item -f |
5735c3ea | 172 | @itemx --function-summaries |
2be7973e DE |
173 | Output summaries for each function in addition to the file level summary. |
174 | ||
2f360676 ML |
175 | @item -h |
176 | @itemx --help | |
177 | Display help about using @command{gcov} (on the standard output), and | |
178 | exit without doing any further processing. | |
acdb4da7 | 179 | |
fc8a650e SS |
180 | @item -i |
181 | @itemx --intermediate-format | |
182 | Output gcov file in an easy-to-parse intermediate text format that can | |
183 | be used by @command{lcov} or other tools. The output is a single | |
184 | @file{.gcov} file per @file{.gcda} file. No source code is required. | |
185 | ||
186 | The format of the intermediate @file{.gcov} file is plain text with | |
187 | one entry per line | |
188 | ||
189 | @smallexample | |
190 | file:@var{source_file_name} | |
191 | function:@var{line_number},@var{execution_count},@var{function_name} | |
192 | lcount:@var{line number},@var{execution_count} | |
193 | branch:@var{line_number},@var{branch_coverage_type} | |
194 | ||
195 | Where the @var{branch_coverage_type} is | |
196 | notexec (Branch not executed) | |
197 | taken (Branch executed and taken) | |
198 | nottaken (Branch executed, but not taken) | |
199 | ||
200 | There can be multiple @var{file} entries in an intermediate gcov | |
201 | file. All entries following a @var{file} pertain to that source file | |
202 | until the next @var{file} entry. | |
203 | @end smallexample | |
204 | ||
54a41d1b | 205 | Here is a sample when @option{-i} is used in conjunction with @option{-b} option: |
fc8a650e SS |
206 | |
207 | @smallexample | |
208 | file:array.cc | |
209 | function:11,1,_Z3sumRKSt6vectorIPiSaIS0_EE | |
210 | function:22,1,main | |
211 | lcount:11,1 | |
212 | lcount:12,1 | |
213 | lcount:14,1 | |
214 | branch:14,taken | |
215 | lcount:26,1 | |
216 | branch:28,nottaken | |
217 | @end smallexample | |
218 | ||
28f4a4a8 ML |
219 | @item -k |
220 | @itemx --use-colors | |
221 | ||
222 | Use colors for lines of code that have zero coverage. We use red color for | |
223 | non-exceptional lines and cyan for exceptional. Same colors are used for | |
224 | basic blocks with @option{-a} option. | |
225 | ||
226 | ||
2f360676 ML |
227 | @item -l |
228 | @itemx --long-file-names | |
229 | Create long file names for included source files. For example, if the | |
230 | header file @file{x.h} contains code, and was included in the file | |
231 | @file{a.c}, then running @command{gcov} on the file @file{a.c} will | |
232 | produce an output file called @file{a.c##x.h.gcov} instead of | |
233 | @file{x.h.gcov}. This can be useful if @file{x.h} is included in | |
234 | multiple source files and you want to see the individual | |
235 | contributions. If you use the @samp{-p} option, both the including | |
236 | and included file names will be complete path names. | |
237 | ||
fc8a650e SS |
238 | @item -m |
239 | @itemx --demangled-names | |
240 | Display demangled function names in output. The default is to show | |
241 | mangled function names. | |
242 | ||
2f360676 ML |
243 | @item -n |
244 | @itemx --no-output | |
245 | Do not create the @command{gcov} output file. | |
246 | ||
247 | @item -o @var{directory|file} | |
248 | @itemx --object-directory @var{directory} | |
249 | @itemx --object-file @var{file} | |
250 | Specify either the directory containing the gcov data files, or the | |
251 | object path name. The @file{.gcno}, and | |
252 | @file{.gcda} data files are searched for using this option. If a directory | |
253 | is specified, the data files are in that directory and named after the | |
254 | input file name, without its extension. If a file is specified here, | |
255 | the data files are named after that file, without its extension. | |
256 | ||
257 | @item -p | |
258 | @itemx --preserve-paths | |
259 | Preserve complete path information in the names of generated | |
260 | @file{.gcov} files. Without this option, just the filename component is | |
261 | used. With this option, all directories are used, with @samp{/} characters | |
262 | translated to @samp{#} characters, @file{.} directory components | |
263 | removed and unremoveable @file{..} | |
264 | components renamed to @samp{^}. This is useful if sourcefiles are in several | |
265 | different directories. | |
266 | ||
267 | @item -r | |
268 | @itemx --relative-only | |
269 | Only output information about source files with a relative pathname | |
270 | (after source prefix elision). Absolute paths are usually system | |
271 | header files and coverage of any inline functions therein is normally | |
272 | uninteresting. | |
273 | ||
274 | @item -s @var{directory} | |
275 | @itemx --source-prefix @var{directory} | |
276 | A prefix for source file names to remove when generating the output | |
277 | coverage files. This option is useful when building in a separate | |
278 | directory, and the pathname to the source directory is not wanted when | |
279 | determining the output file names. Note that this prefix detection is | |
280 | applied before determining whether the source file is absolute. | |
281 | ||
282 | @item -u | |
283 | @itemx --unconditional-branches | |
284 | When branch probabilities are given, include those of unconditional branches. | |
285 | Unconditional branches are normally not interesting. | |
286 | ||
287 | @item -v | |
288 | @itemx --version | |
289 | Display the @command{gcov} version number (on the standard output), | |
290 | and exit without doing any further processing. | |
291 | ||
292 | @item -w | |
293 | @itemx --verbose | |
294 | Print verbose informations related to basic blocks and arcs. | |
295 | ||
75cc66f2 ML |
296 | @item -x |
297 | @itemx --hash-filenames | |
298 | By default, gcov uses the full pathname of the source files to to create | |
299 | an output filename. This can lead to long filenames that can overflow | |
300 | filesystem limits. This option creates names of the form | |
301 | @file{@var{source-file}##@var{md5}.gcov}, | |
302 | where the @var{source-file} component is the final filename part and | |
303 | the @var{md5} component is calculated from the full mangled name that | |
304 | would have been used otherwise. | |
305 | ||
2be7973e DE |
306 | @end table |
307 | ||
daf2f129 | 308 | @command{gcov} should be run with the current directory the same as that |
8a36672b JM |
309 | when you invoked the compiler. Otherwise it will not be able to locate |
310 | the source files. @command{gcov} produces files called | |
311 | @file{@var{mangledname}.gcov} in the current directory. These contain | |
daf2f129 | 312 | the coverage information of the source file they correspond to. |
eeabee0a NS |
313 | One @file{.gcov} file is produced for each source (or header) file |
314 | containing code, | |
8a36672b | 315 | which was compiled to produce the data files. The @var{mangledname} part |
8100063e NS |
316 | of the output file name is usually simply the source file name, but can |
317 | be something more complicated if the @samp{-l} or @samp{-p} options are | |
8a36672b | 318 | given. Refer to those options for details. |
8100063e | 319 | |
eeabee0a NS |
320 | If you invoke @command{gcov} with multiple input files, the |
321 | contributions from each input file are summed. Typically you would | |
322 | invoke it with the same list of files as the final link of your executable. | |
323 | ||
78466c0e | 324 | The @file{.gcov} files contain the @samp{:} separated fields along with |
8a36672b | 325 | program source code. The format is |
37b8715b NS |
326 | |
327 | @smallexample | |
328 | @var{execution_count}:@var{line_number}:@var{source line text} | |
329 | @end smallexample | |
330 | ||
331 | Additional block information may succeed each line, when requested by | |
8a36672b | 332 | command line option. The @var{execution_count} is @samp{-} for lines |
8919c0d9 NS |
333 | containing no code. Unexecuted lines are marked @samp{#####} or |
334 | @samp{====}, depending on whether they are reachable by | |
335 | non-exceptional paths or only exceptional paths such as C++ exception | |
e03f26cb | 336 | handlers, respectively. Given @samp{-a} option, unexecuted blocks are |
4e8bfd79 | 337 | marked @samp{$$$$$} or @samp{%%%%%}, depending on whether a basic block |
e03f26cb | 338 | is reachable via non-exceptional or exceptional paths. |
f5d39c3d | 339 | |
00da60d4 ML |
340 | Note that GCC can completely remove the bodies of functions that are |
341 | not needed -- for instance if they are inlined everywhere. Such functions | |
342 | are marked with @samp{-}, which can be confusing. | |
343 | Use the @option{-fkeep-inline-functions} and @option{-fkeep-static-functions} | |
344 | options to retain these functions and | |
345 | allow gcov to properly show their @var{execution_count}. | |
346 | ||
8919c0d9 NS |
347 | Some lines of information at the start have @var{line_number} of zero. |
348 | These preamble lines are of the form | |
f5d39c3d NS |
349 | |
350 | @smallexample | |
351 | -:0:@var{tag}:@var{value} | |
352 | @end smallexample | |
353 | ||
354 | The ordering and number of these preamble lines will be augmented as | |
355 | @command{gcov} development progresses --- do not rely on them remaining | |
356 | unchanged. Use @var{tag} to locate a particular preamble line. | |
357 | ||
358 | The additional block information is of the form | |
359 | ||
360 | @smallexample | |
361 | @var{tag} @var{information} | |
362 | @end smallexample | |
363 | ||
364 | The @var{information} is human readable, but designed to be simple | |
365 | enough for machine parsing too. | |
37b8715b NS |
366 | |
367 | When printing percentages, 0% and 100% are only printed when the values | |
8a36672b | 368 | are @emph{exactly} 0% and 100% respectively. Other values which would |
37b8715b NS |
369 | conventionally be rounded to 0% or 100% are instead printed as the |
370 | nearest non-boundary value. | |
371 | ||
c50174e7 | 372 | When using @command{gcov}, you must first compile your program with two |
f0523f02 | 373 | special GCC options: @samp{-fprofile-arcs -ftest-coverage}. |
2be7973e DE |
374 | This tells the compiler to generate additional information needed by |
375 | gcov (basically a flow graph of the program) and also includes | |
376 | additional code in the object files for generating the extra profiling | |
377 | information needed by gcov. These additional files are placed in the | |
37b8715b | 378 | directory where the object file is located. |
2be7973e DE |
379 | |
380 | Running the program will cause profile output to be generated. For each | |
58cd2515 NS |
381 | source file compiled with @option{-fprofile-arcs}, an accompanying |
382 | @file{.gcda} file will be placed in the object file directory. | |
2be7973e | 383 | |
c50174e7 | 384 | Running @command{gcov} with your program's source file names as arguments |
2be7973e | 385 | will now produce a listing of the code along with frequency of execution |
c50174e7 JM |
386 | for each line. For example, if your program is called @file{tmp.c}, this |
387 | is what you see when you use the basic @command{gcov} facility: | |
2be7973e DE |
388 | |
389 | @smallexample | |
390 | $ gcc -fprofile-arcs -ftest-coverage tmp.c | |
391 | $ a.out | |
392 | $ gcov tmp.c | |
c1c6ca63 ML |
393 | File 'tmp.c' |
394 | Lines executed:90.00% of 10 | |
395 | Creating 'tmp.c.gcov' | |
2be7973e DE |
396 | @end smallexample |
397 | ||
c50174e7 | 398 | The file @file{tmp.c.gcov} contains output from @command{gcov}. |
2be7973e DE |
399 | Here is a sample: |
400 | ||
401 | @smallexample | |
37b8715b | 402 | -: 0:Source:tmp.c |
8100063e NS |
403 | -: 0:Graph:tmp.gcno |
404 | -: 0:Data:tmp.gcda | |
27283c73 NS |
405 | -: 0:Runs:1 |
406 | -: 0:Programs:1 | |
407 | -: 1:#include <stdio.h> | |
408 | -: 2: | |
409 | -: 3:int main (void) | |
27283c73 NS |
410 | 1: 4:@{ |
411 | 1: 5: int i, total; | |
daf2f129 | 412 | -: 6: |
27283c73 | 413 | 1: 7: total = 0; |
daf2f129 | 414 | -: 8: |
27283c73 NS |
415 | 11: 9: for (i = 0; i < 10; i++) |
416 | 10: 10: total += i; | |
daf2f129 | 417 | -: 11: |
27283c73 NS |
418 | 1: 12: if (total != 45) |
419 | #####: 13: printf ("Failure\n"); | |
420 | -: 14: else | |
421 | 1: 15: printf ("Success\n"); | |
422 | 1: 16: return 0; | |
423 | -: 17:@} | |
424 | @end smallexample | |
425 | ||
426 | When you use the @option{-a} option, you will get individual block | |
427 | counts, and the output looks like this: | |
428 | ||
429 | @smallexample | |
430 | -: 0:Source:tmp.c | |
8100063e NS |
431 | -: 0:Graph:tmp.gcno |
432 | -: 0:Data:tmp.gcda | |
27283c73 NS |
433 | -: 0:Runs:1 |
434 | -: 0:Programs:1 | |
37b8715b NS |
435 | -: 1:#include <stdio.h> |
436 | -: 2: | |
437 | -: 3:int main (void) | |
438 | 1: 4:@{ | |
27283c73 | 439 | 1: 4-block 0 |
37b8715b | 440 | 1: 5: int i, total; |
daf2f129 | 441 | -: 6: |
37b8715b | 442 | 1: 7: total = 0; |
daf2f129 | 443 | -: 8: |
37b8715b | 444 | 11: 9: for (i = 0; i < 10; i++) |
27283c73 | 445 | 11: 9-block 0 |
37b8715b | 446 | 10: 10: total += i; |
27283c73 | 447 | 10: 10-block 0 |
daf2f129 | 448 | -: 11: |
37b8715b | 449 | 1: 12: if (total != 45) |
27283c73 | 450 | 1: 12-block 0 |
37b8715b | 451 | #####: 13: printf ("Failure\n"); |
27283c73 | 452 | $$$$$: 13-block 0 |
37b8715b NS |
453 | -: 14: else |
454 | 1: 15: printf ("Success\n"); | |
27283c73 | 455 | 1: 15-block 0 |
37b8715b | 456 | 1: 16: return 0; |
27283c73 NS |
457 | 1: 16-block 0 |
458 | -: 17:@} | |
2be7973e DE |
459 | @end smallexample |
460 | ||
10b7602f | 461 | In this mode, each basic block is only shown on one line -- the last |
8a36672b | 462 | line of the block. A multi-line block will only contribute to the |
10b7602f NS |
463 | execution count of that last line, and other lines will not be shown |
464 | to contain code, unless previous blocks end on those lines. | |
465 | The total execution count of a line is shown and subsequent lines show | |
8a36672b | 466 | the execution counts for individual blocks that end on that line. After each |
10b7602f NS |
467 | block, the branch and call counts of the block will be shown, if the |
468 | @option{-b} option is given. | |
469 | ||
2dd76960 | 470 | Because of the way GCC instruments calls, a call count can be shown |
10b7602f | 471 | after a line with no individual blocks. |
27283c73 NS |
472 | As you can see, line 13 contains a basic block that was not executed. |
473 | ||
2be7973e | 474 | @need 450 |
c50174e7 | 475 | When you use the @option{-b} option, your output looks like this: |
2be7973e DE |
476 | |
477 | @smallexample | |
478 | $ gcov -b tmp.c | |
c1c6ca63 ML |
479 | File 'tmp.c' |
480 | Lines executed:90.00% of 10 | |
481 | Branches executed:80.00% of 5 | |
482 | Taken at least once:80.00% of 5 | |
483 | Calls executed:50.00% of 2 | |
484 | Creating 'tmp.c.gcov' | |
2be7973e DE |
485 | @end smallexample |
486 | ||
487 | Here is a sample of a resulting @file{tmp.c.gcov} file: | |
488 | ||
489 | @smallexample | |
37b8715b | 490 | -: 0:Source:tmp.c |
8100063e NS |
491 | -: 0:Graph:tmp.gcno |
492 | -: 0:Data:tmp.gcda | |
27283c73 NS |
493 | -: 0:Runs:1 |
494 | -: 0:Programs:1 | |
37b8715b NS |
495 | -: 1:#include <stdio.h> |
496 | -: 2: | |
497 | -: 3:int main (void) | |
27283c73 | 498 | function main called 1 returned 1 blocks executed 75% |
37b8715b NS |
499 | 1: 4:@{ |
500 | 1: 5: int i, total; | |
daf2f129 | 501 | -: 6: |
37b8715b | 502 | 1: 7: total = 0; |
daf2f129 | 503 | -: 8: |
37b8715b | 504 | 11: 9: for (i = 0; i < 10; i++) |
27283c73 NS |
505 | branch 0 taken 91% (fallthrough) |
506 | branch 1 taken 9% | |
37b8715b | 507 | 10: 10: total += i; |
daf2f129 | 508 | -: 11: |
37b8715b | 509 | 1: 12: if (total != 45) |
27283c73 NS |
510 | branch 0 taken 0% (fallthrough) |
511 | branch 1 taken 100% | |
37b8715b | 512 | #####: 13: printf ("Failure\n"); |
27283c73 | 513 | call 0 never executed |
37b8715b NS |
514 | -: 14: else |
515 | 1: 15: printf ("Success\n"); | |
27283c73 | 516 | call 0 called 1 returned 100% |
37b8715b | 517 | 1: 16: return 0; |
27283c73 | 518 | -: 17:@} |
2be7973e DE |
519 | @end smallexample |
520 | ||
f5d39c3d NS |
521 | For each function, a line is printed showing how many times the function |
522 | is called, how many times it returns and what percentage of the | |
523 | function's blocks were executed. | |
524 | ||
2be7973e DE |
525 | For each basic block, a line is printed after the last line of the basic |
526 | block describing the branch or call that ends the basic block. There can | |
527 | be multiple branches and calls listed for a single source line if there | |
528 | are multiple basic blocks that end on that line. In this case, the | |
529 | branches and calls are each given a number. There is no simple way to map | |
530 | these branches and calls back to source constructs. In general, though, | |
531 | the lowest numbered branch or call will correspond to the leftmost construct | |
532 | on the source line. | |
533 | ||
534 | For a branch, if it was executed at least once, then a percentage | |
535 | indicating the number of times the branch was taken divided by the | |
536 | number of times the branch was executed will be printed. Otherwise, the | |
537 | message ``never executed'' is printed. | |
538 | ||
539 | For a call, if it was executed at least once, then a percentage | |
540 | indicating the number of times the call returned divided by the number | |
541 | of times the call was executed will be printed. This will usually be | |
3e72a66f | 542 | 100%, but may be less for functions that call @code{exit} or @code{longjmp}, |
3b7a2e58 | 543 | and thus may not return every time they are called. |
2be7973e DE |
544 | |
545 | The execution counts are cumulative. If the example program were | |
58cd2515 | 546 | executed again without removing the @file{.gcda} file, the count for the |
2be7973e DE |
547 | number of times each line in the source was executed would be added to |
548 | the results of the previous run(s). This is potentially useful in | |
549 | several ways. For example, it could be used to accumulate data over a | |
550 | number of program runs as part of a test verification suite, or to | |
551 | provide more accurate long-term information over a large number of | |
552 | program runs. | |
553 | ||
58cd2515 | 554 | The data in the @file{.gcda} files is saved immediately before the program |
37b8715b | 555 | exits. For each source file compiled with @option{-fprofile-arcs}, the |
58cd2515 | 556 | profiling code first attempts to read in an existing @file{.gcda} file; if |
37b8715b NS |
557 | the file doesn't match the executable (differing number of basic block |
558 | counts) it will ignore the contents of the file. It then adds in the | |
559 | new execution counts and finally writes the data to the file. | |
2be7973e DE |
560 | |
561 | @node Gcov and Optimization | |
c50174e7 | 562 | @section Using @command{gcov} with GCC Optimization |
2be7973e | 563 | |
c50174e7 | 564 | If you plan to use @command{gcov} to help optimize your code, you must |
f0523f02 | 565 | first compile your program with two special GCC options: |
2be7973e | 566 | @samp{-fprofile-arcs -ftest-coverage}. Aside from that, you can use any |
f0523f02 | 567 | other GCC options; but if you want to prove that every single line |
2be7973e DE |
568 | in your program was executed, you should not compile with optimization |
569 | at the same time. On some machines the optimizer can eliminate some | |
570 | simple code lines by combining them with other lines. For example, code | |
571 | like this: | |
572 | ||
573 | @smallexample | |
574 | if (a != b) | |
575 | c = 1; | |
576 | else | |
577 | c = 0; | |
578 | @end smallexample | |
579 | ||
580 | @noindent | |
581 | can be compiled into one instruction on some machines. In this case, | |
c50174e7 | 582 | there is no way for @command{gcov} to calculate separate execution counts |
2be7973e | 583 | for each line because there isn't separate code for each line. Hence |
c50174e7 | 584 | the @command{gcov} output looks like this if you compiled the program with |
2be7973e DE |
585 | optimization: |
586 | ||
587 | @smallexample | |
37b8715b NS |
588 | 100: 12:if (a != b) |
589 | 100: 13: c = 1; | |
590 | 100: 14:else | |
591 | 100: 15: c = 0; | |
2be7973e DE |
592 | @end smallexample |
593 | ||
594 | The output shows that this block of code, combined by optimization, | |
595 | executed 100 times. In one sense this result is correct, because there | |
596 | was only one instruction representing all four of these lines. However, | |
597 | the output does not indicate how many times the result was 0 and how | |
598 | many times the result was 1. | |
58cd2515 NS |
599 | |
600 | Inlineable functions can create unexpected line counts. Line counts are | |
601 | shown for the source code of the inlineable function, but what is shown | |
602 | depends on where the function is inlined, or if it is not inlined at all. | |
603 | ||
604 | If the function is not inlined, the compiler must emit an out of line | |
605 | copy of the function, in any object file that needs it. If | |
606 | @file{fileA.o} and @file{fileB.o} both contain out of line bodies of a | |
607 | particular inlineable function, they will also both contain coverage | |
608 | counts for that function. When @file{fileA.o} and @file{fileB.o} are | |
609 | linked together, the linker will, on many systems, select one of those | |
610 | out of line bodies for all calls to that function, and remove or ignore | |
611 | the other. Unfortunately, it will not remove the coverage counters for | |
612 | the unused function body. Hence when instrumented, all but one use of | |
613 | that function will show zero counts. | |
614 | ||
615 | If the function is inlined in several places, the block structure in | |
616 | each location might not be the same. For instance, a condition might | |
617 | now be calculable at compile time in some instances. Because the | |
618 | coverage of all the uses of the inline function will be shown for the | |
619 | same source lines, the line counts themselves might seem inconsistent. | |
620 | ||
e0c8eebf | 621 | Long-running applications can use the @code{__gcov_reset} and @code{__gcov_dump} |
4e8ee9cb | 622 | facilities to restrict profile collection to the program region of |
e0c8eebf ML |
623 | interest. Calling @code{__gcov_reset(void)} will clear all profile counters |
624 | to zero, and calling @code{__gcov_dump(void)} will cause the profile information | |
4e8ee9cb | 625 | collected at that point to be dumped to @file{.gcda} output files. |
8c9434c2 ML |
626 | Instrumented applications use a static destructor with priority 99 |
627 | to invoke the @code{__gcov_dump} function. Thus @code{__gcov_dump} | |
628 | is executed after all user defined static destructors, | |
629 | as well as handlers registered with @code{atexit}. | |
4e8ee9cb | 630 | |
c01a508e | 631 | @c man end |
2be7973e DE |
632 | |
633 | @node Gcov Data Files | |
e6f3f526 | 634 | @section Brief Description of @command{gcov} Data Files |
2be7973e | 635 | |
4977bab6 ZW |
636 | @command{gcov} uses two files for profiling. The names of these files |
637 | are derived from the original @emph{object} file by substituting the | |
efbb59b2 SB |
638 | file suffix with either @file{.gcno}, or @file{.gcda}. The files |
639 | contain coverage and profile data stored in a platform-independent format. | |
640 | The @file{.gcno} files are placed in the same directory as the object | |
641 | file. By default, the @file{.gcda} files are also stored in the same | |
9472dcec | 642 | directory as the object file, but the GCC @option{-fprofile-dir} option |
efbb59b2 SB |
643 | may be used to store the @file{.gcda} files in a separate directory. |
644 | ||
645 | The @file{.gcno} notes file is generated when the source file is compiled | |
646 | with the GCC @option{-ftest-coverage} option. It contains information to | |
4977bab6 ZW |
647 | reconstruct the basic block graphs and assign source line numbers to |
648 | blocks. | |
6c208acd | 649 | |
efbb59b2 SB |
650 | The @file{.gcda} count data file is generated when a program containing |
651 | object files built with the GCC @option{-fprofile-arcs} option is executed. | |
652 | A separate @file{.gcda} file is created for each object file compiled with | |
653 | this option. It contains arc transition counts, value profile counts, and | |
654 | some summary information. | |
2be7973e | 655 | |
4977bab6 ZW |
656 | The full details of the file format is specified in @file{gcov-io.h}, |
657 | and functions provided in that header file should be used to access the | |
658 | coverage files. | |
992f396f GZ |
659 | |
660 | @node Cross-profiling | |
e6f3f526 | 661 | @section Data File Relocation to Support Cross-Profiling |
992f396f | 662 | |
ff2ce160 MS |
663 | Running the program will cause profile output to be generated. For each |
664 | source file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda} | |
665 | file will be placed in the object file directory. That implicitly requires | |
666 | running the program on the same system as it was built or having the same | |
992f396f GZ |
667 | absolute directory structure on the target system. The program will try |
668 | to create the needed directory structure, if it is not already present. | |
669 | ||
670 | To support cross-profiling, a program compiled with @option{-fprofile-arcs} | |
ff2ce160 | 671 | can relocate the data files based on two environment variables: |
992f396f GZ |
672 | |
673 | @itemize @bullet | |
674 | @item | |
ff2ce160 | 675 | GCOV_PREFIX contains the prefix to add to the absolute paths |
78e7dd6a KT |
676 | in the object file. Prefix can be absolute, or relative. The |
677 | default is no prefix. | |
992f396f GZ |
678 | |
679 | @item | |
680 | GCOV_PREFIX_STRIP indicates the how many initial directory names to strip off | |
681 | the hardwired absolute paths. Default value is 0. | |
682 | ||
78e7dd6a KT |
683 | @emph{Note:} If GCOV_PREFIX_STRIP is set without GCOV_PREFIX is undefined, |
684 | then a relative path is made out of the hardwired absolute paths. | |
992f396f GZ |
685 | @end itemize |
686 | ||
687 | For example, if the object file @file{/user/build/foo.o} was built with | |
688 | @option{-fprofile-arcs}, the final executable will try to create the data file | |
689 | @file{/user/build/foo.gcda} when running on the target system. This will | |
690 | fail if the corresponding directory does not exist and it is unable to create | |
691 | it. This can be overcome by, for example, setting the environment as | |
692 | @samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}. Such a | |
693 | setting will name the data file @file{/target/run/build/foo.gcda}. | |
694 | ||
695 | You must move the data files to the expected directory tree in order to | |
e03f26cb | 696 | use them for profile directed optimizations (@option{-fprofile-use}), or to |
a4d05547 | 697 | use the @command{gcov} tool. |