@ifinfo
This file documents the gprof profiler of the GNU system.
-Copyright (C) 1988, 1992, 1997, 1998, 1999 Free Software Foundation, Inc.
+Copyright (C) 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
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 was edited January 1993 by Jeffrey Osier
-and updated September 1997 by Brent Baccala.
-
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 1992, 1997, 1998 Free Software Foundation, Inc.
+Copyright @copyright{} 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
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 was updated August 1997 by Brent Baccala.
-
@menu
* Introduction:: What profiling means, and why it is useful.
* Output Options:: Controlling @code{gprof}'s output style
* Analysis Options:: Controlling how @code{gprof} analyses its data
* Miscellaneous Options::
-* Depricated Options:: Options you no longer need to use, but which
+* 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
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, specifing
+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.
@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 convery this information.
+can also be used to convey this information.
Used mostly for annotated source output.
@item -J[@var{symspec}]
@item -y
@itemx --separate-files
This option affects annotated source output only.
-Normally, gprof prints annotated source files
+Normally, @code{gprof} prints annotated source files
to standard-output. If this option is specified,
-annotated source for a file named @file{path/filename}
-is generated in the file @file{filename-ann}.
+annotated source for a file named @file{path/@var{filename}}
+is generated in the file @file{@var{filename}-ann}. If the underlying
+filesystem 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}]
@end group
@end smallexample
-GNU @code{nm} @samp{--extern-only} @samp{--defined-only} @samp{-v} @samp{--print-file-name} can be used to create @var{map_file}.
+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
@end table
-@node Miscellaneous Options,Depricated Options,Analysis Options,Invoking
+@node Miscellaneous Options,Deprecated Options,Analysis Options,Invoking
@section Miscellaneous Options
@table @code
@end table
-@node Depricated Options,Symspecs,Miscellaneous Options,Invoking
-@section Depricated Options
+@node Deprecated Options,Symspecs,Miscellaneous Options,Invoking
+@section Deprecated Options
@table @code
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,,Depricated Options,Invoking
+@node Symspecs,,Deprecated Options,Invoking
@section Symspecs
Many of the output options allow functions to be included or excluded
@table @samp
@item main.c
Selects everything in file @file{main.c}---the
-dot in the string tells gprof to interpret
+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
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. gprof
-will normally not print these underscores. However, you must use the
-underscore when you name a symbol in a symspec. You can use the
-@code{nm} program to see whether symbols have underscores for the object
-file format you are using.
+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}.
The functions are sorted by 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
-aparatus and appear in every flat profile; their time gives a measure of
+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
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 occured while the
+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
-occured one each in @samp{offtime}, @samp{memccpy}, @samp{write},
+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.
@item called
Two numbers: the number of times @code{report} was called from @code{main},
-followed by the total number of nonrecursive calls to @code{report} from
+followed by the total number of non-recursive calls to @code{report} from
all its callers.
@item name and index number
@item called
Two numbers, the number of calls to @code{report} from @code{main}
-followed by the total number of nonrecursive calls to @code{report}.
+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}.
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 nonrecursive and
+itself). This is a generalization of the usual split into non-recursive and
recursive calls.
The @code{calls} field of a subroutine-line for a cycle member in the
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
-occured on each of lines 349, 351, 382 and 385. In the call graph,
+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
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 exeucted.
+of code was executed.
For example, consider the following function, taken from gzip,
with line numbers added:
basic-blocks to handle various special cases.
A program augmented for basic-block counting can be analyzed with
-@code{gprof -l -A}. I also suggest use of the @samp{-x} option,
+@samp{gprof -l -A}. I also suggest use of the @samp{-x} option,
which ensures that each line of code is labeled at least once.
Here is @code{updcrc}'s
annotated source listing for a sample @code{gzip} run:
@item How do I find which lines in my program called a particular function?
-Use @code{gprof -l} and lookup the function in the call graph.
+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?
@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, seperated by commas.
+@sc{gnu} @code{gprof} prints all of their counts, separated by commas.
@ignore - it does this now
@item
@chapter Details of Profiling
@menu
-* Implementation:: How a program collets profiling information
+* 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
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-dependant operation, @code{mcount}
+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 transversed.
+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
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
-gprof file. Furthermore, it does not provide a version number, thus
+@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
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 appropiate sized array of asymbols. At this point,
+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).
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 appropiate length.
+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).
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-dependant
+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.
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 propogate to each parent
+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
-propogates the timings along the call graph, subject
+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
projects / deliverable / binutils-gdb.git / blobdiff