264 lines
8.7 KiB
Groff
264 lines
8.7 KiB
Groff
.\" Copyright (c) 1994, 2019, 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" "2020" "JDK 14" "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.
|