monstartup man page on NeXTSTEP

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


MONITOR(3)							    MONITOR(3)

NAME
       monitor,	  monstartup,	moncontrol,   moninit,	 monreset,  monoutput,
       monaddition, moncount - prepare execution profile

SYNOPSIS
       extern void monstartup(
	    char *lowpc,
	    char *highpc);
       extern void monitor(
	    char *lowpc,
	    char *highpc,
	    char *buf,
	    int bufsiz,
	    int nfunc);
       extern void moncontrol(
	    int mode);
       extern void moninit(void);
       extern void moninitshlibs(void);
       extern void monreset(void);
       extern void monoutput(
	    const char *filename);
       extern void monaddition(
	    char *lowpc,
	    char *highpc);
       extern void moncount(
	    char *frompc,
	    char *selfpc)

DESCRIPTION
       These functions support execution  profiling.   An  executable  program
       created	with  the profiling option -pg of cc(1) automatically includes
       calls for the gprof(1) monitor,	which  displays	 execution  times  and
       statistics  for	the functions in the program.  The functions described
       here provide different sorts of control over the profiling.

       Monstartup is a high-level interface to profil(2).   Lowpc  and	highpc
       specify	the  address  range  that is to be sampled; the lowest address
       sampled is that	of  lowpc  and	the  highest  is  just	below  highpc.
       Monstartup  allocates  a	 buffer	 and passes it to monitor (see below),
       which records into it a histogram of periodically sampled values of the
       program counter, as well as counts of calls to certain functions.  Only
       calls to functions compiled with the profiling option -pg of cc(1)  are
       recorded.

       To profile the entire program, it is sufficient to include the line:

	    moninit();

       in  the	source	code.	This  routine is invoked just before main() is
       called, if the program is linked with the profiling run-time  start-off
       (/lib/gcrt0.o).	 The  profiling	 run-time start-off is used instead of
       the standard run-time start-off when the program is linked  with	 cc(1)
       and the profiling option -pg is specified on the link line.

       To  stop	 execution  monitoring	and  write  the	 results  on  the file
       gmon.out, use

	    monitor(0);

       Again, this happens automatically in the profiling  run-time  startoff,
       which  defines  a  version  of exit(2) that makes this call to monitor.
       After the file gmon.out is written, the program gprof(1) can be used to
       examine the results.

       Moncontrol  is  used to selectively control profiling within a program.
       When the program starts, profiling begins.  To stop the	collection  of
       histogram ticks and call counts, use

	    moncontrol (0);

       and to resume the collection of histogram ticks and call counts, use

	    moncontrol (1);

       This  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 moncontrol.

       Monitor	is  a  low-level interface to profil(2).  Lowpc and highpc are
       the addresses of two functions;	buffer	is  the	 address  of  a	 user-
       supplied	 array	of  bufsize  short  integers.	The parameter nfunc is
       ignored and exists only for historical reasons.	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.  Monitor divides the buffer into
       space to record the histogram of program counter samples over the range
       lowpc to highpc.	 The space to record call counts of functions compiled
       with the -pg option to cc(1) is allocated by moncount.

       Moninit is invoked just before main() is called in the  profiling  run-
       time  start-off	(/lib/gcrt0.o).	  It  sets up the entire program to be
       profiled.  This includes a call to moninitshlibs,  which	 causes	 entry
       points  in  any	shared	libraries  used	 to have their call counts and
       histogram  ticks	 of  the  shared  libraries'  code  to	be   recorded.
       Recording  for shared libraries can be disabled by linking in a version
       of moninitshlibs that does nothing.  Moninit also causes the Objective-
       C  run-time  system  to record counts for Objective-C messages that are
       sent.  Moninit also sets up profiling for any code that will be	loaded
       with  rld(3).   For  call  counts  of the code loaded with rld(3) to be
       recorded, the code must have been compiled with	the  profiling	option
       -pg of cc(1).

       Monreset resets all the histogram ticks and call counts to zero.

       Monoutput  writes  the  profiling information into the specified output
       file.

       To the existing set of regions, monaddition adds	 a  region  to	record
       histogram  ticks and call counts.  This function is used to add regions
       for shared libraries and code loaded with rld(3).

       Moncount is the routine that increments the call counts	for  the  call
       site  frompc  which  is	calling	 the routine at selfpc.	 Moncount gets
       called at the beginning of each routine	compiled  with	the  profiling
       option -pg to cc(1).

FILES
       gmon.out

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

NeXT, Inc.			 July 29, 1993			    MONITOR(3)
[top]

List of man pages available for NeXTSTEP

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