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 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.


     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
     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 3