\input texinfo @c -*-texinfo-*-
@setfilename gprof.info
+@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001
+@c Free Software Foundation, Inc.
@settitle GNU gprof
@setchapternewpage odd
@ifinfo
This file documents the gprof profiler of the GNU system.
-Copyright (C) 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.
+@c man begin COPYRIGHT
+Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001 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
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, with no Front-Cover Texts, and with no
- Back-Cover Texts. A copy of the license is included in the
- section entitled "GNU Free Documentation License".
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts. A copy of the license is included in the
+section entitled "GNU Free Documentation License".
+
+@c man end
@ignore
Permission is granted to process this file through Tex and print the
@end titlepage
-@ifinfo
+@ifnottex
@node Top
@top Profiling a Program: Where Does It Spend Its Time?
* Details:: Details of how profiling is done
* GNU Free Documentation License:: GNU Free Documentation License
@end menu
-@end ifinfo
+@end ifnottex
@node Introduction
@chapter Introduction to Profiling
+@ifset man
+@c man title gprof display call graph profile data
+
+@smallexample
+@c man begin SYNOPSIS
+gprof [ -[abcDhilLsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ]
+ [ -I @var{dirs} ] [ -d[@var{num}] ] [ -k @var{from/to} ]
+ [ -m @var{min-count} ] [ -t @var{table-length} ]
+ [ --[no-]annotated-source[=@var{name}] ]
+ [ --[no-]exec-counts[=@var{name}] ]
+ [ --[no-]flat-profile[=@var{name}] ] [ --[no-]graph[=@var{name}] ]
+ [ --[no-]time=@var{name}] [ --all-lines ] [ --brief ]
+ [ --debug[=@var{level}] ] [ --function-ordering ]
+ [ --file-ordering ] [ --directory-path=@var{dirs} ]
+ [ --display-unused-functions ] [ --file-format=@var{name} ]
+ [ --file-info ] [ --help ] [ --line ] [ --min-count=@var{n} ]
+ [ --no-static ] [ --print-path ] [ --separate-files ]
+ [ --static-call-graph ] [ --sum ] [ --table-length=@var{len} ]
+ [ --traditional ] [ --version ] [ --width=@var{n} ]
+ [ --ignore-non-functions ] [ --demangle[=@var{STYLE}] ]
+ [ --no-demangle ] [ @var{image-file} ] [ @var{profile-file} @dots{} ]
+@c man end
+@end smallexample
+
+@c man begin DESCRIPTION
+@code{gprof} produces an execution profile of C, Pascal, or Fortran77
+programs. The effect of called routines is incorporated in the profile
+of each caller. The profile data is taken from the call graph profile file
+(@file{gmon.out} default) which is created by programs
+that are compiled with the @samp{-pg} option of
+@code{cc}, @code{pc}, and @code{f77}.
+The @samp{-pg} option also links in versions of the library routines
+that are compiled for profiling. @code{Gprof} reads the given object
+file (the default is @code{a.out}) and establishes the relation between
+its symbol table and the call graph profile from @file{gmon.out}.
+If more than one profile file is specified, the @code{gprof}
+output shows the sum of the profile information in the given profile files.
+
+@code{Gprof} calculates the amount of time spent in each routine.
+Next, these times are propagated along the edges of the call graph.
+Cycles are discovered, and calls into a cycle are made to share the time
+of the cycle.
+
+@c man end
+
+@c man begin BUGS
+The granularity of the sampling is shown, but remains
+statistical at best.
+We assume that the time for each execution of a function
+can be expressed by the total time for the function divided
+by the number of times the function is called.
+Thus the time propagated along the call graph arcs to the function's
+parents is directly proportional to the number of times that
+arc is traversed.
+
+Parents that are not themselves profiled will have the time of
+their profiled children propagated to them, but they will appear
+to be spontaneously invoked in the call graph listing, and will
+not have their time propagated further.
+Similarly, signal catchers, even though profiled, will appear
+to be spontaneous (although for more obscure reasons).
+Any profiled children of signal catchers should have their times
+propagated properly, unless the signal catcher was invoked during
+the execution of the profiling routine, in which case all is lost.
+
+The profiled program must call @code{exit}(2)
+or return normally for the profiling information to be saved
+in the @file{gmon.out} file.
+@c man end
+
+@c man begin FILES
+@table @code
+@item @file{a.out}
+the namelist and text space.
+@item @file{gmon.out}
+dynamic call graph and profile.
+@item @file{gmon.sum}
+summarized dynamic call graph and profile.
+@end table
+@c man end
+
+@c man begin SEEALSO
+monitor(3), profil(2), cc(1), prof(1), and the Info entry for @file{gprof}.
+
+``An Execution Profiler for Modular Programs'',
+by S. Graham, P. Kessler, M. McKusick;
+Software - Practice and Experience,
+Vol. 13, pp. 671-685, 1983.
+
+``gprof: A Call Graph Execution Profiler'',
+by S. Graham, P. Kessler, M. McKusick;
+Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
+SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, June 1982.
+@c man end
+@end ifset
+
Profiling allows you to learn where your program spent its time and which
functions called which other functions while it was executing. This
information can show you which pieces of your program are slower than you
The next three chapters explain these steps in greater detail.
+@c man begin DESCRIPTION
+
Several forms of output are available from the analysis.
The @dfn{flat profile} shows how much time your program spent in each function,
The @dfn{annotated source} listing is a copy of the program's
source code, labeled with the number of times each line of the
program was executed. @xref{Annotated Source}.
+@c man end
To better understand how profiling works, you may wish to read
a description of its implementation.
counts didn't get written into @file{gmon.out}.
The Perl script @code{bbconv.pl}, included with the @code{gprof}
source distribution, will convert a @file{bb.out} file into
-a format readable by @code{gprof}.
+a format readable by @code{gprof}. Invoke it like this:
+
+@smallexample
+bbconv.pl < bb.out > @var{bh-data}
+@end smallexample
+
+This translates the information in @file{bb.out} into a form that
+@code{gprof} can understand. But you still need to tell @code{gprof}
+about the existence of this translated information. To do that, include
+@var{bb-data} on the @code{gprof} command line, @emph{along with
+@file{gmon.out}}, like this:
+
+@smallexample
+gprof @var{options} @var{executable-file} gmon.out @var{bb-data} [@var{yet-more-profile-data-files}@dots{}] [> @var{outfile}]
+@end smallexample
@node Invoking
@chapter @code{gprof} Command Summary
@node Output Options,Analysis Options,,Invoking
@section Output Options
+@c man begin OPTIONS
These options specify which of several output formats
@code{gprof} should produce.
@end table
+@c man end
+
Note that only one function can be specified with each @code{-e},
@code{-E}, @code{-f} or @code{-F} option. To specify more than one
function, use multiple options. For example, this command:
The new file format is defined in header file @file{gmon_out.h}. It
consists of a header containing the magic cookie and a version number,
as well as some spare bytes available for future extensions. All data
-in a profile data file is in the native format of the host on which
-the profile was collected. @sc{gnu} @code{gprof} adapts automatically to the
-byte-order in use.
+in a profile data file is in the native format of the target for which
+the profile was collected. @sc{gnu} @code{gprof} adapts automatically
+to the byte-order in use.
In the new file format, the header is followed by a sequence of
records. Currently, there are three different record types: histogram
projects / deliverable / binutils-gdb.git / blobdiff