monitor(3X)

NAME
     monitor, moncontrol - prepare execution profile

SYNOPSIS
     #include <cmplrs/mon.h>

     int monitor(int mode, unsigned grain, int (*lowpc)(), int (*highpc)());

     void moncontrol(int mode);

DESCRIPTION
     NOTE: These functions have been moved from the standard C library to the
     libprof library.  If a program needs to access these routines it must
     either use the -p option on the compiler/linker or explicitly link with
     the -lprof linker option. These functions have been changed to work
     correctly with dynamic shared objects (dsos).

     Use of the option -p during compilation and linking automatically
     generates calls to the monitor and moncontrol functions. You need to call
     these functions explicitly only if you want finer control over profiling.

     There are three varieties of profiling available:  program-counter (pc)
     sampling, invocation counting, and basic block counting.  The functions
     described on this page provide only pc-sampling, the pixie(1) command
     must be used to get the other types of profiling information.

     The -p option used during linking forces the link editor (ld) to include
     a special start-up routine mcrt1.o and the library libprof.a that
     contains these routines.

     monitor(mode, grain, lowpc, highpc) is used to initialize pc-sampling.
     grain is the number of instruction counted in one bucket. lowpc and
     highpc are currently unused. For finer control, the user can use the
     moncontrol() function.

     monitor(PCS_MAIN, grain, 0, 0) specifies that only the MAIN module of a
     shared program is included for program counter sampling.
     monitor(PCS_WHOLE, grain, 0, 0) specifies that the whole program
     (including dynamic shared libraries) is included for program counter
     sampling.  monitor(PCS_MAIN, grain, 0, 0) and monitor(PCS_WHOLE, grain,
     0, 0) are equivalent for non-shared programs.

     Without mcrt1.o , to profile the entire program, use:

          monitor (PCS_WHOLE, 2, 0, 0);

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

          moncontrol (PCS_DONE);

     moncontrol selectively disables and re-enables pc-sampling within a
     program.  To disable pc-sampling, use:

          moncontrol (PCS_SUSPEND);

     to resume, use:

          moncontrol (PCS_RESUME);

     This is done automatically by a special exit function linked in with
     mcrt1.o.

     This allows the cost of particular operations to be measured.  If any
     profiling is enabled, moncontrol cannot prevent the program from
     generating a file of profiling information on exit.

     The location of the profiling output files, and whether or not calls to
     monitor will cause pc-sampling to be started are determined by the
     environment variable  PROFDIR.  If PROFDIR is not set, the results will
     be placed in a file called mon.out in the current directory (unless, as
     explained below, shared address processes are being pc- sampled).  If
     PROFDIR is set to a nonempty string, it constructs a file name of the
     form profdir/progname.mon.pid , where "profdir" comes from the
     environment variable, "pid" is the process id, and "progname" is the
     "argv[0]" for the process.

     It is also possible via moncontrol to profile parts of a program, write
     those results to a file, and continue profiling.  The

          moncontrol (PCS_NEWPHASE);

     function causes the current contents of the profiling buffer to be
     written to a file of the form "profdir/progname.mon.pid.phase_id" or
     "mon.out.phase_id"; "phase_id" is the string "p<n>", where <n> starts
     from 1 and increments for each call to moncontrol(PCS_NEWPHASE).  The
     profiling buffer is cleared after every call to moncontrol.

     If a program that is performing pc-sampling executes the fork(2) system
     call, the profiling information is duplicated, and each will continue to
     pc-sample into their own buffer.  However, it is important that PROFDIR
     be defined otherwise the last process to exit will overwrite the values
     in mon.out of the rest.

     If a program that is performing pc-sampling executes the sproc(2) system
     call, mcrt1.o initiates profiling for the new process.  At exit time,
     regardless of whether PROFDIR is set, unique file names will be created.

FILES
     mon.out             default name for output file
     libprof.a           routines for pc-sampling
     /usr/lib/mcrt1.o    special start-up routine for pc-sampling
SEE ALSO
     cc(1), pixie(1), prof(1), ld(1), fork(2), profil(2), sprofil(2) and
     sproc(2).

DIAGNOSTICS
     monitor returns 0 on failure due to insufficient memory.  It returns 1
     for a successful call.  If the result file cannot be created or written
     to, an error message is printed on stderr and a 0 is returned.  monitor
     forces the caller to exit on a failed call to monitor.