Chapter 3:  Startup Options

• command line flag options
• environment variable options

Command-Line Flag Options

-b <number>

Parameter buffers are printed if verbosity is 2 or greater. These buffers are displayed as plain text and this option controls the amount of buffer characters printed. default value is 30. Max is 255.

-e

Causes ZFtrace to follow execs, creating a new instance of ZFtrace if the process calls exec to load a new program.

For example if the original command is zftr -e aixterm, ZFtrace will create a trace file 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.

Note that this flag can be resource intensive depending on the number of simultaneous instances of ZFtrace that result.

See also Daemons and other background programs for a discussion of similar issues.

-G

ZFtrace will trace all subroutine calls and all system calls. This option can dramatically slow the process and can quickly create large trace files. However, the data generated is quite useful for determining detailed program behavior and clues. We recommend that this option be used where the output file (see -o) is in its own filesystem to protect against using all the space in any system-oriented filesystem. The -U option can provide similar detail as -G with less trace file volume.

-i <number>

The number of arguments/parameters to print in system calls. Default is 0, which specifies "automatic" behavior where ZFtrace determines the number to print on a per system call basis. Max is 8.

-j <number>

The number of arguments/parameters to print in subroutine calls (i.e when -G is used). Default is 0, which specifies "automatic" behavior where ZFtrace determines the number to print on a per subroutine basis. Max is 8.

-l <number>

Sets the maximum length of all stack tracebacks to <number> functions; the default is 15.  Note that setting this to a large number may cause excessive memory usage. This option only applies to the stack traces generated when using the -U option.

-m <number>

Parameter strings are printed if verbosity is 2 or greater. These strings are displayed as plain text and this option controls the amount of string characters printed. default value is 30. Max is 255. File names in the trace data are typically strings. If your filenames are truncated, then setting this parameter to higher values is a good solution.

-o <directory name>

Specifies the directory in which ZFtrace puts all its output files; the default is the current working directory.

-S

Run Silent. ZFtrace begins program execution with all trace information suppressed. This allows you to position a long running program for problem recreation without voluminous data accumulating in the trace file(s). Use the signal associated with the -W option to toggle trace suppression on or off at any time. This option is particularly handy when combined with -G or -U options which typically produce large amounts of trace data.

-T

Print the thread-ID in each trace output line. This is useful to associate trace data on a per-thread basis for multi-threaded programs.

-U

For each system call traced, produce a stack trace which describes the subroutines leading to the system call. This gives fine grain detail of program execution without the volume overhead of the -G option. This option is suppressed if the -G option is specified. If the Verbosity (see -V) is 5 or greater, then source file name and line number information is included in the stack trace. The -l option can limit the size of the stack trace.

-v

Print the build level information of the ZFtrace program itself.

-V <number>

Set the detail verbosity of the tracing information collected:

    0 system call, argvalues, and return code
    1 argument numeric symbol expansion
    2 argument string expansion
    3 return value errno details (default)
    4 offsets in stack traces
    5 filename and line numbers in stack traces
    6 argument structure expansion and multi-line system call detail

-V3 is the default. Note that filename and line numbers in stack traces require that the traced program have debugging information contained in it. Some programs are shipped with debugging information removed. Most compilers use a -g option to enable debugging information.

-W <number>

Use the signal number to toggle tracing on or off (see -S and -Y also). The default signal number is 54 or SIGUSR1. This option allows a different signal to be associated with toggling tracing on or off. Example: Assume ZFtrace is silently running the program 'smitty' having been started as follows:

		# zftr -Y -S smitty
		18905

The process id (or pid) of smitty is 18905. To toggle tracing on, issue the following command:

		# kill -USR1 18905
	or
		# kill -54 18905

To use a different signal, use the -W option as in this complete example:

		# zftr -Y -S -W60 smitty
		18907
		
		# kill -60 18907

-Y

Print the pid to standard out. This is useful when used with the -S option. It allows you to immediately know the pid of the traced process which can then be used with the signal technique to toggle tracing on or off. (See -W)

Environment Variable Options

The following environment variables are used by ZFtrace:

ZFTR_HOME

Points to the base installation directory for ZFtrace. This is how ZFtrace finds its configuration files and binaries; the default value is /usr/lpp/ZFtrace.

Specifies the signal number that makes ZFtrace toggle tracing on or off. The default signal number is 54. This behavior is also controlled by the -W startup option.

Controls the loading of libraries used by the program, exactly as it would without ZFtrace. 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 ZFtrace 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.