sprofil(2)sprofil(2)NAMEsprofil() - execution time profile for disjointed text spaces
SYNOPSISDESCRIPTION
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 in that it allows
simultaneous profiling of many disjointed regions of memory.
profp must point to an ordered array of structures.
The structure is defined as:
profcnt specifies the number of structures in the profp array. If
profcnt is 0, profiling is disabled.
If non-NULL, tvp points to a which on return contains the time value
corresponding to one clock tick.
The only valid flags values are and The flags parameter must be set to
one of these values.
When profiling is enabled, each thread's program counter is examined
each clock tick times per second), and the system searches the profp
array for a region that includes
Each 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 or flag speci‐
fied 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 value falls within a region if (offset=((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 element 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 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 one element. If the value did not fall within the range of
one of the preceding descriptors, the single element specified by the
pr_base field is incremented, unless that would result in overflow.
Each call to disables profiling if it was enabled and then enables pro‐
filing of the regions specified by the array entries.
Due to variations in instruction length on different architectures, the
pr_scale setting results in different entry-to-instruction ratios. The
following tables show the number of instructions that map into each
element of the array that pr_base points to based on instruction size,
pr_scale and flags.
On PA-RISC machines, instructions are 4 bytes each.
┌───────┬───────────────────────────────────────┐
│Scale │ PROF_USHORT PROF_UINT PROF_UINT64 │
├───────┼───────────────────────────────────────┤
│ 2 │ 16384 32768 65536 │
│ 4 │ 8192 16384 32768 │
│ 8 │ 4096 8192 16384 │
│ 16 │ 2048 4096 8192 │
│ 32 │ 1024 2048 4096 │
│ 64 │ 512 1024 2048 │
│ 128 │ 256 512 1024 │
│ 256 │ 128 256 512 │
│ 512 │ 64 128 256 │
│ 1024 │ 32 64 128 │
│ 2048 │ 16 32 64 │
│ 4096 │ 8 16 32 │
│ 8192 │ 4 8 16 │
│ 16384 │ 2 4 8 │
│ 32768 │ 1 2 4 │
│ 65536 │ 0.5 1 2 │
│131072 │ 0.25 0.5 1 │
└───────┴───────────────────────────────────────┘
On Itanium-based machines, pc points to a 16-byte bundle containing
three instructions. It is not possible to profile individual instruc‐
tions.
┌──────┬───────────────────────────────────────┐
│Scale │ PROF_USHORT PROF_UINT PROF_UINT64 │
├──────┼───────────────────────────────────────┤
│ 2 │ 4096 8192 16384 │
│ 4 │ 2048 4096 8192 │
│ 8 │ 1024 2048 4096 │
│ 16 │ 512 1024 2048 │
│ 32 │ 256 512 1024 │
│ 64 │ 128 256 512 │
│ 128 │ 64 128 256 │
│ 256 │ 32 64 128 │
│ 512 │ 16 32 64 │
│ 1024 │ 8 16 32 │
│ 2048 │ 4 8 16 │
│ 4096 │ 2 4 8 │
│ 8192 │ 1 2 4 │
│16384 │ 0.5 1 2 │
│32768 │ 0.25 0.5 1 │
└──────┴───────────────────────────────────────┘
Note that a 1-1 mapping of counters consumes twice as much space as for
counters, and should only be used in those cases where you expect a
16-bit counter to overflow. Likewise, a 1-1 mapping of counters con‐
sumes twice as much space as for counters, and should only be used in
those cases where you expect a 32-bit counter to overflow.
The results of specifying a pr_scale that corresponds to an instruc‐
tion-to-profiling element ratio smaller than 1-1 mapping produces unde‐
fined behavior.
If overlapping text regions are specified, then the pr_base associated
with the largest offset less than the value of the program counter gets
incremented. If more than one text region has the same offset, the
first one is chosen.
A text region with the pr_offset of 0 and pr_scale of 0x0002 acts as an
overflow bin. Any 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.
Notes
Profiling is turned off when an is executed, but remains on in both
child and parent processes after a
A call to has the same effect as calling with just one member in the
profp array with the fields profcnt, tvp, and flags taking on the val‐
ues of and respectively.
RETURN VALUE
On success, returns 0. Otherwise, it returns -1 and sets the global
variable to indicate the error.
ERRORS
The function fails if:
profcnt was less than or equal to 0, or greater than
Either profp or tvp points to an illegal address.
The flags parameter is not valid or a pr_size field is zero
or greater than (2^46 * pr_scale) / 65536 or is not a
multiple of the element size or the overflow descriptor
is not last in the list of specified regions or is more
than one element long or the regions are not sorted in
ascending order by pr_offset or the regions overlap.
SEE ALSOprof(1), intro(2), profil(2), times(2), monitor(3C), smonitor(3C).
sprofil(2)
