Contents
Legal Notices
Chapter 1: Quick Start
Chapter 2: Introduction and Installation
Chapter 3: About Memory Analysis
Chapter 4: Finding Memory Leaks
Chapter 5: Finding Memory Errors
Chapter 6: Startup Options
Chapter 7: Viewing Error Messages
Chapter 8: Viewing Source Code
Chapter 9: Tips and Techniques
Chapter 10: Troubleshooting
Chapter 11: Obtaining Support
|
Chapter 6: Startup Options
There are several different types of options that can affect ZeroFault's behavior:
Command-Line Flag Options
-?
the command line options are printed (only).
-a <number>
The number of errors detected at a single instruction
location before error detection at that location is turned off;
the default value is 1.
An error in a tight loop might be detected thousands or millions
of times, requiring the use of significant resources to discover
that each of the errors is a duplicate and discard it. In
order to prevent this, ZeroFault can disable error detection for
an instruction once an error at that instruction has been reported
a given number of times.
Note that setting this limit to lower than the error repeat count
has no effect; therefore the -a value should always be greater
than or equal to the -r value.
-c
Creates a new user interface for each forked child process.
The errors generated by the child are displayed in the new GUI.
Errors from child processes are always written to separate output files,
one per process, regardless of whether or not the -c option is
specified.
-d <display>
The -d flag option controls which X Window System display
ZeroFault uses to display its user interface (GUI). It is commonly
used to specify a monitor other than the default on systems with
multiple monitors. It is also used to run ZeroFault on one system
and display the results on another system's monitor. The general
format for <display> is:
<HostName>:<ServerNumber>.<ScreenNumber>
For more information about the display format, refer to the X Window
System reference.
The -d option to ZeroFault overrides the DISPLAY environment
variable, which is usually set when you start the X Window System.
Note: The user interface may be disabled by specifying -d none,
which causes ZeroFault not to create a GUI.
-e
Causes ZeroFault to follow execs, creating a new instance
of ZeroFault if the process calls exec to load a new program. New
instances of the user interface are created for each new program
if the -d flag is
specified with a display value other than none or if the DISPLAY environment variable
is set when the exec occurs.
For example if the original command is zf -e aixterm, ZeroFault
will create a GUI for the aixterm process, the shell spawned by
aixterm, and all commands started by that shell in the process
of running the profile and responding to user input (you may also
need to specify the -c flag if
the program forks before it execs).
Note that this flag can be resource intensive depending on the
number of simultaneous instances of ZeroFault that result.
See also Daemons and other background
programs for a discussion of similar issues.
-f <output file name>
Specifies the output file name
that ZeroFault uses for this session. An output file is created
for every ZeroFault session, and contains all the error messages
generated during the session.
The default output file name is
derived from the debugged program name, as follows:
<program_base_name>.<run_number>.zfo
where <program_base_name> is the basename of the program
(with the directory stripped off) and <run_number> is the
first integer for which there is not an already existing output
file of this name. For instance if ZeroFault were run on the command
/bin/ls, the output file name would be ls.1.zfo; the second time
it is run, the output file name would be ls.2.zfo.
The ZeroFault output files can be viewed by using either the
ZeroFault graphical user interface zf_ui or the ASCII
report generator zf_rpt.
-l <number>
Sets the maximum length of all stack tracebacks to <number>
functions. default is 20.
-o <directory name>
Specifies the directory in which ZeroFault puts all its
output files; the default is the current working directory.
-p <search path>
The -p flag option sets the source search
path, which is where ZeroFault looks for source code files.
<search path> is a whitespace (space, tab, newline)
separated list of directories. For example:
$ zf -p "/usr/local/src /src" prog args
tells ZeroFault to look in the /usr/local/src and /src directories
to find source code files. A relative pathname is interpreted as
relative to the current working directory.
-r <repeat count>
Specifies the number of error messages ZeroFault reports
for each unique error location; the default number is 1. The error
location is defined by the entire traceback. Once the number of
errors detected at a given location reaches the repeat count, any
subsequent errors are not reported.
-s <signal number>
Sets the signal used by ZeroFault to communicate with
the GUI to the value of <signal number>; the default
is 53 (which is undefined in AIX). If the target program uses the
same signal, ZeroFault generates a warning message indicating that
there is a conflict, and does not allow the target program to install
a signal handler for this signal. In this case you should resolve
the conflict by using the -s option to redefine the signal that
ZeroFault uses to one that is unused by the program.
-u
Causes ZeroFault to inspect the target application for
unfreed memory blocks
immediately before the application exits. The unfreed blocks are
reported in the same way as are unreferenced blocks
when the GUI's Find Leaks button is used.
-v
Displays the distributionID of ZeroFault. ZeroFault displays
output similar to the following:
ZeroFault distribution 590s.6.1.0.32on64Bit.
-A
When a memory snapshot
is taken, the address of each block is a part of the information
printed out by default. Specifying the -A option causes this information
to not be listed for each block in the snapshot.
-F <n Kbytes>
Specifies the number of kilobytes of memory that ZeroFault
maintains in the heap free list before beginning to recycle freed
memory blocks. This can aid in the detection of writes to freed
memory by keeping blocks free for longer. For example:
main() { int *p1, *p2; p1=(int*) malloc(10); free(p1); p2=(int*) malloc(10); *p1=888; }
ZeroFault may not report an error for this code, since
malloc could reuse the memory block for p2 that had been allocated
and freed for p1. Thus the write and read of p1 would not
be detected as errors because the region of memory pointed to by
p1 would be allocated and available. This is a common problem
in multi-threaded programs.
Specifying -F 1024 would force ZeroFault to delay free memory
blocks until there were one megabyte in the free list (note that
when memory is recycled, it is recycled oldest block first). Thus
in the above example ZeroFault would detect the write and
read errors, since the memory returned for p2 would not be the
same block originally returned for p1.
-H <number>
The default signal for NewHeap is 55. If that signal conflicts with your
application, the -H option can be used to change ZF's NewHeap signal.
This mechanism allows you to signal your application to obtain a new logical
heap. It is the same as the "New Heap" button in the GUI. You can obtain
a logical heap in order to constrain heap reporting and garbage collection
to a sub-set of the total heap. This is particularly useful for long running
applications which require considerable time to position themselves before
they exhibit a suspected leak behavior. The common use of this feature is
to wait for the application to stablize or reach a point in time from which
leak detection will be attempted. At this point, obtaining a new heap will
allow ZF's various leak detection capabilities to focus only on the memory
and activities associated with the new heap. Potentially, hundreds or
thousands of items can exist in the heap when the application is finally
at a point of interest. Obtaining a new heap allows you to ignore those
prior heap entries. Up to 127 separate heaps are supported.
-M <signal number>
Sets the signal used by ZeroFault to take a memory snapshot
to the value of <signal number>; the default is 54
(which is undefined in AIX). If the target program uses the same
signal, ZeroFault generates a warning message indicating that there
is a conflict, and does not allow the target program to install
a signal handler for this signal. In this case you should resolve
the conflict by using the -M option to redefine the signal that
ZeroFault uses to one that is unused by the program.
When it receives this signal, ZeroFault writes a list of all
currently allocated blocks, their sizes, and the stack traceback
of their allocation to the output leak file; see Finding Logical Memory Leaks
for more information. The block address
can be included in the snapshot by specifying the -A flag.
The output leak file name is of the form:
<program_name>.<n>.zfl.<m>
where <n> is the run number of the program (which matches
the one used for the output file),
and <m> is an integer starting at 1 and incrementing each
time a snapshot is taken.
-S
Causes ZeroFault to suppress warning messages. All error messages are displayed as usual.
-T
allows for extended function name searches during stack trace discovery.
-Z1
This option allows better ZF performance when old bsd COMPAT_43 sockets are
used by the application.
-ZA
Some applications or dependent libraries can generate many error messages
in ZF because they do not adhere to AIX register linkage conventions. This
option allows ZF to consider different stack usage from the norm and can
reduce error counts in noisy applications.
-ZD
This option is similar to -ZS and enables the discard-filtered-messages
option at the startup of the zf_ui (GUI). When this feature is enabled,
the GUI will discard error messages that match its filter rules. This
prevents the accumulation of filtered (invisible) memory errors in the GUI
which can be important in long-running applications. This option does not
effect the delivery of ZF's memory error messages to the .zfo collection
file that ZF assigns to each session. Those errors which are filtered
by the GUI are present in the .zfo collection file for later analysis.
-ZS
This option forces ZF to start the zf_ui (GUI) with the Squelch option
enabled. The Squelch option in the GUI enables complete rejection of
all memory error messages sent by ZF. This allows a long-running
application to position itself without accumulating memory errors in
the GUI. Some applications require hours or days of use prior to
recreating a known problem. In those cases, it is best to squelch
all error messages until ready for analysis. At that time, the
Squelch option is disabled using the GUI controls and the GUI will
accept and display the incoming messages. This option does not
effect the delivery of ZF's memory error messages to the .zfo collection
file that ZF assigns to each session. Those errors which are rejected
by the GUI are present in the .zfo collection file for later analysis.
X Resource Options
ZeroFault recognizes a variety of X resources that allow the user
to customize the user interface. These resources are strings of text
entered into an X resource file, usually the .Xdefaults file in the
user's home directory. You can also use the standard X Window System
facilities to make these resources effective at the server level or
system-wide level. See the reference for the xrdb command for more
information about X resources.
zf*background
Sets the color of window backgrounds in ZeroFault.
zf*foreground
Sets the color of window foregrounds in ZeroFault.
zf*indent_width
Sets the amount (in pixels) of indentation in the error
pane. The default value is 30.
Example:
zf*indent_width: 60
zf*terseLength
Sets the maximum number of characters in each error summary
line. The default value is 105.
zf*terseColumns
Sets the minimum number of characters of each field in
the error summary
lines. Note that fields with values larger than this number
change the boundaries of the columns in their particular summary
line. The default value is 25.
zf*discardMessages
Sets whether ZeroFault discards filtered
messages. The default value is False. To discard error messages
that are filtered, use:
zf*discardMessages: True
zf*args_text.fontList
Sets the font used to display arguments in the error message
display pane. The default value is courb12.
Example:
zf*args_text.fontList: rom14
zf*fontList
Sets the font generally used by ZeroFault in the user
interface. The default value is helvr12.
Example:
zf*fontList: rom11
zf*condense
Sets whether ZeroFault initially condenses error messages.
The default value is True.
Example:
zf*condense: False
zf*Outline.font
Sets font used to display text in the error pane. The
default value is courr12.
Example:
zf*Outline.font: rom10
zf*Outline.iconForeground
Sets the color of the foreground of the error message
icons in the error pane.
Example:
zf*Outline.iconForeground: blue
zf*Outline*background
Sets the color of the background of the error message
icons in the error pane.
Example:
zf*Outline*background: #ffffd0
zf*Outline.foreground
Sets the color of the foreground of the error pane.
Example:
zf*Outline.foreground: #0000a0
Environment Variable Options
ZeroFault uses certain environment variables to change its behavior.
Environment variables are usually set in your login script, e.g. $HOME/.profile
if you use the Korn shell, or in a system-wide script, e.g. /etc/profile,
which gets executed by everyone. You can also set environment variables
on the command line; e.g. in the Korn shell, entering:
export ENV_VAR=value
at
the command line sets the environment variable ENV_VAR to value.
Refer to the documentation for your particular shell for more information
on setting environment variables.
The following environment variables are used by ZeroFault:
ZF_HOME
Points to the base installation directory for ZeroFault.
This is how ZeroFault finds its configuration files and binaries;
the default value is /usr/lpp/ZeroFault.
ZF_SUPPRESS_FILE
Specifies the pathname of the filter file
to use for suppressing errors. ZeroFault always loads the contents
of the /usr/lpp/ZeroFault/bin/zf_suppress file, and then searches
for an additional suppression file in the following order:
- The value of the ZF_SUPPRESS_FILE environment variable if
it is set.
- The ./.zf_suppress file if it exists.
- The $HOME/.zf_suppress file if it exists.
- The $ZF_HOME/.zf_suppress
file if it exists.
ZF_PATH_FILE
Specifies the pathname of the source search
path file.
ZF_SOURCE_PATH
Specifies the source search
path.
ZF_MALSIGNAL
Specifies the signal number that makes ZeroFault
dump a snapshot file of the currently
allocated memory. The default signal number is 54.
DISPLAY
Specifies the X Window System display on
which the ZeroFault GUI will appear.
LIBPATH
Controls the loading of libraries used by the program,
exactly as it would without ZeroFault. See the AIX exec and load
system-call reference for more information on LIBPATH.
Note that placing /usr/lib/threads in the LIBPATH before /usr/lib
prevents ZeroFault from loading properly. If a program requires
/usr/lib/threads in its LIBPATH before /usr/lib you may accomplish
this by linking the program with the -L /usr/lib/threads flag
and unsetting LIBPATH.
|
|