Annotation of src/usr.bin/gprof/gprof.1, Revision 1.1.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