prof(1)								      prof(1)



NAME

  prof - analyze profile data

SYNOPSIS

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

  prof -pixie [ options ]

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 pro-
       gram counter.

    +  Divides the program into blocks delimited by labels, jump instruc-
       tions, 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 speak-
  ing, 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 por-
  tion is profiled.  For instance, none of the routines it calls in libc are
  profiled.  To profile all library routines a program uses, build the pro-
  gram 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 suf-
  fix .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 .Addrs and .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 pro-
      gram, 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.

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:

  -asm
      Use 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 speci-
      fied 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 informa-
      tion that the compiler system can use to decide what parts of the pro-
      gram will benefit most from global optimization and what parts will
      benefit most from in-line procedure substitution (requires basic-block
      counting).

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

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

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

  -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 "%"
      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%" trun-
      cates 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.

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

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

RELATED INFORMATION

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