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