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