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