190 lines
4.2 KiB
Groff
190 lines
4.2 KiB
Groff
.\" @(#)monitor.3 1.1 94/10/31 SMI; from UCB 4.2
|
|
.TH MONITOR 3 "18 February 1988"
|
|
.SH NAME
|
|
monitor, monstartup, moncontrol \- prepare execution profile
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <a.out.h>
|
|
.LP
|
|
.B monitor(lowpc, highpc, buffer, bufsize, nfunc)
|
|
.B int (*lowpc)(\|), (*highpc)(\|);
|
|
.B short buffer[\|];
|
|
.LP
|
|
.B monstartup(lowpc, highpc)
|
|
.B int (*lowpc)(\|), (*highpc)(\|);
|
|
.LP
|
|
.B moncontrol(mode)
|
|
.fi
|
|
.IX "monitor()" "" "\fLmonitor()\fP \(em make execution profile"
|
|
.IX "monstartup()" "" "\fLmonstartup()\fP \(em make execution profile"
|
|
.IX "moncontrol()" "" "\fLmoncontrol()\fP \(em make execution profile"
|
|
.IX "prepare execution profile" "monitor()" "" "\fLmonitor()\fP \(em make execution profile"
|
|
.IX "prepare execution profile" "monstartup()" "" "\fLmonstartup()\fP \(em make execution profile"
|
|
.IX "prepare execution profile" "moncontrol()" "" "\fLmoncontrol()\fP \(em make execution profile"
|
|
.IX "execution profile, prepare \(em \fLmonitor()\fR"
|
|
.IX "profile, execution \(em \fLmonitor()\fR"
|
|
.SH DESCRIPTION
|
|
.LP
|
|
There are two different forms of monitoring available.
|
|
An executable program created by
|
|
.RB ` "cc \-p" '
|
|
automatically includes calls for the
|
|
.BR prof (1)
|
|
monitor, and includes an initial call
|
|
with default parameters to its start-up routine
|
|
.BR monstartup .
|
|
In this case,
|
|
.B monitor(\|)
|
|
need not be called explicitly, except to
|
|
gain fine control over
|
|
.BR profil (2)
|
|
buffer allocation. An executable program created by
|
|
.RB ` "cc \-pg" '
|
|
automatically includes calls for the
|
|
.BR gprof (1)
|
|
monitor.
|
|
.LP
|
|
.B monstartup(\|)
|
|
is a high-level interface to
|
|
.BR profil (2).
|
|
.I lowpc
|
|
and
|
|
.I highpc
|
|
specify the address range that is to be
|
|
sampled; the lowest address
|
|
sampled is that of
|
|
.I lowpc
|
|
and the highest is just below
|
|
.IR highpc .
|
|
.B monstartup(\|)
|
|
allocates space using
|
|
.B sbrk
|
|
(see
|
|
.BR brk (2))
|
|
and passes it to
|
|
.B monitor(\|)
|
|
(as described below) to record a histogram of
|
|
program-counter values,
|
|
and calls to certain functions.
|
|
Only calls to functions compiled with
|
|
.RB ` "cc \-p" '
|
|
are recorded.
|
|
.LP
|
|
On Sun-2, Sun-3, and Sun-4 systems, an entire program can be profiled with:
|
|
.RS
|
|
.LP
|
|
.nf
|
|
.B extern etext(\|);
|
|
\&.\|.\|.
|
|
.B monstartup(\s-1N_TXTOFF\s0(0), etext);
|
|
.fi
|
|
.RE
|
|
.LP
|
|
On Sun386i systems, the equivalent code sequence is:
|
|
.RS
|
|
.LP
|
|
.nf
|
|
.B extern etext(\|);
|
|
.B extern _start(\|);
|
|
\&.\|.\|.
|
|
.B monstartup(_start, etext);
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.B etext
|
|
lies just above all the program text, see
|
|
.BR end (3).
|
|
.LP
|
|
To stop execution monitoring and post results to the file
|
|
.BR mon.out ,
|
|
use:
|
|
.IP
|
|
.B monitor(0);
|
|
.LP
|
|
.BR prof (1)
|
|
can then be used to examine the results.
|
|
.LP
|
|
.B moncontrol(\|)
|
|
is used to selectively control profiling
|
|
within a program. This works with both
|
|
.BR prof (1)
|
|
and
|
|
.BR gprof (1).
|
|
Profiling begins when the program starts.
|
|
To stop the collection of profiling statistics, use:
|
|
.IP
|
|
.B moncontrol(\&0)
|
|
.LP
|
|
To resume the collection of statistics, use:
|
|
.IP
|
|
.B moncontrol(\&1)
|
|
.LP
|
|
This allows you to measure the cost of
|
|
particular functions. Note: an output file
|
|
is be produced upon program exit,
|
|
regardless of the state of
|
|
.BR moncontrol .
|
|
.LP
|
|
.B monitor(\|)
|
|
is a low level interface to
|
|
.BR profil (2).
|
|
.I lowpc
|
|
and
|
|
.I highpc
|
|
are the addresses of two functions;
|
|
.I buffer
|
|
is the address of a (user supplied) array of
|
|
.I bufsize
|
|
short integers. At most
|
|
.I nfunc
|
|
call counts can be kept.
|
|
.LP
|
|
For the results to be significant, especially
|
|
where there are small, heavily used routines,
|
|
it is suggested that the buffer be no more than
|
|
a few times smaller than the range of locations sampled.
|
|
.B monitor(\|)
|
|
divides the buffer into space to record the
|
|
histogram of program counter samples over the range
|
|
.I lowpc
|
|
to
|
|
.IR highpc ,
|
|
and space to record call counts of functions
|
|
compiled with the
|
|
.BR "cc \-p" .
|
|
.LP
|
|
To profile the entire program on Sun-2, Sun-3, and Sun-4 systems
|
|
using the low-level interface to
|
|
.BR profil (2),
|
|
it is sufficient to use
|
|
.RS
|
|
.LP
|
|
.nf
|
|
.B extern etext(\|);
|
|
\&.\|.\|.
|
|
.B monitor(\s-1N_TXTOFF\s0(0), etext, buf, bufsize, nfunc);
|
|
.fi
|
|
.RE
|
|
On Sun386i systems, the equivalent calls are:
|
|
.LP
|
|
.RS
|
|
.nf
|
|
.B extern etext(\|);
|
|
.B extern _start(\|);
|
|
\&.\|.\|.
|
|
.B monitor(_start, etext, buf, bufsize, nfunc);
|
|
.fi
|
|
.RE
|
|
.SH FILES
|
|
.PD 0
|
|
.TP
|
|
.B mon.out
|
|
.PD
|
|
.SH "SEE ALSO"
|
|
.BR cc (1V),
|
|
.BR prof (1),
|
|
.BR gprof (1),
|
|
.BR brk (2),
|
|
.BR profil (2),
|
|
.BR end (3)
|