2583 lines
108 KiB
Plaintext
2583 lines
108 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@setfilename gprof.info
|
|
@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.
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* gprof: (gprof). Profiling your program's execution
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
@end ifinfo
|
|
|
|
@copying
|
|
This file documents the gprof profiler of the GNU system.
|
|
|
|
@c man begin COPYRIGHT
|
|
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
|
|
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
|
|
@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
|
|
|
|
This manual describes the @sc{gnu} profiler, @code{gprof}, and how you
|
|
can use it to determine which parts of a program are taking most of the
|
|
execution time. We assume that you know how to write, compile, and
|
|
execute programs. @sc{gnu} @code{gprof} was written by Jay Fenlason.
|
|
Eric S. Raymond made some minor corrections and additions in 2003.
|
|
|
|
@vskip 0pt plus 1filll
|
|
Copyright @copyright{} 1988, 92, 97, 98, 99, 2000, 2003 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''.
|
|
|
|
@end titlepage
|
|
@contents
|
|
|
|
@ifnottex
|
|
@node Top
|
|
@top Profiling a Program: Where Does It Spend Its Time?
|
|
|
|
This manual describes the @sc{gnu} profiler, @code{gprof}, and how you
|
|
can use it to determine which parts of a program are taking most of the
|
|
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''.
|
|
|
|
@menu
|
|
* Introduction:: What profiling means, and why it is useful.
|
|
|
|
* Compiling:: How to compile your program for profiling.
|
|
* Executing:: Executing your program to generate profile data
|
|
* Invoking:: How to run @code{gprof}, and its options
|
|
|
|
* Output:: Interpreting @code{gprof}'s output
|
|
|
|
* Inaccuracy:: Potential problems you should be aware of
|
|
* How do I?:: Answers to common questions
|
|
* Incompatibilities:: (between @sc{gnu} @code{gprof} and Unix @code{gprof}.)
|
|
* Details:: Details of how profiling is done
|
|
* GNU Free Documentation License:: GNU Free Documentation License
|
|
@end menu
|
|
@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 [ -[abcDhilLrsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ]
|
|
[ -I @var{dirs} ] [ -d[@var{num}] ] [ -k @var{from/to} ]
|
|
[ -m @var{min-count} ] [ -R @var{map_file} ] [ -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 @var{map_file} ] [ --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
|
|
expected, and might be candidates for rewriting to make your program
|
|
execute faster. It can also tell you which functions are being called more
|
|
or less often than you expected. This may help you spot bugs that had
|
|
otherwise been unnoticed.
|
|
|
|
Since the profiler uses information collected during the actual execution
|
|
of your program, it can be used on programs that are too large or too
|
|
complex to analyze by reading the source. However, how your program is run
|
|
will affect the information that shows up in the profile data. If you
|
|
don't use some feature of your program while it is being profiled, no
|
|
profile information will be generated for that feature.
|
|
|
|
Profiling has several steps:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
You must compile and link your program with profiling enabled.
|
|
@xref{Compiling, ,Compiling a Program for Profiling}.
|
|
|
|
@item
|
|
You must execute your program to generate a profile data file.
|
|
@xref{Executing, ,Executing the Program}.
|
|
|
|
@item
|
|
You must run @code{gprof} to analyze the profile data.
|
|
@xref{Invoking, ,@code{gprof} Command Summary}.
|
|
@end itemize
|
|
|
|
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,
|
|
and how many times that function was called. If you simply want to know
|
|
which functions burn most of the cycles, it is stated concisely here.
|
|
@xref{Flat Profile, ,The Flat Profile}.
|
|
|
|
The @dfn{call graph} shows, for each function, which functions called it, which
|
|
other functions it called, and how many times. There is also an estimate
|
|
of how much time was spent in the subroutines of each function. This can
|
|
suggest places where you might try to eliminate function calls that use a
|
|
lot of time. @xref{Call Graph, ,The Call Graph}.
|
|
|
|
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, ,The Annotated Source
|
|
Listing}.
|
|
@c man end
|
|
|
|
To better understand how profiling works, you may wish to read
|
|
a description of its implementation.
|
|
@xref{Implementation, ,Implementation of Profiling}.
|
|
|
|
@node Compiling
|
|
@chapter Compiling a Program for Profiling
|
|
|
|
The first step in generating profile information for your program is
|
|
to compile and link it with profiling enabled.
|
|
|
|
To compile a source file for profiling, specify the @samp{-pg} option when
|
|
you run the compiler. (This is in addition to the options you normally
|
|
use.)
|
|
|
|
To link the program for profiling, if you use a compiler such as @code{cc}
|
|
to do the linking, simply specify @samp{-pg} in addition to your usual
|
|
options. The same option, @samp{-pg}, alters either compilation or linking
|
|
to do what is necessary for profiling. Here are examples:
|
|
|
|
@example
|
|
cc -g -c myprog.c utils.c -pg
|
|
cc -o myprog myprog.o utils.o -pg
|
|
@end example
|
|
|
|
The @samp{-pg} option also works with a command that both compiles and links:
|
|
|
|
@example
|
|
cc -o myprog myprog.c utils.c -g -pg
|
|
@end example
|
|
|
|
Note: The @samp{-pg} option must be part of your compilation options
|
|
as well as your link options. If it is not then no call-graph data
|
|
will be gathered and when you run @code{gprof} you will get an error
|
|
message like this:
|
|
|
|
@example
|
|
gprof: gmon.out file is missing call-graph data
|
|
@end example
|
|
|
|
If you add the @samp{-Q} switch to suppress the printing of the call
|
|
graph data you will still be able to see the time samples:
|
|
|
|
@example
|
|
Flat profile:
|
|
|
|
Each sample counts as 0.01 seconds.
|
|
% cumulative self self total
|
|
time seconds seconds calls Ts/call Ts/call name
|
|
44.12 0.07 0.07 zazLoop
|
|
35.29 0.14 0.06 main
|
|
20.59 0.17 0.04 bazMillion
|
|
@end example
|
|
|
|
If you run the linker @code{ld} directly instead of through a compiler
|
|
such as @code{cc}, you may have to specify a profiling startup file
|
|
@file{gcrt0.o} as the first input file instead of the usual startup
|
|
file @file{crt0.o}. In addition, you would probably want to
|
|
specify the profiling C library, @file{libc_p.a}, by writing
|
|
@samp{-lc_p} instead of the usual @samp{-lc}. This is not absolutely
|
|
necessary, but doing this gives you number-of-calls information for
|
|
standard library functions such as @code{read} and @code{open}. For
|
|
example:
|
|
|
|
@example
|
|
ld -o myprog /lib/gcrt0.o myprog.o utils.o -lc_p
|
|
@end example
|
|
|
|
If you compile only some of the modules of the program with @samp{-pg}, you
|
|
can still profile the program, but you won't get complete information about
|
|
the modules that were compiled without @samp{-pg}. The only information
|
|
you get for the functions in those modules is the total time spent in them;
|
|
there is no record of how many times they were called, or from where. This
|
|
will not affect the flat profile (except that the @code{calls} field for
|
|
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
|
|
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.
|
|
|
|
@node Executing
|
|
@chapter Executing the Program
|
|
|
|
Once the program is compiled for profiling, you must run it in order to
|
|
generate the information that @code{gprof} needs. Simply run the program
|
|
as usual, using the normal arguments, file names, etc. The program should
|
|
run normally, producing the same output as usual. It will, however, run
|
|
somewhat slower than normal because of the time spent collecting and
|
|
writing the profile data.
|
|
|
|
The way you run the program---the arguments and input that you give
|
|
it---may have a dramatic effect on what the profile information shows. The
|
|
profile data will describe the parts of the program that were activated for
|
|
the particular input you use. For example, if the first command you give
|
|
to your program is to quit, the profile data will show the time used in
|
|
initialization and in cleanup, but not much else.
|
|
|
|
Your program will write the profile data into a file called @file{gmon.out}
|
|
just before exiting. If there is already a file called @file{gmon.out},
|
|
its contents are overwritten. There is currently no way to tell the
|
|
program to write the profile data under a different name, but you can rename
|
|
the file afterwards if you are concerned that it may be overwritten.
|
|
|
|
In order to write the @file{gmon.out} file properly, your program must exit
|
|
normally: by returning from @code{main} or by calling @code{exit}. Calling
|
|
the low-level function @code{_exit} does not write the profile data, and
|
|
neither does abnormal termination due to an unhandled signal.
|
|
|
|
The @file{gmon.out} file is written in the program's @emph{current working
|
|
directory} at the time it exits. This means that if your program calls
|
|
@code{chdir}, the @file{gmon.out} file will be left in the last directory
|
|
your program @code{chdir}'d to. If you don't have permission to write in
|
|
this directory, the file is not written, and you will get an error message.
|
|
|
|
Older versions of the @sc{gnu} profiling library may also write a file
|
|
called @file{bb.out}. This file, if present, contains an human-readable
|
|
listing of the basic-block execution counts. Unfortunately, the
|
|
appearance of a human-readable @file{bb.out} means the basic-block
|
|
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}. 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
|
|
|
|
After you have a profile data file @file{gmon.out}, you can run @code{gprof}
|
|
to interpret the information in it. The @code{gprof} program prints a
|
|
flat profile and a call graph on standard output. Typically you would
|
|
redirect the output of @code{gprof} into a file with @samp{>}.
|
|
|
|
You run @code{gprof} like this:
|
|
|
|
@smallexample
|
|
gprof @var{options} [@var{executable-file} [@var{profile-data-files}@dots{}]] [> @var{outfile}]
|
|
@end smallexample
|
|
|
|
@noindent
|
|
Here square-brackets indicate optional arguments.
|
|
|
|
If you omit the executable file name, the file @file{a.out} is used. If
|
|
you give no profile data file name, the file @file{gmon.out} is used. If
|
|
any file is not in the proper format, or if the profile data file does not
|
|
appear to belong to the executable file, an error message is printed.
|
|
|
|
You can give more than one profile data file by entering all their names
|
|
after the executable file name; then the statistics in all the data files
|
|
are summed together.
|
|
|
|
The order of these options does not matter.
|
|
|
|
@menu
|
|
* Output Options:: Controlling @code{gprof}'s output style
|
|
* Analysis Options:: Controlling how @code{gprof} analyzes its data
|
|
* Miscellaneous Options::
|
|
* Deprecated Options:: Options you no longer need to use, but which
|
|
have been retained for compatibility
|
|
* Symspecs:: Specifying functions to include or exclude
|
|
@end menu
|
|
|
|
@node Output Options
|
|
@section Output Options
|
|
|
|
@c man begin OPTIONS
|
|
These options specify which of several output formats
|
|
@code{gprof} should produce.
|
|
|
|
Many of these options take an optional @dfn{symspec} to specify
|
|
functions to be included or excluded. These options can be
|
|
specified multiple times, with different symspecs, to include
|
|
or exclude sets of symbols. @xref{Symspecs, ,Symspecs}.
|
|
|
|
Specifying any of these options overrides the default (@samp{-p -q}),
|
|
which prints a flat profile and call graph analysis
|
|
for all functions.
|
|
|
|
@table @code
|
|
|
|
@item -A[@var{symspec}]
|
|
@itemx --annotated-source[=@var{symspec}]
|
|
The @samp{-A} option causes @code{gprof} to print annotated source code.
|
|
If @var{symspec} is specified, print output only for matching symbols.
|
|
@xref{Annotated Source, ,The Annotated Source Listing}.
|
|
|
|
@item -b
|
|
@itemx --brief
|
|
If the @samp{-b} option is given, @code{gprof} doesn't print the
|
|
verbose blurbs that try to explain the meaning of all of the fields in
|
|
the tables. This is useful if you intend to print out the output, or
|
|
are tired of seeing the blurbs.
|
|
|
|
@item -C[@var{symspec}]
|
|
@itemx --exec-counts[=@var{symspec}]
|
|
The @samp{-C} option causes @code{gprof} to
|
|
print a tally of functions and the number of times each was called.
|
|
If @var{symspec} is specified, print tally only for matching symbols.
|
|
|
|
If the profile data file contains basic-block count records, specifying
|
|
the @samp{-l} option, along with @samp{-C}, will cause basic-block
|
|
execution counts to be tallied and displayed.
|
|
|
|
@item -i
|
|
@itemx --file-info
|
|
The @samp{-i} option causes @code{gprof} to display summary information
|
|
about the profile data file(s) and then exit. The number of histogram,
|
|
call graph, and basic-block count records is displayed.
|
|
|
|
@item -I @var{dirs}
|
|
@itemx --directory-path=@var{dirs}
|
|
The @samp{-I} option specifies a list of search directories in
|
|
which to find source files. Environment variable @var{GPROF_PATH}
|
|
can also be used to convey this information.
|
|
Used mostly for annotated source output.
|
|
|
|
@item -J[@var{symspec}]
|
|
@itemx --no-annotated-source[=@var{symspec}]
|
|
The @samp{-J} option causes @code{gprof} not to
|
|
print annotated source code.
|
|
If @var{symspec} is specified, @code{gprof} prints annotated source,
|
|
but excludes matching symbols.
|
|
|
|
@item -L
|
|
@itemx --print-path
|
|
Normally, source filenames are printed with the path
|
|
component suppressed. The @samp{-L} option causes @code{gprof}
|
|
to print the full pathname of
|
|
source filenames, which is determined
|
|
from symbolic debugging information in the image file
|
|
and is relative to the directory in which the compiler
|
|
was invoked.
|
|
|
|
@item -p[@var{symspec}]
|
|
@itemx --flat-profile[=@var{symspec}]
|
|
The @samp{-p} option causes @code{gprof} to print a flat profile.
|
|
If @var{symspec} is specified, print flat profile only for matching symbols.
|
|
@xref{Flat Profile, ,The Flat Profile}.
|
|
|
|
@item -P[@var{symspec}]
|
|
@itemx --no-flat-profile[=@var{symspec}]
|
|
The @samp{-P} option causes @code{gprof} to suppress printing a flat profile.
|
|
If @var{symspec} is specified, @code{gprof} prints a flat profile,
|
|
but excludes matching symbols.
|
|
|
|
@item -q[@var{symspec}]
|
|
@itemx --graph[=@var{symspec}]
|
|
The @samp{-q} option causes @code{gprof} to print the call graph analysis.
|
|
If @var{symspec} is specified, print call graph only for matching symbols
|
|
and their children.
|
|
@xref{Call Graph, ,The Call Graph}.
|
|
|
|
@item -Q[@var{symspec}]
|
|
@itemx --no-graph[=@var{symspec}]
|
|
The @samp{-Q} option causes @code{gprof} to suppress printing the
|
|
call graph.
|
|
If @var{symspec} is specified, @code{gprof} prints a call graph,
|
|
but excludes matching symbols.
|
|
|
|
@item -t
|
|
@itemx --table-length=@var{num}
|
|
The @samp{-t} option causes the @var{num} most active source lines in
|
|
each source file to be listed when source annotation is enabled. The
|
|
default is 10.
|
|
|
|
@item -y
|
|
@itemx --separate-files
|
|
This option affects annotated source output only.
|
|
Normally, @code{gprof} prints annotated source files
|
|
to standard-output. If this option is specified,
|
|
annotated source for a file named @file{path/@var{filename}}
|
|
is generated in the file @file{@var{filename}-ann}. If the underlying
|
|
file system would truncate @file{@var{filename}-ann} so that it
|
|
overwrites the original @file{@var{filename}}, @code{gprof} generates
|
|
annotated source in the file @file{@var{filename}.ann} instead (if the
|
|
original file name has an extension, that extension is @emph{replaced}
|
|
with @file{.ann}).
|
|
|
|
@item -Z[@var{symspec}]
|
|
@itemx --no-exec-counts[=@var{symspec}]
|
|
The @samp{-Z} option causes @code{gprof} not to
|
|
print a tally of functions and the number of times each was called.
|
|
If @var{symspec} is specified, print tally, but exclude matching symbols.
|
|
|
|
@item -r
|
|
@itemx --function-ordering
|
|
The @samp{--function-ordering} option causes @code{gprof} to print a
|
|
suggested function ordering for the program based on profiling data.
|
|
This option suggests an ordering which may improve paging, tlb and
|
|
cache behavior for the program on systems which support arbitrary
|
|
ordering of functions in an executable.
|
|
|
|
The exact details of how to force the linker to place functions
|
|
in a particular order is system dependent and out of the scope of this
|
|
manual.
|
|
|
|
@item -R @var{map_file}
|
|
@itemx --file-ordering @var{map_file}
|
|
The @samp{--file-ordering} option causes @code{gprof} to print a
|
|
suggested .o link line ordering for the program based on profiling data.
|
|
This option suggests an ordering which may improve paging, tlb and
|
|
cache behavior for the program on systems which do not support arbitrary
|
|
ordering of functions in an executable.
|
|
|
|
Use of the @samp{-a} argument is highly recommended with this option.
|
|
|
|
The @var{map_file} argument is a pathname to a file which provides
|
|
function name to object file mappings. The format of the file is similar to
|
|
the output of the program @code{nm}.
|
|
|
|
@smallexample
|
|
@group
|
|
c-parse.o:00000000 T yyparse
|
|
c-parse.o:00000004 C yyerrflag
|
|
c-lang.o:00000000 T maybe_objc_method_name
|
|
c-lang.o:00000000 T print_lang_statistics
|
|
c-lang.o:00000000 T recognize_objc_keyword
|
|
c-decl.o:00000000 T print_lang_identifier
|
|
c-decl.o:00000000 T print_lang_type
|
|
@dots{}
|
|
|
|
@end group
|
|
@end smallexample
|
|
|
|
To create a @var{map_file} with @sc{gnu} @code{nm}, type a command like
|
|
@kbd{nm --extern-only --defined-only -v --print-file-name program-name}.
|
|
|
|
@item -T
|
|
@itemx --traditional
|
|
The @samp{-T} option causes @code{gprof} to print its output in
|
|
``traditional'' BSD style.
|
|
|
|
@item -w @var{width}
|
|
@itemx --width=@var{width}
|
|
Sets width of output lines to @var{width}.
|
|
Currently only used when printing the function index at the bottom
|
|
of the call graph.
|
|
|
|
@item -x
|
|
@itemx --all-lines
|
|
This option affects annotated source output only.
|
|
By default, only the lines at the beginning of a basic-block
|
|
are annotated. If this option is specified, every line in
|
|
a basic-block is annotated by repeating the annotation for the
|
|
first line. This behavior is similar to @code{tcov}'s @samp{-a}.
|
|
|
|
@item --demangle[=@var{style}]
|
|
@itemx --no-demangle
|
|
These options control whether C++ symbol names should be demangled when
|
|
printing output. The default is to demangle symbols. The
|
|
@code{--no-demangle} option may be used to turn off demangling. Different
|
|
compilers have different mangling styles. The optional demangling style
|
|
argument can be used to choose an appropriate demangling style for your
|
|
compiler.
|
|
@end table
|
|
|
|
@node Analysis Options
|
|
@section Analysis Options
|
|
|
|
@table @code
|
|
|
|
@item -a
|
|
@itemx --no-static
|
|
The @samp{-a} option causes @code{gprof} to suppress the printing of
|
|
statically declared (private) functions. (These are functions whose
|
|
names are not listed as global, and which are not visible outside the
|
|
file/function/block where they were defined.) Time spent in these
|
|
functions, calls to/from them, etc., will all be attributed to the
|
|
function that was loaded directly before it in the executable file.
|
|
@c This is compatible with Unix @code{gprof}, but a bad idea.
|
|
This option affects both the flat profile and the call graph.
|
|
|
|
@item -c
|
|
@itemx --static-call-graph
|
|
The @samp{-c} option causes the call graph of the program to be
|
|
augmented by a heuristic which examines the text space of the object
|
|
file and identifies function calls in the binary machine code.
|
|
Since normal call graph records are only generated when functions are
|
|
entered, this option identifies children that could have been called,
|
|
but never were. Calls to functions that were not compiled with
|
|
profiling enabled are also identified, but only if symbol table
|
|
entries are present for them.
|
|
Calls to dynamic library routines are typically @emph{not} found
|
|
by this option.
|
|
Parents or children identified via this heuristic
|
|
are indicated in the call graph with call counts of @samp{0}.
|
|
|
|
@item -D
|
|
@itemx --ignore-non-functions
|
|
The @samp{-D} option causes @code{gprof} to ignore symbols which
|
|
are not known to be functions. This option will give more accurate
|
|
profile data on systems where it is supported (Solaris and HPUX for
|
|
example).
|
|
|
|
@item -k @var{from}/@var{to}
|
|
The @samp{-k} option allows you to delete from the call graph any arcs from
|
|
symbols matching symspec @var{from} to those matching symspec @var{to}.
|
|
|
|
@item -l
|
|
@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.
|
|
If the program was compiled with basic-block counting enabled,
|
|
this option will also identify how many times each line of
|
|
code was executed.
|
|
While line-by-line profiling can help isolate where in a large function
|
|
a program is spending its time, it also significantly increases
|
|
the running time of @code{gprof}, and magnifies statistical
|
|
inaccuracies.
|
|
@xref{Sampling Error, ,Statistical Sampling Error}.
|
|
|
|
@item -m @var{num}
|
|
@itemx --min-count=@var{num}
|
|
This option affects execution count output only.
|
|
Symbols that are executed less than @var{num} times are suppressed.
|
|
|
|
@item -n@var{symspec}
|
|
@itemx --time=@var{symspec}
|
|
The @samp{-n} option causes @code{gprof}, in its call graph analysis,
|
|
to only propagate times for symbols matching @var{symspec}.
|
|
|
|
@item -N@var{symspec}
|
|
@itemx --no-time=@var{symspec}
|
|
The @samp{-n} option causes @code{gprof}, in its call graph analysis,
|
|
not to propagate times for symbols matching @var{symspec}.
|
|
|
|
@item -z
|
|
@itemx --display-unused-functions
|
|
If you give the @samp{-z} option, @code{gprof} will mention all
|
|
functions in the flat profile, even those that were never called, and
|
|
that had no time spent in them. This is useful in conjunction with the
|
|
@samp{-c} option for discovering which routines were never called.
|
|
|
|
@end table
|
|
|
|
@node Miscellaneous Options
|
|
@section Miscellaneous Options
|
|
|
|
@table @code
|
|
|
|
@item -d[@var{num}]
|
|
@itemx --debug[=@var{num}]
|
|
The @samp{-d @var{num}} option specifies debugging options.
|
|
If @var{num} is not specified, enable all debugging.
|
|
@xref{Debugging, ,Debugging @code{gprof}}.
|
|
|
|
@item -h
|
|
@itemx --help
|
|
The @samp{-h} option prints command line usage.
|
|
|
|
@item -O@var{name}
|
|
@itemx --file-format=@var{name}
|
|
Selects the format of the profile data files. Recognized formats are
|
|
@samp{auto} (the default), @samp{bsd}, @samp{4.4bsd}, @samp{magic}, and
|
|
@samp{prof} (not yet supported).
|
|
|
|
@item -s
|
|
@itemx --sum
|
|
The @samp{-s} option causes @code{gprof} to summarize the information
|
|
in the profile data files it read in, and write out a profile data
|
|
file called @file{gmon.sum}, which contains all the information from
|
|
the profile data files that @code{gprof} read in. The file @file{gmon.sum}
|
|
may be one of the specified input files; the effect of this is to
|
|
merge the data in the other input files into @file{gmon.sum}.
|
|
|
|
Eventually you can run @code{gprof} again without @samp{-s} to analyze the
|
|
cumulative data in the file @file{gmon.sum}.
|
|
|
|
@item -v
|
|
@itemx --version
|
|
The @samp{-v} flag causes @code{gprof} to print the current version
|
|
number, and then exit.
|
|
|
|
@end table
|
|
|
|
@node Deprecated Options
|
|
@section Deprecated Options
|
|
|
|
@table @code
|
|
|
|
These options have been replaced with newer versions that use symspecs.
|
|
|
|
@item -e @var{function_name}
|
|
The @samp{-e @var{function}} option tells @code{gprof} to not print
|
|
information about the function @var{function_name} (and its
|
|
children@dots{}) in the call graph. The function will still be listed
|
|
as a child of any functions that call it, but its index number will be
|
|
shown as @samp{[not printed]}. More than one @samp{-e} option may be
|
|
given; only one @var{function_name} may be indicated with each @samp{-e}
|
|
option.
|
|
|
|
@item -E @var{function_name}
|
|
The @code{-E @var{function}} option works like the @code{-e} option, but
|
|
time spent in the function (and children who were not called from
|
|
anywhere else), will not be used to compute the percentages-of-time for
|
|
the call graph. More than one @samp{-E} option may be given; only one
|
|
@var{function_name} may be indicated with each @samp{-E} option.
|
|
|
|
@item -f @var{function_name}
|
|
The @samp{-f @var{function}} option causes @code{gprof} to limit the
|
|
call graph to the function @var{function_name} and its children (and
|
|
their children@dots{}). More than one @samp{-f} option may be given;
|
|
only one @var{function_name} may be indicated with each @samp{-f}
|
|
option.
|
|
|
|
@item -F @var{function_name}
|
|
The @samp{-F @var{function}} option works like the @code{-f} option, but
|
|
only time spent in the function and its children (and their
|
|
children@dots{}) will be used to determine total-time and
|
|
percentages-of-time for the call graph. More than one @samp{-F} option
|
|
may be given; only one @var{function_name} may be indicated with each
|
|
@samp{-F} option. The @samp{-F} option overrides the @samp{-E} option.
|
|
|
|
@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:
|
|
|
|
@example
|
|
gprof -e boring -f foo -f bar myprogram > gprof.output
|
|
@end example
|
|
|
|
@noindent
|
|
lists in the call graph all functions that were reached from either
|
|
@code{foo} or @code{bar} and were not reachable from @code{boring}.
|
|
|
|
@node Symspecs
|
|
@section Symspecs
|
|
|
|
Many of the output options allow functions to be included or excluded
|
|
using @dfn{symspecs} (symbol specifications), which observe the
|
|
following syntax:
|
|
|
|
@example
|
|
filename_containing_a_dot
|
|
| funcname_not_containing_a_dot
|
|
| linenumber
|
|
| ( [ any_filename ] `:' ( any_funcname | linenumber ) )
|
|
@end example
|
|
|
|
Here are some sample symspecs:
|
|
|
|
@table @samp
|
|
@item main.c
|
|
Selects everything in file @file{main.c}---the
|
|
dot in the string tells @code{gprof} to interpret
|
|
the string as a filename, rather than as
|
|
a function name. To select a file whose
|
|
name does not contain a dot, a trailing colon
|
|
should be specified. For example, @samp{odd:} is
|
|
interpreted as the file named @file{odd}.
|
|
|
|
@item main
|
|
Selects all functions named @samp{main}.
|
|
|
|
Note that there may be multiple instances of the same function name
|
|
because some of the definitions may be local (i.e., static). Unless a
|
|
function name is unique in a program, you must use the colon notation
|
|
explained below to specify a function from a specific source file.
|
|
|
|
Sometimes, function names contain dots. In such cases, it is necessary
|
|
to add a leading colon to the name. For example, @samp{:.mul} selects
|
|
function @samp{.mul}.
|
|
|
|
In some object file formats, symbols have a leading underscore.
|
|
@code{gprof} will normally not print these underscores. When you name a
|
|
symbol in a symspec, you should type it exactly as @code{gprof} prints
|
|
it in its output. For example, if the compiler produces a symbol
|
|
@samp{_main} from your @code{main} function, @code{gprof} still prints
|
|
it as @samp{main} in its output, so you should use @samp{main} in
|
|
symspecs.
|
|
|
|
@item main.c:main
|
|
Selects function @samp{main} in file @file{main.c}.
|
|
|
|
@item main.c:134
|
|
Selects line 134 in file @file{main.c}.
|
|
@end table
|
|
|
|
@node Output
|
|
@chapter Interpreting @code{gprof}'s Output
|
|
|
|
@code{gprof} can produce several different output styles, the
|
|
most important of which are described below. The simplest output
|
|
styles (file information, execution count, and function and file ordering)
|
|
are not described here, but are documented with the respective options
|
|
that trigger them.
|
|
@xref{Output Options, ,Output Options}.
|
|
|
|
@menu
|
|
* Flat Profile:: The flat profile shows how much time was spent
|
|
executing directly in each function.
|
|
* Call Graph:: The call graph shows which functions called which
|
|
others, and how much time each function used
|
|
when its subroutine calls are included.
|
|
* Line-by-line:: @code{gprof} can analyze individual source code lines
|
|
* Annotated Source:: The annotated source listing displays source code
|
|
labeled with execution counts
|
|
@end menu
|
|
|
|
|
|
@node Flat Profile
|
|
@section The Flat Profile
|
|
@cindex flat profile
|
|
|
|
The @dfn{flat profile} shows the total amount of time your program
|
|
spent executing each function. Unless the @samp{-z} option is given,
|
|
functions with no apparent time spent in them, and no apparent calls
|
|
to them, are not mentioned. Note that if a function was not compiled
|
|
for profiling, and didn't run long enough to show up on the program
|
|
counter histogram, it will be indistinguishable from a function that
|
|
was never called.
|
|
|
|
This is part of a flat profile for a small program:
|
|
|
|
@smallexample
|
|
@group
|
|
Flat profile:
|
|
|
|
Each sample counts as 0.01 seconds.
|
|
% cumulative self self total
|
|
time seconds seconds calls ms/call ms/call name
|
|
33.34 0.02 0.02 7208 0.00 0.00 open
|
|
16.67 0.03 0.01 244 0.04 0.12 offtime
|
|
16.67 0.04 0.01 8 1.25 1.25 memccpy
|
|
16.67 0.05 0.01 7 1.43 1.43 write
|
|
16.67 0.06 0.01 mcount
|
|
0.00 0.06 0.00 236 0.00 0.00 tzset
|
|
0.00 0.06 0.00 192 0.00 0.00 tolower
|
|
0.00 0.06 0.00 47 0.00 0.00 strlen
|
|
0.00 0.06 0.00 45 0.00 0.00 strchr
|
|
0.00 0.06 0.00 1 0.00 50.00 main
|
|
0.00 0.06 0.00 1 0.00 0.00 memcpy
|
|
0.00 0.06 0.00 1 0.00 10.11 print
|
|
0.00 0.06 0.00 1 0.00 0.00 profil
|
|
0.00 0.06 0.00 1 0.00 50.00 report
|
|
@dots{}
|
|
@end group
|
|
@end smallexample
|
|
|
|
@noindent
|
|
The functions are sorted first by decreasing run-time spent in them,
|
|
then by decreasing number of calls, then alphabetically by name. The
|
|
functions @samp{mcount} and @samp{profil} are part of the profiling
|
|
apparatus and appear in every flat profile; their time gives a measure of
|
|
the amount of overhead due to profiling.
|
|
|
|
Just before the column headers, a statement appears indicating
|
|
how much time each sample counted as.
|
|
This @dfn{sampling period} estimates the margin of error in each of the time
|
|
figures. A time figure that is not much larger than this is not
|
|
reliable. In this example, each sample counted as 0.01 seconds,
|
|
suggesting a 100 Hz sampling rate.
|
|
The program's total execution time was 0.06
|
|
seconds, as indicated by the @samp{cumulative seconds} field. Since
|
|
each sample counted for 0.01 seconds, this means only six samples
|
|
were taken during the run. Two of the samples occurred while the
|
|
program was in the @samp{open} function, as indicated by the
|
|
@samp{self seconds} field. Each of the other four samples
|
|
occurred one each in @samp{offtime}, @samp{memccpy}, @samp{write},
|
|
and @samp{mcount}.
|
|
Since only six samples were taken, none of these values can
|
|
be regarded as particularly reliable.
|
|
In another run,
|
|
the @samp{self seconds} field for
|
|
@samp{mcount} might well be @samp{0.00} or @samp{0.02}.
|
|
@xref{Sampling Error, ,Statistical Sampling Error},
|
|
for a complete discussion.
|
|
|
|
The remaining functions in the listing (those whose
|
|
@samp{self seconds} field is @samp{0.00}) didn't appear
|
|
in the histogram samples at all. However, the call graph
|
|
indicated that they were called, so therefore they are listed,
|
|
sorted in decreasing order by the @samp{calls} field.
|
|
Clearly some time was spent executing these functions,
|
|
but the paucity of histogram samples prevents any
|
|
determination of how much time each took.
|
|
|
|
Here is what the fields in each line mean:
|
|
|
|
@table @code
|
|
@item % time
|
|
This is the percentage of the total execution time your program spent
|
|
in this function. These should all add up to 100%.
|
|
|
|
@item cumulative seconds
|
|
This is the cumulative total number of seconds the computer spent
|
|
executing this functions, plus the time spent in all the functions
|
|
above this one in this table.
|
|
|
|
@item self seconds
|
|
This is the number of seconds accounted for by this function alone.
|
|
The flat profile listing is sorted first by this number.
|
|
|
|
@item calls
|
|
This is the total number of times the function was called. If the
|
|
function was never called, or the number of times it was called cannot
|
|
be determined (probably because the function was not compiled with
|
|
profiling enabled), the @dfn{calls} field is blank.
|
|
|
|
@item self ms/call
|
|
This represents the average number of milliseconds spent in this
|
|
function per call, if this function is profiled. Otherwise, this field
|
|
is blank for this function.
|
|
|
|
@item total ms/call
|
|
This represents the average number of milliseconds spent in this
|
|
function and its descendants per call, if this function is profiled.
|
|
Otherwise, this field is blank for this function.
|
|
This is the only field in the flat profile that uses call graph analysis.
|
|
|
|
@item name
|
|
This is the name of the function. The flat profile is sorted by this
|
|
field alphabetically after the @dfn{self seconds} and @dfn{calls}
|
|
fields are sorted.
|
|
@end table
|
|
|
|
@node Call Graph
|
|
@section The Call Graph
|
|
@cindex call graph
|
|
|
|
The @dfn{call graph} shows how much time was spent in each function
|
|
and its children. From this information, you can find functions that,
|
|
while they themselves may not have used much time, called other
|
|
functions that did use unusual amounts of time.
|
|
|
|
Here is a sample call from a small program. This call came from the
|
|
same @code{gprof} run as the flat profile example in the previous
|
|
section.
|
|
|
|
@smallexample
|
|
@group
|
|
granularity: each sample hit covers 2 byte(s) for 20.00% of 0.05 seconds
|
|
|
|
index % time self children called name
|
|
<spontaneous>
|
|
[1] 100.0 0.00 0.05 start [1]
|
|
0.00 0.05 1/1 main [2]
|
|
0.00 0.00 1/2 on_exit [28]
|
|
0.00 0.00 1/1 exit [59]
|
|
-----------------------------------------------
|
|
0.00 0.05 1/1 start [1]
|
|
[2] 100.0 0.00 0.05 1 main [2]
|
|
0.00 0.05 1/1 report [3]
|
|
-----------------------------------------------
|
|
0.00 0.05 1/1 main [2]
|
|
[3] 100.0 0.00 0.05 1 report [3]
|
|
0.00 0.03 8/8 timelocal [6]
|
|
0.00 0.01 1/1 print [9]
|
|
0.00 0.01 9/9 fgets [12]
|
|
0.00 0.00 12/34 strncmp <cycle 1> [40]
|
|
0.00 0.00 8/8 lookup [20]
|
|
0.00 0.00 1/1 fopen [21]
|
|
0.00 0.00 8/8 chewtime [24]
|
|
0.00 0.00 8/16 skipspace [44]
|
|
-----------------------------------------------
|
|
[4] 59.8 0.01 0.02 8+472 <cycle 2 as a whole> [4]
|
|
0.01 0.02 244+260 offtime <cycle 2> [7]
|
|
0.00 0.00 236+1 tzset <cycle 2> [26]
|
|
-----------------------------------------------
|
|
@end group
|
|
@end smallexample
|
|
|
|
The lines full of dashes divide this table into @dfn{entries}, one for each
|
|
function. Each entry has one or more lines.
|
|
|
|
In each entry, the primary line is the one that starts with an index number
|
|
in square brackets. The end of this line says which function the entry is
|
|
for. The preceding lines in the entry describe the callers of this
|
|
function and the following lines describe its subroutines (also called
|
|
@dfn{children} when we speak of the call graph).
|
|
|
|
The entries are sorted by time spent in the function and its subroutines.
|
|
|
|
The internal profiling function @code{mcount} (@pxref{Flat Profile, ,The
|
|
Flat Profile}) is never mentioned in the call graph.
|
|
|
|
@menu
|
|
* Primary:: Details of the primary line's contents.
|
|
* Callers:: Details of caller-lines' contents.
|
|
* Subroutines:: Details of subroutine-lines' contents.
|
|
* Cycles:: When there are cycles of recursion,
|
|
such as @code{a} calls @code{b} calls @code{a}@dots{}
|
|
@end menu
|
|
|
|
@node Primary
|
|
@subsection The Primary Line
|
|
|
|
The @dfn{primary line} in a call graph entry is the line that
|
|
describes the function which the entry is about and gives the overall
|
|
statistics for this function.
|
|
|
|
For reference, we repeat the primary line from the entry for function
|
|
@code{report} in our main example, together with the heading line that
|
|
shows the names of the fields:
|
|
|
|
@smallexample
|
|
@group
|
|
index % time self children called name
|
|
@dots{}
|
|
[3] 100.0 0.00 0.05 1 report [3]
|
|
@end group
|
|
@end smallexample
|
|
|
|
Here is what the fields in the primary line mean:
|
|
|
|
@table @code
|
|
@item index
|
|
Entries are numbered with consecutive integers. Each function
|
|
therefore has an index number, which appears at the beginning of its
|
|
primary line.
|
|
|
|
Each cross-reference to a function, as a caller or subroutine of
|
|
another, gives its index number as well as its name. The index number
|
|
guides you if you wish to look for the entry for that function.
|
|
|
|
@item % time
|
|
This is the percentage of the total time that was spent in this
|
|
function, including time spent in subroutines called from this
|
|
function.
|
|
|
|
The time spent in this function is counted again for the callers of
|
|
this function. Therefore, adding up these percentages is meaningless.
|
|
|
|
@item self
|
|
This is the total amount of time spent in this function. This
|
|
should be identical to the number printed in the @code{seconds} field
|
|
for this function in the flat profile.
|
|
|
|
@item children
|
|
This is the total amount of time spent in the subroutine calls made by
|
|
this function. This should be equal to the sum of all the @code{self}
|
|
and @code{children} entries of the children listed directly below this
|
|
function.
|
|
|
|
@item called
|
|
This is the number of times the function was called.
|
|
|
|
If the function called itself recursively, there are two numbers,
|
|
separated by a @samp{+}. The first number counts non-recursive calls,
|
|
and the second counts recursive calls.
|
|
|
|
In the example above, the function @code{report} was called once from
|
|
@code{main}.
|
|
|
|
@item name
|
|
This is the name of the current function. The index number is
|
|
repeated after it.
|
|
|
|
If the function is part of a cycle of recursion, the cycle number is
|
|
printed between the function's name and the index number
|
|
(@pxref{Cycles, ,How Mutually Recursive Functions Are Described}).
|
|
For example, if function @code{gnurr} is part of
|
|
cycle number one, and has index number twelve, its primary line would
|
|
be end like this:
|
|
|
|
@example
|
|
gnurr <cycle 1> [12]
|
|
@end example
|
|
@end table
|
|
|
|
@node Callers
|
|
@subsection Lines for a Function's Callers
|
|
|
|
A function's entry has a line for each function it was called by.
|
|
These lines' fields correspond to the fields of the primary line, but
|
|
their meanings are different because of the difference in context.
|
|
|
|
For reference, we repeat two lines from the entry for the function
|
|
@code{report}, the primary line and one caller-line preceding it, together
|
|
with the heading line that shows the names of the fields:
|
|
|
|
@smallexample
|
|
index % time self children called name
|
|
@dots{}
|
|
0.00 0.05 1/1 main [2]
|
|
[3] 100.0 0.00 0.05 1 report [3]
|
|
@end smallexample
|
|
|
|
Here are the meanings of the fields in the caller-line for @code{report}
|
|
called from @code{main}:
|
|
|
|
@table @code
|
|
@item self
|
|
An estimate of the amount of time spent in @code{report} itself when it was
|
|
called from @code{main}.
|
|
|
|
@item children
|
|
An estimate of the amount of time spent in subroutines of @code{report}
|
|
when @code{report} was called from @code{main}.
|
|
|
|
The sum of the @code{self} and @code{children} fields is an estimate
|
|
of the amount of time spent within calls to @code{report} from @code{main}.
|
|
|
|
@item called
|
|
Two numbers: the number of times @code{report} was called from @code{main},
|
|
followed by the total number of non-recursive calls to @code{report} from
|
|
all its callers.
|
|
|
|
@item name and index number
|
|
The name of the caller of @code{report} to which this line applies,
|
|
followed by the caller's index number.
|
|
|
|
Not all functions have entries in the call graph; some
|
|
options to @code{gprof} request the omission of certain functions.
|
|
When a caller has no entry of its own, it still has caller-lines
|
|
in the entries of the functions it calls.
|
|
|
|
If the caller is part of a recursion cycle, the cycle number is
|
|
printed between the name and the index number.
|
|
@end table
|
|
|
|
If the identity of the callers of a function cannot be determined, a
|
|
dummy caller-line is printed which has @samp{<spontaneous>} as the
|
|
``caller's name'' and all other fields blank. This can happen for
|
|
signal handlers.
|
|
@c What if some calls have determinable callers' names but not all?
|
|
@c FIXME - still relevant?
|
|
|
|
@node Subroutines
|
|
@subsection Lines for a Function's Subroutines
|
|
|
|
A function's entry has a line for each of its subroutines---in other
|
|
words, a line for each other function that it called. These lines'
|
|
fields correspond to the fields of the primary line, but their meanings
|
|
are different because of the difference in context.
|
|
|
|
For reference, we repeat two lines from the entry for the function
|
|
@code{main}, the primary line and a line for a subroutine, together
|
|
with the heading line that shows the names of the fields:
|
|
|
|
@smallexample
|
|
index % time self children called name
|
|
@dots{}
|
|
[2] 100.0 0.00 0.05 1 main [2]
|
|
0.00 0.05 1/1 report [3]
|
|
@end smallexample
|
|
|
|
Here are the meanings of the fields in the subroutine-line for @code{main}
|
|
calling @code{report}:
|
|
|
|
@table @code
|
|
@item self
|
|
An estimate of the amount of time spent directly within @code{report}
|
|
when @code{report} was called from @code{main}.
|
|
|
|
@item children
|
|
An estimate of the amount of time spent in subroutines of @code{report}
|
|
when @code{report} was called from @code{main}.
|
|
|
|
The sum of the @code{self} and @code{children} fields is an estimate
|
|
of the total time spent in calls to @code{report} from @code{main}.
|
|
|
|
@item called
|
|
Two numbers, the number of calls to @code{report} from @code{main}
|
|
followed by the total number of non-recursive calls to @code{report}.
|
|
This ratio is used to determine how much of @code{report}'s @code{self}
|
|
and @code{children} time gets credited to @code{main}.
|
|
@xref{Assumptions, ,Estimating @code{children} Times}.
|
|
|
|
@item name
|
|
The name of the subroutine of @code{main} to which this line applies,
|
|
followed by the subroutine's index number.
|
|
|
|
If the caller is part of a recursion cycle, the cycle number is
|
|
printed between the name and the index number.
|
|
@end table
|
|
|
|
@node Cycles
|
|
@subsection How Mutually Recursive Functions Are Described
|
|
@cindex cycle
|
|
@cindex recursion cycle
|
|
|
|
The graph may be complicated by the presence of @dfn{cycles of
|
|
recursion} in the call graph. A cycle exists if a function calls
|
|
another function that (directly or indirectly) calls (or appears to
|
|
call) the original function. For example: if @code{a} calls @code{b},
|
|
and @code{b} calls @code{a}, then @code{a} and @code{b} form a cycle.
|
|
|
|
Whenever there are call paths both ways between a pair of functions, they
|
|
belong to the same cycle. If @code{a} and @code{b} call each other and
|
|
@code{b} and @code{c} call each other, all three make one cycle. Note that
|
|
even if @code{b} only calls @code{a} if it was not called from @code{a},
|
|
@code{gprof} cannot determine this, so @code{a} and @code{b} are still
|
|
considered a cycle.
|
|
|
|
The cycles are numbered with consecutive integers. When a function
|
|
belongs to a cycle, each time the function name appears in the call graph
|
|
it is followed by @samp{<cycle @var{number}>}.
|
|
|
|
The reason cycles matter is that they make the time values in the call
|
|
graph paradoxical. The ``time spent in children'' of @code{a} should
|
|
include the time spent in its subroutine @code{b} and in @code{b}'s
|
|
subroutines---but one of @code{b}'s subroutines is @code{a}! How much of
|
|
@code{a}'s time should be included in the children of @code{a}, when
|
|
@code{a} is indirectly recursive?
|
|
|
|
The way @code{gprof} resolves this paradox is by creating a single entry
|
|
for the cycle as a whole. The primary line of this entry describes the
|
|
total time spent directly in the functions of the cycle. The
|
|
``subroutines'' of the cycle are the individual functions of the cycle, and
|
|
all other functions that were called directly by them. The ``callers'' of
|
|
the cycle are the functions, outside the cycle, that called functions in
|
|
the cycle.
|
|
|
|
Here is an example portion of a call graph which shows a cycle containing
|
|
functions @code{a} and @code{b}. The cycle was entered by a call to
|
|
@code{a} from @code{main}; both @code{a} and @code{b} called @code{c}.
|
|
|
|
@smallexample
|
|
index % time self children called name
|
|
----------------------------------------
|
|
1.77 0 1/1 main [2]
|
|
[3] 91.71 1.77 0 1+5 <cycle 1 as a whole> [3]
|
|
1.02 0 3 b <cycle 1> [4]
|
|
0.75 0 2 a <cycle 1> [5]
|
|
----------------------------------------
|
|
3 a <cycle 1> [5]
|
|
[4] 52.85 1.02 0 0 b <cycle 1> [4]
|
|
2 a <cycle 1> [5]
|
|
0 0 3/6 c [6]
|
|
----------------------------------------
|
|
1.77 0 1/1 main [2]
|
|
2 b <cycle 1> [4]
|
|
[5] 38.86 0.75 0 1 a <cycle 1> [5]
|
|
3 b <cycle 1> [4]
|
|
0 0 3/6 c [6]
|
|
----------------------------------------
|
|
@end smallexample
|
|
|
|
@noindent
|
|
(The entire call graph for this program contains in addition an entry for
|
|
@code{main}, which calls @code{a}, and an entry for @code{c}, with callers
|
|
@code{a} and @code{b}.)
|
|
|
|
@smallexample
|
|
index % time self children called name
|
|
<spontaneous>
|
|
[1] 100.00 0 1.93 0 start [1]
|
|
0.16 1.77 1/1 main [2]
|
|
----------------------------------------
|
|
0.16 1.77 1/1 start [1]
|
|
[2] 100.00 0.16 1.77 1 main [2]
|
|
1.77 0 1/1 a <cycle 1> [5]
|
|
----------------------------------------
|
|
1.77 0 1/1 main [2]
|
|
[3] 91.71 1.77 0 1+5 <cycle 1 as a whole> [3]
|
|
1.02 0 3 b <cycle 1> [4]
|
|
0.75 0 2 a <cycle 1> [5]
|
|
0 0 6/6 c [6]
|
|
----------------------------------------
|
|
3 a <cycle 1> [5]
|
|
[4] 52.85 1.02 0 0 b <cycle 1> [4]
|
|
2 a <cycle 1> [5]
|
|
0 0 3/6 c [6]
|
|
----------------------------------------
|
|
1.77 0 1/1 main [2]
|
|
2 b <cycle 1> [4]
|
|
[5] 38.86 0.75 0 1 a <cycle 1> [5]
|
|
3 b <cycle 1> [4]
|
|
0 0 3/6 c [6]
|
|
----------------------------------------
|
|
0 0 3/6 b <cycle 1> [4]
|
|
0 0 3/6 a <cycle 1> [5]
|
|
[6] 0.00 0 0 6 c [6]
|
|
----------------------------------------
|
|
@end smallexample
|
|
|
|
The @code{self} field of the cycle's primary line is the total time
|
|
spent in all the functions of the cycle. It equals the sum of the
|
|
@code{self} fields for the individual functions in the cycle, found
|
|
in the entry in the subroutine lines for these functions.
|
|
|
|
The @code{children} fields of the cycle's primary line and subroutine lines
|
|
count only subroutines outside the cycle. Even though @code{a} calls
|
|
@code{b}, the time spent in those calls to @code{b} is not counted in
|
|
@code{a}'s @code{children} time. Thus, we do not encounter the problem of
|
|
what to do when the time in those calls to @code{b} includes indirect
|
|
recursive calls back to @code{a}.
|
|
|
|
The @code{children} field of a caller-line in the cycle's entry estimates
|
|
the amount of time spent @emph{in the whole cycle}, and its other
|
|
subroutines, on the times when that caller called a function in the cycle.
|
|
|
|
The @code{called} field in the primary line for the cycle has two numbers:
|
|
first, the number of times functions in the cycle were called by functions
|
|
outside the cycle; second, the number of times they were called by
|
|
functions in the cycle (including times when a function in the cycle calls
|
|
itself). This is a generalization of the usual split into non-recursive and
|
|
recursive calls.
|
|
|
|
The @code{called} field of a subroutine-line for a cycle member in the
|
|
cycle's entry says how many time that function was called from functions in
|
|
the cycle. The total of all these is the second number in the primary line's
|
|
@code{called} field.
|
|
|
|
In the individual entry for a function in a cycle, the other functions in
|
|
the same cycle can appear as subroutines and as callers. These lines show
|
|
how many times each function in the cycle called or was called from each other
|
|
function in the cycle. The @code{self} and @code{children} fields in these
|
|
lines are blank because of the difficulty of defining meanings for them
|
|
when recursion is going on.
|
|
|
|
@node Line-by-line
|
|
@section Line-by-line Profiling
|
|
|
|
@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
|
|
to generate debugging symbols for tracking source code lines.
|
|
|
|
The flat profile is the most useful output table
|
|
in line-by-line mode.
|
|
The call graph isn't as useful as normal, since
|
|
the current version of @code{gprof} does not propagate
|
|
call graph arcs from source code lines to the enclosing function.
|
|
The call graph does, however, show each line of code
|
|
that called each function, along with a count.
|
|
|
|
Here is a section of @code{gprof}'s output, without line-by-line profiling.
|
|
Note that @code{ct_init} accounted for four histogram hits, and
|
|
13327 calls to @code{init_block}.
|
|
|
|
@smallexample
|
|
Flat profile:
|
|
|
|
Each sample counts as 0.01 seconds.
|
|
% cumulative self self total
|
|
time seconds seconds calls us/call us/call name
|
|
30.77 0.13 0.04 6335 6.31 6.31 ct_init
|
|
|
|
|
|
Call graph (explanation follows)
|
|
|
|
|
|
granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
|
|
|
|
index % time self children called name
|
|
|
|
0.00 0.00 1/13496 name_too_long
|
|
0.00 0.00 40/13496 deflate
|
|
0.00 0.00 128/13496 deflate_fast
|
|
0.00 0.00 13327/13496 ct_init
|
|
[7] 0.0 0.00 0.00 13496 init_block
|
|
|
|
@end smallexample
|
|
|
|
Now let's look at some of @code{gprof}'s output from the same program run,
|
|
this time with line-by-line profiling enabled. Note that @code{ct_init}'s
|
|
four histogram hits are broken down into four lines of source code---one hit
|
|
occurred on each of lines 349, 351, 382 and 385. In the call graph,
|
|
note how
|
|
@code{ct_init}'s 13327 calls to @code{init_block} are broken down
|
|
into one call from line 396, 3071 calls from line 384, 3730 calls
|
|
from line 385, and 6525 calls from 387.
|
|
|
|
@smallexample
|
|
Flat profile:
|
|
|
|
Each sample counts as 0.01 seconds.
|
|
% cumulative self
|
|
time seconds seconds calls name
|
|
7.69 0.10 0.01 ct_init (trees.c:349)
|
|
7.69 0.11 0.01 ct_init (trees.c:351)
|
|
7.69 0.12 0.01 ct_init (trees.c:382)
|
|
7.69 0.13 0.01 ct_init (trees.c:385)
|
|
|
|
|
|
Call graph (explanation follows)
|
|
|
|
|
|
granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
|
|
|
|
% time self children called name
|
|
|
|
0.00 0.00 1/13496 name_too_long (gzip.c:1440)
|
|
0.00 0.00 1/13496 deflate (deflate.c:763)
|
|
0.00 0.00 1/13496 ct_init (trees.c:396)
|
|
0.00 0.00 2/13496 deflate (deflate.c:727)
|
|
0.00 0.00 4/13496 deflate (deflate.c:686)
|
|
0.00 0.00 5/13496 deflate (deflate.c:675)
|
|
0.00 0.00 12/13496 deflate (deflate.c:679)
|
|
0.00 0.00 16/13496 deflate (deflate.c:730)
|
|
0.00 0.00 128/13496 deflate_fast (deflate.c:654)
|
|
0.00 0.00 3071/13496 ct_init (trees.c:384)
|
|
0.00 0.00 3730/13496 ct_init (trees.c:385)
|
|
0.00 0.00 6525/13496 ct_init (trees.c:387)
|
|
[6] 0.0 0.00 0.00 13496 init_block (trees.c:408)
|
|
|
|
@end smallexample
|
|
|
|
|
|
@node Annotated Source
|
|
@section The Annotated Source Listing
|
|
|
|
@code{gprof}'s @samp{-A} option triggers an annotated source listing,
|
|
which lists the program's source code, each function labeled with the
|
|
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.
|
|
For example, consider the following function, taken from gzip,
|
|
with line numbers added:
|
|
|
|
@smallexample
|
|
1 ulg updcrc(s, n)
|
|
2 uch *s;
|
|
3 unsigned n;
|
|
4 @{
|
|
5 register ulg c;
|
|
6
|
|
7 static ulg crc = (ulg)0xffffffffL;
|
|
8
|
|
9 if (s == NULL) @{
|
|
10 c = 0xffffffffL;
|
|
11 @} else @{
|
|
12 c = crc;
|
|
13 if (n) do @{
|
|
14 c = crc_32_tab[...];
|
|
15 @} while (--n);
|
|
16 @}
|
|
17 crc = c;
|
|
18 return c ^ 0xffffffffL;
|
|
19 @}
|
|
|
|
@end smallexample
|
|
|
|
@code{updcrc} has at least five basic-blocks.
|
|
One is the function itself. The
|
|
@code{if} statement on line 9 generates two more basic-blocks, one
|
|
for each branch of the @code{if}. A fourth basic-block results from
|
|
the @code{if} on line 13, and the contents of the @code{do} loop form
|
|
the fifth basic-block. The compiler may also generate additional
|
|
basic-blocks to handle various special cases.
|
|
|
|
A program augmented for basic-block counting can be analyzed with
|
|
@samp{gprof -l -A}.
|
|
The @samp{-x} option is also helpful,
|
|
to ensure that each line of code is labeled at least once.
|
|
Here is @code{updcrc}'s
|
|
annotated source listing for a sample @code{gzip} run:
|
|
|
|
@smallexample
|
|
ulg updcrc(s, n)
|
|
uch *s;
|
|
unsigned n;
|
|
2 ->@{
|
|
register ulg c;
|
|
|
|
static ulg crc = (ulg)0xffffffffL;
|
|
|
|
2 -> if (s == NULL) @{
|
|
1 -> c = 0xffffffffL;
|
|
1 -> @} else @{
|
|
1 -> c = crc;
|
|
1 -> if (n) do @{
|
|
26312 -> c = crc_32_tab[...];
|
|
26312,1,26311 -> @} while (--n);
|
|
@}
|
|
2 -> crc = c;
|
|
2 -> return c ^ 0xffffffffL;
|
|
2 ->@}
|
|
@end smallexample
|
|
|
|
In this example, the function was called twice, passing once through
|
|
each branch of the @code{if} statement. The body of the @code{do}
|
|
loop was executed a total of 26312 times. Note how the @code{while}
|
|
statement is annotated. It began execution 26312 times, once for
|
|
each iteration through the loop. One of those times (the last time)
|
|
it exited, while it branched back to the beginning of the loop 26311 times.
|
|
|
|
@node Inaccuracy
|
|
@chapter Inaccuracy of @code{gprof} Output
|
|
|
|
@menu
|
|
* Sampling Error:: Statistical margins of error
|
|
* Assumptions:: Estimating children times
|
|
@end menu
|
|
|
|
@node Sampling Error
|
|
@section Statistical Sampling Error
|
|
|
|
The run-time figures that @code{gprof} gives you are based on a sampling
|
|
process, so they are subject to statistical inaccuracy. If a function runs
|
|
only a small amount of time, so that on the average the sampling process
|
|
ought to catch that function in the act only once, there is a pretty good
|
|
chance it will actually find that function zero times, or twice.
|
|
|
|
By contrast, the number-of-calls and basic-block figures
|
|
are derived by counting, not
|
|
sampling. They are completely accurate and will not vary from run to run
|
|
if your program is deterministic.
|
|
|
|
The @dfn{sampling period} that is printed at the beginning of the flat
|
|
profile says how often samples are taken. The rule of thumb is that a
|
|
run-time figure is accurate if it is considerably bigger than the sampling
|
|
period.
|
|
|
|
The actual amount of error can be predicted.
|
|
For @var{n} samples, the @emph{expected} error
|
|
is the square-root of @var{n}. For example,
|
|
if the sampling period is 0.01 seconds and @code{foo}'s run-time is 1 second,
|
|
@var{n} is 100 samples (1 second/0.01 seconds), sqrt(@var{n}) is 10 samples, so
|
|
the expected error in @code{foo}'s run-time is 0.1 seconds (10*0.01 seconds),
|
|
or ten percent of the observed value.
|
|
Again, if the sampling period is 0.01 seconds and @code{bar}'s run-time is
|
|
100 seconds, @var{n} is 10000 samples, sqrt(@var{n}) is 100 samples, so
|
|
the expected error in @code{bar}'s run-time is 1 second,
|
|
or one percent of the observed value.
|
|
It is likely to
|
|
vary this much @emph{on the average} from one profiling run to the next.
|
|
(@emph{Sometimes} it will vary more.)
|
|
|
|
This does not mean that a small run-time figure is devoid of information.
|
|
If the program's @emph{total} run-time is large, a small run-time for one
|
|
function does tell you that that function used an insignificant fraction of
|
|
the whole program's time. Usually this means it is not worth optimizing.
|
|
|
|
One way to get more accuracy is to give your program more (but similar)
|
|
input data so it will take longer. Another way is to combine the data from
|
|
several runs, using the @samp{-s} option of @code{gprof}. Here is how:
|
|
|
|
@enumerate
|
|
@item
|
|
Run your program once.
|
|
|
|
@item
|
|
Issue the command @samp{mv gmon.out gmon.sum}.
|
|
|
|
@item
|
|
Run your program again, the same as before.
|
|
|
|
@item
|
|
Merge the new data in @file{gmon.out} into @file{gmon.sum} with this command:
|
|
|
|
@example
|
|
gprof -s @var{executable-file} gmon.out gmon.sum
|
|
@end example
|
|
|
|
@item
|
|
Repeat the last two steps as often as you wish.
|
|
|
|
@item
|
|
Analyze the cumulative data using this command:
|
|
|
|
@example
|
|
gprof @var{executable-file} gmon.sum > @var{output-file}
|
|
@end example
|
|
@end enumerate
|
|
|
|
@node Assumptions
|
|
@section Estimating @code{children} Times
|
|
|
|
Some of the figures in the call graph are estimates---for example, the
|
|
@code{children} time values and all the time figures in caller and
|
|
subroutine lines.
|
|
|
|
There is no direct information about these measurements in the profile
|
|
data itself. Instead, @code{gprof} estimates them by making an assumption
|
|
about your program that might or might not be true.
|
|
|
|
The assumption made is that the average time spent in each call to any
|
|
function @code{foo} is not correlated with who called @code{foo}. If
|
|
@code{foo} used 5 seconds in all, and 2/5 of the calls to @code{foo} came
|
|
from @code{a}, then @code{foo} contributes 2 seconds to @code{a}'s
|
|
@code{children} time, by assumption.
|
|
|
|
This assumption is usually true enough, but for some programs it is far
|
|
from true. Suppose that @code{foo} returns very quickly when its argument
|
|
is zero; suppose that @code{a} always passes zero as an argument, while
|
|
other callers of @code{foo} pass other arguments. In this program, all the
|
|
time spent in @code{foo} is in the calls from callers other than @code{a}.
|
|
But @code{gprof} has no way of knowing this; it will blindly and
|
|
incorrectly charge 2 seconds of time in @code{foo} to the children of
|
|
@code{a}.
|
|
|
|
@c FIXME - has this been fixed?
|
|
We hope some day to put more complete data into @file{gmon.out}, so that
|
|
this assumption is no longer needed, if we can figure out how. For the
|
|
novice, the estimated figures are usually more useful than misleading.
|
|
|
|
@node How do I?
|
|
@chapter Answers to Common Questions
|
|
|
|
@table @asis
|
|
@item How can I get more exact information about hot spots in my program?
|
|
|
|
Looking at the per-line call counts only tells part of the story.
|
|
Because @code{gprof} can only report call times and counts by function,
|
|
the best way to get finer-grained information on where the program
|
|
is spending its time is to re-factor large functions into sequences
|
|
of calls to smaller ones. Beware however that this can introduce
|
|
artificial hot spots since compiling with @samp{-pg} adds a significant
|
|
overhead to function calls. An alternative solution is to use a
|
|
non-intrusive profiler, e.g.@: oprofile.
|
|
|
|
@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.
|
|
|
|
@item How do I find which lines in my program called a particular function?
|
|
|
|
Use @samp{gprof -l} and lookup the function in the call graph.
|
|
The callers will be broken down by function and line number.
|
|
|
|
@item How do I analyze a program that runs for less than a second?
|
|
|
|
Try using a shell script like this one:
|
|
|
|
@example
|
|
for i in `seq 1 100`; do
|
|
fastprog
|
|
mv gmon.out gmon.out.$i
|
|
done
|
|
|
|
gprof -s fastprog gmon.out.*
|
|
|
|
gprof fastprog gmon.sum
|
|
@end example
|
|
|
|
If your program is completely deterministic, all the call counts
|
|
will be simple multiples of 100 (i.e., a function called once in
|
|
each run will appear with a call count of 100).
|
|
|
|
@end table
|
|
|
|
@node Incompatibilities
|
|
@chapter Incompatibilities with Unix @code{gprof}
|
|
|
|
@sc{gnu} @code{gprof} and Berkeley Unix @code{gprof} use the same data
|
|
file @file{gmon.out}, and provide essentially the same information. But
|
|
there are a few differences.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@sc{gnu} @code{gprof} uses a new, generalized file format with support
|
|
for basic-block execution counts and non-realtime histograms. A magic
|
|
cookie and version number allows @code{gprof} to easily identify
|
|
new style files. Old BSD-style files can still be read.
|
|
@xref{File Format, ,Profiling Data File Format}.
|
|
|
|
@item
|
|
For a recursive function, Unix @code{gprof} lists the function as a
|
|
parent and as a child, with a @code{calls} field that lists the number
|
|
of recursive calls. @sc{gnu} @code{gprof} omits these lines and puts
|
|
the number of recursive calls in the primary line.
|
|
|
|
@item
|
|
When a function is suppressed from the call graph with @samp{-e}, @sc{gnu}
|
|
@code{gprof} still lists it as a subroutine of functions that call it.
|
|
|
|
@item
|
|
@sc{gnu} @code{gprof} accepts the @samp{-k} with its argument
|
|
in the form @samp{from/to}, instead of @samp{from to}.
|
|
|
|
@item
|
|
In the annotated source listing,
|
|
if there are multiple basic blocks on the same line,
|
|
@sc{gnu} @code{gprof} prints all of their counts, separated by commas.
|
|
|
|
@ignore - it does this now
|
|
@item
|
|
The function names printed in @sc{gnu} @code{gprof} output do not include
|
|
the leading underscores that are added internally to the front of all
|
|
C identifiers on many operating systems.
|
|
@end ignore
|
|
|
|
@item
|
|
The blurbs, field widths, and output formats are different. @sc{gnu}
|
|
@code{gprof} prints blurbs after the tables, so that you can see the
|
|
tables without skipping the blurbs.
|
|
@end itemize
|
|
|
|
@node Details
|
|
@chapter Details of Profiling
|
|
|
|
@menu
|
|
* Implementation:: How a program collects profiling information
|
|
* File Format:: Format of @samp{gmon.out} files
|
|
* Internals:: @code{gprof}'s internal operation
|
|
* Debugging:: Using @code{gprof}'s @samp{-d} option
|
|
@end menu
|
|
|
|
@node Implementation
|
|
@section Implementation of Profiling
|
|
|
|
Profiling works by changing how every function in your program is compiled
|
|
so that when it is called, it will stash away some information about where
|
|
it was called from. From this, the profiler can figure out what function
|
|
called it, and can count how many times it was called. This change is made
|
|
by the compiler when your program is compiled with the @samp{-pg} option,
|
|
which causes every function to call @code{mcount}
|
|
(or @code{_mcount}, or @code{__mcount}, depending on the OS and compiler)
|
|
as one of its first operations.
|
|
|
|
The @code{mcount} routine, included in the profiling library,
|
|
is responsible for recording in an in-memory call graph table
|
|
both its parent routine (the child) and its parent's parent. This is
|
|
typically done by examining the stack frame to find both
|
|
the address of the child, and the return address in the original parent.
|
|
Since this is a very machine-dependent operation, @code{mcount}
|
|
itself is typically a short assembly-language stub routine
|
|
that extracts the required
|
|
information, and then calls @code{__mcount_internal}
|
|
(a normal C function) with two arguments---@code{frompc} and @code{selfpc}.
|
|
@code{__mcount_internal} is responsible for maintaining
|
|
the in-memory call graph, which records @code{frompc}, @code{selfpc},
|
|
and the number of times each of these call arcs was traversed.
|
|
|
|
GCC Version 2 provides a magical function (@code{__builtin_return_address}),
|
|
which allows a generic @code{mcount} function to extract the
|
|
required information from the stack frame. However, on some
|
|
architectures, most notably the SPARC, using this builtin can be
|
|
very computationally expensive, and an assembly language version
|
|
of @code{mcount} is used for performance reasons.
|
|
|
|
Number-of-calls information for library routines is collected by using a
|
|
special version of the C library. The programs in it are the same as in
|
|
the usual C library, but they were compiled with @samp{-pg}. If you
|
|
link your program with @samp{gcc @dots{} -pg}, it automatically uses the
|
|
profiling version of the library.
|
|
|
|
Profiling also involves watching your program as it runs, and keeping a
|
|
histogram of where the program counter happens to be every now and then.
|
|
Typically the program counter is looked at around 100 times per second of
|
|
run time, but the exact frequency may vary from system to system.
|
|
|
|
This is done is one of two ways. Most UNIX-like operating systems
|
|
provide a @code{profil()} system call, which registers a memory
|
|
array with the kernel, along with a scale
|
|
factor that determines how the program's address space maps
|
|
into the array.
|
|
Typical scaling values cause every 2 to 8 bytes of address space
|
|
to map into a single array slot.
|
|
On every tick of the system clock
|
|
(assuming the profiled program is running), the value of the
|
|
program counter is examined and the corresponding slot in
|
|
the memory array is incremented. Since this is done in the kernel,
|
|
which had to interrupt the process anyway to handle the clock
|
|
interrupt, very little additional system overhead is required.
|
|
|
|
However, some operating systems, most notably Linux 2.0 (and earlier),
|
|
do not provide a @code{profil()} system call. On such a system,
|
|
arrangements are made for the kernel to periodically deliver
|
|
a signal to the process (typically via @code{setitimer()}),
|
|
which then performs the same operation of examining the
|
|
program counter and incrementing a slot in the memory array.
|
|
Since this method requires a signal to be delivered to
|
|
user space every time a sample is taken, it uses considerably
|
|
more overhead than kernel-based profiling. Also, due to the
|
|
added delay required to deliver the signal, this method is
|
|
less accurate as well.
|
|
|
|
A special startup routine allocates memory for the histogram and
|
|
either calls @code{profil()} or sets up
|
|
a clock signal handler.
|
|
This routine (@code{monstartup}) can be invoked in several ways.
|
|
On Linux systems, a special profiling startup file @code{gcrt0.o},
|
|
which invokes @code{monstartup} before @code{main},
|
|
is used instead of the default @code{crt0.o}.
|
|
Use of this special startup file is one of the effects
|
|
of using @samp{gcc @dots{} -pg} to link.
|
|
On SPARC systems, no special startup files are used.
|
|
Rather, the @code{mcount} routine, when it is invoked for
|
|
the first time (typically when @code{main} is called),
|
|
calls @code{monstartup}.
|
|
|
|
If the compiler's @samp{-a} option was used, basic-block counting
|
|
is also enabled. Each object file is then compiled with a static array
|
|
of counts, initially zero.
|
|
In the executable code, every time a new basic-block begins
|
|
(i.e., when an @code{if} statement appears), an extra instruction
|
|
is inserted to increment the corresponding count in the array.
|
|
At compile time, a paired array was constructed that recorded
|
|
the starting address of each basic-block. Taken together,
|
|
the two arrays record the starting address of every basic-block,
|
|
along with the number of times it was executed.
|
|
|
|
The profiling library also includes a function (@code{mcleanup}) which is
|
|
typically registered using @code{atexit()} to be called as the
|
|
program exits, and is responsible for writing the file @file{gmon.out}.
|
|
Profiling is turned off, various headers are output, and the histogram
|
|
is written, followed by the call-graph arcs and the basic-block counts.
|
|
|
|
The output from @code{gprof} gives no indication of parts of your program that
|
|
are limited by I/O or swapping bandwidth. This is because samples of the
|
|
program counter are taken at fixed intervals of the program's run time.
|
|
Therefore, the
|
|
time measurements in @code{gprof} output say nothing about time that your
|
|
program was not running. For example, a part of the program that creates
|
|
so much data that it cannot all fit in physical memory at once may run very
|
|
slowly due to thrashing, but @code{gprof} will say it uses little time. On
|
|
the other hand, sampling by run time has the advantage that the amount of
|
|
load due to other users won't directly affect the output you get.
|
|
|
|
@node File Format
|
|
@section Profiling Data File Format
|
|
|
|
The old BSD-derived file format used for profile data does not contain a
|
|
magic cookie that allows to check whether a data file really is a
|
|
@code{gprof} file. Furthermore, it does not provide a version number, thus
|
|
rendering changes to the file format almost impossible. @sc{gnu} @code{gprof}
|
|
uses a new file format that provides these features. For backward
|
|
compatibility, @sc{gnu} @code{gprof} continues to support the old BSD-derived
|
|
format, but not all features are supported with it. For example,
|
|
basic-block execution counts cannot be accommodated by the old file
|
|
format.
|
|
|
|
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 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
|
|
records, call-graph arc records, and basic-block execution count
|
|
records. Each file can contain any number of each record type. When
|
|
reading a file, @sc{gnu} @code{gprof} will ensure records of the same type are
|
|
compatible with each other and compute the union of all records. For
|
|
example, for basic-block execution counts, the union is simply the sum
|
|
of all execution counts for each basic-block.
|
|
|
|
@subsection Histogram Records
|
|
|
|
Histogram records consist of a header that is followed by an array of
|
|
bins. The header contains the text-segment range that the histogram
|
|
spans, the size of the histogram in bytes (unlike in the old BSD
|
|
format, this does not include the size of the header), the rate of the
|
|
profiling clock, and the physical dimension that the bin counts
|
|
represent after being scaled by the profiling clock rate. The
|
|
physical dimension is specified in two parts: a long name of up to 15
|
|
characters and a single character abbreviation. For example, a
|
|
histogram representing real-time would specify the long name as
|
|
``seconds'' and the abbreviation as ``s''. This feature is useful for
|
|
architectures that support performance monitor hardware (which,
|
|
fortunately, is becoming increasingly common). For example, under DEC
|
|
OSF/1, the ``uprofile'' command can be used to produce a histogram of,
|
|
say, instruction cache misses. In this case, the dimension in the
|
|
histogram header could be set to ``i-cache misses'' and the abbreviation
|
|
could be set to ``1'' (because it is simply a count, not a physical
|
|
dimension). Also, the profiling rate would have to be set to 1 in
|
|
this case.
|
|
|
|
Histogram bins are 16-bit numbers and each bin represent an equal
|
|
amount of text-space. For example, if the text-segment is one
|
|
thousand bytes long and if there are ten bins in the histogram, each
|
|
bin represents one hundred bytes.
|
|
|
|
|
|
@subsection Call-Graph Records
|
|
|
|
Call-graph records have a format that is identical to the one used in
|
|
the BSD-derived file format. It consists of an arc in the call graph
|
|
and a count indicating the number of times the arc was traversed
|
|
during program execution. Arcs are specified by a pair of addresses:
|
|
the first must be within caller's function and the second must be
|
|
within the callee's function. When performing profiling at the
|
|
function level, these addresses can point anywhere within the
|
|
respective function. However, when profiling at the line-level, it is
|
|
better if the addresses are as close to the call-site/entry-point as
|
|
possible. This will ensure that the line-level call-graph is able to
|
|
identify exactly which line of source code performed calls to a
|
|
function.
|
|
|
|
@subsection Basic-Block Execution Count Records
|
|
|
|
Basic-block execution count records consist of a header followed by a
|
|
sequence of address/count pairs. The header simply specifies the
|
|
length of the sequence. In an address/count pair, the address
|
|
identifies a basic-block and the count specifies the number of times
|
|
that basic-block was executed. Any address within the basic-address can
|
|
be used.
|
|
|
|
@node Internals
|
|
@section @code{gprof}'s Internal Operation
|
|
|
|
Like most programs, @code{gprof} begins by processing its options.
|
|
During this stage, it may building its symspec list
|
|
(@code{sym_ids.c:@-sym_id_add}), if
|
|
options are specified which use symspecs.
|
|
@code{gprof} maintains a single linked list of symspecs,
|
|
which will eventually get turned into 12 symbol tables,
|
|
organized into six include/exclude pairs---one
|
|
pair each for the flat profile (INCL_FLAT/EXCL_FLAT),
|
|
the call graph arcs (INCL_ARCS/EXCL_ARCS),
|
|
printing in the call graph (INCL_GRAPH/EXCL_GRAPH),
|
|
timing propagation in the call graph (INCL_TIME/EXCL_TIME),
|
|
the annotated source listing (INCL_ANNO/EXCL_ANNO),
|
|
and the execution count listing (INCL_EXEC/EXCL_EXEC).
|
|
|
|
After option processing, @code{gprof} finishes
|
|
building the symspec list by adding all the symspecs in
|
|
@code{default_excluded_list} to the exclude lists
|
|
EXCL_TIME and EXCL_GRAPH, and if line-by-line profiling is specified,
|
|
EXCL_FLAT as well.
|
|
These default excludes are not added to EXCL_ANNO, EXCL_ARCS, and EXCL_EXEC.
|
|
|
|
Next, the BFD library is called to open the object file,
|
|
verify that it is an object file,
|
|
and read its symbol table (@code{core.c:@-core_init}),
|
|
using @code{bfd_canonicalize_symtab} after mallocing
|
|
an appropriately sized array of symbols. At this point,
|
|
function mappings are read (if the @samp{--file-ordering} option
|
|
has been specified), and the core text space is read into
|
|
memory (if the @samp{-c} option was given).
|
|
|
|
@code{gprof}'s own symbol table, an array of Sym structures,
|
|
is now built.
|
|
This is done in one of two ways, by one of two routines, depending
|
|
on whether line-by-line profiling (@samp{-l} option) has been
|
|
enabled.
|
|
For normal profiling, the BFD canonical symbol table is scanned.
|
|
For line-by-line profiling, every
|
|
text space address is examined, and a new symbol table entry
|
|
gets created every time the line number changes.
|
|
In either case, two passes are made through the symbol
|
|
table---one to count the size of the symbol table required,
|
|
and the other to actually read the symbols. In between the
|
|
two passes, a single array of type @code{Sym} is created of
|
|
the appropriate length.
|
|
Finally, @code{symtab.c:@-symtab_finalize}
|
|
is called to sort the symbol table and remove duplicate entries
|
|
(entries with the same memory address).
|
|
|
|
The symbol table must be a contiguous array for two reasons.
|
|
First, the @code{qsort} library function (which sorts an array)
|
|
will be used to sort the symbol table.
|
|
Also, the symbol lookup routine (@code{symtab.c:@-sym_lookup}),
|
|
which finds symbols
|
|
based on memory address, uses a binary search algorithm
|
|
which requires the symbol table to be a sorted array.
|
|
Function symbols are indicated with an @code{is_func} flag.
|
|
Line number symbols have no special flags set.
|
|
Additionally, a symbol can have an @code{is_static} flag
|
|
to indicate that it is a local symbol.
|
|
|
|
With the symbol table read, the symspecs can now be translated
|
|
into Syms (@code{sym_ids.c:@-sym_id_parse}). Remember that a single
|
|
symspec can match multiple symbols.
|
|
An array of symbol tables
|
|
(@code{syms}) is created, each entry of which is a symbol table
|
|
of Syms to be included or excluded from a particular listing.
|
|
The master symbol table and the symspecs are examined by nested
|
|
loops, and every symbol that matches a symspec is inserted
|
|
into the appropriate syms table. This is done twice, once to
|
|
count the size of each required symbol table, and again to build
|
|
the tables, which have been malloced between passes.
|
|
From now on, to determine whether a symbol is on an include
|
|
or exclude symspec list, @code{gprof} simply uses its
|
|
standard symbol lookup routine on the appropriate table
|
|
in the @code{syms} array.
|
|
|
|
Now the profile data file(s) themselves are read
|
|
(@code{gmon_io.c:@-gmon_out_read}),
|
|
first by checking for a new-style @samp{gmon.out} header,
|
|
then assuming this is an old-style BSD @samp{gmon.out}
|
|
if the magic number test failed.
|
|
|
|
New-style histogram records are read by @code{hist.c:@-hist_read_rec}.
|
|
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 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
|
|
are matched to symbol table entries, and a call graph arc is
|
|
created by @code{cg_arcs.c:@-arc_add}, unless the arc fails a symspec
|
|
check against INCL_ARCS/EXCL_ARCS. As each arc is added,
|
|
a linked list is maintained of the parent's child arcs, and of the child's
|
|
parent arcs.
|
|
Both the child's call count and the arc's call count are
|
|
incremented by the record's call count.
|
|
|
|
Basic-block records are read (@code{basic_blocks.c:@-bb_read_rec}),
|
|
but only if line-by-line profiling has been selected.
|
|
Each basic-block address is matched to a corresponding line
|
|
symbol in the symbol table, and an entry made in the symbol's
|
|
bb_addr and bb_calls arrays. Again, if multiple basic-block
|
|
records are present for the same address, the call counts
|
|
are cumulative.
|
|
|
|
A gmon.sum file is dumped, if requested (@code{gmon_io.c:@-gmon_out_write}).
|
|
|
|
If histograms were present in the data files, assign them to symbols
|
|
(@code{hist.c:@-hist_assign_samples}) by iterating over all the sample
|
|
bins and assigning them to symbols. Since the symbol table
|
|
is sorted in order of ascending memory addresses, we can
|
|
simple follow along in the symbol table as we make our pass
|
|
over the sample bins.
|
|
This step includes a symspec check against INCL_FLAT/EXCL_FLAT.
|
|
Depending on the histogram
|
|
scale factor, a sample bin may span multiple symbols,
|
|
in which case a fraction of the sample count is allocated
|
|
to each symbol, proportional to the degree of overlap.
|
|
This effect is rare for normal profiling, but overlaps
|
|
are more common during line-by-line profiling, and can
|
|
cause each of two adjacent lines to be credited with half
|
|
a hit, for example.
|
|
|
|
If call graph data is present, @code{cg_arcs.c:@-cg_assemble} is called.
|
|
First, if @samp{-c} was specified, a machine-dependent
|
|
routine (@code{find_call}) scans through each symbol's machine code,
|
|
looking for subroutine call instructions, and adding them
|
|
to the call graph with a zero call count.
|
|
A topological sort is performed by depth-first numbering
|
|
all the symbols (@code{cg_dfn.c:@-cg_dfn}), so that
|
|
children are always numbered less than their parents,
|
|
then making a array of pointers into the symbol table and sorting it into
|
|
numerical order, which is reverse topological
|
|
order (children appear before parents).
|
|
Cycles are also detected at this point, all members
|
|
of which are assigned the same topological number.
|
|
Two passes are now made through this sorted array of symbol pointers.
|
|
The first pass, from end to beginning (parents to children),
|
|
computes the fraction of child time to propagate to each parent
|
|
and a print flag.
|
|
The print flag reflects symspec handling of INCL_GRAPH/EXCL_GRAPH,
|
|
with a parent's include or exclude (print or no print) property
|
|
being propagated to its children, unless they themselves explicitly appear
|
|
in INCL_GRAPH or EXCL_GRAPH.
|
|
A second pass, from beginning to end (children to parents) actually
|
|
propagates the timings along the call graph, subject
|
|
to a check against INCL_TIME/EXCL_TIME.
|
|
With the print flag, fractions, and timings now stored in the symbol
|
|
structures, the topological sort array is now discarded, and a
|
|
new array of pointers is assembled, this time sorted by propagated time.
|
|
|
|
Finally, print the various outputs the user requested, which is now fairly
|
|
straightforward. The call graph (@code{cg_print.c:@-cg_print}) and
|
|
flat profile (@code{hist.c:@-hist_print}) are regurgitations of values
|
|
already computed. The annotated source listing
|
|
(@code{basic_blocks.c:@-print_annotated_source}) uses basic-block
|
|
information, if present, to label each line of code with call counts,
|
|
otherwise only the function call counts are presented.
|
|
|
|
The function ordering code is marginally well documented
|
|
in the source code itself (@code{cg_print.c}). Basically,
|
|
the functions with the most use and the most parents are
|
|
placed first, followed by other functions with the most use,
|
|
followed by lower use functions, followed by unused functions
|
|
at the end.
|
|
|
|
@node Debugging
|
|
@section Debugging @code{gprof}
|
|
|
|
If @code{gprof} was compiled with debugging enabled,
|
|
the @samp{-d} option triggers debugging output
|
|
(to stdout) which can be helpful in understanding its operation.
|
|
The debugging number specified is interpreted as a sum of the following
|
|
options:
|
|
|
|
@table @asis
|
|
@item 2 - Topological sort
|
|
Monitor depth-first numbering of symbols during call graph analysis
|
|
@item 4 - Cycles
|
|
Shows symbols as they are identified as cycle heads
|
|
@item 16 - Tallying
|
|
As the call graph arcs are read, show each arc and how
|
|
the total calls to each function are tallied
|
|
@item 32 - Call graph arc sorting
|
|
Details sorting individual parents/children within each call graph entry
|
|
@item 64 - Reading histogram and call graph records
|
|
Shows address ranges of histograms as they are read, and each
|
|
call graph arc
|
|
@item 128 - Symbol table
|
|
Reading, classifying, and sorting the symbol table from the object file.
|
|
For line-by-line profiling (@samp{-l} option), also shows line numbers
|
|
being assigned to memory addresses.
|
|
@item 256 - Static call graph
|
|
Trace operation of @samp{-c} option
|
|
@item 512 - Symbol table and arc table lookups
|
|
Detail operation of lookup routines
|
|
@item 1024 - Call graph propagation
|
|
Shows how function times are propagated along the call graph
|
|
@item 2048 - Basic-blocks
|
|
Shows basic-block records as they are read from profile data
|
|
(only meaningful with @samp{-l} option)
|
|
@item 4096 - Symspecs
|
|
Shows symspec-to-symbol pattern matching operation
|
|
@item 8192 - Annotate source
|
|
Tracks operation of @samp{-A} option
|
|
@end table
|
|
|
|
@node GNU Free Documentation License
|
|
@appendix GNU Free Documentation License
|
|
@center Version 1.1, March 2000
|
|
|
|
@display
|
|
Copyright (C) 2000, 2003 Free Software Foundation, Inc.
|
|
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
|
|
Everyone is permitted to copy and distribute verbatim copies
|
|
of this license document, but changing it is not allowed.
|
|
@end display
|
|
@sp 1
|
|
@enumerate 0
|
|
@item
|
|
PREAMBLE
|
|
|
|
The purpose of this License is to make a manual, textbook, or other
|
|
written document ``free'' in the sense of freedom: to assure everyone
|
|
the effective freedom to copy and redistribute it, with or without
|
|
modifying it, either commercially or noncommercially. Secondarily,
|
|
this License preserves for the author and publisher a way to get
|
|
credit for their work, while not being considered responsible for
|
|
modifications made by others.
|
|
|
|
This License is a kind of ``copyleft'', which means that derivative
|
|
works of the document must themselves be free in the same sense. It
|
|
complements the GNU General Public License, which is a copyleft
|
|
license designed for free software.
|
|
|
|
We have designed this License in order to use it for manuals for free
|
|
software, because free software needs free documentation: a free
|
|
program should come with manuals providing the same freedoms that the
|
|
software does. But this License is not limited to software manuals;
|
|
it can be used for any textual work, regardless of subject matter or
|
|
whether it is published as a printed book. We recommend this License
|
|
principally for works whose purpose is instruction or reference.
|
|
|
|
@sp 1
|
|
@item
|
|
APPLICABILITY AND DEFINITIONS
|
|
|
|
This License applies to any manual or other work that contains a
|
|
notice placed by the copyright holder saying it can be distributed
|
|
under the terms of this License. The ``Document'', below, refers to any
|
|
such manual or work. Any member of the public is a licensee, and is
|
|
addressed as ``you.''
|
|
|
|
A ``Modified Version'' of the Document means any work containing the
|
|
Document or a portion of it, either copied verbatim, or with
|
|
modifications and/or translated into another language.
|
|
|
|
A ``Secondary Section'' is a named appendix or a front-matter section of
|
|
the Document that deals exclusively with the relationship of the
|
|
publishers or authors of the Document to the Document's overall subject
|
|
(or to related matters) and contains nothing that could fall directly
|
|
within that overall subject. (For example, if the Document is in part a
|
|
textbook of mathematics, a Secondary Section may not explain any
|
|
mathematics.) The relationship could be a matter of historical
|
|
connection with the subject or with related matters, or of legal,
|
|
commercial, philosophical, ethical or political position regarding
|
|
them.
|
|
|
|
The ``Invariant Sections'' are certain Secondary Sections whose titles
|
|
are designated, as being those of Invariant Sections, in the notice
|
|
that says that the Document is released under this License.
|
|
|
|
The ``Cover Texts'' are certain short passages of text that are listed,
|
|
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
|
|
the Document is released under this License.
|
|
|
|
A ``Transparent'' copy of the Document means a machine-readable copy,
|
|
represented in a format whose specification is available to the
|
|
general public, whose contents can be viewed and edited directly and
|
|
straightforwardly with generic text editors or (for images composed of
|
|
pixels) generic paint programs or (for drawings) some widely available
|
|
drawing editor, and that is suitable for input to text formatters or
|
|
for automatic translation to a variety of formats suitable for input
|
|
to text formatters. A copy made in an otherwise Transparent file
|
|
format whose markup has been designed to thwart or discourage
|
|
subsequent modification by readers is not Transparent. A copy that is
|
|
not ``Transparent'' is called ``Opaque.''
|
|
|
|
Examples of suitable formats for Transparent copies include plain
|
|
ASCII without markup, Texinfo input format, LaTeX input format, SGML
|
|
or XML using a publicly available DTD, and standard-conforming simple
|
|
HTML designed for human modification. Opaque formats include
|
|
PostScript, PDF, proprietary formats that can be read and edited only
|
|
by proprietary word processors, SGML or XML for which the DTD and/or
|
|
processing tools are not generally available, and the
|
|
machine-generated HTML produced by some word processors for output
|
|
purposes only.
|
|
|
|
The ``Title Page'' means, for a printed book, the title page itself,
|
|
plus such following pages as are needed to hold, legibly, the material
|
|
this License requires to appear in the title page. For works in
|
|
formats which do not have any title page as such, ``Title Page'' means
|
|
the text near the most prominent appearance of the work's title,
|
|
preceding the beginning of the body of the text.
|
|
@sp 1
|
|
@item
|
|
VERBATIM COPYING
|
|
|
|
You may copy and distribute the Document in any medium, either
|
|
commercially or noncommercially, provided that this License, the
|
|
copyright notices, and the license notice saying this License applies
|
|
to the Document are reproduced in all copies, and that you add no other
|
|
conditions whatsoever to those of this License. You may not use
|
|
technical measures to obstruct or control the reading or further
|
|
copying of the copies you make or distribute. However, you may accept
|
|
compensation in exchange for copies. If you distribute a large enough
|
|
number of copies you must also follow the conditions in section 3.
|
|
|
|
You may also lend copies, under the same conditions stated above, and
|
|
you may publicly display copies.
|
|
@sp 1
|
|
@item
|
|
COPYING IN QUANTITY
|
|
|
|
If you publish printed copies of the Document numbering more than 100,
|
|
and the Document's license notice requires Cover Texts, you must enclose
|
|
the copies in covers that carry, clearly and legibly, all these Cover
|
|
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
|
|
the back cover. Both covers must also clearly and legibly identify
|
|
you as the publisher of these copies. The front cover must present
|
|
the full title with all words of the title equally prominent and
|
|
visible. You may add other material on the covers in addition.
|
|
Copying with changes limited to the covers, as long as they preserve
|
|
the title of the Document and satisfy these conditions, can be treated
|
|
as verbatim copying in other respects.
|
|
|
|
If the required texts for either cover are too voluminous to fit
|
|
legibly, you should put the first ones listed (as many as fit
|
|
reasonably) on the actual cover, and continue the rest onto adjacent
|
|
pages.
|
|
|
|
If you publish or distribute Opaque copies of the Document numbering
|
|
more than 100, you must either include a machine-readable Transparent
|
|
copy along with each Opaque copy, or state in or with each Opaque copy
|
|
a publicly-accessible computer-network location containing a complete
|
|
Transparent copy of the Document, free of added material, which the
|
|
general network-using public has access to download anonymously at no
|
|
charge using public-standard network protocols. If you use the latter
|
|
option, you must take reasonably prudent steps, when you begin
|
|
distribution of Opaque copies in quantity, to ensure that this
|
|
Transparent copy will remain thus accessible at the stated location
|
|
until at least one year after the last time you distribute an Opaque
|
|
copy (directly or through your agents or retailers) of that edition to
|
|
the public.
|
|
|
|
It is requested, but not required, that you contact the authors of the
|
|
Document well before redistributing any large number of copies, to give
|
|
them a chance to provide you with an updated version of the Document.
|
|
@sp 1
|
|
@item
|
|
MODIFICATIONS
|
|
|
|
You may copy and distribute a Modified Version of the Document under
|
|
the conditions of sections 2 and 3 above, provided that you release
|
|
the Modified Version under precisely this License, with the Modified
|
|
Version filling the role of the Document, thus licensing distribution
|
|
and modification of the Modified Version to whoever possesses a copy
|
|
of it. In addition, you must do these things in the Modified Version:
|
|
|
|
A. Use in the Title Page (and on the covers, if any) a title distinct
|
|
from that of the Document, and from those of previous versions
|
|
(which should, if there were any, be listed in the History section
|
|
of the Document). You may use the same title as a previous version
|
|
if the original publisher of that version gives permission.@*
|
|
B. List on the Title Page, as authors, one or more persons or entities
|
|
responsible for authorship of the modifications in the Modified
|
|
Version, together with at least five of the principal authors of the
|
|
Document (all of its principal authors, if it has less than five).@*
|
|
C. State on the Title page the name of the publisher of the
|
|
Modified Version, as the publisher.@*
|
|
D. Preserve all the copyright notices of the Document.@*
|
|
E. Add an appropriate copyright notice for your modifications
|
|
adjacent to the other copyright notices.@*
|
|
F. Include, immediately after the copyright notices, a license notice
|
|
giving the public permission to use the Modified Version under the
|
|
terms of this License, in the form shown in the Addendum below.@*
|
|
G. Preserve in that license notice the full lists of Invariant Sections
|
|
and required Cover Texts given in the Document's license notice.@*
|
|
H. Include an unaltered copy of this License.@*
|
|
I. Preserve the section entitled ``History'', and its title, and add to
|
|
it an item stating at least the title, year, new authors, and
|
|
publisher of the Modified Version as given on the Title Page. If
|
|
there is no section entitled ``History'' in the Document, create one
|
|
stating the title, year, authors, and publisher of the Document as
|
|
given on its Title Page, then add an item describing the Modified
|
|
Version as stated in the previous sentence.@*
|
|
J. Preserve the network location, if any, given in the Document for
|
|
public access to a Transparent copy of the Document, and likewise
|
|
the network locations given in the Document for previous versions
|
|
it was based on. These may be placed in the ``History'' section.
|
|
You may omit a network location for a work that was published at
|
|
least four years before the Document itself, or if the original
|
|
publisher of the version it refers to gives permission.@*
|
|
K. In any section entitled ``Acknowledgements'' or ``Dedications'',
|
|
preserve the section's title, and preserve in the section all the
|
|
substance and tone of each of the contributor acknowledgements
|
|
and/or dedications given therein.@*
|
|
L. Preserve all the Invariant Sections of the Document,
|
|
unaltered in their text and in their titles. Section numbers
|
|
or the equivalent are not considered part of the section titles.@*
|
|
M. Delete any section entitled ``Endorsements.'' Such a section
|
|
may not be included in the Modified Version.@*
|
|
N. Do not retitle any existing section as ``Endorsements''
|
|
or to conflict in title with any Invariant Section.@*
|
|
@sp 1
|
|
If the Modified Version includes new front-matter sections or
|
|
appendices that qualify as Secondary Sections and contain no material
|
|
copied from the Document, you may at your option designate some or all
|
|
of these sections as invariant. To do this, add their titles to the
|
|
list of Invariant Sections in the Modified Version's license notice.
|
|
These titles must be distinct from any other section titles.
|
|
|
|
You may add a section entitled ``Endorsements'', provided it contains
|
|
nothing but endorsements of your Modified Version by various
|
|
parties--for example, statements of peer review or that the text has
|
|
been approved by an organization as the authoritative definition of a
|
|
standard.
|
|
|
|
You may add a passage of up to five words as a Front-Cover Text, and a
|
|
passage of up to 25 words as a Back-Cover Text, to the end of the list
|
|
of Cover Texts in the Modified Version. Only one passage of
|
|
Front-Cover Text and one of Back-Cover Text may be added by (or
|
|
through arrangements made by) any one entity. If the Document already
|
|
includes a cover text for the same cover, previously added by you or
|
|
by arrangement made by the same entity you are acting on behalf of,
|
|
you may not add another; but you may replace the old one, on explicit
|
|
permission from the previous publisher that added the old one.
|
|
|
|
The author(s) and publisher(s) of the Document do not by this License
|
|
give permission to use their names for publicity for or to assert or
|
|
imply endorsement of any Modified Version.
|
|
@sp 1
|
|
@item
|
|
COMBINING DOCUMENTS
|
|
|
|
You may combine the Document with other documents released under this
|
|
License, under the terms defined in section 4 above for modified
|
|
versions, provided that you include in the combination all of the
|
|
Invariant Sections of all of the original documents, unmodified, and
|
|
list them all as Invariant Sections of your combined work in its
|
|
license notice.
|
|
|
|
The combined work need only contain one copy of this License, and
|
|
multiple identical Invariant Sections may be replaced with a single
|
|
copy. If there are multiple Invariant Sections with the same name but
|
|
different contents, make the title of each such section unique by
|
|
adding at the end of it, in parentheses, the name of the original
|
|
author or publisher of that section if known, or else a unique number.
|
|
Make the same adjustment to the section titles in the list of
|
|
Invariant Sections in the license notice of the combined work.
|
|
|
|
In the combination, you must combine any sections entitled ``History''
|
|
in the various original documents, forming one section entitled
|
|
``History''; likewise combine any sections entitled ``Acknowledgements'',
|
|
and any sections entitled ``Dedications.'' You must delete all sections
|
|
entitled ``Endorsements.''
|
|
@sp 1
|
|
@item
|
|
COLLECTIONS OF DOCUMENTS
|
|
|
|
You may make a collection consisting of the Document and other documents
|
|
released under this License, and replace the individual copies of this
|
|
License in the various documents with a single copy that is included in
|
|
the collection, provided that you follow the rules of this License for
|
|
verbatim copying of each of the documents in all other respects.
|
|
|
|
You may extract a single document from such a collection, and distribute
|
|
it individually under this License, provided you insert a copy of this
|
|
License into the extracted document, and follow this License in all
|
|
other respects regarding verbatim copying of that document.
|
|
@sp 1
|
|
@item
|
|
AGGREGATION WITH INDEPENDENT WORKS
|
|
|
|
A compilation of the Document or its derivatives with other separate
|
|
and independent documents or works, in or on a volume of a storage or
|
|
distribution medium, does not as a whole count as a Modified Version
|
|
of the Document, provided no compilation copyright is claimed for the
|
|
compilation. Such a compilation is called an ``aggregate'', and this
|
|
License does not apply to the other self-contained works thus compiled
|
|
with the Document, on account of their being thus compiled, if they
|
|
are not themselves derivative works of the Document.
|
|
|
|
If the Cover Text requirement of section 3 is applicable to these
|
|
copies of the Document, then if the Document is less than one quarter
|
|
of the entire aggregate, the Document's Cover Texts may be placed on
|
|
covers that surround only the Document within the aggregate.
|
|
Otherwise they must appear on covers around the whole aggregate.
|
|
@sp 1
|
|
@item
|
|
TRANSLATION
|
|
|
|
Translation is considered a kind of modification, so you may
|
|
distribute translations of the Document under the terms of section 4.
|
|
Replacing Invariant Sections with translations requires special
|
|
permission from their copyright holders, but you may include
|
|
translations of some or all Invariant Sections in addition to the
|
|
original versions of these Invariant Sections. You may include a
|
|
translation of this License provided that you also include the
|
|
original English version of this License. In case of a disagreement
|
|
between the translation and the original English version of this
|
|
License, the original English version will prevail.
|
|
@sp 1
|
|
@item
|
|
TERMINATION
|
|
|
|
You may not copy, modify, sublicense, or distribute the Document except
|
|
as expressly provided for under this License. Any other attempt to
|
|
copy, modify, sublicense or distribute the Document is void, and will
|
|
automatically terminate your rights under this License. However,
|
|
parties who have received copies, or rights, from you under this
|
|
License will not have their licenses terminated so long as such
|
|
parties remain in full compliance.
|
|
@sp 1
|
|
@item
|
|
FUTURE REVISIONS OF THIS LICENSE
|
|
|
|
The Free Software Foundation may publish new, revised versions
|
|
of the GNU Free Documentation License from time to time. Such new
|
|
versions will be similar in spirit to the present version, but may
|
|
differ in detail to address new problems or concerns. See
|
|
http://www.gnu.org/copyleft/.
|
|
|
|
Each version of the License is given a distinguishing version number.
|
|
If the Document specifies that a particular numbered version of this
|
|
License ``or any later version'' applies to it, you have the option of
|
|
following the terms and conditions either of that specified version or
|
|
of any later version that has been published (not as a draft) by the
|
|
Free Software Foundation. If the Document does not specify a version
|
|
number of this License, you may choose any version ever published (not
|
|
as a draft) by the Free Software Foundation.
|
|
|
|
@end enumerate
|
|
|
|
@unnumberedsec ADDENDUM: How to use this License for your documents
|
|
|
|
To use this License in a document you have written, include a copy of
|
|
the License in the document and put the following copyright and
|
|
license notices just after the title page:
|
|
|
|
@smallexample
|
|
@group
|
|
Copyright (C) @var{year} @var{your name}.
|
|
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 the Invariant Sections being @var{list their titles}, with the
|
|
Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
|
|
A copy of the license is included in the section entitled "GNU
|
|
Free Documentation License."
|
|
@end group
|
|
@end smallexample
|
|
|
|
If you have no Invariant Sections, write ``with no Invariant Sections''
|
|
instead of saying which ones are invariant. If you have no
|
|
Front-Cover Texts, write ``no Front-Cover Texts'' instead of
|
|
``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
|
|
|
|
If your document contains nontrivial examples of program code, we
|
|
recommend releasing these examples in parallel under your choice of
|
|
free software license, such as the GNU General Public License,
|
|
to permit their use in free software.
|
|
|
|
@bye
|
|
|
|
NEEDS AN INDEX
|
|
|
|
-T - "traditional BSD style": How is it different? Should the
|
|
differences be documented?
|
|
|
|
example flat file adds up to 100.01%...
|
|
|
|
note: time estimates now only go out to one decimal place (0.0), where
|
|
they used to extend two (78.67).
|