\input texinfo @c -*-texinfo-*-
@setfilename gprof.info
-@c Copyright 1988, 1992, 1993, 1998, 1999, 2000, 2001, 2002, 2003,
-@c 2004, 2007, 2008
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1988-2020 Free Software Foundation, Inc.
@settitle GNU gprof
@setchapternewpage odd
@include bfdver.texi
@c man end
-@ifinfo
+@ifnottex
@c This is a dir.info fragment to support semi-automated addition of
@c manuals to an info tree. zoo@cygnus.com is developing this facility.
-@format
-START-INFO-DIR-ENTRY
+@dircategory Software development
+@direntry
* gprof: (gprof). Profiling your program's execution
-END-INFO-DIR-ENTRY
-@end format
-@end ifinfo
+@end direntry
+@end ifnottex
@copying
This file documents the gprof profiler of the GNU system.
@c man begin COPYRIGHT
-Copyright @copyright{} 1988, 92, 97, 98, 99, 2000, 2001, 2003, 2007, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2020 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.3
@titlepage
@title GNU gprof
-@subtitle The @sc{gnu} Profiler
+@subtitle The @sc{gnu} Profiler
@ifset VERSION_PACKAGE
@subtitle @value{VERSION_PACKAGE}
@end ifset
Eric S. Raymond made some minor corrections and additions in 2003.
@vskip 0pt plus 1filll
-Copyright @copyright{} 1988, 92, 97, 98, 99, 2000, 2003, 2008 Free Software Foundation, Inc.
+Copyright @copyright{} 1988-2020 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.3
@smallexample
@c man begin SYNOPSIS
-gprof [ -[abcDhilLrsTvwxyz] ] [ -[ACeEfFJnNOpPqQZ][@var{name}] ]
+gprof [ -[abcDhilLrsTvwxyz] ] [ -[ACeEfFJnNOpPqQRStZ][@var{name}] ]
[ -I @var{dirs} ] [ -d[@var{num}] ] [ -k @var{from/to} ]
[ -m @var{min-count} ] [ -R @var{map_file} ] [ -t @var{table-length} ]
- [ --[no-]annotated-source[=@var{name}] ]
+ [ --[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 ]
+ [ --[no-]time=@var{name}] [ --all-lines ] [ --brief ]
+ [ --debug[=@var{level}] ] [ --function-ordering ]
[ --file-ordering @var{map_file} ] [ --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{} ]
+ [ --file-info ] [ --help ] [ --line ] [ --inline-file-names ]
+ [ --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 ]
+ [--external-symbol-table=name]
+ [ @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
+@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
+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}
@item @file{gmon.out}
dynamic call graph and profile.
@item @file{gmon.sum}
-summarized dynamic call graph and profile.
+summarized dynamic call graph and profile.
@end table
@c man end
Flat profile:
Each sample counts as 0.01 seconds.
- % cumulative self self total
- time seconds seconds calls Ts/call Ts/call name
+ % cumulative self self total
+ time seconds seconds calls Ts/call Ts/call name
44.12 0.07 0.07 zazLoop
35.29 0.14 0.06 main
20.59 0.17 0.04 bazMillion
ld -o myprog /lib/gcrt0.o myprog.o utils.o -lc_p
@end example
+If you are running the program on a system which supports shared
+libraries you may run into problems with the profiling support code in
+a shared library being called before that library has been fully
+initialised. This is usually detected by the program encountering a
+segmentation fault as soon as it is run. The solution is to link
+against a static version of the library containing the profiling
+support code, which for @code{gcc} users can be done via the
+@samp{-static} or @samp{-static-libgcc} command-line option. For
+example:
+
+@example
+gcc -g -pg -static-libgcc myprog.c utils.c -o myprog
+@end example
+
If you compile only some of the modules of the program with @samp{-pg}, you
can still profile the program, but you won't get complete information about
the modules that were compiled without @samp{-pg}. The only information
@code{gprof}. @xref{Line-by-line, ,Line-by-line Profiling}.
It also worth noting that @code{gcc} implements a
-@samp{-finstrument-functions} command line option which will insert
+@samp{-finstrument-functions} command-line option which will insert
calls to special user supplied instrumentation routines at the entry
and exit of every function in their program. This can be used to
implement an alternative profiling scheme.
@itemx --no-demangle
These options control whether C++ symbol names should be demangled when
printing output. The default is to demangle symbols. The
-@code{--no-demangle} 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
+@code{--no-demangle} 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.
@end table
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.
-@c This is compatible with Unix @code{gprof}, but a bad idea.
+@c This is compatible with Unix @code{gprof}, but a bad idea.
This option affects both the flat profile and the call graph.
@item -c
inaccuracies.
@xref{Sampling Error, ,Statistical Sampling Error}.
+@item --inline-file-names
+This option causes @code{gprof} to print the source file after each
+symbol in both the flat profile and the call graph. The full path to the
+file is printed if used with the @samp{-L} option.
+
@item -m @var{num}
@itemx --min-count=@var{num}
This option affects execution count output only.
The @samp{-n} option causes @code{gprof}, in its call graph analysis,
not to propagate times for symbols matching @var{symspec}.
+@item -S@var{filename}
+@itemx --external-symbol-table=@var{filename}
+The @samp{-S} option causes @code{gprof} to read an external symbol table
+file, such as @file{/proc/kallsyms}, rather than read the symbol table
+from the given object file (the default is @code{a.out}). This is useful
+for profiling kernel modules.
+
@item -z
@itemx --display-unused-functions
If you give the @samp{-z} option, @code{gprof} will mention all
@node Deprecated Options
@section Deprecated Options
-@table @code
-
These options have been replaced with newer versions that use symspecs.
+@table @code
+
@item -e @var{function_name}
The @samp{-e @var{function}} option tells @code{gprof} to not print
information about the function @var{function_name} (and its
as a child of any functions that call it, but its index number will be
shown as @samp{[not printed]}. More than one @samp{-e} option may be
given; only one @var{function_name} may be indicated with each @samp{-e}
-option.
+option.
@item -E @var{function_name}
The @code{-E @var{function}} option works like the @code{-e} option, but
call graph to the function @var{function_name} and its children (and
their children@dots{}). More than one @samp{-f} option may be given;
only one @var{function_name} may be indicated with each @samp{-f}
-option.
+option.
@item -F @var{function_name}
The @samp{-F @var{function}} option works like the @code{-f} option, but
Flat profile:
Each sample counts as 0.01 seconds.
- % cumulative self self total
- time seconds seconds calls ms/call ms/call name
+ % cumulative self self total
+ time seconds seconds calls ms/call ms/call name
33.34 0.02 0.02 7208 0.00 0.00 open
16.67 0.03 0.01 244 0.04 0.12 offtime
16.67 0.04 0.01 8 1.25 1.25 memccpy
The entries are sorted by time spent in the function and its subroutines.
-The internal profiling function @code{mcount} (@pxref{Flat Profile, ,The
+The internal profiling function @code{mcount} (@pxref{Flat Profile, ,The
Flat Profile}) is never mentioned in the call graph.
@menu
compiled with a @samp{-g} option, in addition to @samp{-pg}, in order
to generate debugging symbols for tracking source code lines.
Note, in much older versions of @code{gcc} the program had to be
-compiled with the @samp{-a} command line option as well.
+compiled with the @samp{-a} command-line option as well.
The flat profile is the most useful output table
in line-by-line mode.
Flat profile:
Each sample counts as 0.01 seconds.
- % cumulative self self total
- time seconds seconds calls us/call us/call name
+ % cumulative self self total
+ time seconds seconds calls us/call us/call name
30.77 0.13 0.04 6335 6.31 6.31 ct_init
Flat profile:
Each sample counts as 0.01 seconds.
- % cumulative self
- time seconds seconds calls name
+ % cumulative self
+ time seconds seconds calls name
7.69 0.10 0.01 ct_init (trees.c:349)
7.69 0.11 0.01 ct_init (trees.c:351)
7.69 0.12 0.01 ct_init (trees.c:382)
unsigned n;
2 ->@{
register ulg c;
-
+
static ulg crc = (ulg)0xffffffffL;
-
+
2 -> if (s == NULL) @{
1 -> c = 0xffffffffL;
1 -> @} else @{
ought to catch that function in the act only once, there is a pretty good
chance it will actually find that function zero times, or twice.
-By contrast, the number-of-calls and basic-block figures
-are derived by counting, not
-sampling. They are completely accurate and will not vary from run to run
-if your program is deterministic.
+By contrast, the number-of-calls and basic-block figures are derived
+by counting, not sampling. They are completely accurate and will not
+vary from run to run if your program is deterministic and single
+threaded. In multi-threaded applications, or single threaded
+applications that link with multi-threaded libraries, the counts are
+only deterministic if the counting function is thread-safe. (Note:
+beware that the mcount counting function in glibc is @emph{not}
+thread-safe). @xref{Implementation, ,Implementation of Profiling}.
The @dfn{sampling period} that is printed at the beginning of the flat
profile says how often samples are taken. The rule of thumb is that a
added delay required to deliver the signal, this method is
less accurate as well.
-A special startup routine allocates memory for the histogram and
+A special startup routine allocates memory for the histogram and
either calls @code{profil()} or sets up
a clock signal handler.
This routine (@code{monstartup}) can be invoked in several ways.
records) are read, the memory ranges of each pair of histogram records
must be either equal, or non-overlapping. For each pair of histogram
records, the resolution (memory region size divided by the number of
-bins) must be the same. The time unit must be the same for all
+bins) must be the same. The time unit must be the same for all
histogram records. If the above containts are met, all histograms
for the same memory range are merged.
projects / deliverable / binutils-gdb.git / blobdiff