*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> moncontrol (3)              
Title
Content
Arch
Section
 

monitor(3)

Contents


NAME    [Toc]    [Back]

       monitor,  monstartup, moncontrol, monitor_signal - Prepare
       execution profile

SYNOPSIS    [Toc]    [Back]

       #include <stdio.h>

       int monstartup(
               caddr_t lowpc,
               caddr_t highpc ); int moncontrol(
               int mode ); void monitor_signal(
               int signal ); int monitor(
               caddr_t lowpc,
               caddr_t highpc,
               char *buffer,
               size_t bufsiz,
               size_t nfunc ); #include <mon.h>

       int monitor(
               int lowpc,
               0,
               struct monitor_args *argbuf,
               size_t bufsiz,
               unsigned long flags );

LIBRARY    [Toc]    [Back]

       libprof1.a, libprof1_r.a (linked automatically when -p  or
       -pg option is used)

PARAMETERS    [Toc]    [Back]

       Specifies the lower address boundary of a function address
       range. When lowpc is -1, a monitor call is interpreted  as
       a  call  to profile multiple discontiguous address ranges,
       such as those in an executable and its  shared  libraries.
       This  type of monitor call must have a highpc with a value
       of 0 and have the format shown in the second monitor  synopsis
  above.   Specifies  the upper address boundary of a
       function address range. In a call to the monitor function,
       the highpc argument must be 0 when lowpc is -1.  NOTE When
       a program is compiled at a  low  optimization  level,  the
       compiler preserves the ordering of routines established in
       the source program. However, when a program is compiled at
       higher  optimization  levels (with the -O3 or -O4 option),
       the compiler may rearrange the order of its  routines.  If
       you  compile a program that calls monitor or monstartup at
       a high optimization level, the address specified by  lowpc
       could be placed at a higher address than that specified by
       highpc. Subsequently, calls to monitor and monstartup will
       fail  and  no  profiling data will be generated. To verify
       that the lowpc and highpc passed  to  these  routines  are
       correct,  use  the  nm  command  to  check  their assigned
       addresses in the program's  object  file.   Specifies  the
       signal  number for which monitor_signal(3) is the handler.
       Specifies the address of a (user-supplied) array of bufsiz
       short  integers.   This  is  defined  only if the lowpc or
       highpc argument to the monitor() function is not 0 (zero).
       Specifies  the  size of buffer in bytes. This parameter is
       defined only if the lowpc argument to the monitor function
       is not zero. When lowpc is -1, bufsiz specifies the number
       of monitor_args structures in the argbuf  array;  in  this
       case,  the  extended form of the monitor call, as shown in
       the second monitor synopsis above, is used.  This field is
       not  used  and should be set to zero.  Specifies an operation
 mode for the collection of PC samples. Use a value of
       0 (zero) to stop the collection of PC samples. Use a value
       of 1 to resume the collection of  histogram  ticks.   When
       lowpc  is  -1,  specifies  an array of monitor_args structures,
 each describing a single  address  range  in  which
       profiling  is to occur.  Specifies options that modify the
       behavior of a monitor call that profiles multiple disjoint
       address.  This  argument  is  reserved  for future use and
       should be 0.

DESCRIPTION    [Toc]    [Back]

       When an executable program is compiled  for  profiling  by
       using either the -p or -pg option with the cc command, the
       default parameters cause the entire  text  segment  to  be
       profiled.

       For  large  programs,  this may be more than you need. The
       size of the buffer allocated, and the portion of the  program
  profiled,  can  be  controlled by calling either the
       monstartup() or monitor() routine directly from  the  program.
  The  buffer  size  can also be reduced by using the
       -stride option in the PROFFLAGS environment variable  (see
       the Environment Variables section, below).

       The moncontrol() function can be used to turn profiling on
       and off for the process or the thread. The  monitor()  and
       monstartup()  routines contain an implicit moncontrol call
       to turn profiling on. A moncontrol(0) call can be used  to
       turn off sampling, providing user control over when a section
 of code is sampled.

       The profiling support does not profile  shared  libraries,
       by  default,  and  not  at  all for gprof profiling (using
       gcrt0.o instead of mcrt0.o). See the -all  option  in  the
       PROFFLAGS  part  of  the  Environment  Variables  section,
       below.

   The monitor() Function    [Toc]    [Back]
       The monitor() function is a low  level  interface  to  the
       profil()  system call. The lowpc and highpc parameters are
       the addresses of two functions in a program  that  delimit
       the  text  range  to  profile. If the lowpc parameter is 0
       (zero), the monitor() function stops profiling and  writes
       out  the  data  output file mon.out.  The buffer allocated
       must be one-half the size of the text range to be sampled.

       NOTE  The  monitor()  interface, except monitor(0), is not
       supported for gprof profiling. Use only  monstartup()  for
       gprof profiling. Calls to monitor() will return -1 and set
       errno to EINVAL.

       To stop execution monitoring and to have the results written
  to  the  mon.out  or  gmon.out  file  (depending upon
       whether the program was linked with prof  or  gprof),  use
       the following call: monitor(0). Then use the prof or gprof
       command, as appropriate, to examine the results.

       The second form of monitor call allows you to profile multiple
  disjoint  address ranges, such as an executable and
       its shared libraries.  This  form  of  monitor  call  must
       specify  a  lowpc value of -1 and a highpc value of 0. The
       argbuf argument, specifies an array of monitor_args structures,
  each  describing  a  single address range in which
       profiling is to occur. The number of  monitor_args  structures
 in this array is indicated by the bufsiz argument.

       The  fields  of  each  monitor_args  struct  in  the array
       pointed to by argbuf have the same types and  meanings  as
       the arguments in the traditional monitor call, except that
       the buffer field is an array of unsigned ints  instead  of
       an  array  of  chars.  The following are the contents of a
       monitor_args struct:

               struct monitor_args {
                       caddr_t       lowpc;
                       caddr_t       highpc;
                       unsigned int  *buffer;
                       size_t        bufsiz;
                       }

       The elements of the argbuf array are sorted  in  order  of
       decreasing  lowpc  value,  if they are not already in that
       order. It is an error to attempt  to  profile  an  address
       range that is not currently loaded.

       In  a multithreaded program, every thread that calls monitor
 must use the same arguments unless the -threads option
       is set in the PROFFLAGS environment variable.

   The monstartup() Function    [Toc]    [Back]
       The monstartup() function is a high level interface to the
       profil() system call.

       The lowpc and highpc parameters specify the address  range
       that  is to be sampled; the lowest address sampled is that
       of lowpc and the highest is just below highpc.

       The monstartup() function allocates  space  by  using  the
       calloc()  function and passes it to the monitor() function
       to record a histogram of periodically  sampled  values  of
       the program counter.

       When  a  program is linked with -p, a monstartup(0,0) call
       requests to profile, using 32-bit counters, the whole text
       segment  in  all permanently-loaded shared libraries (that
       is, those libraries not  included  in  the  program  by  a
       dlopen(3)  call. When a program is linked with -pg, a monstartup(0,0)
 call requests that  only  the  executable  be
       profiled using 32-bit counters.

       The  monstartup() function uses information requested from
       the loader the first time it is called to determine  which
       libraries  are  loaded and what their text segment address
       ranges are.  Before  starting  to  profile  these  address
       ranges, all existing profiling is stopped.

       The  monstartup()  function allocates counter buffers that
       are arrays of unsigned int, and combines the  samples  for
       two instructions in each counter. The scale and the set of
       text segments profiled can be changed by setting the PROFFLAGS
 environment variable, as for default profiling.

       A  call  to monstartup() affects the profiling of only the
       thread in which the call was made. The PROFFLAGS  -threads
       switch  causes  separate  counters  to  be  used  for each
       thread, resulting in a separate profiling  data  file  for
       each  thread.  If  the  -threads switch is not used, every
       thread that calls monstartup must specify the  same  lowpc
       and highpc.



   The moncontrol() Function    [Toc]    [Back]
       The  moncontrol() function is used in conjunction with the
       monstartup() and monitor() routines to  turn  sampling  on
       and  off during program execution. When a program that has
       been compiled and linked with either the -p or -pg  option
       starts executing, profiling begins. To stop the collection
       of PC samples, use the following function call:

         moncontrol(0);

       To resume the collection of PC samples, use the  following
       function call:

         moncontrol(1);

       This method allows the cost of particular operations to be
       measured. Note that an output file will be  produced  upon
       program  exit  regardless of the state of the moncontrol()
       function.

   The monitor_signal() Function    [Toc]    [Back]
       The monitor_signal() function allows you to  profile  programs
  that do not terminate, such as daemons. To use this
       routine, declare it as a signal handler  in  your  program
       for the signal of your choice (for instance, SIGUSR1), and
       compile the program with the -p option for prof profiling,
       or with -pg for gprof profiling.

       While  the  program executes, send a signal to the program
       from the shell by  using  the  kill(1)  command.  Themonitor_signal()
   routine  is  invoked  when  the  signal  is
       received and then writes  out  the  profiling  data  file,
       [g]mon.out.  If another signal is sent to the process, the
       profiling data file is overwritten. You might want to save
       the  profiling  data  file  between sending signals to the
       process.

       Using sigaction or signal to make monitor_signal the  process-wide
  signal  handler  is  fully  supported  for nonthreaded
 and multithreaded  programs  when  the  PROFFLAGS
       environment variable does not include the -threads option.
       This allows you to create a profiling data  file  for  the
       thread that is running when the signal arrives. This mechanism
 is not recommended when PROFFLAGS includes -threads,
       although  it  may  be  possible in many cases. For certain
       multithreaded processes, delivery of the asynchronous signal
  may cause execution problems. When -threads is specified,
 the recommended approach is to program a  thread  to
       await the signal using sigwait and then tell other threads
       to call monitor_signal.

   Environment Variables    [Toc]    [Back]
       To gain explicit control over profiling, use the monitor()
       (for  -p only) or monstartup() routines within your source
       code, and use the PROFDIR or PROFFLAGS  environment  variables.


       You  must  use the PROFDIR and PROFFLAGS environment variables
 to gain explicit control over the profiling done  by
       your  program. Using these variables overrides the default
       profiling support provided by the system.

       The PROFDIR environment variable allows you to run a  program
 multiple times and collect profiling data in multiple
       files, rather than overwriting the mon.out file  generated
       by  default.  The PROFDIR environment variable specifies a
       directory in which to write profiling data files. You  set
       the  variable as follows: For C shell: setenv PROFDIR path
       For Bourne shell: PROFDIR = path; export PROFDIR For  Korn
       shell: export PROFDIR = path

       To use the PROFDIR environment variable with the monitor()
       routines, first set PROFDIR to null  before  running  your
       program  and  then  be  sure to set PROFDIR to a path from
       within the program. Setting PROFDIR to null before running
       the  program to be profiled disables default initiation of
       profiling.  For example:

          setenv PROFDIR

       When you have set the PROFDIR environment  variable,  profiling
  data  is  collected in the file path/pid.progname,
       where path is the directory path specified  with  PROFDIR,
       pid  is the process ID of the executing program, and progname
 is the program name. The pid is also included in  the
       name  of any profiling data file created for a forked subprocess.
 If fork() is called from a signal  handler  in  a
       threaded  program,  the -threads option (see below) should
       be used.

       The PROFFLAGS environment variable can  take  any  of  the
       following  values. Note that only the -disable_default and
       -threads options are defined  for  -pg.   -disable_default
       allows  you to disable the default profiling buffers. This
       option is recommended when monitor or monstartup is called
       to  start  profiling.   To use monitor or monstartup calls
       with multithreaded programs, you  must  set  PROFFLAGS  to
       -disable_default.  This gives the program complete control
       of profiling.  Note that monstartup() and monitor()  calls
       after  the first have no effect (except restarting profil)
       if all threads are sharing the same samples buffers.  This
       means that all application calls to monstartup() and monitor()
 are ignored unless  -disable_defaults  is  specified
       (to  disable the automatic call to monstartup().  -threads
       causes a separate data  file  to  be  generated  for  each
       thread.  The  name  of  the  data file takes the following
       form: pid.sid.progname. The form of the filename  resolves
       to  pid  as  the  process  ID  of  the program, sid as the
       sequence ID of the thread, and progname as the name of the
       program  being  profiled.   -all causes monstartup(0,0) to
       fully profile all the permanently loaded shared libraries,
       in  addition  to  the  non-shared  or call-shared program.
       -incobj <name> causes monstartup(0,0) to profile only  the
       named executable or shared library.  -excobj <name> causes
       monitor and monstartup(0,0) not to profile the named  executable
  or  shared library.  -stride causes monstartup to
       change the ratio of text segment stride size to  pc-sample
       counter  buffer  size: that is, the number of instructions
       that are counted together in a single  counter  word.  The
       appropriate  ratio involves a tradeoff of size versus precision.
  Strides of 1, 2, 4, and 8 are supported.  A  special
  stride  of  0  causes a single pc-sample count to be
       recorded for each text  segment.   -sigdump  <signal-name>
       automatically  establishes monitor_signal(3) as the signal
       handler for the named signal, and it  causes  monitor_signal(3)  to zero the profile after it is written to a file.
       This allows a signal to be sent several times without  the
       successive  profiles  overlapping, if the file is renamed.
       The asynchronous nature of a signal may cause small variations
   in  the  profile.  Unrecognized  signal-names  are
       ignored. The -threads option is ignored if  combined  with
       -sigdump.  -dirname directory specifies the directory path
       in which the profiling data file  or  files  are  created.
       -[no]pids  [disables]  or enables the addition of the process-id
 number to the name of the profiling data  file  or
       files.

       The  general  form  for  setting these variables is: For C
       shell: setenv varname "value" For Bourne shell: varname  =
       "value";  export  varname For Korn shell: export varname =
       value

RETURN VALUES    [Toc]    [Back]

       Upon successful completion, when profiling is started, the
       monitor()  and  monstartup() functions return a value of 0
       (zero). Otherwise, they return a value of -1, and errno is
       set. Upon successful completion, the moncontrol() function
       returns the previous value  of  the  mode.  Otherwise,  it
       returns a value of -1, and errno is set.

ERRORS    [Toc]    [Back]

       If  the following condition occurs, the monitor() and monstartup()
 functions set errno to the corresponding  value:
       Either  the  bufsiz  parameter, or the value of the highpc
       parameter  minus  the  lowpc  parameter,  is  negative  or
       uneven.

       In  addition,  the  loader(5) and pthread(3) functions can
       set errno to values resulting from  manipulations  in  the
       file system or from calls to the calloc(3) function.

FILES    [Toc]    [Back]

       Default  profile  when  linked for gprof.  Default profile
       when linked for prof.  Location and name of the  profiling
       data  file  when the PROFDIR environment variable has been
       set.

SEE ALSO    [Toc]    [Back]

      
      
       Commands: cc(1), gprof(1), prof(1), pdtostd(1)

       Functions: calloc(3), end(3), profil(2)

       Programmer's Guide



                                                       monitor(3)
[ Back ]
 Similar pages
Name OS Title
monstartup NetBSD control execution profile
moncontrol NetBSD control execution profile
profil HP-UX execution time profile
monstartup FreeBSD control execution profile
moncontrol OpenBSD control execution profile
profil Linux execution time profile
monstartup OpenBSD control execution profile
moncontrol FreeBSD control execution profile
profil IRIX execution time profile
sprofil HP-UX execution time profile for disjointed text spaces
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service