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