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