1JDB(1) JDK Commands JDB(1)
2
6 jdb - find and fix bugs in Java platform programs
7
9 jdb [options] [classname] [arguments]
10 options
12 This represents the jdb command-line options. See Options for
13 the jdb command.
14 classname
16 This represents the name of the main class to debug.
17 arguments
19 This represents the arguments that are passed to the main()
20 method of the class.
21
23 The Java Debugger (JDB) is a simple command-line debugger for Java
24 classes. The jdb command and its options call the JDB. The jdb com‐
25 mand demonstrates the Java Platform Debugger Architecture and provides
26 inspection and debugging of a local or remote JVM.
27
29 There are many ways to start a JDB session. The most frequently used
30 way is to have the JDB launch a new JVM with the main class of the ap‐
31 plication to be debugged. Do this by substituting the jdb command for
32 the java command in the command line. For example, if your applica‐
33 tion's main class is MyClass, then use the following command to debug
34 it under the JDB:
35 jdb MyClass
37 When started this way, the jdb command calls a second JVM with the
39 specified parameters, loads the specified class, and stops the JVM be‐
40 fore executing that class's first instruction.
41 Another way to use the jdb command is by attaching it to a JVM that's
43 already running. Syntax for starting a JVM to which the jdb command
44 attaches when the JVM is running is as follows. This loads in-process
45 debugging libraries and specifies the kind of connection to be made.
46 java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n My‐
48 Class
49 You can then attach the jdb command to the JVM with the following com‐
51 mand:
52 jdb -attach 8000
54 8000 is the address of the running JVM.
56 The MyClass argument isn't specified in the jdb command line in this
58 case because the jdb command is connecting to an existing JVM instead
59 of launching a new JVM.
60 There are many other ways to connect the debugger to a JVM, and all of
62 them are supported by the jdb command. The Java Platform Debugger Ar‐
63 chitecture has additional documentation on these connection options.
64
66 Breakpoints can be set in the JDB at line numbers or at the first in‐
67 struction of a method, for example:
68 • The command stop at MyClass:22 sets a breakpoint at the first in‐
70 struction for line 22 of the source file containing MyClass.
71 • The command stop in java.lang.String.length sets a breakpoint at the
73 beginning of the method java.lang.String.length.
74 • The command stop in MyClass.<clinit> uses <clinit> to identify the
76 static initialization code for MyClass.
77 When a method is overloaded, you must also specify its argument types
79 so that the proper method can be selected for a breakpoint. For exam‐
80 ple, MyClass.myMethod(int,java.lang.String) or MyClass.myMethod().
81 The clear command removes breakpoints using the following syntax: clear
83 MyClass:45. Using the clear or stop command with no argument displays
84 a list of all breakpoints currently set. The cont command continues
85 execution.
86
88 The step command advances execution to the next line whether it's in
89 the current stack frame or a called method. The next command advances
90 execution to the next line in the current stack frame.
91
93 When an exception occurs for which there isn't a catch statement any‐
94 where in the throwing thread's call stack, the JVM typically prints an
95 exception trace and exits. When running under the JDB, however, con‐
96 trol returns to the JDB at the offending throw. You can then use the
97 jdb command to diagnose the cause of the exception.
98 Use the catch command to cause the debugged application to stop at oth‐
100 er thrown exceptions, for example: catch java.io.FileNotFoundException
101 or catch mypackage.BigTroubleException. Any exception that's an in‐
102 stance of the specified class or subclass stops the application at the
103 point where the exception is thrown.
104 The ignore command negates the effect of an earlier catch command. The
106 ignore command doesn't cause the debugged JVM to ignore specific excep‐
107 tions, but only to ignore the debugger.
108
110 When you use the jdb command instead of the java command on the command
111 line, the jdb command accepts many of the same options as the java com‐
112 mand.
113 The following options are accepted by the jdb command:
115 -help Displays a help message.
117 -sourcepath dir1:dir2:...
119 Uses the specified path to search for source files in the speci‐
120 fied path. If this option is not specified, then use the de‐
121 fault path of dot (.).
122 -attach address
124 Attaches the debugger to a running JVM with the default connec‐
125 tion mechanism.
126 -listen address
128 Waits for a running JVM to connect to the specified address with
129 a standard connector.
130 -listenany
132 Waits for a running JVM to connect at any available address us‐
133 ing a standard connector.
134 -launch
136 Starts the debugged application immediately upon startup of the
137 jdb command. The -launch option removes the need for the run
138 command. The debugged application is launched and then stopped
139 just before the initial application class is loaded. At that
140 point, you can set any necessary breakpoints and use the cont
141 command to continue execution.
142 -listconnectors
144 Lists the connectors available in this JVM.
145 -connect connector-name:name1=value1....
147 Connects to the target JVM with the named connector and listed
148 argument values.
149 -dbgtrace [flags]
151 Prints information for debugging the jdb command.
152 -tclient
154 Runs the application in the Java HotSpot VM client.
155 -trackallthreads
157 Track all threads as they are created, including virtual
158 threads. See Working With Virtual Threads below.
159 -tserver
161 Runs the application in the Java HotSpot VM server.
162 -Joption
164 Passes option to the JDB JVM, where option is one of the options
165 described on the reference page for the Java application launch‐
166 er. For example, -J-Xms48m sets the startup memory to 48 MB.
167 See Overview of Java Options in java.
168 The following options are forwarded to the debuggee process:
170 -Roption
172 Passes option to the debuggee JVM, where option is one of the
173 options described on the reference page for the Java application
174 launcher. For example, -R-Xms48m sets the startup memory to 48
175 MB. See Overview of Java Options in java.
176 -v or -verbose[:class|gc|jni]
178 Turns on the verbose mode.
179 -Dname=value
181 Sets a system property.
182 -classpath dir
184 Lists directories separated by colons in which to look for
185 classes.
186 -X option
188 A nonstandard target JVM option.
189 Other options are supported to provide alternate mechanisms for con‐
191 necting the debugger to the JVM that it's to debug.
192
194 Often virtual theads are created in such large numbers and frequency
195 that they can overwhelm a debugger. For this reason by default JDB
196 does not keep track of virtual threads as they are created. It will
197 only keep track of virtual threads that an event has arrived on, such
198 as a breakpoint event. The -trackallthreads option can be used to make
199 JDB track all virtual threads as they are created.
200 When JDB first connects, it requests a list of all known threads from
202 the Debug Agent. By default the debug agent does not return any virtu‐
203 al threads in this list, once again because the list could be so large
204 that it overwhelms the debugger. The Debug Agent has an includevirtu‐
205 althreads option that can be enabled to change this behavior so all
206 known virtual threads will be included in the list. The JDB -track‐
207 allthreads option will cause JDB to automatically enable the Debug
208 Agent's includevirtualthreads option when JDB launches an application
209 to debug. However, keep in mind that the Debug Agent may not know
210 about any virtual threads that were created before JDB attached to the
211 debugged application.
212JDK 21 2023 JDB(1)