profil(2)                                                         profil(2)

NAME
     profil - execution time profile

SYNOPSIS
     #include <unistd.h>

     void profil(unsigned short *buff, sizet bufsiz, int offset,
     unsigned scale);

DESCRIPTION
     profil() provides CPU-use statistics by profiling the amount of CPU
     time expended by a program. profil() generates the statistics by
     creating an execution histogram for a current process. The histogram
     is defined for a specific region of program code to be profiled, and
     the identified region is logically broken up into a set of equal size
     subdivisions, each of which corresponds to a count in the histogram.
     With each clock tick, the current subdivision is identified and its
     corresponding histogram count is incremented. These counts establish a
     relative value for the amount of time being spent in each code subdi-
     vision. The resulting histogram counts for a profiled region and can
     be used to identify those functions that consume a disproportionately
     high percentage of CPU time.

     buff is a buffer of bufsiz bytes in which the histogram counts are
     stored in an array of unsigned short int.

     offset, scale, and bufsiz specify the region to be profiled.

     offset is the start address of the region to be profiled.

     scale is a contraction factor that indicates how much smaller the his-
     togram buffer is than the region to be profiled. That is, scale is
     interpreted as an unsigned 16-bit fixed-point fraction with the
     decimal point implied on the left. Its value is the reciprocal of the
     number of bytes in a subdivision, per byte of histogram buffer. Since
     there are two bytes per histogram counter, the effective ratio of sub-
     division bytes per counter is double the scale.

     -  The maximum value of scale, 0xffff (approximately 1), maps subdivi-
        sions 2 bytes long to each counter.

     -  The minimum value of scale (for which profiling is performed),
        0x0002 (1/32768), maps a subdivision 65536 bytes long to each
        counter.











Page 1                       Reliant UNIX 5.44                Printed 11/98

profil(2)                                                         profil(2)

     -  The default value of scale (currently used by cc -qp), 0x4000, maps
        a subdivision 8 bytes long to each counter.

     The values are used within the kernel as follows: when the process is
     interrupted for a clock tick, the value of offset is subtracted from
     the current value of the program counter, and the remainder is multi-
     plied by scale to derive a result. That result is used as an index
     into the histogram array to locate the cell to be incremented. There-
     fore, the cell count represents the number of times that the process
     was executing code in the subdivision associated with that cell when
     the process was interrupted.

     scale can be computed as (RATIO * 0200000L), where RATIO is the
     desired ratio of bufsiz to profiled region size, and has a value
     between 0 and 1. The closer RATIO is to 1, the higher the resolution
     of the profile information.

     bufsiz can be computed as (sizeofregiontobeprofiled * RATIO).

NOTES
     Profiling is turned off by giving a scale of 0 or 1, and is rendered
     ineffective by giving a bufsiz of 0. Profiling is turned off when an
     exec(2) is executed, but remains on in both child and parent processes
     after a fork(2). Profiling is turned off if a buff update would cause
     a memory fault.

SEE ALSO
     times(2), monitor(3C).


























Page 2                       Reliant UNIX 5.44                Printed 11/98