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