19990502 sourceware importbinu_ss_19990502

1 files changed, 252 insertions, 0 deletions

diff --git a/gprof/gprof.1 b/gprof/gprof.1
new file mode 100644
index 0000000..5a734da
--- /dev/null
+++ b/gprof/gprof.1
@@ -0,0 +1,252 @@
+.\" 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
+.\"
+.TH GPROF 1 "January 29, 1993"
+.SH NAME
+gprof \- display call graph profile data
+.SH SYNOPSIS
+.B gprof [ \-abcsz ] [ \-e|\-E
+.I name
+.B ] [ \-f|\-F 
+.I name
+.B ] 
+.B [ \-k
+.I fromname toname
+.B ] [ 
+.I objfile
+.B [ 
+.I gmon.out
+.B ] 
+.B ] 
+.SH DESCRIPTION
+.B 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
+\&(`gmon.out' default) which is created by programs
+that are compiled with the
+.B \-pg
+option of
+.BR cc ( 1 ) ,
+.BR pc ( 1 ) ,
+and
+.BR f77 ( 1 ) .
+The
+.B \-pg
+option also links in versions of the library routines
+that are compiled for profiling.
+.B Gprof
+reads the given object file (the default is `a.out')
+and establishes the relation between its symbol table
+and the call graph profile from `gmon.out'.
+If more than one profile file is specified,
+the
+.B gprof
+output shows the sum of the profile information in the given profile files.
+.PP
+.B 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 descendants.
+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 descendants 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
+.BR prof ( 1 )  .
+This listing gives the total execution times, the call counts,
+the time in milliseconds the call spent in the routine itself, and
+the time in milliseconds the call spent in the routine itself including
+its descendants.
+.PP
+Finally, an index of the function names is provided.
+.SH OPTIONS
+The following options are available:
+.TP
+.B \-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
+\&`objfile' file.
+.TP
+.B \-b
+suppresses the printing of a description of each field in the profile.
+.TP
+.B \-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.
+.TP
+.BI "\-e " name
+suppresses the printing of the graph profile entry for routine
+.I name
+and all its descendants
+(unless they have other ancestors that aren't suppressed).
+More than one
+.B \-e
+option may be given.
+Only one
+.I name
+may be given with each
+.B \-e
+option.
+.TP
+.BI "\-E " name
+suppresses the printing of the graph profile entry for routine
+.I name
+(and its descendants) as
+.B \-e  ,
+above, and also excludes the time spent in
+.I name
+(and its descendants) from the total and percentage time computations.
+(For example,
+.BI "\-E " mcount
+.BI "\-E " mcleanup
+is the default.)
+.TP
+.BI "\-f " name
+prints the graph profile entry of only the specified routine
+.I name
+and its descendants.
+More than one
+.B \-f
+option may be given.
+Only one
+.I name
+may be given with each
+.B \-f
+option.
+.TP
+.BI "\-F " name
+prints the graph profile entry of only the routine
+.I name
+and its descendants (as
+.B \-f ,
+above) and also uses only the times of the printed routines
+in total time and percentage computations.
+More than one
+.B \-F
+option may be given.
+Only one
+.I name
+may be given with each
+.B \-F
+option.
+The
+.B \-F
+option
+overrides
+the
+.B \-E
+option.
+.TP
+.BI "\-k " "fromname toname"
+will delete any arcs from routine
+.I fromname
+to routine
+.IR toname  .
+This can be used to break undesired cycles.
+More than one
+.B \-k
+option may be given.
+Only one pair of routine names may be given with each
+.B \-k
+option.
+.TP
+.B \-s
+a profile file `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
+.BR \-s  )
+to accumulate profile data across several runs of an `objfile' file.
+.TP
+.B -v
+prints the version number for gprof, and then exits.
+.TP
+.B -z
+displays routines that have zero usage (as shown by call counts
+and accumulated time).
+This is useful with the
+.B \-c
+option for discovering which routines were never called.
+.PP
+.SH FILES
+.ta \w'gmon.sum 'u
+a.out	the namelist and text space.
+.br
+gmon.out	dynamic call graph and profile.
+.br
+gmon.sum summarized dynamic call graph and profile.
+.SH SEE ALSO
+.BR monitor ( 3 ) ,
+.BR profil ( 2 ) ,
+.BR cc ( 1 ) ,
+.BR prof ( 1 )
+.sp
+``An Execution Profiler for Modular Programs'',
+by S. Graham, P. Kessler, M. McKusick;
+.I
+Software \- Practice and Experience,
+Vol. 13, pp. 671-685, 1983.
+.sp
+``gprof: A Call Graph Execution Profiler'',
+by S. Graham, P. Kessler, M. McKusick;
+.I
+Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
+SIGPLAN Notices, Vol. 17, No  6, pp. 120-126, June 1982.
+.SH HISTORY
+.B 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
+.BR exit ( 2 )
+or return normally for the profiling information to be saved
+in the `gmon.out' file.