[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]

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: AND
  3. When the LowProgramCounter value is -1 and the HighProgramCounter value is not 0: AND
  4. When the LowProgramCounter value is -1 and the HighProgramCounter value is 0: AND

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

  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


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


[ Previous | Next | Table of Contents | Index | Library Home | Legal | Search ]