monstartup man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

monitor(3)							    monitor(3)

NAME
       monitor,	 monstartup,  moncontrol,  monitor_signal  - Prepare execution
       profile

SYNOPSIS
       #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
       libprof1.a, libprof1_r.a (linked automatically when -p or -pg option is
       used)

PARAMETERS
       Specifies  the lower address boundary of a function address range. When
       lowpc is -1, a monitor call is interpreted as a call to profile	multi‐
       ple  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  optimiza‐
       tion 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 speci‐
       fied 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.	Speci‐
       fies 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	 moni‐
       tor_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, spec‐
       ifies  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
       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 con‐
       trolled	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 Envi‐
       ronment 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 con‐
       tain  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
       The monitor() function is a low level interface to the profil()	system
       call.  The  lowpc  and highpc parameters are the addresses of two func‐
       tions 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  arg‐
       buf  have  the  same  types and meanings as the arguments in the tradi‐
       tional monitor call, except that	 the  buffer  field  is	 an  array  of
       unsigned	 ints instead of an array of chars. The following are the con‐
       tents 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
       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() func‐
       tion 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	perma‐
       nently-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  profil‐
       ing.

       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
       The  moncontrol() function is used in conjunction with the monstartup()
       and monitor() routines to turn sampling on and off during program  exe‐
       cution.	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
       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 profil‐
       ing 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 sig‐
       nal handler is fully supported for nonthreaded and  multithreaded  pro‐
       grams  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	 moni‐
       tor_signal.

   Environment Variables
       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 sys‐
       tem.

       The PROFDIR environment variable allows you to run a  program  multiple
       times  and  collect profiling data in multiple files, rather than over‐
       writing 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 initia‐
       tion 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  val‐
       ues.  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 mon‐
       startup is called to start profiling.  To  use  monitor	or  monstartup
       calls  with  multithreaded  programs,  you  must set PROFFLAGS to -dis‐
       able_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 pro‐
       filed.  -all causes monstartup(0,0) to fully  profile  all  the	perma‐
       nently  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 direc‐
       tory 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
       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. Other‐
       wise, it returns a value of -1, and errno is set.

ERRORS
       If the following condition occurs, the monitor() and monstartup() func‐
       tions  set  errno to the corresponding value: Either the bufsiz parame‐
       ter, 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
       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
       Commands: cc(1), gprof(1), prof(1), pdtostd(1)

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

       Programmer's Guide

								    monitor(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net