espressif/binutils-gdb
1
0
Fork 0
mirror of https://github.com/espressif/binutils-gdb.git synced 2025-09-10 14:59:31 +08:00
Code Issues Packages Projects Releases Wiki Activity

* gprof.texi: Use TeX-style quotes and em-dashes consistently.

Browse Source 
Specify section names in cross references.  Fix typos.
        Omit "next", "previous" and "up" fields from @node lines.
        (SYNOPSIS): Show map_file argument to --file-ordering.
        (Compiling): Remove extra, truncated lines from example output.
        (Cycles): Fix references to "called" field.
        (Internals): Allow hyphenation between file:function names.
        (GNU Free Documentation License): Update formatting to match fdl.texi.
This commit is contained in:
Bob Wilson
2006-09-25 16:16:45 +00:00
parent f983a9b6a3
commit afb175693a
2 changed files with 194 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
gprof/ChangeLog
View File

@ -1,3 +1,14 @@
2006-09-19 Bob Wilson <bob.wilson@acm.org>
* gprof.texi: Use TeX-style quotes and em-dashes consistently.
Specify section names in cross references. Fix typos.
Omit "next", "previous" and "up" fields from @node lines.
(SYNOPSIS): Show map_file argument to --file-ordering.
(Compiling): Remove extra, truncated lines from example output.
(Cycles): Fix references to "called" field.
(Internals): Allow hyphenation between file:function names.
(GNU Free Documentation License): Update formatting to match fdl.texi.
2006-07-24 Ralk Wildenhues <Ralf.Wildenhues@gmx.de> 2006-07-24 Ralk Wildenhues <Ralf.Wildenhues@gmx.de>
* gprof.texi: Fix some typos. * gprof.texi: Fix some typos.

360
gprof/gprof.texi
View File

@ -26,7 +26,7 @@ under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation; or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License". section entitled ``GNU Free Documentation License''.
@c man end @c man end
@ -63,7 +63,7 @@ Copyright @copyright{} 1988, 92, 97, 98, 99, 2000, 2003 Free Software Foundation
or any later version published by the Free Software Foundation; or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no with no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts. A copy of the license is included in the Back-Cover Texts. A copy of the license is included in the
section entitled "GNU Free Documentation License". section entitled ``GNU Free Documentation License''.
@end titlepage @end titlepage
@ -78,7 +78,7 @@ execute programs. @sc{gnu} @code{gprof} was written by Jay Fenlason.
This document is distributed under the terms of the GNU Free This document is distributed under the terms of the GNU Free
Documentation License. A copy of the license is included in the Documentation License. A copy of the license is included in the
section entitled "GNU Free Documentation License". section entitled ``GNU Free Documentation License''.
@menu @menu
* Introduction:: What profiling means, and why it is useful. * Introduction:: What profiling means, and why it is useful.
@ -87,7 +87,7 @@ section entitled "GNU Free Documentation License".
* Executing:: Executing your program to generate profile data * Executing:: Executing your program to generate profile data
* Invoking:: How to run @code{gprof}, and its options * Invoking:: How to run @code{gprof}, and its options
* Output:: Interpreting @code{gprof}'s output * Output:: Interpreting @code{gprof}'s output
* Inaccuracy:: Potential problems you should be aware of * Inaccuracy:: Potential problems you should be aware of
* How do I?:: Answers to common questions * How do I?:: Answers to common questions
@ -113,7 +113,7 @@ gprof [ -[abcDhilLrsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ]
[ --[no-]flat-profile[=@var{name}] ] [ --[no-]graph[=@var{name}] ] [ --[no-]flat-profile[=@var{name}] ] [ --[no-]graph[=@var{name}] ]
[ --[no-]time=@var{name}] [ --all-lines ] [ --brief ] [ --[no-]time=@var{name}] [ --all-lines ] [ --brief ]
[ --debug[=@var{level}] ] [ --function-ordering ] [ --debug[=@var{level}] ] [ --function-ordering ]
[ --file-ordering ] [ --directory-path=@var{dirs} ] [ --file-ordering @var{map_file} ] [ --directory-path=@var{dirs} ]
[ --display-unused-functions ] [ --file-format=@var{name} ] [ --display-unused-functions ] [ --file-format=@var{name} ]
[ --file-info ] [ --help ] [ --line ] [ --min-count=@var{n} ] [ --file-info ] [ --help ] [ --line ] [ --min-count=@var{n} ]
[ --no-static ] [ --print-path ] [ --separate-files ] [ --no-static ] [ --print-path ] [ --separate-files ]
@ -216,15 +216,15 @@ Profiling has several steps:
@itemize @bullet @itemize @bullet
@item @item
You must compile and link your program with profiling enabled. You must compile and link your program with profiling enabled.
@xref{Compiling}. @xref{Compiling, ,Compiling a Program for Profiling}.
@item @item
You must execute your program to generate a profile data file. You must execute your program to generate a profile data file.
@xref{Executing}. @xref{Executing, ,Executing the Program}.
@item @item
You must run @code{gprof} to analyze the profile data. You must run @code{gprof} to analyze the profile data.
@xref{Invoking}. @xref{Invoking, ,@code{gprof} Command Summary}.
@end itemize @end itemize
The next three chapters explain these steps in greater detail. The next three chapters explain these steps in greater detail.
@ -236,22 +236,23 @@ Several forms of output are available from the analysis.
The @dfn{flat profile} shows how much time your program spent in each function, The @dfn{flat profile} shows how much time your program spent in each function,
and how many times that function was called. If you simply want to know 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. which functions burn most of the cycles, it is stated concisely here.
@xref{Flat Profile}. @xref{Flat Profile, ,The Flat Profile}.
The @dfn{call graph} shows, for each function, which functions called it, which The @dfn{call graph} shows, for each function, which functions called it, which
other functions it called, and how many times. There is also an estimate 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 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 suggest places where you might try to eliminate function calls that use a
lot of time. @xref{Call Graph}. lot of time. @xref{Call Graph, ,The Call Graph}.
The @dfn{annotated source} listing is a copy of the program's The @dfn{annotated source} listing is a copy of the program's
source code, labeled with the number of times each line of the source code, labeled with the number of times each line of the
program was executed. @xref{Annotated Source}. program was executed. @xref{Annotated Source, ,The Annotated Source
Listing}.
@c man end @c man end
To better understand how profiling works, you may wish to read To better understand how profiling works, you may wish to read
a description of its implementation. a description of its implementation.
@xref{Implementation}. @xref{Implementation, ,Implementation of Profiling}.
@node Compiling @node Compiling
@chapter Compiling a Program for Profiling @chapter Compiling a Program for Profiling
@ -300,8 +301,6 @@ Each sample counts as 0.01 seconds.
44.12 0.07 0.07 zazLoop 44.12 0.07 0.07 zazLoop
35.29 0.14 0.06 main 35.29 0.14 0.06 main
20.59 0.17 0.04 bazMillion 20.59 0.17 0.04 bazMillion
% the percentage of the total running time of the
@end example @end example
If you run the linker @code{ld} directly instead of through a compiler If you run the linker @code{ld} directly instead of through a compiler
@ -331,7 +330,7 @@ If you wish to perform line-by-line profiling,
you will also need to specify the @samp{-g} option, you will also need to specify the @samp{-g} option,
instructing the compiler to insert debugging symbols into the program instructing the compiler to insert debugging symbols into the program
that match program addresses to source code lines. that match program addresses to source code lines.
@xref{Line-by-line}. @xref{Line-by-line, ,Line-by-line Profiling}.
In addition to the @samp{-pg} and @samp{-g} options, older versions of In addition to the @samp{-pg} and @samp{-g} options, older versions of
GCC required you to specify the @samp{-a} option when compiling in GCC required you to specify the @samp{-a} option when compiling in
@ -362,7 +361,7 @@ Once the program is compiled for profiling, you must run it in order to
generate the information that @code{gprof} needs. Simply run the program generate the information that @code{gprof} needs. Simply run the program
as usual, using the normal arguments, file names, etc. The program should as usual, using the normal arguments, file names, etc. The program should
run normally, producing the same output as usual. It will, however, run run normally, producing the same output as usual. It will, however, run
somewhat slower than normal because of the time spent collecting and the somewhat slower than normal because of the time spent collecting and
writing the profile data. writing the profile data.
The way you run the program---the arguments and input that you give The way you run the program---the arguments and input that you give
@ -449,7 +448,7 @@ The order of these options does not matter.
* Symspecs:: Specifying functions to include or exclude * Symspecs:: Specifying functions to include or exclude
@end menu @end menu
@node Output Options,Analysis Options,,Invoking @node Output Options
@section Output Options @section Output Options
@c man begin OPTIONS @c man begin OPTIONS
@ -459,7 +458,7 @@ These options specify which of several output formats
Many of these options take an optional @dfn{symspec} to specify Many of these options take an optional @dfn{symspec} to specify
functions to be included or excluded. These options can be functions to be included or excluded. These options can be
specified multiple times, with different symspecs, to include specified multiple times, with different symspecs, to include
or exclude sets of symbols. @xref{Symspecs}. or exclude sets of symbols. @xref{Symspecs, ,Symspecs}.
Specifying any of these options overrides the default (@samp{-p -q}), Specifying any of these options overrides the default (@samp{-p -q}),
which prints a flat profile and call graph analysis which prints a flat profile and call graph analysis
@ -471,7 +470,7 @@ for all functions.
@itemx --annotated-source[=@var{symspec}] @itemx --annotated-source[=@var{symspec}]
The @samp{-A} option causes @code{gprof} to print annotated source code. The @samp{-A} option causes @code{gprof} to print annotated source code.
If @var{symspec} is specified, print output only for matching symbols. If @var{symspec} is specified, print output only for matching symbols.
@xref{Annotated Source}. @xref{Annotated Source, ,The Annotated Source Listing}.
@item -b @item -b
@itemx --brief @itemx --brief
@ -524,7 +523,7 @@ was invoked.
@itemx --flat-profile[=@var{symspec}] @itemx --flat-profile[=@var{symspec}]
The @samp{-p} option causes @code{gprof} to print a flat profile. The @samp{-p} option causes @code{gprof} to print a flat profile.
If @var{symspec} is specified, print flat profile only for matching symbols. If @var{symspec} is specified, print flat profile only for matching symbols.
@xref{Flat Profile}. @xref{Flat Profile, ,The Flat Profile}.
@item -P[@var{symspec}] @item -P[@var{symspec}]
@itemx --no-flat-profile[=@var{symspec}] @itemx --no-flat-profile[=@var{symspec}]
@ -537,7 +536,7 @@ but excludes matching symbols.
The @samp{-q} option causes @code{gprof} to print the call graph analysis. The @samp{-q} option causes @code{gprof} to print the call graph analysis.
If @var{symspec} is specified, print call graph only for matching symbols If @var{symspec} is specified, print call graph only for matching symbols
and their children. and their children.
@xref{Call Graph}. @xref{Call Graph, ,The Call Graph}.
@item -Q[@var{symspec}] @item -Q[@var{symspec}]
@itemx --no-graph[=@var{symspec}] @itemx --no-graph[=@var{symspec}]
@ -643,7 +642,7 @@ argument can be used to choose an appropriate demangling style for your
compiler. compiler.
@end table @end table
@node Analysis Options,Miscellaneous Options,Output Options,Invoking @node Analysis Options
@section Analysis Options @section Analysis Options
@table @code @table @code
@ -697,7 +696,7 @@ While line-by-line profiling can help isolate where in a large function
a program is spending its time, it also significantly increases a program is spending its time, it also significantly increases
the running time of @code{gprof}, and magnifies statistical the running time of @code{gprof}, and magnifies statistical
inaccuracies. inaccuracies.
@xref{Sampling Error}. @xref{Sampling Error, ,Statistical Sampling Error}.
@item -m @var{num} @item -m @var{num}
@itemx --min-count=@var{num} @itemx --min-count=@var{num}
@ -723,7 +722,7 @@ that had no time spent in them. This is useful in conjunction with the
@end table @end table
@node Miscellaneous Options,Deprecated Options,Analysis Options,Invoking @node Miscellaneous Options
@section Miscellaneous Options @section Miscellaneous Options
@table @code @table @code
@ -732,7 +731,7 @@ that had no time spent in them. This is useful in conjunction with the
@itemx --debug[=@var{num}] @itemx --debug[=@var{num}]
The @samp{-d @var{num}} option specifies debugging options. The @samp{-d @var{num}} option specifies debugging options.
If @var{num} is not specified, enable all debugging. If @var{num} is not specified, enable all debugging.
@xref{Debugging}. @xref{Debugging, ,Debugging @code{gprof}}.
@item -h @item -h
@itemx --help @itemx --help
@ -763,7 +762,7 @@ number, and then exit.
@end table @end table
@node Deprecated Options,Symspecs,Miscellaneous Options,Invoking @node Deprecated Options
@section Deprecated Options @section Deprecated Options
@table @code @table @code
@ -817,7 +816,7 @@ gprof -e boring -f foo -f bar myprogram > gprof.output
lists in the call graph all functions that were reached from either lists in the call graph all functions that were reached from either
@code{foo} or @code{bar} and were not reachable from @code{boring}. @code{foo} or @code{bar} and were not reachable from @code{boring}.
@node Symspecs,,Deprecated Options,Invoking @node Symspecs
@section Symspecs @section Symspecs
Many of the output options allow functions to be included or excluded Many of the output options allow functions to be included or excluded
@ -878,7 +877,7 @@ most important of which are described below. The simplest output
styles (file information, execution count, and function and file ordering) styles (file information, execution count, and function and file ordering)
are not described here, but are documented with the respective options are not described here, but are documented with the respective options
that trigger them. that trigger them.
@xref{Output Options}. @xref{Output Options, ,Output Options}.
@menu @menu
* Flat Profile:: The flat profile shows how much time was spent * Flat Profile:: The flat profile shows how much time was spent
@ -892,7 +891,7 @@ that trigger them.
@end menu @end menu
@node Flat Profile,Call Graph,,Output @node Flat Profile
@section The Flat Profile @section The Flat Profile
@cindex flat profile @cindex flat profile
@ -932,7 +931,7 @@ Each sample counts as 0.01 seconds.
@end smallexample @end smallexample
@noindent @noindent
The functions are sorted by first by decreasing run-time spent in them, The functions are sorted first by decreasing run-time spent in them,
then by decreasing number of calls, then alphabetically by name. The then by decreasing number of calls, then alphabetically by name. The
functions @samp{mcount} and @samp{profil} are part of the profiling functions @samp{mcount} and @samp{profil} are part of the profiling
apparatus and appear in every flat profile; their time gives a measure of apparatus and appear in every flat profile; their time gives a measure of
@ -957,7 +956,8 @@ be regarded as particularly reliable.
In another run, In another run,
the @samp{self seconds} field for the @samp{self seconds} field for
@samp{mcount} might well be @samp{0.00} or @samp{0.02}. @samp{mcount} might well be @samp{0.00} or @samp{0.02}.
@xref{Sampling Error}, for a complete discussion. @xref{Sampling Error, ,Statistical Sampling Error},
for a complete discussion.
The remaining functions in the listing (those whose The remaining functions in the listing (those whose
@samp{self seconds} field is @samp{0.00}) didn't appear @samp{self seconds} field is @samp{0.00}) didn't appear
@ -1007,7 +1007,7 @@ field alphabetically after the @dfn{self seconds} and @dfn{calls}
fields are sorted. fields are sorted.
@end table @end table
@node Call Graph,Line-by-line,Flat Profile,Output @node Call Graph
@section The Call Graph @section The Call Graph
@cindex call graph @cindex call graph
@ -1018,7 +1018,7 @@ functions that did use unusual amounts of time.
Here is a sample call from a small program. This call came from the Here is a sample call from a small program. This call came from the
same @code{gprof} run as the flat profile example in the previous same @code{gprof} run as the flat profile example in the previous
chapter. section.
@smallexample @smallexample
@group @group
@ -1046,7 +1046,7 @@ index % time self children called name
0.00 0.00 8/8 chewtime [24] 0.00 0.00 8/8 chewtime [24]
0.00 0.00 8/16 skipspace [44] 0.00 0.00 8/16 skipspace [44]
----------------------------------------------- -----------------------------------------------
[4] 59.8 0.01 0.02 8+472 <cycle 2 as a whole> [4] [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.01 0.02 244+260 offtime <cycle 2> [7]
0.00 0.00 236+1 tzset <cycle 2> [26] 0.00 0.00 236+1 tzset <cycle 2> [26]
----------------------------------------------- -----------------------------------------------
@ -1064,8 +1064,8 @@ function and the following lines describe its subroutines (also called
The entries are sorted by time spent in the function and its subroutines. The entries are sorted by time spent in the function and its subroutines.
The internal profiling function @code{mcount} (@pxref{Flat Profile}) The internal profiling function @code{mcount} (@pxref{Flat Profile, ,The
is never mentioned in the call graph. Flat Profile}) is never mentioned in the call graph.
@menu @menu
* Primary:: Details of the primary line's contents. * Primary:: Details of the primary line's contents.
@ -1141,7 +1141,8 @@ repeated after it.
If the function is part of a cycle of recursion, the cycle number is If the function is part of a cycle of recursion, the cycle number is
printed between the function's name and the index number printed between the function's name and the index number
(@pxref{Cycles}). For example, if function @code{gnurr} is part of (@pxref{Cycles, ,How Mutually Recursive Functions Are Described}).
For example, if function @code{gnurr} is part of
cycle number one, and has index number twelve, its primary line would cycle number one, and has index number twelve, its primary line would
be end like this: be end like this:
@ -1150,7 +1151,7 @@ gnurr <cycle 1> [12]
@end example @end example
@end table @end table
@node Callers, Subroutines, Primary, Call Graph @node Callers
@subsection Lines for a Function's Callers @subsection Lines for a Function's Callers
A function's entry has a line for each function it was called by. A function's entry has a line for each function it was called by.
@ -1208,7 +1209,7 @@ signal handlers.
@c What if some calls have determinable callers' names but not all? @c What if some calls have determinable callers' names but not all?
@c FIXME - still relevant? @c FIXME - still relevant?
@node Subroutines, Cycles, Callers, Call Graph @node Subroutines
@subsection Lines for a Function's Subroutines @subsection Lines for a Function's Subroutines
A function's entry has a line for each of its subroutines---in other A function's entry has a line for each of its subroutines---in other
@ -1247,7 +1248,7 @@ Two numbers, the number of calls to @code{report} from @code{main}
followed by the total number of non-recursive calls to @code{report}. followed by the total number of non-recursive calls to @code{report}.
This ratio is used to determine how much of @code{report}'s @code{self} This ratio is used to determine how much of @code{report}'s @code{self}
and @code{children} time gets credited to @code{main}. and @code{children} time gets credited to @code{main}.
@xref{Assumptions}. @xref{Assumptions, ,Estimating @code{children} Times}.
@item name @item name
The name of the subroutine of @code{main} to which this line applies, The name of the subroutine of @code{main} to which this line applies,
@ -1257,7 +1258,7 @@ If the caller is part of a recursion cycle, the cycle number is
printed between the name and the index number. printed between the name and the index number.
@end table @end table
@node Cycles,, Subroutines, Call Graph @node Cycles
@subsection How Mutually Recursive Functions Are Described @subsection How Mutually Recursive Functions Are Described
@cindex cycle @cindex cycle
@cindex recursion cycle @cindex recursion cycle
@ -1373,17 +1374,17 @@ The @code{children} field of a caller-line in the cycle's entry estimates
the amount of time spent @emph{in the whole cycle}, and its other the amount of time spent @emph{in the whole cycle}, and its other
subroutines, on the times when that caller called a function in the cycle. subroutines, on the times when that caller called a function in the cycle.
The @code{calls} field in the primary line for the cycle has two numbers: The @code{called} field in the primary line for the cycle has two numbers:
first, the number of times functions in the cycle were called by functions 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 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 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 itself). This is a generalization of the usual split into non-recursive and
recursive calls. recursive calls.
The @code{calls} field of a subroutine-line for a cycle member in the The @code{called} 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 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 the cycle. The total of all these is the second number in the primary line's
@code{calls} field. @code{called} field.
In the individual entry for a function in a cycle, the other functions in 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 the same cycle can appear as subroutines and as callers. These lines show
@ -1392,7 +1393,7 @@ function in the cycle. The @code{self} and @code{children} fields in these
lines are blank because of the difficulty of defining meanings for them lines are blank because of the difficulty of defining meanings for them
when recursion is going on. when recursion is going on.
@node Line-by-line,Annotated Source,Call Graph,Output @node Line-by-line
@section Line-by-line Profiling @section Line-by-line Profiling
@code{gprof}'s @samp{-l} option causes the program to perform @code{gprof}'s @samp{-l} option causes the program to perform
@ -1440,7 +1441,7 @@ index % time self children called name
Now let's look at some of @code{gprof}'s output from the same program run, Now let's look at some of @code{gprof}'s output from the same program run,
this time with line-by-line profiling enabled. Note that @code{ct_init}'s this time with line-by-line profiling enabled. Note that @code{ct_init}'s
four histogram hits are broken down into four lines of source code - one hit 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, occurred on each of lines 349, 351, 382 and 385. In the call graph,
note how note how
@code{ct_init}'s 13327 calls to @code{init_block} are broken down @code{ct_init}'s 13327 calls to @code{init_block} are broken down
@ -1483,7 +1484,7 @@ granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
@end smallexample @end smallexample
@node Annotated Source,,Line-by-line,Output @node Annotated Source
@section The Annotated Source Listing @section The Annotated Source Listing
@code{gprof}'s @samp{-A} option triggers an annotated source listing, @code{gprof}'s @samp{-A} option triggers an annotated source listing,
@ -1530,8 +1531,9 @@ the fifth basic-block. The compiler may also generate additional
basic-blocks to handle various special cases. basic-blocks to handle various special cases.
A program augmented for basic-block counting can be analyzed with A program augmented for basic-block counting can be analyzed with
@samp{gprof -l -A}. I also suggest use of the @samp{-x} option, @samp{gprof -l -A}.
which ensures that each line of code is labeled at least once. The @samp{-x} option is also helpful,
to ensure that each line of code is labeled at least once.
Here is @code{updcrc}'s Here is @code{updcrc}'s
annotated source listing for a sample @code{gzip} run: annotated source listing for a sample @code{gzip} run:
@ -1545,9 +1547,9 @@ annotated source listing for a sample @code{gzip} run:
static ulg crc = (ulg)0xffffffffL; static ulg crc = (ulg)0xffffffffL;
2 -> if (s == NULL) @{ 2 -> if (s == NULL) @{
1 -> c = 0xffffffffL; 1 -> c = 0xffffffffL;
1 -> @} else @{ 1 -> @} else @{
1 -> c = crc; 1 -> c = crc;
1 -> if (n) do @{ 1 -> if (n) do @{
26312 -> c = crc_32_tab[...]; 26312 -> c = crc_32_tab[...];
26312,1,26311 -> @} while (--n); 26312,1,26311 -> @} while (--n);
@ -1572,7 +1574,7 @@ it exited, while it branched back to the beginning of the loop 26311 times.
* Assumptions:: Estimating children times * Assumptions:: Estimating children times
@end menu @end menu
@node Sampling Error,Assumptions,,Inaccuracy @node Sampling Error
@section Statistical Sampling Error @section Statistical Sampling Error
The run-time figures that @code{gprof} gives you are based on a sampling The run-time figures that @code{gprof} gives you are based on a sampling
@ -1643,7 +1645,7 @@ gprof @var{executable-file} gmon.sum > @var{output-file}
@end example @end example
@end enumerate @end enumerate
@node Assumptions,,Sampling Error,Inaccuracy @node Assumptions
@section Estimating @code{children} Times @section Estimating @code{children} Times
Some of the figures in the call graph are estimates---for example, the Some of the figures in the call graph are estimates---for example, the
@ -1672,7 +1674,7 @@ incorrectly charge 2 seconds of time in @code{foo} to the children of
@c FIXME - has this been fixed? @c FIXME - has this been fixed?
We hope some day to put more complete data into @file{gmon.out}, so that We hope some day to put more complete data into @file{gmon.out}, so that
this assumption is no longer needed, if we can figure out how. For the this assumption is no longer needed, if we can figure out how. For the
nonce, the estimated figures are usually more useful than misleading. novice, the estimated figures are usually more useful than misleading.
@node How do I? @node How do I?
@chapter Answers to Common Questions @chapter Answers to Common Questions
@ -1740,7 +1742,7 @@ there are a few differences.
for basic-block execution counts and non-realtime histograms. A magic for basic-block execution counts and non-realtime histograms. A magic
cookie and version number allows @code{gprof} to easily identify cookie and version number allows @code{gprof} to easily identify
new style files. Old BSD-style files can still be read. new style files. Old BSD-style files can still be read.
@xref{File Format}. @xref{File Format, ,Profiling Data File Format}.
@item @item
For a recursive function, Unix @code{gprof} lists the function as a For a recursive function, Unix @code{gprof} lists the function as a
@ -1784,7 +1786,7 @@ tables without skipping the blurbs.
* Debugging:: Using @code{gprof}'s @samp{-d} option * Debugging:: Using @code{gprof}'s @samp{-d} option
@end menu @end menu
@node Implementation,File Format,,Details @node Implementation
@section Implementation of Profiling @section Implementation of Profiling
Profiling works by changing how every function in your program is compiled Profiling works by changing how every function in your program is compiled
@ -1805,7 +1807,7 @@ Since this is a very machine-dependent operation, @code{mcount}
itself is typically a short assembly-language stub routine itself is typically a short assembly-language stub routine
that extracts the required that extracts the required
information, and then calls @code{__mcount_internal} information, and then calls @code{__mcount_internal}
(a normal C function) with two arguments - @code{frompc} and @code{selfpc}. (a normal C function) with two arguments---@code{frompc} and @code{selfpc}.
@code{__mcount_internal} is responsible for maintaining @code{__mcount_internal} is responsible for maintaining
the in-memory call graph, which records @code{frompc}, @code{selfpc}, the in-memory call graph, which records @code{frompc}, @code{selfpc},
and the number of times each of these call arcs was traversed. and the number of times each of these call arcs was traversed.
@ -1872,7 +1874,7 @@ If the compiler's @samp{-a} option was used, basic-block counting
is also enabled. Each object file is then compiled with a static array is also enabled. Each object file is then compiled with a static array
of counts, initially zero. of counts, initially zero.
In the executable code, every time a new basic-block begins In the executable code, every time a new basic-block begins
(i.e. when an @code{if} statement appears), an extra instruction (i.e., when an @code{if} statement appears), an extra instruction
is inserted to increment the corresponding count in the array. is inserted to increment the corresponding count in the array.
At compile time, a paired array was constructed that recorded At compile time, a paired array was constructed that recorded
the starting address of each basic-block. Taken together, the starting address of each basic-block. Taken together,
@ -1896,7 +1898,7 @@ slowly due to thrashing, but @code{gprof} will say it uses little time. On
the other hand, sampling by run time has the advantage that the amount of 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. load due to other users won't directly affect the output you get.
@node File Format,Internals,Implementation,Details @node File Format
@section Profiling Data File Format @section Profiling Data File Format
The old BSD-derived file format used for profile data does not contain a The old BSD-derived file format used for profile data does not contain a
@ -1936,13 +1938,13 @@ represent after being scaled by the profiling clock rate. The
physical dimension is specified in two parts: a long name of up to 15 physical dimension is specified in two parts: a long name of up to 15
characters and a single character abbreviation. For example, a characters and a single character abbreviation. For example, a
histogram representing real-time would specify the long name as histogram representing real-time would specify the long name as
"seconds" and the abbreviation as "s". This feature is useful for ``seconds'' and the abbreviation as ``s''. This feature is useful for
architectures that support performance monitor hardware (which, architectures that support performance monitor hardware (which,
fortunately, is becoming increasingly common). For example, under DEC fortunately, is becoming increasingly common). For example, under DEC
OSF/1, the "uprofile" command can be used to produce a histogram of, OSF/1, the ``uprofile'' command can be used to produce a histogram of,
say, instruction cache misses. In this case, the dimension in the say, instruction cache misses. In this case, the dimension in the
histogram header could be set to "i-cache misses" and the abbreviation 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 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 dimension). Also, the profiling rate would have to be set to 1 in
this case. this case.
@ -1976,16 +1978,16 @@ identifies a basic-block and the count specifies the number of times
that basic-block was executed. Any address within the basic-address can that basic-block was executed. Any address within the basic-address can
be used. be used.
@node Internals,Debugging,File Format,Details @node Internals
@section @code{gprof}'s Internal Operation @section @code{gprof}'s Internal Operation
Like most programs, @code{gprof} begins by processing its options. Like most programs, @code{gprof} begins by processing its options.
During this stage, it may building its symspec list During this stage, it may building its symspec list
(@code{sym_ids.c:sym_id_add}), if (@code{sym_ids.c:@-sym_id_add}), if
options are specified which use symspecs. options are specified which use symspecs.
@code{gprof} maintains a single linked list of symspecs, @code{gprof} maintains a single linked list of symspecs,
which will eventually get turned into 12 symbol tables, which will eventually get turned into 12 symbol tables,
organized into six include/exclude pairs - one organized into six include/exclude pairs---one
pair each for the flat profile (INCL_FLAT/EXCL_FLAT), pair each for the flat profile (INCL_FLAT/EXCL_FLAT),
the call graph arcs (INCL_ARCS/EXCL_ARCS), the call graph arcs (INCL_ARCS/EXCL_ARCS),
printing in the call graph (INCL_GRAPH/EXCL_GRAPH), printing in the call graph (INCL_GRAPH/EXCL_GRAPH),
@ -2002,7 +2004,7 @@ These default excludes are not added to EXCL_ANNO, EXCL_ARCS, and EXCL_EXEC.
Next, the BFD library is called to open the object file, Next, the BFD library is called to open the object file,
verify that it is an object file, verify that it is an object file,
and read its symbol table (@code{core.c:core_init}), and read its symbol table (@code{core.c:@-core_init}),
using @code{bfd_canonicalize_symtab} after mallocing using @code{bfd_canonicalize_symtab} after mallocing
an appropriately sized array of symbols. At this point, an appropriately sized array of symbols. At this point,
function mappings are read (if the @samp{--file-ordering} option function mappings are read (if the @samp{--file-ordering} option
@ -2019,18 +2021,18 @@ For line-by-line profiling, every
text space address is examined, and a new symbol table entry text space address is examined, and a new symbol table entry
gets created every time the line number changes. gets created every time the line number changes.
In either case, two passes are made through the symbol In either case, two passes are made through the symbol
table - one to count the size of the symbol table required, table---one to count the size of the symbol table required,
and the other to actually read the symbols. In between the and the other to actually read the symbols. In between the
two passes, a single array of type @code{Sym} is created of two passes, a single array of type @code{Sym} is created of
the appropriate length. the appropriate length.
Finally, @code{symtab.c:symtab_finalize} Finally, @code{symtab.c:@-symtab_finalize}
is called to sort the symbol table and remove duplicate entries is called to sort the symbol table and remove duplicate entries
(entries with the same memory address). (entries with the same memory address).
The symbol table must be a contiguous array for two reasons. The symbol table must be a contiguous array for two reasons.
First, the @code{qsort} library function (which sorts an array) First, the @code{qsort} library function (which sorts an array)
will be used to sort the symbol table. will be used to sort the symbol table.
Also, the symbol lookup routine (@code{symtab.c:sym_lookup}), Also, the symbol lookup routine (@code{symtab.c:@-sym_lookup}),
which finds symbols which finds symbols
based on memory address, uses a binary search algorithm based on memory address, uses a binary search algorithm
which requires the symbol table to be a sorted array. which requires the symbol table to be a sorted array.
@ -2040,7 +2042,7 @@ Additionally, a symbol can have an @code{is_static} flag
to indicate that it is a local symbol. to indicate that it is a local symbol.
With the symbol table read, the symspecs can now be translated With the symbol table read, the symspecs can now be translated
into Syms (@code{sym_ids.c:sym_id_parse}). Remember that a single into Syms (@code{sym_ids.c:@-sym_id_parse}). Remember that a single
symspec can match multiple symbols. symspec can match multiple symbols.
An array of symbol tables An array of symbol tables
(@code{syms}) is created, each entry of which is a symbol table (@code{syms}) is created, each entry of which is a symbol table
@ -2056,12 +2058,12 @@ standard symbol lookup routine on the appropriate table
in the @code{syms} array. in the @code{syms} array.
Now the profile data file(s) themselves are read Now the profile data file(s) themselves are read
(@code{gmon_io.c:gmon_out_read}), (@code{gmon_io.c:@-gmon_out_read}),
first by checking for a new-style @samp{gmon.out} header, first by checking for a new-style @samp{gmon.out} header,
then assuming this is an old-style BSD @samp{gmon.out} then assuming this is an old-style BSD @samp{gmon.out}
if the magic number test failed. if the magic number test failed.
New-style histogram records are read by @code{hist.c:hist_read_rec}. New-style histogram records are read by @code{hist.c:@-hist_read_rec}.
For the first histogram record, allocate a memory array to hold For the first histogram record, allocate a memory array to hold
all the bins, and read them in. all the bins, and read them in.
When multiple profile data files (or files with multiple histogram When multiple profile data files (or files with multiple histogram
@ -2071,17 +2073,17 @@ or a fatal error will result.
If everything matches, just sum the additional histograms into If everything matches, just sum the additional histograms into
the existing in-memory array. the existing in-memory array.
As each call graph record is read (@code{call_graph.c:cg_read_rec}), As each call graph record is read (@code{call_graph.c:@-cg_read_rec}),
the parent and child addresses the parent and child addresses
are matched to symbol table entries, and a call graph arc is are matched to symbol table entries, and a call graph arc is
created by @code{cg_arcs.c:arc_add}, unless the arc fails a symspec created by @code{cg_arcs.c:@-arc_add}, unless the arc fails a symspec
check against INCL_ARCS/EXCL_ARCS. As each arc is added, 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 a linked list is maintained of the parent's child arcs, and of the child's
parent arcs. parent arcs.
Both the child's call count and the arc's call count are Both the child's call count and the arc's call count are
incremented by the record's call count. incremented by the record's call count.
Basic-block records are read (@code{basic_blocks.c:bb_read_rec}), Basic-block records are read (@code{basic_blocks.c:@-bb_read_rec}),
but only if line-by-line profiling has been selected. but only if line-by-line profiling has been selected.
Each basic-block address is matched to a corresponding line Each basic-block address is matched to a corresponding line
symbol in the symbol table, and an entry made in the symbol's symbol in the symbol table, and an entry made in the symbol's
@ -2089,10 +2091,10 @@ bb_addr and bb_calls arrays. Again, if multiple basic-block
records are present for the same address, the call counts records are present for the same address, the call counts
are cumulative. are cumulative.
A gmon.sum file is dumped, if requested (@code{gmon_io.c:gmon_out_write}). A gmon.sum file is dumped, if requested (@code{gmon_io.c:@-gmon_out_write}).
If histograms were present in the data files, assign them to symbols If histograms were present in the data files, assign them to symbols
(@code{hist.c:hist_assign_samples}) by iterating over all the sample (@code{hist.c:@-hist_assign_samples}) by iterating over all the sample
bins and assigning them to symbols. Since the symbol table bins and assigning them to symbols. Since the symbol table
is sorted in order of ascending memory addresses, we can is sorted in order of ascending memory addresses, we can
simple follow along in the symbol table as we make our pass simple follow along in the symbol table as we make our pass
@ -2107,13 +2109,13 @@ are more common during line-by-line profiling, and can
cause each of two adjacent lines to be credited with half cause each of two adjacent lines to be credited with half
a hit, for example. a hit, for example.
If call graph data is present, @code{cg_arcs.c:cg_assemble} is called. If call graph data is present, @code{cg_arcs.c:@-cg_assemble} is called.
First, if @samp{-c} was specified, a machine-dependent First, if @samp{-c} was specified, a machine-dependent
routine (@code{find_call}) scans through each symbol's machine code, routine (@code{find_call}) scans through each symbol's machine code,
looking for subroutine call instructions, and adding them looking for subroutine call instructions, and adding them
to the call graph with a zero call count. to the call graph with a zero call count.
A topological sort is performed by depth-first numbering A topological sort is performed by depth-first numbering
all the symbols (@code{cg_dfn.c:cg_dfn}), so that all the symbols (@code{cg_dfn.c:@-cg_dfn}), so that
children are always numbered less than their parents, children are always numbered less than their parents,
then making a array of pointers into the symbol table and sorting it into then making a array of pointers into the symbol table and sorting it into
numerical order, which is reverse topological numerical order, which is reverse topological
@ -2136,10 +2138,10 @@ structures, the topological sort array is now discarded, and a
new array of pointers is assembled, this time sorted by propagated time. new array of pointers is assembled, this time sorted by propagated time.
Finally, print the various outputs the user requested, which is now fairly Finally, print the various outputs the user requested, which is now fairly
straightforward. The call graph (@code{cg_print.c:cg_print}) and straightforward. The call graph (@code{cg_print.c:@-cg_print}) and
flat profile (@code{hist.c:hist_print}) are regurgitations of values flat profile (@code{hist.c:@-hist_print}) are regurgitations of values
already computed. The annotated source listing already computed. The annotated source listing
(@code{basic_blocks.c:print_annotated_source}) uses basic-block (@code{basic_blocks.c:@-print_annotated_source}) uses basic-block
information, if present, to label each line of code with call counts, information, if present, to label each line of code with call counts,
otherwise only the function call counts are presented. otherwise only the function call counts are presented.
@ -2150,7 +2152,7 @@ placed first, followed by other functions with the most use,
followed by lower use functions, followed by unused functions followed by lower use functions, followed by unused functions
at the end. at the end.
@node Debugging,,Internals,Details @node Debugging
@subsection Debugging @code{gprof} @subsection Debugging @code{gprof}
If @code{gprof} was compiled with debugging enabled, If @code{gprof} was compiled with debugging enabled,
@ -2192,30 +2194,30 @@ Tracks operation of @samp{-A} option
@end table @end table
@node GNU Free Documentation License @node GNU Free Documentation License
@chapter GNU Free Documentation License @appendix GNU Free Documentation License
@center Version 1.1, March 2000
GNU Free Documentation License @display
Copyright (C) 2000, 2003 Free Software Foundation, Inc.
Version 1.1, March 2000 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Copyright (C) 2000 Free Software Foundation, Inc. Everyone is permitted to copy and distribute verbatim copies
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA of this license document, but changing it is not allowed.
@end display
Everyone is permitted to copy and distribute verbatim copies @sp 1
of this license document, but changing it is not allowed. @enumerate 0
@item
PREAMBLE
0. PREAMBLE
The purpose of this License is to make a manual, textbook, or other The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone written document ``free'' in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially. Secondarily, modifying it, either commercially or noncommercially. Secondarily,
this License preserves for the author and publisher a way to get this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for credit for their work, while not being considered responsible for
modifications made by others. modifications made by others.
This License is a kind of "copyleft", which means that derivative This License is a kind of ``copyleft'', which means that derivative
works of the document must themselves be free in the same sense. It works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft complements the GNU General Public License, which is a copyleft
license designed for free software. license designed for free software.
@ -2228,20 +2230,21 @@ 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 whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference. principally for works whose purpose is instruction or reference.
@sp 1
1. APPLICABILITY AND DEFINITIONS @item
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work that contains a This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed notice placed by the copyright holder saying it can be distributed
under the terms of this License. The "Document", below, refers to any under the terms of this License. The ``Document'', below, refers to any
such manual or work. Any member of the public is a licensee, and is such manual or work. Any member of the public is a licensee, and is
addressed as "you". addressed as ``you.''
A "Modified Version" of the Document means any work containing the A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language. modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of A ``Secondary Section'' is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly (or to related matters) and contains nothing that could fall directly
@ -2252,15 +2255,15 @@ connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding commercial, philosophical, ethical or political position regarding
them. them.
The "Invariant Sections" are certain Secondary Sections whose titles The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. that says that the Document is released under this License.
The "Cover Texts" are certain short passages of text that are listed, 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 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. the Document is released under this License.
A "Transparent" copy of the Document means a machine-readable copy, A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of straightforwardly with generic text editors or (for images composed of
@ -2270,7 +2273,7 @@ for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file to text formatters. A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy that is subsequent modification by readers is not Transparent. A copy that is
not "Transparent" is called "Opaque". not ``Transparent'' is called ``Opaque.''
Examples of suitable formats for Transparent copies include plain Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML ASCII without markup, Texinfo input format, LaTeX input format, SGML
@ -2282,15 +2285,15 @@ processing tools are not generally available, and the
machine-generated HTML produced by some word processors for output machine-generated HTML produced by some word processors for output
purposes only. purposes only.
The "Title Page" means, for a printed book, the title page itself, The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in 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 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, the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text. preceding the beginning of the body of the text.
@sp 1
@item
2. VERBATIM COPYING VERBATIM COPYING
You may copy and distribute the Document in any medium, either You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the commercially or noncommercially, provided that this License, the
@ -2304,9 +2307,9 @@ number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and You may also lend copies, under the same conditions stated above, and
you may publicly display copies. you may publicly display copies.
@sp 1
@item
3. COPYING IN QUANTITY COPYING IN QUANTITY
If you publish printed copies of the Document numbering more than 100, If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose and the Document's license notice requires Cover Texts, you must enclose
@ -2342,9 +2345,9 @@ the public.
It is requested, but not required, that you contact the authors of the It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document. them a chance to provide you with an updated version of the Document.
@sp 1
@item
4. MODIFICATIONS MODIFICATIONS
You may copy and distribute a Modified Version of the Document under 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 conditions of sections 2 and 3 above, provided that you release
@ -2357,48 +2360,48 @@ A. 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 from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section (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 of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission. if the original publisher of that version gives permission.@*
B. List on the Title Page, as authors, one or more persons or entities B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has less than five). Document (all of its principal authors, if it has less than five).@*
C. State on the Title page the name of the publisher of the C. State on the Title page the name of the publisher of the
Modified Version, as the publisher. Modified Version, as the publisher.@*
D. Preserve all the copyright notices of the Document. D. Preserve all the copyright notices of the Document.@*
E. Add an appropriate copyright notice for your modifications E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices. adjacent to the other copyright notices.@*
F. Include, immediately after the copyright notices, a license notice F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below. terms of this License, in the form shown in the Addendum below.@*
G. Preserve in that license notice the full lists of Invariant Sections G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice. and required Cover Texts given in the Document's license notice.@*
H. Include an unaltered copy of this License. H. Include an unaltered copy of this License.@*
I. Preserve the section entitled "History", and its title, and add to I. Preserve the section entitled ``History'', and its title, and add to
it an item stating at least the title, year, new authors, and it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If publisher of the Modified Version as given on the Title Page. If
there is no section entitled "History" in the Document, create one there is no section entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence. Version as stated in the previous sentence.@*
J. Preserve the network location, if any, given in the Document for J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions the network locations given in the Document for previous versions
it was based on. These may be placed in the "History" section. 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 You may omit a network location for a work that was published at
least four years before the Document itself, or if the original least four years before the Document itself, or if the original
publisher of the version it refers to gives permission. publisher of the version it refers to gives permission.@*
K. In any section entitled "Acknowledgements" or "Dedications", K. In any section entitled ``Acknowledgements'' or ``Dedications'',
preserve the section's title, and preserve in the section all the preserve the section's title, and preserve in the section all the
substance and tone of each of the contributor acknowledgements substance and tone of each of the contributor acknowledgements
and/or dedications given therein. and/or dedications given therein.@*
L. Preserve all the Invariant Sections of the Document, L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles. or the equivalent are not considered part of the section titles.@*
M. Delete any section entitled "Endorsements". Such a section M. Delete any section entitled ``Endorsements.'' Such a section
may not be included in the Modified Version. may not be included in the Modified Version.@*
N. Do not retitle any existing section as "Endorsements" N. Do not retitle any existing section as ``Endorsements''
or to conflict in title with any Invariant Section. or to conflict in title with any Invariant Section.@*
@sp 1
If the Modified Version includes new front-matter sections or If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all copied from the Document, you may at your option designate some or all
@ -2406,7 +2409,7 @@ of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice. list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles. These titles must be distinct from any other section titles.
You may add a section entitled "Endorsements", provided it contains You may add a section entitled ``Endorsements'', provided it contains
nothing but endorsements of your Modified Version by various nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a been approved by an organization as the authoritative definition of a
@ -2425,9 +2428,9 @@ permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License 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 give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version. imply endorsement of any Modified Version.
@sp 1
@item
5. COMBINING DOCUMENTS COMBINING DOCUMENTS
You may combine the Document with other documents released under this You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified License, under the terms defined in section 4 above for modified
@ -2445,14 +2448,14 @@ 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 Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work. Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections entitled "History" In the combination, you must combine any sections entitled ``History''
in the various original documents, forming one section entitled in the various original documents, forming one section entitled
"History"; likewise combine any sections entitled "Acknowledgements", ``History''; likewise combine any sections entitled ``Acknowledgements'',
and any sections entitled "Dedications". You must delete all sections and any sections entitled ``Dedications.'' You must delete all sections
entitled "Endorsements." entitled ``Endorsements.''
@sp 1
@item
6. COLLECTIONS OF DOCUMENTS COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this released under this License, and replace the individual copies of this
@ -2464,15 +2467,15 @@ You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document. other respects regarding verbatim copying of that document.
@sp 1
@item
7. AGGREGATION WITH INDEPENDENT WORKS AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate 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 and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the of the Document, provided no compilation copyright is claimed for the
compilation. Such a compilation is called an "aggregate", and this compilation. Such a compilation is called an ``aggregate'', and this
License does not apply to the other self-contained works thus compiled License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document. are not themselves derivative works of the Document.
@ -2482,9 +2485,9 @@ copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate. covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate. Otherwise they must appear on covers around the whole aggregate.
@sp 1
@item
8. TRANSLATION TRANSLATION
Translation is considered a kind of modification, so you may Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4. distribute translations of the Document under the terms of section 4.
@ -2496,9 +2499,9 @@ translation of this License provided that you also include the
original English version of this License. In case of a disagreement original English version of this License. In case of a disagreement
between the translation and the original English version of this between the translation and the original English version of this
License, the original English version will prevail. License, the original English version will prevail.
@sp 1
@item
9. TERMINATION TERMINATION
You may not copy, modify, sublicense, or distribute the Document except You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to as expressly provided for under this License. Any other attempt to
@ -2507,9 +2510,9 @@ automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such License will not have their licenses terminated so long as such
parties remain in full compliance. parties remain in full compliance.
@sp 1
@item
10. FUTURE REVISIONS OF THIS LICENSE FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new of the GNU Free Documentation License from time to time. Such new
@ -2519,35 +2522,38 @@ http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or 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 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 Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation. as a draft) by the Free Software Foundation.
@end enumerate
ADDENDUM: How to use this License for your documents @unnumberedsec ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of 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 the License in the document and put the following copyright and
license notices just after the title page: license notices just after the title page:
@smallexample @smallexample
Copyright (c) YEAR YOUR NAME. @group
Permission is granted to copy, distribute and/or modify this document Copyright (C) @var{year} @var{your name}.
under the terms of the GNU Free Documentation License, Version 1.1 Permission is granted to copy, distribute and/or modify this document
or any later version published by the Free Software Foundation; under the terms of the GNU Free Documentation License, Version 1.1
with the Invariant Sections being LIST THEIR TITLES, with the or any later version published by the Free Software Foundation;
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. with the Invariant Sections being @var{list their titles}, with the
A copy of the license is included in the section entitled "GNU Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
Free Documentation License". A copy of the license is included in the section entitled "GNU
Free Documentation License."
@end group
@end smallexample @end smallexample
If you have no Invariant Sections, write "with no Invariant Sections" If you have no Invariant Sections, write ``with no Invariant Sections''
instead of saying which ones are invariant. If you have no instead of saying which ones are invariant. If you have no
Front-Cover Texts, write "no Front-Cover Texts" instead of Front-Cover Texts, write ``no Front-Cover Texts'' instead of
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts. ``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
If your document contains nontrivial examples of program code, we If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of recommend releasing these examples in parallel under your choice of