smonitor(3C)

NAME

smonitor() — prepare execution profile

SYNOPSIS

#include <mon.h> 
#include <sys/profil.h> 

void smonitor( 
     struct text_region *regions, 
     int nregions, 
     void *buffer, 
     size_t bufsize, 
     int nfunc, 
     unsigned flags 
); 

DESCRIPTION

smonitor() is an interface to sprofil(2) for collecting sampling information for execution profiles.

To use smonitor(), link in the gprof library by specifying -lgprof on the linker command line or -G on the compiler command line. See gprof(1).

For any application compiled with the -G option, the gprof library collects profiling sampling information. But if an application requires finer control over profiling, the gprof library yields control to an application that uses smonitor().

To stop the collection of sampling information, use:

smonitor(0, 0, 0, 0, 0, 0); 

Use gprof(1) to examine the results.

Parameters

regions is an array of text_region structures describing the regions to be profiled. It is defined in header <mon.h>. The text_region structure has the following fields:

unsigned long text_start; 
unsigned long text_end; 
char *name; 

The fields are as follows:

text_start is the start address of the text segment of the load module.
text_end is the end address of the text segment of the load module.
name is the name of the load module (not the path name). The name of the load module should be the same as recorded in the executable by ld.

nregions is the number of elements in the array regions.

buffer is the starting address a buffer to collect sampling information.

bufsize is the length of buffer. buffer is the only memory region used by smonitor() to collect profiling information, so it should be big enough for all specified regions. smonitor() does not initialize buffer. With more than one call to smonitor() in the same process, smonitor() dumps the sampling information collected with the last call. smonitor() does not discard the information collected in previous calls if it is present in the buffer passed to last call of smonitor().

nfunc is unused and kept for future usage.

flags is used to choose 16-bit or 32-bit buckets to collect sampling information. If flags is set to PROF_USHORT, smonitor() treats the buffer as an array of 16-bit buckets; if set to PROF_UINT, smonitor() treats the buffer as an array of 32-bit buckets. For more information refer to sprofil(2).

EXTERNAL INFLUENCES

Environment Variables

The behavior of smonitor() is controlled by the LD_PROFILE environment variable. See gprof(1). smonitor() behaves with different settings of LD_PROFILE as follows:

LD_PROFILE="": libgprof.so does not set up the buffers to collect sampling information. It is expected that smonitor() will be called explicitly to collect the sampling information. So it is the ideal case to call the smonitor() explicitly.
LD_PROFILE=ALL: libgprof.so sets up the sampling buffer for all the load modules and starts sprofil() to collect the sampling information. Now if smonitor() is invoked explicitly, sprofil() is stopped, the buffer allocated by libgprof.so is deallocated, and all the sampling information collected prior to calling smonitor() is lost. smonitor() uses the buffer passed as an argument and starts sprofil() again.
LD_PROFILE=ldm1:ldm2: libgprof.so sets up the sampling buffer for the load modules ldm1 and ldm2 and starts sprofil() to collect the sampling information. Now if smonitor() is invoked explicitly, sprofil() is stopped, the buffer allocated by libgprof.so is deallocated, and all the sampling information collected prior to calling smonitor() is lost. smonitor() uses the buffer passed as an argument and starts sprofil() again.

If LD_PROFILE is not set, smonitor() behaves as though LD_PROFILE=ALL.

FILES

/usr/lib/hpux32/libgprof.so 
/usr/lib/hpux64/libgprof.so 

smonitor(3C)

Technical documentation

» Table of Contents

» Index