| .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) |
| .\" |
| .\" Standard preamble: |
| .\" ======================================================================== |
| .de Sp \" Vertical space (when we can't use .PP) |
| .if t .sp .5v |
| .if n .sp |
| .. |
| .de Vb \" Begin verbatim text |
| .ft CW |
| .nf |
| .ne \\$1 |
| .. |
| .de Ve \" End verbatim text |
| .ft R |
| .fi |
| .. |
| .\" Set up some character translations and predefined strings. \*(-- will |
| .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
| .\" give a nicer C++. Capital omega is used to do unbreakable dashes and |
| .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, |
| .\" nothing in troff, for use with C<>. |
| .tr \(*W- |
| .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| .ie n \{\ |
| . ds -- \(*W- |
| . ds PI pi |
| . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| . ds L" "" |
| . ds R" "" |
| . ds C` "" |
| . ds C' "" |
| 'br\} |
| .el\{\ |
| . ds -- \|\(em\| |
| . ds PI \(*p |
| . ds L" `` |
| . ds R" '' |
| 'br\} |
| .\" |
| .\" Escape single quotes in literal strings from groff's Unicode transform. |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" |
| .\" If the F register is turned on, we'll generate index entries on stderr for |
| .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| .\" entries marked with X<> in POD. Of course, you'll have to process the |
| .\" output yourself in some meaningful fashion. |
| .ie \nF \{\ |
| . de IX |
| . tm Index:\\$1\t\\n%\t"\\$2" |
| .. |
| . nr % 0 |
| . rr F |
| .\} |
| .el \{\ |
| . de IX |
| .. |
| .\} |
| .\" |
| .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| .\" Fear. Run. Save yourself. No user-serviceable parts. |
| . \" fudge factors for nroff and troff |
| .if n \{\ |
| . ds #H 0 |
| . ds #V .8m |
| . ds #F .3m |
| . ds #[ \f1 |
| . ds #] \fP |
| .\} |
| .if t \{\ |
| . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| . ds #V .6m |
| . ds #F 0 |
| . ds #[ \& |
| . ds #] \& |
| .\} |
| . \" simple accents for nroff and troff |
| .if n \{\ |
| . ds ' \& |
| . ds ` \& |
| . ds ^ \& |
| . ds , \& |
| . ds ~ ~ |
| . ds / |
| .\} |
| .if t \{\ |
| . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| .\} |
| . \" troff and (daisy-wheel) nroff accents |
| .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| .ds ae a\h'-(\w'a'u*4/10)'e |
| .ds Ae A\h'-(\w'A'u*4/10)'E |
| . \" corrections for vroff |
| .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| . \" for low resolution devices (crt and lpr) |
| .if \n(.H>23 .if \n(.V>19 \ |
| \{\ |
| . ds : e |
| . ds 8 ss |
| . ds o a |
| . ds d- d\h'-1'\(ga |
| . ds D- D\h'-1'\(hy |
| . ds th \o'bp' |
| . ds Th \o'LP' |
| . ds ae ae |
| . ds Ae AE |
| .\} |
| .rm #[ #] #H #V #F C |
| .\" ======================================================================== |
| .\" |
| .IX Title "GPROF 1" |
| .TH GPROF 1 "2013-05-12" "binutils-2.23.52.0.2" "GNU" |
| .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| .\" way too many mistakes in technical documents. |
| .if n .ad l |
| .nh |
| .SH "NAME" |
| gprof \- display call graph profile data |
| .SH "SYNOPSIS" |
| .IX Header "SYNOPSIS" |
| gprof [ \-[abcDhilLrsTvwxyz] ] [ \-[ACeEfFJnNOpPqQZ][\fIname\fR] ] |
| [ \-I \fIdirs\fR ] [ \-d[\fInum\fR] ] [ \-k \fIfrom/to\fR ] |
| [ \-m \fImin-count\fR ] [ \-R \fImap_file\fR ] [ \-t \fItable-length\fR ] |
| [ \-\-[no\-]annotated\-source[=\fIname\fR] ] |
| [ \-\-[no\-]exec\-counts[=\fIname\fR] ] |
| [ \-\-[no\-]flat\-profile[=\fIname\fR] ] [ \-\-[no\-]graph[=\fIname\fR] ] |
| [ \-\-[no\-]time=\fIname\fR] [ \-\-all\-lines ] [ \-\-brief ] |
| [ \-\-debug[=\fIlevel\fR] ] [ \-\-function\-ordering ] |
| [ \-\-file\-ordering \fImap_file\fR ] [ \-\-directory\-path=\fIdirs\fR ] |
| [ \-\-display\-unused\-functions ] [ \-\-file\-format=\fIname\fR ] |
| [ \-\-file\-info ] [ \-\-help ] [ \-\-line ] [ \-\-min\-count=\fIn\fR ] |
| [ \-\-no\-static ] [ \-\-print\-path ] [ \-\-separate\-files ] |
| [ \-\-static\-call\-graph ] [ \-\-sum ] [ \-\-table\-length=\fIlen\fR ] |
| [ \-\-traditional ] [ \-\-version ] [ \-\-width=\fIn\fR ] |
| [ \-\-ignore\-non\-functions ] [ \-\-demangle[=\fI\s-1STYLE\s0\fR] ] |
| [ \-\-no\-demangle ] [\-\-external\-symbol\-table=name] |
| [ \fIimage-file\fR ] [ \fIprofile-file\fR ... ] |
| .SH "DESCRIPTION" |
| .IX Header "DESCRIPTION" |
| \&\f(CW\*(C`gprof\*(C'\fR produces an execution profile of C, Pascal, or Fortran77 |
| programs. The effect of called routines is incorporated in the profile |
| of each caller. The profile data is taken from the call graph profile file |
| (\fIgmon.out\fR default) which is created by programs |
| that are compiled with the \fB\-pg\fR option of |
| \&\f(CW\*(C`cc\*(C'\fR, \f(CW\*(C`pc\*(C'\fR, and \f(CW\*(C`f77\*(C'\fR. |
| The \fB\-pg\fR option also links in versions of the library routines |
| that are compiled for profiling. \f(CW\*(C`Gprof\*(C'\fR reads the given object |
| file (the default is \f(CW\*(C`a.out\*(C'\fR) and establishes the relation between |
| its symbol table and the call graph profile from \fIgmon.out\fR. |
| If more than one profile file is specified, the \f(CW\*(C`gprof\*(C'\fR |
| output shows the sum of the profile information in the given profile files. |
| .PP |
| \&\f(CW\*(C`Gprof\*(C'\fR calculates the amount of time spent in each routine. |
| Next, these times are propagated along the edges of the call graph. |
| Cycles are discovered, and calls into a cycle are made to share the time |
| of the cycle. |
| .PP |
| Several forms of output are available from the analysis. |
| .PP |
| The \fIflat profile\fR shows how much time your program spent in each function, |
| and how many times that function was called. If you simply want to know |
| which functions burn most of the cycles, it is stated concisely here. |
| .PP |
| The \fIcall graph\fR shows, for each function, which functions called it, which |
| other functions it called, and how many times. There is also an estimate |
| of how much time was spent in the subroutines of each function. This can |
| suggest places where you might try to eliminate function calls that use a |
| lot of time. |
| .PP |
| The \fIannotated source\fR listing is a copy of the program's |
| source code, labeled with the number of times each line of the |
| program was executed. |
| .SH "OPTIONS" |
| .IX Header "OPTIONS" |
| These options specify which of several output formats |
| \&\f(CW\*(C`gprof\*(C'\fR should produce. |
| .PP |
| Many of these options take an optional \fIsymspec\fR to specify |
| functions to be included or excluded. These options can be |
| specified multiple times, with different symspecs, to include |
| or exclude sets of symbols. |
| .PP |
| Specifying any of these options overrides the default (\fB\-p \-q\fR), |
| which prints a flat profile and call graph analysis |
| for all functions. |
| .ie n .IP """\-A[\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-A[\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "-A[symspec]" |
| .PD 0 |
| .ie n .IP """\-\-annotated\-source[=\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "--annotated-source[=symspec]" |
| .PD |
| The \fB\-A\fR option causes \f(CW\*(C`gprof\*(C'\fR to print annotated source code. |
| If \fIsymspec\fR is specified, print output only for matching symbols. |
| .ie n .IP """\-b""" 4 |
| .el .IP "\f(CW\-b\fR" 4 |
| .IX Item "-b" |
| .PD 0 |
| .ie n .IP """\-\-brief""" 4 |
| .el .IP "\f(CW\-\-brief\fR" 4 |
| .IX Item "--brief" |
| .PD |
| If the \fB\-b\fR option is given, \f(CW\*(C`gprof\*(C'\fR doesn't print the |
| verbose blurbs that try to explain the meaning of all of the fields in |
| the tables. This is useful if you intend to print out the output, or |
| are tired of seeing the blurbs. |
| .ie n .IP """\-C[\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-C[\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "-C[symspec]" |
| .PD 0 |
| .ie n .IP """\-\-exec\-counts[=\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "--exec-counts[=symspec]" |
| .PD |
| The \fB\-C\fR option causes \f(CW\*(C`gprof\*(C'\fR to |
| print a tally of functions and the number of times each was called. |
| If \fIsymspec\fR is specified, print tally only for matching symbols. |
| .Sp |
| If the profile data file contains basic-block count records, specifying |
| the \fB\-l\fR option, along with \fB\-C\fR, will cause basic-block |
| execution counts to be tallied and displayed. |
| .ie n .IP """\-i""" 4 |
| .el .IP "\f(CW\-i\fR" 4 |
| .IX Item "-i" |
| .PD 0 |
| .ie n .IP """\-\-file\-info""" 4 |
| .el .IP "\f(CW\-\-file\-info\fR" 4 |
| .IX Item "--file-info" |
| .PD |
| The \fB\-i\fR option causes \f(CW\*(C`gprof\*(C'\fR to display summary information |
| about the profile data file(s) and then exit. The number of histogram, |
| call graph, and basic-block count records is displayed. |
| .ie n .IP """\-I \f(CIdirs\f(CW""" 4 |
| .el .IP "\f(CW\-I \f(CIdirs\f(CW\fR" 4 |
| .IX Item "-I dirs" |
| .PD 0 |
| .ie n .IP """\-\-directory\-path=\f(CIdirs\f(CW""" 4 |
| .el .IP "\f(CW\-\-directory\-path=\f(CIdirs\f(CW\fR" 4 |
| .IX Item "--directory-path=dirs" |
| .PD |
| The \fB\-I\fR option specifies a list of search directories in |
| which to find source files. Environment variable \fI\s-1GPROF_PATH\s0\fR |
| can also be used to convey this information. |
| Used mostly for annotated source output. |
| .ie n .IP """\-J[\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-J[\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "-J[symspec]" |
| .PD 0 |
| .ie n .IP """\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "--no-annotated-source[=symspec]" |
| .PD |
| The \fB\-J\fR option causes \f(CW\*(C`gprof\*(C'\fR not to |
| print annotated source code. |
| If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints annotated source, |
| but excludes matching symbols. |
| .ie n .IP """\-L""" 4 |
| .el .IP "\f(CW\-L\fR" 4 |
| .IX Item "-L" |
| .PD 0 |
| .ie n .IP """\-\-print\-path""" 4 |
| .el .IP "\f(CW\-\-print\-path\fR" 4 |
| .IX Item "--print-path" |
| .PD |
| Normally, source filenames are printed with the path |
| component suppressed. The \fB\-L\fR option causes \f(CW\*(C`gprof\*(C'\fR |
| to print the full pathname of |
| source filenames, which is determined |
| from symbolic debugging information in the image file |
| and is relative to the directory in which the compiler |
| was invoked. |
| .ie n .IP """\-p[\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-p[\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "-p[symspec]" |
| .PD 0 |
| .ie n .IP """\-\-flat\-profile[=\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "--flat-profile[=symspec]" |
| .PD |
| The \fB\-p\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a flat profile. |
| If \fIsymspec\fR is specified, print flat profile only for matching symbols. |
| .ie n .IP """\-P[\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-P[\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "-P[symspec]" |
| .PD 0 |
| .ie n .IP """\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "--no-flat-profile[=symspec]" |
| .PD |
| The \fB\-P\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing a flat profile. |
| If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a flat profile, |
| but excludes matching symbols. |
| .ie n .IP """\-q[\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-q[\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "-q[symspec]" |
| .PD 0 |
| .ie n .IP """\-\-graph[=\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-\-graph[=\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "--graph[=symspec]" |
| .PD |
| The \fB\-q\fR option causes \f(CW\*(C`gprof\*(C'\fR to print the call graph analysis. |
| If \fIsymspec\fR is specified, print call graph only for matching symbols |
| and their children. |
| .ie n .IP """\-Q[\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-Q[\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "-Q[symspec]" |
| .PD 0 |
| .ie n .IP """\-\-no\-graph[=\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-\-no\-graph[=\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "--no-graph[=symspec]" |
| .PD |
| The \fB\-Q\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress printing the |
| call graph. |
| If \fIsymspec\fR is specified, \f(CW\*(C`gprof\*(C'\fR prints a call graph, |
| but excludes matching symbols. |
| .ie n .IP """\-t""" 4 |
| .el .IP "\f(CW\-t\fR" 4 |
| .IX Item "-t" |
| .PD 0 |
| .ie n .IP """\-\-table\-length=\f(CInum\f(CW""" 4 |
| .el .IP "\f(CW\-\-table\-length=\f(CInum\f(CW\fR" 4 |
| .IX Item "--table-length=num" |
| .PD |
| The \fB\-t\fR option causes the \fInum\fR most active source lines in |
| each source file to be listed when source annotation is enabled. The |
| default is 10. |
| .ie n .IP """\-y""" 4 |
| .el .IP "\f(CW\-y\fR" 4 |
| .IX Item "-y" |
| .PD 0 |
| .ie n .IP """\-\-separate\-files""" 4 |
| .el .IP "\f(CW\-\-separate\-files\fR" 4 |
| .IX Item "--separate-files" |
| .PD |
| This option affects annotated source output only. |
| Normally, \f(CW\*(C`gprof\*(C'\fR prints annotated source files |
| to standard-output. If this option is specified, |
| annotated source for a file named \fIpath/\fIfilename\fI\fR |
| is generated in the file \fI\fIfilename\fI\-ann\fR. If the underlying |
| file system would truncate \fI\fIfilename\fI\-ann\fR so that it |
| overwrites the original \fI\fIfilename\fI\fR, \f(CW\*(C`gprof\*(C'\fR generates |
| annotated source in the file \fI\fIfilename\fI.ann\fR instead (if the |
| original file name has an extension, that extension is \fIreplaced\fR |
| with \fI.ann\fR). |
| .ie n .IP """\-Z[\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-Z[\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "-Z[symspec]" |
| .PD 0 |
| .ie n .IP """\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]""" 4 |
| .el .IP "\f(CW\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]\fR" 4 |
| .IX Item "--no-exec-counts[=symspec]" |
| .PD |
| The \fB\-Z\fR option causes \f(CW\*(C`gprof\*(C'\fR not to |
| print a tally of functions and the number of times each was called. |
| If \fIsymspec\fR is specified, print tally, but exclude matching symbols. |
| .ie n .IP """\-r""" 4 |
| .el .IP "\f(CW\-r\fR" 4 |
| .IX Item "-r" |
| .PD 0 |
| .ie n .IP """\-\-function\-ordering""" 4 |
| .el .IP "\f(CW\-\-function\-ordering\fR" 4 |
| .IX Item "--function-ordering" |
| .PD |
| The \fB\-\-function\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a |
| suggested function ordering for the program based on profiling data. |
| This option suggests an ordering which may improve paging, tlb and |
| cache behavior for the program on systems which support arbitrary |
| ordering of functions in an executable. |
| .Sp |
| The exact details of how to force the linker to place functions |
| in a particular order is system dependent and out of the scope of this |
| manual. |
| .ie n .IP """\-R \f(CImap_file\f(CW""" 4 |
| .el .IP "\f(CW\-R \f(CImap_file\f(CW\fR" 4 |
| .IX Item "-R map_file" |
| .PD 0 |
| .ie n .IP """\-\-file\-ordering \f(CImap_file\f(CW""" 4 |
| .el .IP "\f(CW\-\-file\-ordering \f(CImap_file\f(CW\fR" 4 |
| .IX Item "--file-ordering map_file" |
| .PD |
| The \fB\-\-file\-ordering\fR option causes \f(CW\*(C`gprof\*(C'\fR to print a |
| suggested .o link line ordering for the program based on profiling data. |
| This option suggests an ordering which may improve paging, tlb and |
| cache behavior for the program on systems which do not support arbitrary |
| ordering of functions in an executable. |
| .Sp |
| Use of the \fB\-a\fR argument is highly recommended with this option. |
| .Sp |
| The \fImap_file\fR argument is a pathname to a file which provides |
| function name to object file mappings. The format of the file is similar to |
| the output of the program \f(CW\*(C`nm\*(C'\fR. |
| .Sp |
| .Vb 8 |
| \& c\-parse.o:00000000 T yyparse |
| \& c\-parse.o:00000004 C yyerrflag |
| \& c\-lang.o:00000000 T maybe_objc_method_name |
| \& c\-lang.o:00000000 T print_lang_statistics |
| \& c\-lang.o:00000000 T recognize_objc_keyword |
| \& c\-decl.o:00000000 T print_lang_identifier |
| \& c\-decl.o:00000000 T print_lang_type |
| \& ... |
| .Ve |
| .Sp |
| To create a \fImap_file\fR with \s-1GNU\s0 \f(CW\*(C`nm\*(C'\fR, type a command like |
| \&\f(CW\*(C`nm \-\-extern\-only \-\-defined\-only \-v \-\-print\-file\-name program\-name\*(C'\fR. |
| .ie n .IP """\-T""" 4 |
| .el .IP "\f(CW\-T\fR" 4 |
| .IX Item "-T" |
| .PD 0 |
| .ie n .IP """\-\-traditional""" 4 |
| .el .IP "\f(CW\-\-traditional\fR" 4 |
| .IX Item "--traditional" |
| .PD |
| The \fB\-T\fR option causes \f(CW\*(C`gprof\*(C'\fR to print its output in |
| \&\*(L"traditional\*(R" \s-1BSD\s0 style. |
| .ie n .IP """\-w \f(CIwidth\f(CW""" 4 |
| .el .IP "\f(CW\-w \f(CIwidth\f(CW\fR" 4 |
| .IX Item "-w width" |
| .PD 0 |
| .ie n .IP """\-\-width=\f(CIwidth\f(CW""" 4 |
| .el .IP "\f(CW\-\-width=\f(CIwidth\f(CW\fR" 4 |
| .IX Item "--width=width" |
| .PD |
| Sets width of output lines to \fIwidth\fR. |
| Currently only used when printing the function index at the bottom |
| of the call graph. |
| .ie n .IP """\-x""" 4 |
| .el .IP "\f(CW\-x\fR" 4 |
| .IX Item "-x" |
| .PD 0 |
| .ie n .IP """\-\-all\-lines""" 4 |
| .el .IP "\f(CW\-\-all\-lines\fR" 4 |
| .IX Item "--all-lines" |
| .PD |
| This option affects annotated source output only. |
| By default, only the lines at the beginning of a basic-block |
| are annotated. If this option is specified, every line in |
| a basic-block is annotated by repeating the annotation for the |
| first line. This behavior is similar to \f(CW\*(C`tcov\*(C'\fR's \fB\-a\fR. |
| .ie n .IP """\-\-demangle[=\f(CIstyle\f(CW]""" 4 |
| .el .IP "\f(CW\-\-demangle[=\f(CIstyle\f(CW]\fR" 4 |
| .IX Item "--demangle[=style]" |
| .PD 0 |
| .ie n .IP """\-\-no\-demangle""" 4 |
| .el .IP "\f(CW\-\-no\-demangle\fR" 4 |
| .IX Item "--no-demangle" |
| .PD |
| These options control whether \*(C+ symbol names should be demangled when |
| printing output. The default is to demangle symbols. The |
| \&\f(CW\*(C`\-\-no\-demangle\*(C'\fR option may be used to turn off demangling. Different |
| compilers have different mangling styles. The optional demangling style |
| argument can be used to choose an appropriate demangling style for your |
| compiler. |
| .SS "Analysis Options" |
| .IX Subsection "Analysis Options" |
| .ie n .IP """\-a""" 4 |
| .el .IP "\f(CW\-a\fR" 4 |
| .IX Item "-a" |
| .PD 0 |
| .ie n .IP """\-\-no\-static""" 4 |
| .el .IP "\f(CW\-\-no\-static\fR" 4 |
| .IX Item "--no-static" |
| .PD |
| The \fB\-a\fR option causes \f(CW\*(C`gprof\*(C'\fR to suppress the printing of |
| statically declared (private) functions. (These are functions whose |
| names are not listed as global, and which are not visible outside the |
| file/function/block where they were defined.) Time spent in these |
| functions, calls to/from them, etc., will all be attributed to the |
| function that was loaded directly before it in the executable file. |
| This option affects both the flat profile and the call graph. |
| .ie n .IP """\-c""" 4 |
| .el .IP "\f(CW\-c\fR" 4 |
| .IX Item "-c" |
| .PD 0 |
| .ie n .IP """\-\-static\-call\-graph""" 4 |
| .el .IP "\f(CW\-\-static\-call\-graph\fR" 4 |
| .IX Item "--static-call-graph" |
| .PD |
| The \fB\-c\fR option causes the call graph of the program to be |
| augmented by a heuristic which examines the text space of the object |
| file and identifies function calls in the binary machine code. |
| Since normal call graph records are only generated when functions are |
| entered, this option identifies children that could have been called, |
| but never were. Calls to functions that were not compiled with |
| profiling enabled are also identified, but only if symbol table |
| entries are present for them. |
| Calls to dynamic library routines are typically \fInot\fR found |
| by this option. |
| Parents or children identified via this heuristic |
| are indicated in the call graph with call counts of \fB0\fR. |
| .ie n .IP """\-D""" 4 |
| .el .IP "\f(CW\-D\fR" 4 |
| .IX Item "-D" |
| .PD 0 |
| .ie n .IP """\-\-ignore\-non\-functions""" 4 |
| .el .IP "\f(CW\-\-ignore\-non\-functions\fR" 4 |
| .IX Item "--ignore-non-functions" |
| .PD |
| The \fB\-D\fR option causes \f(CW\*(C`gprof\*(C'\fR to ignore symbols which |
| are not known to be functions. This option will give more accurate |
| profile data on systems where it is supported (Solaris and \s-1HPUX\s0 for |
| example). |
| .ie n .IP """\-k \f(CIfrom\f(CW/\f(CIto\f(CW""" 4 |
| .el .IP "\f(CW\-k \f(CIfrom\f(CW/\f(CIto\f(CW\fR" 4 |
| .IX Item "-k from/to" |
| The \fB\-k\fR option allows you to delete from the call graph any arcs from |
| symbols matching symspec \fIfrom\fR to those matching symspec \fIto\fR. |
| .ie n .IP """\-l""" 4 |
| .el .IP "\f(CW\-l\fR" 4 |
| .IX Item "-l" |
| .PD 0 |
| .ie n .IP """\-\-line""" 4 |
| .el .IP "\f(CW\-\-line\fR" 4 |
| .IX Item "--line" |
| .PD |
| The \fB\-l\fR option enables line-by-line profiling, which causes |
| histogram hits to be charged to individual source code lines, |
| instead of functions. This feature only works with programs compiled |
| by older versions of the \f(CW\*(C`gcc\*(C'\fR compiler. Newer versions of |
| \&\f(CW\*(C`gcc\*(C'\fR are designed to work with the \f(CW\*(C`gcov\*(C'\fR tool instead. |
| .Sp |
| If the program was compiled with basic-block counting enabled, |
| this option will also identify how many times each line of |
| code was executed. |
| While line-by-line profiling can help isolate where in a large function |
| a program is spending its time, it also significantly increases |
| the running time of \f(CW\*(C`gprof\*(C'\fR, and magnifies statistical |
| inaccuracies. |
| .ie n .IP """\-m \f(CInum\f(CW""" 4 |
| .el .IP "\f(CW\-m \f(CInum\f(CW\fR" 4 |
| .IX Item "-m num" |
| .PD 0 |
| .ie n .IP """\-\-min\-count=\f(CInum\f(CW""" 4 |
| .el .IP "\f(CW\-\-min\-count=\f(CInum\f(CW\fR" 4 |
| .IX Item "--min-count=num" |
| .PD |
| This option affects execution count output only. |
| Symbols that are executed less than \fInum\fR times are suppressed. |
| .ie n .IP """\-n\f(CIsymspec\f(CW""" 4 |
| .el .IP "\f(CW\-n\f(CIsymspec\f(CW\fR" 4 |
| .IX Item "-nsymspec" |
| .PD 0 |
| .ie n .IP """\-\-time=\f(CIsymspec\f(CW""" 4 |
| .el .IP "\f(CW\-\-time=\f(CIsymspec\f(CW\fR" 4 |
| .IX Item "--time=symspec" |
| .PD |
| The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis, |
| to only propagate times for symbols matching \fIsymspec\fR. |
| .ie n .IP """\-N\f(CIsymspec\f(CW""" 4 |
| .el .IP "\f(CW\-N\f(CIsymspec\f(CW\fR" 4 |
| .IX Item "-Nsymspec" |
| .PD 0 |
| .ie n .IP """\-\-no\-time=\f(CIsymspec\f(CW""" 4 |
| .el .IP "\f(CW\-\-no\-time=\f(CIsymspec\f(CW\fR" 4 |
| .IX Item "--no-time=symspec" |
| .PD |
| The \fB\-n\fR option causes \f(CW\*(C`gprof\*(C'\fR, in its call graph analysis, |
| not to propagate times for symbols matching \fIsymspec\fR. |
| .ie n .IP """\-S\f(CIfilename\f(CW""" 4 |
| .el .IP "\f(CW\-S\f(CIfilename\f(CW\fR" 4 |
| .IX Item "-Sfilename" |
| .PD 0 |
| .ie n .IP """\-\-external\-symbol\-table=\f(CIfilename\f(CW""" 4 |
| .el .IP "\f(CW\-\-external\-symbol\-table=\f(CIfilename\f(CW\fR" 4 |
| .IX Item "--external-symbol-table=filename" |
| .PD |
| The \fB\-S\fR option causes \f(CW\*(C`gprof\*(C'\fR to read an external symbol table |
| file, such as \fI/proc/kallsyms\fR, rather than read the symbol table |
| from the given object file (the default is \f(CW\*(C`a.out\*(C'\fR). This is useful |
| for profiling kernel modules. |
| .ie n .IP """\-z""" 4 |
| .el .IP "\f(CW\-z\fR" 4 |
| .IX Item "-z" |
| .PD 0 |
| .ie n .IP """\-\-display\-unused\-functions""" 4 |
| .el .IP "\f(CW\-\-display\-unused\-functions\fR" 4 |
| .IX Item "--display-unused-functions" |
| .PD |
| If you give the \fB\-z\fR option, \f(CW\*(C`gprof\*(C'\fR will mention all |
| functions in the flat profile, even those that were never called, and |
| that had no time spent in them. This is useful in conjunction with the |
| \&\fB\-c\fR option for discovering which routines were never called. |
| .SS "Miscellaneous Options" |
| .IX Subsection "Miscellaneous Options" |
| .ie n .IP """\-d[\f(CInum\f(CW]""" 4 |
| .el .IP "\f(CW\-d[\f(CInum\f(CW]\fR" 4 |
| .IX Item "-d[num]" |
| .PD 0 |
| .ie n .IP """\-\-debug[=\f(CInum\f(CW]""" 4 |
| .el .IP "\f(CW\-\-debug[=\f(CInum\f(CW]\fR" 4 |
| .IX Item "--debug[=num]" |
| .PD |
| The \fB\-d\fR \fInum\fR option specifies debugging options. |
| If \fInum\fR is not specified, enable all debugging. |
| .ie n .IP """\-h""" 4 |
| .el .IP "\f(CW\-h\fR" 4 |
| .IX Item "-h" |
| .PD 0 |
| .ie n .IP """\-\-help""" 4 |
| .el .IP "\f(CW\-\-help\fR" 4 |
| .IX Item "--help" |
| .PD |
| The \fB\-h\fR option prints command line usage. |
| .ie n .IP """\-O\f(CIname\f(CW""" 4 |
| .el .IP "\f(CW\-O\f(CIname\f(CW\fR" 4 |
| .IX Item "-Oname" |
| .PD 0 |
| .ie n .IP """\-\-file\-format=\f(CIname\f(CW""" 4 |
| .el .IP "\f(CW\-\-file\-format=\f(CIname\f(CW\fR" 4 |
| .IX Item "--file-format=name" |
| .PD |
| Selects the format of the profile data files. Recognized formats are |
| \&\fBauto\fR (the default), \fBbsd\fR, \fB4.4bsd\fR, \fBmagic\fR, and |
| \&\fBprof\fR (not yet supported). |
| .ie n .IP """\-s""" 4 |
| .el .IP "\f(CW\-s\fR" 4 |
| .IX Item "-s" |
| .PD 0 |
| .ie n .IP """\-\-sum""" 4 |
| .el .IP "\f(CW\-\-sum\fR" 4 |
| .IX Item "--sum" |
| .PD |
| The \fB\-s\fR option causes \f(CW\*(C`gprof\*(C'\fR to summarize the information |
| in the profile data files it read in, and write out a profile data |
| file called \fIgmon.sum\fR, which contains all the information from |
| the profile data files that \f(CW\*(C`gprof\*(C'\fR read in. The file \fIgmon.sum\fR |
| may be one of the specified input files; the effect of this is to |
| merge the data in the other input files into \fIgmon.sum\fR. |
| .Sp |
| Eventually you can run \f(CW\*(C`gprof\*(C'\fR again without \fB\-s\fR to analyze the |
| cumulative data in the file \fIgmon.sum\fR. |
| .ie n .IP """\-v""" 4 |
| .el .IP "\f(CW\-v\fR" 4 |
| .IX Item "-v" |
| .PD 0 |
| .ie n .IP """\-\-version""" 4 |
| .el .IP "\f(CW\-\-version\fR" 4 |
| .IX Item "--version" |
| .PD |
| The \fB\-v\fR flag causes \f(CW\*(C`gprof\*(C'\fR to print the current version |
| number, and then exit. |
| .SS "Deprecated Options" |
| .IX Subsection "Deprecated Options" |
| These options have been replaced with newer versions that use symspecs. |
| .ie n .IP """\-e \f(CIfunction_name\f(CW""" 4 |
| .el .IP "\f(CW\-e \f(CIfunction_name\f(CW\fR" 4 |
| .IX Item "-e function_name" |
| The \fB\-e\fR \fIfunction\fR option tells \f(CW\*(C`gprof\*(C'\fR to not print |
| information about the function \fIfunction_name\fR (and its |
| children...) in the call graph. The function will still be listed |
| as a child of any functions that call it, but its index number will be |
| shown as \fB[not printed]\fR. More than one \fB\-e\fR option may be |
| given; only one \fIfunction_name\fR may be indicated with each \fB\-e\fR |
| option. |
| .ie n .IP """\-E \f(CIfunction_name\f(CW""" 4 |
| .el .IP "\f(CW\-E \f(CIfunction_name\f(CW\fR" 4 |
| .IX Item "-E function_name" |
| The \f(CW\*(C`\-E \f(CIfunction\f(CW\*(C'\fR option works like the \f(CW\*(C`\-e\*(C'\fR option, but |
| time spent in the function (and children who were not called from |
| anywhere else), will not be used to compute the percentages-of-time for |
| the call graph. More than one \fB\-E\fR option may be given; only one |
| \&\fIfunction_name\fR may be indicated with each \fB\-E\fR option. |
| .ie n .IP """\-f \f(CIfunction_name\f(CW""" 4 |
| .el .IP "\f(CW\-f \f(CIfunction_name\f(CW\fR" 4 |
| .IX Item "-f function_name" |
| The \fB\-f\fR \fIfunction\fR option causes \f(CW\*(C`gprof\*(C'\fR to limit the |
| call graph to the function \fIfunction_name\fR and its children (and |
| their children...). More than one \fB\-f\fR option may be given; |
| only one \fIfunction_name\fR may be indicated with each \fB\-f\fR |
| option. |
| .ie n .IP """\-F \f(CIfunction_name\f(CW""" 4 |
| .el .IP "\f(CW\-F \f(CIfunction_name\f(CW\fR" 4 |
| .IX Item "-F function_name" |
| The \fB\-F\fR \fIfunction\fR option works like the \f(CW\*(C`\-f\*(C'\fR option, but |
| only time spent in the function and its children (and their |
| children...) will be used to determine total-time and |
| percentages-of-time for the call graph. More than one \fB\-F\fR option |
| may be given; only one \fIfunction_name\fR may be indicated with each |
| \&\fB\-F\fR option. The \fB\-F\fR option overrides the \fB\-E\fR option. |
| .SH "FILES" |
| .IX Header "FILES" |
| .ie n .IP """\f(CIa.out\f(CW""" 4 |
| .el .IP "\f(CW\f(CIa.out\f(CW\fR" 4 |
| .IX Item "a.out" |
| the namelist and text space. |
| .ie n .IP """\f(CIgmon.out\f(CW""" 4 |
| .el .IP "\f(CW\f(CIgmon.out\f(CW\fR" 4 |
| .IX Item "gmon.out" |
| dynamic call graph and profile. |
| .ie n .IP """\f(CIgmon.sum\f(CW""" 4 |
| .el .IP "\f(CW\f(CIgmon.sum\f(CW\fR" 4 |
| .IX Item "gmon.sum" |
| summarized dynamic call graph and profile. |
| .SH "BUGS" |
| .IX Header "BUGS" |
| The granularity of the sampling is shown, but remains |
| statistical at best. |
| We assume that the time for each execution of a function |
| can be expressed by the total time for the function divided |
| by the number of times the function is called. |
| Thus the time propagated along the call graph arcs to the function's |
| parents is directly proportional to the number of times that |
| arc is traversed. |
| .PP |
| Parents that are not themselves profiled will have the time of |
| their profiled children propagated to them, but they will appear |
| to be spontaneously invoked in the call graph listing, and will |
| not have their time propagated further. |
| Similarly, signal catchers, even though profiled, will appear |
| to be spontaneous (although for more obscure reasons). |
| Any profiled children of signal catchers should have their times |
| propagated properly, unless the signal catcher was invoked during |
| the execution of the profiling routine, in which case all is lost. |
| .PP |
| The profiled program must call \f(CW\*(C`exit\*(C'\fR(2) |
| or return normally for the profiling information to be saved |
| in the \fIgmon.out\fR file. |
| .SH "SEE ALSO" |
| .IX Header "SEE ALSO" |
| \&\fImonitor\fR\|(3), \fIprofil\fR\|(2), \fIcc\fR\|(1), \fIprof\fR\|(1), and the Info entry for \fIgprof\fR. |
| .PP |
| \&\*(L"An Execution Profiler for Modular Programs\*(R", |
| by S. Graham, P. Kessler, M. McKusick; |
| Software \- Practice and Experience, |
| Vol. 13, pp. 671\-685, 1983. |
| .PP |
| \&\*(L"gprof: A Call Graph Execution Profiler\*(R", |
| by S. Graham, P. Kessler, M. McKusick; |
| Proceedings of the \s-1SIGPLAN\s0 '82 Symposium on Compiler Construction, |
| \&\s-1SIGPLAN\s0 Notices, Vol. 17, No 6, pp. 120\-126, June 1982. |
| .SH "COPYRIGHT" |
| .IX Header "COPYRIGHT" |
| Copyright (c) 1988, 1992, 1997, 1998, 1999, 2000, 2001, 2003, |
| 2007, 2008, 2009 Free Software Foundation, Inc. |
| .PP |
| Permission is granted to copy, distribute and/or modify this document |
| under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 |
| or any later version published by the Free Software Foundation; |
| with no Invariant Sections, with no Front-Cover Texts, and with no |
| Back-Cover Texts. A copy of the license is included in the |
| section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R". |
