man page generation from gprof.texi by Stephane Carrez

gprof/gprof.texi

@@ -1,6 +1,6 @@
 \input texinfo @c -*-texinfo-*-
 @setfilename gprof.info
-@c Copyright 1988, 1992, 1993, 1998, 1999, 2000
+@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001
 @c Free Software Foundation, Inc.
 @settitle GNU gprof
 @setchapternewpage odd
@@ -18,14 +18,17 @@ END-INFO-DIR-ENTRY
 @ifinfo
 This file documents the gprof profiler of the GNU system.
 
-Copyright (C) 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.
+@c man begin COPYRIGHT
+Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
 
-      Permission is granted to copy, distribute and/or modify this document
-      under the terms of the GNU Free Documentation License, Version 1.1
-      or any later version published by the Free Software Foundation;
-      with no Invariant Sections, with no Front-Cover Texts, and with no
-      Back-Cover Texts.  A copy of the license is included in the
-      section entitled "GNU Free Documentation License".
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled "GNU Free Documentation License".
+
+@c man end
 
 @ignore
 Permission is granted to process this file through Tex and print the
@@ -96,6 +99,102 @@ section entitled "GNU Free Documentation License".
 @node Introduction
 @chapter Introduction to Profiling
 
+@ifset man
+@c man title gprof display call graph profile data
+
+@smallexample
+@c man begin SYNOPSIS
+gprof [ -[abcDhilLsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ] 
+ [ -I @var{dirs} ] [ -d[@var{num}] ] [ -k @var{from/to} ]
+ [ -m @var{min-count} ] [ -t @var{table-length} ]
+ [ --[no-]annotated-source[=@var{name}] ] 
+ [ --[no-]exec-counts[=@var{name}] ]
+ [ --[no-]flat-profile[=@var{name}] ] [ --[no-]graph[=@var{name}] ]
+ [ --[no-]time=@var{name}] [ --all-lines ] [ --brief ] 
+ [ --debug[=@var{level}] ] [ --function-ordering ] 
+ [ --file-ordering ] [ --directory-path=@var{dirs} ]
+ [ --display-unused-functions ] [ --file-format=@var{name} ]
+ [ --file-info ] [ --help ] [ --line ] [ --min-count=@var{n} ]
+ [ --no-static ] [ --print-path ] [ --separate-files ]
+ [ --static-call-graph ] [ --sum ] [ --table-length=@var{len} ]
+ [ --traditional ] [ --version ] [ --width=@var{n} ]
+ [ --ignore-non-functions ] [ --demangle[=@var{STYLE}] ]
+ [ --no-demangle ] [ @var{image-file} ] [ @var{profile-file} @dots{} ]
+@c man end
+@end smallexample
+
+@c man begin DESCRIPTION
+@code{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
+(@file{gmon.out} default) which is created by programs
+that are compiled with the @samp{-pg} option of
+@code{cc}, @code{pc}, and @code{f77}.
+The @samp{-pg} option also links in versions of the library routines
+that are compiled for profiling.  @code{Gprof} reads the given object 
+file (the default is @code{a.out}) and establishes the relation between
+its symbol table and the call graph profile from @file{gmon.out}.
+If more than one profile file is specified, the @code{gprof}
+output shows the sum of the profile information in the given profile files.
+
+@code{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.
+
+@c man end
+
+@c man begin 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.
+
+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.
+
+The profiled program must call @code{exit}(2)
+or return normally for the profiling information to be saved
+in the @file{gmon.out} file.
+@c man end
+
+@c man begin FILES
+@table @code
+@item @file{a.out}
+the namelist and text space.
+@item @file{gmon.out}
+dynamic call graph and profile.
+@item @file{gmon.sum}
+summarized dynamic call graph and profile.  
+@end table
+@c man end
+
+@c man begin SEEALSO
+monitor(3), profil(2), cc(1), prof(1), and the Info entry for @file{gprof}.
+
+``An Execution Profiler for Modular Programs'',
+by S. Graham, P. Kessler, M. McKusick;
+Software - Practice and Experience,
+Vol. 13, pp. 671-685, 1983.
+
+``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.
+@c man end
+@end ifset
+
 Profiling allows you to learn where your program spent its time and which
 functions called which other functions while it was executing.  This
 information can show you which pieces of your program are slower than you
@@ -129,6 +228,8 @@ You must run @code{gprof} to analyze the profile data.
 
 The next three chapters explain these steps in greater detail.
 
+@c man begin DESCRIPTION
+
 Several forms of output are available from the analysis.
 
 The @dfn{flat profile} shows how much time your program spent in each function,
@@ -145,6 +246,7 @@ lot of time.  @xref{Call Graph}.
 The @dfn{annotated source} listing is a copy of the program's
 source code, labeled with the number of times each line of the
 program was executed.  @xref{Annotated Source}.
+@c man end
 
 To better understand how profiling works, you may wish to read
 a description of its implementation.
@@ -297,6 +399,7 @@ The order of these options does not matter.
 @node Output Options,Analysis Options,,Invoking
 @section Output Options
 
+@c man begin OPTIONS
 These options specify which of several output formats
 @code{gprof} should produce.
 
@@ -635,6 +738,8 @@ may be given; only one @var{function_name} may be indicated with each
 
 @end table
 
+@c man end
+
 Note that only one function can be specified with each @code{-e},
 @code{-E}, @code{-f} or @code{-F} option.  To specify more than one
 function, use multiple options.  For example, this command: