'\"macro stdmacro
.if n .pH g3c.monitor @(#)monitor	40.15 of 10/27/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} monitor 3C "C Programming Language Utilities" "\&"
.if \nX=1 .ds x} monitor 3C "C Programming Language Utilities"
.if \nX=2 .ds x} monitor 3C "" "\&"
.if \nX=3 .ds x} monitor "" "" "\&"
.TH \*(x}
.SH NAME
\f4monitor\f1 \- prepare execution profile
.SH SYNOPSIS
\f4#include <mon.h>\f1
.PP
.nf
\f4void monitor (int (\(**lowpc)(\|), int (\(**highpc)(\|), WORD \(**buffer,
    size_t bufsize, size_t nfunc);\f1
.fi
.SH DESCRIPTION
\f4monitor\fP is an interface to \f4profil\fP,
and is called automatically with default parameters
by any program created by \f4cc \-p\f1.
Except to establish
further control over profiling activity, it is not necessary
to explicitly call \f4monitor\fP.
.PP
When used, \f4monitor\fP is called at least at the beginning and 
the end of a program.
The first call to \f4monitor\fP 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 \f4profil\fP and the function call
counts are generated by code supplied to the object file
(or files) by \f4cc \-p\f1.
Both types of information
are collected as a program executes.
The last call to \f4monitor\fP writes this collected data to
the output file \f4mon.out\f1.
.PP
\f2lowpc\f1 and \f2highpc\f1 are the beginning and ending
addresses of the region to be profiled.
.PP
\f2buffer\f1 is the address of a user-supplied array of
\f4WORD\f1 (\f4WORD\f1 is defined
in the header file \f4mon.h\f1).
\f2buffer\f1 is used by
\f4monitor\fP to store the histogram generated by \f4profil\fP
and the call counts.
.PP
\f2bufsize\f1 identifies the number of array elements
in \f2buffer\f1.
.PP
\f2nfunc\f1 is the number of call count cells that have been
reserved in \f2buffer\f1.
Additional call count cells will
be allocated automatically as they are needed.
.PP
\f2bufsize\f1 should be computed using the following formula:
.PP
.RS
.ft CW
size_of_buffer =
.ft
.br
.RS .5i 
.ft CW
sizeof(struct hdr) +
.ft
.br
.ft CW
nfunc \(** sizeof(struct cnt) +
.ft
.br
.ft CW
((highpc-lowpc)/\s-1BARSIZE\s+1) \(** sizeof(WORD) +
.ft
.br
.ft CW 
sizeof(WORD) \- 1 ;
.ft
.RE
.PP
.ft CW
bufsize = (size_of_buffer / sizeof(WORD)) ;
.ft
.PP
.RE
where:
.PP
.RS
\f2lowpc\f1, \f2highpc\f1, \f2nfunc\f1 are the same
as the arguments to \f4monitor\fP;
.PP
\f2BARSIZE\f1 is the number of program bytes that
correspond to each histogram bar, or cell, of the
\f4profil\fP buffer;
.PP
the \f4hdr\fP and \f4cnt\fP structures and the type \f4WORD\f1 are
defined in the header file \f4mon.h\f1.
.RE
.bp
.PP
The default call to \f4monitor\fP is shown below:
.PP
.RS
.ft CW
.nf
monitor (&eprol, &etext, wbuf, wbufsz, 600);
.fi
.ft
.RE
where:
.PP
.RS
\f4eprol\f1 is the beginning
of the user's program when linked with \f4cc \-p\f1
[see \f4end\fP(3C)];
.PP
\f4etext\f1 is the end of the user's program
[see \f4end\f1(3C)];
.PP
\f2wbuf\f1 is an array of \f4WORD\f1 with \f2wbufsz\f1 elements;
.PP
\f2wbufsz\f1 is computed using the \f2bufsize\f1 formula
shown above with \f2BARSIZE\f1 of 8;
.PP
\f4600\f1
is the number of call count cells that have been reserved in \f2buffer\f1.
.RE
.PP
These parameter settings establish the computation of an execution-time
distribution histogram that uses \f4profil\fP for the entire program,
initially reserves room for 600 call count cells in \f2buffer\f1, and provides
for enough histogram cells to generate significant distribution-measurement
results.
[For more information on the effects of \f2bufsize\f1 on
execution-distribution measurements, see \f4profil\fP(2).]
.PP
To stop execution monitoring and write the results to a file, use the following:
.RS
.PP
.ft CW
monitor(\|(int (\(**)(\|)\|)0, (int (\(**)(\|)\|)0, (WORD \(**)0, 0, 0);
.ft
.PP
.RE
Use \f4prof\fP to examine the results.
.SH FILES
\f4mon.out\f1
.SH SEE ALSO
\f4cc\fP(1), \f4prof\fP(1), \f4profil\fP(2), \f4end\fP(3C).
.SH NOTE
.PP
Additional calls to \f4monitor\fP after \f4main\f1 has been called
and before \f4exit\fP has been called will add to the function-call
count capacity, but such calls will also replace and restart the
\f4profil\fP histogram computation.
.PP
The name of the file written by \f4monitor\fP is controlled by the
environment variable \f4PROFDIR\f1.
If \f4PROFDIR\f1 does not
exist, the file \f4mon.out\f1 is created in the current directory.
If \f4PROFDIR\f1 exists but has no value, \f4monitor\fP does no profiling
and creates no output file.
If \f4PROFDIR\f1 is \f2dirname\fP,
and
\f4monitor\fP is called
automatically by compilation with \f4cc \-p\f1, the file created is
\f2dirname\f4/\f2pid.progname\f1 where \f2progname\f1 is the name
of the program.
.Ee
