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