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
+ * platform equivalent of a dynamic library. If a native agent library
+ * called agent-lib-name is statically linked with the VM, then the
+ * Agent_OnAttach_agent-lib-name function exported by the agent
+ * is invoked.
+ *
+ * See the JVMTI Specification for more details.
+ *
+ * Otherwise, 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
+ * or, for statically linked agents, the Agent_OnAttach_agent-lib-name function
* as specified in the
* JVM Tools
- * Interface specification. Note that the Agent_OnAttach
+ * Interface specification. Note that the Agent_OnAttach[_agent-lib-name]
* function is invoked even if the agent library was loaded prior to invoking
* this method.
*
@@ -314,9 +322,9 @@
* libfoo.so, and located using the search path specified by the
* LD_LIBRARY_PATH environment variable.
If the Agent_OnAttach function in the agent library returns
+ *
If the Agent_OnAttach[_agent-lib-name] 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[_agent-lib-name] can then be
* obtained by invoking the {@link
* com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
* method on the exception.
Agent_OnAttach
+ * The options to provide to the Agent_OnAttach[_agent-lib-name]
* 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
+ * or, for statically linked agents, if the
+ * Agent_OnAttach_agent-lib-name function returns
+ * an error.
*
* @throws IOException
* If an I/O error occurs
@@ -359,11 +371,15 @@
* 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
+ * or, for statically linked agents, if the
+ * Agent_OnAttach_agent-lib-name function returns
+ * an error.
*
* @throws IOException
* If an I/O error occurs
@@ -383,12 +399,19 @@
* 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
+ * platform equivalent of a dynamic library. If a native agent library
+ * called agent-lib-name is statically linked with the VM, then the
+ * Agent_OnAttach_agent-lib-name function exported by the agent
+ * is invoked.
+ *
+ * See the JVMTI Specification for more details.
+ *
+ * Otherwise, 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
+ * It then causes the target VM to invoke the Agent_OnAttach[_agent-lib-name] function
* as specified in the
* JVM Tools
- * Interface specification. Note that the Agent_OnAttach
+ * Interface specification. Note that the Agent_OnAttach[_agent-lib-name]
* function is invoked even if the agent library was loaded prior to invoking
* this method.
*
@@ -396,9 +419,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[_agent-lib-name] 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[_agent-lib-name] can then be
* obtained by invoking the {@link
* com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
* method on the exception.
Agent_OnAttach
+ * The options to provide to the Agent_OnAttach[_agent-lib-name]
* 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
+ * or, for statically linked agents, if the
+ * Agent_OnAttach_agent-lib-name function returns an error
*
* @throws IOException
* If an I/O error occurs
@@ -441,11 +467,15 @@
* 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
+ * or, for statically linked agents, if the
+ * Agent_OnAttach_agent-lib-name function returns
+ * an error.
*
* @throws IOException
* If an I/O error occurs