monitor(3)monitor(3)NAME
monitor, monstartup, moncontrol, monitor_signal - Prepare execution
profile
SYNOPSIS
#include <stdio.h>
int monstartup(
caddr_t lowpc,
caddr_t highpc ); int moncontrol(
int mode ); void monitor_signal(
int 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 );
LIBRARY
libprof1.a, libprof1_r.a (linked automatically when -p or -pg option is
used)
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 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 optimiza‐
tion 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 option), 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 speci‐
fied 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 signal number for which monitor_signal(3) is the handler. Speci‐
fies 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 moni‐
tor_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
address range in which profiling is to occur. Specifies options 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 option 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
directly 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 con‐
tain 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 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
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 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
unsigned 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 option 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() 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 profil‐
ing.
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 exe‐
cution. When a program that has been compiled and linked with either
the -p or -pg option 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 option 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. Themonitor_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 pid is also included in
the name of any profiling data file created for a forked subprocess. If
fork() is called from a signal handler in a threaded program, the
-threads option (see below) should be used.
The PROFFLAGS environment variable can take any of the following val‐
ues. Note that only the -disable_default and -threads options are
defined for -pg.-disable_default allows you to disable the default
profiling buffers. This option is recommended when monitor or mon‐
startup is called to start profiling. To use monitor or monstartup
calls with multithreaded programs, you must set PROFFLAGS to -dis‐
able_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 pro‐
filed. -all causes monstartup(0,0) to fully profile all the perma‐
nently 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. -sigdump
<signal-name> automatically establishes monitor_signal(3) as the signal
handler for the named signal, and it causes monitor_signal(3) to zero
the profile after it is written to a file. This allows a signal to be
sent several times without the successive profiles overlapping, if the
file is renamed. The asynchronous nature of a signal may cause small
variations in the profile. Unrecognized signal-names are ignored. The
-threads option is ignored if combined with -sigdump.-dirname direc‐
tory specifies the directory path in which the profiling data file or
files are created. -[no]pids [disables] or enables the addition of the
process-id number to the name of the profiling data file or files.
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. Other‐
wise, 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.
SEE ALSO
Commands: cc(1), gprof(1), prof(1), pdtostd(1)
Functions: calloc(3), end(3), profil(2)
Programmer's Guide
monitor(3)