prof(CP)                       6 January 1993                       prof(CP)


 Name

    prof - display profile data

 Syntax

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

 Description

    The prof command interprets a profile file produced by the monitor(S)
    function.  The symbol table in the object file prog (called 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).

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

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

    -s  Print a summary of several of the monitoring parameters and statis-
        tics on standard error.

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

    A program creates a profile if it has been loaded with the -p option of
    cc(CP).  This option to cc arranges for calls to monitor(S) at the begin-
    ning and end of execution.  It is the call to monitor at the end of exe-
    cution that causes the profile 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 pro-
    duced 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(M)).

 Files


    mon.out  Profile.

    a.out    Namelist.

 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 measure-
    ments.

    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 (that is, the static function
    call counts are not added in with the call counts of the external func-
    tion).

 Notes

    If you are using XENIX binaries, please refer to the XENIX manual page
    for this utility for information on the appropriate usage with XENIX
    binaries.

    Only programs that call exit(S) 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(CP) to invoke profiling imposes a default
    limit of 600 `pdp' (300 on the PDP-11)  functions that may have call
    counters established during program execution. If this limit is exceeded,
    other data will be overwritten and the mon.out file will be corrupted.
    For more counters you can call monitor(S) directly. Alternatively, the
    value of the global variable nfunc, located in libc.a, can be increased
    before compiling the code with the -p option.  The number of call
    counters used will be reported automatically by prof whenever the number
    exceeds 5/6 of the maximum.

 See also

    cc(CP), exit(S), monitor(S), prof(M), profil(S)

 Standards conformance

    prof is conformant with:
    AT&T SVID Issue 2.