src/share/classes/com/sun/tools/attach/VirtualMachine.java

Print this page

        

*** 57,67 **** * #loadAgent loadAgent} method is used to load agents that are written in the Java * Language and deployed in a {@link java.util.jar.JarFile JAR file}. (See * {@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 <a * href="../../../../../../../../technotes/guides/jvmti/index.html">JVM Tools * Interface</a>. </p> * * <p> In addition to loading agents a VirtualMachine provides read access to the * {@link java.lang.System#getProperties() system properties} in the target VM. --- 57,67 ---- * #loadAgent loadAgent} method is used to load agents that are written in the Java * Language and deployed in a {@link java.util.jar.JarFile JAR file}. (See * {@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 either in a dynamic library or statically linked into the VM and make use of the <a * href="../../../../../../../../technotes/guides/jvmti/index.html">JVM Tools * Interface</a>. </p> * * <p> In addition to loading agents a VirtualMachine provides read access to the * {@link java.lang.System#getProperties() system properties} in the target VM.
*** 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,349 ---- * 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. 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 <code>Agent_OnAttach</code> function + * or, for a statically linked agent named 'L', the <code>Agent_OnAttach_L</code> function * as specified in the * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools ! * Interface</a> specification. Note that the <code>Agent_OnAttach[_L]</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>L</tt> might be expanded to ! * <tt>libL.so</tt>, and located using the search path specified by the ! * <tt>LD_LIBRARY_PATH</tt> environment variable. If the agent named 'L' is ! * statically linked into the VM then the VM must export a function named ! * <code>Agent_OnAttach_L</code>.</p> * ! * <p> If the <code>Agent_OnAttach[_L]</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[_L]</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[_L]</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 a statically linked agent named 'L', if the + * <code>Agent_OnAttach_L</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 --- 365,383 ---- * * @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 a statically linked agent named 'L', if the + * <code>Agent_OnAttach_L</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 --- 393,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. Alternatively, the native ! * library specified by the agentPath parameter may be statically ! * linked with the VM. The parsing of the agentPath paramter into ! * a statically linked library name is done in a platform ! * specific manner in the VM. For example, in UNIX, an agentPath paramter ! * of <code>/a/b/libL.so</code> 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 <code>Agent_OnAttach</code> ! * function or, for a statically linked agent named 'L', the ! * <code>Agent_OnAttach_L</code> function as specified in the * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools ! * Interface</a> specification. ! * Note that the <code>Agent_OnAttach[_L]</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[_L]</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[_L]</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[_L]</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 a statically linked agent named 'L', if the + * <code>Agent_OnAttach_L</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 a statically linked agent named 'L', if the + * <code>Agent_OnAttach_L</code> function returns + * an error. * * @throws IOException * If an I/O error occurs * * @throws NullPointerException