1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14

     2 .\"

     3 .\" Standard preamble:

     4 .\" ========================================================================

     5 .de Sh \" Subsection heading

     6 .br

     7 .if t .Sp

     8 .ne 5

     9 .PP

    10 \fB\\$1\fR

    11 .PP

    12 ..

    13 .de Sp \" Vertical space (when we can't use .PP)

    14 .if t .sp .5v

    15 .if n .sp

    16 ..

    17 .de Vb \" Begin verbatim text

    18 .ft CW

    19 .nf

    20 .ne \\$1

    21 ..

    22 .de Ve \" End verbatim text

    23 .ft R

    24 .fi

    25 ..

    26 .\" Set up some character translations and predefined strings.  \*(-- will

    27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left

    28 .\" double quote, and \*(R" will give a right double quote.  | will give a

    29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to

    30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'

    31 .\" expand to `' in nroff, nothing in troff, for use with C<>.

    32 .tr \(*W-|\(bv\*(Tr

    33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'

    34 .ie n \{\

    35 .    ds -- \(*W-

    36 .    ds PI pi

    37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch

    38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch

    39 .    ds L" ""

    40 .    ds R" ""

    41 .    ds C` ""

    42 .    ds C' ""

    43 'br\}

    44 .el\{\

    45 .    ds -- \|\(em\|

    46 .    ds PI \(*p

    47 .    ds L" ``

    48 .    ds R" ''

    49 'br\}

    50 .\"

    51 .\" If the F register is turned on, we'll generate index entries on stderr for

    52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index

    53 .\" entries marked with X<> in POD.  Of course, you'll have to process the

    54 .\" output yourself in some meaningful fashion.

    55 .if \nF \{\

    56 .    de IX

    57 .    tm Index:\\$1\t\\n%\t"\\$2"

    58 ..

    59 .    nr % 0

    60 .    rr F

    61 .\}

    62 .\"

    63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes

    64 .\" way too many mistakes in technical documents.

    65 .hy 0

    66 .\"

    67 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).

    68 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.

    69 .    \" fudge factors for nroff and troff

    70 .if n \{\

    71 .    ds #H 0

    72 .    ds #V .8m

    73 .    ds #F .3m

    74 .    ds #[ \f1

    75 .    ds #] \fP

    76 .\}

    77 .if t \{\

    78 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)

    79 .    ds #V .6m

    80 .    ds #F 0

    81 .    ds #[ \&

    82 .    ds #] \&

    83 .\}

    84 .    \" simple accents for nroff and troff

    85 .if n \{\

    86 .    ds ' \&

    87 .    ds ` \&

    88 .    ds ^ \&

    89 .    ds , \&

    90 .    ds ~ ~

    91 .    ds /

    92 .\}

    93 .if t \{\

    94 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"

    95 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'

    96 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'

    97 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'

    98 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'

    99 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'

   100 .\}

   101 .    \" troff and (daisy-wheel) nroff accents

   102 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'

   103 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'

   104 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]

   105 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'

   106 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'

   107 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]

   108 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]

   109 .ds ae a\h'-(\w'a'u*4/10)'e

   110 .ds Ae A\h'-(\w'A'u*4/10)'E

   111 .    \" corrections for vroff

   112 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'

   113 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'

   114 .    \" for low resolution devices (crt and lpr)

   115 .if \n(.H>23 .if \n(.V>19 \

   116 \{\

   117 .    ds : e

   118 .    ds 8 ss

   119 .    ds o a

   120 .    ds d- d\h'-1'\(ga

   121 .    ds D- D\h'-1'\(hy

   122 .    ds th \o'bp'

   123 .    ds Th \o'LP'

   124 .    ds ae ae

   125 .    ds Ae AE

   126 .\}

   127 .rm #[ #] #H #V #F C

   128 .\" ========================================================================

   129 .\"

   130 .IX Title "GPROF 1"

   131 .TH GPROF 1 "2008-01-09" "binutils-2.18.50" "GNU"

   132 .SH "NAME"

   133 gprof \- display call graph profile data

   134 .SH "SYNOPSIS"

   135 .IX Header "SYNOPSIS"

   136 gprof [ \-[abcDhilLrsTvwxyz] ] [ \-[ACeEfFJnNOpPqQZ][\fIname\fR] ] 

   137  [ \-I \fIdirs\fR ] [ \-d[\fInum\fR] ] [ \-k \fIfrom/to\fR ]

   138  [ \-m \fImin-count\fR ] [ \-R \fImap_file\fR ] [ \-t \fItable-length\fR ]

   139  [ \-\-[no\-]annotated\-source[=\fIname\fR] ] 

   140  [ \-\-[no\-]exec\-counts[=\fIname\fR] ]

   141  [ \-\-[no\-]flat\-profile[=\fIname\fR] ] [ \-\-[no\-]graph[=\fIname\fR] ]

   142  [ \-\-[no\-]time=\fIname\fR] [ \-\-all\-lines ] [ \-\-brief ] 

   143  [ \-\-debug[=\fIlevel\fR] ] [ \-\-function\-ordering ] 

   144  [ \-\-file\-ordering \fImap_file\fR ] [ \-\-directory\-path=\fIdirs\fR ]

   145  [ \-\-display\-unused\-functions ] [ \-\-file\-format=\fIname\fR ]

   146  [ \-\-file\-info ] [ \-\-help ] [ \-\-line ] [ \-\-min\-count=\fIn\fR ]

   147  [ \-\-no\-static ] [ \-\-print\-path ] [ \-\-separate\-files ]

   148  [ \-\-static\-call\-graph ] [ \-\-sum ] [ \-\-table\-length=\fIlen\fR ]

   149  [ \-\-traditional ] [ \-\-version ] [ \-\-width=\fIn\fR ]

   150  [ \-\-ignore\-non\-functions ] [ \-\-demangle[=\fI\s-1STYLE\s0\fR] ]

   151  [ \-\-no\-demangle ] [ \fIimage-file\fR ] [ \fIprofile-file\fR ... ]

   152 .SH "DESCRIPTION"

   153 .IX Header "DESCRIPTION"

   154 \&\f(CW\*(C`gprof\*(C'\fR produces an execution profile of C, Pascal, or Fortran77 

   155 programs.  The effect of called routines is incorporated in the profile 

   156 of each caller.  The profile data is taken from the call graph profile file

   157 (\fIgmon.out\fR default) which is created by programs

   158 that are compiled with the \fB\-pg\fR option of

   159 \&\f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`pc\*(C'\fR, and \f(CW\*(C`f77\*(C'\fR.

   160 The \fB\-pg\fR option also links in versions of the library routines

   161 that are compiled for profiling.  \f(CW\*(C`Gprof\*(C'\fR reads the given object 

   162 file (the default is \f(CW\*(C`a.out\*(C'\fR) and establishes the relation between

   163 its symbol table and the call graph profile from \fIgmon.out\fR.

   164 If more than one profile file is specified, the \f(CW\*(C`gprof\*(C'\fR

   165 output shows the sum of the profile information in the given profile files.

   166 .PP

   167 \&\f(CW\*(C`Gprof\*(C'\fR calculates the amount of time spent in each routine.

   168 Next, these times are propagated along the edges of the call graph.

   169 Cycles are discovered, and calls into a cycle are made to share the time

   170 of the cycle.

   171 .PP

   172 Several forms of output are available from the analysis.

   173 .PP

   174 The \fIflat profile\fR shows how much time your program spent in each function,

   175 and how many times that function was called.  If you simply want to know

   176 which functions burn most of the cycles, it is stated concisely here.

   177 .PP

   178 The \fIcall graph\fR shows, for each function, which functions called it, which

   179 other functions it called, and how many times.  There is also an estimate

   180 of how much time was spent in the subroutines of each function.  This can

   181 suggest places where you might try to eliminate function calls that use a

   182 lot of time.  

   183 .PP

   184 The \fIannotated source\fR listing is a copy of the program's

   185 source code, labeled with the number of times each line of the

   186 program was executed.  

   187 .SH "OPTIONS"

   188 .IX Header "OPTIONS"

   189 These options specify which of several output formats

   190 \&\f(CW\*(C`gprof\*(C'\fR should produce.

   191 .PP

   192 Many of these options take an optional \fIsymspec\fR to specify

   193 functions to be included or excluded.  These options can be

   194 specified multiple times, with different symspecs, to include

   195 or exclude sets of symbols.  

   196 .PP

   197 Specifying any of these options overrides the default (\fB\-p \-q\fR),

   198 which prints a flat profile and call graph analysis

   199 for all functions.

   200 .ie n .IP """\-A[\f(CIsymspec\f(CW]""" 4

   201 .el .IP "\f(CW\-A[\f(CIsymspec\f(CW]\fR" 4

   202 .IX Item "-A[symspec]"

   203 .PD 0

   204 .ie n .IP """\-\-annotated\-source[=\f(CIsymspec\f(CW]""" 4

   205 .el .IP "\f(CW\-\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4

   206 .IX Item "--annotated-source[=symspec]"

   207 .PD

   208 The \fB\-A\fR option causes \f(CW\*(C`gprof\*(C'\fR to print annotated source code.

   209 If \fIsymspec\fR is specified, print output only for matching symbols.

   210 .ie n .IP """\-b""" 4

   211 .el .IP "\f(CW\-b\fR" 4

   212 .IX Item "-b"

   213 .PD 0

   214 .ie n .IP """\-\-brief""" 4

   215 .el .IP "\f(CW\-\-brief\fR" 4

   216 .IX Item "--brief"

   217 .PD

   218 If the \fB\-b\fR option is given, \f(CW\*(C`gprof\*(C'\fR doesn't print the

   219 verbose blurbs that try to explain the meaning of all of the fields in

   220 the tables.  This is useful if you intend to print out the output, or

   221 are tired of seeing the blurbs.

   222 .ie n .IP """\-C[\f(CIsymspec\f(CW]""" 4

   223 .el .IP "\f(CW\-C[\f(CIsymspec\f(CW]\fR" 4

   224 .IX Item "-C[symspec]"

   225 .PD 0

   226 .ie n .IP """\-\-exec\-counts[=\f(CIsymspec\f(CW]""" 4

   227 .el .IP "\f(CW\-\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4

   228 .IX Item "--exec-counts[=symspec]"

   229 .PD

   230 The \fB\-C\fR option causes \f(CW\*(C`gprof\*(C'\fR to

   231 print a tally of functions and the number of times each was called.

   232 If \fIsymspec\fR is specified, print tally only for matching symbols.

   233 .Sp

   234 If the profile data file contains basic-block count records, specifying

   235 the \fB\-l\fR option, along with \fB\-C\fR, will cause basic-block

   236 execution counts to be tallied and displayed.

   237 .ie n .IP """\-i""" 4

   238 .el .IP "\f(CW\-i\fR" 4

   239 .IX Item "-i"

   240 .PD 0

   241 .ie n .IP """\-\-file\-info""" 4

   242 .el .IP "\f(CW\-\-file\-info\fR" 4

   243 .IX Item "--file-info"

   244 .PD

   245 The \fB\-i\fR option causes \f(CW\*(C`gprof\*(C'\fR to display summary information

   246 about the profile data file(s) and then exit.  The number of histogram,

   247 call graph, and basic-block count records is displayed.

   248 .ie n .IP """\-I \f(CIdirs\f(CW""" 4

   249 .el .IP "\f(CW\-I \f(CIdirs\f(CW\fR" 4

   250 .IX Item "-I dirs"

   251 .PD 0

   252 .ie n .IP """\-\-directory\-path=\f(CIdirs\f(CW""" 4

   253 .el .IP "\f(CW\-\-directory\-path=\f(CIdirs\f(CW\fR" 4

   254 .IX Item "--directory-path=dirs"

   255 .PD

   256 The \fB\-I\fR option specifies a list of search directories in

   257 which to find source files.  Environment variable \fI\s-1GPROF_PATH\s0\fR

   258 can also be used to convey this information.

   259 Used mostly for annotated source output.

   260 .ie n .IP """\-J[\f(CIsymspec\f(CW]""" 4

   261 .el .IP "\f(CW\-J[\f(CIsymspec\f(CW]\fR" 4

   262 .IX Item "-J[symspec]"

   263 .PD 0

   264 .ie n .IP """\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]""" 4

   265 .el .IP "\f(CW\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4

   266 .IX Item "--no-annotated-source[=symspec]"

   267 .PD

   268 The \fB\-J\fR option causes \f(CW\*(C`gprof\*(C'\fR not to

   269 print annotated source code.

   270 If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints annotated source,

   271 but excludes matching symbols.

   272 .ie n .IP """\-L""" 4

   273 .el .IP "\f(CW\-L\fR" 4

   274 .IX Item "-L"

   275 .PD 0

   276 .ie n .IP """\-\-print\-path""" 4

   277 .el .IP "\f(CW\-\-print\-path\fR" 4

   278 .IX Item "--print-path"

   279 .PD

   280 Normally, source filenames are printed with the path

   281 component suppressed.  The \fB\-L\fR option causes \f(CW\*(C`gprof\*(C'\fR

   282 to print the full pathname of

   283 source filenames, which is determined

   284 from symbolic debugging information in the image file

   285 and is relative to the directory in which the compiler

   286 was invoked.

   287 .ie n .IP """\-p[\f(CIsymspec\f(CW]""" 4

   288 .el .IP "\f(CW\-p[\f(CIsymspec\f(CW]\fR" 4

   289 .IX Item "-p[symspec]"

   290 .PD 0

   291 .ie n .IP """\-\-flat\-profile[=\f(CIsymspec\f(CW]""" 4

   292 .el .IP "\f(CW\-\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4

   293 .IX Item "--flat-profile[=symspec]"

   294 .PD

   295 The \fB\-p\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a flat profile.

   296 If \fIsymspec\fR is specified, print flat profile only for matching symbols.

   297 .ie n .IP """\-P[\f(CIsymspec\f(CW]""" 4

   298 .el .IP "\f(CW\-P[\f(CIsymspec\f(CW]\fR" 4

   299 .IX Item "-P[symspec]"

   300 .PD 0

   301 .ie n .IP """\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]""" 4

   302 .el .IP "\f(CW\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4

   303 .IX Item "--no-flat-profile[=symspec]"

   304 .PD

   305 The \fB\-P\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing a flat profile.

   306 If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a flat profile,

   307 but excludes matching symbols.

   308 .ie n .IP """\-q[\f(CIsymspec\f(CW]""" 4

   309 .el .IP "\f(CW\-q[\f(CIsymspec\f(CW]\fR" 4

   310 .IX Item "-q[symspec]"

   311 .PD 0

   312 .ie n .IP """\-\-graph[=\f(CIsymspec\f(CW]""" 4

   313 .el .IP "\f(CW\-\-graph[=\f(CIsymspec\f(CW]\fR" 4

   314 .IX Item "--graph[=symspec]"

   315 .PD

   316 The \fB\-q\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis.

   317 If \fIsymspec\fR is specified, print call graph only for matching symbols

   318 and their children.

   319 .ie n .IP """\-Q[\f(CIsymspec\f(CW]""" 4

   320 .el .IP "\f(CW\-Q[\f(CIsymspec\f(CW]\fR" 4

   321 .IX Item "-Q[symspec]"

   322 .PD 0

   323 .ie n .IP """\-\-no\-graph[=\f(CIsymspec\f(CW]""" 4

   324 .el .IP "\f(CW\-\-no\-graph[=\f(CIsymspec\f(CW]\fR" 4

   325 .IX Item "--no-graph[=symspec]"

   326 .PD

   327 The \fB\-Q\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing the

   328 call graph.

   329 If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a call graph,

   330 but excludes matching symbols.

   331 .ie n .IP """\-t""" 4

   332 .el .IP "\f(CW\-t\fR" 4

   333 .IX Item "-t"

   334 .PD 0

   335 .ie n .IP """\-\-table\-length=\f(CInum\f(CW""" 4

   336 .el .IP "\f(CW\-\-table\-length=\f(CInum\f(CW\fR" 4

   337 .IX Item "--table-length=num"

   338 .PD

   339 The \fB\-t\fR option causes the \fInum\fR most active source lines in

   340 each source file to be listed when source annotation is enabled.  The

   341 default is 10.

   342 .ie n .IP """\-y""" 4

   343 .el .IP "\f(CW\-y\fR" 4

   344 .IX Item "-y"

   345 .PD 0

   346 .ie n .IP """\-\-separate\-files""" 4

   347 .el .IP "\f(CW\-\-separate\-files\fR" 4

   348 .IX Item "--separate-files"

   349 .PD

   350 This option affects annotated source output only.

   351 Normally, \f(CW\*(C`gprof\*(C'\fR prints annotated source files

   352 to standard\-output.  If this option is specified,

   353 annotated source for a file named \fIpath/\fIfilename\fI\fR

   354 is generated in the file \fI\fIfilename\fI\-ann\fR.  If the underlying

   355 file system would truncate \fI\fIfilename\fI\-ann\fR so that it

   356 overwrites the original \fI\fIfilename\fI\fR, \f(CW\*(C`gprof\*(C'\fR generates

   357 annotated source in the file \fI\fIfilename\fI.ann\fR instead (if the

   358 original file name has an extension, that extension is \fIreplaced\fR

   359 with \fI.ann\fR).

   360 .ie n .IP """\-Z[\f(CIsymspec\f(CW]""" 4

   361 .el .IP "\f(CW\-Z[\f(CIsymspec\f(CW]\fR" 4

   362 .IX Item "-Z[symspec]"

   363 .PD 0

   364 .ie n .IP """\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]""" 4

   365 .el .IP "\f(CW\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4

   366 .IX Item "--no-exec-counts[=symspec]"

   367 .PD

   368 The \fB\-Z\fR option causes \f(CW\*(C`gprof\*(C'\fR not to

   369 print a tally of functions and the number of times each was called.

   370 If \fIsymspec\fR is specified, print tally, but exclude matching symbols.

   371 .ie n .IP """\-r""" 4

   372 .el .IP "\f(CW\-r\fR" 4

   373 .IX Item "-r"

   374 .PD 0

   375 .ie n .IP """\-\-function\-ordering""" 4

   376 .el .IP "\f(CW\-\-function\-ordering\fR" 4

   377 .IX Item "--function-ordering"

   378 .PD

   379 The \fB\-\-function\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a

   380 suggested function ordering for the program based on profiling data.

   381 This option suggests an ordering which may improve paging, tlb and

   382 cache behavior for the program on systems which support arbitrary

   383 ordering of functions in an executable.

   384 .Sp

   385 The exact details of how to force the linker to place functions

   386 in a particular order is system dependent and out of the scope of this

   387 manual.

   388 .ie n .IP """\-R \f(CImap_file\f(CW""" 4

   389 .el .IP "\f(CW\-R \f(CImap_file\f(CW\fR" 4

   390 .IX Item "-R map_file"

   391 .PD 0

   392 .ie n .IP """\-\-file\-ordering \f(CImap_file\f(CW""" 4

   393 .el .IP "\f(CW\-\-file\-ordering \f(CImap_file\f(CW\fR" 4

   394 .IX Item "--file-ordering map_file"

   395 .PD

   396 The \fB\-\-file\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a

   397 suggested .o link line ordering for the program based on profiling data.

   398 This option suggests an ordering which may improve paging, tlb and

   399 cache behavior for the program on systems which do not support arbitrary

   400 ordering of functions in an executable.

   401 .Sp

   402 Use of the \fB\-a\fR argument is highly recommended with this option.

   403 .Sp

   404 The \fImap_file\fR argument is a pathname to a file which provides

   405 function name to object file mappings.  The format of the file is similar to

   406 the output of the program \f(CW\*(C`nm\*(C'\fR.

   407 .Sp

   408 .Vb 8

   409 \&        c-parse.o:00000000 T yyparse

   410 \&        c-parse.o:00000004 C yyerrflag

   411 \&        c-lang.o:00000000 T maybe_objc_method_name

   412 \&        c-lang.o:00000000 T print_lang_statistics

   413 \&        c-lang.o:00000000 T recognize_objc_keyword

   414 \&        c-decl.o:00000000 T print_lang_identifier

   415 \&        c-decl.o:00000000 T print_lang_type

   416 \&        ...

   417 .Ve

   418 .Sp

   419 To create a \fImap_file\fR with \s-1GNU\s0 \f(CW\*(C`nm\*(C'\fR, type a command like

   420 \&\f(CW\*(C`nm \-\-extern\-only \-\-defined\-only \-v \-\-print\-file\-name program\-name\*(C'\fR.

   421 .ie n .IP """\-T""" 4

   422 .el .IP "\f(CW\-T\fR" 4

   423 .IX Item "-T"

   424 .PD 0

   425 .ie n .IP """\-\-traditional""" 4

   426 .el .IP "\f(CW\-\-traditional\fR" 4

   427 .IX Item "--traditional"

   428 .PD

   429 The \fB\-T\fR option causes \f(CW\*(C`gprof\*(C'\fR to print its output in

   430 \&\*(L"traditional\*(R" \s-1BSD\s0 style.

   431 .ie n .IP """\-w \f(CIwidth\f(CW""" 4

   432 .el .IP "\f(CW\-w \f(CIwidth\f(CW\fR" 4

   433 .IX Item "-w width"

   434 .PD 0

   435 .ie n .IP """\-\-width=\f(CIwidth\f(CW""" 4

   436 .el .IP "\f(CW\-\-width=\f(CIwidth\f(CW\fR" 4

   437 .IX Item "--width=width"

   438 .PD

   439 Sets width of output lines to \fIwidth\fR.

   440 Currently only used when printing the function index at the bottom

   441 of the call graph.

   442 .ie n .IP """\-x""" 4

   443 .el .IP "\f(CW\-x\fR" 4

   444 .IX Item "-x"

   445 .PD 0

   446 .ie n .IP """\-\-all\-lines""" 4

   447 .el .IP "\f(CW\-\-all\-lines\fR" 4

   448 .IX Item "--all-lines"

   449 .PD

   450 This option affects annotated source output only.

   451 By default, only the lines at the beginning of a basic-block

   452 are annotated.  If this option is specified, every line in

   453 a basic-block is annotated by repeating the annotation for the

   454 first line.  This behavior is similar to \f(CW\*(C`tcov\*(C'\fR's \fB\-a\fR.

   455 .ie n .IP """\-\-demangle[=\f(CIstyle\f(CW]""" 4

   456 .el .IP "\f(CW\-\-demangle[=\f(CIstyle\f(CW]\fR" 4

   457 .IX Item "--demangle[=style]"

   458 .PD 0

   459 .ie n .IP """\-\-no\-demangle""" 4

   460 .el .IP "\f(CW\-\-no\-demangle\fR" 4

   461 .IX Item "--no-demangle"

   462 .PD

   463 These options control whether \*(C+ symbol names should be demangled when

   464 printing output.  The default is to demangle symbols.  The

   465 \&\f(CW\*(C`\-\-no\-demangle\*(C'\fR option may be used to turn off demangling. Different 

   466 compilers have different mangling styles.  The optional demangling style 

   467 argument can be used to choose an appropriate demangling style for your 

   468 compiler.

   469 .Sh "Analysis Options"

   470 .IX Subsection "Analysis Options"

   471 .ie n .IP """\-a""" 4

   472 .el .IP "\f(CW\-a\fR" 4

   473 .IX Item "-a"

   474 .PD 0

   475 .ie n .IP """\-\-no\-static""" 4

   476 .el .IP "\f(CW\-\-no\-static\fR" 4

   477 .IX Item "--no-static"

   478 .PD

   479 The \fB\-a\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress the printing of

   480 statically declared (private) functions.  (These are functions whose

   481 names are not listed as global, and which are not visible outside the

   482 file/function/block where they were defined.)  Time spent in these

   483 functions, calls to/from them, etc., will all be attributed to the

   484 function that was loaded directly before it in the executable file.

   485 This option affects both the flat profile and the call graph.

   486 .ie n .IP """\-c""" 4

   487 .el .IP "\f(CW\-c\fR" 4

   488 .IX Item "-c"

   489 .PD 0

   490 .ie n .IP """\-\-static\-call\-graph""" 4

   491 .el .IP "\f(CW\-\-static\-call\-graph\fR" 4

   492 .IX Item "--static-call-graph"

   493 .PD

   494 The \fB\-c\fR option causes the call graph of the program to be

   495 augmented by a heuristic which examines the text space of the object

   496 file and identifies function calls in the binary machine code.

   497 Since normal call graph records are only generated when functions are

   498 entered, this option identifies children that could have been called,

   499 but never were.  Calls to functions that were not compiled with

   500 profiling enabled are also identified, but only if symbol table

   501 entries are present for them.

   502 Calls to dynamic library routines are typically \fInot\fR found

   503 by this option.

   504 Parents or children identified via this heuristic

   505 are indicated in the call graph with call counts of \fB0\fR.

   506 .ie n .IP """\-D""" 4

   507 .el .IP "\f(CW\-D\fR" 4

   508 .IX Item "-D"

   509 .PD 0

   510 .ie n .IP """\-\-ignore\-non\-functions""" 4

   511 .el .IP "\f(CW\-\-ignore\-non\-functions\fR" 4

   512 .IX Item "--ignore-non-functions"

   513 .PD

   514 The \fB\-D\fR option causes \f(CW\*(C`gprof\*(C'\fR to ignore symbols which

   515 are not known to be functions.  This option will give more accurate

   516 profile data on systems where it is supported (Solaris and \s-1HPUX\s0 for

   517 example).

   518 .ie n .IP """\-k \f(CIfrom\f(CW/\f(CIto\f(CW""" 4

   519 .el .IP "\f(CW\-k \f(CIfrom\f(CW/\f(CIto\f(CW\fR" 4

   520 .IX Item "-k from/to"

   521 The \fB\-k\fR option allows you to delete from the call graph any arcs from

   522 symbols matching symspec \fIfrom\fR to those matching symspec \fIto\fR.

   523 .ie n .IP """\-l""" 4

   524 .el .IP "\f(CW\-l\fR" 4

   525 .IX Item "-l"

   526 .PD 0

   527 .ie n .IP """\-\-line""" 4

   528 .el .IP "\f(CW\-\-line\fR" 4

   529 .IX Item "--line"

   530 .PD

   531 The \fB\-l\fR option enables line-by-line profiling, which causes

   532 histogram hits to be charged to individual source code lines,

   533 instead of functions.  This feature only works with programs compiled

   534 by older versions of the \f(CW\*(C`gcc\*(C'\fR compiler.  Newer versions of

   535 \&\f(CW\*(C`gcc\*(C'\fR are designed to work with the \f(CW\*(C`gcov\*(C'\fR tool instead.

   536 .Sp

   537 If the program was compiled with basic-block counting enabled,

   538 this option will also identify how many times each line of

   539 code was executed.

   540 While line-by-line profiling can help isolate where in a large function

   541 a program is spending its time, it also significantly increases

   542 the running time of \f(CW\*(C`gprof\*(C'\fR, and magnifies statistical

   543 inaccuracies.

   544 .ie n .IP """\-m \f(CInum\f(CW""" 4

   545 .el .IP "\f(CW\-m \f(CInum\f(CW\fR" 4

   546 .IX Item "-m num"

   547 .PD 0

   548 .ie n .IP """\-\-min\-count=\f(CInum\f(CW""" 4

   549 .el .IP "\f(CW\-\-min\-count=\f(CInum\f(CW\fR" 4

   550 .IX Item "--min-count=num"

   551 .PD

   552 This option affects execution count output only.

   553 Symbols that are executed less than \fInum\fR times are suppressed.

   554 .ie n .IP """\-n\f(CIsymspec\f(CW""" 4

   555 .el .IP "\f(CW\-n\f(CIsymspec\f(CW\fR" 4

   556 .IX Item "-nsymspec"

   557 .PD 0

   558 .ie n .IP """\-\-time=\f(CIsymspec\f(CW""" 4

   559 .el .IP "\f(CW\-\-time=\f(CIsymspec\f(CW\fR" 4

   560 .IX Item "--time=symspec"

   561 .PD

   562 The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis,

   563 to only propagate times for symbols matching \fIsymspec\fR.

   564 .ie n .IP """\-N\f(CIsymspec\f(CW""" 4

   565 .el .IP "\f(CW\-N\f(CIsymspec\f(CW\fR" 4

   566 .IX Item "-Nsymspec"

   567 .PD 0

   568 .ie n .IP """\-\-no\-time=\f(CIsymspec\f(CW""" 4

   569 .el .IP "\f(CW\-\-no\-time=\f(CIsymspec\f(CW\fR" 4

   570 .IX Item "--no-time=symspec"

   571 .PD

   572 The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis,

   573 not to propagate times for symbols matching \fIsymspec\fR.

   574 .ie n .IP """\-z""" 4

   575 .el .IP "\f(CW\-z\fR" 4

   576 .IX Item "-z"

   577 .PD 0

   578 .ie n .IP """\-\-display\-unused\-functions""" 4

   579 .el .IP "\f(CW\-\-display\-unused\-functions\fR" 4

   580 .IX Item "--display-unused-functions"

   581 .PD

   582 If you give the \fB\-z\fR option, \f(CW\*(C`gprof\*(C'\fR will mention all

   583 functions in the flat profile, even those that were never called, and

   584 that had no time spent in them.  This is useful in conjunction with the

   585 \&\fB\-c\fR option for discovering which routines were never called.

   586 .Sh "Miscellaneous Options"

   587 .IX Subsection "Miscellaneous Options"

   588 .ie n .IP """\-d[\f(CInum\f(CW]""" 4

   589 .el .IP "\f(CW\-d[\f(CInum\f(CW]\fR" 4

   590 .IX Item "-d[num]"

   591 .PD 0

   592 .ie n .IP """\-\-debug[=\f(CInum\f(CW]""" 4

   593 .el .IP "\f(CW\-\-debug[=\f(CInum\f(CW]\fR" 4

   594 .IX Item "--debug[=num]"

   595 .PD

   596 The \fB\-d\fR \fInum\fR option specifies debugging options.

   597 If \fInum\fR is not specified, enable all debugging.

   598 .ie n .IP """\-h""" 4

   599 .el .IP "\f(CW\-h\fR" 4

   600 .IX Item "-h"

   601 .PD 0

   602 .ie n .IP """\-\-help""" 4

   603 .el .IP "\f(CW\-\-help\fR" 4

   604 .IX Item "--help"

   605 .PD

   606 The \fB\-h\fR option prints command line usage.

   607 .ie n .IP """\-O\f(CIname\f(CW""" 4

   608 .el .IP "\f(CW\-O\f(CIname\f(CW\fR" 4

   609 .IX Item "-Oname"

   610 .PD 0

   611 .ie n .IP """\-\-file\-format=\f(CIname\f(CW""" 4

   612 .el .IP "\f(CW\-\-file\-format=\f(CIname\f(CW\fR" 4

   613 .IX Item "--file-format=name"

   614 .PD

   615 Selects the format of the profile data files.  Recognized formats are

   616 \&\fBauto\fR (the default), \fBbsd\fR, \fB4.4bsd\fR, \fBmagic\fR, and

   617 \&\fBprof\fR (not yet supported).

   618 .ie n .IP """\-s""" 4

   619 .el .IP "\f(CW\-s\fR" 4

   620 .IX Item "-s"

   621 .PD 0

   622 .ie n .IP """\-\-sum""" 4

   623 .el .IP "\f(CW\-\-sum\fR" 4

   624 .IX Item "--sum"

   625 .PD

   626 The \fB\-s\fR option causes \f(CW\*(C`gprof\*(C'\fR to summarize the information

   627 in the profile data files it read in, and write out a profile data

   628 file called \fIgmon.sum\fR, which contains all the information from

   629 the profile data files that \f(CW\*(C`gprof\*(C'\fR read in.  The file \fIgmon.sum\fR

   630 may be one of the specified input files; the effect of this is to

   631 merge the data in the other input files into \fIgmon.sum\fR.

   632 .Sp

   633 Eventually you can run \f(CW\*(C`gprof\*(C'\fR again without \fB\-s\fR to analyze the

   634 cumulative data in the file \fIgmon.sum\fR.

   635 .ie n .IP """\-v""" 4

   636 .el .IP "\f(CW\-v\fR" 4

   637 .IX Item "-v"

   638 .PD 0

   639 .ie n .IP """\-\-version""" 4

   640 .el .IP "\f(CW\-\-version\fR" 4

   641 .IX Item "--version"

   642 .PD

   643 The \fB\-v\fR flag causes \f(CW\*(C`gprof\*(C'\fR to print the current version

   644 number, and then exit.

   645 .Sh "Deprecated Options"

   646 .IX Subsection "Deprecated Options"

   647 .RS 4

   648 These options have been replaced with newer versions that use symspecs.

   649 .RE

   650 .ie n .IP """\-e \f(CIfunction_name\f(CW""" 4

   651 .el .IP "\f(CW\-e \f(CIfunction_name\f(CW\fR" 4

   652 .IX Item "-e function_name"

   653 The \fB\-e\fR \fIfunction\fR option tells \f(CW\*(C`gprof\*(C'\fR to not print

   654 information about the function \fIfunction_name\fR (and its

   655 children...) in the call graph.  The function will still be listed

   656 as a child of any functions that call it, but its index number will be

   657 shown as \fB[not printed]\fR.  More than one \fB\-e\fR option may be

   658 given; only one \fIfunction_name\fR may be indicated with each \fB\-e\fR

   659 option. 

   660 .ie n .IP """\-E \f(CIfunction_name\f(CW""" 4

   661 .el .IP "\f(CW\-E \f(CIfunction_name\f(CW\fR" 4

   662 .IX Item "-E function_name"

   663 The \f(CW\*(C`\-E \f(CIfunction\f(CW\*(C'\fR option works like the \f(CW\*(C`\-e\*(C'\fR option, but

   664 time spent in the function (and children who were not called from

   665 anywhere else), will not be used to compute the percentages-of-time for

   666 the call graph.  More than one \fB\-E\fR option may be given; only one

   667 \&\fIfunction_name\fR may be indicated with each \fB\-E\fR option.

   668 .ie n .IP """\-f \f(CIfunction_name\f(CW""" 4

   669 .el .IP "\f(CW\-f \f(CIfunction_name\f(CW\fR" 4

   670 .IX Item "-f function_name"

   671 The \fB\-f\fR \fIfunction\fR option causes \f(CW\*(C`gprof\*(C'\fR to limit the

   672 call graph to the function \fIfunction_name\fR and its children (and

   673 their children...).  More than one \fB\-f\fR option may be given;

   674 only one \fIfunction_name\fR may be indicated with each \fB\-f\fR

   675 option.  

   676 .ie n .IP """\-F \f(CIfunction_name\f(CW""" 4

   677 .el .IP "\f(CW\-F \f(CIfunction_name\f(CW\fR" 4

   678 .IX Item "-F function_name"

   679 The \fB\-F\fR \fIfunction\fR option works like the \f(CW\*(C`\-f\*(C'\fR option, but

   680 only time spent in the function and its children (and their

   681 children...) will be used to determine total-time and

   682 percentages-of-time for the call graph.  More than one \fB\-F\fR option

   683 may be given; only one \fIfunction_name\fR may be indicated with each

   684 \&\fB\-F\fR option.  The \fB\-F\fR option overrides the \fB\-E\fR option.

   685 .SH "FILES"

   686 .IX Header "FILES"

   687 .ie n .IP """\f(CIa.out\f(CW""" 4

   688 .el .IP "\f(CW\f(CIa.out\f(CW\fR" 4

   689 .IX Item "a.out"

   690 the namelist and text space.

   691 .ie n .IP """\f(CIgmon.out\f(CW""" 4

   692 .el .IP "\f(CW\f(CIgmon.out\f(CW\fR" 4

   693 .IX Item "gmon.out"

   694 dynamic call graph and profile.

   695 .ie n .IP """\f(CIgmon.sum\f(CW""" 4

   696 .el .IP "\f(CW\f(CIgmon.sum\f(CW\fR" 4

   697 .IX Item "gmon.sum"

   698 summarized dynamic call graph and profile.  

   699 .SH "BUGS"

   700 .IX Header "BUGS"

   701 The granularity of the sampling is shown, but remains

   702 statistical at best.

   703 We assume that the time for each execution of a function

   704 can be expressed by the total time for the function divided

   705 by the number of times the function is called.

   706 Thus the time propagated along the call graph arcs to the function's

   707 parents is directly proportional to the number of times that

   708 arc is traversed.

   709 .PP

   710 Parents that are not themselves profiled will have the time of

   711 their profiled children propagated to them, but they will appear

   712 to be spontaneously invoked in the call graph listing, and will

   713 not have their time propagated further.

   714 Similarly, signal catchers, even though profiled, will appear

   715 to be spontaneous (although for more obscure reasons).

   716 Any profiled children of signal catchers should have their times

   717 propagated properly, unless the signal catcher was invoked during

   718 the execution of the profiling routine, in which case all is lost.

   719 .PP

   720 The profiled program must call \f(CW\*(C`exit\*(C'\fR(2)

   721 or return normally for the profiling information to be saved

   722 in the \fIgmon.out\fR file.

   723 .SH "SEE ALSO"

   724 .IX Header "SEE ALSO"

   725 \&\fImonitor\fR\|(3), \fIprofil\fR\|(2), \fIcc\fR\|(1), \fIprof\fR\|(1), and the Info entry for \fIgprof\fR.

   726 .PP

   727 \&\*(L"An Execution Profiler for Modular Programs\*(R",

   728 by S. Graham, P. Kessler, M. McKusick;

   729 Software \- Practice and Experience,

   730 Vol. 13, pp. 671\-685, 1983.

   731 .PP

   732 \&\*(L"gprof: A Call Graph Execution Profiler\*(R",

   733 by S. Graham, P. Kessler, M. McKusick;

   734 Proceedings of the \s-1SIGPLAN\s0 '82 Symposium on Compiler Construction,

   735 \&\s-1SIGPLAN\s0 Notices, Vol. 17, No  6, pp. 120\-126, June 1982.

   736 .SH "COPYRIGHT"

   737 .IX Header "COPYRIGHT"

   738 Copyright (c) 1988, 92, 97, 98, 99, 2000, 2001, 2003, 2007 Free Software Foundation, Inc.

   739 .PP

   740 Permission is granted to copy, distribute and/or modify this document

   741 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1

   742 or any later version published by the Free Software Foundation;

   743 with no Invariant Sections, with no Front-Cover Texts, and with no

   744 Back-Cover Texts.  A copy of the license is included in the

   745 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".