SPROFIL(2)                                                          SPROFIL(2)



NAME
     sprofil - execution time profile for disjoint text spaces

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

     int sprofil(struct prof *profp, int profcnt,

                 struct timeval *tvp, unsigned int flags);


DESCRIPTION

     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 PROFUSHORT and PROFUINT, 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 PROFUSHORT and a pr_scale of

     0x8000, or PROFUINT and a pr_scale of 0x10000.  Note that a 1-1 mapping

     of PROFUINT counters consumes twice as much space as for PROFUSHORT

     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 PROFFAST 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 restrictfastprof
     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
                  PROFILMAX.

     [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
                  (PROFUSHORT or PROFUINT).

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

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

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

NOTES
     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)























































                                                                        Page 3