.\" Copyright (c) 1995, 2018, Oracle and/or its affiliates. All rights reserved.
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
.\"
.\" This code is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License version 2 only, as
.\" published by the Free Software Foundation.
.\"
.\" This code is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" version 2 for more details (a copy is included in the LICENSE file that
.\" accompanied this code).
.\"
.\" You should have received a copy of the GNU General Public License version
.\" 2 along with this work; if not, write to the Free Software Foundation,
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
.\" or visit www.oracle.com if you need additional information or have any
.\" questions.
.\"
.\" Automatically generated by Pandoc 2.3.1
.\"
.TH "JDB" "1" "2021" "JDK 17" "JDK Commands"
.hy
.SH NAME
.PP
jdb \- find and fix bugs in Java platform programs
.SH SYNOPSIS
.PP
\f[CB]jdb\f[R] [\f[I]options\f[R]] [\f[I]classname\f[R]]
[\f[I]arguments\f[R]]
.TP
.B \f[I]options\f[R]
This represents the \f[CB]jdb\f[R] command\-line options.
See \f[B]Options for the jdb command\f[R].
.RS
.RE
.TP
.B \f[I]classname\f[R]
This represents the name of the main class to debug.
.RS
.RE
.TP
.B \f[I]arguments\f[R]
This represents the arguments that are passed to the \f[CB]main()\f[R]
method of the class.
.RS
.RE
.SH DESCRIPTION
.PP
The Java Debugger (JDB) is a simple command\-line debugger for Java
classes.
The \f[CB]jdb\f[R] command and its options call the JDB.
The \f[CB]jdb\f[R] command demonstrates the Java Platform Debugger
Architecture and provides inspection and debugging of a local or remote
JVM.
.SH START A JDB SESSION
.PP
There are many ways to start a JDB session.
The most frequently used way is to have the JDB launch a new JVM with
the main class of the application to be debugged.
Do this by substituting the \f[CB]jdb\f[R] command for the \f[CB]java\f[R]
command in the command line.
For example, if your application\[aq]s main class is \f[CB]MyClass\f[R],
then use the following command to debug it under the JDB:
.RS
.PP
\f[CB]jdb\ MyClass\f[R]
.RE
.PP
When started this way, the \f[CB]jdb\f[R] command calls a second JVM with
the specified parameters, loads the specified class, and stops the JVM
before executing that class\[aq]s first instruction.
.PP
Another way to use the \f[CB]jdb\f[R] command is by attaching it to a JVM
that\[aq]s already running.
Syntax for starting a JVM to which the \f[CB]jdb\f[R] command attaches
when the JVM is running is as follows.
This loads in\-process debugging libraries and specifies the kind of
connection to be made.
.RS
.PP
\f[CB]java\ \-agentlib:jdwp=transport=dt_socket,server=y,suspend=n\ MyClass\f[R]
.RE
.PP
You can then attach the \f[CB]jdb\f[R] command to the JVM with the
following command:
.RS
.PP
\f[CB]jdb\ \-attach\ 8000\f[R]
.RE
.PP
8000 is the address of the running JVM.
.PP
The \f[CB]MyClass\f[R] argument isn\[aq]t specified in the \f[CB]jdb\f[R]
command line in this case because the \f[CB]jdb\f[R] command is connecting
to an existing JVM instead of launching a new JVM.
.PP
There are many other ways to connect the debugger to a JVM, and all of
them are supported by the \f[CB]jdb\f[R] command.
The Java Platform Debugger Architecture has additional documentation on
these connection options.
.SH BREAKPOINTS
.PP
Breakpoints can be set in the JDB at line numbers or at the first
instruction of a method, for example:
.IP \[bu] 2
The command \f[CB]stop\ at\ MyClass:22\f[R] sets a breakpoint at the first
instruction for line 22 of the source file containing \f[CB]MyClass\f[R].
.IP \[bu] 2
The command \f[CB]stop\ in\ java.lang.String.length\f[R] sets a breakpoint
at the beginning of the method \f[CB]java.lang.String.length\f[R].
.IP \[bu] 2
The command \f[CB]stop\ in\ MyClass.<clinit>\f[R] uses \f[CB]<clinit>\f[R]
to identify the static initialization code for \f[CB]MyClass\f[R].
.PP
When a method is overloaded, you must also specify its argument types so
that the proper method can be selected for a breakpoint.
For example, \f[CB]MyClass.myMethod(int,java.lang.String)\f[R] or
\f[CB]MyClass.myMethod()\f[R].
.PP
The \f[CB]clear\f[R] command removes breakpoints using the following
syntax: \f[CB]clear\ MyClass:45\f[R].
Using the \f[CB]clear\f[R] or \f[CB]stop\f[R] command with no argument
displays a list of all breakpoints currently set.
The \f[CB]cont\f[R] command continues execution.
.SH STEPPING
.PP
The \f[CB]step\f[R] command advances execution to the next line whether
it\[aq]s in the current stack frame or a called method.
The \f[CB]next\f[R] command advances execution to the next line in the
current stack frame.
.SH EXCEPTIONS
.PP
When an exception occurs for which there isn\[aq]t a \f[CB]catch\f[R]
statement anywhere in the throwing thread\[aq]s call stack, the JVM
typically prints an exception trace and exits.
When running under the JDB, however, control returns to the JDB at the
offending throw.
You can then use the \f[CB]jdb\f[R] command to diagnose the cause of the
exception.
.PP
Use the \f[CB]catch\f[R] command to cause the debugged application to stop
at other thrown exceptions, for example:
\f[CB]catch\ java.io.FileNotFoundException\f[R] or \f[CB]catch\f[R]
\f[CB]mypackage.BigTroubleException\f[R].
Any exception that\[aq]s an instance of the specified class or subclass
stops the application at the point where the exception is thrown.
.PP
The \f[CB]ignore\f[R] command negates the effect of an earlier
\f[CB]catch\f[R] command.
The \f[CB]ignore\f[R] command doesn\[aq]t cause the debugged JVM to ignore
specific exceptions, but only to ignore the debugger.
.SH OPTIONS FOR THE JDB COMMAND
.PP
When you use the \f[CB]jdb\f[R] command instead of the \f[CB]java\f[R]
command on the command line, the \f[CB]jdb\f[R] command accepts many of
the same options as the \f[CB]java\f[R] command.
.PP
The following options are accepted by the \f[CB]jdb\f[R] command:
.TP
.B \f[CB]\-help\f[R]
Displays a help message.
.RS
.RE
.TP
.B \f[CB]\-sourcepath\f[R] \f[I]dir1\f[R]\f[CB]:\f[R]\f[I]dir2\f[R]\f[CB]:\f[R]...
Uses the specified path to search for source files in the specified
path.
If this option is not specified, then use the default path of dot
(\f[CB]\&.\f[R]).
.RS
.RE
.TP
.B \f[CB]\-attach\f[R] \f[I]address\f[R]
Attaches the debugger to a running JVM with the default connection
mechanism.
.RS
.RE
.TP
.B \f[CB]\-listen\f[R] \f[I]address\f[R]
Waits for a running JVM to connect to the specified address with a
standard connector.
.RS
.RE
.TP
.B \f[CB]\-listenany\f[R]
Waits for a running JVM to connect at any available address using a
standard connector.
.RS
.RE
.TP
.B \f[CB]\-launch\f[R]
Starts the debugged application immediately upon startup of the
\f[CB]jdb\f[R] command.
The \f[CB]\-launch\f[R] option removes the need for the \f[CB]run\f[R]
command.
The debugged application is launched and then stopped just before the
initial application class is loaded.
At that point, you can set any necessary breakpoints and use the
\f[CB]cont\f[R] command to continue execution.
.RS
.RE
.TP
.B \f[CB]\-listconnectors\f[R]
Lists the connectors available in this JVM.
.RS
.RE
.TP
.B \f[CB]\-connect\f[R] \f[I]connector\-name\f[R]\f[CB]:\f[R]\f[I]name1\f[R]\f[CB]=\f[R]\f[I]value1\f[R]....
Connects to the target JVM with the named connector and listed argument
values.
.RS
.RE
.TP
.B \f[CB]\-dbgtrace\f[R] [\f[I]flags\f[R]]
Prints information for debugging the \f[CB]jdb\f[R] command.
.RS
.RE
.TP
.B \f[CB]\-tclient\f[R]
Runs the application in the Java HotSpot VM client.
.RS
.RE
.TP
.B \f[CB]\-tserver\f[R]
Runs the application in the Java HotSpot VM server.
.RS
.RE
.TP
.B \f[CB]\-J\f[R]\f[I]option\f[R]
Passes \f[I]option\f[R] to the JVM, where option is one of the options
described on the reference page for the Java application launcher.
For example, \f[CB]\-J\-Xms48m\f[R] sets the startup memory to 48 MB.
See \f[I]Overview of Java Options\f[R] in \f[B]java\f[R].
.RS
.RE
.PP
The following options are forwarded to the debuggee process:
.TP
.B \f[CB]\-v\f[R] or \f[CB]\-verbose\f[R][\f[CB]:\f[R]\f[I]class\f[R]|\f[CB]gc\f[R]|\f[CB]jni\f[R]]
Turns on the verbose mode.
.RS
.RE
.TP
.B \f[CB]\-D\f[R]\f[I]name\f[R]\f[CB]=\f[R]\f[I]value\f[R]
Sets a system property.
.RS
.RE
.TP
.B \f[CB]\-classpath\f[R] \f[I]dir\f[R]
Lists directories separated by colons in which to look for classes.
.RS
.RE
.TP
.B \f[CB]\-X\f[R] \f[I]option\f[R]
A nonstandard target JVM option.
.RS
.RE
.PP
Other options are supported to provide alternate mechanisms for
connecting the debugger to the JVM that it\[aq]s to debug.