Changeset 609 for branches/GNU/src/binutils/gprof/gprof.texi

Timestamp:

Aug 16, 2003, 6:59:22 PM (22 years ago)

Author:

bird

Message:

binutils v2.14 - offical sources.

File:

• branches/GNU/src/binutils/gprof/gprof.texi (modified) (9 diffs, 1 prop)

branches/GNU/src/binutils/gprof/gprof.texi

@@ -19 +19 @@
 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".
+
+@c man end
+
+@ignore
+Permission is granted to process this file through Tex and print the
+results, provided the printed document carries copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+@end ifinfo
+
+@finalout
+@smallbook
+
+@titlepage
+@title GNU gprof
+@subtitle The @sc{gnu} Profiler 
+@author Jay Fenlason and Richard Stallman
+
+@page
+
+This manual describes the @sc{gnu} profiler, @code{gprof}, and how you
+can use it to determine which parts of a program are taking most of the
+execution time.  We assume that you know how to write, compile, and
+execute programs.  @sc{gnu} @code{gprof} was written by Jay Fenlason.
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.
 
       Permission is granted to copy, distribute and/or modify this document
@@ -28 +65 @@
       section entitled "GNU Free Documentation License".
 
-@ignore
-Permission is granted to process this file through Tex and print the
-results, provided the printed document carries copying permission
-notice identical to this one except for the removal of this paragraph
-(this paragraph not being relevant to the printed manual).
-
-@end ignore
-@end ifinfo
-
-@finalout
-@smallbook
-
-@titlepage
-@title GNU gprof
-@subtitle The @sc{gnu} Profiler 
-@author Jay Fenlason and Richard Stallman
-
-@page
-
-This manual describes the @sc{gnu} profiler, @code{gprof}, and how you
-can use it to determine which parts of a program are taking most of the
-execution time.  We assume that you know how to write, compile, and
-execute programs.  @sc{gnu} @code{gprof} was written by Jay Fenlason.
-
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 92, 97, 98, 99, 2000 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".
-
 @end titlepage
 
-@ifinfo
+@ifnottex
 @node Top
 @top Profiling a Program: Where Does It Spend Its Time?
@@ -92 +95 @@
 * GNU Free Documentation License::  GNU Free Documentation License
 @end menu
-@end ifinfo
+@end ifnottex
 
 @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
@@ -130 +229 @@
 The next three chapters explain these steps in greater detail.
 
+@c man begin DESCRIPTION
+
 Several forms of output are available from the analysis.
 
@@ -146 +247 @@
 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
@@ -256 +358 @@
 The Perl script @code{bbconv.pl}, included with the @code{gprof}
 source distribution, will convert a @file{bb.out} file into
-a format readable by @code{gprof}.
+a format readable by @code{gprof}.  Invoke it like this:
+
+@smallexample
+bbconv.pl < bb.out > @var{bh-data}
+@end smallexample
+
+This translates the information in @file{bb.out} into a form that
+@code{gprof} can understand.  But you still need to tell @code{gprof}
+about the existence of this translated information.  To do that, include
+@var{bb-data} on the @code{gprof} command line, @emph{along with
+@file{gmon.out}}, like this:
+
+@smallexample
+gprof @var{options} @var{executable-file} gmon.out @var{bb-data} [@var{yet-more-profile-data-files}@dots{}] [> @var{outfile}]
+@end smallexample
 
 @node Invoking
@@ -298 +414 @@
 @section Output Options
 
+@c man begin OPTIONS
 These options specify which of several output formats
 @code{gprof} should produce.
@@ -635 +752 @@
 
 @end table
+
+@c man end
 
 Note that only one function can be specified with each @code{-e},
@@ -1732 +1851 @@
 consists of a header containing the magic cookie and a version number,
 as well as some spare bytes available for future extensions.  All data
-in a profile data file is in the native format of the host on which
-the profile was collected.  @sc{gnu} @code{gprof} adapts automatically to the
-byte-order in use.
+in a profile data file is in the native format of the target for which
+the profile was collected.  @sc{gnu} @code{gprof} adapts automatically
+to the byte-order in use.
 
 In the new file format, the header is followed by a sequence of