xref: /freebsd/usr.bin/gprof/gprof.1 (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
1.\" Copyright (c) 1983, 1990, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\"    must display the following acknowledgement:
14.\"	This product includes software developed by the University of
15.\"	California, Berkeley and its contributors.
16.\" 4. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"	@(#)gprof.1	8.1 (Berkeley) 6/6/93
33.\" $FreeBSD$
34.\"
35.Dd December 25, 2008
36.Dt GPROF 1
37.Os
38.Sh NAME
39.Nm gprof
40.Nd display call graph profile data
41.Sh SYNOPSIS
42.Nm
43.Op Fl abKlLsuz
44.Op Fl C Ar count
45.Op Fl e Ar name
46.Op Fl E Ar name
47.Op Fl f Ar name
48.Op Fl F Ar name
49.Op Fl k Ar fromname toname
50.Op Ar a.out Op Ar a.out.gmon ...
51.Sh DESCRIPTION
52The
53.Nm
54utility produces an execution profile of C, Pascal, or Fortran77 programs.
55The effect of called routines is incorporated in the profile of each caller.
56The profile data is taken from the call graph profile file
57which is created by programs that are compiled with the
58.Fl pg
59option of
60.Xr cc 1 ,
61.Xr pc 1 ,
62and
63.Xr f77 1 .
64The
65.Fl pg
66option also links in versions of the library routines
67that are compiled for profiling.
68By convention these libraries have their name suffixed with
69.Pa _p ,
70i.e., the profiled version of
71.Pa libc.a
72is
73.Pa libc_p.a
74and if you specify libraries directly to the
75compiler or linker you can use
76.Fl l Ns Ar c_p
77instead of
78.Fl l Ns Ar c .
79Read the given object file (the default is
80.Pa a.out)
81and establishes the relation between its symbol table
82and the call graph profile.
83The default graph profile file name is the name
84of the executable with the suffix
85.Pa .gmon
86appended.
87If more than one profile file is specified,
88the
89.Nm
90output shows the sum of the profile information in the given profile files.
91.Pp
92The
93.Nm
94utility calculates the amount of time spent in each routine.
95Next, these times are propagated along the edges of the call graph.
96Cycles are discovered, and calls into a cycle are made to share the time
97of the cycle.
98The first listing shows the functions
99sorted according to the time they represent
100including the time of their call graph descendants.
101Below each function entry is shown its (direct) call graph children,
102and how their times are propagated to this function.
103A similar display above the function shows how this function's time and the
104time of its descendants is propagated to its (direct) call graph parents.
105.Pp
106Cycles are also shown, with an entry for the cycle as a whole and
107a listing of the members of the cycle and their contributions to the
108time and call counts of the cycle.
109.Pp
110Second, a flat profile is given,
111similar to that provided by
112.Xr prof 1 .
113This listing gives the total execution times, the call counts,
114the time that the call spent in the routine itself, and
115the time that the call spent in the routine itself including
116its descendants.
117The units for the per-call times are normally milliseconds,
118but they are nanoseconds if the profiling clock frequency
119is 10 million or larger,
120and if a function appears to be never called then its total self time
121is printed as a percentage in the self time per call column.
122The very high profiling clock frequencies needed to get sufficient
123accuracy in the per-call times for short-lived programs are only
124implemented for
125.Dq high resolution
126(non-statistical) kernel profiling.
127.Pp
128Finally, an index of the function names is provided.
129.Pp
130The following options are available:
131.Bl -tag -width indent
132.It Fl a
133Suppress the printing of statically declared functions.
134If this option is given, all relevant information about the static function
135(e.g., time samples, calls to other functions, calls from other functions)
136belongs to the function loaded just before the static function in the
137.Pa a.out
138file.
139.It Fl b
140Suppress the printing of a description of each field in the profile.
141.It Fl C Ar count
142Find a minimal set of arcs that can be broken to eliminate all cycles with
143.Ar count
144or more members.
145Caution: the algorithm used to break cycles is exponential,
146so using this option may cause
147.Nm
148to run for a very long time.
149.It Fl e Ar name
150Suppress the printing of the graph profile entry for routine
151.Ar name
152and all its descendants
153(unless they have other ancestors that are not suppressed).
154More than one
155.Fl e
156option may be given.
157Only one
158.Ar name
159may be given with each
160.Fl e
161option.
162.It Fl E Ar name
163Suppress the printing of the graph profile entry for routine
164.Ar name
165(and its descendants) as
166.Fl e ,
167above, and also excludes the time spent in
168.Ar name
169(and its descendants) from the total and percentage time computations.
170(For example,
171.Fl E
172.Ar mcount
173.Fl E
174.Ar mcleanup
175is the default.)
176.It Fl f Ar name
177Print the graph profile entry of only the specified routine
178.Ar name
179and its descendants.
180More than one
181.Fl f
182option may be given.
183Only one
184.Ar name
185may be given with each
186.Fl f
187option.
188.It Fl F Ar name
189Print the graph profile entry of only the routine
190.Ar name
191and its descendants (as
192.Fl f ,
193above) and also uses only the times of the printed routines
194in total time and percentage computations.
195More than one
196.Fl F
197option may be given.
198Only one
199.Ar name
200may be given with each
201.Fl F
202option.
203The
204.Fl F
205option
206overrides
207the
208.Fl E
209option.
210.It Fl k Ar fromname Ar toname
211Will delete any arcs from routine
212.Ar fromname
213to routine
214.Ar toname .
215This can be used to break undesired cycles.
216More than one
217.Fl k
218option may be given.
219Only one pair of routine names may be given with each
220.Fl k
221option.
222.It Fl K
223Gather information about symbols from the currently-running kernel using the
224.Xr sysctl 3
225and
226.Xr kldsym 2
227interfaces.
228This forces the
229.Pa a.out
230argument to be ignored, and allows for symbols in
231.Xr kld 4
232modules to be used.
233.It Fl l
234Suppress the printing of the call-graph profile.
235.It Fl L
236Suppress the printing of the flat profile.
237.It Fl s
238A profile file
239.Pa gmon.sum
240is produced that represents
241the sum of the profile information in all the specified profile files.
242This summary profile file may be given to later
243executions of gprof (probably also with a
244.Fl s )
245to accumulate profile data across several runs of an
246.Pa a.out
247file.
248.It Fl u
249Suppress the printing of functions whose names are not visible to
250C programs.
251For the ELF object format, this means names that
252contain the
253.Ql .\&
254character.
255For the a.out object format, it means names that do not
256begin with a
257.Ql _
258character.
259All relevant information about such functions belongs to the
260(non-suppressed) function with the next lowest address.
261This is useful for eliminating "functions" that are just labels
262inside other functions.
263.It Fl z
264Display routines that have zero usage (as shown by call counts
265and accumulated time).
266.El
267.Sh FILES
268.Bl -tag -width a.out.gmon -compact
269.It Pa a.out
270The namelist and text space.
271.It Pa a.out.gmon
272Dynamic call graph and profile.
273.It Pa gmon.sum
274Summarized dynamic call graph and profile.
275.El
276.Sh SEE ALSO
277.Xr cc 1 ,
278.Xr profil 2 ,
279.Xr clocks 7
280.\" .Xr monitor 3 ,
281.\" .Xr prof 1
282.Rs
283.%T "An Execution Profiler for Modular Programs"
284.%A S. Graham
285.%A P. Kessler
286.%A M. McKusick
287.%J "Software - Practice and Experience"
288.%V 13
289.%P pp. 671-685
290.%D 1983
291.Re
292.Rs
293.%T "gprof: A Call Graph Execution Profiler"
294.%A S. Graham
295.%A P. Kessler
296.%A M. McKusick
297.%J "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices"
298.%V 17
299.%N 6
300.%P pp. 120-126
301.%D June 1982
302.Re
303.Sh HISTORY
304The
305.Nm
306profiler
307appeared in
308.Bx 4.2 .
309.Sh BUGS
310The granularity of the sampling is shown, but remains
311statistical at best.
312We assume that the time for each execution of a function
313can be expressed by the total time for the function divided
314by the number of times the function is called.
315Thus the time propagated along the call graph arcs to the function's
316parents is directly proportional to the number of times that
317arc is traversed.
318.Pp
319Parents that are not themselves profiled will have the time of
320their profiled children propagated to them, but they will appear
321to be spontaneously invoked in the call graph listing, and will
322not have their time propagated further.
323Similarly, signal catchers, even though profiled, will appear
324to be spontaneous (although for more obscure reasons).
325Any profiled children of signal catchers should have their times
326propagated properly, unless the signal catcher was invoked during
327the execution of the profiling routine, in which case all is lost.
328.Pp
329The profiled program must call
330.Xr exit 3
331or return normally for the profiling information to be saved
332in the graph profile file.
333