OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [binutils-2.20.1/] [gprof/] [gprof.1] - Blame information for rev 846

Go to most recent revision | Details | Compare with Previous | View Log

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

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.