Merge branch 'vendor/GCC50'
[dragonfly.git] / contrib / binutils-2.24 / gprof / gprof.1
1 .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
2 .\"
3 .\" Standard preamble:
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
6 .if t .sp .5v
7 .if n .sp
8 ..
9 .de Vb \" Begin verbatim text
10 .ft CW
11 .nf
12 .ne \\$1
13 ..
14 .de Ve \" End verbatim text
15 .ft R
16 .fi
17 ..
18 .\" Set up some character translations and predefined strings.  \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
24 .tr \(*W-
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
26 .ie n \{\
27 .    ds -- \(*W-
28 .    ds PI pi
29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
31 .    ds L" ""
32 .    ds R" ""
33 .    ds C` ""
34 .    ds C' ""
35 'br\}
36 .el\{\
37 .    ds -- \|\(em\|
38 .    ds PI \(*p
39 .    ds L" ``
40 .    ds R" ''
41 'br\}
42 .\"
43 .\" Escape single quotes in literal strings from groff's Unicode transform.
44 .ie \n(.g .ds Aq \(aq
45 .el       .ds Aq '
46 .\"
47 .\" If the F register is turned on, we'll generate index entries on stderr for
48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
50 .\" output yourself in some meaningful fashion.
51 .ie \nF \{\
52 .    de IX
53 .    tm Index:\\$1\t\\n%\t"\\$2"
54 ..
55 .    nr % 0
56 .    rr F
57 .\}
58 .el \{\
59 .    de IX
60 ..
61 .\}
62 .\"
63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
65 .    \" fudge factors for nroff and troff
66 .if n \{\
67 .    ds #H 0
68 .    ds #V .8m
69 .    ds #F .3m
70 .    ds #[ \f1
71 .    ds #] \fP
72 .\}
73 .if t \{\
74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75 .    ds #V .6m
76 .    ds #F 0
77 .    ds #[ \&
78 .    ds #] \&
79 .\}
80 .    \" simple accents for nroff and troff
81 .if n \{\
82 .    ds ' \&
83 .    ds ` \&
84 .    ds ^ \&
85 .    ds , \&
86 .    ds ~ ~
87 .    ds /
88 .\}
89 .if t \{\
90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
96 .\}
97 .    \" troff and (daisy-wheel) nroff accents
98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105 .ds ae a\h'-(\w'a'u*4/10)'e
106 .ds Ae A\h'-(\w'A'u*4/10)'E
107 .    \" corrections for vroff
108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
110 .    \" for low resolution devices (crt and lpr)
111 .if \n(.H>23 .if \n(.V>19 \
112 \{\
113 .    ds : e
114 .    ds 8 ss
115 .    ds o a
116 .    ds d- d\h'-1'\(ga
117 .    ds D- D\h'-1'\(hy
118 .    ds th \o'bp'
119 .    ds Th \o'LP'
120 .    ds ae ae
121 .    ds Ae AE
122 .\}
123 .rm #[ #] #H #V #F C
124 .\" ========================================================================
125 .\"
126 .IX Title "GPROF 1"
127 .TH GPROF 1 "2013-11-18" "binutils-2.23.91" "GNU"
128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
129 .\" way too many mistakes in technical documents.
130 .if n .ad l
131 .nh
132 .SH "NAME"
133 gprof \- display call graph profile data
134 .SH "SYNOPSIS"
135 .IX Header "SYNOPSIS"
136 gprof [ \-[abcDhilLrsTvwxyz] ] [ \-[ACeEfFJnNOpPqQZ][\fIname\fR] ] 
137  [ \-I \fIdirs\fR ] [ \-d[\fInum\fR] ] [ \-k \fIfrom/to\fR ]
138  [ \-m \fImin-count\fR ] [ \-R \fImap_file\fR ] [ \-t \fItable-length\fR ]
139  [ \-\-[no\-]annotated\-source[=\fIname\fR] ] 
140  [ \-\-[no\-]exec\-counts[=\fIname\fR] ]
141  [ \-\-[no\-]flat\-profile[=\fIname\fR] ] [ \-\-[no\-]graph[=\fIname\fR] ]
142  [ \-\-[no\-]time=\fIname\fR] [ \-\-all\-lines ] [ \-\-brief ] 
143  [ \-\-debug[=\fIlevel\fR] ] [ \-\-function\-ordering ] 
144  [ \-\-file\-ordering \fImap_file\fR ] [ \-\-directory\-path=\fIdirs\fR ]
145  [ \-\-display\-unused\-functions ] [ \-\-file\-format=\fIname\fR ]
146  [ \-\-file\-info ] [ \-\-help ] [ \-\-line ] [ \-\-min\-count=\fIn\fR ]
147  [ \-\-no\-static ] [ \-\-print\-path ] [ \-\-separate\-files ]
148  [ \-\-static\-call\-graph ] [ \-\-sum ] [ \-\-table\-length=\fIlen\fR ]
149  [ \-\-traditional ] [ \-\-version ] [ \-\-width=\fIn\fR ]
150  [ \-\-ignore\-non\-functions ] [ \-\-demangle[=\fI\s-1STYLE\s0\fR] ]
151  [ \-\-no\-demangle ] [\-\-external\-symbol\-table=name] 
152  [ \fIimage-file\fR ] [ \fIprofile-file\fR ... ]
153 .SH "DESCRIPTION"
154 .IX Header "DESCRIPTION"
155 \&\f(CW\*(C`gprof\*(C'\fR produces an execution profile of C, Pascal, or Fortran77 
156 programs.  The effect of called routines is incorporated in the profile 
157 of each caller.  The profile data is taken from the call graph profile file
158 (\fIgmon.out\fR default) which is created by programs
159 that are compiled with the \fB\-pg\fR option of
160 \&\f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`pc\*(C'\fR, and \f(CW\*(C`f77\*(C'\fR.
161 The \fB\-pg\fR option also links in versions of the library routines
162 that are compiled for profiling.  \f(CW\*(C`Gprof\*(C'\fR reads the given object 
163 file (the default is \f(CW\*(C`a.out\*(C'\fR) and establishes the relation between
164 its symbol table and the call graph profile from \fIgmon.out\fR.
165 If more than one profile file is specified, the \f(CW\*(C`gprof\*(C'\fR
166 output shows the sum of the profile information in the given profile files.
167 .PP
168 \&\f(CW\*(C`Gprof\*(C'\fR calculates the amount of time spent in each routine.
169 Next, these times are propagated along the edges of the call graph.
170 Cycles are discovered, and calls into a cycle are made to share the time
171 of the cycle.
172 .PP
173 Several forms of output are available from the analysis.
174 .PP
175 The \fIflat profile\fR shows how much time your program spent in each function,
176 and how many times that function was called.  If you simply want to know
177 which functions burn most of the cycles, it is stated concisely here.
178 .PP
179 The \fIcall graph\fR shows, for each function, which functions called it, which
180 other functions it called, and how many times.  There is also an estimate
181 of how much time was spent in the subroutines of each function.  This can
182 suggest places where you might try to eliminate function calls that use a
183 lot of time.
184 .PP
185 The \fIannotated source\fR listing is a copy of the program's
186 source code, labeled with the number of times each line of the
187 program was executed.
188 .SH "OPTIONS"
189 .IX Header "OPTIONS"
190 These options specify which of several output formats
191 \&\f(CW\*(C`gprof\*(C'\fR should produce.
192 .PP
193 Many of these options take an optional \fIsymspec\fR to specify
194 functions to be included or excluded.  These options can be
195 specified multiple times, with different symspecs, to include
196 or exclude sets of symbols.
197 .PP
198 Specifying any of these options overrides the default (\fB\-p \-q\fR),
199 which prints a flat profile and call graph analysis
200 for all functions.
201 .ie n .IP """\-A[\f(CIsymspec\f(CW]""" 4
202 .el .IP "\f(CW\-A[\f(CIsymspec\f(CW]\fR" 4
203 .IX Item "-A[symspec]"
204 .PD 0
205 .ie n .IP """\-\-annotated\-source[=\f(CIsymspec\f(CW]""" 4
206 .el .IP "\f(CW\-\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4
207 .IX Item "--annotated-source[=symspec]"
208 .PD
209 The \fB\-A\fR option causes \f(CW\*(C`gprof\*(C'\fR to print annotated source code.
210 If \fIsymspec\fR is specified, print output only for matching symbols.
211 .ie n .IP """\-b""" 4
212 .el .IP "\f(CW\-b\fR" 4
213 .IX Item "-b"
214 .PD 0
215 .ie n .IP """\-\-brief""" 4
216 .el .IP "\f(CW\-\-brief\fR" 4
217 .IX Item "--brief"
218 .PD
219 If the \fB\-b\fR option is given, \f(CW\*(C`gprof\*(C'\fR doesn't print the
220 verbose blurbs that try to explain the meaning of all of the fields in
221 the tables.  This is useful if you intend to print out the output, or
222 are tired of seeing the blurbs.
223 .ie n .IP """\-C[\f(CIsymspec\f(CW]""" 4
224 .el .IP "\f(CW\-C[\f(CIsymspec\f(CW]\fR" 4
225 .IX Item "-C[symspec]"
226 .PD 0
227 .ie n .IP """\-\-exec\-counts[=\f(CIsymspec\f(CW]""" 4
228 .el .IP "\f(CW\-\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4
229 .IX Item "--exec-counts[=symspec]"
230 .PD
231 The \fB\-C\fR option causes \f(CW\*(C`gprof\*(C'\fR to
232 print a tally of functions and the number of times each was called.
233 If \fIsymspec\fR is specified, print tally only for matching symbols.
234 .Sp
235 If the profile data file contains basic-block count records, specifying
236 the \fB\-l\fR option, along with \fB\-C\fR, will cause basic-block
237 execution counts to be tallied and displayed.
238 .ie n .IP """\-i""" 4
239 .el .IP "\f(CW\-i\fR" 4
240 .IX Item "-i"
241 .PD 0
242 .ie n .IP """\-\-file\-info""" 4
243 .el .IP "\f(CW\-\-file\-info\fR" 4
244 .IX Item "--file-info"
245 .PD
246 The \fB\-i\fR option causes \f(CW\*(C`gprof\*(C'\fR to display summary information
247 about the profile data file(s) and then exit.  The number of histogram,
248 call graph, and basic-block count records is displayed.
249 .ie n .IP """\-I \f(CIdirs\f(CW""" 4
250 .el .IP "\f(CW\-I \f(CIdirs\f(CW\fR" 4
251 .IX Item "-I dirs"
252 .PD 0
253 .ie n .IP """\-\-directory\-path=\f(CIdirs\f(CW""" 4
254 .el .IP "\f(CW\-\-directory\-path=\f(CIdirs\f(CW\fR" 4
255 .IX Item "--directory-path=dirs"
256 .PD
257 The \fB\-I\fR option specifies a list of search directories in
258 which to find source files.  Environment variable \fI\s-1GPROF_PATH\s0\fR
259 can also be used to convey this information.
260 Used mostly for annotated source output.
261 .ie n .IP """\-J[\f(CIsymspec\f(CW]""" 4
262 .el .IP "\f(CW\-J[\f(CIsymspec\f(CW]\fR" 4
263 .IX Item "-J[symspec]"
264 .PD 0
265 .ie n .IP """\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]""" 4
266 .el .IP "\f(CW\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4
267 .IX Item "--no-annotated-source[=symspec]"
268 .PD
269 The \fB\-J\fR option causes \f(CW\*(C`gprof\*(C'\fR not to
270 print annotated source code.
271 If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints annotated source,
272 but excludes matching symbols.
273 .ie n .IP """\-L""" 4
274 .el .IP "\f(CW\-L\fR" 4
275 .IX Item "-L"
276 .PD 0
277 .ie n .IP """\-\-print\-path""" 4
278 .el .IP "\f(CW\-\-print\-path\fR" 4
279 .IX Item "--print-path"
280 .PD
281 Normally, source filenames are printed with the path
282 component suppressed.  The \fB\-L\fR option causes \f(CW\*(C`gprof\*(C'\fR
283 to print the full pathname of
284 source filenames, which is determined
285 from symbolic debugging information in the image file
286 and is relative to the directory in which the compiler
287 was invoked.
288 .ie n .IP """\-p[\f(CIsymspec\f(CW]""" 4
289 .el .IP "\f(CW\-p[\f(CIsymspec\f(CW]\fR" 4
290 .IX Item "-p[symspec]"
291 .PD 0
292 .ie n .IP """\-\-flat\-profile[=\f(CIsymspec\f(CW]""" 4
293 .el .IP "\f(CW\-\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4
294 .IX Item "--flat-profile[=symspec]"
295 .PD
296 The \fB\-p\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a flat profile.
297 If \fIsymspec\fR is specified, print flat profile only for matching symbols.
298 .ie n .IP """\-P[\f(CIsymspec\f(CW]""" 4
299 .el .IP "\f(CW\-P[\f(CIsymspec\f(CW]\fR" 4
300 .IX Item "-P[symspec]"
301 .PD 0
302 .ie n .IP """\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]""" 4
303 .el .IP "\f(CW\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4
304 .IX Item "--no-flat-profile[=symspec]"
305 .PD
306 The \fB\-P\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing a flat profile.
307 If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a flat profile,
308 but excludes matching symbols.
309 .ie n .IP """\-q[\f(CIsymspec\f(CW]""" 4
310 .el .IP "\f(CW\-q[\f(CIsymspec\f(CW]\fR" 4
311 .IX Item "-q[symspec]"
312 .PD 0
313 .ie n .IP """\-\-graph[=\f(CIsymspec\f(CW]""" 4
314 .el .IP "\f(CW\-\-graph[=\f(CIsymspec\f(CW]\fR" 4
315 .IX Item "--graph[=symspec]"
316 .PD
317 The \fB\-q\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis.
318 If \fIsymspec\fR is specified, print call graph only for matching symbols
319 and their children.
320 .ie n .IP """\-Q[\f(CIsymspec\f(CW]""" 4
321 .el .IP "\f(CW\-Q[\f(CIsymspec\f(CW]\fR" 4
322 .IX Item "-Q[symspec]"
323 .PD 0
324 .ie n .IP """\-\-no\-graph[=\f(CIsymspec\f(CW]""" 4
325 .el .IP "\f(CW\-\-no\-graph[=\f(CIsymspec\f(CW]\fR" 4
326 .IX Item "--no-graph[=symspec]"
327 .PD
328 The \fB\-Q\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing the
329 call graph.
330 If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a call graph,
331 but excludes matching symbols.
332 .ie n .IP """\-t""" 4
333 .el .IP "\f(CW\-t\fR" 4
334 .IX Item "-t"
335 .PD 0
336 .ie n .IP """\-\-table\-length=\f(CInum\f(CW""" 4
337 .el .IP "\f(CW\-\-table\-length=\f(CInum\f(CW\fR" 4
338 .IX Item "--table-length=num"
339 .PD
340 The \fB\-t\fR option causes the \fInum\fR most active source lines in
341 each source file to be listed when source annotation is enabled.  The
342 default is 10.
343 .ie n .IP """\-y""" 4
344 .el .IP "\f(CW\-y\fR" 4
345 .IX Item "-y"
346 .PD 0
347 .ie n .IP """\-\-separate\-files""" 4
348 .el .IP "\f(CW\-\-separate\-files\fR" 4
349 .IX Item "--separate-files"
350 .PD
351 This option affects annotated source output only.
352 Normally, \f(CW\*(C`gprof\*(C'\fR prints annotated source files
353 to standard-output.  If this option is specified,
354 annotated source for a file named \fIpath/\fIfilename\fI\fR
355 is generated in the file \fI\fIfilename\fI\-ann\fR.  If the underlying
356 file system would truncate \fI\fIfilename\fI\-ann\fR so that it
357 overwrites the original \fI\fIfilename\fI\fR, \f(CW\*(C`gprof\*(C'\fR generates
358 annotated source in the file \fI\fIfilename\fI.ann\fR instead (if the
359 original file name has an extension, that extension is \fIreplaced\fR
360 with \fI.ann\fR).
361 .ie n .IP """\-Z[\f(CIsymspec\f(CW]""" 4
362 .el .IP "\f(CW\-Z[\f(CIsymspec\f(CW]\fR" 4
363 .IX Item "-Z[symspec]"
364 .PD 0
365 .ie n .IP """\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]""" 4
366 .el .IP "\f(CW\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4
367 .IX Item "--no-exec-counts[=symspec]"
368 .PD
369 The \fB\-Z\fR option causes \f(CW\*(C`gprof\*(C'\fR not to
370 print a tally of functions and the number of times each was called.
371 If \fIsymspec\fR is specified, print tally, but exclude matching symbols.
372 .ie n .IP """\-r""" 4
373 .el .IP "\f(CW\-r\fR" 4
374 .IX Item "-r"
375 .PD 0
376 .ie n .IP """\-\-function\-ordering""" 4
377 .el .IP "\f(CW\-\-function\-ordering\fR" 4
378 .IX Item "--function-ordering"
379 .PD
380 The \fB\-\-function\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a
381 suggested function ordering for the program based on profiling data.
382 This option suggests an ordering which may improve paging, tlb and
383 cache behavior for the program on systems which support arbitrary
384 ordering of functions in an executable.
385 .Sp
386 The exact details of how to force the linker to place functions
387 in a particular order is system dependent and out of the scope of this
388 manual.
389 .ie n .IP """\-R \f(CImap_file\f(CW""" 4
390 .el .IP "\f(CW\-R \f(CImap_file\f(CW\fR" 4
391 .IX Item "-R map_file"
392 .PD 0
393 .ie n .IP """\-\-file\-ordering \f(CImap_file\f(CW""" 4
394 .el .IP "\f(CW\-\-file\-ordering \f(CImap_file\f(CW\fR" 4
395 .IX Item "--file-ordering map_file"
396 .PD
397 The \fB\-\-file\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a
398 suggested .o link line ordering for the program based on profiling data.
399 This option suggests an ordering which may improve paging, tlb and
400 cache behavior for the program on systems which do not support arbitrary
401 ordering of functions in an executable.
402 .Sp
403 Use of the \fB\-a\fR argument is highly recommended with this option.
404 .Sp
405 The \fImap_file\fR argument is a pathname to a file which provides
406 function name to object file mappings.  The format of the file is similar to
407 the output of the program \f(CW\*(C`nm\*(C'\fR.
408 .Sp
409 .Vb 8
410 \&        c\-parse.o:00000000 T yyparse
411 \&        c\-parse.o:00000004 C yyerrflag
412 \&        c\-lang.o:00000000 T maybe_objc_method_name
413 \&        c\-lang.o:00000000 T print_lang_statistics
414 \&        c\-lang.o:00000000 T recognize_objc_keyword
415 \&        c\-decl.o:00000000 T print_lang_identifier
416 \&        c\-decl.o:00000000 T print_lang_type
417 \&        ...
418 .Ve
419 .Sp
420 To create a \fImap_file\fR with \s-1GNU\s0 \f(CW\*(C`nm\*(C'\fR, type a command like
421 \&\f(CW\*(C`nm \-\-extern\-only \-\-defined\-only \-v \-\-print\-file\-name program\-name\*(C'\fR.
422 .ie n .IP """\-T""" 4
423 .el .IP "\f(CW\-T\fR" 4
424 .IX Item "-T"
425 .PD 0
426 .ie n .IP """\-\-traditional""" 4
427 .el .IP "\f(CW\-\-traditional\fR" 4
428 .IX Item "--traditional"
429 .PD
430 The \fB\-T\fR option causes \f(CW\*(C`gprof\*(C'\fR to print its output in
431 \&\*(L"traditional\*(R" \s-1BSD\s0 style.
432 .ie n .IP """\-w \f(CIwidth\f(CW""" 4
433 .el .IP "\f(CW\-w \f(CIwidth\f(CW\fR" 4
434 .IX Item "-w width"
435 .PD 0
436 .ie n .IP """\-\-width=\f(CIwidth\f(CW""" 4
437 .el .IP "\f(CW\-\-width=\f(CIwidth\f(CW\fR" 4
438 .IX Item "--width=width"
439 .PD
440 Sets width of output lines to \fIwidth\fR.
441 Currently only used when printing the function index at the bottom
442 of the call graph.
443 .ie n .IP """\-x""" 4
444 .el .IP "\f(CW\-x\fR" 4
445 .IX Item "-x"
446 .PD 0
447 .ie n .IP """\-\-all\-lines""" 4
448 .el .IP "\f(CW\-\-all\-lines\fR" 4
449 .IX Item "--all-lines"
450 .PD
451 This option affects annotated source output only.
452 By default, only the lines at the beginning of a basic-block
453 are annotated.  If this option is specified, every line in
454 a basic-block is annotated by repeating the annotation for the
455 first line.  This behavior is similar to \f(CW\*(C`tcov\*(C'\fR's \fB\-a\fR.
456 .ie n .IP """\-\-demangle[=\f(CIstyle\f(CW]""" 4
457 .el .IP "\f(CW\-\-demangle[=\f(CIstyle\f(CW]\fR" 4
458 .IX Item "--demangle[=style]"
459 .PD 0
460 .ie n .IP """\-\-no\-demangle""" 4
461 .el .IP "\f(CW\-\-no\-demangle\fR" 4
462 .IX Item "--no-demangle"
463 .PD
464 These options control whether \*(C+ symbol names should be demangled when
465 printing output.  The default is to demangle symbols.  The
466 \&\f(CW\*(C`\-\-no\-demangle\*(C'\fR option may be used to turn off demangling. Different 
467 compilers have different mangling styles.  The optional demangling style 
468 argument can be used to choose an appropriate demangling style for your 
469 compiler.
470 .SS "Analysis Options"
471 .IX Subsection "Analysis Options"
472 .ie n .IP """\-a""" 4
473 .el .IP "\f(CW\-a\fR" 4
474 .IX Item "-a"
475 .PD 0
476 .ie n .IP """\-\-no\-static""" 4
477 .el .IP "\f(CW\-\-no\-static\fR" 4
478 .IX Item "--no-static"
479 .PD
480 The \fB\-a\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress the printing of
481 statically declared (private) functions.  (These are functions whose
482 names are not listed as global, and which are not visible outside the
483 file/function/block where they were defined.)  Time spent in these
484 functions, calls to/from them, etc., will all be attributed to the
485 function that was loaded directly before it in the executable file.
486 This option affects both the flat profile and the call graph.
487 .ie n .IP """\-c""" 4
488 .el .IP "\f(CW\-c\fR" 4
489 .IX Item "-c"
490 .PD 0
491 .ie n .IP """\-\-static\-call\-graph""" 4
492 .el .IP "\f(CW\-\-static\-call\-graph\fR" 4
493 .IX Item "--static-call-graph"
494 .PD
495 The \fB\-c\fR option causes the call graph of the program to be
496 augmented by a heuristic which examines the text space of the object
497 file and identifies function calls in the binary machine code.
498 Since normal call graph records are only generated when functions are
499 entered, this option identifies children that could have been called,
500 but never were.  Calls to functions that were not compiled with
501 profiling enabled are also identified, but only if symbol table
502 entries are present for them.
503 Calls to dynamic library routines are typically \fInot\fR found
504 by this option.
505 Parents or children identified via this heuristic
506 are indicated in the call graph with call counts of \fB0\fR.
507 .ie n .IP """\-D""" 4
508 .el .IP "\f(CW\-D\fR" 4
509 .IX Item "-D"
510 .PD 0
511 .ie n .IP """\-\-ignore\-non\-functions""" 4
512 .el .IP "\f(CW\-\-ignore\-non\-functions\fR" 4
513 .IX Item "--ignore-non-functions"
514 .PD
515 The \fB\-D\fR option causes \f(CW\*(C`gprof\*(C'\fR to ignore symbols which
516 are not known to be functions.  This option will give more accurate
517 profile data on systems where it is supported (Solaris and \s-1HPUX\s0 for
518 example).
519 .ie n .IP """\-k \f(CIfrom\f(CW/\f(CIto\f(CW""" 4
520 .el .IP "\f(CW\-k \f(CIfrom\f(CW/\f(CIto\f(CW\fR" 4
521 .IX Item "-k from/to"
522 The \fB\-k\fR option allows you to delete from the call graph any arcs from
523 symbols matching symspec \fIfrom\fR to those matching symspec \fIto\fR.
524 .ie n .IP """\-l""" 4
525 .el .IP "\f(CW\-l\fR" 4
526 .IX Item "-l"
527 .PD 0
528 .ie n .IP """\-\-line""" 4
529 .el .IP "\f(CW\-\-line\fR" 4
530 .IX Item "--line"
531 .PD
532 The \fB\-l\fR option enables line-by-line profiling, which causes
533 histogram hits to be charged to individual source code lines,
534 instead of functions.  This feature only works with programs compiled
535 by older versions of the \f(CW\*(C`gcc\*(C'\fR compiler.  Newer versions of
536 \&\f(CW\*(C`gcc\*(C'\fR are designed to work with the \f(CW\*(C`gcov\*(C'\fR tool instead.
537 .Sp
538 If the program was compiled with basic-block counting enabled,
539 this option will also identify how many times each line of
540 code was executed.
541 While line-by-line profiling can help isolate where in a large function
542 a program is spending its time, it also significantly increases
543 the running time of \f(CW\*(C`gprof\*(C'\fR, and magnifies statistical
544 inaccuracies.
545 .ie n .IP """\-m \f(CInum\f(CW""" 4
546 .el .IP "\f(CW\-m \f(CInum\f(CW\fR" 4
547 .IX Item "-m num"
548 .PD 0
549 .ie n .IP """\-\-min\-count=\f(CInum\f(CW""" 4
550 .el .IP "\f(CW\-\-min\-count=\f(CInum\f(CW\fR" 4
551 .IX Item "--min-count=num"
552 .PD
553 This option affects execution count output only.
554 Symbols that are executed less than \fInum\fR times are suppressed.
555 .ie n .IP """\-n\f(CIsymspec\f(CW""" 4
556 .el .IP "\f(CW\-n\f(CIsymspec\f(CW\fR" 4
557 .IX Item "-nsymspec"
558 .PD 0
559 .ie n .IP """\-\-time=\f(CIsymspec\f(CW""" 4
560 .el .IP "\f(CW\-\-time=\f(CIsymspec\f(CW\fR" 4
561 .IX Item "--time=symspec"
562 .PD
563 The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis,
564 to only propagate times for symbols matching \fIsymspec\fR.
565 .ie n .IP """\-N\f(CIsymspec\f(CW""" 4
566 .el .IP "\f(CW\-N\f(CIsymspec\f(CW\fR" 4
567 .IX Item "-Nsymspec"
568 .PD 0
569 .ie n .IP """\-\-no\-time=\f(CIsymspec\f(CW""" 4
570 .el .IP "\f(CW\-\-no\-time=\f(CIsymspec\f(CW\fR" 4
571 .IX Item "--no-time=symspec"
572 .PD
573 The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis,
574 not to propagate times for symbols matching \fIsymspec\fR.
575 .ie n .IP """\-S\f(CIfilename\f(CW""" 4
576 .el .IP "\f(CW\-S\f(CIfilename\f(CW\fR" 4
577 .IX Item "-Sfilename"
578 .PD 0
579 .ie n .IP """\-\-external\-symbol\-table=\f(CIfilename\f(CW""" 4
580 .el .IP "\f(CW\-\-external\-symbol\-table=\f(CIfilename\f(CW\fR" 4
581 .IX Item "--external-symbol-table=filename"
582 .PD
583 The \fB\-S\fR option causes \f(CW\*(C`gprof\*(C'\fR to read an external symbol table
584 file, such as \fI/proc/kallsyms\fR, rather than read the symbol table 
585 from the given object file (the default is \f(CW\*(C`a.out\*(C'\fR). This is useful 
586 for profiling kernel modules.
587 .ie n .IP """\-z""" 4
588 .el .IP "\f(CW\-z\fR" 4
589 .IX Item "-z"
590 .PD 0
591 .ie n .IP """\-\-display\-unused\-functions""" 4
592 .el .IP "\f(CW\-\-display\-unused\-functions\fR" 4
593 .IX Item "--display-unused-functions"
594 .PD
595 If you give the \fB\-z\fR option, \f(CW\*(C`gprof\*(C'\fR will mention all
596 functions in the flat profile, even those that were never called, and
597 that had no time spent in them.  This is useful in conjunction with the
598 \&\fB\-c\fR option for discovering which routines were never called.
599 .SS "Miscellaneous Options"
600 .IX Subsection "Miscellaneous Options"
601 .ie n .IP """\-d[\f(CInum\f(CW]""" 4
602 .el .IP "\f(CW\-d[\f(CInum\f(CW]\fR" 4
603 .IX Item "-d[num]"
604 .PD 0
605 .ie n .IP """\-\-debug[=\f(CInum\f(CW]""" 4
606 .el .IP "\f(CW\-\-debug[=\f(CInum\f(CW]\fR" 4
607 .IX Item "--debug[=num]"
608 .PD
609 The \fB\-d\fR \fInum\fR option specifies debugging options.
610 If \fInum\fR is not specified, enable all debugging.
611 .ie n .IP """\-h""" 4
612 .el .IP "\f(CW\-h\fR" 4
613 .IX Item "-h"
614 .PD 0
615 .ie n .IP """\-\-help""" 4
616 .el .IP "\f(CW\-\-help\fR" 4
617 .IX Item "--help"
618 .PD
619 The \fB\-h\fR option prints command line usage.
620 .ie n .IP """\-O\f(CIname\f(CW""" 4
621 .el .IP "\f(CW\-O\f(CIname\f(CW\fR" 4
622 .IX Item "-Oname"
623 .PD 0
624 .ie n .IP """\-\-file\-format=\f(CIname\f(CW""" 4
625 .el .IP "\f(CW\-\-file\-format=\f(CIname\f(CW\fR" 4
626 .IX Item "--file-format=name"
627 .PD
628 Selects the format of the profile data files.  Recognized formats are
629 \&\fBauto\fR (the default), \fBbsd\fR, \fB4.4bsd\fR, \fBmagic\fR, and
630 \&\fBprof\fR (not yet supported).
631 .ie n .IP """\-s""" 4
632 .el .IP "\f(CW\-s\fR" 4
633 .IX Item "-s"
634 .PD 0
635 .ie n .IP """\-\-sum""" 4
636 .el .IP "\f(CW\-\-sum\fR" 4
637 .IX Item "--sum"
638 .PD
639 The \fB\-s\fR option causes \f(CW\*(C`gprof\*(C'\fR to summarize the information
640 in the profile data files it read in, and write out a profile data
641 file called \fIgmon.sum\fR, which contains all the information from
642 the profile data files that \f(CW\*(C`gprof\*(C'\fR read in.  The file \fIgmon.sum\fR
643 may be one of the specified input files; the effect of this is to
644 merge the data in the other input files into \fIgmon.sum\fR.
645 .Sp
646 Eventually you can run \f(CW\*(C`gprof\*(C'\fR again without \fB\-s\fR to analyze the
647 cumulative data in the file \fIgmon.sum\fR.
648 .ie n .IP """\-v""" 4
649 .el .IP "\f(CW\-v\fR" 4
650 .IX Item "-v"
651 .PD 0
652 .ie n .IP """\-\-version""" 4
653 .el .IP "\f(CW\-\-version\fR" 4
654 .IX Item "--version"
655 .PD
656 The \fB\-v\fR flag causes \f(CW\*(C`gprof\*(C'\fR to print the current version
657 number, and then exit.
658 .SS "Deprecated Options"
659 .IX Subsection "Deprecated Options"
660 These options have been replaced with newer versions that use symspecs.
661 .ie n .IP """\-e \f(CIfunction_name\f(CW""" 4
662 .el .IP "\f(CW\-e \f(CIfunction_name\f(CW\fR" 4
663 .IX Item "-e function_name"
664 The \fB\-e\fR \fIfunction\fR option tells \f(CW\*(C`gprof\*(C'\fR to not print
665 information about the function \fIfunction_name\fR (and its
666 children...) in the call graph.  The function will still be listed
667 as a child of any functions that call it, but its index number will be
668 shown as \fB[not printed]\fR.  More than one \fB\-e\fR option may be
669 given; only one \fIfunction_name\fR may be indicated with each \fB\-e\fR
670 option.
671 .ie n .IP """\-E \f(CIfunction_name\f(CW""" 4
672 .el .IP "\f(CW\-E \f(CIfunction_name\f(CW\fR" 4
673 .IX Item "-E function_name"
674 The \f(CW\*(C`\-E \f(CIfunction\f(CW\*(C'\fR option works like the \f(CW\*(C`\-e\*(C'\fR option, but
675 time spent in the function (and children who were not called from
676 anywhere else), will not be used to compute the percentages-of-time for
677 the call graph.  More than one \fB\-E\fR option may be given; only one
678 \&\fIfunction_name\fR may be indicated with each \fB\-E\fR option.
679 .ie n .IP """\-f \f(CIfunction_name\f(CW""" 4
680 .el .IP "\f(CW\-f \f(CIfunction_name\f(CW\fR" 4
681 .IX Item "-f function_name"
682 The \fB\-f\fR \fIfunction\fR option causes \f(CW\*(C`gprof\*(C'\fR to limit the
683 call graph to the function \fIfunction_name\fR and its children (and
684 their children...).  More than one \fB\-f\fR option may be given;
685 only one \fIfunction_name\fR may be indicated with each \fB\-f\fR
686 option.
687 .ie n .IP """\-F \f(CIfunction_name\f(CW""" 4
688 .el .IP "\f(CW\-F \f(CIfunction_name\f(CW\fR" 4
689 .IX Item "-F function_name"
690 The \fB\-F\fR \fIfunction\fR option works like the \f(CW\*(C`\-f\*(C'\fR option, but
691 only time spent in the function and its children (and their
692 children...) will be used to determine total-time and
693 percentages-of-time for the call graph.  More than one \fB\-F\fR option
694 may be given; only one \fIfunction_name\fR may be indicated with each
695 \&\fB\-F\fR option.  The \fB\-F\fR option overrides the \fB\-E\fR option.
696 .SH "FILES"
697 .IX Header "FILES"
698 .ie n .IP """\f(CIa.out\f(CW""" 4
699 .el .IP "\f(CW\f(CIa.out\f(CW\fR" 4
700 .IX Item "a.out"
701 the namelist and text space.
702 .ie n .IP """\f(CIgmon.out\f(CW""" 4
703 .el .IP "\f(CW\f(CIgmon.out\f(CW\fR" 4
704 .IX Item "gmon.out"
705 dynamic call graph and profile.
706 .ie n .IP """\f(CIgmon.sum\f(CW""" 4
707 .el .IP "\f(CW\f(CIgmon.sum\f(CW\fR" 4
708 .IX Item "gmon.sum"
709 summarized dynamic call graph and profile.
710 .SH "BUGS"
711 .IX Header "BUGS"
712 The granularity of the sampling is shown, but remains
713 statistical at best.
714 We assume that the time for each execution of a function
715 can be expressed by the total time for the function divided
716 by the number of times the function is called.
717 Thus the time propagated along the call graph arcs to the function's
718 parents is directly proportional to the number of times that
719 arc is traversed.
720 .PP
721 Parents that are not themselves profiled will have the time of
722 their profiled children propagated to them, but they will appear
723 to be spontaneously invoked in the call graph listing, and will
724 not have their time propagated further.
725 Similarly, signal catchers, even though profiled, will appear
726 to be spontaneous (although for more obscure reasons).
727 Any profiled children of signal catchers should have their times
728 propagated properly, unless the signal catcher was invoked during
729 the execution of the profiling routine, in which case all is lost.
730 .PP
731 The profiled program must call \f(CW\*(C`exit\*(C'\fR(2)
732 or return normally for the profiling information to be saved
733 in the \fIgmon.out\fR file.
734 .SH "SEE ALSO"
735 .IX Header "SEE ALSO"
736 \&\fImonitor\fR\|(3), \fIprofil\fR\|(2), \fIcc\fR\|(1), \fIprof\fR\|(1), and the Info entry for \fIgprof\fR.
737 .PP
738 \&\*(L"An Execution Profiler for Modular Programs\*(R",
739 by S. Graham, P. Kessler, M. McKusick;
740 Software \- Practice and Experience,
741 Vol. 13, pp. 671\-685, 1983.
742 .PP
743 \&\*(L"gprof: A Call Graph Execution Profiler\*(R",
744 by S. Graham, P. Kessler, M. McKusick;
745 Proceedings of the \s-1SIGPLAN\s0 '82 Symposium on Compiler Construction,
746 \&\s-1SIGPLAN\s0 Notices, Vol. 17, No  6, pp. 120\-126, June 1982.
747 .SH "COPYRIGHT"
748 .IX Header "COPYRIGHT"
749 Copyright (c) 1988, 1992, 1997, 1998, 1999, 2000, 2001, 2003,
750 2007, 2008, 2009 Free Software Foundation, Inc.
751 .PP
752 Permission is granted to copy, distribute and/or modify this document
753 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3
754 or any later version published by the Free Software Foundation;
755 with no Invariant Sections, with no Front-Cover Texts, and with no
756 Back-Cover Texts.  A copy of the license is included in the
757 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".