gcc: Invoking Gcov
1
1 10.2 Invoking 'gcov'
1 ====================
1
1 gcov [OPTIONS] FILES
1
1 'gcov' accepts the following options:
1
1 '-a'
1 '--all-blocks'
1 Write individual execution counts for every basic block. Normally
1 gcov outputs execution counts only for the main blocks of a line.
1 With this option you can determine if blocks within a single line
1 are not being executed.
1
1 '-b'
1 '--branch-probabilities'
1 Write branch frequencies to the output file, and write branch
1 summary info to the standard output. This option allows you to see
1 how often each branch in your program was taken. Unconditional
1 branches will not be shown, unless the '-u' option is given.
1
1 '-c'
1 '--branch-counts'
1 Write branch frequencies as the number of branches taken, rather
1 than the percentage of branches taken.
1
1 '-d'
1 '--display-progress'
1 Display the progress on the standard output.
1
1 '-f'
1 '--function-summaries'
1 Output summaries for each function in addition to the file level
1 summary.
1
1 '-h'
1 '--help'
1 Display help about using 'gcov' (on the standard output), and exit
1 without doing any further processing.
1
1 '-i'
1 '--intermediate-format'
1 Output gcov file in an easy-to-parse intermediate text format that
1 can be used by 'lcov' or other tools. The output is a single
1 '.gcov' file per '.gcda' file. No source code is required.
1
1 The format of the intermediate '.gcov' file is plain text with one
1 entry per line
1
1 version:GCC_VERSION
1 file:SOURCE_FILE_NAME
1 function:START_LINE_NUMBER,END_LINE_NUMBER,EXECUTION_COUNT,FUNCTION_NAME
1 lcount:LINE NUMBER,EXECUTION_COUNT,HAS_UNEXECUTED_BLOCK
1 branch:LINE_NUMBER,BRANCH_COVERAGE_TYPE
1
1 Where the BRANCH_COVERAGE_TYPE is
1 notexec (Branch not executed)
1 taken (Branch executed and taken)
1 nottaken (Branch executed, but not taken)
1
1 There can be multiple FILE entries in an intermediate gcov file.
1 All entries following a FILE pertain to that source file until the
1 next FILE entry. If there are multiple functions that start on a
1 single line, then corresponding lcount is repeated multiple times.
1
1 Here is a sample when '-i' is used in conjunction with '-b' option:
1
1 version: 8.1.0 20180103
1 file:tmp.cpp
1 function:7,7,0,_ZN3FooIcEC2Ev
1 function:7,7,1,_ZN3FooIiEC2Ev
1 function:8,8,0,_ZN3FooIcE3incEv
1 function:8,8,2,_ZN3FooIiE3incEv
1 function:18,37,1,main
1 lcount:7,0,1
1 lcount:7,1,0
1 lcount:8,0,1
1 lcount:8,2,0
1 lcount:18,1,0
1 lcount:21,1,0
1 branch:21,taken
1 branch:21,nottaken
1 lcount:23,1,0
1 branch:23,taken
1 branch:23,nottaken
1 lcount:24,1,0
1 branch:24,taken
1 branch:24,nottaken
1 lcount:25,1,0
1 lcount:27,11,0
1 branch:27,taken
1 branch:27,taken
1 lcount:28,10,0
1 lcount:30,1,1
1 branch:30,nottaken
1 branch:30,taken
1 lcount:32,1,0
1 branch:32,nottaken
1 branch:32,taken
1 lcount:33,0,1
1 branch:33,notexec
1 branch:33,notexec
1 lcount:35,1,0
1 branch:35,taken
1 branch:35,nottaken
1 lcount:36,1,0
1
1 '-j'
1 '--human-readable'
1 Write counts in human readable format (like 24k).
1
1 '-k'
1 '--use-colors'
1
1 Use colors for lines of code that have zero coverage. We use red
1 color for non-exceptional lines and cyan for exceptional. Same
1 colors are used for basic blocks with '-a' option.
1
1 '-l'
1 '--long-file-names'
1 Create long file names for included source files. For example, if
1 the header file 'x.h' contains code, and was included in the file
1 'a.c', then running 'gcov' on the file 'a.c' will produce an output
1 file called 'a.c##x.h.gcov' instead of 'x.h.gcov'. This can be
1 useful if 'x.h' is included in multiple source files and you want
1 to see the individual contributions. If you use the '-p' option,
1 both the including and included file names will be complete path
1 names.
1
1 '-m'
1 '--demangled-names'
1 Display demangled function names in output. The default is to show
1 mangled function names.
1
1 '-n'
1 '--no-output'
1 Do not create the 'gcov' output file.
1
1 '-o DIRECTORY|FILE'
1 '--object-directory DIRECTORY'
1 '--object-file FILE'
1 Specify either the directory containing the gcov data files, or the
1 object path name. The '.gcno', and '.gcda' data files are searched
1 for using this option. If a directory is specified, the data files
1 are in that directory and named after the input file name, without
1 its extension. If a file is specified here, the data files are
1 named after that file, without its extension.
1
1 '-p'
1 '--preserve-paths'
1 Preserve complete path information in the names of generated
1 '.gcov' files. Without this option, just the filename component is
1 used. With this option, all directories are used, with '/'
1 characters translated to '#' characters, '.' directory components
1 removed and unremoveable '..' components renamed to '^'. This is
1 useful if sourcefiles are in several different directories.
1
1 '-r'
1 '--relative-only'
1 Only output information about source files with a relative pathname
1 (after source prefix elision). Absolute paths are usually system
1 header files and coverage of any inline functions therein is
1 normally uninteresting.
1
1 '-s DIRECTORY'
1 '--source-prefix DIRECTORY'
1 A prefix for source file names to remove when generating the output
1 coverage files. This option is useful when building in a separate
1 directory, and the pathname to the source directory is not wanted
1 when determining the output file names. Note that this prefix
1 detection is applied before determining whether the source file is
1 absolute.
1
1 '-u'
1 '--unconditional-branches'
1 When branch probabilities are given, include those of unconditional
1 branches. Unconditional branches are normally not interesting.
1
1 '-v'
1 '--version'
1 Display the 'gcov' version number (on the standard output), and
1 exit without doing any further processing.
1
1 '-w'
1 '--verbose'
1 Print verbose informations related to basic blocks and arcs.
1
1 '-x'
1 '--hash-filenames'
1 By default, gcov uses the full pathname of the source files to
1 create an output filename. This can lead to long filenames that
1 can overflow filesystem limits. This option creates names of the
1 form 'SOURCE-FILE##MD5.gcov', where the SOURCE-FILE component is
1 the final filename part and the MD5 component is calculated from
1 the full mangled name that would have been used otherwise.
1
1 'gcov' should be run with the current directory the same as that when
1 you invoked the compiler. Otherwise it will not be able to locate the
1 source files. 'gcov' produces files called 'MANGLEDNAME.gcov' in the
1 current directory. These contain the coverage information of the source
1 file they correspond to. One '.gcov' file is produced for each source
1 (or header) file containing code, which was compiled to produce the data
1 files. The MANGLEDNAME part of the output file name is usually simply
1 the source file name, but can be something more complicated if the '-l'
1 or '-p' options are given. Refer to those options for details.
1
1 If you invoke 'gcov' with multiple input files, the contributions from
1 each input file are summed. Typically you would invoke it with the same
1 list of files as the final link of your executable.
1
1 The '.gcov' files contain the ':' separated fields along with program
1 source code. The format is
1
1 EXECUTION_COUNT:LINE_NUMBER:SOURCE LINE TEXT
1
1 Additional block information may succeed each line, when requested by
1 command line option. The EXECUTION_COUNT is '-' for lines containing no
1 code. Unexecuted lines are marked '#####' or '=====', depending on
1 whether they are reachable by non-exceptional paths or only exceptional
1 paths such as C++ exception handlers, respectively. Given '-a' option,
1 unexecuted blocks are marked '$$$$$' or '%%%%%', depending on whether a
1 basic block is reachable via non-exceptional or exceptional paths.
1 Executed basic blocks having a statement with zero EXECUTION_COUNT end
1 with '*' character and are colored with magenta color with '-k' option.
1 The functionality is not supported in Ada.
1
1 Note that GCC can completely remove the bodies of functions that are
1 not needed - for instance if they are inlined everywhere. Such
1 functions are marked with '-', which can be confusing. Use the
1 '-fkeep-inline-functions' and '-fkeep-static-functions' options to
1 retain these functions and allow gcov to properly show their
1 EXECUTION_COUNT.
1
1 Some lines of information at the start have LINE_NUMBER of zero. These
1 preamble lines are of the form
1
1 -:0:TAG:VALUE
1
1 The ordering and number of these preamble lines will be augmented as
1 'gcov' development progresses -- do not rely on them remaining
1 unchanged. Use TAG to locate a particular preamble line.
1
1 The additional block information is of the form
1
1 TAG INFORMATION
1
1 The INFORMATION is human readable, but designed to be simple enough for
1 machine parsing too.
1
1 When printing percentages, 0% and 100% are only printed when the values
1 are _exactly_ 0% and 100% respectively. Other values which would
1 conventionally be rounded to 0% or 100% are instead printed as the
1 nearest non-boundary value.
1
1 When using 'gcov', you must first compile your program with two special
1 GCC options: '-fprofile-arcs -ftest-coverage'. This tells the compiler
1 to generate additional information needed by gcov (basically a flow
1 graph of the program) and also includes additional code in the object
1 files for generating the extra profiling information needed by gcov.
1 These additional files are placed in the directory where the object file
1 is located.
1
1 Running the program will cause profile output to be generated. For
1 each source file compiled with '-fprofile-arcs', an accompanying '.gcda'
1 file will be placed in the object file directory.
1
1 Running 'gcov' with your program's source file names as arguments will
1 now produce a listing of the code along with frequency of execution for
1 each line. For example, if your program is called 'tmp.cpp', this is
1 what you see when you use the basic 'gcov' facility:
1
1 $ g++ -fprofile-arcs -ftest-coverage tmp.cpp
1 $ a.out
1 $ gcov tmp.cpp -m
1 File 'tmp.cpp'
1 Lines executed:92.86% of 14
1 Creating 'tmp.cpp.gcov'
1
1 The file 'tmp.cpp.gcov' contains output from 'gcov'. Here is a sample:
1
1 -: 0:Source:tmp.cpp
1 -: 0:Graph:tmp.gcno
1 -: 0:Data:tmp.gcda
1 -: 0:Runs:1
1 -: 0:Programs:1
1 -: 1:#include <stdio.h>
1 -: 2:
1 -: 3:template<class T>
1 -: 4:class Foo
1 -: 5:{
1 -: 6: public:
1 1*: 7: Foo(): b (1000) {}
1 ------------------
1 Foo<char>::Foo():
1 #####: 7: Foo(): b (1000) {}
1 ------------------
1 Foo<int>::Foo():
1 1: 7: Foo(): b (1000) {}
1 ------------------
1 2*: 8: void inc () { b++; }
1 ------------------
1 Foo<char>::inc():
1 #####: 8: void inc () { b++; }
1 ------------------
1 Foo<int>::inc():
1 2: 8: void inc () { b++; }
1 ------------------
1 -: 9:
1 -: 10: private:
1 -: 11: int b;
1 -: 12:};
1 -: 13:
1 -: 14:template class Foo<int>;
1 -: 15:template class Foo<char>;
1 -: 16:
1 -: 17:int
1 1: 18:main (void)
1 -: 19:{
1 -: 20: int i, total;
1 1: 21: Foo<int> counter;
1 -: 22:
1 1: 23: counter.inc();
1 1: 24: counter.inc();
1 1: 25: total = 0;
1 -: 26:
1 11: 27: for (i = 0; i < 10; i++)
1 10: 28: total += i;
1 -: 29:
1 1*: 30: int v = total > 100 ? 1 : 2;
1 -: 31:
1 1: 32: if (total != 45)
1 #####: 33: printf ("Failure\n");
1 -: 34: else
1 1: 35: printf ("Success\n");
1 1: 36: return 0;
1 -: 37:}
1
1 Note that line 7 is shown in the report multiple times. First
1 occurrence presents total number of execution of the line and the next
1 two belong to instances of class Foo constructors. As you can also see,
1 line 30 contains some unexecuted basic blocks and thus execution count
1 has asterisk symbol.
1
1 When you use the '-a' option, you will get individual block counts, and
1 the output looks like this:
1
1 -: 0:Source:tmp.cpp
1 -: 0:Graph:tmp.gcno
1 -: 0:Data:tmp.gcda
1 -: 0:Runs:1
1 -: 0:Programs:1
1 -: 1:#include <stdio.h>
1 -: 2:
1 -: 3:template<class T>
1 -: 4:class Foo
1 -: 5:{
1 -: 6: public:
1 1*: 7: Foo(): b (1000) {}
1 ------------------
1 Foo<char>::Foo():
1 #####: 7: Foo(): b (1000) {}
1 ------------------
1 Foo<int>::Foo():
1 1: 7: Foo(): b (1000) {}
1 ------------------
1 2*: 8: void inc () { b++; }
1 ------------------
1 Foo<char>::inc():
1 #####: 8: void inc () { b++; }
1 ------------------
1 Foo<int>::inc():
1 2: 8: void inc () { b++; }
1 ------------------
1 -: 9:
1 -: 10: private:
1 -: 11: int b;
1 -: 12:};
1 -: 13:
1 -: 14:template class Foo<int>;
1 -: 15:template class Foo<char>;
1 -: 16:
1 -: 17:int
1 1: 18:main (void)
1 -: 19:{
1 -: 20: int i, total;
1 1: 21: Foo<int> counter;
1 1: 21-block 0
1 -: 22:
1 1: 23: counter.inc();
1 1: 23-block 0
1 1: 24: counter.inc();
1 1: 24-block 0
1 1: 25: total = 0;
1 -: 26:
1 11: 27: for (i = 0; i < 10; i++)
1 1: 27-block 0
1 11: 27-block 1
1 10: 28: total += i;
1 10: 28-block 0
1 -: 29:
1 1*: 30: int v = total > 100 ? 1 : 2;
1 1: 30-block 0
1 %%%%%: 30-block 1
1 1: 30-block 2
1 -: 31:
1 1: 32: if (total != 45)
1 1: 32-block 0
1 #####: 33: printf ("Failure\n");
1 %%%%%: 33-block 0
1 -: 34: else
1 1: 35: printf ("Success\n");
1 1: 35-block 0
1 1: 36: return 0;
1 1: 36-block 0
1 -: 37:}
1
1 In this mode, each basic block is only shown on one line - the last
1 line of the block. A multi-line block will only contribute to the
1 execution count of that last line, and other lines will not be shown to
1 contain code, unless previous blocks end on those lines. The total
1 execution count of a line is shown and subsequent lines show the
1 execution counts for individual blocks that end on that line. After
1 each block, the branch and call counts of the block will be shown, if
1 the '-b' option is given.
1
1 Because of the way GCC instruments calls, a call count can be shown
1 after a line with no individual blocks. As you can see, line 33
1 contains a basic block that was not executed.
1
1 When you use the '-b' option, your output looks like this:
1
1 -: 0:Source:tmp.cpp
1 -: 0:Graph:tmp.gcno
1 -: 0:Data:tmp.gcda
1 -: 0:Runs:1
1 -: 0:Programs:1
1 -: 1:#include <stdio.h>
1 -: 2:
1 -: 3:template<class T>
1 -: 4:class Foo
1 -: 5:{
1 -: 6: public:
1 1*: 7: Foo(): b (1000) {}
1 ------------------
1 Foo<char>::Foo():
1 function Foo<char>::Foo() called 0 returned 0% blocks executed 0%
1 #####: 7: Foo(): b (1000) {}
1 ------------------
1 Foo<int>::Foo():
1 function Foo<int>::Foo() called 1 returned 100% blocks executed 100%
1 1: 7: Foo(): b (1000) {}
1 ------------------
1 2*: 8: void inc () { b++; }
1 ------------------
1 Foo<char>::inc():
1 function Foo<char>::inc() called 0 returned 0% blocks executed 0%
1 #####: 8: void inc () { b++; }
1 ------------------
1 Foo<int>::inc():
1 function Foo<int>::inc() called 2 returned 100% blocks executed 100%
1 2: 8: void inc () { b++; }
1 ------------------
1 -: 9:
1 -: 10: private:
1 -: 11: int b;
1 -: 12:};
1 -: 13:
1 -: 14:template class Foo<int>;
1 -: 15:template class Foo<char>;
1 -: 16:
1 -: 17:int
1 function main called 1 returned 100% blocks executed 81%
1 1: 18:main (void)
1 -: 19:{
1 -: 20: int i, total;
1 1: 21: Foo<int> counter;
1 call 0 returned 100%
1 branch 1 taken 100% (fallthrough)
1 branch 2 taken 0% (throw)
1 -: 22:
1 1: 23: counter.inc();
1 call 0 returned 100%
1 branch 1 taken 100% (fallthrough)
1 branch 2 taken 0% (throw)
1 1: 24: counter.inc();
1 call 0 returned 100%
1 branch 1 taken 100% (fallthrough)
1 branch 2 taken 0% (throw)
1 1: 25: total = 0;
1 -: 26:
1 11: 27: for (i = 0; i < 10; i++)
1 branch 0 taken 91% (fallthrough)
1 branch 1 taken 9%
1 10: 28: total += i;
1 -: 29:
1 1*: 30: int v = total > 100 ? 1 : 2;
1 branch 0 taken 0% (fallthrough)
1 branch 1 taken 100%
1 -: 31:
1 1: 32: if (total != 45)
1 branch 0 taken 0% (fallthrough)
1 branch 1 taken 100%
1 #####: 33: printf ("Failure\n");
1 call 0 never executed
1 branch 1 never executed
1 branch 2 never executed
1 -: 34: else
1 1: 35: printf ("Success\n");
1 call 0 returned 100%
1 branch 1 taken 100% (fallthrough)
1 branch 2 taken 0% (throw)
1 1: 36: return 0;
1 -: 37:}
1
1 For each function, a line is printed showing how many times the
1 function is called, how many times it returns and what percentage of the
1 function's blocks were executed.
1
1 For each basic block, a line is printed after the last line of the
1 basic block describing the branch or call that ends the basic block.
1 There can be multiple branches and calls listed for a single source line
1 if there are multiple basic blocks that end on that line. In this case,
1 the branches and calls are each given a number. There is no simple way
1 to map these branches and calls back to source constructs. In general,
1 though, the lowest numbered branch or call will correspond to the
1 leftmost construct on the source line.
1
1 For a branch, if it was executed at least once, then a percentage
1 indicating the number of times the branch was taken divided by the
1 number of times the branch was executed will be printed. Otherwise, the
1 message "never executed" is printed.
1
1 For a call, if it was executed at least once, then a percentage
1 indicating the number of times the call returned divided by the number
1 of times the call was executed will be printed. This will usually be
1 100%, but may be less for functions that call 'exit' or 'longjmp', and
1 thus may not return every time they are called.
1
1 The execution counts are cumulative. If the example program were
1 executed again without removing the '.gcda' file, the count for the
1 number of times each line in the source was executed would be added to
1 the results of the previous run(s). This is potentially useful in
1 several ways. For example, it could be used to accumulate data over a
1 number of program runs as part of a test verification suite, or to
1 provide more accurate long-term information over a large number of
1 program runs.
1
1 The data in the '.gcda' files is saved immediately before the program
1 exits. For each source file compiled with '-fprofile-arcs', the
1 profiling code first attempts to read in an existing '.gcda' file; if
1 the file doesn't match the executable (differing number of basic block
1 counts) it will ignore the contents of the file. It then adds in the
1 new execution counts and finally writes the data to the file.
1