ZAP
NAME zap - The command-line Java(tm) bug zapper.
Copyright (c) 1996, Software Farm, Inc. "Java" is a registered trademark of Sun Microsystems.
SYNOPSIS zap [-applet] [-password <password>] [-host <hostname>] [java options] [class-to-debug] [class-to-debug-arguments]
AVAILABILITY Zap is distributed as shareware and includes both the source and class files. If you are still happy with Zap after the thirty (30) day free trial period please send $25 to:
Software Farm, Inc. 211 HighView Drive Boulder CO 80304
to help defray development costs. Registered users will be promptly notified of updates when they become available.
DESCRIPTION zap is a program written in Java that is used to examine and debug programs written in Java, including both applications and applets. It uses the command-line standard terminal (TTY) interface for both input and output.
The [class-to-debug] is a Java application class file that either includes a main() function as the entry point or an applet, in which case the [-applet] option must be used.
If no [class-to-debug] is specified then it can be specified in exactly the same way from the zap debugger command-line using the 'debug' command.
zap is also able to debug remote Java sessions. The remote host is specified using the [-host <hostname>] and [-password <password>] options. The password is obtained from the remote Java interpreter upon startup by using the java '-debug' option. for example:
C:\> java -debug myRemoteApplet The password is ACZD5...
In order for the zap debugger to examine local variables within a class file method the class must be compiled (using javac) with the '-g' option.
OPTIONS
-applet
Specifies that the debugged program is an applet.
-password <password>
Specifies that the zap debugger is to attach to a Java interpreter that is already running. This other interpreter had been started with the -debug option which caused it to print out the given password.
-host <hostname>
Specifies that the zap debugger is to debug a program already running on another machine on the network and the machine is called <hostname>. This option is used in conjunction with the -password option.
java options
These options are passed straight through to the Java interpreter when it is started. Any valid Java interpreter option is valid (for example -classpath).
class-to-debug
This is the name of the class to debug. It must be the full name including any package identifiers and excluding the .class extension.
class-to-debug-arguments
These are the arguments, if any, to the debugged program.
USAGE
The basic command set consists of 'run', to run the debugged program, 'print', to display the value of a variable or contents of a object, 'where', to display the call stack and 'stop', to set a breakpoint.
GENERAL COMMANDS
help [command]
Display the general help message or help for the specified command.
run [args]
Run (begin executing) or re-run the current program being debugged. The specified arguments are passed to the program. If no arguments are specified here then the arguments specified in the last run are used. If this is the first run then the arguments (if any) specified on the Zap command-line are used.
The current program is specified either on the Zap command-line or by using the 'debug' command. Note that this differs from 'jdb' (but resembles 'dbx') in that the current program cannot be specified as an argument to the 'run' command.
debug [program [args]]
Display or specify the program to debug and it's arguments. Zap command-line arguments may be specified at this time.
Examples:
> debug -applet ../demo/example1.html
> debug jeo.Demo -f
quit | exit
Quit running the debugged program and exit the debugger.
kill Quit running the debugged program and reinitialize the debugger.
zapenv
Display Zap's properties. This will display the properties of the debugger such as classpath, os version, etc. At this time there is no way to access the properties of the debugged program.
Example:
> zapenv
java.home = /home2/docs/java/jdk/java/bin/.. java.version = 1.0 file.separator = / line.separator =
java.vendor = Sun Microsystems Inc. user.name = michael os.arch = sparc os.name = Solaris java.vendor.url = http://www.sun.com/ user.dir = /home2/zap/bin java.class.path = /home2/docs/jde/JDK/classes:/home2/[...] java.class.version = 45.3 os.version = 2.x path.separator = : user.home = /export/home/michael
verbose [false]
Turn on [off] the display of trace messages from Zap and the Java RemoteDebugger about their internal states.
splash
Display the Zap splash introduction message.
noSplash
Do not display the Zap splash introduction message automat- ically upon startup of the debugger. This command is typically put in the 'zap.ini' command file.
options
Display the Zap command-line options.
prompt [style]
Specify style of debugger prompt to be one of:
this location thread this+location thread+location none
Examples: > prompt this <static>
> prompt this (java.lang.String)0xee31a0d8>
> prompt location [java.lang.String:55]>
> prompt this+location (java.lang.String)0xee31a0d8[java.lang.String:55]>
> prompt thread+location Thread-5[java.lang.String:55]>
> prompt thread+location
> prompt thread Thread-5>
> prompt none >
genEmacsInfo [false]
Turn on [off] the generation of location information of interest to Emacs. This information is used by Emacs to visually indicate the current line of execution in the source code.
This is some code that fools Emacs with a shell buffer running Zap into thinking it is talking to a gdb:
(defun zap-mode () (interactive) (require 'gdb) (set-process-filter (get-buffer-process (current-buffer)) 'gdb-filter) (set-process-sentinel (get-buffer-process (current-buffer)) 'gdb-sentinel) (gdb-mode) (gdb-set-buffer))
use [path1:path2:...]
Display or optionally specify the paths in which the debugger will look for source code files. This source code is what is displayed at breakpoints, when the 'list' command is used, etc.
CONTROL FLOW COMMANDS
catch [name]
Display or optionally specify exceptions that are caught. Exceptions that are specified as caught will cause a breakpoint when thrown. Exceptions that are not caught are completely ignored and do not cause any visible behavior or output. By default all exceptions are ignored.
Examples:
> catch java.lang.IllegalArgumentException
ignore [name]
Display or optionally specify exceptions that are caught. Exceptions that are specified as caught will cause a breakpoint when thrown. Exceptions that are not caught are completely ignored and do not cause any visible behavior or output. By default all exceptions are ignored.
Examples:
> catch java.lang.IllegalArgumentException
threads
Display information about all threads associated with the debugged program.
thread [name]
Display or optionally specify the current thread. A running, suspended or breakpointed program will typically have a number of associated threads. The 'where', 'up', 'down', 'next' and 'step' commands operate on the 'current thread'. The current thread is specified by the 'thread' command or automatically when a breakpoint or exception occurs.
Examples:
> thread Thread-5
suspend [threadName | all]
Suspend the current thread (the default), or optionally a specified thread or all threads. Threads can later be resumed by using the 'cont' or 'resume' commands.
halt | break
Suspend all threads. The threads can later be resumed by using the 'cont' or 'resume' commands.
cont | resume [name|all]
Resume running the current, specified or all threads. If the current or specified thread is blocked waiting on another suspended tread then it will not be resumed until the other 'waited upon' thread is resumed (either by it's own 'resume' command or by using 'resume all').
next
Execute one source level instruction by the current thread, stepping over any method calls.
step
Execute one source level instruction by the current thread, stepping into any method calls.
up [numberOfFrames]
Change the debugger current stack frame to be that of the caller of the current method, if any. This is repeated for the specified number of frames (the default number of frames to move up is one). The commands like 'dump', 'locals', 'list' will now display information about the current frame. The 'where' command will display the whole call stack at any time.
down [numberOfFrames]
Change the debugger current stack frame to be that called by the current method, if any. This is repeated for the number of times specified (the default number of frames to move down is one). The commands like 'print', 'locals', 'list' will now display information about this current frame. The 'where' command will display the whole call stack at any time.
assign | set <variable> [=] <value>
Assign the given value to the given variable.
Examples:
> assign x=1 > assign y 2 > set z = 3
Caveats:
This feature is new with the 1.0.2 JDK. However there is still no way to assign values to Objects or Strings or Array elements.
DISPLAY COMMANDS
where [numberOfFrames]
Display information about all (or the specified number) of frames in the call stack.
dump | locals
Display the variables and their value for the current stack frame.
whatis <variable>
Display the type of the given variable.
classes [searchSpec]
Display the names of the currently loaded classes. The searchSpec can be used to narrow the search. Which classes are loaded depends on which code has been executed up to the current point. A class may be loaded manually by using the 'load' command.
methods [className]
Display the names of the methods of the current (or specified) class.
load <className>
Load the given class. This command actually tells the Java interpreter which is executing the debugged program to load the given class. This command will fail if the class is not found in the classpath.
print [-r] <variable | ...>
Display information about the specified variable, address, class, or thread. The type and address of the variable is displayed. The -r option is used to display the contents of the variable.
Examples:
/*********************/ /* Printing a Thread */ /*********************/
> print main main = (sun.tools.debug.MainThread)0xee300dc0
> print -r main main = (sun.tools.debug.MainThread)0xee300dc0 { name = "main" priority = 5 threadQ = null PrivateInfo = -280920608 eetop = -280920884 single_step = false daemon = false stillborn = false target = null group = (java.lang.ThreadGroup)0xee300bc8 agent = (sun.tools.debug.Agent)0xee300910 clazz = 0xee30fc08:class(jeo.Demo) argv = <error occurred> }
/********************/ /* Printing a Class */ /********************/
> print String String = 0xee300028:class(java.lang.String)
> print -r String String = 0xee300028:class(java.lang.String) { superClass = 0xee300018:class(java.lang.Object) interfaces = None loader = None InternSet = null }
/**********************/ /* Printing a Literal */ /**********************/
> print hidden hidden = false
/************************/ /* Printing an Instance */ /************************/
> print offScreenGraphics offScreenGraphics = (sun.awt.motif.X11Graphics)0xee324bb8
> print -r offScreenGraphics
offScreenGraphics = (sun.awt.motif.X11Graphics)0xee324bb8 { pData = 2004464 foreground = null font = null originX = 0 originY = 0 image = (sun.awt.motif.X11Image)0xee324a70 }
memory
Display amounts of used and free memory available to the Java interpreter running the debugged program.
Example:
> memory Total: 1052664, Free: 207808
class <className>
Display or specify current class. The current class is used as the default class in the 'list' and breakpoint commands.
func | method <methodName>
Specify current method. This is usually used before the 'list' command in order to view the source code of a method.
Example:
[java.lang.Object:-1]> func GraphPanel.relax [GraphPanel:84]> list 84 85 synchronized void relax() { 86 for (int i = 0 ; i < nedges ; i++) { 87 Edge e = edges[i]; 88 double vx = nodes[e.to].x - nodes[e.from].x; 89 double vy = nodes[e.to].y - nodes[e.from].y; 90 double len = Math.sqrt(vx * vx + vy * vy); 91 double f = (edges[i].len - len) / (len * 3) ; 92 double dx = f * vx; 93 double dy = f * vy;
[GraphPanel:94]>
list [start [end]]
Display lines of source code in the current class. The default starting line is the current line. The default ending line is 10 lines after the start line.
/[string]
Search forward through the current source file for the given text string. If no string is specified then the previous search string is used.
?[string]
Search backward through the current source file for the given text string. If no string is specified then the previous search string is used.
line
Display the source code for the current line.
file
Display the current source code filename.
BREAKPOINT COMMANDS
stop in <[className.]methodName> [if <var> <condition> <value>]
Set a breakpoint to stop execution on entry to the specified method. If no class is specified the current class is used (see the 'class' command). 'var' can be any variable name. 'condition' can be any one of: >, >=, =, ==, <=, < and !=. 'value' can be a <number>, true, false, or <string>.
stop at <[className:]lineNumber> [if <var> <condition> <value>]
Set a breakpoint to stop execution at the specified line number. If no class is specified the current class is used (see the 'class' command). 'var' can be any variable name. 'condition' can be any one of: >, >=, =, ==, <=, < and !=. 'value' can be a <number>, true, false, or <string>.
when at <[className:]lineNumber> <command>
Execute the given command at specified line number in the given class. If no class is specified the current class is used (see the 'class' command).
clear | delete [# | all]
Remove the breakpoints at the location where the last breakpoint was encountered.
breakPointID
Remove the breakpoint with given numerical ID (as listed using the 'stop' or 'status' commands).
all Remove all breakpoints.
enable [breakPointID | all]
Enable (set) the breakpoints at the location where the last breakpoint was encountered.
breakPointID
Enable the breakpoint with given numerical ID (as listed using the 'stop' or 'status' commands).
all Enable all breakpoints.
disable [# | all]
Disable (unset) the breakpoints at the location where the last breakpoint was encountered.
breakPointID
Disable the breakpoint with given numerical ID (as listed using the 'stop' or 'status' commands).
all Disable all breakpoints.
stop | status
List all breakpoints, their ID and their state (either enabled or disabled).
breakpoints [save | load]
List all breakpoints, their ID and their state (either enabled or disabled).
save
Save all breakpoints to a file (zap.brk).
load
Load all breakpoints from a file (zap.brk).
SHELL COMMANDS
alias [orig] [new]
Display all aliases or add a new command name alias. Aliases are typically found in the zap.ini configuration file.
Examples:
alias l list alias si 'stop in'
history [size]
Display or resize history buffer. The history buffer maintains a copy of the last [size] zap debugger commands entered by the user. The default size of the history buffer is 200.
history save [fileName]
Save history buffer to a file. The default filename is zap.hst.
history load [fileName]
Load history buffer from a file and execute it. The default filename is zap.hst.
source [fileName]
Load history buffer from a file and execute it. The default filename is zap.hst.
!!
Repeat last command.
!<prevCmd# | prevCmd>
Repeat a previous command. prevCmd# may be the numerical index of any of the previous commands stored in the history buffer as listed by the 'history' command. prevCmd may be the first few characters of any of the previous commands stored in the history buffer as listed by the 'history' command.
ENVIRONMENT
The CLASSPATH and PATH environment variables need to be modified in order for the zap debugger to run. Add 'Zap/classes' to the CLASSPATH and 'Zap/bin' to the PATH environment variables.
FILES
zap.ini
This file contains zap debugger commands and is read and executed when zap is started. It is read first from the current user's home directory and then from the local directory. The commands in the (possibly) two files are executed in order. This file typically contains a list of alias commands and a sample is provided with Zap.
zap.hst
The default file used by the zap debugger 'history save' and 'history load' commands.
zap.brk
The default file used by the zap debugger 'breakpoints save' and 'breakpoints load' commands.
SEE ALSO
The documentation for Sun's 'jdb' debugger and debug package (sun.tools.debug.*).
NOTES
BUGS