HP-UX Reference (11i v2 03/08) - 2 System Calls (vol 5)

s
sprofil(2) sprofil(2)
NAME
sprofil() - execution time profile for disjointed 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() 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 profil(2) in
that it allows simultaneous profiling of many disjointed regions of memory.
profp must point to an ordered array of
prof structures.
The
prof structure is defined as:
struct prof {
void *pr_base; /* buffer base */
unsigned int pr_size; /* buffer size */
void *pr_offset; /* pc offset */
unsigned int pr_scale; /* pc scaling */
};
profcnt specifies the number of prof structures in the profp array. If profcnt is 0, profiling is dis-
abled.
If non-NULL,
tvp points to a struct timeval which on return contains the time value corresponding
to one clock tick.
The only valid
flags values are PROF_USHORT, PROF_UINT, and PROF_UINT64. The flags
parameter must be set to one of these values.
When profiling is enabled, each thread’s program counter (
pc) is examined each clock tick (CLK_TICK
times per second), and the system searches the profp array for a region that includes pc.
Each
prof 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
PROF_USHORT, PROF_UINT,or
PROF_UINT64 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
pc value falls within a region if ( offset =((pc-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 ele-
ment 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 prof 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
Section 2−−402 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: August 2003