MONITOR(3X)MONITOR(3X)


NAME
     monitor, moncontrol - Prepares execution profile

SYNOPSIS
     #include <cmplrs/mon.h>

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

     "void moncontrol(int mode);"

IMPLEMENTATION
     IRIX systems

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 -p option during compilation and linking automatically
     generates calls to the monitor and moncontrol functions.  You must
     call these functions explicitly only if you want finer control over
     profiling.

     The following three varieties of profiling are 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 libprof.a library
     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 nonshared programs.

     To profile the entire program without mcrt1.o, specify the following:

          monitor (PCS_WHOLE, 2, 0, 0);

     To stop execution monitoring and write the results into an output
     file, specify the following:

          moncontrol (PCS_DONE);

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

          moncontrol (PCS_SUSPEND);

     To resume, specify the following:

          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
     PROFDIR environment variable.  If PROFDIR is not set, the results will
     be placed in a file called mon.out in the current directory (unless,
     as explained later in this man page, 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 following
     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):

          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

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.

SEE ALSO
     cc(1), pixie(1), prof(1), ld(1)

     fork(2), profil(2), sprofil(2), sproc(2)