gprof - Displays call-graph profile data
gprof [options] prog_name [profile_file...]
Name of the program executable whose profile is to be displayed.
For a program compiled for PC-sampling with the
-pg option or instrumented for PC-sampling with hiprof,
specify the name of the executable that was run to produce
the profile file specified. For other kinds of hiprof profiling,
specify the uninstrumented executable that was the
input to hiprof. The program should also be compiled with
the -g1, -g2, or -g3 option to obtain more complete profiling
information. If the default symbol table level
(-g0) has been used, line number information, static procedure
names, and file names are unavailable to the profiling
code. Name of the call graph profile file. This
is either a PC sampling profile file or an instrumented
event-counting profile file. By default, gprof looks for
the profile file named gmon.out (see the description of
the PROFDIR environment variable). If more than one profile_file
is specified, gprof output shows the sum of the
profile information in the specified profile files.
For each gprof option, you need type only enough of the
name to distinguish it from the other options. Suppresses
the printing of statically declared functions. If this
option is given, all relevant information about the static
function (for example, time samples, calls to other functions,
calls from other functions) belongs to the function
loaded just before the static function in the a.out file.
Causes the profiles for all shared libraries (if any)
described in the data file(s) to be displayed, in addition
to the profile for the executable. Profiles each instruction
within selected procedures. (Use this option only
with hiprof's PC-sampling profile data, and note that the
first few instructions of each instrumented procedure
includes the code that counted calls to that procedure.)
Suppresses the printing of a description of each field in
the profile. Limits those functions for which a callgraph
entry is printed to those functions specified in the
-f or -F options. By default, call graphs are printed for
all procedures in the tree of procedures called by the
selected procedures. Suppresses the printing of the graph
profile entry for routine and all its descendants (unless
they have other ancestors that are not suppressed). More
than one -e option may be given. Only one routine may be
given with each -e option. Suppresses the printing of the
graph profile entry for routine and its descendants (same
as -e), and also excludes the time spent in routine and
its descendants from the total and percentage time computations.
The library routines used to collect the profile
data are excluded by default (except for certain common
libpthread routines). Causes the profile for the named
executable or shared library not to be printed. You can
use this option multiple times in a single gprof command.
Prints the graph profile entry of only the specified routine
and its descendants. More than one -f option may be
given. Only one routine may be given with each -f option.
The -f option overrides the -e option. Prints the graph
profile entry of only routine and its descendants (same as
-f), and also uses only the times of the printed routines
in total time and percentage computations. More than one
-F option may be given. Only one routine may be given
with each -F option. The -F option overrides the -E
option. Profiles procedures as an indexed call graph
(default). Profiles source lines, listing the most heavily
used first. (Use this option only with hiprof's PCsampling
profile data.) Causes the profile for the named
shared library to be printed, in addition to the profile
for the executable. You can use this option multiple times
in a single gprof command. Changes the library directory
search order for shared object libraries so that gprof
looks for them in dir before the library recorded in profile_file
and the default library directories. You can
specify multiple -Ldir switches to specify several directory
names. Change the library directory search order for
shared object libraries so that gprof never looks for them
in the default library directories. Use this option when
the default library directories should not be searched and
only the directories specified by -Ldir are to be
searched. Profiles source lines, in order within selected
procedures. (Use this option only with hiprof's PC-sampling
profile data.) Produces a profile file with the
specified file name, which represents the sum of the profile
information contained in all the specified profile
files. Same as -s, except that -merge lets you specify the
name of the resulting profile file (rather than using the
default file name, gmon.sum). Also lets you use gmon.sum
as an input file. Regular profile reports are not printed
when -merge is specified. Prints each procedure's object
file name, source file name, and starting line number if
source file information is available from the object file.
Use this switch when the profiled program contains multiple
static procedures with the same name. In such cases,
the source and object file names uniquely identify each
procedure. Profiles procedures, listing the most heavily
used first (default). Produces a profile file, gmon.sum,
which represents the sum of the profile information in all
the specified profile files. This summary profile file may
be given to subsequent executions of gprof (probably also
with a -s) to accumulate profile data across several runs
of an a.out file. Scales all results into scientific
notation so that numbers that are either very small or
very large can be printed within the column boundaries.
Larger numbers lose very little precision to rounding off,
whereas smaller numbers gain precision. Prints cumulative
statistics for the entire object file instead of for each
procedure in the object. Prints the tool's version number.
Displays routines that have zero usage, as indicated
by call counts and accumulated time.
The gprof command produces an execution profile of programs.
The effect of called routines is incorporated into
the profile of each caller. Profile data of three kinds is
accepted by gprof: PC-sampling profiles of CPU time produced
by programs compiled with the -pg option of the cc
command PC-sampling profiles of CPU time produced by programs
instrumented by hiprof. Event-counting profiles of
CPU time or page faults produced by programs modified by
hiprof.
PC-Sampling with cc -pg [Toc] [Back]
The profile data is taken from one or more specified call
graph profile_files (gmon.out by default), created by programs
compiled with the -pg option with the cc driver command.
The -pg option also links in versions of the libc
and libm library routines compiled for profiling when your
program is linked by using the -non_shared option with the
cc command.
The gprof command fully profiles only the non-shared or
call-shared executable.
To produce call graph data, follow these steps: Compile
your program with the -pg option to the cc command. Execute
the program to produce a data file. Run gprof on the
data file.
The default "-graph" listing shows the functions sorted
according to the time they represent, including the time
of their call graph descendants. Below each function entry
is shown its (direct) call graph children, and how their
times are propagated to this function. A similar display
above the function estimates how this function's time and
the time of its descendants may be propagated to its
(direct) call graph parents, assuming that each call has
the same cost. Note that some procedures occur both
as children of other procedures and as spontaneous procedures.
A procedure with one or more parents is never
listed separately in the call graph display, even if sometimes
it is spontaneously generated. An index of the procedures
is also printed.
The default "-procedures" listing shows a flat profile
similar to that provided by prof. This listing gives the
total execution times and call counts for each of the
functions in the program, sorted by decreasing time.
To obtain call graph data on libraries, link your program
by using the -non_shared option with the cc command. To
disable profiling of a particular library, use the -no_pg
option when linking. For example, to enable call graph
profiling of your executable program, including library
routines, and then disable call graph profiling for a
library called mylib, link your program by using the following
command: % cc -non_shared -pg myprog -no_pg -lmylib
You can use environment variables to change the default
profiling behavior. The variables are PROFDIR and PROFFLAGS.
The general form for setting these variables is:
For C shell: setenv varname "value" For Bourne shell: varname
= "value"; export varname For Korn shell: export varname
= value
In the preceding example, varname can be one of the following:
This environment variable causes PC-sampling data
files to be generated with unique names in the directory
you specify.
You specify a directory path as the value and your
prof results are placed in the file path/pid.progname
where path is the pathname, pid is the process
ID of the executing program, and progname is the
program name. This environment variable can take
any of the following values: -threads causes a separate
data file to be generated for each thread.
The name of the data file takes the following form:
pid.sid.prog_name
The form of the filename resolves to pid as the
process ID of the program, sid as the sequence number
of the thread and prog_name as the name of the
program being profiled. -sigdump signal-name automatically
establishes monitor_signal(3) as the signal
handler for the named signal, and it causes
monitor_signal(3) to zero the profile after it is
written to a file. This allows a signal to be sent
several times without the successive profiles overlapping,
if the file is renamed. The asynchronous
nature of a signal may cause small variations in
the profile. Unrecognized signal-names are ignored.
The -threads option is ignored if combined with
-sigdump. -dirname directory specifies the directory
path in which the profiling data file or files
are created. -[no]pids [disables] or enables the
addition of the process-id number to the name of
the profiling data file or files.
You can use the PROFDIR and PROFFLAGS environment variables
together. For more information, see the Programmer's
Guide.
PC-Sampling Profiles with hiprof [Toc] [Back]
The profile data is taken from the specified call-graph
profile_file, created by a program that has been instrumented
in the default manner for the hiprof command. The
profile can cover all the libraries used by the threaded
or non-threaded program, and it can be displayed as the
time used by procedures, source lines, or instructions.
To produce and display PC-sampling data, see hiprof(1) for
one-step profiling, or follow these steps: Compile your
program using the required -O and -g levels. Use the
hiprof command to instrument the executable and any shared
libraries the program uses:
hiprof prog_name
For a multi-threaded program, specify the -pthread
option, or specify the -threads option to profile
each thread separately (but note that many
megabytes of memory and disk space may be used as a
result). The instrumented program is named
prog_name.hiprof by default. Run the instrumented
program to produce the profile data file(s), named
prog_name.hiout by default. Run gprof on the
instrumented executable (not the original): % gprof
-all -b -scaled prog_name.hiprof prog_name.hiout
The default -graph and -procedures profile displays
are the same as for PC-Sampling with cc -pg,
described previously.
To display profiles of the CPU time used by the
most expensive source lines, use the -heavy option:
% gprof -all -b -scaled -heavy prog_name.hiprof
prog_name.hiout
To display profiles of the lines or instructions in
particular procedures, specify -lines or -asm and
the procedures: % gprof -all -lines -asm -f main
prog_name.hiprof prog_name.hiout
Event-Counting Profiles with hiprof [Toc] [Back]
The profile data is taken from the specified call-graph
profile_file, created by programs that have been instrumented
with the -cycles or -faults option of the hiprof
command.
To produce and display event-counting data, see hiprof(1)
for one step profiling, or follow these steps: Compile
your program using the required -O and -g levels. For
multi-threaded programs you must use a different profiling
technique. Use the hiprof command to instrument the executable
and any shared libraries the program uses:
hiprof [-cycles|-faults] prog_name
Specify the -cycles option to count the number of
machine cycles used by each procedure. If instead
you want the number of page faults suffered by each
procedure, specify the -faults option. The instrumented
program is named prog_name.hiprof, by
default. Run the instrumented program to produce
the profile data file, named prog_name.hiout, by
default:
prog_name.hiprof [arg...] Run gprof on the original
executable and one or more profile data files,
specifying any required options other than -E and
-F, which are not meaningful with hiprof's eventcounting
call data:
gprof [options] program program*.hiout
The gprof command produces a report with the following
sections: A call-graph profile, showing the procedures
that call each procedure and the procedures it calls,
including the number of calls and instructions, seconds,
or page-faults involved in them. The costs of the calls
printed in this report are individually measured, rather
than being statistically estimated like in reports based
on PC-sampling data. A flat profile showing the instructions,
seconds, or page-faults associated with each procedure.
An index of procedures sorted by name, including
object, source file, and line number if -numbers is specified.
The hiprof data files profile the executable and all the
shared libraries used by a call-shared program. By
default, gprof prints call-graph and flat profile entries
only for the procedures in the executable, though the number
and cost of calls to shared library procedures are
printed in the call-graph. Specify the -incobj or -all
options to see entries for procedures in some or all of
the shared libraries.
Be aware of possible quantization errors when using gprof
with PC-sampling profile data files. The granularity of
the sampling is shown, but remains statistical at best.
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 parents of that function is
directly proportional to the number of times that arc is
traversed. Parents that are not themselves profiled have
the time of their profiled children propagated to them,
but appear to be spontaneously invoked in the call graph
listing; they do not have their time propagated further.
Similarly, signal catchers, even though profiled, appear
to be spontaneous. 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 propagation cannot occur.
The profiled program must call exit or return normally for
the profiling information to be saved in the gmon.out
file, unless -sigdump and kill are used to save the profile
early. A threaded program that is linked -non_shared
will appear to spend a large proportion of its time in
pthread_mutex_unlock, pthread_mutex_lock, pthread_getspecific,
and other threads-related procedures that have no
calls recorded, when using PC-sampling data. While the
application code may be using these routines, much or all
of the reported time is actually used by the profile data
collection library's use of them, so it can usually be
ignored.
If a PC-sampling program makes more procedure calls than
can be recorded, the error "Arc limit exceeded" will
occur. The program will continue to execute to completion,
but some call-arc information will be lost. A possible
work-around for this problem is to reduce the portion
of the program that is profiled using the monstartup()
routine. See monitor(3) for more information.
Default object file Default (PC-sampling) call graph and
profile Default summarized dynamic call graph and profile
Profiling data file produced by hiprof-generated program
Introduction: prof_intro(1)
Commands: prof(1), hiprof(1), dxprof(1). (dxprof(1) is
available as an option.)
Functions: profil(2), monitor(3)
Programmer's Guide
gprof: A Call Graph Execution Profiler, by Graham, S.L.,
Kessler, P.B., McKusick, M.K.
Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
SIGPLAN Notices, Vol. 17, No. 6, pp. 120-126,
June 1982.
gprof(1)
[ Back ] |
