Return to monitor.3 CVS log

Up to [Power 6/32 Unix Tahoe 4.2BSD] / cci / usr / src / man / man3

Annotation of cci/usr/src/man/man3/monitor.3, revision 1.1.1.1

1.1       root        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)

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.