1 .\" Copyright (c) 1994, 2019, 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.3.1
  23 .\"
  24 .TH "JDB" "1" "2018" "JDK 13" "JDK Commands"
  25 .hy
  26 .SH NAME
  27 .PP
  28 jdb \- find and fix bugs in Java platform programs
  29 .SH SYNOPSIS
  30 .PP
  31 \f[CB]jdb\f[R] [\f[I]options\f[R]] [\f[I]classname\f[R]]
  32 [\f[I]arguments\f[R]]
  33 .TP
  34 .B \f[I]options\f[R]
  35 This represents the \f[CB]jdb\f[R] command\-line options.
  36 See \f[B]Options for the jdb command\f[R].
  37 .RS
  38 .RE
  39 .TP
  40 .B \f[I]classname\f[R]
  41 This represents the name of the main class to debug.
  42 .RS
  43 .RE
  44 .TP
  45 .B \f[I]arguments\f[R]
  46 This represents the arguments that are passed to the \f[CB]main()\f[R]
  47 method of the class.
  48 .RS
  49 .RE
  50 .SH DESCRIPTION
  51 .PP
  52 The Java Debugger (JDB) is a simple command\-line debugger for Java
  53 classes.
  54 The \f[CB]jdb\f[R] command and its options call the JDB.
  55 The \f[CB]jdb\f[R] command demonstrates the Java Platform Debugger
  56 Architecture and provides inspection and debugging of a local or remote
  57 JVM.
  58 .SH START A JDB SESSION
  59 .PP
  60 There are many ways to start a JDB session.
  61 The most frequently used way is to have the JDB launch a new JVM with
  62 the main class of the application to be debugged.
  63 Do this by substituting the \f[CB]jdb\f[R] command for the \f[CB]java\f[R]
  64 command in the command line.
  65 For example, if your application\[aq]s main class is \f[CB]MyClass\f[R],
  66 then use the following command to debug it under the JDB:
  67 .RS
  68 .PP
  69 \f[CB]jdb\ MyClass\f[R]
  70 .RE
  71 .PP
  72 When started this way, the \f[CB]jdb\f[R] command calls a second JVM with
  73 the specified parameters, loads the specified class, and stops the JVM
  74 before executing that class\[aq]s first instruction.
  75 .PP
  76 Another way to use the \f[CB]jdb\f[R] command is by attaching it to a JVM
  77 that\[aq]s already running.
  78 Syntax for starting a JVM to which the \f[CB]jdb\f[R] command attaches
  79 when the JVM is running is as follows.
  80 This loads in\-process debugging libraries and specifies the kind of
  81 connection to be made.
  82 .RS
  83 .PP
  84 \f[CB]java\ \-agentlib:jdwp=transport=dt_socket,server=y,suspend=n\ MyClass\f[R]
  85 .RE
  86 .PP
  87 You can then attach the \f[CB]jdb\f[R] command to the JVM with the
  88 following command:
  89 .RS
  90 .PP
  91 \f[CB]jdb\ \-attach\ 8000\f[R]
  92 .RE
  93 .PP
  94 8000 is the address of the running JVM.
  95 .PP
  96 The \f[CB]MyClass\f[R] argument isn\[aq]t specified in the \f[CB]jdb\f[R]
  97 command line in this case because the \f[CB]jdb\f[R] command is connecting
  98 to an existing JVM instead of launching a new JVM.
  99 .PP
 100 There are many other ways to connect the debugger to a JVM, and all of
 101 them are supported by the \f[CB]jdb\f[R] command.
 102 The Java Platform Debugger Architecture has additional documentation on
 103 these connection options.
 104 .SH BREAKPOINTS
 105 .PP
 106 Breakpoints can be set in the JDB at line numbers or at the first
 107 instruction of a method, for example:
 108 .IP \[bu] 2
 109 The command \f[CB]stop\ at\ MyClass:22\f[R] sets a breakpoint at the first
 110 instruction for line 22 of the source file containing \f[CB]MyClass\f[R].
 111 .IP \[bu] 2
 112 The command \f[CB]stop\ in\ java.lang.String.length\f[R] sets a breakpoint
 113 at the beginning of the method \f[CB]java.lang.String.length\f[R].
 114 .IP \[bu] 2
 115 The command \f[CB]stop\ in\ MyClass.<clinit>\f[R] uses \f[CB]<clinit>\f[R]
 116 to identify the static initialization code for \f[CB]MyClass\f[R].
 117 .PP
 118 When a method is overloaded, you must also specify its argument types so
 119 that the proper method can be selected for a breakpoint.
 120 For example, \f[CB]MyClass.myMethod(int,java.lang.String)\f[R] or
 121 \f[CB]MyClass.myMethod()\f[R].
 122 .PP
 123 The \f[CB]clear\f[R] command removes breakpoints using the following
 124 syntax: \f[CB]clear\ MyClass:45\f[R].
 125 Using the \f[CB]clear\f[R] or \f[CB]stop\f[R] command with no argument
 126 displays a list of all breakpoints currently set.
 127 The \f[CB]cont\f[R] command continues execution.
 128 .SH STEPPING
 129 .PP
 130 The \f[CB]step\f[R] command advances execution to the next line whether
 131 it\[aq]s in the current stack frame or a called method.
 132 The \f[CB]next\f[R] command advances execution to the next line in the
 133 current stack frame.
 134 .SH EXCEPTIONS
 135 .PP
 136 When an exception occurs for which there isn\[aq]t a \f[CB]catch\f[R]
 137 statement anywhere in the throwing thread\[aq]s call stack, the JVM
 138 typically prints an exception trace and exits.
 139 When running under the JDB, however, control returns to the JDB at the
 140 offending throw.
 141 You can then use the \f[CB]jdb\f[R] command to diagnose the cause of the
 142 exception.
 143 .PP
 144 Use the \f[CB]catch\f[R] command to cause the debugged application to stop
 145 at other thrown exceptions, for example:
 146 \f[CB]catch\ java.io.FileNotFoundException\f[R] or \f[CB]catch\f[R]
 147 \f[CB]mypackage.BigTroubleException\f[R].
 148 Any exception that\[aq]s an instance of the specified class or subclass
 149 stops the application at the point where the exception is thrown.
 150 .PP
 151 The \f[CB]ignore\f[R] command negates the effect of an earlier
 152 \f[CB]catch\f[R] command.
 153 The \f[CB]ignore\f[R] command doesn\[aq]t cause the debugged JVM to ignore
 154 specific exceptions, but only to ignore the debugger.
 155 .SH OPTIONS FOR THE JDB COMMAND
 156 .PP
 157 When you use the \f[CB]jdb\f[R] command instead of the \f[CB]java\f[R]
 158 command on the command line, the \f[CB]jdb\f[R] command accepts many of
 159 the same options as the \f[CB]java\f[R] command.
 160 .PP
 161 The following options are accepted by the \f[CB]jdb\f[R] command:
 162 .TP
 163 .B \f[CB]\-help\f[R]
 164 Displays a help message.
 165 .RS
 166 .RE
 167 .TP
 168 .B \f[CB]\-sourcepath\f[R] \f[I]dir1\f[R]\f[CB]:\f[R]\f[I]dir2\f[R]\f[CB]:\f[R]...
 169 Uses the specified path to search for source files in the specified
 170 path.
 171 If this option is not specified, then use the default path of dot
 172 (\f[CB]\&.\f[R]).
 173 .RS
 174 .RE
 175 .TP
 176 .B \f[CB]\-attach\f[R] \f[I]address\f[R]
 177 Attaches the debugger to a running JVM with the default connection
 178 mechanism.
 179 .RS
 180 .RE
 181 .TP
 182 .B \f[CB]\-listen\f[R] \f[I]address\f[R]
 183 Waits for a running JVM to connect to the specified address with a
 184 standard connector.
 185 .RS
 186 .RE
 187 .TP
 188 .B \f[CB]\-listenany\f[R]
 189 Waits for a running JVM to connect at any available address using a
 190 standard connector.
 191 .RS
 192 .RE
 193 .TP
 194 .B \f[CB]\-launch\f[R]
 195 Starts the debugged application immediately upon startup of the
 196 \f[CB]jdb\f[R] command.
 197 The \f[CB]\-launch\f[R] option removes the need for the \f[CB]run\f[R]
 198 command.
 199 The debugged application is launched and then stopped just before the
 200 initial application class is loaded.
 201 At that point, you can set any necessary breakpoints and use the
 202 \f[CB]cont\f[R] command to continue execution.
 203 .RS
 204 .RE
 205 .TP
 206 .B \f[CB]\-listconnectors\f[R]
 207 Lists the connectors available in this JVM.
 208 .RS
 209 .RE
 210 .TP
 211 .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]....
 212 Connects to the target JVM with the named connector and listed argument
 213 values.
 214 .RS
 215 .RE
 216 .TP
 217 .B \f[CB]\-dbgtrace\f[R] [\f[I]flags\f[R]]
 218 Prints information for debugging the \f[CB]jdb\f[R] command.
 219 .RS
 220 .RE
 221 .TP
 222 .B \f[CB]\-tclient\f[R]
 223 Runs the application in the Java HotSpot VM client.
 224 .RS
 225 .RE
 226 .TP
 227 .B \f[CB]\-tserver\f[R]
 228 Runs the application in the Java HotSpot VM server.
 229 .RS
 230 .RE
 231 .TP
 232 .B \f[CB]\-J\f[R]\f[I]option\f[R]
 233 Passes \f[I]option\f[R] to the JVM, where option is one of the options
 234 described on the reference page for the Java application launcher.
 235 For example, \f[CB]\-J\-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 .RS
 238 .RE
 239 .PP
 240 The following options are forwarded to the debuggee process:
 241 .TP
 242 .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]]
 243 Turns on the verbose mode.
 244 .RS
 245 .RE
 246 .TP
 247 .B \f[CB]\-D\f[R]\f[I]name\f[R]\f[CB]=\f[R]\f[I]value\f[R]
 248 Sets a system property.
 249 .RS
 250 .RE
 251 .TP
 252 .B \f[CB]\-classpath\f[R] \f[I]dir\f[R]
 253 Lists directories separated by colons in which to look for classes.
 254 .RS
 255 .RE
 256 .TP
 257 .B \f[CB]\-X\f[R] \f[I]option\f[R]
 258 A nonstandard target JVM option.
 259 .RS
 260 .RE
 261 .PP
 262 Other options are supported to provide alternate mechanisms for
 263 connecting the debugger to the JVM that it\[aq]s to debug.