 |
Index for
Section 1 |
|
 |
Alphabetical
listing for G |
|
 |
Bottom of
page |
|
gprof(1)
NAME
gprof - Displays call-graph profile data
SYNOPSIS
gprof [options] prog_name [profile_file...]
OPERANDS
prog_name
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.
profile_file
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 distinguish
it from the other options.
-a 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.
-all
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.
-asm
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.)
-b Suppresses the printing of a description of each field in the profile.
-bounded
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.
-e routine
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.
-E routine
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).
-excobj object_file_name
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.
-f routine
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.
-F routine
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.
-graph
Profiles procedures as an indexed call graph (default).
-heavy
Profiles source lines, listing the most heavily used first. (Use this
option only with hiprof's PC-sampling profile data.)
-incobj object_file_name
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.
-Ldir
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.
-L 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.
-lines
Profiles source lines, in order within selected procedures. (Use this
option only with hiprof's PC-sampling profile data.)
-merge filename
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.
-numbers
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.
-procedures
Profiles procedures, listing the most heavily used first (default).
-s 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.
-scaled
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.
-totals
Prints cumulative statistics for the entire object file instead of for
each procedure in the object.
-version
Prints the tool's version number.
-z Displays routines 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 instrumented 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
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:
1. Compile your program with the -pg option to the cc command.
2. Execute the program to produce a data file.
3. 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:
PROFDIR
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.
PROFFLAGS
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
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:
1. Compile your program using the required -O and -g levels.
2. 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.
3. Run the instrumented program to produce the profile data file(s),
named prog_name.hiout by default.
4. 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:
1. Compile your program using the required -O and -g levels. For multi-
threaded programs you must use a different profiling technique.
2. 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.
3. Run the instrumented program to produce the profile data file, named
prog_name.hiout, by default:
prog_name.hiprof [arg...]
4. 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
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.
NOTES
1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
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 portion of the
program that is profiled using the monstartup() routine. See monitor(3) for
more information.
FILES
a.out
Default object file
gmon.out
Default (PC-sampling) call graph and profile
gmon.sum
Default summarized dynamic call graph and profile
program[.pid][.thread].hiout
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, SIGPLAN
Notices, Vol. 17, No. 6, pp. 120-126, June 1982.
|
Index for
Section 1 |
|
|
Alphabetical
listing for G |
|
 |
Top of
page |
|