*** UNIX MANUAL PAGE BROWSER ***

gprof(1) General Commands Manual 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 distin- guish 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 func- tions specified in the -f or -F options. By default, call graphs are printed for all procedures in the tree of procedures called by the se- lected 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 over- rides 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 direc- tory 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 direc- tories 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 cumu- lative statistics for the entire object file instead of for each proce- dure in the object. Displays routines that have zero usage, as indi- cated by call counts and accumulated time. OPERANDS 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 pro- filing 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. 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-sam- pling 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: 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 execu- tion 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, in- cluding 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 mem- bers 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 par- ticular library, use the -no_pg option when linking. For example, to enable call graph profiling of your executable program, including li- brary 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 be- havior. 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 en- vironment 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 path- name, pid is the process ID of the executing program, and prog- name 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 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 prog- name as the name of the program being profiled. -sigdump sig- nal-name automatically establishes monitor_signal(3) as the sig- nal handler for the named signal, and it causes monitor_sig- nal(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 out- put shows the sum of the profile information in the given profile files. To produce call-graph data follow these steps: Compile your program us- ing 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): program.hiprof[.threads] [arg...] Run gprof on the original ex- ecutable and one or more data files, specifying any required op- tions 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 de- scription 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 mea- sured, 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 asso- ciated with each procedure. An index of procedures sorted by name, in- cluding object, source file, and line number if -numbers is specified. The hiprof data files profile the executable and all the shared li- braries used by a call-shared program. By default, gprof prints call- graph and flat profile entries only for the procedures in the exe- cutable, though the number and cost of calls to shared library proce- dures are printed in the call-graph. Specify the -incobj or -all op- tions to see entries for procedures in some or all of the shared li- braries. NOTES Be aware of possible quantization errors when using gprof with PC-sam- pling 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 num- ber of times the function is called; thus, the time propagated along the call graph arcs to parents of that function is directly propor- tional to the number of times that arc is traversed. Parents that are not themselves profiled have the time of their profiled children propa- gated 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 pro- file data collection library's use of them, so it can usually be ig- nored. 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 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 De- fault summarized dynamic call graph and profile Profiling data file produced by hiprof-generated program SEE ALSO Commands: prof(1), atom(1), dxprof(1). ( dxprof(1) is available only if the Developer's Tool Kit and associated reference pages are in- stalled on your system.) 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, SIG- PLAN Notices, Vol. 17, No. 6, pp. 120-126, June 1982. gprof(1)