MONITOR(3X)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);
Page 1
MONITOR(3X)MONITOR(3X)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
Page 2
MONITOR(3X)MONITOR(3X)SEE ALSOcc(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.
Page 3
