src/share/vm/prims/jvmti.xml

Print this page




 387     independent of them.
 388     <p/>
 389     Agents run in the same process with and communicate directly with 
 390     the virtual machine executing
 391     the application being examined.  This communication is
 392     through a native interface (<jvmti/>). The native in-process interface allows
 393     maximal control with minimal intrusion on the part of a tool. 
 394     Typically, agents are relatively compact. They can be controlled
 395     by a separate process which implements the bulk of a tool's
 396     function without interfering with the target application's normal execution.
 397   </intro>
 398 
 399   <intro id="architecture" label="Architecture">
 400     Tools can be written directly to <jvmti/> or indirectly
 401     through higher level interfaces.
 402     The Java Platform Debugger Architecture includes <jvmti/>, but also
 403     contains higher-level, out-of-process debugger interfaces. The higher-level 
 404     interfaces are more appropriate than <jvmti/> for many tools. 
 405     For more information on the Java Platform Debugger Architecture, 
 406     see the 
 407     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">Java 
 408       Platform Debugger Architecture website</externallink>. 
 409   </intro>
 410 
 411   <intro id="writingAgents" label="Writing Agents">
 412     Agents can be written in any native language that supports C
 413     language calling conventions and C or C++
 414     definitions.
 415     <p/>
 416     The function, event, data type, and constant definitions needed for
 417     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 418     To use these definitions add the <tm>J2SE</tm> include directory
 419     to your include path and add
 420     <example>
 421 #include &lt;jvmti.h&gt;
 422     </example>
 423     to your source code.
 424   </intro>
 425 
 426   <intro id="deployingAgents" label="Deploying Agents">
 427     An agent is deployed in a platform specific manner but is typically the 


 747     others.  The state of a <jvmti/> 
 748     environment includes:
 749     <ul>
 750       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
 751       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
 752       <li><internallink id="capability">the capabilities</internallink></li>
 753       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
 754     </ul>
 755     Although their <jvmti/> state 
 756     is separate, agents inspect and modify the shared state
 757     of the VM, they also share the native environment in which they execute.
 758     As such, an agent can perturb the results of other agents or cause them
 759     to fail.  It is the responsibility of the agent writer to specify the level
 760     of compatibility with other agents.  <jvmti/> implementations are not capable
 761     of preventing destructive interactions between agents. Techniques to reduce
 762     the likelihood of these occurrences are beyond the scope of this document.
 763     <p/>
 764     An agent creates a <jvmti/> environment 
 765     by passing a <jvmti/> version 
 766     as the interface ID to the JNI Invocation API function 
 767     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>.

 768     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
 769     for more details on the creation and use of 
 770     <jvmti/> environments.
 771     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from 
 772     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
 773   </intro>
 774 
 775   <intro id="bci" label="Bytecode Instrumentation">
 776     This interface does not include some events that one might expect in an interface with
 777     profiling support.  Some examples include object allocation events and full speed
 778     method enter and exit events.  The interface instead provides support for 
 779     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
 780     bytecode instructions which comprise the target program.  Typically, these alterations
 781     are to add "events" to the code of a method - for example, to add, at the beginning of a method,
 782     a call to <code>MyProfiler.methodEntered()</code>.  
 783     Since the changes are purely additive, they do not modify application
 784     state or behavior.
 785     Because the inserted agent code is standard bytecodes, the VM can run at full speed,
 786     optimizing not only the target program but also the instrumentation.  If the 
 787     instrumentation does not involve switching from bytecode execution, no expensive


 868   in a support class in another module, then the module of the instrumented
 869   code should read the module of the supporting class. Furthermore, the
 870   supporting class will only be accessible to the instrumented code if
 871   it is <code>public</code> and in a package that is exported by its module.
 872   Agents can use the JNI functions <code>CanReadModule</code> and
 873   <code>AddModuleReads</code> to test and update a module to read another.
 874   <p/>
 875   As an aid to agents that deploy supporting classes on the search path of
 876   the bootstrap class loader, or the search path of the class loader that
 877   loads the main class, the Java virtual machine arranges for the module
 878   of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
 879   read the unnamed module of both class loaders.
 880 </intro>
 881 
 882   <intro id="mUTF" label="Modified UTF-8 String Encoding">
 883     <jvmti/> uses modified UTF-8 to encode character strings.
 884     This is the same encoding used by JNI.
 885     Modified UTF-8 differs 
 886     from standard UTF-8 in the representation of supplementary characters 
 887     and of the null character. See the
 888     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542">
 889       Modified UTF-8 Strings</externallink>
 890     section of the JNI specification for details.
 891   </intro>
 892 
 893   <intro id="context" label="Specification Context">
 894     Since this interface provides access to the state of applications running in the
 895     Java virtual machine; 
 896     terminology refers to the Java platform and not the native
 897     platform (unless stated otherwise).  For example:
 898     <ul>
 899       <li>"thread" means Java programming language thread.</li>
 900       <li>"stack frame" means Java virtual machine stack frame.</li>
 901       <li>"class" means Java programming language class.</li>
 902       <li>"heap" means Java virtual machine heap.</li>
 903       <li>"monitor" means Java programming language object monitor.</li>
 904     </ul>
 905     <p/>
 906     Sun, Sun Microsystems, the Sun logo, Java, and JVM
 907     are trademarks or registered trademarks of Oracle 
 908     and/or its affiliates, in the U.S. and other countries.
 909   </intro>
 910 
 911 
 912 <functionsection label="Functions">
 913   <intro id="jvmtiEnvAccess" label="Accessing Functions">
 914     Native code accesses <jvmti/> features 
 915     by calling <jvmti/> functions. 
 916     Access to <jvmti/> functions is by use of an interface pointer
 917     in the same manner as 
 918     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java 
 919       Native Interface (JNI) functions</externallink> are accessed.
 920     The <jvmti/> interface pointer is called the 
 921     <i>environment pointer</i>.
 922     <p/>
 923     An environment pointer is a pointer to an environment and has
 924     the type <code>jvmtiEnv*</code>.
 925     An environment has information about its <jvmti/> connection.
 926     The first value in the environment is a pointer to the function table.
 927     The function table is an array of pointers to <jvmti/> functions.
 928     Every function pointer is at a predefined offset inside the 
 929     array. 
 930     <p/>
 931     When used from the C language:
 932     double indirection is used to access the functions;
 933     the environment pointer provides context and is the first
 934     parameter of each function call; for example:
 935     <example>
 936 jvmtiEnv *jvmti;
 937 ...
 938 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);


 990     returned as <code>NULL</code>.
 991     <p/>
 992     In the event that the <jvmti/> function encounters
 993     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
 994     of memory referenced by argument pointers is undefined, but no memory
 995     will have been allocated and no global references will have been allocated.
 996     If the error occurs because of invalid input, no action will have occurred.
 997   </intro>
 998 
 999 <intro id="refs" label="Managing JNI Object References">
1000     <jvmti/> functions identify objects with JNI references 
1001     (<datalink id="jobject"/> and <datalink id="jclass"/>)
1002     and their derivatives
1003     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
1004     References passed to 
1005     <jvmti/> functions can be either global or local, but they must be 
1006     strong references. All references returned by <jvmti/> functions are 
1007     local references--these local references are created 
1008     during the <jvmti/> call.
1009     Local references are a resource that must be managed (see the 
1010     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>).  

1011     When threads return from native code all local references
1012     are freed.  Note that some threads, including typical
1013     agent threads, will never return from native code.
1014     A thread is ensured the ability to create sixteen local 
1015     references without the need for any explicit management.
1016     For threads executing a limited number of <jvmti/> calls before
1017     returning from native code
1018     (for example, threads processing events), 
1019     it may be determined that no explicit management
1020     is needed.
1021     However, long running agent threads will need explicit
1022     local reference management--usually with the JNI functions
1023     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
1024     Conversely, to preserve references beyond the
1025     return from native code, they must be converted to global references.
1026     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> 
1027     as they are not <datalink id="jobject"/>s.
1028 </intro>
1029 
1030     <intro id="prereqState" label="Prerequisite State for Calling Functions">
1031       Unless the function explicitly states that the agent must bring
1032       a thread or the VM to a particular state (for example, suspended),
1033       the <jvmti/> implementation is responsible for bringing the VM to a
1034       safe and consistent state for performing the function.
1035     </intro>
1036 
1037     <intro id="functionsExceptions" label="Exceptions and Functions">
1038       <jvmti/> functions never throw exceptions; error conditions are 
1039       communicated via the 
1040       <internallink id="functionReturn">function return value</internallink>.
1041       Any existing exception state is preserved across a call to a 
1042       <jvmti/> function.
1043       See the
1044       <externallink 
1045         id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770"
1046              >Java Exceptions</externallink>
1047       section of the JNI specification for information on handling exceptions.
1048     </intro>
1049 
1050   <category id="memory" label="Memory Management">
1051     <intro>
1052       These functions provide for the allocation and deallocation of 
1053       memory used by <jvmti/> functionality and can be used to provide
1054       working memory for agents.
1055       Memory managed by <jvmti/> is not compatible with other memory
1056       allocation libraries and mechanisms.
1057     </intro>
1058 
1059     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
1060       <synopsis>Allocate</synopsis>
1061       <description>
1062         Allocate an area of memory through the <jvmti/> allocator. 
1063         The allocated
1064         memory should be freed with <functionlink id="Deallocate"></functionlink>.
1065       </description>


2091         </constants>
2092         <p/>
2093         The new thread is started as a daemon thread with the specified
2094         <paramlink id="priority"></paramlink>.
2095         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2096         <p/>
2097         Since the thread has been started, the thread will be live when this function
2098         returns, unless the thread has died immediately.
2099         <p/>
2100         The thread group of the thread is ignored -- specifically, the thread is not
2101         added to the thread group and the thread is not seen on queries of the thread
2102         group at either the Java programming language or <jvmti/> levels.
2103         <p/>
2104         The thread is not visible to Java programming language queries but is 
2105         included in <jvmti/> queries (for example, 
2106         <functionlink id="GetAllThreads"/> and
2107         <functionlink id="GetAllStackTraces"/>).
2108         <p/>
2109         Upon execution of <code>proc</code>, the new thread will be attached to the
2110         VM--see the JNI documentation on 
2111         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060"
2112                       >Attaching to the VM</externallink>.
2113       </description>
2114       <origin>jvmdiClone</origin>
2115       <capabilities>
2116       </capabilities>
2117       <parameters>
2118         <param id="thread">
2119           <jthread impl="noconvert" started="no"/>
2120             <description>
2121               The thread to run.
2122             </description>
2123         </param>
2124         <param id="proc">
2125           <ptrtype>
2126             <struct>jvmtiStartFunction</struct>
2127           </ptrtype>
2128           <description>
2129             The start function.
2130           </description>
2131         </param>


6633           <description>
6634             On return, points to the number of classes.
6635           </description>
6636         </param>
6637         <param id="classes_ptr">
6638           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6639             <description>
6640               On return, points to an array of references, one
6641               for each class.
6642             </description>
6643         </param>
6644       </parameters>
6645       <errors>
6646       </errors>
6647     </function>
6648 
6649     <function id="GetClassSignature" phase="start" num="48">
6650       <synopsis>Get Class Signature</synopsis>
6651       <description>
6652         For the class indicated by <code>klass</code>, return the 
6653         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI 
6654             type signature</externallink> 
6655         and the generic signature of the class.
6656         For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
6657         and <code>int[]</code> is <code>"[I"</code>
6658         The returned name for primitive classes
6659         is the type signature character of the corresponding primitive type. 
6660         For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
6661       </description>
6662       <origin>jvmdiClone</origin>
6663       <capabilities>
6664       </capabilities>
6665       <parameters>
6666         <param id="klass">
6667           <jclass/>
6668             <description>
6669               The class to query.
6670             </description>
6671         </param>
6672         <param id="signature_ptr">
6673           <allocbuf>


8922         </param>
8923         <param id="monitors_ptr">
8924           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
8925           <description>
8926             On return, pointer to the monitor list.
8927           </description>
8928         </param>
8929       </parameters>
8930       <errors>
8931       </errors>
8932     </function>
8933     </elide>
8934   </category>
8935 
8936   <category id="jniIntercept" label="JNI Function Interception">
8937 
8938     <intro>
8939       Provides the ability to intercept and resend 
8940       Java Native Interface (JNI) function calls
8941       by manipulating the JNI function table.
8942       See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI
8943         Functions</externallink> in the <i>Java Native Interface Specification</i>.
8944       <p/>
8945       The following example illustrates intercepting the 
8946       <code>NewGlobalRef</code> JNI call in order to count reference
8947       creation.
8948       <example>
8949 JNIEnv original_jni_Functions;
8950 JNIEnv redirected_jni_Functions;
8951 int my_global_ref_count = 0;
8952 
8953 jobject
8954 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
8955    ++my_global_ref_count;
8956    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
8957 }
8958 
8959 void
8960 myInit() {
8961    jvmtiError err;
8962 


10623       These functions allow the agent to add to the locations that a class loader searches for a class.
10624       This is useful for installing instrumentation under the correct class loader.
10625     </intro>
10626 
10627     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
10628       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
10629       <description>
10630           This function can be used to cause instrumentation classes to be defined by the 
10631           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
10632           After the bootstrap
10633           class loader unsuccessfully searches for a class, the specified platform-dependent 
10634           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in 
10635           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, 
10636           the segments will be searched in the order that this function was called.
10637           <p/>
10638           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10639           search path segment to be searched after the bootstrap class loader unsuccessfully searches
10640           for a class. The segment is typically a directory or JAR file.
10641           <p/>      
10642           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
10643           path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">
10644           JAR file</externallink>. The agent should take care that the JAR file does not
10645           contain any classes or resources other than those to be defined by the bootstrap
10646           class loader for the purposes of instrumentation.
10647           <p/>
10648           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10649           reference that the Java virtual machine has previously unsuccessfully attempted
10650           to resolve always fails with the same error that was thrown as a result of the
10651           initial resolution attempt. Consequently, if the JAR file contains an entry
10652           that corresponds to a class for which the Java virtual machine has
10653           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10654           resolve that reference will fail with the same error as the initial attempt.
10655       </description>
10656       <origin>new</origin>
10657       <capabilities>
10658       </capabilities>
10659       <parameters>
10660         <param id="segment">
10661           <inbuf><char/></inbuf>
10662           <description>
10663             The platform-dependent search path segment, encoded as a


10670           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10671            existing JAR file is an invalid path.
10672         </error>
10673       </errors>
10674     </function>
10675 
10676     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
10677       <synopsis>Add To System Class Loader Search</synopsis>
10678       <description>
10679           This function can be used to cause instrumentation classes to be
10680           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
10681           After the class loader unsuccessfully searches for a class, the specified platform-dependent search 
10682           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the 
10683           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the 
10684           segments will be searched in the order that this function was called.
10685           <p/>
10686           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10687           search path segment to be searched after the system class loader unsuccessfully searches
10688           for a class. The segment is typically a directory or JAR file.
10689           <p/>      
10690           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink 
10691           id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be
10692           searched after the system class loader unsuccessfully searches for a class. The agent should
10693           take care that the JAR file does not contain any classes or resources other than those to be
10694           defined by the system class loader for the purposes of instrumentation.
10695           <p/>
10696           In the live phase the system class loader supports adding a JAR file to be searched if
10697           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> 
10698           which takes a single parameter of type <code>java.lang.String</code>. The method is not required 
10699           to have <code>public</code> access. 
10700           <p/>
10701           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10702           reference that the Java virtual machine has previously unsuccessfully attempted
10703           to resolve always fails with the same error that was thrown as a result of the
10704           initial resolution attempt. Consequently, if the JAR file contains an entry
10705           that corresponds to a class for which the Java virtual machine has
10706           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10707           resolve that reference will fail with the same error as the initial attempt.
10708       </description>
10709       <origin>new</origin>
10710       <capabilities>
10711       </capabilities>


13502 } jvmtiEventCallbacks;
13503 </example>
13504         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> 
13505         for the complete structure.
13506         <p/>
13507         Where, for example, the VM initialization callback is defined:
13508 <example>
13509 typedef void (JNICALL *jvmtiEventVMInit)
13510     (jvmtiEnv *jvmti_env, 
13511      JNIEnv* jni_env,
13512      jthread thread);
13513 </example>
13514         See the individual events for the callback function definition.
13515       </description>
13516     </basetype>
13517     <basetype id="jniNativeInterface">
13518       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
13519       <description>
13520         Typedef for the JNI function table <code>JNINativeInterface</code>
13521         defined in the 
13522         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>.

13523         The JNI reference implementation defines this with an underscore.
13524       </description>
13525     </basetype>
13526   </basetypes>
13527 
13528 </datasection>
13529 
13530 <issuessection label="Issues">
13531   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
13532     JVMDI requires that the agent suspend threads before calling
13533     certain sensitive functions.  JVMPI requires garbage collection to be 
13534     disabled before calling certain sensitive functions. 
13535     It was suggested that rather than have this requirement, that
13536     VM place itself in a suitable state before performing an
13537     operation.  This makes considerable sense since each VM
13538     knows its requirements and can most easily arrange a
13539     safe state.  
13540     <p/>
13541     The ability to externally suspend/resume threads will, of
13542     course, remain.  The ability to enable/disable garbage collection will not.




 387     independent of them.
 388     <p/>
 389     Agents run in the same process with and communicate directly with 
 390     the virtual machine executing
 391     the application being examined.  This communication is
 392     through a native interface (<jvmti/>). The native in-process interface allows
 393     maximal control with minimal intrusion on the part of a tool. 
 394     Typically, agents are relatively compact. They can be controlled
 395     by a separate process which implements the bulk of a tool's
 396     function without interfering with the target application's normal execution.
 397   </intro>
 398 
 399   <intro id="architecture" label="Architecture">
 400     Tools can be written directly to <jvmti/> or indirectly
 401     through higher level interfaces.
 402     The Java Platform Debugger Architecture includes <jvmti/>, but also
 403     contains higher-level, out-of-process debugger interfaces. The higher-level 
 404     interfaces are more appropriate than <jvmti/> for many tools. 
 405     For more information on the Java Platform Debugger Architecture, 
 406     see the 
 407     <externallink id="docs/technotes/guides/jpda/architecture.html">Java 
 408       Platform Debugger Architecture website</externallink>. 
 409   </intro>
 410 
 411   <intro id="writingAgents" label="Writing Agents">
 412     Agents can be written in any native language that supports C
 413     language calling conventions and C or C++
 414     definitions.
 415     <p/>
 416     The function, event, data type, and constant definitions needed for
 417     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 418     To use these definitions add the <tm>J2SE</tm> include directory
 419     to your include path and add
 420     <example>
 421 #include &lt;jvmti.h&gt;
 422     </example>
 423     to your source code.
 424   </intro>
 425 
 426   <intro id="deployingAgents" label="Deploying Agents">
 427     An agent is deployed in a platform specific manner but is typically the 


 747     others.  The state of a <jvmti/> 
 748     environment includes:
 749     <ul>
 750       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
 751       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
 752       <li><internallink id="capability">the capabilities</internallink></li>
 753       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
 754     </ul>
 755     Although their <jvmti/> state 
 756     is separate, agents inspect and modify the shared state
 757     of the VM, they also share the native environment in which they execute.
 758     As such, an agent can perturb the results of other agents or cause them
 759     to fail.  It is the responsibility of the agent writer to specify the level
 760     of compatibility with other agents.  <jvmti/> implementations are not capable
 761     of preventing destructive interactions between agents. Techniques to reduce
 762     the likelihood of these occurrences are beyond the scope of this document.
 763     <p/>
 764     An agent creates a <jvmti/> environment 
 765     by passing a <jvmti/> version 
 766     as the interface ID to the JNI Invocation API function 
 767     <externallink id="docs/technotes/guides/jni/spec/invocation.html#GetEnv">
 768       <code>GetEnv</code></externallink>.
 769     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
 770     for more details on the creation and use of 
 771     <jvmti/> environments.
 772     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from 
 773     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
 774   </intro>
 775 
 776   <intro id="bci" label="Bytecode Instrumentation">
 777     This interface does not include some events that one might expect in an interface with
 778     profiling support.  Some examples include object allocation events and full speed
 779     method enter and exit events.  The interface instead provides support for 
 780     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
 781     bytecode instructions which comprise the target program.  Typically, these alterations
 782     are to add "events" to the code of a method - for example, to add, at the beginning of a method,
 783     a call to <code>MyProfiler.methodEntered()</code>.  
 784     Since the changes are purely additive, they do not modify application
 785     state or behavior.
 786     Because the inserted agent code is standard bytecodes, the VM can run at full speed,
 787     optimizing not only the target program but also the instrumentation.  If the 
 788     instrumentation does not involve switching from bytecode execution, no expensive


 869   in a support class in another module, then the module of the instrumented
 870   code should read the module of the supporting class. Furthermore, the
 871   supporting class will only be accessible to the instrumented code if
 872   it is <code>public</code> and in a package that is exported by its module.
 873   Agents can use the JNI functions <code>CanReadModule</code> and
 874   <code>AddModuleReads</code> to test and update a module to read another.
 875   <p/>
 876   As an aid to agents that deploy supporting classes on the search path of
 877   the bootstrap class loader, or the search path of the class loader that
 878   loads the main class, the Java virtual machine arranges for the module
 879   of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
 880   read the unnamed module of both class loaders.
 881 </intro>
 882 
 883   <intro id="mUTF" label="Modified UTF-8 String Encoding">
 884     <jvmti/> uses modified UTF-8 to encode character strings.
 885     This is the same encoding used by JNI.
 886     Modified UTF-8 differs 
 887     from standard UTF-8 in the representation of supplementary characters 
 888     and of the null character. See the
 889     <externallink id="docs/technotes/guides/jni/spec/types.html#modified_utf_8_strings">
 890       Modified UTF-8 Strings</externallink>
 891     section of the JNI specification for details.
 892   </intro>
 893 
 894   <intro id="context" label="Specification Context">
 895     Since this interface provides access to the state of applications running in the
 896     Java virtual machine; 
 897     terminology refers to the Java platform and not the native
 898     platform (unless stated otherwise).  For example:
 899     <ul>
 900       <li>"thread" means Java programming language thread.</li>
 901       <li>"stack frame" means Java virtual machine stack frame.</li>
 902       <li>"class" means Java programming language class.</li>
 903       <li>"heap" means Java virtual machine heap.</li>
 904       <li>"monitor" means Java programming language object monitor.</li>
 905     </ul>
 906     <p/>
 907     Sun, Sun Microsystems, the Sun logo, Java, and JVM
 908     are trademarks or registered trademarks of Oracle 
 909     and/or its affiliates, in the U.S. and other countries.
 910   </intro>
 911 
 912 
 913 <functionsection label="Functions">
 914   <intro id="jvmtiEnvAccess" label="Accessing Functions">
 915     Native code accesses <jvmti/> features 
 916     by calling <jvmti/> functions. 
 917     Access to <jvmti/> functions is by use of an interface pointer
 918     in the same manner as 
 919     <externallink id="docs/technotes/guides/jni/spec/design.html">Java 
 920       Native Interface (JNI) functions</externallink> are accessed.
 921     The <jvmti/> interface pointer is called the 
 922     <i>environment pointer</i>.
 923     <p/>
 924     An environment pointer is a pointer to an environment and has
 925     the type <code>jvmtiEnv*</code>.
 926     An environment has information about its <jvmti/> connection.
 927     The first value in the environment is a pointer to the function table.
 928     The function table is an array of pointers to <jvmti/> functions.
 929     Every function pointer is at a predefined offset inside the 
 930     array. 
 931     <p/>
 932     When used from the C language:
 933     double indirection is used to access the functions;
 934     the environment pointer provides context and is the first
 935     parameter of each function call; for example:
 936     <example>
 937 jvmtiEnv *jvmti;
 938 ...
 939 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);


 991     returned as <code>NULL</code>.
 992     <p/>
 993     In the event that the <jvmti/> function encounters
 994     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
 995     of memory referenced by argument pointers is undefined, but no memory
 996     will have been allocated and no global references will have been allocated.
 997     If the error occurs because of invalid input, no action will have occurred.
 998   </intro>
 999 
1000 <intro id="refs" label="Managing JNI Object References">
1001     <jvmti/> functions identify objects with JNI references 
1002     (<datalink id="jobject"/> and <datalink id="jclass"/>)
1003     and their derivatives
1004     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
1005     References passed to 
1006     <jvmti/> functions can be either global or local, but they must be 
1007     strong references. All references returned by <jvmti/> functions are 
1008     local references--these local references are created 
1009     during the <jvmti/> call.
1010     Local references are a resource that must be managed (see the 
1011     <externallink id="docs/technotes/guides/jni/spec/functions.html#local_references">
1012       JNI Documentation</externallink>).  
1013     When threads return from native code all local references
1014     are freed.  Note that some threads, including typical
1015     agent threads, will never return from native code.
1016     A thread is ensured the ability to create sixteen local 
1017     references without the need for any explicit management.
1018     For threads executing a limited number of <jvmti/> calls before
1019     returning from native code
1020     (for example, threads processing events), 
1021     it may be determined that no explicit management
1022     is needed.
1023     However, long running agent threads will need explicit
1024     local reference management--usually with the JNI functions
1025     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
1026     Conversely, to preserve references beyond the
1027     return from native code, they must be converted to global references.
1028     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> 
1029     as they are not <datalink id="jobject"/>s.
1030 </intro>
1031 
1032     <intro id="prereqState" label="Prerequisite State for Calling Functions">
1033       Unless the function explicitly states that the agent must bring
1034       a thread or the VM to a particular state (for example, suspended),
1035       the <jvmti/> implementation is responsible for bringing the VM to a
1036       safe and consistent state for performing the function.
1037     </intro>
1038 
1039     <intro id="functionsExceptions" label="Exceptions and Functions">
1040       <jvmti/> functions never throw exceptions; error conditions are 
1041       communicated via the 
1042       <internallink id="functionReturn">function return value</internallink>.
1043       Any existing exception state is preserved across a call to a 
1044       <jvmti/> function.
1045       See the
1046       <externallink 
1047         id="docs/technotes/guides/jni/spec/design.html#java_exceptions"
1048              >Java Exceptions</externallink>
1049       section of the JNI specification for information on handling exceptions.
1050     </intro>
1051 
1052   <category id="memory" label="Memory Management">
1053     <intro>
1054       These functions provide for the allocation and deallocation of 
1055       memory used by <jvmti/> functionality and can be used to provide
1056       working memory for agents.
1057       Memory managed by <jvmti/> is not compatible with other memory
1058       allocation libraries and mechanisms.
1059     </intro>
1060 
1061     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
1062       <synopsis>Allocate</synopsis>
1063       <description>
1064         Allocate an area of memory through the <jvmti/> allocator. 
1065         The allocated
1066         memory should be freed with <functionlink id="Deallocate"></functionlink>.
1067       </description>


2093         </constants>
2094         <p/>
2095         The new thread is started as a daemon thread with the specified
2096         <paramlink id="priority"></paramlink>.
2097         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2098         <p/>
2099         Since the thread has been started, the thread will be live when this function
2100         returns, unless the thread has died immediately.
2101         <p/>
2102         The thread group of the thread is ignored -- specifically, the thread is not
2103         added to the thread group and the thread is not seen on queries of the thread
2104         group at either the Java programming language or <jvmti/> levels.
2105         <p/>
2106         The thread is not visible to Java programming language queries but is 
2107         included in <jvmti/> queries (for example, 
2108         <functionlink id="GetAllThreads"/> and
2109         <functionlink id="GetAllStackTraces"/>).
2110         <p/>
2111         Upon execution of <code>proc</code>, the new thread will be attached to the
2112         VM--see the JNI documentation on 
2113         <externallink id="docs/technotes/guides/jni/spec/invocation.html#attaching_to_the_vm"
2114                       >Attaching to the VM</externallink>.
2115       </description>
2116       <origin>jvmdiClone</origin>
2117       <capabilities>
2118       </capabilities>
2119       <parameters>
2120         <param id="thread">
2121           <jthread impl="noconvert" started="no"/>
2122             <description>
2123               The thread to run.
2124             </description>
2125         </param>
2126         <param id="proc">
2127           <ptrtype>
2128             <struct>jvmtiStartFunction</struct>
2129           </ptrtype>
2130           <description>
2131             The start function.
2132           </description>
2133         </param>


6635           <description>
6636             On return, points to the number of classes.
6637           </description>
6638         </param>
6639         <param id="classes_ptr">
6640           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6641             <description>
6642               On return, points to an array of references, one
6643               for each class.
6644             </description>
6645         </param>
6646       </parameters>
6647       <errors>
6648       </errors>
6649     </function>
6650 
6651     <function id="GetClassSignature" phase="start" num="48">
6652       <synopsis>Get Class Signature</synopsis>
6653       <description>
6654         For the class indicated by <code>klass</code>, return the 
6655         <externallink id="docs/technotes/guides/jni/spec/types.html#type_signatures">JNI 
6656             type signature</externallink> 
6657         and the generic signature of the class.
6658         For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
6659         and <code>int[]</code> is <code>"[I"</code>
6660         The returned name for primitive classes
6661         is the type signature character of the corresponding primitive type. 
6662         For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
6663       </description>
6664       <origin>jvmdiClone</origin>
6665       <capabilities>
6666       </capabilities>
6667       <parameters>
6668         <param id="klass">
6669           <jclass/>
6670             <description>
6671               The class to query.
6672             </description>
6673         </param>
6674         <param id="signature_ptr">
6675           <allocbuf>


8924         </param>
8925         <param id="monitors_ptr">
8926           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
8927           <description>
8928             On return, pointer to the monitor list.
8929           </description>
8930         </param>
8931       </parameters>
8932       <errors>
8933       </errors>
8934     </function>
8935     </elide>
8936   </category>
8937 
8938   <category id="jniIntercept" label="JNI Function Interception">
8939 
8940     <intro>
8941       Provides the ability to intercept and resend 
8942       Java Native Interface (JNI) function calls
8943       by manipulating the JNI function table.
8944       See <externallink id="docs/technotes/guides/jni/spec/functions.html">JNI
8945         Functions</externallink> in the <i>Java Native Interface Specification</i>.
8946       <p/>
8947       The following example illustrates intercepting the 
8948       <code>NewGlobalRef</code> JNI call in order to count reference
8949       creation.
8950       <example>
8951 JNIEnv original_jni_Functions;
8952 JNIEnv redirected_jni_Functions;
8953 int my_global_ref_count = 0;
8954 
8955 jobject
8956 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
8957    ++my_global_ref_count;
8958    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
8959 }
8960 
8961 void
8962 myInit() {
8963    jvmtiError err;
8964 


10625       These functions allow the agent to add to the locations that a class loader searches for a class.
10626       This is useful for installing instrumentation under the correct class loader.
10627     </intro>
10628 
10629     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
10630       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
10631       <description>
10632           This function can be used to cause instrumentation classes to be defined by the 
10633           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
10634           After the bootstrap
10635           class loader unsuccessfully searches for a class, the specified platform-dependent 
10636           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in 
10637           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, 
10638           the segments will be searched in the order that this function was called.
10639           <p/>
10640           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10641           search path segment to be searched after the bootstrap class loader unsuccessfully searches
10642           for a class. The segment is typically a directory or JAR file.
10643           <p/>      
10644           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
10645           path to a <externallink id="docs/technotes/guides/jar/jar.html">
10646           JAR file</externallink>. The agent should take care that the JAR file does not
10647           contain any classes or resources other than those to be defined by the bootstrap
10648           class loader for the purposes of instrumentation.
10649           <p/>
10650           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10651           reference that the Java virtual machine has previously unsuccessfully attempted
10652           to resolve always fails with the same error that was thrown as a result of the
10653           initial resolution attempt. Consequently, if the JAR file contains an entry
10654           that corresponds to a class for which the Java virtual machine has
10655           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10656           resolve that reference will fail with the same error as the initial attempt.
10657       </description>
10658       <origin>new</origin>
10659       <capabilities>
10660       </capabilities>
10661       <parameters>
10662         <param id="segment">
10663           <inbuf><char/></inbuf>
10664           <description>
10665             The platform-dependent search path segment, encoded as a


10672           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10673            existing JAR file is an invalid path.
10674         </error>
10675       </errors>
10676     </function>
10677 
10678     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
10679       <synopsis>Add To System Class Loader Search</synopsis>
10680       <description>
10681           This function can be used to cause instrumentation classes to be
10682           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
10683           After the class loader unsuccessfully searches for a class, the specified platform-dependent search 
10684           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the 
10685           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the 
10686           segments will be searched in the order that this function was called.
10687           <p/>
10688           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10689           search path segment to be searched after the system class loader unsuccessfully searches
10690           for a class. The segment is typically a directory or JAR file.
10691           <p/>      
10692           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a
10693           <externallink id="docs/technotes/guides/jar/jar.html">JAR file</externallink> to be
10694           searched after the system class loader unsuccessfully searches for a class. The agent should
10695           take care that the JAR file does not contain any classes or resources other than those to be
10696           defined by the system class loader for the purposes of instrumentation.
10697           <p/>
10698           In the live phase the system class loader supports adding a JAR file to be searched if
10699           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> 
10700           which takes a single parameter of type <code>java.lang.String</code>. The method is not required 
10701           to have <code>public</code> access. 
10702           <p/>
10703           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10704           reference that the Java virtual machine has previously unsuccessfully attempted
10705           to resolve always fails with the same error that was thrown as a result of the
10706           initial resolution attempt. Consequently, if the JAR file contains an entry
10707           that corresponds to a class for which the Java virtual machine has
10708           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10709           resolve that reference will fail with the same error as the initial attempt.
10710       </description>
10711       <origin>new</origin>
10712       <capabilities>
10713       </capabilities>


13504 } jvmtiEventCallbacks;
13505 </example>
13506         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> 
13507         for the complete structure.
13508         <p/>
13509         Where, for example, the VM initialization callback is defined:
13510 <example>
13511 typedef void (JNICALL *jvmtiEventVMInit)
13512     (jvmtiEnv *jvmti_env, 
13513      JNIEnv* jni_env,
13514      jthread thread);
13515 </example>
13516         See the individual events for the callback function definition.
13517       </description>
13518     </basetype>
13519     <basetype id="jniNativeInterface">
13520       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
13521       <description>
13522         Typedef for the JNI function table <code>JNINativeInterface</code>
13523         defined in the 
13524         <externallink id="docs/technotes/guides/jni/spec/functions.html#interface_function_table">
13525           JNI Specification</externallink>.
13526         The JNI reference implementation defines this with an underscore.
13527       </description>
13528     </basetype>
13529   </basetypes>
13530 
13531 </datasection>
13532 
13533 <issuessection label="Issues">
13534   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
13535     JVMDI requires that the agent suspend threads before calling
13536     certain sensitive functions.  JVMPI requires garbage collection to be 
13537     disabled before calling certain sensitive functions. 
13538     It was suggested that rather than have this requirement, that
13539     VM place itself in a suitable state before performing an
13540     operation.  This makes considerable sense since each VM
13541     knows its requirements and can most easily arrange a
13542     safe state.  
13543     <p/>
13544     The ability to externally suspend/resume threads will, of
13545     course, remain.  The ability to enable/disable garbage collection will not.