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