fprof(1)

Synopsis

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

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:

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.

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 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.

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.

Files

References