Annotation of src/usr.bin/gprof/gprof.1, Revision 1.4
1.4 ! deraadt 1: .\" $OpenBSD: gprof.1,v 1.3 1996/06/26 05:33:50 deraadt 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
39: .Os BSD 4.2
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
48: .Nm Gprof
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.
65: .Nm Gprof
66: reads the given object file (the default is
67: .Pa a.out)
68: and establishes the relation between it's symbol table
69: and the call graph profile from
70: .Pa gmon.out .
71: If more than one profile file is specified,
72: the
73: .Nm gprof
74: output shows the sum of the profile information in the given profile files.
75: .Pp
76: .Nm Gprof
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
95: .Xr prof 1 .
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
103: The following options are available:
104: .Bl -tag -width Fl
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,
124: so using this option may cause
125: .Nm gprof
126: to run for a very long time.
127: .It Fl e Ar name
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.
140: .It Fl E Ar name
141: Suppresses the printing of the graph profile entry for routine
142: .Ar name
143: (and its descendants) as
144: .Fl e ,
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.)
154: .It Fl f Ar name
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.
166: .It Fl F Ar name
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.
188: .It Fl k Ar fromname Ar toname
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
206: executions of gprof (probably also with a
207: .Fl s )
208: to accumulate profile data across several runs of an
209: .Pa a.out
210: file.
211: .It Fl z
212: Displays routines that have zero usage (as shown by call counts
213: and accumulated time).
214: This is useful with the
215: .Fl c
216: option for discovering which routines were never called.
1.2 deraadt 217: .El
218: .Sh ENVIRONMENT
219: .Bl -tag -width PROFDIR
220: .It Ev PROFDIR
221: If the environmental variable
222: .Ev PROFDIR
223: is set, profiling information is placed in that directory in a file named
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
232: The namelist and text space.
233: .It Pa gmon.out
234: Dynamic call graph and profile.
235: .It Pa gmon.sum
236: Summarized dynamic call graph and profile.
237: .El
238: .Sh SEE ALSO
239: .Xr monitor 3 ,
240: .Xr profil 2 ,
241: .Xr cc 1 ,
242: .Xr prof 1
243: .Rs
244: .%T "An Execution Profiler for Modular Programs"
245: .%A S. Graham
246: .%A P. Kessler
247: .%A M. McKusick
248: .%J "Software - Practice and Experience"
249: .%V 13
250: .%P pp. 671-685
251: .%D 1983
252: .Re
253: .Rs
254: .%T "gprof: A Call Graph Execution Profiler"
255: .%A S. Graham
256: .%A P. Kessler
257: .%A M. McKusick
258: .%J "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices"
259: .%V 17
260: .%N 6
261: .%P pp. 120-126
262: .%D June 1982
263: .Re
264: .Sh HISTORY
265: The
266: .Nm gprof
267: profiler
268: appeared in
269: .Bx 4.2 .
270: .Sh BUGS
271: The granularity of the sampling is shown, but remains
272: statistical at best.
273: We assume that the time for each execution of a function
274: can be expressed by the total time for the function divided
275: by the number of times the function is called.
276: Thus the time propagated along the call graph arcs to the function's
277: parents is directly proportional to the number of times that
278: arc is traversed.
279: .Pp
280: Parents that are not themselves profiled will have the time of
281: their profiled children propagated to them, but they will appear
282: to be spontaneously invoked in the call graph listing, and will
283: not have their time propagated further.
284: Similarly, signal catchers, even though profiled, will appear
285: to be spontaneous (although for more obscure reasons).
286: Any profiled children of signal catchers should have their times
287: propagated properly, unless the signal catcher was invoked during
288: the execution of the profiling routine, in which case all is lost.
289: .Pp
290: The profiled program must call
291: .Xr exit 2
292: or return normally for the profiling information to be saved
293: in the
294: .Pa gmon.out
295: 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