jdb - find and fix bugs in Java platform programs
jdb [options] [classname] [arguments]
The Java Debugger (JDB) is a simple command-line debugger for Java classes. The jdb command and its options call the JDB. The jdb command demonstrates the Java Platform Debugger Architecture and provides inspection and debugging of a local or remote JVM.
There are many ways to start a JDB session. The most frequently used way is to have the JDB launch a new JVM with the main class of the application to be debugged. Do this by substituting the jdb command for the java command in the command line. For example, if your application's main class is MyClass, then use the following command to debug it under the JDB:
jdb MyClass
When started this way, the jdb command calls a second JVM with the specified parameters, loads the specified class, and stops the JVM before executing that class's first instruction.
Another way to use the jdb command is by attaching it to a JVM that's already running. Syntax for starting a JVM to which the jdb command attaches when the JVM is running is as follows. This loads in-process debugging libraries and specifies the kind of connection to be made.
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass
You can then attach the jdb command to the JVM with the following command:
jdb -attach 8000
8000 is the address of the running JVM.
The MyClass argument isn't specified in the jdb command line in this case because the jdb command is connecting to an existing JVM instead of launching a new JVM.
There are many other ways to connect the debugger to a JVM, and all of them are supported by the jdb command. The Java Platform Debugger Architecture has additional documentation on these connection options.
Breakpoints can be set in the JDB at line numbers or at the first instruction of a method, for example:
When a method is overloaded, you must also specify its argument types so that the proper method can be selected for a breakpoint. For example, MyClass.myMethod(int,java.lang.String) or MyClass.myMethod().
The clear command removes breakpoints using the following syntax: clear MyClass:45. Using the clear or stop command with no argument displays a list of all breakpoints currently set. The cont command continues execution.
The step command advances execution to the next line whether it's in the current stack frame or a called method. The next command advances execution to the next line in the current stack frame.
When an exception occurs for which there isn't a catch statement anywhere in the throwing thread's call stack, the JVM typically prints an exception trace and exits. When running under the JDB, however, control returns to the JDB at the offending throw. You can then use the jdb command to diagnose the cause of the exception.
Use the catch command to cause the debugged application to stop at other thrown exceptions, for example: catch java.io.FileNotFoundException or catch mypackage.BigTroubleException. Any exception that's an instance of the specified class or subclass stops the application at the point where the exception is thrown.
The ignore command negates the effect of an earlier catch command. The ignore command doesn't cause the debugged JVM to ignore specific exceptions, but only to ignore the debugger.
When you use the jdb command instead of the java command on the command line, the jdb command accepts many of the same options as the java command.
The following options are accepted by the jdb command:
The following options are forwarded to the debuggee process:
Other options are supported to provide alternate mechanisms for connecting the debugger to the JVM that it's to debug.
Often virtual theads are created in such large numbers and frequency that they can overwhelm a debugger. For this reason by default JDB does not keep track of virtual threads as they are created. It will only keep track of virtual threads that an event has arrived on, such as a breakpoint event. The -trackallthreads option can be used to make JDB track all virtual threads as they are created.
When JDB first connects, it requests a list of all known threads from the Debug Agent. By default the debug agent does not return any virtual threads in this list, once again because the list could be so large that it overwhelms the debugger. The Debug Agent has an includevirtualthreads option that can be enabled to change this behavior so all known virtual threads will be included in the list. The JDB -trackallthreads option will cause JDB to automatically enable the Debug Agent's includevirtualthreads option when JDB launches an application to debug. However, keep in mind that the Debug Agent may not know about any virtual threads that were created before JDB attached to the debugged application.