Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
profil(2)			 System	Calls			     profil(2)

       profil -	execution time profile

       #include	<unistd.h>

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

       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	 iden-
       tified  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  dispro-
       portionately 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  pro-

       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  his-
       togram  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	subdi-
	    visions 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

	 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 *

       Profiling is turned off by giving a scale value of 0 or 1, and is  ren-
       dered  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.

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

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

       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 pro-
       filing  on and off. In Solaris 2.6, the profil()	system call for	multi-
       threaded	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.

SunOS 5.10			  12 Nov 2001			     profil(2)


Want to link to this manual page? Use this URL:

home | help