| 1 | .\" Automatically generated by Pod::Man version 1.15 |
| 2 | .\" Fri Apr 6 20:13:00 2001 |
| 3 | .\" |
| 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 |
| 74 | .\" |
| 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 | .\" ====================================================================== |
| 138 | .\" |
| 139 | .IX Title "GPROF 1" |
| 140 | .TH GPROF 1 "binutils-2.11.90" "2001-04-06" "GNU" |
| 141 | .UC |
| 142 | .SH "NAME" |
| 143 | gprof \- display call graph profile data |
| 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 |
| 175 | output shows the sum of the profile information in the given profile files. |
| 176 | .PP |
| 177 | \&\f(CW\*(C`Gprof\*(C'\fR calculates the amount of time spent in each routine. |
| 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. |
| 181 | .PP |
| 182 | Several forms of output are available from the analysis. |
| 183 | .PP |
| 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. |
| 187 | .PP |
| 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. |
| 193 | .PP |
| 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" |
| 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 |
| 694 | The profiled program must call \f(CW\*(C`exit\*(C'\fR(2) |
| 695 | or return normally for the profiling information to be saved |
| 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". |