Content-type: text/html
gprof - Displays pc-sampling or hiprof call graph profile data
gprof [options] prog_name profile_file [...]
For each
prof
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.
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 computations. (For example,
_gprof_mcount -E _gprof_monstop
is the default.)
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.
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.
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.
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.
Displays routines that have zero usage, as indicated by call
counts and accumulated time.
Name of the program executable to be profiled. The program
should be compiled with the
-pg
option so that, when executed,
it will produce a profile file (named
gmon.out, by default).
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 (produced by executing a program that was compiled with the
-pg
option) or an instrumented profile file (produced by executing
a program that was instrumented by an
atom -tool hiprof
command). 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.
The
gprof
command produces an execution profile of
programs. The effect of called routines is incorporated into the profile of
each caller. Profile data from either of two sources is accepted by
gprof:
PC-sampling profiles produced by programs compiled with the
-pg
option of the
cc
command
Instrumented profiles produced by programs modified by an
atom -tool hiprof
command.
The profile data is taken from the specified call graph profile_file (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 program.
The gprof profiling tool reads the symbol table in the specified prog_name (a.out by default), correlating it with the call profile file. If more than one profile_file is specified, gprof output shows the sum of the profile information in the given profile files.
To produce call graph data, follow these steps: Compile your program with the -pg switch to the cc command. Execute the program to produce a data file. Run gprof on the data file.
The gprof command produces three items: First, a flat profile is given, 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. Next, these execution 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. A second listing shows the functions sorted according to the time they represent, including the time of their call graph descendents. 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 shows how this function's time and the time of its descendents are propagated to its (direct) call graph parents. Lastly, cycles are also shown, with an entry for the cycle as a whole and a listing of the members of the cycle and their contributions to the time and call counts of the cycle.
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 can use the
PROFDIR
and
PROFFLAGS
environment variables
together. For more information, see the
Programmer's Guide.
The profile data is taken from the specified call-graph profile_file, created by programs that have been instrumented by the atom -tool hiprof command. If more than one profile_file is specified, gprof output shows the sum of the profile information in the given profile files.
To produce call-graph data follow these steps: Compile your program using the required -O and -g levels. Use the atom command to instrument the executable and any shared libraries the program uses, specifying -toolargs=-cputime or -toolargs=-pagefaults if instruction counts are not required, and specifying -env threads for a multithreaded program. Run the instrumented program to produce one profile data file or one file per thread, having defined the optional HIPROF_ARGS environment variable, if desired, as described in hiprof(5):
The gprof command produces a report with the following sections: A description of each field in the call-graph profile (can be suppressed with the -b option). 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 description of each field in the flat profile. 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.
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
Commands: prof(1), atom(1), dxprof(1). (dxprof(1) is available as an option.)
AtomTools: hiprof(5)
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.