SPROFIL(2)SPROFIL(2)NAMEsprofil - 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);
DESCRIPTIONsprofil 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
If successful, sprofil returns 0. Otherwise, a -1 is returned and the
global variable errno is set to indicate the error.
SEE ALSOprofil(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
