\input texinfo @c -*-texinfo-*-
@setfilename gprof.info
-@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001, 2002, 2003, 2004
+@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001, 2002, 2003,
+@c 2004, 2007
@c Free Software Foundation, Inc.
@settitle GNU gprof
@setchapternewpage odd
+@c man begin INCLUDE
+@include bfdver.texi
+@c man end
+
@ifinfo
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree. zoo@cygnus.com is developing this facility.
@end format
@end ifinfo
-@ifinfo
+@copying
This file documents the gprof profiler of the GNU system.
@c man begin COPYRIGHT
-Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001, 2003 Free Software Foundation, Inc.
+Copyright @copyright{} 1988, 92, 97, 98, 99, 2000, 2001, 2003, 2007 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.1
section entitled ``GNU Free Documentation License''.
@c man end
-
-@ignore
-Permission is granted to process this file through Tex and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-@end ifinfo
+@end copying
@finalout
@smallbook
@titlepage
@title GNU gprof
@subtitle The @sc{gnu} Profiler
+@ifset VERSION_PACKAGE
+@subtitle @value{VERSION_PACKAGE}
+@end ifset
+@subtitle Version @value{VERSION}
@author Jay Fenlason and Richard Stallman
@page
section entitled ``GNU Free Documentation License''.
@end titlepage
+@contents
@ifnottex
@node Top
execution time. We assume that you know how to write, compile, and
execute programs. @sc{gnu} @code{gprof} was written by Jay Fenlason.
+This manual is for @code{gprof}
+@ifset VERSION_PACKAGE
+@value{VERSION_PACKAGE}
+@end ifset
+version @value{VERSION}.
+
This document is distributed under the terms of the GNU Free
Documentation License. A copy of the license is included in the
section entitled ``GNU Free Documentation License''.
the functions will be blank), but will greatly reduce the usefulness of the
call graph.
-If you wish to perform line-by-line profiling,
-you will also need to specify the @samp{-g} option,
-instructing the compiler to insert debugging symbols into the program
-that match program addresses to source code lines.
-@xref{Line-by-line, ,Line-by-line Profiling}.
-
-In addition to the @samp{-pg} and @samp{-g} options, older versions of
-GCC required you to specify the @samp{-a} option when compiling in
-order to instrument it to perform basic-block counting. Newer
-versions do not require this option and will not accept it;
-basic-block counting is always enabled when @samp{-pg} is on.
-
-When basic-block counting is enabled, as the program runs
-it will count how many times it executed each branch of each @samp{if}
-statement, each iteration of each @samp{do} loop, etc. This will
-enable @code{gprof} to construct an annotated source code
-listing showing how many times each line of code was executed.
-
-It also worth noting that GCC supports a different profiling method
-which is enabled by the @samp{-fprofile-arcs}, @samp{-ftest-coverage}
-and @samp{-fprofile-values} switches. These switches do not produce
-data which is useful to @code{gprof} however, so they are not
-discussed further here. There is also the
-@samp{-finstrument-functions} switch which will cause GCC to insert
+If you wish to perform line-by-line profiling you should use the
+@code{gcov} tool instead of @code{gprof}. See that tool's manual or
+info pages for more details of how to do this.
+
+Note, older versions of @code{gcc} produce line-by-line profiling
+information that works with @code{gprof} rather than @code{gcov} so
+there is still support for displaying this kind of information in
+@code{gprof}. @xref{Line-by-line, ,Line-by-line Profiling}.
+
+It also worth noting that @code{gcc} implements a
+@samp{-finstrument-functions} command line option which will insert
calls to special user supplied instrumentation routines at the entry
and exit of every function in their program. This can be used to
implement an alternative profiling scheme.
@itemx --line
The @samp{-l} option enables line-by-line profiling, which causes
histogram hits to be charged to individual source code lines,
-instead of functions.
+instead of functions. This feature only works with programs compiled
+by older versions of the @code{gcc} compiler. Newer versions of
+@code{gcc} are designed to work with the @code{gcov} tool instead.
+
If the program was compiled with basic-block counting enabled,
this option will also identify how many times each line of
code was executed.
@code{gprof}'s @samp{-l} option causes the program to perform
@dfn{line-by-line} profiling. In this mode, histogram
samples are assigned not to functions, but to individual
-lines of source code. The program usually must be compiled
-with a @samp{-g} option, in addition to @samp{-pg}, in order
+lines of source code. This only works with programs compiled with
+older versions of the @code{gcc} compiler. Newer versions of @code{gcc}
+use a different program - @code{gcov} - to display line-by-line
+profiling information.
+
+With the older versions of @code{gcc} the program usually has to be
+compiled with a @samp{-g} option, in addition to @samp{-pg}, in order
to generate debugging symbols for tracking source code lines.
+Note, in much older versions of @code{gcc} the program had to be
+compiled with the @samp{-a} command line option as well.
The flat profile is the most useful output table
in line-by-line mode.
number of times it was called. You may also need to specify the
@samp{-I} option, if @code{gprof} can't find the source code files.
-Compiling with @samp{gcc @dots{} -g -pg -a} augments your program
-with basic-block counting code, in addition to function counting code.
-This enables @code{gprof} to determine how many times each line
-of code was executed.
+With older versions of @code{gcc} compiling with @samp{gcc @dots{} -g
+-pg -a} augments your program with basic-block counting code, in
+addition to function counting code. This enables @code{gprof} to
+determine how many times each line of code was executed. With newer
+versions of @code{gcc} support for displaying basic-block counts is
+provided by the @code{gcov} program.
+
For example, consider the following function, taken from gzip,
with line numbers added:
@item How do I find which lines in my program were executed the most times?
-Compile your program with basic-block counting enabled, run it, then
-use the following pipeline:
-
-@example
-gprof -l -C @var{objfile} | sort -k 3 -n -r
-@end example
-
-This listing will show you the lines in your code executed most often,
-but not necessarily those that consumed the most time.
+Use the @code{gcov} program.
@item How do I find which lines in my program called a particular function?
For the first histogram record, allocate a memory array to hold
all the bins, and read them in.
When multiple profile data files (or files with multiple histogram
-records) are read, the starting address, ending address, number
-of bins and sampling rate must match between the various histograms,
-or a fatal error will result.
-If everything matches, just sum the additional histograms into
-the existing in-memory array.
+records) are read, the memory ranges of each pair of histogram records
+must be either equal, or non-overlapping. For each pair of histogram
+records, the resolution (memory region size divided by the number of
+bins) must be the same. The time unit must be the same for all
+histogram records. If the above containts are met, all histograms
+for the same memory range are merged.
As each call graph record is read (@code{call_graph.c:@-cg_read_rec}),
the parent and child addresses
free software license, such as the GNU General Public License,
to permit their use in free software.
-@contents
@bye
NEEDS AN INDEX
projects / deliverable / binutils-gdb.git / blobdiff