src/share/classes/com/sun/tools/attach/VirtualMachine.java
Print this page
*** 296,341 ****
* Loads an agent library.
*
* <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
* TI</a> client is called an <i>agent</i>. 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 <code>Agent_OnAttach</code> function
* as specified in the
* <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
! * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
* function is invoked even if the agent library was loaded prior to invoking
* this method.
*
* <p> 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 <tt>foo</tt> might be expanded to
* <tt>libfoo.so</tt>, and located using the search path specified by the
* <tt>LD_LIBRARY_PATH</tt> environment variable.</p>
*
! * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
* an error then an {@link com.sun.tools.attach.AgentInitializationException} is
! * thrown. The return value from the <code>Agent_OnAttach</code> can then be
* obtained by invoking the {@link
* com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
* method on the exception. </p>
*
* @param agentLibrary
* The name of the agent library.
*
* @param options
! * The options to provide to the <code>Agent_OnAttach</code>
* function (can be <code>null</code>).
*
* @throws AgentLoadException
! * If the agent library does not exist, or cannot be loaded for
! * another reason.
*
* @throws AgentInitializationException
* If the <code>Agent_OnAttach</code> function returns an error
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
--- 296,353 ----
* Loads an agent library.
*
* <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
* TI</a> client is called an <i>agent</i>. 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. If a native agent library
! * called <code>agent-lib-name</code> is statically linked with the VM, then the
! * <code>Agent_OnAttach_agent-lib-name</code> 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 <code>Agent_OnAttach</code> function
+ * or, for statically linked agents, the <code>Agent_OnAttach_agent-lib-name</code> function
* as specified in the
* <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
! * Interface</a> specification. Note that the <code>Agent_OnAttach[_agent-lib-name]</code>
* function is invoked even if the agent library was loaded prior to invoking
* this method.
*
* <p> 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 <tt>foo</tt> might be expanded to
* <tt>libfoo.so</tt>, and located using the search path specified by the
* <tt>LD_LIBRARY_PATH</tt> environment variable.</p>
*
! * <p> If the <code>Agent_OnAttach[_agent-lib-name]</code> function in the agent library returns
* an error then an {@link com.sun.tools.attach.AgentInitializationException} is
! * thrown. The return value from the <code>Agent_OnAttach[_agent-lib-name]</code> can then be
* obtained by invoking the {@link
* com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
* method on the exception. </p>
*
* @param agentLibrary
* The name of the agent library.
*
* @param options
! * The options to provide to the <code>Agent_OnAttach[_agent-lib-name]</code>
* function (can be <code>null</code>).
*
* @throws AgentLoadException
! * 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 <code>Agent_OnAttach</code> function returns an error
+ * or, for statically linked agents, if the
+ * <code>Agent_OnAttach_agent-lib-name</code> function returns
+ * an error.
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
*** 357,371 ****
*
* @param agentLibrary
* The name of the agent library.
*
* @throws AgentLoadException
! * If the agent library does not exist, or cannot be loaded for
! * another reason.
*
* @throws AgentInitializationException
* If the <code>Agent_OnAttach</code> function returns an error
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
--- 369,387 ----
*
* @param agentLibrary
* The name of the agent library.
*
* @throws AgentLoadException
! * 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 <code>Agent_OnAttach</code> function returns an error
+ * or, for statically linked agents, if the
+ * <code>Agent_OnAttach_agent-lib-name</code> function returns
+ * an error.
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
*** 381,423 ****
* Load a native agent library by full pathname.
*
* <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
* TI</a> client is called an <i>agent</i>. 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 <code>Agent_OnAttach</code> function
* as specified in the
* <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
! * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
* function is invoked even if the agent library was loaded prior to invoking
* this method.
*
* <p> The agent library provided is the absolute path from which to load the
* agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
* is not expanded in the target virtual machine. </p>
*
! * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
* an error then an {@link com.sun.tools.attach.AgentInitializationException} is
! * thrown. The return value from the <code>Agent_OnAttach</code> can then be
* obtained by invoking the {@link
* com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
* method on the exception. </p>
*
* @param agentPath
* The full path of the agent library.
*
* @param options
! * The options to provide to the <code>Agent_OnAttach</code>
* function (can be <code>null</code>).
*
* @throws AgentLoadException
! * If the agent library does not exist, or cannot be loaded for
! * another reason.
*
* @throws AgentInitializationException
* If the <code>Agent_OnAttach</code> function returns an error
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
--- 397,449 ----
* Load a native agent library by full pathname.
*
* <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
* TI</a> client is called an <i>agent</i>. 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. If a native agent library
! * called <code>agent-lib-name</code> is statically linked with the VM, then the
! * <code>Agent_OnAttach_agent-lib-name</code> 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 <code>Agent_OnAttach[_agent-lib-name]</code> function
* as specified in the
* <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
! * Interface</a> specification. Note that the <code>Agent_OnAttach[_agent-lib-name]</code>
* function is invoked even if the agent library was loaded prior to invoking
* this method.
*
* <p> The agent library provided is the absolute path from which to load the
* agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
* is not expanded in the target virtual machine. </p>
*
! * <p> If the <code>Agent_OnAttach[_agent-lib-name]</code> function in the agent library returns
* an error then an {@link com.sun.tools.attach.AgentInitializationException} is
! * thrown. The return value from the <code>Agent_OnAttach[_agent-lib-name]</code> can then be
* obtained by invoking the {@link
* com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
* method on the exception. </p>
*
* @param agentPath
* The full path of the agent library.
*
* @param options
! * The options to provide to the <code>Agent_OnAttach[_agent-lib-name]</code>
* function (can be <code>null</code>).
*
* @throws AgentLoadException
! * 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 <code>Agent_OnAttach</code> function returns an error
+ * or, for statically linked agents, if the
+ * <code>Agent_OnAttach_agent-lib-name</code> function returns an error
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
*** 439,453 ****
*
* @param agentPath
* The full path to the agent library.
*
* @throws AgentLoadException
! * If the agent library does not exist, or cannot be loaded for
! * another reason.
*
* @throws AgentInitializationException
* If the <code>Agent_OnAttach</code> function returns an error
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException
--- 465,483 ----
*
* @param agentPath
* The full path to the agent library.
*
* @throws AgentLoadException
! * 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 <code>Agent_OnAttach</code> function returns an error
+ * or, for statically linked agents, if the
+ * <code>Agent_OnAttach_agent-lib-name</code> function returns
+ * an error.
*
* @throws IOException
* If an I/O error occurs
*
* @throws NullPointerException