NAME

gprof - Displays pc-sampling or hiprof call graph profile data

SYNOPSIS

gprof [ options ]

PARAMETERS

prog_nameName of the program executable to be profiled.  This program should be compiled with the −g1, −g2, or −g3 flag 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. 

FLAGS

For each prof option, you need type only enough of the name to distinguish it from the other options. 

-aSuppresses the printing of statically declared functions.  If this flag 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. 

−allCauses 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. 

-bSuppresses the printing of a description of each field in the profile. 

-boundedLimits those functions for which a call-graph entry is printed to those functions specified in the −f or −F flags.  By default, call graphs are printed for all procedures in the tree of procedures called by the selected procedures. 

-e routineSuppresses 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 flag may be given.  Only one routine may be given with each -e flag. 

-E routineSuppresses 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 flag multiple times in a single gprof command. 

-f routinePrints the graph profile entry of only the specified routine and its descendants.  More than one -f flag may be given.  Only one routine may be given with each -f flag.  The -f flag overrides the -e flag. 

-F routinePrints 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 flag may be given.  Only one routine may be given with each -F flag.  The -F flag overrides the -E flag. 

−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 flag multiple times in a single gprof command. 

−LdirChanges 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. 

−LChange 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. 

-numbersPrints 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. 

-sProduces 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. 

−totalsPrints cumulative statistics for the entire object file instead of for each procedure in the object. 

-zDisplays 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 from either of two sources is accepted by gprof:

       •PC-sampling profiles produced by programs compiled with the −pg flag 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 flag with the cc driver command.  The -pg flag also links in versions of the libc and libm library routines compiled for profiling when your program is linked by using the −non_shared flag with the cc command. 

gprof fully profiles only the nonshared 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 flag with cc command. To disable profiling of a library, use the −no_pg flag when linking. For example, to enable call graph profiling of your executable program and then disable call graph profiling for system supplied libraries, such as libc, link your program by using the following command:

   % cc -non_shared -pg myprog -no_pg

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. 

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 flags other than −E and −F, which are not meaningful with hiprof’s nonstatistical call data:

gprof [flags] 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 flag). 

       •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 or 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 flags 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. 

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.outDefault object file

gmon.outDefault (PC-sampling) call graph and profile

gmon.sumSummarized dynamic call graph and profile

program[.pid][.thread].hiout
Profiling data file produced by hiprof-generated program

RELATED INFORMATION

Programmer’s Guide

Commands:  prof(1), atom(1), dxprof(1) (dxprof(1) is available only if the Developer’s Tool Kit and associated reference pages are installed on your system.) 

Atom Tools: hiprof(5)

Functions:  profil(2), monitor(3). 

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.