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:

1. 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.

2. 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.
3. 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.
4. 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

Examples

1. 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*/
   }
   

2. 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*/
   }
   

3. 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.

Implementation Specifics

This subroutine is part of Base Operating System (BOS) Runtime.

Files

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.1 General Programming Concepts: Writing and Debugging Programs.