MONITOR(3X)							   MONITOR(3X)

NAME    [Toc]    [Back]

     monitor, moncontrol - prepare execution profile

SYNOPSIS    [Toc]    [Back]

     #include <cmplrs/mon.h>

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

     void moncontrol(int mode);

DESCRIPTION    [Toc]    [Back]

     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    [Toc]    [Back]

     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 ALSO    [Toc]    [Back]

     cc(1), pixie(1), prof(1), ld(1), fork(2), profil(2), sprofil(2) and
     sproc(2).

DIAGNOSTICS    [Toc]    [Back]

     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.


									PPPPaaaaggggeeee 3333