gprof/gprof.1

   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".