![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gprof.1 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSDReno / pgrm / gprof|
Return to gprof.1 CVS log | Up to [CSRG BSD Unix] / 43BSDReno / pgrm / gprof |
1.1 root 1: .\" Copyright (c) 1983, 1990 The Regents of the University of California.
2: .\" All rights reserved.
3: .\"
4: .\" Redistribution and use in source and binary forms are permitted provided
5: .\" that: (1) source distributions retain this entire copyright notice and
6: .\" comment, and (2) distributions including binaries display the following
7: .\" acknowledgement: ``This product includes software developed by the
8: .\" University of California, Berkeley and its contributors'' in the
9: .\" documentation or other materials provided with the distribution and in
10: .\" all advertising materials mentioning features or use of this software.
11: .\" Neither the name of the University nor the names of its contributors may
12: .\" be used to endorse or promote products derived from this software without
13: .\" specific prior written permission.
14: .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
15: .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
16: .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
17: .\"
18: .\" @(#)gprof.1 6.6 (Berkeley) 7/24/90
19: .\"
20: .Dd July 24, 1990
21: .Dt GPROF 1
22: .Os BSD 4.2
23: .Sh NAME
24: .Nm gprof
25: .Nd display call graph profile data
26: .Sh SYNOPSIS
27: .Nm gprof
28: .Op options
29: .Op Ar a.out Op Ar gmon.out ...
30: .Sh DESCRIPTION
31: .Nm gprof
32: produces an execution profile of C, Pascal, or Fortran77 programs.
33: The effect of called routines is incorporated in the profile of each caller.
34: The profile data is taken from the call graph profile file
35: .Pf \&( Pa gmon.out
36: default) which is created by programs
37: that are compiled with the
38: .Fl pg
39: option of
40: .Xr cc 1 ,
41: .Xr pc 1 ,
42: and
43: .Xr f77 1 .
44: The
45: .Fl pg
46: option also links in versions of the library routines
47: that are compiled for profiling.
48: .Nm Gprof
49: reads the given object file (the default is
50: .Pa a.out)
51: and establishes the relation between it's symbol table
52: and the call graph profile from
53: .Pa gmon.out .
54: If more than one profile file is specified,
55: the
56: .Nm gprof
57: output shows the sum of the profile information in the given profile files.
58: .Pp
59: .Nm Gprof
60: calculates the amount of time spent in each routine.
61: Next, these times are propagated along the edges of the call graph.
62: Cycles are discovered, and calls into a cycle are made to share the time
63: of the cycle.
64: The first listing shows the functions
65: sorted according to the time they represent
66: including the time of their call graph descendents.
67: Below each function entry is shown its (direct) call graph children,
68: and how their times are propagated to this function.
69: A similar display above the function shows how this function's time and the
70: time of its descendents is propagated to its (direct) call graph parents.
71: .Pp
72: Cycles are also shown, with an entry for the cycle as a whole and
73: a listing of the members of the cycle and their contributions to the
74: time and call counts of the cycle.
75: .Pp
76: Second, a flat profile is given,
77: similar to that provided by
78: .Xr prof 1 .
79: This listing gives the total execution times, the call counts,
80: the time in milleseconds the call spent in the routine itself, and
81: the time in milleseconds the call spent in the routine itself including
82: its descendents.
83: .Pp
84: Finally, an index of the function names is provided.
85: .Pp
86: The following options are available:
87: .Tw Fl
88: .Tp Fl a
89: suppresses the printing of statically declared functions.
90: If this option is given, all relevant information about the static function
91: (e.g., time samples, calls to other functions, calls from other functions)
92: belongs to the function loaded just before the static function in the
93: .Pa a.out
94: file.
95: .Tp Fl b
96: suppresses the printing of a description of each field in the profile.
97: .Tp Fl c
98: the static call graph of the program is discovered by a heuristic
99: that examines the text space of the object file.
100: Static-only parents or children are shown
101: with call counts of 0.
102: .Tc Fl e
103: .Ws
104: .Ar name
105: .Cx
106: suppresses the printing of the graph profile entry for routine
107: .Ar name
108: and all its descendants
109: (unless they have other ancestors that aren't suppressed).
110: More than one
111: .Fl e
112: option may be given.
113: Only one
114: .Ar name
115: may be given with each
116: .Fl e
117: option.
118: .Tc Fl E
119: .Ws
120: .Ar name
121: .Cx
122: suppresses the printing of the graph profile entry for routine
123: .Ar name
124: (and its descendants) as
125: .Fl e ,
126: above, and also excludes the time spent in
127: .Ar name
128: (and its descendants) from the total and percentage time computations.
129: (For example,
130: .Fl E
131: .Ar mcount
132: .Fl E
133: .Ar mcleanup
134: is the default.)
135: .Tc Fl f
136: .Ws
137: .Ar name
138: .Cx
139: prints the graph profile entry of only the specified routine
140: .Ar name
141: and its descendants.
142: More than one
143: .Fl f
144: option may be given.
145: Only one
146: .Ar name
147: may be given with each
148: .Fl f
149: option.
150: .Tc Fl F
151: .Ws
152: .Ar name
153: .Cx
154: prints the graph profile entry of only the routine
155: .Ar name
156: and its descendants (as
157: .Fl f ,
158: above) and also uses only the times of the printed routines
159: in total time and percentage computations.
160: More than one
161: .Fl F
162: option may be given.
163: Only one
164: .Ar name
165: may be given with each
166: .Fl F
167: option.
168: The
169: .Fl F
170: option
171: overrides
172: the
173: .Fl E
174: option.
175: .Tc Fl k
176: .Ws
177: .Ar fromname
178: .Ws
179: .Ar toname
180: .Cx
181: will delete any arcs from routine
182: .Ar fromname
183: to routine
184: .Ar toname .
185: This can be used to break undesired cycles.
186: More than one
187: .Fl k
188: option may be given.
189: Only one pair of routine names may be given with each
190: .Fl k
191: option.
192: .Tp Fl s
193: a profile file
194: .Pa gmon.sum
195: is produced that represents
196: the sum of the profile information in all the specified profile files.
197: This summary profile file may be given to later
198: executions of gprof (probably also with a
199: .Fl s )
200: to accumulate profile data across several runs of an
201: .Pa a.out
202: file.
203: .Tp Fl z
204: displays routines that have zero usage (as shown by call counts
205: and accumulated time).
206: This is useful with the
207: .Fl c
208: option for discovering which routines were never called.
209: .Tp
210: .Sh FILES
211: .Dw gmon.sum
212: .Di L
213: .Dp Pa a.out
214: the namelist and text space.
215: .Dp Pa gmon.out
216: dynamic call graph and profile.
217: .Dp Pa gmon.sum
218: summarized dynamic call graph and profile.
219: .Dp
220: .Sh SEE ALSO
221: .Xr monitor 3 ,
222: .Xr profil 2 ,
223: .Xr cc 1 ,
224: .Xr prof 1
225: .br
226: .Em An Execution Profiler for Modular Programs ,
227: by
228: S. Graham, P. Kessler, M. McKusick;
229: Software - Practice and Experience,
230: Vol. 13, pp. 671-685, 1983.
231: .br
232: .Em gprof: A Call Graph Execution Profiler ,
233: by S. Graham, P. Kessler, M. McKusick;
234: Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
235: SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, June 1982.
236: .Sh HISTORY
237: .Nm Gprof
238: appeared in 4.2 BSD.
239: .Sh BUGS
240: The granularity of the sampling is shown, but remains
241: statistical at best.
242: We assume that the time for each execution of a function
243: can be expressed by the total time for the function divided
244: by the number of times the function is called.
245: Thus the time propagated along the call graph arcs to the function's
246: parents is directly proportional to the number of times that
247: arc is traversed.
248: .Pp
249: Parents that are not themselves profiled will have the time of
250: their profiled children propagated to them, but they will appear
251: to be spontaneously invoked in the call graph listing, and will
252: not have their time propagated further.
253: Similarly, signal catchers, even though profiled, will appear
254: to be spontaneous (although for more obscure reasons).
255: Any profiled children of signal catchers should have their times
256: propagated properly, unless the signal catcher was invoked during
257: the execution of the profiling routine, in which case all is lost.
258: .Pp
259: The profiled program must call
260: .Xr exit 2
261: or return normally for the profiling information to be saved
262: in the
263: .Pa gmon.out
264: file.
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.