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