daily update
[binutils.git] / gprof / gprof.texi
bloba81b109ec5236f067c4e015fb4f675b2ffef54ff
1 \input texinfo @c -*-texinfo-*-
2 @setfilename gprof.info
3 @c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001, 2002, 2003, 2004
4 @c Free Software Foundation, Inc.
5 @settitle GNU gprof
6 @setchapternewpage odd
8 @ifinfo
9 @c This is a dir.info fragment to support semi-automated addition of
10 @c manuals to an info tree.  zoo@cygnus.com is developing this facility.
11 @format
12 START-INFO-DIR-ENTRY
13 * gprof: (gprof).                Profiling your program's execution
14 END-INFO-DIR-ENTRY
15 @end format
16 @end ifinfo
18 @ifinfo
19 This file documents the gprof profiler of the GNU system.
21 @c man begin COPYRIGHT
22 Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001, 2003 Free Software Foundation, Inc.
24 Permission is granted to copy, distribute and/or modify this document
25 under the terms of the GNU Free Documentation License, Version 1.1
26 or any later version published by the Free Software Foundation;
27 with no Invariant Sections, with no Front-Cover Texts, and with no
28 Back-Cover Texts.  A copy of the license is included in the
29 section entitled "GNU Free Documentation License".
31 @c man end
33 @ignore
34 Permission is granted to process this file through Tex and print the
35 results, provided the printed document carries copying permission
36 notice identical to this one except for the removal of this paragraph
37 (this paragraph not being relevant to the printed manual).
39 @end ignore
40 @end ifinfo
42 @finalout
43 @smallbook
45 @titlepage
46 @title GNU gprof
47 @subtitle The @sc{gnu} Profiler 
48 @author Jay Fenlason and Richard Stallman
50 @page
52 This manual describes the @sc{gnu} profiler, @code{gprof}, and how you
53 can use it to determine which parts of a program are taking most of the
54 execution time.  We assume that you know how to write, compile, and
55 execute programs.  @sc{gnu} @code{gprof} was written by Jay Fenlason.
56 Eric S. Raymond made some minor corrections and additions in 2003.
58 @vskip 0pt plus 1filll
59 Copyright @copyright{} 1988, 92, 97, 98, 99, 2000, 2003 Free Software Foundation, Inc.
61       Permission is granted to copy, distribute and/or modify this document
62       under the terms of the GNU Free Documentation License, Version 1.1
63       or any later version published by the Free Software Foundation;
64       with no Invariant Sections, with no Front-Cover Texts, and with no
65       Back-Cover Texts.  A copy of the license is included in the
66       section entitled "GNU Free Documentation License".
68 @end titlepage
70 @ifnottex
71 @node Top
72 @top Profiling a Program: Where Does It Spend Its Time?
74 This manual describes the @sc{gnu} profiler, @code{gprof}, and how you
75 can use it to determine which parts of a program are taking most of the
76 execution time.  We assume that you know how to write, compile, and
77 execute programs.  @sc{gnu} @code{gprof} was written by Jay Fenlason.
79 This document is distributed under the terms of the GNU Free
80 Documentation License.  A copy of the license is included in the
81 section entitled "GNU Free Documentation License".
83 @menu
84 * Introduction::        What profiling means, and why it is useful.
86 * Compiling::           How to compile your program for profiling.
87 * Executing::           Executing your program to generate profile data
88 * Invoking::            How to run @code{gprof}, and its options
90 * Output::              Interpreting @code{gprof}'s output
92 * Inaccuracy::          Potential problems you should be aware of
93 * How do I?::           Answers to common questions
94 * Incompatibilities::   (between @sc{gnu} @code{gprof} and Unix @code{gprof}.)
95 * Details::             Details of how profiling is done
96 * GNU Free Documentation License::  GNU Free Documentation License
97 @end menu
98 @end ifnottex
100 @node Introduction
101 @chapter Introduction to Profiling
103 @ifset man
104 @c man title gprof display call graph profile data
106 @smallexample
107 @c man begin SYNOPSIS
108 gprof [ -[abcDhilLrsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ] 
109  [ -I @var{dirs} ] [ -d[@var{num}] ] [ -k @var{from/to} ]
110  [ -m @var{min-count} ] [ -R @var{map_file} ] [ -t @var{table-length} ]
111  [ --[no-]annotated-source[=@var{name}] ] 
112  [ --[no-]exec-counts[=@var{name}] ]
113  [ --[no-]flat-profile[=@var{name}] ] [ --[no-]graph[=@var{name}] ]
114  [ --[no-]time=@var{name}] [ --all-lines ] [ --brief ] 
115  [ --debug[=@var{level}] ] [ --function-ordering ] 
116  [ --file-ordering ] [ --directory-path=@var{dirs} ]
117  [ --display-unused-functions ] [ --file-format=@var{name} ]
118  [ --file-info ] [ --help ] [ --line ] [ --min-count=@var{n} ]
119  [ --no-static ] [ --print-path ] [ --separate-files ]
120  [ --static-call-graph ] [ --sum ] [ --table-length=@var{len} ]
121  [ --traditional ] [ --version ] [ --width=@var{n} ]
122  [ --ignore-non-functions ] [ --demangle[=@var{STYLE}] ]
123  [ --no-demangle ] [ @var{image-file} ] [ @var{profile-file} @dots{} ]
124 @c man end
125 @end smallexample
127 @c man begin DESCRIPTION
128 @code{gprof} produces an execution profile of C, Pascal, or Fortran77 
129 programs.  The effect of called routines is incorporated in the profile 
130 of each caller.  The profile data is taken from the call graph profile file
131 (@file{gmon.out} default) which is created by programs
132 that are compiled with the @samp{-pg} option of
133 @code{cc}, @code{pc}, and @code{f77}.
134 The @samp{-pg} option also links in versions of the library routines
135 that are compiled for profiling.  @code{Gprof} reads the given object 
136 file (the default is @code{a.out}) and establishes the relation between
137 its symbol table and the call graph profile from @file{gmon.out}.
138 If more than one profile file is specified, the @code{gprof}
139 output shows the sum of the profile information in the given profile files.
141 @code{Gprof} calculates the amount of time spent in each routine.
142 Next, these times are propagated along the edges of the call graph.
143 Cycles are discovered, and calls into a cycle are made to share the time
144 of the cycle.
146 @c man end
148 @c man begin BUGS
149 The granularity of the sampling is shown, but remains
150 statistical at best.
151 We assume that the time for each execution of a function
152 can be expressed by the total time for the function divided
153 by the number of times the function is called.
154 Thus the time propagated along the call graph arcs to the function's
155 parents is directly proportional to the number of times that
156 arc is traversed.
158 Parents that are not themselves profiled will have the time of
159 their profiled children propagated to them, but they will appear
160 to be spontaneously invoked in the call graph listing, and will
161 not have their time propagated further.
162 Similarly, signal catchers, even though profiled, will appear
163 to be spontaneous (although for more obscure reasons).
164 Any profiled children of signal catchers should have their times
165 propagated properly, unless the signal catcher was invoked during
166 the execution of the profiling routine, in which case all is lost.
168 The profiled program must call @code{exit}(2)
169 or return normally for the profiling information to be saved
170 in the @file{gmon.out} file.
171 @c man end
173 @c man begin FILES
174 @table @code
175 @item @file{a.out}
176 the namelist and text space.
177 @item @file{gmon.out}
178 dynamic call graph and profile.
179 @item @file{gmon.sum}
180 summarized dynamic call graph and profile.  
181 @end table
182 @c man end
184 @c man begin SEEALSO
185 monitor(3), profil(2), cc(1), prof(1), and the Info entry for @file{gprof}.
187 ``An Execution Profiler for Modular Programs'',
188 by S. Graham, P. Kessler, M. McKusick;
189 Software - Practice and Experience,
190 Vol. 13, pp. 671-685, 1983.
192 ``gprof: A Call Graph Execution Profiler'',
193 by S. Graham, P. Kessler, M. McKusick;
194 Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
195 SIGPLAN Notices, Vol. 17, No  6, pp. 120-126, June 1982.
196 @c man end
197 @end ifset
199 Profiling allows you to learn where your program spent its time and which
200 functions called which other functions while it was executing.  This
201 information can show you which pieces of your program are slower than you
202 expected, and might be candidates for rewriting to make your program
203 execute faster.  It can also tell you which functions are being called more
204 or less often than you expected.  This may help you spot bugs that had
205 otherwise been unnoticed.
207 Since the profiler uses information collected during the actual execution
208 of your program, it can be used on programs that are too large or too
209 complex to analyze by reading the source.  However, how your program is run
210 will affect the information that shows up in the profile data.  If you
211 don't use some feature of your program while it is being profiled, no
212 profile information will be generated for that feature.
214 Profiling has several steps:
216 @itemize @bullet
217 @item
218 You must compile and link your program with profiling enabled.
219 @xref{Compiling}.
221 @item
222 You must execute your program to generate a profile data file.
223 @xref{Executing}.
225 @item
226 You must run @code{gprof} to analyze the profile data.
227 @xref{Invoking}.
228 @end itemize
230 The next three chapters explain these steps in greater detail.
232 @c man begin DESCRIPTION
234 Several forms of output are available from the analysis.
236 The @dfn{flat profile} shows how much time your program spent in each function,
237 and how many times that function was called.  If you simply want to know
238 which functions burn most of the cycles, it is stated concisely here.
239 @xref{Flat Profile}.
241 The @dfn{call graph} shows, for each function, which functions called it, which
242 other functions it called, and how many times.  There is also an estimate
243 of how much time was spent in the subroutines of each function.  This can
244 suggest places where you might try to eliminate function calls that use a
245 lot of time.  @xref{Call Graph}.
247 The @dfn{annotated source} listing is a copy of the program's
248 source code, labeled with the number of times each line of the
249 program was executed.  @xref{Annotated Source}.
250 @c man end
252 To better understand how profiling works, you may wish to read
253 a description of its implementation.
254 @xref{Implementation}.
256 @node Compiling
257 @chapter Compiling a Program for Profiling
259 The first step in generating profile information for your program is
260 to compile and link it with profiling enabled.
262 To compile a source file for profiling, specify the @samp{-pg} option when
263 you run the compiler.  (This is in addition to the options you normally
264 use.)
266 To link the program for profiling, if you use a compiler such as @code{cc}
267 to do the linking, simply specify @samp{-pg} in addition to your usual
268 options.  The same option, @samp{-pg}, alters either compilation or linking
269 to do what is necessary for profiling.  Here are examples:
271 @example
272 cc -g -c myprog.c utils.c -pg
273 cc -o myprog myprog.o utils.o -pg
274 @end example
276 The @samp{-pg} option also works with a command that both compiles and links:
278 @example
279 cc -o myprog myprog.c utils.c -g -pg
280 @end example
282 Note: The @samp{-pg} option must be part of your compilation options
283 as well as your link options.  If it is not then no call-graph data
284 will be gathered and when you run @code{gprof} you will get an error
285 message like this:
287 @example
288 gprof: gmon.out file is missing call-graph data
289 @end example
291 If you add the @samp{-Q} switch to suppress the printing of the call
292 graph data you will still be able to see the time samples:
294 @example
295 Flat profile:
297 Each sample counts as 0.01 seconds.
298   %   cumulative   self              self     total           
299  time   seconds   seconds    calls  Ts/call  Ts/call  name    
300  44.12      0.07     0.07                             zazLoop
301  35.29      0.14     0.06                             main
302  20.59      0.17     0.04                             bazMillion
304  %         the percentage of the total running time of the
305 @end example
307 If you run the linker @code{ld} directly instead of through a compiler
308 such as @code{cc}, you may have to specify a profiling startup file
309 @file{gcrt0.o} as the first input file instead of the usual startup
310 file @file{crt0.o}.  In addition, you would probably want to
311 specify the profiling C library, @file{libc_p.a}, by writing
312 @samp{-lc_p} instead of the usual @samp{-lc}.  This is not absolutely
313 necessary, but doing this gives you number-of-calls information for
314 standard library functions such as @code{read} and @code{open}.  For
315 example:
317 @example
318 ld -o myprog /lib/gcrt0.o myprog.o utils.o -lc_p
319 @end example
321 If you compile only some of the modules of the program with @samp{-pg}, you
322 can still profile the program, but you won't get complete information about
323 the modules that were compiled without @samp{-pg}.  The only information
324 you get for the functions in those modules is the total time spent in them;
325 there is no record of how many times they were called, or from where.  This
326 will not affect the flat profile (except that the @code{calls} field for
327 the functions will be blank), but will greatly reduce the usefulness of the
328 call graph.
330 If you wish to perform line-by-line profiling,
331 you will also need to specify the @samp{-g} option,
332 instructing the compiler to insert debugging symbols into the program
333 that match program addresses to source code lines.
334 @xref{Line-by-line}.
336 In addition to the @samp{-pg} and @samp{-g} options, older versions of
337 GCC required you to specify the @samp{-a} option when compiling in
338 order to instrument it to perform basic-block counting.  Newer
339 versions do not require this option and will not accept it;
340 basic-block counting is always enabled when @samp{-pg} is on.
342 When basic-block counting is enabled, as the program runs
343 it will count how many times it executed each branch of each @samp{if}
344 statement, each iteration of each @samp{do} loop, etc.  This will
345 enable @code{gprof} to construct an annotated source code
346 listing showing how many times each line of code was executed.
348 It also worth noting that GCC supports a different profiling method
349 which is enabled by the @samp{-fprofile-arcs}, @samp{-ftest-coverage}
350 and @samp{-fprofile-values} switches. These switches do not produce
351 data which is useful to @code{gprof} however, so they are not
352 discussed further here.  There is also the
353 @samp{-finstrument-functions} switch which will cause GCC to insert
354 calls to special user supplied instrumentation routines at the entry
355 and exit of every function in their program.  This can be used to
356 implement an alternative profiling scheme.
358 @node Executing
359 @chapter Executing the Program
361 Once the program is compiled for profiling, you must run it in order to
362 generate the information that @code{gprof} needs.  Simply run the program
363 as usual, using the normal arguments, file names, etc.  The program should
364 run normally, producing the same output as usual.  It will, however, run
365 somewhat slower than normal because of the time spent collecting and the
366 writing the profile data.
368 The way you run the program---the arguments and input that you give
369 it---may have a dramatic effect on what the profile information shows.  The
370 profile data will describe the parts of the program that were activated for
371 the particular input you use.  For example, if the first command you give
372 to your program is to quit, the profile data will show the time used in
373 initialization and in cleanup, but not much else.
375 Your program will write the profile data into a file called @file{gmon.out}
376 just before exiting.  If there is already a file called @file{gmon.out},
377 its contents are overwritten.  There is currently no way to tell the
378 program to write the profile data under a different name, but you can rename
379 the file afterwards if you are concerned that it may be overwritten.
381 In order to write the @file{gmon.out} file properly, your program must exit
382 normally: by returning from @code{main} or by calling @code{exit}.  Calling
383 the low-level function @code{_exit} does not write the profile data, and
384 neither does abnormal termination due to an unhandled signal.
386 The @file{gmon.out} file is written in the program's @emph{current working
387 directory} at the time it exits.  This means that if your program calls
388 @code{chdir}, the @file{gmon.out} file will be left in the last directory
389 your program @code{chdir}'d to.  If you don't have permission to write in
390 this directory, the file is not written, and you will get an error message.
392 Older versions of the @sc{gnu} profiling library may also write a file
393 called @file{bb.out}.  This file, if present, contains an human-readable
394 listing of the basic-block execution counts.  Unfortunately, the
395 appearance of a human-readable @file{bb.out} means the basic-block
396 counts didn't get written into @file{gmon.out}.
397 The Perl script @code{bbconv.pl}, included with the @code{gprof}
398 source distribution, will convert a @file{bb.out} file into
399 a format readable by @code{gprof}.  Invoke it like this:
401 @smallexample
402 bbconv.pl < bb.out > @var{bh-data}
403 @end smallexample
405 This translates the information in @file{bb.out} into a form that
406 @code{gprof} can understand.  But you still need to tell @code{gprof}
407 about the existence of this translated information.  To do that, include
408 @var{bb-data} on the @code{gprof} command line, @emph{along with
409 @file{gmon.out}}, like this:
411 @smallexample
412 gprof @var{options} @var{executable-file} gmon.out @var{bb-data} [@var{yet-more-profile-data-files}@dots{}] [> @var{outfile}]
413 @end smallexample
415 @node Invoking
416 @chapter @code{gprof} Command Summary
418 After you have a profile data file @file{gmon.out}, you can run @code{gprof}
419 to interpret the information in it.  The @code{gprof} program prints a
420 flat profile and a call graph on standard output.  Typically you would
421 redirect the output of @code{gprof} into a file with @samp{>}.
423 You run @code{gprof} like this:
425 @smallexample
426 gprof @var{options} [@var{executable-file} [@var{profile-data-files}@dots{}]] [> @var{outfile}]
427 @end smallexample
429 @noindent
430 Here square-brackets indicate optional arguments.
432 If you omit the executable file name, the file @file{a.out} is used.  If
433 you give no profile data file name, the file @file{gmon.out} is used.  If
434 any file is not in the proper format, or if the profile data file does not
435 appear to belong to the executable file, an error message is printed.
437 You can give more than one profile data file by entering all their names
438 after the executable file name; then the statistics in all the data files
439 are summed together.
441 The order of these options does not matter.
443 @menu
444 * Output Options::      Controlling @code{gprof}'s output style
445 * Analysis Options::    Controlling how @code{gprof} analyses its data
446 * Miscellaneous Options::
447 * Deprecated Options::  Options you no longer need to use, but which
448                             have been retained for compatibility
449 * Symspecs::            Specifying functions to include or exclude
450 @end menu
452 @node Output Options,Analysis Options,,Invoking
453 @section Output Options
455 @c man begin OPTIONS
456 These options specify which of several output formats
457 @code{gprof} should produce.
459 Many of these options take an optional @dfn{symspec} to specify
460 functions to be included or excluded.  These options can be
461 specified multiple times, with different symspecs, to include
462 or exclude sets of symbols.  @xref{Symspecs}.
464 Specifying any of these options overrides the default (@samp{-p -q}),
465 which prints a flat profile and call graph analysis
466 for all functions.
468 @table @code
470 @item -A[@var{symspec}]
471 @itemx --annotated-source[=@var{symspec}]
472 The @samp{-A} option causes @code{gprof} to print annotated source code.
473 If @var{symspec} is specified, print output only for matching symbols.
474 @xref{Annotated Source}.
476 @item -b
477 @itemx --brief
478 If the @samp{-b} option is given, @code{gprof} doesn't print the
479 verbose blurbs that try to explain the meaning of all of the fields in
480 the tables.  This is useful if you intend to print out the output, or
481 are tired of seeing the blurbs.
483 @item -C[@var{symspec}]
484 @itemx --exec-counts[=@var{symspec}]
485 The @samp{-C} option causes @code{gprof} to
486 print a tally of functions and the number of times each was called.
487 If @var{symspec} is specified, print tally only for matching symbols.
489 If the profile data file contains basic-block count records, specifying
490 the @samp{-l} option, along with @samp{-C}, will cause basic-block
491 execution counts to be tallied and displayed.
493 @item -i
494 @itemx --file-info
495 The @samp{-i} option causes @code{gprof} to display summary information
496 about the profile data file(s) and then exit.  The number of histogram,
497 call graph, and basic-block count records is displayed.
499 @item -I @var{dirs}
500 @itemx --directory-path=@var{dirs}
501 The @samp{-I} option specifies a list of search directories in
502 which to find source files.  Environment variable @var{GPROF_PATH}
503 can also be used to convey this information.
504 Used mostly for annotated source output.
506 @item -J[@var{symspec}]
507 @itemx --no-annotated-source[=@var{symspec}]
508 The @samp{-J} option causes @code{gprof} not to
509 print annotated source code.
510 If @var{symspec} is specified, @code{gprof} prints annotated source,
511 but excludes matching symbols.
513 @item -L
514 @itemx --print-path
515 Normally, source filenames are printed with the path
516 component suppressed.  The @samp{-L} option causes @code{gprof}
517 to print the full pathname of
518 source filenames, which is determined
519 from symbolic debugging information in the image file
520 and is relative to the directory in which the compiler
521 was invoked.
523 @item -p[@var{symspec}]
524 @itemx --flat-profile[=@var{symspec}]
525 The @samp{-p} option causes @code{gprof} to print a flat profile.
526 If @var{symspec} is specified, print flat profile only for matching symbols.
527 @xref{Flat Profile}.
529 @item -P[@var{symspec}]
530 @itemx --no-flat-profile[=@var{symspec}]
531 The @samp{-P} option causes @code{gprof} to suppress printing a flat profile.
532 If @var{symspec} is specified, @code{gprof} prints a flat profile,
533 but excludes matching symbols.
535 @item -q[@var{symspec}]
536 @itemx --graph[=@var{symspec}]
537 The @samp{-q} option causes @code{gprof} to print the call graph analysis.
538 If @var{symspec} is specified, print call graph only for matching symbols
539 and their children.
540 @xref{Call Graph}.
542 @item -Q[@var{symspec}]
543 @itemx --no-graph[=@var{symspec}]
544 The @samp{-Q} option causes @code{gprof} to suppress printing the
545 call graph.
546 If @var{symspec} is specified, @code{gprof} prints a call graph,
547 but excludes matching symbols.
549 @item -t
550 @itemx --table-length=@var{num}
551 The @samp{-t} option causes the @var{num} most active source lines in
552 each source file to be listed when source annotation is enabled.  The
553 default is 10.
555 @item -y
556 @itemx --separate-files
557 This option affects annotated source output only.
558 Normally, @code{gprof} prints annotated source files
559 to standard-output.  If this option is specified,
560 annotated source for a file named @file{path/@var{filename}}
561 is generated in the file @file{@var{filename}-ann}.  If the underlying
562 filesystem would truncate @file{@var{filename}-ann} so that it
563 overwrites the original @file{@var{filename}}, @code{gprof} generates
564 annotated source in the file @file{@var{filename}.ann} instead (if the
565 original file name has an extension, that extension is @emph{replaced}
566 with @file{.ann}).
568 @item -Z[@var{symspec}]
569 @itemx --no-exec-counts[=@var{symspec}]
570 The @samp{-Z} option causes @code{gprof} not to
571 print a tally of functions and the number of times each was called.
572 If @var{symspec} is specified, print tally, but exclude matching symbols.
574 @item -r
575 @itemx --function-ordering
576 The @samp{--function-ordering} option causes @code{gprof} to print a
577 suggested function ordering for the program based on profiling data.
578 This option suggests an ordering which may improve paging, tlb and
579 cache behavior for the program on systems which support arbitrary
580 ordering of functions in an executable.
582 The exact details of how to force the linker to place functions
583 in a particular order is system dependent and out of the scope of this
584 manual.
586 @item -R @var{map_file}
587 @itemx --file-ordering @var{map_file}
588 The @samp{--file-ordering} option causes @code{gprof} to print a
589 suggested .o link line ordering for the program based on profiling data.
590 This option suggests an ordering which may improve paging, tlb and
591 cache behavior for the program on systems which do not support arbitrary
592 ordering of functions in an executable.
594 Use of the @samp{-a} argument is highly recommended with this option.
596 The @var{map_file} argument is a pathname to a file which provides
597 function name to object file mappings.  The format of the file is similar to
598 the output of the program @code{nm}.
600 @smallexample
601 @group
602 c-parse.o:00000000 T yyparse
603 c-parse.o:00000004 C yyerrflag
604 c-lang.o:00000000 T maybe_objc_method_name
605 c-lang.o:00000000 T print_lang_statistics
606 c-lang.o:00000000 T recognize_objc_keyword
607 c-decl.o:00000000 T print_lang_identifier
608 c-decl.o:00000000 T print_lang_type
609 @dots{}
611 @end group
612 @end smallexample
614 To create a @var{map_file} with @sc{gnu} @code{nm}, type a command like
615 @kbd{nm --extern-only --defined-only -v --print-file-name program-name}.
617 @item -T
618 @itemx --traditional
619 The @samp{-T} option causes @code{gprof} to print its output in
620 ``traditional'' BSD style.
622 @item -w @var{width}
623 @itemx --width=@var{width}
624 Sets width of output lines to @var{width}.
625 Currently only used when printing the function index at the bottom
626 of the call graph.
628 @item -x
629 @itemx --all-lines
630 This option affects annotated source output only.
631 By default, only the lines at the beginning of a basic-block
632 are annotated.  If this option is specified, every line in
633 a basic-block is annotated by repeating the annotation for the
634 first line.  This behavior is similar to @code{tcov}'s @samp{-a}.
636 @item --demangle[=@var{style}]
637 @itemx --no-demangle
638 These options control whether C++ symbol names should be demangled when
639 printing output.  The default is to demangle symbols.  The
640 @code{--no-demangle} option may be used to turn off demangling. Different 
641 compilers have different mangling styles.  The optional demangling style 
642 argument can be used to choose an appropriate demangling style for your 
643 compiler.
644 @end table
646 @node Analysis Options,Miscellaneous Options,Output Options,Invoking
647 @section Analysis Options
649 @table @code
651 @item -a
652 @itemx --no-static
653 The @samp{-a} option causes @code{gprof} to suppress the printing of
654 statically declared (private) functions.  (These are functions whose
655 names are not listed as global, and which are not visible outside the
656 file/function/block where they were defined.)  Time spent in these
657 functions, calls to/from them, etc, will all be attributed to the
658 function that was loaded directly before it in the executable file.
659 @c This is compatible with Unix @code{gprof}, but a bad idea.  
660 This option affects both the flat profile and the call graph.
662 @item -c
663 @itemx --static-call-graph
664 The @samp{-c} option causes the call graph of the program to be
665 augmented by a heuristic which examines the text space of the object
666 file and identifies function calls in the binary machine code.
667 Since normal call graph records are only generated when functions are
668 entered, this option identifies children that could have been called,
669 but never were.  Calls to functions that were not compiled with
670 profiling enabled are also identified, but only if symbol table
671 entries are present for them.
672 Calls to dynamic library routines are typically @emph{not} found
673 by this option.
674 Parents or children identified via this heuristic
675 are indicated in the call graph with call counts of @samp{0}.
677 @item -D
678 @itemx --ignore-non-functions
679 The @samp{-D} option causes @code{gprof} to ignore symbols which
680 are not known to be functions.  This option will give more accurate
681 profile data on systems where it is supported (Solaris and HPUX for
682 example).
684 @item -k @var{from}/@var{to}
685 The @samp{-k} option allows you to delete from the call graph any arcs from
686 symbols matching symspec @var{from} to those matching symspec @var{to}.
688 @item -l
689 @itemx --line
690 The @samp{-l} option enables line-by-line profiling, which causes
691 histogram hits to be charged to individual source code lines,
692 instead of functions.
693 If the program was compiled with basic-block counting enabled,
694 this option will also identify how many times each line of
695 code was executed.
696 While line-by-line profiling can help isolate where in a large function
697 a program is spending its time, it also significantly increases
698 the running time of @code{gprof}, and magnifies statistical
699 inaccuracies.
700 @xref{Sampling Error}.
702 @item -m @var{num}
703 @itemx --min-count=@var{num}
704 This option affects execution count output only.
705 Symbols that are executed less than @var{num} times are suppressed.
707 @item -n[@var{symspec}]
708 @itemx --time[=@var{symspec}]
709 The @samp{-n} option causes @code{gprof}, in its call graph analysis,
710 to only propagate times for symbols matching @var{symspec}.
712 @item -N[@var{symspec}]
713 @itemx --no-time[=@var{symspec}]
714 The @samp{-n} option causes @code{gprof}, in its call graph analysis,
715 not to propagate times for symbols matching @var{symspec}.
717 @item -z
718 @itemx --display-unused-functions
719 If you give the @samp{-z} option, @code{gprof} will mention all
720 functions in the flat profile, even those that were never called, and
721 that had no time spent in them.  This is useful in conjunction with the
722 @samp{-c} option for discovering which routines were never called.
724 @end table
726 @node Miscellaneous Options,Deprecated Options,Analysis Options,Invoking
727 @section Miscellaneous Options
729 @table @code
731 @item -d[@var{num}]
732 @itemx --debug[=@var{num}]
733 The @samp{-d @var{num}} option specifies debugging options.
734 If @var{num} is not specified, enable all debugging.
735 @xref{Debugging}.
737 @item -h
738 @itemx --help
739 The @samp{-h} option prints command line usage.
741 @item -O@var{name}
742 @itemx --file-format=@var{name}
743 Selects the format of the profile data files.  Recognized formats are
744 @samp{auto} (the default), @samp{bsd}, @samp{4.4bsd}, @samp{magic}, and
745 @samp{prof} (not yet supported).
747 @item -s
748 @itemx --sum
749 The @samp{-s} option causes @code{gprof} to summarize the information
750 in the profile data files it read in, and write out a profile data
751 file called @file{gmon.sum}, which contains all the information from
752 the profile data files that @code{gprof} read in.  The file @file{gmon.sum}
753 may be one of the specified input files; the effect of this is to
754 merge the data in the other input files into @file{gmon.sum}.
756 Eventually you can run @code{gprof} again without @samp{-s} to analyze the
757 cumulative data in the file @file{gmon.sum}.
759 @item -v
760 @itemx --version
761 The @samp{-v} flag causes @code{gprof} to print the current version
762 number, and then exit.
764 @end table
766 @node Deprecated Options,Symspecs,Miscellaneous Options,Invoking
767 @section Deprecated Options
769 @table @code
771 These options have been replaced with newer versions that use symspecs.
773 @item -e @var{function_name}
774 The @samp{-e @var{function}} option tells @code{gprof} to not print
775 information about the function @var{function_name} (and its
776 children@dots{}) in the call graph.  The function will still be listed
777 as a child of any functions that call it, but its index number will be
778 shown as @samp{[not printed]}.  More than one @samp{-e} option may be
779 given; only one @var{function_name} may be indicated with each @samp{-e}
780 option. 
782 @item -E @var{function_name}
783 The @code{-E @var{function}} option works like the @code{-e} option, but
784 time spent in the function (and children who were not called from
785 anywhere else), will not be used to compute the percentages-of-time for
786 the call graph.  More than one @samp{-E} option may be given; only one
787 @var{function_name} may be indicated with each @samp{-E} option.
789 @item -f @var{function_name}
790 The @samp{-f @var{function}} option causes @code{gprof} to limit the
791 call graph to the function @var{function_name} and its children (and
792 their children@dots{}).  More than one @samp{-f} option may be given;
793 only one @var{function_name} may be indicated with each @samp{-f}
794 option.  
796 @item -F @var{function_name}
797 The @samp{-F @var{function}} option works like the @code{-f} option, but
798 only time spent in the function and its children (and their
799 children@dots{}) will be used to determine total-time and
800 percentages-of-time for the call graph.  More than one @samp{-F} option
801 may be given; only one @var{function_name} may be indicated with each
802 @samp{-F} option.  The @samp{-F} option overrides the @samp{-E} option.
804 @end table
806 @c man end
808 Note that only one function can be specified with each @code{-e},
809 @code{-E}, @code{-f} or @code{-F} option.  To specify more than one
810 function, use multiple options.  For example, this command:
812 @example
813 gprof -e boring -f foo -f bar myprogram > gprof.output
814 @end example
816 @noindent
817 lists in the call graph all functions that were reached from either
818 @code{foo} or @code{bar} and were not reachable from @code{boring}.
820 @node Symspecs,,Deprecated Options,Invoking
821 @section Symspecs
823 Many of the output options allow functions to be included or excluded
824 using @dfn{symspecs} (symbol specifications), which observe the
825 following syntax:
827 @example
828   filename_containing_a_dot
829 | funcname_not_containing_a_dot
830 | linenumber
831 | ( [ any_filename ] `:' ( any_funcname | linenumber ) )
832 @end example
834 Here are some sample symspecs:
836 @table @samp
837 @item main.c
838 Selects everything in file @file{main.c}---the
839 dot in the string tells @code{gprof} to interpret
840 the string as a filename, rather than as
841 a function name.  To select a file whose
842 name does not contain a dot, a trailing colon
843 should be specified.  For example, @samp{odd:} is
844 interpreted as the file named @file{odd}.
846 @item main
847 Selects all functions named @samp{main}.
849 Note that there may be multiple instances of the same function name
850 because some of the definitions may be local (i.e., static).  Unless a
851 function name is unique in a program, you must use the colon notation
852 explained below to specify a function from a specific source file.
854 Sometimes, function names contain dots.  In such cases, it is necessary
855 to add a leading colon to the name.  For example, @samp{:.mul} selects
856 function @samp{.mul}.
858 In some object file formats, symbols have a leading underscore.
859 @code{gprof} will normally not print these underscores.  When you name a
860 symbol in a symspec, you should type it exactly as @code{gprof} prints
861 it in its output.  For example, if the compiler produces a symbol
862 @samp{_main} from your @code{main} function, @code{gprof} still prints
863 it as @samp{main} in its output, so you should use @samp{main} in
864 symspecs.
866 @item main.c:main
867 Selects function @samp{main} in file @file{main.c}.
869 @item main.c:134
870 Selects line 134 in file @file{main.c}.
871 @end table
873 @node Output
874 @chapter Interpreting @code{gprof}'s Output
876 @code{gprof} can produce several different output styles, the
877 most important of which are described below.  The simplest output
878 styles (file information, execution count, and function and file ordering)
879 are not described here, but are documented with the respective options
880 that trigger them.
881 @xref{Output Options}.
883 @menu
884 * Flat Profile::        The flat profile shows how much time was spent
885                             executing directly in each function.
886 * Call Graph::          The call graph shows which functions called which
887                             others, and how much time each function used
888                             when its subroutine calls are included.
889 * Line-by-line::        @code{gprof} can analyze individual source code lines
890 * Annotated Source::    The annotated source listing displays source code
891                             labeled with execution counts
892 @end menu
895 @node Flat Profile,Call Graph,,Output
896 @section The Flat Profile
897 @cindex flat profile
899 The @dfn{flat profile} shows the total amount of time your program
900 spent executing each function.  Unless the @samp{-z} option is given,
901 functions with no apparent time spent in them, and no apparent calls
902 to them, are not mentioned.  Note that if a function was not compiled
903 for profiling, and didn't run long enough to show up on the program
904 counter histogram, it will be indistinguishable from a function that
905 was never called.
907 This is part of a flat profile for a small program:
909 @smallexample
910 @group
911 Flat profile:
913 Each sample counts as 0.01 seconds.
914   %   cumulative   self              self     total           
915  time   seconds   seconds    calls  ms/call  ms/call  name    
916  33.34      0.02     0.02     7208     0.00     0.00  open
917  16.67      0.03     0.01      244     0.04     0.12  offtime
918  16.67      0.04     0.01        8     1.25     1.25  memccpy
919  16.67      0.05     0.01        7     1.43     1.43  write
920  16.67      0.06     0.01                             mcount
921   0.00      0.06     0.00      236     0.00     0.00  tzset
922   0.00      0.06     0.00      192     0.00     0.00  tolower
923   0.00      0.06     0.00       47     0.00     0.00  strlen
924   0.00      0.06     0.00       45     0.00     0.00  strchr
925   0.00      0.06     0.00        1     0.00    50.00  main
926   0.00      0.06     0.00        1     0.00     0.00  memcpy
927   0.00      0.06     0.00        1     0.00    10.11  print
928   0.00      0.06     0.00        1     0.00     0.00  profil
929   0.00      0.06     0.00        1     0.00    50.00  report
930 @dots{}
931 @end group
932 @end smallexample
934 @noindent
935 The functions are sorted by first by decreasing run-time spent in them,
936 then by decreasing number of calls, then alphabetically by name.  The
937 functions @samp{mcount} and @samp{profil} are part of the profiling
938 apparatus and appear in every flat profile; their time gives a measure of
939 the amount of overhead due to profiling.
941 Just before the column headers, a statement appears indicating
942 how much time each sample counted as.
943 This @dfn{sampling period} estimates the margin of error in each of the time
944 figures.  A time figure that is not much larger than this is not
945 reliable.  In this example, each sample counted as 0.01 seconds,
946 suggesting a 100 Hz sampling rate.
947 The program's total execution time was 0.06
948 seconds, as indicated by the @samp{cumulative seconds} field.  Since
949 each sample counted for 0.01 seconds, this means only six samples
950 were taken during the run.  Two of the samples occurred while the
951 program was in the @samp{open} function, as indicated by the
952 @samp{self seconds} field.  Each of the other four samples
953 occurred one each in @samp{offtime}, @samp{memccpy}, @samp{write},
954 and @samp{mcount}.
955 Since only six samples were taken, none of these values can
956 be regarded as particularly reliable.
957 In another run,
958 the @samp{self seconds} field for
959 @samp{mcount} might well be @samp{0.00} or @samp{0.02}.
960 @xref{Sampling Error}, for a complete discussion.
962 The remaining functions in the listing (those whose
963 @samp{self seconds} field is @samp{0.00}) didn't appear
964 in the histogram samples at all.  However, the call graph
965 indicated that they were called, so therefore they are listed,
966 sorted in decreasing order by the @samp{calls} field.
967 Clearly some time was spent executing these functions,
968 but the paucity of histogram samples prevents any
969 determination of how much time each took.
971 Here is what the fields in each line mean:
973 @table @code
974 @item % time
975 This is the percentage of the total execution time your program spent
976 in this function.  These should all add up to 100%.
978 @item cumulative seconds
979 This is the cumulative total number of seconds the computer spent
980 executing this functions, plus the time spent in all the functions
981 above this one in this table.
983 @item self seconds
984 This is the number of seconds accounted for by this function alone.
985 The flat profile listing is sorted first by this number.
987 @item calls
988 This is the total number of times the function was called.  If the
989 function was never called, or the number of times it was called cannot
990 be determined (probably because the function was not compiled with
991 profiling enabled), the @dfn{calls} field is blank.
993 @item self ms/call
994 This represents the average number of milliseconds spent in this
995 function per call, if this function is profiled.  Otherwise, this field
996 is blank for this function.
998 @item total ms/call
999 This represents the average number of milliseconds spent in this
1000 function and its descendants per call, if this function is profiled.
1001 Otherwise, this field is blank for this function.
1002 This is the only field in the flat profile that uses call graph analysis.
1004 @item name
1005 This is the name of the function.   The flat profile is sorted by this
1006 field alphabetically after the @dfn{self seconds} and @dfn{calls}
1007 fields are sorted.
1008 @end table
1010 @node Call Graph,Line-by-line,Flat Profile,Output
1011 @section The Call Graph
1012 @cindex call graph
1014 The @dfn{call graph} shows how much time was spent in each function
1015 and its children.  From this information, you can find functions that,
1016 while they themselves may not have used much time, called other
1017 functions that did use unusual amounts of time.
1019 Here is a sample call from a small program.  This call came from the
1020 same @code{gprof} run as the flat profile example in the previous
1021 chapter.
1023 @smallexample
1024 @group
1025 granularity: each sample hit covers 2 byte(s) for 20.00% of 0.05 seconds
1027 index % time    self  children    called     name
1028                                                  <spontaneous>
1029 [1]    100.0    0.00    0.05                 start [1]
1030                 0.00    0.05       1/1           main [2]
1031                 0.00    0.00       1/2           on_exit [28]
1032                 0.00    0.00       1/1           exit [59]
1033 -----------------------------------------------
1034                 0.00    0.05       1/1           start [1]
1035 [2]    100.0    0.00    0.05       1         main [2]
1036                 0.00    0.05       1/1           report [3]
1037 -----------------------------------------------
1038                 0.00    0.05       1/1           main [2]
1039 [3]    100.0    0.00    0.05       1         report [3]
1040                 0.00    0.03       8/8           timelocal [6]
1041                 0.00    0.01       1/1           print [9]
1042                 0.00    0.01       9/9           fgets [12]
1043                 0.00    0.00      12/34          strncmp <cycle 1> [40]
1044                 0.00    0.00       8/8           lookup [20]
1045                 0.00    0.00       1/1           fopen [21]
1046                 0.00    0.00       8/8           chewtime [24]
1047                 0.00    0.00       8/16          skipspace [44]
1048 -----------------------------------------------
1049 [4]     59.8    0.01        0.02       8+472     <cycle 2 as a whole>   [4]
1050                 0.01        0.02     244+260         offtime <cycle 2> [7]
1051                 0.00        0.00     236+1           tzset <cycle 2> [26]
1052 -----------------------------------------------
1053 @end group
1054 @end smallexample
1056 The lines full of dashes divide this table into @dfn{entries}, one for each
1057 function.  Each entry has one or more lines.
1059 In each entry, the primary line is the one that starts with an index number
1060 in square brackets.  The end of this line says which function the entry is
1061 for.  The preceding lines in the entry describe the callers of this
1062 function and the following lines describe its subroutines (also called
1063 @dfn{children} when we speak of the call graph).
1065 The entries are sorted by time spent in the function and its subroutines.
1067 The internal profiling function @code{mcount} (@pxref{Flat Profile})
1068 is never mentioned in the call graph.
1070 @menu
1071 * Primary::       Details of the primary line's contents.
1072 * Callers::       Details of caller-lines' contents.
1073 * Subroutines::   Details of subroutine-lines' contents.
1074 * Cycles::        When there are cycles of recursion,
1075                    such as @code{a} calls @code{b} calls @code{a}@dots{}
1076 @end menu
1078 @node Primary
1079 @subsection The Primary Line
1081 The @dfn{primary line} in a call graph entry is the line that
1082 describes the function which the entry is about and gives the overall
1083 statistics for this function.
1085 For reference, we repeat the primary line from the entry for function
1086 @code{report} in our main example, together with the heading line that
1087 shows the names of the fields:
1089 @smallexample
1090 @group
1091 index  % time    self  children called     name
1092 @dots{}
1093 [3]    100.0    0.00    0.05       1         report [3]
1094 @end group
1095 @end smallexample
1097 Here is what the fields in the primary line mean:
1099 @table @code
1100 @item index
1101 Entries are numbered with consecutive integers.  Each function
1102 therefore has an index number, which appears at the beginning of its
1103 primary line.
1105 Each cross-reference to a function, as a caller or subroutine of
1106 another, gives its index number as well as its name.  The index number
1107 guides you if you wish to look for the entry for that function.
1109 @item % time
1110 This is the percentage of the total time that was spent in this
1111 function, including time spent in subroutines called from this
1112 function.
1114 The time spent in this function is counted again for the callers of
1115 this function.  Therefore, adding up these percentages is meaningless.
1117 @item self
1118 This is the total amount of time spent in this function.  This
1119 should be identical to the number printed in the @code{seconds} field
1120 for this function in the flat profile.
1122 @item children
1123 This is the total amount of time spent in the subroutine calls made by
1124 this function.  This should be equal to the sum of all the @code{self}
1125 and @code{children} entries of the children listed directly below this
1126 function.
1128 @item called
1129 This is the number of times the function was called.
1131 If the function called itself recursively, there are two numbers,
1132 separated by a @samp{+}.  The first number counts non-recursive calls,
1133 and the second counts recursive calls.
1135 In the example above, the function @code{report} was called once from
1136 @code{main}.
1138 @item name
1139 This is the name of the current function.  The index number is
1140 repeated after it.
1142 If the function is part of a cycle of recursion, the cycle number is
1143 printed between the function's name and the index number
1144 (@pxref{Cycles}).  For example, if function @code{gnurr} is part of
1145 cycle number one, and has index number twelve, its primary line would
1146 be end like this:
1148 @example
1149 gnurr <cycle 1> [12]
1150 @end example
1151 @end table
1153 @node Callers, Subroutines, Primary, Call Graph
1154 @subsection Lines for a Function's Callers
1156 A function's entry has a line for each function it was called by.
1157 These lines' fields correspond to the fields of the primary line, but
1158 their meanings are different because of the difference in context.
1160 For reference, we repeat two lines from the entry for the function
1161 @code{report}, the primary line and one caller-line preceding it, together
1162 with the heading line that shows the names of the fields:
1164 @smallexample
1165 index  % time    self  children called     name
1166 @dots{}
1167                 0.00    0.05       1/1           main [2]
1168 [3]    100.0    0.00    0.05       1         report [3]
1169 @end smallexample
1171 Here are the meanings of the fields in the caller-line for @code{report}
1172 called from @code{main}:
1174 @table @code
1175 @item self
1176 An estimate of the amount of time spent in @code{report} itself when it was
1177 called from @code{main}.
1179 @item children
1180 An estimate of the amount of time spent in subroutines of @code{report}
1181 when @code{report} was called from @code{main}.
1183 The sum of the @code{self} and @code{children} fields is an estimate
1184 of the amount of time spent within calls to @code{report} from @code{main}.
1186 @item called
1187 Two numbers: the number of times @code{report} was called from @code{main},
1188 followed by the total number of non-recursive calls to @code{report} from
1189 all its callers.
1191 @item name and index number
1192 The name of the caller of @code{report} to which this line applies,
1193 followed by the caller's index number.
1195 Not all functions have entries in the call graph; some
1196 options to @code{gprof} request the omission of certain functions.
1197 When a caller has no entry of its own, it still has caller-lines
1198 in the entries of the functions it calls.
1200 If the caller is part of a recursion cycle, the cycle number is
1201 printed between the name and the index number.
1202 @end table
1204 If the identity of the callers of a function cannot be determined, a
1205 dummy caller-line is printed which has @samp{<spontaneous>} as the
1206 ``caller's name'' and all other fields blank.  This can happen for
1207 signal handlers.
1208 @c What if some calls have determinable callers' names but not all?
1209 @c FIXME - still relevant?
1211 @node Subroutines, Cycles, Callers, Call Graph
1212 @subsection Lines for a Function's Subroutines
1214 A function's entry has a line for each of its subroutines---in other
1215 words, a line for each other function that it called.  These lines'
1216 fields correspond to the fields of the primary line, but their meanings
1217 are different because of the difference in context.
1219 For reference, we repeat two lines from the entry for the function
1220 @code{main}, the primary line and a line for a subroutine, together
1221 with the heading line that shows the names of the fields:
1223 @smallexample
1224 index  % time    self  children called     name
1225 @dots{}
1226 [2]    100.0    0.00    0.05       1         main [2]
1227                 0.00    0.05       1/1           report [3]
1228 @end smallexample
1230 Here are the meanings of the fields in the subroutine-line for @code{main}
1231 calling @code{report}:
1233 @table @code
1234 @item self
1235 An estimate of the amount of time spent directly within @code{report}
1236 when @code{report} was called from @code{main}.
1238 @item children
1239 An estimate of the amount of time spent in subroutines of @code{report}
1240 when @code{report} was called from @code{main}.
1242 The sum of the @code{self} and @code{children} fields is an estimate
1243 of the total time spent in calls to @code{report} from @code{main}.
1245 @item called
1246 Two numbers, the number of calls to @code{report} from @code{main}
1247 followed by the total number of non-recursive calls to @code{report}.
1248 This ratio is used to determine how much of @code{report}'s @code{self}
1249 and @code{children} time gets credited to @code{main}.
1250 @xref{Assumptions}.
1252 @item name
1253 The name of the subroutine of @code{main} to which this line applies,
1254 followed by the subroutine's index number.
1256 If the caller is part of a recursion cycle, the cycle number is
1257 printed between the name and the index number.
1258 @end table
1260 @node Cycles,, Subroutines, Call Graph
1261 @subsection How Mutually Recursive Functions Are Described
1262 @cindex cycle
1263 @cindex recursion cycle
1265 The graph may be complicated by the presence of @dfn{cycles of
1266 recursion} in the call graph.  A cycle exists if a function calls
1267 another function that (directly or indirectly) calls (or appears to
1268 call) the original function.  For example: if @code{a} calls @code{b},
1269 and @code{b} calls @code{a}, then @code{a} and @code{b} form a cycle.
1271 Whenever there are call paths both ways between a pair of functions, they
1272 belong to the same cycle.  If @code{a} and @code{b} call each other and
1273 @code{b} and @code{c} call each other, all three make one cycle.  Note that
1274 even if @code{b} only calls @code{a} if it was not called from @code{a},
1275 @code{gprof} cannot determine this, so @code{a} and @code{b} are still
1276 considered a cycle.
1278 The cycles are numbered with consecutive integers.  When a function
1279 belongs to a cycle, each time the function name appears in the call graph
1280 it is followed by @samp{<cycle @var{number}>}.
1282 The reason cycles matter is that they make the time values in the call
1283 graph paradoxical.  The ``time spent in children'' of @code{a} should
1284 include the time spent in its subroutine @code{b} and in @code{b}'s
1285 subroutines---but one of @code{b}'s subroutines is @code{a}!  How much of
1286 @code{a}'s time should be included in the children of @code{a}, when
1287 @code{a} is indirectly recursive?
1289 The way @code{gprof} resolves this paradox is by creating a single entry
1290 for the cycle as a whole.  The primary line of this entry describes the
1291 total time spent directly in the functions of the cycle.  The
1292 ``subroutines'' of the cycle are the individual functions of the cycle, and
1293 all other functions that were called directly by them.  The ``callers'' of
1294 the cycle are the functions, outside the cycle, that called functions in
1295 the cycle.
1297 Here is an example portion of a call graph which shows a cycle containing
1298 functions @code{a} and @code{b}.  The cycle was entered by a call to
1299 @code{a} from @code{main}; both @code{a} and @code{b} called @code{c}.
1301 @smallexample
1302 index  % time    self  children called     name
1303 ----------------------------------------
1304                  1.77        0    1/1        main [2]
1305 [3]     91.71    1.77        0    1+5    <cycle 1 as a whole> [3]
1306                  1.02        0    3          b <cycle 1> [4]
1307                  0.75        0    2          a <cycle 1> [5]
1308 ----------------------------------------
1309                                   3          a <cycle 1> [5]
1310 [4]     52.85    1.02        0    0      b <cycle 1> [4]
1311                                   2          a <cycle 1> [5]
1312                     0        0    3/6        c [6]
1313 ----------------------------------------
1314                  1.77        0    1/1        main [2]
1315                                   2          b <cycle 1> [4]
1316 [5]     38.86    0.75        0    1      a <cycle 1> [5]
1317                                   3          b <cycle 1> [4]
1318                     0        0    3/6        c [6]
1319 ----------------------------------------
1320 @end smallexample
1322 @noindent
1323 (The entire call graph for this program contains in addition an entry for
1324 @code{main}, which calls @code{a}, and an entry for @code{c}, with callers
1325 @code{a} and @code{b}.)
1327 @smallexample
1328 index  % time    self  children called     name
1329                                              <spontaneous>
1330 [1]    100.00       0     1.93    0      start [1]
1331                  0.16     1.77    1/1        main [2]
1332 ----------------------------------------
1333                  0.16     1.77    1/1        start [1]
1334 [2]    100.00    0.16     1.77    1      main [2]
1335                  1.77        0    1/1        a <cycle 1> [5]
1336 ----------------------------------------
1337                  1.77        0    1/1        main [2]
1338 [3]     91.71    1.77        0    1+5    <cycle 1 as a whole> [3]
1339                  1.02        0    3          b <cycle 1> [4]
1340                  0.75        0    2          a <cycle 1> [5]
1341                     0        0    6/6        c [6]
1342 ----------------------------------------
1343                                   3          a <cycle 1> [5]
1344 [4]     52.85    1.02        0    0      b <cycle 1> [4]
1345                                   2          a <cycle 1> [5]
1346                     0        0    3/6        c [6]
1347 ----------------------------------------
1348                  1.77        0    1/1        main [2]
1349                                   2          b <cycle 1> [4]
1350 [5]     38.86    0.75        0    1      a <cycle 1> [5]
1351                                   3          b <cycle 1> [4]
1352                     0        0    3/6        c [6]
1353 ----------------------------------------
1354                     0        0    3/6        b <cycle 1> [4]
1355                     0        0    3/6        a <cycle 1> [5]
1356 [6]      0.00       0        0    6      c [6]
1357 ----------------------------------------
1358 @end smallexample
1360 The @code{self} field of the cycle's primary line is the total time
1361 spent in all the functions of the cycle.  It equals the sum of the
1362 @code{self} fields for the individual functions in the cycle, found
1363 in the entry in the subroutine lines for these functions.
1365 The @code{children} fields of the cycle's primary line and subroutine lines
1366 count only subroutines outside the cycle.  Even though @code{a} calls
1367 @code{b}, the time spent in those calls to @code{b} is not counted in
1368 @code{a}'s @code{children} time.  Thus, we do not encounter the problem of
1369 what to do when the time in those calls to @code{b} includes indirect
1370 recursive calls back to @code{a}.
1372 The @code{children} field of a caller-line in the cycle's entry estimates
1373 the amount of time spent @emph{in the whole cycle}, and its other
1374 subroutines, on the times when that caller called a function in the cycle.
1376 The @code{calls} field in the primary line for the cycle has two numbers:
1377 first, the number of times functions in the cycle were called by functions
1378 outside the cycle; second, the number of times they were called by
1379 functions in the cycle (including times when a function in the cycle calls
1380 itself).  This is a generalization of the usual split into non-recursive and
1381 recursive calls.
1383 The @code{calls} field of a subroutine-line for a cycle member in the
1384 cycle's entry says how many time that function was called from functions in
1385 the cycle.  The total of all these is the second number in the primary line's
1386 @code{calls} field.
1388 In the individual entry for a function in a cycle, the other functions in
1389 the same cycle can appear as subroutines and as callers.  These lines show
1390 how many times each function in the cycle called or was called from each other
1391 function in the cycle.  The @code{self} and @code{children} fields in these
1392 lines are blank because of the difficulty of defining meanings for them
1393 when recursion is going on.
1395 @node Line-by-line,Annotated Source,Call Graph,Output
1396 @section Line-by-line Profiling
1398 @code{gprof}'s @samp{-l} option causes the program to perform
1399 @dfn{line-by-line} profiling.  In this mode, histogram
1400 samples are assigned not to functions, but to individual
1401 lines of source code.  The program usually must be compiled
1402 with a @samp{-g} option, in addition to @samp{-pg}, in order
1403 to generate debugging symbols for tracking source code lines.
1405 The flat profile is the most useful output table
1406 in line-by-line mode.
1407 The call graph isn't as useful as normal, since
1408 the current version of @code{gprof} does not propagate
1409 call graph arcs from source code lines to the enclosing function.
1410 The call graph does, however, show each line of code
1411 that called each function, along with a count.
1413 Here is a section of @code{gprof}'s output, without line-by-line profiling.
1414 Note that @code{ct_init} accounted for four histogram hits, and
1415 13327 calls to @code{init_block}.
1417 @smallexample
1418 Flat profile:
1420 Each sample counts as 0.01 seconds.
1421   %   cumulative   self              self     total           
1422  time   seconds   seconds    calls  us/call  us/call  name    
1423  30.77      0.13     0.04     6335     6.31     6.31  ct_init
1426                      Call graph (explanation follows)
1429 granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
1431 index % time    self  children    called     name
1433                 0.00    0.00       1/13496       name_too_long
1434                 0.00    0.00      40/13496       deflate
1435                 0.00    0.00     128/13496       deflate_fast
1436                 0.00    0.00   13327/13496       ct_init
1437 [7]      0.0    0.00    0.00   13496         init_block
1439 @end smallexample
1441 Now let's look at some of @code{gprof}'s output from the same program run,
1442 this time with line-by-line profiling enabled.  Note that @code{ct_init}'s
1443 four histogram hits are broken down into four lines of source code - one hit
1444 occurred on each of lines 349, 351, 382 and 385.  In the call graph,
1445 note how
1446 @code{ct_init}'s 13327 calls to @code{init_block} are broken down
1447 into one call from line 396, 3071 calls from line 384, 3730 calls
1448 from line 385, and 6525 calls from 387.
1450 @smallexample
1451 Flat profile:
1453 Each sample counts as 0.01 seconds.
1454   %   cumulative   self                    
1455  time   seconds   seconds    calls  name    
1456   7.69      0.10     0.01           ct_init (trees.c:349)
1457   7.69      0.11     0.01           ct_init (trees.c:351)
1458   7.69      0.12     0.01           ct_init (trees.c:382)
1459   7.69      0.13     0.01           ct_init (trees.c:385)
1462                      Call graph (explanation follows)
1465 granularity: each sample hit covers 4 byte(s) for 7.69% of 0.13 seconds
1467   % time    self  children    called     name
1469             0.00    0.00       1/13496       name_too_long (gzip.c:1440)
1470             0.00    0.00       1/13496       deflate (deflate.c:763)
1471             0.00    0.00       1/13496       ct_init (trees.c:396)
1472             0.00    0.00       2/13496       deflate (deflate.c:727)
1473             0.00    0.00       4/13496       deflate (deflate.c:686)
1474             0.00    0.00       5/13496       deflate (deflate.c:675)
1475             0.00    0.00      12/13496       deflate (deflate.c:679)
1476             0.00    0.00      16/13496       deflate (deflate.c:730)
1477             0.00    0.00     128/13496       deflate_fast (deflate.c:654)
1478             0.00    0.00    3071/13496       ct_init (trees.c:384)
1479             0.00    0.00    3730/13496       ct_init (trees.c:385)
1480             0.00    0.00    6525/13496       ct_init (trees.c:387)
1481 [6]  0.0    0.00    0.00   13496         init_block (trees.c:408)
1483 @end smallexample
1486 @node Annotated Source,,Line-by-line,Output
1487 @section The Annotated Source Listing
1489 @code{gprof}'s @samp{-A} option triggers an annotated source listing,
1490 which lists the program's source code, each function labeled with the
1491 number of times it was called.  You may also need to specify the
1492 @samp{-I} option, if @code{gprof} can't find the source code files.
1494 Compiling with @samp{gcc @dots{} -g -pg -a} augments your program
1495 with basic-block counting code, in addition to function counting code.
1496 This enables @code{gprof} to determine how many times each line
1497 of code was executed.
1498 For example, consider the following function, taken from gzip,
1499 with line numbers added:
1501 @smallexample
1502  1 ulg updcrc(s, n)
1503  2     uch *s;
1504  3     unsigned n;
1505  4 @{
1506  5     register ulg c;
1508  7     static ulg crc = (ulg)0xffffffffL;
1510  9     if (s == NULL) @{
1511 10         c = 0xffffffffL;
1512 11     @} else @{
1513 12         c = crc;
1514 13         if (n) do @{
1515 14             c = crc_32_tab[...];
1516 15         @} while (--n);
1517 16     @}
1518 17     crc = c;
1519 18     return c ^ 0xffffffffL;
1520 19 @}
1522 @end smallexample
1524 @code{updcrc} has at least five basic-blocks.
1525 One is the function itself.  The
1526 @code{if} statement on line 9 generates two more basic-blocks, one
1527 for each branch of the @code{if}.  A fourth basic-block results from
1528 the @code{if} on line 13, and the contents of the @code{do} loop form
1529 the fifth basic-block.  The compiler may also generate additional
1530 basic-blocks to handle various special cases.
1532 A program augmented for basic-block counting can be analyzed with
1533 @samp{gprof -l -A}.  I also suggest use of the @samp{-x} option,
1534 which ensures that each line of code is labeled at least once.
1535 Here is @code{updcrc}'s
1536 annotated source listing for a sample @code{gzip} run:
1538 @smallexample
1539                 ulg updcrc(s, n)
1540                     uch *s;
1541                     unsigned n;
1542             2 ->@{
1543                     register ulg c;
1544                 
1545                     static ulg crc = (ulg)0xffffffffL;
1546                 
1547             2 ->    if (s == NULL) @{
1548             1 ->        c = 0xffffffffL;
1549             1 ->    @} else @{
1550             1 ->        c = crc;
1551             1 ->        if (n) do @{
1552         26312 ->            c = crc_32_tab[...];
1553 26312,1,26311 ->        @} while (--n);
1554                     @}
1555             2 ->    crc = c;
1556             2 ->    return c ^ 0xffffffffL;
1557             2 ->@}
1558 @end smallexample
1560 In this example, the function was called twice, passing once through
1561 each branch of the @code{if} statement.  The body of the @code{do}
1562 loop was executed a total of 26312 times.  Note how the @code{while}
1563 statement is annotated.  It began execution 26312 times, once for
1564 each iteration through the loop.  One of those times (the last time)
1565 it exited, while it branched back to the beginning of the loop 26311 times.
1567 @node Inaccuracy
1568 @chapter Inaccuracy of @code{gprof} Output
1570 @menu
1571 * Sampling Error::      Statistical margins of error
1572 * Assumptions::         Estimating children times
1573 @end menu
1575 @node Sampling Error,Assumptions,,Inaccuracy
1576 @section Statistical Sampling Error
1578 The run-time figures that @code{gprof} gives you are based on a sampling
1579 process, so they are subject to statistical inaccuracy.  If a function runs
1580 only a small amount of time, so that on the average the sampling process
1581 ought to catch that function in the act only once, there is a pretty good
1582 chance it will actually find that function zero times, or twice.
1584 By contrast, the number-of-calls and basic-block figures
1585 are derived by counting, not
1586 sampling.  They are completely accurate and will not vary from run to run
1587 if your program is deterministic.
1589 The @dfn{sampling period} that is printed at the beginning of the flat
1590 profile says how often samples are taken.  The rule of thumb is that a
1591 run-time figure is accurate if it is considerably bigger than the sampling
1592 period.
1594 The actual amount of error can be predicted.
1595 For @var{n} samples, the @emph{expected} error
1596 is the square-root of @var{n}.  For example,
1597 if the sampling period is 0.01 seconds and @code{foo}'s run-time is 1 second,
1598 @var{n} is 100 samples (1 second/0.01 seconds), sqrt(@var{n}) is 10 samples, so
1599 the expected error in @code{foo}'s run-time is 0.1 seconds (10*0.01 seconds),
1600 or ten percent of the observed value.
1601 Again, if the sampling period is 0.01 seconds and @code{bar}'s run-time is
1602 100 seconds, @var{n} is 10000 samples, sqrt(@var{n}) is 100 samples, so
1603 the expected error in @code{bar}'s run-time is 1 second,
1604 or one percent of the observed value.
1605 It is likely to
1606 vary this much @emph{on the average} from one profiling run to the next.
1607 (@emph{Sometimes} it will vary more.)
1609 This does not mean that a small run-time figure is devoid of information.
1610 If the program's @emph{total} run-time is large, a small run-time for one
1611 function does tell you that that function used an insignificant fraction of
1612 the whole program's time.  Usually this means it is not worth optimizing.
1614 One way to get more accuracy is to give your program more (but similar)
1615 input data so it will take longer.  Another way is to combine the data from
1616 several runs, using the @samp{-s} option of @code{gprof}.  Here is how:
1618 @enumerate
1619 @item
1620 Run your program once.
1622 @item
1623 Issue the command @samp{mv gmon.out gmon.sum}.
1625 @item
1626 Run your program again, the same as before.
1628 @item
1629 Merge the new data in @file{gmon.out} into @file{gmon.sum} with this command:
1631 @example
1632 gprof -s @var{executable-file} gmon.out gmon.sum
1633 @end example
1635 @item
1636 Repeat the last two steps as often as you wish.
1638 @item
1639 Analyze the cumulative data using this command:
1641 @example
1642 gprof @var{executable-file} gmon.sum > @var{output-file}
1643 @end example
1644 @end enumerate
1646 @node Assumptions,,Sampling Error,Inaccuracy
1647 @section Estimating @code{children} Times
1649 Some of the figures in the call graph are estimates---for example, the
1650 @code{children} time values and all the time figures in caller and
1651 subroutine lines.
1653 There is no direct information about these measurements in the profile
1654 data itself.  Instead, @code{gprof} estimates them by making an assumption
1655 about your program that might or might not be true.
1657 The assumption made is that the average time spent in each call to any
1658 function @code{foo} is not correlated with who called @code{foo}.  If
1659 @code{foo} used 5 seconds in all, and 2/5 of the calls to @code{foo} came
1660 from @code{a}, then @code{foo} contributes 2 seconds to @code{a}'s
1661 @code{children} time, by assumption.
1663 This assumption is usually true enough, but for some programs it is far
1664 from true.  Suppose that @code{foo} returns very quickly when its argument
1665 is zero; suppose that @code{a} always passes zero as an argument, while
1666 other callers of @code{foo} pass other arguments.  In this program, all the
1667 time spent in @code{foo} is in the calls from callers other than @code{a}.
1668 But @code{gprof} has no way of knowing this; it will blindly and
1669 incorrectly charge 2 seconds of time in @code{foo} to the children of
1670 @code{a}.
1672 @c FIXME - has this been fixed?
1673 We hope some day to put more complete data into @file{gmon.out}, so that
1674 this assumption is no longer needed, if we can figure out how.  For the
1675 nonce, the estimated figures are usually more useful than misleading.
1677 @node How do I?
1678 @chapter Answers to Common Questions
1680 @table @asis
1681 @item How can I get more exact information about hot spots in my program?
1683 Looking at the per-line call counts only tells part of the story.
1684 Because @code{gprof} can only report call times and counts by function,
1685 the best way to get finer-grained information on where the program
1686 is spending its time is to re-factor large functions into sequences
1687 of calls to smaller ones.  Beware however that this can introduce
1688 artifical hot spots since compiling with @samp{-pg} adds a significant
1689 overhead to function calls.  An alternative solution is to use a
1690 non-intrusive profiler, e.g.@: oprofile.
1692 @item How do I find which lines in my program were executed the most times?
1694 Compile your program with basic-block counting enabled, run it, then
1695 use the following pipeline:
1697 @example
1698 gprof -l -C @var{objfile} | sort -k 3 -n -r
1699 @end example
1701 This listing will show you the lines in your code executed most often,
1702 but not necessarily those that consumed the most time.
1704 @item How do I find which lines in my program called a particular function?
1706 Use @samp{gprof -l} and lookup the function in the call graph.
1707 The callers will be broken down by function and line number.
1709 @item How do I analyze a program that runs for less than a second?
1711 Try using a shell script like this one:
1713 @example
1714 for i in `seq 1 100`; do
1715   fastprog
1716   mv gmon.out gmon.out.$i
1717 done
1719 gprof -s fastprog gmon.out.*
1721 gprof fastprog gmon.sum
1722 @end example
1724 If your program is completely deterministic, all the call counts
1725 will be simple multiples of 100 (i.e. a function called once in
1726 each run will appear with a call count of 100).
1728 @end table
1730 @node Incompatibilities
1731 @chapter Incompatibilities with Unix @code{gprof}
1733 @sc{gnu} @code{gprof} and Berkeley Unix @code{gprof} use the same data
1734 file @file{gmon.out}, and provide essentially the same information.  But
1735 there are a few differences.
1737 @itemize @bullet
1738 @item
1739 @sc{gnu} @code{gprof} uses a new, generalized file format with support
1740 for basic-block execution counts and non-realtime histograms.  A magic
1741 cookie and version number allows @code{gprof} to easily identify
1742 new style files.  Old BSD-style files can still be read.
1743 @xref{File Format}.
1745 @item
1746 For a recursive function, Unix @code{gprof} lists the function as a
1747 parent and as a child, with a @code{calls} field that lists the number
1748 of recursive calls.  @sc{gnu} @code{gprof} omits these lines and puts
1749 the number of recursive calls in the primary line.
1751 @item
1752 When a function is suppressed from the call graph with @samp{-e}, @sc{gnu}
1753 @code{gprof} still lists it as a subroutine of functions that call it.
1755 @item
1756 @sc{gnu} @code{gprof} accepts the @samp{-k} with its argument
1757 in the form @samp{from/to}, instead of @samp{from to}.
1759 @item
1760 In the annotated source listing,
1761 if there are multiple basic blocks on the same line,
1762 @sc{gnu} @code{gprof} prints all of their counts, separated by commas.
1764 @ignore - it does this now
1765 @item
1766 The function names printed in @sc{gnu} @code{gprof} output do not include
1767 the leading underscores that are added internally to the front of all
1768 C identifiers on many operating systems.
1769 @end ignore
1771 @item
1772 The blurbs, field widths, and output formats are different.  @sc{gnu}
1773 @code{gprof} prints blurbs after the tables, so that you can see the
1774 tables without skipping the blurbs.
1775 @end itemize
1777 @node Details
1778 @chapter Details of Profiling
1780 @menu
1781 * Implementation::      How a program collects profiling information
1782 * File Format::         Format of @samp{gmon.out} files
1783 * Internals::           @code{gprof}'s internal operation
1784 * Debugging::           Using @code{gprof}'s @samp{-d} option
1785 @end menu
1787 @node Implementation,File Format,,Details
1788 @section Implementation of Profiling
1790 Profiling works by changing how every function in your program is compiled
1791 so that when it is called, it will stash away some information about where
1792 it was called from.  From this, the profiler can figure out what function
1793 called it, and can count how many times it was called.  This change is made
1794 by the compiler when your program is compiled with the @samp{-pg} option,
1795 which causes every function to call @code{mcount}
1796 (or @code{_mcount}, or @code{__mcount}, depending on the OS and compiler)
1797 as one of its first operations.
1799 The @code{mcount} routine, included in the profiling library,
1800 is responsible for recording in an in-memory call graph table
1801 both its parent routine (the child) and its parent's parent.  This is
1802 typically done by examining the stack frame to find both
1803 the address of the child, and the return address in the original parent.
1804 Since this is a very machine-dependent operation, @code{mcount}
1805 itself is typically a short assembly-language stub routine
1806 that extracts the required
1807 information, and then calls @code{__mcount_internal}
1808 (a normal C function) with two arguments - @code{frompc} and @code{selfpc}.
1809 @code{__mcount_internal} is responsible for maintaining
1810 the in-memory call graph, which records @code{frompc}, @code{selfpc},
1811 and the number of times each of these call arcs was traversed.
1813 GCC Version 2 provides a magical function (@code{__builtin_return_address}),
1814 which allows a generic @code{mcount} function to extract the
1815 required information from the stack frame.  However, on some
1816 architectures, most notably the SPARC, using this builtin can be
1817 very computationally expensive, and an assembly language version
1818 of @code{mcount} is used for performance reasons.
1820 Number-of-calls information for library routines is collected by using a
1821 special version of the C library.  The programs in it are the same as in
1822 the usual C library, but they were compiled with @samp{-pg}.  If you
1823 link your program with @samp{gcc @dots{} -pg}, it automatically uses the
1824 profiling version of the library.
1826 Profiling also involves watching your program as it runs, and keeping a
1827 histogram of where the program counter happens to be every now and then.
1828 Typically the program counter is looked at around 100 times per second of
1829 run time, but the exact frequency may vary from system to system.
1831 This is done is one of two ways.  Most UNIX-like operating systems
1832 provide a @code{profil()} system call, which registers a memory
1833 array with the kernel, along with a scale
1834 factor that determines how the program's address space maps
1835 into the array.
1836 Typical scaling values cause every 2 to 8 bytes of address space
1837 to map into a single array slot.
1838 On every tick of the system clock
1839 (assuming the profiled program is running), the value of the
1840 program counter is examined and the corresponding slot in
1841 the memory array is incremented.  Since this is done in the kernel,
1842 which had to interrupt the process anyway to handle the clock
1843 interrupt, very little additional system overhead is required.
1845 However, some operating systems, most notably Linux 2.0 (and earlier),
1846 do not provide a @code{profil()} system call.  On such a system,
1847 arrangements are made for the kernel to periodically deliver
1848 a signal to the process (typically via @code{setitimer()}),
1849 which then performs the same operation of examining the
1850 program counter and incrementing a slot in the memory array.
1851 Since this method requires a signal to be delivered to
1852 user space every time a sample is taken, it uses considerably
1853 more overhead than kernel-based profiling.  Also, due to the
1854 added delay required to deliver the signal, this method is
1855 less accurate as well.
1857 A special startup routine allocates memory for the histogram and 
1858 either calls @code{profil()} or sets up
1859 a clock signal handler.
1860 This routine (@code{monstartup}) can be invoked in several ways.
1861 On Linux systems, a special profiling startup file @code{gcrt0.o},
1862 which invokes @code{monstartup} before @code{main},
1863 is used instead of the default @code{crt0.o}.
1864 Use of this special startup file is one of the effects
1865 of using @samp{gcc @dots{} -pg} to link.
1866 On SPARC systems, no special startup files are used.
1867 Rather, the @code{mcount} routine, when it is invoked for
1868 the first time (typically when @code{main} is called),
1869 calls @code{monstartup}.
1871 If the compiler's @samp{-a} option was used, basic-block counting
1872 is also enabled.  Each object file is then compiled with a static array
1873 of counts, initially zero.
1874 In the executable code, every time a new basic-block begins
1875 (i.e. when an @code{if} statement appears), an extra instruction
1876 is inserted to increment the corresponding count in the array.
1877 At compile time, a paired array was constructed that recorded
1878 the starting address of each basic-block.  Taken together,
1879 the two arrays record the starting address of every basic-block,
1880 along with the number of times it was executed.
1882 The profiling library also includes a function (@code{mcleanup}) which is
1883 typically registered using @code{atexit()} to be called as the
1884 program exits, and is responsible for writing the file @file{gmon.out}.
1885 Profiling is turned off, various headers are output, and the histogram
1886 is written, followed by the call-graph arcs and the basic-block counts.
1888 The output from @code{gprof} gives no indication of parts of your program that
1889 are limited by I/O or swapping bandwidth.  This is because samples of the
1890 program counter are taken at fixed intervals of the program's run time.
1891 Therefore, the
1892 time measurements in @code{gprof} output say nothing about time that your
1893 program was not running.  For example, a part of the program that creates
1894 so much data that it cannot all fit in physical memory at once may run very
1895 slowly due to thrashing, but @code{gprof} will say it uses little time.  On
1896 the other hand, sampling by run time has the advantage that the amount of
1897 load due to other users won't directly affect the output you get.
1899 @node File Format,Internals,Implementation,Details
1900 @section Profiling Data File Format
1902 The old BSD-derived file format used for profile data does not contain a
1903 magic cookie that allows to check whether a data file really is a
1904 @code{gprof} file.  Furthermore, it does not provide a version number, thus
1905 rendering changes to the file format almost impossible.  @sc{gnu} @code{gprof}
1906 uses a new file format that provides these features.  For backward
1907 compatibility, @sc{gnu} @code{gprof} continues to support the old BSD-derived
1908 format, but not all features are supported with it.  For example,
1909 basic-block execution counts cannot be accommodated by the old file
1910 format.
1912 The new file format is defined in header file @file{gmon_out.h}.  It
1913 consists of a header containing the magic cookie and a version number,
1914 as well as some spare bytes available for future extensions.  All data
1915 in a profile data file is in the native format of the target for which
1916 the profile was collected.  @sc{gnu} @code{gprof} adapts automatically
1917 to the byte-order in use.
1919 In the new file format, the header is followed by a sequence of
1920 records.  Currently, there are three different record types: histogram
1921 records, call-graph arc records, and basic-block execution count
1922 records.  Each file can contain any number of each record type.  When
1923 reading a file, @sc{gnu} @code{gprof} will ensure records of the same type are
1924 compatible with each other and compute the union of all records.  For
1925 example, for basic-block execution counts, the union is simply the sum
1926 of all execution counts for each basic-block.
1928 @subsection Histogram Records
1930 Histogram records consist of a header that is followed by an array of
1931 bins.  The header contains the text-segment range that the histogram
1932 spans, the size of the histogram in bytes (unlike in the old BSD
1933 format, this does not include the size of the header), the rate of the
1934 profiling clock, and the physical dimension that the bin counts
1935 represent after being scaled by the profiling clock rate.  The
1936 physical dimension is specified in two parts: a long name of up to 15
1937 characters and a single character abbreviation.  For example, a
1938 histogram representing real-time would specify the long name as
1939 "seconds" and the abbreviation as "s".  This feature is useful for
1940 architectures that support performance monitor hardware (which,
1941 fortunately, is becoming increasingly common).  For example, under DEC
1942 OSF/1, the "uprofile" command can be used to produce a histogram of,
1943 say, instruction cache misses.  In this case, the dimension in the
1944 histogram header could be set to "i-cache misses" and the abbreviation
1945 could be set to "1" (because it is simply a count, not a physical
1946 dimension).  Also, the profiling rate would have to be set to 1 in
1947 this case.
1949 Histogram bins are 16-bit numbers and each bin represent an equal
1950 amount of text-space.  For example, if the text-segment is one
1951 thousand bytes long and if there are ten bins in the histogram, each
1952 bin represents one hundred bytes.
1955 @subsection Call-Graph Records
1957 Call-graph records have a format that is identical to the one used in
1958 the BSD-derived file format.  It consists of an arc in the call graph
1959 and a count indicating the number of times the arc was traversed
1960 during program execution.  Arcs are specified by a pair of addresses:
1961 the first must be within caller's function and the second must be
1962 within the callee's function.  When performing profiling at the
1963 function level, these addresses can point anywhere within the
1964 respective function.  However, when profiling at the line-level, it is
1965 better if the addresses are as close to the call-site/entry-point as
1966 possible.  This will ensure that the line-level call-graph is able to
1967 identify exactly which line of source code performed calls to a
1968 function.
1970 @subsection Basic-Block Execution Count Records
1972 Basic-block execution count records consist of a header followed by a
1973 sequence of address/count pairs.  The header simply specifies the
1974 length of the sequence.  In an address/count pair, the address
1975 identifies a basic-block and the count specifies the number of times
1976 that basic-block was executed.  Any address within the basic-address can
1977 be used.
1979 @node Internals,Debugging,File Format,Details
1980 @section @code{gprof}'s Internal Operation
1982 Like most programs, @code{gprof} begins by processing its options.
1983 During this stage, it may building its symspec list
1984 (@code{sym_ids.c:sym_id_add}), if
1985 options are specified which use symspecs.
1986 @code{gprof} maintains a single linked list of symspecs,
1987 which will eventually get turned into 12 symbol tables,
1988 organized into six include/exclude pairs - one
1989 pair each for the flat profile (INCL_FLAT/EXCL_FLAT),
1990 the call graph arcs (INCL_ARCS/EXCL_ARCS),
1991 printing in the call graph (INCL_GRAPH/EXCL_GRAPH),
1992 timing propagation in the call graph (INCL_TIME/EXCL_TIME),
1993 the annotated source listing (INCL_ANNO/EXCL_ANNO),
1994 and the execution count listing (INCL_EXEC/EXCL_EXEC).
1996 After option processing, @code{gprof} finishes
1997 building the symspec list by adding all the symspecs in
1998 @code{default_excluded_list} to the exclude lists
1999 EXCL_TIME and EXCL_GRAPH, and if line-by-line profiling is specified,
2000 EXCL_FLAT as well.
2001 These default excludes are not added to EXCL_ANNO, EXCL_ARCS, and EXCL_EXEC.
2003 Next, the BFD library is called to open the object file,
2004 verify that it is an object file,
2005 and read its symbol table (@code{core.c:core_init}),
2006 using @code{bfd_canonicalize_symtab} after mallocing
2007 an appropriately sized array of symbols.  At this point,
2008 function mappings are read (if the @samp{--file-ordering} option
2009 has been specified), and the core text space is read into
2010 memory (if the @samp{-c} option was given).
2012 @code{gprof}'s own symbol table, an array of Sym structures,
2013 is now built.
2014 This is done in one of two ways, by one of two routines, depending
2015 on whether line-by-line profiling (@samp{-l} option) has been
2016 enabled.
2017 For normal profiling, the BFD canonical symbol table is scanned.
2018 For line-by-line profiling, every
2019 text space address is examined, and a new symbol table entry
2020 gets created every time the line number changes.
2021 In either case, two passes are made through the symbol
2022 table - one to count the size of the symbol table required,
2023 and the other to actually read the symbols.  In between the
2024 two passes, a single array of type @code{Sym} is created of
2025 the appropriate length.
2026 Finally, @code{symtab.c:symtab_finalize}
2027 is called to sort the symbol table and remove duplicate entries
2028 (entries with the same memory address).
2030 The symbol table must be a contiguous array for two reasons.
2031 First, the @code{qsort} library function (which sorts an array)
2032 will be used to sort the symbol table.
2033 Also, the symbol lookup routine (@code{symtab.c:sym_lookup}),
2034 which finds symbols
2035 based on memory address, uses a binary search algorithm
2036 which requires the symbol table to be a sorted array.
2037 Function symbols are indicated with an @code{is_func} flag.
2038 Line number symbols have no special flags set.
2039 Additionally, a symbol can have an @code{is_static} flag
2040 to indicate that it is a local symbol.
2042 With the symbol table read, the symspecs can now be translated
2043 into Syms (@code{sym_ids.c:sym_id_parse}).  Remember that a single
2044 symspec can match multiple symbols.
2045 An array of symbol tables
2046 (@code{syms}) is created, each entry of which is a symbol table
2047 of Syms to be included or excluded from a particular listing.
2048 The master symbol table and the symspecs are examined by nested
2049 loops, and every symbol that matches a symspec is inserted
2050 into the appropriate syms table.  This is done twice, once to
2051 count the size of each required symbol table, and again to build
2052 the tables, which have been malloced between passes.
2053 From now on, to determine whether a symbol is on an include
2054 or exclude symspec list, @code{gprof} simply uses its
2055 standard symbol lookup routine on the appropriate table
2056 in the @code{syms} array.
2058 Now the profile data file(s) themselves are read
2059 (@code{gmon_io.c:gmon_out_read}),
2060 first by checking for a new-style @samp{gmon.out} header,
2061 then assuming this is an old-style BSD @samp{gmon.out}
2062 if the magic number test failed.
2064 New-style histogram records are read by @code{hist.c:hist_read_rec}.
2065 For the first histogram record, allocate a memory array to hold
2066 all the bins, and read them in.
2067 When multiple profile data files (or files with multiple histogram
2068 records) are read, the starting address, ending address, number
2069 of bins and sampling rate must match between the various histograms,
2070 or a fatal error will result.
2071 If everything matches, just sum the additional histograms into
2072 the existing in-memory array.
2074 As each call graph record is read (@code{call_graph.c:cg_read_rec}),
2075 the parent and child addresses
2076 are matched to symbol table entries, and a call graph arc is
2077 created by @code{cg_arcs.c:arc_add}, unless the arc fails a symspec
2078 check against INCL_ARCS/EXCL_ARCS.  As each arc is added,
2079 a linked list is maintained of the parent's child arcs, and of the child's
2080 parent arcs.
2081 Both the child's call count and the arc's call count are
2082 incremented by the record's call count.
2084 Basic-block records are read (@code{basic_blocks.c:bb_read_rec}),
2085 but only if line-by-line profiling has been selected.
2086 Each basic-block address is matched to a corresponding line
2087 symbol in the symbol table, and an entry made in the symbol's
2088 bb_addr and bb_calls arrays.  Again, if multiple basic-block
2089 records are present for the same address, the call counts
2090 are cumulative.
2092 A gmon.sum file is dumped, if requested (@code{gmon_io.c:gmon_out_write}).
2094 If histograms were present in the data files, assign them to symbols
2095 (@code{hist.c:hist_assign_samples}) by iterating over all the sample
2096 bins and assigning them to symbols.  Since the symbol table
2097 is sorted in order of ascending memory addresses, we can
2098 simple follow along in the symbol table as we make our pass
2099 over the sample bins.
2100 This step includes a symspec check against INCL_FLAT/EXCL_FLAT.
2101 Depending on the histogram
2102 scale factor, a sample bin may span multiple symbols,
2103 in which case a fraction of the sample count is allocated
2104 to each symbol, proportional to the degree of overlap.
2105 This effect is rare for normal profiling, but overlaps
2106 are more common during line-by-line profiling, and can
2107 cause each of two adjacent lines to be credited with half
2108 a hit, for example.
2110 If call graph data is present, @code{cg_arcs.c:cg_assemble} is called.
2111 First, if @samp{-c} was specified, a machine-dependent
2112 routine (@code{find_call}) scans through each symbol's machine code,
2113 looking for subroutine call instructions, and adding them
2114 to the call graph with a zero call count.
2115 A topological sort is performed by depth-first numbering
2116 all the symbols (@code{cg_dfn.c:cg_dfn}), so that
2117 children are always numbered less than their parents,
2118 then making a array of pointers into the symbol table and sorting it into
2119 numerical order, which is reverse topological
2120 order (children appear before parents).
2121 Cycles are also detected at this point, all members
2122 of which are assigned the same topological number.
2123 Two passes are now made through this sorted array of symbol pointers.
2124 The first pass, from end to beginning (parents to children),
2125 computes the fraction of child time to propagate to each parent
2126 and a print flag.
2127 The print flag reflects symspec handling of INCL_GRAPH/EXCL_GRAPH,
2128 with a parent's include or exclude (print or no print) property
2129 being propagated to its children, unless they themselves explicitly appear
2130 in INCL_GRAPH or EXCL_GRAPH.
2131 A second pass, from beginning to end (children to parents) actually
2132 propagates the timings along the call graph, subject
2133 to a check against INCL_TIME/EXCL_TIME.
2134 With the print flag, fractions, and timings now stored in the symbol
2135 structures, the topological sort array is now discarded, and a
2136 new array of pointers is assembled, this time sorted by propagated time.
2138 Finally, print the various outputs the user requested, which is now fairly
2139 straightforward.  The call graph (@code{cg_print.c:cg_print}) and
2140 flat profile (@code{hist.c:hist_print}) are regurgitations of values
2141 already computed.  The annotated source listing
2142 (@code{basic_blocks.c:print_annotated_source}) uses basic-block
2143 information, if present, to label each line of code with call counts,
2144 otherwise only the function call counts are presented.
2146 The function ordering code is marginally well documented
2147 in the source code itself (@code{cg_print.c}).  Basically,
2148 the functions with the most use and the most parents are
2149 placed first, followed by other functions with the most use,
2150 followed by lower use functions, followed by unused functions
2151 at the end.
2153 @node Debugging,,Internals,Details
2154 @subsection Debugging @code{gprof}
2156 If @code{gprof} was compiled with debugging enabled,
2157 the @samp{-d} option triggers debugging output
2158 (to stdout) which can be helpful in understanding its operation.
2159 The debugging number specified is interpreted as a sum of the following
2160 options:
2162 @table @asis
2163 @item 2 - Topological sort
2164 Monitor depth-first numbering of symbols during call graph analysis
2165 @item 4 - Cycles
2166 Shows symbols as they are identified as cycle heads
2167 @item 16 - Tallying
2168 As the call graph arcs are read, show each arc and how
2169 the total calls to each function are tallied
2170 @item 32 - Call graph arc sorting
2171 Details sorting individual parents/children within each call graph entry
2172 @item 64 - Reading histogram and call graph records
2173 Shows address ranges of histograms as they are read, and each
2174 call graph arc
2175 @item 128 - Symbol table
2176 Reading, classifying, and sorting the symbol table from the object file.
2177 For line-by-line profiling (@samp{-l} option), also shows line numbers
2178 being assigned to memory addresses.
2179 @item 256 - Static call graph
2180 Trace operation of @samp{-c} option
2181 @item 512 - Symbol table and arc table lookups
2182 Detail operation of lookup routines
2183 @item 1024 - Call graph propagation
2184 Shows how function times are propagated along the call graph
2185 @item 2048 - Basic-blocks
2186 Shows basic-block records as they are read from profile data
2187 (only meaningful with @samp{-l} option)
2188 @item 4096 - Symspecs
2189 Shows symspec-to-symbol pattern matching operation
2190 @item 8192 - Annotate source
2191 Tracks operation of @samp{-A} option
2192 @end table
2194 @node GNU Free Documentation License
2195 @chapter GNU Free Documentation License
2197                 GNU Free Documentation License
2198                 
2199                    Version 1.1, March 2000
2201  Copyright (C) 2000  Free Software Foundation, Inc.
2202   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
2203      
2204  Everyone is permitted to copy and distribute verbatim copies
2205  of this license document, but changing it is not allowed.
2208 0. PREAMBLE
2210 The purpose of this License is to make a manual, textbook, or other
2211 written document "free" in the sense of freedom: to assure everyone
2212 the effective freedom to copy and redistribute it, with or without
2213 modifying it, either commercially or noncommercially.  Secondarily,
2214 this License preserves for the author and publisher a way to get
2215 credit for their work, while not being considered responsible for
2216 modifications made by others.
2218 This License is a kind of "copyleft", which means that derivative
2219 works of the document must themselves be free in the same sense.  It
2220 complements the GNU General Public License, which is a copyleft
2221 license designed for free software.
2223 We have designed this License in order to use it for manuals for free
2224 software, because free software needs free documentation: a free
2225 program should come with manuals providing the same freedoms that the
2226 software does.  But this License is not limited to software manuals;
2227 it can be used for any textual work, regardless of subject matter or
2228 whether it is published as a printed book.  We recommend this License
2229 principally for works whose purpose is instruction or reference.
2232 1. APPLICABILITY AND DEFINITIONS
2234 This License applies to any manual or other work that contains a
2235 notice placed by the copyright holder saying it can be distributed
2236 under the terms of this License.  The "Document", below, refers to any
2237 such manual or work.  Any member of the public is a licensee, and is
2238 addressed as "you".
2240 A "Modified Version" of the Document means any work containing the
2241 Document or a portion of it, either copied verbatim, or with
2242 modifications and/or translated into another language.
2244 A "Secondary Section" is a named appendix or a front-matter section of
2245 the Document that deals exclusively with the relationship of the
2246 publishers or authors of the Document to the Document's overall subject
2247 (or to related matters) and contains nothing that could fall directly
2248 within that overall subject.  (For example, if the Document is in part a
2249 textbook of mathematics, a Secondary Section may not explain any
2250 mathematics.)  The relationship could be a matter of historical
2251 connection with the subject or with related matters, or of legal,
2252 commercial, philosophical, ethical or political position regarding
2253 them.
2255 The "Invariant Sections" are certain Secondary Sections whose titles
2256 are designated, as being those of Invariant Sections, in the notice
2257 that says that the Document is released under this License.
2259 The "Cover Texts" are certain short passages of text that are listed,
2260 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
2261 the Document is released under this License.
2263 A "Transparent" copy of the Document means a machine-readable copy,
2264 represented in a format whose specification is available to the
2265 general public, whose contents can be viewed and edited directly and
2266 straightforwardly with generic text editors or (for images composed of
2267 pixels) generic paint programs or (for drawings) some widely available
2268 drawing editor, and that is suitable for input to text formatters or
2269 for automatic translation to a variety of formats suitable for input
2270 to text formatters.  A copy made in an otherwise Transparent file
2271 format whose markup has been designed to thwart or discourage
2272 subsequent modification by readers is not Transparent.  A copy that is
2273 not "Transparent" is called "Opaque".
2275 Examples of suitable formats for Transparent copies include plain
2276 ASCII without markup, Texinfo input format, LaTeX input format, SGML
2277 or XML using a publicly available DTD, and standard-conforming simple
2278 HTML designed for human modification.  Opaque formats include
2279 PostScript, PDF, proprietary formats that can be read and edited only
2280 by proprietary word processors, SGML or XML for which the DTD and/or
2281 processing tools are not generally available, and the
2282 machine-generated HTML produced by some word processors for output
2283 purposes only.
2285 The "Title Page" means, for a printed book, the title page itself,
2286 plus such following pages as are needed to hold, legibly, the material
2287 this License requires to appear in the title page.  For works in
2288 formats which do not have any title page as such, "Title Page" means
2289 the text near the most prominent appearance of the work's title,
2290 preceding the beginning of the body of the text.
2293 2. VERBATIM COPYING
2295 You may copy and distribute the Document in any medium, either
2296 commercially or noncommercially, provided that this License, the
2297 copyright notices, and the license notice saying this License applies
2298 to the Document are reproduced in all copies, and that you add no other
2299 conditions whatsoever to those of this License.  You may not use
2300 technical measures to obstruct or control the reading or further
2301 copying of the copies you make or distribute.  However, you may accept
2302 compensation in exchange for copies.  If you distribute a large enough
2303 number of copies you must also follow the conditions in section 3.
2305 You may also lend copies, under the same conditions stated above, and
2306 you may publicly display copies.
2309 3. COPYING IN QUANTITY
2311 If you publish printed copies of the Document numbering more than 100,
2312 and the Document's license notice requires Cover Texts, you must enclose
2313 the copies in covers that carry, clearly and legibly, all these Cover
2314 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
2315 the back cover.  Both covers must also clearly and legibly identify
2316 you as the publisher of these copies.  The front cover must present
2317 the full title with all words of the title equally prominent and
2318 visible.  You may add other material on the covers in addition.
2319 Copying with changes limited to the covers, as long as they preserve
2320 the title of the Document and satisfy these conditions, can be treated
2321 as verbatim copying in other respects.
2323 If the required texts for either cover are too voluminous to fit
2324 legibly, you should put the first ones listed (as many as fit
2325 reasonably) on the actual cover, and continue the rest onto adjacent
2326 pages.
2328 If you publish or distribute Opaque copies of the Document numbering
2329 more than 100, you must either include a machine-readable Transparent
2330 copy along with each Opaque copy, or state in or with each Opaque copy
2331 a publicly-accessible computer-network location containing a complete
2332 Transparent copy of the Document, free of added material, which the
2333 general network-using public has access to download anonymously at no
2334 charge using public-standard network protocols.  If you use the latter
2335 option, you must take reasonably prudent steps, when you begin
2336 distribution of Opaque copies in quantity, to ensure that this
2337 Transparent copy will remain thus accessible at the stated location
2338 until at least one year after the last time you distribute an Opaque
2339 copy (directly or through your agents or retailers) of that edition to
2340 the public.
2342 It is requested, but not required, that you contact the authors of the
2343 Document well before redistributing any large number of copies, to give
2344 them a chance to provide you with an updated version of the Document.
2347 4. MODIFICATIONS
2349 You may copy and distribute a Modified Version of the Document under
2350 the conditions of sections 2 and 3 above, provided that you release
2351 the Modified Version under precisely this License, with the Modified
2352 Version filling the role of the Document, thus licensing distribution
2353 and modification of the Modified Version to whoever possesses a copy
2354 of it.  In addition, you must do these things in the Modified Version:
2356 A. Use in the Title Page (and on the covers, if any) a title distinct
2357    from that of the Document, and from those of previous versions
2358    (which should, if there were any, be listed in the History section
2359    of the Document).  You may use the same title as a previous version
2360    if the original publisher of that version gives permission.
2361 B. List on the Title Page, as authors, one or more persons or entities
2362    responsible for authorship of the modifications in the Modified
2363    Version, together with at least five of the principal authors of the
2364    Document (all of its principal authors, if it has less than five).
2365 C. State on the Title page the name of the publisher of the
2366    Modified Version, as the publisher.
2367 D. Preserve all the copyright notices of the Document.
2368 E. Add an appropriate copyright notice for your modifications
2369    adjacent to the other copyright notices.
2370 F. Include, immediately after the copyright notices, a license notice
2371    giving the public permission to use the Modified Version under the
2372    terms of this License, in the form shown in the Addendum below.
2373 G. Preserve in that license notice the full lists of Invariant Sections
2374    and required Cover Texts given in the Document's license notice.
2375 H. Include an unaltered copy of this License.
2376 I. Preserve the section entitled "History", and its title, and add to
2377    it an item stating at least the title, year, new authors, and
2378    publisher of the Modified Version as given on the Title Page.  If
2379    there is no section entitled "History" in the Document, create one
2380    stating the title, year, authors, and publisher of the Document as
2381    given on its Title Page, then add an item describing the Modified
2382    Version as stated in the previous sentence.
2383 J. Preserve the network location, if any, given in the Document for
2384    public access to a Transparent copy of the Document, and likewise
2385    the network locations given in the Document for previous versions
2386    it was based on.  These may be placed in the "History" section.
2387    You may omit a network location for a work that was published at
2388    least four years before the Document itself, or if the original
2389    publisher of the version it refers to gives permission.
2390 K. In any section entitled "Acknowledgements" or "Dedications",
2391    preserve the section's title, and preserve in the section all the
2392    substance and tone of each of the contributor acknowledgements
2393    and/or dedications given therein.
2394 L. Preserve all the Invariant Sections of the Document,
2395    unaltered in their text and in their titles.  Section numbers
2396    or the equivalent are not considered part of the section titles.
2397 M. Delete any section entitled "Endorsements".  Such a section
2398    may not be included in the Modified Version.
2399 N. Do not retitle any existing section as "Endorsements"
2400    or to conflict in title with any Invariant Section.
2402 If the Modified Version includes new front-matter sections or
2403 appendices that qualify as Secondary Sections and contain no material
2404 copied from the Document, you may at your option designate some or all
2405 of these sections as invariant.  To do this, add their titles to the
2406 list of Invariant Sections in the Modified Version's license notice.
2407 These titles must be distinct from any other section titles.
2409 You may add a section entitled "Endorsements", provided it contains
2410 nothing but endorsements of your Modified Version by various
2411 parties--for example, statements of peer review or that the text has
2412 been approved by an organization as the authoritative definition of a
2413 standard.
2415 You may add a passage of up to five words as a Front-Cover Text, and a
2416 passage of up to 25 words as a Back-Cover Text, to the end of the list
2417 of Cover Texts in the Modified Version.  Only one passage of
2418 Front-Cover Text and one of Back-Cover Text may be added by (or
2419 through arrangements made by) any one entity.  If the Document already
2420 includes a cover text for the same cover, previously added by you or
2421 by arrangement made by the same entity you are acting on behalf of,
2422 you may not add another; but you may replace the old one, on explicit
2423 permission from the previous publisher that added the old one.
2425 The author(s) and publisher(s) of the Document do not by this License
2426 give permission to use their names for publicity for or to assert or
2427 imply endorsement of any Modified Version.
2430 5. COMBINING DOCUMENTS
2432 You may combine the Document with other documents released under this
2433 License, under the terms defined in section 4 above for modified
2434 versions, provided that you include in the combination all of the
2435 Invariant Sections of all of the original documents, unmodified, and
2436 list them all as Invariant Sections of your combined work in its
2437 license notice.
2439 The combined work need only contain one copy of this License, and
2440 multiple identical Invariant Sections may be replaced with a single
2441 copy.  If there are multiple Invariant Sections with the same name but
2442 different contents, make the title of each such section unique by
2443 adding at the end of it, in parentheses, the name of the original
2444 author or publisher of that section if known, or else a unique number.
2445 Make the same adjustment to the section titles in the list of
2446 Invariant Sections in the license notice of the combined work.
2448 In the combination, you must combine any sections entitled "History"
2449 in the various original documents, forming one section entitled
2450 "History"; likewise combine any sections entitled "Acknowledgements",
2451 and any sections entitled "Dedications".  You must delete all sections
2452 entitled "Endorsements."
2455 6. COLLECTIONS OF DOCUMENTS
2457 You may make a collection consisting of the Document and other documents
2458 released under this License, and replace the individual copies of this
2459 License in the various documents with a single copy that is included in
2460 the collection, provided that you follow the rules of this License for
2461 verbatim copying of each of the documents in all other respects.
2463 You may extract a single document from such a collection, and distribute
2464 it individually under this License, provided you insert a copy of this
2465 License into the extracted document, and follow this License in all
2466 other respects regarding verbatim copying of that document.
2469 7. AGGREGATION WITH INDEPENDENT WORKS
2471 A compilation of the Document or its derivatives with other separate
2472 and independent documents or works, in or on a volume of a storage or
2473 distribution medium, does not as a whole count as a Modified Version
2474 of the Document, provided no compilation copyright is claimed for the
2475 compilation.  Such a compilation is called an "aggregate", and this
2476 License does not apply to the other self-contained works thus compiled
2477 with the Document, on account of their being thus compiled, if they
2478 are not themselves derivative works of the Document.
2480 If the Cover Text requirement of section 3 is applicable to these
2481 copies of the Document, then if the Document is less than one quarter
2482 of the entire aggregate, the Document's Cover Texts may be placed on
2483 covers that surround only the Document within the aggregate.
2484 Otherwise they must appear on covers around the whole aggregate.
2487 8. TRANSLATION
2489 Translation is considered a kind of modification, so you may
2490 distribute translations of the Document under the terms of section 4.
2491 Replacing Invariant Sections with translations requires special
2492 permission from their copyright holders, but you may include
2493 translations of some or all Invariant Sections in addition to the
2494 original versions of these Invariant Sections.  You may include a
2495 translation of this License provided that you also include the
2496 original English version of this License.  In case of a disagreement
2497 between the translation and the original English version of this
2498 License, the original English version will prevail.
2501 9. TERMINATION
2503 You may not copy, modify, sublicense, or distribute the Document except
2504 as expressly provided for under this License.  Any other attempt to
2505 copy, modify, sublicense or distribute the Document is void, and will
2506 automatically terminate your rights under this License.  However,
2507 parties who have received copies, or rights, from you under this
2508 License will not have their licenses terminated so long as such
2509 parties remain in full compliance.
2512 10. FUTURE REVISIONS OF THIS LICENSE
2514 The Free Software Foundation may publish new, revised versions
2515 of the GNU Free Documentation License from time to time.  Such new
2516 versions will be similar in spirit to the present version, but may
2517 differ in detail to address new problems or concerns.  See
2518 http://www.gnu.org/copyleft/.
2520 Each version of the License is given a distinguishing version number.
2521 If the Document specifies that a particular numbered version of this
2522 License "or any later version" applies to it, you have the option of
2523 following the terms and conditions either of that specified version or
2524 of any later version that has been published (not as a draft) by the
2525 Free Software Foundation.  If the Document does not specify a version
2526 number of this License, you may choose any version ever published (not
2527 as a draft) by the Free Software Foundation.
2530 ADDENDUM: How to use this License for your documents
2532 To use this License in a document you have written, include a copy of
2533 the License in the document and put the following copyright and
2534 license notices just after the title page:
2536 @smallexample
2537     Copyright (c)  YEAR  YOUR NAME.
2538     Permission is granted to copy, distribute and/or modify this document
2539     under the terms of the GNU Free Documentation License, Version 1.1
2540     or any later version published by the Free Software Foundation;
2541     with the Invariant Sections being LIST THEIR TITLES, with the
2542     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
2543     A copy of the license is included in the section entitled "GNU
2544     Free Documentation License".
2545 @end smallexample
2547 If you have no Invariant Sections, write "with no Invariant Sections"
2548 instead of saying which ones are invariant.  If you have no
2549 Front-Cover Texts, write "no Front-Cover Texts" instead of
2550 "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
2552 If your document contains nontrivial examples of program code, we
2553 recommend releasing these examples in parallel under your choice of
2554 free software license, such as the GNU General Public License,
2555 to permit their use in free software.
2557 @contents
2558 @bye
2560 NEEDS AN INDEX
2562 -T - "traditional BSD style": How is it different?  Should the
2563 differences be documented?
2565 example flat file adds up to 100.01%...
2567 note: time estimates now only go out to one decimal place (0.0), where
2568 they used to extend two (78.67).