fprof(1) fprof(1)
NAME
fprof - configure, start, control or analyze the results of a
flow-profile experiment
SYNOPSIS
fprof -C[Logging=on|off,][StartState=on|off,][Accuracy=accurate|normal,]
[LogPrefix=pathname]
fprof -s [-C[Logging=on|off,][StartState=on|off,][Accuracy=accurate|normal,]
[LogPrefix=pathname]] command-line
fprof [-o|-O] [-m] log [log] . . .
fprof [-i] [log] . . .
DESCRIPTION
fprof is the controlling program for the flow profiling
features. Flow profiling is a form of tracing used to analyze
performance and locality of reference of text.
Profiling revolves around running experiments. An experiment
consists of running the program that you want to analyze with
profiling compiled into the program. For flow profiling, the
-qf option must be given to cc(1) or CC(1C++). When a program
being profiled is running (i.e., a flow-profile experiment is
running), the current time is recorded every time a function
is called and every time it exits.
There are three different uses for fprof:
Setting up flow-profile experiment parameters
Controlling the activity of a running experiment
Viewing the results of experiments
The first 2 uses are optional. If the default configuration
is the way you want it and the experiment needs no fine
control, you can just compile your program with flow
profiling, run the program and analyze the results. If this
is all you need, viewing the results of experiments is
described below.
Setting up flow-profile experiment parameters is accomplished
in one of three ways: system-wide configuration files,
environment variables or per-experiment command-line
arguments. There are four configuration parameters:
Copyright 1994 Novell, Inc. Page 1
fprof(1) fprof(1)
Logging
Controls whether any logging will be performed on
programs that were compiled for flow-profiling. By
default, logging is on.
StartState
Controls whether the logging state is on when the
experiment is begun. (The logging state is on by
default.) If StartState is set to off, logging may be
turned on while the program is running. The only reason
to use this parameter is to preclude start-up
information from a flow-profile log.
Accuracy
Set to either accurate or normal. Accurate logs write
time stamp information accurate to the microsecond (at
least). Normal logs will contain timestamps that are
accurate to 1/100 of a second. By default, the accuracy
is normal. Note that due to system architecture
constraints, only programs running with root privilege
may use accurate timestamping.
LogPrefix
Allows you to choose where you would like the logs to be
stored. When a program is begun that has logging turned
on, an output file is created with the name
LogPrefix.pid (where pid is the process-id of the
running program). By default, LogPrefix is set to
/tmp/out. This means that for a process with a pid of
12, its log will be the file /tmp/out.12.
Setting up system-wide configuration parameters requires the
root privilege and is done with fprof -C (with no -s option).
Once this is accomplished all experiments will use these
parameters. The configuration is stored in the file
/usr/ccs/lib/fprof.cfg.
The system-wide configuration may be superseded through the
environment variables FprofLogging, FprofStartState,
FprofAccuracy and FprofLogPrefix.
A third way to specify the configuration for a flow-profile
experiment is to start the experiment using fprof -s. This
sets the four environment variables above and executes the
command-line specified in its argument.
Copyright 1994 Novell, Inc. Page 2
fprof(1) fprof(1)
Controlling the activity of a running experiment is
accomplished using the third form of the command shown above.
Control, in this case, means starting and stopping logging or
putting marks in the log.
To specify which running processes are to be controlled, a set
of log files are given as arguments (each log file corresponds
to a process). The -o option sets the logging state to on.
The -O option sets the logging state to off. The -m option
places a mark record into the log at its current point.
Viewing the results of experiments is done using the last form
of fprof. This form sets up an interactive shell for the
user. The interface is that of the ksh(1) command, but more
commands are available. These commands can be used like any
shell commands, that is, they can be piped, redirected, etc.
A set of logs may be specified on the command-line. This is
equivalent to starting fprof with no arguments and giving an
open command to the interpreter with those logs (see open
below). The -i option requests that an info (see below)
command be done on the specified logs. It is common practice
to call fprof -i right after an experiment to make sure that
the log turned out the way you expected it to.
The available commands are:
open log [log]...
Takes a list of logs and opens them for reading.
info Writes information about the open logs to the standard
output.
close Closes logs opened by an open command.
output [count]
Writes count records to the standard output. If count
is not supplied, 10 records are written.
output_until_mark
Writes records to the standard output until it reaches
the end of all logs or until it sees a marked entry.
search regular-expression
Searches for the next log entry whose function call
matches the regular expression and writes the record to
Copyright 1994 Novell, Inc. Page 3
fprof(1) fprof(1)
the standard output.
bracket
Writes all records between the previous mark and the
next mark to the standard output.
rewind
Returns to the beginning of the first log.
seekmark [-]
Seeks to the next (or previous if the '-' is present)
mark.
count [time1 [time2]]
Gathers statistics on any subset of the log (or the
whole log); there is no output. Time may be specified
in marks or in absolute numbers. Each may be specified
relatively or absolutely as well. For example, count
-m-1 -m+1 would gather statistics from the previous mark
to the next; count -1000 +1000 would gather statistics
from the previous millisecond to the next; count 1000
would gather statistics from one millisecond into the
log until the end.
stats
Prints out call statistics gathered by count. It shows
each function called, how many times it was called, how
much time it spent running (time at top of stack) and
how much time it or any function it called spent running
(time on stack).
callers regular-expression [regular-expression]...
Prints out caller statistics gathered by count. For
each function that matches any of the regular
expressions, print out the percentage of:
calls to the function that resulted from the
execution of each other function,
time spent in the function that resulted from the
execution of each other function,
time the function spent on the stack that resulted
from the execution of each other function.
Copyright 1994 Novell, Inc. Page 4
fprof(1) fprof(1)
For example, assume there is a function x that is
consuming a lot of time on the stack (not necessarily on
top of the stack), callers will tell you in its 3rd
column how much of that time was spent from a call from
each other function.
callees regular-expression [regular-expression]...
Prints out callee statistics gathered by count. This is
similar to callers. Used when one notices that a certain
function is spending a lot of time somewhere on the
stack.
The term compile is often associated with flow-profile logs.
Compiling a log is analogous to compiling a program. It means
that the log is converted to a format that can be read faster.
The first time a log is read, by either fprof or lrt_scan(1)
(which analyzes the results of a flow-profiling experiment for
locality of reference tuning), the log is compiled so that it
can be read faster the next time. The one exception to this
rule is that if the log is read while the experiment is still
running (this is perfectly acceptable), the log is not
compiled.
FILES
/usr/ccs/lib/fprof.cfg system-wide configuration file
REFERENCES
CC(1C++), cc(1), ksh(1), lprof(1), lrt_scan(1) prof(1),
regcmp(3G)
Copyright 1994 Novell, Inc. Page 5