--- old/src/share/classes/com/sun/tools/attach/VirtualMachine.java 2013-08-20 12:50:59.673752440 -0400 +++ new/src/share/classes/com/sun/tools/attach/VirtualMachine.java 2013-08-20 12:50:58.581691075 -0400 @@ -59,7 +59,7 @@ * {@link java.lang.instrument} for a detailed description on how these agents * are loaded and started). The {@link #loadAgentLibrary loadAgentLibrary} and * {@link #loadAgentPath loadAgentPath} methods are used to load agents that - * are deployed in a dynamic library and make use of the JVM Tools * Interface.

* @@ -298,25 +298,29 @@ *

A JVM * TI client is called an agent. It is developed in a native language. * A JVM TI agent is deployed in a platform specific manner but it is typically the - * platform equivalent of a dynamic library. This method causes the given agent - * library to be loaded into the target VM (if not already loaded). + * platform equivalent of a dynamic library. Alternatively, it may be statically linked into the VM. + * This method causes the given agent library to be loaded into the target + * VM (if not already loaded or if not statically linked into the VM). * It then causes the target VM to invoke the Agent_OnAttach function + * or, for a statically linked agent named 'L', the Agent_OnAttach_L function * as specified in the * JVM Tools - * Interface specification. Note that the Agent_OnAttach + * Interface specification. Note that the Agent_OnAttach[_L] * function is invoked even if the agent library was loaded prior to invoking * this method. * *

The agent library provided is the name of the agent library. It is interpreted * in the target virtual machine in an implementation-dependent manner. Typically an * implementation will expand the library name into an operating system specific file - * name. For example, on UNIX systems, the name foo might be expanded to - * libfoo.so, and located using the search path specified by the - * LD_LIBRARY_PATH environment variable.

+ * name. For example, on UNIX systems, the name L might be expanded to + * libL.so, and located using the search path specified by the + * LD_LIBRARY_PATH environment variable. If the agent named 'L' is + * statically linked into the VM then the VM must export a function named + * Agent_OnAttach_L.

* - *

If the Agent_OnAttach function in the agent library returns + *

If the Agent_OnAttach[_L] function in the agent library returns * an error then an {@link com.sun.tools.attach.AgentInitializationException} is - * thrown. The return value from the Agent_OnAttach can then be + * thrown. The return value from the Agent_OnAttach[_L] can then be * obtained by invoking the {@link * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue} * method on the exception.

@@ -325,15 +329,16 @@ * The name of the agent library. * * @param options - * The options to provide to the Agent_OnAttach + * The options to provide to the Agent_OnAttach[_L] * function (can be null). * * @throws AgentLoadException - * If the agent library does not exist, or cannot be loaded for - * another reason. + * If the agent library does not exist, the agent library is not + * statically linked with the VM, or the agent library cannot be + * loaded for another reason. * * @throws AgentInitializationException - * If the Agent_OnAttach function returns an error + * If the Agent_OnAttach[_L] function returns an error. * * @throws IOException * If an I/O error occurs @@ -359,11 +364,12 @@ * The name of the agent library. * * @throws AgentLoadException - * If the agent library does not exist, or cannot be loaded for - * another reason. + * If the agent library does not exist, the agent library is not + * statically linked with the VM, or the agent library cannot be + * loaded for another reason. * * @throws AgentInitializationException - * If the Agent_OnAttach function returns an error + * If the Agent_OnAttach[_L] function returns an error. * * @throws IOException * If an I/O error occurs @@ -383,12 +389,23 @@ *

A JVM * TI client is called an agent. It is developed in a native language. * A JVM TI agent is deployed in a platform specific manner but it is typically the - * platform equivalent of a dynamic library. This method causes the given agent - * library to be loaded into the target VM (if not already loaded). - * It then causes the target VM to invoke the Agent_OnAttach function - * as specified in the + * platform equivalent of a dynamic library. Alternatively, the native + * library specified by the agentPath parameter may be statically + * linked with the VM. The parsing of the agentPath parameter into + * a statically linked library name is done in a platform + * specific manner in the VM. For example, in UNIX, an agentPath parameter + * of /a/b/libL.so would name a library 'L'. + * + * See the JVM TI Specification for more details. + * + * This method causes the given agent library to be loaded into the target + * VM (if not already loaded or if not statically linked into the VM). + * It then causes the target VM to invoke the Agent_OnAttach + * function or, for a statically linked agent named 'L', the + * Agent_OnAttach_L function as specified in the * JVM Tools - * Interface specification. Note that the Agent_OnAttach + * Interface specification. + * Note that the Agent_OnAttach[_L] * function is invoked even if the agent library was loaded prior to invoking * this method. * @@ -396,9 +413,9 @@ * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name * is not expanded in the target virtual machine.

* - *

If the Agent_OnAttach function in the agent library returns + *

If the Agent_OnAttach[_L] function in the agent library returns * an error then an {@link com.sun.tools.attach.AgentInitializationException} is - * thrown. The return value from the Agent_OnAttach can then be + * thrown. The return value from the Agent_OnAttach[_L] can then be * obtained by invoking the {@link * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue} * method on the exception.

@@ -407,15 +424,16 @@ * The full path of the agent library. * * @param options - * The options to provide to the Agent_OnAttach + * The options to provide to the Agent_OnAttach[_L] * function (can be null). * * @throws AgentLoadException - * If the agent library does not exist, or cannot be loaded for - * another reason. + * If the agent library does not exist, the agent library is not + * statically linked with the VM, or the agent library cannot be + * loaded for another reason. * * @throws AgentInitializationException - * If the Agent_OnAttach function returns an error + * If the Agent_OnAttach[_L] function returns an error. * * @throws IOException * If an I/O error occurs @@ -441,11 +459,12 @@ * The full path to the agent library. * * @throws AgentLoadException - * If the agent library does not exist, or cannot be loaded for - * another reason. + * If the agent library does not exist, the agent library is not + * statically linked with the VM, or the agent library cannot be + * loaded for another reason. * * @throws AgentInitializationException - * If the Agent_OnAttach function returns an error + * If the Agent_OnAttach[_L] function returns an error. * * @throws IOException * If an I/O error occurs