prof(1) 						      General Commands Manual							   prof(1)

Name
       prof - analyze profile data

Syntax
       prof [ options ] [ prog_name ] [ pcsampling_data_file ...  ]
       prof -pixie [ -note comment_string ] [ options ] [ prog_name [ bbaddrs_file [ bbcounts_file ...	] ] ]

Description
       The  command  analyzes  one or more data files generated by the compiler's execution-profiling system and produces a listing. Prof can also
       combine those data files or produce a feedback file that lets the optimizer take into account the program's runtime behavior during a  sub-
       sequent compilation.  Profiling is a three-step process: first compile the program, then execute it, and finally run to analyze the data.

       The compiler system provides two kinds of profiling:

	    1.	   pc-sampling interrupts the program periodically, recording the value of the program counter.

	    2.	   basic-block counting 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.

Using Pc-sampling
       To use pc-sampling, compile your program with the option -p (strictly speaking, it is sufficient to use this option 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 records the data in a file at the end of execution.

       The environment variable PROFDIR determines the name of the pc-sampling data file and determines whether pc-sampling takes place:  if it is
       not  set,  the  pc-sampling data file is named mon.out ; if it is set to the empty string, no profiling occurs; if it is set to a non-empty
       string, the file is named string/pid.progname, where pid is the process id of the executing program and progname is the program's name,	as
       it appears in argv[0]. The subdirectory string must already exist.

       After running your program, use 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  for pc-sampling, the program name defaults to a.out and the pc-sampling data file name defaults to mon.out ; if you specify
       more than one pc-sampling data file, reports the sum of the data.

Using Basic-block Counting
       To use basic-block counting, compile your program without the option -p .  Use to translate your program into a profiling version and  gen-
       erate a file, whose name ends in .Addrs, containing block addresses. Then run the profiling version, which (assuming the program terminates
       normally or calls will generate a file, whose name ends in .Counts, containing block counts.  Then use with the -pixie  option  to  analyze
       the bbaddrs and bbcounts files. Notice that you must tell the name of your original program, not the name of the profiling version.

       For example:

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

       When  you  use  with  the -pixie option, the program name defaults to a.out , the bbaddrs file name defaults to program_name.Addrs, and the
       bbcounts file name defaults to program_name.Counts. If you specify more than one bbcounts file (never specify more than one bbaddrs  file),
       reports	the  sum of the data.  -note comment_string If you use this argument, the comment_string appears near the beginning of the listing
       as a comment.

       Provided you do not use -pixie, processes mon.out files produced by earlier versions of the compiler system using the obsolete -p2  or  -p3
       options.

Options
       For  each  option,  you	need  type only enough of the name to distinguish it from the other options (usually the first character is suffi-
       cient).	Unless otherwise noted, each part of the listing operates only on the set of procedures that results from the combination  of  the
       -exclude and -only options.

       If the options you specify would neither produce a listing nor generate a file, uses -procedures plus -heavy by default.

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

       -heavy	 Reports the most heavily used lines in descending order of use (requires basic-block counting).

       -lines	 Like -heavy , but gives the lines in order of occurrence.

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

       -zero	 Prints a list of procedures that were never invoked (requires basic-block counting).

       -testcoverage
		 Reports all lines that never executed (requires basic-block counting).

       -feedback filename
		 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). See

       -merge filename
		 Sums the pc-sampling data files (or, in pixie mode, the bbcounts files) and writes the result into a new file with the  specified
		 name. The -only and -exclude options have no effect 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, uses only the named procedures, rather than the entire program, as the base  upon  which
		 it calculates percentages.

       -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, also omits that procedure from the base upon which it calculates percentages.

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

       -quit n	 Truncates  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 percent 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.
		 -quit 15cum%
		 truncates each part after the line that brought the cumulative percentage above 15 percent.

Restrictions
       The command does not yet take into account interactions among floating-point instructions.

Files
       crt0.o	    normal startup code
       mcrt0.o	    startup code for pc-sampling
       libprof1.a   library for pc-sampling
       mon.out	    default pc-sampling data file

See Also
       as(1), cc(1), pixie(1), profil(2), monitor(3)
       Guide to Languages and Programming

								       RISC								   prof(1)