'\" te
.\"  Copyright 1989 AT&T  Copyright (c) 1997, Sun Microsystems, Inc.  All Rights Reserved
.TH monitor 3C "29 Dec 1996" "SunOS 5.11" "Standard C Library Functions"
.SH NAME
monitor \- prepare process execution profile
.SH SYNOPSIS
.LP
.nf
#include <mon.h>

\fBvoid\fR \fBmonitor\fR(\fBint (*\fR\fIlowpc\fR(), \fBint (*\fR\fIhighpc\fR)(), \fBWORD *\fR\fIbuffer\fR, \fBsize_t\fR \fIbufsize\fR,
     \fBsize_t\fR \fInfunc\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBmonitor()\fR function is an interface to the \fBprofil\fR(2) function and is called automatically with default parameters by any program created by the \fBcc\fR utility with the \fB-p\fR option specified. Except to establish further control over profiling activity, it is not necessary to explicitly call \fBmonitor()\fR.
.sp
.LP
When used, \fBmonitor()\fR is called at least at the beginning and the end of a program. The first call to \fBmonitor()\fR 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 \fBprofil()\fR and the function call counts are generated by code supplied to the object file (or files) by  \fBcc\fR \fB-p.\fR Both types of information are collected as a program executes. The last call to \fBmonitor()\fR writes this collected data to the output file \fBmon.out\fR.
.sp
.LP
The name of the file written by \fBmonitor()\fR is controlled by the environment variable \fBPROFDIR\fR. If \fBPROFDIR\fR does not exist, the file \fBmon.out\fR is created in the current directory. If \fBPROFDIR\fR exists but has no value, \fBmonitor()\fR does no profiling and creates no output file. If \fBPROFDIR\fR is \fBdirname\fR, and \fBmonitor()\fR is called automatically by compilation with \fBcc \fR\fB-p\fR, the file created is \fBdirname\fR\fB/\fR\fIpid.progname\fR where \fIprogname\fR is the name of the program.
.sp
.LP
The \fIlowpc\fR and \fIhighpc\fR arguments are the beginning and ending addresses of the region to be profiled.
.sp
.LP
The \fIbuffer\fR argument is the address of a user-supplied array of \fBWORD\fR (defined in the header \fB<mon.h>\fR).  The \fIbuffer\fR argument is used by \fBmonitor()\fR to store the histogram generated by \fBprofil()\fR and the call counts.
.sp
.LP
The \fIbufsize\fR argument identifies the number of array elements in \fIbuffer\fR.
.sp
.LP
The \fInfunc\fR argument is the number of call count cells that have been reserved in \fIbuffer\fR. Additional call count cells will be allocated automatically as they are needed.
.sp
.LP
The \fIbufsize\fR argument should be computed using the following formula:
.sp
.in +2
.nf
size_of_buffer =
        sizeof(struct hdr) +
        \fInfunc\fR * sizeof(struct cnt) +
        ((\fIhighpc\fR-\fIlowpc\fR)/\fIBARSIZE\fR) * sizeof(WORD) +
        sizeof(WORD) \(mi 1 ;
bufsize = (size_of_buffer / sizeof(WORD));
.fi
.in -2

.sp
.LP
where:
.RS +4
.TP
.ie t \(bu
.el o
\fIlowpc\fR, \fIhighpc\fR, \fInfunc\fR are the same as the arguments to \fBmonitor()\fR;
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fIBARSIZE\fR is the number of program bytes that correspond to each histogram bar, or cell, of the \fBprofil()\fR buffer;
.RE
.RS +4
.TP
.ie t \(bu
.el o
the \fBhdr\fR and \fBcnt\fR structures and the type \fBWORD\fR are defined in the header \fB<mon.h>\fR\&.
.RE
.sp
.LP
The default call to \fBmonitor()\fR is as follows:
.sp
.in +2
.nf
monitor (&eprol, &etext, wbuf, wbufsz, 600);
.fi
.in -2

.sp
.LP
where:
.RS +4
.TP
.ie t \(bu
.el o
\fBeprol\fR is the beginning of the user's program when linked with \fBcc \fR\fB-p\fR (see \fBend\fR(3C));
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBetext\fR is the end of the user's program (see \fBend\fR(3C));
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBwbuf\fR is an array of \fBWORD\fR with \fIwbufsz\fR elements;
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fBwbufsz\fR is computed using the \fIbufsize\fR formula shown above with \fIBARSIZE\fR of 8;
.RE
.RS +4
.TP
.ie t \(bu
.el o
\fB600\fR is the number of call count cells that have been reserved in \fIbuffer\fR.
.RE
.sp
.LP
These parameter settings establish the computation of an execution-time distribution histogram that uses \fBprofil()\fR for the entire program, initially reserves room for 600 call count cells in \fIbuffer\fR, and provides for enough histogram cells to generate significant distribution-measurement results. For more information on the effects of \fIbufsize\fR on execution-distribution measurements, see \fBprofil\fR(2).
.SH EXAMPLES
.LP
\fBExample 1 \fRExample to stop execution monitoring and write the results to a file.
.sp
.LP
To stop execution monitoring and write the results to a file, use the following:

.sp
.in +2
.nf
monitor(\|(int (*)(\|)\|)0, (int (*)(\|)\|)0, (WORD *)0, 0, 0);
.fi
.in -2

.sp
.LP
Use \fBprof\fR to examine the results.

.SH USAGE
.sp
.LP
Additional calls to \fBmonitor()\fR after \fBmain()\fR has been called and before \fBexit()\fR has been called will add to the function-call count capacity, but such calls will also replace and restart the \fBprofil()\fR histogram computation.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBprofil\fR(2), \fBend\fR(3C), \fBattributes\fR(5), \fBprof\fR(5)