 |
Index for
Section 3 |
|
 |
Alphabetical
listing for M |
|
 |
Bottom of
page |
|
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
lowpc
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.
highpc
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.
signal
Specifies the signal number for which monitor_signal(3) is the handler.
buffer
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).
bufsiz
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.
nfunc
This field is not used and should be set to zero.
mode
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.
argbuf
When lowpc is -1, specifies an array of monitor_args structures, each
describing a single address range in which profiling is to occur.
options
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 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 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() 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
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 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 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
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 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
gmon.out
Default profile when linked for gprof.
mon.out
Default profile when linked for prof.
PROFDIR/pid.program
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
|
Index for
Section 3 |
|
|
Alphabetical
listing for M |
|
 |
Top of
page |
|