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