monitor(3c) - osol9

1monitor(3C)              Standard C Library Functions              monitor(3C)
2
3
4

NAME

6       monitor - prepare process execution profile
7

SYNOPSIS

9       #include <mon.h>
10
11       void monitor(int (*lowpc(), int (*highpc)(), WORD *buffer, size_t bufsize,
12            size_t nfunc);
13
14

DESCRIPTION

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

EXAMPLES

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

USAGE

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

ATTRIBUTES

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

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

USAGE

ATTRIBUTES

SEE ALSO