1JDB(1)                           JDK Commands                           JDB(1)
2
3
4

NAME

6       jdb - find and fix bugs in Java platform programs
7

SYNOPSIS

9       jdb [options] [classname] [arguments]
10
11       options
12              This  represents  the jdb command-line options.  See Options for
13              the jdb command.
14
15       classname
16              This represents the name of the main class to debug.
17
18       arguments
19              This represents the arguments that  are  passed  to  the  main()
20              method of the class.
21

DESCRIPTION

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

START A JDB SESSION

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
36              jdb MyClass
37
38       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
42       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
47              java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n My‐
48              Class
49
50       You  can then attach the jdb command to the JVM with the following com‐
51       mand:
52
53              jdb -attach 8000
54
55       8000 is the address of the running JVM.
56
57       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
61       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

BREAKPOINTS

66       Breakpoints can be set in the JDB at line numbers or at the  first  in‐
67       struction of a method, for example:
68
69       • 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
72       • The command stop in java.lang.String.length sets a breakpoint at  the
73         beginning of the method java.lang.String.length.
74
75       • The  command  stop in MyClass.<clinit>  uses <clinit> to identify the
76         static initialization code for MyClass.
77
78       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
82       The clear command  removes  breakpoints  using  the  following  syntax:
83       clear MyClass:45.   Using  the  clear  or stop command with no argument
84       displays a list of all breakpoints currently  set.   The  cont  command
85       continues execution.
86

STEPPING

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

EXCEPTIONS

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
99       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
105       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

OPTIONS FOR THE JDB COMMAND

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
114       The following options are accepted by the jdb command:
115
116       -help  Displays a help message.
117
118       -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
123       -attach address
124              Attaches  the debugger to a running JVM with the default connec‐
125              tion mechanism.
126
127       -listen address
128              Waits for a running JVM to connect to the specified address with
129              a standard connector.
130
131       -listenany
132              Waits  for a running JVM to connect at any available address us‐
133              ing a standard connector.
134
135       -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
143       -listconnectors
144              Lists the connectors available in this JVM.
145
146       -connect connector-name:name1=value1....
147              Connects  to  the target JVM with the named connector and listed
148              argument values.
149
150       -dbgtrace [flags]
151              Prints information for debugging the jdb command.
152
153       -tclient
154              Runs the application in the Java HotSpot VM client.
155
156       -tserver
157              Runs the application in the Java HotSpot VM server.
158
159       -Joption
160              Passes option to the JVM, where option is one of the options de‐
161              scribed on the reference page for the Java application launcher.
162              For example, -J-Xms48m sets the startup memory to  48  MB.   See
163              Overview of Java Options in java.
164
165       The following options are forwarded to the debuggee process:
166
167       -v or -verbose[:class|gc|jni]
168              Turns on the verbose mode.
169
170       -Dname=value
171              Sets a system property.
172
173       -classpath dir
174              Lists  directories  separated  by  colons  in  which to look for
175              classes.
176
177       -X option
178              A nonstandard target JVM option.
179
180       Other options are supported to provide alternate  mechanisms  for  con‐
181       necting the debugger to the JVM that it's to debug.
182
183
184
185JDK 17                               2021                               JDB(1)