-?

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

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

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.

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.

Specifies the pathname of the source search path file.

Specifies the source search path.

Specifies the signal number that makes ZeroFault dump a snapshot file of the currently allocated memory. The default signal number is 54.

Specifies the X Window System display on which the ZeroFault GUI will appear.

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.