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