monitor

Synopsis

Description

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 utility
with the -p option specified. Except to establish further control over profiling
activity, it is not necessary to explicitly 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 distribution 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-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
environment 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
monitor() 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 reserved in buffer. Additional call count cells will be allocated automatically
as they are needed.

wbufsz is computed using the bufsize formula shown above with BARSIZE of 8;

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

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

Examples

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 following:

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

Use prof to examine the results.

Usage

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 computation.