X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=gprof%2Fgprof.texi;h=790cd6b133495a4da9c84a809fc0736df698bff4;hb=b5624945ea67525c0ba4ffec7a9d3f9366bf9071;hp=1f86383de7c155b3a2c1223a224de2c9270fcb63;hpb=c8d1c0af8062b171426f9dc64e895a39eb255146;p=external%2Fbinutils.git diff --git a/gprof/gprof.texi b/gprof/gprof.texi index 1f86383..790cd6b 100644 --- a/gprof/gprof.texi +++ b/gprof/gprof.texi @@ -1,8 +1,6 @@ \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-2019 Free Software Foundation, Inc. @settitle GNU gprof @setchapternewpage odd @@ -10,21 +8,20 @@ @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-2019 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 @@ -41,7 +38,7 @@ section entitled ``GNU Free Documentation License''. @titlepage @title GNU gprof -@subtitle The @sc{gnu} Profiler +@subtitle The @sc{gnu} Profiler @ifset VERSION_PACKAGE @subtitle @value{VERSION_PACKAGE} @end ifset @@ -57,7 +54,7 @@ execute programs. @sc{gnu} @code{gprof} was written by Jay Fenlason. 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-2019 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 @@ -113,34 +110,36 @@ in the section entitled ``GNU Free Documentation License''. @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} @@ -185,7 +184,7 @@ the namelist and text space. @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 @@ -304,8 +303,8 @@ graph data you will still be able to see the time samples: 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 @@ -332,7 +331,7 @@ 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 +@samp{-static} or @samp{-static-libgcc} command-line option. For example: @example @@ -358,7 +357,7 @@ there is still support for displaying this kind of information in @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. @@ -645,9 +644,9 @@ first line. This behavior is similar to @code{tcov}'s @samp{-a}. @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 @@ -664,7 +663,7 @@ 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. -@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 @@ -710,6 +709,11 @@ the running time of @code{gprof}, and magnifies statistical 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. @@ -725,6 +729,13 @@ to only propagate times for symbols matching @var{symspec}. 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 @@ -777,10 +788,10 @@ number, and then exit. @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 @@ -788,7 +799,7 @@ children@dots{}) 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 @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 @@ -802,7 +813,7 @@ The @samp{-f @var{function}} option causes @code{gprof} to limit the 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 @@ -922,8 +933,8 @@ This is part of a flat profile for a small program: 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 @@ -1076,7 +1087,7 @@ function and the following lines describe its subroutines (also called 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 @@ -1420,7 +1431,7 @@ With the older versions of @code{gcc} the program usually has to be 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. @@ -1438,8 +1449,8 @@ Note that @code{ct_init} accounted for four histogram hits, and 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 @@ -1471,8 +1482,8 @@ from line 385, and 6525 calls from 387. 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) @@ -1565,9 +1576,9 @@ annotated source listing for a sample @code{gzip} run: unsigned n; 2 ->@{ register ulg c; - + static ulg crc = (ulg)0xffffffffL; - + 2 -> if (s == NULL) @{ 1 -> c = 0xffffffffL; 1 -> @} else @{ @@ -1605,10 +1616,14 @@ only a small amount of time, so that on the average the sampling process 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 @@ -1870,7 +1885,7 @@ more overhead than kernel-based profiling. Also, due to the 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. @@ -2084,7 +2099,7 @@ When multiple profile data files (or files with multiple histogram 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.