4.3BSD - /usr/man/cat3/moncontrol.0

MONITOR(3)                                                          MONITOR(3)


NAME
       monitor, monstartup, moncontrol - prepare execution profile

SYNOPSIS
       monitor(lowpc, highpc, buffer, bufsize, nfunc)
       int (*lowpc)(), (*highpc)();
       short buffer[];

       monstartup(lowpc, highpc)
       int (*lowpc)(), (*highpc)();

       moncontrol(mode)

DESCRIPTION
       There  are  two  different forms of monitoring available: An executable
       program created by:

            cc -p . . .

       automatically includes calls for the prof(1) monitor  and  includes  an
       initial  call  to  its start-up routine monstartup with default parame‐
       ters; monitor need not be called explicitly except to gain fine control
       over profil buffer allocation.  An executable program created by:

            cc -pg . . .

       automatically includes calls for the gprof(1) monitor.

       Monstartup  is  a  high level interface to profil(2).  Lowpc and highpc
       specify the address range that is to be  sampled;  the  lowest  address
       sampled  is  that  of lowpc and the highest is just below highpc.  Mon���
       startup allocates space using sbrk(2) and passes  it  to  monitor  (see
       below) to record a histogram of periodically sampled values of the pro‐
       gram counter, and of counts of  calls  of  certain  functions,  in  the
       buffer.   Only calls of functions compiled with the profiling option -p
       of cc(1) are recorded.

       To profile the entire program, it is sufficient to use

            extern etext();
            . . .
            monstartup((int) 2, etext);

       Etext lies just above all the program text, see end(3).

       To stop execution monitoring and write the results on the file mon.out,
       use

            monitor(0);

       then prof(1) can be used to examine the results.

       Moncontrol  is  used to selectively control profiling within a program.
       This works with either prof(1) or gprof(1) type  profiling.   When  the
       program  starts, profiling begins.  To stop the collection of histogram
       ticks and call counts use moncontrol(0); to resume  the  collection  of
       histogram  ticks  and  call  counts use moncontrol(1).  This allows the
       cost of particular operations to be measured.  Note that an output file
       will be produced upon program exit irregardless of the state of moncon���
       trol.

       Monitor is a low level interface to profil(2).  Lowpc  and  highpc  are
       the  addresses  of two functions; buffer is the address of a (user sup‐
       plied) array of bufsize short integers.  At most nfunc call counts  can
       be kept.  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.
       Monitor divides the buffer into space to record the histogram  of  pro‐
       gram  counter  samples  over  the  range  lowpc to highpc, and space to
       record call counts of functions compiled with the -p option to cc(1).

       To profile the entire program, it is sufficient to use

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

FILES
       mon.out

SEE ALSO
       cc(1), prof(1), gprof(1), profil(2), sbrk(2)


4th Berkeley Distribution        May 15, 1985                       MONITOR(3)