Debian Codegraph @

upstream/opensuse-tumbleweed/man1/gprof.1

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