Chapter 7: Viewing Error Messages
There are two ways to view the error reports that ZeroFault
generates. By default, ZeroFault creates a graphical user interface
(GUI) to display the errors generated for each session. In addition,
the zf_rpt command can be used to generate an ASCII text
version of the error report.
The ZeroFault Graphical User Interface
ZeroFault creates a graphical user
interface to display the error messages if the
DISPLAY environment
variable is set or if the -d
option is specified. The user interface can be disabled by
specifying -d none.
If either of the above conditions are met, ZeroFault creates an instance
of the GUI for each invocation of ZeroFault. ZeroFault also creates
a new GUI to display the output of any forked child of
a process if the -c
option is specified on the command line.
Finally, ZeroFault creates a new GUI for each
program loaded by an exec call if the
-e
option is specified on the command line.
It is important to understand the flow of the program being debugged,
to know whether it calls fork or exec, and to decide
whether you want ZeroFault to "follow" the forks and execs and create
new GUIs for them. Normally, when a program calls exec its
execution is considered terminated, and the new program takes over
if the exec succeeds. The
-e
flag allows you to continue running ZeroFault against any programs that
are loaded by the initial debugged program.
You can also run a ZeroFault GUI from the command line to view the
contents of any ZeroFault output
file. An output file is created for every ZeroFault instance; it
contains the full error report and any other information about the
debugging session.
To start the ZeroFault GUI from the command line, enter:
zf_ui <zf_out_file>
where <zf_out_file> is the name of the ZeroFault
output file. Various options that affect the appearance and behavior
of the user interface can be specified using
X-Windows resources.
Error Message Appearance
ZeroFault displays errors in an outline form in the GUI's main
error pane (the one with the white background). By default, errors
are initially shown in a summary (collapsed) form, with a
right-pointing arrow icon at the beginning of each error message.
Clicking the left mouse button on a message line makes the GUI
expand the message into its detail form, showing the relevant memory
location, tracebacks, etc. Clicking again on the line collapses the
message back to its summary form. The error tracebacks are also
shown in summary form, and can be expanded and collapsed in the same
way.
You can alter the appearance of the error message display by
selecting different message sorting and grouping criteria.
As the program executes and messages are generated, ZeroFault
continually updates the display according to these criteria.
Error Message Sorting
The order in which error messages are displayed is determined by
the criteria selected in the Sort By menu in the error message
pane. There are four different sorting criteria, as follows:
Error Message Grouping
In order to present the errors in a more usable format, ZeroFault
can condense similar error messages into a
single line of output in the error pane. Groups of condensed
messages are signified by a double-arrow icon on the left side of the line.
To view individual errors in a condensed group, click the left
mouse button anywhere on the condensed group. This "peels off" and
expands a message from the group of similar messages. To collapse an
expanded message and condense it back into a group of similar
messages, click the left button anywhere on its first line.
You can specify the criteria that ZeroFault uses to condense
messages using the following options on the Condense By
menu:
- None
Performs no grouping and shows all errors in the error message display
pane.
- Module
Groups errors generated by statements within the same program module.
Modules consist of the debugged executable itself, any shared
libraries that were loaded with it, and any dynamically loaded modules that it
explicitly loaded.
- Source File
Groups errors generated by statements within the same source file.
This is useful for a functional view of the detected errors if
the application's source files map to a functional grouping of the application.
- Function
Groups errors
detected within the same function; this is the default option.
- Error Location
Groups errors by the exact instruction where the error occurred.
- Complete Traceback
Groups errors by the full traceback of where the error occurred.
Error Message Filtering
ZeroFault allows you to specify certain error messages that
you don't want displayed. For example, you may choose to filter
out error messages for modules over which you have no control.
The unwanted messages are specified using the
filter list, which can be manipulated in a number of ways.
The Message Filters menu contains several options that affect
error filtering; the menu is shown below with the Disable Filtering
and Discard Filtered Messages toggle buttons disabled, which is
their default state:
These options, and other means of modifying the filter list, are described
in the following sections.
Adding an error to the filter list
Error messages can be hidden from view by adding them to the filter
list. If you want to add many errors at once, it may be best to directly
edit the filter list. To add an
individual error to the filter list, click anywhere on it with
the right mouse button to bring up the error message popup menu.
The error type and location is listed at the top of the menu, which
contains the following options:
- Add to Filter List
Adds the error message to the list of errors to suppress. Note that
ZeroFault does not prevent you from adding duplicate errors to the
filter list.
- Add and Apply
Adds the error message to the list and immediately
applies the new filter rule, causing the message to disappear
from the error pane.
The accelerator for this menu option is Ctrl-Left Mouse Button.
- Show Source
Displays the source related to the selected error.
The accelerator for this menu option is Shift-Left Mouse Button.
Editing the filter list
Selecting the Edit Filter List option from the Message
Filters menu brings up a
window
that allows you to
directly edit the
filter file.
The syntax for the filter file entries is:
# <comment>
<error type> <location>
Error type can be any of the
error type abbreviations
(UMR, BMW, etc.). The error type can also be
"ANY", which matches any error.
Location specifies the location at which an error must occur in order
to be suppressed. Location can be specified in any of the following forms:
Errors are suppressed that match any filter list entry's
error type and location.
If the location is a function then the function name may be
specified as an extended regular expression enclosed in single quotes (').
Refer to the AIX reference for the egrep command
for further information on extended regular expressions.
An example filter file is:
ANY module libXt.a
BMR function foo +0x10
WNULL anywhere
UMR file myfile1.c:20
UMR function '^str.*|^mem.*'
USTKR file myfile2.c
This file causes ZeroFault to suppress the following errors:
- Any errors that occur in the libXt.a module.
- BMR errors that occur at the instruction at offset 0x10
in function foo.
- WNULL errors that occur anywhere.
- UMR errors that occur at line 20 in file myfile1.c.
- UMR errors that occur in any function whose name begins with
str or mem.
- USTKR errors that occur anywhere in file myfile2.c.
If you directly select
errors for the filter list while the filter
list edit window is open, ZeroFault will update the window with your selections.
A filter list may be saved, applied to the current error messages,
or loaded from a previously-saved filter list file.
For example, to start a ZeroFault session on a target application with
a filter list which was created from a previous session:
- Start ZeroFault with the target application.
- Select the Edit Filter List menu item.
- Press the Load button.
- Select the appropriate file from the file selection dialog.
- Press the Apply button.
If ZeroFault detects an error in the filter list, it will display
a warning dialog box.
Temporarily turning off filtering
You can toggle filtering on or off by selecting the Disable Filtering
toggle button in the Message Filters pulldown menu.
Discarding Messages
Even when messages are filtered, they still are retained by the GUI
by default, and may be viewed by removing them from the filter
list. You may choose instead to discard filtered messages.
Discard messages as they are filtered by selecting the Message Filters
pulldown menu and turning on the Discard Filtered Messages toggle
button.
Discard all currently displayed messages (including any which were filtered
and not displayed) by selecting the Discard Current Messages menu
item from the Message Filters pulldown menu.
Saving Messages
You can save error messages to an ASCII
format output file in two ways: fully expanded and currently displayed.
To create an output file that contains the fully expanded error messages,
select the Save Expanded option from the File pulldown menu.
If you select the Save option then the file will contain the messages
as they currently appear on the screen.
Generating Text Reports
The zf_rpt command converts a
ZeroFault output file to an
ASCII version
suitable for text manipulation or editing.
The syntax is:
zf_rpt [<options>] <filename>
The flag options are:
-t
Creates single-line terse output
suitable for manipulating with
text utilities such as sort and grep.
The width of the output lines and the spacing between columns are
controlled by the -w and -c flag options, respectively.
-w <width>
Controls the total line width of the output for -t
style output. The output will have no more than <width>
columns of information per line. This will often cause the stack tracebacks
to be truncated.
-c <chars>
Controls the number of characters per column and is most
useful to adjust the spacing between columns of output in terse mode with
extremely long or short function names.
The output of zf_rpt is sent to the standard output stream.
Note that error messages are not sorted or condensed when viewed
using zf_rpt; all error messages are reported, and they
appear in the order in which they occurred.
A useful way of quickly assessing the state of an application is to run
ZeroFault against it and then use zf_rpt to summarize the
error messages:
$ zf_rpt -t <output file> | sort | uniq -c | more
The output contains unique errors, one per line, with a count
of the number of duplicates preceding each message.