PROFIL(2) System Calls PROFIL(2)

NAME

profil - execution time profile

SYNOPSIS

#include <unistd.h>

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

DESCRIPTION

The profil() function provides CPU-use statistics by profiling the amount
of CPU time expended by a program. The profil() function 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 measure of how much time is being spent in each code
subdivision. The resulting histogram counts for a profiled region can be
used to identify those functions that consume a disproportionately high
percentage of CPU time.


The buff argument is a buffer of bufsiz bytes in which the histogram
counts are stored in an array of unsigned short int. Once one of the
counts reaches 32767 (the size of a short int), profiling stops and no
more data is collected.


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


The offset argument is effectively the start address of the region to be
profiled.


The scale argument is a contraction factor that indicates how much
smaller the histogram buffer is than the region to be profiled. More
precisely, 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 subdivision bytes per counter is one half the scale.


The values of scale are as follows:

o the maximum value of scale, 0xffff (approximately 1), maps
subdivisions 2 bytes long to each counter.

o the minimum value of scale (for which profiling is
performed), 0x0002 (1/32,768), maps subdivision 65,536 bytes
long to each counter.

o the default value of scale (currently used by cc -qp),
0x4000, maps subdivisions 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 (pc), and the remainder is
multiplied by scale to derive a result. That result is used as an index
into the histogram array to locate the cell to be incremented. Therefore,
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.


The value of 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. Qualitatively speaking, the closer RATIO is to 1, the
higher the resolution of the profile information.


The value of bufsiz can be computed as (size_of_region_to_be_profiled *
RATIO).


Profiling is turned off by giving a scale value of 0 or 1, and is
rendered ineffective by giving a bufsiz value of 0. Profiling is turned
off when one of the exec family of functions (see 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.

USAGE

The pcsample(2) function should be used when profiling dynamically-linked
programs and 64-bit programs.

SEE ALSO

exec(2), fork(2), pcsample(2), times(2), monitor(3C), prof(7)

NOTES

In Solaris releases prior to 2.6, calling profil() in a multithreaded
program would impact only the calling LWP; the profile state was not
inherited at LWP creation time. To profile a multithreaded program with a
global profile buffer, each thread needed to issue a call to profil() at
threads start-up time, and each thread had to be a bound thread. This was
cumbersome and did not easily support dynamically turning profiling on
and off. In Solaris 2.6, the profil() system call for multithreaded
processes has global impact -- that is, a call to profil() impacts all
LWPs/threads in the process. This may cause applications that depend on
the previous per-LWP semantic to break, but it is expected to improve
multithreaded programs that wish to turn profiling on and off dynamically
at runtime.

November 12, 2001 PROFIL(2)