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     ! 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.