1monitor(3C) Standard C Library Functions monitor(3C)
2
3
4
6 monitor - prepare process execution profile
7
9 #include <mon.h>
10
11 void monitor(int (*lowpc(), int (*highpc)(), WORD *buffer, size_t bufsize,
12 size_t nfunc);
13
14
16 The monitor() function is an interface to the profil(2) function and is
17 called automatically with default parameters by any program created by
18 the cc utility with the -p option specified. Except to establish fur‐
19 ther control over profiling activity, it is not necessary to explicitly
20 call monitor().
21
22
23 When used, monitor() is called at least at the beginning and the end of
24 a program. The first call to monitor() initiates the recording of two
25 different kinds of execution-profile information: execution-time dis‐
26 tribution and function call count. Execution-time distribution data is
27 generated by profil() and the function call counts are generated by
28 code supplied to the object file (or files) by cc -p. Both types of
29 information are collected as a program executes. The last call to moni‐
30 tor() writes this collected data to the output file mon.out.
31
32
33 The name of the file written by monitor() is controlled by the environ‐
34 ment variable PROFDIR. If PROFDIR does not exist, the file mon.out is
35 created in the current directory. If PROFDIR exists but has no value,
36 monitor() does no profiling and creates no output file. If PROFDIR is
37 dirname, and monitor() is called automatically by compilation with cc
38 -p, the file created is dirname/pid.progname where progname is the name
39 of the program.
40
41
42 The lowpc and highpc arguments are the beginning and ending addresses
43 of the region to be profiled.
44
45
46 The buffer argument is the address of a user-supplied array of WORD
47 (defined in the header <mon.h>). The buffer argument is used by moni‐
48 tor() to store the histogram generated by profil() and the call counts.
49
50
51 The bufsize argument identifies the number of array elements in buffer.
52
53
54 The nfunc argument is the number of call count cells that have been
55 reserved in buffer. Additional call count cells will be allocated auto‐
56 matically as they are needed.
57
58
59 The bufsize argument should be computed using the following formula:
60
61 size_of_buffer =
62 sizeof(struct hdr) +
63 nfunc * sizeof(struct cnt) +
64 ((highpc-lowpc)/BARSIZE) * sizeof(WORD) +
65 sizeof(WORD) − 1 ;
66 bufsize = (size_of_buffer / sizeof(WORD));
67
68
69
70 where:
71
72 o lowpc, highpc, nfunc are the same as the arguments to moni‐
73 tor();
74
75 o BARSIZE is the number of program bytes that correspond to
76 each histogram bar, or cell, of the profil() buffer;
77
78 o the hdr and cnt structures and the type WORD are defined in
79 the header <mon.h>.
80
81
82 The default call to monitor() is as follows:
83
84 monitor (&eprol, &etext, wbuf, wbufsz, 600);
85
86
87
88 where:
89
90 o eprol is the beginning of the user's program when linked
91 with cc -p (see end(3C));
92
93 o etext is the end of the user's program (see end(3C));
94
95 o wbuf is an array of WORD with wbufsz elements;
96
97 o wbufsz is computed using the bufsize formula shown above
98 with BARSIZE of 8;
99
100 o 600 is the number of call count cells that have been
101 reserved in buffer.
102
103
104 These parameter settings establish the computation of an execution-time
105 distribution histogram that uses profil() for the entire program, ini‐
106 tially reserves room for 600 call count cells in buffer, and provides
107 for enough histogram cells to generate significant distribution-mea‐
108 surement results. For more information on the effects of bufsize on
109 execution-distribution measurements, see profil(2).
110
112 Example 1 Example to stop execution monitoring and write the results to
113 a file.
114
115
116 To stop execution monitoring and write the results to a file, use the
117 following:
118
119
120 monitor((int (*)())0, (int (*)())0, (WORD *)0, 0, 0);
121
122
123
124 Use prof to examine the results.
125
126
128 Additional calls to monitor() after main() has been called and before
129 exit() has been called will add to the function-call count capacity,
130 but such calls will also replace and restart the profil() histogram
131 computation.
132
134 See attributes(5) for descriptions of the following attributes:
135
136
137
138
139 ┌─────────────────────────────┬─────────────────────────────┐
140 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
141 ├─────────────────────────────┼─────────────────────────────┤
142 │MT-Level │Safe │
143 └─────────────────────────────┴─────────────────────────────┘
144
146 profil(2), end(3C), attributes(5), prof(5)
147
148
149
150SunOS 5.11 29 Dec 1996 monitor(3C)