MONITOR(3,L) AIX Technical Reference MONITOR(3,L)
-------------------------------------------------------------------------------
monitor, monstartup, moncontrol
PURPOSE
Starts and stops execution profiling.
LIBRARY
Standard C Library (libc.a)
SYNTAX
#include <mon.h>
void monitor (lowpc, highpc, shortbuff, bufsize, nfunc)
- or -
void monitor (lowpc, highpc, profbuff, -1, nfunc)
Note: The lowpc value for the second definition must be nonzero.
int (*lowpc) ( ), (*highpc) ( );
short *shortbuff;
struct prof *profbuff;
int bufsize, nfunc;
int monstartup (lowpc, highpc)
int (*lowpc) ( ), (*highpc) ( );
void moncontrol (mode)
int mode;
DESCRIPTION
The monitor subroutine records a histogram of periodically sampled values of
the program counter and counts the number of times certain subroutines are
called. The monitor subroutine is an interface to the profil system call.
Executable programs created with cc -p automatically include calls to the
monitor subroutine. You do not need to call the monitor subroutine unless you
want fine control over profiling.
If the bufsize parameter has any value other than -1, then the parameters to
monitor are interpreted as shown in the first syntax definition. The lowpc
parameter specifies the lowest address to be sampled, and the highest address
to be sampled is the address just below highpc. The lowpc parameter cannot be
0 when using the monitor subroutine to begin profiling. If monitor is called
with a lowpc value of 0, then monitoring is stopped and the results are written
to a file named mon.out.
Processed November 7, 1990 MONITOR(3,L) 1
MONITOR(3,L) AIX Technical Reference MONITOR(3,L)
The shortbuff parameter points to a user-supplied array of short integers. The
number of shorts in shortbuff is specified by the bufsize parameter.
The nfunc parameter specifies the maximum number of subroutines whose calls are
to be counted. Only calls to functions compiled with the -p flag of the cc
command are recorded.
For the results to be significant, especially for programs with small,
heavily-used subroutines, specify a buffer that is no more than a few times
smaller than the range of locations sampled.
If bufsize has the value -1, then the parameters to monitor are interpreted as
shown in the second syntax definition. In this case, the arguments lowpc and
highpc are ignored, nfunc retains the same meaning as described above, and
profbuff points to an array of prof structures. The prof structure is defined
in the mon.h header file, and it contains the following members:
daddr_t p_low;
daddr_t p_high;
short_t *p_buff;
int_t p_bufsize;
int_t p_scale;
The monitor subroutine ignores the value given in p_scale and computes a value
for it. The p_high members in successive structures must be in ascending
sequence. The array of structures is terminated with a structure containing a
p_high member set to 0.
Use the prof command to examine the results after executing your program.
The monstartup subroutine is a high level interface to profil. The lowpc and
highpc parameters specify the address range that is to be sampled; the lowest
address sampled is that of lowpc and the highest is just below highpc. The
monstartup subroutine allocates space using sbrk and passes it to monitor to
record a histogram of periodically sampled values of the program counter, and
of counts of calls to certain functions, in the buffer. Only calls of
functions compiled with the profiling option -p of cc are recorded.
To profile the entire program, it is sufficient to use the following:
extern etext();
...
monstartup((int)2, etext);
The etext parameter points to just above all the program text.
To stop execution monitoring and write the results on the file mon.out, use the
following:
monitor(0);
Then use prof to examine the results.
Processed November 7, 1990 MONITOR(3,L) 2
MONITOR(3,L) AIX Technical Reference MONITOR(3,L)
The moncontrol subroutine is used to selectively control profiling within a
program. This works with either prof or gprof profiling. When the program
starts, profiling begins. This allows the cost of a particular operation to be
measured. Note that an output file is produced upon program exit, regardless
of the state of moncontrol.
EXAMPLES
1. To profile the entire AIX PS/2 program:
extern etext;
...
monitor ((int (*)()) 0x00400000, etext, buf, bufsize, nfunc);
The identifier etext is the address immediately following the program text.
(See "end, etext, edata" for more information about etext.)
2. To profile the entire AIX System/370 program:
extern etext;
...
monitor ((int (*)()) 0x00010000, etext, buf, bufsize, nfunc);
The identifier etext is the address immediately following the program text.
(See "end, etext, edata" for more information about etext.)
3. To profile an entire AIX PS/2 program that includes a shared library:
extern etext;
struct prof buf[3];
...
buf[0].p_low = 0x00400000 /* program text */
buf[0].p_high = etext
buf[1].p_low = 0xD0000000 /* shared library text */
buf[1].p_high = 0xD0030D40
buf[2].p_low = 0 /* end of array */
buf[2].p_high = 0
monitor((int (*)())0, (int (*)())0, buf, -1, nfunc);
The addresses shown for the shared library text may differ from the ones
appropriate for a program you write.
4. To stop execution monitoring and write the results to the file mon.out:
monitor ((int (*)()) 0, (int (*)())0, (short *)0, 0, 0);
Processed November 7, 1990 MONITOR(3,L) 3
MONITOR(3,L) AIX Technical Reference MONITOR(3,L)
FILE
mon.out
RELATED INFORMATION
In this book: "end, etext, edata" and "profil."
The cc and prof commands in AIX Operating System Commands Reference.
Processed November 7, 1990 MONITOR(3,L) 4