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