PROF(1)      (Extended Software Generation Utilities)     PROF(1)



  NAME
       prof - display profile data

  SYNOPSIS
       prof [-tcan] [-ox] [-g] [-z] [-h] [-s] [-m mdata] [prog]

  DESCRIPTION
       The prof command interprets a profile file produced by the
       monitor(3C) function.  The symbol table in the object file
       prog (a.out by default) is read and correlated with a
       profile file (mon.out by default).  For each external text
       symbol the percentage of time spent executing between the
       address of that symbol and the address of the next is
       printed, together with the number of times that function was
       called and the average number of milliseconds per call.

       The mutually exclusive options t, c, a, and n determine the
       type of sorting of the output lines:

       -t   Sort by decreasing percentage of total time (default).

       -c   Sort by decreasing number of calls.

       -a   Sort by increasing symbol address.

       -n   Sort lexically by symbol name.

       The mutually exclusive options o and x specify the printing
       of the address of each symbol monitored:

       -o   Print each symbol address (in octal) along with the
            symbol name.

       -x   Print each symbol address (in hexadecimal) along with
            the symbol name.

       The following options may be used in any combination:

       -g   Include non-global symbols (static functions).



  Page 1                                                   May 1989

  PROF(1)      (Extended Software Generation Utilities)     PROF(1)



       -z   Include all symbols in the profile range [see
            monitor(3C)], even if associated with zero number of
            calls and zero time.

       -h   Suppress the heading normally printed on the report.
            (This is useful if the report is to be processed
            further.)

       -s   Print a summary of several of the monitoring parameters
            and statistics on the standard error output.

       -m mdata
            Use file mdata instead of mon.out as the input profile
            file.

       A program creates a profile file if it has been loaded with
       the -p option of cc(1).  This option to the cc command
       arranges for calls to monitor(3C) at the beginning and end
       of execution.  It is the call to monitor at the end of
       execution that causes a profile file to be written.  The
       number of calls to a function is tallied if the -p option
       was used when the file containing the function was compiled.

       The name of the file created by a profiled program is
       controlled by the environment variable PROFDIR.  If PROFDIR
       does not exist, ``mon.out'' is produced in the directory
       that is current when the program terminates.  If PROFDIR =
       string, ``string/pid.progname'' is produced, where progname
       consists of argv[0] with any path prefix removed, and pid is
       the program's process id.  If PROFDIR is the null string, no
       profiling output is produced.

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

  FILES
       mon.out  for profile
       a.out    for namelist

  SEE ALSO


  Page 2                                                   May 1989

  PROF(1)      (Extended Software Generation Utilities)     PROF(1)



       cc(1), exit(2), profil(2), monitor(3C), prof(5).

  WARNING
       The times reported in successive identical runs may show
       variances of 20% or more, because of varying cache-hit
       ratios due to sharing of the cache with other processes.
       Even if a program seems to be the only one using the
       machine, hidden background or asynchronous processes may
       blur the data.  In rare cases, the clock ticks initiating
       recording of the program counter may ``beat'' with loops in
       a program, grossly distorting measurements.

       Call counts are always recorded precisely.

       The times for static functions are attributed to the
       preceding external text symbol if the -g option is not used.
       However, the call counts for the preceding function are
       still correct, i.e., the static function call counts are not
       added in with the call counts of the external function.

  CAVEATS
       Only programs that call exit(2) or return from main will
       cause a profile file to be produced, unless a final call to
       monitor is explicitly coded.

       The use of the -p option to cc(1) to invoke profiling
       imposes a limit of 600 functions that may have call counters
       established during program execution.  For more counters you
       must call monitor(3C) directly.  If this limit is exceeded,
       other data will be overwritten and the mon.out file will be
       corrupted.  The number of call counters used will be
       reported automatically by the prof command whenever the
       number exceeds 5/6 of the maximum.









  Page 3                                                   May 1989