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