Debian Codegraph @

upstream/debian-unstable/man1/gprof.1

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