-@c Copyright (C) 1996, 1997, 1999, 2000, 2001,
-@c 2002, 2003, 2004 Free Software Foundation, Inc.
+@c Copyright (C) 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
+@c 2008, 2010 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, 1997, 1999, 2000, 2001, 2002, 2003
-Free Software Foundation, Inc.
+Copyright @copyright{} 1996, 1997, 1999, 2000, 2001, 2002, 2003, 2004,
+2005, 2008, 2010 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.2 or
+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
Free Software'', the Front-Cover texts being (a) (see below), and with
test code coverage in your programs.
@menu
-* Gcov Intro:: Introduction to gcov.
-* Invoking Gcov:: How to use gcov.
+* Gcov Intro:: Introduction to gcov.
+* Invoking Gcov:: How to use gcov.
* Gcov and Optimization:: Using gcov with GCC optimization.
* Gcov Data Files:: The files used by gcov.
+* Cross-profiling:: Data file relocation.
@end menu
@node Gcov Intro
@c man end
@node Invoking Gcov
-@section Invoking gcov
+@section Invoking @command{gcov}
@smallexample
-gcov @r{[}@var{options}@r{]} @var{sourcefile}
+gcov @r{[}@var{options}@r{]} @var{sourcefiles}
@end smallexample
@command{gcov} accepts the following options:
[@option{-l}|@option{--long-file-names}]
[@option{-p}|@option{--preserve-paths}]
[@option{-f}|@option{--function-summaries}]
- [@option{-o}|@option{--object-directory} @var{directory|file}] @var{sourcefile}
+ [@option{-o}|@option{--object-directory} @var{directory|file}] @var{sourcefiles}
[@option{-u}|@option{--unconditional-branches}]
+ [@option{-d}|@option{--display-progress}]
@c man end
@c man begin SEEALSO
gpl(7), gfdl(7), fsf-funding(7), gcc(1) and the Info entry for @file{gcc}.
@file{a.c}, then running @command{gcov} on the file @file{a.c} will produce
an output file called @file{a.c##x.h.gcov} instead of @file{x.h.gcov}.
This can be useful if @file{x.h} is included in multiple source
-files. If you uses the @samp{-p} option, both the including and
+files. If you use the @samp{-p} option, both the including and
included file names will be complete path names.
@item -p
@item -u
@itemx --unconditional-branches
-When branch counts are given, include those of unconditional branches.
+When branch probabilities are given, include those of unconditional branches.
Unconditional branches are normally not interesting.
+@item -d
+@itemx --display-progress
+Display the progress on the standard output.
+
@end table
@command{gcov} should be run with the current directory the same as that
Additional block information may succeed each line, when requested by
command line option. The @var{execution_count} is @samp{-} for lines
-containing no code and @samp{#####} for lines which were never
-executed. Some lines of information at the start have @var{line_number}
-of zero.
+containing no code and @samp{#####} for lines which were never executed.
+Some lines of information at the start have @var{line_number} of zero.
+
+The preamble lines are of the form
+
+@smallexample
+-:0:@var{tag}:@var{value}
+@end smallexample
+
+The ordering and number of these preamble lines will be augmented as
+@command{gcov} development progresses --- do not rely on them remaining
+unchanged. Use @var{tag} to locate a particular preamble line.
+
+The additional block information is of the form
+
+@smallexample
+@var{tag} @var{information}
+@end smallexample
+
+The @var{information} is human readable, but designed to be simple
+enough for machine parsing too.
When printing percentages, 0% and 100% are only printed when the values
are @emph{exactly} 0% and 100% respectively. Other values which would
-: 1:#include <stdio.h>
-: 2:
-: 3:int main (void)
-function main called 1 returned 1 blocks executed 75%
1: 4:@{
1: 5: int i, total;
-: 6:
-: 1:#include <stdio.h>
-: 2:
-: 3:int main (void)
-function main called 1 returned 1 blocks executed 75%
1: 4:@{
1: 4-block 0
1: 5: int i, total;
-: 17:@}
@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.
+
For each basic block, a line is printed after the last line of the basic
block describing the branch or call that ends the basic block. There can
be multiple branches and calls listed for a single source line if there
For a call, if it was executed at least once, then a percentage
indicating the number of times the call returned divided by the number
of times the call was executed will be printed. This will usually be
-100%, but may be less for functions call @code{exit} or @code{longjmp},
+100%, but may be less for functions that call @code{exit} or @code{longjmp},
and thus may not return every time they are called.
The execution counts are cumulative. If the example program were
The full details of the file format is specified in @file{gcov-io.h},
and functions provided in that header file should be used to access the
coverage files.
+
+@node Cross-profiling
+@section Data file relocation to support cross-profiling
+
+Running the program will cause profile output to be generated. For each
+source file compiled with @option{-fprofile-arcs}, an accompanying @file{.gcda}
+file will be placed in the object file directory. That implicitly requires
+running the program on the same system as it was built or having the same
+absolute directory structure on the target system. The program will try
+to create the needed directory structure, if it is not already present.
+
+To support cross-profiling, a program compiled with @option{-fprofile-arcs}
+can relocate the data files based on two environment variables:
+
+@itemize @bullet
+@item
+GCOV_PREFIX contains the prefix to add to the absolute paths
+in the object file. Prefix can be absolute, or relative. The
+default is no prefix.
+
+@item
+GCOV_PREFIX_STRIP indicates the how many initial directory names to strip off
+the hardwired absolute paths. Default value is 0.
+
+@emph{Note:} If GCOV_PREFIX_STRIP is set without GCOV_PREFIX is undefined,
+ then a relative path is made out of the hardwired absolute paths.
+@end itemize
+
+For example, if the object file @file{/user/build/foo.o} was built with
+@option{-fprofile-arcs}, the final executable will try to create the data file
+@file{/user/build/foo.gcda} when running on the target system. This will
+fail if the corresponding directory does not exist and it is unable to create
+it. This can be overcome by, for example, setting the environment as
+@samp{GCOV_PREFIX=/target/run} and @samp{GCOV_PREFIX_STRIP=1}. Such a
+setting will name the data file @file{/target/run/build/foo.gcda}.
+
+You must move the data files to the expected directory tree in order to
+use them for profile directed optimizations (@option{--use-profile}), or to
+use the @command{gcov} tool.
OSDN Git Service
