Troubleshooting Guide for Java SE 6 with HotSpot VM

• Document Information
• Preface

• 1. Diagnostic Tools and Options
• 2. Detailed Tool Descriptions
• 3. Troubleshooting Memory Leaks
• 4. Troubleshooting System Crashes
• 5. Troubleshooting Hanging or Looping Processes
• 6. Integrating Signal and Exception Handling
• 7. Submitting Bug Reports
• A.  Environment Variables and System Properties
• B.  Command-Line Options
• C.  Fatal Error Log
• D.  Summary of Tools in This Release

Appendix A

Environment Variables and System Properties

This section describes environment variables and system properties that can be useful in troubleshooting situations.

• A.1 JAVA_HOME Environment Variable
• A.2 JAVA_TOOL_OPTIONS Environment Variable
• A.3 java.security.debug System Property

See also 7.3.5 Environment Variables in 7.3 Collecting Data for a Bug Report.

A.1 JAVA_HOME Environment Variable

The JAVA_HOME environment variable indicates the directory where the JDK software is installed.

A.2 JAVA_TOOL_OPTIONS Environment Variable

In many environments the command line to start the application is not readily accessible. This often arises with applications that use embedded VMs (meaning they use the JNI Invocation API to start the VM), or where the startup is deeply nested in scripts. In these environments the JAVA_TOOL_OPTIONS environment variable can be useful to augment a command line.

When this environment variable is set, the JNI_CreateJavaVM function (in the JNI Invocation API) prepends the value of the environment variable to the options supplied in its JavaVMInitArgs argument. In some cases this option is disabled for security reasons, for example, on Solaris OS the option is disabled when the effective user or group ID differs from the real ID.

This environment variable allows you to specify the initialization of tools, specifically the launching of native or Java programming language agents using the -agentlib or -javaagent options. In the following example the environment variable is set so that the HPROF profiler is launched when the application is started.

$  
        export JAVA_TOOL_OPTIONS="-agentlib:hprof"

This variable can also be used to augment the command line with other options for diagnostic purposes. For example, you can supply the -XX:OnError option to specify a script or command to be executed when a fatal error occurs.

Since this environment variable is examined at the time that JNI_CreateJavaVM is called, it cannot be used to augment the command line with options that would normally be handled by the launcher, for example, VM selection using the -client or the -server option.

The JAVA_TOOL_OPTIONS environment variable is fully described in the JAVA_TOOL_OPTIONS section of the JVM Tool Interface documentation.

A.3 java.security.debug System Property

The java.security.debug system property controls whether the security system of the JRE prints trace messages during execution. This option can be useful when diagnosing an issue involving a security manager when a SecurityException is thrown.

The property can have the following values:

• access - print all checkPermission results

• jar - print jar verification information

• policy - print policy information

• scl - print permissions that SecureClassLoader assigns

The following sub-options can be used with the access option:

• stack - include stack trace

• domain - dump all domains in context

• failure - before throwing exception, dump the stack and domain that did not have permission

For example, to print all checkPermission results and trace all domains in context, set the java.security.debug property to access,stack. To trace access failures, set the property to access,failure.

The following example shows the output of a checkPermission failure.

$ java -Djava.security.debug="access,failure" Application
access denied (java.net.SocketPermission server.foobar.com resolve
)
java.lang.Exception: Stack trace
    at java.lang.Thread.dumpStack(Thread.java:1158)
    at java.security.AccessControlContext.checkPermission
                          (AccessControlContext.java:253)
    at java.security.AccessController.checkPermission(AccessController.java:427)
    at java.lang.SecurityManager.checkPermission(SecurityManager.java:532)
    at java.lang.SecurityManager.checkConnect(SecurityManager.java:1031)
    at java.net.InetAddress.getAllByName0(InetAddress.java:1117)
    at java.net.InetAddress.getAllByName0(InetAddress.java:1098)
    at java.net.InetAddress.getAllByName(InetAddress.java:1061)
    at java.net.InetAddress.getByName(InetAddress.java:958)
    at java.net.InetSocketAddress.<init>(InetSocketAddress.java:124)
    at java.net.Socket.<init>(Socket.java:178)
    at Test.main(Test.java:7)