diff options
Diffstat (limited to 'usr.bin/gprof/gprof.1')
| -rw-r--r-- | usr.bin/gprof/gprof.1 | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/usr.bin/gprof/gprof.1 b/usr.bin/gprof/gprof.1 new file mode 100644 index 0000000..dfb0f21 --- /dev/null +++ b/usr.bin/gprof/gprof.1 @@ -0,0 +1,281 @@ +.\" Copyright (c) 1983, 1990, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. 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 BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)gprof.1 8.1 (Berkeley) 6/6/93 +.\" +.Dd June 6, 1993 +.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: +.Bl -tag -width Fl +.It 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. +.It Fl b +Suppresses the printing of a description of each field in the profile. +.It 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. +.It Fl C Ar count +Find a minimal set of arcs that can be broken to eliminate all cycles with +.Ar count +or more members. +Caution: the algorithm used to break cycles is exponential, +so using this option may cause +.Nm gprof +to run for a very long time. +.It Fl e Ar name +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. +.It Fl E Ar name +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.) +.It Fl f Ar name +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. +.It Fl F Ar name +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. +.It Fl k Ar fromname Ar toname +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. +.It 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. +.It 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. +.El +.Sh FILES +.Bl -tag -width gmon.sum -compact +.It Pa a.out +The namelist and text space. +.It Pa gmon.out +Dynamic call graph and profile. +.It Pa gmon.sum +Summarized dynamic call graph and profile. +.El +.Sh SEE ALSO +.Xr monitor 3 , +.Xr profil 2 , +.Xr cc 1 , +.Xr prof 1 +.Rs +.%T "An Execution Profiler for Modular Programs" +.%A S. Graham +.%A P. Kessler +.%A M. McKusick +.%J "Software - Practice and Experience" +.%V 13 +.%P pp. 671-685 +.%D 1983 +.Re +.Rs +.%T "gprof: A Call Graph Execution Profiler" +.%A S. Graham +.%A P. Kessler +.%A M. McKusick +.%J "Proceedings of the SIGPLAN '82 Symposium on Compiler Construction, SIGPLAN Notices" +.%V 17 +.%N 6 +.%P pp. 120-126 +.%D June 1982 +.Re +.Sh HISTORY +The +.Nm gprof +profiler +appeared in +.Bx 4.2 . +.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. |
