Content-type: text/html Man page of monitor

monitor

Section: C Library Functions (3)
Index Return to Main Contents
 

NAME

monitor, monstartup, moncontrol, monitor_signal - Prepare execution profile  

LIBRARY

libprof1.a, libprof1_r.a (linked automatically when -p or -pg flag is used)  

SYNOPSIS

#include <stdio.h> int monstartup(        caddr_t lowpc,
       caddr_t highpc);

int moncontrol(        int mode);

extern int monitor_signal();

int monitor(        caddr_t lowpc,
       caddr_t highpc,
       char * buffer,
       size_t bufsiz,
       size_t nfunc);

#include <mon.h> int monitor(        int lowpc,
       0,
       struct monitor_args *argbuf,
       size_t bufsiz,
       unsigned long flags);
 

PARAMETERS

Specifies the lower address boundary of a function address range. When lowpc is -1, a monitor call is interpreted as a call to profile multiple discontiguous address ranges, such as those in an executable and its shared libraries. This type of monitor call must have a highpc with a value of 0 and have the format shown in the second monitor synopsis above. Specifies the upper address boundary of a function address range. In a call to the monitor function, the highpc argument must be 0 when lowpc is -1.

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.

Specifies the address of a (user-supplied) array of bufsiz short integers. This is defined only if the lowpc or highpc argument to the monitor() function is not 0 (zero). Specifies the size of buffer in bytes. This parameter is defined only if the lowpc argument to the monitor function is not zero. When lowpc is -1, bufsiz specifies the number of monitor_args structures in the argbuf array; in this case, the extended form of the monitor call, as shown in the second monitor synopsis above, is used. This field is not used and should be set to zero. Specifies an operation mode for the collection of PC samples. Use a value of 0 (zero) to stop the collection of PC samples. Use a value of 1 to resume the collection of histogram ticks. When lowpc is -1, specifies an array of monitor_args structures, each describing a single address range in which profiling is to occur. Specifies flags that modify the behavior of a monitor call that profiles multiple disjoint address. This argument is reserved for future use and should be 0.  

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 buffer size can also be reduced by using the -stride option in the PROFFLAGS environment variable (see the Environment Variables section, below).

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 by default, and not at all for gprof profiling (using gcrt0.o instead of mcrt0.o). See the -all option in the PROFFLAGS part of the Environment Variables section, below.  

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

NOTE

The monitor() interface, except monitor(0), is not supported for gprof profiling. Use only monstartup() for gprof profiling. Calls to monitor() will return -1 and set errno to EINVAL.

To stop execution monitoring and to have the results written to the mon.out or gmon.out file (depending upon whether the program was linked with prof or gprof), use the following call: monitor(0). Then use the prof or gprof command, as appropriate, to examine the results.

The second form of monitor call allows you to profile multiple disjoint address ranges, such as an executable and its shared libraries. This form of monitor call must specify a lowpc value of -1 and a highpc value of 0. The argbuf argument, specifies an array of monitor_args structures, each describing a single address range in which profiling is to occur. The number of monitor_args structures in this array is indicated by the bufsiz argument.

The fields of each monitor_args struct in the array pointed to by argbuf have the same types and meanings as the arguments in the traditional monitor call, except that the buffer field is an array of unsigned ints instead of an array of chars. The following are the contents of a monitor_args struct:
        struct monitor_args {
                caddr_t       lowpc;
                caddr_t       highpc;
                unsigned int  *buffer;
                size_t        bufsiz;
                }

The elements of the argbuf array are sorted in order of decreasing lowpc value, if they are not already in that order. It is an error to attempt to profile an address range that is not currently loaded.

In a multithreaded program, every thread that calls monitor must use the same arguments unless the -threads flag is set in the PROFFLAGS environment variable.  

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.

When a program is linked with -p, a monstartup(0,0) call requests to profile, using 32-bit counters, the whole text segment in all permanently-loaded shared libraries (that is, those libraries not included in the program by a dlopen(3) call. When a program is linked with -pg, a monstartup(0,0) call requests that only the executable be profiled using 32-bit counters.

The monstartup function uses information requested from the loader the first time it is called to determine which libraries are loaded and what their text segment address ranges are. Before starting to profile these address ranges, all existing profiling is stopped.

The monstartup function allocates counter buffers that are arrays of unsigned int, and combines the samples for two instructions in each counter. The scale and the set of text segments profiled can be changed by setting the PROFFLAGS environment variable, as for default profiling.

A call to monstartup affects the profiling of only the thread in which the call was made. The PROFFLAGS -threads switch causes separate counters to be used for each thread, resulting in a separate profiling data file for each thread. If the -threads switch is not used, every thread that calls monstartup must specify the same lowpc and highpc.  

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 PC samples, use the following function call:
   moncontrol(0); To resume the collection of PC samples, 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 for the signal of your choice (for instance, SIGUSR1), 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.

Using sigaction or signal to make monitor_signal the process-wide signal handler is fully supported for nonthreaded and multithreaded programs when the PROFFLAGS environment variable does not include the -threads option. This allows you to create a profiling data file for the thread that is running when the signal arrives. This mechanism is not recommended when PROFFLAGS includes -threads, although it may be possible in many cases. For certain multithreaded processes, delivery of the asynchronous signal may cause execution problems. When -threads is specified, the recommended approach is to program a thread to await the signal using sigwait and then tell other threads to call monitor_signal.

 

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 overrides 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 For Korn shell: export PROFDIR = path

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. For example:


     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 can take any of the following values. Note that only the -disable_default and -threads flags are defined for -pg. -disable_default allows you to disable the default profiling buffers. This flag is recommended when monitor or monstartup is called to start profiling. To use monitor or monstartup calls with multithreaded programs, you must set PROFFLAGS to -disable_default. This gives the program complete control of profiling. Note that monstartup() and monitor() calls after the first have no effect (except restarting profil) if all threads are sharing the same samples buffers. This means that all application calls to monstartup() and monitor() are ignored unless -disable_defaults is specified (to disable the automatic call to monstartup(). -threads causes a separate data file to be generated for each thread. The name of the data file takes the following form:
pid.sid.progname.

The form of the filename resolves to pid as the process ID of the program, sid as the sequence ID of the thread, and progname as the name of the program being profiled. -all causes monstartup(0,0) to fully profile all the permanently loaded shared libraries, in addition to the non-shared or call-shared program. -incobj <name> causes monstartup(0,0) to profile only the named executable or shared library. -excobj <name> causes monitor and monstartup(0,0) not to profile the named executable or shared library. -stride causes monstartup to change the ratio of text segment stride size to pc-sample counter buffer size: that is, the number of instructions that are counted together in a single counter word. The appropriate ratio involves a tradeoff of size versus precision. Strides of 1, 2, 4, and 8 are supported. A special stride of 0 causes a single pc-sample count to be recorded for each text segment.

The general form for setting these variables is: For C shell: setenv varname "value" For Bourne shell: varname = "value"; export varname For Korn shell: export varname = value  

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: Either the bufsiz parameter, or the value of the highpc parameter minus the lowpc parameter, is negative or uneven.

In addition, the loader(5) and pthread(3) functions can set errno to values resulting from manipulations in the file system or from calls to the calloc(3) function.  

FILES

Default profile when linked for gprof. Default profile when linked for prof. 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), pdtostd(1)

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

Programmer's Guide delim off


 

Index

NAME
LIBRARY
SYNOPSIS
PARAMETERS
DESCRIPTION
The monitor() Function
The monstartup() Function
The moncontrol() Function
The monitor_signal() Function
Environment Variables
RETURN VALUES
ERRORS
FILES
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:49 GMT, October 02, 2010