'\" t
.\" @(#)jdb.1 1.6 99/02/19 SMI;
.\" Copyright 1999 Sun Microsystems, Inc. All rights reserved.
.\" Copyright 1999 Sun Microsystems, Inc. Tous droits réservés.
.\" 
.\" 
.\"  This document was created by saving an HTML file as text
.\"  from the JavaSoft web site:
.\" 
.\" http://java.sun.com/products/jdk/1.2/docs/tooldocs/tools.html
.\" 
.\"  and adding appropriate troff macros.  Because the JavaSoft web site 
.\"  man pages can change without notice, it may be helpful to diff
.\"  files to identify changes other than new functionality. 
.\" 
.TH jdb 1 "18 Feb 1999"
.SH NAME
jdb \- Java debugger
.SH SYNOPSIS
.B jdb 
[ 
.BI \-host " hostname"
] [
.BI \-password " password"
] [
.I class
] 
.if n .ti 10
[
.I  arguments
]
.SH PARAMETERS
.TP 15
.I class
Name of the class to begin debugging.
.TP
.I arguments
Arguments passed to the main() method of class.
.SH DESCRIPTION
.IX "Java debugger" "" "Java debugger \(em \fLjdb\fP"
.IX "jdb" "" "\fLjdb\fP \(em Java debugger"
The Java\(tm debugger, 
.BR jdb , 
is a dbx-like command-line debugger for
Java classes. It uses the Java debugger API to provide inspection
and debugging of a local or remote Java interpreter.
.SS Starting a jdb Session
.IX "jdb" "Starting a jdb Session" "\fLjdb\fP \(em Java debugger"
Like dbx, there are two ways 
.B jdb 
can be used for
debugging. The most frequently used way is to have 
.B jdb
start 
.BR  java (1)
with the class to be
debugged. This is done by substituting the command 
.B jdb
for 
.BR java (1)
in the command line. For example, to start
.BR appletviewer (1)
under 
.BR jdb , 
use the following:
.LP
.RS
.B example% jdb sun.applet.AppletViewer
.RE
or
.RS 
.B example% jdb -classpath $INSTALL_DIR/classes sun.applet.AppletViewer
.RE
.LP
When started this way, 
.B jdb 
invokes a second Java
interpreter with any specified parameters, loads the
specified class, and stops the interpreter before
executing the first instruction of that class.
.LP
The second way to use 
.B jdb 
is by attaching it to a running Java.
For security
reasons, Java interpreters can only be debugged if 
started with the 
.B \-Xdebug 
option. When started
with the 
.B \-Xdebug 
option, the Java interpreter displays out
a password for the Java debugger to use.
In addition, the debugged interpreter must not run
with the JIT compiler.  Use the 
.B -Djava.compiler=NONE
option to disable the loading of any JIT compiler.
Special debugger classes must be available to debugged
interpreter.  These classes are not part of
the default runtime class library.  Use the 
.LP
.B \-Xbootclasspath:$INSTALL_DIR/jre/lib/rt.jar:$INSTALL_DIR/lib/tools.jar
.LP
option to allow the debugged interpreter to locate all
necessary classes.  To summarize, launch the Java
interpreter as follows:
.LP
.ft 3
.nf
example% java -Xdebug -Djava.compiler=NONE   \\
-Xbootclasspath:$INSTALL_DIR/jre/lib/rt.jar:$INSTALL_DIR/lib/tools.jar \\
\f2class\fP
.fi
.ft 1
.LP
To attach 
.B jdb 
to a running Java interpreter (once the
session 
.I password 
is known), invoke it as follows:
.LP
.RS 
\f3example% jdb -host \f2hostname\f3 -password \f2password\f3\f1
.RE
.LP
.SS Basic jdb Commands
.IX "jdb" "Basic jdb Commands" "\fLjdb\fP \(em Java debugger"
The following is a list of the basic 
.B jdb 
commands. The Java
debugger supports other commands listed with the
.B help command.
.LP
Please note that to browse local (stack) variables, the class 
must have been compiled with the 
.B \-g 
option.
.TP 15
.B dump
Dumps an object's instance variables. Objects are
specified by their object ID (a hexadecimal
integer).
.LP
.RS 15
Classes are specified by either their object ID or
by name. If a class is already loaded, a substring
can be used, such as 
.B Thread 
for 
.BR java.lang.Thread .
If a class isn't loaded, its full name must be
specified, and the class is loaded as a side
effect. This is needed to set breakpoints in
referenced classes before an applet runs.
.LP
The dump command supports Java expressions such as
dump 
.BR 0x12345678.myCache[3].foo . 
Method invocation is not currently supported.
.RE
.br
.ne 3
.TP 15
.B help, or ?
The most important 
.B jdb 
command, 
.B help 
displays the
list of recognized commands with a brief
description.
.TP 15
.B print
Browses Java objects. The 
.B print 
command calls the
.B toString() 
method of the object, so it will be formatted
differently depending on its class.
.LP 
.RS 15
Classes are specified by either their object ID or
by name. If a class is already loaded, a substring
can be used, such as 
.B Thread 
for 
.BR java.lang.Thread .
.LP
The
.B print 
subcommand supports Java expressions, such as print
.BR MyClass.clsVar . 
Method invocation is not currently
supported.
.RE
.TP 15
.B threads
Lists the threads. 
Threads are referenced by their object ID.
.TP 15
.B where
The
.B where 
subcommand with no arguments dumps the stack of the
current thread (which is set with the 
.B thread
command). Using
.B where all 
dumps the stack of all threads
in the current thread group. Using
.BI where " threadid"
dumps the stack of the specified thread. The
.I threadid 
subcommand takes the form of \f3t@\f2index\f1, such as 
.BR t@3 . 
If a requested
thread is suspended (either because it's at a
breakpoint or via the 
.B suspend 
command), local
(stack) and instance variables can be browsed with
the 
.B print 
and 
.B dump 
commands. The 
.B up 
and 
.B down
commands select which stack frame is current.
.SS Breakpoint Commands
.IX "jdb" "Breakpoints" "\fLjdb\fP \(em Java debugger"
Breakpoints are set in 
.B jdb 
in classes as follows:
.TP 15
\f3clear at\fP \f2class\fP:\f2line\fP
Removes breakpoints using a
syntax similar to 
.BR  stop .
.TP 15
.B cont 
Continues
execution. 
.TP 15
.B step 
Single step line execution.
.TP 15
\f3stop at\fP \f2class\fP:\f2line\fP
The source file line number must be
specified, or the name of the method (the breakpoint
will then be set at the first instruction of that
method). 
.RS
.sp 1n
.B stop at MyClass:45
.RE
.SS Exception Commands
.IX "jdb" "Exceptions" "\fLjdb\fP \(em Java debugger"
When an exception occurs for which there is no catch
statement anywhere up a Java program's stack, the Java
runtime normally dumps an exception trace and exits.
When running under 
.BR jdb , 
however, that exception is
treated as a non-recoverable breakpoint, and 
.B jdb 
stops
at the offending instruction. If that class was compiled
with the 
.B \-g 
option, instance and local variables can be
printed to determine the cause of the exception.
.br
.ne 14
.TP 15
.B  catch
Breaks for specific exception.
.RS 15
.LP
Specific exceptions may be caught with the catch
command, for example: 
.LP
.RS
.B catch FileNotFoundException
.RE
.LP
or
.LP
.RS
.B catch mypackage.BigTroubleException
.RE
.LP
The Java debugging
facility keeps a list of these exceptions, and when one
is thrown, it is treated as if a breakpoint had been on
the instruction that caused the exception. 
.RE
.TP 15
.B ignore
Removes exception classes from this list.
Please note that the
.B ignore 
command does not cause the Java
interpreter to ignore specific exceptions, only the
debugger.
.SH OPTIONS
When using 
.B jdb 
in place of the Java interpreter on the command
line, 
.B jdb 
accepts the same options as the 
.BR java (1)
command.
.LP
When using 
.B jdb 
to attach to a running Java interpreter session,
.B jdb 
accepts the following options:
.TP 15
.BI \-host " hostname"
Sets the name of the host machine on which the interpreter
session is to attach when running.
.TP 15
.BI \-password " password"
Logs in to the active interpreter session. This is the
password printed by the Java interpreter when
invoked with the 
.B \-Xdebug 
option.
.SH ENVIRONMENT VARIABLES
.TP 15
.SB CLASSPATH
Used to provide the system a path to user-defined classes.
Directories are separated by colons, for example,
.LP
.RS 20
.B .:/home/avh/classes:/usr/local/java/classes
.RE
.br
.ne 11
.SH ATTRIBUTES
See
.BR attributes (5)
for a description of the following attributes:
.sp
.TS
box;
cbp-1 | cbp-1
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
=
Availability	SUNWjvdev
.TE
.SH SEE ALSO
.BR java (1), 
.BR javac (1), 
.BR javadoc (1),
.BR javah (1), 
.BR javap (1)