man page generation from gprof.texi by Stephane Carrez
This commit is contained in:
Alan Modra
parent
a250df2e35
commit
40f905288f
|
|
@ -1,3 +1,14 @@
|
|||
2001-04-06 Stephane Carrez <Stephane.Carrez@worldnet.fr>
|
||||
|
||||
* gprof.texi: Put @c man begin and @c man end indications
|
||||
to generate man page using texi2pod and pod2man. Added SEEALSO,
|
||||
SYNOPSIS, BUGS, FILES and DESCRIPTION from original gprof.1
|
||||
enclosed in @ifset man condition.
|
||||
* Makefile.am (MANCONF, TEXI2POD, POD2MAN): New variable.
|
||||
Generate gprof.1 from gprof.texi.
|
||||
* gprof.1: Generate from gprof.texi.
|
||||
* Makefile.in: Regenerate.
|
||||
|
||||
2001-03-13 David Mosberger <davidm@hpl.hp.com>
|
||||
|
||||
* hist.c (hist_dimension): Declare as an array of 16 characters.
|
||||
|
|
|
|||
|
|
@ -49,9 +49,27 @@ po/POTFILES.in: @MAINT@ Makefile
|
|||
for file in $(POTFILES); do echo $$file; done | sort > tmp \
|
||||
&& mv tmp $(srcdir)/po/POTFILES.in
|
||||
|
||||
MANCONF = -Dman
|
||||
|
||||
TEXI2POD = perl $(srcdir)/../etc/texi2pod.pl
|
||||
|
||||
POD2MAN = pod2man --center="GNU" --release="binutils-$(VERSION)" --section=1
|
||||
|
||||
info_TEXINFOS = gprof.texi
|
||||
man_MANS = gprof.1
|
||||
|
||||
# Build the man page from the texinfo file
|
||||
# The sed command removes the no-adjust Nroff command so that
|
||||
# the man output looks standard.
|
||||
$(srcdir)/gprof.1: $(srcdir)/gprof.texi
|
||||
touch $(srcdir)/gprof.1
|
||||
-$(TEXI2POD) $(MANCONF) -Dgprof < $(srcdir)/gprof.texi > gprof.pod
|
||||
-($(POD2MAN) gprof.pod | \
|
||||
sed -e '/^.if n .na/d' > $(srcdir)/gprof.1.T$$$$ && \
|
||||
mv -f $(srcdir)/gprof.1.T$$$$ $(srcdir)/gprof.1) || \
|
||||
(rm -f $(srcdir)/gprof.1.T$$$$ && exit 1)
|
||||
rm -f gprof.pod
|
||||
|
||||
# Targets to rebuild dependencies in this Makefile.
|
||||
# Have to get rid of DEP1 here so that "$?" later includes all sources.
|
||||
DEP: dep.sed $(gprof_SOURCES) $(noinst_HEADERS) gconfig.h
|
||||
|
|
|
|||
|
|
@ -141,6 +141,12 @@ BUILT_SOURCES = flat_bl.c bsd_callg_bl.c fsf_callg_bl.c
|
|||
|
||||
POTFILES = $(sources) $(noinst_HEADERS)
|
||||
|
||||
MANCONF = -Dman
|
||||
|
||||
TEXI2POD = perl $(srcdir)/../etc/texi2pod.pl
|
||||
|
||||
POD2MAN = pod2man --center="GNU" --release="binutils-$(VERSION)" --section=1
|
||||
|
||||
info_TEXINFOS = gprof.texi
|
||||
man_MANS = gprof.1
|
||||
|
||||
|
|
@ -716,6 +722,18 @@ po/POTFILES.in: @MAINT@ Makefile
|
|||
for file in $(POTFILES); do echo $$file; done | sort > tmp \
|
||||
&& mv tmp $(srcdir)/po/POTFILES.in
|
||||
|
||||
# Build the man page from the texinfo file
|
||||
# The sed command removes the no-adjust Nroff command so that
|
||||
# the man output looks standard.
|
||||
$(srcdir)/gprof.1: $(srcdir)/gprof.texi
|
||||
touch $(srcdir)/gprof.1
|
||||
-$(TEXI2POD) $(MANCONF) -Dgprof < $(srcdir)/gprof.texi > gprof.pod
|
||||
-($(POD2MAN) gprof.pod | \
|
||||
sed -e '/^.if n .na/d' > $(srcdir)/gprof.1.T$$$$ && \
|
||||
mv -f $(srcdir)/gprof.1.T$$$$ $(srcdir)/gprof.1) || \
|
||||
(rm -f $(srcdir)/gprof.1.T$$$$ && exit 1)
|
||||
rm -f gprof.pod
|
||||
|
||||
# Targets to rebuild dependencies in this Makefile.
|
||||
# Have to get rid of DEP1 here so that "$?" later includes all sources.
|
||||
DEP: dep.sed $(gprof_SOURCES) $(noinst_HEADERS) gconfig.h
|
||||
|
|
|
|||
905
gprof/gprof.1
905
gprof/gprof.1
|
|
@ -1,232 +1,677 @@
|
|||
.\" Copyright (c) 1983, 1990 The Regents of the University of California.
|
||||
.\" All rights reserved.
|
||||
.\" Automatically generated by Pod::Man version 1.15
|
||||
.\" Fri Apr 6 20:13:00 2001
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms are permitted provided
|
||||
.\" that: (1) source distributions retain this entire copyright notice and
|
||||
.\" comment, and (2) distributions including binaries display the following
|
||||
.\" acknowledgement: ``This product includes software developed by the
|
||||
.\" University of California, Berkeley and its contributors'' in the
|
||||
.\" documentation or other materials provided with the distribution and in
|
||||
.\" all advertising materials mentioning features or use of this software.
|
||||
.\" Neither the name of the University nor the names of its contributors may
|
||||
.\" be used to endorse or promote products derived from this software without
|
||||
.\" specific prior written permission.
|
||||
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
|
||||
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
|
||||
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
|
||||
.\" Standard preamble:
|
||||
.\" ======================================================================
|
||||
.de Sh \" Subsection heading
|
||||
.br
|
||||
.if t .Sp
|
||||
.ne 5
|
||||
.PP
|
||||
\fB\\$1\fR
|
||||
.PP
|
||||
..
|
||||
.de Sp \" Vertical space (when we can't use .PP)
|
||||
.if t .sp .5v
|
||||
.if n .sp
|
||||
..
|
||||
.de Ip \" List item
|
||||
.br
|
||||
.ie \\n(.$>=3 .ne \\$3
|
||||
.el .ne 3
|
||||
.IP "\\$1" \\$2
|
||||
..
|
||||
.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. | will give a
|
||||
.\" real vertical bar. \*(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-|\(bv\*(Tr
|
||||
.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\}
|
||||
.\"
|
||||
.\" @(#)gprof.1 6.6 (Berkeley) 7/24/90
|
||||
.\" If the F register is turned on, we'll generate index entries on stderr
|
||||
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
|
||||
.\" index entries marked with X<> in POD. Of course, you'll have to process
|
||||
.\" the output yourself in some meaningful fashion.
|
||||
.if \nF \{\
|
||||
. de IX
|
||||
. tm Index:\\$1\t\\n%\t"\\$2"
|
||||
..
|
||||
. nr % 0
|
||||
. rr F
|
||||
.\}
|
||||
.\"
|
||||
.TH GPROF 1 "January 29, 1993"
|
||||
.SH NAME
|
||||
.\" For nroff, turn off justification. Always turn off hyphenation; it
|
||||
.\" makes way too many mistakes in technical documents.
|
||||
.hy 0
|
||||
.\"
|
||||
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
||||
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
||||
.bd B 3
|
||||
. \" 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 "binutils-2.11.90" "2001-04-06" "GNU"
|
||||
.UC
|
||||
.SH "NAME"
|
||||
gprof \- display call graph profile data
|
||||
.SH SYNOPSIS
|
||||
.B gprof [ \-abcsz ] [ \-e|\-E
|
||||
.I name
|
||||
.B ] [ \-f|\-F
|
||||
.I name
|
||||
.B ]
|
||||
.B [ \-k
|
||||
.I fromname toname
|
||||
.B ] [
|
||||
.I objfile
|
||||
.B [
|
||||
.I gmon.out
|
||||
.B ]
|
||||
.B ]
|
||||
.SH DESCRIPTION
|
||||
.B gprof
|
||||
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
|
||||
\&(`gmon.out' default) which is created by programs
|
||||
that are compiled with the
|
||||
.B \-pg
|
||||
option of
|
||||
.BR cc ( 1 ) ,
|
||||
.BR pc ( 1 ) ,
|
||||
and
|
||||
.BR f77 ( 1 ) .
|
||||
The
|
||||
.B \-pg
|
||||
option also links in versions of the library routines
|
||||
that are compiled for profiling.
|
||||
.B Gprof
|
||||
reads the given object file (the default is `a.out')
|
||||
and establishes the relation between its symbol table
|
||||
and the call graph profile from `gmon.out'.
|
||||
If more than one profile file is specified,
|
||||
the
|
||||
.B gprof
|
||||
.SH "SYNOPSIS"
|
||||
.IX Header "SYNOPSIS"
|
||||
gprof [ \-[abcDhilLsTvwxyz] ] [ \-[ACeEfFJnNOpPqQZ][\fIname\fR] ]
|
||||
[ \-I \fIdirs\fR ] [ \-d[\fInum\fR] ] [ \-k \fIfrom/to\fR ]
|
||||
[ \-m \fImin-count\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 ] [ \-\-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 ] [ \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
|
||||
.B Gprof
|
||||
calculates the amount of time spent in each routine.
|
||||
\&\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.
|
||||
The first listing shows the functions
|
||||
sorted according to the time they represent
|
||||
including the time of their call graph descendants.
|
||||
Below each function entry is shown its (direct) call graph children,
|
||||
and how their times are propagated to this function.
|
||||
A similar display above the function shows how this function's time and the
|
||||
time of its descendants is propagated to its (direct) call graph parents.
|
||||
.PP
|
||||
Cycles are also shown, with an entry for the cycle as a whole and
|
||||
a listing of the members of the cycle and their contributions to the
|
||||
time and call counts of the cycle.
|
||||
Several forms of output are available from the analysis.
|
||||
.PP
|
||||
Second, a flat profile is given,
|
||||
similar to that provided by
|
||||
.BR prof ( 1 ) .
|
||||
This listing gives the total execution times, the call counts,
|
||||
the time in milliseconds the call spent in the routine itself, and
|
||||
the time in milliseconds the call spent in the routine itself including
|
||||
its descendants.
|
||||
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
|
||||
Finally, an index of the function names is provided.
|
||||
.SH OPTIONS
|
||||
The following options are available:
|
||||
.TP
|
||||
.B \-a
|
||||
suppresses the printing of statically declared functions.
|
||||
If this option is given, all relevant information about the static function
|
||||
(e.g., time samples, calls to other functions, calls from other functions)
|
||||
belongs to the function loaded just before the static function in the
|
||||
\&`objfile' file.
|
||||
.TP
|
||||
.B \-b
|
||||
suppresses the printing of a description of each field in the profile.
|
||||
.TP
|
||||
.B \-c
|
||||
the static call graph of the program is discovered by a heuristic
|
||||
that examines the text space of the object file.
|
||||
Static-only parents or children are shown
|
||||
with call counts of 0.
|
||||
.TP
|
||||
.BI "\-e " name
|
||||
suppresses the printing of the graph profile entry for routine
|
||||
.I name
|
||||
and all its descendants
|
||||
(unless they have other ancestors that aren't suppressed).
|
||||
More than one
|
||||
.B \-e
|
||||
option may be given.
|
||||
Only one
|
||||
.I name
|
||||
may be given with each
|
||||
.B \-e
|
||||
option.
|
||||
.TP
|
||||
.BI "\-E " name
|
||||
suppresses the printing of the graph profile entry for routine
|
||||
.I name
|
||||
(and its descendants) as
|
||||
.B \-e ,
|
||||
above, and also excludes the time spent in
|
||||
.I name
|
||||
(and its descendants) from the total and percentage time computations.
|
||||
(For example,
|
||||
.BI "\-E " mcount
|
||||
.BI "\-E " mcleanup
|
||||
is the default.)
|
||||
.TP
|
||||
.BI "\-f " name
|
||||
prints the graph profile entry of only the specified routine
|
||||
.I name
|
||||
and its descendants.
|
||||
More than one
|
||||
.B \-f
|
||||
option may be given.
|
||||
Only one
|
||||
.I name
|
||||
may be given with each
|
||||
.B \-f
|
||||
option.
|
||||
.TP
|
||||
.BI "\-F " name
|
||||
prints the graph profile entry of only the routine
|
||||
.I name
|
||||
and its descendants (as
|
||||
.B \-f ,
|
||||
above) and also uses only the times of the printed routines
|
||||
in total time and percentage computations.
|
||||
More than one
|
||||
.B \-F
|
||||
option may be given.
|
||||
Only one
|
||||
.I name
|
||||
may be given with each
|
||||
.B \-F
|
||||
option.
|
||||
The
|
||||
.B \-F
|
||||
option
|
||||
overrides
|
||||
the
|
||||
.B \-E
|
||||
option.
|
||||
.TP
|
||||
.BI "\-k " "fromname toname"
|
||||
will delete any arcs from routine
|
||||
.I fromname
|
||||
to routine
|
||||
.IR toname .
|
||||
This can be used to break undesired cycles.
|
||||
More than one
|
||||
.B \-k
|
||||
option may be given.
|
||||
Only one pair of routine names may be given with each
|
||||
.B \-k
|
||||
option.
|
||||
.TP
|
||||
.B \-s
|
||||
a profile file `gmon.sum' is produced that represents
|
||||
the sum of the profile information in all the specified profile files.
|
||||
This summary profile file may be given to later
|
||||
executions of gprof (probably also with a
|
||||
.BR \-s )
|
||||
to accumulate profile data across several runs of an `objfile' file.
|
||||
.TP
|
||||
.B -v
|
||||
prints the version number for gprof, and then exits.
|
||||
.TP
|
||||
.B -z
|
||||
displays routines that have zero usage (as shown by call counts
|
||||
and accumulated time).
|
||||
This is useful with the
|
||||
.B \-c
|
||||
option for discovering which routines were never called.
|
||||
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
|
||||
.SH FILES
|
||||
.ta \w'gmon.sum 'u
|
||||
a.out the namelist and text space.
|
||||
.br
|
||||
gmon.out dynamic call graph and profile.
|
||||
.br
|
||||
gmon.sum summarized dynamic call graph and profile.
|
||||
.SH SEE ALSO
|
||||
.BR monitor ( 3 ) ,
|
||||
.BR profil ( 2 ) ,
|
||||
.BR cc ( 1 ) ,
|
||||
.BR prof ( 1 )
|
||||
.sp
|
||||
``An Execution Profiler for Modular Programs'',
|
||||
by S. Graham, P. Kessler, M. McKusick;
|
||||
.I
|
||||
Software \- Practice and Experience,
|
||||
Vol. 13, pp. 671-685, 1983.
|
||||
.sp
|
||||
``gprof: A Call Graph Execution Profiler'',
|
||||
by S. Graham, P. Kessler, M. McKusick;
|
||||
.I
|
||||
Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
|
||||
SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, June 1982.
|
||||
.SH HISTORY
|
||||
.B Gprof
|
||||
appeared in 4.2 BSD.
|
||||
.SH BUGS
|
||||
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.
|
||||
.if n .Ip "\f(CW""""\-A[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-A[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-A[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-annotated\-source[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-b""""\fR" 4
|
||||
.el .Ip "\f(CW\-b\fR" 4
|
||||
.IX Item "-b"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-brief""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-C[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-C[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-C[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-exec\-counts[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-i""""\fR" 4
|
||||
.el .Ip "\f(CW\-i\fR" 4
|
||||
.IX Item "-i"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-file\-info""""\fR" 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 \fIfile\fR\|(s) and then exit. The number of histogram,
|
||||
call graph, and basic-block count records is displayed.
|
||||
.if n .Ip "\f(CW""""\-I \f(CIdirs\f(CW""""\fR" 4
|
||||
.el .Ip "\f(CW\-I \f(CIdirs\f(CW\fR" 4
|
||||
.IX Item "-I dirs"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-directory\-path=\f(CIdirs\f(CW""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-J[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-J[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-J[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-no\-annotated\-source[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-L""""\fR" 4
|
||||
.el .Ip "\f(CW\-L\fR" 4
|
||||
.IX Item "-L"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-print\-path""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-p[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-p[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-p[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-flat\-profile[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-P[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-P[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-P[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-no\-flat\-profile[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-q[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-q[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-q[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-graph[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-Q[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-Q[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-Q[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-no\-graph[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-y""""\fR" 4
|
||||
.el .Ip "\f(CW\-y\fR" 4
|
||||
.IX Item "-y"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-separate\-files""""\fR" 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
|
||||
filesystem 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).
|
||||
.if n .Ip "\f(CW""""\-Z[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-Z[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-Z[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-no\-exec\-counts[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-\-function\-ordering""""\fR" 4
|
||||
.el .Ip "\f(CW\-\-function\-ordering\fR" 4
|
||||
.IX Item "--function-ordering"
|
||||
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.
|
||||
.if n .Ip "\f(CW""""\-\-file\-ordering \f(CImap_file\f(CW""""\fR" 4
|
||||
.el .Ip "\f(CW\-\-file\-ordering \f(CImap_file\f(CW\fR" 4
|
||||
.IX Item "--file-ordering map_file"
|
||||
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
|
||||
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.
|
||||
.if n .Ip "\f(CW""""\-T""""\fR" 4
|
||||
.el .Ip "\f(CW\-T\fR" 4
|
||||
.IX Item "-T"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-traditional""""\fR" 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
|
||||
``traditional'' \s-1BSD\s0 style.
|
||||
.if n .Ip "\f(CW""""\-w \f(CIwidth\f(CW""""\fR" 4
|
||||
.el .Ip "\f(CW\-w \f(CIwidth\f(CW\fR" 4
|
||||
.IX Item "-w width"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-width=\f(CIwidth\f(CW""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-x""""\fR" 4
|
||||
.el .Ip "\f(CW\-x\fR" 4
|
||||
.IX Item "-x"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-all\-lines""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-\-demangle[=\f(CIstyle\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-\-demangle[=\f(CIstyle\f(CW]\fR" 4
|
||||
.IX Item "--demangle[=style]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-no\-demangle""""\fR" 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.
|
||||
.Sh "Analysis Options"
|
||||
.IX Subsection "Analysis Options"
|
||||
.if n .Ip "\f(CW""""\-a""""\fR" 4
|
||||
.el .Ip "\f(CW\-a\fR" 4
|
||||
.IX Item "-a"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-no\-static""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-c""""\fR" 4
|
||||
.el .Ip "\f(CW\-c\fR" 4
|
||||
.IX Item "-c"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-static\-call\-graph""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-D""""\fR" 4
|
||||
.el .Ip "\f(CW\-D\fR" 4
|
||||
.IX Item "-D"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-ignore\-non\-functions""""\fR" 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).
|
||||
.if n .Ip "\f(CW""""\-k \f(CIfrom\f(CW/\f(CIto\f(CW""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-l""""\fR" 4
|
||||
.el .Ip "\f(CW\-l\fR" 4
|
||||
.IX Item "-l"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-line""""\fR" 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.
|
||||
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.
|
||||
.if n .Ip "\f(CW""""\-m \f(CInum\f(CW""""\fR" 4
|
||||
.el .Ip "\f(CW\-m \f(CInum\f(CW\fR" 4
|
||||
.IX Item "-m num"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-min\-count=\f(CInum\f(CW""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-n[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-n[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-n[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-time[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-N[\f(CIsymspec\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-N[\f(CIsymspec\f(CW]\fR" 4
|
||||
.IX Item "-N[symspec]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-no\-time[=\f(CIsymspec\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-z""""\fR" 4
|
||||
.el .Ip "\f(CW\-z\fR" 4
|
||||
.IX Item "-z"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-display\-unused\-functions""""\fR" 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.
|
||||
.Sh "Miscellaneous Options"
|
||||
.IX Subsection "Miscellaneous Options"
|
||||
.if n .Ip "\f(CW""""\-d[\f(CInum\f(CW]""""\fR" 4
|
||||
.el .Ip "\f(CW\-d[\f(CInum\f(CW]\fR" 4
|
||||
.IX Item "-d[num]"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-debug[=\f(CInum\f(CW]""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-O\f(CIname\f(CW""""\fR" 4
|
||||
.el .Ip "\f(CW\-O\f(CIname\f(CW\fR" 4
|
||||
.IX Item "-Oname"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-file\-format=\f(CIname\f(CW""""\fR" 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).
|
||||
.if n .Ip "\f(CW""""\-s""""\fR" 4
|
||||
.el .Ip "\f(CW\-s\fR" 4
|
||||
.IX Item "-s"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-sum""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-v""""\fR" 4
|
||||
.el .Ip "\f(CW\-v\fR" 4
|
||||
.IX Item "-v"
|
||||
.PD 0
|
||||
.if n .Ip "\f(CW""""\-\-version""""\fR" 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.
|
||||
.Sh "Deprecated Options"
|
||||
.IX Subsection "Deprecated Options"
|
||||
These options have been replaced with newer versions that use symspecs.
|
||||
.if n .Ip "\f(CW""""\-e \f(CIfunction_name\f(CW""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-E \f(CIfunction_name\f(CW""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-f \f(CIfunction_name\f(CW""""\fR" 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.
|
||||
.if n .Ip "\f(CW""""\-F \f(CIfunction_name\f(CW""""\fR" 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"
|
||||
.if n .Ip "\f(CW""""\f(CIa.out\f(CW""""\fR" 4
|
||||
.el .Ip "\f(CW\f(CIa.out\f(CW\fR" 4
|
||||
.IX Item "a.out"
|
||||
the namelist and text space.
|
||||
.if n .Ip "\f(CW""""\f(CIgmon.out\f(CW""""\fR" 4
|
||||
.el .Ip "\f(CW\f(CIgmon.out\f(CW\fR" 4
|
||||
.IX Item "gmon.out"
|
||||
dynamic call graph and profile.
|
||||
.if n .Ip "\f(CW""""\f(CIgmon.sum\f(CW""""\fR" 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
|
||||
|
|
@ -246,7 +691,29 @@ 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
|
||||
.BR exit ( 2 )
|
||||
The profiled program must call \f(CW\*(C`exit\*(C'\fR(2)
|
||||
or return normally for the profiling information to be saved
|
||||
in the `gmon.out' file.
|
||||
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
|
||||
``An Execution Profiler for Modular Programs'',
|
||||
by S. Graham, P. Kessler, M. McKusick;
|
||||
Software \- Practice and Experience,
|
||||
Vol. 13, pp. 671\-685, 1983.
|
||||
.PP
|
||||
``gprof: A Call Graph Execution Profiler'',
|
||||
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, 92, 97, 98, 99, 2000, 2001 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.1
|
||||
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".
|
||||
|
|
|
|||
121
gprof/gprof.texi
121
gprof/gprof.texi
|
|
@ -1,6 +1,6 @@
|
|||
\input texinfo @c -*-texinfo-*-
|
||||
@setfilename gprof.info
|
||||
@c Copyright 1988, 1992, 1993, 1998, 1999, 2000
|
||||
@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001
|
||||
@c Free Software Foundation, Inc.
|
||||
@settitle GNU gprof
|
||||
@setchapternewpage odd
|
||||
|
|
@ -18,14 +18,17 @@ END-INFO-DIR-ENTRY
|
|||
@ifinfo
|
||||
This file documents the gprof profiler of the GNU system.
|
||||
|
||||
Copyright (C) 1988, 92, 97, 98, 99, 2000 Free Software Foundation, Inc.
|
||||
@c man begin COPYRIGHT
|
||||
Copyright (C) 1988, 92, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
|
||||
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
under the terms of the GNU Free Documentation License, Version 1.1
|
||||
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 "GNU Free Documentation License".
|
||||
Permission is granted to copy, distribute and/or modify this document
|
||||
under the terms of the GNU Free Documentation License, Version 1.1
|
||||
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 "GNU Free Documentation License".
|
||||
|
||||
@c man end
|
||||
|
||||
@ignore
|
||||
Permission is granted to process this file through Tex and print the
|
||||
|
|
@ -96,6 +99,102 @@ section entitled "GNU Free Documentation License".
|
|||
@node Introduction
|
||||
@chapter Introduction to Profiling
|
||||
|
||||
@ifset man
|
||||
@c man title gprof display call graph profile data
|
||||
|
||||
@smallexample
|
||||
@c man begin SYNOPSIS
|
||||
gprof [ -[abcDhilLsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ]
|
||||
[ -I @var{dirs} ] [ -d[@var{num}] ] [ -k @var{from/to} ]
|
||||
[ -m @var{min-count} ] [ -t @var{table-length} ]
|
||||
[ --[no-]annotated-source[=@var{name}] ]
|
||||
[ --[no-]exec-counts[=@var{name}] ]
|
||||
[ --[no-]flat-profile[=@var{name}] ] [ --[no-]graph[=@var{name}] ]
|
||||
[ --[no-]time=@var{name}] [ --all-lines ] [ --brief ]
|
||||
[ --debug[=@var{level}] ] [ --function-ordering ]
|
||||
[ --file-ordering ] [ --directory-path=@var{dirs} ]
|
||||
[ --display-unused-functions ] [ --file-format=@var{name} ]
|
||||
[ --file-info ] [ --help ] [ --line ] [ --min-count=@var{n} ]
|
||||
[ --no-static ] [ --print-path ] [ --separate-files ]
|
||||
[ --static-call-graph ] [ --sum ] [ --table-length=@var{len} ]
|
||||
[ --traditional ] [ --version ] [ --width=@var{n} ]
|
||||
[ --ignore-non-functions ] [ --demangle[=@var{STYLE}] ]
|
||||
[ --no-demangle ] [ @var{image-file} ] [ @var{profile-file} @dots{} ]
|
||||
@c man end
|
||||
@end smallexample
|
||||
|
||||
@c man begin DESCRIPTION
|
||||
@code{gprof} 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
|
||||
(@file{gmon.out} default) which is created by programs
|
||||
that are compiled with the @samp{-pg} option of
|
||||
@code{cc}, @code{pc}, and @code{f77}.
|
||||
The @samp{-pg} option also links in versions of the library routines
|
||||
that are compiled for profiling. @code{Gprof} reads the given object
|
||||
file (the default is @code{a.out}) and establishes the relation between
|
||||
its symbol table and the call graph profile from @file{gmon.out}.
|
||||
If more than one profile file is specified, the @code{gprof}
|
||||
output shows the sum of the profile information in the given profile files.
|
||||
|
||||
@code{Gprof} 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.
|
||||
|
||||
@c man end
|
||||
|
||||
@c man begin 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.
|
||||
|
||||
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.
|
||||
|
||||
The profiled program must call @code{exit}(2)
|
||||
or return normally for the profiling information to be saved
|
||||
in the @file{gmon.out} file.
|
||||
@c man end
|
||||
|
||||
@c man begin FILES
|
||||
@table @code
|
||||
@item @file{a.out}
|
||||
the namelist and text space.
|
||||
@item @file{gmon.out}
|
||||
dynamic call graph and profile.
|
||||
@item @file{gmon.sum}
|
||||
summarized dynamic call graph and profile.
|
||||
@end table
|
||||
@c man end
|
||||
|
||||
@c man begin SEEALSO
|
||||
monitor(3), profil(2), cc(1), prof(1), and the Info entry for @file{gprof}.
|
||||
|
||||
``An Execution Profiler for Modular Programs'',
|
||||
by S. Graham, P. Kessler, M. McKusick;
|
||||
Software - Practice and Experience,
|
||||
Vol. 13, pp. 671-685, 1983.
|
||||
|
||||
``gprof: A Call Graph Execution Profiler'',
|
||||
by S. Graham, P. Kessler, M. McKusick;
|
||||
Proceedings of the SIGPLAN '82 Symposium on Compiler Construction,
|
||||
SIGPLAN Notices, Vol. 17, No 6, pp. 120-126, June 1982.
|
||||
@c man end
|
||||
@end ifset
|
||||
|
||||
Profiling allows you to learn where your program spent its time and which
|
||||
functions called which other functions while it was executing. This
|
||||
information can show you which pieces of your program are slower than you
|
||||
|
|
@ -129,6 +228,8 @@ You must run @code{gprof} to analyze the profile data.
|
|||
|
||||
The next three chapters explain these steps in greater detail.
|
||||
|
||||
@c man begin DESCRIPTION
|
||||
|
||||
Several forms of output are available from the analysis.
|
||||
|
||||
The @dfn{flat profile} shows how much time your program spent in each function,
|
||||
|
|
@ -145,6 +246,7 @@ lot of time. @xref{Call Graph}.
|
|||
The @dfn{annotated source} listing is a copy of the program's
|
||||
source code, labeled with the number of times each line of the
|
||||
program was executed. @xref{Annotated Source}.
|
||||
@c man end
|
||||
|
||||
To better understand how profiling works, you may wish to read
|
||||
a description of its implementation.
|
||||
|
|
@ -297,6 +399,7 @@ The order of these options does not matter.
|
|||
@node Output Options,Analysis Options,,Invoking
|
||||
@section Output Options
|
||||
|
||||
@c man begin OPTIONS
|
||||
These options specify which of several output formats
|
||||
@code{gprof} should produce.
|
||||
|
||||
|
|
@ -635,6 +738,8 @@ may be given; only one @var{function_name} may be indicated with each
|
|||
|
||||
@end table
|
||||
|
||||
@c man end
|
||||
|
||||
Note that only one function can be specified with each @code{-e},
|
||||
@code{-E}, @code{-f} or @code{-F} option. To specify more than one
|
||||
function, use multiple options. For example, this command:
|
||||
|
|
|
|||
Loading…
Reference in New Issue