profil

Purpose

     Starts and stops execution profiling.

Syntax

     #include <mon.h>

     void profil (shortbuff, bufsiz, offset, scale)
         -- or --
     void profil (profbuff, -1, 0, 0)

     short *shortbuff;
     struct prof *profbuff;
     unsigned int bufsiz, offset, scale;

Description

     The profil system call arranges  to record a histogram of
     periodically  sampled  values  of the  calling  process's
     program counter.

     If the  bufsiz parameter has  any value but -1,  then the
     parameters  to profil  are  interpreted as  shown in  the
     first syntax definition.   The shortbuff parameter points
     to an area of memory, and  its length (in bytes) is given
     by the bufsiz parameter.

     After this call, the user's program counter (pc) is exam-
     ined 60 times  a second.  The value of  the offset param-
     eter  is  subtracted  from  the pc,  and  the  result  is
     multiplied by the  value of the scale  parameter.  If the
     resulting  number is  less than   bufsiz / sizeof(short),
     then the  corresponding short inside shortbuff  is incre-
     mented.

     The least significant 16 bits  of the scale parameter are
     interpreted as  an unsigned, fixed-point fraction  with a
     binary point at  the left.  The most  significant 16 bits
     of scale are ignored.  For example:

                    Octal    Hex     Meaning

                    0177777  0xFFFF  Maps approximately each pair of bytes in
                                     the instruction space  to a unique short
                                     in shortbuff.
                    077777   0x7FFF  Maps approximately every four bytes to a
                                     short in shortbuff.
                    01       0x0001  Maps all instructions to the first short
                                     in  shortbuff,   producing  a  noninter-
                                     rupting core clock.

                    Octal    Hex     Meaning

                    0        0x0000  Turns profiling off.

Mapping  each  byte of  the  instruction  space  to  an individual  short  in
shortbuff is not possible.

If the  second parameter (bufsize) has  the value -1, then  the parameters to
profil are  interpreted as shown  in the  second syntax definition.   In this
case, the offset and scale parameters  are ignored, and profbuff points to an
array of prof structures.  The prof  structure is defined in the mon.h header
file, and it contains the following members:

     daddr_t  p_low;
     daddr_t  p_high;
     short_t  *p_buff;
     int_t    p_bufsize;
     int_t    p_scale;

If the p_scale member has the value -1, then 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 termi-
nated with a structure containing a p_high member set to zero.

Profiling is turned off:

o   If the value of the scale parameter is 0.
o   When an exec system call is executed
o   If updating the buffer pointed to  by the shortbuff or profbuff parameter
    would cause a memory fault.

Profiling is  rendered ineffective by  giving a value  of "0" for  the bufsiz
parameter.

Profiling remains on in both the child process and the parent process after a
fork system call.

Related Information

In this book:  "exec:  execl, execv, execle, execve, execlp, execvp," "fork,"
and "monitor."

The cc and prof commands in AIX Operating System Commands Reference.