MONITOR(3C)                          SysV                          MONITOR(3C)



NAME
     monitor - prepare execution profile

SYNOPSIS
     #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.

     monitor is an interface to profil(2).  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 arranges to
     record a histogram of periodically sampled values of the program counter,
     and of counts of calls of certain functions, 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 functions compiled with the profiling option
     -p of cc(1) 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(3C).

     To stop execution monitoring and write the results, use

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

     prof(1) 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
     output file.  If PROFDIR is dirname, then the file written is
     ``dirname/pid.mon.out'' where pid is the program's process id.  (When
     monitor is called automatically by compiling via cc -p, the file created
     is ``dirname/pid.progname'' where progname is the name of the program.)

FILES
     mon.out

SEE ALSO
     cc(1), Prof(1), profil(2), end(3C).

BUGS

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