MONITOR(3C)                                           MONITOR(3C)



     NAME
          monitor, monstartup, moncontrol - prepare execution profile

     SYNOPSIS
          monitor(lowpc, highpc, buffer, bufsize, nfunc)
          int (*lowpc)(), (*highpc)();
          short buffer[];

          monstartup(lowpc, highpc)
          int (*lowpc)(), (*highpc)();

          moncontrol(mode)

     DESCRIPTION
          Use of the options "-p", "-p1", "-p2", or "-p3" during
          compilation and linking (see The MIPS Languages Programmer
          Guide) automatically generates calls to the monitor,
          monstartup, and moncontrol functions. You need to call these
          functions explicitly only if you want finer control over
          profiling.

          The "-p" option you use during linking determines what
          profiling libraries the link editor (ld) searches and
          determines what variety of profiling (program-counter
          sampling, invocation counting, or basic block counting)
          takes place.

          Monstartup allocates space using sbrk(2) and passes the
          space to the monitor (see below) to provide room for profile
          data in memory during execution.  Monstartup also specifies
          the range of addresses for program counter sampling,
          starting with lowpc and ending just below highpc.

          To profile the entire program, use:

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

          Etext lies just above all program text, as described in
          end(3).

          To stop execution monitoring and write the results in an
          output file, use:

               monitor(0);

          Moncontrol selectively disables and re-enables pc-sampling
          within a program.  It has no affect on invocation-counting
          or basic-block counting.  To disable pc-sampling, use
          moncontrol(0); to resume, use moncontrol(1).  This allows
          the cost of particular operations to be measured.  If the



     Page 1                                        (last mod. 8/20/87)

     MONITOR(3C)                                           MONITOR(3C)



          PROFSAMP variable is not set as described below,
          moncontrol(1) cannot enable pc-sampling; if any profiling is
          enabled, moncontrol(0) cannot prevent the program from
          generating a file of profiling information on exit.

          Monitor is a low-level interface to profil(2).  Lowpc is the
          address of the lowest function to be pc-sampled; highpc is
          the address of the lowest function not to be pc-sampled; and
          buffer is the address of a (user supplied) array of bufsize
          short integers.

          The Monitor devotes the first part of the buffer to
          invocation or basic-block counts, if appropriate.  It uses
          the remainder for the pc samples, if appropriate.  If you
          plan to use invocation counting or basic-block counting,
          nfunc should be nonzero and the buffer must be large enough
          to accommodate the counts (half the size of the program's
          text section).  Otherwise, nfunc should be zero.  If you
          plan to use only pc-sampling, the buffer can be any size;
          however, for best results, the buffer should not be less
          than a few times smaller than the range of locations
          specified by lowpc and highpc. If invocation counting or
          basic-block counting takes place and the buffer is not large
          enough, the monitor indicates an error by returning 0.

          The monitor enables pc-sampling only if (a) you set the
          environment variable PROFSAMP to an empty string or to the
          "argv[0]" for the process, (b) you do not set the
          environment variable PROFDIR to an empty string.  In either
          case, the monitor puts the results in a file called
          "mon.out"; however, if it finds the environment variable
          PROFDIR set to a nonempty string, it constructs a file name
          of the form "profdir/pid.progname", where "profdir" comes
          from the environment variable, "pid" is the process id, and
          "progname" is the "argv[0]" for the process.

          To profile the entire program, use:

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

     FILES
          mon.out       default name for output file
          libprof1.a    routines for optional pc-sampling only

     SEE ALSO
          cc(1), prof(1), profil(2), sbrk(2), end(3c), ld(1) and The
          MIPS Languages Programmer Guide.

     ORIGIN
          MIPS Computer Systems



     Page 2                                        (last mod. 8/20/87)