diff options
| -rw-r--r-- | gprof/ChangeLog | 11 | ||||
| -rw-r--r-- | gprof/Makefile.am | 18 | ||||
| -rw-r--r-- | gprof/Makefile.in | 18 | ||||
| -rw-r--r-- | gprof/gprof.1 | 905 | ||||
| -rw-r--r-- | gprof/gprof.texi | 121 |
5 files changed, 846 insertions, 227 deletions
diff --git a/gprof/ChangeLog b/gprof/ChangeLog index c3728a1..72d634e 100644 --- a/gprof/ChangeLog +++ b/gprof/ChangeLog @@ -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. diff --git a/gprof/Makefile.am b/gprof/Makefile.am index af50f57..4e311d4 100644 --- a/gprof/Makefile.am +++ b/gprof/Makefile.am @@ -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 diff --git a/gprof/Makefile.in b/gprof/Makefile.in index 4cf26dc..aca0211 100644 --- a/gprof/Makefile.in +++ b/gprof/Makefile.in @@ -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 diff --git a/gprof/gprof.1 b/gprof/gprof.1 index 5a734da..f058b82 100644 --- a/gprof/gprof.1 +++ b/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\} +.\" +.\" 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 +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it +.\" makes way too many mistakes in technical documents. +.hy 0 .\" -.\" @(#)gprof.1 6.6 (Berkeley) 7/24/90 +.\" 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 +.\" ====================================================================== .\" -.TH GPROF 1 "January 29, 1993" -.SH NAME +.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". diff --git a/gprof/gprof.texi b/gprof/gprof.texi index 266f0f3..2008da7 100644 --- a/gprof/gprof.texi +++ b/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: |