1 .\" Copyright (c) 1995, 2023, Oracle and/or its affiliates. All rights reserved.
  2 .\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  3 .\"
  4 .\" This code is free software; you can redistribute it and/or modify it
  5 .\" under the terms of the GNU General Public License version 2 only, as
  6 .\" published by the Free Software Foundation.
  7 .\"
  8 .\" This code is distributed in the hope that it will be useful, but WITHOUT
  9 .\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 10 .\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 11 .\" version 2 for more details (a copy is included in the LICENSE file that
 12 .\" accompanied this code).
 13 .\"
 14 .\" You should have received a copy of the GNU General Public License version
 15 .\" 2 along with this work; if not, write to the Free Software Foundation,
 16 .\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 17 .\"
 18 .\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 19 .\" or visit www.oracle.com if you need additional information or have any
 20 .\" questions.
 21 .\"
 22 .\" Automatically generated by Pandoc 2.19.2
 23 .\"
 24 .\" Define V font for inline verbatim, using C font in formats
 25 .\" that render this, and otherwise B font.
 26 .ie "\f[CB]x\f[R]"x" \{\
 27 . ftr V B
 28 . ftr VI BI
 29 . ftr VB B
 30 . ftr VBI BI
 31 .\}
 32 .el \{\
 33 . ftr V CR
 34 . ftr VI CI
 35 . ftr VB CB
 36 . ftr VBI CBI
 37 .\}
 38 .TH "JDB" "1" "2023" "JDK 21-ea" "JDK Commands"
 39 .hy
 40 .SH NAME
 41 .PP
 42 jdb - find and fix bugs in Java platform programs
 43 .SH SYNOPSIS
 44 .PP
 45 \f[V]jdb\f[R] [\f[I]options\f[R]] [\f[I]classname\f[R]]
 46 [\f[I]arguments\f[R]]
 47 .TP
 48 \f[I]options\f[R]
 49 This represents the \f[V]jdb\f[R] command-line options.
 50 See \f[B]Options for the jdb command\f[R].
 51 .TP
 52 \f[I]classname\f[R]
 53 This represents the name of the main class to debug.
 54 .TP
 55 \f[I]arguments\f[R]
 56 This represents the arguments that are passed to the \f[V]main()\f[R]
 57 method of the class.
 58 .SH DESCRIPTION
 59 .PP
 60 The Java Debugger (JDB) is a simple command-line debugger for Java
 61 classes.
 62 The \f[V]jdb\f[R] command and its options call the JDB.
 63 The \f[V]jdb\f[R] command demonstrates the Java Platform Debugger
 64 Architecture and provides inspection and debugging of a local or remote
 65 JVM.
 66 .SH START A JDB SESSION
 67 .PP
 68 There are many ways to start a JDB session.
 69 The most frequently used way is to have the JDB launch a new JVM with
 70 the main class of the application to be debugged.
 71 Do this by substituting the \f[V]jdb\f[R] command for the \f[V]java\f[R]
 72 command in the command line.
 73 For example, if your application\[aq]s main class is \f[V]MyClass\f[R],
 74 then use the following command to debug it under the JDB:
 75 .RS
 76 .PP
 77 \f[V]jdb MyClass\f[R]
 78 .RE
 79 .PP
 80 When started this way, the \f[V]jdb\f[R] command calls a second JVM with
 81 the specified parameters, loads the specified class, and stops the JVM
 82 before executing that class\[aq]s first instruction.
 83 .PP
 84 Another way to use the \f[V]jdb\f[R] command is by attaching it to a JVM
 85 that\[aq]s already running.
 86 Syntax for starting a JVM to which the \f[V]jdb\f[R] command attaches
 87 when the JVM is running is as follows.
 88 This loads in-process debugging libraries and specifies the kind of
 89 connection to be made.
 90 .RS
 91 .PP
 92 \f[V]java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass\f[R]
 93 .RE
 94 .PP
 95 You can then attach the \f[V]jdb\f[R] command to the JVM with the
 96 following command:
 97 .RS
 98 .PP
 99 \f[V]jdb -attach 8000\f[R]
100 .RE
101 .PP
102 8000 is the address of the running JVM.
103 .PP
104 The \f[V]MyClass\f[R] argument isn\[aq]t specified in the \f[V]jdb\f[R]
105 command line in this case because the \f[V]jdb\f[R] command is
106 connecting to an existing JVM instead of launching a new JVM.
107 .PP
108 There are many other ways to connect the debugger to a JVM, and all of
109 them are supported by the \f[V]jdb\f[R] command.
110 The Java Platform Debugger Architecture has additional documentation on
111 these connection options.
112 .SH BREAKPOINTS
113 .PP
114 Breakpoints can be set in the JDB at line numbers or at the first
115 instruction of a method, for example:
116 .IP \[bu] 2
117 The command \f[V]stop at MyClass:22\f[R] sets a breakpoint at the first
118 instruction for line 22 of the source file containing \f[V]MyClass\f[R].
119 .IP \[bu] 2
120 The command \f[V]stop in java.lang.String.length\f[R] sets a breakpoint
121 at the beginning of the method \f[V]java.lang.String.length\f[R].
122 .IP \[bu] 2
123 The command \f[V]stop in MyClass.<clinit>\f[R] uses \f[V]<clinit>\f[R]
124 to identify the static initialization code for \f[V]MyClass\f[R].
125 .PP
126 When a method is overloaded, you must also specify its argument types so
127 that the proper method can be selected for a breakpoint.
128 For example, \f[V]MyClass.myMethod(int,java.lang.String)\f[R] or
129 \f[V]MyClass.myMethod()\f[R].
130 .PP
131 The \f[V]clear\f[R] command removes breakpoints using the following
132 syntax: \f[V]clear MyClass:45\f[R].
133 Using the \f[V]clear\f[R] or \f[V]stop\f[R] command with no argument
134 displays a list of all breakpoints currently set.
135 The \f[V]cont\f[R] command continues execution.
136 .SH STEPPING
137 .PP
138 The \f[V]step\f[R] command advances execution to the next line whether
139 it\[aq]s in the current stack frame or a called method.
140 The \f[V]next\f[R] command advances execution to the next line in the
141 current stack frame.
142 .SH EXCEPTIONS
143 .PP
144 When an exception occurs for which there isn\[aq]t a \f[V]catch\f[R]
145 statement anywhere in the throwing thread\[aq]s call stack, the JVM
146 typically prints an exception trace and exits.
147 When running under the JDB, however, control returns to the JDB at the
148 offending throw.
149 You can then use the \f[V]jdb\f[R] command to diagnose the cause of the
150 exception.
151 .PP
152 Use the \f[V]catch\f[R] command to cause the debugged application to
153 stop at other thrown exceptions, for example:
154 \f[V]catch java.io.FileNotFoundException\f[R] or \f[V]catch\f[R]
155 \f[V]mypackage.BigTroubleException\f[R].
156 Any exception that\[aq]s an instance of the specified class or subclass
157 stops the application at the point where the exception is thrown.
158 .PP
159 The \f[V]ignore\f[R] command negates the effect of an earlier
160 \f[V]catch\f[R] command.
161 The \f[V]ignore\f[R] command doesn\[aq]t cause the debugged JVM to
162 ignore specific exceptions, but only to ignore the debugger.
163 .SH OPTIONS FOR THE JDB COMMAND
164 .PP
165 When you use the \f[V]jdb\f[R] command instead of the \f[V]java\f[R]
166 command on the command line, the \f[V]jdb\f[R] command accepts many of
167 the same options as the \f[V]java\f[R] command.
168 .PP
169 The following options are accepted by the \f[V]jdb\f[R] command:
170 .TP
171 \f[V]-help\f[R]
172 Displays a help message.
173 .TP
174 \f[V]-sourcepath\f[R] \f[I]dir1\f[R]\f[V]:\f[R]\f[I]dir2\f[R]\f[V]:\f[R]...
175 Uses the specified path to search for source files in the specified
176 path.
177 If this option is not specified, then use the default path of dot
178 (\f[V].\f[R]).
179 .TP
180 \f[V]-attach\f[R] \f[I]address\f[R]
181 Attaches the debugger to a running JVM with the default connection
182 mechanism.
183 .TP
184 \f[V]-listen\f[R] \f[I]address\f[R]
185 Waits for a running JVM to connect to the specified address with a
186 standard connector.
187 .TP
188 \f[V]-listenany\f[R]
189 Waits for a running JVM to connect at any available address using a
190 standard connector.
191 .TP
192 \f[V]-launch\f[R]
193 Starts the debugged application immediately upon startup of the
194 \f[V]jdb\f[R] command.
195 The \f[V]-launch\f[R] option removes the need for the \f[V]run\f[R]
196 command.
197 The debugged application is launched and then stopped just before the
198 initial application class is loaded.
199 At that point, you can set any necessary breakpoints and use the
200 \f[V]cont\f[R] command to continue execution.
201 .TP
202 \f[V]-listconnectors\f[R]
203 Lists the connectors available in this JVM.
204 .TP
205 \f[V]-connect\f[R] \f[I]connector-name\f[R]\f[V]:\f[R]\f[I]name1\f[R]\f[V]=\f[R]\f[I]value1\f[R]....
206 Connects to the target JVM with the named connector and listed argument
207 values.
208 .TP
209 \f[V]-dbgtrace\f[R] [\f[I]flags\f[R]]
210 Prints information for debugging the \f[V]jdb\f[R] command.
211 .TP
212 \f[V]-tclient\f[R]
213 Runs the application in the Java HotSpot VM client.
214 .TP
215 \f[V]-trackallthreads\f[R]
216 Track all threads as they are created, including virtual threads.
217 See \f[B]Working With Virtual Threads\f[R] below.
218 .TP
219 \f[V]-tserver\f[R]
220 Runs the application in the Java HotSpot VM server.
221 .TP
222 \f[V]-J\f[R]\f[I]option\f[R]
223 Passes \f[I]option\f[R] to the JDB JVM, where option is one of the
224 options described on the reference page for the Java application
225 launcher.
226 For example, \f[V]-J-Xms48m\f[R] sets the startup memory to 48 MB.
227 See \f[I]Overview of Java Options\f[R] in \f[B]java\f[R].
228 .PP
229 The following options are forwarded to the debuggee process:
230 .TP
231 \f[V]-R\f[R]\f[I]option\f[R]
232 Passes \f[I]option\f[R] to the debuggee JVM, where option is one of the
233 options described on the reference page for the Java application
234 launcher.
235 For example, \f[V]-R-Xms48m\f[R] sets the startup memory to 48 MB.
236 See \f[I]Overview of Java Options\f[R] in \f[B]java\f[R].
237 .TP
238 \f[V]-v\f[R] or \f[V]-verbose\f[R][\f[V]:\f[R]\f[I]class\f[R]|\f[V]gc\f[R]|\f[V]jni\f[R]]
239 Turns on the verbose mode.
240 .TP
241 \f[V]-D\f[R]\f[I]name\f[R]\f[V]=\f[R]\f[I]value\f[R]
242 Sets a system property.
243 .TP
244 \f[V]-classpath\f[R] \f[I]dir\f[R]
245 Lists directories separated by colons in which to look for classes.
246 .TP
247 \f[V]-X\f[R] \f[I]option\f[R]
248 A nonstandard target JVM option.
249 .PP
250 Other options are supported to provide alternate mechanisms for
251 connecting the debugger to the JVM that it\[aq]s to debug.
252 .SH WORKING WITH VIRTUAL THREADS
253 .PP
254 Often virtual theads are created in such large numbers and frequency
255 that they can overwhelm a debugger.
256 For this reason by default JDB does not keep track of virtual threads as
257 they are created.
258 It will only keep track of virtual threads that an event has arrived on,
259 such as a breakpoint event.
260 The \f[V]-trackallthreads\f[R] option can be used to make JDB track all
261 virtual threads as they are created.
262 .PP
263 When JDB first connects, it requests a list of all known threads from
264 the Debug Agent.
265 By default the debug agent does not return any virtual threads in this
266 list, once again because the list could be so large that it overwhelms
267 the debugger.
268 The Debug Agent has an \f[V]includevirtualthreads\f[R] option that can
269 be enabled to change this behavior so all known virtual threads will be
270 included in the list.
271 The JDB \f[V]-trackallthreads\f[R] option will cause JDB to
272 automatically enable the Debug Agent\[aq]s
273 \f[V]includevirtualthreads\f[R] option when JDB launches an application
274 to debug.
275 However, keep in mind that the Debug Agent may not know about any
276 virtual threads that were created before JDB attached to the debugged
277 application.