Availability

JDK 1.0 and later.

Synopsis

jdb [ java options ] class
jdb [ -host hostname ] -password password

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.

When jdb is invoked with the name of a Java class, it starts another copy of the java interpreter, passing any specified java options to the interpreter. jdb is itself a Java program, running in its own copy of the interpreter. This new interpreter loads the specified class file and stops for debugging before executing the first Java byte-code.

jdb may also be started with the -password and optional -host arguments. Invoked in this way, jdb "attaches itself" to an already running copy of the interpreter. In order for this to work, the Java interpreter running the program to be debugged must have been started with the -debug option. When the interpreter is started with this option, it prints a password that must be used with the jdb -password option.

Once a debugging session is started, you may issue any of the commands described below.

Options

When invoking jdb with a specified class file, any of the java interpreter options may be specified. See the java reference page for an explanation of these options.

When attaching jdb to an already running Java interpreter, the following options are available:

-host hostname

Specifies the name of the host upon which the desired interpreter session is running.

-password password

This option is required to attach to a running interpreter. The interpreter must have been started with the -debug option, and this -password option specifies the password that the interpreter generated. Only a debugger that knows this password is allowed to attach to the interpreter. Note that the passwords generated by java should not be considered cryptologically secure.

Commands

jdb understands the following debugging commands:

!!

This is a shorthand command that is replaced with the text of the last command entered. It may be followed with additional text that is appended to that previous command.

catch [ exception class ]

Cause 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

List all classes that have been loaded.

clear [ class:line ]

Remove the breakpoint set at the specified line of the specified class. Typing clear or stop with no arguments displays a list of current breakpoints and the line numbers that they are set at.

cont

Resume execution. This command should be used when the current thread is stopped at a breakpoint.

down [ n ]

Move down n frames in the call stack of the current thread. If n is not specified, move down one frame.

dump id(s)

Print 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 may be specified by name or by their eight-digit hexadecimal ID number. Threads may also be specified with the shorthand t@thread-number.

exit (or quit)

Quit jdb.

gc

Run the garbage collector to force unused objects to be reclaimed.

help (or ?)

Display a list of all jdb commands.

ignore exception class

Do not treat the specified exception as a breakpoint. This command turns off a catch command.

list [ line number ]

List the specified line of source code as well as several lines that appear before and after it. If no line number is specified, use 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.

load classname

Load the specified class into jdb.

locals

Display 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.

memory

Display a summary of memory usage for the Java program being debugged.

methods class

List all methods of the specified class. Use dump to list the instance variables or an object or the class (static) variables of a class.

print id(s)

Print the value of the specified item or items. Each item may be a class, object, field, or local variable, and may be specified by name or by eight-digit hexadecimal ID number. You may also refer to threads with the special syntax t@thread-number. The print command displays an object's value by invoking its toString() method.

resume [ thread(s) ]

Resume execution of the specified thread or threads. If no threads are specified, all suspended threads are resumed. See also suspend.

run [ class ] [ args ]

Run the main() method of the specified class, passing the specified arguments to it. If no class or arguments are specified, use the class and arguments specified on the jdb command line.

step

Run the current line of the current thread and stop again.

stop [ at class:line ]
stop [ in class.method ]

Set a breakpoint at the specified line of the specified class or at the beginning of the specified method of the specified class. Program execution stops when it reaches this line or enters the method. If stop is executed with no arguments, then it lists the current breakpoints.

suspend [ thread(s) ]

Suspend the specified thread or threads. If no threads are specified, suspend all running threads. Use resume to restart them.

thread thread

Set the current thread to the specified thread. This thread is used implicitly by a number of other jdb commands. The thread may be specified by name or number.

threadgroup name

Set the current thread group to the named thread group.

threadgroups

List all thread groups running in the Java interpreter session being debugged.

threads [ threadgroups ]

List all threads in the named thread group. If no thread group is specified, list all threads in the current thread group (specified by threadgroup).

up [ n ]

Move up n frames in the call stack of the current thread. If n is not specified, move up one frame.

use [ source-file-path ]

Set the path used by jdb to look up source files for the classes being debugged. If no path is specified, display the current source path being used.

where [ thread ] [ all ]

Display a stack trace for the specified thread. If no thread is specified, display a stack trace for the current thread. If all is specified, display a stack trace for all threads.

Environment

CLASSPATH

Specifies an ordered list (colon-separated on UNIX, semicolon-separated on Windows systems) of directories and ZIP files in which jdb should look for class definitions. When a path is specified with this environment variable, jdb always implicitly appends the location of the system classes to the end of the path. If this environment variable is not specified, the default path is the current directory and the system classes. This variable is overridden by the -classpath option.

See Also

java