9/28/2010

java -agentlib:jdwp for attaching debugger

In Java SE 5 or newer, one can use a new standard JVM option to attach a remote debugger. For example,

-agentlib:jdwp=transport=dt_socket,address=localhost:9009,server=y,suspend=y
In Sun JDK 1.4 or earlier, one still uses this old options:
-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=9009
An additional benefits of using the new -agentlib args is, it doesn't contain any whitespace, so you don't need to worry if you need to quote it or not. But if you do want to use the old flags, be careful about when to quote the value and when to not quote.

When using it directly in java command (Windows or Unix), do not quote it:

java -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=9009 test.Main
java "-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=9009" test.Main

When specifying it as an environment variable on Linux, or Unix, quote it:

export VMARGS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=9009"
export VMARGS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=9009

When specifying it as an environment variable on Windows, do not quote it:

set VMARGS=-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=9009
set VMARGS="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=9009"

The following is the usage from running this java command:
$ java -agentlib:jdwp=help

Java Debugger JDWP Agent Library
--------------------------------

(see http://java.sun.com/products/jpda for more information)

jdwp usage: java -agentlib:jdwp=[help]|[<option>=<value>, ...]

Option Name and Value Description Default
--------------------- ----------- -------
suspend=y|n wait on startup? y
transport=<name> transport spec none
address=<listen/attach address> transport spec ""
server=y|n listen for debugger? n
launch=<command line> run debugger on event none
onthrow=<exception name> debug on throw none
onuncaught=y|n debug on any uncaught? n
timeout=<timeout value> for listen/attach in milliseconds n
mutf8=y|n output modified utf-8 n
quiet=y|n control over terminal messages n

Obsolete Options
----------------
strict=y|n
stdalloc=y|n

Examples
--------
- Using sockets connect to a debugger at a specific address:
java -agentlib:jdwp=transport=dt_socket,address=localhost:8000 ...
- Using sockets listen for a debugger to attach:
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y ...

Notes
-----
- A timeout value of 0 (the default) is no timeout.

Warnings
--------
- The older -Xrunjdwp interface can still be used, but will be removed in
a future release, for example:
java -Xdebug -Xrunjdwp:[help]|[<option>=<value>, ...]

3 comments: