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