1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
   3 <!--
   4  Copyright (c) 2002, 2012, Oracle and/or its affiliates. All rights reserved.
   5  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6 
   7  This code is free software; you can redistribute it and/or modify it
   8  under the terms of the GNU General Public License version 2 only, as
   9  published by the Free Software Foundation.
  10 
  11  This code is distributed in the hope that it will be useful, but WITHOUT
  12  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  version 2 for more details (a copy is included in the LICENSE file that
  15  accompanied this code).
  16 
  17  You should have received a copy of the GNU General Public License version
  18  2 along with this work; if not, write to the Free Software Foundation,
  19  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20 
  21  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  or visit www.oracle.com if you need additional information or have any
  23  questions.
  24   
  25 -->
  26 
  27 <!DOCTYPE specification [
  28    <!ELEMENT specification (title, intro*, functionsection, errorsection, 
  29                             eventsection, datasection, issuessection, changehistory)>
  30    <!ATTLIST specification label CDATA #REQUIRED 
  31                            majorversion CDATA #REQUIRED 
  32                            minorversion CDATA #REQUIRED 
  33                            microversion CDATA #REQUIRED>
  34 
  35    <!ELEMENT title (#PCDATA|jvmti|tm)*>
  36    <!ATTLIST title subtitle CDATA #REQUIRED>
  37 
  38    <!ELEMENT intro ANY>
  39    <!ATTLIST intro id CDATA #IMPLIED
  40                    label CDATA "">
  41 
  42    <!ELEMENT functionsection (intro*, category*)>
  43    <!ATTLIST functionsection label CDATA #REQUIRED>
  44 
  45    <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*, 
  46                           (function|callback|elide)*)>
  47    <!ATTLIST category id CDATA #REQUIRED
  48                       label CDATA #REQUIRED>
  49 
  50    <!ELEMENT function (synopsis, typedef*, description?, origin,
  51                          (capabilities|eventcapabilities), 
  52                          parameters, errors)>
  53    <!ATTLIST function id CDATA #REQUIRED
  54                       num CDATA #REQUIRED
  55                       phase (onload|onloadOnly|start|live|any) #IMPLIED
  56                       callbacksafe (safe|unsafe) #IMPLIED
  57                       impl CDATA #IMPLIED
  58                       hide CDATA #IMPLIED
  59                       jkernel (yes|no) #IMPLIED
  60                       since CDATA "1.0">
  61 
  62    <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  63                         jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
  64                         synopsis, description?, parameters)>
  65    <!ATTLIST callback id CDATA #REQUIRED
  66                       since CDATA "1.0">
  67 
  68    <!ELEMENT synopsis (#PCDATA|jvmti)*>
  69 
  70    <!ELEMENT typedef (description?, field*)>
  71    <!ATTLIST typedef id CDATA #REQUIRED
  72                      label CDATA #REQUIRED
  73                      since CDATA "1.0">
  74 
  75    <!ELEMENT uniontypedef (description?, field*)>
  76    <!ATTLIST uniontypedef id CDATA #REQUIRED
  77                      label CDATA #REQUIRED
  78                      since CDATA "1.0">
  79 
  80    <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  81                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct), 
  82                     description)>
  83    <!ATTLIST field id CDATA #REQUIRED>
  84 
  85    <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
  86    <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
  87                      label CDATA #REQUIRED>
  88 
  89    <!ELEMENT capabilityfield (description)>
  90    <!ATTLIST capabilityfield id CDATA #REQUIRED
  91                    disp1 CDATA ""
  92                    disp2 CDATA ""
  93                    since CDATA "1.0">
  94 
  95    <!ELEMENT description ANY>
  96 
  97    <!ELEMENT capabilities (required*, capability*)>
  98 
  99    <!ELEMENT eventcapabilities EMPTY>
 100 
 101    <!ELEMENT required ANY>
 102    <!ATTLIST required id CDATA #REQUIRED>
 103 
 104    <!ELEMENT capability ANY>
 105    <!ATTLIST capability id CDATA #REQUIRED>
 106 
 107    <!ELEMENT parameters (param*)>
 108 
 109    <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
 110                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
 111                      outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf), 
 112                     description)>
 113    <!ATTLIST param id CDATA #REQUIRED>
 114 
 115    <!ELEMENT jmethodID EMPTY>
 116    <!ATTLIST jmethodID class  CDATA #IMPLIED
 117                        native CDATA #IMPLIED>
 118 
 119    <!ELEMENT jfieldID EMPTY>
 120    <!ATTLIST jfieldID class CDATA #IMPLIED>
 121 
 122    <!ELEMENT jclass EMPTY>
 123    <!ATTLIST jclass method CDATA #IMPLIED
 124                     field  CDATA #IMPLIED>
 125 
 126    <!ELEMENT jframeID EMPTY>
 127    <!ATTLIST jframeID thread CDATA #IMPLIED>
 128 
 129    <!ELEMENT jrawMonitorID EMPTY>
 130 
 131    <!ELEMENT jthread EMPTY>
 132    <!ATTLIST jthread started CDATA #IMPLIED
 133                      null CDATA #IMPLIED
 134                      frame CDATA #IMPLIED
 135                      impl CDATA #IMPLIED>
 136 
 137    <!ELEMENT varargs EMPTY>
 138 
 139    <!ELEMENT jthreadGroup EMPTY>
 140    <!ELEMENT jobject EMPTY>
 141    <!ELEMENT jvalue EMPTY>
 142    <!ELEMENT jchar EMPTY>
 143    <!ELEMENT jint EMPTY>
 144    <!ATTLIST jint min CDATA #IMPLIED>
 145    <!ELEMENT jlong EMPTY>
 146    <!ELEMENT jfloat EMPTY>
 147    <!ELEMENT jdouble EMPTY>
 148    <!ELEMENT jlocation EMPTY>
 149    <!ELEMENT jboolean EMPTY>
 150    <!ELEMENT char EMPTY>
 151    <!ELEMENT uchar EMPTY>
 152    <!ELEMENT size_t EMPTY>
 153    <!ELEMENT void EMPTY>
 154    <!ELEMENT enum (#PCDATA)*>
 155    <!ELEMENT struct (#PCDATA)*>
 156 
 157    <!ELEMENT nullok ANY>
 158 
 159    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 160                                    jthreadGroup|jobject|jvalue), nullok?)>
 161 
 162    <!ELEMENT outptr     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 163                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 164                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 165 
 166    <!ELEMENT allocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 167                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 168                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 169    <!ATTLIST allocbuf incount CDATA #IMPLIED
 170                       outcount CDATA #IMPLIED>
 171 
 172    <!ELEMENT allocallocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 173                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 174                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 175    <!ATTLIST allocallocbuf incount CDATA #IMPLIED
 176                       outcount CDATA #IMPLIED>
 177 
 178    <!ELEMENT inptr      (struct, nullok?)>
 179 
 180    <!ELEMENT inbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 181                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 182                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 183    <!ATTLIST inbuf    incount CDATA #IMPLIED>
 184 
 185    <!ELEMENT outbuf     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 186                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 187                                    jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
 188    <!ATTLIST outbuf   incount CDATA #IMPLIED
 189                       outcount CDATA #IMPLIED>
 190 
 191    <!ELEMENT vmbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 192                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 193                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 194    <!ATTLIST vmbuf    incount CDATA #IMPLIED
 195                       outcount CDATA #IMPLIED>
 196 
 197    <!ELEMENT agentbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 198                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 199                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 200    <!ATTLIST agentbuf incount CDATA #IMPLIED
 201                       outcount CDATA #IMPLIED>
 202 
 203    <!ELEMENT allocfieldbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 204                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 205                                    jlocation|jboolean|char|uchar|size_t|void))>
 206    <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
 207 
 208    <!ELEMENT errors (error*)>
 209 
 210    <!ELEMENT error ANY>
 211    <!ATTLIST error id CDATA #REQUIRED>
 212 
 213    <!ELEMENT errorsection (intro*, errorcategory*)>
 214    <!ATTLIST errorsection label CDATA #REQUIRED>
 215 
 216    <!ELEMENT errorcategory (intro*, errorid*)>
 217    <!ATTLIST errorcategory id CDATA #REQUIRED
 218                            label CDATA #REQUIRED>
 219 
 220    <!ELEMENT errorid ANY>
 221    <!ATTLIST errorid id CDATA #REQUIRED
 222                      num CDATA #REQUIRED>
 223 
 224    <!ELEMENT datasection (intro*, basetypes*)>
 225 
 226    <!ELEMENT basetypes (intro*, basetype*)>
 227    <!ATTLIST basetypes id CDATA #REQUIRED
 228                        label CDATA #REQUIRED>
 229 
 230    <!ELEMENT basetype (definition?,description)>
 231    <!ATTLIST basetype id CDATA #REQUIRED>
 232 
 233    <!ELEMENT definition (#PCDATA|jvmti)*>
 234 
 235    <!ELEMENT eventsection (intro*, (event|elide)*)>
 236    <!ATTLIST eventsection label CDATA #REQUIRED>
 237 
 238    <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
 239    <!ATTLIST event id CDATA #REQUIRED
 240                    label CDATA #REQUIRED
 241                    const CDATA #REQUIRED
 242                    num CDATA #REQUIRED
 243                    phase (onload|start|live|any) #IMPLIED
 244                    filtered (thread|global) #IMPLIED
 245                    since CDATA "1.0">
 246 
 247    <!ELEMENT issuessection (intro*)>
 248    <!ATTLIST issuessection label CDATA #REQUIRED>
 249 
 250    <!ELEMENT changehistory (intro*, change*)>
 251    <!ATTLIST changehistory update CDATA #REQUIRED
 252                            id CDATA #REQUIRED>
 253 
 254    <!ELEMENT change ANY>
 255    <!ATTLIST change date CDATA #REQUIRED
 256                     version CDATA #IMPLIED>
 257 
 258    <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
 259    <!ATTLIST functionlink id CDATA #REQUIRED>
 260 
 261    <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
 262    <!ATTLIST datalink id CDATA #REQUIRED>
 263 
 264    <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
 265    <!ATTLIST typelink id CDATA #REQUIRED>
 266 
 267    <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
 268    <!ATTLIST fieldlink id CDATA #REQUIRED
 269                        struct CDATA #REQUIRED>
 270 
 271    <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
 272    <!ATTLIST paramlink id CDATA #REQUIRED>
 273 
 274    <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
 275    <!ATTLIST eventlink id CDATA #REQUIRED>
 276 
 277    <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
 278    <!ATTLIST errorlink id CDATA #REQUIRED>
 279 
 280    <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
 281    <!ATTLIST externallink id CDATA #REQUIRED>
 282 
 283    <!ELEMENT vmspec EMPTY>
 284    <!ATTLIST vmspec chapter CDATA #IMPLIED>
 285 
 286    <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
 287    <!ATTLIST internallink id CDATA #REQUIRED>
 288 
 289    <!ELEMENT functionphaselist EMPTY>
 290    <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
 291 
 292    <!ELEMENT eventphaselist EMPTY>
 293    <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
 294 
 295    <!ELEMENT issue ANY>
 296    
 297    <!ELEMENT rationale ANY>
 298    
 299    <!ELEMENT todo ANY>
 300    
 301    <!ELEMENT origin (#PCDATA)*>
 302 
 303    <!ELEMENT elide (intro|function|callback|event)*>
 304    <!ATTLIST elide why CDATA #IMPLIED>
 305    
 306    <!ELEMENT constants (constant*)>
 307    <!ATTLIST constants id CDATA #REQUIRED
 308                        label CDATA #REQUIRED
 309                        kind (enum|bits|const) #REQUIRED
 310                        since CDATA "1.0">
 311 
 312    <!ELEMENT constant ANY>
 313    <!ATTLIST constant id CDATA #REQUIRED
 314                       num CDATA #REQUIRED>
 315 
 316    <!ELEMENT tm (#PCDATA)>
 317 
 318    <!ELEMENT i (#PCDATA|jvmti|tm)*>
 319 
 320    <!ELEMENT b (#PCDATA|jvmti|code)*>
 321 
 322    <!ELEMENT code (#PCDATA|space)*>
 323 
 324    <!ELEMENT pre ANY>
 325 
 326    <!ELEMENT space EMPTY>
 327 
 328    <!ELEMENT jvmti EMPTY>
 329 
 330    <!ELEMENT example (#PCDATA|i)*>
 331 
 332    <!ELEMENT br EMPTY>
 333 
 334    <!ELEMENT p EMPTY>
 335 
 336    <!ELEMENT dl  (dt|dd)+>
 337 
 338    <!ELEMENT dd  ANY>
 339 
 340    <!ELEMENT dt  (#PCDATA|jvmti|code|i|b)*>
 341 
 342    <!ELEMENT table  (tr)+>
 343 
 344    <!ELEMENT tr  (td|th)*>
 345 
 346    <!ELEMENT td  ANY>
 347    <!ATTLIST td align (left|right|center) "center">
 348 
 349    <!ELEMENT th  ANY>
 350    <!ATTLIST th align (left|right|center) "center">
 351 
 352    <!ELEMENT ul  (li)+>
 353    <!ATTLIST ul type (disc|circle|square) "disc">
 354 
 355    <!ELEMENT li  ANY>
 356  ]>
 357 
 358 <specification label="JVM(TM) Tool Interface"
 359         majorversion="1"
 360         minorversion="2"
 361         microversion="2">
 362   <title subtitle="Version">
 363     <tm>JVM</tm> Tool Interface
 364   </title>
 365   
 366   <intro id="whatIs" label="What is the JVM Tool Interface?">
 367     The <tm>JVM</tm> Tool Interface (<jvmti/>) 
 368     is a programming interface used by development and monitoring tools. 
 369     It provides both a way to inspect the state and 
 370     to control the execution of applications running in the
 371     <tm>Java</tm> virtual machine (VM).
 372     <p/>
 373     <jvmti/> is intended to provide a VM interface for the full breadth of tools
 374     that need access to VM state, including but not limited to: profiling,
 375     debugging, monitoring, thread analysis, and coverage analysis tools.
 376     <p/>
 377     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
 378     machine.
 379     <p/>
 380     <jvmti/> is a two-way interface. 
 381     A client of <jvmti/>, hereafter called an <i>agent</i>,
 382     can be notified of
 383     interesting occurrences through <internallink id="EventSection">events</internallink>. 
 384     <jvmti/>
 385     can query and control the application through many 
 386     <internallink id="FunctionSection">functions</internallink>, 
 387     either in response to events or 
 388     independent of them.
 389     <p/>
 390     Agents run in the same process with and communicate directly with 
 391     the virtual machine executing
 392     the application being examined.  This communication is
 393     through a native interface (<jvmti/>). The native in-process interface allows
 394     maximal control with minimal intrusion on the part of a tool. 
 395     Typically, agents are relatively compact. They can be controlled
 396     by a separate process which implements the bulk of a tool's
 397     function without interfering with the target application's normal execution.
 398   </intro>
 399 
 400   <intro id="architecture" label="Architecture">
 401     Tools can be written directly to <jvmti/> or indirectly
 402     through higher level interfaces.
 403     The Java Platform Debugger Architecture includes <jvmti/>, but also
 404     contains higher-level, out-of-process debugger interfaces. The higher-level 
 405     interfaces are more appropriate than <jvmti/> for many tools. 
 406     For more information on the Java Platform Debugger Architecture, 
 407     see the 
 408     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">Java 
 409       Platform Debugger Architecture website</externallink>. 
 410   </intro>
 411 
 412   <intro id="writingAgents" label="Writing Agents">
 413     Agents can be written in any native language that supports C
 414     language calling conventions and C or C++
 415     definitions.
 416     <p/>
 417     The function, event, data type, and constant definitions needed for
 418     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 419     To use these definitions add the <tm>J2SE</tm> include directory
 420     to your include path and add
 421     <example>
 422 #include &lt;jvmti.h&gt;
 423     </example>
 424     to your source code.
 425   </intro>
 426 
 427   <intro id="deployingAgents" label="Deploying Agents">
 428     An agent is deployed in a platform specific manner but is typically the 
 429     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating 
 430     system, for example, an agent library is a "Dynamic Linked Library" (DLL). 
 431     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
 432     object (<code>.so</code> file).
 433     <p/>
 434     An agent may be started at VM startup by specifying the agent library
 435     name using a <internallink id="starting">command line option</internallink>.
 436     Some implementations may support a mechanism to <internallink id="onattach"> 
 437     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
 438     The details of how this is initiated are implementation specific.
 439   </intro>
 440   
 441   <intro id="starting" label="Agent Command Line Options">
 442     The term "command-line option" is used below to
 443     mean options supplied in the <code>JavaVMInitArgs</code> argument
 444     to the <code>JNI_CreateJavaVM</code> function of the JNI
 445     Invocation API.
 446     <p/>
 447     One of the two following 
 448     command-line options is used on VM startup to 
 449     properly load and run agents.
 450     These arguments identify the library containing 
 451     the agent as well as an options
 452     string to be passed in at startup. 
 453     <dl>
 454       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 455       <dd>
 456         The name following <code>-agentlib:</code> is the name of the
 457         library to load.  Lookup of the library, both its full name and location,
 458         proceeds in a platform-specific manner. 
 459         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
 460         operating system specific file name.
 461         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 462         For example, if the option 
 463         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to 
 464         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
 465         under <tm>Windows</tm> or <code>libfoo.so</code> from the 
 466         <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment.
 467       </dd>
 468       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 469       <dd>
 470         The path following <code>-agentpath:</code> is the absolute path from which
 471         to load the library.
 472         No library name expansion will occur.
 473         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 474         For example, if the option 
 475         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to 
 476         load the shared library <code>c:\myLibs\foo.dll</code>.
 477       </dd>
 478     </dl>
 479     The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 480     in the library will be invoked.
 481     <p/>
 482     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
 483     will be searched for JNI native method implementations to facilitate the
 484     use of Java programming language code in tools, as is needed for 
 485     <internallink id="bci">bytecode instrumentation</internallink>.
 486     <p/>
 487     The agent libraries will be searched after all other libraries have been
 488     searched (agents wishing to override or intercept the native method
 489     implementations of non-agent methods can use the
 490     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
 491     <p/>
 492     These switches do the above and nothing more - they do not change the 
 493     state of the VM or <jvmti/>.  No command line options are needed 
 494     to enable <jvmti/> 
 495     or aspects of <jvmti/>, this is handled programmatically
 496     by the use of 
 497     <internallink id="capability">capabilities</internallink>.
 498   </intro>
 499 
 500   <intro id="startup" label="Agent Start-Up">
 501     The VM starts each agent by invoking a start-up function.
 502     If the agent is started in the <code>OnLoad</code>
 503     <functionlink id="GetPhase">phase</functionlink> the function
 504     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 505     will be invoked.
 506     If the agent is started in the live
 507     <functionlink id="GetPhase">phase</functionlink> the function
 508     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
 509     will be invoked.
 510     Exactly one call to a start-up function is made per agent.  
 511   </intro>
 512 
 513   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
 514     If an agent is started during the <code>OnLoad</code> phase then its
 515     agent library must export a start-up function with the following prototype:
 516     <example>
 517 JNIEXPORT jint JNICALL 
 518 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
 519     The VM will start the agent by calling this function.  
 520     It will be called early enough in VM initialization that:
 521     <ul>
 522       <li><functionlink id="SetSystemProperty">system properties</functionlink>
 523         may be set before they have been used in the start-up of the VM</li>
 524       <li>the full set of 
 525         <internallink id="capability">capabilities</internallink>
 526         is still available (note that capabilities that configure the VM
 527         may only be available at this time--see the 
 528         <internallink id="capability">Capability function section</internallink>)</li>
 529       <li>no bytecodes have executed</li>
 530       <li>no classes have been loaded</li>
 531       <li>no objects have been created</li>
 532     </ul>
 533     <p/>
 534     The VM will call the <code>Agent_OnLoad</code> function with
 535     <i>&lt;options&gt;</i> as the second argument - 
 536     that is, using the command-line option examples,
 537     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> 
 538     argument of <code>Agent_OnLoad</code>.
 539     The <code>options</code> argument is encoded as a
 540     <internallink id="mUTF">modified UTF-8</internallink> string.
 541     If <i>=&lt;options&gt;</i> is not specified, 
 542     a zero length string is passed to <code>options</code>.
 543     The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code>
 544     call.  If needed beyond this time the string or parts of the string must
 545     be copied.
 546     The period between when <code>Agent_OnLoad</code> is called and when it
 547     returns is called the <i>OnLoad phase</i>.
 548     Since the VM is not initialized during the OnLoad 
 549     <functionlink id="GetPhase">phase</functionlink>,
 550     the set of allowed operations 
 551     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
 552     functionality available at this time). 
 553     The agent can safely process the options and set 
 554     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once  
 555     the VM initialization event is received 
 556     (that is, the <eventlink id="VMInit">VMInit</eventlink> 
 557     callback is invoked), the agent
 558     can complete its initialization.
 559     <rationale>
 560       Early startup is required so that agents can set the desired capabilities,
 561       many of which must be set before the VM is initialized.
 562       In JVMDI, the -Xdebug command-line option provided 
 563       very coarse-grain control of capabilities. 
 564       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
 565       No reasonable command-line 
 566       option could provide the fine-grain of control required to balance needed capabilities vs
 567       performance impact.  
 568       Early startup is also needed so that agents can control the execution
 569       environment - modifying the file system and system properties to install
 570       their functionality.
 571     </rationale>
 572     <p/>
 573     The return value from <code>Agent_OnLoad</code> is used to indicate an error.
 574     Any value other than zero indicates an error and causes termination of the VM.
 575   </intro>
 576   
 577   <intro id="onattach" label="Agent Start-Up (Live phase)">
 578     A VM may support a mechanism that allows agents to be started in the VM during the live 
 579     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
 580     are implementation specific. For example, a tool may use some platform specific mechanism, 
 581     or implementation specific API, to attach to the running VM, and request it start a given
 582     agent.
 583     <p/>
 584     If an agent is started during the live phase then its agent library
 585     must export a start-up function 
 586     with the following prototype:
 587     <example>
 588 JNIEXPORT jint JNICALL 
 589 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
 590     <p/>         
 591     The VM will start the agent by calling this function.  
 592     It will be called in the context of a thread
 593     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
 594     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
 595     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
 596     </internallink> string.
 597     If startup options were not provided, a zero length string is passed to 
 598     <code>options</code>. The lifespan of the <code>options</code> string is the 
 599     <code>Agent_OnAttach</code> call.  If needed beyond this time the string or parts of 
 600     the string must be copied.
 601     <p/>
 602     Note that some <internallink id="capability">capabilities</internallink> 
 603     may not be available in the live phase.
 604     <p/>
 605     The <code>Agent_OnAttach</code> function initializes the agent and returns a value
 606     to the VM to indicate if an error occurred. Any value other than zero indicates an error. 
 607     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes 
 608     some implementation specific action -- for example it might print an error to standard error, 
 609     or record the error in a system log.
 610   </intro>
 611 
 612   <intro id="onunload" label="Agent Shutdown">
 613     The library may optionally export a 
 614     shutdown function with the following prototype:
 615     <example>
 616 JNIEXPORT void JNICALL 
 617 Agent_OnUnload(JavaVM *vm)</example>
 618     This function will be called by the VM when the library is about to be unloaded.
 619     The library will be unloaded and this function will be called if some platform specific 
 620     mechanism causes the unload (an unload mechanism is not specified in this document)
 621     or the library is (in effect) unloaded by the termination of the VM whether through 
 622     normal termination or VM failure, including start-up failure.
 623     Uncontrolled shutdown is, of couse, an exception to this rule.
 624     Note the distinction between this function and the 
 625     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
 626     to be sent, the VM must have run at least to the point of initialization and a valid 
 627     <jvmti/> environment must exist which has set a callback for VMDeath
 628     and enabled the event
 629     None of these are required for <code>Agent_OnUnload</code> and this function
 630     is also called if the library is unloaded for other reasons.
 631     In the case that a VM Death event is sent, it will be sent before this 
 632     function is called (assuming this function is called due to VM termination).
 633     This function can be used to clean-up resources allocated by the agent.
 634   </intro>
 635 
 636   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
 637     Since the command-line cannot always be accessed or modified, for example in embedded VMs
 638     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
 639     provided so that agents may be launched in these cases.
 640     <p/>
 641     Platforms which support environment variables or other named strings, may support the 
 642     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space 
 643     boundaries.  White-space characters include space, tab, carriage-return, new-line, 
 644     vertical-tab, and form-feed.  Sequences of white-space characters are considered 
 645     equivalent to a single white-space character.  No white-space is included in the options 
 646     unless quoted.  Quoting is as follows:
 647     <ul>
 648         <li>All characters enclosed between a pair of single quote marks (''), except a single 
 649         quote, are quoted.</li>
 650         <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
 651         <li>All characters enclosed between a pair of double quote marks (""), except a double 
 652         quote, are quoted.</li>
 653         <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
 654         <li>A quoted part can start or end anywhere in the variable.</li>
 655         <li>White-space characters have no special meaning when quoted -- they are included in
 656         the option like any other character and do not mark white-space boundaries.</li>
 657         <li>The pair of quote marks is not included in the option.</li>
 658     </ul>
 659     <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied 
 660     in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is 
 661     a concern; for example, the Reference Implementation disables this feature on Unix systems when 
 662     the effective user or group ID differs from the real ID.  
 663     This feature is intended to support the initialization of tools -- specifically including the 
 664     launching of native or Java programming language agents.  Multiple tools may wish to use this 
 665     feature, so the variable should not be overwritten, instead,  options should be appended to 
 666     the variable.  Note that since the variable is processed at the time of the JNI Invocation 
 667     API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
 668   </intro>
 669 
 670   <intro id="environments" label="Environments">
 671     The <jvmti/> specification supports the use of multiple simultaneous
 672     <jvmti/> agents.
 673     Each agent has its own <jvmti/> environment.  
 674     That is, the <jvmti/> state is
 675     separate for each agent - changes to one environment do not affect the
 676     others.  The state of a <jvmti/> 
 677     environment includes:
 678     <ul>
 679       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
 680       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
 681       <li><internallink id="capability">the capabilities</internallink></li>
 682       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
 683     </ul>
 684     Although their <jvmti/> state 
 685     is separate, agents inspect and modify the shared state
 686     of the VM, they also share the native environment in which they execute.
 687     As such, an agent can perturb the results of other agents or cause them
 688     to fail.  It is the responsibility of the agent writer to specify the level
 689     of compatibility with other agents.  <jvmti/> implementations are not capable
 690     of preventing destructive interactions between agents. Techniques to reduce
 691     the likelihood of these occurrences are beyond the scope of this document.
 692     <p/>
 693     An agent creates a <jvmti/> environment 
 694     by passing a <jvmti/> version 
 695     as the interface ID to the JNI Invocation API function 
 696     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>.
 697     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
 698     for more details on the creation and use of 
 699     <jvmti/> environments.
 700     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from 
 701     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
 702   </intro>
 703 
 704   <intro id="bci" label="Bytecode Instrumentation">
 705     This interface does not include some events that one might expect in an interface with
 706     profiling support.  Some examples include object allocation events and full speed
 707     method enter and exit events.  The interface instead provides support for 
 708     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
 709     bytecode instructions which comprise the target program.  Typically, these alterations
 710     are to add "events" to the code of a method - for example, to add, at the beginning of a method,
 711     a call to <code>MyProfiler.methodEntered()</code>.  
 712     Since the changes are purely additive, they do not modify application
 713     state or behavior.
 714     Because the inserted agent code is standard bytecodes, the VM can run at full speed,
 715     optimizing not only the target program but also the instrumentation.  If the 
 716     instrumentation does not involve switching from bytecode execution, no expensive
 717     state transitions are needed.  The result is high performance events.
 718     This approach also provides complete control to the agent: instrumentation can be
 719     restricted to "interesting" portions of the code (e.g., the end user's code) and
 720     can be conditional.  Instrumentation can run entirely in Java programming language
 721     code or can call into the native agent.  Instrumentation can simply maintain
 722     counters or can statistically sample events.
 723     <p/>  
 724     Instrumentation can be inserted in one of three ways:
 725     <ul>
 726       <li>
 727         Static Instrumentation: The class file is instrumented before it
 728         is loaded into the VM - for example, by creating a duplicate directory of
 729         <code>*.class</code> files which have been modified to add the instrumentation.
 730         This method is extremely awkward and, in general, an agent cannot know 
 731         the origin of the class files which will be loaded.
 732       </li>
 733       <li>
 734         Load-Time Instrumentation: When a class file is loaded by the VM, the raw
 735         bytes of the class file are sent for instrumentation to the agent.
 736         The <eventlink id="ClassFileLoadHook"/>
 737         event, triggered by the class load,
 738         provides this functionality.  This mechanism provides efficient
 739         and complete access to one-time instrumentation.
 740       </li>
 741       <li>
 742         Dynamic Instrumentation: A class which is already loaded (and possibly
 743         even running) is modified.  This optional feature is provided by the
 744         <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
 745         <functionlink id="RetransformClasses"/> function.
 746         Classes can be modified multiple times and can be returned to their
 747         original state.
 748         The mechanism allows instrumentation which changes during the 
 749         course of execution.
 750       </li>
 751     </ul>
 752     <p/>  
 753     The class modification functionality provided in this interface
 754     is intended to provide a mechanism for instrumentation
 755     (the <eventlink id="ClassFileLoadHook"/> event
 756     and the <functionlink id="RetransformClasses"/> function)
 757     and, during development, for fix-and-continue debugging
 758     (the <functionlink id="RedefineClasses"/> function).
 759     <p/>  
 760     Care must be taken to avoid perturbing dependencies, especially when 
 761     instrumenting core classes.  For example, an approach to getting notification
 762     of every object allocation is to instrument the constructor on 
 763     <code>Object</code>.  Assuming that the constructor is initially
 764     empty, the constructor could be changed to:
 765     <example>
 766       public Object() {
 767         MyProfiler.allocationTracker(this);
 768       }
 769     </example>
 770     However, if this change was made using the 
 771     <eventlink id="ClassFileLoadHook"/>
 772     event then this might impact a typical VM as follows: 
 773     the first created object will call the constructor causing a class load of
 774     <code>MyProfiler</code>; which will then cause
 775     object creation, and since <code>MyProfiler</code> isn't loaded yet,
 776     infinite recursion; resulting in a stack overflow.  A refinement of this
 777     would be to delay invoking the tracking method until a safe time.  For
 778     example, <code>trackAllocations</code> could be set in the 
 779     handler for the <code>VMInit</code> event.
 780     <example>
 781       static boolean trackAllocations = false;
 782 
 783       public Object() {
 784         if (trackAllocations) {
 785           MyProfiler.allocationTracker(this);
 786         }
 787       }
 788     </example>
 789     <p/>
 790     The <functionlink id="SetNativeMethodPrefix"/> allows native methods
 791     to be instrumented by the use of wrapper methods.
 792   </intro>
 793 
 794   <intro id="mUTF" label="Modified UTF-8 String Encoding">
 795     <jvmti/> uses modified UTF-8 to encode character strings.
 796     This is the same encoding used by JNI.
 797     Modified UTF-8 differs 
 798     from standard UTF-8 in the representation of supplementary characters 
 799     and of the null character. See the
 800     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542">
 801       Modified UTF-8 Strings</externallink>
 802     section of the JNI specification for details.
 803   </intro>
 804 
 805   <intro id="context" label="Specification Context">
 806     Since this interface provides access to the state of applications running in the
 807     Java virtual machine; 
 808     terminology refers to the Java platform and not the native
 809     platform (unless stated otherwise).  For example:
 810     <ul>
 811       <li>"thread" means Java programming language thread.</li>
 812       <li>"stack frame" means Java virtual machine stack frame.</li>
 813       <li>"class" means Java programming language class.</li>
 814       <li>"heap" means Java virtual machine heap.</li>
 815       <li>"monitor" means Java programming language object monitor.</li>
 816     </ul>
 817     <p/>
 818     Sun, Sun Microsystems, the Sun logo, Java, and JVM
 819     are trademarks or registered trademarks of Oracle 
 820     and/or its affiliates, in the U.S. and other countries.
 821   </intro>
 822 
 823 
 824 <functionsection label="Functions">
 825   <intro id="jvmtiEnvAccess" label="Accessing Functions">
 826     Native code accesses <jvmti/> features 
 827     by calling <jvmti/> functions. 
 828     Access to <jvmti/> functions is by use of an interface pointer
 829     in the same manner as 
 830     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java 
 831       Native Interface (JNI) functions</externallink> are accessed.
 832     The <jvmti/> interface pointer is called the 
 833     <i>environment pointer</i>.
 834     <p/>
 835     An environment pointer is a pointer to an environment and has
 836     the type <code>jvmtiEnv*</code>.
 837     An environment has information about its <jvmti/> connection.
 838     The first value in the environment is a pointer to the function table.
 839     The function table is an array of pointers to <jvmti/> functions.
 840     Every function pointer is at a predefined offset inside the 
 841     array. 
 842     <p/>
 843     When used from the C language:
 844     double indirection is used to access the functions;
 845     the environment pointer provides context and is the first
 846     parameter of each function call; for example:
 847     <example>
 848 jvmtiEnv *jvmti;
 849 ...
 850 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);
 851     </example>
 852     <p/>
 853     When used from the C++ language:
 854     functions are accessed as member functions of <code>jvmtiEnv</code>;
 855     the environment pointer is not passed to the function call; for example:
 856     <example>
 857 jvmtiEnv *jvmti;
 858 ...
 859 jvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);
 860     </example>
 861     Unless otherwise stated, all examples and declarations in this 
 862     specification use the C language.
 863     <p/>
 864     A <jvmti/> environment can be obtained through the JNI Invocation API
 865     <code>GetEnv</code> function:
 866     <example>
 867 jvmtiEnv *jvmti;
 868 ...
 869 (*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);
 870     </example>
 871     Each call to <code>GetEnv</code> 
 872     creates a new <jvmti/> connection and thus
 873     a new <jvmti/> environment. 
 874     The <code>version</code> argument of <code>GetEnv</code> must be
 875     a <jvmti/> version.
 876     The returned environment may have a different version than the
 877     requested version but the returned environment must be compatible.
 878     <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a 
 879     compatible version is not available, if <jvmti/> is not supported or
 880     <jvmti/> is not supported in the current VM configuration.
 881     Other interfaces may be added for creating <jvmti/> environments
 882     in specific contexts.
 883     Each environment has its own state (for example,
 884     <functionlink id="SetEventNotificationMode">desired events</functionlink>, 
 885     <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and 
 886     <functionlink id="AddCapabilities">capabilities</functionlink>). 
 887     An environment is released with 
 888     <functionlink id="DisposeEnvironment"></functionlink>. 
 889     Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
 890     across threads and are created dynamically.
 891   </intro>
 892 
 893   <intro id="functionReturn" label="Function Return Values">
 894     <jvmti/> functions always return an
 895     <internallink id="ErrorSection">error code</internallink> via the
 896     <datalink id="jvmtiError"/> function return value. 
 897     Some functions can return additional
 898     values through pointers provided by the calling function. 
 899     In some cases, <jvmti/> functions allocate memory that your program must
 900     explicitly deallocate. This is indicated in the individual <jvmti/>
 901     function descriptions.  Empty lists, arrays, sequences, etc are 
 902     returned as <code>NULL</code>.
 903     <p/>
 904     In the event that the <jvmti/> function encounters
 905     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
 906     of memory referenced by argument pointers is undefined, but no memory
 907     will have been allocated and no global references will have been allocated.
 908     If the error occurs because of invalid input, no action will have occurred.
 909   </intro>
 910 
 911 <intro id="refs" label="Managing JNI Object References">
 912     <jvmti/> functions identify objects with JNI references 
 913     (<datalink id="jobject"/> and <datalink id="jclass"/>)
 914     and their derivatives
 915     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
 916     References passed to 
 917     <jvmti/> functions can be either global or local, but they must be 
 918     strong references. All references returned by <jvmti/> functions are 
 919     local references--these local references are created 
 920     during the <jvmti/> call.
 921     Local references are a resource that must be managed (see the 
 922     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>).  
 923     When threads return from native code all local references
 924     are freed.  Note that some threads, including typical
 925     agent threads, will never return from native code.
 926     A thread is ensured the ability to create sixteen local 
 927     references without the need for any explicit management.
 928     For threads executing a limited number of <jvmti/> calls before
 929     returning from native code
 930     (for example, threads processing events), 
 931     it may be determined that no explicit management
 932     is needed.
 933     However, long running agent threads will need explicit
 934     local reference management--usually with the JNI functions
 935     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
 936     Conversely, to preserve references beyond the
 937     return from native code, they must be converted to global references.
 938     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> 
 939     as they are not <datalink id="jobject"/>s.
 940 </intro>
 941 
 942     <intro id="prereqState" label="Prerequisite State for Calling Functions">
 943       Unless the function explicitly states that the agent must bring
 944       a thread or the VM to a particular state (for example, suspended),
 945       the <jvmti/> implementation is responsible for bringing the VM to a
 946       safe and consistent state for performing the function.
 947     </intro>
 948 
 949     <intro id="functionsExceptions" label="Exceptions and Functions">
 950       <jvmti/> functions never throw exceptions; error conditions are 
 951       communicated via the 
 952       <internallink id="functionReturn">function return value</internallink>.
 953       Any existing exception state is preserved across a call to a 
 954       <jvmti/> function.
 955       See the
 956       <externallink 
 957         id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770"
 958              >Java Exceptions</externallink>
 959       section of the JNI specification for information on handling exceptions.
 960     </intro>
 961 
 962   <category id="memory" label="Memory Management">
 963     <intro>
 964       These functions provide for the allocation and deallocation of 
 965       memory used by <jvmti/> functionality and can be used to provide
 966       working memory for agents.
 967       Memory managed by <jvmti/> is not compatible with other memory
 968       allocation libraries and mechanisms.
 969     </intro>
 970 
 971     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
 972       <synopsis>Allocate</synopsis>
 973       <description>
 974         Allocate an area of memory through the <jvmti/> allocator. 
 975         The allocated
 976         memory should be freed with <functionlink id="Deallocate"></functionlink>.
 977       </description>
 978       <origin>jvmdi</origin>
 979       <capabilities>
 980       </capabilities>
 981       <parameters>
 982         <param id="size">
 983           <jlong/>
 984           <description>
 985             The number of bytes to allocate.
 986             <rationale>
 987               <code>jlong</code> is used for compatibility with JVMDI.
 988             </rationale>
 989           </description>
 990         </param>
 991         <param id="mem_ptr">
 992           <allocbuf incount="size"><uchar/></allocbuf>
 993           <description>
 994             On return, a pointer to the beginning of the allocated memory.
 995             If <code>size</code> is zero, <code>NULL</code> is returned.
 996           </description>
 997         </param>
 998       </parameters>
 999       <errors>
1000         <error id="JVMTI_ERROR_OUT_OF_MEMORY">
1001           Memory request cannot be honored.
1002         </error>
1003         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
1004           <paramlink id="size"></paramlink> is less than zero.
1005         </error>
1006       </errors>
1007     </function>
1008 
1009     <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
1010       <synopsis>Deallocate</synopsis>
1011       <description>
1012         Deallocate <code>mem</code>  using the <jvmti/> allocator. 
1013         This function should
1014         be used to deallocate any memory allocated and returned 
1015         by a <jvmti/> function
1016         (including memory allocated with <functionlink id="Allocate"></functionlink>).
1017         All allocated memory must be deallocated
1018         or the memory cannot be reclaimed.
1019       </description>
1020       <origin>jvmdi</origin>
1021       <capabilities>
1022       </capabilities>
1023       <parameters>
1024         <param id="mem">
1025           <outbuf>
1026             <uchar/>
1027             <nullok>the call is ignored</nullok>
1028           </outbuf>
1029           <description>
1030             A pointer to the beginning of the allocated memory.
1031             Please ignore "On return, the elements are set."
1032               <todo>keep it from generating "On return, the elements are set"</todo>
1033           </description>
1034         </param>
1035       </parameters>
1036       <errors>
1037       </errors>
1038     </function>
1039   </category>
1040 
1041   <category id="threadCategory" label="Thread">
1042     <intro>
1043     </intro>
1044 
1045     <function id="GetThreadState" num="17">
1046       <synopsis>Get Thread State</synopsis>
1047       <description>
1048         Get the state of a thread.  The state of the thread is represented by the
1049         answers to the hierarchical set of questions below:
1050           <ul type="circle">
1051             <li><i>Alive?</i>
1052               <ul>
1053                 <li>Not alive.
1054                   <ul type="circle">
1055                     <li><i>Why not alive?</i>
1056                       <ul>
1057                         <li>New.</li>
1058                         <li>Terminated (<datalink 
1059                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
1060                       </ul>
1061                     </li>
1062                   </ul>
1063                 </li>
1064                 <li>Alive (<datalink 
1065                     id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
1066                   <ul type="circle">
1067                     <li><i>Suspended?</i>
1068                       <ul>
1069                         <li>Suspended (<datalink 
1070                             id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
1071                         <li>Not suspended</li>
1072                       </ul>
1073                     </li>
1074                     <li><i>Interrupted?</i>
1075                       <ul>
1076                         <li>Interrupted (<datalink 
1077                             id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
1078                         <li>Not interrupted.</li>
1079                       </ul>
1080                     </li>
1081                     <li><i>In native?</i>
1082                       <ul>
1083                         <li>In native code (<datalink 
1084                             id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
1085                         <li>In Java programming language code</li>
1086                       </ul>
1087                     </li>
1088                     <li><i>What alive state?</i>
1089                       <ul>
1090                         <li>Runnable (<datalink 
1091                             id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
1092                         <li>Blocked (<datalink 
1093                             id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
1094                         <li>Waiting (<datalink 
1095                             id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
1096                           <ul type="circle">
1097                             <li><i>Timed wait?</i>
1098                               <ul>
1099                                 <li>Indefinite (<datalink 
1100                                     id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
1101                                 <li>Timed (<datalink 
1102                                     id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
1103                               </ul>
1104                             </li>
1105                             <li><i>Why waiting?</i>
1106                               <ul>
1107                                 <li>Object.wait (<datalink 
1108                                     id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
1109                                 <li>LockSupport.park (<datalink 
1110                                     id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
1111                                 <li>Sleeping (<datalink 
1112                                     id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
1113                               </ul>
1114                             </li>
1115                           </ul>
1116                         </li>
1117                       </ul>
1118                     </li>
1119                   </ul>
1120                 </li>
1121               </ul>
1122             </li>
1123           </ul>
1124         <p/>
1125         The answers are represented by the following bit vector. 
1126         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
1127           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
1128             Thread is alive. Zero if thread is new (not started) or terminated.
1129           </constant>
1130           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
1131             Thread has completed execution.
1132           </constant>
1133           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
1134             Thread is runnable.
1135           </constant>
1136           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
1137             Thread is waiting to enter a synchronization block/method or,
1138             after an <code>Object.wait()</code>, waiting to re-enter a 
1139             synchronization block/method.
1140           </constant>
1141           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
1142             Thread is waiting.
1143           </constant>
1144           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
1145             Thread is waiting without a timeout.
1146             For example, <code>Object.wait()</code>.
1147           </constant>
1148           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
1149             Thread is waiting with a maximum time to wait specified.
1150             For example, <code>Object.wait(long)</code>.
1151           </constant>
1152           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
1153             Thread is sleeping -- <code>Thread.sleep(long)</code>.
1154           </constant>
1155           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
1156             Thread is waiting on an object monitor -- <code>Object.wait</code>.
1157           </constant>
1158           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
1159             Thread is parked, for example: <code>LockSupport.park</code>,
1160             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
1161           </constant>
1162           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
1163             Thread suspended.
1164             <code>java.lang.Thread.suspend()</code>
1165             or a <jvmti/> suspend function 
1166             (such as <functionlink id="SuspendThread"></functionlink>) 
1167             has been called on the thread. If this bit
1168             is set, the other bits refer to the thread state before suspension.
1169           </constant>
1170           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
1171             Thread has been interrupted.
1172           </constant>
1173           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
1174             Thread is in native code--that is, a native method is running
1175             which has not called back into the VM or Java programming
1176             language code.
1177             <p/>
1178             This flag is not set when running VM compiled Java programming
1179             language code nor is it set when running VM code or
1180             VM support code. Native VM interface functions, such as JNI and
1181             <jvmti/> functions, may be implemented as VM code.
1182           </constant>
1183           <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
1184             Defined by VM vendor.
1185           </constant>
1186           <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
1187             Defined by VM vendor.
1188           </constant>
1189           <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
1190             Defined by VM vendor.
1191           </constant>
1192         </constants>
1193         The following definitions are used to convert <jvmti/> thread state
1194         to <code>java.lang.Thread.State</code> style states.
1195         <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
1196           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
1197                      num="JVMTI_THREAD_STATE_TERMINATED | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1198             Mask the state with this before comparison
1199           </constant>
1200           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
1201                      num="0">
1202             <code>java.lang.Thread.State.NEW</code>
1203           </constant>
1204           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
1205                      num="JVMTI_THREAD_STATE_TERMINATED">
1206             <code>java.lang.Thread.State.TERMINATED</code>
1207           </constant>
1208           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
1209                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
1210             <code>java.lang.Thread.State.RUNNABLE</code>
1211           </constant>
1212           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
1213                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
1214             <code>java.lang.Thread.State.BLOCKED</code>
1215           </constant>
1216           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
1217                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
1218             <code>java.lang.Thread.State.WAITING</code>
1219           </constant>
1220           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
1221                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1222             <code>java.lang.Thread.State.TIMED_WAITING</code>
1223           </constant>
1224         </constants>
1225         <b>Rules</b>
1226         <p/>
1227         There can be no more than one answer to a question, although there can be no
1228         answer (because the answer is unknown, does not apply, or none of the answers is 
1229         correct).  An answer is set only when the enclosing answers match.
1230         That is, no more than one of
1231           <ul type="circle">
1232               <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
1233               <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
1234               <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
1235           </ul>
1236         can be set (a <tm>J2SE</tm> compliant implementation will always set
1237         one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). 
1238         And if any of these are set, the enclosing answer 
1239         <code>JVMTI_THREAD_STATE_ALIVE</code> is set. 
1240         No more than one of
1241           <ul type="circle">
1242               <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
1243               <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
1244           </ul>
1245         can be set (a <tm>J2SE</tm> compliant implementation will always set
1246         one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). 
1247         And if either is set, the enclosing answers 
1248         <code>JVMTI_THREAD_STATE_ALIVE</code> and 
1249         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 
1250         No more than one of
1251           <ul type="circle">
1252               <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
1253               <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
1254               <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
1255           </ul>
1256         can be set. And if any of these is set, the enclosing answers 
1257         <code>JVMTI_THREAD_STATE_ALIVE</code> and 
1258         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 
1259         Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
1260         then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
1261         If a state <i>A</i> is implemented using the mechanism of 
1262         state <i>B</i> then it is state <i>A</i> which 
1263         is returned by this function.
1264         For example, if <code>Thread.sleep(long)</code>
1265         is implemented using <code>Object.wait(long)</code>
1266         then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
1267         which is returned.
1268         More than one of
1269           <ul type="circle">
1270               <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
1271               <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
1272               <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
1273           </ul>
1274         can be set, but if any is set,
1275         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1276         <p/>
1277         And finally,
1278         <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
1279         <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.  
1280         <p/>
1281         The thread state representation is designed for extension in future versions
1282         of the specification; thread state values should be used accordingly, that is
1283         they should not be used as ordinals.  
1284         Most queries can be made by testing a single bit, if use in a switch statement is desired,
1285         the state bits should be masked with the interesting bits.
1286         All bits not defined above are reserved for future use.  
1287         A VM, compliant to the current specification, must set reserved bits to zero.
1288         An agent should ignore reserved bits -- 
1289         they should not be assumed to be zero and thus should not be included in comparisons.
1290         <p/>
1291         <b>Examples</b>
1292         <p/>
1293         Note that the values below exclude reserved and vendor bits.
1294         <p/>
1295         The state of a thread blocked at a <code>synchronized</code>-statement would be:
1296         <example>
1297             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
1298         </example>
1299         The state of a thread which hasn't started yet would be:
1300         <example>
1301             0
1302         </example>
1303         The state of a thread at a <code>Object.wait(3000)</code> would be:
1304         <example>
1305             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + 
1306                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + 
1307                 JVMTI_THREAD_STATE_MONITOR_WAITING
1308         </example>
1309         The state of a thread suspended while runnable would be:
1310         <example>
1311             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
1312         </example>
1313         <p/>
1314         <b>Testing the State</b>
1315         <p/>
1316         In most cases, the thread state can be determined by testing the one bit corresponding
1317         to that question.  For example, the code to test if a thread is sleeping:
1318         <example>
1319         jint state;
1320         jvmtiError err;
1321 
1322         err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1323         if (err == JVMTI_ERROR_NONE) {
1324            if (state &amp; JVMTI_THREAD_STATE_SLEEPING) {  ...
1325         </example>
1326         <p/>
1327         For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
1328         <example>
1329            if (state &amp; JVMTI_THREAD_STATE_WAITING) {  ...
1330         </example>
1331         For some states, more than one bit will need to be tested as is the case
1332         when testing if a thread has not yet been started:
1333         <example>
1334            if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
1335         </example>
1336         To distinguish timed from untimed <code>Object.wait</code>:
1337         <example>
1338            if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {  
1339              if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
1340                printf("in Object.wait(long timeout)\n");
1341              } else {
1342                printf("in Object.wait()\n");
1343              }
1344            }
1345         </example>
1346         <p/>
1347         <b>Relationship to <code>java.lang.Thread.State</code></b>
1348         <p/>
1349         The thread state represented by <code>java.lang.Thread.State</code>
1350         returned from <code>java.lang.Thread.getState()</code> is a subset of the
1351         information returned from this function.  
1352         The corresponding <code>java.lang.Thread.State</code> can be determined
1353         by using the provided conversion masks.
1354         For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
1355         <example>
1356             err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1357             abortOnError(err);
1358             switch (state &amp; JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
1359             case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
1360               return "NEW";
1361             case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
1362               return "TERMINATED";
1363             case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
1364               return "RUNNABLE";
1365             case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
1366               return "BLOCKED";
1367             case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
1368               return "WAITING";
1369             case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
1370               return "TIMED_WAITING";
1371             }
1372         </example>
1373       </description>
1374       <origin>new</origin>
1375       <capabilities>
1376       </capabilities>
1377       <parameters>
1378         <param id="thread">
1379           <jthread null="current" started="maybe" impl="noconvert"/>
1380             <description>
1381               The thread to query. 
1382             </description>
1383         </param>
1384         <param id="thread_state_ptr">
1385           <outptr><jint/></outptr>
1386           <description>
1387             On return, points to state flags,
1388             as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
1389           </description>
1390         </param>
1391       </parameters>
1392       <errors>
1393       </errors>
1394     </function>
1395 
1396     <function id="GetCurrentThread" phase="start" num="18" since="1.1">
1397       <synopsis>Get Current Thread</synopsis>
1398       <description>
1399         Get the current thread.  
1400         The current thread is the Java programming language thread which has called the function.
1401         <p/>
1402         Note that most <jvmti/> functions that take a thread 
1403         as an argument will accept <code>NULL</code> to mean 
1404         the current thread.
1405       </description>
1406       <origin>new</origin>
1407       <capabilities>
1408       </capabilities>
1409       <parameters>
1410         <param id="thread_ptr">
1411           <outptr><jthread/></outptr>
1412           <description>
1413              On return, points to the current thread.
1414           </description>
1415         </param>
1416       </parameters>
1417       <errors>
1418       </errors>
1419     </function>
1420 
1421     <function id="GetAllThreads" num="4">
1422       <synopsis>Get All Threads</synopsis>
1423       <description>
1424         Get all live threads.
1425         The threads are Java programming language threads;
1426         that is, threads that are attached to the VM.
1427         A thread is live if <code>java.lang.Thread.isAlive()</code> 
1428         would return <code>true</code>, that is, the thread has
1429         been started and has not yet died.
1430         The universe of threads is determined by the context of the <jvmti/>
1431         environment, which typically is all threads attached to the VM.
1432         Note that this includes <jvmti/> agent threads 
1433         (see <functionlink id="RunAgentThread"/>).
1434       </description>
1435       <origin>jvmdi</origin>
1436       <capabilities>
1437       </capabilities>
1438       <parameters>
1439         <param id="threads_count_ptr">
1440           <outptr><jint/></outptr>
1441           <description>
1442             On return, points to the number of running threads.
1443           </description>
1444         </param>
1445         <param id="threads_ptr">
1446           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
1447             <description>
1448               On return, points to an array of references, one
1449               for each running thread.
1450             </description>
1451         </param>
1452       </parameters>
1453       <errors>
1454       </errors>
1455     </function>
1456 
1457     <function id="SuspendThread" num="5">
1458       <synopsis>Suspend Thread</synopsis>
1459       <description>
1460         Suspend the specified thread. If the calling thread is specified, 
1461         this function will not return until some other thread calls 
1462         <functionlink id="ResumeThread"></functionlink>.
1463         If the thread is currently suspended, this function
1464         does nothing and returns an error.
1465       </description>
1466       <origin>jvmdi</origin>
1467       <capabilities>
1468         <required id="can_suspend"></required>
1469       </capabilities>
1470       <parameters>
1471         <param id="thread">
1472           <jthread null="current"/>
1473             <description>
1474               The thread to suspend. 
1475             </description>
1476         </param>
1477       </parameters>
1478       <errors>
1479         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
1480           Thread already suspended.
1481         </error>
1482       </errors>
1483     </function>
1484 
1485     <elide>
1486     <function id="SuspendAllThreads" num="101">
1487       <synopsis>Suspend All Threads</synopsis>
1488       <description>
1489         <issue>
1490             There has been no explicit call for this function, and it will
1491             thus be removed if there is no interest.
1492         </issue>
1493         Suspend all live threads except:
1494         <ul>
1495           <li>already suspended threads</li>
1496           <li>those listed in <paramlink id="except_list"></paramlink></li>
1497           <li>certain system (non application) threads, as determined
1498             by the VM implementation</li>
1499         </ul>
1500         The threads are Java programming language threads;
1501         native threads which are not attached to the VM are not
1502         Java programming language threads.
1503         A thread is live if <code>java.lang.Thread.isAlive()</code> 
1504         would return <code>true</code>, that is, the thread has
1505         been started and has not yet died.
1506         The universe of threads is determined 
1507         by the context of the <jvmti/>
1508         environment, which, typically, is all threads attached to the VM,
1509         except critical VM internal threads and <jvmti/> agent threads 
1510         (see <functionlink id="RunAgentThread"/>).
1511         <p/>
1512         If the calling thread is specified, 
1513         all other threads are suspended first then the caller thread is suspended -
1514         this function will not return until some other thread calls 
1515         <functionlink id="ResumeThread"></functionlink>.
1516         <p/>
1517         The list of actually
1518         suspended threads is returned in 
1519         <paramlink id="suspended_list_ptr"></paramlink>.
1520         Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
1521         <functionlink id="ResumeThreadList"></functionlink>
1522         can be used to resume the suspended threads.
1523       </description>
1524       <origin>new</origin>
1525       <capabilities>
1526         <required id="can_suspend"></required>
1527       </capabilities>
1528       <parameters>
1529         <param id="except_count">
1530           <jint min="0"/>
1531           <description>
1532             The number of threads in the list of threads not to be suspended.
1533           </description>
1534         </param>
1535         <param id="except_list">
1536             <inbuf incount="except_count">
1537               <jthread/>
1538               <nullok>not an error if <code>except_count == 0</code></nullok>
1539             </inbuf>
1540             <description>
1541               The list of threads not to be suspended.
1542             </description>
1543         </param>
1544         <param id="suspended_count_ptr">
1545           <outptr><jint/></outptr>
1546           <description>
1547             On return, points to the number of threads suspended by this call.
1548           </description>
1549         </param>
1550         <param id="suspended_list_ptr">
1551           <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
1552             <description>
1553               On return, points to an array of references, one
1554               for each thread suspended.
1555             </description>
1556         </param>
1557       </parameters>
1558       <errors>
1559         <error id="JVMTI_ERROR_INVALID_THREAD">
1560           A thread in <paramlink id="except_list"></paramlink> was invalid.
1561         </error>
1562         <error id="JVMTI_ERROR_NULL_POINTER">
1563           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1564           and <paramlink id="except_count"></paramlink> was non-zero.
1565         </error>
1566       </errors>
1567     </function>
1568     </elide>
1569 
1570     <function id="SuspendThreadList" num="92">
1571       <synopsis>Suspend Thread List</synopsis>
1572       <description>
1573         Suspend the <paramlink id="request_count"></paramlink> 
1574         threads specified in the 
1575         <paramlink id="request_list"></paramlink> array. 
1576         Threads may be resumed with
1577         <functionlink id="ResumeThreadList"></functionlink> or
1578         <functionlink id="ResumeThread"></functionlink>.
1579         If the calling thread is specified in the 
1580         <paramlink id="request_list"></paramlink> array, this function will
1581         not return until some other thread resumes it.
1582         Errors encountered in the suspension of a thread
1583         are returned in the <paramlink id="results"></paramlink>
1584         array, <b>not</b> in the return value of this function.
1585         Threads that are currently suspended do not change state.
1586       </description>
1587       <origin>jvmdi</origin>
1588       <capabilities>
1589         <required id="can_suspend"></required>
1590       </capabilities>
1591       <parameters>
1592         <param id="request_count">
1593           <jint min="0"/>
1594           <description>
1595             The number of threads to suspend.
1596           </description>
1597         </param>
1598         <param id="request_list">
1599           <inbuf incount="request_count"><jthread/></inbuf>
1600             <description>
1601               The list of threads to suspend.
1602             </description>
1603         </param>
1604         <param id="results">
1605           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1606           <description>
1607             An agent supplied array of 
1608             <paramlink id="request_count"></paramlink> elements.
1609             On return, filled with the error code for
1610             the suspend of the corresponding thread.
1611             The error code will be 
1612             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1613             if the thread was suspended by this call.
1614             Possible error codes are those specified
1615             for <functionlink id="SuspendThread"></functionlink>.
1616           </description>
1617         </param>
1618       </parameters>
1619       <errors>
1620       </errors>
1621     </function>
1622 
1623     <function id="ResumeThread" num="6">
1624       <synopsis>Resume Thread</synopsis>
1625       <description>
1626         Resume a suspended thread. 
1627         Any threads currently suspended through
1628         a <jvmti/> suspend function (eg.
1629         <functionlink id="SuspendThread"></functionlink>) 
1630         or <code>java.lang.Thread.suspend()</code>
1631         will resume execution;  
1632         all other threads are unaffected.
1633       </description>
1634       <origin>jvmdi</origin>
1635       <capabilities>
1636         <required id="can_suspend"></required>
1637       </capabilities>
1638       <parameters>
1639         <param id="thread">
1640           <jthread/>
1641             <description>
1642               The thread to resume.
1643             </description>
1644         </param>
1645       </parameters>
1646       <errors>
1647         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
1648           Thread was not suspended.
1649         </error>
1650         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
1651           The state of the thread has been modified, and is now inconsistent. 
1652         </error>
1653       </errors>
1654     </function>
1655 
1656     <function id="ResumeThreadList" num="93">
1657       <synopsis>Resume Thread List</synopsis>
1658       <description>
1659         Resume the <paramlink id="request_count"></paramlink> 
1660         threads specified in the 
1661         <paramlink id="request_list"></paramlink> array. 
1662         Any thread suspended through
1663         a <jvmti/> suspend function (eg.
1664         <functionlink id="SuspendThreadList"></functionlink>) 
1665         or <code>java.lang.Thread.suspend()</code>
1666         will resume execution.
1667       </description>
1668       <origin>jvmdi</origin>
1669       <capabilities>
1670         <required id="can_suspend"></required>
1671       </capabilities>
1672       <parameters>
1673         <param id="request_count">
1674           <jint min="0"/>
1675           <description>
1676             The number of threads to resume.
1677           </description>
1678         </param>
1679         <param id="request_list">
1680           <inbuf incount="request_count"><jthread/></inbuf>
1681             <description>
1682               The threads to resume.
1683             </description>
1684         </param>
1685         <param id="results">
1686           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1687           <description>
1688             An agent supplied array of 
1689             <paramlink id="request_count"></paramlink> elements.
1690             On return, filled with the error code for
1691             the resume of the corresponding thread.
1692             The error code will be 
1693             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1694             if the thread was suspended by this call.
1695             Possible error codes are those specified
1696             for <functionlink id="ResumeThread"></functionlink>.
1697           </description>
1698         </param>
1699       </parameters>
1700       <errors>
1701       </errors>
1702     </function>
1703 
1704     <function id="StopThread" num="7">
1705       <synopsis>Stop Thread</synopsis>
1706       <description>
1707         Send the specified asynchronous exception to the specified thread 
1708         (similar to <code>java.lang.Thread.stop</code>).
1709         Normally, this function is used to kill the specified thread with an 
1710         instance of the exception <code>ThreadDeath</code>.
1711       </description>
1712       <origin>jvmdi</origin>
1713       <capabilities>
1714         <required id="can_signal_thread"></required>
1715       </capabilities>
1716       <parameters>
1717         <param id="thread">
1718           <jthread/>
1719             <description>
1720               The thread to stop.
1721             </description>
1722         </param>
1723         <param id="exception">
1724           <jobject/>
1725             <description>
1726               The asynchronous exception object.
1727             </description>
1728         </param>
1729       </parameters>
1730       <errors>
1731       </errors>
1732     </function>
1733 
1734     <function id="InterruptThread" num="8">
1735       <synopsis>Interrupt Thread</synopsis>
1736       <description>
1737         Interrupt the specified thread
1738         (similar to <code>java.lang.Thread.interrupt</code>).
1739       </description>
1740       <origin>jvmdi</origin>
1741       <capabilities>
1742         <required id="can_signal_thread"></required>
1743       </capabilities>
1744       <parameters>
1745         <param id="thread">
1746           <jthread impl="noconvert"/>
1747             <description>
1748               The thread to interrupt.
1749             </description>
1750         </param>
1751       </parameters>
1752       <errors>
1753       </errors>
1754     </function>
1755 
1756     <function id="GetThreadInfo" num="9">
1757       <synopsis>Get Thread Info</synopsis>
1758       <typedef id="jvmtiThreadInfo" label="Thread information structure">
1759         <field id="name">
1760           <allocfieldbuf><char/></allocfieldbuf>
1761           <description>
1762             The thread name, encoded as a
1763             <internallink id="mUTF">modified UTF-8</internallink> string.
1764           </description>
1765         </field>
1766         <field id="priority">
1767           <jint/>
1768           <description>
1769             The thread priority.  See the thread priority constants:
1770             <datalink id="jvmtiThreadPriority"></datalink>.
1771           </description>
1772         </field>
1773         <field id="is_daemon">
1774           <jboolean/>
1775           <description>
1776             Is this a daemon thread?
1777           </description>
1778         </field>
1779         <field id="thread_group">
1780           <jthreadGroup/>
1781           <description>
1782             The thread group to which this thread belongs.
1783             <code>NULL</code> if the thread has died.
1784           </description>
1785         </field>
1786         <field id="context_class_loader">
1787           <jobject/>
1788             <description>
1789               The context class loader associated with this thread.
1790             </description>
1791         </field>
1792       </typedef>
1793       <description>
1794         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure 
1795         are filled in with details of the specified thread.
1796       </description>
1797       <origin>jvmdi</origin>
1798       <capabilities>
1799       </capabilities>
1800       <parameters>
1801         <param id="thread">
1802           <jthread null="current" impl="noconvert" started="maybe"/>
1803             <description>
1804               The thread to query.
1805             </description>
1806         </param>
1807         <param id="info_ptr">
1808           <outptr><struct>jvmtiThreadInfo</struct></outptr>
1809           <description>
1810             On return, filled with information describing the specified thread.
1811             <p/>
1812             For JDK 1.1 implementations that don't
1813             recognize context class loaders, 
1814             the <code>context_class_loader</code> field will be NULL.
1815           </description>
1816         </param>
1817       </parameters>
1818       <errors>
1819       </errors>
1820     </function>
1821 
1822     <function id="GetOwnedMonitorInfo" num="10">
1823       <synopsis>Get Owned Monitor Info</synopsis>
1824       <description>
1825         Get information about the monitors owned by the 
1826         specified thread. 
1827       </description>
1828       <origin>jvmdiClone</origin>
1829       <capabilities>
1830         <required id="can_get_owned_monitor_info"></required>
1831       </capabilities>
1832       <parameters>
1833         <param id="thread">
1834           <jthread null="current"/>
1835             <description>
1836               The thread to query.
1837             </description>
1838         </param>
1839         <param id="owned_monitor_count_ptr">
1840           <outptr><jint/></outptr>
1841           <description>
1842             The number of monitors returned.
1843           </description>
1844         </param>
1845         <param id="owned_monitors_ptr">
1846           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
1847             <description>
1848               The array of owned monitors.
1849             </description>
1850         </param>
1851       </parameters>
1852       <errors>
1853       </errors>
1854     </function>
1855 
1856     <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
1857       <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
1858       <typedef id="jvmtiMonitorStackDepthInfo" 
1859                label="Monitor stack depth information structure">
1860         <field id="monitor">
1861           <jobject/>
1862             <description>
1863               The owned monitor.
1864             </description>
1865         </field>
1866         <field id="stack_depth">
1867           <jint/>
1868           <description>
1869             The stack depth.  Corresponds to the stack depth used in the 
1870             <internallink id="stack">Stack Frame functions</internallink>.
1871             That is, zero is the current frame, one is the frame which
1872             called the current frame. And it is negative one if the 
1873             implementation cannot determine the stack depth (e.g., for 
1874             monitors acquired by JNI <code>MonitorEnter</code>).
1875           </description>
1876         </field>
1877       </typedef>
1878       <description>
1879         Get information about the monitors owned by the 
1880         specified thread and the depth of the stack frame which locked them. 
1881       </description>
1882       <origin>new</origin>
1883       <capabilities>
1884         <required id="can_get_owned_monitor_stack_depth_info"></required>
1885       </capabilities>
1886       <parameters>
1887         <param id="thread">
1888           <jthread null="current"/>
1889             <description>
1890               The thread to query.
1891             </description>
1892         </param>
1893         <param id="monitor_info_count_ptr">
1894           <outptr><jint/></outptr>
1895           <description>
1896             The number of monitors returned.
1897           </description>
1898         </param>
1899         <param id="monitor_info_ptr">
1900           <allocbuf outcount="monitor_info_count_ptr">
1901             <struct>jvmtiMonitorStackDepthInfo</struct>
1902           </allocbuf>
1903           <description>
1904             The array of owned monitor depth information.
1905           </description>
1906         </param>
1907       </parameters>
1908       <errors>
1909       </errors>
1910     </function>
1911 
1912     <function id="GetCurrentContendedMonitor" num="11">
1913       <synopsis>Get Current Contended Monitor</synopsis>
1914       <description>
1915         Get the object, if any, whose monitor the specified thread is waiting to 
1916         enter or waiting to regain through <code>java.lang.Object.wait</code>.
1917       </description>
1918       <origin>jvmdi</origin>
1919       <capabilities>
1920         <required id="can_get_current_contended_monitor"></required>
1921       </capabilities>
1922       <parameters>
1923         <param id="thread">
1924           <jthread null="current"/>
1925             <description>
1926               The thread to query.
1927             </description>
1928         </param>
1929         <param id="monitor_ptr">
1930           <outptr><jobject/></outptr>
1931             <description>
1932               On return, filled with the current contended monitor, or
1933               NULL if there is none.
1934             </description>
1935         </param>
1936       </parameters>
1937       <errors>
1938       </errors>
1939     </function>
1940 
1941     <callback id="jvmtiStartFunction">
1942       <void/>
1943       <synopsis>Agent Start Function</synopsis>
1944       <description>
1945         Agent supplied callback function.
1946         This function is the entry point for an agent thread
1947         started with
1948         <functionlink id="RunAgentThread"></functionlink>.
1949       </description>
1950       <parameters>
1951           <param id="jvmti_env">
1952             <outptr>
1953               <struct>jvmtiEnv</struct>
1954             </outptr>
1955             <description>
1956               The <jvmti/> environment.
1957             </description>
1958           </param>
1959           <param id="jni_env">
1960             <outptr>
1961               <struct>JNIEnv</struct>
1962             </outptr>
1963             <description>
1964               The JNI environment.
1965             </description>
1966           </param>
1967           <param id="arg">
1968             <outptr>
1969               <void/>
1970             </outptr>
1971               <description>
1972                 The <code>arg</code> parameter passed to 
1973                 <functionlink id="RunAgentThread"></functionlink>.
1974               </description>
1975           </param>
1976       </parameters>
1977     </callback>
1978 
1979     <function id="RunAgentThread" num="12">
1980       <synopsis>Run Agent Thread</synopsis>
1981       <description>
1982         Starts the execution of an agent thread. with the specified native function.
1983         The parameter <paramlink id="arg"></paramlink> is forwarded on to the
1984         <functionlink id="jvmtiStartFunction">start function</functionlink>
1985         (specified with <paramlink id="proc"></paramlink>) as its single argument.
1986         This function allows the creation of agent threads 
1987         for handling communication with another process or for handling events 
1988         without the need to load a special subclass of <code>java.lang.Thread</code> or 
1989         implementer of <code>java.lang.Runnable</code>. 
1990         Instead, the created thread can run entirely in native code.
1991         However, the created thread does require a newly created instance
1992         of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to 
1993         which it will be associated.
1994         The thread object can be created with JNI calls.
1995         <p/>
1996         The following common thread priorities are provided for your convenience:
1997         <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
1998           <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
1999             Minimum possible thread priority
2000           </constant>
2001           <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
2002             Normal thread priority
2003           </constant>
2004           <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
2005             Maximum possible thread priority
2006           </constant>
2007         </constants>
2008         <p/>
2009         The new thread is started as a daemon thread with the specified
2010         <paramlink id="priority"></paramlink>.
2011         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2012         <p/>
2013         Since the thread has been started, the thread will be live when this function
2014         returns, unless the thread has died immediately.
2015         <p/>
2016         The thread group of the thread is ignored -- specifically, the thread is not
2017         added to the thread group and the thread is not seen on queries of the thread
2018         group at either the Java programming language or <jvmti/> levels.
2019         <p/>
2020         The thread is not visible to Java programming language queries but is 
2021         included in <jvmti/> queries (for example, 
2022         <functionlink id="GetAllThreads"/> and
2023         <functionlink id="GetAllStackTraces"/>).
2024         <p/>
2025         Upon execution of <code>proc</code>, the new thread will be attached to the
2026         VM--see the JNI documentation on 
2027         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060"
2028                       >Attaching to the VM</externallink>.
2029       </description>
2030       <origin>jvmdiClone</origin>
2031       <capabilities>
2032       </capabilities>
2033       <parameters>
2034         <param id="thread">
2035           <jthread impl="noconvert" started="no"/>
2036             <description>
2037               The thread to run.
2038             </description>
2039         </param>
2040         <param id="proc">
2041           <ptrtype>
2042             <struct>jvmtiStartFunction</struct>
2043           </ptrtype>
2044           <description>
2045             The start function.
2046           </description>
2047         </param>
2048         <param id="arg">
2049           <inbuf>
2050             <void/>
2051             <nullok><code>NULL</code> is passed to the start function</nullok>
2052           </inbuf>
2053           <description>
2054             The argument to the start function.
2055           </description>
2056         </param>
2057         <param id="priority">
2058           <jint/>
2059           <description>
2060             The priority of the started thread. Any thread
2061             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
2062             those in <datalink id="jvmtiThreadPriority"></datalink>.
2063           </description>
2064         </param>
2065       </parameters>
2066       <errors>
2067         <error id="JVMTI_ERROR_INVALID_PRIORITY"> 
2068             <paramlink id="priority"/> is less than 
2069             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
2070               or greater than
2071             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
2072         </error>
2073       </errors>
2074     </function>
2075 
2076     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
2077       <synopsis>Set Thread Local Storage</synopsis>
2078       <description>
2079         The VM stores a pointer value associated with each environment-thread
2080         pair. This pointer value is called <i>thread-local storage</i>.
2081         This value is <code>NULL</code> unless set with this function.
2082         Agents can allocate memory in which they store thread specific
2083         information. By setting thread-local storage it can then be
2084         accessed with 
2085         <functionlink id="GetThreadLocalStorage"></functionlink>.
2086         <p/>
2087         This function is called by the agent to set the value of the <jvmti/>
2088         thread-local storage. <jvmti/> supplies to the agent a pointer-size
2089         thread-local storage that can be used to record per-thread
2090         information.
2091       </description>
2092       <origin>jvmpi</origin>
2093       <capabilities>
2094       </capabilities>
2095       <parameters>
2096         <param id="thread">
2097           <jthread null="current"/>
2098             <description>
2099               Store to this thread.
2100             </description>
2101         </param>
2102         <param id="data">
2103           <inbuf> 
2104             <void/> 
2105             <nullok>value is set to <code>NULL</code></nullok> 
2106           </inbuf> 
2107           <description>
2108             The value to be entered into the thread-local storage.
2109           </description>
2110         </param>
2111       </parameters>
2112       <errors>
2113       </errors>
2114     </function>
2115 
2116     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
2117       <synopsis>Get Thread Local Storage</synopsis>
2118       <description>
2119         Called by the agent to get the value of the <jvmti/> thread-local
2120         storage. 
2121       </description>
2122       <origin>jvmpi</origin>
2123       <capabilities>
2124       </capabilities>
2125       <parameters>
2126         <param id="thread">
2127           <jthread null="current" impl="noconvert"/>
2128             <description>
2129               Retrieve from this thread.
2130             </description>
2131         </param>
2132         <param id="data_ptr">
2133           <agentbuf><void/></agentbuf>
2134           <description>
2135             Pointer through which the value of the thread local 
2136             storage is returned.
2137             If thread-local storage has not been set with
2138             <functionlink id="SetThreadLocalStorage"></functionlink> the returned 
2139             pointer is <code>NULL</code>.
2140           </description>
2141         </param>
2142       </parameters>
2143       <errors>
2144       </errors>
2145     </function>
2146 
2147   </category>
2148 
2149   <category id="thread_groups" label="Thread Group">
2150     <intro>
2151     </intro>
2152 
2153     <function id="GetTopThreadGroups" num="13">
2154       <synopsis>Get Top Thread Groups</synopsis>
2155       <description>
2156         Return all top-level (parentless) thread groups in the VM.
2157       </description>
2158       <origin>jvmdi</origin>
2159       <capabilities>
2160       </capabilities>
2161       <parameters>
2162         <param id="group_count_ptr">
2163           <outptr><jint/></outptr>
2164           <description>
2165             On return, points to the number of top-level thread groups.
2166           </description>
2167         </param>
2168         <param id="groups_ptr">
2169           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2170             <description>
2171               On return, refers to a pointer to the top-level thread group array.
2172             </description>
2173         </param>
2174       </parameters>
2175       <errors>
2176       </errors>
2177     </function>
2178 
2179     <function id="GetThreadGroupInfo" num="14">
2180       <synopsis>Get Thread Group Info</synopsis>
2181       <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
2182         <field id="parent">
2183           <jthreadGroup/>
2184           <description>
2185             The parent thread group.
2186           </description>
2187         </field>
2188         <field id="name">
2189           <allocfieldbuf><char/></allocfieldbuf>
2190           <description>
2191             The thread group's name, encoded as a
2192             <internallink id="mUTF">modified UTF-8</internallink> string.
2193           </description>
2194         </field>
2195         <field id="max_priority">
2196           <jint/>
2197           <description>
2198             The maximum priority for this thread group.
2199           </description>
2200         </field>
2201         <field id="is_daemon">
2202           <jboolean/>
2203           <description>
2204             Is this a daemon thread group?
2205           </description>
2206         </field>
2207       </typedef>
2208       <description>
2209         Get information about the thread group. The fields of the 
2210         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure 
2211         are filled in with details of the specified thread group.
2212       </description>
2213       <origin>jvmdi</origin>
2214       <capabilities>
2215       </capabilities>
2216       <parameters>
2217         <param id="group">
2218           <jthreadGroup/>
2219           <description>
2220             The thread group to query.
2221           </description>
2222         </param>
2223         <param id="info_ptr">
2224           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
2225           <description>
2226             On return, filled with information describing the specified
2227             thread group. 
2228           </description>
2229         </param>
2230       </parameters>
2231       <errors>
2232       </errors>
2233     </function>
2234 
2235     <function id="GetThreadGroupChildren" num="15">
2236       <synopsis>Get Thread Group Children</synopsis>
2237       <description>
2238         Get the live threads and active subgroups in this thread group.
2239       </description>
2240       <origin>jvmdi</origin>
2241       <capabilities>
2242       </capabilities>
2243       <parameters>
2244         <param id="group">
2245           <jthreadGroup/>
2246           <description>
2247             The group to query.
2248           </description>
2249         </param>
2250         <param id="thread_count_ptr">
2251           <outptr><jint/></outptr>
2252           <description>
2253             On return, points to the number of live threads in this thread group.
2254           </description>
2255         </param>
2256         <param id="threads_ptr">
2257           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
2258             <description>
2259               On return, points to an array of the live threads in this thread group.
2260             </description>
2261         </param>
2262         <param id="group_count_ptr">
2263           <outptr><jint/></outptr>
2264           <description>
2265             On return, points to the number of active child thread groups
2266           </description>
2267         </param>
2268         <param id="groups_ptr">
2269           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2270             <description>
2271               On return, points to an array of the active child thread groups.
2272             </description>
2273         </param>
2274       </parameters>
2275       <errors>
2276       </errors>
2277     </function>
2278   </category>
2279 
2280   <category id="stack" label="Stack Frame">
2281     <intro>
2282         These functions provide information about the stack of a thread.
2283         Stack frames are referenced by depth.
2284         The frame at depth zero is the current frame.
2285         <p/>
2286         Stack frames are as described in
2287         <vmspec chapter="3.6"/>,
2288         That is, they correspond to method 
2289         invocations (including native methods) but do not correspond to platform native or 
2290         VM internal frames.
2291         <p/>
2292         A <jvmti/> implementation may use method invocations to launch a thread and
2293         the corresponding frames may be included in the stack as presented by these functions --
2294         that is, there may be frames shown
2295         deeper than <code>main()</code> and <code>run()</code>.
2296         However this presentation must be consistent across all <jvmti/> functionality which 
2297         uses stack frames or stack depth.
2298     </intro>
2299 
2300       <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
2301         <description>
2302           Information about a stack frame is returned in this structure.
2303         </description>
2304         <field id="method">
2305           <jmethodID/>
2306             <description>
2307               The method executing in this frame.
2308             </description>
2309         </field>
2310         <field id="location">
2311           <jlocation/>
2312           <description>
2313             The index of the instruction executing in this frame.
2314             <code>-1</code> if the frame is executing a native method.
2315           </description>
2316         </field>
2317       </typedef>
2318 
2319       <typedef id="jvmtiStackInfo" label="Stack information structure">
2320         <description>
2321           Information about a set of stack frames is returned in this structure.
2322         </description>
2323         <field id="thread">
2324           <jthread/>
2325           <description>
2326             On return, the thread traced.
2327           </description>
2328         </field>
2329         <field id="state">
2330           <jint/>
2331           <description>
2332             On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
2333           </description>
2334         </field>
2335         <field id="frame_buffer">
2336           <outbuf incount="max_frame_count">
2337             <struct>jvmtiFrameInfo</struct>
2338           </outbuf>
2339             <description>
2340               On return, this agent allocated buffer is filled 
2341               with stack frame information.  
2342             </description>
2343         </field>
2344         <field id="frame_count">
2345           <jint/>
2346           <description>
2347             On return, the number of records filled into 
2348             <code>frame_buffer</code>.
2349             This will be 
2350             min(<code>max_frame_count</code>, <i>stackDepth</i>).
2351           </description>
2352         </field>
2353       </typedef>
2354 
2355     <function id="GetStackTrace" num="104">
2356       <synopsis>Get Stack Trace</synopsis>
2357       <description>
2358         Get information about the stack of a thread.
2359         If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
2360         the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, 
2361         otherwise the entire stack is returned.
2362         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2363         <p/>
2364         The following example causes up to five of the topmost frames
2365         to be returned and (if there are any frames) the currently
2366         executing method name to be printed.
2367         <example>
2368 jvmtiFrameInfo frames[5];
2369 jint count;
2370 jvmtiError err;
2371 
2372 err = (*jvmti)-&gt;GetStackTrace(jvmti, aThread, 0, 5, 
2373                                frames, &amp;count);
2374 if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
2375    char *methodName;
2376    err = (*jvmti)-&gt;GetMethodName(jvmti, frames[0].method, 
2377                        &amp;methodName, NULL, NULL);
2378    if (err == JVMTI_ERROR_NONE) {
2379       printf("Executing method: %s", methodName);
2380    }
2381 }
2382         </example>
2383         <todo> 
2384           check example code.
2385         </todo>
2386         <p/>
2387         The <paramlink id="thread"></paramlink> need not be suspended
2388         to call this function.  
2389         <p/>
2390         The <functionlink id="GetLineNumberTable"></functionlink>
2391         function can be used to map locations to line numbers. Note that
2392         this mapping can be done lazily.
2393       </description>
2394       <origin>jvmpi</origin>
2395       <capabilities>
2396       </capabilities>
2397       <parameters>
2398         <param id="thread">
2399           <jthread null="current"/>
2400             <description>
2401               Fetch the stack trace of this thread.
2402             </description>
2403         </param>
2404         <param id="start_depth">
2405           <jint/>
2406           <description>
2407             Begin retrieving frames at this depth.  
2408             If non-negative, count from the current frame, 
2409             the first frame retrieved is at depth <code>start_depth</code>.  
2410             For example, if zero, start from the current frame; if one, start from the
2411             caller of the current frame; if two, start from the caller of the
2412             caller of the current frame; and so on.
2413             If negative, count from below the oldest frame,
2414             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,  
2415             where <i>stackDepth</i> is the count of frames on the stack.  
2416             For example, if negative one, only the oldest frame is retrieved;
2417             if negative two, start from the frame called by the oldest frame.
2418           </description>
2419         </param>
2420         <param id="max_frame_count">
2421           <jint min="0"/>
2422           <description>
2423             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2424           </description>
2425         </param>
2426         <param id="frame_buffer">
2427           <outbuf incount="max_frame_count" outcount="count_ptr">
2428             <struct>jvmtiFrameInfo</struct>
2429           </outbuf>
2430             <description>
2431               On return, this agent allocated buffer is filled 
2432               with stack frame information.  
2433             </description>
2434         </param>
2435         <param id="count_ptr">
2436           <outptr><jint/></outptr>
2437           <description>
2438             On return, points to the number of records filled in.
2439             For non-negative <code>start_depth</code>, this will be 
2440             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
2441             For negative <code>start_depth</code>, this will be 
2442             min(<code>max_frame_count</code>, <code>-start_depth</code>).
2443           </description>
2444         </param>
2445       </parameters>
2446       <errors>
2447         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
2448           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
2449           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
2450         </error>
2451       </errors>
2452     </function>
2453 
2454 
2455     <function id="GetAllStackTraces" num="100">
2456       <synopsis>Get All Stack Traces</synopsis>
2457       <description>
2458         Get information about the stacks of all live threads
2459         (including <internallink id="RunAgentThread">agent threads</internallink>).
2460         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2461         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 
2462         otherwise the entire stack is returned.
2463         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2464         <p/>
2465         All stacks are collected simultaneously, that is, no changes will occur to the 
2466         thread state or stacks between the sampling of one thread and the next.
2467         The threads need not be suspended.
2468         
2469         <example>
2470 jvmtiStackInfo *stack_info;
2471 jint thread_count;
2472 int ti;
2473 jvmtiError err;
2474 
2475 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count); 
2476 if (err != JVMTI_ERROR_NONE) {
2477    ...   
2478 }
2479 for (ti = 0; ti &lt; thread_count; ++ti) {
2480    jvmtiStackInfo *infop = &amp;stack_info[ti];
2481    jthread thread = infop-&gt;thread;
2482    jint state = infop-&gt;state;
2483    jvmtiFrameInfo *frames = infop-&gt;frame_buffer;
2484    int fi;
2485 
2486    myThreadAndStatePrinter(thread, state);
2487    for (fi = 0; fi &lt; infop-&gt;frame_count; fi++) {
2488       myFramePrinter(frames[fi].method, frames[fi].location);
2489    }
2490 }
2491 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
2492 err = (*jvmti)-&gt;Deallocate(jvmti, stack_info); 
2493         </example>
2494         <todo> 
2495           check example code.
2496         </todo>
2497 
2498       </description>
2499       <origin>new</origin>
2500       <capabilities>
2501       </capabilities>
2502       <parameters>
2503         <param id="max_frame_count">
2504           <jint min="0"/>
2505           <description>
2506             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2507           </description>
2508         </param>
2509         <param id="stack_info_ptr">
2510           <allocbuf>
2511             <struct>jvmtiStackInfo</struct>
2512           </allocbuf>
2513             <description>
2514               On return, this buffer is filled 
2515               with stack information for each thread.  
2516               The number of <datalink id="jvmtiStackInfo"/> records is determined 
2517               by <paramlink id="thread_count_ptr"/>.
2518               <p/>
2519               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 
2520               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2521               These buffers must not be separately deallocated.
2522             </description>
2523         </param>
2524         <param id="thread_count_ptr">
2525           <outptr><jint/></outptr>
2526           <description>
2527             The number of threads traced.
2528           </description>
2529         </param>
2530       </parameters>
2531       <errors>
2532       </errors>
2533     </function>
2534 
2535     <function id="GetThreadListStackTraces" num="101">
2536       <synopsis>Get Thread List Stack Traces</synopsis>
2537       <description>
2538         Get information about the stacks of the supplied threads.
2539         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2540         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 
2541         otherwise the entire stack is returned.
2542         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2543         <p/>
2544         All stacks are collected simultaneously, that is, no changes will occur to the 
2545         thread state or stacks between the sampling one thread and the next.
2546         The threads need not be suspended.
2547         <p/>
2548         If a thread has not yet started or terminates before the stack information is collected,
2549         a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
2550         will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
2551         <p/>
2552         See the example for the similar function
2553         <functionlink id="GetAllStackTraces"/>.
2554       </description>
2555       <origin>new</origin>
2556       <capabilities>
2557       </capabilities>
2558       <parameters>
2559         <param id="thread_count">
2560           <jint min="0"/>
2561           <description>
2562             The number of threads to trace.
2563           </description>
2564         </param>
2565         <param id="thread_list">
2566           <inbuf incount="thread_count"><jthread/></inbuf>
2567             <description>
2568               The list of threads to trace.
2569             </description>
2570         </param>
2571         <param id="max_frame_count">
2572           <jint min="0"/>
2573           <description>
2574             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2575           </description>
2576         </param>
2577         <param id="stack_info_ptr">
2578           <allocbuf outcount="thread_count">
2579             <struct>jvmtiStackInfo</struct>
2580           </allocbuf>
2581             <description>
2582               On return, this buffer is filled 
2583               with stack information for each thread.  
2584               The number of <datalink id="jvmtiStackInfo"/> records is determined 
2585               by <paramlink id="thread_count"/>.
2586               <p/>
2587               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 
2588               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2589               These buffers must not be separately deallocated.
2590             </description>
2591         </param>
2592       </parameters>
2593       <errors>
2594         <error id="JVMTI_ERROR_INVALID_THREAD">
2595           An element in <paramlink id="thread_list"/> is not a thread object.
2596         </error>
2597       </errors>
2598     </function>
2599 
2600     <elide>
2601     <function id="AsyncGetStackTrace" num="1000">
2602       <synopsis>Get Stack Trace--Asynchronous</synopsis>
2603       <description>
2604         Get information about the entire stack of a thread (or a sub-section of it).
2605         This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
2606         and is reentrant and safe to call
2607         from asynchronous signal handlers.
2608         The stack trace is returned only for the calling thread.
2609         <p/>
2610         The <functionlink id="GetLineNumberTable"></functionlink>
2611         function can be used to map locations to line numbers. Note that
2612         this mapping can be done lazily.
2613       </description>
2614       <origin>jvmpi</origin>
2615       <capabilities>
2616         <required id="can_get_async_stack_trace"></required>
2617         <capability id="can_show_JVM_spec_async_frames">
2618           If <code>false</code>, 
2619           <paramlink id="use_java_stack"></paramlink> 
2620           must be <code>false</code>.
2621         </capability>
2622       </capabilities>
2623       <parameters>
2624         <param id="use_java_stack">
2625           <jboolean/>
2626           <description>
2627             Return the stack showing <vmspec/>
2628             model of the stack; 
2629             otherwise, show the internal representation of the stack with
2630             inlined and optimized methods missing.  If the virtual machine
2631             is using the <i>Java Virtual Machine Specification</i> stack model
2632             internally, this flag is ignored.
2633           </description>
2634         </param>
2635         <param id="max_count">
2636           <jint min="0"/>
2637           <description>
2638             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2639             Retrieve this many unless the stack depth is less than <code>max_count</code>.
2640           </description>
2641         </param>
2642         <param id="frame_buffer">
2643           <outbuf incount="max_count" outcount="count_ptr">
2644             <struct>jvmtiFrameInfo</struct>
2645             <nullok>this information is not returned</nullok>
2646           </outbuf>
2647             <description>
2648               The agent passes in a buffer
2649               large enough to hold <code>max_count</code> records of 
2650               <datalink id="jvmtiFrameInfo"></datalink>.  This buffer must be
2651               pre-allocated by the agent.  
2652             </description>
2653         </param>
2654         <param id="count_ptr">
2655           <outptr><jint/></outptr>
2656           <description>
2657             On return, points to the number of records filled in..
2658           </description>
2659         </param>
2660       </parameters>
2661       <errors>
2662         <error id="JVMTI_ERROR_UNATTACHED_THREAD">
2663           The thread being used to call this function is not attached
2664           to the virtual machine.  Calls must be made from attached threads.
2665         </error>
2666       </errors>
2667     </function>
2668     </elide>
2669 
2670     <function id="GetFrameCount" num="16">
2671       <synopsis>Get Frame Count</synopsis>
2672       <description>
2673         Get the number of frames currently in the specified thread's call stack.
2674         <p/>
2675         If this function is called for a thread actively executing bytecodes (for example,
2676         not the current thread and not suspended), the information returned is transient.
2677       </description>
2678       <origin>jvmdi</origin>
2679       <capabilities>
2680       </capabilities>
2681       <parameters>
2682         <param id="thread">
2683           <jthread null="current"/>
2684             <description>
2685               The thread to query.
2686             </description>
2687         </param>
2688         <param id="count_ptr">
2689           <outptr><jint/></outptr>
2690           <description>
2691             On return, points to the number of frames in the call stack.
2692           </description>
2693         </param>
2694       </parameters>
2695       <errors>
2696       </errors>
2697     </function>
2698 
2699     <function id="PopFrame" num="80">
2700       <synopsis>Pop Frame</synopsis>
2701       <description>
2702         Pop the current frame of <code>thread</code>'s stack.
2703         Popping a frame takes you to the previous frame.  
2704         When the thread is resumed, the execution 
2705         state of the thread is reset to the state
2706         immediately before the called method was invoked.
2707         That is (using <vmspec/> terminology):
2708           <ul>
2709             <li>the current frame is discarded as the previous frame becomes the current one</li>
2710             <li>the operand stack is restored--the argument values are added back
2711               and if the invoke was not <code>invokestatic</code>, 
2712               <code>objectref</code> is added back as well</li>
2713             <li>the Java virtual machine PC is restored to the opcode
2714               of the invoke instruction</li>
2715           </ul>
2716         Note however, that any changes to the arguments, which
2717         occurred in the called method, remain; 
2718         when execution continues, the first instruction to 
2719         execute will be the invoke.  
2720         <p/>
2721         Between calling <code>PopFrame</code> and resuming the 
2722         thread the state of the stack is undefined.  
2723         To pop frames beyond the first, 
2724         these three steps must be repeated:
2725         <ul>
2726           <li>suspend the thread via an event (step, breakpoint, ...)</li>
2727           <li>call <code>PopFrame</code></li>
2728           <li>resume the thread</li>
2729         </ul>
2730         <p/>
2731         A lock acquired by calling the called method 
2732         (if it is a <code>synchronized</code>  method) 
2733         and locks acquired by entering <code>synchronized</code>
2734         blocks within the called method are released. 
2735         Note: this does not apply to native locks or 
2736         <code>java.util.concurrent.locks</code> locks.
2737         <p/>
2738         Finally blocks are not executed.
2739         <p/>
2740         Changes to global state are not addressed and thus remain changed.
2741         <p/>
2742         The specified thread must be suspended (which implies it cannot be the current thread).
2743         <p/>
2744         Both the called method and calling method must be non-native Java programming 
2745         language methods.
2746         <p/>
2747         No <jvmti/> events are generated by this function.
2748       </description>
2749       <origin>jvmdi</origin>
2750       <capabilities>
2751         <required id="can_pop_frame"></required>
2752       </capabilities>
2753       <parameters>
2754         <param id="thread">
2755           <jthread/>
2756             <description>
2757               The thread whose current frame is to be popped.
2758             </description>
2759         </param>
2760       </parameters>
2761       <errors>
2762         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2763           Called or calling method is a native method.
2764           The implementation is unable to pop this frame.
2765         </error>
2766         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2767           Thread was not suspended.
2768         </error>
2769         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2770           There are less than two stack frames on the call stack.
2771         </error>
2772       </errors>
2773     </function>
2774 
2775     <function id="GetFrameLocation" num="19">
2776       <synopsis>Get Frame Location</synopsis>
2777       <description>
2778         <p/>
2779         For a Java programming language frame, return the location of the instruction
2780         currently executing.
2781       </description>
2782       <origin>jvmdiClone</origin>
2783       <capabilities>
2784       </capabilities>
2785       <parameters>
2786         <param id="thread">
2787           <jthread null="current" frame="frame"/>
2788           <description>
2789             The thread of the frame to query.
2790           </description>
2791         </param>
2792         <param id="depth">
2793           <jframeID thread="thread"/>
2794           <description>
2795             The depth of the frame to query.
2796           </description>
2797         </param>
2798         <param id="method_ptr">
2799           <outptr><jmethodID/></outptr>
2800             <description>
2801               On return, points to the method for the current location.
2802             </description>
2803         </param>
2804         <param id="location_ptr">
2805           <outptr><jlocation/></outptr>
2806           <description>
2807             On return, points to the index of the currently 
2808             executing instruction.
2809             Is set to <code>-1</code> if the frame is executing
2810             a native method.
2811           </description>
2812         </param>
2813       </parameters>
2814       <errors>
2815       </errors>
2816     </function>
2817 
2818     <function id="NotifyFramePop" num="20">
2819       <synopsis>Notify Frame Pop</synopsis>
2820       <description>
2821         When the frame that is currently at <paramlink id="depth"></paramlink> 
2822         is popped from the stack, generate a
2823         <eventlink id="FramePop"></eventlink> event.  See the 
2824         <eventlink id="FramePop"></eventlink> event for details.
2825         Only frames corresponding to non-native Java programming language 
2826         methods can receive notification.
2827         <p/>
2828         The specified thread must either be the current thread
2829         or the thread must be suspended.
2830       </description>
2831       <origin>jvmdi</origin>
2832       <capabilities>
2833         <required id="can_generate_frame_pop_events"></required>
2834       </capabilities>
2835       <parameters>
2836         <param id="thread">
2837           <jthread null="current" frame="depth"/>   
2838           <description>
2839             The thread of the frame for which the frame pop event will be generated.
2840           </description>
2841         </param>
2842         <param id="depth">
2843           <jframeID thread="thread"/>
2844           <description>
2845             The depth of the frame for which the frame pop event will be generated.
2846           </description>
2847         </param>
2848       </parameters>
2849       <errors>
2850         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
2851           The frame at <code>depth</code> is executing a
2852           native method.
2853         </error>
2854         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2855           Thread was not suspended and was not the current thread.
2856         </error>
2857       </errors>
2858     </function>
2859 
2860   </category>
2861 
2862   <category id="ForceEarlyReturn" label="Force Early Return">
2863     <intro>
2864       These functions allow an agent to force a method
2865       to return at any point during its execution.
2866       The method which will return early is referred to as the <i>called method</i>.
2867       The called method is the current method
2868       (as defined by
2869       <vmspec chapter="3.6"/>) 
2870       for the specified thread at
2871       the time the function is called.
2872       <p/>
2873       The specified thread must be suspended or must be the current thread.
2874       The return occurs when execution of Java programming
2875       language code is resumed on this thread.
2876       Between calling one of these functions and resumption
2877       of thread execution, the state of the stack is undefined.  
2878       <p/>
2879       No further instructions are executed in the called method.  
2880       Specifically, finally blocks are not executed.
2881       Note: this can cause inconsistent states in the application.
2882       <p/>
2883       A lock acquired by calling the called method 
2884       (if it is a <code>synchronized</code>  method) 
2885       and locks acquired by entering <code>synchronized</code>
2886       blocks within the called method are released. 
2887       Note: this does not apply to native locks or 
2888       <code>java.util.concurrent.locks</code> locks.
2889       <p/>
2890       Events, such as <eventlink id="MethodExit"></eventlink>,
2891       are generated as they would be in a normal return.
2892       <p/>
2893       The called method must be a non-native Java programming
2894       language method.
2895       Forcing return on a thread with only one frame on the
2896       stack causes the thread to exit when resumed.
2897     </intro>
2898 
2899     <function id="ForceEarlyReturnObject" num="81" since="1.1">
2900       <synopsis>Force Early Return - Object</synopsis>
2901       <description>
2902         This function can be used to return from a method whose
2903         result type is <code>Object</code>
2904         or a subclass of <code>Object</code>. 
2905       </description>
2906       <origin>new</origin>
2907       <capabilities>
2908         <required id="can_force_early_return"></required>
2909       </capabilities>
2910       <parameters>
2911         <param id="thread">
2912           <jthread null="current"/>
2913           <description>
2914             The thread whose current frame is to return early.
2915           </description>
2916         </param>
2917         <param id="value">
2918           <jobject/>
2919           <description>
2920             The return value for the called frame. 
2921             An object or <code>NULL</code>.
2922           </description>
2923         </param>
2924       </parameters>
2925       <errors>
2926         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2927           Attempted to return early from a frame
2928           corresponding to a native method.
2929           Or the implementation is unable to provide
2930           this functionality on this frame.
2931         </error>
2932         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
2933           The result type of the called method is not 
2934           <code>Object</code> or a subclass of <code>Object</code>.
2935         </error>
2936         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
2937           The supplied <paramlink id="value"/> is not compatible with the 
2938           result type of the called method.
2939         </error>
2940         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2941           Thread was not the current thread and was not suspended.
2942         </error>
2943         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2944           There are no more frames on the call stack.
2945         </error>
2946       </errors>
2947     </function>
2948 
2949     <function id="ForceEarlyReturnInt" num="82" since="1.1">
2950       <synopsis>Force Early Return - Int</synopsis>
2951       <description>
2952         This function can be used to return from a method whose
2953         result type is <code>int</code>, <code>short</code>,
2954         <code>char</code>, <code>byte</code>, or 
2955         <code>boolean</code>. 
2956       </description>
2957       <origin>new</origin>
2958       <capabilities>
2959         <required id="can_force_early_return"></required>
2960       </capabilities>
2961       <parameters>
2962         <param id="thread">
2963           <jthread null="current"/>
2964           <description>
2965             The thread whose current frame is to return early.
2966           </description>
2967         </param>
2968         <param id="value">
2969           <jint/>
2970           <description>
2971             The return value for the called frame.
2972           </description>
2973         </param>
2974       </parameters>
2975       <errors>
2976         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2977           Attempted to return early from a frame
2978           corresponding to a native method.
2979           Or the implementation is unable to provide
2980           this functionality on this frame.
2981         </error>
2982         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
2983           The result type of the called method is not 
2984           <code>int</code>, <code>short</code>,
2985           <code>char</code>, <code>byte</code>, or 
2986           <code>boolean</code>.
2987         </error>
2988         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2989           Thread was not the current thread and was not suspended.
2990         </error>
2991         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2992           There are no frames on the call stack.
2993         </error>
2994       </errors>
2995     </function>
2996 
2997     <function id="ForceEarlyReturnLong" num="83" since="1.1">
2998       <synopsis>Force Early Return - Long</synopsis>
2999       <description>
3000         This function can be used to return from a method whose
3001         result type is <code>long</code>.
3002       </description>
3003       <origin>new</origin>
3004       <capabilities>
3005         <required id="can_force_early_return"></required>
3006       </capabilities>
3007       <parameters>
3008         <param id="thread">
3009           <jthread null="current"/>
3010           <description>
3011             The thread whose current frame is to return early.
3012           </description>
3013         </param>
3014         <param id="value">
3015           <jlong/>
3016           <description>
3017             The return value for the called frame.
3018           </description>
3019         </param>
3020       </parameters>
3021       <errors>
3022         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3023           Attempted to return early from a frame
3024           corresponding to a native method.
3025           Or the implementation is unable to provide
3026           this functionality on this frame.
3027         </error>
3028         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3029           The result type of the called method is not <code>long</code>.
3030         </error>
3031         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3032           Thread was not the current thread and was not suspended.
3033         </error>
3034         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3035           There are no frames on the call stack.
3036         </error>
3037       </errors>
3038     </function>
3039 
3040     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
3041       <synopsis>Force Early Return - Float</synopsis>
3042       <description>
3043         This function can be used to return from a method whose
3044         result type is <code>float</code>.
3045       </description>
3046       <origin>new</origin>
3047       <capabilities>
3048         <required id="can_force_early_return"></required>
3049       </capabilities>
3050       <parameters>
3051         <param id="thread">
3052           <jthread null="current"/>
3053           <description>
3054             The thread whose current frame is to return early.
3055           </description>
3056         </param>
3057         <param id="value">
3058           <jfloat/>
3059           <description>
3060             The return value for the called frame.
3061           </description>
3062         </param>
3063       </parameters>
3064       <errors>
3065         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3066           Attempted to return early from a frame
3067           corresponding to a native method.
3068           Or the implementation is unable to provide
3069           this functionality on this frame.
3070         </error>
3071         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3072           The result type of the called method is not <code>float</code>.
3073         </error>
3074         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3075           Thread was not the current thread and was not suspended.
3076         </error>
3077         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3078           There are no frames on the call stack.
3079         </error>
3080       </errors>
3081     </function>
3082 
3083     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
3084       <synopsis>Force Early Return - Double</synopsis>
3085       <description>
3086         This function can be used to return from a method whose
3087         result type is <code>double</code>.
3088       </description>
3089       <origin>new</origin>
3090       <capabilities>
3091         <required id="can_force_early_return"></required>
3092       </capabilities>
3093       <parameters>
3094         <param id="thread">
3095           <jthread null="current"/>
3096           <description>
3097             The thread whose current frame is to return early.
3098           </description>
3099         </param>
3100         <param id="value">
3101           <jdouble/>
3102           <description>
3103             The return value for the called frame.
3104           </description>
3105         </param>
3106       </parameters>
3107       <errors>
3108         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3109           Attempted to return early from a frame corresponding to a native method.
3110           Or the implementation is unable to provide this functionality on this frame.
3111         </error>
3112         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3113           The result type of the called method is not <code>double</code>.
3114         </error>
3115         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3116           Thread was not the current thread and was not suspended.
3117         </error>
3118         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3119           There are no frames on the call stack.
3120         </error>
3121       </errors>
3122     </function>
3123 
3124     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3125       <synopsis>Force Early Return - Void</synopsis>
3126       <description>
3127         This function can be used to return from a method with no result type.
3128         That is, the called method must be declared <code>void</code>.
3129       </description>
3130       <origin>new</origin>
3131       <capabilities>
3132         <required id="can_force_early_return"></required>
3133       </capabilities>
3134       <parameters>
3135         <param id="thread">
3136           <jthread null="current"/>
3137           <description>
3138             The thread whose current frame is to return early.
3139           </description>
3140         </param>
3141       </parameters>
3142       <errors>
3143         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3144           Attempted to return early from a frame
3145           corresponding to a native method.
3146           Or the implementation is unable to provide
3147           this functionality on this frame.
3148         </error>
3149         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3150           The called method has a result type.  
3151         </error>
3152         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3153           Thread was not the current thread and was not suspended.
3154         </error>
3155         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3156           There are no frames on the call stack.
3157         </error>
3158       </errors>
3159     </function>
3160 
3161   </category>
3162 
3163   <category id="Heap" label="Heap">
3164     <intro>
3165       These functions are used to analyze the heap.
3166       Functionality includes the ability to view the objects in the
3167       heap and to tag these objects.
3168     </intro>
3169    
3170     <intro id="objectTags" label="Object Tags">
3171       A <i>tag</i> is a value associated with an object.
3172       Tags are explicitly set by the agent using the
3173       <functionlink id="SetTag"></functionlink> function or by
3174       callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.    
3175       <p/>
3176       Tags are local to the environment; that is, the tags of one
3177       environment are not visible in another.
3178       <p/>
3179       Tags are <code>jlong</code> values which can be used
3180       simply to mark an object or to store a pointer to more detailed
3181       information.  Objects which have not been tagged have a
3182       tag of zero.  
3183       Setting a tag to zero makes the object untagged.
3184     </intro>
3185    
3186     <intro id="heapCallbacks" label="Heap Callback Functions">
3187         Heap functions which iterate through the heap and recursively
3188         follow object references use agent supplied callback functions
3189         to deliver the information.
3190         <p/>
3191         These heap callback functions must adhere to the following restrictions --
3192         These callbacks must not use JNI functions.
3193         These callbacks must not use <jvmti/> functions except 
3194         <i>callback safe</i> functions which
3195         specifically allow such use (see the raw monitor, memory management,
3196         and environment local storage functions).
3197         <p/>
3198         An implementation may invoke a callback on an internal thread or
3199         the thread which called the iteration function.
3200         Heap callbacks are single threaded -- no more than one callback will
3201         be invoked at a time.
3202         <p/>
3203         The Heap Filter Flags can be used to prevent reporting
3204         based on the tag status of an object or its class.  
3205         If no flags are set (the <code>jint</code> is zero), objects
3206         will not be filtered out.
3207 
3208         <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
3209           <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
3210             Filter out tagged objects. Objects which are tagged are not included.
3211           </constant>
3212           <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
3213             Filter out untagged objects. Objects which are not tagged are not included.
3214           </constant>
3215           <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
3216             Filter out objects with tagged classes. Objects whose class is tagged are not included.
3217           </constant>
3218           <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
3219             Filter out objects with untagged classes. Objects whose class is not tagged are not included.
3220           </constant>
3221         </constants>
3222 
3223         <p/>
3224         The Heap Visit Control Flags are returned by the heap callbacks
3225         and can be used to abort the iteration.  For the 
3226         <functionlink id="jvmtiHeapReferenceCallback">Heap 
3227         Reference Callback</functionlink>, it can also be used 
3228         to prune the graph of traversed references
3229         (<code>JVMTI_VISIT_OBJECTS</code> is not set).
3230 
3231         <constants id="jvmtiHeapVisitControl" 
3232                    label="Heap Visit Control Flags" 
3233                    kind="bits" 
3234                    since="1.1">
3235           <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
3236             If we are visiting an object and if this callback
3237             was initiated by <functionlink id="FollowReferences"/>, 
3238             traverse the references of this object.
3239             Otherwise ignored.
3240           </constant>       
3241           <constant id="JVMTI_VISIT_ABORT" num="0x8000">
3242             Abort the iteration.  Ignore all other bits.
3243           </constant>
3244         </constants>
3245 
3246         <p/>
3247         The Heap Reference Enumeration is provided by the 
3248         <functionlink id="jvmtiHeapReferenceCallback">Heap 
3249         Reference Callback</functionlink> and 
3250         <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field 
3251         Callback</functionlink> to 
3252         describe the kind of reference
3253         being reported.
3254 
3255         <constants id="jvmtiHeapReferenceKind" 
3256                    label="Heap Reference Enumeration" 
3257                    kind="enum" 
3258                    since="1.1">
3259           <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
3260             Reference from an object to its class.
3261           </constant>       
3262           <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
3263             Reference from an object to the value of one of its instance fields.
3264           </constant>
3265           <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
3266             Reference from an array to one of its elements.
3267           </constant>
3268           <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
3269             Reference from a class to its class loader.
3270           </constant>
3271           <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
3272             Reference from a class to its signers array.
3273           </constant>
3274           <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
3275             Reference from a class to its protection domain.
3276           </constant>       
3277           <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
3278             Reference from a class to one of its interfaces. 
3279             Note: interfaces are defined via a constant pool reference,
3280             so the referenced interfaces may also be reported with a 
3281             <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3282           </constant>
3283           <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
3284             Reference from a class to the value of one of its static fields.
3285           </constant>
3286           <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
3287             Reference from a class to a resolved entry in the constant pool.
3288           </constant>
3289           <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
3290             Reference from a class to its superclass. 
3291             A callback is bot sent if the superclass is <code>java.lang.Object</code>.
3292             Note: loaded classes define superclasses via a constant pool
3293             reference, so the referenced superclass may also be reported with 
3294             a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3295           </constant>
3296           <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
3297             Heap root reference: JNI global reference.
3298           </constant>
3299           <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
3300             Heap root reference: System class.
3301           </constant>
3302           <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
3303             Heap root reference: monitor.
3304           </constant>
3305           <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
3306             Heap root reference: local variable on the stack.
3307           </constant>
3308           <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
3309             Heap root reference: JNI local reference.
3310           </constant>
3311           <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
3312             Heap root reference: Thread.
3313           </constant>
3314           <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
3315             Heap root reference: other heap root reference.
3316           </constant>
3317         </constants>
3318 
3319         <p/>
3320         Definitions for the single character type descriptors of
3321         primitive types.
3322 
3323         <constants id="jvmtiPrimitiveType" 
3324                    label="Primitive Type Enumeration" 
3325                    kind="enum" 
3326                    since="1.1">
3327           <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
3328             'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
3329           </constant>       
3330           <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
3331             'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
3332           </constant>       
3333           <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
3334             'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
3335           </constant>       
3336           <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
3337             'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
3338           </constant>       
3339           <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
3340             'I' - Java programming language <code>int</code> - JNI <code>jint</code>
3341           </constant>       
3342           <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
3343             'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
3344           </constant>       
3345           <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
3346             'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
3347           </constant>       
3348           <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
3349             'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
3350           </constant>       
3351         </constants>
3352     </intro>
3353 
3354       <typedef id="jvmtiHeapReferenceInfoField" 
3355                label="Reference information structure for Field references" 
3356                since="1.1">
3357         <description>
3358           Reference information returned for 
3359           <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and 
3360           <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3361         </description>
3362         <field id="index">
3363           <jint/>
3364           <description>       
3365             For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the 
3366             referrer object is not a class or an inteface.  
3367             In this case, <code>index</code> is the index of the field 
3368             in the class of the referrer object.  
3369             This class is referred to below as <i>C</i>.
3370             <p/>
3371             For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
3372             the referrer object is a class (referred to below as <i>C</i>)
3373             or an interface (referred to below as <i>I</i>).
3374             In this case, <code>index</code> is the index of the field in 
3375             that class or interface.
3376             <p/>
3377             If the referrer object is not an interface, then the field 
3378             indices are determined as follows: 
3379             <ul>
3380               <li>make a list of all the fields in <i>C</i> and its
3381                   superclasses, starting with all the fields in 
3382                   <code>java.lang.Object</code> and ending with all the
3383                   fields in <i>C</i>.</li>
3384               <li>Within this list, put 
3385                   the fields for a given class in the order returned by
3386                   <functionlink id="GetClassFields"/>.</li>
3387               <li>Assign the fields in this list indices 
3388                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 
3389                   is the count of the fields in all the interfaces
3390                   implemented by <i>C</i>. 
3391                   Note that <i>C</i> implements all interfaces 
3392                   directly implemented by its superclasses; as well
3393                   as all superinterfaces of these interfaces.</li>
3394             </ul>
3395             If the referrer object is an interface, then the field 
3396             indices are determined as follows:
3397             <ul>
3398               <li>make a list of the fields directly declared in 
3399                   <i>I</i>.</li>
3400               <li>Within this list, put 
3401                   the fields in the order returned by
3402                   <functionlink id="GetClassFields"/>.</li>
3403               <li>Assign the fields in this list indices 
3404                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 
3405                   is the count of the fields in all the superinterfaces
3406                   of <i>I</i>.</li>
3407             </ul>
3408             All fields are included in this computation, regardless of
3409             field modifier (static, public, private, etc).
3410             <p/>
3411             For example, given the following classes and interfaces:
3412             <example>
3413 interface I0 {
3414     int p = 0;
3415 }
3416 
3417 interface I1 extends I0 {
3418     int x = 1;
3419 }
3420 
3421 interface I2 extends I0 {
3422     int y = 2;
3423 }
3424 
3425 class C1 implements I1 {
3426     public static int a = 3;
3427     private int b = 4;
3428 }
3429 
3430 class C2 extends C1 implements I2 {
3431     static int q = 5;
3432     final int r = 6;
3433 }
3434             </example>
3435             Assume that <functionlink id="GetClassFields"/> called on
3436             <code>C1</code> returns the fields of <code>C1</code> in the
3437             order: a, b; and that the fields of <code>C2</code> are 
3438             returned in the order: q, r.
3439             An instance of class <code>C1</code> will have the
3440             following field indices:
3441             <dl><dd><table>
3442               <tr>
3443                 <td>
3444                   a
3445                 </td>
3446                 <td>
3447                   2
3448                 </td>
3449                 <td align="left">
3450                   The count of the fields in the interfaces
3451                   implemented by <code>C1</code> is two (<i>n</i>=2):
3452                   <code>p</code> of <code>I0</code>
3453                   and <code>x</code> of <code>I1</code>.
3454                 </td>
3455               </tr>
3456               <tr>
3457                 <td>
3458                   b
3459                 </td>
3460                 <td>
3461                   3
3462                 </td>
3463                 <td align="left">
3464                   the subsequent index.
3465                 </td>
3466               </tr>
3467             </table></dd></dl>
3468             The class <code>C1</code> will have the same field indices.
3469             <p/>
3470             An instance of class <code>C2</code> will have the
3471             following field indices:
3472             <dl><dd><table>
3473               <tr>
3474                 <td>
3475                   a
3476                 </td>
3477                 <td>
3478                   3
3479                 </td>
3480                 <td align="left">
3481                   The count of the fields in the interfaces
3482                   implemented by <code>C2</code> is three (<i>n</i>=3):
3483                   <code>p</code> of <code>I0</code>,
3484                   <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> 
3485                   (an interface of <code>C2</code>).  Note that the field <code>p</code>
3486                   of <code>I0</code> is only included once.
3487                 </td>
3488               </tr>
3489               <tr>
3490                 <td>
3491                   b
3492                 </td>
3493                 <td>
3494                   4
3495                 </td>
3496                 <td align="left">
3497                   the subsequent index to "a".
3498                 </td>
3499               </tr>
3500               <tr>
3501                 <td>
3502                   q
3503                 </td>
3504                 <td>
3505                   5
3506                 </td>
3507                 <td align="left">
3508                   the subsequent index to "b".
3509                 </td>
3510               </tr>
3511               <tr>
3512                 <td>
3513                   r
3514                 </td>
3515                 <td>
3516                   6
3517                 </td>
3518                 <td align="left">
3519                   the subsequent index to "q".
3520                 </td>
3521               </tr>
3522             </table></dd></dl>
3523             The class <code>C2</code> will have the same field indices.
3524             Note that a field may have a different index depending on the
3525             object that is viewing it -- for example field "a" above.
3526             Note also: not all field indices may be visible from the 
3527             callbacks, but all indices are shown for illustrative purposes.
3528             <p/>
3529             The interface <code>I1</code> will have the
3530             following field indices:
3531             <dl><dd><table>
3532               <tr>
3533                 <td>
3534                   x
3535                 </td>
3536                 <td>
3537                   1
3538                 </td>
3539                 <td align="left">
3540                   The count of the fields in the superinterfaces
3541                   of <code>I1</code> is one (<i>n</i>=1):
3542                   <code>p</code> of <code>I0</code>.
3543                 </td>
3544               </tr>
3545             </table></dd></dl>
3546           </description>      
3547         </field>
3548       </typedef>
3549 
3550       <typedef id="jvmtiHeapReferenceInfoArray" 
3551                label="Reference information structure for Array references" 
3552                since="1.1">
3553         <description>
3554           Reference information returned for 
3555          <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3556         </description>
3557         <field id="index">
3558           <jint/>
3559           <description>       
3560             The array index.
3561           </description>
3562         </field>
3563       </typedef>
3564 
3565       <typedef id="jvmtiHeapReferenceInfoConstantPool" 
3566                label="Reference information structure for Constant Pool references" 
3567                since="1.1">
3568         <description>
3569           Reference information returned for 
3570           <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3571         </description>
3572         <field id="index">
3573           <jint/>
3574           <description>       
3575             The index into the constant pool of the class. See the description in 
3576       <vmspec chapter="4.4"/>.
3577           </description>
3578         </field>
3579       </typedef>
3580 
3581       <typedef id="jvmtiHeapReferenceInfoStackLocal" 
3582                label="Reference information structure for Local Variable references" 
3583                since="1.1">
3584         <description>
3585           Reference information returned for 
3586           <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3587         </description>
3588         <field id="thread_tag">
3589           <jlong/>
3590           <description>
3591             The tag of the thread corresponding to this stack, zero if not tagged.
3592           </description>
3593         </field>
3594         <field id="thread_id">
3595           <jlong/>
3596           <description>
3597             The unique thread ID of the thread corresponding to this stack.
3598           </description>
3599         </field>
3600         <field id="depth">
3601           <jint/>
3602           <description>
3603             The depth of the frame. 
3604           </description>
3605         </field>
3606         <field id="method">
3607           <jmethodID/>
3608           <description>
3609             The method executing in this frame.
3610           </description>
3611         </field>
3612         <field id="location">
3613           <jlocation/>
3614           <description>
3615             The currently executing location in this frame.
3616           </description>
3617         </field>
3618         <field id="slot">
3619           <jint/>
3620           <description>
3621             The slot number of the local variable.
3622           </description>
3623         </field>
3624       </typedef>
3625 
3626       <typedef id="jvmtiHeapReferenceInfoJniLocal" 
3627                label="Reference information structure for JNI local references" 
3628                since="1.1">
3629         <description>
3630           Reference information returned for 
3631           <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3632         </description>
3633         <field id="thread_tag">
3634           <jlong/>
3635           <description>
3636             The tag of the thread corresponding to this stack, zero if not tagged.
3637           </description>
3638         </field>
3639         <field id="thread_id">
3640           <jlong/>
3641           <description>
3642             The unique thread ID of the thread corresponding to this stack.
3643           </description>
3644         </field>
3645         <field id="depth">
3646           <jint/>
3647           <description>
3648             The depth of the frame. 
3649           </description>
3650         </field>
3651         <field id="method">
3652           <jmethodID/>
3653           <description>
3654             The method executing in this frame.
3655           </description>
3656         </field>
3657       </typedef>
3658 
3659       <typedef id="jvmtiHeapReferenceInfoReserved" 
3660                label="Reference information structure for Other references" 
3661                since="1.1">
3662         <description>
3663           Reference information returned for other references.
3664         </description>
3665         <field id="reserved1">
3666           <jlong/>
3667           <description>
3668             reserved for future use.
3669           </description>
3670         </field>
3671         <field id="reserved2">
3672           <jlong/>
3673           <description>
3674             reserved for future use.
3675           </description>
3676         </field>
3677         <field id="reserved3">
3678           <jlong/>
3679           <description>
3680             reserved for future use.
3681           </description>
3682         </field>
3683         <field id="reserved4">
3684           <jlong/>
3685           <description>
3686             reserved for future use.
3687           </description>
3688         </field>
3689         <field id="reserved5">
3690           <jlong/>
3691           <description>
3692             reserved for future use.
3693           </description>
3694         </field>
3695         <field id="reserved6">
3696           <jlong/>
3697           <description>
3698             reserved for future use.
3699           </description>
3700         </field>
3701         <field id="reserved7">
3702           <jlong/>
3703           <description>
3704             reserved for future use.
3705           </description>
3706         </field>
3707         <field id="reserved8">
3708           <jlong/>
3709           <description>
3710             reserved for future use.
3711           </description>
3712         </field>
3713       </typedef>
3714 
3715       <uniontypedef id="jvmtiHeapReferenceInfo" 
3716                label="Reference information structure" 
3717                since="1.1">
3718         <description>
3719           The information returned about referrers.
3720           Represented as a union of the various kinds of reference information.
3721         </description>
3722         <field id="field">
3723           <struct>jvmtiHeapReferenceInfoField</struct>
3724           <description>       
3725             The referrer information for 
3726             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> 
3727             and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3728           </description>
3729         </field>
3730         <field id="array">
3731           <struct>jvmtiHeapReferenceInfoArray</struct>
3732           <description>       
3733             The referrer information for 
3734             For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3735           </description>
3736         </field>
3737         <field id="constant_pool">
3738           <struct>jvmtiHeapReferenceInfoConstantPool</struct>
3739           <description>       
3740             The referrer information for 
3741             For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3742           </description>
3743         </field>
3744         <field id="stack_local">
3745           <struct>jvmtiHeapReferenceInfoStackLocal</struct>
3746           <description>       
3747             The referrer information for 
3748             For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3749           </description>
3750         </field>
3751         <field id="jni_local">
3752           <struct>jvmtiHeapReferenceInfoJniLocal</struct>
3753           <description>       
3754             The referrer information for 
3755             For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3756           </description>
3757         </field>
3758         <field id="other">
3759           <struct>jvmtiHeapReferenceInfoReserved</struct>
3760           <description>       
3761             reserved for future use.
3762           </description>
3763         </field>
3764       </uniontypedef>
3765 
3766       <typedef id="jvmtiHeapCallbacks" 
3767                label="Heap callback function structure" 
3768                since="1.1">
3769         <field id="heap_iteration_callback">
3770           <ptrtype>
3771             <struct>jvmtiHeapIterationCallback</struct>
3772           </ptrtype>
3773           <description>
3774             The callback to be called to describe an
3775             object in the heap. Used by the 
3776             <functionlink id="IterateThroughHeap"/> function, ignored by the
3777             <functionlink id="FollowReferences"/> function.
3778           </description>
3779         </field>            
3780         <field id="heap_reference_callback">
3781           <ptrtype>
3782             <struct>jvmtiHeapReferenceCallback</struct>
3783           </ptrtype>
3784           <description>
3785             The callback to be called to describe an
3786             object reference.  Used by the 
3787             <functionlink id="FollowReferences"/> function, ignored by the
3788             <functionlink id="IterateThroughHeap"/> function.
3789           </description>
3790         </field>            
3791         <field id="primitive_field_callback">
3792           <ptrtype>
3793             <struct>jvmtiPrimitiveFieldCallback</struct>
3794           </ptrtype>
3795           <description>
3796             The callback to be called to describe a
3797             primitive field.
3798           </description>
3799         </field>            
3800         <field id="array_primitive_value_callback">
3801           <ptrtype>
3802             <struct>jvmtiArrayPrimitiveValueCallback</struct>
3803           </ptrtype>
3804           <description>
3805             The callback to be called to describe an
3806             array of primitive values.
3807           </description>
3808         </field>            
3809         <field id="string_primitive_value_callback">
3810           <ptrtype>
3811             <struct>jvmtiStringPrimitiveValueCallback</struct>
3812           </ptrtype>
3813           <description>
3814             The callback to be called to describe a String value.
3815           </description>
3816         </field>            
3817         <field id="reserved5">
3818           <ptrtype>
3819             <struct>jvmtiReservedCallback</struct>
3820           </ptrtype>
3821           <description>
3822             Reserved for future use..
3823           </description>
3824         </field>            
3825         <field id="reserved6">
3826           <ptrtype>
3827             <struct>jvmtiReservedCallback</struct>
3828           </ptrtype>
3829           <description>
3830             Reserved for future use..
3831           </description>
3832         </field>            
3833         <field id="reserved7">
3834           <ptrtype>
3835             <struct>jvmtiReservedCallback</struct>
3836           </ptrtype>
3837           <description>
3838             Reserved for future use..
3839           </description>
3840         </field>            
3841         <field id="reserved8">
3842           <ptrtype>
3843             <struct>jvmtiReservedCallback</struct>
3844           </ptrtype>
3845           <description>
3846             Reserved for future use..
3847           </description>
3848         </field>            
3849         <field id="reserved9">
3850           <ptrtype>
3851             <struct>jvmtiReservedCallback</struct>
3852           </ptrtype>
3853           <description>
3854             Reserved for future use..
3855           </description>
3856         </field>            
3857         <field id="reserved10">
3858           <ptrtype>
3859             <struct>jvmtiReservedCallback</struct>
3860           </ptrtype>
3861           <description>
3862             Reserved for future use..
3863           </description>
3864         </field>            
3865         <field id="reserved11">
3866           <ptrtype>
3867             <struct>jvmtiReservedCallback</struct>
3868           </ptrtype>
3869           <description>
3870             Reserved for future use..
3871           </description>
3872         </field>            
3873         <field id="reserved12">
3874           <ptrtype>
3875             <struct>jvmtiReservedCallback</struct>
3876           </ptrtype>
3877           <description>
3878             Reserved for future use..
3879           </description>
3880         </field>            
3881         <field id="reserved13">
3882           <ptrtype>
3883             <struct>jvmtiReservedCallback</struct>
3884           </ptrtype>
3885           <description>
3886             Reserved for future use..
3887           </description>
3888         </field>            
3889         <field id="reserved14">
3890           <ptrtype>
3891             <struct>jvmtiReservedCallback</struct>
3892           </ptrtype>
3893           <description>
3894             Reserved for future use..
3895           </description>
3896         </field>            
3897         <field id="reserved15">
3898           <ptrtype>
3899             <struct>jvmtiReservedCallback</struct>
3900           </ptrtype>
3901           <description>
3902             Reserved for future use..
3903           </description>
3904         </field>            
3905       </typedef>
3906 
3907 
3908     <intro>
3909       <rationale>
3910         The heap dumping functionality (below) uses a callback
3911         for each object.  While it would seem that a buffered approach
3912         would provide better throughput, tests do
3913         not show this to be the case--possibly due to locality of
3914         memory reference or array access overhead.
3915       </rationale>
3916 
3917       <issue>
3918         Still under investigation as to if java.lang.ref references
3919         are reported as a different type of reference.
3920       </issue>
3921 
3922       <issue>
3923         Should or can an indication of the cost or relative cost of
3924         these operations be included?
3925       </issue>
3926 
3927     </intro>
3928 
3929     <callback id="jvmtiHeapIterationCallback" since="1.1">
3930       <jint/>
3931       <synopsis>Heap Iteration Callback</synopsis>
3932       <description>
3933         Agent supplied callback function.
3934         Describes (but does not pass in) an object in the heap.
3935         <p/>
3936         This function should return a bit vector of the desired
3937         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
3938         This will determine if the entire iteration should be aborted
3939         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
3940         <p/>
3941         See the <internallink id="heapCallbacks">heap callback
3942         function restrictions</internallink>.
3943       </description>
3944       <parameters>
3945         <param id="class_tag">
3946           <jlong/>
3947           <description>
3948             The tag of the class of object (zero if the class is not tagged). 
3949             If the object represents a runtime class, 
3950             the <code>class_tag</code> is the tag 
3951             associated with <code>java.lang.Class</code> 
3952             (zero if <code>java.lang.Class</code> is not tagged).
3953           </description>
3954         </param>
3955         <param id="size">
3956           <jlong/>
3957           <description>
3958             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
3959           </description>
3960         </param>
3961         <param id="tag_ptr">
3962           <outptr><jlong/></outptr>
3963           <description>
3964             The object tag value, or zero if the object is not tagged.
3965             To set the tag value to be associated with the object
3966             the agent sets the <code>jlong</code> pointed to by the parameter. 
3967           </description>
3968         </param>
3969         <param id="length">
3970           <jint/>
3971           <description>
3972             If this object is an array, the length of the array. Otherwise negative one (-1).
3973           </description>
3974         </param>
3975         <param id="user_data">
3976           <outptr><void/></outptr>
3977           <description>
3978             The user supplied data that was passed into the iteration function. 
3979           </description>
3980         </param>
3981       </parameters>
3982     </callback>  
3983 
3984     <callback id="jvmtiHeapReferenceCallback" since="1.1">
3985       <jint/>
3986       <synopsis>Heap Reference Callback</synopsis>
3987       <description>
3988         Agent supplied callback function.       
3989         Describes a reference from an object or the VM (the referrer) to another object
3990         (the referree) or a heap root to a referree.
3991         <p/>
3992         This function should return a bit vector of the desired
3993         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
3994         This will determine if the objects referenced by the referree
3995         should be visited or if the entire iteration should be aborted.
3996         <p/>
3997         See the <internallink id="heapCallbacks">heap callback
3998         function restrictions</internallink>.
3999       </description>
4000       <parameters>
4001         <param id="reference_kind">
4002           <enum>jvmtiHeapReferenceKind</enum>
4003           <description>
4004             The kind of reference.
4005           </description>
4006         </param>
4007         <param id="reference_info">
4008           <inptr>
4009             <struct>jvmtiHeapReferenceInfo</struct>
4010           </inptr>
4011           <description>
4012             Details about the reference. 
4013             Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is
4014             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
4015             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
4016             <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
4017             <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, 
4018             <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
4019             or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
4020             Otherwise <code>NULL</code>.
4021           </description>
4022         </param>
4023         <param id="class_tag">
4024           <jlong/>
4025           <description>
4026             The tag of the class of referree object (zero if the class is not tagged). 
4027             If the referree object represents a runtime class, 
4028             the <code>class_tag</code> is the tag 
4029             associated with <code>java.lang.Class</code>
4030             (zero if <code>java.lang.Class</code> is not tagged).
4031           </description>
4032         </param>
4033         <param id="referrer_class_tag">
4034           <jlong/>
4035           <description>
4036             The tag of the class of the referrer object (zero if the class is not tagged
4037             or the referree is a heap root). If the referrer object represents a runtime
4038             class, the <code>referrer_class_tag</code> is the tag associated with
4039             the <code>java.lang.Class</code>
4040             (zero if <code>java.lang.Class</code> is not tagged).
4041           </description>
4042         </param>
4043         <param id="size">
4044           <jlong/>
4045           <description>
4046             Size of the referree object (in bytes). 
4047             See <functionlink id="GetObjectSize"/>.
4048           </description>
4049         </param>
4050         <param id="tag_ptr">
4051           <outptr><jlong/></outptr>
4052           <description>
4053             Points to the referree object tag value, or zero if the object is not 
4054             tagged.
4055             To set the tag value to be associated with the object
4056             the agent sets the <code>jlong</code> pointed to by the parameter.
4057           </description>
4058         </param>
4059         <param id="referrer_tag_ptr">
4060           <outptr><jlong/></outptr>
4061           <description>
4062             Points to the tag of the referrer object, or 
4063             points to the zero if the referrer
4064             object is not tagged. 
4065             <code>NULL</code> if the referrer in not an object (that is,
4066             this callback is reporting a heap root).
4067             To set the tag value to be associated with the referrer object
4068             the agent sets the <code>jlong</code> pointed to by the parameter.
4069             If this callback is reporting a reference from an object to itself, 
4070             <code>referrer_tag_ptr == tag_ptr</code>.
4071           </description>
4072         </param>
4073         <param id="length">
4074           <jint/>
4075           <description>
4076             If this object is an array, the length of the array. Otherwise negative one (-1).
4077           </description>
4078         </param>
4079         <param id="user_data">
4080           <outptr><void/></outptr>
4081           <description>
4082             The user supplied data that was passed into the iteration function. 
4083           </description>
4084         </param>
4085       </parameters>
4086     </callback>
4087 
4088     <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
4089       <jint/>
4090       <synopsis>Primitive Field Callback</synopsis>
4091       <description>
4092         Agent supplied callback function which  
4093         describes a primitive field of an object (<i>the object</i>).
4094         A primitive field is a field whose type is a primitive type.
4095         This callback will describe a static field if the object is a class,
4096         and otherwise will describe an instance field.
4097         <p/>
4098         This function should return a bit vector of the desired
4099         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4100         This will determine if the entire iteration should be aborted
4101         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4102         <p/>
4103         See the <internallink id="heapCallbacks">heap callback
4104         function restrictions</internallink>.
4105       </description>
4106       <parameters>
4107         <param id="kind">
4108           <enum>jvmtiHeapReferenceKind</enum>
4109           <description>
4110             The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or 
4111             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
4112           </description>
4113         </param>
4114         <param id="info">
4115           <inptr>
4116             <struct>jvmtiHeapReferenceInfo</struct>
4117           </inptr>
4118           <description>
4119             Which field (the field index).
4120           </description>
4121         </param>
4122         <param id="object_class_tag">
4123           <jlong/>
4124           <description>
4125             The tag of the class of the object (zero if the class is not tagged). 
4126             If the object represents a runtime class, the 
4127             <code>object_class_tag</code> is the tag 
4128             associated with <code>java.lang.Class</code> 
4129             (zero if <code>java.lang.Class</code> is not tagged).
4130           </description>
4131         </param>
4132         <param id="object_tag_ptr">
4133           <outptr><jlong/></outptr>
4134           <description>
4135             Points to the tag of the object, or zero if the object is not 
4136             tagged.
4137             To set the tag value to be associated with the object
4138             the agent sets the <code>jlong</code> pointed to by the parameter.
4139           </description>
4140         </param>
4141         <param id="value">
4142           <jvalue/>
4143           <description>
4144             The value of the field.
4145           </description>
4146         </param>
4147         <param id="value_type">
4148           <enum>jvmtiPrimitiveType</enum>
4149           <description>
4150             The type of the field.
4151           </description>
4152         </param>
4153         <param id="user_data">
4154           <outptr><void/></outptr>
4155           <description>
4156             The user supplied data that was passed into the iteration function. 
4157           </description>
4158         </param>
4159       </parameters>
4160     </callback>
4161 
4162     <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
4163       <jint/>
4164       <synopsis>Array Primitive Value Callback</synopsis>
4165       <description>
4166         Agent supplied callback function.       
4167         Describes the values in an array of a primitive type.
4168         <p/>
4169         This function should return a bit vector of the desired
4170         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4171         This will determine if the entire iteration should be aborted
4172         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4173         <p/>
4174         See the <internallink id="heapCallbacks">heap callback
4175         function restrictions</internallink>.
4176       </description>
4177       <parameters>
4178         <param id="class_tag">
4179           <jlong/>
4180           <description>
4181             The tag of the class of the array object (zero if the class is not tagged). 
4182           </description>
4183         </param>
4184         <param id="size">
4185           <jlong/>
4186           <description>
4187             Size of the array (in bytes). 
4188             See <functionlink id="GetObjectSize"/>.
4189           </description>
4190         </param>
4191         <param id="tag_ptr">
4192           <outptr><jlong/></outptr>
4193           <description>
4194             Points to the tag of the array object, or zero if the object is not 
4195             tagged.
4196             To set the tag value to be associated with the object
4197             the agent sets the <code>jlong</code> pointed to by the parameter.
4198           </description>
4199         </param>
4200         <param id="element_count">
4201           <jint/>
4202           <description>
4203             The length of the primitive array.
4204           </description>
4205         </param>
4206         <param id="element_type">
4207           <enum>jvmtiPrimitiveType</enum>
4208           <description>
4209             The type of the elements of the array.
4210           </description>
4211         </param>
4212         <param id="elements">
4213           <vmbuf><void/></vmbuf>
4214           <description>
4215             The elements of the array in a packed array of <code>element_count</code>
4216             items of <code>element_type</code> size each.
4217           </description>
4218         </param>
4219         <param id="user_data">
4220           <outptr><void/></outptr>
4221           <description>
4222             The user supplied data that was passed into the iteration function. 
4223           </description>
4224         </param>
4225       </parameters>
4226     </callback>
4227 
4228     <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
4229       <jint/>
4230       <synopsis>String Primitive Value Callback</synopsis>
4231       <description>
4232         Agent supplied callback function.       
4233         Describes the value of a java.lang.String.
4234         <p/>
4235         This function should return a bit vector of the desired
4236         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4237         This will determine if the entire iteration should be aborted
4238         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4239         <p/>
4240         See the <internallink id="heapCallbacks">heap callback
4241         function restrictions</internallink>.
4242       </description>
4243       <parameters>
4244         <param id="class_tag">
4245           <jlong/>
4246           <description>
4247             The tag of the class of the String class (zero if the class is not tagged). 
4248             <issue>Is this needed?</issue>
4249           </description>
4250         </param>
4251         <param id="size">
4252           <jlong/>
4253           <description>
4254             Size of the string (in bytes). 
4255             See <functionlink id="GetObjectSize"/>.
4256           </description>
4257         </param>
4258         <param id="tag_ptr">
4259           <outptr><jlong/></outptr>
4260           <description>
4261             Points to the tag of the String object, or zero if the object is not 
4262             tagged.
4263             To set the tag value to be associated with the object
4264             the agent sets the <code>jlong</code> pointed to by the parameter.
4265           </description>
4266         </param>
4267         <param id="value">
4268           <vmbuf><jchar/></vmbuf>
4269           <description>
4270             The value of the String, encoded as a Unicode string.
4271           </description>
4272         </param>
4273         <param id="value_length">
4274           <jint/>
4275           <description>
4276             The length of the string. 
4277             The length is equal to the number of 16-bit Unicode 
4278             characters in the string.
4279           </description>
4280         </param>
4281         <param id="user_data">
4282           <outptr><void/></outptr>
4283           <description>
4284             The user supplied data that was passed into the iteration function. 
4285           </description>
4286         </param>
4287       </parameters>
4288     </callback>
4289 
4290 
4291     <callback id="jvmtiReservedCallback" since="1.1">
4292       <jint/>
4293       <synopsis>reserved for future use Callback</synopsis>
4294       <description>
4295         Placeholder -- reserved for future use.
4296       </description>
4297       <parameters>
4298       </parameters>
4299     </callback>
4300 
4301     <function id="FollowReferences" num="115" since="1.1">
4302       <synopsis>Follow References</synopsis>
4303       <description>       
4304         This function initiates a traversal over the objects that are 
4305         directly and indirectly reachable from the specified object or,
4306         if <code>initial_object</code> is not specified, all objects 
4307         reachable from the heap roots.
4308         The heap root are the set of system classes, 
4309         JNI globals, references from thread stacks, and other objects used as roots 
4310         for the purposes of garbage collection. 
4311         <p/>
4312         This function operates by traversing the reference graph.
4313         Let <i>A</i>, <i>B</i>, ... represent objects.
4314         When a reference from <i>A</i> to <i>B</i> is traversed,
4315         when a reference from a heap root to <i>B</i> is traversed, 
4316         or when <i>B</i> is specified as the <paramlink id="initial_object"/>, 
4317         then <i>B</i> is said to be <i>visited</i>.
4318         A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> 
4319         is visited.
4320         References are reported in the same order that the references are traversed.
4321         Object references are reported by invoking the agent supplied  
4322         callback function <functionlink id="jvmtiHeapReferenceCallback"/>.
4323         In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known 
4324         as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
4325         The callback is invoked exactly once for each reference from a referrer;
4326         this is true even if there are reference cycles or multiple paths to
4327         the referrer.
4328         There may be more than one reference between a referrer and a referree,
4329         each reference is reported.
4330         These references may be distinguished by examining the
4331         <datalink 
4332          id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
4333          and
4334         <datalink 
4335          id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
4336         parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
4337         <p/>
4338         This function reports a Java programming language view of object references,
4339         not a virtual machine implementation view. The following object references
4340         are reported when they are non-null:
4341         <ul>
4342           <li>Instance objects report references to each non-primitive instance fields
4343               (including inherited fields).</li>
4344           <li>Instance objects report a reference to the object type (class).</li>
4345           <li>Classes report a reference to the superclass and directly
4346               implemented/extended interfaces.</li>
4347           <li>Classes report a reference to the class loader, protection domain,
4348               signers, and resolved entries in the constant pool.</li>
4349           <li>Classes report a reference to each directly declared non-primitive
4350               static field.</li>
4351           <li>Arrays report a reference to the array type (class) and each
4352               array element.</li>
4353           <li>Primitive arrays report a reference to the array type.</li>
4354         </ul>
4355         <p/>
4356         This function can also be used to examine primitive (non-object) values.
4357         The primitive value of an array or String
4358         is reported after the object has been visited;
4359         it is reported by invoking the agent supplied callback function
4360         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4361         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4362         A primitive field
4363         is reported after the object with that field is visited;
4364         it is reported by invoking the agent supplied callback function
4365         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4366         <p/>
4367         Whether a callback is provided or is <code>NULL</code> only determines
4368         whether the callback will be invoked, it does not influence
4369         which objects are visited nor does it influence whether other callbacks
4370         will be invoked.
4371         However, the 
4372         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
4373         returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4374         do determine if the objects referenced by the 
4375         current object as visited.
4376         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4377         and <paramlink id="klass"/> provided as parameters to this function
4378         do not control which objects are visited but they do control which
4379         objects and primitive values are reported by the callbacks.
4380         For example, if the only callback that was set is
4381         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4382         is set to the array of bytes class, then only arrays of byte will be
4383         reported.  
4384         The table below summarizes this:
4385         <p/>
4386         <table>
4387           <tr>
4388             <th/>
4389             <th>
4390               Controls objects visited
4391             </th>
4392             <th>
4393               Controls objects reported
4394             </th>
4395             <th>
4396               Controls primitives reported
4397             </th>
4398           </tr>
4399           <tr>
4400             <th align="left">
4401               the
4402               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4403               returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4404             </th>
4405             <td>
4406               <b>Yes</b>
4407             </td>
4408             <td>
4409               <b>Yes</b>, since visits are controlled
4410             </td>
4411             <td>
4412               <b>Yes</b>, since visits are controlled
4413             </td>
4414           </tr>
4415           <tr>
4416             <th align="left">
4417               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4418               in <paramlink id="callbacks"/> set
4419             </th>
4420             <td>
4421               No
4422             </td>
4423             <td>
4424               <b>Yes</b>
4425             </td>
4426             <td>
4427               No
4428             </td>
4429           </tr>
4430           <tr>
4431             <th align="left">
4432               <paramlink id="heap_filter"/>
4433             </th>
4434             <td>
4435               No
4436             </td>
4437             <td>
4438               <b>Yes</b>
4439             </td>
4440             <td>
4441               <b>Yes</b>
4442             </td>
4443           </tr>
4444           <tr>
4445             <th align="left">
4446               <paramlink id="klass"/>
4447             </th>
4448             <td>
4449               No
4450             </td>
4451             <td>
4452               <b>Yes</b>
4453             </td>
4454             <td>
4455               <b>Yes</b>
4456             </td>
4457           </tr>
4458         </table>
4459         <p/>
4460         During the execution of this function the state of the heap
4461         does not change: no objects are allocated, no objects are
4462         garbage collected, and the state of objects (including 
4463         held values) does not change. 
4464         As a result, threads executing Java 
4465         programming language code, threads attempting to resume the
4466         execution of Java programming language code, and threads 
4467         attempting to execute JNI functions are typically stalled.
4468       </description>
4469       <origin>new</origin>
4470       <capabilities>
4471         <required id="can_tag_objects"></required>
4472       </capabilities>
4473       <parameters>             
4474         <param id="heap_filter">
4475           <jint/>
4476           <description>
4477             This bit vector of 
4478             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4479             restricts the objects for which the callback function is called.
4480             This applies to both the object and primitive callbacks.
4481           </description>
4482         </param>
4483         <param id="klass">
4484           <ptrtype>
4485             <jclass/>
4486             <nullok>callbacks are not limited to instances of a particular
4487                     class</nullok>
4488           </ptrtype>
4489           <description>
4490             Callbacks are only reported when the object is an instance of 
4491             this class.
4492             Objects which are instances of a subclass of <code>klass</code>
4493             are not reported.
4494             If <code>klass</code> is an interface, no objects are reported.
4495             This applies to both the object and primitive callbacks.
4496           </description>
4497         </param>
4498         <param id="initial_object">
4499           <ptrtype>
4500             <jobject/>
4501             <nullok>references are followed from the heap roots</nullok>
4502           </ptrtype>
4503           <description>
4504             The object to follow
4505           </description>
4506         </param>
4507         <param id="callbacks">
4508           <inptr>
4509             <struct>jvmtiHeapCallbacks</struct>
4510           </inptr>
4511           <description>
4512             Structure defining the set of callback functions.
4513           </description>
4514         </param>                  
4515         <param id="user_data">
4516           <inbuf>
4517             <void/>
4518             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4519           </inbuf>
4520           <description>
4521             User supplied data to be passed to the callback. 
4522           </description>
4523         </param>
4524       </parameters>
4525       <errors>
4526         <error id="JVMTI_ERROR_INVALID_CLASS">
4527           <paramlink id="klass"/> is not a valid class.
4528         </error>
4529         <error id="JVMTI_ERROR_INVALID_OBJECT">
4530           <paramlink id="initial_object"/> is not a valid object.
4531         </error>
4532       </errors>
4533     </function>
4534 
4535 
4536     <function id="IterateThroughHeap" num="116" since="1.1">
4537       <synopsis>Iterate Through Heap</synopsis>
4538       <description>        
4539         Initiate an iteration over all objects in the heap. 
4540         This includes both reachable and 
4541         unreachable objects. Objects are visited in no particular order.
4542         <p/>
4543         Heap objects are reported by invoking the agent supplied 
4544         callback function <functionlink id="jvmtiHeapIterationCallback"/>.
4545         References between objects are not reported.
4546         If only reachable objects are desired, or if object reference information
4547         is needed, use <functionlink id="FollowReferences"/>.
4548         <p/>
4549         This function can also be used to examine primitive (non-object) values.
4550         The primitive value of an array or String
4551         is reported after the object has been visited;
4552         it is reported by invoking the agent supplied callback function
4553         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4554         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4555         A primitive field
4556         is reported after the object with that field is visited;
4557         it is reported by invoking the agent supplied 
4558         callback function
4559         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4560         <p/>
4561         Unless the iteration is aborted by the
4562         <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4563         returned by a callback, all objects in the heap are visited.
4564         Whether a callback is provided or is <code>NULL</code> only determines
4565         whether the callback will be invoked, it does not influence
4566         which objects are visited nor does it influence whether other callbacks
4567         will be invoked.
4568         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4569         and <paramlink id="klass"/> provided as parameters to this function
4570         do not control which objects are visited but they do control which
4571         objects and primitive values are reported by the callbacks.
4572         For example, if the only callback that was set is
4573         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4574         is set to the array of bytes class, then only arrays of byte will be
4575         reported. The table below summarizes this (contrast this with 
4576         <functionlink id="FollowReferences"/>):
4577         <p/>
4578         <table>
4579           <tr>
4580             <th/>
4581             <th>
4582               Controls objects visited
4583             </th>
4584             <th>
4585               Controls objects reported
4586             </th>
4587             <th>
4588               Controls primitives reported
4589             </th>
4590           </tr>
4591           <tr>
4592             <th align="left">
4593               the
4594               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4595               returned by <functionlink id="jvmtiHeapIterationCallback"/>
4596             </th>
4597             <td>
4598               No<br/>(unless they abort the iteration)
4599             </td>
4600             <td>
4601               No<br/>(unless they abort the iteration)
4602             </td>
4603             <td>
4604               No<br/>(unless they abort the iteration)
4605             </td>
4606           </tr>
4607           <tr>
4608             <th align="left">
4609               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4610               in <paramlink id="callbacks"/> set
4611             </th>
4612             <td>
4613               No
4614             </td>
4615             <td>
4616               <b>Yes</b>
4617             </td>
4618             <td>
4619               No
4620             </td>
4621           </tr>
4622           <tr>
4623             <th align="left">
4624               <paramlink id="heap_filter"/>
4625             </th>
4626             <td>
4627               No
4628             </td>
4629             <td>
4630               <b>Yes</b>
4631             </td>
4632             <td>
4633               <b>Yes</b>
4634             </td>
4635           </tr>
4636           <tr>
4637             <th align="left">
4638               <paramlink id="klass"/>
4639             </th>
4640             <td>
4641               No
4642             </td>
4643             <td>
4644               <b>Yes</b>
4645             </td>
4646             <td>
4647               <b>Yes</b>
4648             </td>
4649           </tr>
4650         </table>
4651         <p/>
4652         During the execution of this function the state of the heap
4653         does not change: no objects are allocated, no objects are
4654         garbage collected, and the state of objects (including 
4655         held values) does not change. 
4656         As a result, threads executing Java 
4657         programming language code, threads attempting to resume the
4658         execution of Java programming language code, and threads 
4659         attempting to execute JNI functions are typically stalled.
4660       </description>
4661       <origin>new</origin>
4662       <capabilities>
4663         <required id="can_tag_objects"></required>
4664       </capabilities>
4665       <parameters>
4666         <param id="heap_filter">
4667           <jint/>
4668           <description>
4669             This bit vector of 
4670             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4671             restricts the objects for which the callback function is called.
4672             This applies to both the object and primitive callbacks.
4673           </description>
4674         </param>
4675         <param id="klass">
4676           <ptrtype>
4677             <jclass/>
4678             <nullok>callbacks are not limited to instances of a particular class</nullok>
4679           </ptrtype>
4680           <description>
4681             Callbacks are only reported when the object is an instance of 
4682             this class.
4683             Objects which are instances of a subclass of <code>klass</code>
4684             are not reported.
4685             If <code>klass</code> is an interface, no objects are reported.
4686             This applies to both the object and primitive callbacks.
4687           </description>
4688         </param>
4689         <param id="callbacks">
4690           <inptr>
4691             <struct>jvmtiHeapCallbacks</struct>
4692           </inptr>
4693           <description>
4694             Structure defining the set callback functions.
4695           </description>
4696         </param>                  
4697         <param id="user_data">
4698           <inbuf>
4699             <void/>
4700             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4701           </inbuf>
4702           <description>
4703             User supplied data to be passed to the callback. 
4704           </description>
4705         </param>
4706       </parameters>
4707       <errors>
4708         <error id="JVMTI_ERROR_INVALID_CLASS">
4709           <paramlink id="klass"/> is not a valid class.
4710         </error>
4711       </errors>
4712     </function>
4713 
4714     <function id="GetTag" phase="start" num="106">
4715       <synopsis>Get Tag</synopsis>
4716       <description>
4717         Retrieve the tag associated with an object.
4718         The tag is a long value typically used to store a 
4719         unique identifier or pointer to object information.
4720         The tag is set with
4721         <functionlink id="SetTag"></functionlink>.
4722         Objects for which no tags have been set return a
4723         tag value of zero.
4724       </description>
4725       <origin>new</origin>
4726       <capabilities>
4727         <required id="can_tag_objects"></required>
4728       </capabilities>
4729       <parameters>
4730         <param id="object">
4731           <jobject/>
4732             <description>
4733               The object whose tag is to be retrieved.
4734             </description>
4735         </param>
4736         <param id="tag_ptr">
4737           <outptr><jlong/></outptr>
4738           <description>
4739             On return, the referenced long is set to the value 
4740             of the tag.
4741           </description>
4742         </param>
4743       </parameters>
4744       <errors>
4745       </errors>
4746     </function>
4747 
4748     <function id="SetTag" phase="start" num="107">
4749       <synopsis>Set Tag</synopsis>
4750       <description>
4751         Set the tag associated with an object.
4752         The tag is a long value typically used to store a 
4753         unique identifier or pointer to object information.
4754         The tag is visible with
4755         <functionlink id="GetTag"></functionlink>.
4756       </description>
4757       <origin>new</origin>
4758       <capabilities>
4759         <required id="can_tag_objects"></required>
4760       </capabilities>
4761       <parameters>
4762         <param id="object">
4763           <jobject/>
4764             <description>
4765               The object whose tag is to be set.
4766             </description>
4767         </param>
4768         <param id="tag">
4769           <jlong/>
4770           <description>
4771             The new value of the tag.
4772           </description>
4773         </param>
4774       </parameters>
4775       <errors>
4776       </errors>
4777     </function>
4778 
4779     <function id="GetObjectsWithTags" num="114">
4780       <synopsis>Get Objects With Tags</synopsis>
4781       <description>
4782         Return objects in the heap with the specified tags.
4783         The format is parallel arrays of objects and tags.
4784       </description>
4785       <origin>new</origin>
4786       <capabilities>
4787         <required id="can_tag_objects"></required>
4788       </capabilities>
4789       <parameters>
4790         <param id="tag_count">
4791           <jint min="0"/>
4792             <description>
4793               Number of tags to scan for.
4794             </description>
4795         </param>
4796         <param id="tags">
4797           <inbuf incount="tag_count">
4798             <jlong/>
4799           </inbuf>
4800             <description>
4801               Scan for objects with these tags.
4802               Zero is not permitted in this array.
4803             </description>
4804         </param>
4805         <param id="count_ptr">
4806           <outptr>
4807             <jint/>
4808           </outptr>
4809             <description>
4810               Return the number of objects with any of the tags 
4811               in <paramlink id="tags"/>.
4812             </description>
4813         </param>
4814         <param id="object_result_ptr">
4815           <allocbuf outcount="count_ptr">
4816             <jobject/>
4817             <nullok>this information is not returned</nullok>
4818           </allocbuf>
4819             <description>
4820               Returns the array of objects with any of the tags 
4821               in <paramlink id="tags"/>.
4822             </description>
4823         </param>
4824         <param id="tag_result_ptr">
4825           <allocbuf outcount="count_ptr">
4826             <jlong/>
4827             <nullok>this information is not returned</nullok>
4828           </allocbuf>
4829             <description>
4830               For each object in <paramlink id="object_result_ptr"/>,
4831               return the tag at the corresponding index.
4832             </description>
4833         </param>
4834       </parameters>
4835       <errors>
4836         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
4837           Zero is present in <paramlink id="tags"></paramlink>.
4838         </error>
4839       </errors>
4840     </function>
4841 
4842     <function id="ForceGarbageCollection" num="108">
4843       <synopsis>Force Garbage Collection</synopsis>
4844       <description>
4845         Force the VM to perform a garbage collection.
4846         The garbage collection is as complete as possible.
4847         This function does not cause finalizers to be run.
4848         This function does not return until the garbage collection
4849         is finished.
4850         <p/>
4851         Although garbage collection is as complete 
4852         as possible there is no guarantee that all 
4853         <eventlink id="ObjectFree"/>
4854         events will have been 
4855         sent by the time that this function 
4856         returns. In particular, an object may be 
4857         prevented from being freed because it 
4858         is awaiting finalization.
4859       </description>
4860       <origin>new</origin>
4861       <capabilities>
4862       </capabilities>
4863       <parameters>
4864       </parameters>
4865       <errors>
4866       </errors>
4867     </function>
4868 
4869 
4870   </category>
4871 
4872   <category id="Heap_1_0" label="Heap (1.0)">
4873     <intro>
4874       <b>
4875         These functions and data types were introduced in the original 
4876         <jvmti/> version 1.0 and have been superseded by more
4877       </b>
4878       <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
4879       <b>
4880         which:
4881       </b>
4882       <ul>
4883         <li>
4884           <b>
4885             Allow access to primitive values (the value of Strings, arrays, 
4886             and primitive fields)
4887           </b>
4888         </li>
4889         <li>
4890           <b>
4891             Allow the tag of the referrer to be set, thus enabling more
4892             efficient localized reference graph building
4893           </b>
4894         </li>
4895         <li>
4896           <b>
4897             Provide more extensive filtering abilities
4898           </b>
4899         </li>
4900         <li>
4901           <b>
4902             Are extensible, allowing their abilities to grow in future versions of <jvmti/>
4903           </b>
4904         </li>
4905       </ul>
4906       <p/>
4907       <b>Please use the </b>
4908       <internallink id="Heap"><b>current Heap functions</b></internallink>.
4909         <p/>
4910         <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
4911           <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
4912             Tagged objects only.
4913           </constant>
4914           <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
4915             Untagged objects only.
4916           </constant>
4917           <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
4918             Either tagged or untagged objects.
4919           </constant>
4920         </constants>
4921 
4922         <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
4923           <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
4924             JNI global reference.
4925           </constant>
4926           <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
4927             System class.
4928           </constant>
4929           <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
4930             Monitor.
4931           </constant>
4932           <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
4933             Stack local.
4934           </constant>
4935           <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
4936             JNI local reference.
4937           </constant>
4938           <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
4939             Thread.
4940           </constant>
4941           <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
4942             Other.
4943           </constant>
4944         </constants>
4945 
4946         <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
4947           <constant id="JVMTI_REFERENCE_CLASS" num="1">
4948             Reference from an object to its class.
4949           </constant>       
4950           <constant id="JVMTI_REFERENCE_FIELD" num="2">
4951             Reference from an object to the value of one of its instance fields.
4952             For references of this kind the <code>referrer_index</code>
4953             parameter to the <internallink id="jvmtiObjectReferenceCallback">
4954             jvmtiObjectReferenceCallback</internallink> is the index of the
4955             the instance field. The index is based on the order of all the 
4956             object's fields. This includes all fields of the directly declared
4957             static and instance fields in the class, and includes all fields (both
4958             public and private) fields declared in superclasses and superinterfaces.
4959             The index is thus calculated by summing the index of the field in the directly
4960             declared class (see <functionlink id="GetClassFields"/>), with the total
4961             number of fields (both public and private) declared in all superclasses
4962             and superinterfaces. The index starts at zero.
4963           </constant>
4964           <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
4965             Reference from an array to one of its elements.
4966             For references of this kind the <code>referrer_index</code>
4967             parameter to the <internallink id="jvmtiObjectReferenceCallback">
4968             jvmtiObjectReferenceCallback</internallink> is the array index.
4969           </constant>
4970           <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
4971             Reference from a class to its class loader.
4972           </constant>
4973           <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
4974             Reference from a class to its signers array.
4975           </constant>
4976           <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
4977             Reference from a class to its protection domain.
4978           </constant>       
4979           <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
4980             Reference from a class to one of its interfaces.
4981           </constant>
4982           <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
4983             Reference from a class to the value of one of its static fields.
4984             For references of this kind the <code>referrer_index</code>
4985             parameter to the <internallink id="jvmtiObjectReferenceCallback">
4986             jvmtiObjectReferenceCallback</internallink> is the index of the
4987             the static field. The index is based on the order of all the 
4988             object's fields. This includes all fields of the directly declared
4989             static and instance fields in the class, and includes all fields (both
4990             public and private) fields declared in superclasses and superinterfaces.
4991             The index is thus calculated by summing the index of the field in the directly
4992             declared class (see <functionlink id="GetClassFields"/>), with the total
4993             number of fields (both public and private) declared in all superclasses
4994             and superinterfaces. The index starts at zero.
4995             Note: this definition differs from that in the <jvmti/> 1.0 Specification.
4996             <rationale>No known implementations used the 1.0 definition.</rationale>
4997           </constant>
4998           <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
4999             Reference from a class to a resolved entry in the constant pool.
5000             For references of this kind the <code>referrer_index</code>
5001             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5002             jvmtiObjectReferenceCallback</internallink> is the index into
5003             constant pool table of the class, starting at 1. See
5004             <vmspec chapter="4.4"/>.
5005           </constant>
5006         </constants>
5007 
5008         <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
5009           <constant id="JVMTI_ITERATION_CONTINUE" num="1">
5010             Continue the iteration.  
5011             If this is a reference iteration, follow the references of this object.
5012           </constant>       
5013           <constant id="JVMTI_ITERATION_IGNORE" num="2">
5014             Continue the iteration.  
5015             If this is a reference iteration, ignore the references of this object.
5016           </constant>
5017           <constant id="JVMTI_ITERATION_ABORT" num="0">
5018             Abort the iteration.
5019           </constant>
5020         </constants>
5021     </intro>
5022 
5023     <callback id="jvmtiHeapObjectCallback">
5024       <enum>jvmtiIterationControl</enum>
5025       <synopsis>Heap Object Callback</synopsis>
5026       <description>
5027         Agent supplied callback function.
5028         Describes (but does not pass in) an object in the heap.
5029         <p/>
5030         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5031         or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5032         <p/>
5033         See the <internallink id="heapCallbacks">heap callback
5034         function restrictions</internallink>.
5035       </description>
5036       <parameters>
5037         <param id="class_tag">
5038           <jlong/>
5039           <description>
5040             The tag of the class of object (zero if the class is not tagged). 
5041             If the object represents a runtime class, 
5042             the <code>class_tag</code> is the tag 
5043             associated with <code>java.lang.Class</code>
5044             (zero if <code>java.lang.Class</code> is not tagged).
5045           </description>
5046         </param>
5047         <param id="size">
5048           <jlong/>
5049           <description>
5050             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5051           </description>
5052         </param>
5053         <param id="tag_ptr">
5054           <outptr><jlong/></outptr>
5055           <description>
5056             The object tag value, or zero if the object is not tagged.
5057             To set the tag value to be associated with the object
5058             the agent sets the <code>jlong</code> pointed to by the parameter. 
5059           </description>
5060         </param>
5061         <param id="user_data">
5062           <outptr><void/></outptr>
5063           <description>
5064             The user supplied data that was passed into the iteration function. 
5065           </description>
5066         </param>
5067       </parameters>
5068     </callback>  
5069 
5070     <callback id="jvmtiHeapRootCallback">
5071       <enum>jvmtiIterationControl</enum>
5072       <synopsis>Heap Root Object Callback</synopsis>
5073       <description>
5074         Agent supplied callback function.
5075         Describes (but does not pass in) an object that is a root for the purposes
5076         of garbage collection.
5077         <p/>
5078         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5079         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5080         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5081         <p/>
5082         See the <internallink id="heapCallbacks">heap callback
5083         function restrictions</internallink>.
5084       </description>
5085       <parameters>
5086         <param id="root_kind">
5087           <enum>jvmtiHeapRootKind</enum>
5088           <description>
5089             The kind of heap root.
5090           </description>
5091         </param>
5092         <param id="class_tag">
5093           <jlong/>
5094           <description>
5095             The tag of the class of object (zero if the class is not tagged). 
5096             If the object represents a runtime class, the <code>class_tag</code> is the tag 
5097             associated with <code>java.lang.Class</code> 
5098             (zero if <code>java.lang.Class</code> is not tagged).
5099           </description>
5100         </param>
5101         <param id="size">
5102           <jlong/>
5103           <description>
5104             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5105           </description>
5106         </param>
5107         <param id="tag_ptr">
5108           <outptr><jlong/></outptr>
5109           <description>
5110             The object tag value, or zero if the object is not tagged.
5111             To set the tag value to be associated with the object
5112             the agent sets the <code>jlong</code> pointed to by the parameter.
5113           </description>
5114         </param>
5115         <param id="user_data">
5116           <outptr><void/></outptr>
5117           <description>
5118             The user supplied data that was passed into the iteration function. 
5119           </description>
5120         </param>
5121       </parameters>
5122     </callback> 
5123 
5124     <callback id="jvmtiStackReferenceCallback">
5125       <enum>jvmtiIterationControl</enum>
5126       <synopsis>Stack Reference Object Callback</synopsis>
5127       <description>
5128         Agent supplied callback function.
5129         Describes (but does not pass in) an object on the stack that is a root for 
5130         the purposes of garbage collection.
5131         <p/>
5132         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5133         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5134         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5135         <p/>
5136         See the <internallink id="heapCallbacks">heap callback
5137         function restrictions</internallink>.
5138       </description>
5139       <parameters>
5140         <param id="root_kind">
5141           <enum>jvmtiHeapRootKind</enum>
5142           <description>
5143             The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5144             <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
5145           </description>
5146         </param>
5147         <param id="class_tag">
5148           <jlong/>
5149           <description>
5150            The tag of the class of object (zero if the class is not tagged). 
5151            If the object represents a runtime class, the  <code>class_tag</code> is the tag 
5152            associated with <code>java.lang.Class</code> 
5153            (zero if <code>java.lang.Class</code> is not tagged).
5154           </description>
5155         </param>
5156         <param id="size">
5157           <jlong/>
5158           <description>
5159             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5160           </description>
5161         </param>
5162         <param id="tag_ptr">
5163           <outptr><jlong/></outptr>
5164           <description>
5165             The object tag value, or zero if the object is not tagged.
5166             To set the tag value to be associated with the object
5167             the agent sets the <code>jlong</code> pointed to by the parameter.
5168           </description>
5169         </param>
5170         <param id="thread_tag">
5171           <jlong/>
5172           <description>
5173             The tag of the thread corresponding to this stack, zero if not tagged.
5174           </description>
5175         </param>
5176         <param id="depth">
5177           <jint/>
5178           <description>
5179             The depth of the frame. 
5180           </description>
5181         </param>
5182         <param id="method">
5183           <jmethodID/>
5184           <description>
5185             The method executing in this frame.
5186           </description>
5187         </param>
5188         <param id="slot">
5189           <jint/>
5190           <description>
5191             The slot number.
5192           </description>
5193         </param>
5194         <param id="user_data">
5195           <outptr><void/></outptr>
5196           <description>
5197             The user supplied data that was passed into the iteration function. 
5198           </description>
5199         </param>
5200       </parameters>
5201     </callback>
5202 
5203     <callback id="jvmtiObjectReferenceCallback">
5204       <enum>jvmtiIterationControl</enum>
5205       <synopsis>Object Reference Callback</synopsis>
5206       <description>
5207         Agent supplied callback function.       
5208         Describes a reference from an object (the referrer) to another object
5209         (the referree).
5210         <p/>
5211         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5212         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5213         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5214         <p/>
5215         See the <internallink id="heapCallbacks">heap callback
5216         function restrictions</internallink>.
5217       </description>
5218       <parameters>
5219         <param id="reference_kind">
5220           <enum>jvmtiObjectReferenceKind</enum>
5221           <description>
5222             The type of reference.
5223           </description>
5224         </param>
5225         <param id="class_tag">
5226           <jlong/>
5227           <description>
5228             The tag of the class of referree object (zero if the class is not tagged). 
5229             If the referree object represents a runtime class,
5230             the  <code>class_tag</code> is the tag 
5231             associated with <code>java.lang.Class</code> 
5232             (zero if <code>java.lang.Class</code> is not tagged).
5233           </description>
5234         </param>
5235         <param id="size">
5236           <jlong/>
5237           <description>
5238             Size of the referree object (in bytes). 
5239             See <functionlink id="GetObjectSize"/>.
5240           </description>
5241         </param>
5242         <param id="tag_ptr">
5243           <outptr><jlong/></outptr>
5244           <description>
5245             The referree object tag value, or zero if the object is not 
5246             tagged.
5247             To set the tag value to be associated with the object
5248             the agent sets the <code>jlong</code> pointed to by the parameter.
5249           </description>
5250         </param>
5251         <param id="referrer_tag">
5252           <jlong/>
5253           <description>
5254             The tag of the referrer object, or zero if the referrer
5255             object is not tagged.
5256           </description>
5257         </param>
5258         <param id="referrer_index">
5259           <jint/>
5260           <description>       
5261             For references of type <code>JVMTI_REFERENCE_FIELD</code> or
5262             <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
5263             of the field in the referrer object. The index is based on the 
5264             order of all the object's fields - see <internallink 
5265             id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
5266             or <internallink
5267             id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
5268             </internallink> for further description.
5269             <p/>
5270             For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
5271             the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
5272             JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
5273             <p/>
5274             For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
5275             the index into the constant pool of the class - see
5276             <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
5277             JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further 
5278             description.
5279             <p/>
5280             For references of other kinds the <code>referrer_index</code> is
5281             <code>-1</code>.
5282           </description>
5283         </param>
5284         <param id="user_data">
5285           <outptr><void/></outptr>
5286           <description>
5287             The user supplied data that was passed into the iteration function. 
5288           </description>
5289         </param>
5290       </parameters>
5291     </callback>
5292 
5293     <function id="IterateOverObjectsReachableFromObject" num="109">
5294       <synopsis>Iterate Over Objects Reachable From Object</synopsis>
5295       <description>       
5296         This function iterates over all objects that are directly
5297         and indirectly reachable from the specified object.
5298         For each object <i>A</i> (known
5299         as the referrer) with a reference to object <i>B</i> the specified 
5300         callback function is called to describe the object reference.
5301         The callback is called exactly once for each reference from a referrer;
5302         this is true even if there are reference cycles or multiple paths to
5303         the referrer.
5304         There may be more than one reference between a referrer and a referree,
5305         These may be distinguished by the 
5306         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5307         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5308         The callback for an object will always occur after the callback for
5309         its referrer.
5310         <p/>
5311         See <functionlink id="FollowReferences"/> for the object
5312         references which are reported.
5313         <p/>
5314         During the execution of this function the state of the heap
5315         does not change: no objects are allocated, no objects are
5316         garbage collected, and the state of objects (including 
5317         held values) does not change. 
5318         As a result, threads executing Java 
5319         programming language code, threads attempting to resume the
5320         execution of Java programming language code, and threads 
5321         attempting to execute JNI functions are typically stalled.
5322       </description>
5323       <origin>new</origin>
5324       <capabilities>
5325         <required id="can_tag_objects"></required>
5326       </capabilities>
5327       <parameters>             
5328         <param id="object">
5329           <jobject/>
5330             <description>
5331               The object
5332             </description>
5333         </param>
5334         <param id="object_reference_callback">
5335           <ptrtype>
5336             <struct>jvmtiObjectReferenceCallback</struct>
5337           </ptrtype>
5338             <description>
5339               The callback to be called to describe each
5340               object reference.
5341             </description>
5342         </param>            
5343         <param id="user_data">
5344           <inbuf>
5345             <void/>
5346             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5347           </inbuf>
5348           <description>
5349             User supplied data to be passed to the callback. 
5350           </description>
5351         </param>
5352       </parameters>
5353       <errors>
5354       </errors>
5355     </function>
5356 
5357     <function id="IterateOverReachableObjects" num="110">
5358       <synopsis>Iterate Over Reachable Objects</synopsis>
5359       <description>
5360         This function iterates over the root objects and all objects that
5361         are directly and indirectly reachable from the root objects.
5362         The root objects comprise the set of system classes, 
5363         JNI globals, references from thread stacks, and other objects used as roots 
5364         for the purposes of garbage collection. 
5365         <p/>
5366         For each root the <paramlink id="heap_root_callback"></paramlink>
5367         or <paramlink id="stack_ref_callback"></paramlink> callback is called.
5368         An object can be a root object for more than one reason and in that case
5369         the appropriate callback is called for each reason.
5370         <p/>
5371         For each object reference the <paramlink id="object_ref_callback"></paramlink>
5372         callback function is called to describe the object reference.
5373         The callback is called exactly once for each reference from a referrer;
5374         this is true even if there are reference cycles or multiple paths to
5375         the referrer.
5376         There may be more than one reference between a referrer and a referree,
5377         These may be distinguished by the 
5378         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5379         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5380         The callback for an object will always occur after the callback for
5381         its referrer.
5382         <p/>
5383         See <functionlink id="FollowReferences"/> for the object
5384         references which are reported.
5385         <p/>
5386         Roots are always reported to the profiler before any object references
5387         are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> 
5388         callback will not be called until the appropriate callback has been called
5389         for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is 
5390         specified as <code>NULL</code> then this function returns after
5391         reporting the root objects to the profiler.
5392         <p/>
5393         During the execution of this function the state of the heap
5394         does not change: no objects are allocated, no objects are
5395         garbage collected, and the state of objects (including 
5396         held values) does not change. 
5397         As a result, threads executing Java 
5398         programming language code, threads attempting to resume the
5399         execution of Java programming language code, and threads 
5400         attempting to execute JNI functions are typically stalled.
5401       </description>
5402       <origin>new</origin>
5403       <capabilities>
5404         <required id="can_tag_objects"></required>
5405       </capabilities>
5406       <parameters>        
5407         <param id="heap_root_callback">
5408           <ptrtype>
5409             <struct>jvmtiHeapRootCallback</struct>
5410             <nullok>do not report heap roots</nullok>
5411           </ptrtype>
5412             <description>
5413               The callback function to be called for each heap root of type
5414               <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
5415               <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
5416               <code>JVMTI_HEAP_ROOT_MONITOR</code>,
5417               <code>JVMTI_HEAP_ROOT_THREAD</code>, or 
5418               <code>JVMTI_HEAP_ROOT_OTHER</code>.
5419             </description>
5420         </param>
5421         <param id="stack_ref_callback">
5422           <ptrtype>
5423             <struct>jvmtiStackReferenceCallback</struct>
5424             <nullok>do not report stack references</nullok>
5425           </ptrtype>
5426             <description>
5427               The callback function to be called for each heap root of
5428               <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5429               <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
5430             </description>
5431         </param>
5432         <param id="object_ref_callback">
5433           <ptrtype>
5434             <struct>jvmtiObjectReferenceCallback</struct>
5435             <nullok>do not follow references from the root objects</nullok>
5436           </ptrtype>
5437             <description>
5438               The callback function to be called for each object reference.
5439             </description>
5440         </param>
5441         <param id="user_data">
5442           <inbuf>
5443             <void/>
5444             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5445           </inbuf>
5446           <description>
5447             User supplied data to be passed to the callback. 
5448           </description>
5449         </param>
5450       </parameters>
5451       <errors>
5452       </errors>
5453     </function>
5454 
5455     <function id="IterateOverHeap" num="111">
5456       <synopsis>Iterate Over Heap</synopsis>
5457       <description>        
5458         Iterate over all objects in the heap. This includes both reachable and 
5459         unreachable objects.
5460         <p/>
5461         The <paramlink id="object_filter"></paramlink> parameter indicates the
5462         objects for which the callback function is called. If this parameter
5463         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 
5464         called for every object that is tagged. If the parameter is 
5465         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5466         for objects that are not tagged. If the parameter
5467         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5468         called for every object in the heap, irrespective of whether it is
5469         tagged or not.
5470         <p/>
5471         During the execution of this function the state of the heap
5472         does not change: no objects are allocated, no objects are
5473         garbage collected, and the state of objects (including 
5474         held values) does not change. 
5475         As a result, threads executing Java 
5476         programming language code, threads attempting to resume the
5477         execution of Java programming language code, and threads 
5478         attempting to execute JNI functions are typically stalled.
5479       </description>
5480       <origin>new</origin>
5481       <capabilities>
5482         <required id="can_tag_objects"></required>
5483       </capabilities>
5484       <parameters>
5485         <param id="object_filter">
5486           <enum>jvmtiHeapObjectFilter</enum>
5487           <description>
5488             Indicates the objects for which the callback function is called.
5489           </description>
5490         </param>
5491         <param id="heap_object_callback">
5492           <ptrtype>
5493             <struct>jvmtiHeapObjectCallback</struct>
5494           </ptrtype>
5495             <description>
5496               The iterator function to be called for each
5497               object matching the <paramlink id="object_filter"/>.
5498             </description>
5499         </param>
5500         <param id="user_data">
5501           <inbuf>
5502             <void/>
5503             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5504           </inbuf>
5505           <description>
5506             User supplied data to be passed to the callback. 
5507           </description>
5508         </param>
5509       </parameters>
5510       <errors>
5511       </errors>
5512     </function>
5513 
5514     <function id="IterateOverInstancesOfClass" num="112">
5515       <synopsis>Iterate Over Instances Of Class</synopsis>
5516       <description>
5517         Iterate over all objects in the heap that are instances of the specified class. 
5518         This includes direct instances of the specified class and 
5519         instances of all subclasses of the specified class.
5520         This includes both reachable and unreachable objects.
5521         <p/>
5522         The <paramlink id="object_filter"></paramlink> parameter indicates the
5523         objects for which the callback function is called. If this parameter
5524         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 
5525         called for every object that is tagged. If the parameter is 
5526         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5527         called for objects that are not tagged. If the parameter
5528         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5529         called for every object in the heap, irrespective of whether it is
5530         tagged or not.
5531         <p/>
5532         During the execution of this function the state of the heap
5533         does not change: no objects are allocated, no objects are
5534         garbage collected, and the state of objects (including 
5535         held values) does not change. 
5536         As a result, threads executing Java 
5537         programming language code, threads attempting to resume the
5538         execution of Java programming language code, and threads 
5539         attempting to execute JNI functions are typically stalled.
5540       </description>
5541       <origin>new</origin>
5542       <capabilities>
5543         <required id="can_tag_objects"></required>
5544       </capabilities>
5545       <parameters>
5546         <param id="klass">
5547           <jclass/>
5548             <description>
5549               Iterate over objects of this class only.
5550             </description>
5551         </param>
5552         <param id="object_filter">
5553           <enum>jvmtiHeapObjectFilter</enum>
5554           <description>
5555             Indicates the objects for which the callback function is called.
5556           </description>
5557         </param>
5558         <param id="heap_object_callback">
5559           <ptrtype>
5560             <struct>jvmtiHeapObjectCallback</struct>
5561           </ptrtype>
5562             <description>
5563               The iterator function to be called for each
5564               <paramlink id="klass"/> instance matching 
5565               the <paramlink id="object_filter"/>.
5566             </description>
5567         </param>
5568         <param id="user_data">
5569           <inbuf>
5570             <void/>
5571             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5572           </inbuf>
5573           <description>
5574             User supplied data to be passed to the callback. 
5575           </description>
5576         </param>
5577       </parameters>
5578       <errors>
5579       </errors>
5580     </function>
5581 
5582   </category>
5583 
5584   <category id="local" label="Local Variable">
5585 
5586     <intro>
5587       These functions are used to retrieve or set the value of a local variable. 
5588       The variable is identified by the depth of the frame containing its
5589       value and the variable's slot number within that frame. 
5590       The mapping of variables to 
5591       slot numbers can be obtained with the function 
5592       <functionlink id="GetLocalVariableTable"></functionlink>.
5593     </intro>
5594 
5595     <function id="GetLocalObject" num="21">
5596       <synopsis>Get Local Variable - Object</synopsis>
5597       <description>
5598         This function can be used to retrieve the value of a local 
5599         variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 
5600       </description>
5601       <origin>jvmdi</origin>
5602       <capabilities>
5603         <required id="can_access_local_variables"></required>
5604       </capabilities>
5605       <parameters>
5606         <param id="thread">
5607           <jthread null="current" frame="frame"/>
5608           <description>
5609             The thread of the frame containing the variable's value.
5610           </description>
5611         </param>
5612         <param id="depth">
5613           <jframeID thread="thread"/>
5614           <description>
5615             The depth of the frame containing the variable's value.
5616           </description>
5617         </param>
5618         <param id="slot">
5619           <jint/>
5620           <description>
5621             The variable's slot number.
5622           </description>
5623         </param>
5624         <param id="value_ptr">
5625           <outptr><jobject/></outptr>
5626             <description>
5627               On return, points to the variable's value. 
5628             </description>
5629         </param>
5630       </parameters>
5631       <errors>
5632         <error id="JVMTI_ERROR_INVALID_SLOT">
5633           Invalid <code>slot</code>.
5634         </error>
5635         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5636           The variable type is not
5637           <code>Object</code> or a subclass of <code>Object</code>.
5638         </error>
5639         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5640           Not a visible frame
5641         </error>
5642       </errors>
5643     </function>
5644 
5645     <function id="GetLocalInstance" num="155" since="1.2">
5646       <synopsis>Get Local Instance</synopsis>
5647       <description>
5648         This function can be used to retrieve the value of the local object
5649         variable at slot 0 (the "<code>this</code>" object) from non-static
5650         frames.  This function can retrieve the "<code>this</code>" object from
5651         native method frames, whereas <code>GetLocalObject()</code> would 
5652         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5653       </description>
5654       <origin>new</origin>
5655       <capabilities>
5656         <required id="can_access_local_variables"></required>
5657       </capabilities>
5658       <parameters>
5659         <param id="thread">
5660           <jthread null="current" frame="frame"/>
5661           <description>
5662             The thread of the frame containing the variable's value.
5663           </description>
5664         </param>
5665         <param id="depth">
5666           <jframeID thread="thread"/>
5667           <description>
5668             The depth of the frame containing the variable's value.
5669           </description>
5670         </param>
5671         <param id="value_ptr">
5672           <outptr><jobject/></outptr>
5673             <description>
5674               On return, points to the variable's value. 
5675             </description>
5676         </param>
5677       </parameters>
5678       <errors>
5679         <error id="JVMTI_ERROR_INVALID_SLOT">
5680           If the specified frame is a static method frame.
5681         </error>
5682       </errors>
5683     </function>
5684     <function id="GetLocalInt" num="22">
5685       <synopsis>Get Local Variable - Int</synopsis>
5686       <description>
5687         This function can be used to retrieve the value of a local 
5688         variable whose type is <code>int</code>,
5689         <code>short</code>, <code>char</code>, <code>byte</code>, or 
5690         <code>boolean</code>. 
5691       </description>
5692       <origin>jvmdi</origin>
5693       <capabilities>
5694         <required id="can_access_local_variables"></required>
5695       </capabilities>
5696       <parameters>
5697         <param id="thread">
5698           <jthread null="current" frame="frame"/>
5699           <description>
5700             The thread of the frame containing the variable's value.
5701           </description>
5702         </param>
5703         <param id="depth">
5704           <jframeID thread="thread"/>
5705           <description>
5706             The depth of the frame containing the variable's value.
5707           </description>
5708         </param>
5709         <param id="slot">
5710           <jint/>
5711           <description>
5712             The variable's slot number.
5713           </description>
5714         </param>
5715         <param id="value_ptr">
5716           <outptr><jint/></outptr>
5717           <description>
5718             On return, points to the variable's value. 
5719           </description>
5720         </param>
5721       </parameters>
5722       <errors>
5723         <error id="JVMTI_ERROR_INVALID_SLOT">
5724           Invalid <code>slot</code>.
5725         </error>
5726         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5727           The variable type is not 
5728           <code>int</code>, <code>short</code>,
5729           <code>char</code>, <code>byte</code>, or 
5730           <code>boolean</code>.
5731         </error>
5732         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5733           Not a visible frame
5734         </error>
5735       </errors>
5736     </function>
5737 
5738     <function id="GetLocalLong" num="23">
5739       <synopsis>Get Local Variable - Long</synopsis>
5740       <description>
5741         This function can be used to retrieve the value of a local 
5742         variable whose type is <code>long</code>. 
5743       </description>
5744       <origin>jvmdi</origin>
5745       <capabilities>
5746         <required id="can_access_local_variables"></required>
5747       </capabilities>
5748       <parameters>
5749         <param id="thread">
5750           <jthread null="current" frame="frame"/>
5751           <description>
5752             The thread of the frame containing the variable's value.
5753           </description>
5754         </param>
5755         <param id="depth">
5756           <jframeID thread="thread"/>
5757           <description>
5758             The depth of the frame containing the variable's value.
5759           </description>
5760         </param>
5761         <param id="slot">
5762           <jint/>
5763           <description>
5764             The variable's slot number.
5765           </description>
5766         </param>
5767         <param id="value_ptr">
5768           <outptr><jlong/></outptr>
5769           <description>
5770             On return, points to the variable's value. 
5771           </description>
5772         </param>
5773       </parameters>
5774       <errors>
5775         <error id="JVMTI_ERROR_INVALID_SLOT">
5776           Invalid <code>slot</code>.
5777         </error>
5778         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5779           The variable type is not <code>long</code>.
5780         </error>
5781         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5782           Not a visible frame
5783         </error>
5784       </errors>
5785     </function>
5786 
5787     <function id="GetLocalFloat" num="24">
5788       <synopsis>Get Local Variable - Float</synopsis>
5789       <description>
5790         This function can be used to retrieve the value of a local 
5791         variable whose type is <code>float</code>. 
5792       </description>
5793       <origin>jvmdi</origin>
5794       <capabilities>
5795         <required id="can_access_local_variables"></required>
5796       </capabilities>
5797       <parameters>
5798         <param id="thread">
5799           <jthread null="current" frame="frame"/>
5800           <description>
5801             The thread of the frame containing the variable's value.
5802           </description>
5803         </param>
5804         <param id="depth">
5805           <jframeID thread="thread"/>
5806           <description>
5807             The depth of the frame containing the variable's value.
5808           </description>
5809         </param>
5810         <param id="slot">
5811           <jint/>
5812           <description>
5813             The variable's slot number.
5814           </description>
5815         </param>
5816         <param id="value_ptr">
5817           <outptr><jfloat/></outptr>
5818           <description>
5819             On return, points to the variable's value. 
5820           </description>
5821         </param>
5822       </parameters>
5823       <errors>
5824         <error id="JVMTI_ERROR_INVALID_SLOT">
5825           Invalid <code>slot</code>.
5826         </error>
5827         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5828           The variable type is not <code>float</code>.
5829         </error>
5830         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5831           Not a visible frame
5832         </error>
5833       </errors>
5834     </function>
5835 
5836     <function id="GetLocalDouble" num="25">
5837       <synopsis>Get Local Variable - Double</synopsis>
5838       <description>
5839         This function can be used to retrieve the value of a local 
5840         variable whose type is <code>long</code>. 
5841       </description>
5842       <origin>jvmdi</origin>
5843       <capabilities>
5844         <required id="can_access_local_variables"></required>
5845       </capabilities>
5846       <parameters>
5847         <param id="thread">
5848           <jthread null="current" frame="frame"/>
5849           <description>
5850             The thread of the frame containing the variable's value.
5851           </description>
5852         </param>
5853         <param id="depth">
5854           <jframeID thread="thread"/>
5855           <description>
5856             The depth of the frame containing the variable's value.
5857           </description>
5858         </param>
5859         <param id="slot">
5860           <jint/>
5861           <description>
5862             The variable's slot number.
5863           </description>
5864         </param>
5865         <param id="value_ptr">
5866           <outptr><jdouble/></outptr>
5867           <description>
5868             On return, points to the variable's value. 
5869           </description>
5870         </param>
5871       </parameters>
5872       <errors>
5873         <error id="JVMTI_ERROR_INVALID_SLOT">
5874           Invalid <code>slot</code>.
5875         </error>
5876         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5877           The variable type is not <code>double</code>.
5878         </error>
5879         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5880           Not a visible frame
5881         </error>
5882       </errors>
5883     </function>
5884 
5885     <function id="SetLocalObject" num="26">
5886       <synopsis>Set Local Variable - Object</synopsis>
5887       <description>
5888         This function can be used to set the value of a local 
5889         variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 
5890       </description>
5891       <origin>jvmdi</origin>
5892       <capabilities>
5893         <required id="can_access_local_variables"></required>
5894       </capabilities>
5895       <parameters>
5896         <param id="thread">
5897           <jthread null="current" frame="frame"/>
5898           <description>
5899             The thread of the frame containing the variable's value.
5900           </description>
5901         </param>
5902         <param id="depth">
5903           <jframeID thread="thread"/>
5904           <description>
5905             The depth of the frame containing the variable's value.
5906           </description>
5907         </param>
5908         <param id="slot">
5909           <jint/>
5910           <description>
5911             The variable's slot number.
5912           </description>
5913         </param>
5914         <param id="value">
5915           <jobject/>
5916             <description>
5917               The new value for the variable.
5918             </description>
5919         </param>
5920       </parameters>
5921       <errors>
5922         <error id="JVMTI_ERROR_INVALID_SLOT">
5923           Invalid <code>slot</code>.
5924         </error>
5925         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5926           The variable type is not
5927           <code>Object</code> or a subclass of <code>Object</code>.
5928         </error>
5929         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5930           The supplied <paramlink id="value"/> is not compatible 
5931           with the variable type.
5932         </error>
5933         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5934           Not a visible frame
5935         </error>
5936       </errors>
5937     </function>
5938 
5939     <function id="SetLocalInt" num="27">
5940       <synopsis>Set Local Variable - Int</synopsis>
5941       <description>
5942         This function can be used to set the value of a local 
5943         variable whose type is <code>int</code>,
5944         <code>short</code>, <code>char</code>, <code>byte</code>, or 
5945         <code>boolean</code>. 
5946       </description>
5947       <origin>jvmdi</origin>
5948       <capabilities>
5949         <required id="can_access_local_variables"></required>
5950       </capabilities>
5951       <parameters>
5952         <param id="thread">
5953           <jthread null="current" frame="frame"/>
5954           <description>
5955             The thread of the frame containing the variable's value.
5956           </description>
5957         </param>
5958         <param id="depth">
5959           <jframeID thread="thread"/>
5960           <description>
5961             The depth of the frame containing the variable's value.
5962           </description>
5963         </param>
5964         <param id="slot">
5965           <jint/>
5966           <description>
5967             The variable's slot number.
5968           </description>
5969         </param>
5970         <param id="value">
5971           <jint/>
5972           <description>
5973             The new value for the variable.
5974           </description>
5975         </param>
5976       </parameters>
5977       <errors>
5978         <error id="JVMTI_ERROR_INVALID_SLOT">
5979           Invalid <code>slot</code>.
5980         </error>
5981         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5982           The variable type is not 
5983           <code>int</code>, <code>short</code>,
5984           <code>char</code>, <code>byte</code>, or 
5985           <code>boolean</code>.
5986         </error>
5987         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5988           Not a visible frame
5989         </error>
5990       </errors>
5991     </function>
5992 
5993     <function id="SetLocalLong" num="28">
5994       <synopsis>Set Local Variable - Long</synopsis>
5995       <description>
5996         This function can be used to set the value of a local 
5997         variable whose type is <code>long</code>. 
5998       </description>
5999       <origin>jvmdi</origin>
6000       <capabilities>
6001         <required id="can_access_local_variables"></required>
6002       </capabilities>
6003       <parameters>
6004         <param id="thread">
6005           <jthread null="current" frame="frame"/>
6006           <description>
6007             The thread of the frame containing the variable's value.
6008           </description>
6009         </param>
6010         <param id="depth">
6011           <jframeID thread="thread"/>
6012           <description>
6013             The depth of the frame containing the variable's value.
6014           </description>
6015         </param>
6016         <param id="slot">
6017           <jint/>
6018           <description>
6019             The variable's slot number.
6020           </description>
6021         </param>
6022         <param id="value">
6023           <jlong/>
6024           <description>
6025             The new value for the variable.
6026           </description>
6027         </param>
6028       </parameters>
6029       <errors>
6030         <error id="JVMTI_ERROR_INVALID_SLOT">
6031           Invalid <code>slot</code>.
6032         </error>
6033         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6034           The variable type is not <code>long</code>.
6035         </error>
6036         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6037           Not a visible frame
6038         </error>
6039       </errors>
6040     </function>
6041 
6042     <function id="SetLocalFloat" num="29">
6043       <synopsis>Set Local Variable - Float</synopsis>
6044       <description>
6045         This function can be used to set the value of a local 
6046         variable whose type is <code>float</code>. 
6047       </description>
6048       <origin>jvmdi</origin>
6049       <capabilities>
6050         <required id="can_access_local_variables"></required>
6051       </capabilities>
6052       <parameters>
6053         <param id="thread">
6054           <jthread null="current" frame="frame"/>
6055           <description>
6056             The thread of the frame containing the variable's value.
6057           </description>
6058         </param>
6059         <param id="depth">
6060           <jframeID thread="thread"/>
6061           <description>
6062             The depth of the frame containing the variable's value.
6063           </description>
6064         </param>
6065         <param id="slot">
6066           <jint/>
6067           <description>
6068             The variable's slot number.
6069           </description>
6070         </param>
6071         <param id="value">
6072           <jfloat/>
6073           <description>
6074             The new value for the variable.
6075           </description>
6076         </param>
6077       </parameters>
6078       <errors>
6079         <error id="JVMTI_ERROR_INVALID_SLOT">
6080           Invalid <code>slot</code>.
6081         </error>
6082         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6083           The variable type is not <code>float</code>.
6084         </error>
6085         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6086           Not a visible frame
6087         </error>
6088       </errors>
6089     </function>
6090 
6091     <function id="SetLocalDouble" num="30">
6092       <synopsis>Set Local Variable - Double</synopsis>
6093       <description>
6094         This function can be used to set the value of a local 
6095         variable whose type is <code>double</code>. 
6096       </description>
6097       <origin>jvmdi</origin>
6098       <capabilities>
6099         <required id="can_access_local_variables"></required>
6100       </capabilities>
6101       <parameters>
6102         <param id="thread">
6103           <jthread null="current" frame="frame"/>
6104           <description>
6105             The thread of the frame containing the variable's value.
6106           </description>
6107         </param>
6108         <param id="depth">
6109           <jframeID thread="thread"/>
6110           <description>
6111             The depth of the frame containing the variable's value.
6112           </description>
6113         </param>
6114         <param id="slot">
6115           <jint/>
6116           <description>
6117             The variable's slot number.
6118           </description>
6119         </param>
6120         <param id="value">
6121           <jdouble/>
6122           <description>
6123             The new value for the variable.
6124           </description>
6125         </param>
6126       </parameters>
6127       <errors>
6128         <error id="JVMTI_ERROR_INVALID_SLOT">
6129           Invalid <code>slot</code>.
6130         </error>
6131         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6132           The variable type is not <code>double</code>.
6133         </error>
6134         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6135           Not a visible frame
6136         </error>
6137       </errors>
6138     </function>
6139   </category>
6140 
6141   <category id="breakpointCategory" label="Breakpoint">
6142 
6143     <intro>
6144     </intro>
6145 
6146     <function id="SetBreakpoint" num="38">
6147       <synopsis>Set Breakpoint</synopsis>
6148       <description>
6149         Set a breakpoint at the instruction indicated by
6150         <code>method</code> and <code>location</code>.
6151         An instruction can only have one breakpoint.
6152         <p/>
6153         Whenever the designated instruction is about to be executed, a
6154         <eventlink id="Breakpoint"></eventlink> event is generated.
6155       </description>
6156       <origin>jvmdi</origin>
6157       <capabilities>
6158         <required id="can_generate_breakpoint_events"></required>
6159       </capabilities>
6160       <parameters>
6161         <param id="klass">
6162           <jclass method="method"/>
6163             <description>
6164               The class in which to set the breakpoint
6165             </description>
6166         </param>
6167         <param id="method">
6168           <jmethodID class="klass"/>
6169             <description>
6170               The method in which to set the breakpoint
6171             </description>
6172         </param>
6173         <param id="location">
6174           <jlocation/>
6175           <description>
6176             the index of the instruction at which to set the breakpoint
6177 
6178           </description>
6179         </param>
6180       </parameters>
6181       <errors>
6182         <error id="JVMTI_ERROR_DUPLICATE"> 
6183           The designated bytecode already has a breakpoint.
6184         </error>
6185       </errors>
6186     </function>
6187 
6188     <function id="ClearBreakpoint" num="39">
6189       <synopsis>Clear Breakpoint</synopsis>
6190       <description>
6191         Clear the breakpoint at the bytecode indicated by
6192         <code>method</code> and <code>location</code>.
6193       </description>
6194       <origin>jvmdi</origin>
6195       <capabilities>
6196         <required id="can_generate_breakpoint_events"></required>
6197       </capabilities>
6198       <parameters>
6199         <param id="klass">
6200           <jclass method="method"/>
6201             <description>
6202               The class in which to clear the breakpoint
6203             </description>
6204         </param>
6205         <param id="method">
6206           <jmethodID class="klass"/>
6207             <description>
6208               The method in which to clear the breakpoint
6209             </description>
6210         </param>
6211         <param id="location">
6212           <jlocation/>
6213           <description>
6214             the index of the instruction at which to clear the breakpoint
6215           </description>
6216         </param>
6217       </parameters>
6218       <errors>
6219         <error id="JVMTI_ERROR_NOT_FOUND"> 
6220           There's no breakpoint at the designated bytecode.
6221         </error>
6222       </errors>
6223     </function>
6224 
6225   </category>
6226 
6227   <category id="fieldWatch" label="Watched Field">
6228 
6229     <intro>
6230     </intro>
6231 
6232     <function id="SetFieldAccessWatch" num="41">
6233       <synopsis>Set Field Access Watch</synopsis>
6234       <description>
6235         Generate a <eventlink id="FieldAccess"></eventlink> event
6236         when the field specified
6237         by <code>klass</code> and
6238         <code>field</code> is about to be accessed.
6239         An event will be generated for each access of the field
6240         until it is canceled with 
6241         <functionlink id="ClearFieldAccessWatch"></functionlink>.
6242         Field accesses from Java programming language code or from JNI code are watched,
6243         fields modified by other means are not watched.
6244         Note that <jvmti/> users should be aware that their own field accesses
6245         will trigger the watch.
6246         A field can only have one field access watch set.
6247         Modification of a field is not considered an access--use 
6248         <functionlink id="SetFieldModificationWatch"></functionlink>
6249         to monitor modifications.
6250       </description>
6251       <origin>jvmdi</origin>
6252       <capabilities>
6253         <required id="can_generate_field_access_events"></required>
6254       </capabilities>
6255       <parameters>
6256         <param id="klass">
6257           <jclass field="field"/>
6258             <description>
6259               The class containing the field to watch
6260             </description>
6261         </param>
6262         <param id="field">
6263           <jfieldID class="klass"/>
6264             <description>
6265               The field to watch
6266 
6267             </description>
6268         </param>
6269       </parameters>
6270       <errors>
6271         <error id="JVMTI_ERROR_DUPLICATE"> 
6272           The designated field is already being watched for accesses.
6273         </error>
6274       </errors>
6275     </function>
6276 
6277     <function id="ClearFieldAccessWatch" num="42">
6278       <synopsis>Clear Field Access Watch</synopsis>
6279       <description>
6280         Cancel a field access watch previously set by 
6281         <functionlink id="SetFieldAccessWatch"></functionlink>, on the 
6282         field specified
6283         by <code>klass</code> and
6284         <code>field</code>.
6285       </description>
6286       <origin>jvmdi</origin>
6287       <capabilities>
6288         <required id="can_generate_field_access_events"></required>
6289       </capabilities>
6290       <parameters>
6291         <param id="klass">
6292           <jclass field="field"/>
6293             <description>
6294               The class containing the field to watch
6295             </description>
6296         </param>
6297         <param id="field">
6298           <jfieldID class="klass"/>
6299             <description>
6300               The field to watch
6301 
6302             </description>
6303         </param>
6304       </parameters>
6305       <errors>
6306         <error id="JVMTI_ERROR_NOT_FOUND"> 
6307           The designated field is not being watched for accesses.
6308         </error>
6309       </errors>
6310     </function>
6311 
6312     <function id="SetFieldModificationWatch" num="43">
6313       <synopsis>Set Field Modification Watch</synopsis>
6314       <description>
6315         Generate a <eventlink id="FieldModification"></eventlink> event
6316         when the field specified
6317         by <code>klass</code> and
6318         <code>field</code> is about to be modified.
6319         An event will be generated for each modification of the field
6320         until it is canceled with 
6321         <functionlink id="ClearFieldModificationWatch"></functionlink>.
6322         Field modifications from Java programming language code or from JNI code are watched,
6323         fields modified by other means are not watched.
6324         Note that <jvmti/> users should be aware that their own field modifications
6325         will trigger the watch.
6326         A field can only have one field modification watch set.
6327       </description>
6328       <origin>jvmdi</origin>
6329       <capabilities>
6330         <required id="can_generate_field_modification_events"></required>
6331       </capabilities>
6332       <parameters>
6333         <param id="klass">
6334           <jclass field="field"/>
6335             <description>
6336               The class containing the field to watch
6337             </description>
6338         </param>
6339         <param id="field">
6340           <jfieldID class="klass"/>
6341             <description>
6342               The field to watch
6343 
6344             </description>
6345         </param>
6346       </parameters>
6347       <errors>
6348         <error id="JVMTI_ERROR_DUPLICATE"> 
6349           The designated field is already being watched for modifications.
6350         </error>
6351       </errors>
6352     </function>
6353 
6354     <function id="ClearFieldModificationWatch" num="44">
6355       <synopsis>Clear Field Modification Watch</synopsis>
6356       <description>
6357 
6358         Cancel a field modification watch previously set by 
6359         <functionlink id="SetFieldModificationWatch"></functionlink>, on the 
6360         field specified
6361         by <code>klass</code> and
6362         <code>field</code>.
6363       </description>
6364       <origin>jvmdi</origin>
6365       <capabilities>
6366         <required id="can_generate_field_modification_events"></required>
6367       </capabilities>
6368       <parameters>
6369         <param id="klass">
6370           <jclass field="field"/>
6371             <description>
6372               The class containing the field to watch
6373             </description>
6374         </param>
6375         <param id="field">
6376           <jfieldID class="klass"/>
6377             <description>
6378               The field to watch
6379 
6380             </description>
6381         </param>
6382       </parameters>
6383       <errors>
6384         <error id="JVMTI_ERROR_NOT_FOUND"> 
6385           The designated field is not being watched for modifications.
6386         </error>
6387       </errors>
6388     </function>
6389   </category>
6390 
6391   <category id="class" label="Class">
6392 
6393     <intro>
6394     </intro>
6395 
6396     <function id="GetLoadedClasses" jkernel="yes" num="78">
6397       <synopsis>Get Loaded Classes</synopsis>
6398       <description>
6399         Return an array of all classes loaded in the virtual machine.
6400         The number of classes in the array is returned via
6401         <code>class_count_ptr</code>, and the array itself via
6402         <code>classes_ptr</code>.
6403         <p/>
6404         Array classes of all types (including arrays of primitive types) are 
6405         included in the returned list. Primitive classes (for example, 
6406         <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. 
6407       </description>
6408       <origin>jvmdi</origin>
6409       <capabilities>
6410       </capabilities>
6411       <parameters>
6412         <param id="class_count_ptr">
6413           <outptr><jint/></outptr>
6414           <description>
6415             On return, points to the number of classes.
6416           </description>
6417         </param>
6418         <param id="classes_ptr">
6419           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6420             <description>
6421               On return, points to an array of references, one
6422               for each class.
6423             </description>
6424         </param>
6425       </parameters>
6426       <errors>
6427       </errors>
6428     </function>
6429 
6430     <function id="GetClassLoaderClasses" jkernel="yes" num="79">
6431       <synopsis>Get Classloader Classes</synopsis>
6432       <description>
6433         Returns an array of those classes for which this class loader has
6434         been recorded as an initiating loader. Each 
6435         class in the returned array was created by this class loader, 
6436         either by defining it directly or by delegation to another class loader.
6437         See <vmspec chapter="5.3"/>.
6438         <p/>
6439         For JDK version 1.1 implementations that don't
6440         recognize the distinction between initiating and defining class loaders,
6441         this function should return all classes loaded in the virtual machine.
6442         The number of classes in the array is returned via
6443         <code>class_count_ptr</code>, and the array itself via
6444         <code>classes_ptr</code>.
6445       </description>
6446       <origin>jvmdi</origin>
6447       <capabilities>
6448       </capabilities>
6449       <parameters>
6450         <param id="initiating_loader">
6451           <ptrtype>
6452             <jobject/>
6453             <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
6454           </ptrtype>
6455             <description>
6456               An initiating class loader.
6457             </description>
6458         </param>
6459         <param id="class_count_ptr">
6460           <outptr><jint/></outptr>
6461           <description>
6462             On return, points to the number of classes.
6463           </description>
6464         </param>
6465         <param id="classes_ptr">
6466           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6467             <description>
6468               On return, points to an array of references, one
6469               for each class.
6470             </description>
6471         </param>
6472       </parameters>
6473       <errors>
6474       </errors>
6475     </function>
6476 
6477     <function id="GetClassSignature" phase="start" num="48">
6478       <synopsis>Get Class Signature</synopsis>
6479       <description>
6480         For the class indicated by <code>klass</code>, return the 
6481         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI 
6482             type signature</externallink> 
6483         and the generic signature of the class.
6484         For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
6485         and <code>int[]</code> is <code>"[I"</code>
6486         The returned name for primitive classes
6487         is the type signature character of the corresponding primitive type. 
6488         For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
6489       </description>
6490       <origin>jvmdiClone</origin>
6491       <capabilities>
6492       </capabilities>
6493       <parameters>
6494         <param id="klass">
6495           <jclass/>
6496             <description>
6497               The class to query.
6498             </description>
6499         </param>
6500         <param id="signature_ptr">
6501           <allocbuf>
6502             <char/>           
6503             <nullok>the signature is not returned</nullok>
6504           </allocbuf>
6505           <description>
6506             On return, points to the JNI type signature of the class, encoded as a
6507             <internallink id="mUTF">modified UTF-8</internallink> string.
6508           </description>
6509         </param>
6510         <param id="generic_ptr">
6511           <allocbuf>
6512             <char/>           
6513             <nullok>the generic signature is not returned</nullok>
6514           </allocbuf>
6515           <description>
6516             On return, points to the generic signature of the class, encoded as a
6517             <internallink id="mUTF">modified UTF-8</internallink> string.
6518             If there is no generic signature attribute for the class, then,
6519             on return, points to <code>NULL</code>. 
6520           </description>
6521         </param>
6522       </parameters>
6523       <errors>
6524       </errors>
6525     </function>
6526 
6527     <function id="GetClassStatus" phase="start" num="49">
6528       <synopsis>Get Class Status</synopsis>
6529       <description>
6530         Get the status of the class. Zero or more of the following bits can be 
6531         set.
6532         <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
6533           <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
6534             Class bytecodes have been verified
6535           </constant>
6536           <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
6537             Class preparation is complete
6538           </constant>
6539           <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
6540             Class initialization is complete. Static initializer has been run.
6541           </constant>
6542           <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
6543             Error during initialization makes class unusable
6544           </constant>
6545           <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
6546             Class is an array.  If set, all other bits are zero.
6547           </constant>
6548           <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
6549             Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).  
6550             If set, all other bits are zero.
6551           </constant>
6552         </constants>
6553       </description>
6554       <origin>jvmdi</origin>
6555       <capabilities>
6556       </capabilities>
6557       <parameters>
6558         <param id="klass">
6559           <jclass/>
6560             <description>
6561               The class to query.
6562             </description>
6563         </param>
6564         <param id="status_ptr">
6565           <outptr><jint/></outptr>
6566           <description>
6567             On return, points to the current state of this class as one or 
6568             more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
6569           </description>
6570         </param>
6571       </parameters>
6572       <errors>
6573       </errors>
6574     </function>
6575 
6576     <function id="GetSourceFileName" phase="start" num="50">
6577       <synopsis>Get Source File Name</synopsis>
6578       <description>
6579         For the class indicated by <code>klass</code>, return the source file
6580         name via <code>source_name_ptr</code>. The returned string 
6581         is a file name only and never contains a directory name. 
6582         <p/>
6583         For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) 
6584         and for arrays this function returns 
6585         <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
6586       </description>
6587       <origin>jvmdi</origin>
6588       <capabilities>
6589         <required id="can_get_source_file_name"></required>
6590       </capabilities>
6591       <parameters>
6592         <param id="klass">
6593           <jclass/>
6594             <description>
6595               The class to query.
6596             </description>
6597         </param>
6598         <param id="source_name_ptr">
6599           <allocbuf><char/></allocbuf>
6600           <description>
6601             On return, points to the class's source file name, encoded as a
6602             <internallink id="mUTF">modified UTF-8</internallink> string.
6603           </description>
6604         </param>
6605       </parameters>
6606       <errors>
6607         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
6608           Class information does not include a source file name. This includes
6609           cases where the class is an array class or primitive class.
6610         </error>
6611       </errors>
6612     </function>
6613 
6614     <function id="GetClassModifiers" phase="start" num="51">
6615       <synopsis>Get Class Modifiers</synopsis>
6616       <description>
6617         For the class indicated by <code>klass</code>, return the access
6618         flags
6619         via <code>modifiers_ptr</code>.
6620         Access flags are defined in <vmspec chapter="4"/>.
6621         <p/>
6622         If the class is an array class, then its public, private, and protected 
6623         modifiers are the same as those of its component type. For arrays of 
6624         primitives, this component type is represented by one of the primitive 
6625         classes (for example, <code>java.lang.Integer.TYPE</code>). 
6626         <p/>
6627         If the class is a primitive class, its public modifier is always true, 
6628         and its protected and private modifiers are always false. 
6629         <p/>
6630         If the class is an array class or a primitive class then its final 
6631         modifier is always true and its interface modifier is always false. 
6632         The values of its other modifiers are not determined by this specification. 
6633 
6634       </description>
6635       <origin>jvmdi</origin>
6636       <capabilities>
6637       </capabilities>
6638       <parameters>
6639         <param id="klass">
6640           <jclass/>
6641             <description>
6642               The class to query.
6643             </description>
6644         </param>
6645         <param id="modifiers_ptr">
6646           <outptr><jint/></outptr>
6647           <description>
6648             On return, points to the current access flags of this class.
6649 
6650           </description>
6651         </param>
6652       </parameters>
6653       <errors>
6654       </errors>
6655     </function>
6656 
6657     <function id="GetClassMethods" phase="start" num="52">
6658       <synopsis>Get Class Methods</synopsis>
6659       <description>
6660         For the class indicated by <code>klass</code>, return a count of
6661         methods via <code>method_count_ptr</code> and a list of
6662         method IDs via <code>methods_ptr</code>. The method list contains 
6663         constructors and static initializers as well as true methods.
6664         Only directly declared methods are returned (not inherited methods).
6665         An empty method list is returned for array classes and primitive classes
6666         (for example, <code>java.lang.Integer.TYPE</code>).
6667       </description>
6668       <origin>jvmdi</origin>
6669       <capabilities>
6670         <capability id="can_maintain_original_method_order"/>
6671       </capabilities>
6672       <parameters>
6673         <param id="klass">
6674           <jclass/>
6675             <description>
6676               The class to query.
6677             </description>
6678         </param>
6679         <param id="method_count_ptr">
6680           <outptr><jint/></outptr>
6681           <description>
6682             On return, points to the number of methods declared in this class.
6683           </description>
6684         </param>
6685         <param id="methods_ptr">
6686           <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
6687             <description>
6688               On return, points to the method ID array.
6689             </description>
6690         </param>
6691       </parameters>
6692       <errors>
6693         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
6694           <paramlink id="klass"></paramlink> is not prepared.
6695         </error>
6696       </errors>
6697     </function>
6698 
6699     <function id="GetClassFields" phase="start" num="53">
6700       <synopsis>Get Class Fields</synopsis>
6701       <description>
6702         For the class indicated by <code>klass</code>, return a count of fields
6703         via <code>field_count_ptr</code> and a list of field IDs via
6704         <code>fields_ptr</code>.
6705         Only directly declared fields are returned (not inherited fields).
6706         Fields are returned in the order they occur in the class file.
6707         An empty field list is returned for array classes and primitive classes
6708         (for example, <code>java.lang.Integer.TYPE</code>).
6709         Use JNI to determine the length of an array.
6710       </description>
6711       <origin>jvmdi</origin>
6712       <capabilities>
6713       </capabilities>
6714       <parameters>
6715         <param id="klass">
6716           <jclass/>
6717             <description>
6718               The class to query.
6719             </description>
6720         </param>
6721         <param id="field_count_ptr">
6722           <outptr><jint/></outptr>
6723           <description>
6724             On return, points to the number of fields declared in this class.
6725           </description>
6726         </param>
6727         <param id="fields_ptr">
6728           <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
6729             <description>
6730               On return, points to the field ID array.
6731             </description>
6732         </param>
6733       </parameters>
6734       <errors>
6735         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 
6736           <paramlink id="klass"></paramlink> is not prepared.
6737         </error>
6738       </errors>
6739     </function>
6740 
6741     <function id="GetImplementedInterfaces" phase="start" num="54">
6742       <synopsis>Get Implemented Interfaces</synopsis>
6743       <description>
6744         Return the direct super-interfaces of this class. For a class, this 
6745         function returns the interfaces declared in its <code>implements</code>
6746         clause. For an interface, this function returns the interfaces declared in
6747         its <code>extends</code> clause.
6748         An empty interface list is returned for array classes and primitive classes
6749         (for example, <code>java.lang.Integer.TYPE</code>).
6750       </description>
6751       <origin>jvmdi</origin>
6752       <capabilities>
6753       </capabilities>
6754       <parameters>
6755         <param id="klass">
6756           <jclass/>
6757             <description>
6758               The class to query.
6759             </description>
6760         </param>
6761         <param id="interface_count_ptr">
6762           <outptr><jint/></outptr>
6763           <description>
6764             On return, points to the number of interfaces.
6765           </description>
6766         </param>
6767         <param id="interfaces_ptr">
6768           <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
6769             <description>
6770               On return, points to the interface array.
6771             </description>
6772         </param>
6773       </parameters>
6774       <errors>
6775         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 
6776           <paramlink id="klass"></paramlink> is not prepared.
6777         </error>
6778       </errors>
6779     </function>
6780 
6781     <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
6782       <synopsis>Get Class Version Numbers</synopsis>
6783       <description>
6784         For the class indicated by <code>klass</code>, 
6785         return the minor and major version numbers,
6786         as defined in
6787         <vmspec chapter="4"/>. 
6788       </description>
6789       <origin>new</origin>
6790       <capabilities>
6791       </capabilities>
6792       <parameters>
6793         <param id="klass">
6794           <jclass/>
6795             <description>
6796               The class to query.
6797             </description>
6798         </param>
6799         <param id="minor_version_ptr">
6800           <outptr><jint/></outptr>
6801           <description>
6802             On return, points to the value of the
6803             <code>minor_version</code> item of the 
6804             Class File Format.
6805             Note: to be consistent with the Class File Format,
6806             the minor version number is the first parameter.
6807           </description>
6808         </param>
6809         <param id="major_version_ptr">
6810           <outptr><jint/></outptr>
6811           <description>
6812             On return, points to the value of the
6813             <code>major_version</code> item of the 
6814             Class File Format.
6815           </description>
6816         </param>
6817       </parameters>
6818       <errors>
6819         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
6820           The class is a primitive or array class.
6821         </error>
6822       </errors>
6823     </function>
6824 
6825     <function id="GetConstantPool" phase="start" num="146" since="1.1">
6826       <synopsis>Get Constant Pool</synopsis>
6827       <description>
6828         For the class indicated by <code>klass</code>, 
6829         return the raw bytes of the constant pool in the format of the
6830         <code>constant_pool</code> item of 
6831         <vmspec chapter="4"/>.
6832         The format of the constant pool may differ between versions
6833         of the Class File Format, so, the 
6834         <functionlink id="GetClassVersionNumbers">minor and major 
6835         class version numbers</functionlink> should be checked for
6836         compatibility.
6837         <p/>
6838         The returned constant pool might not have the same layout or
6839         contents as the constant pool in the defining class file.
6840         The constant pool returned by GetConstantPool() may have
6841         more or fewer entries than the defining constant pool.
6842         Entries may be in a different order.
6843         The constant pool returned by GetConstantPool() will match the
6844         constant pool used by 
6845         <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
6846         That is, the bytecodes returned by GetBytecodes() will have
6847         constant pool indices which refer to constant pool entries returned
6848         by GetConstantPool().
6849         Note that since <functionlink id="RetransformClasses"/> 
6850         and <functionlink id="RedefineClasses"/> can change 
6851         the constant pool, the constant pool returned by this function
6852         can change accordingly.  Thus, the correspondence between 
6853         GetConstantPool() and GetBytecodes() does not hold if there
6854         is an intervening class retransformation or redefinition. 
6855         The value of a constant pool entry used by a given bytecode will
6856         match that of the defining class file (even if the indices don't match).
6857         Constant pool entries which are not used directly or indirectly by
6858         bytecodes (for example,  UTF-8 strings associated with annotations) are
6859         not  required to exist in the returned constant pool.
6860       </description>
6861       <origin>new</origin>
6862       <capabilities>
6863         <required id="can_get_constant_pool"></required>
6864       </capabilities>
6865       <parameters>
6866         <param id="klass">
6867           <jclass/>
6868             <description>
6869               The class to query.
6870             </description>
6871         </param>
6872         <param id="constant_pool_count_ptr">
6873           <outptr><jint/></outptr>
6874           <description>
6875             On return, points to the number of entries
6876             in the constant pool table plus one.
6877             This corresponds to the <code>constant_pool_count</code>
6878             item of the Class File Format.
6879           </description>
6880         </param>
6881         <param id="constant_pool_byte_count_ptr">
6882           <outptr><jint/></outptr>
6883           <description>
6884             On return, points to the number of bytes
6885             in the returned raw constant pool.
6886           </description>
6887         </param>
6888         <param id="constant_pool_bytes_ptr">
6889           <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
6890             <description>
6891               On return, points to the raw constant pool, that is the bytes
6892               defined by the <code>constant_pool</code> item of the 
6893               Class File Format
6894             </description>
6895         </param>
6896       </parameters>
6897       <errors>
6898         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
6899           The class is a primitive or array class.
6900         </error>
6901       </errors>
6902     </function>
6903 
6904     <function id="IsInterface" phase="start" num="55">
6905       <synopsis>Is Interface</synopsis>
6906       <description>
6907         Determines whether a class object reference represents an interface.
6908         The <code>jboolean</code> result is
6909         <code>JNI_TRUE</code> if the "class" is actually an interface,
6910         <code>JNI_FALSE</code> otherwise. 
6911       </description>
6912       <origin>jvmdi</origin>
6913       <capabilities>
6914       </capabilities>
6915       <parameters>
6916         <param id="klass">
6917           <jclass/>
6918             <description>
6919               The class to query.
6920             </description>
6921         </param>
6922         <param id="is_interface_ptr">
6923           <outptr><jboolean/></outptr>
6924           <description>
6925             On return, points to the boolean result of this function.
6926 
6927           </description>
6928         </param>
6929       </parameters>
6930       <errors>
6931       </errors>
6932     </function>
6933 
6934     <function id="IsArrayClass" phase="start" num="56">
6935       <synopsis>Is Array Class</synopsis>
6936       <description>
6937         Determines whether a class object reference represents an array.
6938         The <code>jboolean</code> result is
6939         <code>JNI_TRUE</code> if the class is an array,
6940         <code>JNI_FALSE</code> otherwise. 
6941       </description>
6942       <origin>jvmdi</origin>
6943       <capabilities>
6944       </capabilities>
6945       <parameters>
6946         <param id="klass">
6947           <jclass/>
6948             <description>
6949               The class to query.
6950             </description>
6951         </param>
6952         <param id="is_array_class_ptr">
6953           <outptr><jboolean/></outptr>
6954           <description>
6955             On return, points to the boolean result of this function.
6956 
6957           </description>
6958         </param>
6959       </parameters>
6960       <errors>
6961       </errors>
6962     </function>
6963 
6964     <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
6965       <synopsis>Is Modifiable Class</synopsis>
6966       <description>
6967         Determines whether a class is modifiable.
6968         If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
6969         returns <code>JNI_TRUE</code>) the class can be
6970         redefined with <functionlink id="RedefineClasses"/> (assuming 
6971         the agent possesses the
6972         <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
6973         capability) or
6974         retransformed with <functionlink id="RetransformClasses"/> (assuming 
6975         the agent possesses the
6976         <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
6977         capability).
6978         If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
6979         returns <code>JNI_FALSE</code>) the class can be neither
6980         redefined nor retransformed.
6981         <p/>
6982         Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) 
6983         and array classes are never modifiable. 
6984         <p/>
6985       </description>
6986       <origin>new</origin>
6987       <capabilities>
6988         <capability id="can_redefine_any_class">
6989           If possessed then all classes (except primitive and array classes) 
6990           are modifiable.
6991         </capability>
6992         <capability id="can_redefine_classes">
6993           No effect on the result of the function.
6994           But must additionally be possessed to modify the class with
6995           <functionlink id="RedefineClasses"/>.
6996         </capability>
6997         <capability id="can_retransform_classes">
6998           No effect on the result of the function.
6999           But must additionally be possessed to modify the class with
7000           <functionlink id="RetransformClasses"/>.
7001         </capability>
7002       </capabilities>
7003       <parameters>
7004         <param id="klass">
7005           <jclass/>
7006             <description>
7007               The class to query.
7008             </description>
7009         </param>
7010         <param id="is_modifiable_class_ptr">
7011           <outptr><jboolean/></outptr>
7012           <description>
7013             On return, points to the boolean result of this function.
7014           </description>
7015         </param>
7016       </parameters>
7017       <errors>
7018       </errors>
7019     </function>
7020 
7021     <function id="GetClassLoader" phase="start" num="57">
7022       <synopsis>Get Class Loader</synopsis>
7023       <description>
7024         For the class indicated by <code>klass</code>, return via
7025         <code>classloader_ptr</code> a reference to the class loader for the
7026         class.
7027       </description>
7028       <origin>jvmdi</origin>
7029       <capabilities>
7030       </capabilities>
7031       <parameters>
7032         <param id="klass">
7033           <jclass/>
7034             <description>
7035               The class to query.
7036             </description>
7037         </param>
7038         <param id="classloader_ptr">
7039           <outptr><jobject/></outptr>
7040             <description>
7041               On return, points to the class loader that loaded
7042               this class.
7043               If the class was not created by a class loader
7044               or if the class loader is the bootstrap class loader,
7045               points to <code>NULL</code>.
7046             </description>
7047         </param>
7048       </parameters>
7049       <errors>
7050       </errors>
7051 
7052     </function>
7053 
7054     <function id="GetSourceDebugExtension" phase="start" num="90">
7055       <synopsis>Get Source Debug Extension</synopsis>
7056       <description>
7057         For the class indicated by <code>klass</code>, return the debug 
7058         extension via <code>source_debug_extension_ptr</code>.
7059         The returned string 
7060         contains exactly the debug extension information present in the
7061         class file of <code>klass</code>. 
7062       </description>
7063       <origin>jvmdi</origin>
7064       <capabilities>
7065         <required id="can_get_source_debug_extension"></required>
7066       </capabilities>
7067       <parameters>
7068         <param id="klass">
7069           <jclass/>
7070             <description>
7071               The class to query.
7072             </description>
7073         </param>
7074         <param id="source_debug_extension_ptr">
7075           <allocbuf><char/></allocbuf>
7076           <description>
7077             On return, points to the class's debug extension, encoded as a
7078             <internallink id="mUTF">modified UTF-8</internallink> string.
7079           </description>
7080         </param>
7081       </parameters>
7082       <errors>
7083         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
7084           Class information does not include a debug extension.
7085         </error>
7086       </errors>
7087     </function>
7088 
7089     <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
7090       <synopsis>Retransform Classes</synopsis>
7091       <description>
7092         This function facilitates the 
7093         <internallink id="bci">bytecode instrumentation</internallink>
7094         of already loaded classes.
7095         To replace the class definition without reference to the existing
7096         bytecodes, as one might do when recompiling from source for 
7097         fix-and-continue debugging, <functionlink id="RedefineClasses"/>
7098         function should be used instead.
7099         <p/>
7100         When classes are initially loaded or when they are 
7101         <functionlink id="RedefineClasses">redefined</functionlink>,
7102         the initial class file bytes can be transformed with the
7103         <eventlink id="ClassFileLoadHook"/> event.
7104         This function reruns the transformation process
7105         (whether or not a transformation has previously occurred).
7106         This retransformation follows these steps:
7107         <ul>
7108           <li>starting from the initial class file bytes 
7109           </li>
7110           <li>for each <fieldlink id="can_retransform_classes"
7111                      struct="jvmtiCapabilities">retransformation
7112                                                 incapable</fieldlink>
7113             agent which received a
7114             <code>ClassFileLoadHook</code> event during the previous
7115             load or redefine, the bytes it returned 
7116             (via the <code>new_class_data</code> parameter)
7117             are reused as the output of the transformation; 
7118             note that this is equivalent to reapplying
7119             the previous transformation, unaltered. except that
7120             the <code>ClassFileLoadHook</code> event
7121             is <b>not</b> sent to these agents
7122           </li>
7123           <li>for each <fieldlink id="can_retransform_classes"
7124                      struct="jvmtiCapabilities">retransformation
7125                                                 capable</fieldlink>
7126             agent, the <code>ClassFileLoadHook</code> event is sent,
7127             allowing a new transformation to be applied
7128           </li>
7129           <li>the transformed class file bytes are installed as the new
7130             definition of the class
7131           </li>
7132         </ul>
7133         See the <eventlink id="ClassFileLoadHook"/> event for more details.
7134         <p/>
7135         The initial class file bytes represent the bytes passed to 
7136         <code>ClassLoader.defineClass</code>
7137         or <code>RedefineClasses</code> (before any transformations
7138         were applied), however they may not exactly match them.
7139         The constant pool may differ in ways described in
7140         <functionlink id="GetConstantPool"/>.
7141         Constant pool indices in the bytecodes of methods will correspond.
7142         Some attributes may not be present.
7143         Where order is not meaningful, for example the order of methods,
7144         order may not be preserved.
7145         <p/>
7146         Retransformation can cause new versions of methods to be installed.
7147         Old method versions may become 
7148         <internallink id="obsoleteMethods">obsolete</internallink>
7149         The new method version will be used on new invokes.  
7150         If a method has active stack frames, those active frames continue to
7151         run the bytecodes of the original method version. 
7152         <p/>
7153         This function does not cause any initialization except that which 
7154         would occur under the customary JVM semantics.
7155         In other words, retransforming a class does not cause its initializers to be
7156         run. The values of static fields will remain as they were
7157         prior to the call.
7158         <p/>
7159         Threads need not be suspended.
7160         <p/>
7161         All breakpoints in the class are cleared.
7162         <p/>
7163         All attributes are updated.
7164         <p/>
7165         Instances of the retransformed class are not affected -- fields retain their
7166         previous values.  
7167         <functionlink id="GetTag">Tags</functionlink> on the instances are
7168         also unaffected.
7169         <p/>
7170         In response to this call, no events other than the
7171         <eventlink id="ClassFileLoadHook"/> event
7172         will be sent.
7173         <p/>
7174         The retransformation may change method bodies, the constant pool and attributes.
7175         The retransformation must not add, remove or rename fields or methods, change the 
7176         signatures of methods, change modifiers, or change inheritance.  
7177         These restrictions may be lifted in future versions.
7178         See the error return description below for information on error codes
7179         returned if an unsupported retransformation is attempted.
7180         The class file bytes are not verified or installed until they have passed
7181         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7182         returned error code reflects the result of the transformations.
7183         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7184         none of the classes to be retransformed will have a new definition installed.
7185         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7186         all of the classes to be retransformed will have their new definitions installed.        
7187       </description>
7188       <origin>new</origin>
7189       <capabilities>
7190         <required id="can_retransform_classes"></required>
7191         <capability id="can_retransform_any_class"></capability>
7192       </capabilities>
7193       <parameters>
7194         <param id="class_count">
7195           <jint min="0"/>
7196           <description>
7197             The number of classes to be retransformed.
7198           </description>
7199         </param>
7200         <param id="classes">
7201           <inbuf incount="class_count"><jclass/></inbuf>
7202           <description>
7203             The array of classes to be retransformed.
7204           </description>
7205         </param>
7206       </parameters>
7207       <errors>
7208         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7209           One of the <paramlink id="classes"/> cannot be modified. 
7210           See <functionlink id="IsModifiableClass"/>.
7211         </error>
7212         <error id="JVMTI_ERROR_INVALID_CLASS">
7213           One of the <paramlink id="classes"/> is not a valid class.
7214         </error>
7215         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7216           A retransformed class file has a version number not supported by this VM.
7217         </error>
7218         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7219           A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>).
7220         </error>
7221         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7222           The retransformed class file definitions would lead to a circular definition 
7223           (the VM would return a <code>ClassCircularityError</code>).
7224         </error>
7225         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7226           The retransformed class file bytes fail verification.
7227         </error>
7228         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7229           The class name defined in a retransformed class file is
7230           different from the name in the old class object.
7231         </error>
7232         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7233           A retransformed class file would require adding a method.
7234         </error>
7235         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7236           A retransformed class file changes a field.
7237         </error>
7238         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7239           A direct superclass is different for a retransformed class file,
7240           or the set of directly implemented
7241           interfaces is different.
7242         </error>
7243         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7244           A retransformed class file does not declare a method
7245           declared in the old class version.
7246         </error>
7247         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7248           A retransformed class file has different class modifiers.
7249         </error>
7250         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7251           A method in the retransformed class file has different modifiers
7252           than its counterpart in the old class version.
7253         </error>
7254       </errors>
7255     </function>
7256 
7257     <function id="RedefineClasses" jkernel="yes" num="87">
7258       <synopsis>Redefine Classes</synopsis>
7259       <typedef id="jvmtiClassDefinition" label="Class redefinition description">
7260         <field id="klass">
7261           <jclass/>
7262             <description>
7263               Class object for this class
7264             </description>
7265         </field>
7266         <field id="class_byte_count">
7267           <jint/>
7268           <description>
7269             Number of bytes defining class (below)
7270           </description>
7271         </field>
7272         <field id="class_bytes">
7273           <inbuf incount="class_byte_count"><uchar/></inbuf>
7274           <description>
7275             Bytes defining class (in <vmspec chapter="4"/>)
7276           </description>
7277         </field>
7278       </typedef>
7279       <description>
7280         All classes given are redefined according to the definitions
7281         supplied.
7282         This function is used to replace the definition of a class
7283         with a new definition, as might be needed in fix-and-continue
7284         debugging.
7285         Where the existing class file bytes are to be transformed, for 
7286         example in
7287         <internallink id="bci">bytecode instrumentation</internallink>,
7288         <functionlink id="RetransformClasses"/> should be used.
7289         <p/>
7290         Redefinition can cause new versions of methods to be installed.
7291         Old method versions may become 
7292         <internallink id="obsoleteMethods">obsolete</internallink>
7293         The new method version will be used on new invokes.  
7294         If a method has active stack frames, those active frames continue to
7295         run the bytecodes of the original method version. 
7296         If resetting of stack frames is desired, use 
7297         <functionlink id="PopFrame"></functionlink>
7298         to pop frames with obsolete method versions.
7299         <p/>
7300         This function does not cause any initialization except that which 
7301         would occur under the customary JVM semantics.
7302         In other words, redefining a class does not cause its initializers to be
7303         run. The values of static fields will remain as they were
7304         prior to the call.
7305         <p/>
7306         Threads need not be suspended.
7307         <p/>
7308         All breakpoints in the class are cleared.
7309         <p/>
7310         All attributes are updated.
7311         <p/>
7312         Instances of the redefined class are not affected -- fields retain their
7313         previous values.  
7314         <functionlink id="GetTag">Tags</functionlink> on the instances are
7315         also unaffected.
7316         <p/>
7317         In response to this call, the <jvmti/> event
7318         <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
7319         will be sent (if enabled), but no other <jvmti/> events will be sent.
7320         <p/>
7321         The redefinition may change method bodies, the constant pool and attributes.
7322         The redefinition must not add, remove or rename fields or methods, change the 
7323         signatures of methods, change modifiers, or change inheritance.  
7324         These restrictions may be lifted in future versions.
7325         See the error return description below for information on error codes
7326         returned if an unsupported redefinition is attempted.
7327         The class file bytes are not verified or installed until they have passed
7328         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7329         returned error code reflects the result of the transformations applied
7330         to the bytes passed into <paramlink id="class_definitions"/>.
7331         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7332         none of the classes to be redefined will have a new definition installed.
7333         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7334         all of the classes to be redefined will have their new definitions installed.        
7335       </description>
7336       <origin>jvmdi</origin>
7337       <capabilities>
7338         <required id="can_redefine_classes"></required>
7339         <capability id="can_redefine_any_class"></capability>
7340       </capabilities>
7341       <parameters>
7342         <param id="class_count">
7343           <jint min="0"/>
7344           <description>
7345             The number of classes specified in <code>class_definitions</code>
7346           </description>
7347         </param>
7348         <param id="class_definitions">
7349           <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
7350           <description>
7351             The array of new class definitions
7352           </description>
7353         </param>
7354       </parameters>
7355       <errors>
7356         <error id="JVMTI_ERROR_NULL_POINTER">
7357           One of <code>class_bytes</code> is <code>NULL</code>.
7358         </error>
7359         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7360           An element of <code>class_definitions</code> cannot be modified.
7361           See <functionlink id="IsModifiableClass"/>.
7362         </error>
7363         <error id="JVMTI_ERROR_INVALID_CLASS">
7364           An element of <code>class_definitions</code> is not a valid class.
7365         </error>
7366         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7367           A new class file has a version number not supported by this VM.
7368         </error>
7369         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7370           A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
7371         </error>
7372         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7373           The new class file definitions would lead to a circular definition 
7374           (the VM would return a <code>ClassCircularityError</code>).
7375         </error>
7376         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7377           The class bytes fail verification.
7378         </error>
7379         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7380           The class name defined in a new class file is
7381           different from the name in the old class object.
7382         </error>
7383         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7384           A new class file would require adding a method.
7385         </error>
7386         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7387           A new class version changes a field.
7388         </error>
7389         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7390           A direct superclass is different for a new class
7391           version, or the set of directly implemented
7392           interfaces is different.
7393         </error>
7394         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7395           A new class version does not declare a method
7396           declared in the old class version.
7397         </error>
7398         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7399           A new class version has different modifiers.
7400         </error>
7401         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7402           A method in the new class version has different modifiers
7403           than its counterpart in the old class version.
7404         </error>
7405       </errors>
7406     </function>
7407 
7408   </category>
7409 
7410   <category id="object" label="Object">
7411 
7412     <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
7413       <synopsis>Get Object Size</synopsis>
7414       <description>
7415         For the object indicated by <code>object</code>,
7416         return via <code>size_ptr</code> the size of the object.
7417         This size is an implementation-specific approximation of
7418         the amount of storage consumed by this object. 
7419         It may include some or all of the object's overhead, and thus
7420         is useful for comparison within an implementation but not
7421         between implementations.
7422         The estimate may change during a single invocation of the JVM.
7423       </description>
7424       <origin>new</origin>
7425       <capabilities>
7426       </capabilities>
7427       <parameters>
7428         <param id="object">
7429           <jobject/>
7430             <description>
7431               The object to query.
7432             </description>
7433         </param>
7434         <param id="size_ptr">
7435           <outptr><jlong/></outptr>
7436           <description>
7437             On return, points to the object's size in bytes.
7438           </description>
7439         </param>
7440       </parameters>
7441       <errors>
7442       </errors>
7443     </function>
7444 
7445     <function id="GetObjectHashCode" phase="start" num="58">
7446       <synopsis>Get Object Hash Code</synopsis>
7447       <description>
7448         For the object indicated by <code>object</code>,
7449         return via <code>hash_code_ptr</code> a hash code.
7450         This hash code could be used to maintain a hash table of object references,
7451         however, on some implementations this can cause significant performance 
7452         impacts--in most cases 
7453         <internallink id="Heap">tags</internallink> 
7454         will be a more efficient means of associating information with objects.
7455         This function guarantees 
7456         the same hash code value for a particular object throughout its life
7457       </description>
7458       <origin>jvmdi</origin>
7459       <capabilities>
7460       </capabilities>
7461       <parameters>
7462         <param id="object">
7463           <jobject/>
7464             <description>
7465               The object to query.
7466             </description>
7467         </param>
7468         <param id="hash_code_ptr">
7469           <outptr><jint/></outptr>
7470           <description>
7471             On return, points to the object's hash code.
7472           </description>
7473         </param>
7474       </parameters>
7475       <errors>
7476       </errors>
7477     </function>
7478 
7479     <function id="GetObjectMonitorUsage" num="59">
7480       <synopsis>Get Object Monitor Usage</synopsis>
7481       <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
7482         <field id="owner">
7483           <jthread/>
7484             <description>
7485               The thread owning this monitor, or <code>NULL</code> if unused
7486             </description>
7487         </field>
7488         <field id="entry_count">
7489           <jint/>
7490           <description>
7491             The number of times the owning thread has entered the monitor
7492           </description>
7493         </field>
7494         <field id="waiter_count">
7495           <jint/>
7496           <description>
7497             The number of threads waiting to own this monitor
7498           </description>
7499         </field>
7500         <field id="waiters">
7501           <allocfieldbuf><jthread/></allocfieldbuf>
7502             <description>
7503               The <code>waiter_count</code> waiting threads
7504             </description>
7505         </field>
7506         <field id="notify_waiter_count">
7507           <jint/>
7508           <description>
7509             The number of threads waiting to be notified by this monitor
7510           </description>
7511         </field>
7512         <field id="notify_waiters">
7513           <allocfieldbuf><jthread/></allocfieldbuf>
7514             <description>
7515               The <code>notify_waiter_count</code> threads waiting to be notified
7516             </description>
7517         </field>
7518       </typedef>
7519       <description>
7520         Get information about the object's monitor.
7521         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 
7522         are filled in with information about usage of the monitor.
7523           <todo>
7524             Decide and then clarify suspend requirements.
7525           </todo>
7526       </description>
7527       <origin>jvmdi</origin>
7528       <capabilities>
7529         <required id="can_get_monitor_info"></required>
7530       </capabilities>
7531       <parameters>
7532         <param id="object">
7533           <jobject/>
7534             <description>
7535               The object to query.
7536             </description>
7537         </param>
7538         <param id="info_ptr">
7539           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
7540           <description>
7541             On return, filled with monitor information for the 
7542             specified object.
7543           </description>
7544         </param>
7545       </parameters>
7546       <errors>
7547       </errors>
7548     </function>
7549 
7550     <elide>
7551     <function id="GetObjectMonitors" num="116">
7552       <synopsis>Get Object Monitors</synopsis>
7553       <description>
7554         Return the list of object monitors.
7555         <p/>
7556         Note: details about each monitor can be examined with 
7557         <functionlink id="GetObjectMonitorUsage"></functionlink>.
7558       </description>
7559       <origin>new</origin>
7560       <capabilities>
7561         <required id="can_get_monitor_info"></required>
7562       </capabilities>
7563       <parameters>
7564         <param id="monitorCnt">
7565           <outptr><jint/></outptr>
7566           <description>
7567             On return, pointer to the number 
7568             of monitors returned in <code>monitors_ptr</code>.
7569           </description>
7570         </param>
7571         <param id="monitors_ptr">
7572           <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
7573             <description>
7574               On return, pointer to the monitor list.
7575             </description>
7576         </param>
7577       </parameters>
7578       <errors>
7579       </errors>
7580     </function>
7581     </elide>
7582 
7583   </category>
7584 
7585   <category id="fieldCategory" label="Field">
7586 
7587     <intro>
7588     </intro>
7589 
7590     <function id="GetFieldName" phase="start" num="60">
7591       <synopsis>Get Field Name (and Signature)</synopsis>
7592       <description>
7593         For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
7594         return the field name via <paramlink id="name_ptr"/> and field signature via
7595         <paramlink id="signature_ptr"/>.
7596         <p/>
7597         Field signatures are defined in the JNI Specification and 
7598         are referred to as <code>field descriptors</code> in
7599         <vmspec chapter="4.3.2"/>.
7600       </description>
7601       <origin>jvmdiClone</origin>
7602       <capabilities>
7603       </capabilities>
7604       <parameters>
7605         <param id="klass">
7606           <jclass field="field"/>
7607             <description>
7608               The class of the field to query.
7609             </description>
7610         </param>
7611         <param id="field">
7612           <jfieldID class="klass"/>
7613             <description>
7614               The field to query.
7615             </description>
7616         </param>
7617         <param id="name_ptr">
7618           <allocbuf>
7619             <char/>
7620             <nullok>the name is not returned</nullok>
7621           </allocbuf>
7622           <description>
7623             On return, points to the field name, encoded as a
7624             <internallink id="mUTF">modified UTF-8</internallink> string.
7625           </description>
7626         </param>
7627         <param id="signature_ptr">
7628           <allocbuf>
7629             <char/>
7630             <nullok>the signature is not returned</nullok>
7631           </allocbuf>
7632           <description>
7633             On return, points to the field signature, encoded as a
7634             <internallink id="mUTF">modified UTF-8</internallink> string.
7635           </description>
7636         </param>
7637         <param id="generic_ptr">
7638           <allocbuf>
7639             <char/>           
7640             <nullok>the generic signature is not returned</nullok>
7641           </allocbuf>
7642           <description>
7643             On return, points to the generic signature of the field, encoded as a
7644             <internallink id="mUTF">modified UTF-8</internallink> string.
7645             If there is no generic signature attribute for the field, then,
7646             on return, points to <code>NULL</code>. 
7647           </description>
7648         </param>
7649       </parameters>
7650       <errors>
7651       </errors>
7652     </function>
7653 
7654     <function id="GetFieldDeclaringClass" phase="start" num="61">
7655       <synopsis>Get Field Declaring Class</synopsis>
7656       <description>
7657         For the field indicated by <code>klass</code> and <code>field</code>
7658         return the class that defined it via <code>declaring_class_ptr</code>.
7659         The declaring class will either be <code>klass</code>, a superclass, or
7660         an implemented interface.
7661       </description>
7662       <origin>jvmdi</origin>
7663       <capabilities>
7664       </capabilities>
7665       <parameters>
7666         <param id="klass">
7667           <jclass field="field"/>
7668             <description>
7669               The class to query.
7670             </description>
7671         </param>
7672         <param id="field">
7673           <jfieldID class="klass"/>
7674             <description>
7675               The field to query.
7676             </description>
7677         </param>
7678         <param id="declaring_class_ptr">
7679           <outptr><jclass/></outptr>
7680             <description>
7681               On return, points to the declaring class
7682             </description>
7683         </param>
7684       </parameters>
7685       <errors>
7686       </errors>
7687     </function>
7688 
7689     <function id="GetFieldModifiers" phase="start" num="62">
7690       <synopsis>Get Field Modifiers</synopsis>
7691       <description>
7692         For the field indicated by <code>klass</code> and <code>field</code>
7693         return the access flags via <code>modifiers_ptr</code>.
7694         Access flags are defined in <vmspec chapter="4"/>.
7695       </description>
7696       <origin>jvmdi</origin>
7697       <capabilities>
7698       </capabilities>
7699       <parameters>
7700         <param id="klass">
7701           <jclass field="field"/>
7702             <description>
7703               The class to query.
7704             </description>
7705         </param>
7706         <param id="field">
7707           <jfieldID class="klass"/>
7708             <description>
7709               The field to query.
7710             </description>
7711         </param>
7712         <param id="modifiers_ptr">
7713           <outptr><jint/></outptr>
7714           <description>
7715             On return, points to the access flags.
7716           </description>
7717         </param>
7718       </parameters>
7719       <errors>
7720       </errors>
7721     </function>
7722 
7723     <function id="IsFieldSynthetic" phase="start" num="63">
7724       <synopsis>Is Field Synthetic</synopsis>
7725       <description>
7726         For the field indicated by <code>klass</code> and <code>field</code>, return a
7727         value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
7728         Synthetic fields are generated by the compiler but not present in the 
7729         original source code.
7730       </description>
7731       <origin>jvmdi</origin>
7732       <capabilities>
7733         <required id="can_get_synthetic_attribute"></required>
7734       </capabilities>
7735       <parameters>
7736         <param id="klass">
7737           <jclass field="field"/>
7738             <description>
7739               The class of the field to query.
7740             </description>
7741         </param>
7742         <param id="field">
7743           <jfieldID class="klass"/>
7744             <description>
7745               The field to query.
7746             </description>
7747         </param>
7748         <param id="is_synthetic_ptr">
7749           <outptr><jboolean/></outptr>
7750           <description>
7751             On return, points to the boolean result of this function.
7752           </description>
7753         </param>
7754       </parameters>
7755       <errors>
7756       </errors>
7757     </function>
7758 
7759   </category>
7760 
7761   <category id="method" label="Method">
7762 
7763     <intro>
7764       These functions provide information about a method (represented as a
7765       <typelink id="jmethodID"/>) and set how methods are processed.
7766     </intro>
7767 
7768     <intro id="obsoleteMethods" label="Obsolete Methods">
7769       The functions <functionlink id="RetransformClasses"/> and
7770       <functionlink id="RedefineClasses"/> can cause new versions
7771       of methods to be installed.
7772       An original version of a method is considered equivalent
7773       to the new version if:
7774       <ul>
7775         <li>their bytecodes are the same except for indices into the
7776           constant pool and </li>
7777         <li>the referenced constants are equal.</li>
7778       </ul>
7779       An original method version which is not equivalent to the
7780       new method version is called obsolete and is assigned a new method ID;
7781       the original method ID now refers to the new method version.
7782       A method ID can be tested for obsolescence with 
7783       <functionlink id="IsMethodObsolete"/>.
7784     </intro>
7785 
7786     <function id="GetMethodName" phase="start" num="64">
7787       <synopsis>Get Method Name (and Signature)</synopsis>
7788       <description>
7789         For the method indicated by <code>method</code>,
7790         return the method name via <code>name_ptr</code> and method signature via
7791         <code>signature_ptr</code>.
7792         <p/>
7793         Method signatures are defined in the JNI Specification and are 
7794         referred to as <code>method descriptors</code> in 
7795         <vmspec chapter="4.3.3"/>.
7796         Note this is different
7797         than method signatures as defined in the <i>Java Language Specification</i>.
7798       </description>
7799       <origin>jvmdiClone</origin>
7800       <capabilities>
7801       </capabilities>
7802       <parameters>
7803         <param id="method">
7804           <jmethodID/>
7805             <description>
7806               The method to query.
7807             </description>
7808         </param>
7809         <param id="name_ptr">
7810           <allocbuf>
7811             <char/>
7812             <nullok>the name is not returned</nullok>
7813           </allocbuf>
7814           <description>
7815             On return, points to the method name, encoded as a
7816             <internallink id="mUTF">modified UTF-8</internallink> string.
7817           </description>
7818         </param>
7819         <param id="signature_ptr">
7820           <allocbuf>
7821             <char/>
7822             <nullok>the signature is not returned</nullok>
7823           </allocbuf>
7824           <description>
7825             On return, points to the method signature, encoded as a
7826             <internallink id="mUTF">modified UTF-8</internallink> string.
7827           </description>
7828         </param>
7829         <param id="generic_ptr">
7830           <allocbuf>
7831             <char/>           
7832             <nullok>the generic signature is not returned</nullok>
7833           </allocbuf>
7834           <description>
7835             On return, points to the generic signature of the method, encoded as a
7836             <internallink id="mUTF">modified UTF-8</internallink> string.
7837             If there is no generic signature attribute for the method, then,
7838             on return, points to <code>NULL</code>. 
7839           </description>
7840         </param>
7841       </parameters>
7842       <errors>
7843       </errors>
7844     </function>
7845 
7846     <function id="GetMethodDeclaringClass" phase="start" num="65">
7847       <synopsis>Get Method Declaring Class</synopsis>
7848       <description>
7849         For the method indicated by <code>method</code>,
7850         return the class that defined it via <code>declaring_class_ptr</code>.
7851       </description>
7852       <origin>jvmdi</origin>
7853       <capabilities>
7854       </capabilities>
7855       <parameters>
7856         <param id="klass">
7857           <jclass method="method"/>
7858             <description>
7859               The class to query.
7860             </description>
7861         </param>
7862         <param id="method">
7863           <jmethodID class="klass"/>
7864             <description>
7865               The method to query.
7866             </description>
7867         </param>
7868         <param id="declaring_class_ptr">
7869           <outptr><jclass/></outptr>
7870             <description>
7871               On return, points to the declaring class
7872             </description>
7873         </param>
7874       </parameters>
7875       <errors>
7876       </errors>
7877     </function>
7878 
7879     <function id="GetMethodModifiers" phase="start" num="66">
7880       <synopsis>Get Method Modifiers</synopsis>
7881       <description>
7882         For the method indicated by <code>method</code>,
7883         return the access flags via <code>modifiers_ptr</code>.
7884         Access flags are defined in <vmspec chapter="4"/>.
7885       </description>
7886       <origin>jvmdi</origin>
7887       <capabilities>
7888       </capabilities>
7889       <parameters>
7890         <param id="klass">
7891           <jclass method="method"/>
7892             <description>
7893               The class to query.
7894             </description>
7895         </param>
7896         <param id="method">
7897           <jmethodID class="klass"/>
7898             <description>
7899               The method to query.
7900             </description>
7901         </param>
7902         <param id="modifiers_ptr">
7903           <outptr><jint/></outptr>
7904           <description>
7905             On return, points to the access flags.
7906           </description>
7907         </param>
7908       </parameters>
7909       <errors>
7910       </errors>
7911     </function>
7912 
7913     <function id="GetMaxLocals" phase="start" num="68">
7914       <synopsis>Get Max Locals</synopsis>
7915       <description>
7916           For the method indicated by <code>method</code>,
7917           return the number of local variable slots used by the method,
7918           including the local variables used to pass parameters to the
7919           method on its invocation. 
7920           <p/>
7921           See <code>max_locals</code> in <vmspec chapter="4.7.3"/>.
7922       </description>
7923       <origin>jvmdi</origin>
7924       <capabilities>
7925       </capabilities>
7926       <parameters>
7927         <param id="klass">
7928           <jclass method="method"/>
7929             <description>
7930               The class to query.
7931             </description>
7932         </param>
7933         <param id="method">
7934           <jmethodID class="klass" native="error"/>
7935             <description>
7936               The method to query.
7937             </description>
7938         </param>
7939         <param id="max_ptr">
7940           <outptr><jint/></outptr>
7941           <description>
7942             On return, points to the maximum number of local slots
7943           </description>
7944         </param>
7945       </parameters>
7946       <errors>
7947       </errors>
7948     </function>
7949 
7950     <function id="GetArgumentsSize" phase="start" num="69">
7951       <synopsis>Get Arguments Size</synopsis>
7952       <description>
7953         For the method indicated by <code>method</code>,
7954         return via <code>max_ptr</code> the number of local variable slots used
7955         by the method's arguments.
7956         Note that two-word arguments use two slots.
7957       </description>
7958       <origin>jvmdi</origin>
7959       <capabilities>
7960       </capabilities>
7961       <parameters>
7962         <param id="klass">
7963           <jclass method="method"/>
7964             <description>
7965               The class to query.
7966             </description>
7967         </param>
7968         <param id="method">
7969           <jmethodID class="klass" native="error"/>
7970             <description>
7971               The method to query.
7972             </description>
7973         </param>
7974         <param id="size_ptr">
7975           <outptr><jint/></outptr>
7976           <description>
7977             On return, points to the number of argument slots
7978           </description>
7979         </param>
7980       </parameters>
7981       <errors>
7982       </errors>
7983     </function>
7984 
7985     <function id="GetLineNumberTable" phase="start" num="70">
7986       <synopsis>Get Line Number Table</synopsis>
7987       <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
7988         <field id="start_location">
7989           <jlocation/>
7990           <description>
7991             the <datalink id="jlocation"></datalink> where the line begins
7992           </description>
7993         </field>
7994         <field id="line_number">
7995           <jint/>
7996           <description>
7997             the line number
7998           </description>
7999         </field>
8000       </typedef>
8001       <description>
8002         For the method indicated by <code>method</code>,
8003         return a table of source line number entries. The size of the table is
8004         returned via <code>entry_count_ptr</code> and the table itself is
8005         returned via <code>table_ptr</code>. 
8006       </description>
8007       <origin>jvmdi</origin>
8008       <capabilities>
8009         <required id="can_get_line_numbers"></required>
8010       </capabilities>
8011       <parameters>
8012         <param id="klass">
8013           <jclass method="method"/>
8014             <description>
8015               The class to query.
8016             </description>
8017         </param>
8018         <param id="method">
8019           <jmethodID class="klass" native="error"/>
8020             <description>
8021               The method to query.
8022             </description>
8023         </param>
8024         <param id="entry_count_ptr">
8025           <outptr><jint/></outptr>
8026           <description>
8027             On return, points to the number of entries in the table
8028           </description>
8029         </param>
8030         <param id="table_ptr">
8031           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
8032           <description>
8033             On return, points to the line number table pointer.
8034           </description>
8035         </param>
8036       </parameters>
8037       <errors>
8038         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
8039           Class information does not include line numbers.
8040         </error>
8041       </errors>
8042     </function>
8043 
8044     <function id="GetMethodLocation" phase="start" num="71">
8045       <synopsis>Get Method Location</synopsis>
8046       <description>
8047         For the method indicated by <code>method</code>,
8048         return the beginning and ending addresses through
8049         <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
8050         conventional byte code indexing scheme, 
8051         <code>start_location_ptr</code> will always point to zero
8052         and <code>end_location_ptr</code> 
8053         will always point to the byte code count minus one. 
8054       </description>
8055       <origin>jvmdi</origin>
8056       <capabilities>
8057       </capabilities>
8058       <parameters>
8059         <param id="klass">
8060           <jclass method="method"/>
8061             <description>
8062               The class to query.
8063             </description>
8064         </param>
8065         <param id="method">
8066           <jmethodID class="klass" native="error"/>
8067             <description>
8068               The method to query.
8069             </description>
8070         </param>
8071         <param id="start_location_ptr">
8072           <outptr><jlocation/></outptr>
8073           <description>
8074             On return, points to the first location, or 
8075             <code>-1</code> if location information is not available.
8076             If the information is available and 
8077             <functionlink id="GetJLocationFormat"></functionlink>
8078             returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
8079             then this will always be zero.
8080           </description>
8081         </param>
8082         <param id="end_location_ptr">
8083           <outptr><jlocation/></outptr>
8084           <description>
8085             On return, points to the last location,
8086             or <code>-1</code> if location information is not available.
8087           </description>
8088         </param>
8089       </parameters>
8090       <errors>
8091         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
8092           Class information does not include method sizes.
8093         </error>
8094       </errors>
8095     </function>
8096 
8097     <function id="GetLocalVariableTable" num="72">
8098       <synopsis>Get Local Variable Table</synopsis>
8099       <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
8100         <field id="start_location">
8101           <jlocation/>
8102           <description>
8103             The code array index where the local variable is first valid
8104             (that is, where it must have a value).
8105           </description>
8106         </field>
8107         <field id="length">
8108           <jint/>
8109           <description>
8110             The length of the valid section for this local variable.
8111             The last code array index where the local variable is valid 
8112             is <code>start_location + length</code>.
8113           </description>
8114         </field>
8115         <field id="name">
8116           <allocfieldbuf><char/></allocfieldbuf>
8117           <description>
8118             The local variable name, encoded as a
8119             <internallink id="mUTF">modified UTF-8</internallink> string.
8120           </description>
8121         </field>
8122         <field id="signature">
8123           <allocfieldbuf><char/></allocfieldbuf>
8124           <description>
8125             The local variable's type signature, encoded as a
8126             <internallink id="mUTF">modified UTF-8</internallink> string.
8127             The signature format is the same as that defined in
8128             <vmspec chapter="4.3.2"/>.
8129           </description>
8130         </field>
8131         <field id="generic_signature">
8132           <allocfieldbuf><char/></allocfieldbuf>
8133           <description>
8134             The local variable's generic signature, encoded as a
8135             <internallink id="mUTF">modified UTF-8</internallink> string.
8136             The value of this field will be <code>NULL</code> for any local 
8137             variable which does not have a generic type.
8138           </description>
8139         </field>
8140         <field id="slot">
8141           <jint/>
8142           <description>
8143             The local variable's slot.  See <internallink id="local">Local Variables</internallink>.
8144           </description>
8145         </field>
8146       </typedef>
8147       <description>
8148         Return local variable information.
8149       </description>
8150       <origin>jvmdiClone</origin>
8151       <capabilities>
8152         <required id="can_access_local_variables"></required>
8153       </capabilities>
8154       <parameters>
8155         <param id="method">
8156           <jmethodID native="error"/>
8157             <description>
8158               The method to query.
8159             </description>
8160         </param>
8161         <param id="entry_count_ptr">
8162           <outptr><jint/></outptr>
8163           <description>
8164             On return, points to the number of entries in the table
8165           </description>
8166         </param>
8167         <param id="table_ptr">
8168           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
8169           <description>
8170             On return, points to an array of local variable table entries.
8171           </description>
8172         </param>
8173       </parameters>
8174       <errors>
8175         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8176           Class information does not include local variable
8177           information.
8178         </error>
8179       </errors>
8180     </function>
8181 
8182     <function id="GetBytecodes" phase="start" num="75">
8183       <synopsis>Get Bytecodes</synopsis>
8184       <description>
8185         For the method indicated by <code>method</code>,
8186         return the byte codes that implement the method. The number of
8187         bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes
8188         themselves are returned via <code>bytecodes_ptr</code>.
8189       </description>
8190       <origin>jvmdi</origin>
8191       <capabilities>
8192         <required id="can_get_bytecodes"></required>
8193       </capabilities>
8194       <parameters>
8195         <param id="klass">
8196           <jclass method="method"/>
8197             <description>
8198               The class to query.
8199             </description>
8200         </param>
8201         <param id="method">
8202           <jmethodID class="klass" native="error"/>
8203             <description>
8204               The method to query.
8205             </description>
8206         </param>
8207         <param id="bytecode_count_ptr">
8208           <outptr><jint/></outptr>
8209           <description>
8210             On return, points to the length of the byte code array
8211           </description>
8212         </param>
8213         <param id="bytecodes_ptr">
8214           <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
8215           <description>
8216             On return, points to the pointer to the byte code array
8217           </description>
8218         </param>
8219       </parameters>
8220       <errors>
8221       </errors>
8222     </function>
8223 
8224     <function id="IsMethodNative" phase="start" num="76">
8225       <synopsis>Is Method Native</synopsis>
8226       <description>
8227         For the method indicated by <code>method</code>, return a
8228         value indicating whether the method is native via <code>is_native_ptr</code>
8229       </description>
8230       <origin>jvmdi</origin>
8231       <capabilities>
8232       </capabilities>
8233       <parameters>
8234         <param id="klass">
8235           <jclass method="method"/>
8236             <description>
8237               The class to query.
8238             </description>
8239         </param>
8240         <param id="method">
8241           <jmethodID class="klass"/>
8242             <description>
8243               The method to query.
8244             </description>
8245         </param>
8246         <param id="is_native_ptr">
8247           <outptr><jboolean/></outptr>
8248           <description>
8249             On return, points to the boolean result of this function.
8250           </description>
8251         </param>
8252       </parameters>
8253       <errors>
8254       </errors>
8255     </function>
8256 
8257     <function id="IsMethodSynthetic" phase="start" num="77">
8258       <synopsis>Is Method Synthetic</synopsis>
8259       <description>
8260         For the method indicated by <code>method</code>, return a
8261         value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
8262         Synthetic methods are generated by the compiler but not present in the 
8263         original source code.
8264       </description>
8265       <origin>jvmdi</origin>
8266       <capabilities>
8267         <required id="can_get_synthetic_attribute"></required>
8268       </capabilities>
8269       <parameters>
8270         <param id="klass">
8271           <jclass method="method"/>
8272             <description>
8273               The class to query.
8274             </description>
8275         </param>
8276         <param id="method">
8277           <jmethodID class="klass"/>
8278             <description>
8279               The method to query.
8280             </description>
8281         </param>
8282         <param id="is_synthetic_ptr">
8283           <outptr><jboolean/></outptr>
8284           <description>
8285             On return, points to the boolean result of this function.
8286           </description>
8287         </param>
8288       </parameters>
8289       <errors>
8290       </errors>
8291     </function>
8292 
8293     <function id="IsMethodObsolete" phase="start" num="91">
8294       <synopsis>Is Method Obsolete</synopsis>
8295       <description>
8296         Determine if a method ID refers to an
8297         <internallink id="obsoleteMethods">obsolete</internallink>
8298         method version.
8299       </description>
8300       <origin>jvmdi</origin>
8301       <capabilities>
8302       </capabilities>
8303       <parameters>
8304         <param id="klass">
8305           <jclass method="method"/>
8306             <description>
8307               The class to query.
8308             </description>
8309         </param>
8310         <param id="method">
8311           <jmethodID class="klass"/>
8312             <description>
8313               The method ID to query.
8314             </description>
8315         </param>
8316         <param id="is_obsolete_ptr">
8317           <outptr><jboolean/></outptr>
8318           <description>
8319             On return, points to the boolean result of this function.
8320           </description>
8321         </param>
8322       </parameters>
8323       <errors>
8324       </errors>
8325     </function>
8326 
8327     <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
8328       <synopsis>Set Native Method Prefix</synopsis>
8329       <description>
8330         This function modifies the failure handling of
8331         native method resolution by allowing retry
8332         with a prefix applied to the name.
8333         When used with the 
8334         <eventlink id="ClassFileLoadHook">ClassFileLoadHook
8335         event</eventlink>, it enables native methods to be
8336         <internallink id="bci">instrumented</internallink>.
8337         <p/>
8338         Since native methods cannot be directly instrumented
8339         (they have no bytecodes), they must be wrapped with
8340         a non-native method which can be instrumented.
8341         For example, if we had:
8342         <example>
8343 native boolean foo(int x);</example>
8344         <p/>
8345         We could transform the class file (with the 
8346         ClassFileLoadHook event) so that this becomes:
8347         <example>
8348 boolean foo(int x) {
8349   <i>... record entry to foo ...</i>
8350   return wrapped_foo(x);
8351 }
8352 
8353 native boolean wrapped_foo(int x);</example>
8354         <p/>
8355         Where foo becomes a wrapper for the actual native method
8356         with the appended prefix "wrapped_".  Note that
8357         "wrapped_" would be a poor choice of prefix since it
8358         might conceivably form the name of an existing method
8359         thus something like "$$$MyAgentWrapped$$$_" would be
8360         better but would make these examples less readable.
8361         <p/>
8362         The wrapper will allow data to be collected on the native
8363         method call, but now the problem becomes linking up the  
8364         wrapped method with the native implementation.  
8365         That is, the method <code>wrapped_foo</code> needs to be 
8366         resolved to the native implementation of <code>foo</code>,
8367         which might be:
8368         <example>
8369 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
8370         <p/>
8371         This function allows the prefix to be specified and the
8372         proper resolution to occur.  
8373         Specifically, when the standard resolution fails, the
8374         resolution is retried taking the prefix into consideration.
8375         There are two ways that resolution occurs, explicit
8376         resolution with the JNI function <code>RegisterNatives</code>
8377         and the normal automatic resolution.  For 
8378         <code>RegisterNatives</code>, the VM will attempt this 
8379         association:
8380         <example>
8381 method(foo) -> nativeImplementation(foo)</example>
8382         <p/>
8383         When this fails, the resolution will be retried with
8384         the specified prefix prepended to the method name, 
8385         yielding the correct resolution:
8386         <example>
8387 method(wrapped_foo) -> nativeImplementation(foo)</example>
8388         <p/>
8389         For automatic resolution, the VM will attempt:
8390         <example>
8391 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
8392         <p/>
8393         When this fails, the resolution will be retried with
8394         the specified prefix deleted from the implementation name, 
8395         yielding the correct resolution:
8396         <example>
8397 method(wrapped_foo) -> nativeImplementation(foo)</example>
8398         <p/>
8399         Note that since the prefix is only used when standard
8400         resolution fails, native methods can be wrapped selectively.
8401         <p/>
8402         Since each <jvmti/> environment is independent and
8403         can do its own transformation of the bytecodes, more 
8404         than one layer of wrappers may be applied. Thus each
8405         environment needs its own prefix.  Since transformations
8406         are applied in order, the prefixes, if applied, will
8407         be applied in the same order.
8408         The order of transformation application is described in
8409         the <eventlink id="ClassFileLoadHook"/> event.
8410         Thus if three environments applied
8411         wrappers, <code>foo</code> might become 
8412         <code>$env3_$env2_$env1_foo</code>.  But if, say,
8413         the second environment did not apply a wrapper to
8414         <code>foo</code> it would be just 
8415         <code>$env3_$env1_foo</code>.  To be able to 
8416         efficiently determine the sequence of prefixes,
8417         an intermediate prefix is only applied if its non-native
8418         wrapper exists.  Thus, in the last example, even though 
8419         <code>$env1_foo</code> is not a native method, the
8420         <code>$env1_</code> prefix is applied since 
8421         <code>$env1_foo</code> exists.
8422         <p/>
8423         Since the prefixes are used at resolution time
8424         and since resolution may be arbitrarily delayed, a
8425         native method prefix must remain set as long as there 
8426         are corresponding prefixed native methods.
8427       </description>
8428       <origin>new</origin>
8429       <capabilities>
8430         <required id="can_set_native_method_prefix"></required>
8431       </capabilities>
8432       <parameters>
8433         <param id="prefix">
8434           <inbuf>
8435             <char/>
8436             <nullok>
8437               any existing prefix in this environment is cancelled
8438             </nullok>
8439           </inbuf>
8440           <description>
8441             The prefix to apply, encoded as a
8442             <internallink id="mUTF">modified UTF-8</internallink> string.
8443           </description>
8444         </param>
8445       </parameters>
8446       <errors>
8447       </errors>
8448     </function>
8449 
8450     <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
8451       <synopsis>Set Native Method Prefixes</synopsis>
8452       <description>
8453          For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
8454          will provide all needed native method prefixing.
8455          For a meta-agent that performs multiple independent class
8456          file transformations (for example as a proxy for another
8457          layer of agents) this function allows each transformation
8458          to have its own prefix.  
8459          The prefixes are applied in the order supplied and are
8460          processed in the same manor as described for the
8461          application of prefixes from multiple <jvmti/> environments
8462          in <functionlink id="SetNativeMethodPrefix"/>.
8463          <p/>
8464          Any previous prefixes are replaced.  Thus, calling this
8465          function with a <paramlink id="prefix_count"/> of <code>0</code>
8466          disables prefixing in this environment.
8467          <p/>
8468          <functionlink id="SetNativeMethodPrefix"/> and this function
8469          are the two ways to set the prefixes.  
8470          Calling <code>SetNativeMethodPrefix</code> with 
8471          a prefix is the same as calling this function with 
8472          <paramlink id="prefix_count"/> of <code>1</code>. 
8473          Calling <code>SetNativeMethodPrefix</code> with 
8474          <code>NULL</code> is the same as calling this function with 
8475          <paramlink id="prefix_count"/> of <code>0</code>. 
8476       </description>
8477       <origin>new</origin>
8478       <capabilities>
8479         <required id="can_set_native_method_prefix"></required>
8480       </capabilities>
8481       <parameters>
8482         <param id="prefix_count">
8483           <jint min="0"/>
8484             <description>
8485               The number of prefixes to apply.
8486             </description>
8487         </param>
8488         <param id="prefixes">
8489           <agentbuf>
8490             <char/>
8491           </agentbuf>
8492           <description>
8493             The prefixes to apply for this environment, each encoded as a
8494             <internallink id="mUTF">modified UTF-8</internallink> string.
8495           </description>
8496         </param>
8497       </parameters>
8498       <errors>
8499       </errors>
8500     </function>
8501 
8502   </category>
8503 
8504   <category id="RawMonitors" label="Raw Monitor">
8505 
8506     <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
8507       <synopsis>Create Raw Monitor</synopsis>
8508       <description>
8509         Create a raw monitor.
8510       </description>
8511       <origin>jvmdi</origin>
8512       <capabilities>
8513       </capabilities>
8514       <parameters>
8515         <param id="name">
8516           <inbuf><char/></inbuf>
8517           <description>
8518             A name to identify the monitor, encoded as a
8519             <internallink id="mUTF">modified UTF-8</internallink> string.
8520           </description>
8521         </param>
8522         <param id="monitor_ptr">
8523           <outptr><jrawMonitorID/></outptr>
8524           <description>
8525             On return, points to the created monitor.
8526           </description>
8527         </param>
8528       </parameters>
8529       <errors>
8530       </errors>
8531     </function>
8532 
8533     <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
8534       <synopsis>Destroy Raw Monitor</synopsis>
8535       <description>
8536         Destroy the raw monitor.
8537         If the monitor being destroyed has been entered by this thread, it will be
8538         exited before it is destroyed.
8539         If the monitor being destroyed has been entered by another thread,
8540         an error will be returned and the monitor will not be destroyed.
8541       </description>
8542       <origin>jvmdi</origin>
8543       <capabilities>
8544       </capabilities>
8545       <parameters>
8546         <param id="monitor">
8547           <jrawMonitorID/>
8548           <description>
8549             The monitor
8550           </description>
8551         </param>
8552       </parameters>
8553       <errors>
8554         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8555           Not monitor owner
8556         </error>        
8557       </errors>
8558     </function>
8559 
8560     <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
8561       <synopsis>Raw Monitor Enter</synopsis>
8562       <description>
8563         Gain exclusive ownership of a raw monitor.  
8564         The same thread may enter a monitor more then once.
8565         The thread must
8566         <functionlink id="RawMonitorExit">exit</functionlink>
8567         the monitor the same number of times as it is entered.
8568         If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
8569         and has not exited when attached threads come into existence, the enter
8570         is considered to have occurred on the main thread.
8571       </description>
8572       <origin>jvmdi</origin>
8573       <capabilities>
8574       </capabilities>
8575       <parameters>
8576         <param id="monitor">
8577           <jrawMonitorID/>
8578           <description>
8579             The monitor
8580           </description>
8581         </param>
8582       </parameters>
8583       <errors>
8584       </errors>
8585     </function>
8586 
8587     <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
8588       <synopsis>Raw Monitor Exit</synopsis>
8589       <description>
8590         Release exclusive ownership of a raw monitor.
8591       </description>
8592       <origin>jvmdi</origin>
8593       <capabilities>
8594       </capabilities>
8595       <parameters>
8596         <param id="monitor">
8597           <jrawMonitorID/>
8598           <description>
8599             The monitor
8600           </description>
8601         </param>
8602       </parameters>
8603       <errors>
8604         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8605           Not monitor owner
8606         </error>
8607       </errors>
8608     </function>
8609 
8610     <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
8611       <synopsis>Raw Monitor Wait</synopsis>
8612       <description>
8613         Wait for notification of the raw monitor.
8614         <p/>
8615         Causes the current thread to wait until either another thread calls 
8616         <functionlink id="RawMonitorNotify"/> or 
8617         <functionlink id="RawMonitorNotifyAll"/> 
8618         for the specified raw monitor, or the specified
8619         <paramlink id="millis">timeout</paramlink>
8620         has elapsed.
8621       </description>
8622       <origin>jvmdi</origin>
8623       <capabilities>
8624       </capabilities>
8625       <parameters>
8626         <param id="monitor">
8627           <jrawMonitorID/>
8628           <description>
8629             The monitor
8630           </description>
8631         </param>
8632         <param id="millis">
8633           <jlong/>
8634           <description>
8635             The timeout, in milliseconds.  If the timeout is
8636             zero, then real time is not taken into consideration
8637             and the thread simply waits until notified.
8638           </description>
8639         </param>
8640       </parameters>
8641       <errors>
8642         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8643           Not monitor owner
8644         </error>
8645         <error id="JVMTI_ERROR_INTERRUPT"> 
8646           Wait was interrupted, try again
8647         </error>
8648       </errors>
8649     </function>
8650 
8651     <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
8652       <synopsis>Raw Monitor Notify</synopsis>
8653       <description>
8654         Notify a single thread waiting on the raw monitor.
8655       </description>
8656       <origin>jvmdi</origin>
8657       <capabilities>
8658       </capabilities>
8659       <parameters>
8660         <param id="monitor">
8661           <jrawMonitorID/>
8662           <description>
8663             The monitor
8664           </description>
8665         </param>
8666       </parameters>
8667       <errors>
8668         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
8669           Not monitor owner
8670         </error>
8671       </errors>
8672     </function>
8673 
8674     <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
8675       <synopsis>Raw Monitor Notify All</synopsis>
8676       <description>
8677         Notify all threads waiting on the raw monitor.
8678       </description>
8679       <origin>jvmdi</origin>
8680       <capabilities>
8681       </capabilities>
8682       <parameters>
8683         <param id="monitor">
8684           <jrawMonitorID/>
8685           <description>
8686             The monitor
8687           </description>
8688         </param>
8689       </parameters>
8690       <errors>
8691         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8692           Not monitor owner
8693         </error>
8694       </errors>
8695     </function>
8696 
8697    <elide>
8698     <function id="GetRawMonitorUse" num="118">
8699       <synopsis>Get Raw Monitor Use</synopsis>
8700       <description>
8701         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 
8702         are filled in with information about usage of the raw monitor.
8703       </description>
8704       <origin>new</origin>
8705       <capabilities>
8706         <required id="can_get_raw_monitor_usage"></required>
8707       </capabilities>
8708       <parameters>
8709         <param id="monitor">
8710           <jrawMonitorID/>
8711           <description>
8712             the raw monitor to query.
8713           </description>
8714         </param>
8715         <param id="info_ptr">
8716           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
8717           <description>
8718             On return, filled with monitor information for the 
8719             specified raw monitor.
8720           </description>
8721         </param>
8722       </parameters>
8723       <errors>
8724       </errors>
8725     </function>
8726 
8727     <function id="GetRawMonitors" num="119">
8728       <synopsis>Get Raw Monitors</synopsis>
8729       <description>
8730         Return the list of raw monitors.
8731         <p/>
8732         Note: details about each monitor can be examined with 
8733         <functionlink id="GetRawMonitorUse"></functionlink>.
8734       </description>
8735       <origin>new</origin>
8736       <capabilities>
8737         <required id="can_get_raw_monitor_usage"></required>
8738       </capabilities>
8739       <parameters>
8740         <param id="monitorCnt">
8741           <outptr><jint/></outptr>
8742           <description>
8743             On return, pointer to the number 
8744             of monitors returned in <code>monitors_ptr</code>.
8745           </description>
8746         </param>
8747         <param id="monitors_ptr">
8748           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
8749           <description>
8750             On return, pointer to the monitor list.
8751           </description>
8752         </param>
8753       </parameters>
8754       <errors>
8755       </errors>
8756     </function>
8757     </elide>
8758   </category>
8759 
8760   <category id="jniIntercept" label="JNI Function Interception">
8761 
8762     <intro>
8763       Provides the ability to intercept and resend 
8764       Java Native Interface (JNI) function calls
8765       by manipulating the JNI function table.
8766       See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI
8767         Functions</externallink> in the <i>Java Native Interface Specification</i>.
8768       <p/>
8769       The following example illustrates intercepting the 
8770       <code>NewGlobalRef</code> JNI call in order to count reference
8771       creation.
8772       <example>
8773 JNIEnv original_jni_Functions;
8774 JNIEnv redirected_jni_Functions;
8775 int my_global_ref_count = 0;
8776 
8777 jobject
8778 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
8779    ++my_global_ref_count;
8780    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
8781 }
8782 
8783 void
8784 myInit() {
8785    jvmtiError err;
8786 
8787    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;original_jni_Functions);
8788    if (err != JVMTI_ERROR_NONE) {
8789       die();
8790    }
8791    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;redirected_jni_Functions);
8792    if (err != JVMTI_ERROR_NONE) {
8793       die();
8794    }
8795    redirectedJNIFunctions-&gt;NewGlobalRef = MyNewGlobalRef;
8796       err = (*jvmti_env)-&gt;SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
8797    if (err != JVMTI_ERROR_NONE) {
8798       die();
8799    }
8800 }
8801       </example>
8802       Sometime after <code>myInit</code> is called the user's JNI
8803       code is executed which makes the call to create a new global
8804       reference.  Instead of going to the normal JNI implementation
8805       the call goes to <code>myNewGlobalRef</code>.  Note that a
8806       copy of the original function table is kept so that the normal
8807       JNI function can be called after the data is collected.
8808       Note also that any JNI functions which are not overwritten
8809       will behave normally.
8810       <todo>
8811         check that the example compiles and executes.
8812       </todo>
8813     </intro>
8814     
8815     <function id="SetJNIFunctionTable" phase="start" num="120">
8816       <synopsis>Set JNI Function Table</synopsis>
8817       <description>
8818         Set the JNI function table 
8819         in all current and future JNI environments.
8820         As a result, all future JNI calls are directed to the specified functions.
8821         Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
8822         function table to pass to this function.
8823         For this function to take effect the the updated table entries must be 
8824         used by the JNI clients.
8825         Since the table is defined <code>const</code> some compilers may optimize
8826         away the access to the table, thus preventing this function from taking 
8827         effect.
8828         The table is copied--changes to the local copy of the
8829         table have no effect.
8830         This function affects only the function table, all other aspects of the environment are
8831         unaffected.
8832         See the examples <internallink id="jniIntercept">above</internallink>.
8833       </description>
8834       <origin>new</origin>
8835       <capabilities>
8836       </capabilities>
8837       <parameters>
8838         <param id="function_table">
8839           <inptr>
8840             <struct>jniNativeInterface</struct>
8841           </inptr>
8842           <description>
8843             Points to the new JNI function table.
8844           </description>
8845         </param>
8846       </parameters>
8847       <errors>
8848       </errors>
8849     </function>
8850     
8851     <function id="GetJNIFunctionTable" phase="start" num="121">
8852       <synopsis>Get JNI Function Table</synopsis>
8853       <description>
8854         Get the JNI function table.
8855         The JNI function table is copied into allocated memory.
8856         If <functionlink id="SetJNIFunctionTable"></functionlink> 
8857         has been called, the modified (not the original) function
8858         table is returned.
8859         Only the function table is copied, no other aspects of the environment 
8860         are copied.
8861         See the examples <internallink id="jniIntercept">above</internallink>.
8862       </description>
8863       <origin>new</origin>
8864       <capabilities>
8865       </capabilities>
8866       <parameters>
8867         <param id="function_table">
8868           <allocbuf>
8869             <struct>jniNativeInterface</struct>
8870           </allocbuf>
8871           <description>
8872             On return, <code>*function_table</code> 
8873             points a newly allocated copy of the JNI function table.
8874           </description>
8875         </param>
8876       </parameters>
8877       <errors>
8878       </errors>
8879     </function>
8880 
8881   </category>
8882 
8883   <category id="eventManagement" label="Event Management">
8884 
8885     <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
8886       <synopsis>Set Event Callbacks</synopsis>
8887       <description>
8888         Set the functions to be called for each event.
8889         The callbacks are specified by supplying a replacement function table.
8890         The function table is copied--changes to the local copy of the
8891         table have no effect.
8892         This is an atomic action, all callbacks are set at once.
8893         No events are sent before this function is called.
8894         When an entry is <code>NULL</code> or when the event is beyond 
8895         <paramlink id="size_of_callbacks"></paramlink> no event is sent.
8896         Details on events are 
8897         described <internallink id="EventSection">later</internallink> in this document.
8898         An event must be enabled and have a callback in order to be
8899         sent--the order in which this function and 
8900         <functionlink id="SetEventNotificationMode"></functionlink> 
8901         are called does not affect the result.
8902       </description>
8903       <origin>new</origin>
8904       <capabilities>
8905       </capabilities>
8906       <parameters>
8907         <param id="callbacks">
8908           <inptr>
8909             <struct>jvmtiEventCallbacks</struct>
8910             <nullok>remove the existing callbacks</nullok>
8911           </inptr>
8912           <description>
8913             The new event callbacks.
8914           </description>
8915         </param>
8916         <param id="size_of_callbacks">
8917           <jint min="0"/>
8918           <description>
8919             <code>sizeof(jvmtiEventCallbacks)</code>--for version
8920             compatibility.
8921           </description>
8922         </param>
8923       </parameters>
8924       <errors>
8925       </errors>
8926     </function>
8927 
8928     <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
8929       <synopsis>Set Event Notification Mode</synopsis>
8930       <description>
8931         Control the generation of events. 
8932         <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
8933           <constant id="JVMTI_ENABLE" num="1">
8934             If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, 
8935             the event <paramlink id="event_type"></paramlink> will be enabled
8936           </constant>
8937           <constant id="JVMTI_DISABLE" num="0">
8938             If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, 
8939             the event <paramlink id="event_type"></paramlink> will be disabled
8940           </constant>
8941         </constants>
8942         If <code>thread</code> is <code>NULL</code>,
8943         the event is enabled or disabled globally; otherwise, it is 
8944         enabled or disabled for a particular thread. 
8945         An event is generated for 
8946         a particular thread if it is enabled either at the thread or global
8947         levels. 
8948         <p/>
8949         See <internallink id="EventIndex">below</internallink> for information on specific events.
8950         <p/>
8951         The following events cannot be controlled at the thread
8952         level through this function. 
8953         <ul>
8954           <li><eventlink id="VMInit"></eventlink></li>
8955           <li><eventlink id="VMStart"></eventlink></li>
8956           <li><eventlink id="VMDeath"></eventlink></li>
8957           <li><eventlink id="ThreadStart"></eventlink></li>
8958           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
8959           <li><eventlink id="CompiledMethodUnload"></eventlink></li>
8960           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
8961           <li><eventlink id="DataDumpRequest"></eventlink></li>
8962         </ul>
8963         <p/>
8964         Initially, no events are enabled at either the thread level 
8965         or the global level.
8966         <p/>
8967         Any needed capabilities (see Event Enabling Capabilities below) must be possessed
8968         before calling this function.
8969         <p/>
8970         Details on events are 
8971         described <internallink id="EventSection">below</internallink>.
8972       </description>
8973       <origin>jvmdiClone</origin>
8974       <eventcapabilities></eventcapabilities>
8975       <parameters>
8976         <param id="mode">
8977           <enum>jvmtiEventMode</enum>
8978           <description>
8979             <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
8980           </description>
8981         </param>
8982         <param id="event_type">
8983           <enum>jvmtiEvent</enum>
8984           <description>
8985             the event to control
8986           </description>
8987         </param>
8988         <param id="event_thread">
8989           <ptrtype>
8990             <jthread impl="noconvert"/>
8991             <nullok>event is controlled at the global level</nullok>
8992           </ptrtype>
8993             <description>
8994               The thread to control
8995             </description>
8996         </param>
8997         <param id="...">
8998           <varargs/>
8999             <description>
9000               for future expansion
9001             </description>
9002         </param>
9003       </parameters>
9004       <errors>
9005         <error id="JVMTI_ERROR_INVALID_THREAD">
9006           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
9007         </error>
9008         <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
9009           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead).
9010         </error>
9011         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9012           thread level control was attempted on events which do not 
9013           permit thread level control.
9014         </error>
9015         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 
9016           The Required Event Enabling Capability is not possessed.
9017         </error>
9018       </errors>
9019     </function>
9020 
9021     <function id="GenerateEvents" num="123">
9022       <synopsis>Generate Events</synopsis>
9023       <description>
9024         Generate events to represent the current state of the VM.  
9025         For example, if <paramlink id="event_type"/> is 
9026         <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
9027         a <eventlink id="CompiledMethodLoad"></eventlink> event will be
9028         sent for each currently compiled method.
9029         Methods that were loaded and now have been unloaded are not sent.
9030         The history of what events have previously been sent does not 
9031         effect what events are sent by this function--for example, 
9032         all currently compiled methods
9033         will be sent each time this function is called.
9034         <p/>
9035         This function is useful when
9036         events may have been missed due to the agent attaching after program
9037         execution begins; this function generates the missed events.
9038         <p/>
9039         Attempts to execute Java programming language code or
9040         JNI functions may be paused until this function returns -
9041         so neither should be called from the thread sending the event.
9042         This function returns only after the missed events have been 
9043         sent, processed and have returned.
9044         The event may be sent on a different thread than the thread
9045         on which the event occurred.
9046         The callback for the event must be set with 
9047         <functionlink id="SetEventCallbacks"></functionlink> 
9048         and the event must be enabled with
9049         <functionlink id="SetEventNotificationMode"></functionlink> 
9050         or the events will not occur.
9051         If the VM no longer has the information to generate some or
9052         all of the requested events, the events are simply not sent -
9053         no error is returned.
9054         <p/>
9055         Only the following events are supported:
9056         <ul>
9057           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9058           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9059         </ul>
9060       </description>
9061       <origin>new</origin>
9062       <capabilities>
9063         <capability id="can_generate_compiled_method_load_events"></capability>
9064       </capabilities>
9065       <parameters>
9066         <param id="event_type">
9067           <enum>jvmtiEvent</enum>
9068           <description>
9069             The type of event to generate.  Must be one of these:
9070             <ul>
9071               <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
9072               <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
9073             </ul>
9074           </description>
9075         </param>
9076       </parameters>
9077       <errors>
9078         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 
9079           <paramlink id="event_type"/> is 
9080           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9081           and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
9082           is <code>false</code>.
9083         </error>
9084         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 
9085           <paramlink id="event_type"/> is other than
9086           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9087           or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
9088         </error>
9089       </errors>
9090     </function>
9091 
9092   </category>
9093 
9094     <category id="extension" label="Extension Mechanism">
9095 
9096       <intro>
9097         These functions
9098         allow a <jvmti/> implementation to provide functions and events
9099         beyond those defined in this specification.
9100         <p/>
9101         Both extension functions and extension events have parameters
9102         each of which has a 'type' and 'kind' chosen from the following tables:
9103 
9104         <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
9105           <constant id="JVMTI_TYPE_JBYTE" num="101">
9106             Java programming language primitive type - <code>byte</code>. 
9107             JNI type <code>jbyte</code>.
9108           </constant>
9109           <constant id="JVMTI_TYPE_JCHAR" num="102">
9110             Java programming language primitive type - <code>char</code>. 
9111             JNI type <code>jchar</code>.
9112           </constant>
9113           <constant id="JVMTI_TYPE_JSHORT" num="103">
9114             Java programming language primitive type - <code>short</code>. 
9115             JNI type <code>jshort</code>.
9116           </constant>
9117           <constant id="JVMTI_TYPE_JINT" num="104">
9118             Java programming language primitive type - <code>int</code>. 
9119             JNI type <datalink id="jint"></datalink>.
9120           </constant>
9121           <constant id="JVMTI_TYPE_JLONG" num="105">
9122             Java programming language primitive type - <code>long</code>. 
9123             JNI type <datalink id="jlong"></datalink>.
9124           </constant>
9125           <constant id="JVMTI_TYPE_JFLOAT" num="106">
9126             Java programming language primitive type - <code>float</code>. 
9127             JNI type <datalink id="jfloat"></datalink>.
9128           </constant>
9129           <constant id="JVMTI_TYPE_JDOUBLE" num="107">
9130             Java programming language primitive type - <code>double</code>. 
9131             JNI type <datalink id="jdouble"></datalink>.
9132           </constant>
9133           <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
9134             Java programming language primitive type - <code>boolean</code>. 
9135             JNI type <datalink id="jboolean"></datalink>.
9136           </constant>
9137           <constant id="JVMTI_TYPE_JOBJECT" num="109">
9138             Java programming language object type - <code>java.lang.Object</code>. 
9139             JNI type <datalink id="jobject"></datalink>.
9140             Returned values are JNI local references and must be managed.
9141           </constant>
9142           <constant id="JVMTI_TYPE_JTHREAD" num="110">
9143             Java programming language object type - <code>java.lang.Thread</code>. 
9144             <jvmti/> type <datalink id="jthread"></datalink>.
9145             Returned values are JNI local references and must be managed.
9146           </constant>
9147           <constant id="JVMTI_TYPE_JCLASS" num="111">
9148             Java programming language object type - <code>java.lang.Class</code>. 
9149             JNI type <datalink id="jclass"></datalink>.
9150             Returned values are JNI local references and must be managed.
9151           </constant>
9152           <constant id="JVMTI_TYPE_JVALUE" num="112">
9153             Union of all Java programming language primitive and object types - 
9154             JNI type <datalink id="jvalue"></datalink>.
9155             Returned values which represent object types are JNI local references and must be managed.
9156           </constant>
9157           <constant id="JVMTI_TYPE_JFIELDID" num="113">
9158             Java programming language field identifier - 
9159             JNI type <datalink id="jfieldID"></datalink>.
9160           </constant>
9161           <constant id="JVMTI_TYPE_JMETHODID" num="114">
9162             Java programming language method identifier - 
9163             JNI type <datalink id="jmethodID"></datalink>.
9164           </constant>
9165           <constant id="JVMTI_TYPE_CCHAR" num="115">
9166             C programming language type - <code>char</code>.
9167           </constant>
9168           <constant id="JVMTI_TYPE_CVOID" num="116">
9169             C programming language type - <code>void</code>.
9170           </constant>
9171           <constant id="JVMTI_TYPE_JNIENV" num="117">
9172             JNI environment - <code>JNIEnv</code>.
9173             Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
9174           </constant>
9175         </constants>
9176 
9177         <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
9178           <constant id="JVMTI_KIND_IN" num="91">
9179             Ingoing argument - <code>foo</code>.
9180           </constant>
9181           <constant id="JVMTI_KIND_IN_PTR" num="92">
9182             Ingoing pointer argument - <code>const foo*</code>.
9183           </constant>
9184           <constant id="JVMTI_KIND_IN_BUF" num="93">
9185             Ingoing array argument - <code>const foo*</code>.
9186           </constant>
9187           <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
9188             Outgoing allocated array argument -  <code>foo**</code>.
9189             Free with <code>Deallocate</code>.
9190           </constant>
9191           <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
9192             Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
9193             Free with <code>Deallocate</code>.
9194           </constant>
9195           <constant id="JVMTI_KIND_OUT" num="96">
9196             Outgoing argument - <code>foo*</code>.
9197           </constant>
9198           <constant id="JVMTI_KIND_OUT_BUF" num="97">
9199             Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
9200             Do not <code>Deallocate</code>.
9201           </constant>
9202         </constants>
9203 
9204       </intro>
9205 
9206       <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
9207         <field id="name">
9208           <allocfieldbuf><char/></allocfieldbuf>
9209             <description>
9210               The parameter name, encoded as a
9211               <internallink id="mUTF">modified UTF-8</internallink> string
9212             </description>
9213         </field>
9214         <field id="kind">
9215           <enum>jvmtiParamKind</enum>
9216           <description>
9217             The kind of the parameter - type modifiers
9218           </description>
9219         </field>
9220         <field id="base_type">
9221           <enum>jvmtiParamTypes</enum>
9222           <description>
9223             The base type of the parameter -  modified by <code>kind</code>
9224           </description>
9225         </field>
9226         <field id="null_ok">
9227           <jboolean/>
9228             <description>
9229               Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
9230             </description>
9231         </field>
9232       </typedef>
9233 
9234       <callback id="jvmtiExtensionFunction">
9235         <enum>jvmtiError</enum>
9236           <synopsis>Extension Function</synopsis>
9237         <description>
9238           This is the implementation-specific extension function.
9239         </description>
9240         <parameters>
9241           <param id="jvmti_env">
9242             <outptr>
9243               <struct>jvmtiEnv</struct>
9244             </outptr>
9245             <description>
9246               The <jvmti/> environment is the only fixed parameter for extension functions.
9247             </description>
9248           </param>
9249           <param id="...">
9250             <varargs/>
9251               <description>
9252                 The extension function-specific parameters
9253               </description>
9254           </param>
9255         </parameters>
9256       </callback>
9257 
9258       <function id="GetExtensionFunctions" phase="onload" num="124">
9259         <synopsis>Get Extension Functions</synopsis>
9260 
9261         <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
9262           <field id="func">
9263             <ptrtype>
9264               <struct>jvmtiExtensionFunction</struct>
9265             </ptrtype>
9266             <description>
9267               The actual function to call
9268             </description>
9269           </field>
9270           <field id="id">
9271             <allocfieldbuf><char/></allocfieldbuf>
9272               <description>
9273                 The identifier for the extension function, encoded as a
9274                 <internallink id="mUTF">modified UTF-8</internallink> string.
9275                 Uses package name conventions.
9276                 For example, <code>com.sun.hotspot.bar</code>
9277               </description>
9278           </field>
9279           <field id="short_description">
9280             <allocfieldbuf><char/></allocfieldbuf>
9281               <description>
9282                 A one sentence description of the function, encoded as a
9283                 <internallink id="mUTF">modified UTF-8</internallink> string.
9284               </description>
9285           </field>
9286           <field id="param_count">
9287             <jint/>
9288               <description>
9289                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9290               </description>
9291           </field>
9292           <field id="params">
9293             <allocfieldbuf outcount="param_count">
9294               <struct>jvmtiParamInfo</struct>
9295             </allocfieldbuf>
9296             <description>
9297               Array of 
9298               <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9299               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9300             </description>
9301           </field>
9302           <field id="error_count">
9303             <jint/>
9304               <description>
9305                 The number of possible error returns (excluding universal errors)
9306               </description>
9307           </field>
9308           <field id="errors">
9309             <allocfieldbuf outcount="error_count">
9310               <enum>jvmtiError</enum>
9311             </allocfieldbuf>
9312             <description>
9313               Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9314               possible errors
9315             </description>
9316           </field>
9317         </typedef>
9318 
9319         <description>
9320           Returns the set of extension functions.
9321         </description>
9322         <origin>new</origin>
9323         <capabilities>
9324         </capabilities>
9325         <parameters>
9326           <param id="extension_count_ptr">
9327             <outptr><jint/></outptr>
9328               <description>
9329                 On return, points to the number of extension functions
9330               </description>
9331           </param>
9332           <param id="extensions">
9333             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
9334             <description>
9335               Returns an array of extension function info, one per function
9336             </description>
9337           </param>
9338         </parameters>
9339         <errors>
9340         </errors>
9341       </function>
9342 
9343       <function id="GetExtensionEvents" phase="onload" num="125">
9344         <synopsis>Get Extension Events</synopsis>
9345 
9346         <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
9347           <field id="extension_event_index">
9348             <jint/>
9349             <description>
9350               The identifying index of the event
9351             </description>
9352           </field>
9353           <field id="id">
9354             <allocfieldbuf><char/></allocfieldbuf>
9355               <description>
9356                 The identifier for the extension event, encoded as a
9357                 <internallink id="mUTF">modified UTF-8</internallink> string.
9358                 Uses package name conventions.
9359                 For example, <code>com.sun.hotspot.bar</code>
9360               </description>
9361           </field>
9362           <field id="short_description">
9363             <allocfieldbuf><char/></allocfieldbuf>
9364               <description>
9365                 A one sentence description of the event, encoded as a
9366                 <internallink id="mUTF">modified UTF-8</internallink> string.
9367               </description>
9368           </field>
9369           <field id="param_count">
9370             <jint/>
9371               <description>
9372                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9373               </description>
9374           </field>
9375           <field id="params">
9376             <allocfieldbuf outcount="param_count">
9377               <struct>jvmtiParamInfo</struct>
9378             </allocfieldbuf>
9379             <description>
9380               Array of 
9381               <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
9382               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9383             </description>
9384           </field>
9385         </typedef>
9386 
9387         <description>
9388           Returns the set of extension events.
9389         </description>
9390         <origin>new</origin>
9391         <capabilities>
9392         </capabilities>
9393         <parameters>
9394           <param id="extension_count_ptr">
9395             <outptr><jint/></outptr>
9396               <description>
9397                 On return, points to the number of extension events
9398               </description>
9399           </param>
9400           <param id="extensions">
9401             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
9402             <description>
9403               Returns an array of extension event info, one per event
9404             </description>
9405           </param>
9406         </parameters>
9407         <errors>
9408         </errors>
9409       </function>
9410 
9411       <callback id="jvmtiExtensionEvent">
9412         <void/>
9413           <synopsis>Extension Event</synopsis>
9414         <description>
9415           This is the implementation-specific event.
9416           The event handler is set with 
9417           <functionlink id="SetExtensionEventCallback"/>.
9418           <p/>
9419           Event handlers for extension events must be declared varargs to match this definition.
9420           Failure to do so could result in calling convention mismatch and undefined behavior
9421           on some platforms.
9422           <p/>
9423           For example, if the <code>jvmtiParamInfo</code>
9424           returned by <functionlink id="GetExtensionEvents"/> indicates that
9425           there is a <code>jint</code> parameter, the event handler should be
9426           declared:
9427 <example>
9428     void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...)
9429 </example>
9430           Note the terminal "<code>...</code>" which indicates varargs.
9431         </description>
9432         <parameters>
9433           <param id="jvmti_env">
9434             <outptr>
9435               <struct>jvmtiEnv</struct>
9436             </outptr>
9437             <description>
9438               The <jvmti/> environment is the only fixed parameter for extension events.
9439             </description>
9440           </param>
9441           <param id="...">
9442             <varargs/>
9443               <description>
9444                 The extension event-specific parameters
9445               </description>
9446           </param>
9447         </parameters>
9448       </callback>
9449 
9450       <function id="SetExtensionEventCallback" phase="onload" num="126">
9451         <synopsis>Set Extension Event Callback</synopsis>
9452 
9453         <description>
9454           Sets the callback function for an extension event and
9455           enables the event. Or, if the callback is <code>NULL</code>, disables
9456           the event.  Note that unlike standard events, setting
9457           the callback and enabling the event are a single operation.
9458         </description>
9459         <origin>new</origin>
9460         <capabilities>
9461         </capabilities>
9462         <parameters>
9463           <param id="extension_event_index">
9464             <jint/>
9465               <description>
9466                 Identifies which callback to set.
9467                 This index is the 
9468                 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
9469                 field of 
9470                 <datalink id="jvmtiExtensionEventInfo"/>.
9471               </description>
9472           </param>
9473           <param id="callback">
9474             <ptrtype>
9475               <struct>jvmtiExtensionEvent</struct>
9476               <nullok>disable the event</nullok>
9477             </ptrtype>
9478             <description>
9479               If <code>callback</code> is non-<code>NULL</code>, 
9480               set <code>callback</code> to be the event callback function
9481               and enable the event.
9482             </description>
9483           </param>
9484         </parameters>
9485         <errors>
9486         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 
9487             <paramlink id="extension_event_index"/> is not an
9488             <fieldlink id="extension_event_index" 
9489                        struct="jvmtiExtensionEventInfo"/>
9490             returned by 
9491             <functionlink id="GetExtensionEvents"/>
9492         </error>
9493         </errors>
9494       </function>
9495 
9496     </category>
9497 
9498   <category id="capability" label="Capability">
9499 
9500     <intro>
9501       The capabilities functions allow you to change the
9502       functionality available to <jvmti/>--that is, 
9503       which <jvmti/> 
9504       functions can be called, what events can be generated,
9505       and what functionality these events and functions can
9506       provide.
9507       <p/>
9508         The "Capabilities" section of each function and event describe which 
9509         capabilities, if any, they are associated with. "Required Functionality"
9510         means it is available for use and no capabilities must be added to use it.
9511         "Optional Functionality" means the agent must possess the capability
9512         before it can be used.  
9513         To possess a capability, the agent must
9514         <functionlink id="AddCapabilities">add the capability</functionlink>.
9515         "Optional Features" describe capabilities which,
9516         if added, extend the feature set.
9517         <p/>
9518         The potentially available capabilities of each <jvmti/> implementation are different.  
9519         Depending on the implementation, a capability:
9520         <ul>
9521           <li>may never be added</li>
9522           <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
9523           <li>may be added only during the <code>OnLoad</code> phase</li>
9524           <li>may be possessed by only one environment at a time</li>
9525           <li>may be possessed by only one environment at a time, 
9526               and only during the <code>OnLoad</code> phase</li>
9527           <li>and so on ...</li>
9528         </ul>
9529       Frequently, the addition of a capability may incur a cost in execution speed, start up
9530       time, and/or memory footprint.  Note that the overhead of using a capability
9531       is completely different than the overhead of possessing a capability.
9532       Take single stepping as an example. When single stepping is on (that
9533       is, when the event is enabled and thus actively sending events) 
9534       the overhead of sending and processing an event 
9535       on each instruction is huge in any implementation. 
9536       However, the overhead of possessing the capability may be small or large, 
9537       depending on the implementation.  Also, when and if a capability is potentially
9538       available depends on the implementation.  Some examples:
9539       <ul>
9540         <li>One VM might perform all execution by compiling bytecodes into 
9541           native code and be unable to generate single step instructions.
9542           In this implementation the capability can not be added.</li>
9543         <li>Another VM may be able to switch execution to a single stepping
9544           interpreter at any time.  In this implementation, having the capability has no 
9545           overhead and could be added at any time.</li>
9546         <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
9547           execution engine at start up, but be unable to switch between them.
9548           In this implementation the capability would need to be added 
9549           during the <code>OnLoad</code> phase (before bytecode
9550           execution begins) and would have a large impact on execution speed 
9551           even if single stepping was never used.</li>
9552         <li>Still another VM might be able to add an "is single stepping on" check
9553           into compiled bytecodes or a generated interpreter.  Again in this implementation
9554           the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
9555           and branch on each instruction) would be considerably less.</li>
9556       </ul>
9557       <p/>
9558       Each <jvmti/> <internallink id="environments">environment</internallink>
9559       has its own set of capabilities.  
9560       Initially, that set is empty.
9561       Any desired capability must be added.
9562       If possible, capabilities should be added during the <code>OnLoad</code> phase.  For most 
9563       virtual machines certain capabilities require special set up for 
9564       the virtual machine and this set up must happen
9565       during the <code>OnLoad</code> phase, before the virtual machine begins execution. 
9566       Once a capability is added, it can
9567       only be removed if explicitly relinquished by the environment.
9568       <p/>
9569       The agent can, 
9570       <functionlink id="GetPotentialCapabilities">determine what
9571         capabilities this VM can potentially provide</functionlink>,
9572       <functionlink id="AddCapabilities">add the capabilities
9573         to be used</functionlink>,
9574       <functionlink id="RelinquishCapabilities">release capabilities
9575         which are no longer needed</functionlink>, and
9576       <functionlink id="GetCapabilities">examine the currently available 
9577         capabilities</functionlink>.
9578     </intro>
9579 
9580     <intro id="capabilityExamples" label="Capability Examples">
9581       For example, a freshly started agent (in the <code>OnLoad</code> function)
9582       wants to enable all possible capabilities.  
9583       Note that, in general, this is not advisable as the agent may suffer
9584       a performance penalty for functionality it is not using.
9585       The code might look like this in C:
9586       <example>
9587         jvmtiCapabilities capa;
9588         jvmtiError err;
9589 
9590         err = (*jvmti)-&gt;GetPotentialCapabilities(jvmti, &amp;capa);
9591         if (err == JVMTI_ERROR_NONE) {
9592            err = (*jvmti)-&gt;AddCapabilities(jvmti, &amp;capa);
9593       </example>
9594       For example, if an  agent wants to check if it can get
9595       the bytecodes of a method (that is, it wants to check 
9596       if it previously added this capability and has not 
9597       relinquished it), the code might 
9598       look like this in C:
9599       <example>
9600         jvmtiCapabilities capa;
9601         jvmtiError err;
9602 
9603         err = (*jvmti)-&gt;GetCapabilities(jvmti, &amp;capa);
9604         if (err == JVMTI_ERROR_NONE) {
9605            if (capa.can_get_bytecodes) { ... } } 
9606       </example>
9607     </intro>
9608 
9609     <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
9610       <description>
9611         The functions in this category use this capabilities structure 
9612         which contains boolean flags corresponding to each capability:
9613       </description>
9614       <capabilityfield id="can_tag_objects">
9615         <description>
9616           Can set and get tags, as described in the
9617           <internallink id="Heap">Heap category</internallink>.
9618         </description>
9619       </capabilityfield>
9620       <capabilityfield id="can_generate_field_modification_events">
9621         <description>
9622           Can set watchpoints on field modification -
9623           <functionlink id="SetFieldModificationWatch"></functionlink>
9624         </description>
9625       </capabilityfield>
9626       <capabilityfield id="can_generate_field_access_events">
9627         <description>
9628           Can set watchpoints on field access -
9629           <functionlink id="SetFieldAccessWatch"></functionlink>
9630         </description>
9631       </capabilityfield>
9632       <capabilityfield id="can_get_bytecodes">
9633         <description>
9634           Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
9635         </description>
9636       </capabilityfield>
9637       <capabilityfield id="can_get_synthetic_attribute">
9638         <description>
9639           Can test if a field or method is synthetic - 
9640           <functionlink id="IsFieldSynthetic"></functionlink> and
9641           <functionlink id="IsMethodSynthetic"></functionlink>
9642         </description>
9643       </capabilityfield>
9644       <capabilityfield id="can_get_owned_monitor_info">
9645         <description>
9646           Can get information about ownership of monitors - 
9647           <functionlink id="GetOwnedMonitorInfo"></functionlink>
9648         </description>
9649       </capabilityfield>
9650       <capabilityfield id="can_get_current_contended_monitor">
9651         <description>
9652           Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
9653         </description>
9654       </capabilityfield>
9655       <capabilityfield id="can_get_monitor_info">
9656       <description>
9657         Can <functionlink id="GetObjectMonitorUsage"></functionlink>
9658       </description>
9659       </capabilityfield>
9660       <capabilityfield id="can_pop_frame">
9661         <description>
9662           Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
9663         </description>
9664       </capabilityfield>
9665       <capabilityfield id="can_redefine_classes">
9666         <description>
9667           Can redefine classes with <functionlink id="RedefineClasses"/>.
9668         </description>
9669       </capabilityfield>
9670       <capabilityfield id="can_signal_thread">
9671         <description>
9672           Can send stop or interrupt to threads
9673         </description>
9674       </capabilityfield>
9675       <capabilityfield id="can_get_source_file_name">
9676         <description>
9677           Can get the source file name of a class
9678         </description>
9679       </capabilityfield>
9680       <capabilityfield id="can_get_line_numbers">
9681         <description>
9682           Can get the line number table of a method
9683         </description>
9684       </capabilityfield>
9685       <capabilityfield id="can_get_source_debug_extension">
9686         <description>
9687           Can get the source debug extension of a class
9688         </description>
9689       </capabilityfield>
9690       <capabilityfield id="can_access_local_variables">
9691         <description>
9692           Can set and get local variables
9693         </description>
9694       </capabilityfield>
9695       <capabilityfield id="can_maintain_original_method_order">
9696         <description>
9697           Can return methods in the order they occur in the class file
9698         </description>
9699       </capabilityfield>
9700       <capabilityfield id="can_generate_single_step_events">
9701         <description>
9702           Can get <eventlink id="SingleStep">single step</eventlink> events
9703         </description>
9704       </capabilityfield>
9705       <capabilityfield id="can_generate_exception_events">
9706         <description>
9707           Can get <eventlink id="Exception">exception thrown</eventlink> and 
9708             <eventlink id="ExceptionCatch">exception catch</eventlink> events
9709         </description>
9710       </capabilityfield>
9711       <capabilityfield id="can_generate_frame_pop_events">
9712         <description>
9713           Can <functionlink id="NotifyFramePop">set</functionlink> and thus get 
9714             <eventlink id="FramePop"></eventlink> events
9715         </description>
9716       </capabilityfield>
9717       <capabilityfield id="can_generate_breakpoint_events">
9718         <description>
9719           Can <functionlink id="SetBreakpoint">set</functionlink> and thus get 
9720             <eventlink id="Breakpoint"></eventlink> events
9721         </description>
9722       </capabilityfield>
9723       <capabilityfield id="can_suspend">
9724         <description>
9725           Can suspend and resume threads
9726         </description>
9727       </capabilityfield>
9728       <capabilityfield id="can_redefine_any_class">
9729         <description>
9730           Can modify (retransform or redefine) any non-primitive non-array class.
9731           See <functionlink id="IsModifiableClass"/>.
9732         </description>
9733       </capabilityfield>
9734       <capabilityfield id="can_get_current_thread_cpu_time">
9735         <description>
9736           Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
9737           current thread CPU time
9738         </description>
9739       </capabilityfield>
9740       <capabilityfield id="can_get_thread_cpu_time">
9741         <description>
9742           Can <functionlink id="GetThreadCpuTime">get</functionlink>
9743           thread CPU time
9744         </description>
9745       </capabilityfield>
9746       <capabilityfield id="can_generate_method_entry_events" 
9747                        disp1="can_generate" disp2="_method_entry_events" 
9748                        >
9749         <description>
9750           Can generate method entry events on entering a method
9751         </description>
9752       </capabilityfield>
9753       <capabilityfield id="can_generate_method_exit_events" 
9754                        disp1="can_generate" disp2="_method_exit_events" 
9755                        >
9756         <description>
9757           Can generate method exit events on leaving a method
9758         </description>
9759       </capabilityfield>
9760       <capabilityfield id="can_generate_all_class_hook_events" 
9761                        disp1="can_generate" disp2="_all_class_hook_events" 
9762                        >
9763         <description>
9764           Can generate ClassFileLoadHook events for every loaded class.
9765         </description>
9766       </capabilityfield>
9767       <capabilityfield id="can_generate_compiled_method_load_events" 
9768                        disp1="can_generate" disp2="_compiled_method_load_events" 
9769                        >
9770         <description>
9771           Can generate events when a method is compiled or unloaded
9772         </description>
9773       </capabilityfield>
9774       <capabilityfield id="can_generate_monitor_events" 
9775                        disp1="can_generate" disp2="_monitor_events" 
9776                        >
9777         <description>
9778           Can generate events on monitor activity
9779         </description>
9780       </capabilityfield>
9781       <capabilityfield id="can_generate_vm_object_alloc_events" 
9782                        disp1="can_generate" disp2="_vm_object_alloc_events" 
9783                        >
9784         <description>
9785           Can generate events on VM allocation of an object
9786         </description>
9787       </capabilityfield>
9788       <capabilityfield id="can_generate_native_method_bind_events" 
9789                        disp1="can_generate" disp2="_native_method_bind_events" 
9790                        >
9791         <description>
9792           Can generate events when a native method is bound to its
9793           implementation
9794         </description>
9795       </capabilityfield>
9796       <capabilityfield id="can_generate_garbage_collection_events" 
9797                        disp1="can_generate" disp2="_garbage_collection_events" 
9798                        >
9799         <description>
9800           Can generate events when garbage collection begins or ends
9801         </description>
9802       </capabilityfield>
9803       <capabilityfield id="can_generate_object_free_events" 
9804                        disp1="can_generate" disp2="_object_free_events" 
9805                        >
9806         <description>
9807           Can generate events when the garbage collector frees an object
9808         </description>
9809       </capabilityfield>
9810       <capabilityfield id="can_force_early_return" since="1.1">
9811         <description>
9812           Can return early from a method, as described in the
9813           <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
9814         </description>
9815       </capabilityfield>
9816       <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
9817         <description>
9818           Can get information about owned monitors with stack depth -
9819           <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
9820         </description>
9821       </capabilityfield>
9822       <capabilityfield id="can_get_constant_pool" since="1.1">
9823         <description>
9824           Can get the constant pool of a class -
9825           <functionlink id="GetConstantPool"></functionlink>
9826         </description>
9827       </capabilityfield>
9828       <capabilityfield id="can_set_native_method_prefix" since="1.1">
9829         <description>
9830           Can set prefix to be applied when native method cannot be resolved -
9831           <functionlink id="SetNativeMethodPrefix"/> and
9832           <functionlink id="SetNativeMethodPrefixes"/>
9833         </description>
9834       </capabilityfield>
9835       <capabilityfield id="can_retransform_classes" since="1.1">
9836         <description>
9837           Can retransform classes with <functionlink id="RetransformClasses"/>.
9838           In addition to the restrictions imposed by the specific 
9839           implementation on this capability (see the
9840           <internallink id="capability">Capability</internallink> section),
9841           this capability must be set before the 
9842           <eventlink id="ClassFileLoadHook"/> event is enabled for the
9843           first time in this environment.
9844           An environment that possesses this capability at the time that 
9845           <code>ClassFileLoadHook</code> is enabled for the first time is
9846           said to be <i>retransformation capable</i>.
9847           An environment that does not possess this capability at the time that 
9848           <code>ClassFileLoadHook</code> is enabled for the first time is
9849           said to be <i>retransformation incapable</i>.
9850         </description>
9851       </capabilityfield>
9852       <capabilityfield id="can_retransform_any_class" since="1.1">
9853         <description>
9854           <functionlink id="RetransformClasses"/> can be called on any class 
9855           (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
9856           must also be set)
9857         </description>
9858       </capabilityfield>
9859       <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
9860         <description>
9861           Can generate events when the VM is unable to allocate memory from 
9862           the <tm>Java</tm> platform heap.
9863           See <eventlink id="ResourceExhausted"/>.
9864         </description>
9865       </capabilityfield>
9866       <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
9867         <description>
9868           Can generate events when the VM is unable to create a thread.
9869           See <eventlink id="ResourceExhausted"/>.
9870         </description>
9871       </capabilityfield>
9872     </capabilitiestypedef>
9873 
9874     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
9875       <synopsis>Get Potential Capabilities</synopsis>
9876       <description>
9877         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> 
9878         features that can potentially be possessed by this environment
9879         at this time.
9880         The returned capabilities differ from the complete set of capabilities
9881         implemented by the VM in two cases: another environment possesses 
9882         capabilities that can only be possessed by one environment, or the
9883         current <functionlink id="GetPhase">phase</functionlink> is live,
9884         and certain capabilities can only be added during the <code>OnLoad</code> phase.
9885         The <functionlink id="AddCapabilities"></functionlink> function
9886         may be used to set any or all or these capabilities.
9887         Currently possessed capabilities are included.
9888         <p/>
9889         Typically this function is used in the <code>OnLoad</code> function.
9890         Some virtual machines may allow a limited set of capabilities to be
9891         added in the live phase.
9892         In this case, the set of potentially available capabilities
9893         will likely differ from the <code>OnLoad</code> phase set.
9894         <p/>
9895         See the
9896         <internallink id="capabilityExamples">Capability Examples</internallink>.
9897       </description>
9898       <origin>new</origin>
9899       <capabilities>
9900       </capabilities>
9901       <parameters>
9902         <param id="capabilities_ptr">
9903           <outptr><struct>jvmtiCapabilities</struct></outptr>
9904           <description>
9905             On return, points to the <jvmti/> capabilities that may be added.
9906           </description>
9907         </param>
9908       </parameters>
9909       <errors>
9910       </errors>
9911     </function>
9912 
9913     <elide>
9914     <function id="EstimateCostOfCapabilities" phase="onload" num="141">
9915       <synopsis>Estimate Cost Of Capabilities</synopsis>
9916       <description>
9917         <issue>There is strong opposition to this function.  The concern is
9918           that it would be difficult or impossible to provide meaningful
9919           numbers, as the amount of impact is conditional on many factors
9920           that a single number could not represent.  There is doubt that
9921           conditional implementations would be used or are even a good idea.
9922           The thought is that release documentation for the implementation
9923           would be the best means of exposing this information.
9924           Unless new arguments are presented, I intend to remove this 
9925           function in the next revision.
9926         </issue>
9927         <p/>
9928         Return via the <paramlink id="time_impact_ptr"></paramlink> and
9929         <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
9930         of adding the capabilities pointed to by
9931         <paramlink id="capabilities_ptr"></paramlink>.
9932         The returned estimates are in percentage of additional overhead, thus
9933         a time impact of 100 mean the application might run
9934         at half the speed.  
9935         The estimates are very rough approximations and are not guaranteed.
9936         Note also, that the estimates are of the impact of having the
9937         capability available--when and if it is used the impact may be
9938         much greater.
9939         Estimates can be for a single capability or for a set of 
9940         capabilities.  Note that the costs are not necessarily additive,
9941         adding support for one capability might make another available 
9942         for free or conversely having two capabilities at once may 
9943         have multiplicative impact.
9944         Estimates are relative to the current set of capabilities -
9945         that is, how much more impact given the currently possessed capabilities.
9946         <p/>
9947         Typically this function is used in the OnLoad function,
9948         some virtual machines may allow a limited set of capabilities to be
9949         added in the live phase.
9950         In this case, the set of potentially available capabilities
9951         will likely differ from the OnLoad phase set.
9952         <p/>
9953         See the
9954         <internallink id="capabilityExamples">Capability Examples</internallink>.
9955       </description>
9956       <origin>new</origin>
9957       <capabilities>
9958       </capabilities>
9959       <parameters>
9960         <param id="capabilities_ptr">
9961           <inptr><struct>jvmtiCapabilities</struct></inptr>
9962           <description>
9963             points to the <jvmti/> capabilities to evaluate.
9964           </description>
9965         </param>
9966         <param id="time_impact_ptr">
9967           <outptr><jint/></outptr>
9968           <description>
9969             On return, points to the estimated percentage increase in
9970             run time if this capability was added.
9971           </description>
9972         </param>
9973         <param id="space_impact_ptr">
9974           <outptr><jint/></outptr>
9975           <description>
9976             On return, points to the estimated percentage increase in
9977             memory space used if this capability was added.
9978           </description>
9979         </param>
9980       </parameters>
9981       <errors>
9982         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
9983           The desired capabilities are not even potentially available.
9984         </error>
9985       </errors>
9986     </function>
9987     </elide>
9988 
9989     <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
9990       <synopsis>Add Capabilities</synopsis>
9991       <description>
9992         Set new capabilities by adding the capabilities 
9993         whose values are set to one (<code>1</code>) in
9994         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
9995         All previous capabilities are retained.
9996         Typically this function is used in the <code>OnLoad</code> function.
9997         Some virtual machines may allow a limited set of capabilities to be
9998         added in the live phase.
9999         <p/>
10000         See the
10001         <internallink id="capabilityExamples">Capability Examples</internallink>.
10002       </description>
10003       <origin>new</origin>
10004       <capabilities>
10005       </capabilities>
10006       <parameters>
10007         <param id="capabilities_ptr">
10008           <inptr><struct>jvmtiCapabilities</struct></inptr>
10009           <description>
10010             Points to the <jvmti/> capabilities to add.
10011           </description>
10012         </param>
10013       </parameters>
10014       <errors>
10015         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10016           The desired capabilities are not even potentially available.
10017         </error>
10018       </errors>
10019     </function>
10020 
10021 
10022     <function id="RelinquishCapabilities" phase="onload" num="143">
10023       <synopsis>Relinquish Capabilities</synopsis>
10024       <description>
10025         Relinquish the capabilities
10026         whose values are set to one (<code>1</code>) in
10027         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10028         Some implementations may allow only one environment to have a capability
10029         (see the <internallink id="capability">capability introduction</internallink>).
10030         This function releases capabilities
10031         so that they may be used by other agents.
10032         All other capabilities are retained.
10033         The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
10034         Attempting to relinquish a capability that the agent does not possess is not an error.
10035           <issue>
10036             It is possible for the agent to be actively using capabilities
10037             which are being relinquished.  For example, a thread is currently
10038             suspended and can_suspend is being relinquished or an event is currently
10039             enabled and can_generate_whatever is being relinquished.
10040             There are three possible ways we could spec this:
10041             <ul>
10042               <li>relinquish automatically releases them</li>
10043               <li>relinquish checks and returns some error code if held</li>
10044               <li>it is the agent's responsibility and it is not checked</li>
10045             </ul>
10046             One of these should be chosen.
10047           </issue>
10048       </description>
10049       <origin>new</origin>
10050       <capabilities>
10051       </capabilities>
10052       <parameters>
10053         <param id="capabilities_ptr">
10054           <inptr><struct>jvmtiCapabilities</struct></inptr>
10055           <description>
10056             Points to the <jvmti/> capabilities to relinquish.
10057           </description>
10058         </param>
10059       </parameters>
10060       <errors>
10061       </errors>
10062     </function>
10063 
10064 
10065 
10066     <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
10067       <synopsis>Get Capabilities</synopsis>
10068         <description>
10069           Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> 
10070           features which this environment currently possesses.
10071           Each possessed capability is indicated by a one (<code>1</code>) in the
10072           corresponding field of the <internallink id="jvmtiCapabilities">capabilities
10073           structure</internallink>.
10074           An environment does not possess a capability unless it has been successfully added with
10075           <functionlink id="AddCapabilities"/>.
10076           An environment only loses possession of a capability if it has been relinquished with
10077           <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
10078           of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
10079           have been made.
10080           <p/>
10081           See the
10082           <internallink id="capabilityExamples">Capability Examples</internallink>.
10083         </description>
10084       <origin>jvmdiClone</origin>
10085       <capabilities>
10086       </capabilities>
10087       <parameters>
10088         <param id="capabilities_ptr">
10089           <outptr><struct>jvmtiCapabilities</struct></outptr>
10090           <description>
10091             On return, points to the <jvmti/> capabilities.
10092           </description>
10093         </param>
10094       </parameters>
10095       <errors>
10096       </errors>
10097     </function>
10098 
10099   </category>
10100   
10101   
10102   <category id="timers" label="Timers">
10103 
10104       <intro>
10105         These functions provide timing information.
10106         The resolution at which the time is updated is not specified. 
10107         They provides nanosecond precision, but not necessarily nanosecond accuracy. 
10108         Details about the timers, such as their maximum values, can be accessed with
10109         the timer information functions.  
10110       </intro>
10111 
10112       <typedef id="jvmtiTimerInfo" label="Timer Info">
10113         <description>
10114           The information function for each timer returns this data structure.
10115         </description>
10116         <field id="max_value">
10117           <jlong/>
10118             <description>
10119               The maximum value the timer can reach.
10120               After this value is reached the timer wraps back to zero.
10121               This is an unsigned value.  If tested or printed as a jlong (signed value)
10122               it may appear to be a negative number.
10123             </description>
10124         </field>
10125         <field id="may_skip_forward">
10126           <jboolean/>
10127           <description>
10128             If true, the timer can be externally adjusted and as a result skip forward.
10129             If false, the timer value will never increase faster than real time.
10130           </description>
10131         </field>
10132         <field id="may_skip_backward">
10133           <jboolean/>
10134           <description>
10135             If true, the timer can be externally adjusted and as a result skip backward.
10136             If false, the timer value will be monotonically increasing.
10137           </description>
10138         </field>
10139         <field id="kind">
10140           <enum>jvmtiTimerKind</enum>
10141           <description>
10142             The kind of timer.
10143             On a platform that does not distinguish between user and system time, <datalink 
10144                  id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
10145             is returned.
10146           </description>
10147         </field>
10148         <field id="reserved1">
10149           <jlong/>
10150             <description>
10151               Reserved for future use.
10152             </description>
10153         </field>
10154         <field id="reserved2">
10155           <jlong/>
10156             <description>
10157               Reserved for future use.
10158             </description>
10159         </field>
10160       </typedef>
10161 
10162       <intro>
10163         Where the timer kind is --
10164 
10165         <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
10166           <constant id="JVMTI_TIMER_USER_CPU" num="30">
10167             CPU time that a thread is in user mode.
10168           </constant>
10169           <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
10170             CPU time that a thread is in user or system mode.
10171           </constant>
10172           <constant id="JVMTI_TIMER_ELAPSED" num="32">
10173             Elapsed time.
10174           </constant>
10175         </constants>
10176       </intro>
10177 
10178     <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe"  impl="innative notrace" phase="start" num="134">
10179       <synopsis>Get Current Thread CPU Timer Information</synopsis>
10180       <description>
10181         Get information about the 
10182         <functionlink id="GetCurrentThreadCpuTime"/> timer. 
10183         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10184         are filled in with details about the timer.
10185         This information is specific to the platform and the implementation of
10186         <functionlink id="GetCurrentThreadCpuTime"/> and thus 
10187         does not vary by thread nor does it vary
10188         during a particular invocation of the VM.
10189         <p/>
10190         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10191         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10192         returned by <code>GetCurrentThreadCpuTimerInfo</code>
10193         and <functionlink id="GetThreadCpuTimerInfo"/>
10194         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10195       </description>
10196       <origin>new</origin>
10197       <capabilities>
10198         <required id="can_get_current_thread_cpu_time">
10199             Can get current thread CPU time.
10200         </required>
10201       </capabilities>
10202       <parameters>
10203         <param id="info_ptr">
10204           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10205           <description>
10206             On return, filled with information describing the time
10207             returned by <functionlink id="GetCurrentThreadCpuTime"/>.
10208           </description>
10209         </param>
10210       </parameters>
10211       <errors>
10212       </errors>
10213     </function>
10214 
10215     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10216       <synopsis>Get Current Thread CPU Time</synopsis>
10217       <description>
10218             Return the CPU time utilized by the current thread.  
10219             <p/>
10220             Note that the <functionlink id="GetThreadCpuTime"/>
10221             function provides CPU time for any thread, including
10222             the current thread. <code>GetCurrentThreadCpuTime</code> 
10223             exists to support platforms which cannot
10224             supply CPU time for threads other than the current 
10225             thread or which have more accurate information for
10226             the current thread (see 
10227             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10228             <functionlink id="GetThreadCpuTimerInfo"/>).
10229             On many platforms this call will be equivalent to:
10230 <example>
10231   GetThreadCpuTime(env, NULL, nanos_ptr)
10232 </example>
10233       </description>
10234       <origin>new</origin>
10235       <capabilities>
10236         <required id="can_get_current_thread_cpu_time">
10237             Can get current thread CPU time.
10238             <p/>
10239             If this capability is enabled after threads have started, 
10240             the implementation may choose any time up
10241             to and including the time that the capability is enabled 
10242             as the point where CPU time collection starts.
10243             <p/>
10244             This capability must be potentially available on any 
10245             platform where 
10246             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10247             is potentially available.
10248         </required>
10249       </capabilities>
10250       <parameters>
10251         <param id="nanos_ptr">
10252           <outptr><jlong/></outptr>
10253           <description>
10254             On return, points to the CPU time used by this thread
10255             in nanoseconds.  
10256             This is an unsigned value.  If tested or printed as a jlong (signed value)
10257             it may appear to be a negative number.
10258           </description>
10259         </param>
10260       </parameters>
10261       <errors>
10262       </errors>
10263     </function>
10264 
10265     <function id="GetThreadCpuTimerInfo" num="136">
10266       <synopsis>Get Thread CPU Timer Information</synopsis>
10267       <description>
10268         Get information about the 
10269         <functionlink id="GetThreadCpuTime"/> timer. 
10270         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10271         are filled in with details about the timer.
10272         This information is specific to the platform and the implementation of
10273         <functionlink id="GetThreadCpuTime"/> and thus 
10274         does not vary by thread nor does it vary
10275         during a particular invocation of the VM.
10276         <p/>
10277         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10278         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10279         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
10280         and <code>GetThreadCpuTimerInfo</code>
10281         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10282       </description>
10283       <origin>new</origin>
10284       <capabilities>
10285         <required id="can_get_thread_cpu_time">
10286             Can get thread CPU time.
10287         </required>
10288       </capabilities>
10289       <parameters>
10290         <param id="info_ptr">
10291           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10292           <description>
10293             On return, filled with information describing the time
10294             returned by <functionlink id="GetThreadCpuTime"/>.
10295           </description>
10296         </param>
10297       </parameters>
10298       <errors>
10299       </errors>
10300     </function>
10301 
10302     <function id="GetThreadCpuTime" num="137">
10303       <synopsis>Get Thread CPU Time</synopsis>
10304       <description>
10305           Return the CPU time utilized by the specified thread. 
10306           <p/>
10307           Get information about this timer with
10308           <functionlink id="GetThreadCpuTimerInfo"/>. 
10309       </description>
10310       <origin>new</origin>
10311       <capabilities>
10312         <required id="can_get_thread_cpu_time">
10313             Can get thread CPU time.
10314             <p/>
10315             If this capability is enabled after threads have started, 
10316             the implementation may choose any time up
10317             to and including the time that the capability is enabled 
10318             as the point where CPU time collection starts.
10319         </required>
10320       </capabilities>
10321       <parameters>
10322         <param id="thread">
10323           <jthread null="current"/>
10324             <description>
10325               The thread to query.
10326             </description>
10327         </param>
10328         <param id="nanos_ptr">
10329           <outptr><jlong/></outptr>
10330           <description>
10331             On return, points to the CPU time used by the specified thread
10332             in nanoseconds.  
10333             This is an unsigned value.  If tested or printed as a jlong (signed value)
10334             it may appear to be a negative number.
10335           </description>
10336         </param>
10337       </parameters>
10338       <errors>
10339       </errors>
10340     </function>
10341 
10342     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
10343       <synopsis>Get Timer Information</synopsis>
10344       <description>
10345         Get information about the 
10346         <functionlink id="GetTime"/> timer. 
10347         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10348         are filled in with details about the timer.
10349         This information will not change during a particular invocation of the VM.
10350       </description>
10351       <origin>new</origin>
10352       <capabilities>
10353       </capabilities>
10354       <parameters>
10355         <param id="info_ptr">
10356           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10357           <description>
10358             On return, filled with information describing the time
10359             returned by <functionlink id="GetTime"/>.
10360           </description>
10361         </param>
10362       </parameters>
10363       <errors>
10364       </errors>
10365     </function>
10366 
10367     <function id="GetTime" phase="any" callbacksafe="safe" num="139">
10368       <synopsis>Get Time</synopsis>
10369       <description>
10370           Return the current value of the system timer, in nanoseconds. 
10371           <p/>
10372           The value returned represents nanoseconds since some fixed but
10373           arbitrary time (perhaps in the future, so values may be
10374           negative).  This function provides nanosecond precision, but not
10375           necessarily nanosecond accuracy. No guarantees are made about
10376           how frequently values change.
10377           <p/>
10378           Get information about this timer with
10379           <functionlink id="GetTimerInfo"/>. 
10380       </description>
10381       <origin>new</origin>
10382       <capabilities>
10383       </capabilities>
10384       <parameters>
10385         <param id="nanos_ptr">
10386           <outptr><jlong/></outptr>
10387           <description>
10388             On return, points to the time in nanoseconds.  
10389             This is an unsigned value.  If tested or printed as a jlong (signed value)
10390             it may appear to be a negative number.
10391           </description>
10392         </param>
10393       </parameters>
10394       <errors>
10395       </errors>
10396     </function>
10397 
10398     <function id="GetAvailableProcessors" phase="any" num="144">
10399       <synopsis>Get Available Processors</synopsis>
10400       <description>
10401           Returns the number of processors available to the Java virtual machine.
10402           <p/>
10403           This value may change during a particular invocation of the virtual machine. 
10404           Applications that are sensitive to the number of available processors should
10405           therefore occasionally poll this property.
10406       </description>
10407       <origin>new</origin>
10408       <capabilities>
10409       </capabilities>
10410       <parameters>
10411         <param id="processor_count_ptr">
10412           <outptr><jint/></outptr>
10413           <description>
10414             On return, points to the maximum number of processors available to the
10415             virtual machine; never smaller than one.  
10416           </description>
10417         </param>
10418       </parameters>
10419       <errors>
10420       </errors>
10421     </function>
10422 
10423   </category>
10424 
10425 
10426   <category id="classLoaderSearch" label="Class Loader Search">
10427 
10428     <intro>
10429       These functions allow the agent to add to the locations that a class loader searches for a class.
10430       This is useful for installing instrumentation under the correct class loader.
10431     </intro>
10432 
10433     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
10434       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
10435       <description>
10436           This function can be used to cause instrumentation classes to be defined by the 
10437           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
10438           After the bootstrap
10439           class loader unsuccessfully searches for a class, the specified platform-dependent 
10440           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in 
10441           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, 
10442           the segments will be searched in the order that this function was called.
10443           <p/>
10444           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10445           search path segment to be searched after the bootstrap class loader unsuccessfully searches
10446           for a class. The segment is typically a directory or JAR file.
10447           <p/>      
10448           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
10449           path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">
10450           JAR file</externallink>. The agent should take care that the JAR file does not
10451           contain any classes or resources other than those to be defined by the bootstrap
10452           class loader for the purposes of instrumentation.
10453           <p/>
10454           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10455           reference that the Java virtual machine has previously unsuccessfully attempted
10456           to resolve always fails with the same error that was thrown as a result of the
10457           initial resolution attempt. Consequently, if the JAR file contains an entry
10458           that corresponds to a class for which the Java virtual machine has
10459           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10460           resolve that reference will fail with the same error as the initial attempt.
10461       </description>
10462       <origin>new</origin>
10463       <capabilities>
10464       </capabilities>
10465       <parameters>
10466         <param id="segment">
10467           <inbuf><char/></inbuf>
10468           <description>
10469             The platform-dependent search path segment, encoded as a
10470             <internallink id="mUTF">modified UTF-8</internallink> string.
10471           </description>
10472         </param>
10473       </parameters>
10474       <errors>
10475         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">   
10476           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10477            existing JAR file is an invalid path.
10478         </error>
10479       </errors>
10480     </function>
10481 
10482     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
10483       <synopsis>Add To System Class Loader Search</synopsis>
10484       <description>
10485           This function can be used to cause instrumentation classes to be
10486           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
10487           After the class loader unsuccessfully searches for a class, the specified platform-dependent search 
10488           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the 
10489           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the 
10490           segments will be searched in the order that this function was called.
10491           <p/>
10492           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10493           search path segment to be searched after the system class loader unsuccessfully searches
10494           for a class. The segment is typically a directory or JAR file.
10495           <p/>      
10496           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink 
10497           id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be
10498           searched after the system class loader unsuccessfully searches for a class. The agent should
10499           take care that the JAR file does not contain any classes or resources other than those to be
10500           defined by the system class loader for the purposes of instrumentation.
10501           <p/>
10502           In the live phase the system class loader supports adding a JAR file to be searched if
10503           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> 
10504           which takes a single parameter of type <code>java.lang.String</code>. The method is not required 
10505           to have <code>public</code> access. 
10506           <p/>
10507           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10508           reference that the Java virtual machine has previously unsuccessfully attempted
10509           to resolve always fails with the same error that was thrown as a result of the
10510           initial resolution attempt. Consequently, if the JAR file contains an entry
10511           that corresponds to a class for which the Java virtual machine has
10512           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10513           resolve that reference will fail with the same error as the initial attempt.
10514       </description>
10515       <origin>new</origin>
10516       <capabilities>
10517       </capabilities>
10518       <parameters>
10519         <param id="segment">
10520           <inbuf><char/></inbuf>
10521           <description>
10522             The platform-dependent search path segment, encoded as a
10523             <internallink id="mUTF">modified UTF-8</internallink> string.
10524           </description>
10525         </param>
10526       </parameters>
10527       <errors>
10528         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
10529           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10530            existing JAR file is an invalid path.
10531         </error>
10532         <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
10533           Operation not supported by the system class loader.
10534         </error>                                                                                         
10535       </errors>
10536     </function>
10537 
10538   </category>
10539 
10540 
10541   <category id="props" label="System Properties">
10542 
10543     <intro>
10544       These functions get and set system properties.
10545     </intro>
10546 
10547     <function id="GetSystemProperties" phase="onload" num="130">
10548       <synopsis>Get System Properties</synopsis>
10549       <description>
10550         The list of VM system property keys which may be used with 
10551         <functionlink id="GetSystemProperty"/> is returned.
10552         It is strongly recommended that virtual machines provide the
10553         following property keys:
10554         <ul>
10555           <li><code>java.vm.vendor</code></li>
10556           <li><code>java.vm.version</code></li>
10557           <li><code>java.vm.name</code></li>
10558           <li><code>java.vm.info</code></li>
10559           <li><code>java.library.path</code></li>
10560           <li><code>java.class.path</code></li>
10561         </ul>
10562         Provides access to system properties defined by and used
10563         by the VM.
10564         Properties set on the command-line are included.
10565         This allows getting and setting of these properties 
10566         before the VM even begins executing bytecodes.
10567         Since this is a VM view of system properties, the set of available 
10568         properties will usually be different than that
10569         in <code>java.lang.System.getProperties</code>.
10570         JNI method invocation may be used to access 
10571         <code>java.lang.System.getProperties</code>.
10572         <p/>
10573         The set of properties may grow during execution.          
10574       </description>
10575       <origin>new</origin>
10576       <capabilities>
10577       </capabilities>
10578       <parameters>
10579         <param id="count_ptr">
10580           <outptr><jint/></outptr>
10581           <description>
10582             On return, points to the number of property keys returned.
10583           </description>
10584         </param>
10585         <param id="property_ptr">
10586           <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
10587           <description>
10588             On return, points to an array of property keys, encoded as 
10589             <internallink id="mUTF">modified UTF-8</internallink> strings.
10590           </description>
10591         </param>
10592       </parameters>
10593       <errors>
10594       </errors>
10595     </function>
10596 
10597     <function id="GetSystemProperty" phase="onload" num="131">
10598       <synopsis>Get System Property</synopsis>
10599       <description>
10600         Return a VM system property value given the property key.  
10601         <p/>
10602         The function <functionlink id="GetSystemProperties"/>
10603         returns the set of property keys which may be used.
10604         The properties which can be retrieved may grow during
10605         execution.
10606         <p/>
10607         Since this is a VM view of system properties, the values 
10608         of properties may differ from that returned by 
10609         <code>java.lang.System.getProperty(String)</code>.
10610         A typical VM might copy the values of the VM system 
10611         properties into the <code>Properties</code> held by
10612         <code>java.lang.System</code> during the initialization
10613         of that class. Thereafter any changes to the VM system
10614         properties (with <functionlink id="SetSystemProperty"/>) 
10615         or the <code>java.lang.System</code> system properties
10616         (with <code>java.lang.System.setProperty(String,String)</code>)
10617         would cause the values to diverge.
10618         JNI method invocation may be used to access 
10619         <code>java.lang.System.getProperty(String)</code>.
10620       </description>
10621       <origin>new</origin>
10622       <capabilities>
10623       </capabilities>
10624       <parameters>
10625         <param id="property">
10626           <inbuf><char/></inbuf>
10627           <description>
10628             The key of the property to retrieve, encoded as a
10629             <internallink id="mUTF">modified UTF-8</internallink> string.
10630           </description>
10631         </param>
10632         <param id="value_ptr">
10633           <allocbuf><char/></allocbuf>
10634           <description>
10635             On return, points to the property value, encoded as a
10636             <internallink id="mUTF">modified UTF-8</internallink> string.
10637           </description>
10638         </param>
10639       </parameters>
10640       <errors>
10641         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10642           This property is not available.
10643           Use <functionlink id="GetSystemProperties"/> to find available properties.
10644         </error>
10645       </errors>
10646     </function>
10647 
10648     <function id="SetSystemProperty" phase="onloadOnly" num="132">
10649       <synopsis>Set System Property</synopsis>
10650       <description>
10651         Set a VM system property value.  
10652         <p/>
10653         The function <functionlink id="GetSystemProperties"/>
10654         returns the set of property keys, some of these may be settable.
10655         See <functionlink id="GetSystemProperty"/>.
10656       </description>
10657       <origin>new</origin>
10658       <capabilities>
10659       </capabilities>
10660       <parameters>
10661         <param id="property">
10662           <inbuf><char/></inbuf>
10663           <description>
10664             The key of the property, encoded as a
10665             <internallink id="mUTF">modified UTF-8</internallink> string.
10666           </description>
10667         </param>
10668         <param id="value_ptr">
10669           <inbuf>
10670             <char/>
10671             <nullok>
10672               do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
10673               if the property is not writeable
10674             </nullok>
10675           </inbuf>
10676           <description>
10677             The property value to set, encoded as a
10678             <internallink id="mUTF">modified UTF-8</internallink> string.
10679           </description>
10680         </param>
10681       </parameters>
10682       <errors>
10683         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10684           This property is not available or is not writeable.
10685         </error>
10686       </errors>
10687     </function>
10688 
10689   </category>
10690 
10691   <category id="general" label="General">
10692 
10693     <intro>
10694     </intro>
10695 
10696     <function id="GetPhase" jkernel="yes" phase="any" num="133">
10697       <synopsis>Get Phase</synopsis>
10698       <description>
10699           Return the current phase of VM execution.  
10700           The phases proceed in sequence:
10701           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
10702             <constant id="JVMTI_PHASE_ONLOAD" num="1">
10703               <code>OnLoad</code> phase: while in the
10704               <internallink id="onload"><code>Agent_OnLoad</code></internallink> function.
10705             </constant>
10706             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
10707               Primordial phase: between return from <code>Agent_OnLoad</code> and the
10708               <code>VMStart</code> event.
10709             </constant>
10710             <constant id="JVMTI_PHASE_START" num="6">
10711               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event 
10712               is sent and until the <code>VMInit</code> event is sent.
10713             </constant>
10714             <constant id="JVMTI_PHASE_LIVE" num="4">
10715               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
10716               and until the <eventlink id="VMDeath"></eventlink> event returns.
10717             </constant>
10718             <constant id="JVMTI_PHASE_DEAD" num="8">
10719               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
10720               start-up failure.
10721             </constant>
10722           </constants>
10723           In the case of start-up failure the VM will proceed directly to the dead
10724           phase skipping intermediate phases and neither a <code>VMInit</code> nor
10725           <code>VMDeath</code> event will be sent.
10726           <p/>
10727           Most <jvmti/> functions operate only in the live phase.
10728           The following functions operate in either the <code>OnLoad</code> or live phases:
10729           <functionphaselist phase="onload"/>
10730           The following functions operate in only the <code>OnLoad</code> phase:
10731           <functionphaselist phase="onloadOnly"/>
10732           The following functions operate in the start or live phases:
10733           <functionphaselist phase="start"/>
10734           The following functions operate in any phase:
10735           <functionphaselist phase="any"/>
10736           JNI functions (except the Invocation API) must only be used in the start or live phases.
10737           <p/>
10738           Most <jvmti/> events are sent only in the live phase.
10739           The following events operate in others phases:
10740           <eventphaselist phase="start"/>          
10741           <eventphaselist phase="any"/>          
10742       </description>
10743       <origin>new</origin>
10744       <capabilities>
10745       </capabilities>
10746       <parameters>
10747         <param id="phase_ptr">
10748           <outptr><enum>jvmtiPhase</enum></outptr>
10749           <description>
10750             On return, points to the phase.
10751           </description>
10752         </param>
10753       </parameters>
10754       <errors>
10755       </errors>
10756     </function>
10757 
10758     <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
10759       <synopsis>Dispose Environment</synopsis>
10760       <description>
10761         Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
10762         (see <internallink id="environments"><jvmti/> Environments</internallink>).
10763         Dispose of any resources held by the environment.  
10764         <issue>
10765             What resources are reclaimed? What is undone?
10766             Breakpoints,watchpoints removed?
10767         </issue>
10768         Threads suspended by this environment are not resumed by this call,
10769         this must be done explicitly by the agent.
10770         Memory allocated by this environment via calls to <jvmti/> functions
10771         is not released, this can be done explicitly by the agent
10772         by calling <functionlink id="Deallocate"/>.
10773         Raw monitors created by this environment are not destroyed, 
10774         this can be done explicitly by the agent
10775         by calling <functionlink id="DestroyRawMonitor"/>.
10776         The state of threads waiting on raw monitors created by this environment
10777         are not affected.
10778         <p/>
10779         Any <functionlink id="SetNativeMethodPrefix">native method
10780         prefixes</functionlink> for this environment will be unset;
10781         the agent must remove any prefixed native methods before
10782         dispose is called.
10783         <p/>
10784         Any <internallink id="capability">capabilities</internallink>
10785         held by this environment are relinquished.
10786         <p/>
10787         Events enabled by this environment will no longer be sent, however
10788         event handlers currently running will continue to run.  Caution must
10789         be exercised in the design of event handlers whose environment may
10790         be disposed and thus become invalid during their execution.
10791         <p/>
10792         This environment may not be used after this call.
10793         This call returns to the caller.
10794       </description>
10795       <origin>new</origin>
10796       <capabilities>
10797       </capabilities>
10798       <parameters>
10799       </parameters>
10800       <errors>
10801       </errors>
10802     </function>
10803 
10804     <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
10805       <synopsis>Set Environment Local Storage</synopsis>
10806       <description>
10807         The VM stores a pointer value associated with each environment.
10808         This pointer value is called <i>environment-local storage</i>.
10809         This value is <code>NULL</code> unless set with this function.
10810         Agents can allocate memory in which they store environment specific
10811         information. By setting environment-local storage it can then be
10812         accessed with 
10813         <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
10814         <p/>
10815         Called by the agent to set the value of the <jvmti/>
10816         environment-local storage. <jvmti/> supplies to the agent a pointer-size
10817         environment-local storage that can be used to record per-environment
10818         information.
10819       </description>
10820       <origin>new</origin>
10821       <capabilities>
10822       </capabilities>
10823       <parameters>
10824         <param id="data">
10825           <inbuf> 
10826             <void/> 
10827             <nullok>value is set to <code>NULL</code></nullok> 
10828           </inbuf> 
10829           <description>
10830             The value to be entered into the environment-local storage.
10831           </description>
10832         </param>
10833       </parameters>
10834       <errors>
10835       </errors>
10836     </function>
10837 
10838     <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
10839       <synopsis>Get Environment Local Storage</synopsis>
10840       <description>
10841         Called by the agent to get the value of the <jvmti/> environment-local
10842         storage. 
10843       </description>
10844       <origin>new</origin>
10845       <capabilities>
10846       </capabilities>
10847       <parameters>
10848         <param id="data_ptr">
10849           <agentbuf><void/></agentbuf>
10850           <description>
10851             Pointer through which the value of the environment local 
10852             storage is returned.
10853             If environment-local storage has not been set with
10854             <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned 
10855             pointer is <code>NULL</code>.
10856           </description>
10857         </param>
10858       </parameters>
10859       <errors>
10860       </errors>
10861     </function>
10862 
10863     <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
10864       <synopsis>Get Version Number</synopsis>
10865       <description>
10866         Return the <jvmti/> version via <code>version_ptr</code>.
10867         The return value is the version identifier. 
10868         The version identifier includes major, minor and micro
10869         version as well as the interface type.
10870         <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
10871           <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
10872             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
10873           </constant>
10874           <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
10875             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
10876           </constant>
10877         </constants>
10878         <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
10879           <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
10880             Mask to extract interface type.  
10881             The value of the version returned by this function masked with
10882             <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
10883             <code>JVMTI_VERSION_INTERFACE_JVMTI</code> 
10884             since this is a <jvmti/> function.
10885           </constant>
10886           <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
10887             Mask to extract major version number.
10888           </constant>
10889           <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
10890             Mask to extract minor version number.
10891           </constant>
10892           <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
10893             Mask to extract micro version number.
10894           </constant>
10895         </constants>
10896         <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
10897           <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
10898             Shift to extract major version number.
10899           </constant>
10900           <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
10901             Shift to extract minor version number.
10902           </constant>
10903           <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
10904             Shift to extract micro version number.
10905           </constant>
10906         </constants>
10907       </description>
10908       <origin>jvmdi</origin>
10909       <capabilities>
10910       </capabilities>
10911       <parameters>
10912         <param id="version_ptr">
10913           <outptr><jint/></outptr>
10914           <description>
10915             On return, points to the <jvmti/> version.
10916           </description>
10917         </param>
10918       </parameters>
10919       <errors>
10920       </errors>
10921     </function>
10922 
10923 
10924     <function id="GetErrorName" phase="any" num="128">
10925       <synopsis>Get Error Name</synopsis>
10926       <description>
10927         Return the symbolic name for an 
10928           <internallink id="ErrorSection">error code</internallink>.  
10929         <p/>
10930         For example 
10931         <code>GetErrorName(env, JVMTI_ERROR_NONE, &amp;err_name)</code> 
10932         would return in <code>err_name</code> the string
10933         <code>"JVMTI_ERROR_NONE"</code>.
10934       </description>
10935       <origin>new</origin>
10936       <capabilities>
10937       </capabilities>
10938       <parameters>
10939         <param id="error">
10940           <enum>jvmtiError</enum>
10941           <description>
10942             The error code.
10943           </description>
10944         </param>
10945         <param id="name_ptr">
10946           <allocbuf><char/></allocbuf>
10947           <description>
10948             On return, points to the error name.
10949             The name is encoded as a
10950             <internallink id="mUTF">modified UTF-8</internallink> string,
10951             but is restricted to the ASCII subset.
10952           </description>
10953         </param>
10954       </parameters>
10955       <errors>
10956       </errors>
10957     </function>
10958 
10959     <function id="SetVerboseFlag" phase="any" num="150">
10960       <synopsis>Set Verbose Flag</synopsis>
10961       <description>
10962         <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
10963           <constant id="JVMTI_VERBOSE_OTHER" num="0">
10964             Verbose output other than the below.
10965           </constant>
10966           <constant id="JVMTI_VERBOSE_GC" num="1">
10967             Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
10968           </constant>
10969           <constant id="JVMTI_VERBOSE_CLASS" num="2">
10970             Verbose class loading output, like that specified with <code>-verbose:class</code>.
10971           </constant>
10972           <constant id="JVMTI_VERBOSE_JNI" num="4">
10973             Verbose JNI output, like that specified with <code>-verbose:jni</code>.
10974           </constant>
10975         </constants>
10976         Control verbose output.
10977         This is the output which typically is sent to <code>stderr</code>. 
10978       </description>
10979       <origin>new</origin>
10980       <capabilities>
10981       </capabilities>
10982       <parameters>
10983         <param id="flag">
10984           <enum>jvmtiVerboseFlag</enum>
10985           <description>
10986             Which verbose flag to set.
10987           </description>
10988         </param>
10989         <param id="value">
10990           <jboolean/>
10991           <description>
10992             New value of the flag.
10993           </description>
10994         </param>
10995       </parameters>
10996       <errors>
10997       </errors>
10998     </function>
10999 
11000 
11001     <function id="GetJLocationFormat" phase="any" num="129">
11002       <synopsis>Get JLocation Format</synopsis>
11003       <description>
11004         Although the greatest functionality is achieved with location information
11005         referencing the virtual machine bytecode index, the definition of
11006         <code>jlocation</code> has intentionally been left unconstrained to allow VM 
11007         implementations that do not have this information.
11008         <p/>
11009         This function describes the representation of <code>jlocation</code> used in this VM.
11010         If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, 
11011         <code>jlocation</code>s can
11012         be used as in indices into the array returned by
11013         <functionlink id="GetBytecodes"></functionlink>.  
11014         <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
11015           <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
11016             <code>jlocation</code> values represent virtual machine 
11017             bytecode indices--that is, offsets into the 
11018             virtual machine code for a method.
11019           </constant>
11020           <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
11021             <code>jlocation</code> values represent native machine
11022             program counter values.
11023           </constant>
11024           <constant id="JVMTI_JLOCATION_OTHER" num="0">
11025             <code>jlocation</code> values have some other representation.
11026           </constant>
11027         </constants>
11028       </description>
11029       <origin>new</origin>
11030       <capabilities>
11031       </capabilities>
11032       <parameters>
11033         <param id="format_ptr">
11034           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11035           <description>
11036             On return, points to the format identifier for <code>jlocation</code> values.
11037           </description>
11038         </param>
11039       </parameters>
11040       <errors>
11041       </errors>
11042     </function>
11043 
11044   </category>
11045 
11046 </functionsection>
11047 
11048 <errorsection label="Error Reference">
11049   <intro>
11050     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11051     <p/>
11052     It is the responsibility of the agent to call <jvmti/> functions with 
11053     valid parameters and in the proper context (calling thread is attached,
11054     phase is correct, etc.).  
11055     Detecting some error conditions may be difficult, inefficient, or 
11056     impossible for an implementation.
11057     The errors listed in 
11058     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11059     must be detected by the implementation.
11060     All other errors represent the recommended response to the error
11061     condition. 
11062   </intro>
11063 
11064   <errorcategory id="universal-error" label="Universal Errors">
11065     <intro>
11066       The following errors may be returned by any function
11067     </intro>
11068 
11069     <errorid id="JVMTI_ERROR_NONE" num="0">
11070       No error has occurred.  This is the error code that is returned
11071       on successful completion of the function.
11072     </errorid>
11073     <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
11074       Pointer is unexpectedly <code>NULL</code>.
11075     </errorid>
11076     <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
11077       The function attempted to allocate memory and no more memory was 
11078       available for allocation.
11079     </errorid>
11080     <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
11081       The desired functionality has not been enabled in this virtual machine.
11082     </errorid>
11083     <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
11084       The thread being used to call this function is not attached
11085       to the virtual machine.  Calls must be made from attached threads.
11086       See <code>AttachCurrentThread</code> in the JNI invocation API.
11087     </errorid>
11088     <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
11089       The <jvmti/> environment provided is no longer connected or is
11090       not an environment.
11091     </errorid>
11092     <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
11093       The desired functionality is not available in the current
11094         <functionlink id="GetPhase">phase</functionlink>.
11095       Always returned if the virtual machine has completed running.
11096     </errorid>
11097     <errorid id="JVMTI_ERROR_INTERNAL" num="113">
11098       An unexpected internal error has occurred.
11099     </errorid>
11100   </errorcategory>
11101 
11102   <errorcategory id="reqerrors" label="Function Specific Required Errors">
11103     <intro>
11104       The following errors are returned by some <jvmti/> functions and must
11105       be returned by the implementation when the condition occurs.
11106     </intro>
11107 
11108     <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
11109       Invalid priority.
11110     </errorid>
11111     <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
11112       Thread was not suspended.
11113     </errorid>
11114     <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
11115       Thread already suspended.
11116     </errorid>
11117     <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
11118       This operation requires the thread to be alive--that is,
11119       it must be started and not yet have died.
11120     </errorid>
11121     <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
11122       The class has been loaded but not yet prepared.
11123     </errorid>
11124     <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
11125       There are no Java programming language or JNI stack frames at the specified depth.
11126     </errorid>
11127     <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
11128       Information about the frame is not available (e.g. for native frames).
11129     </errorid>
11130     <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
11131       Item already set.
11132     </errorid>
11133     <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
11134       Desired element (e.g. field or breakpoint) not found
11135     </errorid>
11136     <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
11137       This thread doesn't own the raw monitor.
11138     </errorid>
11139     <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
11140       The call has been interrupted before completion.
11141     </errorid>
11142     <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
11143       The class cannot be modified.
11144     </errorid>
11145     <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
11146       The functionality is not available in this virtual machine.
11147     </errorid>
11148     <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
11149       The requested information is not available.
11150     </errorid>
11151     <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
11152       The specified event type ID is not recognized.
11153     </errorid>
11154     <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
11155       The requested information is not available for native method.
11156     </errorid>
11157     <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
11158       The class loader does not support this operation.
11159     </errorid>
11160   </errorcategory>
11161 
11162   <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
11163     <intro>
11164       The following errors are returned by some <jvmti/> functions.
11165       They are returned in the event of invalid parameters passed by the
11166       agent or usage in an invalid context.  
11167       An implementation is not required to detect these errors.
11168     </intro>
11169 
11170     <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
11171       The passed thread is not a valid thread.
11172     </errorid>
11173     <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
11174       Invalid field.
11175     </errorid>
11176     <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
11177       Invalid method.
11178     </errorid>
11179     <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
11180       Invalid location.
11181     </errorid>
11182     <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
11183       Invalid object.
11184     </errorid>
11185     <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
11186       Invalid class.
11187     </errorid>
11188     <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
11189       The variable is not an appropriate type for the function used.
11190     </errorid>
11191     <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
11192       Invalid slot.
11193     </errorid>
11194     <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
11195       The capability being used is false in this environment.
11196     </errorid>
11197     <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
11198       Thread group invalid.
11199     </errorid>
11200     <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
11201       Invalid raw monitor.
11202     </errorid>
11203     <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
11204       Illegal argument.
11205     </errorid>
11206     <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
11207       The state of the thread has been modified, and is now inconsistent.
11208     </errorid>
11209     <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
11210       A new class file has a version number not supported by this VM.
11211     </errorid>
11212     <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
11213       A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
11214     </errorid>
11215     <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
11216       The new class file definitions would lead to a circular
11217       definition (the VM would return a <code>ClassCircularityError</code>).
11218     </errorid>
11219     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
11220       A new class file would require adding a method.
11221     </errorid>
11222     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
11223       A new class version changes a field.
11224     </errorid>
11225     <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
11226       The class bytes fail verification.
11227     </errorid>
11228     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
11229       A direct superclass is different for the new class
11230       version, or the set of directly implemented
11231       interfaces is different.
11232     </errorid>
11233     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
11234       A new class version does not declare a method
11235       declared in the old class version.
11236     </errorid>
11237     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
11238       The class name defined in the new class file is 
11239       different from the name in the old class object.
11240     </errorid>
11241     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
11242       A new class version has different modifiers.
11243     </errorid>
11244     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
11245       A method in the new class version has different modifiers
11246       than its counterpart in the old class version.
11247     </errorid>
11248   </errorcategory>
11249 </errorsection>
11250 
11251 <eventsection label="Events">
11252   <intro label="Handling Events" id="eventIntro">
11253     Agents can be informed of many events that occur in application
11254     programs.
11255     <p/>
11256     To handle events, designate a set of callback functions with
11257     <functionlink id="SetEventCallbacks"></functionlink>. 
11258     For each event the corresponding callback function will be 
11259     called.
11260     Arguments to the callback function provide additional
11261     information about the event. 
11262     <p/>
11263     The callback function is usually called from within an application 
11264     thread. The <jvmti/> implementation does not 
11265     queue events in any way. This means
11266     that event callback functions must be written 
11267     carefully. Here are some general guidelines. See 
11268     the individual event descriptions for further
11269     suggestions.
11270     <p/>
11271     <ul>
11272       <li>Any exception thrown during the execution of an event callback can 
11273         overwrite any current pending exception in the current application thread.
11274         Care must be taken to preserve a pending exception
11275         when an event callback makes a JNI call that might generate an exception.
11276       </li>
11277       <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
11278         not queue events. If an agent needs to process events one at a time, it 
11279         can use a raw monitor inside the 
11280         event callback functions to serialize event processing.
11281       </li>
11282       <li>Event callback functions that execute JNI's FindClass function to load
11283         classes need to note that FindClass locates the class loader associated 
11284         with the current native method. For the purposes of class loading, an
11285         event callback that includes a JNI environment as a parameter to the
11286         callback will treated as if it is a native call, where the native method
11287         is in the class of the event thread's current frame.
11288       </li>
11289     </ul>
11290     <p/>
11291     Some <jvmti/> events identify objects with JNI references. 
11292     All references 
11293     in <jvmti/> events are JNI local references and will become invalid
11294     after the event callback returns.
11295     Unless stated otherwise, memory referenced by pointers sent in event
11296     callbacks may not be referenced after the event callback returns.
11297     <p/>
11298     Except where stated otherwise, events are delivered on the thread
11299     that caused the event.
11300     Events are sent at the time they occur.
11301     The specification for each event includes the set of
11302     <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
11303     if an event triggering activity occurs during another phase, no event 
11304     is sent. 
11305     <p/>
11306     A thread that generates an event does not change its execution status
11307     (for example, the event does not cause the thread to be suspended).
11308     If an agent wishes the event to result in suspension, then the agent
11309     is responsible for explicitly suspending the thread with 
11310     <functionlink id="SuspendThread"></functionlink>.
11311     <p/>
11312     If an event is enabled in multiple environments, the event will be sent
11313     to each agent in the order that the environments were created.
11314   </intro>
11315 
11316   <intro label="Enabling Events" id="enablingevents">
11317     All events are initially disabled.  In order to receive any
11318     event:
11319       <ul>
11320         <li>
11321           If the event requires a capability, that capability must
11322           be added with 
11323           <functionlink id="AddCapabilities"></functionlink>.
11324         </li>
11325         <li>
11326           A callback for the event must be set with 
11327           <functionlink id="SetEventCallbacks"></functionlink>.
11328         </li>
11329         <li>
11330           The event must be enabled with
11331           <functionlink id="SetEventNotificationMode"></functionlink>. 
11332         </li>
11333       </ul>
11334   </intro>
11335 
11336   <intro label="Multiple Co-located Events" id="eventorder">
11337     In many situations it is possible for multiple events to occur 
11338     at the same location in one thread. When this happens, all the events 
11339     are reported through the event callbacks in the order specified in this section.
11340     <p/>
11341     If the current location is at the entry point of a method, the 
11342     <eventlink id="MethodEntry"></eventlink> event is reported before
11343     any other event at the current location in the same thread.
11344     <p/>
11345     If an exception catch has been detected at the current location,
11346     either because it is the beginning of a catch clause or a native method
11347     that cleared a pending exception has returned, the
11348     <code>exceptionCatch</code> event is reported before
11349     any other event at the current location in the same thread.
11350     <p/>
11351     If a <code>singleStep</code> event or 
11352     <code>breakpoint</code> event is triggered at the 
11353     current location, the event is defined to occur 
11354     immediately before the code at the current location is executed. 
11355     These events are reported before any events which are triggered 
11356     by the execution of code at the current location in the same 
11357     thread (specifically: 
11358     <code>exception</code>,
11359     <code>fieldAccess</code>, and
11360     <code>fieldModification</code>).
11361     If both a step and breakpoint event are triggered for the same thread and 
11362     location, the step event is reported before the breakpoint event.
11363     <p/>
11364     If the current location is the exit point of a method (that is, the last
11365     location before returning to the caller), the 
11366     <eventlink id="MethodExit"></eventlink> event and 
11367     the <eventlink id="FramePop"></eventlink> event (if requested)
11368     are reported after all other events at the current location in the same
11369     thread. There is no specified ordering of these two events 
11370     with respect to each other.
11371     <p/>
11372     Co-located events can be triggered during the processing of some other
11373     event by the agent at the same location in the same thread.
11374     If such an event, of type <i>y</i>, is triggered during the processing of 
11375     an event of type <i>x</i>, and if <i>x</i> 
11376     precedes <i>y</i> in the ordering specified above, the co-located event 
11377     <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
11378     <i>y</i>, <i>y</i> is not reported for the current thread and location.
11379     For example, if a breakpoint is set at the current location 
11380     during the processing of <eventlink id="SingleStep"></eventlink>,
11381     that breakpoint will be reported before the thread moves off the current 
11382     location.
11383     <p/>The following events are never considered to be co-located with 
11384     other events.
11385     <ul>
11386       <li><eventlink id="VMStart"></eventlink></li>
11387       <li><eventlink id="VMInit"></eventlink></li>
11388       <li><eventlink id="VMDeath"></eventlink></li>
11389       <li><eventlink id="ThreadStart"></eventlink></li>
11390       <li><eventlink id="ThreadEnd"></eventlink></li>
11391       <li><eventlink id="ClassLoad"></eventlink></li>
11392       <li><eventlink id="ClassPrepare"></eventlink></li>
11393     </ul>
11394   </intro>
11395 
11396   <intro label="Event Callbacks" id="jvmtiEventCallbacks">
11397       The event callback structure below is used to specify the handler function
11398       for events.  It is set with the
11399       <functionlink id="SetEventCallbacks"></functionlink> function. 
11400   </intro>
11401 
11402   <event label="Single Step"
11403          id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
11404     <description>
11405       Single step events allow the agent to trace thread execution
11406       at the finest granularity allowed by the VM. A single step event is
11407       generated whenever a thread reaches a new location. 
11408       Typically, single step events represent the completion of one VM 
11409       instruction as defined in <vmspec/>. However, some implementations 
11410       may define locations differently. In any case the 
11411       <code>method</code> and <code>location</code>
11412       parameters  uniquely identify the current location and allow
11413       the mapping to source file and line number when that information is 
11414       available.
11415       <p/>
11416       No single step events are generated from within native methods.
11417     </description>
11418     <origin>jvmdi</origin>
11419     <capabilities>
11420       <required id="can_generate_single_step_events"></required>
11421     </capabilities>
11422     <parameters> 
11423       <param id="jni_env">
11424         <outptr>
11425           <struct>JNIEnv</struct>
11426         </outptr>
11427           <description>
11428             The JNI environment of the event (current) thread
11429           </description>
11430       </param>
11431       <param id="thread">
11432         <jthread/>
11433           <description>
11434             Thread about to execution a new instruction
11435           </description>
11436       </param>
11437       <param id="klass">
11438         <jclass method="method"/>
11439           <description>
11440             Class of the method about to execute a new instruction
11441           </description>
11442       </param>
11443       <param id="method">
11444         <jmethodID class="klass"/>
11445           <description>
11446             Method about to execute a new instruction
11447           </description>
11448       </param>
11449       <param id="location">
11450         <jlocation/>
11451         <description>
11452           Location of the new instruction
11453         </description>
11454       </param>
11455     </parameters>
11456   </event>
11457 
11458   <event label="Breakpoint"
11459          id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
11460     <description>
11461       Breakpoint events are generated whenever a thread reaches a location
11462       designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
11463       The <code>method</code> and <code>location</code>
11464       parameters uniquely identify the current location and allow
11465       the mapping to source file and line number when that information is 
11466       available.
11467     </description>
11468     <origin>jvmdi</origin>
11469     <capabilities>
11470       <required id="can_generate_breakpoint_events"></required>
11471     </capabilities>
11472     <parameters> 
11473       <param id="jni_env">
11474         <outptr>
11475           <struct>JNIEnv</struct>
11476         </outptr>
11477           <description>
11478             The JNI environment of the event (current) thread.
11479           </description>
11480       </param>
11481       <param id="thread">
11482         <jthread/>
11483           <description>
11484             Thread that hit the breakpoint
11485           </description>
11486       </param>
11487       <param id="klass">
11488         <jclass method="method"/>
11489           <description>
11490             Class of the method that hit the breakpoint
11491           </description>
11492       </param>
11493       <param id="method">
11494         <jmethodID class="klass"/>
11495           <description>
11496             Method that hit the breakpoint
11497           </description>
11498       </param>
11499       <param id="location">
11500         <jlocation/>
11501         <description>
11502           location of the breakpoint
11503         </description>
11504       </param>
11505     </parameters>
11506   </event>
11507 
11508   <event label="Field Access"
11509          id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
11510     <description>
11511       Field access events are generated whenever a thread accesses
11512       a field that was designated as a watchpoint 
11513       with <functionlink id="SetFieldAccessWatch"></functionlink>.
11514       The <code>method</code> and <code>location</code> 
11515       parameters uniquely identify the current location and allow
11516       the mapping to source file and line number when that information is 
11517       available. 
11518     </description>
11519     <origin>jvmdi</origin>
11520     <capabilities>
11521       <required id="can_generate_field_access_events"></required>
11522     </capabilities>
11523     <parameters> 
11524       <param id="jni_env">
11525         <outptr>
11526           <struct>JNIEnv</struct>
11527         </outptr>
11528           <description>
11529             The JNI environment of the event (current) thread
11530           </description>
11531       </param>
11532       <param id="thread">
11533         <jthread/>
11534           <description>
11535             Thread accessing the field
11536           </description>
11537       </param>
11538       <param id="klass">
11539         <jclass method="method"/>
11540           <description>
11541             Class of the method where the access is occurring
11542           </description>
11543       </param>
11544       <param id="method">
11545         <jmethodID class="klass"/>
11546           <description>
11547             Method where the access is occurring
11548           </description>
11549       </param>
11550       <param id="location">
11551         <jlocation/>
11552         <description>
11553           Location where the access is occurring
11554         </description>
11555       </param>
11556       <param id="field_klass">
11557         <jclass field="field"/>
11558           <description>
11559             Class of the field being accessed
11560           </description>
11561       </param>
11562       <param id="object">
11563         <jobject/>
11564           <description>
11565             Object with the field being accessed if the field is an
11566             instance field; <code>NULL</code> otherwise
11567           </description>
11568       </param>
11569       <param id="field">
11570         <jfieldID class="field_klass"/>
11571           <description>
11572             Field being accessed
11573           </description>
11574       </param>
11575     </parameters>
11576   </event>
11577 
11578   <event label="Field Modification"
11579          id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
11580     <description>
11581       Field modification events are generated whenever a thread modifies
11582       a field that was designated as a watchpoint 
11583       with <functionlink id="SetFieldModificationWatch"></functionlink>.
11584       The <code>method</code> and <code>location</code> 
11585       parameters uniquely identify the current location and allow
11586       the mapping to source file and line number when that information is 
11587       available. 
11588     </description>
11589     <origin>jvmdi</origin>
11590     <capabilities>
11591       <required id="can_generate_field_modification_events"></required>
11592     </capabilities>
11593     <parameters> 
11594       <param id="jni_env">
11595         <outptr>
11596           <struct>JNIEnv</struct>
11597         </outptr>
11598           <description>
11599             The JNI environment of the event (current) thread
11600           </description>
11601       </param>
11602       <param id="thread">
11603         <jthread/>
11604           <description>
11605             Thread modifying the field
11606           </description>
11607       </param>
11608       <param id="klass">
11609         <jclass method="method"/>
11610           <description>
11611             Class of the method where the modification is occurring
11612           </description>
11613       </param>
11614       <param id="method">
11615         <jmethodID class="klass"/>
11616           <description>
11617             Method where the modification is occurring
11618           </description>
11619       </param>
11620       <param id="location">
11621         <jlocation/>
11622         <description>
11623           Location where the modification is occurring
11624         </description>
11625       </param>
11626       <param id="field_klass">
11627         <jclass field="field"/>
11628           <description>
11629             Class of the field being modified
11630           </description>
11631       </param>
11632       <param id="object">
11633         <jobject/>
11634           <description>
11635             Object with the field being modified if the field is an
11636             instance field; <code>NULL</code> otherwise
11637           </description>
11638       </param>
11639       <param id="field">
11640         <jfieldID class="field_klass"/>
11641           <description>
11642             Field being modified
11643           </description>
11644       </param>
11645       <param id="signature_type">
11646         <char/>
11647         <description>
11648           Signature type of the new value
11649         </description>
11650       </param>
11651       <param id="new_value">
11652         <jvalue/>
11653         <description>
11654           The new value
11655         </description>
11656       </param>
11657     </parameters>
11658   </event>
11659 
11660   <event label="Frame Pop"
11661          id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
11662     <description>
11663       Frame pop events are generated upon exit from a single method 
11664       in a single frame as specified
11665       in a call to <functionlink id="NotifyFramePop"></functionlink>.
11666       This is true whether termination is caused by
11667       executing its return instruction
11668       or by throwing an exception to its caller 
11669       (see <paramlink id="was_popped_by_exception"></paramlink>).
11670       However, frame pops caused by the <functionlink id="PopFrame"/> 
11671       function are not reported.
11672       <p/>
11673       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11674       identifies the executable location in the returning method, 
11675       immediately prior to the return. 
11676     </description>
11677     <origin>jvmdi</origin>
11678     <capabilities>
11679       <required id="can_generate_frame_pop_events"></required>
11680     </capabilities>
11681     <parameters> 
11682       <param id="jni_env">
11683         <outptr>
11684           <struct>JNIEnv</struct>
11685         </outptr>
11686           <description>
11687             The JNI environment of the event (current) thread
11688           </description>
11689       </param>
11690       <param id="thread">
11691         <jthread/>
11692           <description>
11693             Thread that is popping the frame
11694           </description>
11695       </param>
11696       <param id="klass">
11697         <jclass method="method"/>
11698           <description>
11699             Class of the method being popped
11700           </description>
11701       </param>
11702       <param id="method">
11703         <jmethodID class="klass"/>
11704           <description>
11705             Method being popped
11706           </description>
11707       </param>
11708       <param id="was_popped_by_exception">
11709         <jboolean/>
11710         <description>
11711           True if frame was popped by a thrown exception.
11712           False if method exited through its return instruction.
11713         </description>
11714       </param>
11715     </parameters>
11716   </event>
11717 
11718   <event label="Method Entry"
11719          id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
11720     <description>
11721       Method entry events are generated upon entry of Java 
11722       programming language methods (including native methods).
11723       <p/>
11724       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11725       identifies the initial executable location in
11726       the method. 
11727       <p/>
11728       Enabling method
11729       entry or exit events will significantly degrade performance on many platforms and is thus
11730       not advised for performance critical usage (such as profiling).
11731       <internallink id="bci">Bytecode instrumentation</internallink> should be 
11732       used in these cases.
11733     </description>
11734     <origin>jvmdi</origin>
11735     <capabilities>
11736       <required id="can_generate_method_entry_events"></required>
11737     </capabilities>
11738     <parameters> 
11739       <param id="jni_env">
11740         <outptr>
11741           <struct>JNIEnv</struct>
11742         </outptr>
11743           <description>
11744             The JNI environment of the event (current) thread
11745           </description>
11746       </param>
11747       <param id="thread">
11748         <jthread/>
11749           <description>
11750             Thread entering the method
11751           </description>
11752       </param>
11753       <param id="klass">
11754         <jclass method="method"/>
11755           <description>
11756             Class of the method being entered
11757           </description>
11758       </param>
11759       <param id="method">
11760         <jmethodID class="klass"/>
11761           <description>
11762             Method being entered
11763           </description>
11764       </param>
11765     </parameters>
11766   </event>
11767 
11768   <event label="Method Exit"
11769          id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
11770     <description>
11771       Method exit events are generated upon exit from Java 
11772       programming language methods (including native methods).
11773       This is true whether termination is caused by
11774       executing its return instruction
11775       or by throwing an exception to its caller 
11776       (see <paramlink id="was_popped_by_exception"></paramlink>).
11777       <p/>
11778       The <code>method</code> field uniquely identifies the
11779       method being entered or exited. The <code>frame</code> field provides 
11780       access to the stack frame for the method.
11781       <p/>
11782       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11783       identifies the executable location in the returning method 
11784       immediately prior to the return. 
11785       <p/>
11786         Enabling method
11787         entry or exit events will significantly degrade performance on many platforms and is thus
11788         not advised for performance critical usage (such as profiling).
11789         <internallink id="bci">Bytecode instrumentation</internallink> should be 
11790         used in these cases.
11791     </description>
11792     <origin>jvmdi</origin>
11793     <capabilities>
11794       <required id="can_generate_method_exit_events"></required>
11795     </capabilities>
11796     <parameters>
11797       <param id="jni_env">
11798         <outptr>
11799           <struct>JNIEnv</struct>
11800         </outptr>
11801           <description>
11802             The JNI environment of the event (current) thread
11803           </description>
11804       </param>
11805       <param id="thread">
11806         <jthread/>
11807           <description>
11808             Thread exiting the method
11809           </description>
11810       </param>
11811       <param id="klass">
11812         <jclass method="method"/>
11813           <description>
11814             Class of the method being exited
11815           </description>
11816       </param>
11817       <param id="method">
11818         <jmethodID class="klass"/>
11819           <description>
11820             Method being exited
11821           </description>
11822       </param>
11823       <param id="was_popped_by_exception">
11824         <jboolean/>
11825         <description>
11826           True if frame was popped by a thrown exception.
11827           False if method exited through its return instruction.
11828         </description>
11829       </param>
11830       <param id="return_value">
11831         <jvalue/>
11832         <description>
11833           The return value of the method being exited.
11834           Undefined and should not be used if 
11835           <paramlink id="was_popped_by_exception"></paramlink>
11836           is true.
11837         </description>
11838       </param>
11839     </parameters>
11840   </event>
11841 
11842   <event label="Native Method Bind" phase="any"
11843          id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
11844     <description>
11845       A Native Method Bind event is sent when a VM binds a 
11846       Java programming language native method
11847       to the address of a function that implements the native method. 
11848       This will occur when the native method is called for the first time
11849       and also occurs when the JNI function <code>RegisterNatives</code> is called.
11850       This event allows the bind to be redirected to an agent-specified
11851       proxy function. 
11852       This event is not sent when the native method is unbound.
11853       Typically, this proxy function will need to be specific to a 
11854       particular method or, to handle the general case, automatically
11855       generated assembly code, since after instrumentation code is 
11856       executed the function at the original binding 
11857       address will usually be invoked.
11858       The original binding can be restored or the redirection changed
11859       by use of the JNI function <code>RegisterNatives</code>.
11860       Some events may be sent during the primordial phase, JNI and
11861       most of <jvmti/> cannot be used at this time but the method and
11862       address can be saved for use later.
11863     </description>
11864     <origin>new</origin>
11865     <capabilities>
11866       <required id="can_generate_native_method_bind_events"></required>
11867     </capabilities>
11868     <parameters>
11869       <param id="jni_env">
11870         <outptr>
11871           <struct>JNIEnv</struct>
11872         </outptr>
11873           <description>
11874             The JNI environment of the event (current) thread
11875             Will be <code>NULL</code> if sent during the primordial 
11876             <functionlink id="GetPhase">phase</functionlink>.
11877           </description>
11878       </param>
11879       <param id="thread">
11880         <jthread/>
11881           <description>
11882             Thread requesting the bind
11883           </description>
11884       </param>
11885       <param id="klass">
11886         <jclass method="method"/>
11887           <description>
11888             Class of the method being bound
11889           </description>
11890       </param>
11891       <param id="method">
11892         <jmethodID class="klass"/>
11893           <description>
11894             Native method being bound
11895           </description>
11896       </param>
11897       <param id="address">
11898         <outptr><void/></outptr>
11899         <description>
11900           The address the VM is about to bind to--that is, the
11901           address of the implementation of the native method
11902         </description>
11903       </param>
11904       <param id="new_address_ptr">
11905         <agentbuf><void/></agentbuf>
11906         <description>
11907           if the referenced address is changed (that is, if
11908           <code>*new_address_ptr</code> is set), the binding
11909           will instead be made to the supplied address.
11910         </description>
11911       </param>
11912     </parameters>
11913   </event>
11914 
11915   <event label="Exception"
11916          id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
11917     <description>
11918       Exception events are generated whenever an exception is first detected
11919       in a Java programming language method. 
11920       Where "exception" means any <code>java.lang.Throwable</code>.
11921       The exception may have been thrown by a Java programming language or native
11922       method, but in the case of native methods, the event is not generated
11923       until the exception is first seen by a Java programming language method. If an exception is
11924       set and cleared in a native method (and thus is never visible to Java programming language code),
11925       no exception event is generated.
11926       <p/>
11927       The <code>method</code> and <code>location</code>
11928       parameters  uniquely identify the current location 
11929       (where the exception was detected) and allow
11930       the mapping to source file and line number when that information is 
11931       available. The <code>exception</code> field identifies the thrown
11932       exception object. The <code>catch_method</code>
11933       and <code>catch_location</code> identify the location of the catch clause,
11934       if any, that handles the thrown exception. If there is no such catch clause,
11935       each field is set to 0. There is no guarantee that the thread will ever
11936       reach this catch clause. If there are native methods on the call stack
11937       between the throw location and the catch clause, the exception may 
11938       be reset by one of those native methods.
11939       Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
11940       et al. set to 0) may in fact be caught by native code.
11941       Agents can check for these occurrences by monitoring 
11942       <eventlink id="ExceptionCatch"></eventlink> events.
11943       Note that finally clauses are implemented as catch and re-throw. Therefore they
11944       will be reported in the catch location.
11945     </description>
11946     <origin>jvmdi</origin>
11947     <capabilities>
11948       <required id="can_generate_exception_events"></required>
11949     </capabilities>
11950     <parameters> 
11951       <param id="jni_env">
11952         <outptr>
11953           <struct>JNIEnv</struct>
11954         </outptr>
11955           <description>
11956             The JNI environment of the event (current) thread
11957           </description>
11958       </param>
11959       <param id="thread">
11960         <jthread/>
11961           <description>
11962             Thread generating the exception
11963           </description>
11964       </param>
11965       <param id="klass">
11966         <jclass method="method"/>
11967           <description>
11968             Class generating the exception
11969           </description>
11970       </param>
11971       <param id="method">
11972         <jmethodID class="klass"/>
11973           <description>
11974             Method generating the exception
11975           </description>
11976       </param>
11977       <param id="location">
11978         <jlocation/>
11979         <description>
11980           Location where exception occurred
11981         </description>
11982       </param>
11983       <param id="exception">
11984         <jobject/>
11985           <description>
11986             The exception being thrown
11987           </description>
11988       </param>
11989       <param id="catch_klass">
11990         <jclass method="catch_method"/>
11991           <description>
11992             Class that will catch the exception, or <code>NULL</code> if no known catch
11993           </description>
11994       </param>
11995       <param id="catch_method">
11996         <jmethodID class="catch_klass"/>
11997           <description>
11998             Method that will catch the exception, or <code>NULL</code> if no known catch
11999           </description>
12000       </param>
12001       <param id="catch_location">
12002         <jlocation/>
12003         <description>
12004           location which will catch the exception or zero if no known catch
12005         </description>
12006       </param>
12007     </parameters>
12008   </event>
12009 
12010   <event label="Exception Catch"
12011          id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
12012     <description>
12013       Exception catch events are generated whenever a thrown exception is caught.
12014       Where "exception" means any <code>java.lang.Throwable</code>.
12015       If the exception is caught in a Java programming language method, the event is generated
12016       when the catch clause is reached. If the exception is caught in a native
12017       method, the event is generated as soon as control is returned to a Java programming language 
12018       method. Exception catch events are generated for any exception for which
12019       a throw was detected in a Java programming language method.
12020       Note that finally clauses are implemented as catch and re-throw. Therefore they
12021       will generate exception catch events.
12022       <p/>
12023       The <code>method</code> and <code>location</code>
12024       parameters uniquely identify the current location 
12025       and allow the mapping to source file and line number when that information is 
12026       available. For exceptions caught in a Java programming language method, the 
12027       <code>exception</code> object identifies the exception object. Exceptions
12028       caught in native methods are not necessarily available by the time the 
12029       exception catch is reported, so the <code>exception</code> field is set
12030       to <code>NULL</code>.
12031     </description>
12032     <origin>jvmdi</origin>
12033     <capabilities>
12034       <required id="can_generate_exception_events"></required>
12035     </capabilities>
12036     <parameters> 
12037       <param id="jni_env">
12038         <outptr>
12039           <struct>JNIEnv</struct>
12040         </outptr>
12041           <description>
12042             The JNI environment of the event (current) thread
12043           </description>
12044       </param>
12045       <param id="thread">
12046         <jthread/>
12047           <description>
12048             Thread catching the exception
12049           </description>
12050       </param>
12051       <param id="klass">
12052         <jclass method="method"/>
12053           <description>
12054             Class catching the exception
12055           </description>
12056       </param>
12057       <param id="method">
12058         <jmethodID class="klass"/>
12059           <description>
12060             Method catching the exception
12061           </description>
12062       </param>
12063       <param id="location">
12064         <jlocation/>
12065         <description>
12066           Location where exception is being caught
12067         </description>
12068       </param>
12069       <param id="exception">
12070         <jobject/>
12071           <description>
12072             Exception being caught
12073           </description>
12074       </param>
12075     </parameters>
12076   </event>
12077 
12078   <event label="Thread Start"
12079          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12080     <description>
12081       Thread start events are generated by a new thread before its initial
12082       method executes. 
12083       <p/>
12084       A thread may be listed in the array returned by
12085       <functionlink id="GetAllThreads"></functionlink>
12086       before its thread start event is generated. 
12087       It is possible for other events to be generated
12088       on a thread before its thread start event.
12089       <p/>
12090       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12091     </description>
12092     <origin>jvmdi</origin>
12093     <capabilities>
12094     </capabilities>
12095     <parameters> 
12096       <param id="jni_env">
12097         <outptr>
12098           <struct>JNIEnv</struct>
12099         </outptr>
12100           <description>
12101             The JNI environment of the event (current) thread.
12102           </description>
12103       </param>
12104       <param id="thread">
12105         <jthread/>
12106           <description>
12107             Thread starting
12108           </description>
12109       </param>
12110     </parameters>
12111   </event>
12112 
12113   <event label="Thread End"
12114          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> 
12115     <description>
12116       Thread end events are generated by a terminating thread
12117       after its initial method has finished execution. 
12118       <p/>
12119       A thread may be listed in the array returned by
12120       <functionlink id="GetAllThreads"></functionlink>
12121       after its thread end event is generated. 
12122       No events are generated on a thread
12123       after its thread end event.
12124       <p/>
12125       The event is sent on the dying <paramlink id="thread"></paramlink>.
12126     </description>
12127     <origin>jvmdi</origin>
12128     <capabilities>
12129     </capabilities>
12130     <parameters> 
12131       <param id="jni_env">
12132         <outptr>
12133           <struct>JNIEnv</struct>
12134         </outptr>
12135           <description>
12136             The JNI environment of the event (current) thread.
12137           </description>
12138       </param>
12139       <param id="thread">
12140         <jthread/>
12141           <description>
12142             Thread ending
12143           </description>
12144       </param>
12145     </parameters>
12146   </event>
12147 
12148   <event label="Class Load"
12149          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
12150     <description>
12151       A class load event is generated when a class is first loaded. The order
12152       of class load events generated by a particular thread are guaranteed
12153       to match the order of class loading within that thread. 
12154       Array class creation does not generate a class load event.
12155       The creation of a primitive class (for example, java.lang.Integer.TYPE) 
12156       does not generate a class load event.
12157       <p/>
12158       This event is sent at an early stage in loading the class. As
12159       a result the class should be used carefully.  Note, for example,
12160       that methods and fields are not yet loaded, so queries for methods,
12161       fields, subclasses, and so on will not give correct results. 
12162       See "Loading of Classes and Interfaces" in the <i>Java Language
12163       Specification</i>.  For most
12164       purposes the <eventlink id="ClassPrepare"></eventlink> event will
12165       be more useful.
12166     </description>
12167     <origin>jvmdi</origin>
12168     <capabilities>
12169     </capabilities>
12170     <parameters> 
12171       <param id="jni_env">
12172         <outptr>
12173           <struct>JNIEnv</struct>
12174         </outptr>
12175           <description>
12176             The JNI environment of the event (current) thread
12177           </description>
12178       </param>
12179       <param id="thread">
12180         <jthread/>
12181           <description>
12182             Thread loading the class
12183           </description>
12184       </param>
12185       <param id="klass">
12186         <jclass/>
12187           <description>
12188             Class being loaded
12189           </description>
12190       </param>
12191     </parameters>
12192   </event>
12193 
12194   <elide>
12195   <event label="Class Unload"
12196          id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
12197     <description>
12198       A class unload event is generated when the class is about to be unloaded.
12199       Class unload events take place during garbage collection and must be 
12200       handled extremely carefully. The garbage collector holds many locks
12201       and has suspended all other threads, so the event handler cannot depend
12202       on the ability to acquire any locks. The class unload event handler should
12203       do as little as possible, perhaps by queuing information to be processed
12204       later.  In particular, the <code>jclass</code> should be used only in
12205       the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
12206       <ul>
12207         <li><functionlink id="GetClassSignature"></functionlink></li>
12208         <li><functionlink id="GetSourceFileName"></functionlink></li>
12209         <li><functionlink id="IsInterface"></functionlink></li>
12210         <li><functionlink id="IsArrayClass"></functionlink></li>
12211       </ul>
12212     </description>
12213     <origin>jvmdi</origin>
12214     <capabilities>
12215     </capabilities>
12216     <parameters> 
12217       <param id="jni_env">
12218         <outptr>
12219           <struct>JNIEnv</struct>
12220         </outptr>
12221           <description>
12222             The JNI environment of the event (current) thread
12223           </description>
12224       </param>
12225       <param id="thread">
12226         <jthread/>
12227           <description>
12228             Thread generating the class unload
12229           </description>
12230       </param>
12231       <param id="klass">
12232         <jclass/>
12233           <description>
12234             Class being unloaded
12235           </description>
12236       </param>
12237     </parameters>
12238   </event>
12239   </elide>
12240 
12241   <event label="Class Prepare"
12242          id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
12243     <description>
12244       A class prepare event is generated when class preparation is complete.
12245       At this point, class fields, methods, and implemented interfaces are 
12246       available, and no code from the class has been executed. Since array 
12247       classes never have fields or methods, class prepare events are not 
12248       generated for them. Class prepare events are not generated for 
12249       primitive classes (for example, <code>java.lang.Integer.TYPE</code>). 
12250     </description>
12251     <origin>jvmdi</origin>
12252     <capabilities>
12253     </capabilities>
12254     <parameters> 
12255       <param id="jni_env">
12256         <outptr>
12257           <struct>JNIEnv</struct>
12258         </outptr>
12259           <description>
12260             The JNI environment of the event (current) thread
12261           </description>
12262       </param>
12263       <param id="thread">
12264         <jthread/>
12265           <description>
12266             Thread generating the class prepare
12267           </description>
12268       </param>
12269       <param id="klass">
12270         <jclass/>
12271           <description>
12272             Class being prepared
12273           </description>
12274       </param>
12275     </parameters>
12276   </event>
12277 
12278   <event label="Class File Load Hook" phase="any"
12279          id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
12280     <description>
12281       This event is sent when the VM obtains class file data,
12282       but before it constructs
12283       the in-memory representation for that class. 
12284       This event is also sent when the class is being modified by the 
12285       <functionlink id="RetransformClasses"/> function or
12286       the <functionlink id="RedefineClasses"/> function,
12287       called in any <jvmti/> environment.
12288       The agent can instrument
12289       the existing class file data sent by the VM to include profiling/debugging hooks.
12290       See the description of 
12291       <internallink id="bci">bytecode instrumentation</internallink>
12292       for usage information.
12293       <p/>
12294     This event may be sent before the VM is initialized (the primordial 
12295     <functionlink id="GetPhase">phase</functionlink>). During this time
12296     no VM resources should be created.  Some classes might not be compatible
12297     with the function (eg. ROMized classes) and this event will not be
12298     generated for these classes.
12299     <p/>
12300     The agent must allocate the space for the modified 
12301     class file data buffer
12302     using the memory allocation function 
12303     <functionlink id="Allocate"></functionlink> because the
12304     VM is responsible for freeing the new class file data buffer
12305     using <functionlink id="Deallocate"></functionlink>.  
12306     Note that <functionlink id="Allocate"></functionlink>
12307     is permitted during the primordial phase.
12308     <p/>
12309     If the agent wishes to modify the class file, it must set 
12310     <code>new_class_data</code> to point
12311     to the newly instrumented class file data buffer and set
12312     <code>new_class_data_len</code> to the length of that 
12313     buffer before returning
12314     from this call.  If no modification is desired, the agent simply
12315     does not set <code>new_class_data</code>.  If multiple agents
12316     have enabled this event the results are chained. That is, if
12317     <code>new_class_data</code> has been set, it becomes the 
12318     <code>class_data</code> for the next agent.
12319     <p/>
12320     The order that this event is sent to each environment differs
12321     from other events.
12322     This event is sent to environments in the following order:
12323     <ul>
12324       <li><fieldlink id="can_retransform_classes"
12325                      struct="jvmtiCapabilities">retransformation
12326                                                 incapable</fieldlink>
12327           environments, in the 
12328           order in which they were created
12329       </li>
12330       <li><fieldlink id="can_retransform_classes"
12331                      struct="jvmtiCapabilities">retransformation
12332                                                 capable</fieldlink>
12333           environments, in the 
12334           order in which they were created
12335       </li>
12336     </ul>
12337     When triggered by <functionlink id="RetransformClasses"/>,
12338     this event is sent only to <fieldlink id="can_retransform_classes"
12339                      struct="jvmtiCapabilities">retransformation
12340                                                 capable</fieldlink>
12341     environments.
12342   </description>
12343   <origin>jvmpi</origin>
12344     <capabilities>
12345       <capability id="can_generate_all_class_hook_events"></capability>
12346     </capabilities>
12347     <parameters>
12348       <param id="jni_env">
12349         <outptr>
12350           <struct>JNIEnv</struct>
12351         </outptr>
12352           <description>
12353             The JNI environment of the event (current) thread.
12354             Will be <code>NULL</code> if sent during the primordial 
12355             <functionlink id="GetPhase">phase</functionlink>.
12356           </description>
12357       </param>
12358       <param id="class_being_redefined">
12359         <jclass/>
12360         <description>
12361           The class being
12362           <functionlink id="RedefineClasses">redefined</functionlink> or
12363           <functionlink id="RetransformClasses">retransformed</functionlink>.
12364           <code>NULL</code> if sent by class load.
12365         </description>
12366       </param>
12367       <param id="loader">
12368         <jobject/>
12369           <description>
12370             The class loader loading the class.  
12371             <code>NULL</code> if the bootstrap class loader.
12372           </description>
12373       </param>
12374       <param id="name">
12375         <vmbuf><char/></vmbuf>
12376         <description>
12377             Name of class being loaded as a VM internal qualified name
12378             (for example, "java/util/List"), encoded as a
12379             <internallink id="mUTF">modified UTF-8</internallink> string.
12380             Note: if the class is defined with a <code>NULL</code> name or
12381             without a name specified, <code>name</code> will be <code>NULL</code>.
12382         </description>
12383       </param>
12384       <param id="protection_domain">
12385         <jobject/>
12386         <description>
12387           The <code>ProtectionDomain</code> of the class.
12388         </description>
12389       </param>
12390       <param id="class_data_len">
12391         <jint/>
12392         <description>
12393           Length of current class file data buffer.
12394         </description>
12395       </param>
12396       <param id="class_data">
12397         <vmbuf><uchar/></vmbuf>
12398         <description>
12399           Pointer to the current class file data buffer.
12400         </description>
12401       </param>
12402       <param id="new_class_data_len">
12403         <outptr><jint/></outptr>
12404         <description>
12405           Pointer to the length of the new class file data buffer.
12406         </description>
12407       </param>
12408       <param id="new_class_data">
12409         <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
12410         <description>
12411           Pointer to the pointer to the instrumented class file data buffer.
12412         </description>
12413       </param>
12414     </parameters>
12415   </event>
12416 
12417   <event label="VM Start Event"
12418          id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
12419     <description>
12420       The VM initialization event signals the start of the VM.
12421       At this time JNI is live but the VM is not yet fully initialized.
12422       Once this event is generated, the agent is free to call any JNI function.
12423       This event signals the beginning of the start phase, 
12424       <jvmti/> functions permitted in the start phase may be called.
12425       <p/>
12426       In the case of VM start-up failure, this event will not be sent.
12427     </description>
12428     <origin>jvmdi</origin>
12429     <capabilities>
12430     </capabilities>
12431     <parameters>
12432       <param id="jni_env">
12433         <outptr>
12434           <struct>JNIEnv</struct>
12435         </outptr>
12436           <description>
12437             The JNI environment of the event (current) thread.
12438           </description>
12439       </param>
12440     </parameters>
12441   </event>
12442 
12443   <event label="VM Initialization Event"
12444          id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
12445     <description>
12446       The VM initialization event signals the completion of VM initialization. Once
12447       this event is generated, the agent is free to call any JNI or <jvmti/>
12448       function. The VM initialization event can be preceded by or can be concurrent
12449       with other events, but
12450       the preceding events should be handled carefully, if at all, because the
12451       VM has not completed its initialization. The thread start event for the
12452       main application thread is guaranteed not to occur until after the 
12453       handler for the VM initialization event returns.
12454       <p/>
12455       In the case of VM start-up failure, this event will not be sent.
12456     </description>
12457     <origin>jvmdi</origin>
12458     <capabilities>
12459     </capabilities>
12460     <parameters>
12461       <param id="jni_env">
12462         <outptr>
12463           <struct>JNIEnv</struct>
12464         </outptr>
12465           <description>
12466             The JNI environment of the event (current) thread.
12467           </description>
12468       </param>
12469       <param id="thread">
12470         <jthread/>
12471           <description>
12472             The initial thread
12473           </description>
12474       </param>
12475     </parameters>
12476   </event>
12477 
12478   <event label="VM Death Event"
12479          id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
12480     <description>
12481       The VM death event notifies the agent of the termination of the VM. 
12482       No events will occur after the VMDeath event.
12483       <p/>
12484       In the case of VM start-up failure, this event will not be sent.
12485       Note that <internallink id="onunload">Agent_OnUnload</internallink>
12486       will still be called in these cases.
12487     </description>
12488     <origin>jvmdi</origin>
12489     <capabilities>
12490     </capabilities>
12491     <parameters>
12492       <param id="jni_env">
12493         <outptr>
12494           <struct>JNIEnv</struct>
12495         </outptr>
12496           <description>
12497             The JNI environment of the event (current) thread
12498           </description>
12499       </param>
12500     </parameters>
12501   </event>
12502 
12503   <event label="Compiled Method Load"
12504          id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
12505     <description>
12506       Sent when a method is compiled and loaded into memory by the VM.
12507       If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
12508       If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
12509       followed by a new <code>CompiledMethodLoad</code> event.
12510       Note that a single method may have multiple compiled forms, and that
12511       this event will be sent for each form.
12512       Note also that several methods may be inlined into a single 
12513       address range, and that this event will be sent for each method.
12514       <p/>
12515       These events can be sent after their initial occurrence with
12516       <functionlink id="GenerateEvents"></functionlink>.
12517     </description>
12518     <origin>jvmpi</origin>
12519     <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
12520       <field id="start_address">
12521         <vmbuf><void/></vmbuf>
12522         <description>
12523           Starting native address of code corresponding to a location
12524         </description>
12525       </field>
12526       <field id="location">
12527         <jlocation/>
12528         <description>
12529           Corresponding location. See 
12530           <functionlink id="GetJLocationFormat"></functionlink>
12531           for the meaning of location.
12532         </description>
12533       </field>
12534     </typedef>
12535     <capabilities>
12536       <required id="can_generate_compiled_method_load_events"></required>
12537     </capabilities>
12538     <parameters>
12539       <param id="klass">
12540         <jclass method="method"/>
12541           <description>
12542             Class of the method being compiled and loaded
12543           </description>
12544       </param>
12545       <param id="method">
12546         <jmethodID class="klass"/>
12547           <description>
12548             Method being compiled and loaded
12549           </description>
12550       </param>
12551       <param id="code_size">
12552         <jint/>
12553         <description>
12554           Size of compiled code
12555         </description>
12556       </param>
12557       <param id="code_addr">
12558         <vmbuf><void/></vmbuf>
12559         <description>
12560           Address where compiled method code is loaded
12561         </description>
12562       </param>
12563       <param id="map_length">
12564         <jint/>
12565         <description>
12566           Number of <typelink id="jvmtiAddrLocationMap"></typelink>
12567           entries in the address map.
12568           Zero if mapping information cannot be supplied.
12569         </description>
12570       </param>
12571       <param id="map">
12572         <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
12573         <description>
12574           Map from native addresses to location.
12575           The native address range of each entry is from 
12576           <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
12577           to <code>start_address-1</code> of the next entry.
12578           <code>NULL</code> if mapping information cannot be supplied.
12579         </description>
12580       </param>
12581       <param id="compile_info">
12582         <vmbuf><void/></vmbuf>
12583         <description>
12584           VM-specific compilation information.  
12585           The referenced compile information is managed by the VM
12586           and must not depend on the agent for collection.
12587           A VM implementation defines the content and lifetime 
12588           of the information.
12589         </description>
12590       </param>
12591     </parameters>
12592   </event>
12593 
12594   <event label="Compiled Method Unload"
12595          id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
12596     <description>
12597       Sent when a compiled method is unloaded from memory.
12598       This event might not be sent on the thread which performed the unload.
12599       This event may be sent sometime after the unload occurs, but 
12600       will be sent before the memory is reused
12601       by a newly generated compiled method. This event may be sent after 
12602       the class is unloaded.
12603     </description>
12604     <origin>jvmpi</origin>
12605     <capabilities>
12606       <required id="can_generate_compiled_method_load_events"></required>
12607     </capabilities>
12608     <parameters>
12609       <param id="klass">
12610         <jclass method="method"/>
12611           <description>
12612             Class of the compiled method being unloaded.
12613           </description>
12614       </param>
12615       <param id="method">
12616         <jmethodID class="klass"/>
12617           <description>
12618             Compiled method being unloaded.
12619             For identification of the compiled method only -- the class 
12620             may be unloaded and therefore the method should not be used
12621             as an argument to further JNI or <jvmti/> functions.
12622           </description>
12623       </param>
12624       <param id="code_addr">
12625         <vmbuf><void/></vmbuf>
12626         <description>
12627           Address where compiled method code was loaded.
12628           For identification of the compiled method only -- 
12629           the space may have been reclaimed.
12630         </description>
12631       </param>
12632     </parameters>
12633   </event>
12634 
12635   <event label="Dynamic Code Generated" phase="any"
12636          id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
12637     <description>
12638       Sent when a component of the virtual machine is generated dynamically.
12639       This does not correspond to Java programming language code that is
12640       compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
12641       This is for native code--for example, an interpreter that is generated
12642       differently depending on command-line options.
12643       <p/>
12644       Note that this event has no controlling capability.
12645       If a VM cannot generate these events, it simply does not send any.
12646       <p/>
12647       These events can be sent after their initial occurrence with
12648       <functionlink id="GenerateEvents"></functionlink>.
12649     </description>
12650     <origin>jvmpi</origin>
12651     <capabilities>
12652     </capabilities>
12653     <parameters>
12654       <param id="name">
12655         <vmbuf><char/></vmbuf>
12656         <description>
12657           Name of the code, encoded as a
12658           <internallink id="mUTF">modified UTF-8</internallink> string.
12659           Intended for display to an end-user.
12660           The name might not be unique.
12661         </description>
12662       </param>
12663       <param id="address">
12664         <vmbuf><void/></vmbuf>
12665         <description>
12666           Native address of the code
12667         </description>
12668       </param>
12669       <param id="length">
12670         <jint/>
12671         <description>
12672           Length in bytes of the code
12673         </description>
12674       </param>
12675     </parameters>
12676   </event>
12677 
12678   <event label="Data Dump Request"
12679          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
12680     <description>
12681       Sent by the VM to request the agent to dump its data.  This
12682       is just a hint and the agent need not react to this event.
12683       This is useful for processing command-line signals from users.  For
12684       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris
12685       causes the VM to send this event to the agent.
12686     </description>
12687     <origin>jvmpi</origin>
12688     <capabilities>
12689     </capabilities>
12690     <parameters>
12691     </parameters>
12692   </event>
12693 
12694   <event label="Monitor Contended Enter"
12695          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
12696     <description>
12697       Sent when a thread is attempting to enter a Java programming language
12698       monitor already acquired by another thread.
12699     </description>
12700     <origin>jvmpi</origin>
12701     <capabilities>
12702       <required id="can_generate_monitor_events"></required>
12703     </capabilities>
12704     <parameters>
12705       <param id="jni_env">
12706         <outptr>
12707           <struct>JNIEnv</struct>
12708         </outptr>
12709           <description>
12710             The JNI environment of the event (current) thread
12711           </description>
12712       </param>
12713       <param id="thread">
12714         <jthread/>
12715           <description>
12716             JNI local reference to the thread 
12717             attempting to enter the monitor
12718           </description>
12719       </param>
12720       <param id="object">
12721         <jobject/>
12722           <description>
12723             JNI local reference to the monitor
12724           </description>
12725       </param>
12726     </parameters>
12727   </event>
12728 
12729   <event label="Monitor Contended Entered"
12730          id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
12731     <description>
12732       Sent when a thread enters a Java programming language
12733       monitor after waiting for it to be released by another thread.
12734     </description>
12735     <origin>jvmpi</origin>
12736     <capabilities>
12737       <required id="can_generate_monitor_events"></required>
12738     </capabilities>
12739     <parameters>
12740       <param id="jni_env">
12741         <outptr>
12742           <struct>JNIEnv</struct>
12743         </outptr>
12744           <description>
12745             The JNI environment of the event (current) thread
12746           </description>
12747       </param>
12748       <param id="thread">
12749         <jthread/>
12750           <description>
12751             JNI local reference to the thread entering
12752             the monitor
12753           </description>
12754       </param>
12755       <param id="object">
12756         <jobject/>
12757           <description>
12758             JNI local reference to the monitor
12759           </description>
12760       </param>
12761     </parameters>
12762   </event>
12763 
12764   <event label="Monitor Wait"
12765          id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
12766     <description>
12767       Sent when a thread is about to wait on an object.
12768     </description>
12769     <origin>jvmpi</origin>
12770     <capabilities>
12771       <required id="can_generate_monitor_events"></required>
12772     </capabilities>
12773     <parameters>
12774       <param id="jni_env">
12775         <outptr>
12776           <struct>JNIEnv</struct>
12777         </outptr>
12778           <description>
12779             The JNI environment of the event (current) thread
12780           </description>
12781       </param>
12782       <param id="thread">
12783         <jthread/>
12784           <description>
12785             JNI local reference to the thread about to wait
12786           </description>
12787       </param>
12788       <param id="object">
12789         <jobject/>
12790           <description>
12791             JNI local reference to the monitor
12792           </description>
12793       </param>
12794       <param id="timeout">
12795         <jlong/>
12796         <description>
12797           The number of milliseconds the thread will wait
12798         </description>
12799       </param>
12800     </parameters>
12801   </event>
12802 
12803   <event label="Monitor Waited"
12804          id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
12805     <description>
12806       Sent when a thread finishes waiting on an object.
12807     </description>
12808     <origin>jvmpi</origin>
12809     <capabilities>
12810       <required id="can_generate_monitor_events"></required>
12811     </capabilities>
12812     <parameters>
12813       <param id="jni_env">
12814         <outptr>
12815           <struct>JNIEnv</struct>
12816         </outptr>
12817           <description>
12818             The JNI environment of the event (current) thread
12819           </description>
12820       </param>
12821       <param id="thread">
12822         <jthread/>
12823           <description>
12824             JNI local reference to the thread that was finished waiting
12825           </description>
12826       </param>
12827       <param id="object">
12828         <jobject/>
12829           <description>
12830             JNI local reference to the monitor.
12831           </description>
12832       </param>
12833       <param id="timed_out">
12834         <jboolean/>
12835         <description>
12836           True if the monitor timed out
12837         </description>
12838       </param>
12839     </parameters>
12840   </event>
12841 
12842   <event label="Resource Exhausted"
12843          id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
12844          since="1.1">
12845     <description>
12846       Sent when a VM resource needed by a running application has been exhausted.
12847       Except as required by the optional capabilities, the set of resources 
12848       which report exhaustion is implementation dependent.
12849       <p/>
12850       The following bit flags define the properties of the resource exhaustion:
12851       <constants id="jvmtiResourceExhaustionFlags" 
12852                  label="Resource Exhaustion Flags" 
12853                  kind="bits" 
12854                  since="1.1">
12855         <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
12856           After this event returns, the VM will throw a
12857           <code>java.lang.OutOfMemoryError</code>.
12858         </constant>         
12859         <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
12860           The VM was unable to allocate memory from the <tm>Java</tm> 
12861           platform <i>heap</i>.
12862           The <i>heap</i> is the runtime
12863           data area from which memory for all class instances and
12864           arrays are allocated.
12865         </constant>         
12866         <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
12867           The VM was unable to create a thread.
12868         </constant>         
12869       </constants>
12870     </description>
12871     <origin>new</origin>
12872     <capabilities>
12873       <capability id="can_generate_resource_exhaustion_heap_events">
12874         Can generate events when the VM is unable to allocate memory from the
12875         <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
12876       </capability>
12877       <capability id="can_generate_resource_exhaustion_threads_events">
12878         Can generate events when the VM is unable to 
12879         <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
12880         a thread</internallink>.
12881       </capability>
12882     </capabilities>
12883     <parameters>
12884       <param id="jni_env">
12885         <outptr>
12886           <struct>JNIEnv</struct>
12887         </outptr>
12888           <description>
12889             The JNI environment of the event (current) thread
12890           </description>
12891       </param>
12892       <param id="flags">
12893         <jint/>
12894         <description>
12895           Flags defining the properties of the of resource exhaustion
12896           as specified by the 
12897           <internallink id="jvmtiResourceExhaustionFlags">Resource 
12898           Exhaustion Flags</internallink>.
12899           </description>
12900         </param>
12901       <param id="reserved">
12902         <vmbuf><void/></vmbuf>
12903         <description>
12904           Reserved.
12905         </description>
12906       </param>
12907       <param id="description">
12908         <vmbuf><char/></vmbuf>
12909         <description>
12910           Description of the resource exhaustion, encoded as a
12911           <internallink id="mUTF">modified UTF-8</internallink> string.
12912         </description>
12913       </param>
12914     </parameters>
12915   </event>
12916 
12917   <event label="VM Object Allocation"
12918          id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
12919     <description>
12920       Sent when a method causes the virtual machine to allocate an 
12921       Object visible to Java programming language code and the
12922       allocation is not detectable by other intrumentation mechanisms.
12923       Generally object allocation should be detected by instrumenting
12924       the bytecodes of allocating methods.
12925       Object allocation generated in native code by JNI function
12926       calls should be detected using 
12927       <internallink id="jniIntercept">JNI function interception</internallink>.
12928       Some methods might not have associated bytecodes and are not 
12929       native methods, they instead are executed directly by the 
12930       VM. These methods should send this event.
12931       Virtual machines which are incapable of bytecode instrumentation
12932       for some or all of their methods can send this event.
12933       <p/>
12934       Typical examples where this event might be sent:
12935       <ul>
12936         <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
12937         <li>Methods not represented by bytecodes -- for example, VM intrinsics and
12938             J2ME preloaded classes</li>
12939       </ul>
12940       Cases where this event would not be generated:
12941       <ul>
12942         <li>Allocation due to bytecodes -- for example, the <code>new</code>
12943             and <code>newarray</code> VM instructions</li>
12944         <li>Allocation due to JNI function calls -- for example,
12945             <code>AllocObject</code></li>
12946         <li>Allocations during VM initialization</li>
12947         <li>VM internal objects</li>
12948       </ul>
12949     </description>
12950     <origin>new</origin>
12951     <capabilities>
12952       <required id="can_generate_vm_object_alloc_events"></required>
12953     </capabilities>
12954     <parameters>
12955       <param id="jni_env">
12956         <outptr>
12957           <struct>JNIEnv</struct>
12958         </outptr>
12959           <description>
12960             The JNI environment of the event (current) thread
12961           </description>
12962       </param>
12963       <param id="thread">
12964         <jthread/>
12965           <description>
12966             Thread allocating the object.
12967           </description>
12968       </param>
12969       <param id="object">
12970         <jobject/>
12971           <description>
12972             JNI local reference to the object that was allocated
12973           </description>
12974       </param>
12975       <param id="object_klass">
12976         <jclass/>
12977           <description>
12978             JNI local reference to the class of the object
12979           </description>
12980       </param>
12981       <param id="size">
12982         <jlong/>
12983         <description>
12984             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
12985         </description>
12986       </param>
12987     </parameters>
12988   </event>
12989 
12990   <event label="Object Free"
12991          id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
12992     <description>
12993       An Object Free event is sent when the garbage collector frees an object.
12994       Events are only sent for tagged objects--see
12995       <internallink id="Heap">heap functions</internallink>.
12996       <p/>
12997       The event handler must not use JNI functions and
12998       must not use <jvmti/> functions except those which
12999       specifically allow such use (see the raw monitor, memory management,
13000       and environment local storage functions).
13001     </description>
13002     <origin>new</origin>
13003     <capabilities>
13004       <required id="can_generate_object_free_events"></required>
13005     </capabilities>
13006     <parameters>
13007       <param id="tag">
13008         <jlong/>
13009         <description>
13010           The freed object's tag
13011         </description>
13012       </param>
13013     </parameters>
13014   </event>
13015 
13016   <event label="Garbage Collection Start"
13017          id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
13018     <description>
13019       A Garbage Collection Start event is sent when a 
13020       garbage collection pause begins.
13021       Only stop-the-world collections are reported--that is, collections during
13022       which all threads cease to modify the state of the Java virtual machine.
13023       This means that some collectors will never generate these events.
13024       This event is sent while the VM is still stopped, thus
13025       the event handler must not use JNI functions and
13026       must not use <jvmti/> functions except those which
13027       specifically allow such use (see the raw monitor, memory management,
13028       and environment local storage functions).
13029       <p/>
13030       This event is always sent as a matched pair with 
13031       <eventlink id="GarbageCollectionFinish"/> 
13032       (assuming both events are enabled) and no garbage collection
13033       events will occur between them.
13034     </description>
13035     <origin>new</origin>
13036     <capabilities>
13037       <required id="can_generate_garbage_collection_events"></required>
13038     </capabilities>
13039     <parameters>
13040     </parameters>
13041   </event>
13042 
13043   <event label="Garbage Collection Finish"
13044          id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
13045     <description>
13046       A Garbage Collection Finish event is sent when a
13047       garbage collection pause ends.
13048       This event is sent while the VM is still stopped, thus
13049       the event handler must not use JNI functions and
13050       must not use <jvmti/> functions except those which
13051       specifically allow such use (see the raw monitor, memory management,
13052       and environment local storage functions).
13053       <p/>
13054       Some agents may need to do post garbage collection operations that
13055       require the use of the disallowed <jvmti/> or JNI functions. For these
13056       cases an agent thread can be created which waits on a raw monitor,
13057       and the handler for the Garbage Collection Finish event simply
13058       notifies the raw monitor
13059       <p/>
13060       This event is always sent as a matched pair with 
13061       <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
13062       <issue>
13063         The most important use of this event is to provide timing information,
13064         and thus additional information is not required.  However,  
13065         information about the collection which is "free" should be included -
13066         what that information is needs to be determined.
13067       </issue>
13068     </description>
13069     <origin>new</origin>
13070     <capabilities>
13071       <required id="can_generate_garbage_collection_events"></required>
13072     </capabilities>
13073     <parameters>
13074     </parameters>
13075   </event>
13076 
13077   <elide>
13078   <event label="Verbose Output" phase="any"
13079          id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
13080     <description>
13081       Send verbose messages as strings.
13082         <issue>
13083           This format is extremely fragile, as it can change with each
13084           platform, collector and version.  Alternatives include:
13085           <ul>
13086             <li>building off Java programming language M and M APIs</li>
13087             <li>XML</li>
13088             <li>key/value pairs</li>
13089             <li>removing it</li>
13090           </ul>
13091         </issue>
13092         <issue>
13093           Though this seemed trivial to implement.  
13094           In the RI it appears this will be quite complex.
13095         </issue>
13096     </description>
13097     <origin>new</origin>
13098     <capabilities>
13099     </capabilities>
13100     <parameters>
13101       <param id="flag">
13102         <enum>jvmtiVerboseFlag</enum>
13103         <description>
13104           Which verbose output is being sent.
13105         </description>
13106       </param>
13107       <param id="message">
13108         <vmbuf><char/></vmbuf>
13109         <description>
13110           Message text, encoded as a
13111           <internallink id="mUTF">modified UTF-8</internallink> string.
13112         </description>
13113       </param>
13114     </parameters>
13115   </event>
13116   </elide>
13117 
13118 </eventsection>
13119 
13120 <datasection>
13121   <intro>
13122     <jvmti/> extends the data types defined by JNI.
13123   </intro>
13124   <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
13125     <basetype id="jboolean">
13126       <description>
13127         Holds a Java programming language <code>boolean</code>.
13128         Unsigned 8 bits.
13129       </description>
13130     </basetype>
13131     <basetype id="jchar">
13132       <description>
13133         Holds a Java programming language <code>char</code>.
13134         Unsigned 16 bits.
13135       </description>
13136     </basetype>
13137     <basetype id="jint">
13138       <description>
13139         Holds a Java programming language <code>int</code>. 
13140         Signed 32 bits.
13141       </description>
13142     </basetype>
13143     <basetype id="jlong">
13144       <description>
13145         Holds a Java programming language <code>long</code>. 
13146         Signed 64 bits.
13147       </description>
13148     </basetype>
13149     <basetype id="jfloat">
13150       <description>
13151         Holds a Java programming language <code>float</code>. 
13152         32 bits.
13153       </description>
13154     </basetype>
13155     <basetype id="jdouble">
13156       <description>
13157         Holds a Java programming language <code>double</code>. 
13158         64 bits.
13159       </description>
13160     </basetype>
13161     <basetype id="jobject">
13162       <description>
13163         Holds a Java programming language object. 
13164       </description>
13165     </basetype>
13166     <basetype id="jclass">
13167       <description>
13168         Holds a Java programming language class. 
13169       </description>
13170     </basetype>
13171     <basetype id="jvalue">
13172       <description>
13173         Is a union of all primitive types and <code>jobject</code>.  Thus, holds any Java 
13174         programming language value. 
13175       </description>
13176     </basetype>
13177     <basetype id="jfieldID">
13178       <description>
13179         Identifies a Java programming language field. 
13180         <code>jfieldID</code>s returned by <jvmti/> functions and events may be
13181         safely stored.
13182       </description>
13183     </basetype>
13184     <basetype id="jmethodID">
13185       <description>
13186         Identifies a Java programming language method, initializer, or constructor. 
13187         <code>jmethodID</code>s returned by <jvmti/> functions and events may be
13188         safely stored.  However, if the class is unloaded, they become invalid
13189         and must not be used.
13190       </description>
13191     </basetype>
13192     <basetype id="JNIEnv">
13193       <description>
13194         Pointer to the JNI function table.  Pointer to this (<code>JNIEnv *</code>)
13195         is a JNI environment. 
13196       </description>
13197     </basetype>
13198   </basetypes>
13199 
13200   <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
13201     <basetype id="jvmtiEnv">
13202       <description>
13203         The <jvmti/> <internallink id="environments">environment</internallink> pointer. 
13204         See the <internallink id="FunctionSection">Function Section</internallink>.
13205         <code>jvmtiEnv</code> points to the 
13206         <internallink id="FunctionTable">function table</internallink> pointer.
13207       </description>
13208     </basetype>
13209     <basetype id="jthread">
13210       <definition>typedef jobject jthread;</definition>
13211       <description>
13212         Subtype of <datalink id="jobject"></datalink> that holds a thread.
13213       </description>
13214     </basetype>
13215     <basetype id="jthreadGroup">
13216       <definition>typedef jobject jthreadGroup;</definition>
13217       <description>
13218         Subtype of <datalink id="jobject"></datalink> that holds a thread group.
13219       </description>
13220     </basetype>
13221     <basetype id="jlocation">
13222       <definition>typedef jlong jlocation;</definition>
13223       <description>
13224         A 64 bit value, representing a monotonically increasing 
13225         executable position within a method. 
13226         <code>-1</code> indicates a native method.
13227         See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
13228         given VM.
13229       </description>
13230     </basetype>
13231     <basetype id="jrawMonitorID">
13232       <definition>struct _jrawMonitorID;
13233 typedef struct _jrawMonitorID *jrawMonitorID;</definition>
13234       <description>
13235         A raw monitor.
13236       </description>
13237     </basetype>
13238     <basetype id="jvmtiError">
13239       <description>
13240         Holds an error return code.
13241         See the <internallink id="ErrorSection">Error section</internallink> for possible values.
13242         <example>
13243 typedef enum { 
13244     JVMTI_ERROR_NONE = 0,  
13245     JVMTI_ERROR_INVALID_THREAD = 10,
13246       ... 
13247 } jvmtiError;
13248 </example>
13249       </description>
13250     </basetype>
13251     <basetype id="jvmtiEvent">
13252       <description>
13253         An identifier for an event type.
13254         See the <internallink id="EventSection">Event section</internallink> for possible values.
13255         It is guaranteed that future versions of this specification will 
13256         never assign zero as an event type identifier.
13257 <example>
13258 typedef enum { 
13259     JVMTI_EVENT_SINGLE_STEP = 1, 
13260     JVMTI_EVENT_BREAKPOINT = 2, 
13261       ... 
13262 } jvmtiEvent;
13263 </example>
13264       </description>
13265     </basetype>
13266     <basetype id="jvmtiEventCallbacks">
13267       <description>
13268         The callbacks used for events.
13269 <example>
13270 typedef struct {
13271     jvmtiEventVMInit VMInit;
13272     jvmtiEventVMDeath VMDeath;
13273       ... 
13274 } jvmtiEventCallbacks;
13275 </example>
13276         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> 
13277         for the complete structure.
13278         <p/>
13279         Where, for example, the VM initialization callback is defined:
13280 <example>
13281 typedef void (JNICALL *jvmtiEventVMInit)
13282     (jvmtiEnv *jvmti_env, 
13283      JNIEnv* jni_env,
13284      jthread thread);
13285 </example>
13286         See the individual events for the callback function definition.
13287       </description>
13288     </basetype>
13289     <basetype id="jniNativeInterface">
13290       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
13291       <description>
13292         Typedef for the JNI function table <code>JNINativeInterface</code>
13293         defined in the 
13294         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>.
13295         The JNI reference implementation defines this with an underscore.
13296       </description>
13297     </basetype>
13298   </basetypes>
13299 
13300 </datasection>
13301 
13302 <issuessection label="Issues">
13303   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
13304     JVMDI requires that the agent suspend threads before calling
13305     certain sensitive functions.  JVMPI requires garbage collection to be 
13306     disabled before calling certain sensitive functions. 
13307     It was suggested that rather than have this requirement, that
13308     VM place itself in a suitable state before performing an
13309     operation.  This makes considerable sense since each VM
13310     knows its requirements and can most easily arrange a
13311     safe state.  
13312     <p/>
13313     The ability to externally suspend/resume threads will, of
13314     course, remain.  The ability to enable/disable garbage collection will not.
13315     <p/>
13316     This issue is resolved--suspend will not
13317     be required.  The spec has been updated to reflect this.
13318   </intro>
13319   
13320   <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
13321     There are a variety of approaches to sampling call stacks.
13322     The biggest bifurcation is between VM controlled and agent
13323     controlled.  
13324     <p/>
13325     This issue is resolved--agent controlled
13326     sampling will be the approach.
13327   </intro>
13328   
13329   <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
13330     JVMDI represents threads as jthread.  JVMPI primarily
13331     uses JNIEnv* to represent threads.  
13332     <p/>
13333     The Expert Group has chosen jthread as the representation
13334     for threads in <jvmti/>.
13335     JNIEnv* is sent by
13336     events since it is needed to JNI functions.  JNIEnv, per the
13337     JNI spec, are not supposed to be used outside their thread.
13338   </intro>
13339 
13340   <intro id="design" label="Resolved Issue: Method Representation">
13341     The JNI spec allows an implementation to depend on jclass/jmethodID
13342     pairs, rather than simply a jmethodID, to reference a method.  
13343     JVMDI, for consistency, choose the same representation.  
13344     JVMPI, however, specifies that a jmethodID alone maps to a
13345     method.  Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
13346     pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
13347     In fact, any JVM implementation that supports JVMPI must have
13348     such a representation.  
13349     <jvmti/> will use jmethodID as a unique representation of a method
13350     (no jclass is used).
13351     There should be efficiency gains, particularly in 
13352     functionality like stack dumping, to this representation.
13353     <p/>
13354     Note that fields were not used in JVMPI and that the access profile
13355     of fields differs from methods--for implementation efficiency 
13356     reasons, a jclass/jfieldID pair will still be needed for field 
13357     reference.
13358   </intro>
13359 
13360   <intro id="localReferenceIssue" label="Resolved Issue: Local References">
13361     Functions return local references. 
13362   </intro>
13363 
13364   <intro id="frameRep" label="Resolved Issue: Representation of frames">
13365     In JVMDI, a frame ID is used to represent a frame.  Problem with this
13366     is that a VM must track when a frame becomes invalid, a far better
13367     approach, and the one used in <jvmti/>, is to reference frames by depth.
13368   </intro>
13369 
13370   <intro id="requiredCapabilities" label="Issue: Required Capabilities">
13371     Currently, having a required capabilities means that the functionality
13372     is optional.   Capabilities are useful even for required functionality
13373     since they can inform the VM is needed set-up.  Thus, there should be
13374     a set of capabilities that a conformant implementation must provide
13375     (if requested during Agent_OnLoad).
13376   </intro>
13377 
13378   <intro id="taghint" label="Proposal: add tag hint function">
13379     A hint of the percentage of objects that will be tagged would 
13380     help the VM pick a good implementation.
13381   </intro>
13382 
13383   <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
13384   How difficult or easy would be to extend the monitor_info category to include 
13385     <pre>
13386   - current number of monitors 
13387   - enumeration of monitors 
13388   - enumeration of threads waiting on a given monitor 
13389     </pre>
13390   The reason for my question is the fact that current get_monitor_info support 
13391   requires the agent to specify a given thread to get the info which is probably 
13392   OK in the profiling/debugging space, while in the monitoring space the agent 
13393   could be watching the monitor list and then decide which thread to ask for 
13394   the info. You might ask why is this important for monitoring .... I think it 
13395   can aid in the detection/prediction of application contention caused by hot-locks.
13396   </intro>
13397 </issuessection>
13398 
13399 <changehistory id="ChangeHistory" update="09/05/07">
13400   <intro>
13401     The <jvmti/> specification is an evolving document with major, minor, 
13402     and micro version numbers.
13403     A released version of the specification is uniquely identified
13404     by its major and minor version.
13405     The functions, events, and capabilities in this specification 
13406     indicate a "Since" value which is the major and minor version in
13407     which it was introduced.
13408     The version of the specification implemented by the VM can 
13409     be retrieved at runtime with the <functionlink id="GetVersionNumber"/> 
13410     function.
13411   </intro>
13412   <change date="14 Nov 2002">
13413     Converted to XML document.
13414   </change>
13415   <change date="14 Nov 2002">
13416     Elided heap dump functions (for now) since what was there
13417     was wrong.
13418   </change>
13419   <change date="18 Nov 2002">
13420     Added detail throughout.
13421   </change>
13422   <change date="18 Nov 2002">
13423     Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
13424   </change>
13425   <change date="19 Nov 2002">
13426     Added AsyncGetStackTrace.
13427   </change>
13428   <change date="19 Nov 2002">
13429     Added jframeID return to GetStackTrace.
13430   </change>
13431   <change date="19 Nov 2002">
13432     Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
13433     since they are redundant with GetStackTrace.
13434   </change>
13435   <change date="19 Nov 2002">
13436     Elided ClearAllBreakpoints since it has always been redundant.
13437   </change>
13438   <change date="19 Nov 2002">
13439     Added GetSystemProperties.
13440   </change>
13441   <change date="19 Nov 2002">
13442     Changed the thread local storage functions to use jthread.
13443   </change>
13444   <change date="20 Nov 2002">
13445     Added GetJLocationFormat.
13446   </change>
13447   <change date="22 Nov 2002">
13448     Added events and introductory text.
13449   </change>
13450   <change date="22 Nov 2002">
13451     Cross reference type and constant definitions.
13452   </change>
13453   <change date="24 Nov 2002">
13454     Added DTD.
13455   </change>
13456   <change date="24 Nov 2002">
13457     Added capabilities function section.
13458   </change>
13459   <change date="29 Nov 2002">
13460     Assign capabilities to each function and event.
13461   </change>
13462   <change date="29 Nov 2002">
13463     Add <internallink id="jniIntercept">JNI interception functions</internallink>.
13464   </change>
13465   <change date="30 Nov 2002">
13466     Auto generate SetEventNotificationMode capabilities.
13467   </change>
13468   <change date="30 Nov 2002">
13469     Add <eventlink id="VMObjectAlloc"></eventlink> event.
13470   </change>
13471   <change date="30 Nov 2002">
13472     Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
13473   </change>
13474   <change date="30 Nov 2002">
13475     Add const to declarations.
13476   </change>
13477   <change date="30 Nov 2002">
13478     Change method exit and frame pop to send on exception.
13479   </change>
13480   <change date="1 Dec 2002">
13481     Add ForceGarbageCollection.
13482   </change>
13483   <change date="2 Dec 2002">
13484     Redo Xrun section; clarify GetStackTrace and add example;
13485     Fix width problems; use "agent" consistently.
13486   </change>
13487   <change date="8 Dec 2002">
13488     Remove previous start-up intro.
13489     Add <internallink id="environments"><jvmti/> Environments</internallink>
13490     section.
13491   </change>
13492   <change date="8 Dec 2002">
13493     Add <functionlink id="DisposeEnvironment"></functionlink>.
13494   </change>
13495   <change date="9 Dec 2002">
13496     Numerous minor updates.
13497   </change>
13498   <change date="15 Dec 2002">
13499     Add heap profiling functions added:
13500     get/set annotation, iterate live objects/heap.
13501     Add heap profiling functions place holder added:
13502     heap roots.
13503     Heap profiling event added: object free. 
13504     Heap profiling event redesigned: vm object allocation. 
13505     Heap profiling event placeholders added: garbage collection start/finish. 
13506     Native method bind event added.
13507   </change>
13508   <change date="19 Dec 2002">
13509     Revamp suspend/resume functions.
13510     Add origin information with jvmdi tag.
13511     Misc fixes.
13512   </change>
13513   <change date="24 Dec 2002">
13514     Add semantics to types.
13515   </change>
13516   <change date="27 Dec 2002">
13517     Add local reference section.
13518     Autogenerate parameter descriptions from types.
13519   </change>
13520   <change date="28 Dec 2002">
13521     Document that RunAgentThread sends threadStart.
13522   </change>
13523   <change date="29 Dec 2002">
13524     Remove redundant local ref and dealloc warning.
13525     Convert GetRawMonitorName to allocated buffer.
13526     Add GenerateEvents.
13527   </change>
13528   <change date="30 Dec 2002">
13529     Make raw monitors a type and rename to "jrawMonitorID".
13530   </change>
13531   <change date="1 Jan 2003">
13532     Include origin information.
13533     Clean-up JVMDI issue references.
13534     Remove Deallocate warnings which are now automatically generated.
13535   </change>
13536   <change date="2 Jan 2003">
13537     Fix representation issues for jthread.
13538   </change>
13539   <change date="3 Jan 2003">
13540     Make capabilities buffered out to 64 bits - and do it automatically.
13541   </change>
13542   <change date="4 Jan 2003">
13543     Make constants which are enumeration into enum types.
13544     Parameters now of enum type.
13545     Clean-up and index type section.
13546     Replace remaining datadef entities with callback.
13547   </change>
13548   <change date="7 Jan 2003">
13549     Correct GenerateEvents description.
13550     More internal semantics work.
13551   </change>
13552   <change date="9 Jan 2003">
13553     Replace previous GetSystemProperties with two functions
13554     which use allocated information instead fixed.
13555     Add SetSystemProperty.
13556     More internal semantics work.
13557   </change>
13558   <change date="12 Jan 2003">
13559     Add varargs to end of SetEventNotificationMode.
13560   </change>
13561   <change date="20 Jan 2003">
13562     Finish fixing spec to reflect that alloc sizes are jlong.
13563   </change>
13564   <change date="22 Jan 2003">
13565     Allow NULL as RunAgentThread arg.
13566   </change>
13567   <change date="22 Jan 2003">
13568     Fixed names to standardized naming convention
13569     Removed AsyncGetStackTrace.
13570   </change>
13571   <change date="29 Jan 2003">
13572     Since we are using jthread, removed GetThread.
13573   </change>
13574   <change date="31 Jan 2003">
13575     Change GetFieldName to allow NULLs like GetMethodName.
13576   </change>
13577   <change date="29 Feb 2003" version="v40">
13578       Rewrite the introductory text, adding sections on
13579       start-up, environments and bytecode instrumentation.
13580       Change the command line arguments per EG discussions.
13581       Add an introduction to the capabilities section.
13582       Add the extension mechanism category and functions.
13583       Mark for deletion, but clarified anyhow, SuspendAllThreads.
13584       Rename IterateOverLiveObjects to IterateOverReachableObjects and
13585       change the text accordingly.
13586       Clarify IterateOverHeap.
13587       Clarify CompiledMethodLoad.
13588       Discuss prerequisite state for Calling Functions.
13589       Clarify SetAllocationHooks.
13590       Added issues ("To be resolved:") through-out.
13591       And so on...
13592   </change>
13593   <change date="6 Mar 2003" version="v41">
13594       Remove struct from the call to GetOwnedMonitorInfo.
13595       Automatically generate most error documentation, remove
13596       (rather broken) hand written error doc.
13597       Better describe capability use (empty initial set).
13598       Add min value to jint params.
13599       Remove the capability can_access_thread_local_storage.
13600       Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
13601       same for *NOT_IMPLEMENTED.
13602       Description fixes.
13603   </change>
13604   <change date="8 Mar 2003" version="v42">
13605       Rename GetClassSignature to GetClassName.
13606       Rename IterateOverClassObjects to IterateOverInstancesOfClass.
13607       Remove GetMaxStack (operand stack isn't used in <jvmti/>).
13608       Description fixes: define launch-time, remove native frame pop
13609       from PopFrame, and assorted clarifications.
13610   </change>
13611   <change date="8 Mar 2003" version="v43">
13612       Fix minor editing problem.
13613   </change>
13614   <change date="10 Mar 2003" version="v44">
13615       Add phase information.
13616       Remap (compact) event numbers.
13617   </change>
13618   <change date="11 Mar 2003" version="v45">
13619       More phase information - allow "any".
13620       Elide raw monitor queries and events.
13621       Minor description fixes.
13622   </change>
13623   <change date="12 Mar 2003" version="v46">
13624       Add GetPhase.
13625       Use "phase" through document.
13626       Elide GetRawMonitorName.
13627       Elide GetObjectMonitors.
13628   </change>
13629   <change date="12 Mar 2003" version="v47">
13630       Fixes from link, XML, and spell checking.
13631       Auto-generate the callback structure.
13632   </change>
13633   <change date="13 Mar 2003" version="v48">
13634       One character XML fix.
13635   </change>
13636   <change date="13 Mar 2003" version="v49">
13637       Change function parameter names to be consistent with 
13638       event parameters (fooBarBaz becomes foo_bar_baz).
13639   </change>
13640   <change date="14 Mar 2003" version="v50">
13641       Fix broken link.  Fix thread markers.
13642   </change>
13643   <change date="14 Mar 2003" version="v51">
13644       Change constants so they are under 128 to workaround
13645       compiler problems.
13646   </change>
13647   <change date="23 Mar 2003" version="v52">
13648       Overhaul capabilities.  Separate GetStackTrace into
13649       GetStackTrace and GetStackFrames.
13650   </change>
13651   <change date="8 Apr 2003" version="v54">
13652       Use depth instead of jframeID to reference frames.
13653       Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
13654       Remove frame arg from events.
13655   </change>
13656   <change date="9 Apr 2003" version="v55">
13657       Remove GetObjectWithAnnotation since tests show bufferred approach more efficient.
13658       Add missing annotation_count to GetObjectsWithAnnotations
13659   </change>
13660   <change date="10 Apr 2003" version="v56">
13661       Remove confusing parenthetical statement in GetObjectsWithAnnotations
13662   </change>
13663   <change date="13 Apr 2003" version="v58">
13664       Replace jclass/jmethodID representation of method with simply jmethodID;
13665       Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
13666       Replace can_access_frames with can_access_local_variables; remove from purely stack access.
13667       Use can_get_synthetic_attribute; fix description.
13668       Clarify that zero length arrays must be deallocated.
13669       Clarify RelinquishCapabilities.
13670       Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
13671   </change>
13672   <change date="27 Apr 2003" version="v59">
13673       Remove lingering indirect references to OBSOLETE_METHOD_ID.
13674   </change>
13675   <change date="4 May 2003" version="v60">
13676       Allow DestroyRawMonitor during OnLoad.
13677   </change>
13678   <change date="7 May 2003" version="v61">
13679       Added not monitor owner error return to DestroyRawMonitor.
13680   </change>
13681   <change date="13 May 2003" version="v62">
13682       Clarify semantics of raw monitors.
13683       Change flags on <code>GetThreadStatus</code>.
13684       <code>GetClassLoader</code> return NULL for the bootstrap class loader.
13685       Add <code>GetClassName</code> issue.
13686       Define local variable signature.
13687       Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
13688       Remove over specification in <code>GetObjectsWithAnnotations</code>.
13689       Elide <code>SetAllocationHooks</code>.
13690       Elide <code>SuspendAllThreads</code>.
13691   </change>
13692   <change date="14 May 2003" version="v63">
13693       Define the data type <code>jvmtiEventCallbacks</code>.
13694       Zero length allocations return NULL.  
13695       Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.  
13696       Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
13697   </change>
13698   <change date="15 May 2003" version="v64">
13699       Better wording, per review.
13700   </change>
13701   <change date="15 May 2003" version="v65">
13702       First Alpha.
13703       Make jmethodID and jfieldID unique, jclass not used.
13704   </change>
13705   <change date="27 May 2003" version="v66">
13706       Fix minor XSLT errors.
13707   </change>
13708   <change date="13 June 2003" version="v67">
13709       Undo making jfieldID unique (jmethodID still is).
13710   </change>
13711   <change date="17 June 2003" version="v68">
13712       Changes per June 11th Expert Group meeting --
13713       Overhaul Heap functionality: single callback, 
13714       remove GetHeapRoots, add reachable iterators,
13715       and rename "annotation" to "tag".
13716       NULL thread parameter on most functions is current
13717       thread.
13718       Add timers.
13719       Remove ForceExit.
13720       Add GetEnvironmentLocalStorage.
13721       Add verbose flag and event.
13722       Add AddToBootstrapClassLoaderSearch.
13723       Update ClassFileLoadHook.
13724   </change>
13725   <change date="18 June 2003" version="v69">
13726       Clean up issues sections.
13727       Rename GetClassName back to GetClassSignature and
13728       fix description.
13729       Add generic signature to GetClassSignature, 
13730       GetFieldSignature, GetMethodSignature, and 
13731       GetLocalVariableTable.
13732       Elide EstimateCostOfCapabilities.
13733       Clarify that the system property functions operate
13734       on the VM view of system properties.
13735       Clarify Agent_OnLoad.
13736       Remove "const" from JNIEnv* in events.
13737       Add metadata accessors.
13738   </change>
13739   <change date="18 June 2003" version="v70">
13740       Add start_depth to GetStackTrace.
13741       Move system properties to a new category.
13742       Add GetObjectSize.
13743       Remove "X" from command line flags.
13744       XML, HTML, and spell check corrections.
13745   </change>
13746   <change date="19 June 2003" version="v71">
13747       Fix JVMTI_HEAP_ROOT_THREAD to be 6.
13748       Make each synopsis match the function name.
13749       Fix unclear wording.
13750   </change>
13751   <change date="26 June 2003" version="v72">
13752       SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
13753       to be set to NULL.
13754       NotifyFramePop, GetFrameLocationm and all the local variable operations
13755       needed to have their wording about frames fixed.
13756       Grammar and clarity need to be fixed throughout.
13757       Capitalization and puntuation need to be consistent.
13758       Need micro version number and masks for accessing major, minor, and micro.
13759       The error code lists should indicate which must be returned by
13760       an implementation.
13761       The command line properties should be visible in the properties functions.
13762       Disallow popping from the current thread.
13763       Allow implementations to return opaque frame error when they cannot pop.
13764       The NativeMethodBind event should be sent during any phase.
13765       The DynamicCodeGenerated event should be sent during any phase.
13766       The following functions should be allowed to operate before VMInit:
13767         Set/GetEnvironmentLocalStorage
13768         GetMethodDeclaringClass
13769         GetClassSignature
13770         GetClassModifiers
13771         IsInterface
13772         IsArrayClass
13773         GetMethodName
13774         GetMethodModifiers
13775         GetMaxLocals
13776         GetArgumentsSize
13777         GetLineNumberTable
13778         GetMethodLocation
13779         IsMethodNative
13780         IsMethodSynthetic.
13781       Other changes (to XSL):
13782       Argument description should show asterisk after not before pointers.
13783       NotifyFramePop, GetFrameLocationm and all the local variable operations
13784       should hsve the NO_MORE_FRAMES error added.
13785       Not alive threads should have a different error return than invalid thread.
13786   </change>
13787   <change date="7 July 2003" version="v73">
13788       VerboseOutput event was missing message parameter.
13789       Minor fix-ups.
13790   </change>
13791   <change date="14 July 2003" version="v74">
13792       Technical Publications Department corrections.
13793       Allow thread and environment local storage to be set to NULL.
13794   </change>
13795   <change date="23 July 2003" version="v75">
13796       Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
13797       Add JNICALL to callbacks (XSL).
13798       Document JNICALL requirement for both events and callbacks (XSL).
13799       Restrict RedefineClasses to methods and attributes.
13800       Elide the VerboseOutput event.
13801       VMObjectAlloc: restrict when event is sent and remove method parameter.
13802       Finish loose ends from Tech Pubs edit.
13803   </change>
13804   <change date="24 July 2003" version="v76">
13805       Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
13806   </change>
13807   <change date="24 July 2003" version="v77">
13808       XML fixes.
13809       Minor text clarifications and corrections.
13810   </change>
13811   <change date="24 July 2003" version="v78">
13812       Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
13813       Clarify that stack frames are JVM Spec frames.
13814       Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
13815       and can_get_source_debug_extension.
13816       PopFrame cannot have a native calling method.
13817       Removed incorrect statement in GetClassloaderClasses 
13818       (see <vmspec chapter="4.4"/>).
13819   </change>
13820   <change date="24 July 2003" version="v79">
13821       XML and text fixes.
13822       Move stack frame description into Stack Frame category.
13823   </change>
13824   <change date="26 July 2003" version="v80">
13825       Allow NULL (means bootstrap loader) for GetClassloaderClasses.
13826       Add new heap reference kinds for references from classes.
13827       Add timer information struct and query functions.
13828       Add AvailableProcessors.
13829       Rename GetOtherThreadCpuTime to GetThreadCpuTime.
13830       Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
13831       to SetEventNotification mode.
13832       Add initial thread to the VM_INIT event.
13833       Remove platform assumptions from AddToBootstrapClassLoaderSearch.
13834   </change>
13835   <change date="26 July 2003" version="v81">
13836       Grammar and clarity changes per review.
13837   </change>
13838   <change date="27 July 2003" version="v82">
13839       More grammar and clarity changes per review.
13840       Add Agent_OnUnload.
13841   </change>
13842   <change date="28 July 2003" version="v83">
13843       Change return type of Agent_OnUnload to void.
13844   </change>
13845   <change date="28 July 2003" version="v84">
13846       Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
13847   </change>
13848   <change date="28 July 2003" version="v85">
13849       Steal java.lang.Runtime.availableProcessors() wording for 
13850       AvailableProcessors().
13851       Guarantee that zero will never be an event ID.
13852       Remove some issues which are no longer issues.
13853       Per review, rename and more completely document the timer
13854       information functions.
13855   </change>
13856   <change date="29 July 2003" version="v86">
13857       Non-spec visible change to XML controlled implementation:
13858         SetThreadLocalStorage must run in VM mode.
13859   </change>
13860   <change date="5 August 2003" version="0.1.87">
13861       Add GetErrorName.
13862       Add varargs warning to jvmtiExtensionEvent.
13863       Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
13864       Remove unused can_get_exception_info capability.
13865       Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
13866       Fix jvmtiExtensionFunctionInfo.func declared type.
13867       Extension function returns error code.
13868       Use new version numbering.
13869   </change>
13870   <change date="5 August 2003" version="0.2.88">
13871       Remove the ClassUnload event.
13872   </change>
13873   <change date="8 August 2003" version="0.2.89">
13874       Heap reference iterator callbacks return an enum that 
13875       allows outgoing object references to be ignored.
13876       Allow JNIEnv as a param type to extension events/functions.
13877   </change>
13878   <change date="15 August 2003" version="0.2.90">
13879       Fix a typo.
13880   </change>
13881   <change date="2 September 2003" version="0.2.91">
13882       Remove all metadata functions: GetClassMetadata, 
13883       GetFieldMetadata, and GetMethodMetadata.
13884   </change>
13885   <change date="1 October 2003" version="0.2.92">
13886       Mark the functions Allocate. Deallocate, RawMonitor*, 
13887       SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage 
13888       as safe for use in heap callbacks and GC events.
13889   </change>
13890   <change date="24 November 2003" version="0.2.93">
13891       Add pass through opaque user data pointer to heap iterate 
13892       functions and callbacks.
13893       In the CompiledMethodUnload event, send the code address.
13894       Add GarbageCollectionOccurred event.
13895       Add constant pool reference kind.
13896       Mark the functions CreateRawMonitor and DestroyRawMonitor
13897       as safe for use in heap callbacks and GC events.
13898       Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, 
13899       GetThreadCpuTimerInfo, IterateOverReachableObjects,
13900       IterateOverObjectsReachableFromObject, GetTime and
13901       JVMTI_ERROR_NULL_POINTER.
13902       Add missing errors to: GenerateEvents and
13903       AddToBootstrapClassLoaderSearch.
13904       Fix description of ClassFileLoadHook name parameter.
13905       In heap callbacks and GC/ObjectFree events, specify
13906       that only explicitly allowed functions can be called.
13907       Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
13908       GetTimerInfo, and GetTime during callback.
13909       Allow calling SetTag/GetTag during the onload phase.
13910       SetEventNotificationMode, add: error attempted inappropriate
13911       thread level control.
13912       Remove jvmtiExceptionHandlerEntry.
13913       Fix handling of native methods on the stack -- 
13914       location_ptr param of GetFrameLocation, remove 
13915       JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
13916       jvmtiFrameInfo.location, and jlocation.
13917       Remove typo (from JVMPI) implying that the MonitorWaited
13918       event is sent on sleep.
13919   </change>
13920   <change date="25 November 2003" version="0.2.94">
13921       Clarifications and typos.
13922   </change>
13923   <change date="3 December 2003" version="0.2.95">
13924       Allow NULL user_data in heap iterators.
13925   </change>
13926   <change date="28 January 2004" version="0.2.97">
13927       Add GetThreadState, deprecate GetThreadStatus.
13928   </change>
13929   <change date="29 January 2004" version="0.2.98">
13930       INVALID_SLOT and TYPE_MISMATCH errors should be optional.
13931   </change>
13932   <change date="12 February 2004" version="0.2.102">
13933       Remove MonitorContendedExit.
13934       Added JNIEnv parameter to VMObjectAlloc.
13935       Clarified definition of class_tag and referrer_index 
13936       parameters to heap callbacks.
13937   </change>
13938   <change date="16 Febuary 2004" version="0.2.103">
13939       Document JAVA_TOOL_OPTIONS.
13940   </change>
13941   <change date="17 Febuary 2004" version="0.2.105">
13942       Divide start phase into primordial and start.
13943       Add VMStart event
13944       Change phase associations of functions and events.
13945   </change>
13946   <change date="18 Febuary 2004" version="0.3.6">
13947       Elide deprecated GetThreadStatus.
13948       Bump minor version, subtract 100 from micro version
13949   </change>
13950   <change date="18 Febuary 2004" version="0.3.7">
13951       Document that timer nanosecond values are unsigned.
13952       Clarify text having to do with native methods.
13953   </change>
13954   <change date="19 Febuary 2004" version="0.3.8">
13955       Fix typos.
13956       Remove elided deprecated GetThreadStatus.
13957   </change>
13958   <change date="23 Febuary 2004" version="0.3.9">
13959       Require NotifyFramePop to act on suspended threads.
13960   </change>
13961   <change date="24 Febuary 2004" version="0.3.10">
13962       Add capabilities 
13963         (<internallink id="jvmtiCapabilities.can_redefine_any_class"
13964          ><code>can_redefine_any_class</code></internallink>
13965       and 
13966          <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
13967          ><code>can_generate_all_class_hook_events</code></internallink>) 
13968       and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) 
13969       which allow some classes to be unmodifiable.
13970   </change>
13971   <change date="28 Febuary 2004" version="0.3.11">
13972       Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
13973   </change>
13974   <change date="8 March 2004" version="0.3.12">
13975       Clarified CompiledMethodUnload so that it is clear the event
13976       may be posted after the class has been unloaded.
13977   </change>
13978   <change date="5 March 2004" version="0.3.13">
13979       Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
13980   </change>
13981   <change date="13 March 2004" version="0.3.14">
13982       Added guideline for the use of the JNI FindClass function in event
13983       callback functions.
13984   </change>
13985   <change date="15 March 2004" version="0.3.15">
13986       Add GetAllStackTraces and GetThreadListStackTraces.
13987   </change>
13988   <change date="19 March 2004" version="0.3.16">
13989       ClassLoad and ClassPrepare events can be posted during start phase.
13990   </change>
13991   <change date="25 March 2004" version="0.3.17">
13992       Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
13993       GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
13994   </change>
13995   <change date="29 March 2004" version="0.3.18">
13996       Return the timer kind in the timer information structure.
13997   </change>
13998   <change date="31 March 2004" version="0.3.19">
13999       Spec clarifications:
14000       JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
14001       ForceGarbageCollection does not run finalizers.
14002       The context of the specification is the Java platform.
14003       Warn about early instrumentation.
14004   </change>
14005   <change date="1 April 2004" version="0.3.20">
14006       Refinements to the above clarifications and
14007       Clarify that an error returned by Agent_OnLoad terminates the VM.
14008   </change>
14009   <change date="1 April 2004" version="0.3.21">
14010       Array class creation does not generate a class load event.
14011   </change>
14012   <change date="7 April 2004" version="0.3.22">
14013       Align thread state hierarchy more closely with java.lang.Thread.State.
14014   </change>
14015   <change date="12 April 2004" version="0.3.23">
14016       Clarify the documentation of thread state.
14017   </change>
14018   <change date="19 April 2004" version="0.3.24">
14019       Remove GarbageCollectionOccurred event -- can be done by agent.
14020   </change>
14021   <change date="22 April 2004" version="0.3.25">
14022       Define "command-line option".
14023   </change>
14024   <change date="29 April 2004" version="0.3.26">
14025       Describe the intended use of bytecode instrumentation.
14026       Fix description of extension event first parameter.
14027   </change>
14028   <change date="30 April 2004" version="0.3.27">
14029       Clarification and typos.
14030   </change>
14031   <change date="18 May 2004" version="0.3.28">
14032       Remove DataDumpRequest event.
14033   </change>
14034   <change date="18 May 2004" version="0.3.29">
14035       Clarify RawMonitorWait with zero timeout.
14036       Clarify thread state after RunAgentThread.
14037   </change>
14038   <change date="24 May 2004" version="0.3.30">
14039       Clean-up: fix bad/old links, etc.
14040   </change>
14041   <change date="30 May 2004" version="0.3.31">
14042       Clarifications including:
14043       All character strings are modified UTF-8.
14044       Agent thread visibiity.
14045       Meaning of obsolete method version.
14046       Thread invoking heap callbacks,
14047   </change>
14048   <change date="1 June 2004" version="1.0.32">
14049       Bump major.minor version numbers to "1.0".
14050   </change>
14051   <change date="2 June 2004" version="1.0.33">
14052       Clarify interaction between ForceGarbageCollection 
14053       and ObjectFree.
14054   </change>
14055   <change date="6 June 2004" version="1.0.34">
14056       Restrict AddToBootstrapClassLoaderSearch and 
14057       SetSystemProperty to the OnLoad phase only.
14058   </change>
14059   <change date="11 June 2004" version="1.0.35">
14060       Fix typo in SetTag.
14061   </change>
14062   <change date="18 June 2004" version="1.0.36">
14063       Fix trademarks.
14064       Add missing parameter in example GetThreadState usage.
14065   </change>
14066   <change date="4 August 2004" version="1.0.37">
14067       Copyright updates.
14068   </change>
14069   <change date="5 November 2004" version="1.0.38">
14070       Add missing function table layout.
14071       Add missing description of C++ member function format of functions.
14072       Clarify that name in CFLH can be NULL.
14073       Released as part of <tm>J2SE</tm> 5.0.
14074   </change>
14075   <change date="24 April 2005" version="1.1.47">
14076       Bump major.minor version numbers to "1.1".
14077       Add ForceEarlyReturn* functions.
14078       Add GetOwnedMonitorStackDepthInfo function.
14079       Add GetCurrentThread function.
14080       Add "since" version marker.
14081       Add AddToSystemClassLoaderSearch.
14082       Allow AddToBootstrapClassLoaderSearch be used in live phase.
14083       Fix historic rubbish in the descriptions of the heap_object_callback 
14084       parameter of IterateOverHeap and IterateOverInstancesOfClass functions; 
14085       disallow NULL for this parameter.
14086       Clarify, correct and make consistent: wording about current thread,
14087       opaque frames and insufficient number of frames in PopFrame.
14088       Consistently use "current frame" rather than "topmost".
14089       Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
14090       by making them compatible with those in ForceEarlyReturn*.
14091       Many other clarifications and wording clean ups.
14092   </change>
14093   <change date="25 April 2005" version="1.1.48">
14094       Add GetConstantPool.
14095       Switch references to the first edition of the VM Spec, to the seconds edition.
14096   </change>
14097   <change date="26 April 2005" version="1.1.49">
14098       Clarify minor/major version order in GetConstantPool.
14099   </change>
14100   <change date="26 April 2005" version="1.1.50">
14101       Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
14102       Reassign GetOwnedMonitorStackDepthInfo to position 153.
14103       Break out Class Loader Search in its own documentation category.
14104       Deal with overly long lines in XML source.
14105   </change>
14106   <change date="29 April 2005" version="1.1.51">
14107       Allow agents be started in the live phase.
14108       Added paragraph about deploying agents.  
14109   </change>
14110   <change date="30 April 2005" version="1.1.52">
14111       Add specification description to SetNativeMethodPrefix(es).
14112       Better define the conditions on GetConstantPool.  
14113   </change>
14114   <change date="30 April 2005" version="1.1.53">
14115       Break out the GetClassVersionNumber function from GetConstantPool.
14116       Clean-up the references to the VM Spec.  
14117   </change>
14118   <change date="1 May 2005" version="1.1.54">
14119       Allow SetNativeMethodPrefix(es) in any phase.
14120       Add clarifications about the impact of redefinition on GetConstantPool.  
14121   </change>
14122   <change date="2 May 2005" version="1.1.56">
14123       Various clarifications to SetNativeMethodPrefix(es).
14124   </change>
14125   <change date="2 May 2005" version="1.1.57">
14126       Add missing performance warning to the method entry event.
14127   </change>
14128   <change date="5 May 2005" version="1.1.58">
14129       Remove internal JVMDI support.
14130   </change>
14131   <change date="8 May 2005" version="1.1.59">
14132       Add <functionlink id="RetransformClasses"/>.
14133       Revamp the bytecode instrumentation documentation.
14134       Change <functionlink id="IsMethodObsolete"/> to no longer 
14135       require the can_redefine_classes capability.
14136   </change>
14137   <change date="11 May 2005" version="1.1.63">
14138       Clarifications for retransformation.
14139   </change>
14140   <change date="11 May 2005" version="1.1.64">
14141       Clarifications for retransformation, per review.
14142       Lock "retransformation (in)capable" at class load enable time.
14143   </change>
14144   <change date="4 June 2005" version="1.1.67">
14145       Add new heap functionity which supports reporting primitive values,
14146       allows setting the referrer tag, and has more powerful filtering:
14147       FollowReferences, IterateThroughHeap, and their associated 
14148       callbacks, structs, enums, and constants.
14149   </change>
14150   <change date="4 June 2005" version="1.1.68">
14151       Clarification.
14152   </change>
14153   <change date="6 June 2005" version="1.1.69">
14154       FollowReferences, IterateThroughHeap: Put callbacks in a struct;
14155       Add missing error codes; reduce bits in the visit control flags.
14156   </change>
14157   <change date="14 June 2005" version="1.1.70">
14158       More on new heap functionity: spec clean-up per review.
14159   </change>
14160   <change date="15 June 2005" version="1.1.71">
14161       More on new heap functionity: Rename old heap section to Heap (1.0).
14162   </change>
14163   <change date="21 June 2005" version="1.1.72">
14164       Fix typos.
14165   </change>
14166   <change date="27 June 2005" version="1.1.73">
14167       Make referrer info structure a union.
14168   </change>
14169   <change date="9 September 2005" version="1.1.74">
14170       In new heap functions:
14171       Add missing superclass reference kind.
14172       Use a single scheme for computing field indexes.
14173       Remove outdated references to struct based referrer info.
14174   </change>
14175   <change date="12 September 2005" version="1.1.75">
14176       Don't callback during FollowReferences on frivolous java.lang.Object superclass.
14177   </change>
14178   <change date="13 September 2005" version="1.1.76">
14179       In string primitive callback, length now Unicode length.
14180       In array and string primitive callbacks, value now "const".
14181       Note possible compiler impacts on setting JNI function table.
14182   </change>
14183   <change date="13 September 2005" version="1.1.77">
14184       GetClassVersionNumbers() and GetConstantPool() should return
14185       error on array or primitive class.
14186   </change>
14187   <change date="14 September 2005" version="1.1.78">
14188       Grammar fixes.
14189   </change>
14190   <change date="26 September 2005" version="1.1.79">
14191       Add IsModifiableClass query.
14192   </change>
14193   <change date="9 February 2006" version="1.1.81">
14194       Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
14195   </change>
14196   <change date="13 February 2006" version="1.1.82">
14197       Doc fixes: update can_redefine_any_class to include retransform.
14198       Clarify that exception events cover all Throwables.
14199       In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
14200       Clarify fields reported in Primitive Field Callback -- static vs instance.
14201       Repair confusing names of heap types, including callback names.
14202       Require consistent usage of stack depth in the face of thread launch methods.
14203       Note incompatibility of <jvmti/> memory management with other systems.
14204   </change>
14205   <change date="14 February 2006" version="1.1.85">
14206       Fix typos and missing renames.
14207   </change>
14208   <change date="13 March 2006" version="1.1.86">
14209       Clarify that jmethodIDs and jfieldIDs can be saved.
14210       Clarify that Iterate Over Instances Of Class includes subclasses.
14211   </change>
14212   <change date="14 March 2006" version="1.1.87">
14213       Better phrasing.
14214   </change>
14215   <change date="16 March 2006" version="1.1.88">
14216       Match the referrer_index for static fields in Object Reference Callback 
14217       with the Reference Implementation (and all other known implementations);
14218       that is, make it match the definition for instance fields.
14219       In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover 
14220       an invalid thread in the list; and specify that not started threads
14221       return empty stacks.
14222   </change>
14223   <change date="17 March 2006" version="1.1.89">
14224       Typo.
14225   </change>
14226   <change date="25 March 2006" version="1.1.90">
14227       Typo.
14228   </change>
14229   <change date="6 April 2006" version="1.1.91">
14230       Remove restrictions on AddToBootstrapClassLoaderSearch and
14231       AddToSystemClassLoaderSearch.
14232   </change>
14233   <change date="1 May 2006" version="1.1.93">
14234       Changed spec to return -1 for monitor stack depth for the
14235       implementation which can not determine stack depth. 
14236   </change>
14237   <change date="3 May 2006" version="1.1.94">
14238       Corrections for readability and accuracy courtesy of Alan Pratt of IBM. 
14239       List the object relationships reported in FollowReferences.
14240   </change>
14241   <change date="5 May 2006" version="1.1.95">
14242       Clarify the object relationships reported in FollowReferences.
14243   </change>
14244   <change date="28 June 2006" version="1.1.98">
14245       Clarify DisposeEnvironment; add warning.
14246       Fix typos in SetLocalXXX "retrieve" => "set".
14247       Clarify that native method prefixes must remain set while used.
14248       Clarify that exactly one Agent_OnXXX is called per agent.
14249       Clarify that library loading is independent from start-up.
14250       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14251   </change>
14252   <change date="31 July 2006" version="1.1.99">
14253       Clarify the interaction between functions and exceptions.
14254       Clarify and give examples of field indices.
14255       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14256       Update links to point to Java 6.
14257   </change>
14258   <change date="6 August 2006" version="1.1.102">
14259       Add ResourceExhaustedEvent.
14260   </change>
14261   <change date="11 October 2012" version="1.2.2">
14262       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14263   </change>
14264 </changehistory>
14265 
14266 </specification>
14267 <!-- Keep this comment at the end of the file
14268 Local variables:
14269 mode: sgml
14270 sgml-omittag:t
14271 sgml-shorttag:t
14272 sgml-namecase-general:t
14273 sgml-general-insert-case:lower
14274 sgml-minimize-attributes:nil
14275 sgml-always-quote-attributes:t
14276 sgml-indent-step:2
14277 sgml-indent-data:t
14278 sgml-parent-document:nil
14279 sgml-exposed-tags:nil
14280 sgml-local-catalogs:nil
14281 sgml-local-ecat-files:nil
14282 End:
14283 -->