Commit | Line | Data |
---|---|---|
40f90528 AM |
1 | .\" Automatically generated by Pod::Man version 1.15 |
2 | .\" Fri Apr 6 20:13: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" "" | |
49 | . ds C` "" | |
50 | . ds C' "" | |
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" | |
66 | .. | |
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 AM |
139 | .IX Title "GPROF 1" |
140 | .TH GPROF 1 "binutils-2.11.90" "2001-04-06" "GNU" | |
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. | |
210 | .if n .Ip "\f(CW""""\-A[\f(CIsymspec\f(CW]""""\fR" 4 | |
211 | .el .Ip "\f(CW\-A[\f(CIsymspec\f(CW]\fR" 4 | |
212 | .IX Item "-A[symspec]" | |
213 | .PD 0 | |
214 | .if n .Ip "\f(CW""""\-\-annotated\-source[=\f(CIsymspec\f(CW]""""\fR" 4 | |
215 | .el .Ip "\f(CW\-\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4 | |
216 | .IX Item "--annotated-source[=symspec]" | |
217 | .PD | |
218 | The \fB\-A\fR option causes \f(CW\*(C`gprof\*(C'\fR to print annotated source code. | |
219 | If \fIsymspec\fR is specified, print output only for matching symbols. | |
220 | .if n .Ip "\f(CW""""\-b""""\fR" 4 | |
221 | .el .Ip "\f(CW\-b\fR" 4 | |
222 | .IX Item "-b" | |
223 | .PD 0 | |
224 | .if n .Ip "\f(CW""""\-\-brief""""\fR" 4 | |
225 | .el .Ip "\f(CW\-\-brief\fR" 4 | |
226 | .IX Item "--brief" | |
227 | .PD | |
228 | If the \fB\-b\fR option is given, \f(CW\*(C`gprof\*(C'\fR doesn't print the | |
229 | verbose blurbs that try to explain the meaning of all of the fields in | |
230 | the tables. This is useful if you intend to print out the output, or | |
231 | are tired of seeing the blurbs. | |
232 | .if n .Ip "\f(CW""""\-C[\f(CIsymspec\f(CW]""""\fR" 4 | |
233 | .el .Ip "\f(CW\-C[\f(CIsymspec\f(CW]\fR" 4 | |
234 | .IX Item "-C[symspec]" | |
235 | .PD 0 | |
236 | .if n .Ip "\f(CW""""\-\-exec\-counts[=\f(CIsymspec\f(CW]""""\fR" 4 | |
237 | .el .Ip "\f(CW\-\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4 | |
238 | .IX Item "--exec-counts[=symspec]" | |
239 | .PD | |
240 | The \fB\-C\fR option causes \f(CW\*(C`gprof\*(C'\fR to | |
241 | print a tally of functions and the number of times each was called. | |
242 | If \fIsymspec\fR is specified, print tally only for matching symbols. | |
243 | .Sp | |
244 | If the profile data file contains basic-block count records, specifying | |
245 | the \fB\-l\fR option, along with \fB\-C\fR, will cause basic-block | |
246 | execution counts to be tallied and displayed. | |
247 | .if n .Ip "\f(CW""""\-i""""\fR" 4 | |
248 | .el .Ip "\f(CW\-i\fR" 4 | |
249 | .IX Item "-i" | |
250 | .PD 0 | |
251 | .if n .Ip "\f(CW""""\-\-file\-info""""\fR" 4 | |
252 | .el .Ip "\f(CW\-\-file\-info\fR" 4 | |
253 | .IX Item "--file-info" | |
254 | .PD | |
255 | The \fB\-i\fR option causes \f(CW\*(C`gprof\*(C'\fR to display summary information | |
256 | about the profile data \fIfile\fR\|(s) and then exit. The number of histogram, | |
257 | call graph, and basic-block count records is displayed. | |
258 | .if n .Ip "\f(CW""""\-I \f(CIdirs\f(CW""""\fR" 4 | |
259 | .el .Ip "\f(CW\-I \f(CIdirs\f(CW\fR" 4 | |
260 | .IX Item "-I dirs" | |
261 | .PD 0 | |
262 | .if n .Ip "\f(CW""""\-\-directory\-path=\f(CIdirs\f(CW""""\fR" 4 | |
263 | .el .Ip "\f(CW\-\-directory\-path=\f(CIdirs\f(CW\fR" 4 | |
264 | .IX Item "--directory-path=dirs" | |
265 | .PD | |
266 | The \fB\-I\fR option specifies a list of search directories in | |
267 | which to find source files. Environment variable \fI\s-1GPROF_PATH\s0\fR | |
268 | can also be used to convey this information. | |
269 | Used mostly for annotated source output. | |
270 | .if n .Ip "\f(CW""""\-J[\f(CIsymspec\f(CW]""""\fR" 4 | |
271 | .el .Ip "\f(CW\-J[\f(CIsymspec\f(CW]\fR" 4 | |
272 | .IX Item "-J[symspec]" | |
273 | .PD 0 | |
274 | .if n .Ip "\f(CW""""\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]""""\fR" 4 | |
275 | .el .Ip "\f(CW\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4 | |
276 | .IX Item "--no-annotated-source[=symspec]" | |
277 | .PD | |
278 | The \fB\-J\fR option causes \f(CW\*(C`gprof\*(C'\fR not to | |
279 | print annotated source code. | |
280 | If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints annotated source, | |
281 | but excludes matching symbols. | |
282 | .if n .Ip "\f(CW""""\-L""""\fR" 4 | |
283 | .el .Ip "\f(CW\-L\fR" 4 | |
284 | .IX Item "-L" | |
285 | .PD 0 | |
286 | .if n .Ip "\f(CW""""\-\-print\-path""""\fR" 4 | |
287 | .el .Ip "\f(CW\-\-print\-path\fR" 4 | |
288 | .IX Item "--print-path" | |
289 | .PD | |
290 | Normally, source filenames are printed with the path | |
291 | component suppressed. The \fB\-L\fR option causes \f(CW\*(C`gprof\*(C'\fR | |
292 | to print the full pathname of | |
293 | source filenames, which is determined | |
294 | from symbolic debugging information in the image file | |
295 | and is relative to the directory in which the compiler | |
296 | was invoked. | |
297 | .if n .Ip "\f(CW""""\-p[\f(CIsymspec\f(CW]""""\fR" 4 | |
298 | .el .Ip "\f(CW\-p[\f(CIsymspec\f(CW]\fR" 4 | |
299 | .IX Item "-p[symspec]" | |
300 | .PD 0 | |
301 | .if n .Ip "\f(CW""""\-\-flat\-profile[=\f(CIsymspec\f(CW]""""\fR" 4 | |
302 | .el .Ip "\f(CW\-\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4 | |
303 | .IX Item "--flat-profile[=symspec]" | |
304 | .PD | |
305 | The \fB\-p\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a flat profile. | |
306 | If \fIsymspec\fR is specified, print flat profile only for matching symbols. | |
307 | .if n .Ip "\f(CW""""\-P[\f(CIsymspec\f(CW]""""\fR" 4 | |
308 | .el .Ip "\f(CW\-P[\f(CIsymspec\f(CW]\fR" 4 | |
309 | .IX Item "-P[symspec]" | |
310 | .PD 0 | |
311 | .if n .Ip "\f(CW""""\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]""""\fR" 4 | |
312 | .el .Ip "\f(CW\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4 | |
313 | .IX Item "--no-flat-profile[=symspec]" | |
314 | .PD | |
315 | The \fB\-P\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing a flat profile. | |
316 | If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a flat profile, | |
317 | but excludes matching symbols. | |
318 | .if n .Ip "\f(CW""""\-q[\f(CIsymspec\f(CW]""""\fR" 4 | |
319 | .el .Ip "\f(CW\-q[\f(CIsymspec\f(CW]\fR" 4 | |
320 | .IX Item "-q[symspec]" | |
321 | .PD 0 | |
322 | .if n .Ip "\f(CW""""\-\-graph[=\f(CIsymspec\f(CW]""""\fR" 4 | |
323 | .el .Ip "\f(CW\-\-graph[=\f(CIsymspec\f(CW]\fR" 4 | |
324 | .IX Item "--graph[=symspec]" | |
325 | .PD | |
326 | The \fB\-q\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis. | |
327 | If \fIsymspec\fR is specified, print call graph only for matching symbols | |
328 | and their children. | |
329 | .if n .Ip "\f(CW""""\-Q[\f(CIsymspec\f(CW]""""\fR" 4 | |
330 | .el .Ip "\f(CW\-Q[\f(CIsymspec\f(CW]\fR" 4 | |
331 | .IX Item "-Q[symspec]" | |
332 | .PD 0 | |
333 | .if n .Ip "\f(CW""""\-\-no\-graph[=\f(CIsymspec\f(CW]""""\fR" 4 | |
334 | .el .Ip "\f(CW\-\-no\-graph[=\f(CIsymspec\f(CW]\fR" 4 | |
335 | .IX Item "--no-graph[=symspec]" | |
336 | .PD | |
337 | The \fB\-Q\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing the | |
338 | call graph. | |
339 | If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a call graph, | |
340 | but excludes matching symbols. | |
341 | .if n .Ip "\f(CW""""\-y""""\fR" 4 | |
342 | .el .Ip "\f(CW\-y\fR" 4 | |
343 | .IX Item "-y" | |
344 | .PD 0 | |
345 | .if n .Ip "\f(CW""""\-\-separate\-files""""\fR" 4 | |
346 | .el .Ip "\f(CW\-\-separate\-files\fR" 4 | |
347 | .IX Item "--separate-files" | |
348 | .PD | |
349 | This option affects annotated source output only. | |
350 | Normally, \f(CW\*(C`gprof\*(C'\fR prints annotated source files | |
351 | to standard-output. If this option is specified, | |
352 | annotated source for a file named \fIpath/\fIfilename\fI\fR | |
353 | is generated in the file \fI\fIfilename\fI\-ann\fR. If the underlying | |
354 | filesystem would truncate \fI\fIfilename\fI\-ann\fR so that it | |
355 | overwrites the original \fI\fIfilename\fI\fR, \f(CW\*(C`gprof\*(C'\fR generates | |
356 | annotated source in the file \fI\fIfilename\fI.ann\fR instead (if the | |
357 | original file name has an extension, that extension is \fIreplaced\fR | |
358 | with \fI.ann\fR). | |
359 | .if n .Ip "\f(CW""""\-Z[\f(CIsymspec\f(CW]""""\fR" 4 | |
360 | .el .Ip "\f(CW\-Z[\f(CIsymspec\f(CW]\fR" 4 | |
361 | .IX Item "-Z[symspec]" | |
362 | .PD 0 | |
363 | .if n .Ip "\f(CW""""\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]""""\fR" 4 | |
364 | .el .Ip "\f(CW\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4 | |
365 | .IX Item "--no-exec-counts[=symspec]" | |
366 | .PD | |
367 | The \fB\-Z\fR option causes \f(CW\*(C`gprof\*(C'\fR not to | |
368 | print a tally of functions and the number of times each was called. | |
369 | If \fIsymspec\fR is specified, print tally, but exclude matching symbols. | |
370 | .if n .Ip "\f(CW""""\-\-function\-ordering""""\fR" 4 | |
371 | .el .Ip "\f(CW\-\-function\-ordering\fR" 4 | |
372 | .IX Item "--function-ordering" | |
373 | The \fB\*(--function-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a | |
374 | suggested function ordering for the program based on profiling data. | |
375 | This option suggests an ordering which may improve paging, tlb and | |
376 | cache behavior for the program on systems which support arbitrary | |
377 | ordering of functions in an executable. | |
378 | .Sp | |
379 | The exact details of how to force the linker to place functions | |
380 | in a particular order is system dependent and out of the scope of this | |
381 | manual. | |
382 | .if n .Ip "\f(CW""""\-\-file\-ordering \f(CImap_file\f(CW""""\fR" 4 | |
383 | .el .Ip "\f(CW\-\-file\-ordering \f(CImap_file\f(CW\fR" 4 | |
384 | .IX Item "--file-ordering map_file" | |
385 | The \fB\*(--file-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a | |
386 | suggested .o link line ordering for the program based on profiling data. | |
387 | This option suggests an ordering which may improve paging, tlb and | |
388 | cache behavior for the program on systems which do not support arbitrary | |
389 | ordering of functions in an executable. | |
390 | .Sp | |
391 | Use of the \fB\-a\fR argument is highly recommended with this option. | |
392 | .Sp | |
393 | The \fImap_file\fR argument is a pathname to a file which provides | |
394 | function name to object file mappings. The format of the file is similar to | |
395 | the output of the program \f(CW\*(C`nm\*(C'\fR. | |
396 | .Sp | |
397 | .Vb 8 | |
398 | \& c-parse.o:00000000 T yyparse | |
399 | \& c-parse.o:00000004 C yyerrflag | |
400 | \& c-lang.o:00000000 T maybe_objc_method_name | |
401 | \& c-lang.o:00000000 T print_lang_statistics | |
402 | \& c-lang.o:00000000 T recognize_objc_keyword | |
403 | \& c-decl.o:00000000 T print_lang_identifier | |
404 | \& c-decl.o:00000000 T print_lang_type | |
405 | \& ... | |
406 | .Ve | |
407 | To create a \fImap_file\fR with \s-1GNU\s0 \f(CW\*(C`nm\*(C'\fR, type a command like | |
408 | \&\f(CW\*(C`nm \-\-extern\-only \-\-defined\-only \-v \-\-print\-file\-name program\-name\*(C'\fR. | |
409 | .if n .Ip "\f(CW""""\-T""""\fR" 4 | |
410 | .el .Ip "\f(CW\-T\fR" 4 | |
411 | .IX Item "-T" | |
412 | .PD 0 | |
413 | .if n .Ip "\f(CW""""\-\-traditional""""\fR" 4 | |
414 | .el .Ip "\f(CW\-\-traditional\fR" 4 | |
415 | .IX Item "--traditional" | |
416 | .PD | |
417 | The \fB\-T\fR option causes \f(CW\*(C`gprof\*(C'\fR to print its output in | |
418 | ``traditional'' \s-1BSD\s0 style. | |
419 | .if n .Ip "\f(CW""""\-w \f(CIwidth\f(CW""""\fR" 4 | |
420 | .el .Ip "\f(CW\-w \f(CIwidth\f(CW\fR" 4 | |
421 | .IX Item "-w width" | |
422 | .PD 0 | |
423 | .if n .Ip "\f(CW""""\-\-width=\f(CIwidth\f(CW""""\fR" 4 | |
424 | .el .Ip "\f(CW\-\-width=\f(CIwidth\f(CW\fR" 4 | |
425 | .IX Item "--width=width" | |
426 | .PD | |
427 | Sets width of output lines to \fIwidth\fR. | |
428 | Currently only used when printing the function index at the bottom | |
429 | of the call graph. | |
430 | .if n .Ip "\f(CW""""\-x""""\fR" 4 | |
431 | .el .Ip "\f(CW\-x\fR" 4 | |
432 | .IX Item "-x" | |
433 | .PD 0 | |
434 | .if n .Ip "\f(CW""""\-\-all\-lines""""\fR" 4 | |
435 | .el .Ip "\f(CW\-\-all\-lines\fR" 4 | |
436 | .IX Item "--all-lines" | |
437 | .PD | |
438 | This option affects annotated source output only. | |
439 | By default, only the lines at the beginning of a basic-block | |
440 | are annotated. If this option is specified, every line in | |
441 | a basic-block is annotated by repeating the annotation for the | |
442 | first line. This behavior is similar to \f(CW\*(C`tcov\*(C'\fR's \fB\-a\fR. | |
443 | .if n .Ip "\f(CW""""\-\-demangle[=\f(CIstyle\f(CW]""""\fR" 4 | |
444 | .el .Ip "\f(CW\-\-demangle[=\f(CIstyle\f(CW]\fR" 4 | |
445 | .IX Item "--demangle[=style]" | |
446 | .PD 0 | |
447 | .if n .Ip "\f(CW""""\-\-no\-demangle""""\fR" 4 | |
448 | .el .Ip "\f(CW\-\-no\-demangle\fR" 4 | |
449 | .IX Item "--no-demangle" | |
450 | .PD | |
451 | These options control whether \*(C+ symbol names should be demangled when | |
452 | printing output. The default is to demangle symbols. The | |
453 | \&\f(CW\*(C`\-\-no\-demangle\*(C'\fR option may be used to turn off demangling. Different | |
454 | compilers have different mangling styles. The optional demangling style | |
455 | argument can be used to choose an appropriate demangling style for your | |
456 | compiler. | |
457 | .Sh "Analysis Options" | |
458 | .IX Subsection "Analysis Options" | |
459 | .if n .Ip "\f(CW""""\-a""""\fR" 4 | |
460 | .el .Ip "\f(CW\-a\fR" 4 | |
461 | .IX Item "-a" | |
462 | .PD 0 | |
463 | .if n .Ip "\f(CW""""\-\-no\-static""""\fR" 4 | |
464 | .el .Ip "\f(CW\-\-no\-static\fR" 4 | |
465 | .IX Item "--no-static" | |
466 | .PD | |
467 | The \fB\-a\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress the printing of | |
468 | statically declared (private) functions. (These are functions whose | |
469 | names are not listed as global, and which are not visible outside the | |
470 | file/function/block where they were defined.) Time spent in these | |
471 | functions, calls to/from them, etc, will all be attributed to the | |
472 | function that was loaded directly before it in the executable file. | |
473 | This option affects both the flat profile and the call graph. | |
474 | .if n .Ip "\f(CW""""\-c""""\fR" 4 | |
475 | .el .Ip "\f(CW\-c\fR" 4 | |
476 | .IX Item "-c" | |
477 | .PD 0 | |
478 | .if n .Ip "\f(CW""""\-\-static\-call\-graph""""\fR" 4 | |
479 | .el .Ip "\f(CW\-\-static\-call\-graph\fR" 4 | |
480 | .IX Item "--static-call-graph" | |
481 | .PD | |
482 | The \fB\-c\fR option causes the call graph of the program to be | |
483 | augmented by a heuristic which examines the text space of the object | |
484 | file and identifies function calls in the binary machine code. | |
485 | Since normal call graph records are only generated when functions are | |
486 | entered, this option identifies children that could have been called, | |
487 | but never were. Calls to functions that were not compiled with | |
488 | profiling enabled are also identified, but only if symbol table | |
489 | entries are present for them. | |
490 | Calls to dynamic library routines are typically \fInot\fR found | |
491 | by this option. | |
492 | Parents or children identified via this heuristic | |
493 | are indicated in the call graph with call counts of \fB0\fR. | |
494 | .if n .Ip "\f(CW""""\-D""""\fR" 4 | |
495 | .el .Ip "\f(CW\-D\fR" 4 | |
496 | .IX Item "-D" | |
497 | .PD 0 | |
498 | .if n .Ip "\f(CW""""\-\-ignore\-non\-functions""""\fR" 4 | |
499 | .el .Ip "\f(CW\-\-ignore\-non\-functions\fR" 4 | |
500 | .IX Item "--ignore-non-functions" | |
501 | .PD | |
502 | The \fB\-D\fR option causes \f(CW\*(C`gprof\*(C'\fR to ignore symbols which | |
503 | are not known to be functions. This option will give more accurate | |
504 | profile data on systems where it is supported (Solaris and \s-1HPUX\s0 for | |
505 | example). | |
506 | .if n .Ip "\f(CW""""\-k \f(CIfrom\f(CW/\f(CIto\f(CW""""\fR" 4 | |
507 | .el .Ip "\f(CW\-k \f(CIfrom\f(CW/\f(CIto\f(CW\fR" 4 | |
508 | .IX Item "-k from/to" | |
509 | The \fB\-k\fR option allows you to delete from the call graph any arcs from | |
510 | symbols matching symspec \fIfrom\fR to those matching symspec \fIto\fR. | |
511 | .if n .Ip "\f(CW""""\-l""""\fR" 4 | |
512 | .el .Ip "\f(CW\-l\fR" 4 | |
513 | .IX Item "-l" | |
514 | .PD 0 | |
515 | .if n .Ip "\f(CW""""\-\-line""""\fR" 4 | |
516 | .el .Ip "\f(CW\-\-line\fR" 4 | |
517 | .IX Item "--line" | |
518 | .PD | |
519 | The \fB\-l\fR option enables line-by-line profiling, which causes | |
520 | histogram hits to be charged to individual source code lines, | |
521 | instead of functions. | |
522 | If the program was compiled with basic-block counting enabled, | |
523 | this option will also identify how many times each line of | |
524 | code was executed. | |
525 | While line-by-line profiling can help isolate where in a large function | |
526 | a program is spending its time, it also significantly increases | |
527 | the running time of \f(CW\*(C`gprof\*(C'\fR, and magnifies statistical | |
528 | inaccuracies. | |
529 | .if n .Ip "\f(CW""""\-m \f(CInum\f(CW""""\fR" 4 | |
530 | .el .Ip "\f(CW\-m \f(CInum\f(CW\fR" 4 | |
531 | .IX Item "-m num" | |
532 | .PD 0 | |
533 | .if n .Ip "\f(CW""""\-\-min\-count=\f(CInum\f(CW""""\fR" 4 | |
534 | .el .Ip "\f(CW\-\-min\-count=\f(CInum\f(CW\fR" 4 | |
535 | .IX Item "--min-count=num" | |
536 | .PD | |
537 | This option affects execution count output only. | |
538 | Symbols that are executed less than \fInum\fR times are suppressed. | |
539 | .if n .Ip "\f(CW""""\-n[\f(CIsymspec\f(CW]""""\fR" 4 | |
540 | .el .Ip "\f(CW\-n[\f(CIsymspec\f(CW]\fR" 4 | |
541 | .IX Item "-n[symspec]" | |
542 | .PD 0 | |
543 | .if n .Ip "\f(CW""""\-\-time[=\f(CIsymspec\f(CW]""""\fR" 4 | |
544 | .el .Ip "\f(CW\-\-time[=\f(CIsymspec\f(CW]\fR" 4 | |
545 | .IX Item "--time[=symspec]" | |
546 | .PD | |
547 | The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis, | |
548 | to only propagate times for symbols matching \fIsymspec\fR. | |
549 | .if n .Ip "\f(CW""""\-N[\f(CIsymspec\f(CW]""""\fR" 4 | |
550 | .el .Ip "\f(CW\-N[\f(CIsymspec\f(CW]\fR" 4 | |
551 | .IX Item "-N[symspec]" | |
552 | .PD 0 | |
553 | .if n .Ip "\f(CW""""\-\-no\-time[=\f(CIsymspec\f(CW]""""\fR" 4 | |
554 | .el .Ip "\f(CW\-\-no\-time[=\f(CIsymspec\f(CW]\fR" 4 | |
555 | .IX Item "--no-time[=symspec]" | |
556 | .PD | |
557 | The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis, | |
558 | not to propagate times for symbols matching \fIsymspec\fR. | |
559 | .if n .Ip "\f(CW""""\-z""""\fR" 4 | |
560 | .el .Ip "\f(CW\-z\fR" 4 | |
561 | .IX Item "-z" | |
562 | .PD 0 | |
563 | .if n .Ip "\f(CW""""\-\-display\-unused\-functions""""\fR" 4 | |
564 | .el .Ip "\f(CW\-\-display\-unused\-functions\fR" 4 | |
565 | .IX Item "--display-unused-functions" | |
566 | .PD | |
567 | If you give the \fB\-z\fR option, \f(CW\*(C`gprof\*(C'\fR will mention all | |
568 | functions in the flat profile, even those that were never called, and | |
569 | that had no time spent in them. This is useful in conjunction with the | |
570 | \&\fB\-c\fR option for discovering which routines were never called. | |
571 | .Sh "Miscellaneous Options" | |
572 | .IX Subsection "Miscellaneous Options" | |
573 | .if n .Ip "\f(CW""""\-d[\f(CInum\f(CW]""""\fR" 4 | |
574 | .el .Ip "\f(CW\-d[\f(CInum\f(CW]\fR" 4 | |
575 | .IX Item "-d[num]" | |
576 | .PD 0 | |
577 | .if n .Ip "\f(CW""""\-\-debug[=\f(CInum\f(CW]""""\fR" 4 | |
578 | .el .Ip "\f(CW\-\-debug[=\f(CInum\f(CW]\fR" 4 | |
579 | .IX Item "--debug[=num]" | |
580 | .PD | |
581 | The \fB\-d\fR \fInum\fR option specifies debugging options. | |
582 | If \fInum\fR is not specified, enable all debugging. | |
583 | .if n .Ip "\f(CW""""\-O\f(CIname\f(CW""""\fR" 4 | |
584 | .el .Ip "\f(CW\-O\f(CIname\f(CW\fR" 4 | |
585 | .IX Item "-Oname" | |
586 | .PD 0 | |
587 | .if n .Ip "\f(CW""""\-\-file\-format=\f(CIname\f(CW""""\fR" 4 | |
588 | .el .Ip "\f(CW\-\-file\-format=\f(CIname\f(CW\fR" 4 | |
589 | .IX Item "--file-format=name" | |
590 | .PD | |
591 | Selects the format of the profile data files. Recognized formats are | |
592 | \&\fBauto\fR (the default), \fBbsd\fR, \fB4.4bsd\fR, \fBmagic\fR, and | |
593 | \&\fBprof\fR (not yet supported). | |
594 | .if n .Ip "\f(CW""""\-s""""\fR" 4 | |
595 | .el .Ip "\f(CW\-s\fR" 4 | |
596 | .IX Item "-s" | |
597 | .PD 0 | |
598 | .if n .Ip "\f(CW""""\-\-sum""""\fR" 4 | |
599 | .el .Ip "\f(CW\-\-sum\fR" 4 | |
600 | .IX Item "--sum" | |
601 | .PD | |
602 | The \fB\-s\fR option causes \f(CW\*(C`gprof\*(C'\fR to summarize the information | |
603 | in the profile data files it read in, and write out a profile data | |
604 | file called \fIgmon.sum\fR, which contains all the information from | |
605 | the profile data files that \f(CW\*(C`gprof\*(C'\fR read in. The file \fIgmon.sum\fR | |
606 | may be one of the specified input files; the effect of this is to | |
607 | merge the data in the other input files into \fIgmon.sum\fR. | |
608 | .Sp | |
609 | Eventually you can run \f(CW\*(C`gprof\*(C'\fR again without \fB\-s\fR to analyze the | |
610 | cumulative data in the file \fIgmon.sum\fR. | |
611 | .if n .Ip "\f(CW""""\-v""""\fR" 4 | |
612 | .el .Ip "\f(CW\-v\fR" 4 | |
613 | .IX Item "-v" | |
614 | .PD 0 | |
615 | .if n .Ip "\f(CW""""\-\-version""""\fR" 4 | |
616 | .el .Ip "\f(CW\-\-version\fR" 4 | |
617 | .IX Item "--version" | |
618 | .PD | |
619 | The \fB\-v\fR flag causes \f(CW\*(C`gprof\*(C'\fR to print the current version | |
620 | number, and then exit. | |
621 | .Sh "Deprecated Options" | |
622 | .IX Subsection "Deprecated Options" | |
623 | These options have been replaced with newer versions that use symspecs. | |
624 | .if n .Ip "\f(CW""""\-e \f(CIfunction_name\f(CW""""\fR" 4 | |
625 | .el .Ip "\f(CW\-e \f(CIfunction_name\f(CW\fR" 4 | |
626 | .IX Item "-e function_name" | |
627 | The \fB\-e\fR \fIfunction\fR option tells \f(CW\*(C`gprof\*(C'\fR to not print | |
628 | information about the function \fIfunction_name\fR (and its | |
629 | children...) in the call graph. The function will still be listed | |
630 | as a child of any functions that call it, but its index number will be | |
631 | shown as \fB[not printed]\fR. More than one \fB\-e\fR option may be | |
632 | given; only one \fIfunction_name\fR may be indicated with each \fB\-e\fR | |
633 | option. | |
634 | .if n .Ip "\f(CW""""\-E \f(CIfunction_name\f(CW""""\fR" 4 | |
635 | .el .Ip "\f(CW\-E \f(CIfunction_name\f(CW\fR" 4 | |
636 | .IX Item "-E function_name" | |
637 | The \f(CW\*(C`\-E \f(CIfunction\f(CW\*(C'\fR option works like the \f(CW\*(C`\-e\*(C'\fR option, but | |
638 | time spent in the function (and children who were not called from | |
639 | anywhere else), will not be used to compute the percentages-of-time for | |
640 | the call graph. More than one \fB\-E\fR option may be given; only one | |
641 | \&\fIfunction_name\fR may be indicated with each \fB\-E\fR option. | |
642 | .if n .Ip "\f(CW""""\-f \f(CIfunction_name\f(CW""""\fR" 4 | |
643 | .el .Ip "\f(CW\-f \f(CIfunction_name\f(CW\fR" 4 | |
644 | .IX Item "-f function_name" | |
645 | The \fB\-f\fR \fIfunction\fR option causes \f(CW\*(C`gprof\*(C'\fR to limit the | |
646 | call graph to the function \fIfunction_name\fR and its children (and | |
647 | their children...). More than one \fB\-f\fR option may be given; | |
648 | only one \fIfunction_name\fR may be indicated with each \fB\-f\fR | |
649 | option. | |
650 | .if n .Ip "\f(CW""""\-F \f(CIfunction_name\f(CW""""\fR" 4 | |
651 | .el .Ip "\f(CW\-F \f(CIfunction_name\f(CW\fR" 4 | |
652 | .IX Item "-F function_name" | |
653 | The \fB\-F\fR \fIfunction\fR option works like the \f(CW\*(C`\-f\*(C'\fR option, but | |
654 | only time spent in the function and its children (and their | |
655 | children...) will be used to determine total-time and | |
656 | percentages-of-time for the call graph. More than one \fB\-F\fR option | |
657 | may be given; only one \fIfunction_name\fR may be indicated with each | |
658 | \&\fB\-F\fR option. The \fB\-F\fR option overrides the \fB\-E\fR option. | |
659 | .SH "FILES" | |
660 | .IX Header "FILES" | |
661 | .if n .Ip "\f(CW""""\f(CIa.out\f(CW""""\fR" 4 | |
662 | .el .Ip "\f(CW\f(CIa.out\f(CW\fR" 4 | |
663 | .IX Item "a.out" | |
664 | the namelist and text space. | |
665 | .if n .Ip "\f(CW""""\f(CIgmon.out\f(CW""""\fR" 4 | |
666 | .el .Ip "\f(CW\f(CIgmon.out\f(CW\fR" 4 | |
667 | .IX Item "gmon.out" | |
668 | dynamic call graph and profile. | |
669 | .if n .Ip "\f(CW""""\f(CIgmon.sum\f(CW""""\fR" 4 | |
670 | .el .Ip "\f(CW\f(CIgmon.sum\f(CW\fR" 4 | |
671 | .IX Item "gmon.sum" | |
672 | summarized dynamic call graph and profile. | |
673 | .SH "BUGS" | |
674 | .IX Header "BUGS" | |
252b5132 RH |
675 | The granularity of the sampling is shown, but remains |
676 | statistical at best. | |
677 | We assume that the time for each execution of a function | |
678 | can be expressed by the total time for the function divided | |
679 | by the number of times the function is called. | |
680 | Thus the time propagated along the call graph arcs to the function's | |
681 | parents is directly proportional to the number of times that | |
682 | arc is traversed. | |
683 | .PP | |
684 | Parents that are not themselves profiled will have the time of | |
685 | their profiled children propagated to them, but they will appear | |
686 | to be spontaneously invoked in the call graph listing, and will | |
687 | not have their time propagated further. | |
688 | Similarly, signal catchers, even though profiled, will appear | |
689 | to be spontaneous (although for more obscure reasons). | |
690 | Any profiled children of signal catchers should have their times | |
691 | propagated properly, unless the signal catcher was invoked during | |
692 | the execution of the profiling routine, in which case all is lost. | |
693 | .PP | |
40f90528 | 694 | The profiled program must call \f(CW\*(C`exit\*(C'\fR(2) |
252b5132 | 695 | or return normally for the profiling information to be saved |
40f90528 AM |
696 | in the \fIgmon.out\fR file. |
697 | .SH "SEE ALSO" | |
698 | .IX Header "SEE ALSO" | |
699 | \&\fImonitor\fR\|(3), \fIprofil\fR\|(2), \fIcc\fR\|(1), \fIprof\fR\|(1), and the Info entry for \fIgprof\fR. | |
700 | .PP | |
701 | ``An Execution Profiler for Modular Programs'', | |
702 | by S. Graham, P. Kessler, M. McKusick; | |
703 | Software \- Practice and Experience, | |
704 | Vol. 13, pp. 671\-685, 1983. | |
705 | .PP | |
706 | ``gprof: A Call Graph Execution Profiler'', | |
707 | by S. Graham, P. Kessler, M. McKusick; | |
708 | Proceedings of the \s-1SIGPLAN\s0 '82 Symposium on Compiler Construction, | |
709 | \&\s-1SIGPLAN\s0 Notices, Vol. 17, No 6, pp. 120\-126, June 1982. | |
710 | .SH "COPYRIGHT" | |
711 | .IX Header "COPYRIGHT" | |
712 | Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc. | |
713 | .PP | |
714 | Permission is granted to copy, distribute and/or modify this document | |
715 | under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1 | |
716 | or any later version published by the Free Software Foundation; | |
717 | with no Invariant Sections, with no Front-Cover Texts, and with no | |
718 | Back-Cover Texts. A copy of the license is included in the | |
719 | section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R". |