file reorg, pathnames.h, paths.h

[unix-history] / usr / src / usr.bin / gprof / gprof.1

diff --git a/usr/src/usr.bin/gprof/gprof.1 b/usr/src/usr.bin/gprof/gprof.1
index 705a8a4..60f38fa 100644 (file)
--- a/usr/src/usr.bin/gprof/gprof.1
+++ b/usr/src/usr.bin/gprof/gprof.1
@@ -2,10 +2,9 @@
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"

-.\"    @(#)gprof.1     5.1 (Berkeley) %G%
+.\"    @(#)gprof.1     6.3 (Berkeley) %G%

 .\"
 .\"

-\"     @(#)gprof.1     1.9 (Berkeley) 10/12/82
-.TH GPROF 1 "18 January 1983"
+.TH GPROF 1 ""

 .UC 5
 .SH NAME
 gprof \- display call graph profile data
 .UC 5
 .SH NAME
 gprof \- display call graph profile data


@@ -19,37 +18,32 @@ The effect of called routines is incorporated in the profile of each caller.
 The profile data is taken from the call graph profile file
 .RI ( gmon.out
 default) which is created by programs
 The profile data is taken from the call graph profile file
 .RI ( gmon.out
 default) which is created by programs

-which are compiled with the 
+that are compiled with the 

 .B \-pg
 option of 
 .IR cc ,
 .IR pc ,
 and
 .IR f77 .
 .B \-pg
 option of 
 .IR cc ,
 .IR pc ,
 and
 .IR f77 .

-That option also links in versions of the library routines 
-which are compiled for profiling.
-The symbol table in the
-named object file
+The
+.B \-pg
+option also links in versions of the library routines 
+that are compiled for profiling.
+The symbol table in the named object file

 .RI ( a.out
 default)
 .RI ( a.out
 default)

-is read and correlated with the
-call graph profile file.
+is read and correlated with the call graph profile file.

 If more than one profile file is specified,
 the
 .I gprof
 output shows the sum of the profile information in the given profile files.
 .PP
 If more than one profile file is specified,
 the
 .I gprof
 output shows the sum of the profile information in the given profile files.
 .PP

-First, a flat profile is given,
-similar to that provided by
-.IR prof (1).
-This listing gives the total execution times
-and call counts for each of the functions
-in the program, sorted by decreasing time.
-.PP
+.I 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.
 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.

-A second listing shows the functions
+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,
 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,


@@ -61,6 +55,16 @@ 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
 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
+.IR prof (1).
+This listing gives the total execution times, the call counts,
+the number of milliseconds per call in the routine itself, and
+the number of milliseconds per call in the routine itself including
+its descendents.
+.PP
+Finally, an index of the function names is provided.
+.PP

 The following options are available:
 .TP
 .B \-a
 The following options are available:
 .TP
 .B \-a


@@ -73,12 +77,12 @@ belongs to the function loaded just before the static function in the
 file.
 .TP
 .B \-b
 file.
 .TP
 .B \-b

-supresses the printing of a description of each field in the profile.
+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
 .TP
 .B \-c
 the static call graph of the program is discovered by a heuristic

-which examines the text space of the object file.
-Static-only parents or children are indicated
+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"
 with call counts of 0.
 .TP
 .BI \-e " name"


@@ -146,12 +150,25 @@ the
 .B \-E
 option.
 .TP
 .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
 .I gmon.sum
 .B \-s
 a profile file
 .I gmon.sum

-is produced which represents
+is produced that represents

 the sum of the profile information in all the specified profile files.
 the sum of the profile information in all the specified profile files.

-This summary profile file may be given to subsequent
+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
 executions of gprof (probably also with a
 .BR \-s )
 to accumulate profile data across several runs of an


@@ -159,9 +176,9 @@ to accumulate profile data across several runs of an
 file.
 .TP
 .B \-z
 file.
 .TP
 .B \-z

-displays routines which have zero usage (as indicated by call counts
+displays routines that have zero usage (as shown by call counts

 and accumulated time).
 and accumulated time).

-This is useful in conjunction with the 
+This is useful with the 

 .B \-c
 option for discovering which routines were never called.
 .SH FILES
 .B \-c
 option for discovering which routines were never called.
 .SH FILES


@@ -188,11 +205,11 @@ 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.
 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 parents of that
-function is directly proportional to the number of times that
+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
 arc is traversed.
 .PP

-Parents which are not themselves profiled will have the time of 
+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.
 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.