monitor(3C)                                           monitor(3C)



NAME
     monitor, monstartup, moncontrol - prepare execution profile

SYNOPSIS
     #include <mon.h>

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

SYNOPSIS (4.2BSD)
     void monstartup (lowpc, highpc)
     int (*lowpc)(), (*highpc)();

     void moncontrol (mode)
     int 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 parameters; monitor need not be called expli-
     citly except to gain fine control over profil buffer alloca-
     tion.  An executable program created by:
               cc -pG. . .

     automatically includes calls for the gprof(1) monitor.

     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 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





Page 1                        CX/UX Programmer's Reference Manual

monitor(3C)                                           monitor(3C)



          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 on the
     file mon.out, use

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

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

     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.  Monstartup allocates space using
     sbrk(2) and passes it to monitor to record a histogram of
     periodically sampled values of the program 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);

     Moncontrol is used to selectively control profiling within a
     program.  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 regardless of the
     state of moncontrol.

NOTE
     The format of a profile file is not guaranteed to be port-
     able across systems provided by different vendors.  In par-
     ticular, Motorola 88000 programs which are certified to con-
     form to the 88open Compatibility Standards may not be pro-
     filable on a foreign system.

FILES
     mon.out
     /lib/libp/libc.a
     /lib/libp/libm.a

SEE ALSO
     profil(2), end(3C).



Page 2                        CX/UX Programmer's Reference Manual

monitor(3C)                                           monitor(3C)



     cc(1), prof(1) in the CX/UX User's Reference Manual.






















































Page 3                        CX/UX Programmer's Reference Manual