JDB

NAME

jdb- find and fix bugs in Java platform programs  

SYNOPSIS

V]jdbR] [I]optionsR]] [I]classnameR]] [I]argumentsR]]

I]optionsR]

This represents the V]jdbR] comman-line options. See B]Options for the jdb commandR].

I]classnameR]

This represents the name of the main class to debug.

I]argumentsR]

This represents the arguments that are passed to the V]main()R] method of the class.

DESCRIPTION

The Java Debugger (JDB) is a simple comman-line debugger for Java classes. The V]jdbR] command and its options call the JDB. The V]jdbR] command demonstrates the Java Platform Debugger Architecture and provides inspection and debugging of a local or remote JVM.  

START A JDB SESSION

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 V]jdbR] command for the V]javaR] command in the command line. For example, if your application[aq]s main class is V]MyClassR], then use the following command to debug it under the JDB:

V]jdb MyClassR]

When started this way, the V]jdbR] command calls a second JVM with the specified parameters, loads the specified class, and stops the JVM before executing that class[aq]s first instruction.

Another way to use the V]jdbR] command is by attaching it to a JVM that[aq]s already running. Syntax for starting a JVM to which the V]jdbR] command attaches when the JVM is running is as follows. This loads i-process debugging libraries and specifies the kind of connection to be made.

V]java-agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClassR]

You can then attach the V]jdbR] command to the JVM with the following command:

V]jdb-attach 8000R]

8000 is the address of the running JVM.

The V]MyClassR] argument isn[aq]t specified in the V]jdbR] command line in this case because the V]jdbR] 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 V]jdbR] command. The Java Platform Debugger Architecture has additional documentation on these connection options.  

BREAKPOINTS

Breakpoints can be set in the JDB at line numbers or at the first instruction of a method, for example:

[bu]

The command V]stop at MyClass:22R] sets a breakpoint at the first instruction for line 22 of the source file containing V]MyClassR].

[bu]

The command V]stop in java.lang.String.lengthR] sets a breakpoint at the beginning of the method V]java.lang.String.lengthR].

[bu]

The command V]stop in MyClass.<clinit>R] uses V]<clinit>R] to identify the static initialization code for V]MyClassR].

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, V]MyClass.myMethod(int,java.lang.String)R] or V]MyClass.myMethod()R].

The V]clearR] command removes breakpoints using the following syntax: V]clear MyClass:45R]. Using the V]clearR] or V]stopR] command with no argument displays a list of all breakpoints currently set. The V]contR] command continues execution.  

STEPPING

The V]stepR] command advances execution to the next line whether it[aq]s in the current stack frame or a called method. The V]nextR] command advances execution to the next line in the current stack frame.  

EXCEPTIONS

When an exception occurs for which there isn[aq]t a V]catchR] statement anywhere in the throwing thread[aq]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 V]jdbR] command to diagnose the cause of the exception.

Use the V]catchR] command to cause the debugged application to stop at other thrown exceptions, for example: V]catch java.io.FileNotFoundExceptionR] or V]catchR] V]mypackage.BigTroubleExceptionR]. Any exception that[aq]s an instance of the specified class or subclass stops the application at the point where the exception is thrown.

The V]ignoreR] command negates the effect of an earlier V]catchR] command. The V]ignoreR] command doesn[aq]t cause the debugged JVM to ignore specific exceptions, but only to ignore the debugger.  

OPTIONS FOR THE JDB COMMAND

When you use the V]jdbR] command instead of the V]javaR] command on the command line, the V]jdbR] command accepts many of the same options as the V]javaR] command.

The following options are accepted by the V]jdbR] command:

V-helpR]

Displays a help message.

V-sourcepathR] I]dir1R]V]:R]I]dir2R]V]:R]...

Uses the specified path to search for source files in the specified path. If this option is not specified, then use the default path of dot (V].R]).

V-attachR] I]addressR]

Attaches the debugger to a running JVM with the default connection mechanism.

V-listenR] I]addressR]

Waits for a running JVM to connect to the specified address with a standard connector.

V-listenanyR]

Waits for a running JVM to connect at any available address using a standard connector.

V-launchR]

Starts the debugged application immediately upon startup of the V]jdbR] command. The V-launchR] option removes the need for the V]runR] command. The debugged application is launched and then stopped just before the initial application class is loaded. At that point, you can set any necessary breakpoints and use the V]contR] command to continue execution.

V-listconnectorsR]

Lists the connectors available in this JVM.

V-connectR] I]connecto-nameR]V]:R]I]name1R]V]=R]I]value1R]....

Connects to the target JVM with the named connector and listed argument values.

V-dbgtraceR] [I]flagsR]]

Prints information for debugging the V]jdbR] command.

V-tclientR]

Runs the application in the Java HotSpot VM client.

V-trackallthreadsR]

Track all threads as they are created, including virtual threads. See B]Working With Virtual ThreadsR] below.

V-tserverR]

Runs the application in the Java HotSpot VM server.

V-JR]I]optionR]

Passes I]optionR] to the JDB JVM, where option is one of the options described on the reference page for the Java application launcher. For example, V--Xms48mR] sets the startup memory to 48 MB. See I]Overview of Java OptionsR] in B]javaR].

The following options are forwarded to the debuggee process:

V-RR]I]optionR]

Passes I]optionR] to the debuggee JVM, where option is one of the options described on the reference page for the Java application launcher. For example, V--Xms48mR] sets the startup memory to 48 MB. See I]Overview of Java OptionsR] in B]javaR].

V-vR] or V-verboseR][V]:R]I]classR]|V]gcR]|V]jniR]]

Turns on the verbose mode.

V-DR]I]nameR]V]=R]I]valueR]

Sets a system property.

V-classpathR] I]dirR]

Lists directories separated by colons in which to look for classes.

V-XR] I]optionR]

A nonstandard target JVM option.

Other options are supported to provide alternate mechanisms for connecting the debugger to the JVM that it[aq]s to debug.  

WORKING WITH VIRTUAL THREADS

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 V-trackallthreadsR] 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 V]includevirtualthreadsR] option that can be enabled to change this behavior so all known virtual threads will be included in the list. The JDB V-trackallthreadsR] option will cause JDB to automatically enable the Debug Agent[aq]s V]includevirtualthreadsR] 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.

Index

NAME

SYNOPSIS

DESCRIPTION

START A JDB SESSION

BREAKPOINTS

STEPPING

EXCEPTIONS

OPTIONS FOR THE JDB COMMAND

WORKING WITH VIRTUAL THREADS