gprof(1) General Commands Manual gprof(1)
NAME
gprof - Displays call-graph profile data
SYNOPSIS
gprof [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
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.
OPTIONS
For each gprof option, you need type only enough of the name to distinguish it from the other options. Suppresses the printing of stati-
cally 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 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 sup-
pressed). 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 PC-sampling 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 direc-
tories. 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 directo-
ries 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 mul-
tiple 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.
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: 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 follow-
ing 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: 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 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
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 chil-
dren 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.
ERRORS
If a PC-sampling program makes more procedure calls than can be recorded, the error "Arc limit exceeded" will occur. The program will con-
tinue 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 pro-
duced by hiprof-generated program
SEE ALSO
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)