NAME

prof − analyze profile data

SYNOPSIS

prof [ options ] [ prog_name [ PC-sampling_data_file ... ] ]

prof −pixie [ options ]

PARAMETERS

prog_nameName of the program executable to be profiled.  This program should be compiled with the −g1, −g2, or −g3 flag to obtain more complete profiling information.  If the default symbol table level (−g0) has been used, line number information, static procedure names, and file names are unavailable to the profiling code. 

FLAGS

For each prof option, you need type only enough of the name to distinguish it from the other options.  If you do not specify any options, prof uses −procedures by default. Always specify −pixie when you process .Addrs and .Counts files. 

The prof command accepts the following options:

−asmUse this flag only with the −pixie flag.  Causes the profiler to print the assembly instructions for each subroutine along with the cycle counts for each instruction.  This output mode is similar to the −lines output. The instructions for each subroutine are printed in order; they are not sorted by cycle count.  However, the order of the subroutines themselves are sorted from highest cycle count to lowest. 

−clock megahertz
Use this flag only with the −pixie flag.  Alters the appropriate parts of the listing to reflect the clock speed of the CPU. If you do not specify megahertz, it defaults to "8.0". 

−exclude  procedure_name
If you use one or more −exclude options, the profiler omits the specified procedure and its descendents from the listing. If any option uses an uppercase "E" for "Exclude," prof also omits that procedure from the base upon which it calculates percentages. 

−feedback filename
Use this flag only with the −pixie flag.  Produces a file with information that the compiler system can use to decide what parts of the program will benefit most from global optimization and what parts will benefit most from in-line procedure substitution (requires basic-block counting). 

−heavyUse this flag only with the −pixie flag.  Reports the most heavily used lines in descending order of use (requires basic-block counting). 

−invocations
Use this flag only with the −pixie flag.  For each procedure, reports how many times the procedure was invoked from each of its possible callers (requires basic-block counting).  For this listing, the −exclude and −only options apply to callees, but not to callers. 

−linesUse this flag only with the −pixie flag.  Similar to −heavy, but gives the lines in order of occurrence. 

−merge filename
Sums the PC-sampling data files (or, in pixie mode, the .Counts files) and writes the result into a new file with the specified name. The −only and −exclude options have no affect on the merged data. 

−only  procedure_name
If you use one or more −only options, the profile listing includes only the named procedures, rather than the entire program. If any option uses an uppercase "O" for "Only," prof uses only the named procedures, rather than the entire program, as the base upon which it calculates percentages. 

−pixieSelects pixie mode, as opposed to PC-sampling mode. 

−procedures
Reports time spent per procedure (using data obtained from PC-sampling or basic-block counting; the listing tells which one). For basic-block counting, this option also reports the number of invocations per procedure.

−quit nTruncates the −procedures and −heavy listings. It can truncate after n lines (if n is an integer), after the first entry that represents less than n percent of the total (if n is followed immediately by a "%" character), or after enough entries have been printed to account for n percent of the total (if n is followed immediately by "cum%").  For example, "−quit 15" truncates each part of the listing after 15 lines of text, "−quit 15%" truncates each part after the first line that represents less than 15 percent of the whole, and "−quit 15cum%" truncates each part after the line that brought the cumulative percentage above 15 percent. 

−testcoverage
Use this flag only with the −pixie flag.  Reports all lines that never executed (requires basic-block counting). 

−truecycles [0,1,2]
Use this flag only with the −pixie flag.  Generates more analysis of a program to provide a more accurate reading of cycles. The higher the number chosen from the arguments, the more accurate the reading, although the profiler will run slower. This flag is valid only in −pixie mode. 

−zeroUse this flag only with the −pixie flag.  Prints a list of procedures that were never invoked (requires basic-block counting). 

DESCRIPTION

The prof command analyzes one or more data files generated by the compiler’s execution-profiling system and produces a listing.  The prof command can also combine those data files or produce a feedback file that lets the optimizer take into account the program’s run-time behavior during a subsequent compilation.  Profiling is a three-step process:

     1.Compile the program

     2.Execute the program

     3.Run prof to analyze the data. 

The compiler system provides two kinds of profiling:

       •Interrupts the program periodically, recording the value of the program counter. 

       •Divides the program into blocks delimited by labels, jump instructions, and branch instructions. It counts the number of times each block executes. This provides more detailed (line by line) information than PC-sampling. 

PC-Sampling

To use PC-sampling, compile your program with the −p flag (strictly speaking, it is sufficient to use this flag only when linking the program). Then run the program, which allocates extra memory to hold the profile data, and (provided the program terminates normally or calls exit(2)) records the data in a file at the end of execution. 

Note that, if your program uses shared libraries, only its call-shared portion is profiled.  For instance, none of the routines it calls in libc are profiled.  To profile all library routines a program uses, build the program with the −non_shared switch.  (By default, the compiler produces a call-shared object unless −non_shared is explicitly specified.) 

After running your program, use prof to analyze the PC-sampling data file.  For example:

cc -c myprog.c
cc -p -o myprog myprog.o
myprog   (generates mon.out)
prof myprog mon.out

When you use prof for PC-sampling, the program name defaults to a.out unless you have used the −o flag with the cc command to name an output file.  The PC-sampling data file name defaults to mon.out; if you specify more than one PC-sampling data file, prof reports the sum of the data. 

Basic-Block Counting

To use basic-block counting, compile your program without the option −p. Use the pixie program to translate your program into a profiling version and generate a file, whose name consists of your program name with the suffix .Addrs.  This file contains block addresses. Then run the pixie version of the program, which (assuming the program terminates normally or calls exit(2)) will generate a file, whose name ends in .Counts, containing block counts. 

After running the pixie version of your program, use prof with the −pixie flag to analyze the .Addrsand .Counts files. Notice that you must tell prof the name of your original program, not the name of the pixie version. For example:

cc -c myprog.c
cc -o myprog myprog.o
pixie myprog (generates myprog.Addrs and myprog.pixie)
myprog.pixie (generates myprog.Counts)
prof -pixie myprog myprog.Addrs myprog.Counts

When you use prof with the −pixie option, the .Addrs file name defaults to program_name.Addrs, and the .Counts file name defaults to program_name.Counts. If you specify more than one .Counts file, prof reports the sum of the data.  Never specify more than one .Addrs file. 

Environment Variables

You can use environment variables to change the default profiling behavior.  The variables are PROFDIR and PROFFLAGS. The general form for setting these variables is:

   For C shell:  setenv varname  "value"
   For Bourne shell: varname = "value"; export  varname

In the preceding example, varname can be one of the following:

PROFDIR
This environment variable causes PC-sampling data files to be generated with unique file names in a specified directory. You specify a directory path as the value and your prof results are placed in the file path/pid.progname where path is the pathname, pid is the process of the executing program, and progname is the program name. 

PROFFLAGS
This environment variable, when set to −threads, as the value, 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. 

You can use the PROFDIR and PROFFLAGS environment variables together. For more information, see the Programmer’s Guide. 

FILES

crt0.onormal startup code

mcrt0.ostartup code for PC-sampling

libprof1.alibrary for PC-sampling

mon.outdefault PC-sampling data file

RELATED INFORMATION

as(1), cc(1), gprof(1), pixie(1), profil(2), monitor(3)
Programmer’s Guide