NAME

monitor, monstartup, moncontrol, monitor_signal − Prepare execution profile

LIBRARY

libprof1.a
libprof1_r.a

SYNOPSIS

#include <stdio.h>
int monitor(
caddr_t lowpc,
caddr_t highpc,
char ∗ buffer,
size_t bufsiz,
size_t nfunc);

int monstartup(
caddr_t lowpc,
caddr_t highpc);

int moncontrol(
int mode);

extern int monitor_signal();

PARAMETERS

lowpcSpecifies the lower address boundary of a function address range. 

highpcSpecifies the upper address boundary of a function address range. 

NOTE

When a program is compiled at a low optimization level, the compiler preserves the ordering of routines established in the source program.  However, when a program is compiled at higher optimization levels (with the −O3 or −O4 flag), the compiler may rearrange the order of its routines.  If you compile a program that calls monitor or monstartup at a high optimization level, the address specified by lowpc could be placed at a higher address than that specified by highpc.  Subsequently, calls to monitor and monstartup will fail and no profiling data will be generated.  To verify that the lowpc and highpc passed to these routines are correct, use the nm command to check their assigned addresses in the program’s object file. 

bufferSpecifies the address of a (user-supplied) array of bufsiz short integers. This is defined only if the lowpc argument to the monitor() function is not 0 (zero). 

bufsizSpecifies the size of buffer in bytes. This parameter is defined only if the lowpc argument to the monitor() function is not zero. 

nfuncThis field is not used and should be set to zero. 

modeSpecifies an operation mode for the collection of histogram ticks.  Use a value of 0 (zero) to stop the collection of histogram ticks.  Use a value of 1 to resume the collection of histogram ticks. 

DESCRIPTION

When an executable program is compiled for profiling by using either the −p or −pg flag with the cc command, the default parameters cause the entire text segment to be profiled. 

For large programs, this may be more than you need. The size of the buffer allocated, and the portion of the program profiled, can be controlled by calling either the monstartup() or monitor() routine directly from the program. 

The moncontrol() function can be used to turn profiling on and off for the process or the thread.  The monitor() and monstartup() routines contain an implicit moncontrol call to turn profiling on. A moncontrol(0) call can be used to turn off sampling, providing user control over when a section of code is sampled. 

The profiling support does not profile shared libraries. Only the call_shared part of a program can be profiled.  You can build your program call_shared, but profiling information will not be generated for any of the shared libraries the program uses. 

The monitor() Function

The monitor() function is a low level interface to the profil() system call. The lowpc and highpc parameters are the addresses of two functions in a program that delimit the text range to profile.  If the lowpc parameter is 0 (zero), the monitor() function stops profiling and writes out the data output file mon.out.  The buffer allocated must be one-half the size of the text range to be sample. 

NOTE

The monitor() interface, except monitor(0), is not supported for gprof profiling. Use only monstartup() for gprof profiling. 

To stop execution monitoring and to have the results written to the file mon.out, use the following call: monitor(0).  Then use the prof command to examine the results. 

The monstartup() Function

The monstartup() function is a high level interface to the profil() system call. 

The lowpc and highpc parameters specify the address range that is to be sampled; the lowest address sampled is that of lowpc and the highest is just below highpc.  The monstartup() function allocates space by using the calloc() function and passes it to the monitor() function to record a histogram of periodically sampled values of the program counter. 

The moncontrol() Function

The moncontrol() function is used in conjunction with the monstartup() and monitor() routines to turn sampling on and off during program execution.  When a program that has been compiled and linked with either the −p or −pg flag starts executing, profiling begins.  To stop the collection of histogram ticks, use the following function call:

   moncontrol(0);

To resume the collection of histogram ticks, use the following function call:

   moncontrol(1);

This method 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 the moncontrol() function. 

The monitor_signal() Function

The monitor_signal() function allows you to profile programs that do not terminate, such as daemons. To use this routine, declare it as a signal handler in your program and compile the program with the −p flag for prof profiling, or with −pg for gprof profiling. 

While the program executes, send a signal to the program from the shell by using the kill(1) command. The monitor_signal() routine is invoked when the signal is received and then writes out the profiling data file, [g]mon.out. If another signal is sent to the process, the profiling data file is overwritten. You might want to save the profiling data file between sending signals to the process. 

Environment Variables

To gain explicit control over profiling, use the monitor() (for −p only) or monstartup() routines within your source code, and use the PROFDIR or PROFFLAGS environment variables. 

You must use the PROFDIR and PROFFLAGS environment variables to gain explicit control over the profiling done by your program. Using these variables disables the default profiling support provided by the system. 

The PROFDIR environment variable allows you to run a program multiple times and collect profiling data in multiple files, rather than overwriting the mon.out file generated by default.  The PROFDIR environment variable specifies a directory in which to write profiling data files.  You set the variable as follows:

    For C shell:  setenv PROFDIR path
    For Bourne Shell:  PROFDIR = path;  export  PROFDIR

To use the PROFDIR environment variable with the monitor() routines, first set PROFDIR to null before running your program and then be sure to set PROFDIR to a path from within the program. Setting PROFDIR to null before running the program to be profiled disables default initiation of profiling. 

     setenv PROFDIR ""

When you have set the PROFDIR environment variable, profiling data is collected in the file path/pid.progname, where path is the directory path specified with PROFDIR, pid is the process ID of the executing program, and progname is the program name. 

The PROFFLAGS environment variable allows you to disable the default profiling buffers by setting the variable to −disable_default. This setting does not change the file naming convention of the data output file. You can set PROFDIR to generate multiple files with pid.program names. 

To use monitor calls with multithreaded programs, you must set PROFFLAGS to −disable_default which gives complete complete control of profiling over to the program. If the program uses monitor() and allocates separate buffers for each thread being profiled, set PROFFLAGS to −threads.  This setting affects the naming of the data profile files. Set this variable as follows:

    For C shell:   setenv PROFFLAGS  "-disable_default -threads"
    For Bourne Shell: PROFFLAGS = "-disable_defaults -threads"
                      export  PROFFLAGS

RETURN VALUES

Upon successful completion, when profiling is started, the monitor() and monstartup() functions return a value of 0 (zero).  Otherwise, they return a value of -1, and errno is set.  Upon successful completion, the moncontrol() function returns the previous value of the mode.  Otherwise, it returns a value of -1, and errno is set. 

ERRORS

If the following condition occurs, the monitor() and monstartup() functions set errno to the corresponding value:

[EINVAL]Either the bufsiz parameter, or the value of the highpc parameter minus the lowpc parameter, is negative or uneven. 

In addition, the monitor(0) function can set errno to values resulting from manipulations in the file system, the monstartup() function can get errno values from calls to the calloc(3) function. 

FILES

gmon.outDefault profile when linked for gprof. 

mon.outDefault profile when linked for prof. 

PROFDIR/pid.program
Location and name of the profiling data file when the PROFDIR environment variable has been set. 

RELATED INFORMATION

Commands: cc(1), gprof(1), prof(1)

Functions: calloc(3), end(3), profil(2)

Programmer’s Guide