unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

GPROF(1)                    General Commands Manual                   GPROF(1)



NAME
       gprof - display call-graph profile data

SYNOPSIS
       gprof [ -abcsz ] [ -e function-name ] [ -E function-name ]
            [ -f function-name ] [ -F function-name ]
            [ image-file [ profile-file ... ] ]

DESCRIPTION
       gprof produces an execution profile of a program.  The effect of called
       routines is incorporated in the profile of each  caller.   The  profile
       data is taken from the call graph profile file which is created by pro-
       grams compiled with the -pg option of cc(1V) and other compilers.  That
       option  also  links  in versions of the library routines which are com-
       piled for profiling.  The symbol table in  the  executable  image  file
       image-file  (a.out  by  default)  is  read and correlated with the call
       graph profile file profile-file (gmon.out by default).   If  more  than
       one  profile  file  is specified, the gprof output shows the sum of the
       profile information in the given profile files.

       First, execution times for each routines 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 func-
       tions  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.

       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.

       Next, a flat profile is given, similar to  that  provided  by  prof(1).
       This  listing  gives the total execution times and call counts for each
       of the functions in the program, sorted by decreasing  time.   Finally,
       an  index  showing  the correspondence between function names and call-
       graph profile index numbers.

       A single function may be split into subfunctions for profiling by means
       of the MARK macro (see prof(3)).

       Beware  of  quantization  errors.   The  granularity of the sampling is
       shown, but remains statistical at best.  It is assumed  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 parents of that
       function is directly proportional to the number of times  that  arc  is
       traversed.

       The profiled program must call exit(2V) or return normally for the pro-
       filing information to be saved in the gmon.out file.

OPTIONS
       -a     Suppress printing statically declared functions.  If this option
              is  given,  all  relevant  information about the static function
              (for instance, time samples, calls  to  other  functions,  calls
              from other functions) belongs to the function loaded just before
              the static function in the a.out file.

       -b     Brief.  Suppress descriptions of each field in the profile.

       -c     The static call-graph of the program is discovered by a  heuris-
              tic  which  examines the text space of the object file.  Static-
              only parents or children are indicated with call counts of 0.

       -s     Produce a profile file gmon.sum which represents the sum of  the
              profile  information  in  all the specified profile files.  This
              summary profile file may be given to  subsequent  executions  of
              gprof  (probably  also  with  a -s) option to accumulate profile
              data across several runs of an a.out file.

       -z     Display routines which have zero usage  (as  indicated  by  call
              counts  and  accumulated  time).   This is useful in conjunction
              with the -c option for discovering  which  routines  were  never
              called.

       -e function-name
              Suppress  printing the graph profile entry for routine function-
              name and all its descendants (unless they have  other  ancestors
              that are not suppressed).  More than one -e option may be given.
              Only one function-name may be given with each -e option.

       -E function-name
              Suppress printing the graph profile entry for routine  function-
              name  (and  its  descendants) as -e, above, and also exclude the
              time spent in function-name (and its descendants) from the total
              and  percentage  time computations.  More than one -E option may
              be given.  For example:
                     `-E mcount -E mcleanup'

              is the default.

       -f function-name
              Print the graph profile entry only for routine function-name and
              its  descendants.   More  than one -f option may be given.  Only
              one function-name may be given with each -f option.

       -F function-name
              Print the graph profile entry only for routine function-name and
              its  descendants  (as  -f, above) and also use only the times of
              the printed routines in total time and percentage  computations.
              More  than  one  -F option may be given.  Only one function-name
              may be given with each -F option.  The -F option  overrides  the
              -E option.

ENVIRONMENT
       PROFDIR
              If  this  environment variable contains a value, place profiling
              output within that directory, in a file  named  pid.programname.
              pid  is  the process ID, and programname is the name of the pro-
              gram being profiled, as determined by removing any  path  prefix
              from  the  argv[0]  with  which  the program was called.  If the
              variable contains a NULL value, no profiling output is produced.
              Otherwise, profiling output is placed in the file gmon.out.

FILES
       a.out               executable file containing namelist
       gmon.out            dynamic call-graph and profile
       gmon.sum            summarized dynamic call-graph and profile
       $PROFDIR/pid.programname

SEE ALSO
       cc(1V), prof(1), tcov(1), exit(2V), profil(2), monitor(3), prof(3)

       Graham,  S.L., Kessler, P.B., McKusick, M.K., `gprof: A Call Graph Exe-
       cution Profiler', Proceedings of the SIGPLAN '82 Symposium on  Compiler
       Construction, SIGPLAN Notices, Vol. 17, No. 6, pp. 120-126, June 1982.

BUGS
       Parents  which  are not themselves profiled will have the time of their
       profiled children propagated to them, but they will appear to be  spon-
       taneously  invoked  in  the call-graph listing, and will not have their
       time propagated further.  Similarly, signal catchers, even though  pro-
       filed,  will  appear  to be spontaneous (although for more obscure rea-
       sons).  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.



                               22 December 1987                       GPROF(1)