monitor(3C)            UNIX System V(C Development Set)             monitor(3C)


NAME
      monitor - prepare execution profile

SYNOPSIS
      #include <mon.h>

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

DESCRIPTION
      monitor is an interface to profil, and is called automatically with
      default parameters by any program created by cc -p.  Except to establish
      further control over profiling activity, it is not necessary to
      explicitly call monitor.

      When used, monitor is called at least at the beginning and the end of a
      program.  The first call to monitor initiates the recording of two
      different kinds of execution-profile information:  execution-time
      distribution and function call count.  Execution-time distribution data
      is generated by profil and the function call counts are generated by code
      supplied to the object file (or files) by cc -p.  Both types of
      information are collected as a program executes.  The last call to
      monitor writes this collected data to the output file mon.out.

      lowpc and highpc are the beginning and ending addresses of the region to
      be profiled.

      buffer is the address of a user-supplied array of WORD (WORD is defined
      in the header file mon.h).  buffer is used by monitor to store the
      histogram generated by profil and the call counts.

      bufsize identifies the number of array elements in buffer.

      nfunc is the number of call count cells that have been reserved in
      buffer.  Additional call count cells will be allocated automatically as
      they are needed.

      bufsize should be computed using the following formula:

            size_of_buffer =
                 sizeof(struct hdr) +
                 nfunc * sizeof(struct cnt) +
                 ((highpc-lowpc)/BARSIZE) * sizeof(WORD) +
                 sizeof(WORD) - 1 ;

            bufsize = (size_of_buffer / sizeof(WORD)) ;

      where:

            lowpc, highpc, nfunc are the same as the arguments to monitor;




10/89                                                                    Page 1

monitor(3C)            UNIX System V(C Development Set)             monitor(3C)


            BARSIZE is the number of program bytes that correspond to each
            histogram bar, or cell, of the profil buffer;

            the hdr and cnt structures and the type WORD are defined in the
            header file mon.h.

















































Page 2                                                                    10/89

monitor(3C)            UNIX System V(C Development Set)             monitor(3C)


      The default call to monitor is shown below:

            monitor (&eprol, &etext, wbuf, wbufsz, 600);
      where:

            eprol is the beginning of the user's program when linked with cc -p
            [see end(3C)];

            etext is the end of the user's program [see end(3C)];

            wbuf is an array of WORD with wbufsz elements;

            wbufsz is computed using the bufsize formula shown above with
            BARSIZE of 8;

            600 is the number of call count cells that have been reserved in
            buffer.

      These parameter settings establish the computation of an execution-time
      distribution histogram that uses profil for the entire program, initially
      reserves room for 600 call count cells in buffer, and provides for enough
      histogram cells to generate significant distribution-measurement results.
      [For more information on the effects of bufsize on execution-distribution
      measurements, see profil(2).]

      To stop execution monitoring and write the results to a file, use the
      following:

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

      Use prof to examine the results.

FILES
      mon.out

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

NOTE
      Additional calls to monitor after main has been called and before exit
      has been called will add to the function-call count capacity, but such
      calls will also replace and restart the profil histogram computation.

      The name of the file written by monitor is controlled by the environment
      variable PROFDIR.  If PROFDIR does not exist, the file mon.out is created
      in the current directory.  If PROFDIR exists but has no value, monitor
      does no profiling and creates no output file.  If PROFDIR is dirname, and
      monitor is called automatically by compilation with cc -p, the file
      created is dirname/pid.progname where progname is the name of the
      program.




10/89                                                                    Page 3