gprof(1)gprof(1)NAMEgprof - Displays call-graph profile data
SYNOPSISgprof [options] prog_name [profile_file...]
OPERANDS
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 informa‐
tion, 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.
OPTIONS
For each gprof option, you need type only enough of the name to distin‐
guish 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 instruc‐
tions 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 call-
graph 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 computa‐
tions. 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 com‐
mand. Prints the graph profile entry of only the specified routine and
its descendants. More than one -f option may be given. Only one rou‐
tine may be given with each -f option. The -f option overrides the -e
option. Prints the graph profile entry of only routine and its descen‐
dants (same as -f), and also uses only the times of the printed rou‐
tines 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 PC-sam‐
pling 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 direc‐
tory 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 direc‐
tories 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 informa‐
tion 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 pro‐
gram contains multiple static procedures with the same name. In such
cases, the source and object file names uniquely identify each proce‐
dure. 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 cumu‐
lative statistics for the entire object file instead of for each proce‐
dure in the object. Prints the tool's version number. Displays rou‐
tines that have zero usage, as indicated by call counts and accumulated
time.
DESCRIPTION
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 instru‐
mented by hiprof. Event-counting profiles of CPU time or page faults
produced by programs modified by hiprof.
PC-Sampling with cc -pg
The profile data is taken from one or more specified call graph pro‐
file_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 descen‐
dants. Below each function entry is shown its (direct) call graph chil‐
dren, 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 spon‐
taneous 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 par‐
ticular 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 path‐
name, pid is the process ID of the executing program, and prog‐
name 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_sig‐
nal(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
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
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 event-counting 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 instruc‐
tions, 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 speci‐
fied.
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 exe‐
cutable, though the number and cost of calls to shared library proce‐
dures 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.
NOTES
Be aware of possible quantization errors when using gprof with PC-sam‐
pling 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 num‐
ber of times the function is called; thus, the time propagated along
the call graph arcs to parents of that function is directly propor‐
tional to the number of times that arc is traversed. Parents that are
not themselves profiled have the time of their profiled children propa‐
gated 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 pro‐
file data collection library's use of them, so it can usually be
ignored.
ERRORS
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 por‐
tion of the program that is profiled using the monstartup() routine.
See monitor(3) for more information.
FILES
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
SEE ALSO
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, SIG‐
PLAN Notices, Vol. 17, No. 6, pp. 120-126, June 1982.
gprof(1)
