monitor(S)                     6 January 1993                     monitor(S)


 Name

    monitor - prepare execution profile

 Syntax


    cc ... -lc


    #include <mon.h>

    void monitor (lowpc, highpc, buffer, bufsize, nfunc)
    int (*lowpc)( ), (*highpc)( );
    WORD *buffer;
    int bufsize, nfunc;


 Description

    An executable program created by cc -p automatically includes calls for
    monitor with default parameters; monitor need not be called explicitly
    except to gain fine control over profiling.

    The monitor function is an interface to profil(S).  lowpc and highpc are
    the addresses of two functions; buffer is the address of a user-supplied
    array of bufsize WORDs (defined in the <mon.h> header file).  monitor
    records a histogram of two items:  periodically sampled values of the
    program counter and counts of calls to certain functions.  This histogram
    is recorded in the buffer.  The lowest address sampled is that of lowpc
    and the highest is just below highpc.  lowpc may not equal 0 for this use
    of monitor.  At most nfunc, call counts can be kept; only calls of func-
    tions compiled with the profiling option -p of cc(CP) are recorded.

    For the results to be significant, especially where there are small,
    heavily used routines, it is suggested that the buffer be no more than a
    few times smaller than the range of locations sampled.

    To profile the entire program, it is sufficient to use

               extern etext;
               ...
               monitor ((int (*)())2, &etext, buf, bufsize, nfunc);

    etext lies just above all the program text; see end(S).

    To stop execution monitoring and write the results, use

               monitor ((int (*)())0, 0, 0, 0, 0);

    The prof(CP) command can then be used to examine the results.

    The name of the file written by monitor is controlled by the environment
    variable PROFDIR.  If PROFDIR does not exist, mon.out is created in the
    current directory.  If PROFDIR exists but has no value, monitor does not
    do any profiling and creates no output file.  Otherwise, the value of
    PROFDIR is used as the name of the directory in which to create the out-
    put file.  If PROFDIR is dirname, then the file written is in the format
    of:

       dirname/pid.mon.out

    where pid is the program's process ID.  (When monitor is called automati-
    cally by compiling via cc -p, the file created is
    ``dirname/pid.progname'' where progname is the name of the program.)

 Files

    mon.out

 Notes

    The dirname/pid.mon.out form does not work; the dirname/pid.progname form
    (automatically called via cc -p) does work.

 See also

    cc(CP), end(S), prof(CP), profil(S)

 Standards conformance

    monitor is conformant with:
    AT&T SVID Issue 2, but has been withdrawn from XPG3.  The <mon.h> header
    file has also been withdrawn from XPG3.