diff options
Diffstat (limited to 'share/doc/gprof.html')
| -rw-r--r-- | share/doc/gprof.html | 2906 |
1 files changed, 2906 insertions, 0 deletions
diff --git a/share/doc/gprof.html b/share/doc/gprof.html new file mode 100644 index 0000000..f6cc886 --- /dev/null +++ b/share/doc/gprof.html @@ -0,0 +1,2906 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<!-- This file documents the gprof profiler of the GNU system. + +Copyright (C) 1988-2023 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.3 +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". + --> +<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ --> +<head> +<title>GNU gprof</title> + +<meta name="description" content="GNU gprof"> +<meta name="keywords" content="GNU gprof"> +<meta name="resource-type" content="document"> +<meta name="distribution" content="global"> +<meta name="Generator" content="makeinfo"> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link href="#Top" rel="start" title="Top"> +<link href="#SEC_Contents" rel="contents" title="Table of Contents"> +<link href="dir.html#Top" rel="up" title="(dir)"> +<style type="text/css"> +<!-- +a.summary-letter {text-decoration: none} +blockquote.smallquotation {font-size: smaller} +div.display {margin-left: 3.2em} +div.example {margin-left: 3.2em} +div.indentedblock {margin-left: 3.2em} +div.lisp {margin-left: 3.2em} +div.smalldisplay {margin-left: 3.2em} +div.smallexample {margin-left: 3.2em} +div.smallindentedblock {margin-left: 3.2em; font-size: smaller} +div.smalllisp {margin-left: 3.2em} +kbd {font-style:oblique} +pre.display {font-family: inherit} +pre.format {font-family: inherit} +pre.menu-comment {font-family: serif} +pre.menu-preformatted {font-family: serif} +pre.smalldisplay {font-family: inherit; font-size: smaller} +pre.smallexample {font-size: smaller} +pre.smallformat {font-family: inherit; font-size: smaller} +pre.smalllisp {font-size: smaller} +span.nocodebreak {white-space:nowrap} +span.nolinebreak {white-space:nowrap} +span.roman {font-family:serif; font-weight:normal} +span.sansserif {font-family:sans-serif; font-weight:normal} +ul.no-bullet {list-style: none} +--> +</style> + + +</head> + +<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000"> +<h1 class="settitle" align="center">GNU gprof</h1> + + + + + +<a name="SEC_Contents"></a> +<h2 class="contents-heading">Table of Contents</h2> + +<div class="contents"> + +<ul class="no-bullet"> + <li><a name="toc-Introduction-to-Profiling" href="#Introduction">1 Introduction to Profiling</a></li> + <li><a name="toc-Compiling-a-Program-for-Profiling" href="#Compiling">2 Compiling a Program for Profiling</a></li> + <li><a name="toc-Executing-the-Program" href="#Executing">3 Executing the Program</a></li> + <li><a name="toc-gprof-Command-Summary" href="#Invoking">4 <code>gprof</code> Command Summary</a> + <ul class="no-bullet"> + <li><a name="toc-Output-Options-1" href="#Output-Options">4.1 Output Options</a></li> + <li><a name="toc-Analysis-Options-1" href="#Analysis-Options">4.2 Analysis Options</a></li> + <li><a name="toc-Miscellaneous-Options-1" href="#Miscellaneous-Options">4.3 Miscellaneous Options</a></li> + <li><a name="toc-Deprecated-Options-1" href="#Deprecated-Options">4.4 Deprecated Options</a></li> + <li><a name="toc-Symspecs-1" href="#Symspecs">4.5 Symspecs</a></li> + </ul></li> + <li><a name="toc-Interpreting-gprof_0027s-Output" href="#Output">5 Interpreting <code>gprof</code>’s Output</a> + <ul class="no-bullet"> + <li><a name="toc-The-Flat-Profile" href="#Flat-Profile">5.1 The Flat Profile</a></li> + <li><a name="toc-The-Call-Graph" href="#Call-Graph">5.2 The Call Graph</a> + <ul class="no-bullet"> + <li><a name="toc-The-Primary-Line" href="#Primary">5.2.1 The Primary Line</a></li> + <li><a name="toc-Lines-for-a-Function_0027s-Callers" href="#Callers">5.2.2 Lines for a Function’s Callers</a></li> + <li><a name="toc-Lines-for-a-Function_0027s-Subroutines" href="#Subroutines">5.2.3 Lines for a Function’s Subroutines</a></li> + <li><a name="toc-How-Mutually-Recursive-Functions-Are-Described" href="#Cycles">5.2.4 How Mutually Recursive Functions Are Described</a></li> + </ul></li> + <li><a name="toc-Line_002dby_002dline-Profiling" href="#Line_002dby_002dline">5.3 Line-by-line Profiling</a></li> + <li><a name="toc-The-Annotated-Source-Listing" href="#Annotated-Source">5.4 The Annotated Source Listing</a></li> + </ul></li> + <li><a name="toc-Inaccuracy-of-gprof-Output" href="#Inaccuracy">6 Inaccuracy of <code>gprof</code> Output</a> + <ul class="no-bullet"> + <li><a name="toc-Statistical-Sampling-Error" href="#Sampling-Error">6.1 Statistical Sampling Error</a></li> + <li><a name="toc-Estimating-children-Times" href="#Assumptions">6.2 Estimating <code>children</code> Times</a></li> + </ul></li> + <li><a name="toc-Answers-to-Common-Questions" href="#How-do-I_003f">7 Answers to Common Questions</a></li> + <li><a name="toc-Incompatibilities-with-Unix-gprof" href="#Incompatibilities">8 Incompatibilities with Unix <code>gprof</code></a></li> + <li><a name="toc-Details-of-Profiling" href="#Details">9 Details of Profiling</a> + <ul class="no-bullet"> + <li><a name="toc-Implementation-of-Profiling" href="#Implementation">9.1 Implementation of Profiling</a></li> + <li><a name="toc-Profiling-Data-File-Format" href="#File-Format">9.2 Profiling Data File Format</a> + <ul class="no-bullet"> + <li><a name="toc-Histogram-Records" href="#Histogram-Records">9.2.1 Histogram Records</a></li> + <li><a name="toc-Call_002dGraph-Records" href="#Call_002dGraph-Records">9.2.2 Call-Graph Records</a></li> + <li><a name="toc-Basic_002dBlock-Execution-Count-Records" href="#Basic_002dBlock-Execution-Count-Records">9.2.3 Basic-Block Execution Count Records</a></li> + </ul></li> + <li><a name="toc-gprof_0027s-Internal-Operation" href="#Internals">9.3 <code>gprof</code>’s Internal Operation</a></li> + <li><a name="toc-Debugging-gprof" href="#Debugging">9.4 Debugging <code>gprof</code></a></li> + </ul></li> + <li><a name="toc-GNU-Free-Documentation-License-1" href="#GNU-Free-Documentation-License">Appendix A GNU Free Documentation License</a></li> +</ul> +</div> + + +<a name="Top"></a> +<div class="header"> +<p> +Next: <a href="#Introduction" accesskey="n" rel="next">Introduction</a>, Up: <a href="dir.html#Top" accesskey="u" rel="up">(dir)</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Profiling-a-Program_003a-Where-Does-It-Spend-Its-Time_003f"></a> +<h1 class="top">Profiling a Program: Where Does It Spend Its Time?</h1> + +<p>This manual describes the <small>GNU</small> profiler, <code>gprof</code>, 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. <small>GNU</small> <code>gprof</code> was written by Jay Fenlason. +</p> +<p>This manual is for <code>gprof</code> +(Arm GNU Toolchain 13.2.rel1 (Build arm-13.7)) +version 2.41.0. +</p> +<p>This document is distributed under the terms of the GNU Free +Documentation License version 1.3. A copy of the license is included +in the section entitled “GNU Free Documentation License”. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Introduction" accesskey="1">Introduction</a>:</td><td> </td><td align="left" valign="top">What profiling means, and why it is useful. +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Compiling" accesskey="2">Compiling</a>:</td><td> </td><td align="left" valign="top">How to compile your program for profiling. +</td></tr> +<tr><td align="left" valign="top">• <a href="#Executing" accesskey="3">Executing</a>:</td><td> </td><td align="left" valign="top">Executing your program to generate profile data +</td></tr> +<tr><td align="left" valign="top">• <a href="#Invoking" accesskey="4">Invoking</a>:</td><td> </td><td align="left" valign="top">How to run <code>gprof</code>, and its options +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Output" accesskey="5">Output</a>:</td><td> </td><td align="left" valign="top">Interpreting <code>gprof</code>’s output +</td></tr> +<tr><th colspan="3" align="left" valign="top"><pre class="menu-comment"> +</pre></th></tr><tr><td align="left" valign="top">• <a href="#Inaccuracy" accesskey="6">Inaccuracy</a>:</td><td> </td><td align="left" valign="top">Potential problems you should be aware of +</td></tr> +<tr><td align="left" valign="top">• <a href="#How-do-I_003f" accesskey="7">How do I?</a>:</td><td> </td><td align="left" valign="top">Answers to common questions +</td></tr> +<tr><td align="left" valign="top">• <a href="#Incompatibilities" accesskey="8">Incompatibilities</a>:</td><td> </td><td align="left" valign="top">(between <small>GNU</small> <code>gprof</code> and Unix <code>gprof</code>.) +</td></tr> +<tr><td align="left" valign="top">• <a href="#Details" accesskey="9">Details</a>:</td><td> </td><td align="left" valign="top">Details of how profiling is done +</td></tr> +<tr><td align="left" valign="top">• <a href="#GNU-Free-Documentation-License">GNU Free Documentation License</a>:</td><td> </td><td align="left" valign="top">GNU Free Documentation License +</td></tr> +</table> + +<hr> +<a name="Introduction"></a> +<div class="header"> +<p> +Next: <a href="#Compiling" accesskey="n" rel="next">Compiling</a>, Previous: <a href="#Top" accesskey="p" rel="previous">Top</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Introduction-to-Profiling"></a> +<h2 class="chapter">1 Introduction to Profiling</h2> + + +<p>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 +expected, and might be candidates for rewriting to make your program +execute faster. It can also tell you which functions are being called more +or less often than you expected. This may help you spot bugs that had +otherwise been unnoticed. +</p> +<p>Since the profiler uses information collected during the actual execution +of your program, it can be used on programs that are too large or too +complex to analyze by reading the source. However, how your program is run +will affect the information that shows up in the profile data. If you +don’t use some feature of your program while it is being profiled, no +profile information will be generated for that feature. +</p> +<p>Profiling has several steps: +</p> +<ul> +<li> You must compile and link your program with profiling enabled. +See <a href="#Compiling">Compiling a Program for Profiling</a>. + +</li><li> You must execute your program to generate a profile data file. +See <a href="#Executing">Executing the Program</a>. + +</li><li> You must run <code>gprof</code> to analyze the profile data. +See <a href="#Invoking"><code>gprof</code> Command Summary</a>. +</li></ul> + +<p>The next three chapters explain these steps in greater detail. +</p> + +<p>Several forms of output are available from the analysis. +</p> +<p>The <em>flat profile</em> shows how much time your program spent in each function, +and how many times that function was called. If you simply want to know +which functions burn most of the cycles, it is stated concisely here. +See <a href="#Flat-Profile">The Flat Profile</a>. +</p> +<p>The <em>call graph</em> shows, for each function, which functions called it, which +other functions it called, and how many times. There is also an estimate +of how much time was spent in the subroutines of each function. This can +suggest places where you might try to eliminate function calls that use a +lot of time. See <a href="#Call-Graph">The Call Graph</a>. +</p> +<p>The <em>annotated source</em> listing is a copy of the program’s +source code, labeled with the number of times each line of the +program was executed. See <a href="#Annotated-Source">The Annotated Source +Listing</a>. +</p> +<p>To better understand how profiling works, you may wish to read +a description of its implementation. +See <a href="#Implementation">Implementation of Profiling</a>. +</p> +<hr> +<a name="Compiling"></a> +<div class="header"> +<p> +Next: <a href="#Executing" accesskey="n" rel="next">Executing</a>, Previous: <a href="#Introduction" accesskey="p" rel="previous">Introduction</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Compiling-a-Program-for-Profiling"></a> +<h2 class="chapter">2 Compiling a Program for Profiling</h2> + +<p>The first step in generating profile information for your program is +to compile and link it with profiling enabled. +</p> +<p>To compile a source file for profiling, specify the ‘<samp>-pg</samp>’ option when +you run the compiler. (This is in addition to the options you normally +use.) +</p> +<p>To link the program for profiling, if you use a compiler such as <code>cc</code> +to do the linking, simply specify ‘<samp>-pg</samp>’ in addition to your usual +options. The same option, ‘<samp>-pg</samp>’, alters either compilation or linking +to do what is necessary for profiling. Here are examples: +</p> +<div class="example"> +<pre class="example">cc -g -c myprog.c utils.c -pg +cc -o myprog myprog.o utils.o -pg +</pre></div> + +<p>The ‘<samp>-pg</samp>’ option also works with a command that both compiles and links: +</p> +<div class="example"> +<pre class="example">cc -o myprog myprog.c utils.c -g -pg +</pre></div> + +<p>Note: The ‘<samp>-pg</samp>’ option must be part of your compilation options +as well as your link options. If it is not then no call-graph data +will be gathered and when you run <code>gprof</code> you will get an error +message like this: +</p> +<div class="example"> +<pre class="example">gprof: gmon.out file is missing call-graph data +</pre></div> + +<p>If you add the ‘<samp>-Q</samp>’ switch to suppress the printing of the call +graph data you will still be able to see the time samples: +</p> +<div class="example"> +<pre class="example">Flat profile: + +Each sample counts as 0.01 seconds. + % cumulative self self total + time seconds seconds calls Ts/call Ts/call name + 44.12 0.07 0.07 zazLoop + 35.29 0.14 0.06 main + 20.59 0.17 0.04 bazMillion +</pre></div> + +<p>If you run the linker <code>ld</code> directly instead of through a compiler +such as <code>cc</code>, you may have to specify a profiling startup file +<samp>gcrt0.o</samp> as the first input file instead of the usual startup +file <samp>crt0.o</samp>. In addition, you would probably want to +specify the profiling C library, <samp>libc_p.a</samp>, by writing +‘<samp>-lc_p</samp>’ instead of the usual ‘<samp>-lc</samp>’. This is not absolutely +necessary, but doing this gives you number-of-calls information for +standard library functions such as <code>read</code> and <code>open</code>. For +example: +</p> +<div class="example"> +<pre class="example">ld -o myprog /lib/gcrt0.o myprog.o utils.o -lc_p +</pre></div> + +<p>If you are running the program on a system which supports shared +libraries you may run into problems with the profiling support code in +a shared library being called before that library has been fully +initialised. This is usually detected by the program encountering a +segmentation fault as soon as it is run. The solution is to link +against a static version of the library containing the profiling +support code, which for <code>gcc</code> users can be done via the +‘<samp>-static</samp>’ or ‘<samp>-static-libgcc</samp>’ command-line option. For +example: +</p> +<div class="example"> +<pre class="example">gcc -g -pg -static-libgcc myprog.c utils.c -o myprog +</pre></div> + +<p>If you compile only some of the modules of the program with ‘<samp>-pg</samp>’, you +can still profile the program, but you won’t get complete information about +the modules that were compiled without ‘<samp>-pg</samp>’. The only information +you get for the functions in those modules is the total time spent in them; +there is no record of how many times they were called, or from where. This +will not affect the flat profile (except that the <code>calls</code> field for +the functions will be blank), but will greatly reduce the usefulness of the +call graph. +</p> +<p>If you wish to perform line-by-line profiling you should use the +<code>gcov</code> tool instead of <code>gprof</code>. See that tool’s manual or +info pages for more details of how to do this. +</p> +<p>Note, older versions of <code>gcc</code> produce line-by-line profiling +information that works with <code>gprof</code> rather than <code>gcov</code> so +there is still support for displaying this kind of information in +<code>gprof</code>. See <a href="#Line_002dby_002dline">Line-by-line Profiling</a>. +</p> +<p>It also worth noting that <code>gcc</code> implements a +‘<samp>-finstrument-functions</samp>’ command-line option which will insert +calls to special user supplied instrumentation routines at the entry +and exit of every function in their program. This can be used to +implement an alternative profiling scheme. +</p> +<hr> +<a name="Executing"></a> +<div class="header"> +<p> +Next: <a href="#Invoking" accesskey="n" rel="next">Invoking</a>, Previous: <a href="#Compiling" accesskey="p" rel="previous">Compiling</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Executing-the-Program"></a> +<h2 class="chapter">3 Executing the Program</h2> + +<p>Once the program is compiled for profiling, you must run it in order to +generate the information that <code>gprof</code> needs. Simply run the program +as usual, using the normal arguments, file names, etc. The program should +run normally, producing the same output as usual. It will, however, run +somewhat slower than normal because of the time spent collecting and +writing the profile data. +</p> +<p>The way you run the program—the arguments and input that you give +it—may have a dramatic effect on what the profile information shows. The +profile data will describe the parts of the program that were activated for +the particular input you use. For example, if the first command you give +to your program is to quit, the profile data will show the time used in +initialization and in cleanup, but not much else. +</p> +<p>Your program will write the profile data into a file called <samp>gmon.out</samp> +just before exiting. If there is already a file called <samp>gmon.out</samp>, +its contents are overwritten. You can rename the file afterwards if you +are concerned that it may be overwritten. If your system libc allows you +may be able to write the profile data under a different name. Set the +GMON_OUT_PREFIX environment variable; this name will be appended with +the PID of the running program. +</p> +<p>In order to write the <samp>gmon.out</samp> file properly, your program must exit +normally: by returning from <code>main</code> or by calling <code>exit</code>. Calling +the low-level function <code>_exit</code> does not write the profile data, and +neither does abnormal termination due to an unhandled signal. +</p> +<p>The <samp>gmon.out</samp> file is written in the program’s <em>current working +directory</em> at the time it exits. This means that if your program calls +<code>chdir</code>, the <samp>gmon.out</samp> file will be left in the last directory +your program <code>chdir</code>’d to. If you don’t have permission to write in +this directory, the file is not written, and you will get an error message. +</p> +<p>Older versions of the <small>GNU</small> profiling library may also write a file +called <samp>bb.out</samp>. This file, if present, contains an human-readable +listing of the basic-block execution counts. Unfortunately, the +appearance of a human-readable <samp>bb.out</samp> means the basic-block +counts didn’t get written into <samp>gmon.out</samp>. +The Perl script <code>bbconv.pl</code>, included with the <code>gprof</code> +source distribution, will convert a <samp>bb.out</samp> file into +a format readable by <code>gprof</code>. Invoke it like this: +</p> +<div class="smallexample"> +<pre class="smallexample">bbconv.pl < bb.out > <var>bh-data</var> +</pre></div> + +<p>This translates the information in <samp>bb.out</samp> into a form that +<code>gprof</code> can understand. But you still need to tell <code>gprof</code> +about the existence of this translated information. To do that, include +<var>bb-data</var> on the <code>gprof</code> command line, <em>along with +<samp>gmon.out</samp></em>, like this: +</p> +<div class="smallexample"> +<pre class="smallexample">gprof <var>options</var> <var>executable-file</var> gmon.out <var>bb-data</var> [<var>yet-more-profile-data-files</var>…] [> <var>outfile</var>] +</pre></div> + +<hr> +<a name="Invoking"></a> +<div class="header"> +<p> +Next: <a href="#Output" accesskey="n" rel="next">Output</a>, Previous: <a href="#Executing" accesskey="p" rel="previous">Executing</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="gprof-Command-Summary"></a> +<h2 class="chapter">4 <code>gprof</code> Command Summary</h2> + +<p>After you have a profile data file <samp>gmon.out</samp>, you can run <code>gprof</code> +to interpret the information in it. The <code>gprof</code> program prints a +flat profile and a call graph on standard output. Typically you would +redirect the output of <code>gprof</code> into a file with ‘<samp>></samp>’. +</p> +<p>You run <code>gprof</code> like this: +</p> +<div class="smallexample"> +<pre class="smallexample">gprof <var>options</var> [<var>executable-file</var> [<var>profile-data-files</var>…]] [> <var>outfile</var>] +</pre></div> + +<p>Here square-brackets indicate optional arguments. +</p> +<p>If you omit the executable file name, the file <samp>a.out</samp> is used. If +you give no profile data file name, the file <samp>gmon.out</samp> is used. If +any file is not in the proper format, or if the profile data file does not +appear to belong to the executable file, an error message is printed. +</p> +<p>You can give more than one profile data file by entering all their names +after the executable file name; then the statistics in all the data files +are summed together. +</p> +<p>The order of these options does not matter. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Output-Options" accesskey="1">Output Options</a>:</td><td> </td><td align="left" valign="top">Controlling <code>gprof</code>’s output style +</td></tr> +<tr><td align="left" valign="top">• <a href="#Analysis-Options" accesskey="2">Analysis Options</a>:</td><td> </td><td align="left" valign="top">Controlling how <code>gprof</code> analyzes its data +</td></tr> +<tr><td align="left" valign="top">• <a href="#Miscellaneous-Options" accesskey="3">Miscellaneous Options</a>:</td><td> </td><td align="left" valign="top"> +</td></tr> +<tr><td align="left" valign="top">• <a href="#Deprecated-Options" accesskey="4">Deprecated Options</a>:</td><td> </td><td align="left" valign="top">Options you no longer need to use, but which + have been retained for compatibility +</td></tr> +<tr><td align="left" valign="top">• <a href="#Symspecs" accesskey="5">Symspecs</a>:</td><td> </td><td align="left" valign="top">Specifying functions to include or exclude +</td></tr> +</table> + +<hr> +<a name="Output-Options"></a> +<div class="header"> +<p> +Next: <a href="#Analysis-Options" accesskey="n" rel="next">Analysis Options</a>, Up: <a href="#Invoking" accesskey="u" rel="up">Invoking</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Output-Options-1"></a> +<h3 class="section">4.1 Output Options</h3> + +<p>These options specify which of several output formats +<code>gprof</code> should produce. +</p> +<p>Many of these options take an optional <em>symspec</em> to specify +functions to be included or excluded. These options can be +specified multiple times, with different symspecs, to include +or exclude sets of symbols. See <a href="#Symspecs">Symspecs</a>. +</p> +<p>Specifying any of these options overrides the default (‘<samp>-p -q</samp>’), +which prints a flat profile and call graph analysis +for all functions. +</p> +<dl compact="compact"> +<dt><code>-A[<var>symspec</var>]</code></dt> +<dt><code>--annotated-source[=<var>symspec</var>]</code></dt> +<dd><p>The ‘<samp>-A</samp>’ option causes <code>gprof</code> to print annotated source code. +If <var>symspec</var> is specified, print output only for matching symbols. +See <a href="#Annotated-Source">The Annotated Source Listing</a>. +</p> +</dd> +<dt><code>-b</code></dt> +<dt><code>--brief</code></dt> +<dd><p>If the ‘<samp>-b</samp>’ option is given, <code>gprof</code> doesn’t print the +verbose blurbs that try to explain the meaning of all of the fields in +the tables. This is useful if you intend to print out the output, or +are tired of seeing the blurbs. +</p> +</dd> +<dt><code>-B</code></dt> +<dd><p>The ‘<samp>-B</samp>’ option causes <code>gprof</code> to print the call graph analysis. +</p> +</dd> +<dt><code>-C[<var>symspec</var>]</code></dt> +<dt><code>--exec-counts[=<var>symspec</var>]</code></dt> +<dd><p>The ‘<samp>-C</samp>’ option causes <code>gprof</code> to +print a tally of functions and the number of times each was called. +If <var>symspec</var> is specified, print tally only for matching symbols. +</p> +<p>If the profile data file contains basic-block count records, specifying +the ‘<samp>-l</samp>’ option, along with ‘<samp>-C</samp>’, will cause basic-block +execution counts to be tallied and displayed. +</p> +</dd> +<dt><code>-i</code></dt> +<dt><code>--file-info</code></dt> +<dd><p>The ‘<samp>-i</samp>’ option causes <code>gprof</code> to display summary information +about the profile data file(s) and then exit. The number of histogram, +call graph, and basic-block count records is displayed. +</p> +</dd> +<dt><code>-I <var>dirs</var></code></dt> +<dt><code>--directory-path=<var>dirs</var></code></dt> +<dd><p>The ‘<samp>-I</samp>’ option specifies a list of search directories in +which to find source files. Environment variable <var>GPROF_PATH</var> +can also be used to convey this information. +Used mostly for annotated source output. +</p> +</dd> +<dt><code>-J[<var>symspec</var>]</code></dt> +<dt><code>--no-annotated-source[=<var>symspec</var>]</code></dt> +<dd><p>The ‘<samp>-J</samp>’ option causes <code>gprof</code> not to +print annotated source code. +If <var>symspec</var> is specified, <code>gprof</code> prints annotated source, +but excludes matching symbols. +</p> +</dd> +<dt><code>-L</code></dt> +<dt><code>--print-path</code></dt> +<dd><p>Normally, source filenames are printed with the path +component suppressed. The ‘<samp>-L</samp>’ option causes <code>gprof</code> +to print the full pathname of +source filenames, which is determined +from symbolic debugging information in the image file +and is relative to the directory in which the compiler +was invoked. +</p> +</dd> +<dt><code>-p[<var>symspec</var>]</code></dt> +<dt><code>--flat-profile[=<var>symspec</var>]</code></dt> +<dd><p>The ‘<samp>-p</samp>’ option causes <code>gprof</code> to print a flat profile. +If <var>symspec</var> is specified, print flat profile only for matching symbols. +See <a href="#Flat-Profile">The Flat Profile</a>. +</p> +</dd> +<dt><code>-P[<var>symspec</var>]</code></dt> +<dt><code>--no-flat-profile[=<var>symspec</var>]</code></dt> +<dd><p>The ‘<samp>-P</samp>’ option causes <code>gprof</code> to suppress printing a flat profile. +If <var>symspec</var> is specified, <code>gprof</code> prints a flat profile, +but excludes matching symbols. +</p> +</dd> +<dt><code>-q[<var>symspec</var>]</code></dt> +<dt><code>--graph[=<var>symspec</var>]</code></dt> +<dd><p>The ‘<samp>-q</samp>’ option causes <code>gprof</code> to print the call graph analysis. +If <var>symspec</var> is specified, print call graph only for matching symbols +and their children. +See <a href="#Call-Graph">The Call Graph</a>. +</p> +</dd> +<dt><code>-Q[<var>symspec</var>]</code></dt> +<dt><code>--no-graph[=<var>symspec</var>]</code></dt> +<dd><p>The ‘<samp>-Q</samp>’ option causes <code>gprof</code> to suppress printing the +call graph. +If <var>symspec</var> is specified, <code>gprof</code> prints a call graph, +but excludes matching symbols. +</p> +</dd> +<dt><code>-t</code></dt> +<dt><code>--table-length=<var>num</var></code></dt> +<dd><p>The ‘<samp>-t</samp>’ option causes the <var>num</var> most active source lines in +each source file to be listed when source annotation is enabled. The +default is 10. +</p> +</dd> +<dt><code>-y</code></dt> +<dt><code>--separate-files</code></dt> +<dd><p>This option affects annotated source output only. +Normally, <code>gprof</code> prints annotated source files +to standard-output. If this option is specified, +annotated source for a file named <samp>path/<var>filename</var></samp> +is generated in the file <samp><var>filename</var>-ann</samp>. If the underlying +file system would truncate <samp><var>filename</var>-ann</samp> so that it +overwrites the original <samp><var>filename</var></samp>, <code>gprof</code> generates +annotated source in the file <samp><var>filename</var>.ann</samp> instead (if the +original file name has an extension, that extension is <em>replaced</em> +with <samp>.ann</samp>). +</p> +</dd> +<dt><code>-Z[<var>symspec</var>]</code></dt> +<dt><code>--no-exec-counts[=<var>symspec</var>]</code></dt> +<dd><p>The ‘<samp>-Z</samp>’ option causes <code>gprof</code> not to +print a tally of functions and the number of times each was called. +If <var>symspec</var> is specified, print tally, but exclude matching symbols. +</p> +</dd> +<dt><code>-r</code></dt> +<dt><code>--function-ordering</code></dt> +<dd><p>The ‘<samp>--function-ordering</samp>’ option causes <code>gprof</code> to print a +suggested function ordering for the program based on profiling data. +This option suggests an ordering which may improve paging, tlb and +cache behavior for the program on systems which support arbitrary +ordering of functions in an executable. +</p> +<p>The exact details of how to force the linker to place functions +in a particular order is system dependent and out of the scope of this +manual. +</p> +</dd> +<dt><code>-R <var>map_file</var></code></dt> +<dt><code>--file-ordering <var>map_file</var></code></dt> +<dd><p>The ‘<samp>--file-ordering</samp>’ option causes <code>gprof</code> to print a +suggested .o link line ordering for the program based on profiling data. +This option suggests an ordering which may improve paging, tlb and +cache behavior for the program on systems which do not support arbitrary +ordering of functions in an executable. +</p> +<p>Use of the ‘<samp>-a</samp>’ argument is highly recommended with this option. +</p> +<p>The <var>map_file</var> argument is a pathname to a file which provides +function name to object file mappings. The format of the file is similar to +the output of the program <code>nm</code>. +</p> +<div class="smallexample"> +<pre class="smallexample">c-parse.o:00000000 T yyparse +c-parse.o:00000004 C yyerrflag +c-lang.o:00000000 T maybe_objc_method_name +c-lang.o:00000000 T print_lang_statistics +c-lang.o:00000000 T recognize_objc_keyword +c-decl.o:00000000 T print_lang_identifier +c-decl.o:00000000 T print_lang_type +… + +</pre></div> + +<p>To create a <var>map_file</var> with <small>GNU</small> <code>nm</code>, type a command like +<kbd>nm --extern-only --defined-only -v --print-file-name program-name</kbd>. +</p> +</dd> +<dt><code>-T</code></dt> +<dt><code>--traditional</code></dt> +<dd><p>The ‘<samp>-T</samp>’ option causes <code>gprof</code> to print its output in +“traditional” BSD style. +</p> +</dd> +<dt><code>-w <var>width</var></code></dt> +<dt><code>--width=<var>width</var></code></dt> +<dd><p>Sets width of output lines to <var>width</var>. +Currently only used when printing the function index at the bottom +of the call graph. +</p> +</dd> +<dt><code>-x</code></dt> +<dt><code>--all-lines</code></dt> +<dd><p>This option affects annotated source output only. +By default, only the lines at the beginning of a basic-block +are annotated. If this option is specified, every line in +a basic-block is annotated by repeating the annotation for the +first line. This behavior is similar to <code>tcov</code>’s ‘<samp>-a</samp>’. +</p> +</dd> +<dt><code>--demangle[=<var>style</var>]</code></dt> +<dt><code>--no-demangle</code></dt> +<dd><p>These options control whether C++ symbol names should be demangled when +printing output. The default is to demangle symbols. The +<code>--no-demangle</code> option may be used to turn off demangling. Different +compilers have different mangling styles. The optional demangling style +argument can be used to choose an appropriate demangling style for your +compiler. +</p></dd> +</dl> + +<hr> +<a name="Analysis-Options"></a> +<div class="header"> +<p> +Next: <a href="#Miscellaneous-Options" accesskey="n" rel="next">Miscellaneous Options</a>, Previous: <a href="#Output-Options" accesskey="p" rel="previous">Output Options</a>, Up: <a href="#Invoking" accesskey="u" rel="up">Invoking</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Analysis-Options-1"></a> +<h3 class="section">4.2 Analysis Options</h3> + +<dl compact="compact"> +<dt><code>-a</code></dt> +<dt><code>--no-static</code></dt> +<dd><p>The ‘<samp>-a</samp>’ option causes <code>gprof</code> to suppress the printing of +statically declared (private) functions. (These are functions whose +names are not listed as global, and which are not visible outside the +file/function/block where they were defined.) Time spent in these +functions, calls to/from them, etc., will all be attributed to the +function that was loaded directly before it in the executable file. +This option affects both the flat profile and the call graph. +</p> +</dd> +<dt><code>-c</code></dt> +<dt><code>--static-call-graph</code></dt> +<dd><p>The ‘<samp>-c</samp>’ option causes the call graph of the program to be +augmented by a heuristic which examines the text space of the object +file and identifies function calls in the binary machine code. +Since normal call graph records are only generated when functions are +entered, this option identifies children that could have been called, +but never were. Calls to functions that were not compiled with +profiling enabled are also identified, but only if symbol table +entries are present for them. +Calls to dynamic library routines are typically <em>not</em> found +by this option. +Parents or children identified via this heuristic +are indicated in the call graph with call counts of ‘<samp>0</samp>’. +</p> +</dd> +<dt><code>-D</code></dt> +<dt><code>--ignore-non-functions</code></dt> +<dd><p>The ‘<samp>-D</samp>’ option causes <code>gprof</code> to ignore symbols which +are not known to be functions. This option will give more accurate +profile data on systems where it is supported (Solaris and HPUX for +example). +</p> +</dd> +<dt><code>-k <var>from</var>/<var>to</var></code></dt> +<dd><p>The ‘<samp>-k</samp>’ option allows you to delete from the call graph any arcs from +symbols matching symspec <var>from</var> to those matching symspec <var>to</var>. +</p> +</dd> +<dt><code>-l</code></dt> +<dt><code>--line</code></dt> +<dd><p>The ‘<samp>-l</samp>’ option enables line-by-line profiling, which causes +histogram hits to be charged to individual source code lines, +instead of functions. This feature only works with programs compiled +by older versions of the <code>gcc</code> compiler. Newer versions of +<code>gcc</code> are designed to work with the <code>gcov</code> tool instead. +</p> +<p>If the program was compiled with basic-block counting enabled, +this option will also identify how many times each line of +code was executed. +While line-by-line profiling can help isolate where in a large function +a program is spending its time, it also significantly increases +the running time of <code>gprof</code>, and magnifies statistical +inaccuracies. +See <a href="#Sampling-Error">Statistical Sampling Error</a>. +</p> +</dd> +<dt><code>--inline-file-names</code></dt> +<dd><p>This option causes <code>gprof</code> to print the source file after each +symbol in both the flat profile and the call graph. The full path to the +file is printed if used with the ‘<samp>-L</samp>’ option. +</p> +</dd> +<dt><code>-m <var>num</var></code></dt> +<dt><code>--min-count=<var>num</var></code></dt> +<dd><p>This option affects execution count output only. +Symbols that are executed less than <var>num</var> times are suppressed. +</p> +</dd> +<dt><code>-n<var>symspec</var></code></dt> +<dt><code>--time=<var>symspec</var></code></dt> +<dd><p>The ‘<samp>-n</samp>’ option causes <code>gprof</code>, in its call graph analysis, +to only propagate times for symbols matching <var>symspec</var>. +</p> +</dd> +<dt><code>-N<var>symspec</var></code></dt> +<dt><code>--no-time=<var>symspec</var></code></dt> +<dd><p>The ‘<samp>-n</samp>’ option causes <code>gprof</code>, in its call graph analysis, +not to propagate times for symbols matching <var>symspec</var>. +</p> +</dd> +<dt><code>-S<var>filename</var></code></dt> +<dt><code>--external-symbol-table=<var>filename</var></code></dt> +<dd><p>The ‘<samp>-S</samp>’ option causes <code>gprof</code> to read an external symbol table +file, such as <samp>/proc/kallsyms</samp>, rather than read the symbol table +from the given object file (the default is <code>a.out</code>). This is useful +for profiling kernel modules. +</p> +</dd> +<dt><code>-z</code></dt> +<dt><code>--display-unused-functions</code></dt> +<dd><p>If you give the ‘<samp>-z</samp>’ option, <code>gprof</code> will mention all +functions in the flat profile, even those that were never called, and +that had no time spent in them. This is useful in conjunction with the +‘<samp>-c</samp>’ option for discovering which routines were never called. +</p> +</dd> +</dl> + +<hr> +<a name="Miscellaneous-Options"></a> +<div class="header"> +<p> +Next: <a href="#Deprecated-Options" accesskey="n" rel="next">Deprecated Options</a>, Previous: <a href="#Analysis-Options" accesskey="p" rel="previous">Analysis Options</a>, Up: <a href="#Invoking" accesskey="u" rel="up">Invoking</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Miscellaneous-Options-1"></a> +<h3 class="section">4.3 Miscellaneous Options</h3> + +<dl compact="compact"> +<dt><code>-d[<var>num</var>]</code></dt> +<dt><code>--debug[=<var>num</var>]</code></dt> +<dd><p>The ‘<samp>-d <var>num</var></samp>’ option specifies debugging options. +If <var>num</var> is not specified, enable all debugging. +See <a href="#Debugging">Debugging <code>gprof</code></a>. +</p> +</dd> +<dt><code>-h</code></dt> +<dt><code>--help</code></dt> +<dd><p>The ‘<samp>-h</samp>’ option prints command line usage. +</p> +</dd> +<dt><code>-O<var>name</var></code></dt> +<dt><code>--file-format=<var>name</var></code></dt> +<dd><p>Selects the format of the profile data files. Recognized formats are +‘<samp>auto</samp>’ (the default), ‘<samp>bsd</samp>’, ‘<samp>4.4bsd</samp>’, ‘<samp>magic</samp>’, and +‘<samp>prof</samp>’ (not yet supported). +</p> +</dd> +<dt><code>-s</code></dt> +<dt><code>--sum</code></dt> +<dd><p>The ‘<samp>-s</samp>’ option causes <code>gprof</code> to summarize the information +in the profile data files it read in, and write out a profile data +file called <samp>gmon.sum</samp>, which contains all the information from +the profile data files that <code>gprof</code> read in. The file <samp>gmon.sum</samp> +may be one of the specified input files; the effect of this is to +merge the data in the other input files into <samp>gmon.sum</samp>. +</p> +<p>Eventually you can run <code>gprof</code> again without ‘<samp>-s</samp>’ to analyze the +cumulative data in the file <samp>gmon.sum</samp>. +</p> +</dd> +<dt><code>-v</code></dt> +<dt><code>--version</code></dt> +<dd><p>The ‘<samp>-v</samp>’ flag causes <code>gprof</code> to print the current version +number, and then exit. +</p> +</dd> +</dl> + +<hr> +<a name="Deprecated-Options"></a> +<div class="header"> +<p> +Next: <a href="#Symspecs" accesskey="n" rel="next">Symspecs</a>, Previous: <a href="#Miscellaneous-Options" accesskey="p" rel="previous">Miscellaneous Options</a>, Up: <a href="#Invoking" accesskey="u" rel="up">Invoking</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Deprecated-Options-1"></a> +<h3 class="section">4.4 Deprecated Options</h3> + +<p>These options have been replaced with newer versions that use symspecs. +</p> +<dl compact="compact"> +<dt><code>-e <var>function_name</var></code></dt> +<dd><p>The ‘<samp>-e <var>function</var></samp>’ option tells <code>gprof</code> to not print +information about the function <var>function_name</var> (and its +children…) in the call graph. The function will still be listed +as a child of any functions that call it, but its index number will be +shown as ‘<samp>[not printed]</samp>’. More than one ‘<samp>-e</samp>’ option may be +given; only one <var>function_name</var> may be indicated with each ‘<samp>-e</samp>’ +option. +</p> +</dd> +<dt><code>-E <var>function_name</var></code></dt> +<dd><p>The <code>-E <var>function</var></code> option works like the <code>-e</code> option, but +time spent in the function (and children who were not called from +anywhere else), will not be used to compute the percentages-of-time for +the call graph. More than one ‘<samp>-E</samp>’ option may be given; only one +<var>function_name</var> may be indicated with each ‘<samp>-E</samp>’ option. +</p> +</dd> +<dt><code>-f <var>function_name</var></code></dt> +<dd><p>The ‘<samp>-f <var>function</var></samp>’ option causes <code>gprof</code> to limit the +call graph to the function <var>function_name</var> and its children (and +their children…). More than one ‘<samp>-f</samp>’ option may be given; +only one <var>function_name</var> may be indicated with each ‘<samp>-f</samp>’ +option. +</p> +</dd> +<dt><code>-F <var>function_name</var></code></dt> +<dd><p>The ‘<samp>-F <var>function</var></samp>’ option works like the <code>-f</code> option, but +only time spent in the function and its children (and their +children…) will be used to determine total-time and +percentages-of-time for the call graph. More than one ‘<samp>-F</samp>’ option +may be given; only one <var>function_name</var> may be indicated with each +‘<samp>-F</samp>’ option. The ‘<samp>-F</samp>’ option overrides the ‘<samp>-E</samp>’ option. +</p> +</dd> +</dl> + + +<p>Note that only one function can be specified with each <code>-e</code>, +<code>-E</code>, <code>-f</code> or <code>-F</code> option. To specify more than one +function, use multiple options. For example, this command: +</p> +<div class="example"> +<pre class="example">gprof -e boring -f foo -f bar myprogram > gprof.output +</pre></div> + +<p>lists in the call graph all functions that were reached from either +<code>foo</code> or <code>bar</code> and were not reachable from <code>boring</code>. +</p> +<hr> +<a name="Symspecs"></a> +<div class="header"> +<p> +Previous: <a href="#Deprecated-Options" accesskey="p" rel="previous">Deprecated Options</a>, Up: <a href="#Invoking" accesskey="u" rel="up">Invoking</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Symspecs-1"></a> +<h3 class="section">4.5 Symspecs</h3> + +<p>Many of the output options allow functions to be included or excluded +using <em>symspecs</em> (symbol specifications), which observe the +following syntax: +</p> +<div class="example"> +<pre class="example"> filename_containing_a_dot +| funcname_not_containing_a_dot +| linenumber +| ( [ any_filename ] `:' ( any_funcname | linenumber ) ) +</pre></div> + +<p>Here are some sample symspecs: +</p> +<dl compact="compact"> +<dt>‘<samp>main.c</samp>’</dt> +<dd><p>Selects everything in file <samp>main.c</samp>—the +dot in the string tells <code>gprof</code> to interpret +the string as a filename, rather than as +a function name. To select a file whose +name does not contain a dot, a trailing colon +should be specified. For example, ‘<samp>odd:</samp>’ is +interpreted as the file named <samp>odd</samp>. +</p> +</dd> +<dt>‘<samp>main</samp>’</dt> +<dd><p>Selects all functions named ‘<samp>main</samp>’. +</p> +<p>Note that there may be multiple instances of the same function name +because some of the definitions may be local (i.e., static). Unless a +function name is unique in a program, you must use the colon notation +explained below to specify a function from a specific source file. +</p> +<p>Sometimes, function names contain dots. In such cases, it is necessary +to add a leading colon to the name. For example, ‘<samp>:.mul</samp>’ selects +function ‘<samp>.mul</samp>’. +</p> +<p>In some object file formats, symbols have a leading underscore. +<code>gprof</code> will normally not print these underscores. When you name a +symbol in a symspec, you should type it exactly as <code>gprof</code> prints +it in its output. For example, if the compiler produces a symbol +‘<samp>_main</samp>’ from your <code>main</code> function, <code>gprof</code> still prints +it as ‘<samp>main</samp>’ in its output, so you should use ‘<samp>main</samp>’ in +symspecs. +</p> +</dd> +<dt>‘<samp>main.c:main</samp>’</dt> +<dd><p>Selects function ‘<samp>main</samp>’ in file <samp>main.c</samp>. +</p> +</dd> +<dt>‘<samp>main.c:134</samp>’</dt> +<dd><p>Selects line 134 in file <samp>main.c</samp>. +</p></dd> +</dl> + +<hr> +<a name="Output"></a> +<div class="header"> +<p> +Next: <a href="#Inaccuracy" accesskey="n" rel="next">Inaccuracy</a>, Previous: <a href="#Invoking" accesskey="p" rel="previous">Invoking</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Interpreting-gprof_0027s-Output"></a> +<h2 class="chapter">5 Interpreting <code>gprof</code>’s Output</h2> + +<p><code>gprof</code> can produce several different output styles, the +most important of which are described below. The simplest output +styles (file information, execution count, and function and file ordering) +are not described here, but are documented with the respective options +that trigger them. +See <a href="#Output-Options">Output Options</a>. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Flat-Profile" accesskey="1">Flat Profile</a>:</td><td> </td><td align="left" valign="top">The flat profile shows how much time was spent + executing directly in each function. +</td></tr> +<tr><td align="left" valign="top">• <a href="#Call-Graph" accesskey="2">Call Graph</a>:</td><td> </td><td align="left" valign="top">The call graph shows which functions called which + others, and how much time each function used + when its subroutine calls are included. +</td></tr> +<tr><td align="left" valign="top">• <a href="#Line_002dby_002dline" accesskey="3">Line-by-line</a>:</td><td> </td><td align="left" valign="top"><code>gprof</code> can analyze individual source code lines +</td></tr> +<tr><td align="left" valign="top">• <a href="#Annotated-Source" accesskey="4">Annotated Source</a>:</td><td> </td><td align="left" valign="top">The annotated source listing displays source code + labeled with execution counts +</td></tr> +</table> + + +<hr> +<a name="Flat-Profile"></a> +<div class="header"> +<p> +Next: <a href="#Call-Graph" accesskey="n" rel="next">Call Graph</a>, Up: <a href="#Output" accesskey="u" rel="up">Output</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="The-Flat-Profile"></a> +<h3 class="section">5.1 The Flat Profile</h3> +<a name="index-flat-profile"></a> + +<p>The <em>flat profile</em> shows the total amount of time your program +spent executing each function. Unless the ‘<samp>-z</samp>’ option is given, +functions with no apparent time spent in them, and no apparent calls +to them, are not mentioned. Note that if a function was not compiled +for profiling, and didn’t run long enough to show up on the program +counter histogram, it will be indistinguishable from a function that +was never called. +</p> +<p>This is part of a flat profile for a small program: +</p> +<div class="smallexample"> +<pre class="smallexample">Flat profile: + +Each sample counts as 0.01 seconds. + % cumulative self self total + time seconds seconds calls ms/call ms/call name + 33.34 0.02 0.02 7208 0.00 0.00 open + 16.67 0.03 0.01 244 0.04 0.12 offtime + 16.67 0.04 0.01 8 1.25 1.25 memccpy + 16.67 0.05 0.01 7 1.43 1.43 write + 16.67 0.06 0.01 mcount + 0.00 0.06 0.00 236 0.00 0.00 tzset + 0.00 0.06 0.00 192 0.00 0.00 tolower + 0.00 0.06 0.00 47 0.00 0.00 strlen + 0.00 0.06 0.00 45 0.00 0.00 strchr + 0.00 0.06 0.00 1 0.00 50.00 main + 0.00 0.06 0.00 1 0.00 0.00 memcpy + 0.00 0.06 0.00 1 0.00 10.11 print + 0.00 0.06 0.00 1 0.00 0.00 profil + 0.00 0.06 0.00 1 0.00 50.00 report +… +</pre></div> + +<p>The functions are sorted first by decreasing run-time spent in them, +then by decreasing number of calls, then alphabetically by name. The +functions ‘<samp>mcount</samp>’ and ‘<samp>profil</samp>’ are part of the profiling +apparatus and appear in every flat profile; their time gives a measure of +the amount of overhead due to profiling. +</p> +<p>Just before the column headers, a statement appears indicating +how much time each sample counted as. +This <em>sampling period</em> estimates the margin of error in each of the time +figures. A time figure that is not much larger than this is not +reliable. In this example, each sample counted as 0.01 seconds, +suggesting a 100 Hz sampling rate. +The program’s total execution time was 0.06 +seconds, as indicated by the ‘<samp>cumulative seconds</samp>’ field. Since +each sample counted for 0.01 seconds, this means only six samples +were taken during the run. Two of the samples occurred while the +program was in the ‘<samp>open</samp>’ function, as indicated by the +‘<samp>self seconds</samp>’ field. Each of the other four samples +occurred one each in ‘<samp>offtime</samp>’, ‘<samp>memccpy</samp>’, ‘<samp>write</samp>’, +and ‘<samp>mcount</samp>’. +Since only six samples were taken, none of these values can +be regarded as particularly reliable. +In another run, +the ‘<samp>self seconds</samp>’ field for +‘<samp>mcount</samp>’ might well be ‘<samp>0.00</samp>’ or ‘<samp>0.02</samp>’. +See <a href="#Sampling-Error">Statistical Sampling Error</a>, +for a complete discussion. +</p> +<p>The remaining functions in the listing (those whose +‘<samp>self seconds</samp>’ field is ‘<samp>0.00</samp>’) didn’t appear +in the histogram samples at all. However, the call graph +indicated that they were called, so therefore they are listed, +sorted in decreasing order by the ‘<samp>calls</samp>’ field. +Clearly some time was spent executing these functions, +but the paucity of histogram samples prevents any +determination of how much time each took. +</p> +<p>Here is what the fields in each line mean: +</p> +<dl compact="compact"> +<dt><code>% time</code></dt> +<dd><p>This is the percentage of the total execution time your program spent +in this function. These should all add up to 100%. +</p> +</dd> +<dt><code>cumulative seconds</code></dt> +<dd><p>This is the cumulative total number of seconds the computer spent +executing this functions, plus the time spent in all the functions +above this one in this table. +</p> +</dd> +<dt><code>self seconds</code></dt> +<dd><p>This is the number of seconds accounted for by this function alone. +The flat profile listing is sorted first by this number. +</p> +</dd> +<dt><code>calls</code></dt> +<dd><p>This is the total number of times the function was called. If the +function was never called, or the number of times it was called cannot +be determined (probably because the function was not compiled with +profiling enabled), the <em>calls</em> field is blank. +</p> +</dd> +<dt><code>self ms/call</code></dt> +<dd><p>This represents the average number of milliseconds spent in this +function per call, if this function is profiled. Otherwise, this field +is blank for this function. +</p> +</dd> +<dt><code>total ms/call</code></dt> +<dd><p>This represents the average number of milliseconds spent in this +function and its descendants per call, if this function is profiled. +Otherwise, this field is blank for this function. +This is the only field in the flat profile that uses call graph analysis. +</p> +</dd> +<dt><code>name</code></dt> +<dd><p>This is the name of the function. The flat profile is sorted by this +field alphabetically after the <em>self seconds</em> and <em>calls</em> +fields are sorted. +</p></dd> +</dl> + +<hr> +<a name="Call-Graph"></a> +<div class="header"> +<p> +Next: <a href="#Line_002dby_002dline" accesskey="n" rel="next">Line-by-line</a>, Previous: <a href="#Flat-Profile" accesskey="p" rel="previous">Flat Profile</a>, Up: <a href="#Output" accesskey="u" rel="up">Output</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="The-Call-Graph"></a> +<h3 class="section">5.2 The Call Graph</h3> +<a name="index-call-graph"></a> + +<p>The <em>call graph</em> shows how much time was spent in each function +and its children. From this information, you can find functions that, +while they themselves may not have used much time, called other +functions that did use unusual amounts of time. +</p> +<p>Here is a sample call from a small program. This call came from the +same <code>gprof</code> run as the flat profile example in the previous +section. +</p> +<div class="smallexample"> +<pre class="smallexample">granularity: each sample hit covers 2 byte(s) for 20.00% of 0.05 seconds + +index % time self children called name + <spontaneous> +[1] 100.0 0.00 0.05 start [1] + 0.00 0.05 1/1 main [2] + 0.00 0.00 1/2 on_exit [28] + 0.00 0.00 1/1 exit [59] +----------------------------------------------- + 0.00 0.05 1/1 start [1] +[2] 100.0 0.00 0.05 1 main [2] + 0.00 0.05 1/1 report [3] +----------------------------------------------- + 0.00 0.05 1/1 main [2] +[3] 100.0 0.00 0.05 1 report [3] + 0.00 0.03 8/8 timelocal [6] + 0.00 0.01 1/1 print [9] + 0.00 0.01 9/9 fgets [12] + 0.00 0.00 12/34 strncmp <cycle 1> [40] + 0.00 0.00 8/8 lookup [20] + 0.00 0.00 1/1 fopen [21] + 0.00 0.00 8/8 chewtime [24] + 0.00 0.00 8/16 skipspace [44] +----------------------------------------------- +[4] 59.8 0.01 0.02 8+472 <cycle 2 as a whole> [4] + 0.01 0.02 244+260 offtime <cycle 2> [7] + 0.00 0.00 236+1 tzset <cycle 2> [26] +----------------------------------------------- +</pre></div> + +<p>The lines full of dashes divide this table into <em>entries</em>, one for each +function. Each entry has one or more lines. +</p> +<p>In each entry, the primary line is the one that starts with an index number +in square brackets. The end of this line says which function the entry is +for. The preceding lines in the entry describe the callers of this +function and the following lines describe its subroutines (also called +<em>children</em> when we speak of the call graph). +</p> +<p>The entries are sorted by time spent in the function and its subroutines. +</p> +<p>The internal profiling function <code>mcount</code> (see <a href="#Flat-Profile">The +Flat Profile</a>) is never mentioned in the call graph. +</p> +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Primary" accesskey="1">Primary</a>:</td><td> </td><td align="left" valign="top">Details of the primary line’s contents. +</td></tr> +<tr><td align="left" valign="top">• <a href="#Callers" accesskey="2">Callers</a>:</td><td> </td><td align="left" valign="top">Details of caller-lines’ contents. +</td></tr> +<tr><td align="left" valign="top">• <a href="#Subroutines" accesskey="3">Subroutines</a>:</td><td> </td><td align="left" valign="top">Details of subroutine-lines’ contents. +</td></tr> +<tr><td align="left" valign="top">• <a href="#Cycles" accesskey="4">Cycles</a>:</td><td> </td><td align="left" valign="top">When there are cycles of recursion, + such as <code>a</code> calls <code>b</code> calls <code>a</code>… +</td></tr> +</table> + +<hr> +<a name="Primary"></a> +<div class="header"> +<p> +Next: <a href="#Callers" accesskey="n" rel="next">Callers</a>, Up: <a href="#Call-Graph" accesskey="u" rel="up">Call Graph</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="The-Primary-Line"></a> +<h4 class="subsection">5.2.1 The Primary Line</h4> + +<p>The <em>primary line</em> in a call graph entry is the line that +describes the function which the entry is about and gives the overall +statistics for this function. +</p> +<p>For reference, we repeat the primary line from the entry for function +<code>report</code> in our main example, together with the heading line that +shows the names of the fields: +</p> +<div class="smallexample"> +<pre class="smallexample">index % time self children called name +… +[3] 100.0 0.00 0.05 1 report [3] +</pre></div> + +<p>Here is what the fields in the primary line mean: +</p> +<dl compact="compact"> +<dt><code>index</code></dt> +<dd><p>Entries are numbered with consecutive integers. Each function +therefore has an index number, which appears at the beginning of its +primary line. +</p> +<p>Each cross-reference to a function, as a caller or subroutine of +another, gives its index number as well as its name. The index number +guides you if you wish to look for the entry for that function. +</p> +</dd> +<dt><code>% time</code></dt> +<dd><p>This is the percentage of the total time that was spent in this +function, including time spent in subroutines called from this +function. +</p> +<p>The time spent in this function is counted again for the callers of +this function. Therefore, adding up these percentages is meaningless. +</p> +</dd> +<dt><code>self</code></dt> +<dd><p>This is the total amount of time spent in this function. This +should be identical to the number printed in the <code>seconds</code> field +for this function in the flat profile. +</p> +</dd> +<dt><code>children</code></dt> +<dd><p>This is the total amount of time spent in the subroutine calls made by +this function. This should be equal to the sum of all the <code>self</code> +and <code>children</code> entries of the children listed directly below this +function. +</p> +</dd> +<dt><code>called</code></dt> +<dd><p>This is the number of times the function was called. +</p> +<p>If the function called itself recursively, there are two numbers, +separated by a ‘<samp>+</samp>’. The first number counts non-recursive calls, +and the second counts recursive calls. +</p> +<p>In the example above, the function <code>report</code> was called once from +<code>main</code>. +</p> +</dd> +<dt><code>name</code></dt> +<dd><p>This is the name of the current function. The index number is +repeated after it. +</p> +<p>If the function is part of a cycle of recursion, the cycle number is +printed between the function’s name and the index number +(see <a href="#Cycles">How Mutually Recursive Functions Are Described</a>). +For example, if function <code>gnurr</code> is part of +cycle number one, and has index number twelve, its primary line would +be end like this: +</p> +<div class="example"> +<pre class="example">gnurr <cycle 1> [12] +</pre></div> +</dd> +</dl> + +<hr> +<a name="Callers"></a> +<div class="header"> +<p> +Next: <a href="#Subroutines" accesskey="n" rel="next">Subroutines</a>, Previous: <a href="#Primary" accesskey="p" rel="previous">Primary</a>, Up: <a href="#Call-Graph" accesskey="u" rel="up">Call Graph</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Lines-for-a-Function_0027s-Callers"></a> +<h4 class="subsection">5.2.2 Lines for a Function’s Callers</h4> + +<p>A function’s entry has a line for each function it was called by. +These lines’ fields correspond to the fields of the primary line, but +their meanings are different because of the difference in context. +</p> +<p>For reference, we repeat two lines from the entry for the function +<code>report</code>, the primary line and one caller-line preceding it, together +with the heading line that shows the names of the fields: +</p> +<div class="smallexample"> +<pre class="smallexample">index % time self children called name +… + 0.00 0.05 1/1 main [2] +[3] 100.0 0.00 0.05 1 report [3] +</pre></div> + +<p>Here are the meanings of the fields in the caller-line for <code>report</code> +called from <code>main</code>: +</p> +<dl compact="compact"> +<dt><code>self</code></dt> +<dd><p>An estimate of the amount of time spent in <code>report</code> itself when it was +called from <code>main</code>. +</p> +</dd> +<dt><code>children</code></dt> +<dd><p>An estimate of the amount of time spent in subroutines of <code>report</code> +when <code>report</code> was called from <code>main</code>. +</p> +<p>The sum of the <code>self</code> and <code>children</code> fields is an estimate +of the amount of time spent within calls to <code>report</code> from <code>main</code>. +</p> +</dd> +<dt><code>called</code></dt> +<dd><p>Two numbers: the number of times <code>report</code> was called from <code>main</code>, +followed by the total number of non-recursive calls to <code>report</code> from +all its callers. +</p> +</dd> +<dt><code>name and index number</code></dt> +<dd><p>The name of the caller of <code>report</code> to which this line applies, +followed by the caller’s index number. +</p> +<p>Not all functions have entries in the call graph; some +options to <code>gprof</code> request the omission of certain functions. +When a caller has no entry of its own, it still has caller-lines +in the entries of the functions it calls. +</p> +<p>If the caller is part of a recursion cycle, the cycle number is +printed between the name and the index number. +</p></dd> +</dl> + +<p>If the identity of the callers of a function cannot be determined, a +dummy caller-line is printed which has ‘<samp><spontaneous></samp>’ as the +“caller’s name” and all other fields blank. This can happen for +signal handlers. +</p> +<hr> +<a name="Subroutines"></a> +<div class="header"> +<p> +Next: <a href="#Cycles" accesskey="n" rel="next">Cycles</a>, Previous: <a href="#Callers" accesskey="p" rel="previous">Callers</a>, Up: <a href="#Call-Graph" accesskey="u" rel="up">Call Graph</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Lines-for-a-Function_0027s-Subroutines"></a> +<h4 class="subsection">5.2.3 Lines for a Function’s Subroutines</h4> + +<p>A function’s entry has a line for each of its subroutines—in other +words, a line for each other function that it called. These lines’ +fields correspond to the fields of the primary line, but their meanings +are different because of the difference in context. +</p> +<p>For reference, we repeat two lines from the entry for the function +<code>main</code>, the primary line and a line for a subroutine, together +with the heading line that shows the names of the fields: +</p> +<div class="smallexample"> +<pre class="smallexample">index % time self children called name +… +[2] 100.0 0.00 0.05 1 main [2] + 0.00 0.05 1/1 report [3] +</pre></div> + +<p>Here are the meanings of the fields in the subroutine-line for <code>main</code> +calling <code>report</code>: +</p> +<dl compact="compact"> +<dt><code>self</code></dt> +<dd><p>An estimate of the amount of time spent directly within <code>report</code> +when <code>report</code> was called from <code>main</code>. +</p> +</dd> +<dt><code>children</code></dt> +<dd><p>An estimate of the amount of time spent in subroutines of <code>report</code> +when <code>report</code> was called from <code>main</code>. +</p> +<p>The sum of the <code>self</code> and <code>children</code> fields is an estimate +of the total time spent in calls to <code>report</code> from <code>main</code>. +</p> +</dd> +<dt><code>called</code></dt> +<dd><p>Two numbers, the number of calls to <code>report</code> from <code>main</code> +followed by the total number of non-recursive calls to <code>report</code>. +This ratio is used to determine how much of <code>report</code>’s <code>self</code> +and <code>children</code> time gets credited to <code>main</code>. +See <a href="#Assumptions">Estimating <code>children</code> Times</a>. +</p> +</dd> +<dt><code>name</code></dt> +<dd><p>The name of the subroutine of <code>main</code> to which this line applies, +followed by the subroutine’s index number. +</p> +<p>If the caller is part of a recursion cycle, the cycle number is +printed between the name and the index number. +</p></dd> +</dl> + +<hr> +<a name="Cycles"></a> +<div class="header"> +<p> +Previous: <a href="#Subroutines" accesskey="p" rel="previous">Subroutines</a>, Up: <a href="#Call-Graph" accesskey="u" rel="up">Call Graph</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="How-Mutually-Recursive-Functions-Are-Described"></a> +<h4 class="subsection">5.2.4 How Mutually Recursive Functions Are Described</h4> +<a name="index-cycle"></a> +<a name="index-recursion-cycle"></a> + +<p>The graph may be complicated by the presence of <em>cycles of +recursion</em> in the call graph. A cycle exists if a function calls +another function that (directly or indirectly) calls (or appears to +call) the original function. For example: if <code>a</code> calls <code>b</code>, +and <code>b</code> calls <code>a</code>, then <code>a</code> and <code>b</code> form a cycle. +</p> +<p>Whenever there are call paths both ways between a pair of functions, they +belong to the same cycle. If <code>a</code> and <code>b</code> call each other and +<code>b</code> and <code>c</code> call each other, all three make one cycle. Note that +even if <code>b</code> only calls <code>a</code> if it was not called from <code>a</code>, +<code>gprof</code> cannot determine this, so <code>a</code> and <code>b</code> are still +considered a cycle. +</p> +<p>The cycles are numbered with consecutive integers. When a function +belongs to a cycle, each time the function name appears in the call graph +it is followed by ‘<samp><cycle <var>number</var>></samp>’. +</p> +<p>The reason cycles matter is that they make the time values in the call +graph paradoxical. The “time spent in children” of <code>a</code> should +include the time spent in its subroutine <code>b</code> and in <code>b</code>’s +subroutines—but one of <code>b</code>’s subroutines is <code>a</code>! How much of +<code>a</code>’s time should be included in the children of <code>a</code>, when +<code>a</code> is indirectly recursive? +</p> +<p>The way <code>gprof</code> resolves this paradox is by creating a single entry +for the cycle as a whole. The primary line of this entry describes the +total time spent directly in the functions of the cycle. The +“subroutines” of the cycle are the individual functions of the cycle, and +all other functions that were called directly by them. The “callers” of +the cycle are the functions, outside the cycle, that called functions in +the cycle. +</p> +<p>Here is an example portion of a call graph which shows a cycle containing +functions <code>a</code> and <code>b</code>. The cycle was entered by a call to +<code>a</code> from <code>main</code>; both <code>a</code> and <code>b</code> called <code>c</code>. +</p> +<div class="smallexample"> +<pre class="smallexample">index % time self children called name +---------------------------------------- + 1.77 0 1/1 main [2] +[3] 91.71 1.77 0 1+5 <cycle 1 as a whole> [3] + 1.02 0 3 b <cycle 1> [4] + 0.75 0 2 a <cycle 1> [5] +---------------------------------------- + 3 a <cycle 1> [5] +[4] 52.85 1.02 0 0 b <cycle 1> [4] + 2 a <cycle 1> [5] + 0 0 3/6 c [6] +---------------------------------------- + 1.77 0 1/1 main [2] + 2 b <cycle 1> [4] +[5] 38.86 0.75 0 1 a <cycle 1> [5] + 3 b <cycle 1> [4] + 0 0 3/6 c [6] +---------------------------------------- +</pre></div> + +<p>(The entire call graph for this program contains in addition an entry for +<code>main</code>, which calls <code>a</code>, and an entry for <code>c</code>, with callers +<code>a</code> and <code>b</code>.) +</p> +<div class="smallexample"> +<pre class="smallexample">index % time self children called name + <spontaneous> +[1] 100.00 0 1.93 0 start [1] + 0.16 1.77 1/1 main [2] +---------------------------------------- + 0.16 1.77 1/1 start [1] +[2] 100.00 0.16 1.77 1 main [2] + 1.77 0 1/1 a <cycle 1> [5] +---------------------------------------- + 1.77 0 1/1 main [2] +[3] 91.71 1.77 0 1+5 <cycle 1 as a whole> [3] + 1.02 0 3 b <cycle 1> [4] + 0.75 0 2 a <cycle 1> [5] + 0 0 6/6 c [6] +---------------------------------------- + 3 a <cycle 1> [5] +[4] 52.85 1.02 0 0 b <cycle 1> [4] + 2 a <cycle 1> [5] + 0 0 3/6 c [6] +---------------------------------------- + 1.77 0 1/1 main [2] + 2 b <cycle 1> [4] +[5] 38.86 0.75 0 1 a <cycle 1> [5] + 3 b <cycle 1> [4] + 0 0 3/6 c [6] +---------------------------------------- + 0 0 3/6 b <cycle 1> [4] + 0 0 3/6 a <cycle 1> [5] +[6] 0.00 0 0 6 c [6] +---------------------------------------- +</pre></div> + +<p>The <code>self</code> field of the cycle’s primary line is the total time +spent in all the functions of the cycle. It equals the sum of the +<code>self</code> fields for the individual functions in the cycle, found +in the entry in the subroutine lines for these functions. +</p> +<p>The <code>children</code> fields of the cycle’s primary line and subroutine lines +count only subroutines outside the cycle. Even though <code>a</code> calls +<code>b</code>, the time spent in those calls to <code>b</code> is not counted in +<code>a</code>’s <code>children</code> time. Thus, we do not encounter the problem of +what to do when the time in those calls to <code>b</code> includes indirect +recursive calls back to <code>a</code>. +</p> +<p>The <code>children</code> field of a caller-line in the cycle’s entry estimates +the amount of time spent <em>in the whole cycle</em>, and its other +subroutines, on the times when that caller called a function in the cycle. +</p> +<p>The <code>called</code> field in the primary line for the cycle has two numbers: +first, the number of times functions in the cycle were called by functions +outside the cycle; second, the number of times they were called by +functions in the cycle (including times when a function in the cycle calls +itself). This is a generalization of the usual split into non-recursive and +recursive calls. +</p> +<p>The <code>called</code> field of a subroutine-line for a cycle member in the +cycle’s entry says how many time that function was called from functions in +the cycle. The total of all these is the second number in the primary line’s +<code>called</code> field. +</p> +<p>In the individual entry for a function in a cycle, the other functions in +the same cycle can appear as subroutines and as callers. These lines show +how many times each function in the cycle called or was called from each other +function in the cycle. The <code>self</code> and <code>children</code> fields in these +lines are blank because of the difficulty of defining meanings for them +when recursion is going on. +</p> +<hr> +<a name="Line_002dby_002dline"></a> +<div class="header"> +<p> +Next: <a href="#Annotated-Source" accesskey="n" rel="next">Annotated Source</a>, Previous: <a href="#Call-Graph" accesskey="p" rel="previous">Call Graph</a>, Up: <a href="#Output" accesskey="u" rel="up">Output</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Line_002dby_002dline-Profiling"></a> +<h3 class="section">5.3 Line-by-line Profiling</h3> + +<p><code>gprof</code>’s ‘<samp>-l</samp>’ option causes the program to perform +<em>line-by-line</em> profiling. In this mode, histogram +samples are assigned not to functions, but to individual +lines of source code. This only works with programs compiled with +older versions of the <code>gcc</code> compiler. Newer versions of <code>gcc</code> +use a different program - <code>gcov</code> - to display line-by-line +profiling information. +</p> +<p>With the older versions of <code>gcc</code> the program usually has to be +compiled with a ‘<samp>-g</samp>’ option, in addition to ‘<samp>-pg</samp>’, in order +to generate debugging symbols for tracking source code lines. +Note, in much older versions of <code>gcc</code> the program had to be +compiled with the ‘<samp>-a</samp>’ command-line option as well. +</p> +<p>The flat profile is the most useful output table +in line-by-line mode. +The call graph isn’t as useful as normal, since +the current version of <code>gprof</code> does not propagate +call graph arcs from source code lines to the enclosing function. +The call graph does, however, show each line of code +that called each function, along with a count. +</p> +<p>Here is a section of <code>gprof</code>’s output, without line-by-line profiling. +Note that <code>ct_init</code> accounted for four histogram hits, and +13327 calls to <code>init_block</code>. +</p> +<div class="smallexample"> +<pre class="smallexample">Flat profile: + +Each sample counts as 0.01 seconds. + % cumulative self self total + time seconds seconds calls us/call us/call name + 30.77 0.13 0.04 6335 6.31 6.31 ct_init + + + Call graph (explanation follows) + + +granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds + +index % time self children called name + + 0.00 0.00 1/13496 name_too_long + 0.00 0.00 40/13496 deflate + 0.00 0.00 128/13496 deflate_fast + 0.00 0.00 13327/13496 ct_init +[7] 0.0 0.00 0.00 13496 init_block + +</pre></div> + +<p>Now let’s look at some of <code>gprof</code>’s output from the same program run, +this time with line-by-line profiling enabled. Note that <code>ct_init</code>’s +four histogram hits are broken down into four lines of source code—one hit +occurred on each of lines 349, 351, 382 and 385. In the call graph, +note how +<code>ct_init</code>’s 13327 calls to <code>init_block</code> are broken down +into one call from line 396, 3071 calls from line 384, 3730 calls +from line 385, and 6525 calls from 387. +</p> +<div class="smallexample"> +<pre class="smallexample">Flat profile: + +Each sample counts as 0.01 seconds. + % cumulative self + time seconds seconds calls name + 7.69 0.10 0.01 ct_init (trees.c:349) + 7.69 0.11 0.01 ct_init (trees.c:351) + 7.69 0.12 0.01 ct_init (trees.c:382) + 7.69 0.13 0.01 ct_init (trees.c:385) + + + Call graph (explanation follows) + + +granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds + + % time self children called name + + 0.00 0.00 1/13496 name_too_long (gzip.c:1440) + 0.00 0.00 1/13496 deflate (deflate.c:763) + 0.00 0.00 1/13496 ct_init (trees.c:396) + 0.00 0.00 2/13496 deflate (deflate.c:727) + 0.00 0.00 4/13496 deflate (deflate.c:686) + 0.00 0.00 5/13496 deflate (deflate.c:675) + 0.00 0.00 12/13496 deflate (deflate.c:679) + 0.00 0.00 16/13496 deflate (deflate.c:730) + 0.00 0.00 128/13496 deflate_fast (deflate.c:654) + 0.00 0.00 3071/13496 ct_init (trees.c:384) + 0.00 0.00 3730/13496 ct_init (trees.c:385) + 0.00 0.00 6525/13496 ct_init (trees.c:387) +[6] 0.0 0.00 0.00 13496 init_block (trees.c:408) + +</pre></div> + + +<hr> +<a name="Annotated-Source"></a> +<div class="header"> +<p> +Previous: <a href="#Line_002dby_002dline" accesskey="p" rel="previous">Line-by-line</a>, Up: <a href="#Output" accesskey="u" rel="up">Output</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="The-Annotated-Source-Listing"></a> +<h3 class="section">5.4 The Annotated Source Listing</h3> + +<p><code>gprof</code>’s ‘<samp>-A</samp>’ option triggers an annotated source listing, +which lists the program’s source code, each function labeled with the +number of times it was called. You may also need to specify the +‘<samp>-I</samp>’ option, if <code>gprof</code> can’t find the source code files. +</p> +<p>With older versions of <code>gcc</code> compiling with ‘<samp>gcc … -g +-pg -a</samp>’ augments your program with basic-block counting code, in +addition to function counting code. This enables <code>gprof</code> to +determine how many times each line of code was executed. With newer +versions of <code>gcc</code> support for displaying basic-block counts is +provided by the <code>gcov</code> program. +</p> +<p>For example, consider the following function, taken from gzip, +with line numbers added: +</p> +<div class="smallexample"> +<pre class="smallexample"> 1 ulg updcrc(s, n) + 2 uch *s; + 3 unsigned n; + 4 { + 5 register ulg c; + 6 + 7 static ulg crc = (ulg)0xffffffffL; + 8 + 9 if (s == NULL) { +10 c = 0xffffffffL; +11 } else { +12 c = crc; +13 if (n) do { +14 c = crc_32_tab[...]; +15 } while (--n); +16 } +17 crc = c; +18 return c ^ 0xffffffffL; +19 } + +</pre></div> + +<p><code>updcrc</code> has at least five basic-blocks. +One is the function itself. The +<code>if</code> statement on line 9 generates two more basic-blocks, one +for each branch of the <code>if</code>. A fourth basic-block results from +the <code>if</code> on line 13, and the contents of the <code>do</code> loop form +the fifth basic-block. The compiler may also generate additional +basic-blocks to handle various special cases. +</p> +<p>A program augmented for basic-block counting can be analyzed with +‘<samp>gprof -l -A</samp>’. +The ‘<samp>-x</samp>’ option is also helpful, +to ensure that each line of code is labeled at least once. +Here is <code>updcrc</code>’s +annotated source listing for a sample <code>gzip</code> run: +</p> +<div class="smallexample"> +<pre class="smallexample"> ulg updcrc(s, n) + uch *s; + unsigned n; + 2 ->{ + register ulg c; + + static ulg crc = (ulg)0xffffffffL; + + 2 -> if (s == NULL) { + 1 -> c = 0xffffffffL; + 1 -> } else { + 1 -> c = crc; + 1 -> if (n) do { + 26312 -> c = crc_32_tab[...]; +26312,1,26311 -> } while (--n); + } + 2 -> crc = c; + 2 -> return c ^ 0xffffffffL; + 2 ->} +</pre></div> + +<p>In this example, the function was called twice, passing once through +each branch of the <code>if</code> statement. The body of the <code>do</code> +loop was executed a total of 26312 times. Note how the <code>while</code> +statement is annotated. It began execution 26312 times, once for +each iteration through the loop. One of those times (the last time) +it exited, while it branched back to the beginning of the loop 26311 times. +</p> +<hr> +<a name="Inaccuracy"></a> +<div class="header"> +<p> +Next: <a href="#How-do-I_003f" accesskey="n" rel="next">How do I?</a>, Previous: <a href="#Output" accesskey="p" rel="previous">Output</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Inaccuracy-of-gprof-Output"></a> +<h2 class="chapter">6 Inaccuracy of <code>gprof</code> Output</h2> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Sampling-Error" accesskey="1">Sampling Error</a>:</td><td> </td><td align="left" valign="top">Statistical margins of error +</td></tr> +<tr><td align="left" valign="top">• <a href="#Assumptions" accesskey="2">Assumptions</a>:</td><td> </td><td align="left" valign="top">Estimating children times +</td></tr> +</table> + +<hr> +<a name="Sampling-Error"></a> +<div class="header"> +<p> +Next: <a href="#Assumptions" accesskey="n" rel="next">Assumptions</a>, Up: <a href="#Inaccuracy" accesskey="u" rel="up">Inaccuracy</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Statistical-Sampling-Error"></a> +<h3 class="section">6.1 Statistical Sampling Error</h3> + +<p>The run-time figures that <code>gprof</code> gives you are based on a sampling +process, so they are subject to statistical inaccuracy. If a function runs +only a small amount of time, so that on the average the sampling process +ought to catch that function in the act only once, there is a pretty good +chance it will actually find that function zero times, or twice. +</p> +<p>By contrast, the number-of-calls and basic-block figures are derived +by counting, not sampling. They are completely accurate and will not +vary from run to run if your program is deterministic and single +threaded. In multi-threaded applications, or single threaded +applications that link with multi-threaded libraries, the counts are +only deterministic if the counting function is thread-safe. (Note: +beware that the mcount counting function in glibc is <em>not</em> +thread-safe). See <a href="#Implementation">Implementation of Profiling</a>. +</p> +<p>The <em>sampling period</em> that is printed at the beginning of the flat +profile says how often samples are taken. The rule of thumb is that a +run-time figure is accurate if it is considerably bigger than the sampling +period. +</p> +<p>The actual amount of error can be predicted. +For <var>n</var> samples, the <em>expected</em> error +is the square-root of <var>n</var>. For example, +if the sampling period is 0.01 seconds and <code>foo</code>’s run-time is 1 second, +<var>n</var> is 100 samples (1 second/0.01 seconds), sqrt(<var>n</var>) is 10 samples, so +the expected error in <code>foo</code>’s run-time is 0.1 seconds (10*0.01 seconds), +or ten percent of the observed value. +Again, if the sampling period is 0.01 seconds and <code>bar</code>’s run-time is +100 seconds, <var>n</var> is 10000 samples, sqrt(<var>n</var>) is 100 samples, so +the expected error in <code>bar</code>’s run-time is 1 second, +or one percent of the observed value. +It is likely to +vary this much <em>on the average</em> from one profiling run to the next. +(<em>Sometimes</em> it will vary more.) +</p> +<p>This does not mean that a small run-time figure is devoid of information. +If the program’s <em>total</em> run-time is large, a small run-time for one +function does tell you that that function used an insignificant fraction of +the whole program’s time. Usually this means it is not worth optimizing. +</p> +<p>One way to get more accuracy is to give your program more (but similar) +input data so it will take longer. Another way is to combine the data from +several runs, using the ‘<samp>-s</samp>’ option of <code>gprof</code>. Here is how: +</p> +<ol> +<li> Run your program once. + +</li><li> Issue the command ‘<samp>mv gmon.out gmon.sum</samp>’. + +</li><li> Run your program again, the same as before. + +</li><li> Merge the new data in <samp>gmon.out</samp> into <samp>gmon.sum</samp> with this command: + +<div class="example"> +<pre class="example">gprof -s <var>executable-file</var> gmon.out gmon.sum +</pre></div> + +</li><li> Repeat the last two steps as often as you wish. + +</li><li> Analyze the cumulative data using this command: + +<div class="example"> +<pre class="example">gprof <var>executable-file</var> gmon.sum > <var>output-file</var> +</pre></div> +</li></ol> + +<hr> +<a name="Assumptions"></a> +<div class="header"> +<p> +Previous: <a href="#Sampling-Error" accesskey="p" rel="previous">Sampling Error</a>, Up: <a href="#Inaccuracy" accesskey="u" rel="up">Inaccuracy</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Estimating-children-Times"></a> +<h3 class="section">6.2 Estimating <code>children</code> Times</h3> + +<p>Some of the figures in the call graph are estimates—for example, the +<code>children</code> time values and all the time figures in caller and +subroutine lines. +</p> +<p>There is no direct information about these measurements in the profile +data itself. Instead, <code>gprof</code> estimates them by making an assumption +about your program that might or might not be true. +</p> +<p>The assumption made is that the average time spent in each call to any +function <code>foo</code> is not correlated with who called <code>foo</code>. If +<code>foo</code> used 5 seconds in all, and 2/5 of the calls to <code>foo</code> came +from <code>a</code>, then <code>foo</code> contributes 2 seconds to <code>a</code>’s +<code>children</code> time, by assumption. +</p> +<p>This assumption is usually true enough, but for some programs it is far +from true. Suppose that <code>foo</code> returns very quickly when its argument +is zero; suppose that <code>a</code> always passes zero as an argument, while +other callers of <code>foo</code> pass other arguments. In this program, all the +time spent in <code>foo</code> is in the calls from callers other than <code>a</code>. +But <code>gprof</code> has no way of knowing this; it will blindly and +incorrectly charge 2 seconds of time in <code>foo</code> to the children of +<code>a</code>. +</p> +<p>We hope some day to put more complete data into <samp>gmon.out</samp>, so that +this assumption is no longer needed, if we can figure out how. For the +novice, the estimated figures are usually more useful than misleading. +</p> +<hr> +<a name="How-do-I_003f"></a> +<div class="header"> +<p> +Next: <a href="#Incompatibilities" accesskey="n" rel="next">Incompatibilities</a>, Previous: <a href="#Inaccuracy" accesskey="p" rel="previous">Inaccuracy</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Answers-to-Common-Questions"></a> +<h2 class="chapter">7 Answers to Common Questions</h2> + +<dl compact="compact"> +<dt>How can I get more exact information about hot spots in my program?</dt> +<dd> +<p>Looking at the per-line call counts only tells part of the story. +Because <code>gprof</code> can only report call times and counts by function, +the best way to get finer-grained information on where the program +is spending its time is to re-factor large functions into sequences +of calls to smaller ones. Beware however that this can introduce +artificial hot spots since compiling with ‘<samp>-pg</samp>’ adds a significant +overhead to function calls. An alternative solution is to use a +non-intrusive profiler, e.g. oprofile. +</p> +</dd> +<dt>How do I find which lines in my program were executed the most times?</dt> +<dd> +<p>Use the <code>gcov</code> program. +</p> +</dd> +<dt>How do I find which lines in my program called a particular function?</dt> +<dd> +<p>Use ‘<samp>gprof -l</samp>’ and lookup the function in the call graph. +The callers will be broken down by function and line number. +</p> +</dd> +<dt>How do I analyze a program that runs for less than a second?</dt> +<dd> +<p>Try using a shell script like this one: +</p> +<div class="example"> +<pre class="example">for i in `seq 1 100`; do + fastprog + mv gmon.out gmon.out.$i +done + +gprof -s fastprog gmon.out.* + +gprof fastprog gmon.sum +</pre></div> + +<p>If your program is completely deterministic, all the call counts +will be simple multiples of 100 (i.e., a function called once in +each run will appear with a call count of 100). +</p> +</dd> +</dl> + +<hr> +<a name="Incompatibilities"></a> +<div class="header"> +<p> +Next: <a href="#Details" accesskey="n" rel="next">Details</a>, Previous: <a href="#How-do-I_003f" accesskey="p" rel="previous">How do I?</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Incompatibilities-with-Unix-gprof"></a> +<h2 class="chapter">8 Incompatibilities with Unix <code>gprof</code></h2> + +<p><small>GNU</small> <code>gprof</code> and Berkeley Unix <code>gprof</code> use the same data +file <samp>gmon.out</samp>, and provide essentially the same information. But +there are a few differences. +</p> +<ul> +<li> <small>GNU</small> <code>gprof</code> uses a new, generalized file format with support +for basic-block execution counts and non-realtime histograms. A magic +cookie and version number allows <code>gprof</code> to easily identify +new style files. Old BSD-style files can still be read. +See <a href="#File-Format">Profiling Data File Format</a>. + +</li><li> For a recursive function, Unix <code>gprof</code> lists the function as a +parent and as a child, with a <code>calls</code> field that lists the number +of recursive calls. <small>GNU</small> <code>gprof</code> omits these lines and puts +the number of recursive calls in the primary line. + +</li><li> When a function is suppressed from the call graph with ‘<samp>-e</samp>’, <small>GNU</small> +<code>gprof</code> still lists it as a subroutine of functions that call it. + +</li><li> <small>GNU</small> <code>gprof</code> accepts the ‘<samp>-k</samp>’ with its argument +in the form ‘<samp>from/to</samp>’, instead of ‘<samp>from to</samp>’. + +</li><li> In the annotated source listing, +if there are multiple basic blocks on the same line, +<small>GNU</small> <code>gprof</code> prints all of their counts, separated by commas. + + +</li><li> The blurbs, field widths, and output formats are different. <small>GNU</small> +<code>gprof</code> prints blurbs after the tables, so that you can see the +tables without skipping the blurbs. +</li></ul> + +<hr> +<a name="Details"></a> +<div class="header"> +<p> +Next: <a href="#GNU-Free-Documentation-License" accesskey="n" rel="next">GNU Free Documentation License</a>, Previous: <a href="#Incompatibilities" accesskey="p" rel="previous">Incompatibilities</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Details-of-Profiling"></a> +<h2 class="chapter">9 Details of Profiling</h2> + +<table class="menu" border="0" cellspacing="0"> +<tr><td align="left" valign="top">• <a href="#Implementation" accesskey="1">Implementation</a>:</td><td> </td><td align="left" valign="top">How a program collects profiling information +</td></tr> +<tr><td align="left" valign="top">• <a href="#File-Format" accesskey="2">File Format</a>:</td><td> </td><td align="left" valign="top">Format of ‘<samp>gmon.out</samp>’ files +</td></tr> +<tr><td align="left" valign="top">• <a href="#Internals" accesskey="3">Internals</a>:</td><td> </td><td align="left" valign="top"><code>gprof</code>’s internal operation +</td></tr> +<tr><td align="left" valign="top">• <a href="#Debugging" accesskey="4">Debugging</a>:</td><td> </td><td align="left" valign="top">Using <code>gprof</code>’s ‘<samp>-d</samp>’ option +</td></tr> +</table> + +<hr> +<a name="Implementation"></a> +<div class="header"> +<p> +Next: <a href="#File-Format" accesskey="n" rel="next">File Format</a>, Up: <a href="#Details" accesskey="u" rel="up">Details</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Implementation-of-Profiling"></a> +<h3 class="section">9.1 Implementation of Profiling</h3> + +<p>Profiling works by changing how every function in your program is compiled +so that when it is called, it will stash away some information about where +it was called from. From this, the profiler can figure out what function +called it, and can count how many times it was called. This change is made +by the compiler when your program is compiled with the ‘<samp>-pg</samp>’ option, +which causes every function to call <code>mcount</code> +(or <code>_mcount</code>, or <code>__mcount</code>, depending on the OS and compiler) +as one of its first operations. +</p> +<p>The <code>mcount</code> routine, included in the profiling library, +is responsible for recording in an in-memory call graph table +both its parent routine (the child) and its parent’s parent. This is +typically done by examining the stack frame to find both +the address of the child, and the return address in the original parent. +Since this is a very machine-dependent operation, <code>mcount</code> +itself is typically a short assembly-language stub routine +that extracts the required +information, and then calls <code>__mcount_internal</code> +(a normal C function) with two arguments—<code>frompc</code> and <code>selfpc</code>. +<code>__mcount_internal</code> is responsible for maintaining +the in-memory call graph, which records <code>frompc</code>, <code>selfpc</code>, +and the number of times each of these call arcs was traversed. +</p> +<p>GCC Version 2 provides a magical function (<code>__builtin_return_address</code>), +which allows a generic <code>mcount</code> function to extract the +required information from the stack frame. However, on some +architectures, most notably the SPARC, using this builtin can be +very computationally expensive, and an assembly language version +of <code>mcount</code> is used for performance reasons. +</p> +<p>Number-of-calls information for library routines is collected by using a +special version of the C library. The programs in it are the same as in +the usual C library, but they were compiled with ‘<samp>-pg</samp>’. If you +link your program with ‘<samp>gcc … -pg</samp>’, it automatically uses the +profiling version of the library. +</p> +<p>Profiling also involves watching your program as it runs, and keeping a +histogram of where the program counter happens to be every now and then. +Typically the program counter is looked at around 100 times per second of +run time, but the exact frequency may vary from system to system. +</p> +<p>This is done is one of two ways. Most UNIX-like operating systems +provide a <code>profil()</code> system call, which registers a memory +array with the kernel, along with a scale +factor that determines how the program’s address space maps +into the array. +Typical scaling values cause every 2 to 8 bytes of address space +to map into a single array slot. +On every tick of the system clock +(assuming the profiled program is running), the value of the +program counter is examined and the corresponding slot in +the memory array is incremented. Since this is done in the kernel, +which had to interrupt the process anyway to handle the clock +interrupt, very little additional system overhead is required. +</p> +<p>However, some operating systems, most notably Linux 2.0 (and earlier), +do not provide a <code>profil()</code> system call. On such a system, +arrangements are made for the kernel to periodically deliver +a signal to the process (typically via <code>setitimer()</code>), +which then performs the same operation of examining the +program counter and incrementing a slot in the memory array. +Since this method requires a signal to be delivered to +user space every time a sample is taken, it uses considerably +more overhead than kernel-based profiling. Also, due to the +added delay required to deliver the signal, this method is +less accurate as well. +</p> +<p>A special startup routine allocates memory for the histogram and +either calls <code>profil()</code> or sets up +a clock signal handler. +This routine (<code>monstartup</code>) can be invoked in several ways. +On Linux systems, a special profiling startup file <code>gcrt0.o</code>, +which invokes <code>monstartup</code> before <code>main</code>, +is used instead of the default <code>crt0.o</code>. +Use of this special startup file is one of the effects +of using ‘<samp>gcc … -pg</samp>’ to link. +On SPARC systems, no special startup files are used. +Rather, the <code>mcount</code> routine, when it is invoked for +the first time (typically when <code>main</code> is called), +calls <code>monstartup</code>. +</p> +<p>If the compiler’s ‘<samp>-a</samp>’ option was used, basic-block counting +is also enabled. Each object file is then compiled with a static array +of counts, initially zero. +In the executable code, every time a new basic-block begins +(i.e., when an <code>if</code> statement appears), an extra instruction +is inserted to increment the corresponding count in the array. +At compile time, a paired array was constructed that recorded +the starting address of each basic-block. Taken together, +the two arrays record the starting address of every basic-block, +along with the number of times it was executed. +</p> +<p>The profiling library also includes a function (<code>mcleanup</code>) which is +typically registered using <code>atexit()</code> to be called as the +program exits, and is responsible for writing the file <samp>gmon.out</samp>. +Profiling is turned off, various headers are output, and the histogram +is written, followed by the call-graph arcs and the basic-block counts. +</p> +<p>The output from <code>gprof</code> gives no indication of parts of your program that +are limited by I/O or swapping bandwidth. This is because samples of the +program counter are taken at fixed intervals of the program’s run time. +Therefore, the +time measurements in <code>gprof</code> output say nothing about time that your +program was not running. For example, a part of the program that creates +so much data that it cannot all fit in physical memory at once may run very +slowly due to thrashing, but <code>gprof</code> will say it uses little time. On +the other hand, sampling by run time has the advantage that the amount of +load due to other users won’t directly affect the output you get. +</p> +<hr> +<a name="File-Format"></a> +<div class="header"> +<p> +Next: <a href="#Internals" accesskey="n" rel="next">Internals</a>, Previous: <a href="#Implementation" accesskey="p" rel="previous">Implementation</a>, Up: <a href="#Details" accesskey="u" rel="up">Details</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Profiling-Data-File-Format"></a> +<h3 class="section">9.2 Profiling Data File Format</h3> + +<p>The old BSD-derived file format used for profile data does not contain a +magic cookie that allows one to check whether a data file really is a +<code>gprof</code> file. Furthermore, it does not provide a version number, thus +rendering changes to the file format almost impossible. <small>GNU</small> <code>gprof</code> +uses a new file format that provides these features. For backward +compatibility, <small>GNU</small> <code>gprof</code> continues to support the old BSD-derived +format, but not all features are supported with it. For example, +basic-block execution counts cannot be accommodated by the old file +format. +</p> +<p>The new file format is defined in header file <samp>gmon_out.h</samp>. It +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 target for which +the profile was collected. <small>GNU</small> <code>gprof</code> adapts automatically +to the byte-order in use. +</p> +<p>In the new file format, the header is followed by a sequence of +records. Currently, there are three different record types: histogram +records, call-graph arc records, and basic-block execution count +records. Each file can contain any number of each record type. When +reading a file, <small>GNU</small> <code>gprof</code> will ensure records of the same type are +compatible with each other and compute the union of all records. For +example, for basic-block execution counts, the union is simply the sum +of all execution counts for each basic-block. +</p> +<a name="Histogram-Records"></a> +<h4 class="subsection">9.2.1 Histogram Records</h4> + +<p>Histogram records consist of a header that is followed by an array of +bins. The header contains the text-segment range that the histogram +spans, the size of the histogram in bytes (unlike in the old BSD +format, this does not include the size of the header), the rate of the +profiling clock, and the physical dimension that the bin counts +represent after being scaled by the profiling clock rate. The +physical dimension is specified in two parts: a long name of up to 15 +characters and a single character abbreviation. For example, a +histogram representing real-time would specify the long name as +“seconds” and the abbreviation as “s”. This feature is useful for +architectures that support performance monitor hardware (which, +fortunately, is becoming increasingly common). For example, under DEC +OSF/1, the “uprofile” command can be used to produce a histogram of, +say, instruction cache misses. In this case, the dimension in the +histogram header could be set to “i-cache misses” and the abbreviation +could be set to “1” (because it is simply a count, not a physical +dimension). Also, the profiling rate would have to be set to 1 in +this case. +</p> +<p>Histogram bins are 16-bit numbers and each bin represent an equal +amount of text-space. For example, if the text-segment is one +thousand bytes long and if there are ten bins in the histogram, each +bin represents one hundred bytes. +</p> + +<a name="Call_002dGraph-Records"></a> +<h4 class="subsection">9.2.2 Call-Graph Records</h4> + +<p>Call-graph records have a format that is identical to the one used in +the BSD-derived file format. It consists of an arc in the call graph +and a count indicating the number of times the arc was traversed +during program execution. Arcs are specified by a pair of addresses: +the first must be within caller’s function and the second must be +within the callee’s function. When performing profiling at the +function level, these addresses can point anywhere within the +respective function. However, when profiling at the line-level, it is +better if the addresses are as close to the call-site/entry-point as +possible. This will ensure that the line-level call-graph is able to +identify exactly which line of source code performed calls to a +function. +</p> +<a name="Basic_002dBlock-Execution-Count-Records"></a> +<h4 class="subsection">9.2.3 Basic-Block Execution Count Records</h4> + +<p>Basic-block execution count records consist of a header followed by a +sequence of address/count pairs. The header simply specifies the +length of the sequence. In an address/count pair, the address +identifies a basic-block and the count specifies the number of times +that basic-block was executed. Any address within the basic-address can +be used. +</p> +<hr> +<a name="Internals"></a> +<div class="header"> +<p> +Next: <a href="#Debugging" accesskey="n" rel="next">Debugging</a>, Previous: <a href="#File-Format" accesskey="p" rel="previous">File Format</a>, Up: <a href="#Details" accesskey="u" rel="up">Details</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="gprof_0027s-Internal-Operation"></a> +<h3 class="section">9.3 <code>gprof</code>’s Internal Operation</h3> + +<p>Like most programs, <code>gprof</code> begins by processing its options. +During this stage, it may building its symspec list +(<code>sym_ids.c:sym_id_add</code>), if +options are specified which use symspecs. +<code>gprof</code> maintains a single linked list of symspecs, +which will eventually get turned into 12 symbol tables, +organized into six include/exclude pairs—one +pair each for the flat profile (INCL_FLAT/EXCL_FLAT), +the call graph arcs (INCL_ARCS/EXCL_ARCS), +printing in the call graph (INCL_GRAPH/EXCL_GRAPH), +timing propagation in the call graph (INCL_TIME/EXCL_TIME), +the annotated source listing (INCL_ANNO/EXCL_ANNO), +and the execution count listing (INCL_EXEC/EXCL_EXEC). +</p> +<p>After option processing, <code>gprof</code> finishes +building the symspec list by adding all the symspecs in +<code>default_excluded_list</code> to the exclude lists +EXCL_TIME and EXCL_GRAPH, and if line-by-line profiling is specified, +EXCL_FLAT as well. +These default excludes are not added to EXCL_ANNO, EXCL_ARCS, and EXCL_EXEC. +</p> +<p>Next, the BFD library is called to open the object file, +verify that it is an object file, +and read its symbol table (<code>core.c:core_init</code>), +using <code>bfd_canonicalize_symtab</code> after mallocing +an appropriately sized array of symbols. At this point, +function mappings are read (if the ‘<samp>--file-ordering</samp>’ option +has been specified), and the core text space is read into +memory (if the ‘<samp>-c</samp>’ option was given). +</p> +<p><code>gprof</code>’s own symbol table, an array of Sym structures, +is now built. +This is done in one of two ways, by one of two routines, depending +on whether line-by-line profiling (‘<samp>-l</samp>’ option) has been +enabled. +For normal profiling, the BFD canonical symbol table is scanned. +For line-by-line profiling, every +text space address is examined, and a new symbol table entry +gets created every time the line number changes. +In either case, two passes are made through the symbol +table—one to count the size of the symbol table required, +and the other to actually read the symbols. In between the +two passes, a single array of type <code>Sym</code> is created of +the appropriate length. +Finally, <code>symtab.c:symtab_finalize</code> +is called to sort the symbol table and remove duplicate entries +(entries with the same memory address). +</p> +<p>The symbol table must be a contiguous array for two reasons. +First, the <code>qsort</code> library function (which sorts an array) +will be used to sort the symbol table. +Also, the symbol lookup routine (<code>symtab.c:sym_lookup</code>), +which finds symbols +based on memory address, uses a binary search algorithm +which requires the symbol table to be a sorted array. +Function symbols are indicated with an <code>is_func</code> flag. +Line number symbols have no special flags set. +Additionally, a symbol can have an <code>is_static</code> flag +to indicate that it is a local symbol. +</p> +<p>With the symbol table read, the symspecs can now be translated +into Syms (<code>sym_ids.c:sym_id_parse</code>). Remember that a single +symspec can match multiple symbols. +An array of symbol tables +(<code>syms</code>) is created, each entry of which is a symbol table +of Syms to be included or excluded from a particular listing. +The master symbol table and the symspecs are examined by nested +loops, and every symbol that matches a symspec is inserted +into the appropriate syms table. This is done twice, once to +count the size of each required symbol table, and again to build +the tables, which have been malloced between passes. +From now on, to determine whether a symbol is on an include +or exclude symspec list, <code>gprof</code> simply uses its +standard symbol lookup routine on the appropriate table +in the <code>syms</code> array. +</p> +<p>Now the profile data file(s) themselves are read +(<code>gmon_io.c:gmon_out_read</code>), +first by checking for a new-style ‘<samp>gmon.out</samp>’ header, +then assuming this is an old-style BSD ‘<samp>gmon.out</samp>’ +if the magic number test failed. +</p> +<p>New-style histogram records are read by <code>hist.c:hist_read_rec</code>. +For the first histogram record, allocate a memory array to hold +all the bins, and read them in. +When multiple profile data files (or files with multiple histogram +records) are read, the memory ranges of each pair of histogram records +must be either equal, or non-overlapping. For each pair of histogram +records, the resolution (memory region size divided by the number of +bins) must be the same. The time unit must be the same for all +histogram records. If the above containts are met, all histograms +for the same memory range are merged. +</p> +<p>As each call graph record is read (<code>call_graph.c:cg_read_rec</code>), +the parent and child addresses +are matched to symbol table entries, and a call graph arc is +created by <code>cg_arcs.c:arc_add</code>, unless the arc fails a symspec +check against INCL_ARCS/EXCL_ARCS. As each arc is added, +a linked list is maintained of the parent’s child arcs, and of the child’s +parent arcs. +Both the child’s call count and the arc’s call count are +incremented by the record’s call count. +</p> +<p>Basic-block records are read (<code>basic_blocks.c:bb_read_rec</code>), +but only if line-by-line profiling has been selected. +Each basic-block address is matched to a corresponding line +symbol in the symbol table, and an entry made in the symbol’s +bb_addr and bb_calls arrays. Again, if multiple basic-block +records are present for the same address, the call counts +are cumulative. +</p> +<p>A gmon.sum file is dumped, if requested (<code>gmon_io.c:gmon_out_write</code>). +</p> +<p>If histograms were present in the data files, assign them to symbols +(<code>hist.c:hist_assign_samples</code>) by iterating over all the sample +bins and assigning them to symbols. Since the symbol table +is sorted in order of ascending memory addresses, we can +simple follow along in the symbol table as we make our pass +over the sample bins. +This step includes a symspec check against INCL_FLAT/EXCL_FLAT. +Depending on the histogram +scale factor, a sample bin may span multiple symbols, +in which case a fraction of the sample count is allocated +to each symbol, proportional to the degree of overlap. +This effect is rare for normal profiling, but overlaps +are more common during line-by-line profiling, and can +cause each of two adjacent lines to be credited with half +a hit, for example. +</p> +<p>If call graph data is present, <code>cg_arcs.c:cg_assemble</code> is called. +First, if ‘<samp>-c</samp>’ was specified, a machine-dependent +routine (<code>find_call</code>) scans through each symbol’s machine code, +looking for subroutine call instructions, and adding them +to the call graph with a zero call count. +A topological sort is performed by depth-first numbering +all the symbols (<code>cg_dfn.c:cg_dfn</code>), so that +children are always numbered less than their parents, +then making a array of pointers into the symbol table and sorting it into +numerical order, which is reverse topological +order (children appear before parents). +Cycles are also detected at this point, all members +of which are assigned the same topological number. +Two passes are now made through this sorted array of symbol pointers. +The first pass, from end to beginning (parents to children), +computes the fraction of child time to propagate to each parent +and a print flag. +The print flag reflects symspec handling of INCL_GRAPH/EXCL_GRAPH, +with a parent’s include or exclude (print or no print) property +being propagated to its children, unless they themselves explicitly appear +in INCL_GRAPH or EXCL_GRAPH. +A second pass, from beginning to end (children to parents) actually +propagates the timings along the call graph, subject +to a check against INCL_TIME/EXCL_TIME. +With the print flag, fractions, and timings now stored in the symbol +structures, the topological sort array is now discarded, and a +new array of pointers is assembled, this time sorted by propagated time. +</p> +<p>Finally, print the various outputs the user requested, which is now fairly +straightforward. The call graph (<code>cg_print.c:cg_print</code>) and +flat profile (<code>hist.c:hist_print</code>) are regurgitations of values +already computed. The annotated source listing +(<code>basic_blocks.c:print_annotated_source</code>) uses basic-block +information, if present, to label each line of code with call counts, +otherwise only the function call counts are presented. +</p> +<p>The function ordering code is marginally well documented +in the source code itself (<code>cg_print.c</code>). Basically, +the functions with the most use and the most parents are +placed first, followed by other functions with the most use, +followed by lower use functions, followed by unused functions +at the end. +</p> +<hr> +<a name="Debugging"></a> +<div class="header"> +<p> +Previous: <a href="#Internals" accesskey="p" rel="previous">Internals</a>, Up: <a href="#Details" accesskey="u" rel="up">Details</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="Debugging-gprof"></a> +<h3 class="section">9.4 Debugging <code>gprof</code></h3> + +<p>If <code>gprof</code> was compiled with debugging enabled, +the ‘<samp>-d</samp>’ option triggers debugging output +(to stdout) which can be helpful in understanding its operation. +The debugging number specified is interpreted as a sum of the following +options: +</p> +<dl compact="compact"> +<dt>2 - Topological sort</dt> +<dd><p>Monitor depth-first numbering of symbols during call graph analysis +</p></dd> +<dt>4 - Cycles</dt> +<dd><p>Shows symbols as they are identified as cycle heads +</p></dd> +<dt>16 - Tallying</dt> +<dd><p>As the call graph arcs are read, show each arc and how +the total calls to each function are tallied +</p></dd> +<dt>32 - Call graph arc sorting</dt> +<dd><p>Details sorting individual parents/children within each call graph entry +</p></dd> +<dt>64 - Reading histogram and call graph records</dt> +<dd><p>Shows address ranges of histograms as they are read, and each +call graph arc +</p></dd> +<dt>128 - Symbol table</dt> +<dd><p>Reading, classifying, and sorting the symbol table from the object file. +For line-by-line profiling (‘<samp>-l</samp>’ option), also shows line numbers +being assigned to memory addresses. +</p></dd> +<dt>256 - Static call graph</dt> +<dd><p>Trace operation of ‘<samp>-c</samp>’ option +</p></dd> +<dt>512 - Symbol table and arc table lookups</dt> +<dd><p>Detail operation of lookup routines +</p></dd> +<dt>1024 - Call graph propagation</dt> +<dd><p>Shows how function times are propagated along the call graph +</p></dd> +<dt>2048 - Basic-blocks</dt> +<dd><p>Shows basic-block records as they are read from profile data +(only meaningful with ‘<samp>-l</samp>’ option) +</p></dd> +<dt>4096 - Symspecs</dt> +<dd><p>Shows symspec-to-symbol pattern matching operation +</p></dd> +<dt>8192 - Annotate source</dt> +<dd><p>Tracks operation of ‘<samp>-A</samp>’ option +</p></dd> +</dl> + +<hr> +<a name="GNU-Free-Documentation-License"></a> +<div class="header"> +<p> +Previous: <a href="#Details" accesskey="p" rel="previous">Details</a>, Up: <a href="#Top" accesskey="u" rel="up">Top</a> [<a href="#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p> +</div> +<a name="GNU-Free-Documentation-License-1"></a> +<h2 class="appendix">Appendix A GNU Free Documentation License</h2> +<div align="center">Version 1.3, 3 November 2008 +</div> + +<div class="display"> +<pre class="display">Copyright © 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +<a href="http://fsf.org/">http://fsf.org/</a> + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +</pre></div> + +<ol> +<li> PREAMBLE + +<p>The purpose of this License is to make a manual, textbook, or other +functional and useful document <em>free</em> in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. +</p> +<p>This License is a kind of “copyleft”, which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. +</p> +<p>We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. +</p> +</li><li> APPLICABILITY AND DEFINITIONS + +<p>This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The “Document”, below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as “you”. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. +</p> +<p>A “Modified Version” of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. +</p> +<p>A “Secondary Section” is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document’s overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. +</p> +<p>The “Invariant Sections” are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. +</p> +<p>The “Cover Texts” are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. +</p> +<p>A “Transparent” copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not “Transparent” is called “Opaque”. +</p> +<p>Examples of suitable formats for Transparent copies include plain +<small>ASCII</small> without markup, Texinfo input format, LaTeX input +format, <acronym>SGML</acronym> or <acronym>XML</acronym> using a publicly available +<acronym>DTD</acronym>, and standard-conforming simple <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> designed for human modification. Examples +of transparent image formats include <acronym>PNG</acronym>, <acronym>XCF</acronym> and +<acronym>JPG</acronym>. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, <acronym>SGML</acronym> or +<acronym>XML</acronym> for which the <acronym>DTD</acronym> and/or processing tools are +not generally available, and the machine-generated <acronym>HTML</acronym>, +PostScript or <acronym>PDF</acronym> produced by some word processors for +output purposes only. +</p> +<p>The “Title Page” means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, “Title Page” means +the text near the most prominent appearance of the work’s title, +preceding the beginning of the body of the text. +</p> +<p>The “publisher” means any person or entity that distributes copies +of the Document to the public. +</p> +<p>A section “Entitled XYZ” means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as “Acknowledgements”, +“Dedications”, “Endorsements”, or “History”.) To “Preserve the Title” +of such a section when you modify the Document means that it remains a +section “Entitled XYZ” according to this definition. +</p> +<p>The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. +</p> +</li><li> VERBATIM COPYING + +<p>You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. +</p> +<p>You may also lend copies, under the same conditions stated above, and +you may publicly display copies. +</p> +</li><li> COPYING IN QUANTITY + +<p>If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document’s license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. +</p> +<p>If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. +</p> +<p>If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. +</p> +<p>It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. +</p> +</li><li> MODIFICATIONS + +<p>You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: +</p> +<ol> +<li> Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +</li><li> List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +</li><li> State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +</li><li> Preserve all the copyright notices of the Document. + +</li><li> Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +</li><li> Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +</li><li> Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document’s license notice. + +</li><li> Include an unaltered copy of this License. + +</li><li> Preserve the section Entitled “History”, Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled “History” in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +</li><li> Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the “History” section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +</li><li> For any section Entitled “Acknowledgements” or “Dedications”, Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +</li><li> Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +</li><li> Delete any section Entitled “Endorsements”. Such a section +may not be included in the Modified Version. + +</li><li> Do not retitle any existing section to be Entitled “Endorsements” or +to conflict in title with any Invariant Section. + +</li><li> Preserve any Warranty Disclaimers. +</li></ol> + +<p>If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version’s license notice. +These titles must be distinct from any other section titles. +</p> +<p>You may add a section Entitled “Endorsements”, provided it contains +nothing but endorsements of your Modified Version by various +parties—for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. +</p> +<p>You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. +</p> +<p>The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. +</p> +</li><li> COMBINING DOCUMENTS + +<p>You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. +</p> +<p>The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. +</p> +<p>In the combination, you must combine any sections Entitled “History” +in the various original documents, forming one section Entitled +“History”; likewise combine any sections Entitled “Acknowledgements”, +and any sections Entitled “Dedications”. You must delete all +sections Entitled “Endorsements.” +</p> +</li><li> COLLECTIONS OF DOCUMENTS + +<p>You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. +</p> +<p>You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. +</p> +</li><li> AGGREGATION WITH INDEPENDENT WORKS + +<p>A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an “aggregate” if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation’s users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. +</p> +<p>If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document’s Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. +</p> +</li><li> TRANSLATION + +<p>Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. +</p> +<p>If a section in the Document is Entitled “Acknowledgements”, +“Dedications”, or “History”, the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. +</p> +</li><li> TERMINATION + +<p>You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. +</p> +<p>However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. +</p> +<p>Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. +</p> +<p>Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. +</p> +</li><li> FUTURE REVISIONS OF THIS LICENSE + +<p>The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +<a href="http://www.gnu.org/copyleft/">http://www.gnu.org/copyleft/</a>. +</p> +<p>Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License “or any later version” applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy’s public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. +</p> +</li><li> RELICENSING + +<p>“Massive Multiauthor Collaboration Site” (or “MMC Site”) means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +“Massive Multiauthor Collaboration” (or “MMC”) contained in the +site means any set of copyrightable works thus published on the MMC +site. +</p> +<p>“CC-BY-SA” means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. +</p> +<p>“Incorporate” means to publish or republish a Document, in whole or +in part, as part of another Document. +</p> +<p>An MMC is “eligible for relicensing” if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. +</p> +<p>The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. +</p> +</li></ol> + +<a name="ADDENDUM_003a-How-to-use-this-License-for-your-documents"></a> +<h3 class="heading">ADDENDUM: How to use this License for your documents</h3> + +<p>To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: +</p> +<div class="smallexample"> +<pre class="smallexample"> Copyright (C) <var>year</var> <var>your name</var>. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +</pre></div> + +<p>If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the “with…Texts.” line with this: +</p> +<div class="smallexample"> +<pre class="smallexample"> with the Invariant Sections being <var>list their titles</var>, with + the Front-Cover Texts being <var>list</var>, and with the Back-Cover Texts + being <var>list</var>. +</pre></div> + +<p>If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. +</p> +<p>If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. +</p> + + +<hr> + + + +</body> +</html> |