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