CbC/CbC_gcc: gcc/doc/gcov.texi comparison

comparison gcc/doc/gcov.texi @ 131:84e7813d76e9

gcc-8.2

author	mir3636
date	Thu, 25 Oct 2018 07:37:49 +0900
parents	04ced10e8804
children	1830386684a0

comparison

equal deleted inserted replaced

-:04ced10e8804
+:84e7813d76e9
-@c Copyright (C) 1996-2017 Free Software Foundation, Inc.
+@c Copyright (C) 1996-2018 Free Software Foundation, Inc.
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 @ignore
 @c man begin COPYRIGHT
-Copyright @copyright{} 1996-2017 Free Software Foundation, Inc.
+Copyright @copyright{} 1996-2018 Free Software Foundation, Inc.
 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with the
 Invariant Sections being ``GNU General Public License'' and ``Funding
 [@option{-b}|@option{--branch-probabilities}]
 [@option{-c}|@option{--branch-counts}]
 [@option{-d}|@option{--display-progress}]
 [@option{-f}|@option{--function-summaries}]
 [@option{-i}|@option{--intermediate-format}]
+[@option{-j}|@option{--human-readable}]
+[@option{-k}|@option{--use-colors}]
 [@option{-l}|@option{--long-file-names}]
 [@option{-m}|@option{--demangled-names}]
 [@option{-n}|@option{--no-output}]
 [@option{-o}|@option{--object-directory} @var{directory|file}]
 [@option{-p}|@option{--preserve-paths}]
+[@option{-q}|@option{--use-hotness-colors}]
 [@option{-r}|@option{--relative-only}]
 [@option{-s}|@option{--source-prefix} @var{directory}]
+[@option{-t}|@option{--stdout}]
 [@option{-u}|@option{--unconditional-branches}]
 [@option{-x}|@option{--hash-filenames}]
 @var{files}
 @c man end
 @c man begin SEEALSO
 The format of the intermediate @file{.gcov} file is plain text with
 one entry per line
 @smallexample
+version:@var{gcc_version}
+cwd:@var{working_directory}
 file:@var{source_file_name}
-function:@var{line_number},@var{execution_count},@var{function_name}
+function:@var{start_line_number},@var{end_line_number},@var{execution_count},@var{function_name}
-lcount:@var{line number},@var{execution_count}
+lcount:@var{line number},@var{execution_count},@var{has_unexecuted_block}
 branch:@var{line_number},@var{branch_coverage_type}
 Where the @var{branch_coverage_type} is
 notexec (Branch not executed)
 taken (Branch executed and taken)
 nottaken (Branch executed, but not taken)
+@end smallexample
 There can be multiple @var{file} entries in an intermediate gcov
 file. All entries following a @var{file} pertain to that source file
-until the next @var{file} entry.
+until the next @var{file} entry.  If there are multiple functions that
-@end smallexample
+start on a single line, then corresponding lcount is repeated multiple
+times.
 Here is a sample when @option{-i} is used in conjunction with @option{-b} option:
 @smallexample
-file:array.cc
+version: 8.1.0 20180103
-function:11,1,_Z3sumRKSt6vectorIPiSaIS0_EE
+cwd:/home/gcc/testcase
-function:22,1,main
+file:tmp.cpp
-lcount:11,1
+function:7,7,0,_ZN3FooIcEC2Ev
-lcount:12,1
+function:7,7,1,_ZN3FooIiEC2Ev
-lcount:14,1
+function:8,8,0,_ZN3FooIcE3incEv
-branch:14,taken
+function:8,8,2,_ZN3FooIiE3incEv
-lcount:26,1
+function:18,37,1,main
-branch:28,nottaken
+lcount:7,0,1
-@end smallexample
+lcount:7,1,0
+lcount:8,0,1
+lcount:8,2,0
+lcount:18,1,0
+lcount:21,1,0
+branch:21,taken
+branch:21,nottaken
+lcount:23,1,0
+branch:23,taken
+branch:23,nottaken
+lcount:24,1,0
+branch:24,taken
+branch:24,nottaken
+lcount:25,1,0
+lcount:27,11,0
+branch:27,taken
+branch:27,taken
+lcount:28,10,0
+lcount:30,1,1
+branch:30,nottaken
+branch:30,taken
+lcount:32,1,0
+branch:32,nottaken
+branch:32,taken
+lcount:33,0,1
+branch:33,notexec
+branch:33,notexec
+lcount:35,1,0
+branch:35,taken
+branch:35,nottaken
+lcount:36,1,0
+@end smallexample
+@item -j
+@itemx --human-readable
+Write counts in human readable format (like 24.6k).
+@item -k
+@itemx --use-colors
+Use colors for lines of code that have zero coverage.  We use red color for
+non-exceptional lines and cyan for exceptional.  Same colors are used for
+basic blocks with @option{-a} option.
 @item -l
 @itemx --long-file-names
 Create long file names for included source files.  For example, if the
 header file @file{x.h} contains code, and was included in the file
 translated to @samp{#} characters, @file{.} directory components
 removed and unremoveable @file{..}
 components renamed to @samp{^}.  This is useful if sourcefiles are in several
 different directories.
+@item -q
+@itemx --use-hotness-colors
+Emit perf-like colored output for hot lines.  Legend of the color scale
+is printed at the very beginning of the output file.
 @item -r
 @itemx --relative-only
 Only output information about source files with a relative pathname
 (after source prefix elision).  Absolute paths are usually system
 header files and coverage of any inline functions therein is normally
 coverage files.  This option is useful when building in a separate
 directory, and the pathname to the source directory is not wanted when
 determining the output file names.  Note that this prefix detection is
 applied before determining whether the source file is absolute.
+@item -t
+@itemx --stdout
+Output to standard output instead of output files.
 @item -u
 @itemx --unconditional-branches
 When branch probabilities are given, include those of unconditional branches.
 Unconditional branches are normally not interesting.
 @itemx --verbose
 Print verbose informations related to basic blocks and arcs.
 @item -x
 @itemx --hash-filenames
-By default, gcov uses the full pathname of the source files to to create
+By default, gcov uses the full pathname of the source files to create
 an output filename.  This can lead to long filenames that can overflow
 filesystem limits.  This option creates names of the form
 @file{@var{source-file}##@var{md5}.gcov},
 where the @var{source-file} component is the final filename part and
 the @var{md5} component is calculated from the full mangled name that
 @end smallexample
 Additional block information may succeed each line, when requested by
 command line option.  The @var{execution_count} is @samp{-} for lines
 containing no code.  Unexecuted lines are marked @samp{#####} or
-@samp{====}, depending on whether they are reachable by
+@samp{=====}, depending on whether they are reachable by
 non-exceptional paths or only exceptional paths such as C++ exception
-handlers, respectively. Given @samp{-a} option, unexecuted blocks are
+handlers, respectively. Given the @samp{-a} option, unexecuted blocks are
 marked @samp{$$$$$} or @samp{%%%%%}, depending on whether a basic block
 is reachable via non-exceptional or exceptional paths.
+Executed basic blocks having a statement with zero @var{execution_count}
+end with @samp{*} character and are colored with magenta color with
+the @option{-k} option.  This functionality is not supported in Ada.
+Note that GCC can completely remove the bodies of functions that are
+not needed -- for instance if they are inlined everywhere.  Such functions
+are marked with @samp{-}, which can be confusing.
+Use the @option{-fkeep-inline-functions} and @option{-fkeep-static-functions}
+options to retain these functions and
+allow gcov to properly show their @var{execution_count}.
 Some lines of information at the start have @var{line_number} of zero.
 These preamble lines are of the form
 @smallexample
 source file compiled with @option{-fprofile-arcs}, an accompanying
 @file{.gcda} file will be placed in the object file directory.
 Running @command{gcov} with your program's source file names as arguments
 will now produce a listing of the code along with frequency of execution
-for each line.  For example, if your program is called @file{tmp.c}, this
+for each line.  For example, if your program is called @file{tmp.cpp}, this
 is what you see when you use the basic @command{gcov} facility:
 @smallexample
-$ gcc -fprofile-arcs -ftest-coverage tmp.c
+$ g++ -fprofile-arcs -ftest-coverage tmp.cpp
 $ a.out
-$ gcov tmp.c
+$ gcov tmp.cpp -m
-File 'tmp.c'
+File 'tmp.cpp'
-Lines executed:90.00% of 10
+Lines executed:92.86% of 14
-Creating 'tmp.c.gcov'
+Creating 'tmp.cpp.gcov'
 @end smallexample
-The file @file{tmp.c.gcov} contains output from @command{gcov}.
+The file @file{tmp.cpp.gcov} contains output from @command{gcov}.
 Here is a sample:
 @smallexample
--:    0:Source:tmp.c
+-:    0:Source:tmp.cpp
+-:    0:Working directory:/home/gcc/testcase
 -:    0:Graph:tmp.gcno
 -:    0:Data:tmp.gcda
 -:    0:Runs:1
 -:    0:Programs:1
 -:    1:#include <stdio.h>
 -:    2:
--:    3:int main (void)
+-:    3:template<class T>
-1:    4:@{
+-:    4:class Foo
-1:    5:  int i, total;
+-:    5:@{
--:    6:
+-:    6:  public:
-1:    7:  total = 0;
+1*:    7:  Foo(): b (1000) @{@}
--:    8:
+------------------
-11:    9:  for (i = 0; i < 10; i++)
+Foo<char>::Foo():
-10:   10:    total += i;
+#####:    7:  Foo(): b (1000) @{@}
--:   11:
+------------------
-1:   12:  if (total != 45)
+Foo<int>::Foo():
-#####:   13:    printf ("Failure\n");
+1:    7:  Foo(): b (1000) @{@}
--:   14:  else
+------------------
-1:   15:    printf ("Success\n");
+2*:    8:  void inc () @{ b++; @}
-1:   16:  return 0;
+------------------
--:   17:@}
+Foo<char>::inc():
-@end smallexample
+#####:    8:  void inc () @{ b++; @}
+------------------
+Foo<int>::inc():
+2:    8:  void inc () @{ b++; @}
+------------------
+-:    9:
+-:   10:  private:
+-:   11:  int b;
+-:   12:@};
+-:   13:
+-:   14:template class Foo<int>;
+-:   15:template class Foo<char>;
+-:   16:
+-:   17:int
+1:   18:main (void)
+-:   19:@{
+-:   20:  int i, total;
+1:   21:  Foo<int> counter;
+-:   22:
+1:   23:  counter.inc();
+1:   24:  counter.inc();
+1:   25:  total = 0;
+-:   26:
+11:   27:  for (i = 0; i < 10; i++)
+10:   28:    total += i;
+-:   29:
+1*:   30:  int v = total > 100 ? 1 : 2;
+-:   31:
+1:   32:  if (total != 45)
+#####:   33:    printf ("Failure\n");
+-:   34:  else
+1:   35:    printf ("Success\n");
+1:   36:  return 0;
+-:   37:@}
+@end smallexample
+Note that line 7 is shown in the report multiple times.  First occurrence
+presents total number of execution of the line and the next two belong
+to instances of class Foo constructors.  As you can also see, line 30 contains
+some unexecuted basic blocks and thus execution count has asterisk symbol.
 When you use the @option{-a} option, you will get individual block
 counts, and the output looks like this:
 @smallexample
--:    0:Source:tmp.c
+-:    0:Source:tmp.cpp
+-:    0:Working directory:/home/gcc/testcase
 -:    0:Graph:tmp.gcno
 -:    0:Data:tmp.gcda
 -:    0:Runs:1
 -:    0:Programs:1
 -:    1:#include <stdio.h>
 -:    2:
--:    3:int main (void)
+-:    3:template<class T>
-1:    4:@{
+-:    4:class Foo
-1:    4-block  0
+-:    5:@{
-1:    5:  int i, total;
+-:    6:  public:
--:    6:
+1*:    7:  Foo(): b (1000) @{@}
-1:    7:  total = 0;
+------------------
--:    8:
+Foo<char>::Foo():
-11:    9:  for (i = 0; i < 10; i++)
+#####:    7:  Foo(): b (1000) @{@}
-11:    9-block  0
+------------------
-10:   10:    total += i;
+Foo<int>::Foo():
-10:   10-block  0
+1:    7:  Foo(): b (1000) @{@}
--:   11:
+------------------
-1:   12:  if (total != 45)
+2*:    8:  void inc () @{ b++; @}
-1:   12-block  0
+------------------
-#####:   13:    printf ("Failure\n");
+Foo<char>::inc():
-$$$$$:   13-block  0
+#####:    8:  void inc () @{ b++; @}
--:   14:  else
+------------------
-1:   15:    printf ("Success\n");
+Foo<int>::inc():
-1:   15-block  0
+2:    8:  void inc () @{ b++; @}
-1:   16:  return 0;
+------------------
-1:   16-block  0
+-:    9:
--:   17:@}
+-:   10:  private:
+-:   11:  int b;
+-:   12:@};
+-:   13:
+-:   14:template class Foo<int>;
+-:   15:template class Foo<char>;
+-:   16:
+-:   17:int
+1:   18:main (void)
+-:   19:@{
+-:   20:  int i, total;
+1:   21:  Foo<int> counter;
+1:   21-block  0
+-:   22:
+1:   23:  counter.inc();
+1:   23-block  0
+1:   24:  counter.inc();
+1:   24-block  0
+1:   25:  total = 0;
+-:   26:
+11:   27:  for (i = 0; i < 10; i++)
+1:   27-block  0
+11:   27-block  1
+10:   28:    total += i;
+10:   28-block  0
+-:   29:
+1*:   30:  int v = total > 100 ? 1 : 2;
+1:   30-block  0
+%%%%%:   30-block  1
+1:   30-block  2
+-:   31:
+1:   32:  if (total != 45)
+1:   32-block  0
+#####:   33:    printf ("Failure\n");
+%%%%%:   33-block  0
+-:   34:  else
+1:   35:    printf ("Success\n");
+1:   35-block  0
+1:   36:  return 0;
+1:   36-block  0
+-:   37:@}
 @end smallexample
 In this mode, each basic block is only shown on one line -- the last
 line of the block.  A multi-line block will only contribute to the
 execution count of that last line, and other lines will not be shown
 block, the branch and call counts of the block will be shown, if the
 @option{-b} option is given.
 Because of the way GCC instruments calls, a call count can be shown
 after a line with no individual blocks.
-As you can see, line 13 contains a basic block that was not executed.
+As you can see, line 33 contains a basic block that was not executed.
 @need 450
 When you use the @option{-b} option, your output looks like this:
 @smallexample
-$ gcov -b tmp.c
+-:    0:Source:tmp.cpp
-File 'tmp.c'
+-:    0:Working directory:/home/gcc/testcase
-Lines executed:90.00% of 10
-Branches executed:80.00% of 5
-Taken at least once:80.00% of 5
-Calls executed:50.00% of 2
-Creating 'tmp.c.gcov'
-@end smallexample
-Here is a sample of a resulting @file{tmp.c.gcov} file:
-@smallexample
--:    0:Source:tmp.c
 -:    0:Graph:tmp.gcno
 -:    0:Data:tmp.gcda
 -:    0:Runs:1
 -:    0:Programs:1
 -:    1:#include <stdio.h>
 -:    2:
--:    3:int main (void)
+-:    3:template<class T>
-function main called 1 returned 1 blocks executed 75%
+-:    4:class Foo
-1:    4:@{
+-:    5:@{
-1:    5:  int i, total;
+-:    6:  public:
--:    6:
+1*:    7:  Foo(): b (1000) @{@}
-1:    7:  total = 0;
+------------------
--:    8:
+Foo<char>::Foo():
-11:    9:  for (i = 0; i < 10; i++)
+function Foo<char>::Foo() called 0 returned 0% blocks executed 0%
+#####:    7:  Foo(): b (1000) @{@}
+------------------
+Foo<int>::Foo():
+function Foo<int>::Foo() called 1 returned 100% blocks executed 100%
+1:    7:  Foo(): b (1000) @{@}
+------------------
+2*:    8:  void inc () @{ b++; @}
+------------------
+Foo<char>::inc():
+function Foo<char>::inc() called 0 returned 0% blocks executed 0%
+#####:    8:  void inc () @{ b++; @}
+------------------
+Foo<int>::inc():
+function Foo<int>::inc() called 2 returned 100% blocks executed 100%
+2:    8:  void inc () @{ b++; @}
+------------------
+-:    9:
+-:   10:  private:
+-:   11:  int b;
+-:   12:@};
+-:   13:
+-:   14:template class Foo<int>;
+-:   15:template class Foo<char>;
+-:   16:
+-:   17:int
+function main called 1 returned 100% blocks executed 81%
+1:   18:main (void)
+-:   19:@{
+-:   20:  int i, total;
+1:   21:  Foo<int> counter;
+call    0 returned 100%
+branch  1 taken 100% (fallthrough)
+branch  2 taken 0% (throw)
+-:   22:
+1:   23:  counter.inc();
+call    0 returned 100%
+branch  1 taken 100% (fallthrough)
+branch  2 taken 0% (throw)
+1:   24:  counter.inc();
+call    0 returned 100%
+branch  1 taken 100% (fallthrough)
+branch  2 taken 0% (throw)
+1:   25:  total = 0;
+-:   26:
+11:   27:  for (i = 0; i < 10; i++)
 branch  0 taken 91% (fallthrough)
 branch  1 taken 9%
-10:   10:    total += i;
+10:   28:    total += i;
--:   11:
+-:   29:
-1:   12:  if (total != 45)
+1*:   30:  int v = total > 100 ? 1 : 2;
 branch  0 taken 0% (fallthrough)
 branch  1 taken 100%
-#####:   13:    printf ("Failure\n");
+-:   31:
+1:   32:  if (total != 45)
+branch  0 taken 0% (fallthrough)
+branch  1 taken 100%
+#####:   33:    printf ("Failure\n");
 call    0 never executed
--:   14:  else
+branch  1 never executed
-1:   15:    printf ("Success\n");
+branch  2 never executed
-call    0 called 1 returned 100%
+-:   34:  else
-1:   16:  return 0;
+1:   35:    printf ("Success\n");
--:   17:@}
+call    0 returned 100%
+branch  1 taken 100% (fallthrough)
+branch  2 taken 0% (throw)
+1:   36:  return 0;
+-:   37:@}
 @end smallexample
 For each function, a line is printed showing how many times the function
 is called, how many times it returns and what percentage of the
 function's blocks were executed.
 collected at that point to be dumped to @file{.gcda} output files.
 Instrumented applications use a static destructor with priority 99
 to invoke the @code{__gcov_dump} function. Thus @code{__gcov_dump}
 is executed after all user defined static destructors,
 as well as handlers registered with @code{atexit}.
+If an executable loads a dynamic shared object via dlopen functionality,
+@option{-Wl,--dynamic-list-data} is needed to dump all profile data.
+Profiling run-time library reports various errors related to profile
+manipulation and profile saving.  Errors are printed into standard error output
+or @samp{GCOV_ERROR_FILE} file, if environment variable is used.
+In order to terminate immediately after an errors occurs
+set @samp{GCOV_EXIT_AT_ERROR} environment variable.
+That can help users to find profile clashing which leads
+to a misleading profile.
 @c man end
 @node Gcov Data Files
 @section Brief Description of @command{gcov} Data Files
 object files built with the GCC @option{-fprofile-arcs} option is executed.
 A separate @file{.gcda} file is created for each object file compiled with
 this option.  It contains arc transition counts, value profile counts, and
 some summary information.
-The full details of the file format is specified in @file{gcov-io.h},
+It is not recommended to access the coverage files directly.
-and functions provided in that header file should be used to access the
+Consumers should use the intermediate format that is provided
-coverage files.
+by @command{gcov} tool via @option{--intermediate-format} option.
 @node Cross-profiling
 @section Data File Relocation to Support Cross-Profiling
 Running the program will cause profile output to be generated.  For each

Mercurial > hg > CbC > CbC_gcc

comparison gcc/doc/gcov.texi @ 131:84e7813d76e9