\input texinfo @c -*-texinfo-*-
@setfilename gprof.info
-@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001
+@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001, 2003
@c Free Software Foundation, Inc.
@settitle GNU gprof
@setchapternewpage odd
This file documents the gprof profiler of the GNU system.
@c man begin COPYRIGHT
-Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
+Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001, 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
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 Free Software Foundation, Inc.
+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
@end titlepage
-@ifinfo
+@ifnottex
@node Top
@top Profiling a Program: Where Does It Spend Its Time?
* Details:: Details of how profiling is done
* GNU Free Documentation License:: GNU Free Documentation License
@end menu
-@end ifinfo
+@end ifnottex
@node Introduction
@chapter Introduction to Profiling
@smallexample
@c man begin SYNOPSIS
-gprof [ -[abcDhilLsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ]
+gprof [ -[abcDhilLrsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ]
[ -I @var{dirs} ] [ -d[@var{num}] ] [ -k @var{from/to} ]
- [ -m @var{min-count} ] [ -t @var{table-length} ]
+ [ -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}] ]
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
+
+ % the percentage of the total running time of the
+@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
that match program addresses to source code lines.
@xref{Line-by-line}.
-In addition to the @samp{-pg} and @samp{-g} options,
-you may also wish to specify the @samp{-a} option when compiling.
-This will instrument
-the program to perform basic-block counting. As the program runs,
+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
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 afterward if you are concerned that it may be overwritten.
+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
counts didn't get written into @file{gmon.out}.
The Perl script @code{bbconv.pl}, included with the @code{gprof}
source distribution, will convert a @file{bb.out} file into
-a format readable by @code{gprof}.
+a format readable by @code{gprof}. Invoke it like this:
+
+@smallexample
+bbconv.pl < bb.out > @var{bh-data}
+@end smallexample
+
+This translates the information in @file{bb.out} into a form that
+@code{gprof} can understand. But you still need to tell @code{gprof}
+about the existence of this translated information. To do that, include
+@var{bb-data} on the @code{gprof} command line, @emph{along with
+@file{gmon.out}}, like this:
+
+@smallexample
+gprof @var{options} @var{executable-file} gmon.out @var{bb-data} [@var{yet-more-profile-data-files}@dots{}] [> @var{outfile}]
+@end smallexample
@node Invoking
@chapter @code{gprof} Command Summary
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.
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 --function-ordering
+@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
in a particular order is system dependent and out of the scope of this
manual.
-@item --file-ordering @var{map_file}
+@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
If @var{num} is not specified, enable all debugging.
@xref{Debugging}.
+@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
@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 the time figures in caller and
+@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
@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
+artifical 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
projects / deliverable / binutils-gdb.git / blobdiff