# jdb - The Java Debugger

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

## SYNOPSIS

       jdb [ options ]

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

> >        % jdb sun.applet.AppletViewer

> > or

> >        % 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 -debug option. When started with the -debug option, the Java interpreter prints out a password for jdb's use.

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

> >        % jdb -host <hostname> -password <password>

> > When using jdb on a program that loads a shared library, you must use a debug version of that library. You can create a debug version of the library by simply appending "`_g`" to the file name. For example, if the file name is `libhello.so`, you would change the file name to `libhello_g.so`.

> ### 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
> >   Lists the current threads. This lists all threads, organized by thread group. Threads are referenced by their object ID, or if they are in the current thread group, with the form `t@<index>`, such as `t@3`.

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

## OPTIONS

> 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 these 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 -debug option.

## ENVIRONMENT VARIABLES

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

>          .:/home/avh/classes:/usr/local/java/classes

## SEE ALSO

> javac, java, javah, javap, javadoc, CLASSPATH