monitor

Purpose

     Starts and stops execution profiling.

Library

     Standard C Library (libc.a)

Syntax

     #include <mon.h>

     void monitor (lowpc, highpc, shortbuff, bufsize, nfunc)
         -- or --
     void monitor (0, 0, profbuff, -1, nfunc)

     int (*lowpc) ( ), (*highpc) ( );
     short *shortbuff;
     struct prof *profbuff;
     int bufsize, nfunc;

Description

     The  monitor subroutine  records a  histogram of  period-
     ically sampled  values of the program  counter and counts
     the number of times  certain subroutines are called.  The
     monitor subroutine  is an interface to  the profil system
     call.

     Executable  programs  created  with  cc -p  automatically
     include calls to the monitor subroutine.  You do not need
     to  call  the monitor  subroutine  unless  you want  fine
     control over profiling.

     If the  bufsize parameter  has any  value other  than -1,
     then the  parameters to monitor are  interpreted as shown
     in  the first  syntax  definition.   The lowpc  parameter
     specifies  the  lowest address  to  be  sampled, and  the
     highest address to  be sampled is the  address just below
     highpc.  The lowpc  parameter cannot be 0  when using the
     monitor  subroutine to  begin profiling.   If monitor  is
     called  with  a lowpc  value  of  0, then  monitoring  is
     stopped  and the  results  are written  to  a file  named
     mon.out.

     The shortbuff  parameter points to a  user-supplied array
     of short integers.  The number  of shorts in shortbuff is
     specified by the bufsize parameter.

     The nfunc parameter specifies  the maximum number of sub-
     routines whose  calls are to  be counted.  Only  calls to

     functions compiled with the -p flag of the cc command are
     recorded.

     For the  results to  be significant, especially  for pro-
     grams  with small,  heavily-used  subroutines, specify  a
     buffer that is no more than  a few times smaller than the
     range of locations sampled.

     If  bufsize has  the  value -1,  then  the parameters  to
     monitor  are interpreted  as shown  in the  second syntax
     definition.  In this case, the arguments lowpc and highpc
     are ignored, nfunc retains  the same meaning as described
     above, and  profbuff points  to an  array of  prof struc-
     tures.  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;

     The monitor subroutine ignores the value given in p_scale
     and computes a value for  it.  The p_high members in suc-
     cessive structures  must be  in ascending  sequence.  The
     array of  structures is terminated with  a structure con-
     taining a p_high member set to zero.

     Use the  prof command to  examine the results  after exe-
     cuting your program.

Examples

     1.  To profile  the entire  program except  for floating-
         point operations:

           extern etext;
            . . .
           monitor ((int (*)()) 0x10000000, etext, buf, bufsize, nfunc);

         The identifier etext is  the address immediately fol-
         lowing the  program text.   (See "end,  etext, edata"
         for more information about etext.)

     2.  To  profile the  entire program,  including floating-
         point operations:

           extern etext;
            . . .
           monitor ((int (*)()) 0x800, etext, buf, bufsize, nfunc);

         Note that this samples  many more instructions, which
         decreases the resolution of the histogram.

     3.  To profile an entire  program that includes floating-
         point operations and a shared library:

           extern etext;
           struct prof buf[4|;
            . . .
           buf[0].p_low  = 0x800         /* floating-point text */
           buf[0].p_high = 0x1D108

           buf[1].p_low  = 0x10000000    /* program text        */
           buf[1].p_high = etext

           buf[2].p_low  = 0x40000000    /* shared library text */
           buf[2].p_high = 0x40030D40

           buf[3].p_low  = 0             /* end of array        */
           buf[3].p_high = 0

           monitor(0, 0, buf, -1, nfunc);

         The addresses  shown for the shared  library text may
         differ from  the ones  appropriate for a  program you
         write.

         The end  of the floating-point text  may be different
         on your  system.  To  determine the correct  value to
         use for "buf[0].p_high" in this example, run the fol-
         lowing command:

           nm -x /unix  |  grep _fpend

         This command displays the value of the symbol _fpend,
         which marks the end of the floating-point code in the
         kernel.

     4.  To stop execution monitoring and write the results to
         the file mon.out:

           monitor ((int(*)()) 0);

File

     mon.out

Related Information

     In this book:  "profil" and "end, etext, edata."

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