moncontrol(3) - bsd211

1MONITOR(3)                 Library Functions Manual                 MONITOR(3)
2
3
4

NAME

6       monitor, monstartup, moncontrol - prepare execution profile
7

SYNOPSIS

9       monitor(lowpc, highpc, buffer, bufsize, nfunc)
10       int (*lowpc)(), (*highpc)();
11       short buffer[];
12
13       monstartup(lowpc, highpc)
14       int (*lowpc)(), (*highpc)();
15
16       moncontrol(mode)
17

DESCRIPTION

19       There  are  two  different forms of monitoring available: An executable
20       program created by:
21
22            cc -p . . .
23
24       automatically includes calls for the prof(1) monitor  and  includes  an
25       initial  call  to  its start-up routine monstartup with default parame‐
26       ters; monitor need not be called explicitly except to gain fine control
27       over profil buffer allocation.  An executable program created by:
28
29            cc -pg . . .
30
31       automatically includes calls for the gprof(1) monitor.
32
33       Monstartup  is  a  high level interface to profil(2).  Lowpc and highpc
34       specify the address range that is to be  sampled;  the  lowest  address
35       sampled  is  that  of lowpc and the highest is just below highpc.  Mon‐
36       startup allocates space using sbrk(2) and passes  it  to  monitor  (see
37       below) to record a histogram of periodically sampled values of the pro‐
38       gram counter, and of counts of calls of certain functions, in the  buf‐
39       fer.   Only calls of functions compiled with the profiling option -p of
40       cc(1) are recorded.
41
42       To profile the entire program, it is sufficient to use
43
44            extern etext();
45            . . .
46            monstartup((int) 2, etext);
47
48       Etext lies just above all the program text, see end(3).
49
50       To stop execution monitoring and write the results on the file mon.out,
51       use
52
53            monitor(0);
54
55       then prof(1) can be used to examine the results.
56
57       Moncontrol  is  used to selectively control profiling within a program.
58       This works with either prof(1) or gprof(1) type  profiling.   When  the
59       program  starts, profiling begins.  To stop the collection of histogram
60       ticks and call counts use moncontrol(0); to resume  the  collection  of
61       histogram  ticks  and  call  counts use moncontrol(1).  This allows the
62       cost of particular operations to be measured.  Note that an output file
63       will be produced upon program exit irregardless of the state of moncon‐
64       trol.
65
66       Monitor is a low level interface to profil(2).  Lowpc  and  highpc  are
67       the  addresses  of two functions; buffer is the address of a (user sup‐
68       plied) array of bufsize short integers.  At most nfunc call counts  can
69       be kept.  For the results to be significant, especially where there are
70       small, heavily used routines, it is suggested that  the  buffer  be  no
71       more  than  a  few  times  smaller than the range of locations sampled.
72       Monitor divides the buffer into space to record the histogram  of  pro‐
73       gram  counter  samples  over  the  range  lowpc to highpc, and space to
74       record call counts of functions compiled with the -p option to cc(1).
75
76       To profile the entire program, it is sufficient to use
77
78            extern etext();
79            . . .
80            monitor((int) 2, etext, buf, bufsize, nfunc);
81

FILES

83       mon.out
84

NAME

SYNOPSIS

DESCRIPTION

FILES

SEE ALSO