hpc(1)
NAME
hpc − histogram program counter
SYNOPSIS
hpc [−brief]
[−exclude regular_expression]
[−include regular_expression]
[−interval n]
[−limit n]
[−map]
[−nhdr]
[−stop_on_repeat]
[−library regular_expression]
target_process_specifier where target_process_specifier is [ −existing process_specifier [−executable pathname] |
[−invoke] binary_name [arguments] |
−child_of process_specifier |
[−datafile pathname]
]
DESCRIPTION
hpc (Histogram Program Counter), part of the HP/PAK performance analysis kit, looks at the performance of programs at the statement level. hpc works only on programs that have been compiled with the -g option. While your program is executing, hpc samples the program counter at regular intervals. For each sample it takes, hpc records the source line number of the program statement that is executing. (The −g compile option embeds the line numbers in the compiled code.) Using the −exclude and −include options, you can also select specific procedures to focus on. In this case, hpc collects only those samples that are associated with the selected procedures. hpc stops sampling the program counter when the target program stops. If you select an existing process, you can specify the −stop_on_repeat option to have hpc stop when the call stack returns to its initial state, at the start of sampling. When hpc finishes its sampling, it displays statistics and a histogram of the collected samples. Each bar corresponds to a source code statement (identified by its source line number). The length of a bar indicates the number of samples (and thus the relative execution time) for the associated source statement. An additional bar shows the sum of all source statements that appeared too infrequently to warrant a bar of their own. The target_process_specifier identifies the process associated with the program you want to monitor. This argument is required and must follow the command options. You can specify it using either of the following forms:
−existing process-specifier [−executable pathname]
Monitor the program already running in the specified process. The process-specifier can be a process ID or a unique string (such as the pathname of the process, if it is unique). HPC will return a message indicating that it has attached to the process. In addition, you can use −executable pathname to specify the location of the binaries of a running process, where pathname is an absolute path name.
[−invoke] binary-name [arguments]
Invoke the specified program, passing it the supplied arguments. The binary-name must be the full or relative pathname of the executable because hpc does not use the shell’s path checking. Note that the −invoke keyword is optional. If you omit both −invoke and −existing, hpc assumes that anything after the command options is a binary-name. If your binary-name is identical to an option name, make sure that you specify −invoke.
−child_of process-specifier
Monitor the next child process of the specified process. The process-specifier can be a process ID or a unique string (such as the pathname of the process, if it is unique). HPC will return a message indicating that waiting for the child process to start.
−datafile pathname
Analyze an existing data file, where pathname is the path name of a data file created by the dpat monitor function.
Options
If you do not specify any options, hpc produces a histogram for the entire program, with 20 samples taken per second of target execution time. The options are as follows:
−brief Produce a compact bar chart by showing one line for all the source code statements within the same procedure. By default, hpc displays one line for each source code statement in the program.
−exclude regular_expression
Exclude those procedures that match regular_expression from hpc monitoring. If you omit this option, the default is to include all procedures. If you use this option, hpc includes all procedures except for those that you exclude. When monitoring the target program, hpc discards all samples that are associated with the excluded procedure(s). You can specify this option multiple times on the same hpc command line. Note that when you exclude a procedure, you remove only that procedure from the hpc monitoring. Additional procedures called by an excluded procedure are not themselves automatically excluded. The -exclude and -include options are mutually exclusive. You cannot specify both on the same hpc command.
−include regular_expression
Include those procedures that match regular_expression in hpc monitoring. If you omit this option, the default is to include all procedures. If you use this option, hpc includes only those procedures that you identify. When monitoring the target program, hpc collects only those samples that are associated with the included procedure(s). You can specify this option multiple times on the same hpc command line. Note that when you include a procedure, you register only that procedure with hpc. Additional procedures called by an included procedure are not themselves automatically included. The -exclude and -include options are mutually exclusive. You cannot specify both on the same hpc command.
−interval n Specify how many milliseconds (n) to let the target program run before sampling it again. (The real-time interval between samples will be longer than the specified value, due to sampling overhead.) The default is 10 milliseconds between samples (that is, 100 samples taken per second of target execution time).
−limit n Specify the lowest percentage (n) of execution time included in the histogram. The default is 1. Source code statements that appear less than the specified limit are added together and displayed in one line at the end of the histogram.
−map Generate a list of the names of the procedures in the executing program, along with their starting and ending addresses.
−nhdr Suppress all output except the histogram itself. If you plan to create and use shell scripts to perform post-processing on the HPC output, it is a good idea to turn off the header information so that the headers do not interfere with the post-processing.
−stop_on_repeat
Stop monitoring an existing process when the contents of the call stack are the same as they were at the start of monitoring. This option, which is applicable only if you use -existing in your target process specifier, allows you to monitor an interactive process’s behavior during the execution of one particular command. When the program finishes executing the command, the call stack returns to its former state.
−library regular_expression
Only initialize those shared libraries whose pathnames match regular_expression. hpc needs to initialize (i.e. digest the symbol table of) those loadable images corresponding to the portions of the program for which statistics are sought. If you omit this option, the default is to initialize the main program image only. If you use this option, hpc initializes only those libraries that you identify. When monitoring the target program, hpc collects only those samples that are found within the specified images. You can specify this option multiple times on the same hpc command line.
SEE ALSO
Hewlett-Packard Company — HP/PAK Version 6.2: May 1995