1.\" Copyright (c) 1983, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.Dd November 27, 2017 29.Dt GPROF 1 30.Os 31.Sh NAME 32.Nm gprof 33.Nd display call graph profile data 34.Sh SYNOPSIS 35.Nm 36.Op Fl abKlLsuz 37.Op Fl C Ar count 38.Op Fl e Ar name 39.Op Fl E Ar name 40.Op Fl f Ar name 41.Op Fl F Ar name 42.Op Fl k Ar fromname toname 43.Op Ar a.out Op Ar a.out.gmon ... 44.Sh DESCRIPTION 45The 46.Nm 47utility produces an execution profile of C, Pascal, or Fortran77 programs. 48The effect of called routines is incorporated in the profile of each caller. 49The profile data is taken from the call graph profile file 50which is created by programs that are compiled with the 51.Fl pg 52option of 53.Xr cc 1 , 54.Xr pc 1 , 55and 56.Xr f77 1 . 57The 58.Fl pg 59option also links in versions of the library routines 60that are compiled for profiling. 61By convention these libraries have their name suffixed with 62.Pa _p , 63i.e., the profiled version of 64.Pa libc.a 65is 66.Pa libc_p.a 67and if you specify libraries directly to the 68compiler or linker you can use 69.Fl l Ns Ar c_p 70instead of 71.Fl l Ns Ar c . 72Read the given object file (the default is 73.Pa a.out ) 74and establishes the relation between its symbol table 75and the call graph profile. 76The default graph profile file name is the name 77of the executable with the suffix 78.Pa .gmon 79appended. 80If more than one profile file is specified, 81the 82.Nm 83output shows the sum of the profile information in the given profile files. 84.Pp 85The 86.Nm 87utility calculates the amount of time spent in each routine. 88Next, these times are propagated along the edges of the call graph. 89Cycles are discovered, and calls into a cycle are made to share the time 90of the cycle. 91The first listing shows the functions 92sorted according to the time they represent 93including the time of their call graph descendants. 94Below each function entry is shown its (direct) call graph children, 95and how their times are propagated to this function. 96A similar display above the function shows how this function's time and the 97time of its descendants is propagated to its (direct) call graph parents. 98.Pp 99Cycles are also shown, with an entry for the cycle as a whole and 100a listing of the members of the cycle and their contributions to the 101time and call counts of the cycle. 102.Pp 103Second, a flat profile is given, 104similar to that provided by 105.Xr prof 1 . 106This listing gives the total execution times, the call counts, 107the time that the call spent in the routine itself, and 108the time that the call spent in the routine itself including 109its descendants. 110The units for the per-call times are normally milliseconds, 111but they are nanoseconds if the profiling clock frequency 112is 10 million or larger, 113and if a function appears to be never called then its total self time 114is printed as a percentage in the self time per call column. 115The very high profiling clock frequencies needed to get sufficient 116accuracy in the per-call times for short-lived programs are only 117implemented for 118.Dq high resolution 119(non-statistical) kernel profiling. 120.Pp 121Finally, an index of the function names is provided. 122.Pp 123The following options are available: 124.Bl -tag -width indent 125.It Fl a 126Suppress the printing of statically declared functions. 127If this option is given, all relevant information about the static function 128(e.g., time samples, calls to other functions, calls from other functions) 129belongs to the function loaded just before the static function in the 130.Pa a.out 131file. 132.It Fl b 133Suppress the printing of a description of each field in the profile. 134.It Fl C Ar count 135Find a minimal set of arcs that can be broken to eliminate all cycles with 136.Ar count 137or more members. 138Caution: the algorithm used to break cycles is exponential, 139so using this option may cause 140.Nm 141to run for a very long time. 142.It Fl e Ar name 143Suppress the printing of the graph profile entry for routine 144.Ar name 145and all its descendants 146(unless they have other ancestors that are not suppressed). 147More than one 148.Fl e 149option may be given. 150Only one 151.Ar name 152may be given with each 153.Fl e 154option. 155.It Fl E Ar name 156Suppress the printing of the graph profile entry for routine 157.Ar name 158(and its descendants) as 159.Fl e , 160above, and also excludes the time spent in 161.Ar name 162(and its descendants) from the total and percentage time computations. 163(For example, 164.Fl E 165.Ar mcount 166.Fl E 167.Ar mcleanup 168is the default.) 169.It Fl f Ar name 170Print the graph profile entry of only the specified routine 171.Ar name 172and its descendants. 173More than one 174.Fl f 175option may be given. 176Only one 177.Ar name 178may be given with each 179.Fl f 180option. 181.It Fl F Ar name 182Print the graph profile entry of only the routine 183.Ar name 184and its descendants (as 185.Fl f , 186above) and also uses only the times of the printed routines 187in total time and percentage computations. 188More than one 189.Fl F 190option may be given. 191Only one 192.Ar name 193may be given with each 194.Fl F 195option. 196The 197.Fl F 198option 199overrides 200the 201.Fl E 202option. 203.It Fl k Ar fromname Ar toname 204Will delete any arcs from routine 205.Ar fromname 206to routine 207.Ar toname . 208This can be used to break undesired cycles. 209More than one 210.Fl k 211option may be given. 212Only one pair of routine names may be given with each 213.Fl k 214option. 215.It Fl K 216Gather information about symbols from the currently-running kernel using the 217.Xr sysctl 3 218and 219.Xr kldsym 2 220interfaces. 221This forces the 222.Pa a.out 223argument to be ignored, and allows for symbols in 224.Xr kld 4 225modules to be used. 226.It Fl l 227Suppress the printing of the call-graph profile. 228.It Fl L 229Suppress the printing of the flat profile. 230.It Fl s 231A profile file 232.Pa gmon.sum 233is produced that represents 234the sum of the profile information in all the specified profile files. 235This summary profile file may be given to later 236executions of gprof (probably also with a 237.Fl s ) 238to accumulate profile data across several runs of an 239.Pa a.out 240file. 241.It Fl u 242Suppress the printing of functions whose names are not visible to 243C programs. 244For the ELF object format, this means names that 245contain the 246.Ql .\& 247character. 248For the a.out object format, it means names that do not 249begin with a 250.Ql _ 251character. 252All relevant information about such functions belongs to the 253(non-suppressed) function with the next lowest address. 254This is useful for eliminating "functions" that are just labels 255inside other functions. 256.It Fl z 257Display routines that have zero usage (as shown by call counts 258and accumulated time). 259.El 260.Sh FILES 261.Bl -tag -width a.out.gmon -compact 262.It Pa a.out 263The namelist and text space. 264.It Pa a.out.gmon 265Dynamic call graph and profile. 266.It Pa gmon.sum 267Summarized dynamic call graph and profile. 268.El 269.Sh SEE ALSO 270.Xr cc 1 , 271.Xr profil 2 , 272.Xr clocks 7 , 273.Xr pmcstat 8 274.\" .Xr monitor 3 , 275.\" .Xr prof 1 276.Rs 277.%T "An Execution Profiler for Modular Programs" 278.%A S. Graham 279.%A P. Kessler 280.%A M. McKusick 281.%J "Software - Practice and Experience" 282.%V 13 283.%P pp. 671-685 284.%D 1983 285.Re 286.Rs 287.%T "gprof: A Call Graph Execution Profiler" 288.%A S. Graham 289.%A P. Kessler 290.%A M. McKusick 291.%J "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices" 292.%V 17 293.%N 6 294.%P pp. 120-126 295.%D June 1982 296.Re 297.Sh HISTORY 298The 299.Nm 300profiler 301appeared in 302.Bx 4.2 . 303.Sh BUGS 304The granularity of the sampling is shown, but remains 305statistical at best. 306We assume that the time for each execution of a function 307can be expressed by the total time for the function divided 308by the number of times the function is called. 309Thus the time propagated along the call graph arcs to the function's 310parents is directly proportional to the number of times that 311arc is traversed. 312.Pp 313Parents that are not themselves profiled will have the time of 314their profiled children propagated to them, but they will appear 315to be spontaneously invoked in the call graph listing, and will 316not have their time propagated further. 317Similarly, signal catchers, even though profiled, will appear 318to be spontaneous (although for more obscure reasons). 319Any profiled children of signal catchers should have their times 320propagated properly, unless the signal catcher was invoked during 321the execution of the profiling routine, in which case all is lost. 322.Pp 323The profiled program must call 324.Xr exit 3 325or return normally for the profiling information to be saved 326in the graph profile file. 327