prof(1)

prof -- display profile data

Synopsis

   prof [-t | c | a | n] [-o | x] [-g | l] [-z] [-h] [-s] [-j] [-C]
   	[-m mdata] -V [prog]

Description

The prof command interprets a profile file produced by running an executable file that has either been instrumented for profiling or has been linked with an object that was built for profiling. The symbol table in the object file (a.out by default) is read and correlated with a profile file (mon.out by default). For each external text symbol the percentage of time spent executing between the address of that symbol and the address of the next is printed, together with the number of times that function was called and the average number of milliseconds per call.

The mutually exclusive options -t, -c, -a, and -n determine the type of sorting of the output lines:

-t: Sort by decreasing percentage of total time (default).
-c: Sort by decreasing number of calls.
-a: Sort by increasing symbol address.
-n: Sort lexically by symbol name.

The mutually exclusive options -o and -x specify the printing of the address of each symbol monitored:

-o: Print each symbol address (in octal) along with the symbol name.
-x: Print each symbol address (in hexadecimal) along with the symbol name.

The mutually exclusive options -g and -l control the type of symbols to be reported. The -l option must be used with care; it applies the time spent in a static function to the preceding (in memory) global function, instead of giving the static function a separate entry in the report. If all static functions are properly located (see example below), this feature can be very useful. If not, the resulting report may be misleading.

Assume that A and B are global functions and only A calls static function S. If S is located immediately after A in the source code (that is, if S is properly located), then, with the -l option, the amount of time spent in A can easily be determined, including the time spent in S. If, however, both A and B call S, then, if the -l option is used, the report will be misleading; the time spent during B's call to S will be attributed to A, making it appear as if more time had been spent in A than really had. In this case, function S cannot be properly located.

-g: Include static (non-global) functions.
-l: Do not include static (non-global) functions (default).

The following options may be used in any combination:

-z: Include all symbols in the profile range, even if associated with zero number of calls and zero time.
-h: Suppress the heading normally printed on the report. (This is useful if the report is to be processed further.)
-s: Print a summary of several of the monitoring parameters and statistics on the standard error output.
-m mdata: Use file mdata instead of mon.out as the input profile file.
-V: Print prof version information on the standard error output.
-j: Print one table including profiling data for all profiled objects. The default behavior is to print separate listings for each object that was compiled with the -p option of the cc command.
-C: Print demangled C++ symbol names.

An object file creates a profile file if it has been link edited with the -p option of cc. This option to the cc command arranges for profiling routines defined in libprof.a to be called at the beginning and end of execution. It is the call at the end of execution that causes the system to write a profile file. The number of calls to a function is tallied if the -p option was used when the file containing the function was compiled.

The name of the file created by a profiled program is controlled by the environment variable PROFDIR. If PROFDIR is not set, mon.out is produced in the directory current when the program terminates. If PROFDIR=string, string/pid.progname is produced, where progname consists of argv[0] with any path prefix removed, and pid is the process ID of the program. If PROFDIR is set, but null, no profiling output are produced.

A single function may be split into subfunctions for profiling by means of the MARK macro [see prof(5)].

Files

mon.out: default profile file
a.out: default namelist (object) file

Usage

General.

The times reported in successive identical runs may show variances because of varying cache-hit ratios that result from sharing the cache with other processes. Even if a program seems to be the only one using the machine, hidden background or asynchronous processes may blur the data.

In rare cases, the clock ticks initiating recording of the program counter may ``beat'' with loops in a program, grossly distorting measurements. Call counts are always recorded precisely, however.

Only programs that call exit(2), or return from main() are guaranteed to produce a profile file.

The times for static functions are attributed to the preceding external text symbol if the -g option is not used. However, the call counts for the preceding function are still correct; that is, the static function call counts are not added to the call counts of the external function.

If more than one of the options -t, -c, -a, and -n is specified, the last option specified is used and the user is warned.

Notices

Timing information is not available for multiplexed threads (threads that are not bound to a lightweight process). Profiling is possible on a bound thread (one created with the THR_BOUND flag), but note that the initial thread in a process cannot be bound.

References

CC(1C++), cc(1), exit(2), lprof(1), prof(5)