1jdb(1)                            Basic Tools                           jdb(1)
2
3
4

NAME

6       jdb - Finds and fixes bugs in Java platform programs.
7

SYNOPSIS

9       jdb [options] [classname]  [arguments]
10
11
12       options
13              Command-line options. See Options.
14
15       classname
16              Name of the main class to debug.
17
18       arguments
19              Arguments passed to the main() method of the class.
20

DESCRIPTION

22       The Java Debugger (JDB) is a simple command-line debugger for Java
23       classes. The jdb command and its options call the JDB. The jdb command
24       demonstrates the Java Platform Debugger Architecture (JDBA) and
25       provides inspection and debugging of a local or remote Java Virtual
26       Machine (JVM). See Java Platform Debugger Architecture (JDBA) at
27       http://docs.oracle.com/javase/8/docs/technotes/guides/jpda/index.html
28
29   START A JDB SESSION
30       There are many ways to start a JDB session. The most frequently used
31       way is to have JDB launch a new JVM with the main class of the
32       application to be debugged. Do this by substituting the jdb command for
33       the java command in the command line. For example, if your
34       application's main class is MyClass, then use the following command to
35       debug it under JDB:
36
37       jdb MyClass
38
39       When started this way, the jdb command calls a second JVM with the
40       specified parameters, loads the specified class, and stops the JVM
41       before executing that class's first instruction.
42
43       Another way to use the jdb command is by attaching it to a JVM that is
44       already running. Syntax for starting a JVM to which the jdb command
45       attaches when the JVM is running is as follows. This loads in-process
46       debugging libraries and specifies the kind of connection to be made.
47
48       java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass
49
50       You can then attach the jdb command to the JVM with the following
51       command:
52
53       jdb -attach 8000
54
55       The MyClass argument is not specified in the jdb command line in this
56       case because the jdb command is connecting to an existing JVM instead
57       of launching a new JVM.
58
59       There are many other ways to connect the debugger to a JVM, and all of
60       them are supported by the jdb command. The Java Platform Debugger
61       Architecture has additional documentation on these connection options.
62
63   BASIC JDB COMMANDS
64       The following is a list of the basic jdb commands. The JDB supports
65       other commands that you can list with the -help option.
66
67       help or ?
68              The help or ? commands display the list of recognized commands
69              with a brief description.
70
71       run    After you start JDB and set breakpoints, you can use the run
72              command to execute the debugged application. The run command is
73              available only when the jdb command starts the debugged
74              application as opposed to attaching to an existing JVM.
75
76       cont   Continues execution of the debugged application after a
77              breakpoint, exception, or step.
78
79       print  Displays Java objects and primitive values. For variables or
80              fields of primitive types, the actual value is printed. For
81              objects, a short description is printed. See the dump command to
82              find out how to get more information about an object.
83
84              Note: To display local variables, the containing class must have
85              been compiled with the javac -g option.
86
87              The print command supports many simple Java expressions
88              including those with method invocations, for example:
89
90              print MyClass.myStaticField
91              print myObj.myInstanceField
92              print i + j + k (i, j, k are primities and either fields or local variables)
93              print myObj.myMethod() (if myMethod returns a non-null)
94              print new java.lang.String("Hello").length()
95
96
97
98       dump   For primitive values, the dump command is identical to the print
99              command. For objects, the dump command prints the current value
100              of each field defined in the object. Static and instance fields
101              are included. The dump command supports the same set of
102              expressions as the print command.
103
104       threads
105              List the threads that are currently running. For each thread,
106              its name and current status are printed and an index that can be
107              used in other commands. In this example, the thread index is 4,
108              the thread is an instance of java.lang.Thread, the thread name
109              is main, and it is currently running.
110
111              4. (java.lang.Thread)0x1 main      running
112
113
114
115       thread Select a thread to be the current thread. Many jdb commands are
116              based on the setting of the current thread. The thread is
117              specified with the thread index described in the threads
118              command.
119
120       where  The where command with no arguments dumps the stack of the
121              current thread. The whereall command dumps the stack of all
122              threads in the current thread group. The wherethreadindex
123              command dumps the stack of the specified thread.
124
125              If the current thread is suspended either through an event such
126              as a breakpoint or through the suspend command, then local
127              variables and fields can be displayed with the print and dump
128              commands. The up and down commands select which stack frame is
129              the current stack frame.
130
131   BREAKPOINTS
132       Breakpoints can be set in JDB at line numbers or at the first
133       instruction of a method, for example:
134
135       · The command stop at MyClass:22 sets a breakpoint at the first
136         instruction for line 22 of the source file containing MyClass.
137
138       · The command stop in java.lang.String.length sets a breakpoint at the
139         beginning of the method java.lang.String.length.
140
141       · The command stop in MyClass.<clinit> uses <clinit> to identify the
142         static initialization code for MyClass.
143
144       When a method is overloaded, you must also specify its argument types
145       so that the proper method can be selected for a breakpoint. For
146       example, MyClass.myMethod(int,java.lang.String) or MyClass.myMethod().
147
148       The clear command removes breakpoints using the following syntax: clear
149       MyClass:45. Using the clear or stop command with no argument displays a
150       list of all breakpoints currently set. The cont command continues
151       execution.
152
153   STEPPING
154       The step command advances execution to the next line whether it is in
155       the current stack frame or a called method. The next command advances
156       execution to the next line in the current stack frame.
157
158   EXCEPTIONS
159       When an exception occurs for which there is not a catch statement
160       anywhere in the throwing thread's call stack, the JVM typically prints
161       an exception trace and exits. When running under JDB, however, control
162       returns to JDB at the offending throw. You can then use the jdb command
163       to diagnose the cause of the exception.
164
165       Use the catch command to cause the debugged application to stop at
166       other thrown exceptions, for example: catch
167       java.io.FileNotFoundException or catchmypackage.BigTroubleException.
168       Any exception that is an instance of the specified class or subclass
169       stops the application at the point where it is thrown.
170
171       The ignore command negates the effect of an earlier catch command. The
172       ignore command does not cause the debugged JVM to ignore specific
173       exceptions, but only to ignore the debugger.
174

OPTIONS

176       When you use the jdb command instead of the java command on the command
177       line, the jdb command accepts many of the same options as the java
178       command, including -D, -classpath, and -X options. The following list
179       contains additional options that are accepted by the jdb command.
180
181       Other options are supported to provide alternate mechanisms for
182       connecting the debugger to the JVM it is to debug. For additional
183       documentation about these connection alternatives, see Java Platform
184       Debugger Architecture (JPDA) at
185       http://docs.oracle.com/javase/8/docs/technotes/guides/jpda/index.html
186
187       -help
188              Displays a help message.
189
190       -sourcepath dir1:dir2: . . .
191              Uses the specified path to search for source files in the
192              specified path. If this option is not specified, then use the
193              default path of dot (.).
194
195       -attach address
196              Attaches the debugger to a running JVM with the default
197              connection mechanism.
198
199       -listen address
200              Waits for a running JVM to connect to the specified address with
201              a standard connector.
202
203       -launch
204              Starts the debugged application immediately upon startup of JDB.
205              The -launch option removes the need for the run command. The
206              debugged application is launched and then stopped just before
207              the initial application class is loaded. At that point, you can
208              set any necessary breakpoints and use the cont command to
209              continue execution.
210
211       -listconnectors
212              List the connectors available in this JVM.
213
214       -connect connector-name:name1=value1
215              Connects to the target JVM with the named connector and listed
216              argument values.
217
218       -dbgtrace [flags]
219              Prints information for debugging the jdb command.
220
221       -tclient
222              Runs the application in the Java HotSpot VM client.
223
224       -tserver
225              Runs the application in the Java HotSpot VM server.
226
227       -Joption
228              Passes option to the JVM, where option is one of the options
229              described on the reference page for the Java application
230              launcher. For example, -J-Xms48m sets the startup memory to 48
231              MB. See java(1).
232

OPTIONS FORWARDED TO THE DEBUGGER PROCESS

234       -v -verbose[:class|gc|jni]
235              Turns on verbose mode.
236
237       -Dname=value
238              Sets a system property.
239
240       -classpath dir
241              Lists directories separated by colons in which to look for
242              classes.
243
244       -Xoption
245              Nonstandard target JVM option.
246

SEE ALSO

248       · javac(1)
249
250       · java(1)
251
252       · javah(1)
253
254       · javap(1)
255
256
257
258JDK 8                          21 November 2013                         jdb(1)
Impressum