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