monitor, monstartup, moncontrol, monitor_signal - Prepare
execution profile
#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 );
libprof1.a, libprof1_r.a (linked automatically when -p or
-pg option is used)
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 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 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
signal number for which monitor_signal(3) is the handler.
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 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.
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 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 [Toc] [Back]
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 option
is set in the PROFFLAGS environment variable.
The monstartup() Function [Toc] [Back]
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 [Toc] [Back]
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 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 [Toc] [Back]
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
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 [Toc] [Back]
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 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 values. 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 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. -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 directory 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
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.
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.
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.
Commands: cc(1), gprof(1), prof(1), pdtostd(1)
Functions: calloc(3), end(3), profil(2)
Programmer's Guide
monitor(3)
[ Back ] |
