monitor(3)                          CLIX                          monitor(3)



  NAME

    monitor - Prepares an execution profile

  LIBRARY

    Standard C Library (libc.a)

  SYNOPSIS

    #include <mon.h>

    void monitor(
      int (*lowpc)() ,
      int (*highpc)() ,
      WORD *buffer ,
      int bufsize ,
      int nfunc );

  PARAMETERS

    lowpc()    Acts as a boundary of the text to be monitored and is the
               lowest address monitored.  The value of the lowpc() parameter
               must not be 0.

    highpc()   Acts as a boundary of the text to be monitored and is the
               highest address monitored.

    buffer     Is a user-supplied array of bufsize WORDs.  (WORD is defined in
               header file <mon.h>.)

    bufsize    Specifies the number of WORDs in the buffer.

    nfunc      Specifies the maximum number of function calls to be kept.

  DESCRIPTION

    An executable program created by the cc -p command automatically includes
    calls for monitor() with default parameters; monitor() need not be called
    explicitly except to gain fine control over profiling.

    The monitor() function provides an interface to profil().  The monitor()
    function arranges to record a histogram of periodically sampled values of
    the program counter, and of counts of calls to certain functions in the
    buffer.  The lowest address sampled is that of lowpc() and the highest is
    just below highpc().  Only calls of functions compiled with the profiling
    flag -p of the cc command are recorded.

    The -p flag to cc arranges for the compiler to produce code that counts
    the number of times each function is called; also, if link editing occurs,
    it replaces the standard startup function with one that automatically



  2/94 - Intergraph Corporation                                              1

  monitor(3)                          CLIX                          monitor(3)



    calls monitor() at the start and arranges to write out a mon.out file at
    normal object program termination.  An execution profile can then be
    generated by using prof.

    For the results to be significant, especially where there are small,
    heavily used functions, it is suggested that the buffer be no more than a
    few times smaller than the range of locations sampled.

    To profile the entire program, it is sufficient to use these instructions:

    extern etext;
    monitor ((int (*)())2,&etext,buf,bufsize,nfunc);

    The etext variable lies just above all the program text.  See end().

    To stop execution monitoring and write the results, use this instruction:

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

    The prof command can then be used to examine the results.

    The name of the file written by monitor() is controlled by the environment
    variable PROFDIR.  If PROFDIR does not exist, mon.out is created in the
    current directory.  If PROFDIR exists but has no value, monitor() does not
    do any profiling and creates no output file.  Otherwise, the value of
    PROFDIR is used as the name of the directory in which to create the output
    file.  If PROFDIR is dirname, then the file written is
    dirname/pid.mon.out, where pid is the program's process ID.  (When
    monitor() is called automatically by compiling with cc -p, the file
    created is dirname/pid.progname, where progname() is the name of the
    program.)

  EXAMPLES

    In this example, a whole program is monitored (the text of the program is
    not shown, as noted in the text).  Monitoring is then stopped and the
    results are written to stdout.

    #include <mon.h>
    extern extext;
    main()
    {
         /*monitor the whole program */
         monitor ((int (*)())2,&etext,buf,bufsize,nfunc);

         /*program text goes here */

         ...

         /*stop monitoring and write the results */
         monitor ((int(*)())0,0,0,0,0);



  2                                              Intergraph Corporation - 2/94

  monitor(3)                          CLIX                          monitor(3)



    }

    To examine the results of this executable module, use the prof command,
    having this form:

    prof module_name


  FILES

    mon.out   The output file produced, and to be used, as input to the prof
              command.

  CAUTIONS

    The dirname/pid.mon.out form does not work; the dirname/pid.progname form
    (automatically called with cc -p) does work.

    Do not set the value of the lowpc() parameter to 0.

    Only calls of functions compiled with the -p flag of the cc command are
    recorded.  If the PROFDIR environment variable exists but has no value,
    monitor() does no profiling and does not create an output file.

  RETURN VALUES

    Not valid.

  ERRORS

    Could not create or write the monitor() output file.

  RELATED INFORMATION

    Commands:  acc(1), cc(1), prof(1)

    Functions:  profil(2), end(3)

















  2/94 - Intergraph Corporation                                              3