Commit | Line | Data |
---|---|---|
8e556f67 KM |
1 | .\" Copyright (c) 1980 Regents of the University of California. |
2 | .\" All rights reserved. The Berkeley software License Agreement | |
3 | .\" specifies the terms and conditions for redistribution. | |
4 | .\" | |
5c0bd1c3 | 5 | .\" @(#)moncontrol.3 6.1 (Berkeley) %G% |
8e556f67 | 6 | .\" |
5c0bd1c3 | 7 | .TH MONITOR 3 "" |
8e556f67 KM |
8 | .UC 4 |
9 | .SH NAME | |
4656920c | 10 | monitor, monstartup, moncontrol \- prepare execution profile |
8e556f67 KM |
11 | .SH SYNOPSIS |
12 | .nf | |
13 | .B monitor(lowpc, highpc, buffer, bufsize, nfunc) | |
14 | .B int (*lowpc)(), (*highpc)(); | |
15 | .B short buffer[]; | |
4656920c KM |
16 | .sp |
17 | .B monstartup(lowpc, highpc) | |
18 | .B int (*lowpc)(), (*highpc)(); | |
19 | .sp | |
20 | .B moncontrol(mode) | |
8e556f67 KM |
21 | .fi |
22 | .SH DESCRIPTION | |
4656920c KM |
23 | There are two different forms of monitoring available: |
24 | An executable program created by: | |
25 | .IP " cc \-p . . ." | |
26 | .LP | |
27 | automatically includes calls for the | |
28 | .IR prof (1) | |
29 | monitor and includes an initial call to its start-up routine | |
30 | .I monstartup | |
8e556f67 KM |
31 | with default parameters; |
32 | .I monitor | |
4656920c KM |
33 | need not be called explicitly except to gain fine control over profil |
34 | buffer allocation. | |
35 | An executable program created by: | |
36 | .IP " cc \-pg . . ." | |
37 | .LP | |
38 | automatically includes calls for the | |
39 | .IR gprof (1) | |
40 | monitor. | |
8e556f67 | 41 | .PP |
4656920c KM |
42 | .I Monstartup |
43 | is a high level interface to | |
8e556f67 KM |
44 | .IR profil (2). |
45 | .I Lowpc | |
46 | and | |
47 | .I highpc | |
4656920c | 48 | specify the address range that is to be sampled; the lowest address sampled |
8e556f67 KM |
49 | is that of |
50 | .I lowpc | |
4656920c | 51 | and the highest is just below |
8e556f67 | 52 | .IR highpc . |
4656920c KM |
53 | .I Monstartup |
54 | allocates space using | |
55 | .IR sbrk (2) | |
56 | and passes it to | |
57 | .I monitor | |
58 | (see below) to record a histogram of periodically sampled values of | |
59 | the program counter, and of counts of calls of certain functions, in the buffer. | |
60 | Only calls of functions compiled with the profiling option | |
8e556f67 KM |
61 | .B \-p |
62 | of | |
63 | .IR cc (1) | |
64 | are recorded. | |
8e556f67 | 65 | .PP |
4656920c | 66 | To profile the entire program, it is sufficient to use |
8e556f67 KM |
67 | .PP |
68 | .nf | |
69 | extern etext(); | |
70 | . . . | |
4656920c | 71 | monstartup((int) 2, etext); |
8e556f67 KM |
72 | .fi |
73 | .PP | |
74 | .I Etext | |
4656920c | 75 | lies just above all the program text, see |
8e556f67 KM |
76 | .IR end (3). |
77 | .PP | |
4656920c | 78 | To stop execution monitoring and write the results on the file |
8e556f67 KM |
79 | .I mon.out, |
80 | use | |
81 | .PP | |
82 | monitor(0); | |
83 | .LP | |
84 | then | |
85 | .IR prof (1) | |
4656920c KM |
86 | can be used to examine the results. |
87 | .PP | |
88 | .I Moncontrol | |
89 | is used to selectively control profiling within a program. | |
90 | This works with either | |
91 | .IR prof (1) | |
92 | or | |
93 | .IR gprof (1) | |
94 | type profiling. | |
95 | When the program starts, profiling begins. | |
96 | To stop the collection of histogram ticks and call counts use | |
97 | .IR moncontrol (0); | |
98 | to resume the collection of histogram ticks and call counts use | |
99 | .IR moncontrol (1). | |
100 | This allows the cost of particular operations to be measured. | |
101 | Note that an output file will be produced upon program exit | |
102 | irregardless of the state of | |
103 | .I moncontrol. | |
104 | .PP | |
105 | .I Monitor | |
106 | is a low level interface to | |
107 | .IR profil (2). | |
108 | .I Lowpc | |
109 | and | |
110 | .I highpc | |
111 | are the addresses of two functions; | |
112 | .I buffer | |
113 | is the address of a (user supplied) array of | |
114 | .I bufsize | |
115 | short integers. At most | |
116 | .I nfunc | |
117 | call counts can be kept. | |
118 | For the results to be significant, especially where there are small, heavily | |
119 | used routines, it is suggested that the buffer be no more | |
120 | than a few times smaller than the range of locations sampled. | |
121 | .I Monitor | |
122 | divides the buffer into space to record the histogram | |
123 | of program counter samples over the range | |
124 | .I lowpc | |
125 | to | |
126 | .IR highpc , | |
127 | and space to record call counts of functions compiled with the | |
128 | .B \-p | |
129 | option to | |
130 | .IR cc (1). | |
131 | .PP | |
132 | To profile the entire program, it is sufficient to use | |
133 | .PP | |
134 | .nf | |
135 | extern etext(); | |
136 | . . . | |
137 | monitor((int) 2, etext, buf, bufsize, nfunc); | |
138 | .fi | |
8e556f67 KM |
139 | .SH FILES |
140 | mon.out | |
141 | .SH "SEE ALSO" | |
4656920c | 142 | cc(1), prof(1), gprof(1), profil(2), sbrk(2) |