*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> hiprof (1)              



NAME    [Toc]    [Back]

       hiprof  -  CPU-time and page-fault call-graph profiler for
       performance analysis

SYNOPSIS    [Toc]    [Back]

       hiprof [-flat] [-pthread  |  -threads]  [hiprof-option...]
       [gprof-option...] program [argument...]

       hiprof  { -cycles  | -faults  } [hiprof-option...] [gprofoption...]
 program [argument...]

       See the start of the OPTIONS section for details of hiprof
       options that may be essential for the correct execution of
       the program.

       The atom -tool hiprof interface is  still  available,  for
       compatibility  with  earlier  releases. However, it is now
       undocumented, and it will be retired in a future  release.

DESCRIPTION    [Toc]    [Back]

       See  prof_intro(1)  for an introduction to the application
       performance tuning tools provided with Tru64 UNIX.

       The hiprof command creates an instrumented  version  of  a
       program (program.hiprof) that produces call-graph and flat
       profiles of one of a range of performance statistics:  The
       CPU  time  spent  in  each  procedure (or optionally, each
       source line or instruction), measured by sampling the program
 counter about every millisecond (the default) The CPU
       time spent in each procedure and procedure call,  measured
       as  machine  cycles,  including the effects of any memoryaccess
 delays (with the -cycles option) The number of page
       faults that occur during each procedure and procedure call
       (with the -faults option)

       See the limitations of each performance statistic  in  the
       RESTRICTIONS section below.

       If  you  specify program arguments (argument...)  or -run,
       the instrumented program is also executed.

       If you specify -display or any of the  gprof-options,  the
       hiprof command runs the instrumented program and then displays
 the profile by running  the  gprof  tool  (with  any
       specified gprof-options).

       If  you omit the program name, a usage message is printed.

       The following example shows how to  instrument,  run,  and
       display  the  profile  for a multithreaded program: cc *.c
       -pthread -L. -g1  -O2  -o  program  -lapp1  -lapp2  hiprof
       -pthread -L. -all program data/*

       The  -all option request that all shared libraries be profiled,
 but  threads-related  system  libraries  cannot  be
       safely  instrumented  to  count  procedure  calls that are
       needed to print a call graph. By default, these  libraries
       are  still  sampled to provide flat CPU-time profiles. The
       -cycles and -faults options cannot be used  with  threaded
       programs, but the displayed time or page-fault count for a
       procedure includes the time or count  for  any  procedures
       that   it   calls   but   that   were   not  selected  for
       instrumentation--for example, any procedures in  libraries
       not  selected  by  the -all or -incobj options. This means
       that time is not lost from  these  profiles  by  excluding
       shared libraries.

OPERANDS    [Toc]    [Back]

       File  name of a fully linked call-shared or nonshared executable
 to be profiled. This program  should  be  compiled
       with  the  -g or -gn option (n>=1) to obtain more complete
       profiling information. If the default symbol  table  level
       (-g0)  is  used, line number information, static procedure
       names, and file names are unavailable.  Inlined  procedure
       calls  are  also unavailable.Programs that are stripped or
       are optimized by spike or cc -om are not  supported.   All
       arguments  following the program name are considered to be
       arguments needed by the instrumented  program  to  execute
       the  procedures, lines, and instructions of interest. Multiple
 arguments can be specified. They imply -run  if  any
       are  specified,  and  they can be replaced by -run if none
       are needed.

OPTIONS    [Toc]    [Back]

       Options can be abbreviated to three characters. The gprofoptions,
  which  are provided as alternatives to the -display
 option, can be abbreviated to one character.

       For options that specify a procedure name (proc), C++ procedures
  can omit the argument type list, though this will
       match all overloaded procedures with that name. To  select
       a  specific  procedure,  specify  the full symbol name (as
       printed  by  the  nm  command).  Symbol  names  containing
       spaces, asterisks, and so on must be quoted.

   Essential Options    [Toc]    [Back]
       Some  or all of these options may be needed to prevent the
       instrumented program from malfunctioning: Specify -pthread
       if  the program or any of its libraries calls pthread_create(3) (for example, if it was compiled  with  either  the
       -pthread  option  or  the  -threads compatibility option).
       This will make the collection of profile data thread-safe.
       The -fork option is maintained for compatibility with earlier
 releases. By default,  hiprof  now  profiles  subprocesses
  that  do  not  call exec(2), and produces separate
       profiling data files for the forked subprocesses,  including
  the  process  id  in their file names as if -pids was
       specified.  By default, the hiprof  code  running  in  the
       program's  process  allocates  memory  for  its own use at
       address 38000000000. If the program needs  to  use  memory
       between  38000000000  and 3ff00000000, specify the address
       that the hiprof code  should  use.   Specify  -sigdump  to
       force  the  instrumented program to write the current profile
 data to its file(s) on receipt of the  named  signal.
       By  default, the program writes the profiling data file(s)
       only when the process terminates, but some processes never
       terminate  normally,  so this option lets you generate the
       file(s) on demand. After a file is written,  the  instruction
  counts  of  the  profile  are all set to zero; so by
       sending two signals, any interval of a  test  run  can  be
       profiled, with the second signal's file(s) overwriting the
       first. For example, to use the default kill pid command to
       signal the program, specify -sigdump TERM. Choose a signal
       that the program does not use for another purpose.

   Profiling Statistics Options    [Toc]    [Back]
       Generates a flat profile; that is, it  avoids  the  intrusiveness
 of collecting the default call-graph information.
       If the -display option is specified, it defaults to  gprof
       -procedures.  Do not use the -flat option with the -cycles
       or -faults options.  Profiles CPU  time  by  counting  the
       machine  cycles  used  in  each  procedure  call. Use this
       option only  for  non-threaded  programs.   Profiles  page
       faults  that  occur  during  each procedure instead of the
       default time spent in each  procedure.   Use  this  option
       only for nonthreaded programs.

   File Generating Options    [Toc]    [Back]
       Does  not print informational and progress messages on the
       standard error stream.  Prints the command lines  used  to
       instrument  the  program  and  to execute the instrumented
       program. Prints the names of any procedures that were  not
       instrumented.  Names the instrumented program file instead
       of the default program.hiprof.  Specifies the directory to
       which  the  instrumented program writes the profiling data
       file(s) for each test run.  The  default  is  the  current
       directory.   Adds  the process-id of the instrumented program's
 test run to the name of  the  profiling  data  file
       produced  (that  is,  program.pid.hiout).  By default, the
       file is named program.hiout.  When  profiling  a  threaded
       program,  specify  -threads  to produce a separate profile
       for each pthread in the program. The files are named  program[.pid].sequence.hiout,
  where  sequence  is the thread
       sequence  number  assigned   by   pthread_create(3).   The
       -threads  option  implies the -pthread option. If -sigdump
       is needed, -pthread is recommended instead of -threads, to
       avoid possible synchronization problems.

   Shared-Library Profiling Options    [Toc]    [Back]
       Profiles  all  of  the shared libraries in addition to the
       program's executable.  If -all  was  specified,  does  not
       profile the shared library lib. Can be repeated to exclude
       multiple libraries.  Profiles the shared library lib.  Can
       be  repeated  to include multiple libraries.  Searches for
       shared-libraries in the specified directory before searching
  the  default  directories.  Can be repeated to make a
       search path. Use the same  options  that  were  used  when
       linking the program with ld.  Does not instrument the procedure
 proc. This option can be used to exclude procedures
       that  are uninteresting or that interfere with the instrumentation
 (such as nonstandard assembly code).

   Execution Control Options    [Toc]    [Back]
       Prints the tool's version number.   Executes  the  instrumented
  program,  even  if  no arguments are specified. By
       default, the program is only instrumented (for later  execution).
   Executes  the  instrumented  program,  and runs
       gprof with default options on the resulting file(s).  Executes
  the  instrumented  program,  and  runs gprof on the
       resulting file(s). The following gprof  options  are  supported:
  Profiles  each instruction within selected procedures.
  Does not report on  called  procedures.   Excludes
       procedure  proc  and its descendants from the profile, but
       totals all procedures.  Includes only procedure  proc  and
       its descendants in the profile, but totals all procedures.
       Profiles procedures as an indexed  call  graph  (default).
       Profiles  source  lines,  listing  the  most  heavily used
       first.  Profiles source lines, in  order  within  selected
       procedures.   Merges  all  input  files into file.  Prints
       each   procedure's   starting   line   number.    Profiles
       procedures, listing the most heavily used first (default).
       Profiles the whole executable and  any  shared  libraries.
       Reports procedures that were never called.

NOTES    [Toc]    [Back]

       If   hiprof   finds  any  previously  instrumented  shared
       libraries in the working directory, it will reuse them  if
       they  meet current requirements, to reduce re-instrumentation

       Temporary instrumentation files are created in /tmp.   Set
       the  TMPDIR  environment variable to a different directory
       to create the files elsewhere, for example, in a disk partition
 with more space.

RESTRICTIONS    [Toc]    [Back]

       The  default  sampled  profile only estimates the CPU time
       spent in each  procedure  call;  profiles  made  with  the
       -cycles and -faults options measure it.

       When  timing  a  program's procedures by measuring machine
       cycles (with the -cycles option), the 32-bit  cycle-counting
  hardware  will wrap if no procedure call or return is
       executed by the program every few seconds -- for  example,
       because  of a long-running loop. If the counter wraps, the
       profile will be  incorrect.  Using  the  -all  or  -incobj
       options  to profile all nonsystem libraries and procedures
       can help avoid this restriction.

       The -cycles option generates an inaccurate profile if  the
       instrumented  program  is run on a system whose processors
       have  different  cycle  speeds.  This  inaccuracy  can  be
       avoided by using hiprof's default sampling profiler or the
       cc -p/-pg profilers instead, or by running the application
       on  a  subset of the processors: Select a single processor
       using the runon command.  Check the processor speeds using
       the  psrinfo  -v command and run the application in a processor
 set comprising only processors that run at the same
       speed (see processor_sets(4)).

       Approximate  performance estimates are as follows but will
       vary according to the application and  the  machine's  CPU
       count,  type,  and  clock rate. The hiprof instrumentation
       takes ~2s per Mb of program file on a 500-MHz EV6  (21264)
       Alpha  system,  using ~10 Mb of memory plus another ~10 Mb
       per Mb of the largest file.  The  instrumented  files  are
       ~20% larger than the originals, plus ~1 Mb of hiprof code.
       They run ~4 times slower. By default,  each  profile  data
       file  is  at  least the size of the instrumented code (and
       uses this much memory), but these files are very small for
       the -cycles and -faults options.

       If a procedure contains interprocedural branches or interprocedural
 jumps, that procedure will not be  instrumented
       with  the  -cycles  or  -faults option, and no information
       will be reported about that procedure. Use the  -v  option
       to  see  which procedures were not instrumented. Compilers
       can optimize return statements or  non-returning  function
       calls  to  interprocedural branches. To avoid this, recompile
 with the -O0 or -no_inline option.

FILES    [Toc]    [Back]

       Instrumented version of program produced by hiprof Profile
       data  file  produced by program.hiprof Instrumented shared
       libraries produced by hiprof Temporary  file  created  and
       deleted in the current and -dirname path directories.

SEE ALSO    [Toc]    [Back]

       Introduction: prof_intro(1)

       atom(1),  cc(1),  dxprof(1),  fork(2),  gprof(1), kill(1),
       ld(1),    pixie(1),     processor_sets(4),     psrinfo(1),
       pthread(3),  runon(1),  uprofile(1).  (dxprof is available
       as an option.)

       Programmer's Guide

[ Back ]
 Similar pages
Name OS Title
lpana HP-UX display LP spooler performance analysis information
prof_intro Tru64 Introduction to application profilers, profiling, optimization, and performance analysis
gprof HP-UX display call graph profile data
gprof NetBSD display call graph profile data
gprof OpenBSD display call graph profile data
gprof Linux display call graph profile data
gprof Tru64 Displays call-graph profile data
gprof FreeBSD display call graph profile data
timerhndlr IRIX call a procedure at a given time
hwgraph IRIX hardware graph and hardware graph file system
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service