265 lines
7.3 KiB
Groff
265 lines
7.3 KiB
Groff
.\" Copyright (c) 1983, 1990 The Regents of the University of California.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms are permitted provided
|
|
.\" that: (1) source distributions retain this entire copyright notice and
|
|
.\" comment, and (2) distributions including binaries display the following
|
|
.\" acknowledgement: ``This product includes software developed by the
|
|
.\" University of California, Berkeley and its contributors'' in the
|
|
.\" documentation or other materials provided with the distribution and in
|
|
.\" all advertising materials mentioning features or use of this software.
|
|
.\" Neither the name of the University nor the names of its contributors may
|
|
.\" be used to endorse or promote products derived from this software without
|
|
.\" specific prior written permission.
|
|
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
|
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
|
.\"
|
|
.\" @(#)gprof.1 6.6 (Berkeley) 7/24/90
|
|
.\"
|
|
.Dd July 24, 1990
|
|
.Dt GPROF 1
|
|
.Os BSD 4.2
|
|
.Sh NAME
|
|
.Nm gprof
|
|
.Nd display call graph profile data
|
|
.Sh SYNOPSIS
|
|
.Nm gprof
|
|
.Op options
|
|
.Op Ar a.out Op Ar gmon.out ...
|
|
.Sh DESCRIPTION
|
|
.Nm gprof
|
|
produces an execution profile of C, Pascal, or Fortran77 programs.
|
|
The effect of called routines is incorporated in the profile of each caller.
|
|
The profile data is taken from the call graph profile file
|
|
.Pf \&( Pa gmon.out
|
|
default) which is created by programs
|
|
that are compiled with the
|
|
.Fl pg
|
|
option of
|
|
.Xr cc 1 ,
|
|
.Xr pc 1 ,
|
|
and
|
|
.Xr f77 1 .
|
|
The
|
|
.Fl pg
|
|
option also links in versions of the library routines
|
|
that are compiled for profiling.
|
|
.Nm Gprof
|
|
reads the given object file (the default is
|
|
.Pa a.out)
|
|
and establishes the relation between it's symbol table
|
|
and the call graph profile from
|
|
.Pa gmon.out .
|
|
If more than one profile file is specified,
|
|
the
|
|
.Nm gprof
|
|
output shows the sum of the profile information in the given profile files.
|
|
.Pp
|
|
.Nm Gprof
|
|
calculates the amount of time spent in each routine.
|
|
Next, these times are propagated along the edges of the call graph.
|
|
Cycles are discovered, and calls into a cycle are made to share the time
|
|
of the cycle.
|
|
The first listing shows the functions
|
|
sorted according to the time they represent
|
|
including the time of their call graph descendents.
|
|
Below each function entry is shown its (direct) call graph children,
|
|
and how their times are propagated to this function.
|
|
A similar display above the function shows how this function's time and the
|
|
time of its descendents is propagated to its (direct) call graph parents.
|
|
.Pp
|
|
Cycles are also shown, with an entry for the cycle as a whole and
|
|
a listing of the members of the cycle and their contributions to the
|
|
time and call counts of the cycle.
|
|
.Pp
|
|
Second, a flat profile is given,
|
|
similar to that provided by
|
|
.Xr prof 1 .
|
|
This listing gives the total execution times, the call counts,
|
|
the time in milleseconds the call spent in the routine itself, and
|
|
the time in milleseconds the call spent in the routine itself including
|
|
its descendents.
|
|
.Pp
|
|
Finally, an index of the function names is provided.
|
|
.Pp
|
|
The following options are available:
|
|
.Tw Fl
|
|
.Tp Fl a
|
|
suppresses the printing of statically declared functions.
|
|
If this option is given, all relevant information about the static function
|
|
(e.g., time samples, calls to other functions, calls from other functions)
|
|
belongs to the function loaded just before the static function in the
|
|
.Pa a.out
|
|
file.
|
|
.Tp Fl b
|
|
suppresses the printing of a description of each field in the profile.
|
|
.Tp Fl c
|
|
the static call graph of the program is discovered by a heuristic
|
|
that examines the text space of the object file.
|
|
Static-only parents or children are shown
|
|
with call counts of 0.
|
|
.Tc Fl e
|
|
.Ws
|
|
.Ar name
|
|
.Cx
|
|
suppresses the printing of the graph profile entry for routine
|
|
.Ar name
|
|
and all its descendants
|
|
(unless they have other ancestors that aren't suppressed).
|
|
More than one
|
|
.Fl e
|
|
option may be given.
|
|
Only one
|
|
.Ar name
|
|
may be given with each
|
|
.Fl e
|
|
option.
|
|
.Tc Fl E
|
|
.Ws
|
|
.Ar name
|
|
.Cx
|
|
suppresses the printing of the graph profile entry for routine
|
|
.Ar name
|
|
(and its descendants) as
|
|
.Fl e ,
|
|
above, and also excludes the time spent in
|
|
.Ar name
|
|
(and its descendants) from the total and percentage time computations.
|
|
(For example,
|
|
.Fl E
|
|
.Ar mcount
|
|
.Fl E
|
|
.Ar mcleanup
|
|
is the default.)
|
|
.Tc Fl f
|
|
.Ws
|
|
.Ar name
|
|
.Cx
|
|
prints the graph profile entry of only the specified routine
|
|
.Ar name
|
|
and its descendants.
|
|
More than one
|
|
.Fl f
|
|
option may be given.
|
|
Only one
|
|
.Ar name
|
|
may be given with each
|
|
.Fl f
|
|
option.
|
|
.Tc Fl F
|
|
.Ws
|
|
.Ar name
|
|
.Cx
|
|
prints the graph profile entry of only the routine
|
|
.Ar name
|
|
and its descendants (as
|
|
.Fl f ,
|
|
above) and also uses only the times of the printed routines
|
|
in total time and percentage computations.
|
|
More than one
|
|
.Fl F
|
|
option may be given.
|
|
Only one
|
|
.Ar name
|
|
may be given with each
|
|
.Fl F
|
|
option.
|
|
The
|
|
.Fl F
|
|
option
|
|
overrides
|
|
the
|
|
.Fl E
|
|
option.
|
|
.Tc Fl k
|
|
.Ws
|
|
.Ar fromname
|
|
.Ws
|
|
.Ar toname
|
|
.Cx
|
|
will delete any arcs from routine
|
|
.Ar fromname
|
|
to routine
|
|
.Ar toname .
|
|
This can be used to break undesired cycles.
|
|
More than one
|
|
.Fl k
|
|
option may be given.
|
|
Only one pair of routine names may be given with each
|
|
.Fl k
|
|
option.
|
|
.Tp Fl s
|
|
a profile file
|
|
.Pa gmon.sum
|
|
is produced that represents
|
|
the sum of the profile information in all the specified profile files.
|
|
This summary profile file may be given to later
|
|
executions of gprof (probably also with a
|
|
.Fl s )
|
|
to accumulate profile data across several runs of an
|
|
.Pa a.out
|
|
file.
|
|
.Tp Fl z
|
|
displays routines that have zero usage (as shown by call counts
|
|
and accumulated time).
|
|
This is useful with the
|
|
.Fl c
|
|
option for discovering which routines were never called.
|
|
.Tp
|
|
.Sh FILES
|
|
.Dw gmon.sum
|
|
.Di L
|
|
.Dp Pa a.out
|
|
the namelist and text space.
|
|
.Dp Pa gmon.out
|
|
dynamic call graph and profile.
|
|
.Dp Pa gmon.sum
|
|
summarized dynamic call graph and profile.
|
|
.Dp
|
|
.Sh SEE ALSO
|
|
.Xr monitor 3 ,
|
|
.Xr profil 2 ,
|
|
.Xr cc 1 ,
|
|
.Xr prof 1
|
|
.br
|
|
.Em An Execution Profiler for Modular Programs ,
|
|
by
|
|
S. Graham, P. Kessler, M. McKusick;
|
|
Software - Practice and Experience,
|
|
Vol. 13, pp. 671-685, 1983.
|
|
.br
|
|
.Em gprof: A Call Graph Execution Profiler ,
|
|
by S. Graham, P. Kessler, M. McKusick;
|
|
Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
|
|
SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, June 1982.
|
|
.Sh HISTORY
|
|
.Nm Gprof
|
|
appeared in 4.2 BSD.
|
|
.Sh BUGS
|
|
The granularity of the sampling is shown, but remains
|
|
statistical at best.
|
|
We assume that the time for each execution of a function
|
|
can be expressed by the total time for the function divided
|
|
by the number of times the function is called.
|
|
Thus the time propagated along the call graph arcs to the function's
|
|
parents is directly proportional to the number of times that
|
|
arc is traversed.
|
|
.Pp
|
|
Parents that are not themselves profiled will have the time of
|
|
their profiled children propagated to them, but they will appear
|
|
to be spontaneously invoked in the call graph listing, and will
|
|
not have their time propagated further.
|
|
Similarly, signal catchers, even though profiled, will appear
|
|
to be spontaneous (although for more obscure reasons).
|
|
Any profiled children of signal catchers should have their times
|
|
propagated properly, unless the signal catcher was invoked during
|
|
the execution of the profiling routine, in which case all is lost.
|
|
.Pp
|
|
The profiled program must call
|
|
.Xr exit 2
|
|
or return normally for the profiling information to be saved
|
|
in the
|
|
.Pa gmon.out
|
|
file.
|