MONITOR(3)                                                          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 parame‐
       ters; _m_o_n_i_t_o_r need not be called explicitly except to gain fine control
       over profil buffer allocation.  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 pro‐
       gram 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);

       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 sup‐
       plied) 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  pro‐
       gram  counter  samples  over  the  range  _l_o_w_p_c to _h_i_g_h_p_c, and space to
       record call counts of functions 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)



4th Berkeley Distribution        May 15, 1985                       MONITOR(3)