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

FreeBSD Manual Pages


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

       pcsample	- program execution time profile

       #include	<pcsample.h>

       long pcsample(uintptr_t samples[], long nsamples);

       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 sam-
       ples[] array causes a memory fault.

       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.

       The pcsample() function will fail if:

       EINVAL	       The value of nsamples is	not valid.

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |MT-Level		     |Async-Signal-Safe		   |
       |Interface Stability	     |Stable			   |

       exec(2),	fork(2), profil(2), sysconf(3C), attributes(5)

SunOS 5.10			  10 Mar 1998			   pcsample(2)


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

home | help