jdb - The Java Debugger

jdb helps you find and fix bugs in Java language programs.

SYNOPSIS

jdb [ options ] [ class ] [ arguments ] 

options

Command-line options, as specified below.

class

Name of the class to begin debugging.

arguments

Arguments passed to the main() method of class.

DESCRIPTION

The Java Debugger, 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.

Starting a jdb Session

Like dbx, there are two ways jdb can be used for debugging. The most frequently used way is to have jdb start the Java interpreter with the class to be debugged. This is done by substituting the command jdb for java in the command line. For example, to start the AppletViewer under jdb, you use the following:

C:\> jdb sun.applet.AppletViewer

or

C:\> jdb -classpath %INSTALL_DIR%\classes sun.applet.AppletViewer

When started this way, jdb invokes a second Java interpreter with any specified parameters, loads the specified class, and stops the interpreter before executing that class's first instruction.

The second way to use jdb is by attaching it to a Java interpreter that is already running. For security reasons, Java interpreters can only be debugged if they have been started with the -Xdebug option. When started with the -Xdebug option, the Java interpreter prints out a password for jdb's use. In addition, the debugged interpreter must not be run with a JIT compiler. Use the option -Djava.compiler=NONE to disable the loading of any JIT compiler. Special debugger classes must be available to the debugged interpreter. These classes are not part of the default runtime class library. Use the option -Xbootclasspath:$INSTALL_DIR\jre\lib\rt.jar;$INSTALL_DIR\lib\tools.jar to allow the debugged interpreter to locate all necessary classes. To summarize, launch the Java interpreter as follows:

   % java -Xdebug -Djava.compiler=NONE   \
     -Xbootclasspath:$INSTALL_DIR\jre\lib\rt.jar;$INSTALL_DIR\lib\tools.jar <class>

To attach jdb to a running Java interpreter (once the session password is known), invoke it as follows:

C:\> jdb -host <hostname> -password <password>

For more information on debugging with JDB, see Java Language Debugging [web].

Basic jdb Commands

The following is a list of the basic jdb commands. The Java debugger supports other commands which you can list using jdb's help command.

NOTE: To browse local (stack) variables, the class must have been compiled with the -g option.

help, or ?

The most important jdb command, help displays the list of recognized commands with a brief description.

print

Browses Java objects. The print command calls the object's toString() method, so it will be formatted differently depending on its class.

Classes are specified by either their object ID or by name. If a class is already loaded, a substring can be used, such as Thread for java.lang.Thread.

print supports Java expressions, such as print MyClass.clsVar. Method invocation is not currently supported.

dump

Dumps an object's instance variables. Objects are specified by their object ID (a hexadecimal integer).

Classes are specified by either their object ID or by name. If a class is already loaded, a substring can be used, such as Thread for java.lang.Thread. If a class isn't loaded, its full name must be specified, and the class will be loaded as a side effect. This is needed to set breakpoints in referenced classes before an applet runs.

The dump command supports Java expressions such as dump 0x12345678.myCache[3].foo. Method invocation is not currently supported.

threads

List the threads. Threads are referenced by their object ID.

where

where with no arguments dumps the stack of the current thread (which is set with the thread command). where all dumps the stack of all threads in the current thread group. where threadid dumps the stack of the specified thread. threadid takes the form of t@<index>, such as t@3. If a requested thread is suspended (either because it's at a breakpoint or via the suspend command), local (stack) and instance variables can be browsed with the print and dump commands. The up and down commands select which stack frame is current.

Breakpoints

Breakpoints are set in jdb in classes, such as "stop at MyClass:45". 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). The clear command removes breakpoints using a syntax as in "clear MyClass:45". Using the clear command with no argument displays a list of all breakpoints currently set. The cont command continues execution. Single-stepping is available via step.

Exceptions

When an exception occurs for which there isn't a catch statement anywhere up a Java program's stack, the Java runtime normally dumps an exception trace and exits. When running under jdb, however, that exception is treated as a non-recoverable breakpoint, and jdb stops at the offending instruction. If that class was compiled with the -g option, instance and local variables can be printed to determine the cause of the exception.

Specific exceptions may be caught with the catch command, for example: "catch FileNotFoundException" or "catch mypackage.BigTroubleException. 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 which caused the exception. The ignore command removes exception classes from this list.

NOTE: The ignore command does not cause the Java interpreter to ignore specific exceptions, only the debugger.

When you use jdb in place of the Java interpreter on the command line, jdb accepts the same options as the java command.

When you use jdb to attach to a running Java interpreter session, jdb accepts the following options:

-host <hostname>

Sets the name of the host machine on which the interpreter session to attach to is running.

-password <password>

"Logs in" to the active interpreter session. This is the password printed by the Java interpreter prints out when invoked with the -Xdebug option.

ENVIRONMENT VARIABLES

CLASSPATH

Used to provide the system a path to user-defined classes. Directories are separated by semi-colons, for example,

    .;C:\users\dac\classes;C:\tools\java\classes

SEE ALSO

javac, java, javah, javap, javadoc