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