Return to monitor.3 CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / man / man3

Annotation of 43BSDTahoe/man/man3/monitor.3, revision 1.1.1.1

1.1       root        1: .\" Copyright (c) 1980 Regents of the University of California.
                      2: .\" All rights reserved.  The Berkeley software License Agreement
                      3: .\" specifies the terms and conditions for redistribution.
                      4: .\"
                      5: .\"    @(#)monitor.3   6.1 (Berkeley) 5/15/85
                      6: .\"
                      7: .TH MONITOR 3  "May 15, 1985"
                      8: .UC 4
                      9: .SH NAME
                     10: monitor, monstartup, moncontrol \- prepare execution profile
                     11: .SH SYNOPSIS
                     12: .nf
                     13: .B monitor(lowpc, highpc, buffer, bufsize, nfunc)
                     14: .B int (*lowpc)(), (*highpc)();
                     15: .B short buffer[];
                     16: .sp
                     17: .B monstartup(lowpc, highpc)
                     18: .B int (*lowpc)(), (*highpc)();
                     19: .sp
                     20: .B moncontrol(mode)
                     21: .fi
                     22: .SH DESCRIPTION
                     23: There are two different forms of monitoring available:
                     24: An executable program created by:
                     25: .IP  " cc \-p . . ."
                     26: .LP
                     27: automatically includes calls for the 
                     28: .IR prof (1)
                     29: monitor and includes an initial call to its start-up routine
                     30: .I monstartup
                     31: with default parameters;
                     32: .I monitor
                     33: need not be called explicitly except to gain fine control over profil 
                     34: buffer allocation.
                     35: An executable program created by:
                     36: .IP  " cc \-pg . . ."
                     37: .LP
                     38: automatically includes calls for the
                     39: .IR gprof (1)
                     40: monitor.
                     41: .PP
                     42: .I Monstartup
                     43: is a high level interface to
                     44: .IR profil (2).
                     45: .I Lowpc
                     46: and
                     47: .I highpc
                     48: specify the address range that is to be sampled; the lowest address sampled
                     49: is that of
                     50: .I lowpc
                     51: and the highest is just below
                     52: .IR highpc .
                     53: .I Monstartup
                     54: allocates space using 
                     55: .IR sbrk (2)
                     56: and passes it to
                     57: .I monitor
                     58: (see below) to record a histogram of periodically sampled values of
                     59: the program counter, and of counts of calls of certain functions, in the buffer.
                     60: Only calls of functions compiled with the profiling option
                     61: .B \-p
                     62: of
                     63: .IR cc (1)
                     64: are recorded.
                     65: .PP
                     66: To profile the entire program, it is sufficient to use
                     67: .PP
                     68: .nf
                     69:        extern etext();
                     70:        . . .
                     71:        monstartup((int) 2, etext);
                     72: .fi
                     73: .PP
                     74: .I Etext
                     75: lies just above all the program text, see
                     76: .IR end (3).
                     77: .PP
                     78: To stop execution monitoring and write the results on the file
                     79: .I mon.out,
                     80: use
                     81: .PP
                     82:        monitor(0);
                     83: .LP
                     84: then
                     85: .IR prof (1)
                     86: can be used to examine the results.
                     87: .PP
                     88: .I Moncontrol
                     89: is used to selectively control profiling within a program.
                     90: This works with either 
                     91: .IR prof (1)
                     92: or
                     93: .IR gprof (1)
                     94: type profiling.
                     95: When the program starts, profiling begins.
                     96: To stop the collection of histogram ticks and call counts use
                     97: .IR moncontrol (0);
                     98: to resume the collection of histogram ticks and call counts use
                     99: .IR moncontrol (1).
                    100: This allows the cost of particular operations to be measured.
                    101: Note that an output file will be produced upon program exit
                    102: irregardless of the state of 
                    103: .I moncontrol.
                    104: .PP
                    105: .I Monitor
                    106: is a low level interface to
                    107: .IR profil (2).
                    108: .I Lowpc
                    109: and
                    110: .I highpc
                    111: are the addresses of two functions;
                    112: .I buffer
                    113: is the address of a (user supplied) array of
                    114: .I bufsize
                    115: short integers.  At most
                    116: .I nfunc
                    117: call counts can be kept.
                    118: For the results to be significant, especially where there are small, heavily
                    119: used routines, it is suggested that the buffer be no more
                    120: than a few times smaller than the range of locations sampled.
                    121: .I Monitor
                    122: divides the buffer into space to record the histogram
                    123: of program counter samples over the range
                    124: .I lowpc
                    125: to
                    126: .IR highpc ,
                    127: and space to record call counts of functions compiled with the 
                    128: .B \-p
                    129: option to
                    130: .IR cc (1).
                    131: .PP
                    132: To profile the entire program, it is sufficient to use
                    133: .PP
                    134: .nf
                    135:        extern etext();
                    136:        . . .
                    137:        monitor((int) 2, etext, buf, bufsize, nfunc);
                    138: .fi
                    139: .SH FILES
                    140: mon.out
                    141: .SH "SEE ALSO"
                    142: 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.