MONITOR(3C)          INTERACTIVE UNIX System          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.

               The monitor function 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);

               The prof(1) 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


          Rev. C Software Development Set                            Page 1

          MONITOR(3C)          INTERACTIVE UNIX System          MONITOR(3C)



               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 pro-
               cess 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.






































          Rev. C Software Development Set                            Page 2