pcsample(2) System Calls pcsample(2)NAME
pcsample - program execution time profile
SYNOPSIS
#include <pcsample.h>
long pcsample(uintptr_t samples[], long nsamples);
DESCRIPTION
The pcsample() function provides CPU-use statistics by profiling the amount of CPU time expended by a program.
For profiling dynamically-linked programs and 64-bit programs, it is superior to the profil(2) function, which assumes that the entire pro-
gram is contained in a small, contiguous segment of the address space, divides this segment into "bins", and on each clock tick increments
the counter in the bin where the program is currently executing. With shared libraries creating discontinuous program segments spread
throughout the address space, and with 64-bit address spaces so large that the size of "bins" would be measured in megabytes, the profil()
function is of limited value.
The pcsample() function is passed an array samples containing nsamples pointer-sized elements. During program execution, the kernel samples
the program counter of the process, storing unadulterated values in the array on each clock tick. The kernel stops writing to the array
when it is full, which occurs after nsamples / HZ seconds of process virtual time. The HZ value is obtained by invoking the call
sysconf(_SC_CLK_TCK). See sysconf(3C).
The sampling can be stopped by a subsequent call to pcsample() with the nsamples argument set to 0. Like profil(), sampling continues
across a call to fork(2), but is disabled by a call to one of the exec family of functions (see exec(2)). It is also disabled if an update
of the samples[] array causes a memory fault.
RETURN VALUES
The pcsample() function always returns 0 the first time it is called. On subsequent calls, it returns the number of samples that were
stored during the previous invocation. If nsamples is invalid, it returns -1 and sets errno to indicate the error.
ERRORS
The pcsample() function will fail if:
EINVAL The value of nsamples is not valid.
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
+-----------------------------+-----------------------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+-----------------------------+-----------------------------+
|MT-Level |Async-Signal-Safe |
+-----------------------------+-----------------------------+
|Interface Stability |Stable |
+-----------------------------+-----------------------------+
SEE ALSO exec(2), fork(2), profil(2), sysconf(3C), attributes(5)SunOS 5.10 10 Mar 1998 pcsample(2)
Check Out this Related Man Page
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 gener-
ates 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(5)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 pro-
fil() at threads start-up time, and each thread had to be a bound thread. This was cumbersome and did not easily support dynamically turn-
ing profiling on and off. In Solaris 2.6, the profil() system call for multithreaded processes has global impact -- that is, a call to pro-
fil() 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.
SunOS 5.11 12 Nov 2001 profil(2)