prof Command

Purpose

Displays object file profile data.

Syntax

prof [ -t | -c | -a | -n ] [ -o | -x ] [ -g ] [ -z ] [ -h ] [ -s ] [ -S ] [ -v ] [ -L PathName ] [ Program ] [ -m MonitorData ... ]

Description

The prof command interprets profile data collected by the monitor subroutine for the object file Program (a.out by default). It reads the symbol table in the object file Program and correlates it with the profile file (mon.out by default). The prof command displays, for each external text symbol, the percentage of execution time spent between the address of that symbol and the address of the next, the number of times that function was called, and the average number of milliseconds per call.

Note: Symbols from C++ object files have their names demangled before they are used.

To tally the number of calls to a function, you must have compiled the file using the cc command with the -p flag. The -p flag causes the compiler to insert a call to the mcount subroutine into the object code generated for each recompiled function of your program. While the program runs, each time a parent calls a child function the child calls the mcount subroutine to increment a distinct counter for that parent-child pair. Programs not recompiled with the -p flag do not have the mcount subroutine inserted and therefore keep no record of which function called them.

The -p flag also arranges for the object file to include a special profiling startup function that calls the monitor subroutine when the program begins and ends. The call to the monitor subroutine when the program ends actually writes the mon.out file. Therefore, only programs that explicitly exit or return from the main program cause the mon.out file to be produced.

Note: To change the name of the generated output file, use the PROF environment variable and set it as follows:

PROF=filename:<filename>

For example, if you set PROF=myprof, then the generated file will be named as myprof.out.

The location and names of the objects loaded are stored in the mon.out file. If you do not select any flags, prof will use these names. You must specify a program or use the -L option to access other objects.

Note: Imported external routine calls, such as a call to a shared library routine, have an intermediate call to local glink code that sets up the call to the actual routine. If the timer clock goes off while running this code, time is charged to a routine called routine.gl, where routine is the routine being called. For example, if the timer goes off while in the glink code to call the printf subroutine, time is charged to the printf.gl routine.

Flags

The mutually exclusive flags a, c, n, and t determine how the prof command sorts the output lines:

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

Note: The prof command can still run successfully if you use more than one of flags a, c, n, and t in the same command. The prof command accepts the first of these flags it encounters on the command line and ignores the others.

The mutually exclusive flags o and x specify how to display the address of each symbol monitored.

Item	Description
-o	Displays each address in octal, along with the symbol name.
-x	Displays each address in hexadecimal, along with the symbol name.

Note: The prof command can still run successfully if you use both the -o and -x flags in the same command. The prof command accepts the first of these two flags it encounters on the command line and ignores the other flag.

Use the following flags in any combination:

Item	Description
-g	Includes non-global symbols (static functions).
-h	Suppresses the heading normally displayed on the report. This is useful if the report is to be processed further.
-L PathName	Uses alternate path name for locating shared objects.
-m MonitorData	Takes profiling data from MonitorData instead of mon.out.
-s	Produces a summary file in mon.sum. This is useful when more than one profile file is specified.
-S	Displays a summary of monitoring parameters and statistics on standard error.
-v	Suppresses all printing and sends a graphic version of the profile to standard output for display by the plot filters. When plotting, low and high numbers, by default 0 and 100, can be given to cause a selected percentage of the profile to be plotted with accordingly higher resolution.
-z	Includes all symbols in the profile range, even if associated with 0 (zero) calls and 0 (zero) time.

Examples

To display, without a header, the amount of time spent at each symbol address, sorted by time, enter:
```
prof -t -h
```
The following example obtains a local version of any shared libraries used to create the runfile file in the /home/score/lib directory. The data file used will be runfile.mon rather than mon.out.
```
prof -x -L/home/score/lib runfile -m runfile.mon
```

Files

Item	Description
mon.out	Default profile.
a.out	Default object file.
mon.sum	Summary profile.