*** UNIX MANUAL PAGE BROWSER ***

monitor(3) Library Functions Manual monitor(3) 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 moni- tor_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 multi- ple 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 syn- opsis above. Specifies the upper address boundary of a function ad- dress 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 rou- tines. 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 gen- erated. 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 inte- gers. This is defined only if the lowpc or highpc argument to the moni- tor() 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, spec- ifies an array of monitor_args structures, each describing a single ad- dress range in which profiling is to occur. Specifies flags that mod- ify the behavior of a monitor call that profiles multiple disjoint ad- dress. 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 con- trolled by calling either the monstartup() or monitor() routine di- rectly from the program. The buffer size can also be reduced by using the -stride option in the PROFFLAGS environment variable (see the Envi- ronment 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 moncon- trol(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 sec- tion, 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 func- tions 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 moni- tor() 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 arg- buf have the same types and meanings as the arguments in the tradi- tional monitor call, except that the buffer field is an array of un- signed ints instead of an array of chars. The following are the con- tents 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 en- vironment 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() func- tion 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 perma- nently-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 coun- ters 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 exe- cution. 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 fol- lowing 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 in- stance, 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 profil- ing 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 sig- nal handler is fully supported for nonthreaded and multithreaded pro- grams 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 moni- tor_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 sys- tem. The PROFDIR environment variable allows you to run a program multiple times and collect profiling data in multiple files, rather than over- writing 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 initia- tion 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 val- ues. Note that only the -disable_default and -threads flags are de- fined for -pg. -disable_default allows you to disable the default pro- filing 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 mon- startup() 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 gen- erated 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 pro- gram, 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 pro- file all the permanently loaded shared libraries, in addition to the non-shared or call-shared program. -incobj <name> causes mon- startup(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 to- gether in a single counter word. The appropriate ratio involves a tradeoff of size versus precision. Strides of 1, 2, 4, and 8 are sup- ported. 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. Oth- erwise, it returns a value of -1, and errno is set. ERRORS If the following condition occurs, the monitor() and monstartup() func- tions set errno to the corresponding value: Either the bufsiz parame- ter, 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 monitor(3)