Technical Reference: Base Operating System and Extensions, Volume 1

monstartup Subroutine

Purpose

Starts and stops execution profiling using default-sized data areas.

Library

Standard C Library (libc.a)

Syntax

#include <mon.h>

int monstartup ( LowProgramCounter, HighProgramCounter) OR int monstartup((caddr_t)-1), (caddr_t) FragBuffer) OR int monstartup((caddr_t)-1, (caddr_t)0)

caddr_t LowProgramCounter;
caddr_t HighProgramCounter;

Description

The monstartup subroutine allocates data areas of default size and starts profiling. Profiling causes periodic sampling and recording of the program location within the program address ranges specified, and accumulation of function-call count data for functions that have been compiled with the -p or -pg option.

Executable programs created with the cc -p or cc -pg command automatically include a call to the monstartup subroutine to profile the complete user program, including system libraries. In this case, you do not need to call the monstartup subroutine.

The monstartup subroutine is called by the mcrt0.o (-p) file or the gcrt0.o (-pg) file to begin profiling. The monstartup subroutine requires a global data variable to define whether -p or -pg profiling is to be in effect. The monstartup subroutine calls the monitor subroutine to initialize the data areas and start profiling.

The prof command is used to process the data file produced by -p profiling. The gprof command is used to process the data file produced by -pg profiling.

The monstartup subroutine examines the global and parameter data in the following order:

When the _mondata.prof_type global variable is neither -1 (-p profiling defined) nor +1 (-pg profiling defined), an error is returned and the function is considered complete.
The global variable is set to -1 in the mcrt0.o file and to +1 in the gcrt0.o file, and defaults to 0 when crt0.o is used.
When the LowProgramCounter value is not -1:
- A single program address range is defined for profiling
AND
- The first monstartup definition in the syntax is used to define the program range.
When the LowProgramCounter value is -1 and the HighProgramCounter value is not 0:
- Multiple program address ranges are defined for profiling
AND
- The second monstartup definition in the syntax is used to define multiple ranges. The HighProgramCounter parameter, in this case, is the address of a frag structure array. The frag array size is denoted by a zero value for the HighProgramCounter (p_high) field of the last element of the array. Each array element except the last defines one programming address range to be profiled. Programming ranges must be in ascending order of the program addresses with ascending order of the prof array index. Program ranges may not overlap.
When the LowProgramCounter value is -1 and the HighProgramCounter value is 0:
- The whole program is defined for profiling
AND
- The third monstartup definition in the syntax is used. The program ranges are determined by monstartup and may be single range or multirange.

Parameters

LowProgramCounter (frag name: `p_low`)	Defines the lowest execution-time program address in the range to be profiled.
HighProgramCounter(frag name: `p_high`)	Defines the next address after the highest execution-time program address in the range to be profiled. The program address parameters may be defined by function names or address expressions. If defined by a function name, then a function name expression must be used to dereference the function pointer to get the address of the first instruction in the function. This is required because the function reference in this context produces the address of the function descriptor. The first field of the descriptor is the address of the function code. See the examples for typical expressions to use.
FragBuffer	Specifies the address of a frag structure array.

Examples

This example shows how to profile the main load module of a program with -p profiling:

#include <sys/types.h>
#include <mon.h>
main()
{
extern caddr_t etext;      /*system end of text 
symbol*/
extern int start();      /*first function in main\
             program*/
extern struct monglobal _mondata; /*profiling global variables*/
struct desc {         /*function 
descriptor fields*/
   caddr_t begin;      /*initial code 
address*/
   caddr_t toc;      /*table of contents 
address*/
   caddr_t env;      /*environment 
pointer*/
 } 
;            /*function 
descriptor structure*/
struct desc *fd;      /*pointer to function\
             descriptor*/
int  rc;         /*monstartup 
return code*/
fd = (struct desc *)start;   /*init descriptor pointer to\
             start 
function*/
_mondata.prof_type = _PROF_TYPE_IS_P;   /*define -p profiling*/
rc = monstartup( fd->begin, (caddr_t) &etext);   /*start*/
if ( rc != 0 )         /*profiling did 
not start - do\
            error 
recovery here*/   return(-1);
            /*other code 
for analysis ...*/
return(0);         /*stop profiling and 
write data\
             file 
mon.out*/
}

This example shows how to profile the complete program with -p profiling:

#include <sys/types.h>
#include <mon.h>
main()
{
extern struct monglobal _mondata;   /*profiling global\
                 variables*/
int  rc;         /*monstartup 
return code*/
_mondata.prof_type = _PROF_TYPE_IS_P;   /*define -p profiling*/
rc = monstartup( (caddr_t)-1, (caddr_t)0);   /*start*/
if ( rc != 0 )         /*profiling did 
not start -\
              
  do error recovery here*/
   return (-1);
            /*other code 
for analysis ...*/
return(0);         /*stop profiling and 
write data\
             file 
mon.out*/
}

This example shows how to profile contiguously loaded functions beginning at zit up to but not including zot with -pg profiling:

#include <sys/types.h>
#include <mon.h>
main()
{
extern zit();         /*first function 
to profile*/
extern zot();         /*upper bound 
function*/
extern struct monglobal _mondata; /*profiling global variables*/
int  rc;         /*monstartup 
return code*/
_mondata.prof_type = _PROF_TYPE_IS_PG;   /*define -pg profiling*/
/*Note cast used to obtain function code addresses*/
rc = monstartup(*(uint *)zit,*(uint *)zot);   /*start*/
if ( rc != 0 )         /*profiling did 
not start - do\
             error 
recovery here*/
   return(-1);
            /*other code 
for analysis ...*/
exit(0);   /*stop profiling and write data file gmon.out*/
}

Return Values

The monstartup subroutine returns 0 upon successful completion.

Error Codes

If an error is found, the monstartup subroutine outputs an error message to stderr and returns -1.

Files

mon.out	Data file for -p profiling.
gmon.out	Data file for -pg profiling.
mon.h	Defines the _mondata.prof_type variable in the monglobal data structure, the prof structure, and the functions referred to in the examples.

Related Information

The moncontrol (moncontrol Subroutine)subroutine, monitor (monitor Subroutine) subroutine, profil (profil Subroutine) subroutine.

The gprof command, prof command.

The _end, _etext, or _edata (_end, _etext, or _edata Identifier) Identifier.

List of Memory Manipulation Services in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs.