monitor(3C)                       SDK R4.11                      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 using the -p option with
       cc or gcc.  Except to establish further control over profiling
       activity, it is not necessary to call monitor explicitly.

       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 (g)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.  lowpc is inclusive and highpc is exclusive.  Using
       zero for lowpc indicates to stop monitoring and write the results to
       the output file.

       buffer is the address of a user-supplied array of WORDs (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:

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

              bufsize = (sizeofbuffer / sizeof(WORD));

       where:

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

              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.

       The default call to monitor can be approximated by :

              extern int start(), etext();
              monitor (start, etext, wbuf, wbufsz, 600);
       where:

              start is the first address of the user's program test;

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

              wbuf is an array of WORDs with wbufsz elements;

              wbufsz is computed using the bufsize formula shown above with
              BARSIZE of 4, lowpc of start, and highpc of etext;

              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
       (excluding shared libraries), initially reserves room for 600 call
       count cells in buffer, and provides for enough histogram cells to
       generate maximally 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.


   Considerations for Threads Programming
                     +---------+-----------------------------+
                     |         |                      async- |
                     |function | reentrant   cancel   cancel |
                     |         |             point     safe  |
                     +---------+-----------------------------+
                     |monitor  |     N         -        -    |
                     +---------+-----------------------------+

FILES
       mon.out

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

NOTE
       Additional calls to monitor after main has been called and before
       exit has been called will reset the function-call count capacity to
       the value specified, 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 (g)cc -p, the file created is dirname/pid.progname
       where progname is the name of the program.


Licensed material--property of copyright holder(s)