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