1.\" Copyright (c) 1983, 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)gprof.1 6.7 (Berkeley) 03/14/91 7.\" 8.Vx 9.Vx 10.Dd 11.Dt GPROF 1 12.Os BSD 4.2 13.Sh NAME 14.Nm gprof 15.Nd display call graph profile data 16.Sh SYNOPSIS 17.Nm gprof 18.Op options 19.Op Ar a.out Op Ar gmon.out ... 20.Sh DESCRIPTION 21.Nm gprof 22produces an execution profile of C, Pascal, or Fortran77 programs. 23The effect of called routines is incorporated in the profile of each caller. 24The profile data is taken from the call graph profile file 25.Pf \&( Pa gmon.out 26default) which is created by programs 27that are compiled with the 28.Fl pg 29option of 30.Xr cc 1 , 31.Xr pc 1 , 32and 33.Xr f77 1 . 34The 35.Fl pg 36option also links in versions of the library routines 37that are compiled for profiling. 38.Nm Gprof 39reads the given object file (the default is 40.Pa a.out) 41and establishes the relation between it's symbol table 42and the call graph profile from 43.Pa gmon.out . 44If more than one profile file is specified, 45the 46.Nm gprof 47output shows the sum of the profile information in the given profile files. 48.Pp 49.Nm Gprof 50calculates the amount of time spent in each routine. 51Next, these times are propagated along the edges of the call graph. 52Cycles are discovered, and calls into a cycle are made to share the time 53of the cycle. 54The first listing shows the functions 55sorted according to the time they represent 56including the time of their call graph descendents. 57Below each function entry is shown its (direct) call graph children, 58and how their times are propagated to this function. 59A similar display above the function shows how this function's time and the 60time of its descendents is propagated to its (direct) call graph parents. 61.Pp 62Cycles are also shown, with an entry for the cycle as a whole and 63a listing of the members of the cycle and their contributions to the 64time and call counts of the cycle. 65.Pp 66Second, a flat profile is given, 67similar to that provided by 68.Xr prof 1 . 69This listing gives the total execution times, the call counts, 70the time in milleseconds the call spent in the routine itself, and 71the time in milleseconds the call spent in the routine itself including 72its descendents. 73.Pp 74Finally, an index of the function names is provided. 75.Pp 76The following options are available: 77.Tw Fl 78.Tp Fl a 79suppresses the printing of statically declared functions. 80If this option is given, all relevant information about the static function 81(e.g., time samples, calls to other functions, calls from other functions) 82belongs to the function loaded just before the static function in the 83.Pa a.out 84file. 85.Tp Fl b 86suppresses the printing of a description of each field in the profile. 87.Tp Fl c 88the static call graph of the program is discovered by a heuristic 89that examines the text space of the object file. 90Static-only parents or children are shown 91with call counts of 0. 92.Tc Fl e 93.Ws 94.Ar name 95.Cx 96suppresses the printing of the graph profile entry for routine 97.Ar name 98and all its descendants 99(unless they have other ancestors that aren't suppressed). 100More than one 101.Fl e 102option may be given. 103Only one 104.Ar name 105may be given with each 106.Fl e 107option. 108.Tc Fl E 109.Ws 110.Ar name 111.Cx 112suppresses the printing of the graph profile entry for routine 113.Ar name 114(and its descendants) as 115.Fl e , 116above, and also excludes the time spent in 117.Ar name 118(and its descendants) from the total and percentage time computations. 119(For example, 120.Fl E 121.Ar mcount 122.Fl E 123.Ar mcleanup 124is the default.) 125.Tc Fl f 126.Ws 127.Ar name 128.Cx 129prints the graph profile entry of only the specified routine 130.Ar name 131and its descendants. 132More than one 133.Fl f 134option may be given. 135Only one 136.Ar name 137may be given with each 138.Fl f 139option. 140.Tc Fl F 141.Ws 142.Ar name 143.Cx 144prints the graph profile entry of only the routine 145.Ar name 146and its descendants (as 147.Fl f , 148above) and also uses only the times of the printed routines 149in total time and percentage computations. 150More than one 151.Fl F 152option may be given. 153Only one 154.Ar name 155may be given with each 156.Fl F 157option. 158The 159.Fl F 160option 161overrides 162the 163.Fl E 164option. 165.Tc Fl k 166.Ws 167.Ar fromname 168.Ws 169.Ar toname 170.Cx 171will delete any arcs from routine 172.Ar fromname 173to routine 174.Ar toname . 175This can be used to break undesired cycles. 176More than one 177.Fl k 178option may be given. 179Only one pair of routine names may be given with each 180.Fl k 181option. 182.Tp Fl s 183a profile file 184.Pa gmon.sum 185is produced that represents 186the sum of the profile information in all the specified profile files. 187This summary profile file may be given to later 188executions of gprof (probably also with a 189.Fl s ) 190to accumulate profile data across several runs of an 191.Pa a.out 192file. 193.Tp Fl z 194displays routines that have zero usage (as shown by call counts 195and accumulated time). 196This is useful with the 197.Fl c 198option for discovering which routines were never called. 199.Tp 200.Sh FILES 201.Dw gmon.sum 202.Di L 203.Dp Pa a.out 204the namelist and text space. 205.Dp Pa gmon.out 206dynamic call graph and profile. 207.Dp Pa gmon.sum 208summarized dynamic call graph and profile. 209.Dp 210.Sh SEE ALSO 211.Xr monitor 3 , 212.Xr profil 2 , 213.Xr cc 1 , 214.Xr prof 1 215.br 216.Em An Execution Profiler for Modular Programs , 217by 218S. Graham, P. Kessler, M. McKusick; 219Software - Practice and Experience, 220Vol. 13, pp. 671-685, 1983. 221.br 222.Em gprof: A Call Graph Execution Profiler , 223by S. Graham, P. Kessler, M. McKusick; 224Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, 225SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, June 1982. 226.Sh HISTORY 227.Nm Gprof 228appeared in 4.2 BSD. 229.Sh BUGS 230The granularity of the sampling is shown, but remains 231statistical at best. 232We assume that the time for each execution of a function 233can be expressed by the total time for the function divided 234by the number of times the function is called. 235Thus the time propagated along the call graph arcs to the function's 236parents is directly proportional to the number of times that 237arc is traversed. 238.Pp 239Parents that are not themselves profiled will have the time of 240their profiled children propagated to them, but they will appear 241to be spontaneously invoked in the call graph listing, and will 242not have their time propagated further. 243Similarly, signal catchers, even though profiled, will appear 244to be spontaneous (although for more obscure reasons). 245Any profiled children of signal catchers should have their times 246propagated properly, unless the signal catcher was invoked during 247the execution of the profiling routine, in which case all is lost. 248.Pp 249The profiled program must call 250.Xr exit 2 251or return normally for the profiling information to be saved 252in the 253.Pa gmon.out 254file. 255