4.3BSD-UWisc/man/cat3/monitor.3

MONITOR(3)          UNIX Programmer's Manual           MONITOR(3)



NAME
     monitor, monstartup, moncontrol - prepare execution profile

SYNOPSIS
     monitor(lowpc, highpc, buffer, bufsize, nfunc)
     int (*lowpc)(), (*highpc)();
     short buffer[];

     monstartup(lowpc, highpc)
     int (*lowpc)(), (*highpc)();

     moncontrol(mode)

DESCRIPTION
     There are two different forms of monitoring available: An
     executable program created by:

          cc -p . . .

     automatically includes calls for the _p_r_o_f(1) monitor and
     includes an initial call to its start-up routine _m_o_n_s_t_a_r_t_u_p
     with default parameters; _m_o_n_i_t_o_r need not be called expli-
     citly except to gain fine control over profil buffer alloca-
     tion.  An executable program created by:

          cc -pg . . .

     automatically includes calls for the _g_p_r_o_f(1) monitor.

     _M_o_n_s_t_a_r_t_u_p is a high level interface to _p_r_o_f_i_l(2).  _L_o_w_p_c
     and _h_i_g_h_p_c specify the address range that is to be sampled;
     the lowest address sampled is that of _l_o_w_p_c and the highest
     is just below _h_i_g_h_p_c.  _M_o_n_s_t_a_r_t_u_p allocates space using
     _s_b_r_k(2) and passes it to _m_o_n_i_t_o_r (see below) to record a
     histogram of periodically sampled values of the program
     counter, and of counts of calls of certain functions, in the
     buffer.  Only calls of functions compiled with the profiling
     option -p of _c_c(1) are recorded.

     To profile the entire program, it is sufficient to use

          extern etext();
          . . .
          monstartup((int) 2, etext);

     _E_t_e_x_t lies just above all the program text, see _e_n_d(3).

     To stop execution monitoring and write the results on the
     file _m_o_n._o_u_t, use

          monitor(0);




Printed 12/27/86          May 15, 1985                          1






MONITOR(3)          UNIX Programmer's Manual           MONITOR(3)



     then _p_r_o_f(1) can be used to examine the results.

     _M_o_n_c_o_n_t_r_o_l is used to selectively control profiling within a
     program.  This works with either _p_r_o_f(1) or _g_p_r_o_f(1) type
     profiling.  When the program starts, profiling begins.  To
     stop the collection of histogram ticks and call counts use
     _m_o_n_c_o_n_t_r_o_l(0); to resume the collection of histogram ticks
     and call counts use _m_o_n_c_o_n_t_r_o_l(1).  This allows the cost of
     particular operations to be measured.  Note that an output
     file will be produced upon program exit irregardless of the
     state of _m_o_n_c_o_n_t_r_o_l.

     _M_o_n_i_t_o_r is a low level interface to _p_r_o_f_i_l(2).  _L_o_w_p_c and
     _h_i_g_h_p_c are the addresses of two functions; _b_u_f_f_e_r is the
     address of a (user supplied) array of _b_u_f_s_i_z_e short
     integers.  At most _n_f_u_n_c call counts can be kept.  For the
     results to be significant, especially where there are small,
     heavily used routines, it is suggested that the buffer be no
     more than a few times smaller than the range of locations
     sampled.  _M_o_n_i_t_o_r divides the buffer into space to record
     the histogram of program counter samples over the range
     _l_o_w_p_c to _h_i_g_h_p_c, and space to record call counts of func-
     tions compiled with the -p option to _c_c(1).

     To profile the entire program, it is sufficient to use

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

FILES
     mon.out

SEE ALSO
     cc(1), prof(1), gprof(1), profil(2), sbrk(2)




















Printed 12/27/86          May 15, 1985                          2