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