Operation and Use, Volume 2, Part 2 Profiling
This appendix contains the manual pages for the PE tools commands discussed
throughout this book. Each manual page is organized into the sections
listed below. The sections always appear in the same order, but some
appear in all manual pages while others are optional.
- NAME
- Provides the name of the command described in the manual page, and a brief
description of its purpose.
- SYNOPSIS
- Includes a diagram that summarizes the command syntax, and provides a
brief synopsis of its use and function. If you are unfamiliar with the
typographic conventions used in the syntax diagrams, see "Typographic Conventions".
- FLAGS
- Lists and describes any required and optional flags for the
command.
- DESCRIPTION
- Describes the command more fully than the NAME and
SYNOPSIS sections.
- ENVIRONMENT VARIABLES
- Lists and describes any applicable environment variables.
- EXAMPLES
- Provides examples of ways in which the command is typically used.
- FILES
- Lists and describes any files related to the command.
- RELATED INFORMATION
- Lists commands, functions, file formats, and special files that are
employed by the command, that have a purpose related to the command, or that
are otherwise of interest within the context of the command.
NAME
xprofiler - Invokes the Xprofiler, a GUI-based performance
profiling tool.
SYNOPSIS
xprofiler [program] [-b] [-h]
[-s] [-z] [-a] [-c]
[-L pathname]
[[-e name]...]
[[-E name]...]
[[-f name]...]
[[-F name]...]
[-disp_max number_of_functions]
[[gmon.out]...]
The xprofiler command invokes the Xprofiler, a GUI-based
performance profiling tool.
FLAGS
- -b
- Suppresses the printing of the field descriptions for the Flat Profile,
Call Graph Profile, and Function Index reports when they are written to a file
with the Save As option of the File menu.
- -s
- Produces the gmon.sum profile data file, if multiple
gmon.out files are specified when Xprofiler is started.
The gmon.sum file represents the sum of the profile
information in all the specified profile files. Note that if you
specify a single gmon.out file, the gmon.sum
file contains the same data as the gmon.out file.
- -z
- Includes functions that have both zero CPU usage and no call counts in the
Flat Profile, Call Graph profile, and Function Index reports. A
function will not have a call count if the file that contains its definition
was not compiled with the -pg option, which is common with system
library files.
- -a
- Adds alternative paths to search for source code and library files, or
changes the current path search order. When using this command line
option, you can use the "at" symbol (@) to represent the default file
path, in order to specify that other paths be searched before the default
path.
- -c
- Loads the specified configuration file. If the -c option
is used on the command line, the configuration file name specified with it
will appear in the Configuration File (-c): text field in the
Load Files Dialog, and the Selection field of the
Load Configuration File Dialog. When both the -c
and -disp_max options are specified on the command line, the
-disp_max option is ignored, but the value that was specified with
it will appear in the Initial Display (-disp_max): field in the
Load Files Dialog, the next time it is opened.
- -disp_max
- Sets the number of function boxes that Xprofiler initially displays in the
function call tree. The value supplied with this flag can be any
integer between 0 and 5,000. Xprofiler displays the function boxes for
the most CPU-intensive functions through the number you specify. For
instance, if you specify 50, Xprofiler displays the function boxes for the 50
functions in your program that consume the most CPU. After this, you
can change the number of function boxes that are displayed via the Filter menu
options. This flag has no effect on the content of any of the Xprofiler
reports.
- -e
- De-emphasizes the general appearance of the function box(es) for the
specified function(s) in the function call tree, and limits the number of
entries for these function in the Call Graph Profile report. This also
applies to the specified function's descendants, as long as they have not
been called by non-specified functions.
In the function call tree, the function box(es) for the specified
function(s) appears greyed-out. Its size and the content of the label
remain the same. This also applies to descendant functions, as long as
they have not been called by non-specified functions.
In the Call Graph Profile report, an entry for the specified function only
appears where it is a child of another function, or as a parent of a function
that also has at least one non-specified function as its parent. The
information for this entry remains unchanged. Entries for descendants
of the specified function do not appear unless they have been called by at
least one non-specified function in the program.
- -E
- Changes the general appearance and label information of the function
box(es) for the specified function(s) in the function call tree. Also
limits the number of entries for these functions in the Call Graph Profile
report, and changes the CPU data associated with them. These results
also apply to the specified function's descendants, as long as they have
not been called by non-specified functions in the program.
In the function call tree, the function box for the specified function
appears greyed-out, and its size and shape also changes so that it appears as
a square of the smallest allowable size. In addition, the CPU time
shown in the function box label, appears as 0 (zero). The same applies
to function boxes for descendant functions, as long as they have not been
called by non-specified functions. This option also causes the CPU time
spent by the specified function to be deducted from the left side CPU total in
the label of the function box for each of the specified function's
ancestors.
In the Call Graph Profile report, an entry for the specified function only
appears where it is a child of another function, or as a parent of a function
that also has at least one non-specified function as its parent. When
this is the case, the time in the self and descendants
columns for this entry is set to 0 (zero). In addition, the amount of
time that was in the descendants column for the specified function
is subtracted from the time listed under the descendants column for
the profiled function. As a result, be aware that the value listed in
the % time column for most profiled functions in this report will
change.
- -f
- De-emphasizes the general appearance of all function boxes in the function
call tree, except for that of the specified function(s) and its
descendant(s). In addition, the number of entries in the Call Graph
Profile report for the non-specified functions and non-descendant functions is
limited. The -f flag overrides the -e
flag.
In the function call tree, all function boxes except for that of
the specified function(s) and it descendant(s) appear greyed-out. The
size of these boxes and the content of their labels remain the same.
For the specified function(s), and it descendants, the appearance of the
function boxes and labels remain the same.
In the Call Graph Profile report, an entry for a non-specified or
non-descendant function only appears where it is a parent or child of a
specified function or one of its descendants. All information for this
entry remains the same.
- -F
- Changes the general appearance and label information of all function boxes
in the function call tree except for that of the specified
function(s) and its descendants. In addition, the number of entries in
the Call Graph Profile report for the non-specified and non-descendant
functions is limited, and the CPU data associated with them is changed.
The -F flag overrides the -E flag.
In the function call tree, the function box for the specified function
appears greyed-out, and its size and shape also changes so that it appears as
a square of the smallest allowable size. In addition, the CPU time
shown in the function box label, appears as 0 (zero).
In the Call Graph Profile report, an entry for a non-specified or
non-descendant function only appears where it is a parent or child of a
specified function or one of its descendants. The time in the
self and descendants columns for this entry is set to 0
(zero). When this is the case, the time in the self and
descendants columns for this entry is set to 0 (zero). As a
result, be aware that the value listed in the % time column for
most profiled functions in this report will change.
- -L
- Uses an alternate path name for locating shared libraries. If you
plan to specify multiple paths, use the Set File Search Path option
of the File menu on the Xprofiler GUI.
- -h
- Prints basic Xprofiler command syntax to the screen.
DESCRIPTION
Xprofiler is a GUI-based performance profiling tool, which can be used to
analyze the performance of sequential as well as parallel programs.
Xprofiler provides graphical function call tree display and textual profile
reports to help you understand your program's CPU usage and function call
counts information.
EXAMPLES
To use xprofiler, you first compile your program (for example,
foo.c) with -pg:
xlc -pg -o foo foo.c
When the program foo is executed, one gmon.out
file will be generated for each processor involved in the execution. To
invoke xprofiler, enter:
xprofiler foo [[gmon.out]...]
FILES
/usr/lib/X11/app-defaults/Xprofiler
RELATED INFORMATION
Commands: gprof(1), xlc(1), xlf(1)
[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]