[Chapter 16] jdb
Author: David Flanagan
Date: Thu Jul 31 16:04:28 1997

#

| Chapter 16 JDK Tools |

# jdb

## Name

jdb---The Java Debugger

## 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

javap |  | native2ascii