jdb

jdb

The Java Debugger

Synopsis

jdb [ options ] class [ program options ]
jdb connect options

Description

jdb is a debugger for Java classes. It is text-based, command-line-oriented, and has a command syntax like that of the Unix dbx or gdb debuggers used with C and C++ programs.

jdb is written in Java, so it runs within a Java interpreter. When jdb is invoked with the name of a Java class, it starts another copy of the java interpreter, using any interpreter options specified on the command line. The new interpreter is started with special options that enable it to communicate with jdb. The new interpreter loads the specified class file and then stops and waits for debugging commands before executing the first byte code.

jdb can also debug a program that is already running in another Java interpreter. Doing so requires that special options be passed to both the java interpreter and to jdb. See the -attach option below.

jdb expression syntax

jdb debugging commands such as print, dump, and suspend allow you to refer to classes, objects, methods, fields, and threads in the program being debugged. You can refer to classes by name, with or without their package names. You can also refer to static class members by name. You can refer to individual objects by object ID, which is an eight-digit hexadecimal integer. Or, when the classes you are debugging contain local variable information, you can often use local variable names to refer to objects. You can use normal Java syntax to refer to the fields of an object and the elements of an array; you can also use this syntax to write quite complex expressions. As of Java 1.3, jdb even supports method invocation using standard Java syntax.

Options

When invoking jdb with a specified class file, any of the java interpreter options can be specified. See the java reference page for an explanation of these options. In addition, jdb supports the following options:

-attach [host:]port

Specifies that jdb should connect to the Java VM that is already running on the specified host (or the local host, if unspecified) and listening for debugging connections on the specified port. Java 1.3 and later.

In order to use jdb to connect to a running VM in this way, the VM must have been started with special command-line options. In Java 1.3 and 1.4, use these options:

% java -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

In Java 5.0, use these options instead:

% java -agentlib:jdwp=transport=dt_socket,address=8000,server=y,suspend=n

The Java debugging architecture allows a complex set of interpreter-to-debugger connection options, and java and jdb provide a complex set of options and suboptions to enable it. A detailed description of those options is beyond the scope of this book.

-connect connector:args

This option provides the most general and flexible method for connecting jdb to the process to be debugged. Specify the name of a connector (a Java class) followed by a colon and a comma-separated list of arguments in name=value form. Java 1.4 and later. See -listconnectors for available connectors and their arguments.

-help

Displays a usage message listing supported options.

-launch

Starts the specified application when jdb starts. This avoids the need to explicitly use the run command to start it. Java 1.3 and later.

-listconnectors

List available connection methods. Each connector is a Java class and a list of arguments. Java 5.0 and later. See the -connect option.

-listen port

Listens on the specified port for a Java VM to connect to the debugger. To make this work, the VM must be with options like these:

% java -agentlib:jdwp=transport=dt_socket,address=8000,server=n,suspend=y

Java 1.4 and later.

-listenany

Like the -listen option but jdb picks a port to listen on and prints out the port number for use when launching the Java process to debug. Java 1.4 and later.

-sourcepath path

Specifies the locations jdb searches when attempting to find source files that correspond to the class files being debugged. If unspecified, jdb uses the classpath by default. Java 1.3 and later.

-tclient

Tells jdb to invoke the client version of the Java interpreter.

-tserver

Tells jdb to invoke the server version of the Java interpreter.

-version

Displays the jdb version number and exits.

Commands

jdb understands the following debugging commands. Use the help command for more.

? or help: Lists all supported commands, with a short explanation of each.
!!: A shorthand command that is replaced with the text of the last command entered. It can be followed with additional text to append to that command.
catch [ exception-class ]: Causes a breakpoint whenever the specified exception is thrown. If no exception is specified, the command lists the exceptions currently being caught. Use ignore to stop these breakpoints from occurring.
classes: Lists all classes that have been loaded.
clear: Lists all currently set breakpoints.
clear class.method [( param-type...) ]: Clears the breakpoint set in the specified method of the specified class.
clear [ class:line ]: Removes the breakpoint set at the specified line of the specified class.
cont: Resumes execution. This command should be used when the current thread is stopped at a breakpoint.
down [ n ]: Moves down n frames in the call stack of the current thread. If n is not specified, moves down one frame.
dump id...: Prints the value of all fields of the specified object or objects. If you specify the name of a class, dump displays all class (static) methods and variables of the class and also displays the superclass and list of implemented interfaces. Objects and classes can be specified by name or by their eight-digit hexadecimal ID numbers. Threads can also be specified with the shorthand t@thread-number.
exit or quit: Quits jdb.
gc: Runs the garbage collector to force unused objects to be reclaimed.
ignore exception-class: Does not treat the specified exception as a breakpoint. This command turns off a catch command. This command does not cause the Java interpreter to ignore exceptions; it merely tells jdb to ignore them.
list [ line-number ]: Lists the specified line of source code as well as several lines that appear before and after it. If no line number is specified, uses the line number of the current stack frame of the current thread. The lines listed are from the source file of the current stack frame of the current thread. Use the use command to tell jdb where to find source files.
list method: Displays the source code of the specified method.
load classname: Loads the specified class into jdb.
locals: Displays a list of local variables for the current stack frame. Java code must be compiled with the -g option in order to contain local variable information.
methods class: Lists all methods of the specified class. Use dump to list the instance variables of an object or the class (static) variables of a class.
print id...: Prints the value of the specified item or items. Each item can be a class, object, field, or local variable, and can be specified by name or by eight-digit hexadecimal ID number. You can also refer to threads with the special syntax t@thread-number. The print command displays an object's value by invoking its toString() method.
next: Executes the current line of source code, including any method calls it makes. See also step.
resume [ thread-id... ]: Resumes execution of the specified thread or threads. If no threads are specified, all suspended threads are resumed. See also suspend.
run [ class ] [ args ]: Runs the main() method of the specified class, passing the specified arguments to it. If no class or arguments are specified, uses the class and arguments specified on the jdb command line.
step: Runs the current line of the current thread and stops again. If the line invokes a method, steps into that method and stops. See also next.
stepi: Executes a single Java VM instruction.
step up: Runs until the current method returns to its caller and stops again.
stop: Lists current breakpoints.
stop at class:line: Sets a breakpoint at the specified line of the specified class. Program execution stops when it reaches this line. Use clear to remove a breakpoint.
stop in class.method [( param-type...) ]: Sets a breakpoint at the beginning of the specified method of the specified class. Program execution stops when it enters the method. Use clear to remove a breakpoint.
suspend [ thread-id... ]: Suspends the specified thread or threads. If no threads are specified, suspends all running threads. Use resume to restart them.
thread thread-id: Sets the current thread to the specified thread number. This thread is used implicitly by a number of other jdb commands.
threadgroup name: Sets the current thread group.
threadgroups: Lists all thread groups running in the Java interpreter session being debugged.
threads [ threadgroup ]: Lists all threads in the named thread group. If no thread group is specified, lists all threads in the current thread group (specified by threadgroup).
up [ n ]: Moves up n frames in the call stack of the current thread. If n is not specified, moves up one frame.
use [ source-file-path ]: Sets the path used by jdb to look up source files for the classes being debugged. If no path is specified, displays the current source path.
where [thread-id ] [all ]: Displays a stack trace for the specified thread. If no thread is specified, displays a stack trace for the current thread. If all is specified, displays a stack trace for all threads.
wherei [thread-id x]: Displays a stack trace for the specified or current thread, including detailed program counter information.

Environment