profil Subroutine

Purpose

Starts and stops program address sampling for execution profiling.

Library

Standard C Library (libc.a)

Syntax

#include <mon.h>

void profil ( ShortBuffer, BufferSize, Offset, Scale) OR void profil ( ProfBuffer, -1, 0, 0)

unsigned short *ShortBuffer; struct prof *ProfBuffer; unsigned int Buffersize, Scale; unsigned long Offset;

Description

The profil subroutine arranges to record a histogram of periodically sampled values of the calling process program counter. If BufferSize is not -1:

If the value of the BufferSize parameter is -1:

If the p_scale member has the value of -1, a value for it is computed based on p_low, p_high, and p_bufsize; otherwise p_scale is interpreted like the scale argument in the first synopsis. The p_high members in successive structures must be in ascending sequence. The array of structures is ended with a structure containing a p_high member set to 0; all other fields in this last structure are ignored.

The p_buff buffer pointers in the array of prof structures must point into a single contiguous buffer space.

In every case:

Parameters

Item Description
ShortBuffer Points to an area of memory in the user address space. Its length (in bytes) is given by the BufferSize parameter.
BufferSize Specifies the length (in bytes) of the buffer.
Offset Specifies the delta of program counter start and buffer; for example, a 0 Offset implies that text begins at 0. If the user wants to use the entry point of a routine for the Offset parameter, the syntax of the parameter is as follows:

*(long *)RoutineName

Scale Specifies the mapping factor between the program counter and ShortBuffer.
ProfBuffer Points to an array of prof structures.

Return Values

The profil subroutine always returns a value of 0. Otherwise, the errno global variable is set to indicate the error.

Error Codes

The profil subroutine is unsuccessful if one or both of the following are true:

Item Description
EFAULT The address specified by the ShortBuffer or ProfBuffer parameters is not valid, or the address specified by a p_buff field is not valid. EFAULT can also occur if there are not sufficient resources to pin the profiling buffer in real storage.
EINVAL The p_high fields in the prof structure specified by the ProfBuffer parameter are not in ascending order.