unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-4.1.3)
Page:
Section:
Apropos / Subsearch:
optional field

MONITOR(3)                 Library Functions Manual                 MONITOR(3)



NAME
       monitor, monstartup, moncontrol - prepare execution profile

SYNOPSIS
       #include <&lt;a.out.h>&gt;

       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 with default parameters to its
       start-up routine monstartup.  In  this  case,  monitor()  need  not  be
       called  explicitly,  except  to gain fine control over profil(2) 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 (see brk(2)) and passes it to mon-
       itor()  (as  described  below) to record a histogram of program-counter
       values, and calls to certain functions.  Only calls to  functions  com-
       piled with `cc -p' are recorded.

       On  Sun-2,  Sun-3, and Sun-4 systems, an entire program can be profiled
       with:

              extern etext();
              ...
              monstartup(N_TXTOFF(0), etext);

       On Sun386i systems, the equivalent code sequence is:

              extern etext();
              extern _start();
              ...
              monstartup(_start, etext);

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

       To stop execution monitoring and post results to the file mon.out, use:

              monitor(0);

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

       moncontrol() is used to selectively control profiling within a program.
       This  works  with both prof(1) and gprof(1).  Profiling begins when the
       program starts.  To stop the collection of profiling statistics, use:

              moncontrol(0)

       To resume the collection of statistics, use:

              moncontrol(1)

       This allows you to measure the cost of particular functions.  Note:  an
       output  file  is be produced upon program exit, regardless of the state
       of moncontrol.

       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  program
       counter  samples  over  the  range lowpc to highpc, and space to record
       call counts of functions compiled with the cc -p.

       To profile the entire program on Sun-2, Sun-3, and Sun-4 systems  using
       the low-level interface to profil(2), it is sufficient to use

              extern etext();
              ...
              monitor(N_TXTOFF(0), etext, buf, bufsize, nfunc);
       On Sun386i systems, the equivalent calls are:

              extern etext();
              extern _start();
              ...
              monitor(_start, etext, buf, bufsize, nfunc);

FILES
       mon.out

SEE ALSO
       cc(1V), prof(1), gprof(1), brk(2), profil(2), end(3)



                               18 February 1988                     MONITOR(3)