monitor(3C) monitor(3C)
NAME
monitor - prepare execution profile
SYNOPSIS
#include <mon.h>
void monitor(int (*lowpc)(), int (*highpc)(), WORD *buffer,
sizet bufsize, sizet nfunc);
DESCRIPTION
monitor() is an interface to profil(), and is called automatically
with default parameters by any program created by cc -p. monitor()
only needs to be explicitly called if additional information is
required for the execution-profile.
monitor() is called at least at the beginning and the end of a pro-
gram. The first call to monitor() initiates the recording of two dif-
ferent kinds of execution-profile information: execution-time distri-
bution and function call count. Execution-time distribution data is
generated by profil() and the function call counts are generated by
code supplied to the object file (or files) by the compiler option -p.
The last call to monitor() writes this collected data to the output
file mon.out.
lowpc and highpc are the beginning and ending addresses of the region
to be profiled.
buffer is used by monitor() to store the histogram generated by pro-
fil() and the call counts.
bufsize identifies the number of array elements in buffer.
nfunc is the number of call count cells that have been reserved in
buffer. Additional call count cells will be allocated automatically as
soon as they are needed.
bufsize should be computed using the following (C notation) formula:
sizeofbuffer =
sizeof(struct hdr) +
nfunc * sizeof(struct cnt) +
((highpc-lowpc)/BARSIZE) * sizeof(WORD) +
sizeof(WORD) - 1 ;
bufsize = (sizeofbuffer / sizeof(WORD)) ;
Page 1 Reliant UNIX 5.44 Printed 11/98
monitor(3C) monitor(3C)
where:
- lowpc, highpc, nfunc have the same values as the arguments to moni-
tor();
- BARSIZE is the number of program bytes allocated to each histogram
bar, or cell, of the profil() buffer;
- The hdr and cnt structures and the type WORD are defined in the
header file mon.h.
The standard invocation of monitor() is as follows (C notation):
monitor (&eprol, &etext, wbuf, wbufsz, 600);
where:
- eprol is the beginning of the user's program when compiled with -p;
- etext is the end of the user's program;
- wbuf is an array of WORD with wbufsz elements;
- wbufsz is computed using the bufsize formula shown above with BAR-
SIZE of 8;
- 600 is the number of call count cells that have been reserved in
buffer.
With these parameter settings, an execution-time distribution histo-
gram can be calculated, using profil() for the entire program. Ini-
tially, 600 cells are reserved in buffer, and enough histogram entries
are provided to generate significant distribution-measurement results.
(For more information on the effects of bufsize on execution-
distribution measurements, see profil(2).)
To stop execution monitoring and write the results to a file, use the
following:
monitor((int (*)())0, (int (*)())0, (WORD *)0, 0, 0);
NOTES
Additional calls to monitor() after main() has been called and before
exit() has been called will add to the function-call count capacity.
However, such calls will also replace and restart the profil() histo-
gram computation.
The name of the file written by monitor() is controlled by the envi-
ronment variable PROFDIR. If PROFDIR does not exist, the file mon.out
is created in the current directory. If PROFDIR exists but has no
value, monitor() does no profiling and creates no output file. If
PROFDIR is dirname, and monitor() is called automatically by
Page 2 Reliant UNIX 5.44 Printed 11/98
monitor(3C) monitor(3C)
compilation with -p, the file created is dirname/pid.progname where
progname is the name of the program.
FILES
mon.out
SEE ALSO
cc(1), profil(2).
Page 3 Reliant UNIX 5.44 Printed 11/98