1profil(2) System Calls profil(2)
2
6 profil - execution time profile
7
9 #include <unistd.h>
10 void profil(unsigned short *buff, unsigned int bufsiz, unsigned int offset,
12 unsigned int scale);
13
16 The profil() function provides CPU-use statistics by profiling the
17 amount of CPU time expended by a program. The profil() function gener‐
18 ates the statistics by creating an execution histogram for a current
19 process. The histogram is defined for a specific region of program code
20 to be profiled, and the identified region is logically broken up into a
21 set of equal size subdivisions, each of which corresponds to a count in
22 the histogram. With each clock tick, the current subdivision is iden‐
23 tified and its corresponding histogram count is incremented. These
24 counts establish a relative measure of how much time is being spent in
25 each code subdivision. The resulting histogram counts for a profiled
26 region can be used to identify those functions that consume a dispro‐
27 portionately high percentage of CPU time.
28 The buff argument is a buffer of bufsiz bytes in which the histogram
31 counts are stored in an array of unsigned short int. Once one of the
32 counts reaches 32767 (the size of a short int), profiling stops and no
33 more data is collected.
34 The offset, scale, and bufsiz arguments specify the region to be pro‐
37 filed.
38 The offset argument is effectively the start address of the region to
41 be profiled.
42 The scale argument is a contraction factor that indicates how much
45 smaller the histogram buffer is than the region to be profiled. More
46 precisely, scale is interpreted as an unsigned 16-bit fixed-point
47 fraction with the decimal point implied on the left. Its value is the
48 reciprocal of the number of bytes in a subdivision, per byte of his‐
49 togram buffer. Since there are two bytes per histogram counter, the
50 effective ratio of subdivision bytes per counter is one half the scale.
51 The values of scale are as follows:
54 o the maximum value of scale, 0xffff (approximately 1), maps
56 subdivisions 2 bytes long to each counter.
57 o the minimum value of scale (for which profiling is per‐
59 formed), 0x0002 (1/32,768), maps subdivision 65,536 bytes
60 long to each counter.
61 o the default value of scale (currently used by cc -qp),
63 0x4000, maps subdivisions 8 bytes long to each counter.
64 The values are used within the kernel as follows: when the process is
67 interrupted for a clock tick, the value of offset is subtracted from
68 the current value of the program counter (pc), and the remainder is
69 multiplied by scale to derive a result. That result is used as an
70 index into the histogram array to locate the cell to be incremented.
71 Therefore, the cell count represents the number of times that the
72 process was executing code in the subdivision associated with that cell
73 when the process was interrupted.
74 The value of scale can be computed as (RATIO * 0200000L), where RATIO
77 is the desired ratio of bufsiz to profiled region size, and has a
78 value between 0 and 1. Qualitatively speaking, the closer RATIO is to
79 1, the higher the resolution of the profile information.
80 The value of bufsiz can be computed as (size_of_region_to_be_profiled *
83 RATIO).
84 Profiling is turned off by giving a scale value of 0 or 1, and is ren‐
87 dered ineffective by giving a bufsiz value of 0. Profiling is turned
88 off when one of the exec family of functions (see exec(2)) is executed,
89 but remains on in both child and parent processes after a fork(2).
90 Profiling is turned off if a buff update would cause a memory fault.
91
93 The pcsample(2) function should be used when profiling dynamically-
94 linked programs and 64-bit programs.
95
97 exec(2), fork(2), pcsample(2), times(2), monitor(3C), prof(5)
98
100 In Solaris releases prior to 2.6, calling profil() in a multithreaded
101 program would impact only the calling LWP; the profile state was not
102 inherited at LWP creation time. To profile a multithreaded program with
103 a global profile buffer, each thread needed to issue a call to profil()
104 at threads start-up time, and each thread had to be a bound thread.
105 This was cumbersome and did not easily support dynamically turning pro‐
106 filing on and off. In Solaris 2.6, the profil() system call for multi‐
107 threaded processes has global impact — that is, a call to profil()
108 impacts all LWPs/threads in the process. This may cause applications
109 that depend on the previous per-LWP semantic to break, but it is
110 expected to improve multithreaded programs that wish to turn profiling
111 on and off dynamically at runtime.
112SunOS 5.11 12 Nov 2001 profil(2)