SPROFIL(2)							    SPROFIL(2)

NAME    [Toc]    [Back]

     sprofil - execution time profile for disjoint text	spaces

SYNOPSIS    [Toc]    [Back]

     #include <sys/time.h>
     #include <sys/profil.h>

     int sprofil(struct	prof *profp, int profcnt,
		 struct	timeval	*tvp, unsigned int flags);

DESCRIPTION    [Toc]    [Back]

     sprofil provides CPU-use statistics by profiling the amount of CPU	time
     expended by a program in disjoint text spaces.  This is useful if you
     need to profile programs using shared libraries or	profile	an address
     space using different granularities for different sections	of text.
     sprofil generates the statistics by creating an execution histogram for a
     current process.  The histogram is	defined	for a list of regions of
     program code to be	profiled specified by members of the profp array:
     profp[0], profp[1], ..., profp[profcnt-1].

     The prof structure	is defined as
     struct prof {
	     void     *pr_base;	   /* buffer base */
	     unsigned pr_size;	   /* buffer size */
	     __psunsigned_t pr_off;	/* pc offset */
	     unsigned pr_scale;	   /* pc scaling */
     };

     Each prof entry specifies a region	of text	space that needs to be
     profiled, and the fields of the structure take on the same	meaning	as the
     arguments of the profil(2)	system call.

     pr_base is	a buffer of pr_size bytes in which the histogram counts	are
     stored.

     pr_off , pr_scale , and pr_size specify the region	to be profiled.

     pr_off is effectively the start address of	the region to be profiled.

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

     Valid flags values	include	PROF_USHORT and	PROF_UINT, which result	in the
     pr_base field of each prof	entry being treated as a pointer to an array
     of	unsigned short or unsigned int,	respectively.  You achieve a 1-1
     mapping of	instructions to	counters for PROF_USHORT and a pr_scale	of
     0x8000, or	PROF_UINT and a	pr_scale of 0x10000.  Note that	a 1-1 mapping
     of	PROF_UINT counters consumes twice as much space	as for PROF_USHORT
     counters, and should only be used in those	cases where you	expect a 16-
     bit counter to overflow.





									Page 1






SPROFIL(2)							    SPROFIL(2)



     Callers may also specify PROF_FAST	in the flags field. This value will
     provide more accurate profiling by	forcing	the system to take samples
     once every	millisecond. Fast profiling requests can reduce	system
     performance noticably. The	tuneable system	parameter restrict_fastprof
     can be used to disable this feature.

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

     A text region with	the pr_off of 0	and pr_scale of	0x0002 will act	as an
     overflow bin. Any PC 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.

     sprofil can fail with:

     [E2BIG]	  profcnt was less than	or equal to 0, or greater than
		  PROFIL_MAX.

     [EFAULT]	  Either profp or tvp points to	an illegal address.

     [EINVAL]	  The overflow bin is not last in the list of specified
		  regions, or flags does not contain one of the	values
		  (PROF_USHORT or PROF_UINT).

     [EACCES]	  The flags field specified PROF_FAST but the feature has been
		  disabled using the restrict_fastprof tuneable	system
		  parameter or the hardware does not support fast clock	ticks.

RETURN VALUE    [Toc]    [Back]

     If	successful, sprofil returns 0. Otherwise, a -1 is returned and the
     global variable errno is set to indicate the error.

SEE ALSO    [Toc]    [Back]

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

NOTES    [Toc]    [Back]

     Each call to sprofil will disable any profiling enabled by	previous
     sprofil calls.  Profiling is not enabled for a given text region if the
     value for pr_scale	is 0 or	1, and is rendered ineffective by giving a
     bufsiz of 0.  Profiling is	turned off for the specified region of text
     space if a	pr_base	update would cause a memory fault.

     Profiling is turned off when an exec(2) is	executed, but remains on in
     both child	and parent processes after a fork(2) or	a sproc(2). A call to
     profil(2) has the same effect as calling sprofil with just	one member in
     the profp array with the fields profcnt, tvp and flags taking on the
     values of 1, NULL and PROF_USHORT respectively.




									Page 2






SPROFIL(2)							    SPROFIL(2)


									PPPPaaaaggggeeee 3333