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