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. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" @(#)gprof.1 8.1 (Berkeley) 6/6/93 33.\" $FreeBSD$ 34.\" 35.Dd June 6, 1993 36.Dt GPROF 1 37.Os BSD 4.2 38.Sh NAME 39.Nm gprof 40.Nd display call graph profile data 41.Sh SYNOPSIS 42.Nm 43.Op options 44.Op Ar a.out Op Ar a.out.gmon ... 45.Sh DESCRIPTION 46.Nm Gprof 47produces 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. 61.Nm Gprof 62reads the given object file (the default is 63.Pa a.out) 64and establishes the relation between it's symbol table 65and the call graph profile. 66The default graph profile file name is the name 67of the executable with the suffix 68.Pa .gmon 69appended. 70If more than one profile file is specified, 71the 72.Nm 73output shows the sum of the profile information in the given profile files. 74.Pp 75.Nm Gprof 76calculates the amount of time spent in each routine. 77Next, these times are propagated along the edges of the call graph. 78Cycles are discovered, and calls into a cycle are made to share the time 79of the cycle. 80The first listing shows the functions 81sorted according to the time they represent 82including the time of their call graph descendents. 83Below each function entry is shown its (direct) call graph children, 84and how their times are propagated to this function. 85A similar display above the function shows how this function's time and the 86time of its descendents is propagated to its (direct) call graph parents. 87.Pp 88Cycles are also shown, with an entry for the cycle as a whole and 89a listing of the members of the cycle and their contributions to the 90time and call counts of the cycle. 91.Pp 92Second, a flat profile is given, 93similar to that provided by 94.Xr prof 1 . 95This listing gives the total execution times, the call counts, 96the time in msec or usec the call spent in the routine itself, and 97the time in msec or usec the call spent in the routine itself including 98its descendents. 99.Pp 100Finally, an index of the function names is provided. 101.Pp 102The following options are available: 103.Bl -tag -width Fl 104.It Fl a 105Suppresses the printing of statically declared functions. 106If this option is given, all relevant information about the static function 107(e.g., time samples, calls to other functions, calls from other functions) 108belongs to the function loaded just before the static function in the 109.Pa a.out 110file. 111.It Fl b 112Suppresses the printing of a description of each field in the profile. 113.It Fl c 114The static call graph of the program is discovered by a heuristic 115that examines the text space of the object file. 116Static-only parents or children are shown 117with call counts of 0. 118This option is not supported on some architectures. 119.It Fl C Ar count 120Find a minimal set of arcs that can be broken to eliminate all cycles with 121.Ar count 122or more members. 123Caution: the algorithm used to break cycles is exponential, 124so using this option may cause 125.Nm 126to run for a very long time. 127.It Fl e Ar name 128Suppresses the printing of the graph profile entry for routine 129.Ar name 130and all its descendants 131(unless they have other ancestors that aren't suppressed). 132More than one 133.Fl e 134option may be given. 135Only one 136.Ar name 137may be given with each 138.Fl e 139option. 140.It Fl E Ar name 141Suppresses the printing of the graph profile entry for routine 142.Ar name 143(and its descendants) as 144.Fl e , 145above, and also excludes the time spent in 146.Ar name 147(and its descendants) from the total and percentage time computations. 148(For example, 149.Fl E 150.Ar mcount 151.Fl E 152.Ar mcleanup 153is the default.) 154.It Fl f Ar name 155Prints the graph profile entry of only the specified routine 156.Ar name 157and its descendants. 158More than one 159.Fl f 160option may be given. 161Only one 162.Ar name 163may be given with each 164.Fl f 165option. 166.It Fl F Ar name 167Prints the graph profile entry of only the routine 168.Ar name 169and its descendants (as 170.Fl f , 171above) and also uses only the times of the printed routines 172in total time and percentage computations. 173More than one 174.Fl F 175option may be given. 176Only one 177.Ar name 178may be given with each 179.Fl F 180option. 181The 182.Fl F 183option 184overrides 185the 186.Fl E 187option. 188.It Fl k Ar fromname Ar toname 189Will delete any arcs from routine 190.Ar fromname 191to routine 192.Ar toname . 193This can be used to break undesired cycles. 194More than one 195.Fl k 196option may be given. 197Only one pair of routine names may be given with each 198.Fl k 199option. 200.It Fl l 201Suppresses the printing of the call-graph profile. 202.It Fl L 203Suppresses the printing of the flat profile. 204.It Fl s 205A profile file 206.Pa gmon.sum 207is produced that represents 208the sum of the profile information in all the specified profile files. 209This summary profile file may be given to later 210executions of gprof (probably also with a 211.Fl s ) 212to accumulate profile data across several runs of an 213.Pa a.out 214file. 215.It Fl u 216Suppresses the printing of functions whose names are not visible to 217C programs. For the ELF object format, this means names that 218contain the 219.Ql .\& 220character. For the a.out object format, it means names that do not 221begin with a 222.Ql _ 223character. 224All relevant information about such functions belongs to the 225(non-suppressed) function with the next lowest address. 226This is useful for eliminating "functions" that are just labels 227inside other functions. 228.It Fl z 229Displays routines that have zero usage (as shown by call counts 230and accumulated time). 231This is useful with the 232.Fl c 233option for discovering which routines were never called. 234.El 235.Sh FILES 236.Bl -tag -width a.out.gmon -compact 237.It Pa a.out 238The namelist and text space. 239.It Pa a.out.gmon 240Dynamic call graph and profile. 241.It Pa gmon.sum 242Summarized dynamic call graph and profile. 243.El 244.Sh SEE ALSO 245.Xr cc 1 , 246.Xr profil 2 , 247.Xr clocks 7 248.\" .Xr monitor 3 , 249.\" .Xr prof 1 250.Rs 251.%T "An Execution Profiler for Modular Programs" 252.%A S. Graham 253.%A P. Kessler 254.%A M. McKusick 255.%J "Software - Practice and Experience" 256.%V 13 257.%P pp. 671-685 258.%D 1983 259.Re 260.Rs 261.%T "gprof: A Call Graph Execution Profiler" 262.%A S. Graham 263.%A P. Kessler 264.%A M. McKusick 265.%J "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices" 266.%V 17 267.%N 6 268.%P pp. 120-126 269.%D June 1982 270.Re 271.Sh HISTORY 272The 273.Nm 274profiler 275appeared in 276.Bx 4.2 . 277.Sh BUGS 278The granularity of the sampling is shown, but remains 279statistical at best. 280We assume that the time for each execution of a function 281can be expressed by the total time for the function divided 282by the number of times the function is called. 283Thus the time propagated along the call graph arcs to the function's 284parents is directly proportional to the number of times that 285arc is traversed. 286.Pp 287Parents that are not themselves profiled will have the time of 288their profiled children propagated to them, but they will appear 289to be spontaneously invoked in the call graph listing, and will 290not have their time propagated further. 291Similarly, signal catchers, even though profiled, will appear 292to be spontaneous (although for more obscure reasons). 293Any profiled children of signal catchers should have their times 294propagated properly, unless the signal catcher was invoked during 295the execution of the profiling routine, in which case all is lost. 296.Pp 297The profiled program must call 298.Xr exit 3 299or return normally for the profiling information to be saved 300in the graph profile file. 301