Developing Java Applications: A Tutorial | Debugging Java Applications

Java Debugger Command Reference

This section describes the complete set of Java Debugger commands. The Java Debugger recognizes command truncations as long as they are unique. For example, it recognizes du as dump but it cannot interpret "d". If a truncation is not unique, the debugger informs you. Several commands have shortened aliases (for example, si is equivalent to stepi and bt is equivalent to backtrace). The case of a command does not matter; Break is the same break which is the same as BrEaK . However, the case of arguments often does matter; for example, class and file names must match case ("Exception" is not the same as "exception").

Getting Help

JavaDebug>> non-command
To get a list of Java Debugger commands, enter any string that is not a command after the prompt.

Thread Commands

The Java Debugger recognizes a current thread group and a current thread. When an exception occurs, the current thread is reset. The current thread group is always the thread group containing the current thread.

Group [ groupName ]
Lists thread groups and threads if used by itself. If groupName is given, the current thread group is set to the group identified by that name. To avoid confusion, thread groups are referred to by name, while threads within a group are referred to by number.
Thread threadNum
Sets the thread within the current thread group to threadNum . To find out what the current group and thread are, enter the group command.

Example:

JavaDebug>> group

Group: system
1 Finalizer thread cond. waiting
2 JavaDebug cond. waiting
3 Debugger agent running
4 Breakpoint handler cond. waiting
5 Step handler cond. waiting
6 Agent input cond. waiting
7 main suspended

Group: main
1 main suspended

CURRENT GROUP is "system"
CURRENT THREAD within the group is "main"

JavaDebug>> thread 6

Current thread now Agent input, state=cond. waiting

Stack and Data Inspection

The stack and data inspection commands frame , up , down , print , and dump require that the thread being inspected be suspended. Threads are suspended by program execution hitting a breakpoint or by users giving the suspend command.

Backtrace | bt
Displays the contents of the current thread's Java stack. Currently, only Java stack frames are displayed. No "native" (non-Java) frames appear.

Example:

JavaDebug>> bt
[0] java.io.PipedInputStream.read (PipedInputStream:201) pc = 80
[1] java.io.PipedInputStream.read (PipedInputStream:242) pc = 43
[2] java.io.BufferedInputStream.fill (BufferedInputStream:135) pc = 164
[3] java.io.BufferedInputStream.read (BufferedInputStream:162) pc = 12
[4] java.io.FilterInputStream.read (FilterInputStream:81) pc = 4
[5] sun.tools.debug.AgentIn.run (AgentIn:46) pc = 20
[6] java.lang.Thread.run (Thread:474) pc = 11
Frame [ frameNum ]
Displays the arguments and local variables for the current frame or the frame number frameNum . Frame numbers, which are the numbers displayed in the backtrace, are absolute. If you do not compile Java code with javac 's -g flag, local and argument information is not available to the debugger. The frame command resets the current frame.

Example:

JavaDebug>> backtrace

[0] com.apple.alpha.core.MutableDictionary.<init> (MutableDictionary:213) pc = 0
[1] Document.setRichText (Document:534) pc = 10<
[2] Document.toggleRich (Document:596) pc = 69

JavaDebug>> frame 1

[1] setRichText(flag=true)
<local> view = <NSTextView: 0x194b8c0>
Frame = {{0.00, 0.00}, {490.00, 420.00}}, Bounds = {{0.00, 0.00}, {490.00, 420.00}}
Horizontally resizable: NO, Vertically resizable: YES
MinSize = {490.00, 420.00}, MaxSize = {340282346638528859811704183484516925440.00, 
340282346638528859811704183484516925440.00}
Up [numFrames]
Resets the current frame upwards toward older frames (that is, frames with higher numbers) relative to the current frame. If numFrames is not given, 1 is assumed.
Down [numFrames]
Resets the current frame downwards toward newer frames (that is, frames with lower numbers) relative to the current frame. If numFrames is not given, 1 is assumed.
Print | po anObject
Prints the object anObject by calling its toString() method.

Example:

JavaDebug>> po view

view = <NSTextView: 0x194b8c0>
Frame = {{0.00, 0.00}, {490.00, 420.00}}, Bounds = {{0.00, 0.00}, {490.00, 420.00}}
Horizontally resizable: NO, Vertically resizable: YES
MinSize = {490.00, 420.00}, MaxSize = {340282346638528859811704183484516925440.00, 
340282346638528859811704183484516925440.00}
Dump anObject
Prints the object anObject structurally. An alias for dump is p* (from gdb usage for Print *=reference)

Example:

JavaDebug>> p* view

view = (com.apple.alpha.app.TextView)0x3bc0c0 {
private int instance = 26523840
}

JavaDebug>> p* 0x3bc0c0

0x3bc0c0 = (com.apple.alpha.app.TextView)0x3bc0c0 {
private int instance = 26523840
}

In the above case, the object is obviously a native object with a peer class.

List
Displays source text for the current frame--when it can find it. (See the dir command in Convenience Functions , below).
JavaDebug>> break Document:setRichText

Set breakpoint 2000 in method: setRichText at line 533 in file "Document.java"

JavaDebug>> cont

JavaDebug>> // breakpoint hit because of user action
Broken at 533 in "Document.java"

JavaDebug>> list

File: "Document.java"
529 return layoutManager().hyphenationFactor();
530 }
531
532 public void setRichText(boolean flag) {
533 => TextView view = firstTextView();
534 MutableDictionary textAttributes = new MutableDictionary(2);
535
536 isRichText = flag;
537

Control Functions

Suspend
Suspends all Java threads that are not involved in debugging.
Resume
Resumes all Java threads that are not involved in debugging.
Break [fileName:lineNumber]
Sets a breakpoint in file fileName at line lineNumber . An alias for break is b . With no arguments, it prints the current breakpoints.
Break [className:methodName]
Sets a breakpoint at the start of method methodName in class className . An alias for break is b . With no arguments, it prints the current breakpoints.

Example:

JavaDebug>> break Document:setRichText

Set breakpoint 2000 in method: setRichText at line 533 in file "Document.java"

JavaDebug>> break

break <fileName>:<lineNum> | <class>:<method> -- set a breakpoint
2000 Document.java:533

JavaDebug>> disable 2000

JavaDebug>> break
break <fileName>:<lineNum> | <class>:<method> -- set a breakpoint

2000 Document.java:533 [disabled]
Clear [breakNum]
Clears (forgets) the breakpoint numbered breakNum . With no argument, it prints the current breakpoints.
Disable [breakNum]
Disables, but does not clear, the breakpoint numbered breakNum . If no argument is given, prints the current breakpoints.
Enable [breakNum]
Re-enables the disabled breakpoint numbered breakNum . If no argument is given, prints the current breakpoints.
Continue
Continues (resumes) execution of a suspended thread (must be the current thread).
Step
"Step Into." Steps forward a line of code. If the line is a statement that has a call to a Java method, it steps into the call. If the call is to "native" (non-Java) code, it steps over the code (that is, it acts like next ). If the step returns to native code, it acts like continue .
Stepi
Steps forward a single bytecode instruction. It otherwise acts like step . (Currently, there is no command to display the bytecodes. Use javap -c classFile to see the bytecodes).
Next
"Step Over." Steps forward a line of code. If the code is a method call, it steps over the call. If the step returns to native code, it acts like continue .
Finish
Steps to the end of the code in the current stack frame (also know as "step out").
Catch exceptionClass
Causes exceptions for class exceptionClass and all its subclasses to act like a breakpoint. At this time you cannot step through exception code; you can only inspect the stack and continue.
Drop exceptionClass
Reverses the effect of catch . The system no longer breaks when an exception of class exceptionClass is thrown.

Convenience Functions

Dir [newClassPath]
If newClassPath is given, sets the CLASSPATH environment variable used to search for debug and source information (for example, for the list and frame commands). If the command has no argument, it prints the CLASSPATH variable.
GetProp [propName]
Prints the value for the specified property propName or, if no property is specified, prints all properties of the Java VM. Java VM properties cannot be changed.
JavaDebug>> getprop user.home

/Local/Users/kend

JavaDebug>> getprop

Property Names:
user.language = "en"
java.home = "/System/Library/Frameworks/JavaVM.framework/Home"
file.encoding.pkg = "sun.io"
java.version = "internal_build:kend:03/05/98-09:08"
file.separator = "/"
line.separator = "

file.encoding = "MacRoman"
java.compiler = "jitc_ppc"
java.protocol.handler.pkgs = "com.apple.net.protocol"
java.vendor = "Apple Computer, Inc."
user.timezone = "PST"
user.name = "kend"
os.arch = "ppc"
os.name = "Mac OS X"
java.vendor.url = "http://www.apple.com/"
user.dir = "/Local/Users/kend/Projects/TextEdit"
java.class.path = "/Local/Users/kend/Projects/TextEdit/TextEdit.app/Resources/Java/.:.:/Local/Users/kend/
jdk20build/build/classes:/System/Library/Java:/System/Library/Frameworks/JavaVM.framework/Classes/
classes.jar:/System/Library/Frameworks/JavaVM.framework/Classes/awt.jar"
java.class.version = "45.3"
os.version = "Premier Release"
path.separator = ":"
user.home = "/Local/Users/kend"

Previous | Next
© 1998 Apple Computer, Inc.