NAME

monitor, monstartup, moncontrol − prepare execution profile

SYNOPSIS

monitor(lowpc, highpc, buffer, bufsize, nfunc)
int (*lowpc)(), (*highpc)();
short buffer[];
monstartup(lowpc, highpc)
int (*lowpc)(), (*highpc)();
moncontrol(mode)

DESCRIPTION

These functions use the system call profil() to control program-counter sampling.  Using the option −p when compiling or linking a program automatically generates calls to these functions.  You do need not to call these functions explicitly unless you want more control. 

Typically, you would call either monitor or monstartup to initialize pc-sampling and enable it; call moncontrol to disable or reenable it; and call monitor at the end of execution to disable sampling and record the samples in a file.

Your initial call to monitor enables pc-sampling. The parameters lowpc and highpc specify the range of addresses to be sampled.  The lowest address is that of lowpc and the highest is just below highpc. The buffer parameter is the address of a (user allocated) array of bufsize short integers, which holds a record of the samples; for best results, the buffer should not be less than a few times smaller than the range of addresses sampled.  The nfunc parameter is ignored. 

The environment variable PROFDIR determines the name of the output file and whether pc-sampling takes place: if it is not set, the file is named mon.out; if set to the empty string, no pc-sampling occurs; if set to a non-empty string, the file is named string/pid.progname, where pid is the process id of the executing program and progname is the program’s name as it appears in argv[0]. The subdirectory string must already exist. 

To profile the entire program, use the following:

extern eprol(), etext();
. . .
monitor(eprol, etext, buf, bufsize, 0);

The routine eprol lies just below the user program text, and etext lies just above it, as described in end(.). (Because the user program does not necessarily start at a low memory address, using a small number in place of eprol is dangerous).

The monstartup routine is an alternate form of monitor that calls sbrk (see brk())) for you to allocate the buffer.

The function moncontrol selectively disables and re-enables pc-sampling within a program, allowing you to measure the cost of particular operations. The function moncontrol(0) disables pc-sampling, and moncontrol(1) reenables it.

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

monitor(0);

FILES

mon.outdefault name for output file
libprof1.aroutines for pc-sampling

SEE ALSO

cc(1), ld(1), profil(2), brk(2)

Subroutines