Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
monitor(3C)		 Standard C Library Functions		   monitor(3C)

       monitor - prepare process execution profile

       #include	<mon.h>

       void  monitor(int (*lowpc(), int	(*highpc)(), WORD *buffer, size_t buf-
       size, size_t nfunc);

       The monitor() function is an interface to the profil(2) function	and is
       called  automatically with default parameters by	any program created by
       the cc(1B) utility with the -p option specified.	 Except	 to  establish
       further control over profiling activity,	it is not necessary to explic-
       itly call monitor().

       When used, monitor() is called at least at the beginning	and the	end of
       a  program.  The	first call to monitor()	initiates the recording	of two
       different kinds of execution-profile information:  execution-time  dis-
       tribution  and function call count. Execution-time distribution data is
       generated by profil() and the function call  counts  are	 generated  by
       code  supplied  to the object file (or files) by	 cc(1B)	-p. Both types
       of information are collected as a program executes. The	last  call  to
       monitor() writes	this collected data to the output file mon.out.

       The name	of the file written by monitor() is controlled by the environ-
       ment variable PROFDIR. If PROFDIR does not exist, the file  mon.out  is
       created	in  the	current	directory. If PROFDIR exists but has no	value,
       monitor() does no profiling and creates no output file. If  PROFDIR  is
       dirname,	 and  monitor()	is called automatically	by compilation with cc
       -p, the file created is dirname/pid.progname where progname is the name
       of the program.

       The  lowpc  and highpc arguments	are the	beginning and ending addresses
       of the region to	be profiled.

       The buffer argument is the address of a	user-supplied  array  of  WORD
       (defined	 in the	header <mon.h>).  The buffer argument is used by moni-
       tor() to	store the histogram generated by profil() and the call counts.

       The bufsize argument identifies the number of array elements in buffer.

       The nfunc argument is the number	of call	count cells that have been re-
       served  in  buffer. Additional call count cells will be allocated auto-
       matically as they are needed.

       The bufsize argument should be computed using the following formula:

       size_of_buffer =
	       sizeof(struct hdr) +
	       nfunc * sizeof(struct cnt) +
	       ((highpc-lowpc)/BARSIZE)	* sizeof(WORD) +
	       sizeof(WORD) - 1	;
       bufsize = (size_of_buffer / sizeof(WORD));


	 o  lowpc, highpc, nfunc are the same as the arguments to monitor();

	 o  BARSIZE is the number of program bytes  that  correspond  to  each
	    histogram bar, or cell, of the profil() buffer;

	 o  the	 hdr  and  cnt structures and the type WORD are	defined	in the
	    header <mon.h>.

       The default call	to monitor() is	as follows:

       monitor (&eprol,	&etext,	wbuf, wbufsz, 600);


	 o  eprol is the beginning of the user's program when linked  with  cc
	    -p (see end(3C));

	 o  etext is the end of	the user's program (see	end(3C));

	 o  wbuf is an array of	WORD with wbufsz elements;

	 o  wbufsz is computed using the bufsize formula shown above with BAR-
	    SIZE of 8;

	 o  600	is the number of call count cells that have been  reserved  in

       These parameter settings	establish the computation of an	execution-time
       distribution histogram that uses	profil() for the entire	program,  ini-
       tially  reserves	 room for 600 call count cells in buffer, and provides
       for enough histogram cells to  generate	significant  distribution-mea-
       surement	results. For more information on the effects of	bufsize	on ex-
       ecution-distribution measurements, see profil(2).

       Example 1: Example to stop execution monitoring and write  the  results
       to a file.

       To  stop	 execution monitoring and write	the results to a file, use the

       monitor((int (*)())0, (int (*)())0, (WORD *)0, 0, 0);

       Use prof	to examine the results.

       Additional calls	to monitor() after main() has been called  and	before
       exit()  has  been  called will add to the function-call count capacity,
       but such	calls will also	replace	and  restart  the  profil()  histogram

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |Safe			   |

       cc(1B), profil(2), end(3C), attributes(5), prof(5)

SunOS 5.10			  29 Dec 1996			   monitor(3C)


Want to link to this manual page? Use this URL:

home | help