1profil(2)                        System Calls                        profil(2)
2
3
4

NAME

6       profil - execution time profile
7

SYNOPSIS

9       #include <unistd.h>
10
11       void profil(unsigned short *buff, unsigned int bufsiz, unsigned int offset,
12            unsigned int scale);
13
14

DESCRIPTION

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
29
30       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
35
36       The  offset, scale, and  bufsiz arguments specify the region to be pro‐
37       filed.
38
39
40       The offset argument is effectively the start address of the  region  to
41       be profiled.
42
43
44       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
52
53       The values of scale are as follows:
54
55           o      the  maximum value of  scale, 0xffff (approximately 1), maps
56                  subdivisions 2 bytes long to each counter.
57
58           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
62           o      the default value of  scale (currently  used  by   cc  -qp),
63                  0x4000, maps subdivisions 8 bytes long to each counter.
64
65
66       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
75
76       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
81
82       The value of bufsiz can be computed as (size_of_region_to_be_profiled *
83       RATIO).
84
85
86       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

USAGE

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

SEE ALSO

97       exec(2), fork(2), pcsample(2), times(2), monitor(3C), prof(5)
98

NOTES

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.
112
113
114
115SunOS 5.11                        12 Nov 2001                        profil(2)
Impressum