sprofil(2)							System Calls Manual							sprofil(2)

NAME

       sprofil() - execution time profile for disjointed text spaces

SYNOPSIS

DESCRIPTION

       controls profiling, by which the system maintains estimates of the amount of time the calling program spends executing at various places in
       its address space. It differs from its predecessor in that it allows simultaneous profiling of many disjointed regions of memory.

       profp must point to an ordered array of structures.

       The structure is defined as:

       profcnt specifies the number of structures in the profp array.  If profcnt is 0, profiling is disabled.

       If non-NULL, tvp points to a which on return contains the time value corresponding to one clock tick.

       The only valid flags values are and The flags parameter must be set to one of these values.

       When profiling is enabled, each thread's program counter is examined each clock tick times per second), and the system searches	the  profp
       array for a region that includes

       Each structure is interpreted as follows:

	      pr_base  must  point  to	an  area of memory whose length (in bytes) is given by pr_size.  This memory must not be modified or freed
	      while profiling is enabled.  This memory is treated as an array of 2, 4 or 8-byte elements corresponding to the or flag specified by
	      the flags parameter.

	      pr_size must be a non-zero multiple of the element size.

	      pr_offset  is the start address of the region to be profiled.  Note that it is always interpreted as a text address and never as the
	      address of a function descriptor.

	      pr_scale is interpreted as an unsigned, fixed-point value with sixteen bits to the right of the binary point.

       The value falls within a region if (offset=((pr_offset) * pr_scale) / 65536) < pr_size.

       If a matching region is found, offset is rounded down to a 2, 4 or 8-byte boundary corresponding to the element size specified by the flags
       parameter.  The element at pr_base + offset is incremented by 1, unless that would result in overflow.

       If the calculation above results in an invalid address, profiling is silently disabled.

       The profp array must be sorted in ascending order by pr_offset value.  The profiling regions must not overlap.

       If a pr_scale field is set to 0 or 1, the corresponding array entry is ignored.

       The  last  entry in the profp array is special.	If its pr_offset field is set to 0 and its pr_scale field is set to 2, it is treated as an
       overflow descriptor.  In this case, its pr_size field must be set to the size of one element.  If the value did not fall within	the  range
       of  one	of  the preceding descriptors, the single element specified by the pr_base field is incremented, unless that would result in over-
       flow.

       Each call to disables profiling if it was enabled and then enables profiling of the regions specified by the array entries.

       Due to variations in instruction length on different architectures, the pr_scale setting results in different entry-to-instruction  ratios.
       The  following  tables  show the number of instructions that map into each element of the array that pr_base points to based on instruction
       size, pr_scale and flags.

       On PA-RISC machines, instructions are 4 bytes each.

						    +-------+---------------------------------------+
						    |Scale  | PROF_USHORT   PROF_UINT	PROF_UINT64 |
						    +-------+---------------------------------------+
						    |	  2 |  16384	     32768	   65536    |
						    |	  4 |	8192	     16384	   32768    |
						    |	  8 |	4096	      8192	   16384    |
						    |	 16 |	2048	      4096	    8192    |
						    |	 32 |	1024	      2048	    4096    |
						    |	 64 |	 512	      1024	    2048    |
						    |	128 |	 256	       512	    1024    |
						    |	256 |	 128	       256	     512    |
						    |	512 |	  64	       128	     256    |
						    |  1024 |	  32		64	     128    |
						    |  2048 |	  16		32	      64    |
						    |  4096 |	   8		16	      32    |
						    |  8192 |	   4		 8	      16    |
						    | 16384 |	   2		 4	       8    |
						    | 32768 |	   1		 2	       4    |
						    | 65536 |	   0.5		 1	       2    |
						    |131072 |	   0.25 	 0.5	       1    |
						    +-------+---------------------------------------+
       On Itanium-based machines, pc points to a 16-byte bundle containing three instructions.	It is not possible to profile individual  instruc-
       tions.

						     +------+---------------------------------------+
						     |Scale | PROF_USHORT   PROF_UINT	PROF_UINT64 |
						     +------+---------------------------------------+
						     |	  2 |	4096	     8192	   16384    |
						     |	  4 |	2048	     4096	    8192    |
						     |	  8 |	1024	     2048	    4096    |
						     |	 16 |	 512	     1024	    2048    |
						     |	 32 |	 256	      512	    1024    |
						     |	 64 |	 128	      256	     512    |
						     |	128 |	  64	      128	     256    |
						     |	256 |	  32	       64	     128    |
						     |	512 |	  16	       32	      64    |
						     | 1024 |	   8	       16	      32    |
						     | 2048 |	   4		8	      16    |
						     | 4096 |	   2		4	       8    |
						     | 8192 |	   1		2	       4    |
						     |16384 |	   0.5		1	       2    |
						     |32768 |	   0.25 	0.5	       1    |
						     +------+---------------------------------------+
       Note that a 1-1 mapping of counters consumes twice as much space as for counters, and should only be used in those cases where you expect a
       16-bit counter to overflow.  Likewise, a 1-1 mapping of counters consumes twice as much space as for counters, and should only be  used	in
       those cases where you expect a 32-bit counter to overflow.

       The  results of specifying a pr_scale that corresponds to an instruction-to-profiling element ratio smaller than 1-1 mapping produces unde-
       fined behavior.

       If overlapping text regions are specified, then the pr_base associated with the largest offset less than the value of the  program  counter
       gets incremented.  If more than one text region has the same offset, the first one is chosen.

       A  text	region	with  the  pr_offset of 0 and pr_scale of 0x0002 acts as an overflow bin.  Any value not previously matched or outside the
       regions of text space specified is considered to match this text region and the first counter of the specified pr_base is incremented.	If
       specified, such an overflow bin should always be last in the list of specified regions.

   Notes
       Profiling is turned off when an is executed, but remains on in both child and parent processes after a

       A call to has the same effect as calling with just one member in the profp array with the fields profcnt, tvp, and flags taking on the val-
       ues of and respectively.

RETURN VALUE

       On success, returns 0.  Otherwise, it returns -1 and sets the global variable to indicate the error.

ERRORS

       The function fails if:

       profcnt	      was less than or equal to 0, or greater than

       Either	      profp or tvp points to an illegal address.

       The	      flags parameter is not valid or a pr_size field is zero or greater than (2^46 * pr_scale) / 65536 or is not  a  multiple	of
		      the element size or the overflow descriptor is not last in the list of specified regions or is more than one element long or
		      the regions are not sorted in ascending order by pr_offset or the regions overlap.

SEE ALSO

       prof(1), intro(2), profil(2), times(2), monitor(3C), smonitor(3C).

																	sprofil(2)