Penguin
Recent Changes
Annotated edit history of gprof(1) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 GPROF
2 !!!GPROF
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 OPTIONS
7 FILES
8 BUGS
9 SEE ALSO
10 COPYRIGHT
11 ----
12 !!NAME
13
14
15 gprof - display call graph profile data
16 !!SYNOPSIS
17
18
19 gprof [[ -[[abcDhilLsTvwxyz] ] [[
20 -[[ACeEfFJnNOpPqQZ][[''name''] ] [[ -I ''dirs'' ] [[
21 -d[[''num''] ] [[ -k ''from/to'' ] [[ -m ''min-count''
22 ] [[ -t ''table-length'' ] [[
23 --[[no-]annotated-source[[=''name''] ] [[
24 --[[no-]exec-counts[[=''name''] ] [[
25 --[[no-]flat-profile[[=''name''] ] [[
26 --[[no-]graph[[=''name''] ] [[ --[[no-]time=''name''] [[
27 --all-lines ] [[ --brief ] [[ --debug[[=''level''] ] [[
28 --function-ordering ] [[ --file-ordering ] [[
29 --directory-path=''dirs'' ] [[ --display-unused-functions
30 ] [[ --file-format=''name'' ] [[ --file-info ] [[ --help ] [[
31 --line ] [[ --min-count=''n'' ] [[ --no-static ] [[
32 --print-path ] [[ --separate-files ] [[ --static-call-graph ]
33 [[ --sum ] [[ --table-length=''len'' ] [[ --traditional ] [[
34 --version ] [[ --width=''n'' ] [[ --ignore-non-functions ]
35 [[ --demangle[[= ''STYLE'' ] ] [[
36 --no-demangle ] [[ ''image-file'' ] [[ ''profile-file''
37 ... ]
38 !!DESCRIPTION
39
40
41 gprof produces an execution profile of C, Pascal,
42 or Fortran77 programs. The effect of called routines is
43 incorporated in the profile of each caller. The profile data
44 is taken from the call graph profile file (''gmon.out''
45 default) which is created by programs that are compiled with
46 the __-pg__ option of cc, pc, and
47 f77. The __-pg__ option also links in versions
48 of the library routines that are compiled for profiling.
49 Gprof reads the given object file (the default is
50 a.out) and establishes the relation between its
51 symbol table and the call graph profile from
52 ''gmon.out''. If more than one profile file is specified,
53 the gprof output shows the sum of the profile
54 information in the given profile files.
55
56
57 If you use gcc 2.95.x or 3.0 to compile your binaries, you
58 may need to add the __-fprofile-arcs__ to the compile
59 command line in order for the call graphs to be properly
60 stored in gmon.out.
61
62
63 Gprof calculates the amount of time spent in each
64 routine. Next, these times are propagated along the edges of
65 the call graph. Cycles are discovered, and calls into a
66 cycle are made to share the time of the cycle.
67
68
69 Several forms of output are available from the
70 analysis.
71
72
73 The ''flat profile'' shows how much time your program
74 spent in each function, and how many times that function was
75 called. If you simply want to know which functions burn most
76 of the cycles, it is stated concisely here.
77
78
79 The ''call graph'' shows, for each function, which
80 functions called it, which other functions it called, and
81 how many times. There is also an estimate of how much time
82 was spent in the subroutines of each function. This can
83 suggest places where you might try to eliminate function
84 calls that use a lot of time.
85
86
87 The ''annotated source'' listing is a copy of the
88 program's source code, labeled with the number of times each
89 line of the program was executed.
90 !!OPTIONS
91
92
93 These options specify which of several output formats
94 gprof should produce.
95
96
97 Many of these options take an optional ''symspec'' to
98 specify functions to be included or excluded. These options
99 can be specified multiple times, with different symspecs, to
100 include or exclude sets of symbols.
101
102
103 Specifying any of these options overrides the default (__-p
104 -q__), which prints a flat profile and call graph analysis
105 for all functions.
106
107
108 -A[[symspec]
109
110
111 --annotated-source[[=symspec]
112
113
114 The __-A__ option causes gprof to print
115 annotated source code. If ''symspec'' is specified, print
116 output only for matching symbols.
117
118
119 -b
120
121
122 --brief
123
124
125 If the __-b__ option is given, gprof doesn't
126 print the verbose blurbs that try to explain the meaning of
127 all of the fields in the tables. This is useful if you
128 intend to print out the output, or are tired of seeing the
129 blurbs.
130
131
132 -C[[symspec]
133
134
135 --exec-counts[[=symspec]
136
137
138 The __-C__ option causes gprof to print a tally
139 of functions and the number of times each was called. If
140 ''symspec'' is specified, print tally only for matching
141 symbols.
142
143
144 If the profile data file contains basic-block count records,
145 specifying the __-l__ option, along with __-C__, will
146 cause basic-block execution counts to be tallied and
147 displayed.
148
149
150 -i
151
152
153 --file-info
154
155
156 The __-i__ option causes gprof to display
157 summary information about the profile data file(s) and then
158 exit. The number of histogram, call graph, and basic-block
159 count records is displayed.
160
161
162 -I dirs
163
164
165 --directory-path=dirs
166
167
168 The __-I__ option specifies a list of search directories
169 in which to find source files. Environment variable
170 ''GPROF_PATH'' can also be used to convey
171 this information. Used mostly for annotated source
172 output.
173
174
175 -J[[symspec]
176
177
178 --no-annotated-source[[=symspec]
179
180
181 The __-J__ option causes gprof not to print
182 annotated source code. If ''symspec'' is specified,
183 gprof prints annotated source, but excludes
184 matching symbols.
185
186
187 -L
188
189
190 --print-path
191
192
193 Normally, source filenames are printed with the path
194 component suppressed. The __-L__ option causes
195 gprof to print the full pathname of source
196 filenames, which is determined from symbolic debugging
197 information in the image file and is relative to the
198 directory in which the compiler was invoked.
199
200
201 -p[[symspec]
202
203
204 --flat-profile[[=symspec]
205
206
207 The __-p__ option causes gprof to print a flat
208 profile. If ''symspec'' is specified, print flat profile
209 only for matching symbols.
210
211
212 -P[[symspec]
213
214
215 --no-flat-profile[[=symspec]
216
217
218 The __-P__ option causes gprof to suppress
219 printing a flat profile. If ''symspec'' is specified,
220 gprof prints a flat profile, but excludes matching
221 symbols.
222
223
224 -q[[symspec]
225
226
227 --graph[[=symspec]
228
229
230 The __-q__ option causes gprof to print the call
231 graph analysis. If ''symspec'' is specified, print call
232 graph only for matching symbols and their
233 children.
234
235
236 -Q[[symspec]
237
238
239 --no-graph[[=symspec]
240
241
242 The __-Q__ option causes gprof to suppress
243 printing the call graph. If ''symspec'' is specified,
244 gprof prints a call graph, but excludes matching
245 symbols.
246
247
248 -y
249
250
251 --separate-files
252
253
254 This option affects annotated source output only. Normally,
255 gprof prints annotated source files to
256 standard-output. If this option is specified, annotated
257 source for a file named ''path/filename'' is generated in
258 the file ''filename-ann''. If the underlying filesystem
259 would truncate ''filename-ann'' so that it overwrites the
260 original ''filename'', gprof generates annotated
261 source in the file ''filename.ann'' instead (if the
262 original file name has an extension, that extension is
263 ''replaced'' with ''.ann'').
264
265
266 -Z[[symspec]
267
268
269 --no-exec-counts[[=symspec]
270
271
272 The __-Z__ option causes gprof not to print a
273 tally of functions and the number of times each was called.
274 If ''symspec'' is specified, print tally, but exclude
275 matching symbols.
276
277
278 --function-ordering
279
280
281 The __--function-ordering__ option causes gprof
282 to print a suggested function ordering for the program based
283 on profiling data. This option suggests an ordering which
284 may improve paging, tlb and cache behavior for the program
285 on systems which support arbitrary ordering of functions in
286 an executable.
287
288
289 The exact details of how to force the linker to place
290 functions in a particular order is system dependent and out
291 of the scope of this manual.
292
293
294 --file-ordering map_file
295
296
297 The __--file-ordering__ option causes gprof to
298 print a suggested .o link line ordering for the program
299 based on profiling data. This option suggests an ordering
300 which may improve paging, tlb and cache behavior for the
301 program on systems which do not support arbitrary ordering
302 of functions in an executable.
303
304
305 Use of the __-a__ argument is highly recommended with
306 this option.
307
308
309 The ''map_file'' argument is a pathname to a file which
310 provides function name to object file mappings. The format
311 of the file is similar to the output of the program
312 nm.
313
314
315 c-parse.o:00000000 T yyparse
316 c-parse.o:00000004 C yyerrflag
317 c-lang.o:00000000 T maybe_objc_method_name
318 c-lang.o:00000000 T print_lang_statistics
319 c-lang.o:00000000 T recognize_objc_keyword
320 c-decl.o:00000000 T print_lang_identifier
321 c-decl.o:00000000 T print_lang_type
322 ...
323 To create a ''map_file'' with GNU nm, type a command like nm --extern-only --defined-only -v --print-file-name program-name.
324
325
326 -T
327
328
329 --traditional
330
331
332 The __-T__ option causes gprof to print its
333 output in ``traditional'' BSD
334 style.
335
336
337 -w width
338
339
340 --width=width
341
342
343 Sets width of output lines to ''width''. Currently only
344 used when printing the function index at the bottom of the
345 call graph.
346
347
348 -x
349
350
351 --all-lines
352
353
354 This option affects annotated source output only. By
355 default, only the lines at the beginning of a basic-block
356 are annotated. If this option is specified, every line in a
357 basic-block is annotated by repeating the annotation for the
358 first line. This behavior is similar to tcov's
359 __-a__.
360
361
362 --demangle[[=style]
363
364
365 --no-demangle
366
367
368 These options control whether C ++ symbol
369 names should be demangled when printing output. The default
370 is to demangle symbols. The --no-demangle option
371 may be used to turn off demangling. Different compilers have
372 different mangling styles. The optional demangling style
373 argument can be used to choose an appropriate demangling
374 style for your compiler.
375
376
377 __Analysis Options__
378
379
380 -a
381
382
383 --no-static
384
385
386 The __-a__ option causes gprof to suppress the
387 printing of statically declared (private) functions. (These
388 are functions whose names are not listed as global, and
389 which are not visible outside the file/function/block where
390 they were defined.) Time spent in these functions, calls
391 to/from them, etc, will all be attributed to the function
392 that was loaded directly before it in the executable file.
393 This option affects both the flat profile and the call
394 graph.
395
396
397 -c
398
399
400 --static-call-graph
401
402
403 The __-c__ option causes the call graph of the program to
404 be augmented by a heuristic which examines the text space of
405 the object file and identifies function calls in the binary
406 machine code. Since normal call graph records are only
407 generated when functions are entered, this option identifies
408 children that could have been called, but never were. Calls
409 to functions that were not compiled with profiling enabled
410 are also identified, but only if symbol table entries are
411 present for them. Calls to dynamic library routines are
412 typically ''not'' found by this option. Parents or
413 children identified via this heuristic are indicated in the
414 call graph with call counts of __0__.
415
416
417 -D
418
419
420 --ignore-non-functions
421
422
423 The __-D__ option causes gprof to ignore symbols
424 which are not known to be functions. This option will give
425 more accurate profile data on systems where it is supported
426 (Solaris and HPUX for example).
427
428
429 -k from/to
430
431
432 The __-k__ option allows you to delete from the call
433 graph any arcs from symbols matching symspec ''from'' to
434 those matching symspec ''to''.
435
436
437 -l
438
439
440 --line
441
442
443 The __-l__ option enables line-by-line profiling, which
444 causes histogram hits to be charged to individual source
445 code lines, instead of functions. If the program was
446 compiled with basic-block counting enabled, this option will
447 also identify how many times each line of code was executed.
448 While line-by-line profiling can help isolate where in a
449 large function a program is spending its time, it also
450 significantly increases the running time of gprof,
451 and magnifies statistical inaccuracies.
452
453
454 -m num
455
456
457 --min-count=num
458
459
460 This option affects execution count output only. Symbols
461 that are executed less than ''num'' times are
462 suppressed.
463
464
465 -n[[symspec]
466
467
468 --time[[=symspec]
469
470
471 The __-n__ option causes gprof, in its call
472 graph analysis, to only propagate times for symbols matching
473 ''symspec''.
474
475
476 -N[[symspec]
477
478
479 --no-time[[=symspec]
480
481
482 The __-n__ option causes gprof, in its call
483 graph analysis, not to propagate times for symbols matching
484 ''symspec''.
485
486
487 -z
488
489
490 --display-unused-functions
491
492
493 If you give the __-z__ option, gprof will
494 mention all functions in the flat profile, even those that
495 were never called, and that had no time spent in them. This
496 is useful in conjunction with the __-c__ option for
497 discovering which routines were never called.
498
499
500 __Miscellaneous Options__
501
502
503 -d[[num]
504
505
506 --debug[[=num]
507
508
509 The __-d__ ''num'' option specifies debugging options.
510 If ''num'' is not specified, enable all
511 debugging.
512
513
514 -Oname
515
516
517 --file-format=name
518
519
520 Selects the format of the profile data files. Recognized
521 formats are __auto__ (the default), __bsd__,
522 __4.4bsd__, __magic__, and __prof__ (not yet
523 supported).
524
525
526 -s
527
528
529 --sum
530
531
532 The __-s__ option causes gprof to summarize the
533 information in the profile data files it read in, and write
534 out a profile data file called ''gmon.sum'', which
535 contains all the information from the profile data files
536 that gprof read in. The file ''gmon.sum'' may be
537 one of the specified input files; the effect of this is to
538 merge the data in the other input files into
539 ''gmon.sum''.
540
541
542 Eventually you can run gprof again without
543 __-s__ to analyze the cumulative data in the file
544 ''gmon.sum''.
545
546
547 -v
548
549
550 --version
551
552
553 The __-v__ flag causes gprof to print the
554 current version number, and then exit.
555
556
557 __Deprecated Options__
558
559
560 These options have been replaced with newer versions that
561 use symspecs.
562
563
564 -e function_name
565
566
567 The __-e__ ''function'' option tells gprof to
568 not print information about the function
569 ''function_name'' (and its children...) in the call
570 graph. The function will still be listed as a child of any
571 functions that call it, but its index number will be shown
572 as __[[not printed]__. More than one __-e__ option may
573 be given; only one ''function_name'' may be indicated
574 with each __-e__ option.
575
576
577 -E function_name
578
579
580 The -E function option works like the -e
581 option, but time spent in the function (and children who
582 were not called from anywhere else), will not be used to
583 compute the percentages-of-time for the call graph. More
584 than one __-E__ option may be given; only one
585 ''function_name'' may be indicated with each __-E__
586 option.
587
588
589 -f function_name
590
591
592 The __-f__ ''function'' option causes gprof
593 to limit the call graph to the function ''function_name''
594 and its children (and their children...). More than one
595 __-f__ option may be given; only one ''function_name''
596 may be indicated with each __-f__ option.
597
598
599 -F function_name
600
601
602 The __-F__ ''function'' option works like the
603 -f option, but only time spent in the function and
604 its children (and their children...) will be used to
605 determine total-time and percentages-of-time for the call
606 graph. More than one __-F__ option may be given; only one
607 ''function_name'' may be indicated with each __-F__
608 option. The __-F__ option overrides the __-E__
609 option.
610 !!FILES
611
612
613 a.out
614
615
616 the namelist and text space.
617
618
619 gmon.out
620
621
622 dynamic call graph and profile.
623
624
625 gmon.sum
626
627
628 summarized dynamic call graph and profile.
629 !!BUGS
630
631
632 The granularity of the sampling is shown, but remains
633 statistical at best. We assume that the time for each
634 execution of a function can be expressed by the total time
635 for the function divided by the number of times the function
636 is called. Thus the time propagated along the call graph
637 arcs to the function's parents is directly proportional to
638 the number of times that arc is traversed.
639
640
641 Parents that are not themselves profiled will have the time
642 of their profiled children propagated to them, but they will
643 appear to be spontaneously invoked in the call graph
644 listing, and will not have their time propagated further.
645 Similarly, signal catchers, even though profiled, will
646 appear to be spontaneous (although for more obscure
647 reasons). Any profiled children of signal catchers should
648 have their times propagated properly, unless the signal
649 catcher was invoked during the execution of the profiling
650 routine, in which case all is lost.
651
652
653 The profiled program must call exit(2) or return
654 normally for the profiling information to be saved in the
655 ''gmon.out'' file.
656 !!SEE ALSO
657
658
659 monitor(3), profil(2), cc(1),
660 prof(1), and the Info entry for
661 ''gprof''.
662
663
664 ``An Execution Profiler for Modular Programs'', by S.
2 perry 665 Graham, P. Kessler, M. !McKusick; Software - Practice and
1 perry 666 Experience, Vol. 13, pp. 671-685, 1983.
667
668
669 ``gprof: A Call Graph Execution Profiler'', by S. Graham, P.
2 perry 670 Kessler, M. !McKusick; Proceedings of the
1 perry 671 SIGPLAN '82 Symposium on Compiler
672 Construction, SIGPLAN Notices, Vol. 17, No 6,
673 pp. 120-126, June 1982.
674 !!COPYRIGHT
675
676
677 Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001 Free Software
678 Foundation, Inc.
679
680
681 Permission is granted to copy, distribute and/or modify this
682 document under the terms of the GNU Free
683 Documentation License, Version 1.1 or any later version
684 published by the Free Software Foundation; with no Invariant
685 Sections, with no Front-Cover Texts, and with no Back-Cover
686 Texts. A copy of the license is included in the section
687 entitled `` GNU Free Documentation
688 License''.
689 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.