 |
Index for Section 1 |
|
 |
Alphabetical listing for G |
|
gprof(1)
NAME
gprof - Displays pc-sampling or hiprof call graph profile data
SYNOPSIS
gprof [options] prog_name profile_file [...]
OPTIONS
For each prof 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.
-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.
(For example, _gprof_mcount -E _gprof_monstop is the default.)
-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.
-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.
-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.
-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.
-z Displays routines that have zero usage, as indicated by call counts and
accumulated time.
OPERANDS
prog_name
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.
profile_file
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.
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 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.
PC-Sampling
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:
1. Compile your program with the -pg switch to the cc command.
2. Execute the program to produce a data file.
3. Run gprof on the data file.
The gprof command produces three items:
1. 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.
2. 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.
3. 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:
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.progname
The form of the filename resolves to pid as the process ID of the
program, sid as the sequence number of the thread and progname 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.
Instrumented Profiles
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:
1. Compile your program using the required -O and -g levels.
2. 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.
3. 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):
program.hiprof[.threads] [arg...]
4. Run gprof on the original executable and one or more data files,
specifying any required options other than -E and -F, which are not
meaningful with hiprof's nonstatistical call data:
gprof [options] program program*.hiout
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.
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.
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
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.