1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
   3 <!--
   4  Copyright (c) 2002, 2017, 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 <!DOCTYPE specification [
  27    <!ELEMENT specification (title, intro*, functionsection, errorsection, 
  28                             eventsection, datasection, issuessection, changehistory)>
  29    <!ATTLIST specification label CDATA #REQUIRED 
  30                            majorversion CDATA #REQUIRED 
  31                            minorversion CDATA #REQUIRED 
  32                            microversion CDATA #REQUIRED>
  33 
  34    <!ELEMENT title (#PCDATA|jvmti|tm)*>
  35    <!ATTLIST title subtitle CDATA #REQUIRED>
  36 
  37    <!ELEMENT intro ANY>
  38    <!ATTLIST intro id CDATA #IMPLIED
  39                    label CDATA "">
  40 
  41    <!ELEMENT functionsection (intro*, category*)>
  42    <!ATTLIST functionsection label CDATA #REQUIRED>
  43 
  44    <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*, 
  45                           (function|callback|elide)*)>
  46    <!ATTLIST category id CDATA #REQUIRED
  47                       label CDATA #REQUIRED>
  48 
  49    <!ELEMENT function (synopsis, typedef*, description?, origin,
  50                          (capabilities|eventcapabilities), 
  51                          parameters, errors)>
  52    <!ATTLIST function id CDATA #REQUIRED
  53                       num CDATA #REQUIRED
  54                       phase (onload|onloadOnly|start|live|any) #IMPLIED
  55                       callbacksafe (safe|unsafe) #IMPLIED
  56                       impl CDATA #IMPLIED
  57                       hide CDATA #IMPLIED
  58                       jkernel (yes|no) #IMPLIED
  59                       since CDATA "1.0">
  60 
  61    <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  62                         jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
  63                         synopsis, description?, parameters)>
  64    <!ATTLIST callback id CDATA #REQUIRED
  65                       since CDATA "1.0">
  66 
  67    <!ELEMENT synopsis (#PCDATA|jvmti)*>
  68 
  69    <!ELEMENT typedef (description?, field*)>
  70    <!ATTLIST typedef id CDATA #REQUIRED
  71                      label CDATA #REQUIRED
  72                      since CDATA "1.0">
  73 
  74    <!ELEMENT uniontypedef (description?, field*)>
  75    <!ATTLIST uniontypedef id CDATA #REQUIRED
  76                      label CDATA #REQUIRED
  77                      since CDATA "1.0">
  78 
  79    <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  80                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct), 
  81                     description)>
  82    <!ATTLIST field id CDATA #REQUIRED>
  83 
  84    <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
  85    <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
  86                      label CDATA #REQUIRED>
  87 
  88    <!ELEMENT capabilityfield (description)>
  89    <!ATTLIST capabilityfield id CDATA #REQUIRED
  90                    disp1 CDATA ""
  91                    disp2 CDATA ""
  92                    since CDATA "1.0">
  93 
  94    <!ELEMENT description ANY>
  95 
  96    <!ELEMENT capabilities (required*, capability*)>
  97 
  98    <!ELEMENT eventcapabilities EMPTY>
  99 
 100    <!ELEMENT required ANY>
 101    <!ATTLIST required id CDATA #REQUIRED>
 102 
 103    <!ELEMENT capability ANY>
 104    <!ATTLIST capability id CDATA #REQUIRED>
 105 
 106    <!ELEMENT parameters (param*)>
 107 
 108    <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
 109                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
 110                      outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf), 
 111                     description)>
 112    <!ATTLIST param id CDATA #REQUIRED>
 113 
 114    <!ELEMENT jmethodID EMPTY>
 115    <!ATTLIST jmethodID class  CDATA #IMPLIED
 116                        native CDATA #IMPLIED>
 117 
 118    <!ELEMENT jfieldID EMPTY>
 119    <!ATTLIST jfieldID class CDATA #IMPLIED>
 120 
 121    <!ELEMENT jclass EMPTY>
 122    <!ATTLIST jclass method CDATA #IMPLIED
 123                     field  CDATA #IMPLIED>
 124 
 125    <!ELEMENT jframeID EMPTY>
 126    <!ATTLIST jframeID thread CDATA #IMPLIED>
 127 
 128    <!ELEMENT jrawMonitorID EMPTY>
 129 
 130    <!ELEMENT jthread EMPTY>
 131    <!ATTLIST jthread started CDATA #IMPLIED
 132                      null CDATA #IMPLIED
 133                      frame CDATA #IMPLIED
 134                      impl CDATA #IMPLIED>
 135 
 136    <!ELEMENT varargs EMPTY>
 137 
 138    <!ELEMENT jthreadGroup EMPTY>
 139    <!ELEMENT jobject EMPTY>
 140    <!ELEMENT jvalue EMPTY>
 141    <!ELEMENT jchar EMPTY>
 142    <!ELEMENT jint EMPTY>
 143    <!ATTLIST jint min CDATA #IMPLIED>
 144    <!ELEMENT jlong EMPTY>
 145    <!ELEMENT jfloat EMPTY>
 146    <!ELEMENT jdouble EMPTY>
 147    <!ELEMENT jlocation EMPTY>
 148    <!ELEMENT jboolean EMPTY>
 149    <!ELEMENT char EMPTY>
 150    <!ELEMENT uchar EMPTY>
 151    <!ELEMENT size_t EMPTY>
 152    <!ELEMENT void EMPTY>
 153    <!ELEMENT enum (#PCDATA)*>
 154    <!ELEMENT struct (#PCDATA)*>
 155 
 156    <!ELEMENT nullok ANY>
 157 
 158    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 159                                    jthreadGroup|jobject|jvalue), nullok?)>
 160 
 161    <!ELEMENT outptr     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 162                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 163                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 164 
 165    <!ELEMENT allocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 166                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 167                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 168    <!ATTLIST allocbuf incount CDATA #IMPLIED
 169                       outcount CDATA #IMPLIED>
 170 
 171    <!ELEMENT allocallocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 172                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 173                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 174    <!ATTLIST allocallocbuf incount CDATA #IMPLIED
 175                       outcount CDATA #IMPLIED>
 176 
 177    <!ELEMENT inptr      (struct, nullok?)>
 178 
 179    <!ELEMENT inbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 180                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 181                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 182    <!ATTLIST inbuf    incount CDATA #IMPLIED>
 183 
 184    <!ELEMENT outbuf     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 185                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 186                                    jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
 187    <!ATTLIST outbuf   incount CDATA #IMPLIED
 188                       outcount CDATA #IMPLIED>
 189 
 190    <!ELEMENT vmbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 191                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 192                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 193    <!ATTLIST vmbuf    incount CDATA #IMPLIED
 194                       outcount CDATA #IMPLIED>
 195 
 196    <!ELEMENT agentbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 197                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 198                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 199    <!ATTLIST agentbuf incount CDATA #IMPLIED
 200                       outcount CDATA #IMPLIED>
 201 
 202    <!ELEMENT allocfieldbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 203                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 204                                    jlocation|jboolean|char|uchar|size_t|void))>
 205    <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
 206 
 207    <!ELEMENT errors (error*)>
 208 
 209    <!ELEMENT error ANY>
 210    <!ATTLIST error id CDATA #REQUIRED>
 211 
 212    <!ELEMENT errorsection (intro*, errorcategory*)>
 213    <!ATTLIST errorsection label CDATA #REQUIRED>
 214 
 215    <!ELEMENT errorcategory (intro*, errorid*)>
 216    <!ATTLIST errorcategory id CDATA #REQUIRED
 217                            label CDATA #REQUIRED>
 218 
 219    <!ELEMENT errorid ANY>
 220    <!ATTLIST errorid id CDATA #REQUIRED
 221                      num CDATA #REQUIRED>
 222 
 223    <!ELEMENT datasection (intro*, basetypes*)>
 224 
 225    <!ELEMENT basetypes (intro*, basetype*)>
 226    <!ATTLIST basetypes id CDATA #REQUIRED
 227                        label CDATA #REQUIRED>
 228 
 229    <!ELEMENT basetype (definition?,description)>
 230    <!ATTLIST basetype id CDATA #REQUIRED>
 231 
 232    <!ELEMENT definition (#PCDATA|jvmti)*>
 233 
 234    <!ELEMENT eventsection (intro*, (event|elide)*)>
 235    <!ATTLIST eventsection label CDATA #REQUIRED>
 236 
 237    <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
 238    <!ATTLIST event id CDATA #REQUIRED
 239                    label CDATA #REQUIRED
 240                    const CDATA #REQUIRED
 241                    num CDATA #REQUIRED
 242                    phase (onload|start|live|any) #IMPLIED
 243                    filtered (thread|global) #IMPLIED
 244                    since CDATA "1.0">
 245 
 246    <!ELEMENT issuessection (intro*)>
 247    <!ATTLIST issuessection label CDATA #REQUIRED>
 248 
 249    <!ELEMENT changehistory (intro*, change*)>
 250    <!ATTLIST changehistory update CDATA #REQUIRED
 251                            id CDATA #REQUIRED>
 252 
 253    <!ELEMENT change ANY>
 254    <!ATTLIST change date CDATA #REQUIRED
 255                     version CDATA #IMPLIED>
 256 
 257    <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
 258    <!ATTLIST functionlink id CDATA #REQUIRED>
 259 
 260    <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
 261    <!ATTLIST datalink id CDATA #REQUIRED>
 262 
 263    <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
 264    <!ATTLIST typelink id CDATA #REQUIRED>
 265 
 266    <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
 267    <!ATTLIST fieldlink id CDATA #REQUIRED
 268                        struct CDATA #REQUIRED>
 269 
 270    <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
 271    <!ATTLIST paramlink id CDATA #REQUIRED>
 272 
 273    <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
 274    <!ATTLIST eventlink id CDATA #REQUIRED>
 275 
 276    <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
 277    <!ATTLIST errorlink id CDATA #REQUIRED>
 278 
 279    <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
 280    <!ATTLIST externallink id CDATA #REQUIRED>
 281 
 282    <!ELEMENT vmspec EMPTY>
 283    <!ATTLIST vmspec chapter CDATA #IMPLIED>
 284 
 285    <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
 286    <!ATTLIST internallink id CDATA #REQUIRED>
 287 
 288    <!ELEMENT functionphaselist EMPTY>
 289    <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
 290 
 291    <!ELEMENT eventphaselist EMPTY>
 292    <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
 293 
 294    <!ELEMENT issue ANY>
 295    
 296    <!ELEMENT rationale ANY>
 297    
 298    <!ELEMENT todo ANY>
 299    
 300    <!ELEMENT origin (#PCDATA)*>
 301 
 302    <!ELEMENT elide (intro|function|callback|event)*>
 303    <!ATTLIST elide why CDATA #IMPLIED>
 304    
 305    <!ELEMENT constants (constant*)>
 306    <!ATTLIST constants id CDATA #REQUIRED
 307                        label CDATA #REQUIRED
 308                        kind (enum|bits|const) #REQUIRED
 309                        since CDATA "1.0">
 310 
 311    <!ELEMENT constant ANY>
 312    <!ATTLIST constant id CDATA #REQUIRED
 313                       num CDATA #REQUIRED>
 314 
 315    <!ELEMENT tm (#PCDATA)>
 316 
 317    <!ELEMENT i (#PCDATA|jvmti|tm)*>
 318 
 319    <!ELEMENT b (#PCDATA|jvmti|code)*>
 320 
 321    <!ELEMENT code (#PCDATA|space)*>
 322 
 323    <!ELEMENT pre ANY>
 324 
 325    <!ELEMENT space EMPTY>
 326 
 327    <!ELEMENT jvmti EMPTY>
 328 
 329    <!ELEMENT example (#PCDATA|i)*>
 330 
 331    <!ELEMENT br EMPTY>
 332 
 333    <!ELEMENT p EMPTY>
 334 
 335    <!ELEMENT dl  (dt|dd)+>
 336 
 337    <!ELEMENT dd  ANY>
 338 
 339    <!ELEMENT dt  (#PCDATA|jvmti|code|i|b)*>
 340 
 341    <!ELEMENT table  (tr)+>
 342 
 343    <!ELEMENT tr  (td|th)*>
 344 
 345    <!ELEMENT td  ANY>
 346    <!ATTLIST td align (left|right|center) "center">
 347 
 348    <!ELEMENT th  ANY>
 349    <!ATTLIST th align (left|right|center) "center">
 350 
 351    <!ELEMENT ul  (li)+>
 352    <!ATTLIST ul type (disc|circle|square) "disc">
 353 
 354    <!ELEMENT li  ANY>
 355  ]>
 356 
 357 <specification label="JVM(TM) Tool Interface"
 358         majorversion="9"
 359         minorversion="0"
 360         microversion="0">
 361   <title subtitle="Version">
 362     <tm>JVM</tm> Tool Interface
 363   </title>
 364   
 365   <intro id="whatIs" label="What is the JVM Tool Interface?">
 366     The <tm>JVM</tm> Tool Interface (<jvmti/>) 
 367     is a programming interface used by development and monitoring tools. 
 368     It provides both a way to inspect the state and 
 369     to control the execution of applications running in the
 370     <tm>Java</tm> virtual machine (VM).
 371     <p/>
 372     <jvmti/> is intended to provide a VM interface for the full breadth of tools
 373     that need access to VM state, including but not limited to: profiling,
 374     debugging, monitoring, thread analysis, and coverage analysis tools.
 375     <p/>
 376     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
 377     machine.
 378     <p/>
 379     <jvmti/> is a two-way interface. 
 380     A client of <jvmti/>, hereafter called an <i>agent</i>,
 381     can be notified of
 382     interesting occurrences through <internallink id="EventSection">events</internallink>. 
 383     <jvmti/>
 384     can query and control the application through many 
 385     <internallink id="FunctionSection">functions</internallink>, 
 386     either in response to events or 
 387     independent of them.
 388     <p/>
 389     Agents run in the same process with and communicate directly with 
 390     the virtual machine executing
 391     the application being examined.  This communication is
 392     through a native interface (<jvmti/>). The native in-process interface allows
 393     maximal control with minimal intrusion on the part of a tool. 
 394     Typically, agents are relatively compact. They can be controlled
 395     by a separate process which implements the bulk of a tool's
 396     function without interfering with the target application's normal execution.
 397   </intro>
 398 
 399   <intro id="architecture" label="Architecture">
 400     Tools can be written directly to <jvmti/> or indirectly
 401     through higher level interfaces.
 402     The Java Platform Debugger Architecture includes <jvmti/>, but also
 403     contains higher-level, out-of-process debugger interfaces. The higher-level 
 404     interfaces are more appropriate than <jvmti/> for many tools. 
 405     For more information on the Java Platform Debugger Architecture, 
 406     see the 
 407     <externallink id="docs/technotes/guides/jpda/architecture.html">Java 
 408       Platform Debugger Architecture website</externallink>. 
 409   </intro>
 410 
 411   <intro id="writingAgents" label="Writing Agents">
 412     Agents can be written in any native language that supports C
 413     language calling conventions and C or C++
 414     definitions.
 415     <p/>
 416     The function, event, data type, and constant definitions needed for
 417     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 418     To use these definitions add the <tm>J2SE</tm> include directory
 419     to your include path and add
 420     <example>
 421 #include &lt;jvmti.h&gt;
 422     </example>
 423     to your source code.
 424   </intro>
 425 
 426   <intro id="deployingAgents" label="Deploying Agents">
 427     An agent is deployed in a platform specific manner but is typically the 
 428     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating 
 429     system, for example, an agent library is a "Dynamic Linked Library" (DLL). 
 430     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
 431     object (<code>.so</code> file).
 432     <p/>
 433 
 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="entry point" label="Statically Linked Agents (since version 1.2.3)">
 442 
 443       A native JVMTI Agent may be <i>statically linked</i> with the VM.
 444       The manner in which the library and VM image are combined is
 445       implementation-dependent.
 446       An agent L whose image has been combined with the VM is defined as
 447       <i>statically linked</i> if and only if the agent exports a function
 448       called Agent_OnLoad_L.
 449 <p/>
 450       If a <i>statically linked</i> agent L exports a function called
 451       Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
 452       function will be ignored.
 453       If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
 454       function will be invoked with the same arguments and expected return
 455       value as specified for the Agent_OnLoad function.
 456       An agent L that is <i>statically linked</i> will prohibit an agent of
 457       the same name from being loaded dynamically.
 458 <p/>
 459       The VM will invoke the Agent_OnUnload_L function of the agent, if such
 460       a function is exported, at the same point during VM execution as it would
 461       have called the dynamic entry point Agent_OnUnLoad. A statically loaded
 462       agent cannot be unloaded. The Agent_OnUnload_L function will still be
 463       called to do any other agent shutdown related tasks. 
 464       If a <i>statically linked</i> agent L exports a function called
 465       Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
 466       function will be ignored.
 467 <p/>
 468       If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
 469       will be invoked with the same arguments and expected return value as
 470       specified for the Agent_OnAttach function.
 471       If a <i>statically linked</i> agent L exports a function called
 472       Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
 473       function will be ignored.
 474 </intro>
 475   
 476   <intro id="starting" label="Agent Command Line Options">
 477     The term "command-line option" is used below to
 478     mean options supplied in the <code>JavaVMInitArgs</code> argument
 479     to the <code>JNI_CreateJavaVM</code> function of the JNI
 480     Invocation API.
 481     <p/>
 482     One of the two following 
 483     command-line options is used on VM startup to 
 484     properly load and run agents.
 485     These arguments identify the library containing 
 486     the agent as well as an options
 487     string to be passed in at startup. 
 488     <dl>
 489       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 490       <dd>
 491         The name following <code>-agentlib:</code> is the name of the
 492         library to load.  Lookup of the library, both its full name and location,
 493         proceeds in a platform-specific manner.
 494         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
 495         operating system specific file name.
 496         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 497         For example, if the option 
 498         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to 
 499         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
 500         under <tm>Windows</tm> or <code>libfoo.so</code> from the 
 501         <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating
 502         environment.
 503         If the agent library is statically linked into the executable
 504         then no actual loading takes place.
 505     <p/>
 506       </dd>
 507       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 508       <dd>
 509         The path following <code>-agentpath:</code> is the absolute path from which
 510         to load the library.
 511         No library name expansion will occur.
 512         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 513         For example, if the option 
 514         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to 
 515         load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
 516         library is statically linked into the executable
 517         then no actual loading takes place.
 518     <p/>
 519       </dd>
 520     </dl>
 521     For a dynamic shared library agent, the start-up routine
 522     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 523     in the library will be invoked. If the agent library is statically linked
 524     into the executable then the system will attempt to invoke the
 525     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> entry point where
 526     &lt;agent-lib-name&gt; is the basename of the 
 527     agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
 528     the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
 529     <p/>
 530     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
 531     will be searched for JNI native method implementations to facilitate the
 532     use of Java programming language code in tools, as is needed for 
 533     <internallink id="bci">bytecode instrumentation</internallink>.
 534     <p/>
 535     The agent libraries will be searched after all other libraries have been
 536     searched (agents wishing to override or intercept the native method
 537     implementations of non-agent methods can use the
 538     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
 539     <p/>
 540     These switches do the above and nothing more - they do not change the 
 541     state of the VM or <jvmti/>.  No command line options are needed 
 542     to enable <jvmti/> 
 543     or aspects of <jvmti/>, this is handled programmatically
 544     by the use of 
 545     <internallink id="capability">capabilities</internallink>.
 546   </intro>
 547 
 548   <intro id="startup" label="Agent Start-Up">
 549     The VM starts each agent by invoking a start-up function.
 550     If the agent is started in the <code>OnLoad</code>
 551     <functionlink id="GetPhase">phase</functionlink> the function
 552     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 553     or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
 554     for statically linked agents will be invoked.
 555     If the agent is started in the live
 556     <functionlink id="GetPhase">phase</functionlink> the function
 557     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
 558     or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
 559     for statically linked agents will be invoked.
 560     Exactly one call to a start-up function is made per agent.  
 561   </intro>
 562 
 563   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
 564     If an agent is started during the <code>OnLoad</code> phase then its
 565     agent library must export a start-up function with the following prototype:
 566     <example>
 567 JNIEXPORT jint JNICALL 
 568 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
 569     Or for a statically linked agent named 'L':
 570     <example>
 571 JNIEXPORT jint JNICALL 
 572 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
 573 
 574     The VM will start the agent by calling this function.  
 575     It will be called early enough in VM initialization that:
 576     <ul>
 577       <li><functionlink id="SetSystemProperty">system properties</functionlink>
 578         may be set before they have been used in the start-up of the VM</li>
 579       <li>the full set of 
 580         <internallink id="capability">capabilities</internallink>
 581         is still available (note that capabilities that configure the VM
 582         may only be available at this time--see the 
 583         <internallink id="capability">Capability function section</internallink>)</li>
 584       <li>no bytecodes have executed</li>
 585       <li>no classes have been loaded</li>
 586       <li>no objects have been created</li>
 587     </ul>
 588     <p/>
 589     The VM will call the <code>Agent_OnLoad</code> or
 590     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> function with
 591     <i>&lt;options&gt;</i> as the second argument - 
 592     that is, using the command-line option examples,
 593     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> 
 594     argument of <code>Agent_OnLoad</code>.
 595     The <code>options</code> argument is encoded as a
 596     <internallink id="mUTF">modified UTF-8</internallink> string.
 597     If <i>=&lt;options&gt;</i> is not specified, 
 598     a zero length string is passed to <code>options</code>.
 599     The lifespan of the <code>options</code> string is the
 600     <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code>
 601     call.  If needed beyond this time the string or parts of the string must
 602     be copied.
 603     The period between when <code>Agent_OnLoad</code> is called and when it
 604     returns is called the <i>OnLoad phase</i>.
 605     Since the VM is not initialized during the OnLoad 
 606     <functionlink id="GetPhase">phase</functionlink>,
 607     the set of allowed operations 
 608     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
 609     functionality available at this time). 
 610     The agent can safely process the options and set 
 611     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once  
 612     the VM initialization event is received 
 613     (that is, the <eventlink id="VMInit">VMInit</eventlink> 
 614     callback is invoked), the agent
 615     can complete its initialization.
 616     <rationale>
 617       Early startup is required so that agents can set the desired capabilities,
 618       many of which must be set before the VM is initialized.
 619       In JVMDI, the -Xdebug command-line option provided 
 620       very coarse-grain control of capabilities. 
 621       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
 622       No reasonable command-line 
 623       option could provide the fine-grain of control required to balance needed capabilities vs
 624       performance impact.  
 625       Early startup is also needed so that agents can control the execution
 626       environment - modifying the file system and system properties to install
 627       their functionality.
 628     </rationale>
 629     <p/>
 630     The return value from <code>Agent_OnLoad</code> or
 631     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> is used to indicate an error.
 632     Any value other than zero indicates an error and causes termination of the VM.
 633   </intro>
 634   
 635   <intro id="onattach" label="Agent Start-Up (Live phase)">
 636     A VM may support a mechanism that allows agents to be started in the VM during the live 
 637     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
 638     are implementation specific. For example, a tool may use some platform specific mechanism, 
 639     or implementation specific API, to attach to the running VM, and request it start a given
 640     agent.
 641     <p/>
 642     If an agent is started during the live phase then its agent library
 643     must export a start-up function 
 644     with the following prototype:
 645     <example>
 646 JNIEXPORT jint JNICALL 
 647 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
 648 Or for a statically linked agent named 'L':
 649     <example>
 650 JNIEXPORT jint JNICALL 
 651 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
 652 
 653     <p/>         
 654     The VM will start the agent by calling this function.  
 655     It will be called in the context of a thread
 656     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
 657     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
 658     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
 659     </internallink> string.
 660     If startup options were not provided, a zero length string is passed to 
 661     <code>options</code>. The lifespan of the <code>options</code> string is the 
 662     <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> call.
 663     If needed beyond this time the string or parts of the string must be copied.
 664     <p/>
 665     Note that some <internallink id="capability">capabilities</internallink> 
 666     may not be available in the live phase.
 667     <p/>
 668     The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name
 669     &gt;</code> function initializes the agent and returns a value
 670     to the VM to indicate if an error occurred. Any value other than zero indicates an error. 
 671     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes 
 672     some implementation specific action -- for example it might print an error to standard error, 
 673     or record the error in a system log.
 674   </intro>
 675 
 676   <intro id="onunload" label="Agent Shutdown">
 677     The library may optionally export a 
 678     shutdown function with the following prototype:
 679     <example>
 680 JNIEXPORT void JNICALL 
 681 Agent_OnUnload(JavaVM *vm)</example>
 682     Or for a statically linked agent named 'L':
 683     <example>
 684 JNIEXPORT void JNICALL 
 685 Agent_OnUnload_L(JavaVM *vm)</example>
 686 
 687     This function will be called by the VM when the library is about to be unloaded.
 688     The library will be unloaded (unless it is statically linked into the
 689     executable) and this function will be called if some platform specific 
 690     mechanism causes the unload (an unload mechanism is not specified in this document)
 691     or the library is (in effect) unloaded by the termination of the VM whether through 
 692     normal termination or VM failure, including start-up failure.
 693     Uncontrolled shutdown is, of couse, an exception to this rule.
 694     Note the distinction between this function and the 
 695     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
 696     to be sent, the VM must have run at least to the point of initialization and a valid 
 697     <jvmti/> environment must exist which has set a callback for VMDeath
 698     and enabled the event.
 699     None of these are required for <code>Agent_OnUnload</code> or
 700     <code>Agent_OnUnload_&lt;agent-lib-name&gt;</code> and this function
 701     is also called if the library is unloaded for other reasons.
 702     In the case that a VM Death event is sent, it will be sent before this 
 703     function is called (assuming this function is called due to VM termination).
 704     This function can be used to clean-up resources allocated by the agent.
 705   </intro>
 706 
 707   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
 708     Since the command-line cannot always be accessed or modified, for example in embedded VMs
 709     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
 710     provided so that agents may be launched in these cases.
 711     <p/>
 712     Platforms which support environment variables or other named strings, may support the 
 713     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space 
 714     boundaries.  White-space characters include space, tab, carriage-return, new-line, 
 715     vertical-tab, and form-feed.  Sequences of white-space characters are considered 
 716     equivalent to a single white-space character.  No white-space is included in the options 
 717     unless quoted.  Quoting is as follows:
 718     <ul>
 719         <li>All characters enclosed between a pair of single quote marks (''), except a single 
 720         quote, are quoted.</li>
 721         <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
 722         <li>All characters enclosed between a pair of double quote marks (""), except a double 
 723         quote, are quoted.</li>
 724         <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
 725         <li>A quoted part can start or end anywhere in the variable.</li>
 726         <li>White-space characters have no special meaning when quoted -- they are included in
 727         the option like any other character and do not mark white-space boundaries.</li>
 728         <li>The pair of quote marks is not included in the option.</li>
 729     </ul>
 730     <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied 
 731     in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is 
 732     a concern; for example, the Reference Implementation disables this feature on Unix systems when 
 733     the effective user or group ID differs from the real ID.  
 734     This feature is intended to support the initialization of tools -- specifically including the 
 735     launching of native or Java programming language agents.  Multiple tools may wish to use this 
 736     feature, so the variable should not be overwritten, instead,  options should be appended to 
 737     the variable.  Note that since the variable is processed at the time of the JNI Invocation 
 738     API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
 739   </intro>
 740 
 741   <intro id="environments" label="Environments">
 742     The <jvmti/> specification supports the use of multiple simultaneous
 743     <jvmti/> agents.
 744     Each agent has its own <jvmti/> environment.  
 745     That is, the <jvmti/> state is
 746     separate for each agent - changes to one environment do not affect the
 747     others.  The state of a <jvmti/> 
 748     environment includes:
 749     <ul>
 750       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
 751       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
 752       <li><internallink id="capability">the capabilities</internallink></li>
 753       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
 754     </ul>
 755     Although their <jvmti/> state 
 756     is separate, agents inspect and modify the shared state
 757     of the VM, they also share the native environment in which they execute.
 758     As such, an agent can perturb the results of other agents or cause them
 759     to fail.  It is the responsibility of the agent writer to specify the level
 760     of compatibility with other agents.  <jvmti/> implementations are not capable
 761     of preventing destructive interactions between agents. Techniques to reduce
 762     the likelihood of these occurrences are beyond the scope of this document.
 763     <p/>
 764     An agent creates a <jvmti/> environment 
 765     by passing a <jvmti/> version 
 766     as the interface ID to the JNI Invocation API function 
 767     <externallink id="docs/technotes/guides/jni/spec/invocation.html#GetEnv">
 768       <code>GetEnv</code></externallink>.
 769     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
 770     for more details on the creation and use of 
 771     <jvmti/> environments.
 772     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from 
 773     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
 774   </intro>
 775 
 776   <intro id="bci" label="Bytecode Instrumentation">
 777     This interface does not include some events that one might expect in an interface with
 778     profiling support.  Some examples include object allocation events and full speed
 779     method enter and exit events.  The interface instead provides support for 
 780     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
 781     bytecode instructions which comprise the target program.  Typically, these alterations
 782     are to add "events" to the code of a method - for example, to add, at the beginning of a method,
 783     a call to <code>MyProfiler.methodEntered()</code>.  
 784     Since the changes are purely additive, they do not modify application
 785     state or behavior.
 786     Because the inserted agent code is standard bytecodes, the VM can run at full speed,
 787     optimizing not only the target program but also the instrumentation.  If the 
 788     instrumentation does not involve switching from bytecode execution, no expensive
 789     state transitions are needed.  The result is high performance events.
 790     This approach also provides complete control to the agent: instrumentation can be
 791     restricted to "interesting" portions of the code (e.g., the end user's code) and
 792     can be conditional.  Instrumentation can run entirely in Java programming language
 793     code or can call into the native agent.  Instrumentation can simply maintain
 794     counters or can statistically sample events.
 795     <p/>  
 796     Instrumentation can be inserted in one of three ways:
 797     <ul>
 798       <li>
 799         Static Instrumentation: The class file is instrumented before it
 800         is loaded into the VM - for example, by creating a duplicate directory of
 801         <code>*.class</code> files which have been modified to add the instrumentation.
 802         This method is extremely awkward and, in general, an agent cannot know 
 803         the origin of the class files which will be loaded.
 804       </li>
 805       <li>
 806         Load-Time Instrumentation: When a class file is loaded by the VM, the raw
 807         bytes of the class file are sent for instrumentation to the agent.
 808         The <eventlink id="ClassFileLoadHook"/>
 809         event, triggered by the class load,
 810         provides this functionality.  This mechanism provides efficient
 811         and complete access to one-time instrumentation.
 812       </li>
 813       <li>
 814         Dynamic Instrumentation: A class which is already loaded (and possibly
 815         even running) is modified.  This optional feature is provided by the
 816         <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
 817         <functionlink id="RetransformClasses"/> function.
 818         Classes can be modified multiple times and can be returned to their
 819         original state.
 820         The mechanism allows instrumentation which changes during the 
 821         course of execution.
 822       </li>
 823     </ul>
 824     <p/>  
 825     The class modification functionality provided in this interface
 826     is intended to provide a mechanism for instrumentation
 827     (the <eventlink id="ClassFileLoadHook"/> event
 828     and the <functionlink id="RetransformClasses"/> function)
 829     and, during development, for fix-and-continue debugging
 830     (the <functionlink id="RedefineClasses"/> function).
 831     <p/>  
 832     Care must be taken to avoid perturbing dependencies, especially when 
 833     instrumenting core classes.  For example, an approach to getting notification
 834     of every object allocation is to instrument the constructor on 
 835     <code>Object</code>.  Assuming that the constructor is initially
 836     empty, the constructor could be changed to:
 837     <example>
 838       public Object() {
 839         MyProfiler.allocationTracker(this);
 840       }
 841     </example>
 842     However, if this change was made using the 
 843     <eventlink id="ClassFileLoadHook"/>
 844     event then this might impact a typical VM as follows: 
 845     the first created object will call the constructor causing a class load of
 846     <code>MyProfiler</code>; which will then cause
 847     object creation, and since <code>MyProfiler</code> isn't loaded yet,
 848     infinite recursion; resulting in a stack overflow.  A refinement of this
 849     would be to delay invoking the tracking method until a safe time.  For
 850     example, <code>trackAllocations</code> could be set in the 
 851     handler for the <code>VMInit</code> event.
 852     <example>
 853       static boolean trackAllocations = false;
 854 
 855       public Object() {
 856         if (trackAllocations) {
 857           MyProfiler.allocationTracker(this);
 858         }
 859       }
 860     </example>
 861     <p/>
 862     The <functionlink id="SetNativeMethodPrefix"/> allows native methods
 863     to be instrumented by the use of wrapper methods.
 864   </intro>
 865 
 866 <intro id="bcimodules" label="Bytecode Instrumentation of code in modules">
 867   Agents can use the functions <functionlink id="AddModuleReads"/>,
 868   <functionlink id="AddModuleExports"/>, <functionlink id="AddModuleOpens"/>,
 869   <functionlink id="AddModuleUses"/> and <functionlink id="AddModuleProvides"/>
 870   to update a module to expand the set of modules that it reads, the set of
 871   packages that it exports or opens to other modules, or the services that it
 872   uses and provides.
 873   <p/>
 874   As an aid to agents that deploy supporting classes on the search path of
 875   the bootstrap class loader, or the search path of the class loader that
 876   loads the main class, the Java virtual machine arranges for the module
 877   of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
 878   read the unnamed module of both class loaders.
 879 </intro>
 880 
 881   <intro id="mUTF" label="Modified UTF-8 String Encoding">
 882     <jvmti/> uses modified UTF-8 to encode character strings.
 883     This is the same encoding used by JNI.
 884     Modified UTF-8 differs 
 885     from standard UTF-8 in the representation of supplementary characters 
 886     and of the null character. See the
 887     <externallink id="docs/technotes/guides/jni/spec/types.html#modified_utf_8_strings">
 888       Modified UTF-8 Strings</externallink>
 889     section of the JNI specification for details.
 890   </intro>
 891 
 892   <intro id="context" label="Specification Context">
 893     Since this interface provides access to the state of applications running in the
 894     Java virtual machine; 
 895     terminology refers to the Java platform and not the native
 896     platform (unless stated otherwise).  For example:
 897     <ul>
 898       <li>"thread" means Java programming language thread.</li>
 899       <li>"stack frame" means Java virtual machine stack frame.</li>
 900       <li>"class" means Java programming language class.</li>
 901       <li>"heap" means Java virtual machine heap.</li>
 902       <li>"monitor" means Java programming language object monitor.</li>
 903     </ul>
 904     <p/>
 905     Sun, Sun Microsystems, the Sun logo, Java, and JVM
 906     are trademarks or registered trademarks of Oracle 
 907     and/or its affiliates, in the U.S. and other countries.
 908   </intro>
 909 
 910 
 911 <functionsection label="Functions">
 912   <intro id="jvmtiEnvAccess" label="Accessing Functions">
 913     Native code accesses <jvmti/> features 
 914     by calling <jvmti/> functions. 
 915     Access to <jvmti/> functions is by use of an interface pointer
 916     in the same manner as 
 917     <externallink id="docs/technotes/guides/jni/spec/design.html">Java 
 918       Native Interface (JNI) functions</externallink> are accessed.
 919     The <jvmti/> interface pointer is called the 
 920     <i>environment pointer</i>.
 921     <p/>
 922     An environment pointer is a pointer to an environment and has
 923     the type <code>jvmtiEnv*</code>.
 924     An environment has information about its <jvmti/> connection.
 925     The first value in the environment is a pointer to the function table.
 926     The function table is an array of pointers to <jvmti/> functions.
 927     Every function pointer is at a predefined offset inside the 
 928     array. 
 929     <p/>
 930     When used from the C language:
 931     double indirection is used to access the functions;
 932     the environment pointer provides context and is the first
 933     parameter of each function call; for example:
 934     <example>
 935 jvmtiEnv *jvmti;
 936 ...
 937 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);
 938     </example>
 939     <p/>
 940     When used from the C++ language:
 941     functions are accessed as member functions of <code>jvmtiEnv</code>;
 942     the environment pointer is not passed to the function call; for example:
 943     <example>
 944 jvmtiEnv *jvmti;
 945 ...
 946 jvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);
 947     </example>
 948     Unless otherwise stated, all examples and declarations in this 
 949     specification use the C language.
 950     <p/>
 951     A <jvmti/> environment can be obtained through the JNI Invocation API
 952     <code>GetEnv</code> function:
 953     <example>
 954 jvmtiEnv *jvmti;
 955 ...
 956 (*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);
 957     </example>
 958     Each call to <code>GetEnv</code> 
 959     creates a new <jvmti/> connection and thus
 960     a new <jvmti/> environment. 
 961     The <code>version</code> argument of <code>GetEnv</code> must be
 962     a <jvmti/> version.
 963     The returned environment may have a different version than the
 964     requested version but the returned environment must be compatible.
 965     <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a 
 966     compatible version is not available, if <jvmti/> is not supported or
 967     <jvmti/> is not supported in the current VM configuration.
 968     Other interfaces may be added for creating <jvmti/> environments
 969     in specific contexts.
 970     Each environment has its own state (for example,
 971     <functionlink id="SetEventNotificationMode">desired events</functionlink>, 
 972     <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and 
 973     <functionlink id="AddCapabilities">capabilities</functionlink>). 
 974     An environment is released with 
 975     <functionlink id="DisposeEnvironment"></functionlink>. 
 976     Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
 977     across threads and are created dynamically.
 978   </intro>
 979 
 980   <intro id="functionReturn" label="Function Return Values">
 981     <jvmti/> functions always return an
 982     <internallink id="ErrorSection">error code</internallink> via the
 983     <datalink id="jvmtiError"/> function return value. 
 984     Some functions can return additional
 985     values through pointers provided by the calling function. 
 986     In some cases, <jvmti/> functions allocate memory that your program must
 987     explicitly deallocate. This is indicated in the individual <jvmti/>
 988     function descriptions.  Empty lists, arrays, sequences, etc are 
 989     returned as <code>NULL</code>.
 990     <p/>
 991     In the event that the <jvmti/> function encounters
 992     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
 993     of memory referenced by argument pointers is undefined, but no memory
 994     will have been allocated and no global references will have been allocated.
 995     If the error occurs because of invalid input, no action will have occurred.
 996   </intro>
 997 
 998 <intro id="refs" label="Managing JNI Object References">
 999     <jvmti/> functions identify objects with JNI references 
1000     (<datalink id="jobject"/> and <datalink id="jclass"/>)
1001     and their derivatives
1002     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
1003     References passed to 
1004     <jvmti/> functions can be either global or local, but they must be 
1005     strong references. All references returned by <jvmti/> functions are 
1006     local references--these local references are created 
1007     during the <jvmti/> call.
1008     Local references are a resource that must be managed (see the 
1009     <externallink id="docs/technotes/guides/jni/spec/functions.html#local_references">
1010       JNI Documentation</externallink>).  
1011     When threads return from native code all local references
1012     are freed.  Note that some threads, including typical
1013     agent threads, will never return from native code.
1014     A thread is ensured the ability to create sixteen local 
1015     references without the need for any explicit management.
1016     For threads executing a limited number of <jvmti/> calls before
1017     returning from native code
1018     (for example, threads processing events), 
1019     it may be determined that no explicit management
1020     is needed.
1021     However, long running agent threads will need explicit
1022     local reference management--usually with the JNI functions
1023     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
1024     Conversely, to preserve references beyond the
1025     return from native code, they must be converted to global references.
1026     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> 
1027     as they are not <datalink id="jobject"/>s.
1028 </intro>
1029 
1030     <intro id="prereqState" label="Prerequisite State for Calling Functions">
1031       Unless the function explicitly states that the agent must bring
1032       a thread or the VM to a particular state (for example, suspended),
1033       the <jvmti/> implementation is responsible for bringing the VM to a
1034       safe and consistent state for performing the function.
1035     </intro>
1036 
1037     <intro id="functionsExceptions" label="Exceptions and Functions">
1038       <jvmti/> functions never throw exceptions; error conditions are 
1039       communicated via the 
1040       <internallink id="functionReturn">function return value</internallink>.
1041       Any existing exception state is preserved across a call to a 
1042       <jvmti/> function.
1043       See the
1044       <externallink 
1045         id="docs/technotes/guides/jni/spec/design.html#java_exceptions"
1046              >Java Exceptions</externallink>
1047       section of the JNI specification for information on handling exceptions.
1048     </intro>
1049 
1050   <category id="memory" label="Memory Management">
1051     <intro>
1052       These functions provide for the allocation and deallocation of 
1053       memory used by <jvmti/> functionality and can be used to provide
1054       working memory for agents.
1055       Memory managed by <jvmti/> is not compatible with other memory
1056       allocation libraries and mechanisms.
1057     </intro>
1058 
1059     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
1060       <synopsis>Allocate</synopsis>
1061       <description>
1062         Allocate an area of memory through the <jvmti/> allocator. 
1063         The allocated
1064         memory should be freed with <functionlink id="Deallocate"></functionlink>.
1065       </description>
1066       <origin>jvmdi</origin>
1067       <capabilities>
1068       </capabilities>
1069       <parameters>
1070         <param id="size">
1071           <jlong/>
1072           <description>
1073             The number of bytes to allocate.
1074             <rationale>
1075               <code>jlong</code> is used for compatibility with JVMDI.
1076             </rationale>
1077           </description>
1078         </param>
1079         <param id="mem_ptr">
1080           <allocbuf incount="size"><uchar/></allocbuf>
1081           <description>
1082             On return, a pointer to the beginning of the allocated memory.
1083             If <code>size</code> is zero, <code>NULL</code> is returned.
1084           </description>
1085         </param>
1086       </parameters>
1087       <errors>
1088         <error id="JVMTI_ERROR_OUT_OF_MEMORY">
1089           Memory request cannot be honored.
1090         </error>
1091         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
1092           <paramlink id="size"></paramlink> is less than zero.
1093         </error>
1094       </errors>
1095     </function>
1096 
1097     <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
1098       <synopsis>Deallocate</synopsis>
1099       <description>
1100         Deallocate <code>mem</code>  using the <jvmti/> allocator. 
1101         This function should
1102         be used to deallocate any memory allocated and returned 
1103         by a <jvmti/> function
1104         (including memory allocated with <functionlink id="Allocate"></functionlink>).
1105         All allocated memory must be deallocated
1106         or the memory cannot be reclaimed.
1107       </description>
1108       <origin>jvmdi</origin>
1109       <capabilities>
1110       </capabilities>
1111       <parameters>
1112         <param id="mem">
1113           <outbuf>
1114             <uchar/>
1115             <nullok>the call is ignored</nullok>
1116           </outbuf>
1117           <description>
1118             A pointer to the beginning of the allocated memory.
1119             Please ignore "On return, the elements are set."
1120               <todo>keep it from generating "On return, the elements are set"</todo>
1121           </description>
1122         </param>
1123       </parameters>
1124       <errors>
1125       </errors>
1126     </function>
1127   </category>
1128 
1129   <category id="threadCategory" label="Thread">
1130     <intro>
1131     </intro>
1132 
1133     <function id="GetThreadState" num="17">
1134       <synopsis>Get Thread State</synopsis>
1135       <description>
1136         Get the state of a thread.  The state of the thread is represented by the
1137         answers to the hierarchical set of questions below:
1138           <ul type="circle">
1139             <li><i>Alive?</i>
1140               <ul>
1141                 <li>Not alive.
1142                   <ul type="circle">
1143                     <li><i>Why not alive?</i>
1144                       <ul>
1145                         <li>New.</li>
1146                         <li>Terminated (<datalink 
1147                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
1148                       </ul>
1149                     </li>
1150                   </ul>
1151                 </li>
1152                 <li>Alive (<datalink 
1153                     id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
1154                   <ul type="circle">
1155                     <li><i>Suspended?</i>
1156                       <ul>
1157                         <li>Suspended (<datalink 
1158                             id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
1159                         <li>Not suspended</li>
1160                       </ul>
1161                     </li>
1162                     <li><i>Interrupted?</i>
1163                       <ul>
1164                         <li>Interrupted (<datalink 
1165                             id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
1166                         <li>Not interrupted.</li>
1167                       </ul>
1168                     </li>
1169                     <li><i>In native?</i>
1170                       <ul>
1171                         <li>In native code (<datalink 
1172                             id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
1173                         <li>In Java programming language code</li>
1174                       </ul>
1175                     </li>
1176                     <li><i>What alive state?</i>
1177                       <ul>
1178                         <li>Runnable (<datalink 
1179                             id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
1180                         <li>Blocked (<datalink 
1181                             id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
1182                         <li>Waiting (<datalink 
1183                             id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
1184                           <ul type="circle">
1185                             <li><i>Timed wait?</i>
1186                               <ul>
1187                                 <li>Indefinite (<datalink 
1188                                     id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
1189                                 <li>Timed (<datalink 
1190                                     id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
1191                               </ul>
1192                             </li>
1193                             <li><i>Why waiting?</i>
1194                               <ul>
1195                                 <li>Object.wait (<datalink 
1196                                     id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
1197                                 <li>LockSupport.park (<datalink 
1198                                     id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
1199                                 <li>Sleeping (<datalink 
1200                                     id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
1201                               </ul>
1202                             </li>
1203                           </ul>
1204                         </li>
1205                       </ul>
1206                     </li>
1207                   </ul>
1208                 </li>
1209               </ul>
1210             </li>
1211           </ul>
1212         <p/>
1213         The answers are represented by the following bit vector. 
1214         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
1215           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
1216             Thread is alive. Zero if thread is new (not started) or terminated.
1217           </constant>
1218           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
1219             Thread has completed execution.
1220           </constant>
1221           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
1222             Thread is runnable.
1223           </constant>
1224           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
1225             Thread is waiting to enter a synchronization block/method or,
1226             after an <code>Object.wait()</code>, waiting to re-enter a 
1227             synchronization block/method.
1228           </constant>
1229           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
1230             Thread is waiting.
1231           </constant>
1232           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
1233             Thread is waiting without a timeout.
1234             For example, <code>Object.wait()</code>.
1235           </constant>
1236           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
1237             Thread is waiting with a maximum time to wait specified.
1238             For example, <code>Object.wait(long)</code>.
1239           </constant>
1240           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
1241             Thread is sleeping -- <code>Thread.sleep(long)</code>.
1242           </constant>
1243           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
1244             Thread is waiting on an object monitor -- <code>Object.wait</code>.
1245           </constant>
1246           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
1247             Thread is parked, for example: <code>LockSupport.park</code>,
1248             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
1249           </constant>
1250           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
1251             Thread suspended.
1252             <code>java.lang.Thread.suspend()</code>
1253             or a <jvmti/> suspend function 
1254             (such as <functionlink id="SuspendThread"></functionlink>) 
1255             has been called on the thread. If this bit
1256             is set, the other bits refer to the thread state before suspension.
1257           </constant>
1258           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
1259             Thread has been interrupted.
1260           </constant>
1261           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
1262             Thread is in native code--that is, a native method is running
1263             which has not called back into the VM or Java programming
1264             language code.
1265             <p/>
1266             This flag is not set when running VM compiled Java programming
1267             language code nor is it set when running VM code or
1268             VM support code. Native VM interface functions, such as JNI and
1269             <jvmti/> functions, may be implemented as VM code.
1270           </constant>
1271           <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
1272             Defined by VM vendor.
1273           </constant>
1274           <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
1275             Defined by VM vendor.
1276           </constant>
1277           <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
1278             Defined by VM vendor.
1279           </constant>
1280         </constants>
1281         The following definitions are used to convert <jvmti/> thread state
1282         to <code>java.lang.Thread.State</code> style states.
1283         <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
1284           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
1285                      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">
1286             Mask the state with this before comparison
1287           </constant>
1288           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
1289                      num="0">
1290             <code>java.lang.Thread.State.NEW</code>
1291           </constant>
1292           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
1293                      num="JVMTI_THREAD_STATE_TERMINATED">
1294             <code>java.lang.Thread.State.TERMINATED</code>
1295           </constant>
1296           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
1297                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
1298             <code>java.lang.Thread.State.RUNNABLE</code>
1299           </constant>
1300           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
1301                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
1302             <code>java.lang.Thread.State.BLOCKED</code>
1303           </constant>
1304           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
1305                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
1306             <code>java.lang.Thread.State.WAITING</code>
1307           </constant>
1308           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
1309                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1310             <code>java.lang.Thread.State.TIMED_WAITING</code>
1311           </constant>
1312         </constants>
1313         <b>Rules</b>
1314         <p/>
1315         There can be no more than one answer to a question, although there can be no
1316         answer (because the answer is unknown, does not apply, or none of the answers is 
1317         correct).  An answer is set only when the enclosing answers match.
1318         That is, no more than one of
1319           <ul type="circle">
1320               <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
1321               <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
1322               <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
1323           </ul>
1324         can be set (a <tm>J2SE</tm> compliant implementation will always set
1325         one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). 
1326         And if any of these are set, the enclosing answer 
1327         <code>JVMTI_THREAD_STATE_ALIVE</code> is set. 
1328         No more than one of
1329           <ul type="circle">
1330               <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
1331               <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
1332           </ul>
1333         can be set (a <tm>J2SE</tm> compliant implementation will always set
1334         one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). 
1335         And if either is set, the enclosing answers 
1336         <code>JVMTI_THREAD_STATE_ALIVE</code> and 
1337         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 
1338         No more than one of
1339           <ul type="circle">
1340               <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
1341               <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
1342               <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
1343           </ul>
1344         can be set. And if any of these is set, the enclosing answers 
1345         <code>JVMTI_THREAD_STATE_ALIVE</code> and 
1346         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 
1347         Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
1348         then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
1349         If a state <i>A</i> is implemented using the mechanism of 
1350         state <i>B</i> then it is state <i>A</i> which 
1351         is returned by this function.
1352         For example, if <code>Thread.sleep(long)</code>
1353         is implemented using <code>Object.wait(long)</code>
1354         then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
1355         which is returned.
1356         More than one of
1357           <ul type="circle">
1358               <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
1359               <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
1360               <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
1361           </ul>
1362         can be set, but if any is set,
1363         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1364         <p/>
1365         And finally,
1366         <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
1367         <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.  
1368         <p/>
1369         The thread state representation is designed for extension in future versions
1370         of the specification; thread state values should be used accordingly, that is
1371         they should not be used as ordinals.  
1372         Most queries can be made by testing a single bit, if use in a switch statement is desired,
1373         the state bits should be masked with the interesting bits.
1374         All bits not defined above are reserved for future use.  
1375         A VM, compliant to the current specification, must set reserved bits to zero.
1376         An agent should ignore reserved bits -- 
1377         they should not be assumed to be zero and thus should not be included in comparisons.
1378         <p/>
1379         <b>Examples</b>
1380         <p/>
1381         Note that the values below exclude reserved and vendor bits.
1382         <p/>
1383         The state of a thread blocked at a <code>synchronized</code>-statement would be:
1384         <example>
1385             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
1386         </example>
1387         The state of a thread which hasn't started yet would be:
1388         <example>
1389             0
1390         </example>
1391         The state of a thread at a <code>Object.wait(3000)</code> would be:
1392         <example>
1393             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + 
1394                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + 
1395                 JVMTI_THREAD_STATE_MONITOR_WAITING
1396         </example>
1397         The state of a thread suspended while runnable would be:
1398         <example>
1399             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
1400         </example>
1401         <p/>
1402         <b>Testing the State</b>
1403         <p/>
1404         In most cases, the thread state can be determined by testing the one bit corresponding
1405         to that question.  For example, the code to test if a thread is sleeping:
1406         <example>
1407         jint state;
1408         jvmtiError err;
1409 
1410         err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1411         if (err == JVMTI_ERROR_NONE) {
1412            if (state &amp; JVMTI_THREAD_STATE_SLEEPING) {  ...
1413         </example>
1414         <p/>
1415         For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
1416         <example>
1417            if (state &amp; JVMTI_THREAD_STATE_WAITING) {  ...
1418         </example>
1419         For some states, more than one bit will need to be tested as is the case
1420         when testing if a thread has not yet been started:
1421         <example>
1422            if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
1423         </example>
1424         To distinguish timed from untimed <code>Object.wait</code>:
1425         <example>
1426            if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {  
1427              if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
1428                printf("in Object.wait(long timeout)\n");
1429              } else {
1430                printf("in Object.wait()\n");
1431              }
1432            }
1433         </example>
1434         <p/>
1435         <b>Relationship to <code>java.lang.Thread.State</code></b>
1436         <p/>
1437         The thread state represented by <code>java.lang.Thread.State</code>
1438         returned from <code>java.lang.Thread.getState()</code> is a subset of the
1439         information returned from this function.  
1440         The corresponding <code>java.lang.Thread.State</code> can be determined
1441         by using the provided conversion masks.
1442         For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
1443         <example>
1444             err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1445             abortOnError(err);
1446             switch (state &amp; JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
1447             case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
1448               return "NEW";
1449             case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
1450               return "TERMINATED";
1451             case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
1452               return "RUNNABLE";
1453             case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
1454               return "BLOCKED";
1455             case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
1456               return "WAITING";
1457             case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
1458               return "TIMED_WAITING";
1459             }
1460         </example>
1461       </description>
1462       <origin>new</origin>
1463       <capabilities>
1464       </capabilities>
1465       <parameters>
1466         <param id="thread">
1467           <jthread null="current" started="maybe" impl="noconvert"/>
1468             <description>
1469               The thread to query. 
1470             </description>
1471         </param>
1472         <param id="thread_state_ptr">
1473           <outptr><jint/></outptr>
1474           <description>
1475             On return, points to state flags,
1476             as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
1477           </description>
1478         </param>
1479       </parameters>
1480       <errors>
1481       </errors>
1482     </function>
1483 
1484     <function id="GetCurrentThread" phase="start" num="18" since="1.1">
1485       <synopsis>Get Current Thread</synopsis>
1486       <description>
1487         Get the current thread.  
1488         The current thread is the Java programming language thread which has called the function.
1489         The function may return <code>NULL</code> in the start phase if the
1490         <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
1491         <code>can_generate_early_vmstart</code></internallink> capability is enabled
1492         and the <code>java.lang.Thread</code> class has not been initialized yet.
1493         <p/>
1494         Note that most <jvmti/> functions that take a thread 
1495         as an argument will accept <code>NULL</code> to mean 
1496         the current thread.
1497       </description>
1498       <origin>new</origin>
1499       <capabilities>
1500       </capabilities>
1501       <parameters>
1502         <param id="thread_ptr">
1503           <outptr><jthread/></outptr>
1504           <description>
1505              On return, points to the current thread, or <code>NULL</code>.
1506           </description>
1507         </param>
1508       </parameters>
1509       <errors>
1510       </errors>
1511     </function>
1512 
1513     <function id="GetAllThreads" num="4">
1514       <synopsis>Get All Threads</synopsis>
1515       <description>
1516         Get all live threads.
1517         The threads are Java programming language threads;
1518         that is, threads that are attached to the VM.
1519         A thread is live if <code>java.lang.Thread.isAlive()</code> 
1520         would return <code>true</code>, that is, the thread has
1521         been started and has not yet died.
1522         The universe of threads is determined by the context of the <jvmti/>
1523         environment, which typically is all threads attached to the VM.
1524         Note that this includes <jvmti/> agent threads 
1525         (see <functionlink id="RunAgentThread"/>).
1526       </description>
1527       <origin>jvmdi</origin>
1528       <capabilities>
1529       </capabilities>
1530       <parameters>
1531         <param id="threads_count_ptr">
1532           <outptr><jint/></outptr>
1533           <description>
1534             On return, points to the number of running threads.
1535           </description>
1536         </param>
1537         <param id="threads_ptr">
1538           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
1539             <description>
1540               On return, points to an array of references, one
1541               for each running thread.
1542             </description>
1543         </param>
1544       </parameters>
1545       <errors>
1546       </errors>
1547     </function>
1548 
1549     <function id="SuspendThread" num="5">
1550       <synopsis>Suspend Thread</synopsis>
1551       <description>
1552         Suspend the specified thread. If the calling thread is specified, 
1553         this function will not return until some other thread calls 
1554         <functionlink id="ResumeThread"></functionlink>.
1555         If the thread is currently suspended, this function
1556         does nothing and returns an error.
1557       </description>
1558       <origin>jvmdi</origin>
1559       <capabilities>
1560         <required id="can_suspend"></required>
1561       </capabilities>
1562       <parameters>
1563         <param id="thread">
1564           <jthread null="current"/>
1565             <description>
1566               The thread to suspend. 
1567             </description>
1568         </param>
1569       </parameters>
1570       <errors>
1571         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
1572           Thread already suspended.
1573         </error>
1574       </errors>
1575     </function>
1576 
1577     <elide>
1578     <function id="SuspendAllThreads" num="101">
1579       <synopsis>Suspend All Threads</synopsis>
1580       <description>
1581         <issue>
1582             There has been no explicit call for this function, and it will
1583             thus be removed if there is no interest.
1584         </issue>
1585         Suspend all live threads except:
1586         <ul>
1587           <li>already suspended threads</li>
1588           <li>those listed in <paramlink id="except_list"></paramlink></li>
1589           <li>certain system (non application) threads, as determined
1590             by the VM implementation</li>
1591         </ul>
1592         The threads are Java programming language threads;
1593         native threads which are not attached to the VM are not
1594         Java programming language threads.
1595         A thread is live if <code>java.lang.Thread.isAlive()</code> 
1596         would return <code>true</code>, that is, the thread has
1597         been started and has not yet died.
1598         The universe of threads is determined 
1599         by the context of the <jvmti/>
1600         environment, which, typically, is all threads attached to the VM,
1601         except critical VM internal threads and <jvmti/> agent threads 
1602         (see <functionlink id="RunAgentThread"/>).
1603         <p/>
1604         If the calling thread is specified, 
1605         all other threads are suspended first then the caller thread is suspended -
1606         this function will not return until some other thread calls 
1607         <functionlink id="ResumeThread"></functionlink>.
1608         <p/>
1609         The list of actually
1610         suspended threads is returned in 
1611         <paramlink id="suspended_list_ptr"></paramlink>.
1612         Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
1613         <functionlink id="ResumeThreadList"></functionlink>
1614         can be used to resume the suspended threads.
1615       </description>
1616       <origin>new</origin>
1617       <capabilities>
1618         <required id="can_suspend"></required>
1619       </capabilities>
1620       <parameters>
1621         <param id="except_count">
1622           <jint min="0"/>
1623           <description>
1624             The number of threads in the list of threads not to be suspended.
1625           </description>
1626         </param>
1627         <param id="except_list">
1628             <inbuf incount="except_count">
1629               <jthread/>
1630               <nullok>not an error if <code>except_count == 0</code></nullok>
1631             </inbuf>
1632             <description>
1633               The list of threads not to be suspended.
1634             </description>
1635         </param>
1636         <param id="suspended_count_ptr">
1637           <outptr><jint/></outptr>
1638           <description>
1639             On return, points to the number of threads suspended by this call.
1640           </description>
1641         </param>
1642         <param id="suspended_list_ptr">
1643           <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
1644             <description>
1645               On return, points to an array of references, one
1646               for each thread suspended.
1647             </description>
1648         </param>
1649       </parameters>
1650       <errors>
1651         <error id="JVMTI_ERROR_INVALID_THREAD">
1652           A thread in <paramlink id="except_list"></paramlink> was invalid.
1653         </error>
1654         <error id="JVMTI_ERROR_NULL_POINTER">
1655           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1656           and <paramlink id="except_count"></paramlink> was non-zero.
1657         </error>
1658       </errors>
1659     </function>
1660     </elide>
1661 
1662     <function id="SuspendThreadList" num="92">
1663       <synopsis>Suspend Thread List</synopsis>
1664       <description>
1665         Suspend the <paramlink id="request_count"></paramlink> 
1666         threads specified in the 
1667         <paramlink id="request_list"></paramlink> array. 
1668         Threads may be resumed with
1669         <functionlink id="ResumeThreadList"></functionlink> or
1670         <functionlink id="ResumeThread"></functionlink>.
1671         If the calling thread is specified in the 
1672         <paramlink id="request_list"></paramlink> array, this function will
1673         not return until some other thread resumes it.
1674         Errors encountered in the suspension of a thread
1675         are returned in the <paramlink id="results"></paramlink>
1676         array, <b>not</b> in the return value of this function.
1677         Threads that are currently suspended do not change state.
1678       </description>
1679       <origin>jvmdi</origin>
1680       <capabilities>
1681         <required id="can_suspend"></required>
1682       </capabilities>
1683       <parameters>
1684         <param id="request_count">
1685           <jint min="0"/>
1686           <description>
1687             The number of threads to suspend.
1688           </description>
1689         </param>
1690         <param id="request_list">
1691           <inbuf incount="request_count"><jthread/></inbuf>
1692             <description>
1693               The list of threads to suspend.
1694             </description>
1695         </param>
1696         <param id="results">
1697           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1698           <description>
1699             An agent supplied array of 
1700             <paramlink id="request_count"></paramlink> elements.
1701             On return, filled with the error code for
1702             the suspend of the corresponding thread.
1703             The error code will be 
1704             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1705             if the thread was suspended by this call.
1706             Possible error codes are those specified
1707             for <functionlink id="SuspendThread"></functionlink>.
1708           </description>
1709         </param>
1710       </parameters>
1711       <errors>
1712       </errors>
1713     </function>
1714 
1715     <function id="ResumeThread" num="6">
1716       <synopsis>Resume Thread</synopsis>
1717       <description>
1718         Resume a suspended thread. 
1719         Any threads currently suspended through
1720         a <jvmti/> suspend function (eg.
1721         <functionlink id="SuspendThread"></functionlink>) 
1722         or <code>java.lang.Thread.suspend()</code>
1723         will resume execution;  
1724         all other threads are unaffected.
1725       </description>
1726       <origin>jvmdi</origin>
1727       <capabilities>
1728         <required id="can_suspend"></required>
1729       </capabilities>
1730       <parameters>
1731         <param id="thread">
1732           <jthread/>
1733             <description>
1734               The thread to resume.
1735             </description>
1736         </param>
1737       </parameters>
1738       <errors>
1739         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
1740           Thread was not suspended.
1741         </error>
1742         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
1743           The state of the thread has been modified, and is now inconsistent. 
1744         </error>
1745       </errors>
1746     </function>
1747 
1748     <function id="ResumeThreadList" num="93">
1749       <synopsis>Resume Thread List</synopsis>
1750       <description>
1751         Resume the <paramlink id="request_count"></paramlink> 
1752         threads specified in the 
1753         <paramlink id="request_list"></paramlink> array. 
1754         Any thread suspended through
1755         a <jvmti/> suspend function (eg.
1756         <functionlink id="SuspendThreadList"></functionlink>) 
1757         or <code>java.lang.Thread.suspend()</code>
1758         will resume execution.
1759       </description>
1760       <origin>jvmdi</origin>
1761       <capabilities>
1762         <required id="can_suspend"></required>
1763       </capabilities>
1764       <parameters>
1765         <param id="request_count">
1766           <jint min="0"/>
1767           <description>
1768             The number of threads to resume.
1769           </description>
1770         </param>
1771         <param id="request_list">
1772           <inbuf incount="request_count"><jthread/></inbuf>
1773             <description>
1774               The threads to resume.
1775             </description>
1776         </param>
1777         <param id="results">
1778           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1779           <description>
1780             An agent supplied array of 
1781             <paramlink id="request_count"></paramlink> elements.
1782             On return, filled with the error code for
1783             the resume of the corresponding thread.
1784             The error code will be 
1785             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1786             if the thread was suspended by this call.
1787             Possible error codes are those specified
1788             for <functionlink id="ResumeThread"></functionlink>.
1789           </description>
1790         </param>
1791       </parameters>
1792       <errors>
1793       </errors>
1794     </function>
1795 
1796     <function id="StopThread" num="7">
1797       <synopsis>Stop Thread</synopsis>
1798       <description>
1799         Send the specified asynchronous exception to the specified thread 
1800         (similar to <code>java.lang.Thread.stop</code>).
1801         Normally, this function is used to kill the specified thread with an 
1802         instance of the exception <code>ThreadDeath</code>.
1803       </description>
1804       <origin>jvmdi</origin>
1805       <capabilities>
1806         <required id="can_signal_thread"></required>
1807       </capabilities>
1808       <parameters>
1809         <param id="thread">
1810           <jthread/>
1811             <description>
1812               The thread to stop.
1813             </description>
1814         </param>
1815         <param id="exception">
1816           <jobject/>
1817             <description>
1818               The asynchronous exception object.
1819             </description>
1820         </param>
1821       </parameters>
1822       <errors>
1823       </errors>
1824     </function>
1825 
1826     <function id="InterruptThread" num="8">
1827       <synopsis>Interrupt Thread</synopsis>
1828       <description>
1829         Interrupt the specified thread
1830         (similar to <code>java.lang.Thread.interrupt</code>).
1831       </description>
1832       <origin>jvmdi</origin>
1833       <capabilities>
1834         <required id="can_signal_thread"></required>
1835       </capabilities>
1836       <parameters>
1837         <param id="thread">
1838           <jthread impl="noconvert"/>
1839             <description>
1840               The thread to interrupt.
1841             </description>
1842         </param>
1843       </parameters>
1844       <errors>
1845       </errors>
1846     </function>
1847 
1848     <function id="GetThreadInfo" num="9">
1849       <synopsis>Get Thread Info</synopsis>
1850       <typedef id="jvmtiThreadInfo" label="Thread information structure">
1851         <field id="name">
1852           <allocfieldbuf><char/></allocfieldbuf>
1853           <description>
1854             The thread name, encoded as a
1855             <internallink id="mUTF">modified UTF-8</internallink> string.
1856           </description>
1857         </field>
1858         <field id="priority">
1859           <jint/>
1860           <description>
1861             The thread priority.  See the thread priority constants:
1862             <datalink id="jvmtiThreadPriority"></datalink>.
1863           </description>
1864         </field>
1865         <field id="is_daemon">
1866           <jboolean/>
1867           <description>
1868             Is this a daemon thread?
1869           </description>
1870         </field>
1871         <field id="thread_group">
1872           <jthreadGroup/>
1873           <description>
1874             The thread group to which this thread belongs.
1875             <code>NULL</code> if the thread has died.
1876           </description>
1877         </field>
1878         <field id="context_class_loader">
1879           <jobject/>
1880             <description>
1881               The context class loader associated with this thread.
1882             </description>
1883         </field>
1884       </typedef>
1885       <description>
1886         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure 
1887         are filled in with details of the specified thread.
1888       </description>
1889       <origin>jvmdi</origin>
1890       <capabilities>
1891       </capabilities>
1892       <parameters>
1893         <param id="thread">
1894           <jthread null="current" impl="noconvert" started="maybe"/>
1895             <description>
1896               The thread to query.
1897             </description>
1898         </param>
1899         <param id="info_ptr">
1900           <outptr><struct>jvmtiThreadInfo</struct></outptr>
1901           <description>
1902             On return, filled with information describing the specified thread.
1903           </description>
1904         </param>
1905       </parameters>
1906       <errors>
1907       </errors>
1908     </function>
1909 
1910     <function id="GetOwnedMonitorInfo" num="10">
1911       <synopsis>Get Owned Monitor Info</synopsis>
1912       <description>
1913         Get information about the monitors owned by the 
1914         specified thread. 
1915       </description>
1916       <origin>jvmdiClone</origin>
1917       <capabilities>
1918         <required id="can_get_owned_monitor_info"></required>
1919       </capabilities>
1920       <parameters>
1921         <param id="thread">
1922           <jthread null="current"/>
1923             <description>
1924               The thread to query.
1925             </description>
1926         </param>
1927         <param id="owned_monitor_count_ptr">
1928           <outptr><jint/></outptr>
1929           <description>
1930             The number of monitors returned.
1931           </description>
1932         </param>
1933         <param id="owned_monitors_ptr">
1934           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
1935             <description>
1936               The array of owned monitors.
1937             </description>
1938         </param>
1939       </parameters>
1940       <errors>
1941       </errors>
1942     </function>
1943 
1944     <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
1945       <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
1946       <typedef id="jvmtiMonitorStackDepthInfo" 
1947                label="Monitor stack depth information structure">
1948         <field id="monitor">
1949           <jobject/>
1950             <description>
1951               The owned monitor.
1952             </description>
1953         </field>
1954         <field id="stack_depth">
1955           <jint/>
1956           <description>
1957             The stack depth.  Corresponds to the stack depth used in the 
1958             <internallink id="stack">Stack Frame functions</internallink>.
1959             That is, zero is the current frame, one is the frame which
1960             called the current frame. And it is negative one if the 
1961             implementation cannot determine the stack depth (e.g., for 
1962             monitors acquired by JNI <code>MonitorEnter</code>).
1963           </description>
1964         </field>
1965       </typedef>
1966       <description>
1967         Get information about the monitors owned by the 
1968         specified thread and the depth of the stack frame which locked them. 
1969       </description>
1970       <origin>new</origin>
1971       <capabilities>
1972         <required id="can_get_owned_monitor_stack_depth_info"></required>
1973       </capabilities>
1974       <parameters>
1975         <param id="thread">
1976           <jthread null="current"/>
1977             <description>
1978               The thread to query.
1979             </description>
1980         </param>
1981         <param id="monitor_info_count_ptr">
1982           <outptr><jint/></outptr>
1983           <description>
1984             The number of monitors returned.
1985           </description>
1986         </param>
1987         <param id="monitor_info_ptr">
1988           <allocbuf outcount="monitor_info_count_ptr">
1989             <struct>jvmtiMonitorStackDepthInfo</struct>
1990           </allocbuf>
1991           <description>
1992             The array of owned monitor depth information.
1993           </description>
1994         </param>
1995       </parameters>
1996       <errors>
1997       </errors>
1998     </function>
1999 
2000     <function id="GetCurrentContendedMonitor" num="11">
2001       <synopsis>Get Current Contended Monitor</synopsis>
2002       <description>
2003         Get the object, if any, whose monitor the specified thread is waiting to 
2004         enter or waiting to regain through <code>java.lang.Object.wait</code>.
2005       </description>
2006       <origin>jvmdi</origin>
2007       <capabilities>
2008         <required id="can_get_current_contended_monitor"></required>
2009       </capabilities>
2010       <parameters>
2011         <param id="thread">
2012           <jthread null="current"/>
2013             <description>
2014               The thread to query.
2015             </description>
2016         </param>
2017         <param id="monitor_ptr">
2018           <outptr><jobject/></outptr>
2019             <description>
2020               On return, filled with the current contended monitor, or
2021               NULL if there is none.
2022             </description>
2023         </param>
2024       </parameters>
2025       <errors>
2026       </errors>
2027     </function>
2028 
2029     <callback id="jvmtiStartFunction">
2030       <void/>
2031       <synopsis>Agent Start Function</synopsis>
2032       <description>
2033         Agent supplied callback function.
2034         This function is the entry point for an agent thread
2035         started with
2036         <functionlink id="RunAgentThread"></functionlink>.
2037       </description>
2038       <parameters>
2039           <param id="jvmti_env">
2040             <outptr>
2041               <struct>jvmtiEnv</struct>
2042             </outptr>
2043             <description>
2044               The <jvmti/> environment.
2045             </description>
2046           </param>
2047           <param id="jni_env">
2048             <outptr>
2049               <struct>JNIEnv</struct>
2050             </outptr>
2051             <description>
2052               The JNI environment.
2053             </description>
2054           </param>
2055           <param id="arg">
2056             <outptr>
2057               <void/>
2058             </outptr>
2059               <description>
2060                 The <code>arg</code> parameter passed to 
2061                 <functionlink id="RunAgentThread"></functionlink>.
2062               </description>
2063           </param>
2064       </parameters>
2065     </callback>
2066 
2067     <function id="RunAgentThread" num="12">
2068       <synopsis>Run Agent Thread</synopsis>
2069       <description>
2070         Starts the execution of an agent thread. with the specified native function.
2071         The parameter <paramlink id="arg"></paramlink> is forwarded on to the
2072         <functionlink id="jvmtiStartFunction">start function</functionlink>
2073         (specified with <paramlink id="proc"></paramlink>) as its single argument.
2074         This function allows the creation of agent threads 
2075         for handling communication with another process or for handling events 
2076         without the need to load a special subclass of <code>java.lang.Thread</code> or 
2077         implementer of <code>java.lang.Runnable</code>. 
2078         Instead, the created thread can run entirely in native code.
2079         However, the created thread does require a newly created instance
2080         of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to 
2081         which it will be associated.
2082         The thread object can be created with JNI calls.
2083         <p/>
2084         The following common thread priorities are provided for your convenience:
2085         <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
2086           <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
2087             Minimum possible thread priority
2088           </constant>
2089           <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
2090             Normal thread priority
2091           </constant>
2092           <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
2093             Maximum possible thread priority
2094           </constant>
2095         </constants>
2096         <p/>
2097         The new thread is started as a daemon thread with the specified
2098         <paramlink id="priority"></paramlink>.
2099         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2100         <p/>
2101         Since the thread has been started, the thread will be live when this function
2102         returns, unless the thread has died immediately.
2103         <p/>
2104         The thread group of the thread is ignored -- specifically, the thread is not
2105         added to the thread group and the thread is not seen on queries of the thread
2106         group at either the Java programming language or <jvmti/> levels.
2107         <p/>
2108         The thread is not visible to Java programming language queries but is 
2109         included in <jvmti/> queries (for example, 
2110         <functionlink id="GetAllThreads"/> and
2111         <functionlink id="GetAllStackTraces"/>).
2112         <p/>
2113         Upon execution of <code>proc</code>, the new thread will be attached to the
2114         VM -- see the JNI documentation on 
2115         <externallink id="docs/technotes/guides/jni/spec/invocation.html#attaching_to_the_vm"
2116                       >Attaching to the VM</externallink>.
2117       </description>
2118       <origin>jvmdiClone</origin>
2119       <capabilities>
2120       </capabilities>
2121       <parameters>
2122         <param id="thread">
2123           <jthread impl="noconvert" started="no"/>
2124             <description>
2125               The thread to run.
2126             </description>
2127         </param>
2128         <param id="proc">
2129           <ptrtype>
2130             <struct>jvmtiStartFunction</struct>
2131           </ptrtype>
2132           <description>
2133             The start function.
2134           </description>
2135         </param>
2136         <param id="arg">
2137           <inbuf>
2138             <void/>
2139             <nullok><code>NULL</code> is passed to the start function</nullok>
2140           </inbuf>
2141           <description>
2142             The argument to the start function.
2143           </description>
2144         </param>
2145         <param id="priority">
2146           <jint/>
2147           <description>
2148             The priority of the started thread. Any thread
2149             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
2150             those in <datalink id="jvmtiThreadPriority"></datalink>.
2151           </description>
2152         </param>
2153       </parameters>
2154       <errors>
2155         <error id="JVMTI_ERROR_INVALID_PRIORITY"> 
2156             <paramlink id="priority"/> is less than 
2157             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
2158               or greater than
2159             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
2160         </error>
2161       </errors>
2162     </function>
2163 
2164     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
2165       <synopsis>Set Thread Local Storage</synopsis>
2166       <description>
2167         The VM stores a pointer value associated with each environment-thread
2168         pair. This pointer value is called <i>thread-local storage</i>.
2169         This value is <code>NULL</code> unless set with this function.
2170         Agents can allocate memory in which they store thread specific
2171         information. By setting thread-local storage it can then be
2172         accessed with 
2173         <functionlink id="GetThreadLocalStorage"></functionlink>.
2174         <p/>
2175         This function is called by the agent to set the value of the <jvmti/>
2176         thread-local storage. <jvmti/> supplies to the agent a pointer-size
2177         thread-local storage that can be used to record per-thread
2178         information.
2179       </description>
2180       <origin>jvmpi</origin>
2181       <capabilities>
2182       </capabilities>
2183       <parameters>
2184         <param id="thread">
2185           <jthread null="current"/>
2186             <description>
2187               Store to this thread.
2188             </description>
2189         </param>
2190         <param id="data">
2191           <inbuf> 
2192             <void/> 
2193             <nullok>value is set to <code>NULL</code></nullok> 
2194           </inbuf> 
2195           <description>
2196             The value to be entered into the thread-local storage.
2197           </description>
2198         </param>
2199       </parameters>
2200       <errors>
2201       </errors>
2202     </function>
2203 
2204     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
2205       <synopsis>Get Thread Local Storage</synopsis>
2206       <description>
2207         Called by the agent to get the value of the <jvmti/> thread-local
2208         storage. 
2209       </description>
2210       <origin>jvmpi</origin>
2211       <capabilities>
2212       </capabilities>
2213       <parameters>
2214         <param id="thread">
2215           <jthread null="current" impl="noconvert"/>
2216             <description>
2217               Retrieve from this thread.
2218             </description>
2219         </param>
2220         <param id="data_ptr">
2221           <agentbuf><void/></agentbuf>
2222           <description>
2223             Pointer through which the value of the thread local 
2224             storage is returned.
2225             If thread-local storage has not been set with
2226             <functionlink id="SetThreadLocalStorage"></functionlink> the returned 
2227             pointer is <code>NULL</code>.
2228           </description>
2229         </param>
2230       </parameters>
2231       <errors>
2232       </errors>
2233     </function>
2234 
2235   </category>
2236 
2237   <category id="thread_groups" label="Thread Group">
2238     <intro>
2239     </intro>
2240 
2241     <function id="GetTopThreadGroups" num="13">
2242       <synopsis>Get Top Thread Groups</synopsis>
2243       <description>
2244         Return all top-level (parentless) thread groups in the VM.
2245       </description>
2246       <origin>jvmdi</origin>
2247       <capabilities>
2248       </capabilities>
2249       <parameters>
2250         <param id="group_count_ptr">
2251           <outptr><jint/></outptr>
2252           <description>
2253             On return, points to the number of top-level thread groups.
2254           </description>
2255         </param>
2256         <param id="groups_ptr">
2257           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2258             <description>
2259               On return, refers to a pointer to the top-level thread group array.
2260             </description>
2261         </param>
2262       </parameters>
2263       <errors>
2264       </errors>
2265     </function>
2266 
2267     <function id="GetThreadGroupInfo" num="14">
2268       <synopsis>Get Thread Group Info</synopsis>
2269       <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
2270         <field id="parent">
2271           <jthreadGroup/>
2272           <description>
2273             The parent thread group.
2274           </description>
2275         </field>
2276         <field id="name">
2277           <allocfieldbuf><char/></allocfieldbuf>
2278           <description>
2279             The thread group's name, encoded as a
2280             <internallink id="mUTF">modified UTF-8</internallink> string.
2281           </description>
2282         </field>
2283         <field id="max_priority">
2284           <jint/>
2285           <description>
2286             The maximum priority for this thread group.
2287           </description>
2288         </field>
2289         <field id="is_daemon">
2290           <jboolean/>
2291           <description>
2292             Is this a daemon thread group?
2293           </description>
2294         </field>
2295       </typedef>
2296       <description>
2297         Get information about the thread group. The fields of the 
2298         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure 
2299         are filled in with details of the specified thread group.
2300       </description>
2301       <origin>jvmdi</origin>
2302       <capabilities>
2303       </capabilities>
2304       <parameters>
2305         <param id="group">
2306           <jthreadGroup/>
2307           <description>
2308             The thread group to query.
2309           </description>
2310         </param>
2311         <param id="info_ptr">
2312           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
2313           <description>
2314             On return, filled with information describing the specified
2315             thread group. 
2316           </description>
2317         </param>
2318       </parameters>
2319       <errors>
2320       </errors>
2321     </function>
2322 
2323     <function id="GetThreadGroupChildren" num="15">
2324       <synopsis>Get Thread Group Children</synopsis>
2325       <description>
2326         Get the live threads and active subgroups in this thread group.
2327       </description>
2328       <origin>jvmdi</origin>
2329       <capabilities>
2330       </capabilities>
2331       <parameters>
2332         <param id="group">
2333           <jthreadGroup/>
2334           <description>
2335             The group to query.
2336           </description>
2337         </param>
2338         <param id="thread_count_ptr">
2339           <outptr><jint/></outptr>
2340           <description>
2341             On return, points to the number of live threads in this thread group.
2342           </description>
2343         </param>
2344         <param id="threads_ptr">
2345           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
2346             <description>
2347               On return, points to an array of the live threads in this thread group.
2348             </description>
2349         </param>
2350         <param id="group_count_ptr">
2351           <outptr><jint/></outptr>
2352           <description>
2353             On return, points to the number of active child thread groups
2354           </description>
2355         </param>
2356         <param id="groups_ptr">
2357           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2358             <description>
2359               On return, points to an array of the active child thread groups.
2360             </description>
2361         </param>
2362       </parameters>
2363       <errors>
2364       </errors>
2365     </function>
2366   </category>
2367 
2368   <category id="stack" label="Stack Frame">
2369     <intro>
2370         These functions provide information about the stack of a thread.
2371         Stack frames are referenced by depth.
2372         The frame at depth zero is the current frame.
2373         <p/>
2374         Stack frames are as described in
2375         <vmspec chapter="3.6"/>,
2376         That is, they correspond to method 
2377         invocations (including native methods) but do not correspond to platform native or 
2378         VM internal frames.
2379         <p/>
2380         A <jvmti/> implementation may use method invocations to launch a thread and
2381         the corresponding frames may be included in the stack as presented by these functions --
2382         that is, there may be frames shown
2383         deeper than <code>main()</code> and <code>run()</code>.
2384         However this presentation must be consistent across all <jvmti/> functionality which 
2385         uses stack frames or stack depth.
2386     </intro>
2387 
2388       <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
2389         <description>
2390           Information about a stack frame is returned in this structure.
2391         </description>
2392         <field id="method">
2393           <jmethodID/>
2394             <description>
2395               The method executing in this frame.
2396             </description>
2397         </field>
2398         <field id="location">
2399           <jlocation/>
2400           <description>
2401             The index of the instruction executing in this frame.
2402             <code>-1</code> if the frame is executing a native method.
2403           </description>
2404         </field>
2405       </typedef>
2406 
2407       <typedef id="jvmtiStackInfo" label="Stack information structure">
2408         <description>
2409           Information about a set of stack frames is returned in this structure.
2410         </description>
2411         <field id="thread">
2412           <jthread/>
2413           <description>
2414             On return, the thread traced.
2415           </description>
2416         </field>
2417         <field id="state">
2418           <jint/>
2419           <description>
2420             On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
2421           </description>
2422         </field>
2423         <field id="frame_buffer">
2424           <outbuf incount="max_frame_count">
2425             <struct>jvmtiFrameInfo</struct>
2426           </outbuf>
2427             <description>
2428               On return, this agent allocated buffer is filled 
2429               with stack frame information.  
2430             </description>
2431         </field>
2432         <field id="frame_count">
2433           <jint/>
2434           <description>
2435             On return, the number of records filled into 
2436             <code>frame_buffer</code>.
2437             This will be 
2438             min(<code>max_frame_count</code>, <i>stackDepth</i>).
2439           </description>
2440         </field>
2441       </typedef>
2442 
2443     <function id="GetStackTrace" num="104">
2444       <synopsis>Get Stack Trace</synopsis>
2445       <description>
2446         Get information about the stack of a thread.
2447         If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
2448         the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, 
2449         otherwise the entire stack is returned.
2450         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2451         <p/>
2452         The following example causes up to five of the topmost frames
2453         to be returned and (if there are any frames) the currently
2454         executing method name to be printed.
2455         <example>
2456 jvmtiFrameInfo frames[5];
2457 jint count;
2458 jvmtiError err;
2459 
2460 err = (*jvmti)-&gt;GetStackTrace(jvmti, aThread, 0, 5, 
2461                                frames, &amp;count);
2462 if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
2463    char *methodName;
2464    err = (*jvmti)-&gt;GetMethodName(jvmti, frames[0].method, 
2465                        &amp;methodName, NULL, NULL);
2466    if (err == JVMTI_ERROR_NONE) {
2467       printf("Executing method: %s", methodName);
2468    }
2469 }
2470         </example>
2471         <todo> 
2472           check example code.
2473         </todo>
2474         <p/>
2475         The <paramlink id="thread"></paramlink> need not be suspended
2476         to call this function.  
2477         <p/>
2478         The <functionlink id="GetLineNumberTable"></functionlink>
2479         function can be used to map locations to line numbers. Note that
2480         this mapping can be done lazily.
2481       </description>
2482       <origin>jvmpi</origin>
2483       <capabilities>
2484       </capabilities>
2485       <parameters>
2486         <param id="thread">
2487           <jthread null="current"/>
2488             <description>
2489               Fetch the stack trace of this thread.
2490             </description>
2491         </param>
2492         <param id="start_depth">
2493           <jint/>
2494           <description>
2495             Begin retrieving frames at this depth.  
2496             If non-negative, count from the current frame, 
2497             the first frame retrieved is at depth <code>start_depth</code>.  
2498             For example, if zero, start from the current frame; if one, start from the
2499             caller of the current frame; if two, start from the caller of the
2500             caller of the current frame; and so on.
2501             If negative, count from below the oldest frame,
2502             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,  
2503             where <i>stackDepth</i> is the count of frames on the stack.  
2504             For example, if negative one, only the oldest frame is retrieved;
2505             if negative two, start from the frame called by the oldest frame.
2506           </description>
2507         </param>
2508         <param id="max_frame_count">
2509           <jint min="0"/>
2510           <description>
2511             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2512           </description>
2513         </param>
2514         <param id="frame_buffer">
2515           <outbuf incount="max_frame_count" outcount="count_ptr">
2516             <struct>jvmtiFrameInfo</struct>
2517           </outbuf>
2518             <description>
2519               On return, this agent allocated buffer is filled 
2520               with stack frame information.  
2521             </description>
2522         </param>
2523         <param id="count_ptr">
2524           <outptr><jint/></outptr>
2525           <description>
2526             On return, points to the number of records filled in.
2527             For non-negative <code>start_depth</code>, this will be 
2528             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
2529             For negative <code>start_depth</code>, this will be 
2530             min(<code>max_frame_count</code>, <code>-start_depth</code>).
2531           </description>
2532         </param>
2533       </parameters>
2534       <errors>
2535         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
2536           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
2537           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
2538         </error>
2539       </errors>
2540     </function>
2541 
2542 
2543     <function id="GetAllStackTraces" num="100">
2544       <synopsis>Get All Stack Traces</synopsis>
2545       <description>
2546         Get information about the stacks of all live threads
2547         (including <internallink id="RunAgentThread">agent threads</internallink>).
2548         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2549         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 
2550         otherwise the entire stack is returned.
2551         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2552         <p/>
2553         All stacks are collected simultaneously, that is, no changes will occur to the 
2554         thread state or stacks between the sampling of one thread and the next.
2555         The threads need not be suspended.
2556         
2557         <example>
2558 jvmtiStackInfo *stack_info;
2559 jint thread_count;
2560 int ti;
2561 jvmtiError err;
2562 
2563 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count); 
2564 if (err != JVMTI_ERROR_NONE) {
2565    ...   
2566 }
2567 for (ti = 0; ti &lt; thread_count; ++ti) {
2568    jvmtiStackInfo *infop = &amp;stack_info[ti];
2569    jthread thread = infop-&gt;thread;
2570    jint state = infop-&gt;state;
2571    jvmtiFrameInfo *frames = infop-&gt;frame_buffer;
2572    int fi;
2573 
2574    myThreadAndStatePrinter(thread, state);
2575    for (fi = 0; fi &lt; infop-&gt;frame_count; fi++) {
2576       myFramePrinter(frames[fi].method, frames[fi].location);
2577    }
2578 }
2579 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
2580 err = (*jvmti)-&gt;Deallocate(jvmti, stack_info); 
2581         </example>
2582         <todo> 
2583           check example code.
2584         </todo>
2585 
2586       </description>
2587       <origin>new</origin>
2588       <capabilities>
2589       </capabilities>
2590       <parameters>
2591         <param id="max_frame_count">
2592           <jint min="0"/>
2593           <description>
2594             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2595           </description>
2596         </param>
2597         <param id="stack_info_ptr">
2598           <allocbuf>
2599             <struct>jvmtiStackInfo</struct>
2600           </allocbuf>
2601             <description>
2602               On return, this buffer is filled 
2603               with stack information for each thread.  
2604               The number of <datalink id="jvmtiStackInfo"/> records is determined 
2605               by <paramlink id="thread_count_ptr"/>.
2606               <p/>
2607               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 
2608               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2609               These buffers must not be separately deallocated.
2610             </description>
2611         </param>
2612         <param id="thread_count_ptr">
2613           <outptr><jint/></outptr>
2614           <description>
2615             The number of threads traced.
2616           </description>
2617         </param>
2618       </parameters>
2619       <errors>
2620       </errors>
2621     </function>
2622 
2623     <function id="GetThreadListStackTraces" num="101">
2624       <synopsis>Get Thread List Stack Traces</synopsis>
2625       <description>
2626         Get information about the stacks of the supplied threads.
2627         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2628         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 
2629         otherwise the entire stack is returned.
2630         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2631         <p/>
2632         All stacks are collected simultaneously, that is, no changes will occur to the 
2633         thread state or stacks between the sampling one thread and the next.
2634         The threads need not be suspended.
2635         <p/>
2636         If a thread has not yet started or terminates before the stack information is collected,
2637         a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
2638         will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
2639         <p/>
2640         See the example for the similar function
2641         <functionlink id="GetAllStackTraces"/>.
2642       </description>
2643       <origin>new</origin>
2644       <capabilities>
2645       </capabilities>
2646       <parameters>
2647         <param id="thread_count">
2648           <jint min="0"/>
2649           <description>
2650             The number of threads to trace.
2651           </description>
2652         </param>
2653         <param id="thread_list">
2654           <inbuf incount="thread_count"><jthread/></inbuf>
2655             <description>
2656               The list of threads to trace.
2657             </description>
2658         </param>
2659         <param id="max_frame_count">
2660           <jint min="0"/>
2661           <description>
2662             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2663           </description>
2664         </param>
2665         <param id="stack_info_ptr">
2666           <allocbuf outcount="thread_count">
2667             <struct>jvmtiStackInfo</struct>
2668           </allocbuf>
2669             <description>
2670               On return, this buffer is filled 
2671               with stack information for each thread.  
2672               The number of <datalink id="jvmtiStackInfo"/> records is determined 
2673               by <paramlink id="thread_count"/>.
2674               <p/>
2675               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 
2676               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2677               These buffers must not be separately deallocated.
2678             </description>
2679         </param>
2680       </parameters>
2681       <errors>
2682         <error id="JVMTI_ERROR_INVALID_THREAD">
2683           An element in <paramlink id="thread_list"/> is not a thread object.
2684         </error>
2685       </errors>
2686     </function>
2687 
2688     <elide>
2689     <function id="AsyncGetStackTrace" num="1000">
2690       <synopsis>Get Stack Trace--Asynchronous</synopsis>
2691       <description>
2692         Get information about the entire stack of a thread (or a sub-section of it).
2693         This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
2694         and is reentrant and safe to call
2695         from asynchronous signal handlers.
2696         The stack trace is returned only for the calling thread.
2697         <p/>
2698         The <functionlink id="GetLineNumberTable"></functionlink>
2699         function can be used to map locations to line numbers. Note that
2700         this mapping can be done lazily.
2701       </description>
2702       <origin>jvmpi</origin>
2703       <capabilities>
2704         <required id="can_get_async_stack_trace"></required>
2705         <capability id="can_show_JVM_spec_async_frames">
2706           If <code>false</code>, 
2707           <paramlink id="use_java_stack"></paramlink> 
2708           must be <code>false</code>.
2709         </capability>
2710       </capabilities>
2711       <parameters>
2712         <param id="use_java_stack">
2713           <jboolean/>
2714           <description>
2715             Return the stack showing <vmspec/>
2716             model of the stack; 
2717             otherwise, show the internal representation of the stack with
2718             inlined and optimized methods missing.  If the virtual machine
2719             is using the <i>Java Virtual Machine Specification</i> stack model
2720             internally, this flag is ignored.
2721           </description>
2722         </param>
2723         <param id="max_count">
2724           <jint min="0"/>
2725           <description>
2726             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2727             Retrieve this many unless the stack depth is less than <code>max_count</code>.
2728           </description>
2729         </param>
2730         <param id="frame_buffer">
2731           <outbuf incount="max_count" outcount="count_ptr">
2732             <struct>jvmtiFrameInfo</struct>
2733             <nullok>this information is not returned</nullok>
2734           </outbuf>
2735             <description>
2736               The agent passes in a buffer
2737               large enough to hold <code>max_count</code> records of 
2738               <datalink id="jvmtiFrameInfo"></datalink>.  This buffer must be
2739               pre-allocated by the agent.  
2740             </description>
2741         </param>
2742         <param id="count_ptr">
2743           <outptr><jint/></outptr>
2744           <description>
2745             On return, points to the number of records filled in..
2746           </description>
2747         </param>
2748       </parameters>
2749       <errors>
2750         <error id="JVMTI_ERROR_UNATTACHED_THREAD">
2751           The thread being used to call this function is not attached
2752           to the virtual machine.  Calls must be made from attached threads.
2753         </error>
2754       </errors>
2755     </function>
2756     </elide>
2757 
2758     <function id="GetFrameCount" num="16">
2759       <synopsis>Get Frame Count</synopsis>
2760       <description>
2761         Get the number of frames currently in the specified thread's call stack.
2762         <p/>
2763         If this function is called for a thread actively executing bytecodes (for example,
2764         not the current thread and not suspended), the information returned is transient.
2765       </description>
2766       <origin>jvmdi</origin>
2767       <capabilities>
2768       </capabilities>
2769       <parameters>
2770         <param id="thread">
2771           <jthread null="current"/>
2772             <description>
2773               The thread to query.
2774             </description>
2775         </param>
2776         <param id="count_ptr">
2777           <outptr><jint/></outptr>
2778           <description>
2779             On return, points to the number of frames in the call stack.
2780           </description>
2781         </param>
2782       </parameters>
2783       <errors>
2784       </errors>
2785     </function>
2786 
2787     <function id="PopFrame" num="80">
2788       <synopsis>Pop Frame</synopsis>
2789       <description>
2790         Pop the current frame of <code>thread</code>'s stack.
2791         Popping a frame takes you to the previous frame.  
2792         When the thread is resumed, the execution 
2793         state of the thread is reset to the state
2794         immediately before the called method was invoked.
2795         That is (using <vmspec/> terminology):
2796           <ul>
2797             <li>the current frame is discarded as the previous frame becomes the current one</li>
2798             <li>the operand stack is restored--the argument values are added back
2799               and if the invoke was not <code>invokestatic</code>, 
2800               <code>objectref</code> is added back as well</li>
2801             <li>the Java virtual machine PC is restored to the opcode
2802               of the invoke instruction</li>
2803           </ul>
2804         Note however, that any changes to the arguments, which
2805         occurred in the called method, remain; 
2806         when execution continues, the first instruction to 
2807         execute will be the invoke.  
2808         <p/>
2809         Between calling <code>PopFrame</code> and resuming the 
2810         thread the state of the stack is undefined.  
2811         To pop frames beyond the first, 
2812         these three steps must be repeated:
2813         <ul>
2814           <li>suspend the thread via an event (step, breakpoint, ...)</li>
2815           <li>call <code>PopFrame</code></li>
2816           <li>resume the thread</li>
2817         </ul>
2818         <p/>
2819         A lock acquired by calling the called method 
2820         (if it is a <code>synchronized</code>  method) 
2821         and locks acquired by entering <code>synchronized</code>
2822         blocks within the called method are released. 
2823         Note: this does not apply to native locks or 
2824         <code>java.util.concurrent.locks</code> locks.
2825         <p/>
2826         Finally blocks are not executed.
2827         <p/>
2828         Changes to global state are not addressed and thus remain changed.
2829         <p/>
2830         The specified thread must be suspended (which implies it cannot be the current thread).
2831         <p/>
2832         Both the called method and calling method must be non-native Java programming 
2833         language methods.
2834         <p/>
2835         No <jvmti/> events are generated by this function.
2836       </description>
2837       <origin>jvmdi</origin>
2838       <capabilities>
2839         <required id="can_pop_frame"></required>
2840       </capabilities>
2841       <parameters>
2842         <param id="thread">
2843           <jthread/>
2844             <description>
2845               The thread whose current frame is to be popped.
2846             </description>
2847         </param>
2848       </parameters>
2849       <errors>
2850         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2851           Called or calling method is a native method.
2852           The implementation is unable to pop this frame.
2853         </error>
2854         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2855           Thread was not suspended.
2856         </error>
2857         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2858           There are less than two stack frames on the call stack.
2859         </error>
2860       </errors>
2861     </function>
2862 
2863     <function id="GetFrameLocation" num="19">
2864       <synopsis>Get Frame Location</synopsis>
2865       <description>
2866         <p/>
2867         For a Java programming language frame, return the location of the instruction
2868         currently executing.
2869       </description>
2870       <origin>jvmdiClone</origin>
2871       <capabilities>
2872       </capabilities>
2873       <parameters>
2874         <param id="thread">
2875           <jthread null="current" frame="frame"/>
2876           <description>
2877             The thread of the frame to query.
2878           </description>
2879         </param>
2880         <param id="depth">
2881           <jframeID thread="thread"/>
2882           <description>
2883             The depth of the frame to query.
2884           </description>
2885         </param>
2886         <param id="method_ptr">
2887           <outptr><jmethodID/></outptr>
2888             <description>
2889               On return, points to the method for the current location.
2890             </description>
2891         </param>
2892         <param id="location_ptr">
2893           <outptr><jlocation/></outptr>
2894           <description>
2895             On return, points to the index of the currently 
2896             executing instruction.
2897             Is set to <code>-1</code> if the frame is executing
2898             a native method.
2899           </description>
2900         </param>
2901       </parameters>
2902       <errors>
2903       </errors>
2904     </function>
2905 
2906     <function id="NotifyFramePop" num="20">
2907       <synopsis>Notify Frame Pop</synopsis>
2908       <description>
2909         When the frame that is currently at <paramlink id="depth"></paramlink> 
2910         is popped from the stack, generate a
2911         <eventlink id="FramePop"></eventlink> event.  See the 
2912         <eventlink id="FramePop"></eventlink> event for details.
2913         Only frames corresponding to non-native Java programming language 
2914         methods can receive notification.
2915         <p/>
2916         The specified thread must either be the current thread
2917         or the thread must be suspended.
2918       </description>
2919       <origin>jvmdi</origin>
2920       <capabilities>
2921         <required id="can_generate_frame_pop_events"></required>
2922       </capabilities>
2923       <parameters>
2924         <param id="thread">
2925           <jthread null="current" frame="depth"/>   
2926           <description>
2927             The thread of the frame for which the frame pop event will be generated.
2928           </description>
2929         </param>
2930         <param id="depth">
2931           <jframeID thread="thread"/>
2932           <description>
2933             The depth of the frame for which the frame pop event will be generated.
2934           </description>
2935         </param>
2936       </parameters>
2937       <errors>
2938         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
2939           The frame at <code>depth</code> is executing a
2940           native method.
2941         </error>
2942         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2943           Thread was not suspended and was not the current thread.
2944         </error>
2945       </errors>
2946     </function>
2947 
2948   </category>
2949 
2950   <category id="ForceEarlyReturn" label="Force Early Return">
2951     <intro>
2952       These functions allow an agent to force a method
2953       to return at any point during its execution.
2954       The method which will return early is referred to as the <i>called method</i>.
2955       The called method is the current method
2956       (as defined by
2957       <vmspec chapter="3.6"/>) 
2958       for the specified thread at
2959       the time the function is called.
2960       <p/>
2961       The specified thread must be suspended or must be the current thread.
2962       The return occurs when execution of Java programming
2963       language code is resumed on this thread.
2964       Between calling one of these functions and resumption
2965       of thread execution, the state of the stack is undefined.  
2966       <p/>
2967       No further instructions are executed in the called method.  
2968       Specifically, finally blocks are not executed.
2969       Note: this can cause inconsistent states in the application.
2970       <p/>
2971       A lock acquired by calling the called method 
2972       (if it is a <code>synchronized</code>  method) 
2973       and locks acquired by entering <code>synchronized</code>
2974       blocks within the called method are released. 
2975       Note: this does not apply to native locks or 
2976       <code>java.util.concurrent.locks</code> locks.
2977       <p/>
2978       Events, such as <eventlink id="MethodExit"></eventlink>,
2979       are generated as they would be in a normal return.
2980       <p/>
2981       The called method must be a non-native Java programming
2982       language method.
2983       Forcing return on a thread with only one frame on the
2984       stack causes the thread to exit when resumed.
2985     </intro>
2986 
2987     <function id="ForceEarlyReturnObject" num="81" since="1.1">
2988       <synopsis>Force Early Return - Object</synopsis>
2989       <description>
2990         This function can be used to return from a method whose
2991         result type is <code>Object</code>
2992         or a subclass of <code>Object</code>. 
2993       </description>
2994       <origin>new</origin>
2995       <capabilities>
2996         <required id="can_force_early_return"></required>
2997       </capabilities>
2998       <parameters>
2999         <param id="thread">
3000           <jthread null="current"/>
3001           <description>
3002             The thread whose current frame is to return early.
3003           </description>
3004         </param>
3005         <param id="value">
3006           <jobject/>
3007           <description>
3008             The return value for the called frame. 
3009             An object or <code>NULL</code>.
3010           </description>
3011         </param>
3012       </parameters>
3013       <errors>
3014         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3015           Attempted to return early from a frame
3016           corresponding to a native method.
3017           Or the implementation is unable to provide
3018           this functionality on this frame.
3019         </error>
3020         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3021           The result type of the called method is not 
3022           <code>Object</code> or a subclass of <code>Object</code>.
3023         </error>
3024         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3025           The supplied <paramlink id="value"/> is not compatible with the 
3026           result type of the called method.
3027         </error>
3028         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3029           Thread was not the current thread and was not suspended.
3030         </error>
3031         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3032           There are no more frames on the call stack.
3033         </error>
3034       </errors>
3035     </function>
3036 
3037     <function id="ForceEarlyReturnInt" num="82" since="1.1">
3038       <synopsis>Force Early Return - Int</synopsis>
3039       <description>
3040         This function can be used to return from a method whose
3041         result type is <code>int</code>, <code>short</code>,
3042         <code>char</code>, <code>byte</code>, or 
3043         <code>boolean</code>. 
3044       </description>
3045       <origin>new</origin>
3046       <capabilities>
3047         <required id="can_force_early_return"></required>
3048       </capabilities>
3049       <parameters>
3050         <param id="thread">
3051           <jthread null="current"/>
3052           <description>
3053             The thread whose current frame is to return early.
3054           </description>
3055         </param>
3056         <param id="value">
3057           <jint/>
3058           <description>
3059             The return value for the called frame.
3060           </description>
3061         </param>
3062       </parameters>
3063       <errors>
3064         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3065           Attempted to return early from a frame
3066           corresponding to a native method.
3067           Or the implementation is unable to provide
3068           this functionality on this frame.
3069         </error>
3070         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3071           The result type of the called method is not 
3072           <code>int</code>, <code>short</code>,
3073           <code>char</code>, <code>byte</code>, or 
3074           <code>boolean</code>.
3075         </error>
3076         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3077           Thread was not the current thread and was not suspended.
3078         </error>
3079         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3080           There are no frames on the call stack.
3081         </error>
3082       </errors>
3083     </function>
3084 
3085     <function id="ForceEarlyReturnLong" num="83" since="1.1">
3086       <synopsis>Force Early Return - Long</synopsis>
3087       <description>
3088         This function can be used to return from a method whose
3089         result type is <code>long</code>.
3090       </description>
3091       <origin>new</origin>
3092       <capabilities>
3093         <required id="can_force_early_return"></required>
3094       </capabilities>
3095       <parameters>
3096         <param id="thread">
3097           <jthread null="current"/>
3098           <description>
3099             The thread whose current frame is to return early.
3100           </description>
3101         </param>
3102         <param id="value">
3103           <jlong/>
3104           <description>
3105             The return value for the called frame.
3106           </description>
3107         </param>
3108       </parameters>
3109       <errors>
3110         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3111           Attempted to return early from a frame
3112           corresponding to a native method.
3113           Or the implementation is unable to provide
3114           this functionality on this frame.
3115         </error>
3116         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3117           The result type of the called method is not <code>long</code>.
3118         </error>
3119         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3120           Thread was not the current thread and was not suspended.
3121         </error>
3122         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3123           There are no frames on the call stack.
3124         </error>
3125       </errors>
3126     </function>
3127 
3128     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
3129       <synopsis>Force Early Return - Float</synopsis>
3130       <description>
3131         This function can be used to return from a method whose
3132         result type is <code>float</code>.
3133       </description>
3134       <origin>new</origin>
3135       <capabilities>
3136         <required id="can_force_early_return"></required>
3137       </capabilities>
3138       <parameters>
3139         <param id="thread">
3140           <jthread null="current"/>
3141           <description>
3142             The thread whose current frame is to return early.
3143           </description>
3144         </param>
3145         <param id="value">
3146           <jfloat/>
3147           <description>
3148             The return value for the called frame.
3149           </description>
3150         </param>
3151       </parameters>
3152       <errors>
3153         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3154           Attempted to return early from a frame
3155           corresponding to a native method.
3156           Or the implementation is unable to provide
3157           this functionality on this frame.
3158         </error>
3159         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3160           The result type of the called method is not <code>float</code>.
3161         </error>
3162         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3163           Thread was not the current thread and was not suspended.
3164         </error>
3165         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3166           There are no frames on the call stack.
3167         </error>
3168       </errors>
3169     </function>
3170 
3171     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
3172       <synopsis>Force Early Return - Double</synopsis>
3173       <description>
3174         This function can be used to return from a method whose
3175         result type is <code>double</code>.
3176       </description>
3177       <origin>new</origin>
3178       <capabilities>
3179         <required id="can_force_early_return"></required>
3180       </capabilities>
3181       <parameters>
3182         <param id="thread">
3183           <jthread null="current"/>
3184           <description>
3185             The thread whose current frame is to return early.
3186           </description>
3187         </param>
3188         <param id="value">
3189           <jdouble/>
3190           <description>
3191             The return value for the called frame.
3192           </description>
3193         </param>
3194       </parameters>
3195       <errors>
3196         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3197           Attempted to return early from a frame corresponding to a native method.
3198           Or the implementation is unable to provide this functionality on this frame.
3199         </error>
3200         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3201           The result type of the called method is not <code>double</code>.
3202         </error>
3203         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3204           Thread was not the current thread and was not suspended.
3205         </error>
3206         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3207           There are no frames on the call stack.
3208         </error>
3209       </errors>
3210     </function>
3211 
3212     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3213       <synopsis>Force Early Return - Void</synopsis>
3214       <description>
3215         This function can be used to return from a method with no result type.
3216         That is, the called method must be declared <code>void</code>.
3217       </description>
3218       <origin>new</origin>
3219       <capabilities>
3220         <required id="can_force_early_return"></required>
3221       </capabilities>
3222       <parameters>
3223         <param id="thread">
3224           <jthread null="current"/>
3225           <description>
3226             The thread whose current frame is to return early.
3227           </description>
3228         </param>
3229       </parameters>
3230       <errors>
3231         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3232           Attempted to return early from a frame
3233           corresponding to a native method.
3234           Or the implementation is unable to provide
3235           this functionality on this frame.
3236         </error>
3237         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3238           The called method has a result type.  
3239         </error>
3240         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3241           Thread was not the current thread and was not suspended.
3242         </error>
3243         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3244           There are no frames on the call stack.
3245         </error>
3246       </errors>
3247     </function>
3248 
3249   </category>
3250 
3251   <category id="Heap" label="Heap">
3252     <intro>
3253       These functions are used to analyze the heap.
3254       Functionality includes the ability to view the objects in the
3255       heap and to tag these objects.
3256     </intro>
3257    
3258     <intro id="objectTags" label="Object Tags">
3259       A <i>tag</i> is a value associated with an object.
3260       Tags are explicitly set by the agent using the
3261       <functionlink id="SetTag"></functionlink> function or by
3262       callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.    
3263       <p/>
3264       Tags are local to the environment; that is, the tags of one
3265       environment are not visible in another.
3266       <p/>
3267       Tags are <code>jlong</code> values which can be used
3268       simply to mark an object or to store a pointer to more detailed
3269       information.  Objects which have not been tagged have a
3270       tag of zero.  
3271       Setting a tag to zero makes the object untagged.
3272     </intro>
3273    
3274     <intro id="heapCallbacks" label="Heap Callback Functions">
3275         Heap functions which iterate through the heap and recursively
3276         follow object references use agent supplied callback functions
3277         to deliver the information.
3278         <p/>
3279         These heap callback functions must adhere to the following restrictions --
3280         These callbacks must not use JNI functions.
3281         These callbacks must not use <jvmti/> functions except 
3282         <i>callback safe</i> functions which
3283         specifically allow such use (see the raw monitor, memory management,
3284         and environment local storage functions).
3285         <p/>
3286         An implementation may invoke a callback on an internal thread or
3287         the thread which called the iteration function.
3288         Heap callbacks are single threaded -- no more than one callback will
3289         be invoked at a time.
3290         <p/>
3291         The Heap Filter Flags can be used to prevent reporting
3292         based on the tag status of an object or its class.  
3293         If no flags are set (the <code>jint</code> is zero), objects
3294         will not be filtered out.
3295 
3296         <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
3297           <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
3298             Filter out tagged objects. Objects which are tagged are not included.
3299           </constant>
3300           <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
3301             Filter out untagged objects. Objects which are not tagged are not included.
3302           </constant>
3303           <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
3304             Filter out objects with tagged classes. Objects whose class is tagged are not included.
3305           </constant>
3306           <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
3307             Filter out objects with untagged classes. Objects whose class is not tagged are not included.
3308           </constant>
3309         </constants>
3310 
3311         <p/>
3312         The Heap Visit Control Flags are returned by the heap callbacks
3313         and can be used to abort the iteration.  For the 
3314         <functionlink id="jvmtiHeapReferenceCallback">Heap 
3315         Reference Callback</functionlink>, it can also be used 
3316         to prune the graph of traversed references
3317         (<code>JVMTI_VISIT_OBJECTS</code> is not set).
3318 
3319         <constants id="jvmtiHeapVisitControl" 
3320                    label="Heap Visit Control Flags" 
3321                    kind="bits" 
3322                    since="1.1">
3323           <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
3324             If we are visiting an object and if this callback
3325             was initiated by <functionlink id="FollowReferences"/>, 
3326             traverse the references of this object.
3327             Otherwise ignored.
3328           </constant>       
3329           <constant id="JVMTI_VISIT_ABORT" num="0x8000">
3330             Abort the iteration.  Ignore all other bits.
3331           </constant>
3332         </constants>
3333 
3334         <p/>
3335         The Heap Reference Enumeration is provided by the 
3336         <functionlink id="jvmtiHeapReferenceCallback">Heap 
3337         Reference Callback</functionlink> and 
3338         <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field 
3339         Callback</functionlink> to 
3340         describe the kind of reference
3341         being reported.
3342 
3343         <constants id="jvmtiHeapReferenceKind" 
3344                    label="Heap Reference Enumeration" 
3345                    kind="enum" 
3346                    since="1.1">
3347           <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
3348             Reference from an object to its class.
3349           </constant>       
3350           <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
3351             Reference from an object to the value of one of its instance fields.
3352           </constant>
3353           <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
3354             Reference from an array to one of its elements.
3355           </constant>
3356           <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
3357             Reference from a class to its class loader.
3358           </constant>
3359           <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
3360             Reference from a class to its signers array.
3361           </constant>
3362           <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
3363             Reference from a class to its protection domain.
3364           </constant>       
3365           <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
3366             Reference from a class to one of its interfaces. 
3367             Note: interfaces are defined via a constant pool reference,
3368             so the referenced interfaces may also be reported with a 
3369             <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3370           </constant>
3371           <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
3372             Reference from a class to the value of one of its static fields.
3373           </constant>
3374           <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
3375             Reference from a class to a resolved entry in the constant pool.
3376           </constant>
3377           <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
3378             Reference from a class to its superclass. 
3379             A callback is not sent if the superclass is <code>java.lang.Object</code>.
3380             Note: loaded classes define superclasses via a constant pool
3381             reference, so the referenced superclass may also be reported with 
3382             a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3383           </constant>
3384           <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
3385             Heap root reference: JNI global reference.
3386           </constant>
3387           <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
3388             Heap root reference: System class.
3389           </constant>
3390           <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
3391             Heap root reference: monitor.
3392           </constant>
3393           <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
3394             Heap root reference: local variable on the stack.
3395           </constant>
3396           <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
3397             Heap root reference: JNI local reference.
3398           </constant>
3399           <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
3400             Heap root reference: Thread.
3401           </constant>
3402           <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
3403             Heap root reference: other heap root reference.
3404           </constant>
3405         </constants>
3406 
3407         <p/>
3408         Definitions for the single character type descriptors of
3409         primitive types.
3410 
3411         <constants id="jvmtiPrimitiveType" 
3412                    label="Primitive Type Enumeration" 
3413                    kind="enum" 
3414                    since="1.1">
3415           <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
3416             'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
3417           </constant>       
3418           <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
3419             'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
3420           </constant>       
3421           <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
3422             'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
3423           </constant>       
3424           <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
3425             'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
3426           </constant>       
3427           <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
3428             'I' - Java programming language <code>int</code> - JNI <code>jint</code>
3429           </constant>       
3430           <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
3431             'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
3432           </constant>       
3433           <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
3434             'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
3435           </constant>       
3436           <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
3437             'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
3438           </constant>       
3439         </constants>
3440     </intro>
3441 
3442       <typedef id="jvmtiHeapReferenceInfoField" 
3443                label="Reference information structure for Field references" 
3444                since="1.1">
3445         <description>
3446           Reference information returned for 
3447           <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and 
3448           <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3449         </description>
3450         <field id="index">
3451           <jint/>
3452           <description>       
3453             For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the 
3454             referrer object is not a class or an inteface.  
3455             In this case, <code>index</code> is the index of the field 
3456             in the class of the referrer object.  
3457             This class is referred to below as <i>C</i>.
3458             <p/>
3459             For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
3460             the referrer object is a class (referred to below as <i>C</i>)
3461             or an interface (referred to below as <i>I</i>).
3462             In this case, <code>index</code> is the index of the field in 
3463             that class or interface.
3464             <p/>
3465             If the referrer object is not an interface, then the field 
3466             indices are determined as follows: 
3467             <ul>
3468               <li>make a list of all the fields in <i>C</i> and its
3469                   superclasses, starting with all the fields in 
3470                   <code>java.lang.Object</code> and ending with all the
3471                   fields in <i>C</i>.</li>
3472               <li>Within this list, put 
3473                   the fields for a given class in the order returned by
3474                   <functionlink id="GetClassFields"/>.</li>
3475               <li>Assign the fields in this list indices 
3476                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 
3477                   is the count of the fields in all the interfaces
3478                   implemented by <i>C</i>. 
3479                   Note that <i>C</i> implements all interfaces 
3480                   directly implemented by its superclasses; as well
3481                   as all superinterfaces of these interfaces.</li>
3482             </ul>
3483             If the referrer object is an interface, then the field 
3484             indices are determined as follows:
3485             <ul>
3486               <li>make a list of the fields directly declared in 
3487                   <i>I</i>.</li>
3488               <li>Within this list, put 
3489                   the fields in the order returned by
3490                   <functionlink id="GetClassFields"/>.</li>
3491               <li>Assign the fields in this list indices 
3492                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 
3493                   is the count of the fields in all the superinterfaces
3494                   of <i>I</i>.</li>
3495             </ul>
3496             All fields are included in this computation, regardless of
3497             field modifier (static, public, private, etc).
3498             <p/>
3499             For example, given the following classes and interfaces:
3500             <example>
3501 interface I0 {
3502     int p = 0;
3503 }
3504 
3505 interface I1 extends I0 {
3506     int x = 1;
3507 }
3508 
3509 interface I2 extends I0 {
3510     int y = 2;
3511 }
3512 
3513 class C1 implements I1 {
3514     public static int a = 3;
3515     private int b = 4;
3516 }
3517 
3518 class C2 extends C1 implements I2 {
3519     static int q = 5;
3520     final int r = 6;
3521 }
3522             </example>
3523             Assume that <functionlink id="GetClassFields"/> called on
3524             <code>C1</code> returns the fields of <code>C1</code> in the
3525             order: a, b; and that the fields of <code>C2</code> are 
3526             returned in the order: q, r.
3527             An instance of class <code>C1</code> will have the
3528             following field indices:
3529             <dl><dd><table>
3530               <tr>
3531                 <td>
3532                   a
3533                 </td>
3534                 <td>
3535                   2
3536                 </td>
3537                 <td align="left">
3538                   The count of the fields in the interfaces
3539                   implemented by <code>C1</code> is two (<i>n</i>=2):
3540                   <code>p</code> of <code>I0</code>
3541                   and <code>x</code> of <code>I1</code>.
3542                 </td>
3543               </tr>
3544               <tr>
3545                 <td>
3546                   b
3547                 </td>
3548                 <td>
3549                   3
3550                 </td>
3551                 <td align="left">
3552                   the subsequent index.
3553                 </td>
3554               </tr>
3555             </table></dd></dl>
3556             The class <code>C1</code> will have the same field indices.
3557             <p/>
3558             An instance of class <code>C2</code> will have the
3559             following field indices:
3560             <dl><dd><table>
3561               <tr>
3562                 <td>
3563                   a
3564                 </td>
3565                 <td>
3566                   3
3567                 </td>
3568                 <td align="left">
3569                   The count of the fields in the interfaces
3570                   implemented by <code>C2</code> is three (<i>n</i>=3):
3571                   <code>p</code> of <code>I0</code>,
3572                   <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> 
3573                   (an interface of <code>C2</code>).  Note that the field <code>p</code>
3574                   of <code>I0</code> is only included once.
3575                 </td>
3576               </tr>
3577               <tr>
3578                 <td>
3579                   b
3580                 </td>
3581                 <td>
3582                   4
3583                 </td>
3584                 <td align="left">
3585                   the subsequent index to "a".
3586                 </td>
3587               </tr>
3588               <tr>
3589                 <td>
3590                   q
3591                 </td>
3592                 <td>
3593                   5
3594                 </td>
3595                 <td align="left">
3596                   the subsequent index to "b".
3597                 </td>
3598               </tr>
3599               <tr>
3600                 <td>
3601                   r
3602                 </td>
3603                 <td>
3604                   6
3605                 </td>
3606                 <td align="left">
3607                   the subsequent index to "q".
3608                 </td>
3609               </tr>
3610             </table></dd></dl>
3611             The class <code>C2</code> will have the same field indices.
3612             Note that a field may have a different index depending on the
3613             object that is viewing it -- for example field "a" above.
3614             Note also: not all field indices may be visible from the 
3615             callbacks, but all indices are shown for illustrative purposes.
3616             <p/>
3617             The interface <code>I1</code> will have the
3618             following field indices:
3619             <dl><dd><table>
3620               <tr>
3621                 <td>
3622                   x
3623                 </td>
3624                 <td>
3625                   1
3626                 </td>
3627                 <td align="left">
3628                   The count of the fields in the superinterfaces
3629                   of <code>I1</code> is one (<i>n</i>=1):
3630                   <code>p</code> of <code>I0</code>.
3631                 </td>
3632               </tr>
3633             </table></dd></dl>
3634           </description>      
3635         </field>
3636       </typedef>
3637 
3638       <typedef id="jvmtiHeapReferenceInfoArray" 
3639                label="Reference information structure for Array references" 
3640                since="1.1">
3641         <description>
3642           Reference information returned for 
3643          <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3644         </description>
3645         <field id="index">
3646           <jint/>
3647           <description>       
3648             The array index.
3649           </description>
3650         </field>
3651       </typedef>
3652 
3653       <typedef id="jvmtiHeapReferenceInfoConstantPool" 
3654                label="Reference information structure for Constant Pool references" 
3655                since="1.1">
3656         <description>
3657           Reference information returned for 
3658           <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3659         </description>
3660         <field id="index">
3661           <jint/>
3662           <description>       
3663             The index into the constant pool of the class. See the description in 
3664       <vmspec chapter="4.4"/>.
3665           </description>
3666         </field>
3667       </typedef>
3668 
3669       <typedef id="jvmtiHeapReferenceInfoStackLocal" 
3670                label="Reference information structure for Local Variable references" 
3671                since="1.1">
3672         <description>
3673           Reference information returned for 
3674           <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3675         </description>
3676         <field id="thread_tag">
3677           <jlong/>
3678           <description>
3679             The tag of the thread corresponding to this stack, zero if not tagged.
3680           </description>
3681         </field>
3682         <field id="thread_id">
3683           <jlong/>
3684           <description>
3685             The unique thread ID of the thread corresponding to this stack.
3686           </description>
3687         </field>
3688         <field id="depth">
3689           <jint/>
3690           <description>
3691             The depth of the frame. 
3692           </description>
3693         </field>
3694         <field id="method">
3695           <jmethodID/>
3696           <description>
3697             The method executing in this frame.
3698           </description>
3699         </field>
3700         <field id="location">
3701           <jlocation/>
3702           <description>
3703             The currently executing location in this frame.
3704           </description>
3705         </field>
3706         <field id="slot">
3707           <jint/>
3708           <description>
3709             The slot number of the local variable.
3710           </description>
3711         </field>
3712       </typedef>
3713 
3714       <typedef id="jvmtiHeapReferenceInfoJniLocal" 
3715                label="Reference information structure for JNI local references" 
3716                since="1.1">
3717         <description>
3718           Reference information returned for 
3719           <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3720         </description>
3721         <field id="thread_tag">
3722           <jlong/>
3723           <description>
3724             The tag of the thread corresponding to this stack, zero if not tagged.
3725           </description>
3726         </field>
3727         <field id="thread_id">
3728           <jlong/>
3729           <description>
3730             The unique thread ID of the thread corresponding to this stack.
3731           </description>
3732         </field>
3733         <field id="depth">
3734           <jint/>
3735           <description>
3736             The depth of the frame. 
3737           </description>
3738         </field>
3739         <field id="method">
3740           <jmethodID/>
3741           <description>
3742             The method executing in this frame.
3743           </description>
3744         </field>
3745       </typedef>
3746 
3747       <typedef id="jvmtiHeapReferenceInfoReserved" 
3748                label="Reference information structure for Other references" 
3749                since="1.1">
3750         <description>
3751           Reference information returned for other references.
3752         </description>
3753         <field id="reserved1">
3754           <jlong/>
3755           <description>
3756             reserved for future use.
3757           </description>
3758         </field>
3759         <field id="reserved2">
3760           <jlong/>
3761           <description>
3762             reserved for future use.
3763           </description>
3764         </field>
3765         <field id="reserved3">
3766           <jlong/>
3767           <description>
3768             reserved for future use.
3769           </description>
3770         </field>
3771         <field id="reserved4">
3772           <jlong/>
3773           <description>
3774             reserved for future use.
3775           </description>
3776         </field>
3777         <field id="reserved5">
3778           <jlong/>
3779           <description>
3780             reserved for future use.
3781           </description>
3782         </field>
3783         <field id="reserved6">
3784           <jlong/>
3785           <description>
3786             reserved for future use.
3787           </description>
3788         </field>
3789         <field id="reserved7">
3790           <jlong/>
3791           <description>
3792             reserved for future use.
3793           </description>
3794         </field>
3795         <field id="reserved8">
3796           <jlong/>
3797           <description>
3798             reserved for future use.
3799           </description>
3800         </field>
3801       </typedef>
3802 
3803       <uniontypedef id="jvmtiHeapReferenceInfo" 
3804                label="Reference information structure" 
3805                since="1.1">
3806         <description>
3807           The information returned about referrers.
3808           Represented as a union of the various kinds of reference information.
3809         </description>
3810         <field id="field">
3811           <struct>jvmtiHeapReferenceInfoField</struct>
3812           <description>       
3813             The referrer information for 
3814             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> 
3815             and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3816           </description>
3817         </field>
3818         <field id="array">
3819           <struct>jvmtiHeapReferenceInfoArray</struct>
3820           <description>       
3821             The referrer information for 
3822             For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3823           </description>
3824         </field>
3825         <field id="constant_pool">
3826           <struct>jvmtiHeapReferenceInfoConstantPool</struct>
3827           <description>       
3828             The referrer information for 
3829             For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3830           </description>
3831         </field>
3832         <field id="stack_local">
3833           <struct>jvmtiHeapReferenceInfoStackLocal</struct>
3834           <description>       
3835             The referrer information for 
3836             For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3837           </description>
3838         </field>
3839         <field id="jni_local">
3840           <struct>jvmtiHeapReferenceInfoJniLocal</struct>
3841           <description>       
3842             The referrer information for 
3843             For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3844           </description>
3845         </field>
3846         <field id="other">
3847           <struct>jvmtiHeapReferenceInfoReserved</struct>
3848           <description>       
3849             reserved for future use.
3850           </description>
3851         </field>
3852       </uniontypedef>
3853 
3854       <typedef id="jvmtiHeapCallbacks" 
3855                label="Heap callback function structure" 
3856                since="1.1">
3857         <field id="heap_iteration_callback">
3858           <ptrtype>
3859             <struct>jvmtiHeapIterationCallback</struct>
3860           </ptrtype>
3861           <description>
3862             The callback to be called to describe an
3863             object in the heap. Used by the 
3864             <functionlink id="IterateThroughHeap"/> function, ignored by the
3865             <functionlink id="FollowReferences"/> function.
3866           </description>
3867         </field>            
3868         <field id="heap_reference_callback">
3869           <ptrtype>
3870             <struct>jvmtiHeapReferenceCallback</struct>
3871           </ptrtype>
3872           <description>
3873             The callback to be called to describe an
3874             object reference.  Used by the 
3875             <functionlink id="FollowReferences"/> function, ignored by the
3876             <functionlink id="IterateThroughHeap"/> function.
3877           </description>
3878         </field>            
3879         <field id="primitive_field_callback">
3880           <ptrtype>
3881             <struct>jvmtiPrimitiveFieldCallback</struct>
3882           </ptrtype>
3883           <description>
3884             The callback to be called to describe a
3885             primitive field.
3886           </description>
3887         </field>            
3888         <field id="array_primitive_value_callback">
3889           <ptrtype>
3890             <struct>jvmtiArrayPrimitiveValueCallback</struct>
3891           </ptrtype>
3892           <description>
3893             The callback to be called to describe an
3894             array of primitive values.
3895           </description>
3896         </field>            
3897         <field id="string_primitive_value_callback">
3898           <ptrtype>
3899             <struct>jvmtiStringPrimitiveValueCallback</struct>
3900           </ptrtype>
3901           <description>
3902             The callback to be called to describe a String value.
3903           </description>
3904         </field>            
3905         <field id="reserved5">
3906           <ptrtype>
3907             <struct>jvmtiReservedCallback</struct>
3908           </ptrtype>
3909           <description>
3910             Reserved for future use..
3911           </description>
3912         </field>            
3913         <field id="reserved6">
3914           <ptrtype>
3915             <struct>jvmtiReservedCallback</struct>
3916           </ptrtype>
3917           <description>
3918             Reserved for future use..
3919           </description>
3920         </field>            
3921         <field id="reserved7">
3922           <ptrtype>
3923             <struct>jvmtiReservedCallback</struct>
3924           </ptrtype>
3925           <description>
3926             Reserved for future use..
3927           </description>
3928         </field>            
3929         <field id="reserved8">
3930           <ptrtype>
3931             <struct>jvmtiReservedCallback</struct>
3932           </ptrtype>
3933           <description>
3934             Reserved for future use..
3935           </description>
3936         </field>            
3937         <field id="reserved9">
3938           <ptrtype>
3939             <struct>jvmtiReservedCallback</struct>
3940           </ptrtype>
3941           <description>
3942             Reserved for future use..
3943           </description>
3944         </field>            
3945         <field id="reserved10">
3946           <ptrtype>
3947             <struct>jvmtiReservedCallback</struct>
3948           </ptrtype>
3949           <description>
3950             Reserved for future use..
3951           </description>
3952         </field>            
3953         <field id="reserved11">
3954           <ptrtype>
3955             <struct>jvmtiReservedCallback</struct>
3956           </ptrtype>
3957           <description>
3958             Reserved for future use..
3959           </description>
3960         </field>            
3961         <field id="reserved12">
3962           <ptrtype>
3963             <struct>jvmtiReservedCallback</struct>
3964           </ptrtype>
3965           <description>
3966             Reserved for future use..
3967           </description>
3968         </field>            
3969         <field id="reserved13">
3970           <ptrtype>
3971             <struct>jvmtiReservedCallback</struct>
3972           </ptrtype>
3973           <description>
3974             Reserved for future use..
3975           </description>
3976         </field>            
3977         <field id="reserved14">
3978           <ptrtype>
3979             <struct>jvmtiReservedCallback</struct>
3980           </ptrtype>
3981           <description>
3982             Reserved for future use..
3983           </description>
3984         </field>            
3985         <field id="reserved15">
3986           <ptrtype>
3987             <struct>jvmtiReservedCallback</struct>
3988           </ptrtype>
3989           <description>
3990             Reserved for future use..
3991           </description>
3992         </field>            
3993       </typedef>
3994 
3995 
3996     <intro>
3997       <rationale>
3998         The heap dumping functionality (below) uses a callback
3999         for each object.  While it would seem that a buffered approach
4000         would provide better throughput, tests do
4001         not show this to be the case--possibly due to locality of
4002         memory reference or array access overhead.
4003       </rationale>
4004 
4005       <issue>
4006         Still under investigation as to if java.lang.ref references
4007         are reported as a different type of reference.
4008       </issue>
4009 
4010       <issue>
4011         Should or can an indication of the cost or relative cost of
4012         these operations be included?
4013       </issue>
4014 
4015     </intro>
4016 
4017     <callback id="jvmtiHeapIterationCallback" since="1.1">
4018       <jint/>
4019       <synopsis>Heap Iteration Callback</synopsis>
4020       <description>
4021         Agent supplied callback function.
4022         Describes (but does not pass in) an object in the heap.
4023         <p/>
4024         This function should return a bit vector of the desired
4025         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4026         This will determine if the entire iteration should be aborted
4027         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4028         <p/>
4029         See the <internallink id="heapCallbacks">heap callback
4030         function restrictions</internallink>.
4031       </description>
4032       <parameters>
4033         <param id="class_tag">
4034           <jlong/>
4035           <description>
4036             The tag of the class of object (zero if the class is not tagged). 
4037             If the object represents a runtime class, 
4038             the <code>class_tag</code> is the tag 
4039             associated with <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 object (in bytes). See <functionlink id="GetObjectSize"/>.
4047           </description>
4048         </param>
4049         <param id="tag_ptr">
4050           <outptr><jlong/></outptr>
4051           <description>
4052             The object tag value, or zero if the object is not tagged.
4053             To set the tag value to be associated with the object
4054             the agent sets the <code>jlong</code> pointed to by the parameter. 
4055           </description>
4056         </param>
4057         <param id="length">
4058           <jint/>
4059           <description>
4060             If this object is an array, the length of the array. Otherwise negative one (-1).
4061           </description>
4062         </param>
4063         <param id="user_data">
4064           <outptr><void/></outptr>
4065           <description>
4066             The user supplied data that was passed into the iteration function. 
4067           </description>
4068         </param>
4069       </parameters>
4070     </callback>  
4071 
4072     <callback id="jvmtiHeapReferenceCallback" since="1.1">
4073       <jint/>
4074       <synopsis>Heap Reference Callback</synopsis>
4075       <description>
4076         Agent supplied callback function.       
4077         Describes a reference from an object or the VM (the referrer) to another object
4078         (the referree) or a heap root to a referree.
4079         <p/>
4080         This function should return a bit vector of the desired
4081         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4082         This will determine if the objects referenced by the referree
4083         should be visited or if the entire iteration should be aborted.
4084         <p/>
4085         See the <internallink id="heapCallbacks">heap callback
4086         function restrictions</internallink>.
4087       </description>
4088       <parameters>
4089         <param id="reference_kind">
4090           <enum>jvmtiHeapReferenceKind</enum>
4091           <description>
4092             The kind of reference.
4093           </description>
4094         </param>
4095         <param id="reference_info">
4096           <inptr>
4097             <struct>jvmtiHeapReferenceInfo</struct>
4098           </inptr>
4099           <description>
4100             Details about the reference. 
4101             Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is
4102             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
4103             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
4104             <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
4105             <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, 
4106             <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
4107             or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
4108             Otherwise <code>NULL</code>.
4109           </description>
4110         </param>
4111         <param id="class_tag">
4112           <jlong/>
4113           <description>
4114             The tag of the class of referree object (zero if the class is not tagged). 
4115             If the referree object represents a runtime class, 
4116             the <code>class_tag</code> is the tag 
4117             associated with <code>java.lang.Class</code>
4118             (zero if <code>java.lang.Class</code> is not tagged).
4119           </description>
4120         </param>
4121         <param id="referrer_class_tag">
4122           <jlong/>
4123           <description>
4124             The tag of the class of the referrer object (zero if the class is not tagged
4125             or the referree is a heap root). If the referrer object represents a runtime
4126             class, the <code>referrer_class_tag</code> is the tag associated with
4127             the <code>java.lang.Class</code>
4128             (zero if <code>java.lang.Class</code> is not tagged).
4129           </description>
4130         </param>
4131         <param id="size">
4132           <jlong/>
4133           <description>
4134             Size of the referree object (in bytes). 
4135             See <functionlink id="GetObjectSize"/>.
4136           </description>
4137         </param>
4138         <param id="tag_ptr">
4139           <outptr><jlong/></outptr>
4140           <description>
4141             Points to the referree object tag value, or zero if the object is not 
4142             tagged.
4143             To set the tag value to be associated with the object
4144             the agent sets the <code>jlong</code> pointed to by the parameter.
4145           </description>
4146         </param>
4147         <param id="referrer_tag_ptr">
4148           <outptr><jlong/></outptr>
4149           <description>
4150             Points to the tag of the referrer object, or 
4151             points to the zero if the referrer
4152             object is not tagged. 
4153             <code>NULL</code> if the referrer in not an object (that is,
4154             this callback is reporting a heap root).
4155             To set the tag value to be associated with the referrer object
4156             the agent sets the <code>jlong</code> pointed to by the parameter.
4157             If this callback is reporting a reference from an object to itself, 
4158             <code>referrer_tag_ptr == tag_ptr</code>.
4159           </description>
4160         </param>
4161         <param id="length">
4162           <jint/>
4163           <description>
4164             If this object is an array, the length of the array. Otherwise negative one (-1).
4165           </description>
4166         </param>
4167         <param id="user_data">
4168           <outptr><void/></outptr>
4169           <description>
4170             The user supplied data that was passed into the iteration function. 
4171           </description>
4172         </param>
4173       </parameters>
4174     </callback>
4175 
4176     <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
4177       <jint/>
4178       <synopsis>Primitive Field Callback</synopsis>
4179       <description>
4180         Agent supplied callback function which  
4181         describes a primitive field of an object (<i>the object</i>).
4182         A primitive field is a field whose type is a primitive type.
4183         This callback will describe a static field if the object is a class,
4184         and otherwise will describe an instance field.
4185         <p/>
4186         This function should return a bit vector of the desired
4187         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4188         This will determine if the entire iteration should be aborted
4189         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4190         <p/>
4191         See the <internallink id="heapCallbacks">heap callback
4192         function restrictions</internallink>.
4193       </description>
4194       <parameters>
4195         <param id="kind">
4196           <enum>jvmtiHeapReferenceKind</enum>
4197           <description>
4198             The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or 
4199             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
4200           </description>
4201         </param>
4202         <param id="info">
4203           <inptr>
4204             <struct>jvmtiHeapReferenceInfo</struct>
4205           </inptr>
4206           <description>
4207             Which field (the field index).
4208           </description>
4209         </param>
4210         <param id="object_class_tag">
4211           <jlong/>
4212           <description>
4213             The tag of the class of the object (zero if the class is not tagged). 
4214             If the object represents a runtime class, the 
4215             <code>object_class_tag</code> is the tag 
4216             associated with <code>java.lang.Class</code> 
4217             (zero if <code>java.lang.Class</code> is not tagged).
4218           </description>
4219         </param>
4220         <param id="object_tag_ptr">
4221           <outptr><jlong/></outptr>
4222           <description>
4223             Points to the tag of the object, or zero if the object is not 
4224             tagged.
4225             To set the tag value to be associated with the object
4226             the agent sets the <code>jlong</code> pointed to by the parameter.
4227           </description>
4228         </param>
4229         <param id="value">
4230           <jvalue/>
4231           <description>
4232             The value of the field.
4233           </description>
4234         </param>
4235         <param id="value_type">
4236           <enum>jvmtiPrimitiveType</enum>
4237           <description>
4238             The type of the field.
4239           </description>
4240         </param>
4241         <param id="user_data">
4242           <outptr><void/></outptr>
4243           <description>
4244             The user supplied data that was passed into the iteration function. 
4245           </description>
4246         </param>
4247       </parameters>
4248     </callback>
4249 
4250     <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
4251       <jint/>
4252       <synopsis>Array Primitive Value Callback</synopsis>
4253       <description>
4254         Agent supplied callback function.       
4255         Describes the values in an array of a primitive type.
4256         <p/>
4257         This function should return a bit vector of the desired
4258         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4259         This will determine if the entire iteration should be aborted
4260         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4261         <p/>
4262         See the <internallink id="heapCallbacks">heap callback
4263         function restrictions</internallink>.
4264       </description>
4265       <parameters>
4266         <param id="class_tag">
4267           <jlong/>
4268           <description>
4269             The tag of the class of the array object (zero if the class is not tagged). 
4270           </description>
4271         </param>
4272         <param id="size">
4273           <jlong/>
4274           <description>
4275             Size of the array (in bytes). 
4276             See <functionlink id="GetObjectSize"/>.
4277           </description>
4278         </param>
4279         <param id="tag_ptr">
4280           <outptr><jlong/></outptr>
4281           <description>
4282             Points to the tag of the array object, or zero if the object is not 
4283             tagged.
4284             To set the tag value to be associated with the object
4285             the agent sets the <code>jlong</code> pointed to by the parameter.
4286           </description>
4287         </param>
4288         <param id="element_count">
4289           <jint/>
4290           <description>
4291             The length of the primitive array.
4292           </description>
4293         </param>
4294         <param id="element_type">
4295           <enum>jvmtiPrimitiveType</enum>
4296           <description>
4297             The type of the elements of the array.
4298           </description>
4299         </param>
4300         <param id="elements">
4301           <vmbuf><void/></vmbuf>
4302           <description>
4303             The elements of the array in a packed array of <code>element_count</code>
4304             items of <code>element_type</code> size each.
4305           </description>
4306         </param>
4307         <param id="user_data">
4308           <outptr><void/></outptr>
4309           <description>
4310             The user supplied data that was passed into the iteration function. 
4311           </description>
4312         </param>
4313       </parameters>
4314     </callback>
4315 
4316     <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
4317       <jint/>
4318       <synopsis>String Primitive Value Callback</synopsis>
4319       <description>
4320         Agent supplied callback function.       
4321         Describes the value of a java.lang.String.
4322         <p/>
4323         This function should return a bit vector of the desired
4324         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4325         This will determine if the entire iteration should be aborted
4326         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4327         <p/>
4328         See the <internallink id="heapCallbacks">heap callback
4329         function restrictions</internallink>.
4330       </description>
4331       <parameters>
4332         <param id="class_tag">
4333           <jlong/>
4334           <description>
4335             The tag of the class of the String class (zero if the class is not tagged). 
4336             <issue>Is this needed?</issue>
4337           </description>
4338         </param>
4339         <param id="size">
4340           <jlong/>
4341           <description>
4342             Size of the string (in bytes). 
4343             See <functionlink id="GetObjectSize"/>.
4344           </description>
4345         </param>
4346         <param id="tag_ptr">
4347           <outptr><jlong/></outptr>
4348           <description>
4349             Points to the tag of the String object, or zero if the object is not 
4350             tagged.
4351             To set the tag value to be associated with the object
4352             the agent sets the <code>jlong</code> pointed to by the parameter.
4353           </description>
4354         </param>
4355         <param id="value">
4356           <vmbuf><jchar/></vmbuf>
4357           <description>
4358             The value of the String, encoded as a Unicode string.
4359           </description>
4360         </param>
4361         <param id="value_length">
4362           <jint/>
4363           <description>
4364             The length of the string. 
4365             The length is equal to the number of 16-bit Unicode 
4366             characters in the string.
4367           </description>
4368         </param>
4369         <param id="user_data">
4370           <outptr><void/></outptr>
4371           <description>
4372             The user supplied data that was passed into the iteration function. 
4373           </description>
4374         </param>
4375       </parameters>
4376     </callback>
4377 
4378 
4379     <callback id="jvmtiReservedCallback" since="1.1">
4380       <jint/>
4381       <synopsis>reserved for future use Callback</synopsis>
4382       <description>
4383         Placeholder -- reserved for future use.
4384       </description>
4385       <parameters>
4386       </parameters>
4387     </callback>
4388 
4389     <function id="FollowReferences" num="115" since="1.1">
4390       <synopsis>Follow References</synopsis>
4391       <description>       
4392         This function initiates a traversal over the objects that are 
4393         directly and indirectly reachable from the specified object or,
4394         if <code>initial_object</code> is not specified, all objects 
4395         reachable from the heap roots.
4396         The heap root are the set of system classes, 
4397         JNI globals, references from thread stacks, and other objects used as roots 
4398         for the purposes of garbage collection. 
4399         <p/>
4400         This function operates by traversing the reference graph.
4401         Let <i>A</i>, <i>B</i>, ... represent objects.
4402         When a reference from <i>A</i> to <i>B</i> is traversed,
4403         when a reference from a heap root to <i>B</i> is traversed, 
4404         or when <i>B</i> is specified as the <paramlink id="initial_object"/>, 
4405         then <i>B</i> is said to be <i>visited</i>.
4406         A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> 
4407         is visited.
4408         References are reported in the same order that the references are traversed.
4409         Object references are reported by invoking the agent supplied  
4410         callback function <functionlink id="jvmtiHeapReferenceCallback"/>.
4411         In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known 
4412         as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
4413         The callback is invoked exactly once for each reference from a referrer;
4414         this is true even if there are reference cycles or multiple paths to
4415         the referrer.
4416         There may be more than one reference between a referrer and a referree,
4417         each reference is reported.
4418         These references may be distinguished by examining the
4419         <datalink 
4420          id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
4421          and
4422         <datalink 
4423          id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
4424         parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
4425         <p/>
4426         This function reports a Java programming language view of object references,
4427         not a virtual machine implementation view. The following object references
4428         are reported when they are non-null:
4429         <ul>
4430           <li>Instance objects report references to each non-primitive instance fields
4431               (including inherited fields).</li>
4432           <li>Instance objects report a reference to the object type (class).</li>
4433           <li>Classes report a reference to the superclass and directly
4434               implemented/extended interfaces.</li>
4435           <li>Classes report a reference to the class loader, protection domain,
4436               signers, and resolved entries in the constant pool.</li>
4437           <li>Classes report a reference to each directly declared non-primitive
4438               static field.</li>
4439           <li>Arrays report a reference to the array type (class) and each
4440               array element.</li>
4441           <li>Primitive arrays report a reference to the array type.</li>
4442         </ul>
4443         <p/>
4444         This function can also be used to examine primitive (non-object) values.
4445         The primitive value of an array or String
4446         is reported after the object has been visited;
4447         it is reported by invoking the agent supplied callback function
4448         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4449         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4450         A primitive field
4451         is reported after the object with that field is visited;
4452         it is reported by invoking the agent supplied callback function
4453         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4454         <p/>
4455         Whether a callback is provided or is <code>NULL</code> only determines
4456         whether the callback will be invoked, it does not influence
4457         which objects are visited nor does it influence whether other callbacks
4458         will be invoked.
4459         However, the 
4460         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
4461         returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4462         do determine if the objects referenced by the 
4463         current object as visited.
4464         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4465         and <paramlink id="klass"/> provided as parameters to this function
4466         do not control which objects are visited but they do control which
4467         objects and primitive values are reported by the callbacks.
4468         For example, if the only callback that was set is
4469         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4470         is set to the array of bytes class, then only arrays of byte will be
4471         reported.  
4472         The table below summarizes this:
4473         <p/>
4474         <table>
4475           <tr>
4476             <th/>
4477             <th>
4478               Controls objects visited
4479             </th>
4480             <th>
4481               Controls objects reported
4482             </th>
4483             <th>
4484               Controls primitives reported
4485             </th>
4486           </tr>
4487           <tr>
4488             <th align="left">
4489               the
4490               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4491               returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4492             </th>
4493             <td>
4494               <b>Yes</b>
4495             </td>
4496             <td>
4497               <b>Yes</b>, since visits are controlled
4498             </td>
4499             <td>
4500               <b>Yes</b>, since visits are controlled
4501             </td>
4502           </tr>
4503           <tr>
4504             <th align="left">
4505               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4506               in <paramlink id="callbacks"/> set
4507             </th>
4508             <td>
4509               No
4510             </td>
4511             <td>
4512               <b>Yes</b>
4513             </td>
4514             <td>
4515               No
4516             </td>
4517           </tr>
4518           <tr>
4519             <th align="left">
4520               <paramlink id="heap_filter"/>
4521             </th>
4522             <td>
4523               No
4524             </td>
4525             <td>
4526               <b>Yes</b>
4527             </td>
4528             <td>
4529               <b>Yes</b>
4530             </td>
4531           </tr>
4532           <tr>
4533             <th align="left">
4534               <paramlink id="klass"/>
4535             </th>
4536             <td>
4537               No
4538             </td>
4539             <td>
4540               <b>Yes</b>
4541             </td>
4542             <td>
4543               <b>Yes</b>
4544             </td>
4545           </tr>
4546         </table>
4547         <p/>
4548         During the execution of this function the state of the heap
4549         does not change: no objects are allocated, no objects are
4550         garbage collected, and the state of objects (including 
4551         held values) does not change. 
4552         As a result, threads executing Java 
4553         programming language code, threads attempting to resume the
4554         execution of Java programming language code, and threads 
4555         attempting to execute JNI functions are typically stalled.
4556       </description>
4557       <origin>new</origin>
4558       <capabilities>
4559         <required id="can_tag_objects"></required>
4560       </capabilities>
4561       <parameters>             
4562         <param id="heap_filter">
4563           <jint/>
4564           <description>
4565             This bit vector of 
4566             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4567             restricts the objects for which the callback function is called.
4568             This applies to both the object and primitive callbacks.
4569           </description>
4570         </param>
4571         <param id="klass">
4572           <ptrtype>
4573             <jclass/>
4574             <nullok>callbacks are not limited to instances of a particular
4575                     class</nullok>
4576           </ptrtype>
4577           <description>
4578             Callbacks are only reported when the object is an instance of 
4579             this class.
4580             Objects which are instances of a subclass of <code>klass</code>
4581             are not reported.
4582             If <code>klass</code> is an interface, no objects are reported.
4583             This applies to both the object and primitive callbacks.
4584           </description>
4585         </param>
4586         <param id="initial_object">
4587           <ptrtype>
4588             <jobject/>
4589             <nullok>references are followed from the heap roots</nullok>
4590           </ptrtype>
4591           <description>
4592             The object to follow
4593           </description>
4594         </param>
4595         <param id="callbacks">
4596           <inptr>
4597             <struct>jvmtiHeapCallbacks</struct>
4598           </inptr>
4599           <description>
4600             Structure defining the set of callback functions.
4601           </description>
4602         </param>                  
4603         <param id="user_data">
4604           <inbuf>
4605             <void/>
4606             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4607           </inbuf>
4608           <description>
4609             User supplied data to be passed to the callback. 
4610           </description>
4611         </param>
4612       </parameters>
4613       <errors>
4614         <error id="JVMTI_ERROR_INVALID_CLASS">
4615           <paramlink id="klass"/> is not a valid class.
4616         </error>
4617         <error id="JVMTI_ERROR_INVALID_OBJECT">
4618           <paramlink id="initial_object"/> is not a valid object.
4619         </error>
4620       </errors>
4621     </function>
4622 
4623 
4624     <function id="IterateThroughHeap" num="116" since="1.1">
4625       <synopsis>Iterate Through Heap</synopsis>
4626       <description>        
4627         Initiate an iteration over all objects in the heap. 
4628         This includes both reachable and 
4629         unreachable objects. Objects are visited in no particular order.
4630         <p/>
4631         Heap objects are reported by invoking the agent supplied 
4632         callback function <functionlink id="jvmtiHeapIterationCallback"/>.
4633         References between objects are not reported.
4634         If only reachable objects are desired, or if object reference information
4635         is needed, use <functionlink id="FollowReferences"/>.
4636         <p/>
4637         This function can also be used to examine primitive (non-object) values.
4638         The primitive value of an array or String
4639         is reported after the object has been visited;
4640         it is reported by invoking the agent supplied callback function
4641         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4642         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4643         A primitive field
4644         is reported after the object with that field is visited;
4645         it is reported by invoking the agent supplied 
4646         callback function
4647         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4648         <p/>
4649         Unless the iteration is aborted by the
4650         <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4651         returned by a callback, all objects in the heap are visited.
4652         Whether a callback is provided or is <code>NULL</code> only determines
4653         whether the callback will be invoked, it does not influence
4654         which objects are visited nor does it influence whether other callbacks
4655         will be invoked.
4656         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4657         and <paramlink id="klass"/> provided as parameters to this function
4658         do not control which objects are visited but they do control which
4659         objects and primitive values are reported by the callbacks.
4660         For example, if the only callback that was set is
4661         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4662         is set to the array of bytes class, then only arrays of byte will be
4663         reported. The table below summarizes this (contrast this with 
4664         <functionlink id="FollowReferences"/>):
4665         <p/>
4666         <table>
4667           <tr>
4668             <th/>
4669             <th>
4670               Controls objects visited
4671             </th>
4672             <th>
4673               Controls objects reported
4674             </th>
4675             <th>
4676               Controls primitives reported
4677             </th>
4678           </tr>
4679           <tr>
4680             <th align="left">
4681               the
4682               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4683               returned by <functionlink id="jvmtiHeapIterationCallback"/>
4684             </th>
4685             <td>
4686               No<br/>(unless they abort the iteration)
4687             </td>
4688             <td>
4689               No<br/>(unless they abort the iteration)
4690             </td>
4691             <td>
4692               No<br/>(unless they abort the iteration)
4693             </td>
4694           </tr>
4695           <tr>
4696             <th align="left">
4697               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4698               in <paramlink id="callbacks"/> set
4699             </th>
4700             <td>
4701               No
4702             </td>
4703             <td>
4704               <b>Yes</b>
4705             </td>
4706             <td>
4707               No
4708             </td>
4709           </tr>
4710           <tr>
4711             <th align="left">
4712               <paramlink id="heap_filter"/>
4713             </th>
4714             <td>
4715               No
4716             </td>
4717             <td>
4718               <b>Yes</b>
4719             </td>
4720             <td>
4721               <b>Yes</b>
4722             </td>
4723           </tr>
4724           <tr>
4725             <th align="left">
4726               <paramlink id="klass"/>
4727             </th>
4728             <td>
4729               No
4730             </td>
4731             <td>
4732               <b>Yes</b>
4733             </td>
4734             <td>
4735               <b>Yes</b>
4736             </td>
4737           </tr>
4738         </table>
4739         <p/>
4740         During the execution of this function the state of the heap
4741         does not change: no objects are allocated, no objects are
4742         garbage collected, and the state of objects (including 
4743         held values) does not change. 
4744         As a result, threads executing Java 
4745         programming language code, threads attempting to resume the
4746         execution of Java programming language code, and threads 
4747         attempting to execute JNI functions are typically stalled.
4748       </description>
4749       <origin>new</origin>
4750       <capabilities>
4751         <required id="can_tag_objects"></required>
4752       </capabilities>
4753       <parameters>
4754         <param id="heap_filter">
4755           <jint/>
4756           <description>
4757             This bit vector of 
4758             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4759             restricts the objects for which the callback function is called.
4760             This applies to both the object and primitive callbacks.
4761           </description>
4762         </param>
4763         <param id="klass">
4764           <ptrtype>
4765             <jclass/>
4766             <nullok>callbacks are not limited to instances of a particular class</nullok>
4767           </ptrtype>
4768           <description>
4769             Callbacks are only reported when the object is an instance of 
4770             this class.
4771             Objects which are instances of a subclass of <code>klass</code>
4772             are not reported.
4773             If <code>klass</code> is an interface, no objects are reported.
4774             This applies to both the object and primitive callbacks.
4775           </description>
4776         </param>
4777         <param id="callbacks">
4778           <inptr>
4779             <struct>jvmtiHeapCallbacks</struct>
4780           </inptr>
4781           <description>
4782             Structure defining the set callback functions.
4783           </description>
4784         </param>                  
4785         <param id="user_data">
4786           <inbuf>
4787             <void/>
4788             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4789           </inbuf>
4790           <description>
4791             User supplied data to be passed to the callback. 
4792           </description>
4793         </param>
4794       </parameters>
4795       <errors>
4796         <error id="JVMTI_ERROR_INVALID_CLASS">
4797           <paramlink id="klass"/> is not a valid class.
4798         </error>
4799       </errors>
4800     </function>
4801 
4802     <function id="GetTag" phase="start" num="106">
4803       <synopsis>Get Tag</synopsis>
4804       <description>
4805         Retrieve the tag associated with an object.
4806         The tag is a long value typically used to store a 
4807         unique identifier or pointer to object information.
4808         The tag is set with
4809         <functionlink id="SetTag"></functionlink>.
4810         Objects for which no tags have been set return a
4811         tag value of zero.
4812       </description>
4813       <origin>new</origin>
4814       <capabilities>
4815         <required id="can_tag_objects"></required>
4816       </capabilities>
4817       <parameters>
4818         <param id="object">
4819           <jobject/>
4820             <description>
4821               The object whose tag is to be retrieved.
4822             </description>
4823         </param>
4824         <param id="tag_ptr">
4825           <outptr><jlong/></outptr>
4826           <description>
4827             On return, the referenced long is set to the value 
4828             of the tag.
4829           </description>
4830         </param>
4831       </parameters>
4832       <errors>
4833       </errors>
4834     </function>
4835 
4836     <function id="SetTag" phase="start" num="107">
4837       <synopsis>Set Tag</synopsis>
4838       <description>
4839         Set the tag associated with an object.
4840         The tag is a long value typically used to store a 
4841         unique identifier or pointer to object information.
4842         The tag is visible with
4843         <functionlink id="GetTag"></functionlink>.
4844       </description>
4845       <origin>new</origin>
4846       <capabilities>
4847         <required id="can_tag_objects"></required>
4848       </capabilities>
4849       <parameters>
4850         <param id="object">
4851           <jobject/>
4852             <description>
4853               The object whose tag is to be set.
4854             </description>
4855         </param>
4856         <param id="tag">
4857           <jlong/>
4858           <description>
4859             The new value of the tag.
4860           </description>
4861         </param>
4862       </parameters>
4863       <errors>
4864       </errors>
4865     </function>
4866 
4867     <function id="GetObjectsWithTags" num="114">
4868       <synopsis>Get Objects With Tags</synopsis>
4869       <description>
4870         Return objects in the heap with the specified tags.
4871         The format is parallel arrays of objects and tags.
4872       </description>
4873       <origin>new</origin>
4874       <capabilities>
4875         <required id="can_tag_objects"></required>
4876       </capabilities>
4877       <parameters>
4878         <param id="tag_count">
4879           <jint min="0"/>
4880             <description>
4881               Number of tags to scan for.
4882             </description>
4883         </param>
4884         <param id="tags">
4885           <inbuf incount="tag_count">
4886             <jlong/>
4887           </inbuf>
4888             <description>
4889               Scan for objects with these tags.
4890               Zero is not permitted in this array.
4891             </description>
4892         </param>
4893         <param id="count_ptr">
4894           <outptr>
4895             <jint/>
4896           </outptr>
4897             <description>
4898               Return the number of objects with any of the tags 
4899               in <paramlink id="tags"/>.
4900             </description>
4901         </param>
4902         <param id="object_result_ptr">
4903           <allocbuf outcount="count_ptr">
4904             <jobject/>
4905             <nullok>this information is not returned</nullok>
4906           </allocbuf>
4907             <description>
4908               Returns the array of objects with any of the tags 
4909               in <paramlink id="tags"/>.
4910             </description>
4911         </param>
4912         <param id="tag_result_ptr">
4913           <allocbuf outcount="count_ptr">
4914             <jlong/>
4915             <nullok>this information is not returned</nullok>
4916           </allocbuf>
4917             <description>
4918               For each object in <paramlink id="object_result_ptr"/>,
4919               return the tag at the corresponding index.
4920             </description>
4921         </param>
4922       </parameters>
4923       <errors>
4924         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
4925           Zero is present in <paramlink id="tags"></paramlink>.
4926         </error>
4927       </errors>
4928     </function>
4929 
4930     <function id="ForceGarbageCollection" num="108">
4931       <synopsis>Force Garbage Collection</synopsis>
4932       <description>
4933         Force the VM to perform a garbage collection.
4934         The garbage collection is as complete as possible.
4935         This function does not cause finalizers to be run.
4936         This function does not return until the garbage collection
4937         is finished.
4938         <p/>
4939         Although garbage collection is as complete 
4940         as possible there is no guarantee that all 
4941         <eventlink id="ObjectFree"/>
4942         events will have been 
4943         sent by the time that this function 
4944         returns. In particular, an object may be 
4945         prevented from being freed because it 
4946         is awaiting finalization.
4947       </description>
4948       <origin>new</origin>
4949       <capabilities>
4950       </capabilities>
4951       <parameters>
4952       </parameters>
4953       <errors>
4954       </errors>
4955     </function>
4956 
4957 
4958   </category>
4959 
4960   <category id="Heap_1_0" label="Heap (1.0)">
4961     <intro>
4962       <b>
4963         These functions and data types were introduced in the original 
4964         <jvmti/> version 1.0 and have been superseded by more
4965       </b>
4966       <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
4967       <b>
4968         which:
4969       </b>
4970       <ul>
4971         <li>
4972           <b>
4973             Allow access to primitive values (the value of Strings, arrays, 
4974             and primitive fields)
4975           </b>
4976         </li>
4977         <li>
4978           <b>
4979             Allow the tag of the referrer to be set, thus enabling more
4980             efficient localized reference graph building
4981           </b>
4982         </li>
4983         <li>
4984           <b>
4985             Provide more extensive filtering abilities
4986           </b>
4987         </li>
4988         <li>
4989           <b>
4990             Are extensible, allowing their abilities to grow in future versions of <jvmti/>
4991           </b>
4992         </li>
4993       </ul>
4994       <p/>
4995       <b>Please use the </b>
4996       <internallink id="Heap"><b>current Heap functions</b></internallink>.
4997         <p/>
4998         <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
4999           <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
5000             Tagged objects only.
5001           </constant>
5002           <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
5003             Untagged objects only.
5004           </constant>
5005           <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
5006             Either tagged or untagged objects.
5007           </constant>
5008         </constants>
5009 
5010         <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
5011           <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
5012             JNI global reference.
5013           </constant>
5014           <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
5015             System class.
5016           </constant>
5017           <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
5018             Monitor.
5019           </constant>
5020           <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
5021             Stack local.
5022           </constant>
5023           <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
5024             JNI local reference.
5025           </constant>
5026           <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
5027             Thread.
5028           </constant>
5029           <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
5030             Other.
5031           </constant>
5032         </constants>
5033 
5034         <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
5035           <constant id="JVMTI_REFERENCE_CLASS" num="1">
5036             Reference from an object to its class.
5037           </constant>       
5038           <constant id="JVMTI_REFERENCE_FIELD" num="2">
5039             Reference from an object to the value of one of its instance fields.
5040             For references of this kind the <code>referrer_index</code>
5041             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5042             jvmtiObjectReferenceCallback</internallink> is the index of the
5043             the instance field. The index is based on the order of all the 
5044             object's fields. This includes all fields of the directly declared
5045             static and instance fields in the class, and includes all fields (both
5046             public and private) fields declared in superclasses and superinterfaces.
5047             The index is thus calculated by summing the index of the field in the directly
5048             declared class (see <functionlink id="GetClassFields"/>), with the total
5049             number of fields (both public and private) declared in all superclasses
5050             and superinterfaces. The index starts at zero.
5051           </constant>
5052           <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
5053             Reference from an array to one of its elements.
5054             For references of this kind the <code>referrer_index</code>
5055             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5056             jvmtiObjectReferenceCallback</internallink> is the array index.
5057           </constant>
5058           <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
5059             Reference from a class to its class loader.
5060           </constant>
5061           <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
5062             Reference from a class to its signers array.
5063           </constant>
5064           <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
5065             Reference from a class to its protection domain.
5066           </constant>       
5067           <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
5068             Reference from a class to one of its interfaces.
5069           </constant>
5070           <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
5071             Reference from a class to the value of one of its static fields.
5072             For references of this kind the <code>referrer_index</code>
5073             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5074             jvmtiObjectReferenceCallback</internallink> is the index of the
5075             the static field. The index is based on the order of all the 
5076             object's fields. This includes all fields of the directly declared
5077             static and instance fields in the class, and includes all fields (both
5078             public and private) fields declared in superclasses and superinterfaces.
5079             The index is thus calculated by summing the index of the field in the directly
5080             declared class (see <functionlink id="GetClassFields"/>), with the total
5081             number of fields (both public and private) declared in all superclasses
5082             and superinterfaces. The index starts at zero.
5083             Note: this definition differs from that in the <jvmti/> 1.0 Specification.
5084             <rationale>No known implementations used the 1.0 definition.</rationale>
5085           </constant>
5086           <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
5087             Reference from a class to a resolved entry in the constant pool.
5088             For references of this kind the <code>referrer_index</code>
5089             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5090             jvmtiObjectReferenceCallback</internallink> is the index into
5091             constant pool table of the class, starting at 1. See
5092             <vmspec chapter="4.4"/>.
5093           </constant>
5094         </constants>
5095 
5096         <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
5097           <constant id="JVMTI_ITERATION_CONTINUE" num="1">
5098             Continue the iteration.  
5099             If this is a reference iteration, follow the references of this object.
5100           </constant>       
5101           <constant id="JVMTI_ITERATION_IGNORE" num="2">
5102             Continue the iteration.  
5103             If this is a reference iteration, ignore the references of this object.
5104           </constant>
5105           <constant id="JVMTI_ITERATION_ABORT" num="0">
5106             Abort the iteration.
5107           </constant>
5108         </constants>
5109     </intro>
5110 
5111     <callback id="jvmtiHeapObjectCallback">
5112       <enum>jvmtiIterationControl</enum>
5113       <synopsis>Heap Object Callback</synopsis>
5114       <description>
5115         Agent supplied callback function.
5116         Describes (but does not pass in) an object in the heap.
5117         <p/>
5118         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5119         or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5120         <p/>
5121         See the <internallink id="heapCallbacks">heap callback
5122         function restrictions</internallink>.
5123       </description>
5124       <parameters>
5125         <param id="class_tag">
5126           <jlong/>
5127           <description>
5128             The tag of the class of object (zero if the class is not tagged). 
5129             If the object represents a runtime class, 
5130             the <code>class_tag</code> is the tag 
5131             associated with <code>java.lang.Class</code>
5132             (zero if <code>java.lang.Class</code> is not tagged).
5133           </description>
5134         </param>
5135         <param id="size">
5136           <jlong/>
5137           <description>
5138             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5139           </description>
5140         </param>
5141         <param id="tag_ptr">
5142           <outptr><jlong/></outptr>
5143           <description>
5144             The object tag value, or zero if the object is not tagged.
5145             To set the tag value to be associated with the object
5146             the agent sets the <code>jlong</code> pointed to by the parameter. 
5147           </description>
5148         </param>
5149         <param id="user_data">
5150           <outptr><void/></outptr>
5151           <description>
5152             The user supplied data that was passed into the iteration function. 
5153           </description>
5154         </param>
5155       </parameters>
5156     </callback>  
5157 
5158     <callback id="jvmtiHeapRootCallback">
5159       <enum>jvmtiIterationControl</enum>
5160       <synopsis>Heap Root Object Callback</synopsis>
5161       <description>
5162         Agent supplied callback function.
5163         Describes (but does not pass in) an object that is a root for the purposes
5164         of garbage collection.
5165         <p/>
5166         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5167         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5168         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5169         <p/>
5170         See the <internallink id="heapCallbacks">heap callback
5171         function restrictions</internallink>.
5172       </description>
5173       <parameters>
5174         <param id="root_kind">
5175           <enum>jvmtiHeapRootKind</enum>
5176           <description>
5177             The kind of heap root.
5178           </description>
5179         </param>
5180         <param id="class_tag">
5181           <jlong/>
5182           <description>
5183             The tag of the class of object (zero if the class is not tagged). 
5184             If the object represents a runtime class, the <code>class_tag</code> is the tag 
5185             associated with <code>java.lang.Class</code> 
5186             (zero if <code>java.lang.Class</code> is not tagged).
5187           </description>
5188         </param>
5189         <param id="size">
5190           <jlong/>
5191           <description>
5192             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5193           </description>
5194         </param>
5195         <param id="tag_ptr">
5196           <outptr><jlong/></outptr>
5197           <description>
5198             The object tag value, or zero if the object is not tagged.
5199             To set the tag value to be associated with the object
5200             the agent sets the <code>jlong</code> pointed to by the parameter.
5201           </description>
5202         </param>
5203         <param id="user_data">
5204           <outptr><void/></outptr>
5205           <description>
5206             The user supplied data that was passed into the iteration function. 
5207           </description>
5208         </param>
5209       </parameters>
5210     </callback> 
5211 
5212     <callback id="jvmtiStackReferenceCallback">
5213       <enum>jvmtiIterationControl</enum>
5214       <synopsis>Stack Reference Object Callback</synopsis>
5215       <description>
5216         Agent supplied callback function.
5217         Describes (but does not pass in) an object on the stack that is a root for 
5218         the purposes of garbage collection.
5219         <p/>
5220         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5221         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5222         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5223         <p/>
5224         See the <internallink id="heapCallbacks">heap callback
5225         function restrictions</internallink>.
5226       </description>
5227       <parameters>
5228         <param id="root_kind">
5229           <enum>jvmtiHeapRootKind</enum>
5230           <description>
5231             The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5232             <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
5233           </description>
5234         </param>
5235         <param id="class_tag">
5236           <jlong/>
5237           <description>
5238            The tag of the class of object (zero if the class is not tagged). 
5239            If the object represents a runtime class, the  <code>class_tag</code> is the tag 
5240            associated with <code>java.lang.Class</code> 
5241            (zero if <code>java.lang.Class</code> is not tagged).
5242           </description>
5243         </param>
5244         <param id="size">
5245           <jlong/>
5246           <description>
5247             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5248           </description>
5249         </param>
5250         <param id="tag_ptr">
5251           <outptr><jlong/></outptr>
5252           <description>
5253             The object tag value, or zero if the object is not tagged.
5254             To set the tag value to be associated with the object
5255             the agent sets the <code>jlong</code> pointed to by the parameter.
5256           </description>
5257         </param>
5258         <param id="thread_tag">
5259           <jlong/>
5260           <description>
5261             The tag of the thread corresponding to this stack, zero if not tagged.
5262           </description>
5263         </param>
5264         <param id="depth">
5265           <jint/>
5266           <description>
5267             The depth of the frame. 
5268           </description>
5269         </param>
5270         <param id="method">
5271           <jmethodID/>
5272           <description>
5273             The method executing in this frame.
5274           </description>
5275         </param>
5276         <param id="slot">
5277           <jint/>
5278           <description>
5279             The slot number.
5280           </description>
5281         </param>
5282         <param id="user_data">
5283           <outptr><void/></outptr>
5284           <description>
5285             The user supplied data that was passed into the iteration function. 
5286           </description>
5287         </param>
5288       </parameters>
5289     </callback>
5290 
5291     <callback id="jvmtiObjectReferenceCallback">
5292       <enum>jvmtiIterationControl</enum>
5293       <synopsis>Object Reference Callback</synopsis>
5294       <description>
5295         Agent supplied callback function.       
5296         Describes a reference from an object (the referrer) to another object
5297         (the referree).
5298         <p/>
5299         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5300         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5301         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5302         <p/>
5303         See the <internallink id="heapCallbacks">heap callback
5304         function restrictions</internallink>.
5305       </description>
5306       <parameters>
5307         <param id="reference_kind">
5308           <enum>jvmtiObjectReferenceKind</enum>
5309           <description>
5310             The type of reference.
5311           </description>
5312         </param>
5313         <param id="class_tag">
5314           <jlong/>
5315           <description>
5316             The tag of the class of referree object (zero if the class is not tagged). 
5317             If the referree object represents a runtime class,
5318             the  <code>class_tag</code> is the tag 
5319             associated with <code>java.lang.Class</code> 
5320             (zero if <code>java.lang.Class</code> is not tagged).
5321           </description>
5322         </param>
5323         <param id="size">
5324           <jlong/>
5325           <description>
5326             Size of the referree object (in bytes). 
5327             See <functionlink id="GetObjectSize"/>.
5328           </description>
5329         </param>
5330         <param id="tag_ptr">
5331           <outptr><jlong/></outptr>
5332           <description>
5333             The referree object tag value, or zero if the object is not 
5334             tagged.
5335             To set the tag value to be associated with the object
5336             the agent sets the <code>jlong</code> pointed to by the parameter.
5337           </description>
5338         </param>
5339         <param id="referrer_tag">
5340           <jlong/>
5341           <description>
5342             The tag of the referrer object, or zero if the referrer
5343             object is not tagged.
5344           </description>
5345         </param>
5346         <param id="referrer_index">
5347           <jint/>
5348           <description>       
5349             For references of type <code>JVMTI_REFERENCE_FIELD</code> or
5350             <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
5351             of the field in the referrer object. The index is based on the 
5352             order of all the object's fields - see <internallink 
5353             id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
5354             or <internallink
5355             id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
5356             </internallink> for further description.
5357             <p/>
5358             For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
5359             the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
5360             JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
5361             <p/>
5362             For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
5363             the index into the constant pool of the class - see
5364             <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
5365             JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further 
5366             description.
5367             <p/>
5368             For references of other kinds the <code>referrer_index</code> is
5369             <code>-1</code>.
5370           </description>
5371         </param>
5372         <param id="user_data">
5373           <outptr><void/></outptr>
5374           <description>
5375             The user supplied data that was passed into the iteration function. 
5376           </description>
5377         </param>
5378       </parameters>
5379     </callback>
5380 
5381     <function id="IterateOverObjectsReachableFromObject" num="109">
5382       <synopsis>Iterate Over Objects Reachable From Object</synopsis>
5383       <description>       
5384         This function iterates over all objects that are directly
5385         and indirectly reachable from the specified object.
5386         For each object <i>A</i> (known
5387         as the referrer) with a reference to object <i>B</i> the specified 
5388         callback function is called to describe the object reference.
5389         The callback is called exactly once for each reference from a referrer;
5390         this is true even if there are reference cycles or multiple paths to
5391         the referrer.
5392         There may be more than one reference between a referrer and a referree,
5393         These may be distinguished by the 
5394         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5395         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5396         The callback for an object will always occur after the callback for
5397         its referrer.
5398         <p/>
5399         See <functionlink id="FollowReferences"/> for the object
5400         references which are reported.
5401         <p/>
5402         During the execution of this function the state of the heap
5403         does not change: no objects are allocated, no objects are
5404         garbage collected, and the state of objects (including 
5405         held values) does not change. 
5406         As a result, threads executing Java 
5407         programming language code, threads attempting to resume the
5408         execution of Java programming language code, and threads 
5409         attempting to execute JNI functions are typically stalled.
5410       </description>
5411       <origin>new</origin>
5412       <capabilities>
5413         <required id="can_tag_objects"></required>
5414       </capabilities>
5415       <parameters>             
5416         <param id="object">
5417           <jobject/>
5418             <description>
5419               The object
5420             </description>
5421         </param>
5422         <param id="object_reference_callback">
5423           <ptrtype>
5424             <struct>jvmtiObjectReferenceCallback</struct>
5425           </ptrtype>
5426             <description>
5427               The callback to be called to describe each
5428               object reference.
5429             </description>
5430         </param>            
5431         <param id="user_data">
5432           <inbuf>
5433             <void/>
5434             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5435           </inbuf>
5436           <description>
5437             User supplied data to be passed to the callback. 
5438           </description>
5439         </param>
5440       </parameters>
5441       <errors>
5442       </errors>
5443     </function>
5444 
5445     <function id="IterateOverReachableObjects" num="110">
5446       <synopsis>Iterate Over Reachable Objects</synopsis>
5447       <description>
5448         This function iterates over the root objects and all objects that
5449         are directly and indirectly reachable from the root objects.
5450         The root objects comprise the set of system classes, 
5451         JNI globals, references from thread stacks, and other objects used as roots 
5452         for the purposes of garbage collection. 
5453         <p/>
5454         For each root the <paramlink id="heap_root_callback"></paramlink>
5455         or <paramlink id="stack_ref_callback"></paramlink> callback is called.
5456         An object can be a root object for more than one reason and in that case
5457         the appropriate callback is called for each reason.
5458         <p/>
5459         For each object reference the <paramlink id="object_ref_callback"></paramlink>
5460         callback function is called to describe the object reference.
5461         The callback is called exactly once for each reference from a referrer;
5462         this is true even if there are reference cycles or multiple paths to
5463         the referrer.
5464         There may be more than one reference between a referrer and a referree,
5465         These may be distinguished by the 
5466         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5467         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5468         The callback for an object will always occur after the callback for
5469         its referrer.
5470         <p/>
5471         See <functionlink id="FollowReferences"/> for the object
5472         references which are reported.
5473         <p/>
5474         Roots are always reported to the profiler before any object references
5475         are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> 
5476         callback will not be called until the appropriate callback has been called
5477         for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is 
5478         specified as <code>NULL</code> then this function returns after
5479         reporting the root objects to the profiler.
5480         <p/>
5481         During the execution of this function the state of the heap
5482         does not change: no objects are allocated, no objects are
5483         garbage collected, and the state of objects (including 
5484         held values) does not change. 
5485         As a result, threads executing Java 
5486         programming language code, threads attempting to resume the
5487         execution of Java programming language code, and threads 
5488         attempting to execute JNI functions are typically stalled.
5489       </description>
5490       <origin>new</origin>
5491       <capabilities>
5492         <required id="can_tag_objects"></required>
5493       </capabilities>
5494       <parameters>        
5495         <param id="heap_root_callback">
5496           <ptrtype>
5497             <struct>jvmtiHeapRootCallback</struct>
5498             <nullok>do not report heap roots</nullok>
5499           </ptrtype>
5500             <description>
5501               The callback function to be called for each heap root of type
5502               <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
5503               <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
5504               <code>JVMTI_HEAP_ROOT_MONITOR</code>,
5505               <code>JVMTI_HEAP_ROOT_THREAD</code>, or 
5506               <code>JVMTI_HEAP_ROOT_OTHER</code>.
5507             </description>
5508         </param>
5509         <param id="stack_ref_callback">
5510           <ptrtype>
5511             <struct>jvmtiStackReferenceCallback</struct>
5512             <nullok>do not report stack references</nullok>
5513           </ptrtype>
5514             <description>
5515               The callback function to be called for each heap root of
5516               <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5517               <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
5518             </description>
5519         </param>
5520         <param id="object_ref_callback">
5521           <ptrtype>
5522             <struct>jvmtiObjectReferenceCallback</struct>
5523             <nullok>do not follow references from the root objects</nullok>
5524           </ptrtype>
5525             <description>
5526               The callback function to be called for each object reference.
5527             </description>
5528         </param>
5529         <param id="user_data">
5530           <inbuf>
5531             <void/>
5532             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5533           </inbuf>
5534           <description>
5535             User supplied data to be passed to the callback. 
5536           </description>
5537         </param>
5538       </parameters>
5539       <errors>
5540       </errors>
5541     </function>
5542 
5543     <function id="IterateOverHeap" num="111">
5544       <synopsis>Iterate Over Heap</synopsis>
5545       <description>        
5546         Iterate over all objects in the heap. This includes both reachable and 
5547         unreachable objects.
5548         <p/>
5549         The <paramlink id="object_filter"></paramlink> parameter indicates the
5550         objects for which the callback function is called. If this parameter
5551         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 
5552         called for every object that is tagged. If the parameter is 
5553         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5554         for objects that are not tagged. If the parameter
5555         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5556         called for every object in the heap, irrespective of whether it is
5557         tagged or not.
5558         <p/>
5559         During the execution of this function the state of the heap
5560         does not change: no objects are allocated, no objects are
5561         garbage collected, and the state of objects (including 
5562         held values) does not change. 
5563         As a result, threads executing Java 
5564         programming language code, threads attempting to resume the
5565         execution of Java programming language code, and threads 
5566         attempting to execute JNI functions are typically stalled.
5567       </description>
5568       <origin>new</origin>
5569       <capabilities>
5570         <required id="can_tag_objects"></required>
5571       </capabilities>
5572       <parameters>
5573         <param id="object_filter">
5574           <enum>jvmtiHeapObjectFilter</enum>
5575           <description>
5576             Indicates the objects for which the callback function is called.
5577           </description>
5578         </param>
5579         <param id="heap_object_callback">
5580           <ptrtype>
5581             <struct>jvmtiHeapObjectCallback</struct>
5582           </ptrtype>
5583             <description>
5584               The iterator function to be called for each
5585               object matching the <paramlink id="object_filter"/>.
5586             </description>
5587         </param>
5588         <param id="user_data">
5589           <inbuf>
5590             <void/>
5591             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5592           </inbuf>
5593           <description>
5594             User supplied data to be passed to the callback. 
5595           </description>
5596         </param>
5597       </parameters>
5598       <errors>
5599       </errors>
5600     </function>
5601 
5602     <function id="IterateOverInstancesOfClass" num="112">
5603       <synopsis>Iterate Over Instances Of Class</synopsis>
5604       <description>
5605         Iterate over all objects in the heap that are instances of the specified class. 
5606         This includes direct instances of the specified class and 
5607         instances of all subclasses of the specified class.
5608         This includes both reachable and unreachable objects.
5609         <p/>
5610         The <paramlink id="object_filter"></paramlink> parameter indicates the
5611         objects for which the callback function is called. If this parameter
5612         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 
5613         called for every object that is tagged. If the parameter is 
5614         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5615         called for objects that are not tagged. If the parameter
5616         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5617         called for every object in the heap, irrespective of whether it is
5618         tagged or not.
5619         <p/>
5620         During the execution of this function the state of the heap
5621         does not change: no objects are allocated, no objects are
5622         garbage collected, and the state of objects (including 
5623         held values) does not change. 
5624         As a result, threads executing Java 
5625         programming language code, threads attempting to resume the
5626         execution of Java programming language code, and threads 
5627         attempting to execute JNI functions are typically stalled.
5628       </description>
5629       <origin>new</origin>
5630       <capabilities>
5631         <required id="can_tag_objects"></required>
5632       </capabilities>
5633       <parameters>
5634         <param id="klass">
5635           <jclass/>
5636             <description>
5637               Iterate over objects of this class only.
5638             </description>
5639         </param>
5640         <param id="object_filter">
5641           <enum>jvmtiHeapObjectFilter</enum>
5642           <description>
5643             Indicates the objects for which the callback function is called.
5644           </description>
5645         </param>
5646         <param id="heap_object_callback">
5647           <ptrtype>
5648             <struct>jvmtiHeapObjectCallback</struct>
5649           </ptrtype>
5650             <description>
5651               The iterator function to be called for each
5652               <paramlink id="klass"/> instance matching 
5653               the <paramlink id="object_filter"/>.
5654             </description>
5655         </param>
5656         <param id="user_data">
5657           <inbuf>
5658             <void/>
5659             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5660           </inbuf>
5661           <description>
5662             User supplied data to be passed to the callback. 
5663           </description>
5664         </param>
5665       </parameters>
5666       <errors>
5667       </errors>
5668     </function>
5669 
5670   </category>
5671 
5672   <category id="local" label="Local Variable">
5673 
5674     <intro>
5675       These functions are used to retrieve or set the value of a local variable. 
5676       The variable is identified by the depth of the frame containing its
5677       value and the variable's slot number within that frame. 
5678       The mapping of variables to 
5679       slot numbers can be obtained with the function 
5680       <functionlink id="GetLocalVariableTable"></functionlink>.
5681     </intro>
5682 
5683     <function id="GetLocalObject" num="21">
5684       <synopsis>Get Local Variable - Object</synopsis>
5685       <description>
5686         This function can be used to retrieve the value of a local 
5687         variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 
5688       </description>
5689       <origin>jvmdi</origin>
5690       <capabilities>
5691         <required id="can_access_local_variables"></required>
5692       </capabilities>
5693       <parameters>
5694         <param id="thread">
5695           <jthread null="current" frame="frame"/>
5696           <description>
5697             The thread of the frame containing the variable's value.
5698           </description>
5699         </param>
5700         <param id="depth">
5701           <jframeID thread="thread"/>
5702           <description>
5703             The depth of the frame containing the variable's value.
5704           </description>
5705         </param>
5706         <param id="slot">
5707           <jint/>
5708           <description>
5709             The variable's slot number.
5710           </description>
5711         </param>
5712         <param id="value_ptr">
5713           <outptr><jobject/></outptr>
5714             <description>
5715               On return, points to the variable's value. 
5716             </description>
5717         </param>
5718       </parameters>
5719       <errors>
5720         <error id="JVMTI_ERROR_INVALID_SLOT">
5721           Invalid <code>slot</code>.
5722         </error>
5723         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5724           The variable type is not
5725           <code>Object</code> or a subclass of <code>Object</code>.
5726         </error>
5727         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5728           Not a visible frame
5729         </error>
5730       </errors>
5731     </function>
5732 
5733     <function id="GetLocalInstance" num="155" since="1.2">
5734       <synopsis>Get Local Instance</synopsis>
5735       <description>
5736         This function can be used to retrieve the value of the local object
5737         variable at slot 0 (the "<code>this</code>" object) from non-static
5738         frames.  This function can retrieve the "<code>this</code>" object from
5739         native method frames, whereas <code>GetLocalObject()</code> would 
5740         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5741       </description>
5742       <origin>new</origin>
5743       <capabilities>
5744         <required id="can_access_local_variables"></required>
5745       </capabilities>
5746       <parameters>
5747         <param id="thread">
5748           <jthread null="current" frame="frame"/>
5749           <description>
5750             The thread of the frame containing the variable's value.
5751           </description>
5752         </param>
5753         <param id="depth">
5754           <jframeID thread="thread"/>
5755           <description>
5756             The depth of the frame containing the variable's value.
5757           </description>
5758         </param>
5759         <param id="value_ptr">
5760           <outptr><jobject/></outptr>
5761             <description>
5762               On return, points to the variable's value. 
5763             </description>
5764         </param>
5765       </parameters>
5766       <errors>
5767         <error id="JVMTI_ERROR_INVALID_SLOT">
5768           If the specified frame is a static method frame.
5769         </error>
5770       </errors>
5771     </function>
5772     <function id="GetLocalInt" num="22">
5773       <synopsis>Get Local Variable - Int</synopsis>
5774       <description>
5775         This function can be used to retrieve the value of a local 
5776         variable whose type is <code>int</code>,
5777         <code>short</code>, <code>char</code>, <code>byte</code>, or 
5778         <code>boolean</code>. 
5779       </description>
5780       <origin>jvmdi</origin>
5781       <capabilities>
5782         <required id="can_access_local_variables"></required>
5783       </capabilities>
5784       <parameters>
5785         <param id="thread">
5786           <jthread null="current" frame="frame"/>
5787           <description>
5788             The thread of the frame containing the variable's value.
5789           </description>
5790         </param>
5791         <param id="depth">
5792           <jframeID thread="thread"/>
5793           <description>
5794             The depth of the frame containing the variable's value.
5795           </description>
5796         </param>
5797         <param id="slot">
5798           <jint/>
5799           <description>
5800             The variable's slot number.
5801           </description>
5802         </param>
5803         <param id="value_ptr">
5804           <outptr><jint/></outptr>
5805           <description>
5806             On return, points to the variable's value. 
5807           </description>
5808         </param>
5809       </parameters>
5810       <errors>
5811         <error id="JVMTI_ERROR_INVALID_SLOT">
5812           Invalid <code>slot</code>.
5813         </error>
5814         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5815           The variable type is not 
5816           <code>int</code>, <code>short</code>,
5817           <code>char</code>, <code>byte</code>, or 
5818           <code>boolean</code>.
5819         </error>
5820         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5821           Not a visible frame
5822         </error>
5823       </errors>
5824     </function>
5825 
5826     <function id="GetLocalLong" num="23">
5827       <synopsis>Get Local Variable - Long</synopsis>
5828       <description>
5829         This function can be used to retrieve the value of a local 
5830         variable whose type is <code>long</code>. 
5831       </description>
5832       <origin>jvmdi</origin>
5833       <capabilities>
5834         <required id="can_access_local_variables"></required>
5835       </capabilities>
5836       <parameters>
5837         <param id="thread">
5838           <jthread null="current" frame="frame"/>
5839           <description>
5840             The thread of the frame containing the variable's value.
5841           </description>
5842         </param>
5843         <param id="depth">
5844           <jframeID thread="thread"/>
5845           <description>
5846             The depth of the frame containing the variable's value.
5847           </description>
5848         </param>
5849         <param id="slot">
5850           <jint/>
5851           <description>
5852             The variable's slot number.
5853           </description>
5854         </param>
5855         <param id="value_ptr">
5856           <outptr><jlong/></outptr>
5857           <description>
5858             On return, points to the variable's value. 
5859           </description>
5860         </param>
5861       </parameters>
5862       <errors>
5863         <error id="JVMTI_ERROR_INVALID_SLOT">
5864           Invalid <code>slot</code>.
5865         </error>
5866         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5867           The variable type is not <code>long</code>.
5868         </error>
5869         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5870           Not a visible frame
5871         </error>
5872       </errors>
5873     </function>
5874 
5875     <function id="GetLocalFloat" num="24">
5876       <synopsis>Get Local Variable - Float</synopsis>
5877       <description>
5878         This function can be used to retrieve the value of a local 
5879         variable whose type is <code>float</code>. 
5880       </description>
5881       <origin>jvmdi</origin>
5882       <capabilities>
5883         <required id="can_access_local_variables"></required>
5884       </capabilities>
5885       <parameters>
5886         <param id="thread">
5887           <jthread null="current" frame="frame"/>
5888           <description>
5889             The thread of the frame containing the variable's value.
5890           </description>
5891         </param>
5892         <param id="depth">
5893           <jframeID thread="thread"/>
5894           <description>
5895             The depth of the frame containing the variable's value.
5896           </description>
5897         </param>
5898         <param id="slot">
5899           <jint/>
5900           <description>
5901             The variable's slot number.
5902           </description>
5903         </param>
5904         <param id="value_ptr">
5905           <outptr><jfloat/></outptr>
5906           <description>
5907             On return, points to the variable's value. 
5908           </description>
5909         </param>
5910       </parameters>
5911       <errors>
5912         <error id="JVMTI_ERROR_INVALID_SLOT">
5913           Invalid <code>slot</code>.
5914         </error>
5915         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5916           The variable type is not <code>float</code>.
5917         </error>
5918         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5919           Not a visible frame
5920         </error>
5921       </errors>
5922     </function>
5923 
5924     <function id="GetLocalDouble" num="25">
5925       <synopsis>Get Local Variable - Double</synopsis>
5926       <description>
5927         This function can be used to retrieve the value of a local 
5928         variable whose type is <code>long</code>. 
5929       </description>
5930       <origin>jvmdi</origin>
5931       <capabilities>
5932         <required id="can_access_local_variables"></required>
5933       </capabilities>
5934       <parameters>
5935         <param id="thread">
5936           <jthread null="current" frame="frame"/>
5937           <description>
5938             The thread of the frame containing the variable's value.
5939           </description>
5940         </param>
5941         <param id="depth">
5942           <jframeID thread="thread"/>
5943           <description>
5944             The depth of the frame containing the variable's value.
5945           </description>
5946         </param>
5947         <param id="slot">
5948           <jint/>
5949           <description>
5950             The variable's slot number.
5951           </description>
5952         </param>
5953         <param id="value_ptr">
5954           <outptr><jdouble/></outptr>
5955           <description>
5956             On return, points to the variable's value. 
5957           </description>
5958         </param>
5959       </parameters>
5960       <errors>
5961         <error id="JVMTI_ERROR_INVALID_SLOT">
5962           Invalid <code>slot</code>.
5963         </error>
5964         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5965           The variable type is not <code>double</code>.
5966         </error>
5967         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5968           Not a visible frame
5969         </error>
5970       </errors>
5971     </function>
5972 
5973     <function id="SetLocalObject" num="26">
5974       <synopsis>Set Local Variable - Object</synopsis>
5975       <description>
5976         This function can be used to set the value of a local 
5977         variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 
5978       </description>
5979       <origin>jvmdi</origin>
5980       <capabilities>
5981         <required id="can_access_local_variables"></required>
5982       </capabilities>
5983       <parameters>
5984         <param id="thread">
5985           <jthread null="current" frame="frame"/>
5986           <description>
5987             The thread of the frame containing the variable's value.
5988           </description>
5989         </param>
5990         <param id="depth">
5991           <jframeID thread="thread"/>
5992           <description>
5993             The depth of the frame containing the variable's value.
5994           </description>
5995         </param>
5996         <param id="slot">
5997           <jint/>
5998           <description>
5999             The variable's slot number.
6000           </description>
6001         </param>
6002         <param id="value">
6003           <jobject/>
6004             <description>
6005               The new value for the variable.
6006             </description>
6007         </param>
6008       </parameters>
6009       <errors>
6010         <error id="JVMTI_ERROR_INVALID_SLOT">
6011           Invalid <code>slot</code>.
6012         </error>
6013         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6014           The variable type is not
6015           <code>Object</code> or a subclass of <code>Object</code>.
6016         </error>
6017         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6018           The supplied <paramlink id="value"/> is not compatible 
6019           with the variable type.
6020         </error>
6021         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6022           Not a visible frame
6023         </error>
6024       </errors>
6025     </function>
6026 
6027     <function id="SetLocalInt" num="27">
6028       <synopsis>Set Local Variable - Int</synopsis>
6029       <description>
6030         This function can be used to set the value of a local 
6031         variable whose type is <code>int</code>,
6032         <code>short</code>, <code>char</code>, <code>byte</code>, or 
6033         <code>boolean</code>. 
6034       </description>
6035       <origin>jvmdi</origin>
6036       <capabilities>
6037         <required id="can_access_local_variables"></required>
6038       </capabilities>
6039       <parameters>
6040         <param id="thread">
6041           <jthread null="current" frame="frame"/>
6042           <description>
6043             The thread of the frame containing the variable's value.
6044           </description>
6045         </param>
6046         <param id="depth">
6047           <jframeID thread="thread"/>
6048           <description>
6049             The depth of the frame containing the variable's value.
6050           </description>
6051         </param>
6052         <param id="slot">
6053           <jint/>
6054           <description>
6055             The variable's slot number.
6056           </description>
6057         </param>
6058         <param id="value">
6059           <jint/>
6060           <description>
6061             The new value for the variable.
6062           </description>
6063         </param>
6064       </parameters>
6065       <errors>
6066         <error id="JVMTI_ERROR_INVALID_SLOT">
6067           Invalid <code>slot</code>.
6068         </error>
6069         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6070           The variable type is not 
6071           <code>int</code>, <code>short</code>,
6072           <code>char</code>, <code>byte</code>, or 
6073           <code>boolean</code>.
6074         </error>
6075         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6076           Not a visible frame
6077         </error>
6078       </errors>
6079     </function>
6080 
6081     <function id="SetLocalLong" num="28">
6082       <synopsis>Set Local Variable - Long</synopsis>
6083       <description>
6084         This function can be used to set the value of a local 
6085         variable whose type is <code>long</code>. 
6086       </description>
6087       <origin>jvmdi</origin>
6088       <capabilities>
6089         <required id="can_access_local_variables"></required>
6090       </capabilities>
6091       <parameters>
6092         <param id="thread">
6093           <jthread null="current" frame="frame"/>
6094           <description>
6095             The thread of the frame containing the variable's value.
6096           </description>
6097         </param>
6098         <param id="depth">
6099           <jframeID thread="thread"/>
6100           <description>
6101             The depth of the frame containing the variable's value.
6102           </description>
6103         </param>
6104         <param id="slot">
6105           <jint/>
6106           <description>
6107             The variable's slot number.
6108           </description>
6109         </param>
6110         <param id="value">
6111           <jlong/>
6112           <description>
6113             The new value for the variable.
6114           </description>
6115         </param>
6116       </parameters>
6117       <errors>
6118         <error id="JVMTI_ERROR_INVALID_SLOT">
6119           Invalid <code>slot</code>.
6120         </error>
6121         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6122           The variable type is not <code>long</code>.
6123         </error>
6124         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6125           Not a visible frame
6126         </error>
6127       </errors>
6128     </function>
6129 
6130     <function id="SetLocalFloat" num="29">
6131       <synopsis>Set Local Variable - Float</synopsis>
6132       <description>
6133         This function can be used to set the value of a local 
6134         variable whose type is <code>float</code>. 
6135       </description>
6136       <origin>jvmdi</origin>
6137       <capabilities>
6138         <required id="can_access_local_variables"></required>
6139       </capabilities>
6140       <parameters>
6141         <param id="thread">
6142           <jthread null="current" frame="frame"/>
6143           <description>
6144             The thread of the frame containing the variable's value.
6145           </description>
6146         </param>
6147         <param id="depth">
6148           <jframeID thread="thread"/>
6149           <description>
6150             The depth of the frame containing the variable's value.
6151           </description>
6152         </param>
6153         <param id="slot">
6154           <jint/>
6155           <description>
6156             The variable's slot number.
6157           </description>
6158         </param>
6159         <param id="value">
6160           <jfloat/>
6161           <description>
6162             The new value for the variable.
6163           </description>
6164         </param>
6165       </parameters>
6166       <errors>
6167         <error id="JVMTI_ERROR_INVALID_SLOT">
6168           Invalid <code>slot</code>.
6169         </error>
6170         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6171           The variable type is not <code>float</code>.
6172         </error>
6173         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6174           Not a visible frame
6175         </error>
6176       </errors>
6177     </function>
6178 
6179     <function id="SetLocalDouble" num="30">
6180       <synopsis>Set Local Variable - Double</synopsis>
6181       <description>
6182         This function can be used to set the value of a local 
6183         variable whose type is <code>double</code>. 
6184       </description>
6185       <origin>jvmdi</origin>
6186       <capabilities>
6187         <required id="can_access_local_variables"></required>
6188       </capabilities>
6189       <parameters>
6190         <param id="thread">
6191           <jthread null="current" frame="frame"/>
6192           <description>
6193             The thread of the frame containing the variable's value.
6194           </description>
6195         </param>
6196         <param id="depth">
6197           <jframeID thread="thread"/>
6198           <description>
6199             The depth of the frame containing the variable's value.
6200           </description>
6201         </param>
6202         <param id="slot">
6203           <jint/>
6204           <description>
6205             The variable's slot number.
6206           </description>
6207         </param>
6208         <param id="value">
6209           <jdouble/>
6210           <description>
6211             The new value for the variable.
6212           </description>
6213         </param>
6214       </parameters>
6215       <errors>
6216         <error id="JVMTI_ERROR_INVALID_SLOT">
6217           Invalid <code>slot</code>.
6218         </error>
6219         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6220           The variable type is not <code>double</code>.
6221         </error>
6222         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6223           Not a visible frame
6224         </error>
6225       </errors>
6226     </function>
6227   </category>
6228 
6229   <category id="breakpointCategory" label="Breakpoint">
6230 
6231     <intro>
6232     </intro>
6233 
6234     <function id="SetBreakpoint" num="38">
6235       <synopsis>Set Breakpoint</synopsis>
6236       <description>
6237         Set a breakpoint at the instruction indicated by
6238         <code>method</code> and <code>location</code>.
6239         An instruction can only have one breakpoint.
6240         <p/>
6241         Whenever the designated instruction is about to be executed, a
6242         <eventlink id="Breakpoint"></eventlink> event is generated.
6243       </description>
6244       <origin>jvmdi</origin>
6245       <capabilities>
6246         <required id="can_generate_breakpoint_events"></required>
6247       </capabilities>
6248       <parameters>
6249         <param id="klass">
6250           <jclass method="method"/>
6251             <description>
6252               The class in which to set the breakpoint
6253             </description>
6254         </param>
6255         <param id="method">
6256           <jmethodID class="klass"/>
6257             <description>
6258               The method in which to set the breakpoint
6259             </description>
6260         </param>
6261         <param id="location">
6262           <jlocation/>
6263           <description>
6264             the index of the instruction at which to set the breakpoint
6265 
6266           </description>
6267         </param>
6268       </parameters>
6269       <errors>
6270         <error id="JVMTI_ERROR_DUPLICATE"> 
6271           The designated bytecode already has a breakpoint.
6272         </error>
6273       </errors>
6274     </function>
6275 
6276     <function id="ClearBreakpoint" num="39">
6277       <synopsis>Clear Breakpoint</synopsis>
6278       <description>
6279         Clear the breakpoint at the bytecode indicated by
6280         <code>method</code> and <code>location</code>.
6281       </description>
6282       <origin>jvmdi</origin>
6283       <capabilities>
6284         <required id="can_generate_breakpoint_events"></required>
6285       </capabilities>
6286       <parameters>
6287         <param id="klass">
6288           <jclass method="method"/>
6289             <description>
6290               The class in which to clear the breakpoint
6291             </description>
6292         </param>
6293         <param id="method">
6294           <jmethodID class="klass"/>
6295             <description>
6296               The method in which to clear the breakpoint
6297             </description>
6298         </param>
6299         <param id="location">
6300           <jlocation/>
6301           <description>
6302             the index of the instruction at which to clear the breakpoint
6303           </description>
6304         </param>
6305       </parameters>
6306       <errors>
6307         <error id="JVMTI_ERROR_NOT_FOUND"> 
6308           There's no breakpoint at the designated bytecode.
6309         </error>
6310       </errors>
6311     </function>
6312 
6313   </category>
6314 
6315   <category id="fieldWatch" label="Watched Field">
6316 
6317     <intro>
6318     </intro>
6319 
6320     <function id="SetFieldAccessWatch" num="41">
6321       <synopsis>Set Field Access Watch</synopsis>
6322       <description>
6323         Generate a <eventlink id="FieldAccess"></eventlink> event
6324         when the field specified
6325         by <code>klass</code> and
6326         <code>field</code> is about to be accessed.
6327         An event will be generated for each access of the field
6328         until it is canceled with 
6329         <functionlink id="ClearFieldAccessWatch"></functionlink>.
6330         Field accesses from Java programming language code or from JNI code are watched,
6331         fields modified by other means are not watched.
6332         Note that <jvmti/> users should be aware that their own field accesses
6333         will trigger the watch.
6334         A field can only have one field access watch set.
6335         Modification of a field is not considered an access--use 
6336         <functionlink id="SetFieldModificationWatch"></functionlink>
6337         to monitor modifications.
6338       </description>
6339       <origin>jvmdi</origin>
6340       <capabilities>
6341         <required id="can_generate_field_access_events"></required>
6342       </capabilities>
6343       <parameters>
6344         <param id="klass">
6345           <jclass field="field"/>
6346             <description>
6347               The class containing the field to watch
6348             </description>
6349         </param>
6350         <param id="field">
6351           <jfieldID class="klass"/>
6352             <description>
6353               The field to watch
6354 
6355             </description>
6356         </param>
6357       </parameters>
6358       <errors>
6359         <error id="JVMTI_ERROR_DUPLICATE"> 
6360           The designated field is already being watched for accesses.
6361         </error>
6362       </errors>
6363     </function>
6364 
6365     <function id="ClearFieldAccessWatch" num="42">
6366       <synopsis>Clear Field Access Watch</synopsis>
6367       <description>
6368         Cancel a field access watch previously set by 
6369         <functionlink id="SetFieldAccessWatch"></functionlink>, on the 
6370         field specified
6371         by <code>klass</code> and
6372         <code>field</code>.
6373       </description>
6374       <origin>jvmdi</origin>
6375       <capabilities>
6376         <required id="can_generate_field_access_events"></required>
6377       </capabilities>
6378       <parameters>
6379         <param id="klass">
6380           <jclass field="field"/>
6381             <description>
6382               The class containing the field to watch
6383             </description>
6384         </param>
6385         <param id="field">
6386           <jfieldID class="klass"/>
6387             <description>
6388               The field to watch
6389 
6390             </description>
6391         </param>
6392       </parameters>
6393       <errors>
6394         <error id="JVMTI_ERROR_NOT_FOUND"> 
6395           The designated field is not being watched for accesses.
6396         </error>
6397       </errors>
6398     </function>
6399 
6400     <function id="SetFieldModificationWatch" num="43">
6401       <synopsis>Set Field Modification Watch</synopsis>
6402       <description>
6403         Generate a <eventlink id="FieldModification"></eventlink> event
6404         when the field specified
6405         by <code>klass</code> and
6406         <code>field</code> is about to be modified.
6407         An event will be generated for each modification of the field
6408         until it is canceled with 
6409         <functionlink id="ClearFieldModificationWatch"></functionlink>.
6410         Field modifications from Java programming language code or from JNI code are watched,
6411         fields modified by other means are not watched.
6412         Note that <jvmti/> users should be aware that their own field modifications
6413         will trigger the watch.
6414         A field can only have one field modification watch set.
6415       </description>
6416       <origin>jvmdi</origin>
6417       <capabilities>
6418         <required id="can_generate_field_modification_events"></required>
6419       </capabilities>
6420       <parameters>
6421         <param id="klass">
6422           <jclass field="field"/>
6423             <description>
6424               The class containing the field to watch
6425             </description>
6426         </param>
6427         <param id="field">
6428           <jfieldID class="klass"/>
6429             <description>
6430               The field to watch
6431 
6432             </description>
6433         </param>
6434       </parameters>
6435       <errors>
6436         <error id="JVMTI_ERROR_DUPLICATE"> 
6437           The designated field is already being watched for modifications.
6438         </error>
6439       </errors>
6440     </function>
6441 
6442     <function id="ClearFieldModificationWatch" num="44">
6443       <synopsis>Clear Field Modification Watch</synopsis>
6444       <description>
6445 
6446         Cancel a field modification watch previously set by 
6447         <functionlink id="SetFieldModificationWatch"></functionlink>, on the 
6448         field specified
6449         by <code>klass</code> and
6450         <code>field</code>.
6451       </description>
6452       <origin>jvmdi</origin>
6453       <capabilities>
6454         <required id="can_generate_field_modification_events"></required>
6455       </capabilities>
6456       <parameters>
6457         <param id="klass">
6458           <jclass field="field"/>
6459             <description>
6460               The class containing the field to watch
6461             </description>
6462         </param>
6463         <param id="field">
6464           <jfieldID class="klass"/>
6465             <description>
6466               The field to watch
6467 
6468             </description>
6469         </param>
6470       </parameters>
6471       <errors>
6472         <error id="JVMTI_ERROR_NOT_FOUND"> 
6473           The designated field is not being watched for modifications.
6474         </error>
6475       </errors>
6476     </function>
6477   </category>
6478 
6479   <category id="module" label="Module">
6480 
6481     <intro>
6482     </intro>
6483 
6484     <function id="GetAllModules" num="3" since="9">
6485       <synopsis>Get All Modules</synopsis>
6486       <description>
6487         Return an array of all modules loaded in the virtual machine.
6488         The array includes the unnamed module for each class loader.
6489         The number of modules in the array is returned via
6490         <code>module_count_ptr</code>, and the array itself via
6491         <code>modules_ptr</code>.
6492         <p/>
6493       </description>
6494       <origin>new</origin>
6495       <capabilities>
6496       </capabilities>
6497       <parameters>
6498         <param id="module_count_ptr">
6499           <outptr><jint/></outptr>
6500           <description>
6501             On return, points to the number of returned modules.
6502           </description>
6503         </param>
6504         <param id="modules_ptr">
6505           <allocbuf outcount="module_count_ptr"><jobject/></allocbuf>
6506             <description>
6507               On return, points to an array of references, one
6508               for each module.
6509             </description>
6510         </param>
6511       </parameters>
6512       <errors>
6513       </errors>
6514     </function>
6515 
6516     <function id="GetNamedModule" num="40" since="9">
6517       <synopsis>Get Named Module</synopsis>
6518       <description>
6519         Return the <code>java.lang.reflect.Module</code> object for a named
6520         module defined to a class loader that contains a given package.
6521         The module is returned via <code>module_ptr</code>.
6522         <p/>
6523         If a named module is defined to the class loader and it
6524         contains the package then that named module is returned,
6525         otherwise <code>NULL</code> is returned.
6526         <p/>
6527       </description>
6528       <origin>new</origin>
6529       <capabilities>
6530       </capabilities>
6531       <parameters>
6532         <param id="class_loader">
6533           <ptrtype>
6534             <jobject/>
6535             <nullok>the bootstrap loader is assumed</nullok>
6536           </ptrtype>
6537           <description>
6538             A class loader.
6539             If the <code>class_loader</code> is not <code>NULL</code>
6540             or a subclass of <code>java.lang.ClassLoader</code>
6541             this function returns
6542             <errorlink id="JVMTI_ERROR_ILLEGAL_ARGUMENT"></errorlink>.
6543           </description>
6544         </param>
6545         <param id="package_name">
6546           <inbuf><char/></inbuf>
6547           <description>
6548             The name of the package, encoded as a
6549             <internallink id="mUTF">modified UTF-8</internallink> string.
6550             The package name is in internal form (JVMS 4.2.1);
6551             identifiers are separated by forward slashes rather than periods.
6552           </description>
6553         </param>
6554         <param id="module_ptr">
6555           <outptr><jobject/></outptr>
6556           <description>
6557             On return, points to a <code>java.lang.reflect.Module</code> object
6558             or points to <code>NULL</code>.
6559           </description>
6560         </param>
6561       </parameters>
6562       <errors>
6563         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6564           If class loader is not <code>NULL</code> and is not a class loader object.
6565         </error>
6566       </errors>
6567     </function>
6568 
6569     <function id="AddModuleReads" num="94" since="9">
6570       <synopsis>Add Module Reads</synopsis>
6571       <description>
6572          Update a module to read another module. This function is a no-op
6573          when <paramlink id="module"></paramlink> is an unnamed module.
6574          This function facilitates the instrumentation of code
6575          in named modules where that instrumentation requires
6576          expanding the set of modules that a module reads.
6577       </description>
6578       <origin>new</origin>
6579       <capabilities>
6580       </capabilities>
6581       <parameters>
6582         <param id="module">
6583           <ptrtype><jobject/></ptrtype>
6584           <description>
6585             The module to update.
6586           </description>
6587         </param>
6588         <param id="to_module">
6589           <ptrtype><jobject/></ptrtype>
6590           <description>
6591             The additional module to read.
6592           </description>
6593         </param>
6594       </parameters>
6595       <errors>
6596         <error id="JVMTI_ERROR_INVALID_MODULE">
6597           If <paramlink id="module"></paramlink> is not a module object.
6598         </error>
6599         <error id="JVMTI_ERROR_INVALID_MODULE">
6600           If <paramlink id="to_module"></paramlink> is not a module object.
6601         </error>
6602       </errors>
6603     </function>
6604 
6605     <function id="AddModuleExports" num="95" since="9">
6606       <synopsis>Add Module Exports</synopsis>
6607       <description>
6608          Update a module to export a package to another module.
6609          This function is a no-op when <paramlink id="module"></paramlink>
6610          is an unnamed module or an open module.
6611          This function facilitates the instrumentation of code
6612          in named modules where that instrumentation requires
6613          expanding the set of packages that a module exports.
6614       </description>
6615       <origin>new</origin>
6616       <capabilities>
6617       </capabilities>
6618       <parameters>
6619         <param id="module">
6620           <ptrtype><jobject/></ptrtype>
6621           <description>
6622             The module to update.
6623           </description>
6624         </param>
6625         <param id="pkg_name">
6626           <inbuf><char/></inbuf>
6627           <description>
6628             The exported package name.
6629           </description>
6630         </param>
6631         <param id="to_module">
6632           <ptrtype><jobject/></ptrtype>
6633           <description>
6634             The module the package is exported to.
6635             If the <code>to_module</code> is not a subclass of
6636             <code>java.lang.reflect.Module</code> this function returns
6637             <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
6638           </description>
6639         </param>
6640       </parameters>
6641       <errors>
6642         <error id="JVMTI_ERROR_INVALID_MODULE">
6643           If <paramlink id="module"></paramlink> is not a module object.
6644         </error>
6645         <error id="JVMTI_ERROR_INVALID_MODULE">
6646           If <paramlink id="to_modules"></paramlink> is not a module object.
6647         </error>
6648         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6649           If the package <paramlink id="pkg_name"></paramlink>
6650           does not belong to the module.
6651         </error>
6652       </errors>
6653     </function>
6654 
6655     <function id="AddModuleOpens" num="96" since="9">
6656       <synopsis>Add Module Opens</synopsis>
6657       <description>
6658          Update a module to open a package to another module.
6659          This function is a no-op when <paramlink id="module"></paramlink>
6660          is an unnamed module or an open module.
6661          This function facilitates the instrumentation of code
6662          in modules where that instrumentation requires
6663          expanding the set of packages that a module opens to
6664          other modules.
6665       </description>
6666       <origin>new</origin>
6667       <capabilities>
6668       </capabilities>
6669       <parameters>
6670         <param id="module">
6671           <ptrtype><jobject/></ptrtype>
6672           <description>
6673             The module to update.
6674           </description>
6675         </param>
6676         <param id="pkg_name">
6677           <inbuf><char/></inbuf>
6678           <description>
6679             The package name of the package to open.
6680           </description>
6681         </param>
6682         <param id="to_module">
6683           <ptrtype><jobject/></ptrtype>
6684           <description>
6685             The module with the package to open.
6686             If the <code>to_module</code> is not a subclass of
6687             <code>java.lang.reflect.Module</code> this function returns
6688             <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
6689           </description>
6690         </param>
6691       </parameters>
6692       <errors>
6693         <error id="JVMTI_ERROR_INVALID_MODULE">
6694           If <paramlink id="module"></paramlink> is not a module object.
6695         </error>
6696         <error id="JVMTI_ERROR_INVALID_MODULE">
6697           If <paramlink id="to_modules"></paramlink> is not a module object.
6698         </error>
6699         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6700           If the package <paramlink id="pkg_name"></paramlink>
6701           does not belong to the module.
6702         </error>
6703       </errors>
6704     </function>
6705 
6706     <function id="AddModuleUses" num="97" since="9">
6707       <synopsis>Add Module Uses</synopsis>
6708       <description>
6709          Updates a module to add a service to the set of services that
6710          a module uses. This function is a no-op when the module
6711          is an unnamed module.
6712          This function facilitates the instrumentation of code
6713          in named modules where that instrumentation requires
6714          expanding the set of services that a module is using.
6715       </description>
6716       <origin>new</origin>
6717       <capabilities>
6718       </capabilities>
6719       <parameters>
6720         <param id="module">
6721           <ptrtype><jobject/></ptrtype>
6722           <description>
6723             The module to update.
6724           </description>
6725         </param>
6726         <param id="service">
6727           <ptrtype><jclass/></ptrtype>
6728           <description>
6729             The service to use.
6730           </description>
6731         </param>
6732       </parameters>
6733       <errors>
6734         <error id="JVMTI_ERROR_INVALID_MODULE">
6735           If <paramlink id="module"></paramlink> is not a module object.
6736         </error>
6737         <error id="JVMTI_ERROR_INVALID_CLASS">
6738           If <paramlink id="service"></paramlink> is not a class object.
6739         </error>
6740       </errors>
6741     </function>
6742 
6743     <function id="AddModuleProvides" num="98" since="9">
6744       <synopsis>Add Module Provides</synopsis>
6745       <description>
6746          Updates a module to add a service to the set of services that
6747          a module provides. This function is a no-op when the module
6748          is an unnamed module.
6749          This function facilitates the instrumentation of code
6750          in named modules where that instrumentation requires
6751          changes to the services that are provided.
6752       </description>
6753       <origin>new</origin>
6754       <capabilities>
6755       </capabilities>
6756       <parameters>
6757         <param id="module">
6758           <ptrtype><jobject/></ptrtype>
6759           <description>
6760             The module to update.
6761           </description>
6762         </param>
6763         <param id="service">
6764           <ptrtype><jclass/></ptrtype>
6765           <description>
6766             The service to provide.
6767           </description>
6768         </param>
6769         <param id="impl_class">
6770           <ptrtype><jclass/></ptrtype>
6771           <description>
6772             The implementation class for the provided service.
6773           </description>
6774         </param>
6775       </parameters>
6776       <errors>
6777         <error id="JVMTI_ERROR_INVALID_MODULE">
6778           If <paramlink id="module"></paramlink> is not a module object.
6779         </error>
6780         <error id="JVMTI_ERROR_INVALID_CLASS">
6781           If <paramlink id="service"></paramlink> is not a class object.
6782         </error>
6783         <error id="JVMTI_ERROR_INVALID_CLASS">
6784           If <paramlink id="impl_class"></paramlink> is not a class object.
6785         </error>
6786       </errors>
6787     </function>
6788 
6789   </category>
6790 
6791   <category id="class" label="Class">
6792 
6793     <intro>
6794     </intro>
6795 
6796     <function id="GetLoadedClasses" jkernel="yes" num="78">
6797       <synopsis>Get Loaded Classes</synopsis>
6798       <description>
6799         Return an array of all classes loaded in the virtual machine.
6800         The number of classes in the array is returned via
6801         <code>class_count_ptr</code>, and the array itself via
6802         <code>classes_ptr</code>.
6803         <p/>
6804         Array classes of all types (including arrays of primitive types) are 
6805         included in the returned list. Primitive classes (for example, 
6806         <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. 
6807       </description>
6808       <origin>jvmdi</origin>
6809       <capabilities>
6810       </capabilities>
6811       <parameters>
6812         <param id="class_count_ptr">
6813           <outptr><jint/></outptr>
6814           <description>
6815             On return, points to the number of classes.
6816           </description>
6817         </param>
6818         <param id="classes_ptr">
6819           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6820             <description>
6821               On return, points to an array of references, one
6822               for each class.
6823             </description>
6824         </param>
6825       </parameters>
6826       <errors>
6827       </errors>
6828     </function>
6829 
6830     <function id="GetClassLoaderClasses" jkernel="yes" num="79">
6831       <synopsis>Get Classloader Classes</synopsis>
6832       <description>
6833         Returns an array of those classes for which this class loader has
6834         been recorded as an initiating loader. Each 
6835         class in the returned array was created by this class loader, 
6836         either by defining it directly or by delegation to another class loader.
6837         See <vmspec chapter="5.3"/>.
6838         <p/>
6839         The number of classes in the array is returned via
6840         <code>class_count_ptr</code>, and the array itself via
6841         <code>classes_ptr</code>.
6842       </description>
6843       <origin>jvmdi</origin>
6844       <capabilities>
6845       </capabilities>
6846       <parameters>
6847         <param id="initiating_loader">
6848           <ptrtype>
6849             <jobject/>
6850             <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
6851           </ptrtype>
6852             <description>
6853               An initiating class loader.
6854             </description>
6855         </param>
6856         <param id="class_count_ptr">
6857           <outptr><jint/></outptr>
6858           <description>
6859             On return, points to the number of classes.
6860           </description>
6861         </param>
6862         <param id="classes_ptr">
6863           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6864             <description>
6865               On return, points to an array of references, one
6866               for each class.
6867             </description>
6868         </param>
6869       </parameters>
6870       <errors>
6871       </errors>
6872     </function>
6873 
6874     <function id="GetClassSignature" phase="start" num="48">
6875       <synopsis>Get Class Signature</synopsis>
6876       <description>
6877         For the class indicated by <code>klass</code>, return the 
6878         <externallink id="docs/technotes/guides/jni/spec/types.html#type_signatures">JNI 
6879             type signature</externallink> 
6880         and the generic signature of the class.
6881         For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
6882         and <code>int[]</code> is <code>"[I"</code>
6883         The returned name for primitive classes
6884         is the type signature character of the corresponding primitive type. 
6885         For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
6886       </description>
6887       <origin>jvmdiClone</origin>
6888       <capabilities>
6889       </capabilities>
6890       <parameters>
6891         <param id="klass">
6892           <jclass/>
6893             <description>
6894               The class to query.
6895             </description>
6896         </param>
6897         <param id="signature_ptr">
6898           <allocbuf>
6899             <char/>           
6900             <nullok>the signature is not returned</nullok>
6901           </allocbuf>
6902           <description>
6903             On return, points to the JNI type signature of the class, encoded as a
6904             <internallink id="mUTF">modified UTF-8</internallink> string.
6905           </description>
6906         </param>
6907         <param id="generic_ptr">
6908           <allocbuf>
6909             <char/>           
6910             <nullok>the generic signature is not returned</nullok>
6911           </allocbuf>
6912           <description>
6913             On return, points to the generic signature of the class, encoded as a
6914             <internallink id="mUTF">modified UTF-8</internallink> string.
6915             If there is no generic signature attribute for the class, then,
6916             on return, points to <code>NULL</code>. 
6917           </description>
6918         </param>
6919       </parameters>
6920       <errors>
6921       </errors>
6922     </function>
6923 
6924     <function id="GetClassStatus" phase="start" num="49">
6925       <synopsis>Get Class Status</synopsis>
6926       <description>
6927         Get the status of the class. Zero or more of the following bits can be 
6928         set.
6929         <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
6930           <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
6931             Class bytecodes have been verified
6932           </constant>
6933           <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
6934             Class preparation is complete
6935           </constant>
6936           <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
6937             Class initialization is complete. Static initializer has been run.
6938           </constant>
6939           <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
6940             Error during initialization makes class unusable
6941           </constant>
6942           <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
6943             Class is an array.  If set, all other bits are zero.
6944           </constant>
6945           <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
6946             Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).  
6947             If set, all other bits are zero.
6948           </constant>
6949         </constants>
6950       </description>
6951       <origin>jvmdi</origin>
6952       <capabilities>
6953       </capabilities>
6954       <parameters>
6955         <param id="klass">
6956           <jclass/>
6957             <description>
6958               The class to query.
6959             </description>
6960         </param>
6961         <param id="status_ptr">
6962           <outptr><jint/></outptr>
6963           <description>
6964             On return, points to the current state of this class as one or 
6965             more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
6966           </description>
6967         </param>
6968       </parameters>
6969       <errors>
6970       </errors>
6971     </function>
6972 
6973     <function id="GetSourceFileName" phase="start" num="50">
6974       <synopsis>Get Source File Name</synopsis>
6975       <description>
6976         For the class indicated by <code>klass</code>, return the source file
6977         name via <code>source_name_ptr</code>. The returned string 
6978         is a file name only and never contains a directory name. 
6979         <p/>
6980         For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) 
6981         and for arrays this function returns 
6982         <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
6983       </description>
6984       <origin>jvmdi</origin>
6985       <capabilities>
6986         <required id="can_get_source_file_name"></required>
6987       </capabilities>
6988       <parameters>
6989         <param id="klass">
6990           <jclass/>
6991             <description>
6992               The class to query.
6993             </description>
6994         </param>
6995         <param id="source_name_ptr">
6996           <allocbuf><char/></allocbuf>
6997           <description>
6998             On return, points to the class's source file name, encoded as a
6999             <internallink id="mUTF">modified UTF-8</internallink> string.
7000           </description>
7001         </param>
7002       </parameters>
7003       <errors>
7004         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
7005           Class information does not include a source file name. This includes
7006           cases where the class is an array class or primitive class.
7007         </error>
7008       </errors>
7009     </function>
7010 
7011     <function id="GetClassModifiers" phase="start" num="51">
7012       <synopsis>Get Class Modifiers</synopsis>
7013       <description>
7014         For the class indicated by <code>klass</code>, return the access
7015         flags
7016         via <code>modifiers_ptr</code>.
7017         Access flags are defined in <vmspec chapter="4"/>.
7018         <p/>
7019         If the class is an array class, then its public, private, and protected 
7020         modifiers are the same as those of its component type. For arrays of 
7021         primitives, this component type is represented by one of the primitive 
7022         classes (for example, <code>java.lang.Integer.TYPE</code>). 
7023         <p/>
7024         If the class is a primitive class, its public modifier is always true, 
7025         and its protected and private modifiers are always false. 
7026         <p/>
7027         If the class is an array class or a primitive class then its final 
7028         modifier is always true and its interface modifier is always false. 
7029         The values of its other modifiers are not determined by this specification. 
7030 
7031       </description>
7032       <origin>jvmdi</origin>
7033       <capabilities>
7034       </capabilities>
7035       <parameters>
7036         <param id="klass">
7037           <jclass/>
7038             <description>
7039               The class to query.
7040             </description>
7041         </param>
7042         <param id="modifiers_ptr">
7043           <outptr><jint/></outptr>
7044           <description>
7045             On return, points to the current access flags of this class.
7046 
7047           </description>
7048         </param>
7049       </parameters>
7050       <errors>
7051       </errors>
7052     </function>
7053 
7054     <function id="GetClassMethods" phase="start" num="52">
7055       <synopsis>Get Class Methods</synopsis>
7056       <description>
7057         For the class indicated by <code>klass</code>, return a count of
7058         methods via <code>method_count_ptr</code> and a list of
7059         method IDs via <code>methods_ptr</code>. The method list contains 
7060         constructors and static initializers as well as true methods.
7061         Only directly declared methods are returned (not inherited methods).
7062         An empty method list is returned for array classes and primitive classes
7063         (for example, <code>java.lang.Integer.TYPE</code>).
7064       </description>
7065       <origin>jvmdi</origin>
7066       <capabilities>
7067         <capability id="can_maintain_original_method_order"/>
7068       </capabilities>
7069       <parameters>
7070         <param id="klass">
7071           <jclass/>
7072             <description>
7073               The class to query.
7074             </description>
7075         </param>
7076         <param id="method_count_ptr">
7077           <outptr><jint/></outptr>
7078           <description>
7079             On return, points to the number of methods declared in this class.
7080           </description>
7081         </param>
7082         <param id="methods_ptr">
7083           <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
7084             <description>
7085               On return, points to the method ID array.
7086             </description>
7087         </param>
7088       </parameters>
7089       <errors>
7090         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7091           <paramlink id="klass"></paramlink> is not prepared.
7092         </error>
7093       </errors>
7094     </function>
7095 
7096     <function id="GetClassFields" phase="start" num="53">
7097       <synopsis>Get Class Fields</synopsis>
7098       <description>
7099         For the class indicated by <code>klass</code>, return a count of fields
7100         via <code>field_count_ptr</code> and a list of field IDs via
7101         <code>fields_ptr</code>.
7102         Only directly declared fields are returned (not inherited fields).
7103         Fields are returned in the order they occur in the class file.
7104         An empty field list is returned for array classes and primitive classes
7105         (for example, <code>java.lang.Integer.TYPE</code>).
7106         Use JNI to determine the length of an array.
7107       </description>
7108       <origin>jvmdi</origin>
7109       <capabilities>
7110       </capabilities>
7111       <parameters>
7112         <param id="klass">
7113           <jclass/>
7114             <description>
7115               The class to query.
7116             </description>
7117         </param>
7118         <param id="field_count_ptr">
7119           <outptr><jint/></outptr>
7120           <description>
7121             On return, points to the number of fields declared in this class.
7122           </description>
7123         </param>
7124         <param id="fields_ptr">
7125           <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
7126             <description>
7127               On return, points to the field ID array.
7128             </description>
7129         </param>
7130       </parameters>
7131       <errors>
7132         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 
7133           <paramlink id="klass"></paramlink> is not prepared.
7134         </error>
7135       </errors>
7136     </function>
7137 
7138     <function id="GetImplementedInterfaces" phase="start" num="54">
7139       <synopsis>Get Implemented Interfaces</synopsis>
7140       <description>
7141         Return the direct super-interfaces of this class. For a class, this 
7142         function returns the interfaces declared in its <code>implements</code>
7143         clause. For an interface, this function returns the interfaces declared in
7144         its <code>extends</code> clause.
7145         An empty interface list is returned for array classes and primitive classes
7146         (for example, <code>java.lang.Integer.TYPE</code>).
7147       </description>
7148       <origin>jvmdi</origin>
7149       <capabilities>
7150       </capabilities>
7151       <parameters>
7152         <param id="klass">
7153           <jclass/>
7154             <description>
7155               The class to query.
7156             </description>
7157         </param>
7158         <param id="interface_count_ptr">
7159           <outptr><jint/></outptr>
7160           <description>
7161             On return, points to the number of interfaces.
7162           </description>
7163         </param>
7164         <param id="interfaces_ptr">
7165           <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
7166             <description>
7167               On return, points to the interface array.
7168             </description>
7169         </param>
7170       </parameters>
7171       <errors>
7172         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 
7173           <paramlink id="klass"></paramlink> is not prepared.
7174         </error>
7175       </errors>
7176     </function>
7177 
7178     <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
7179       <synopsis>Get Class Version Numbers</synopsis>
7180       <description>
7181         For the class indicated by <code>klass</code>, 
7182         return the minor and major version numbers,
7183         as defined in
7184         <vmspec chapter="4"/>. 
7185       </description>
7186       <origin>new</origin>
7187       <capabilities>
7188       </capabilities>
7189       <parameters>
7190         <param id="klass">
7191           <jclass/>
7192             <description>
7193               The class to query.
7194             </description>
7195         </param>
7196         <param id="minor_version_ptr">
7197           <outptr><jint/></outptr>
7198           <description>
7199             On return, points to the value of the
7200             <code>minor_version</code> item of the 
7201             Class File Format.
7202             Note: to be consistent with the Class File Format,
7203             the minor version number is the first parameter.
7204           </description>
7205         </param>
7206         <param id="major_version_ptr">
7207           <outptr><jint/></outptr>
7208           <description>
7209             On return, points to the value of the
7210             <code>major_version</code> item of the 
7211             Class File Format.
7212           </description>
7213         </param>
7214       </parameters>
7215       <errors>
7216         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
7217           The class is a primitive or array class.
7218         </error>
7219       </errors>
7220     </function>
7221 
7222     <function id="GetConstantPool" phase="start" num="146" since="1.1">
7223       <synopsis>Get Constant Pool</synopsis>
7224       <description>
7225         For the class indicated by <code>klass</code>, 
7226         return the raw bytes of the constant pool in the format of the
7227         <code>constant_pool</code> item of 
7228         <vmspec chapter="4"/>.
7229         The format of the constant pool may differ between versions
7230         of the Class File Format, so, the 
7231         <functionlink id="GetClassVersionNumbers">minor and major 
7232         class version numbers</functionlink> should be checked for
7233         compatibility.
7234         <p/>
7235         The returned constant pool might not have the same layout or
7236         contents as the constant pool in the defining class file.
7237         The constant pool returned by GetConstantPool() may have
7238         more or fewer entries than the defining constant pool.
7239         Entries may be in a different order.
7240         The constant pool returned by GetConstantPool() will match the
7241         constant pool used by 
7242         <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
7243         That is, the bytecodes returned by GetBytecodes() will have
7244         constant pool indices which refer to constant pool entries returned
7245         by GetConstantPool().
7246         Note that since <functionlink id="RetransformClasses"/> 
7247         and <functionlink id="RedefineClasses"/> can change 
7248         the constant pool, the constant pool returned by this function
7249         can change accordingly.  Thus, the correspondence between 
7250         GetConstantPool() and GetBytecodes() does not hold if there
7251         is an intervening class retransformation or redefinition. 
7252         The value of a constant pool entry used by a given bytecode will
7253         match that of the defining class file (even if the indices don't match).
7254         Constant pool entries which are not used directly or indirectly by
7255         bytecodes (for example,  UTF-8 strings associated with annotations) are
7256         not  required to exist in the returned constant pool.
7257       </description>
7258       <origin>new</origin>
7259       <capabilities>
7260         <required id="can_get_constant_pool"></required>
7261       </capabilities>
7262       <parameters>
7263         <param id="klass">
7264           <jclass/>
7265             <description>
7266               The class to query.
7267             </description>
7268         </param>
7269         <param id="constant_pool_count_ptr">
7270           <outptr><jint/></outptr>
7271           <description>
7272             On return, points to the number of entries
7273             in the constant pool table plus one.
7274             This corresponds to the <code>constant_pool_count</code>
7275             item of the Class File Format.
7276           </description>
7277         </param>
7278         <param id="constant_pool_byte_count_ptr">
7279           <outptr><jint/></outptr>
7280           <description>
7281             On return, points to the number of bytes
7282             in the returned raw constant pool.
7283           </description>
7284         </param>
7285         <param id="constant_pool_bytes_ptr">
7286           <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
7287             <description>
7288               On return, points to the raw constant pool, that is the bytes
7289               defined by the <code>constant_pool</code> item of the 
7290               Class File Format
7291             </description>
7292         </param>
7293       </parameters>
7294       <errors>
7295         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
7296           The class is a primitive or array class.
7297         </error>
7298       </errors>
7299     </function>
7300 
7301     <function id="IsInterface" phase="start" num="55">
7302       <synopsis>Is Interface</synopsis>
7303       <description>
7304         Determines whether a class object reference represents an interface.
7305         The <code>jboolean</code> result is
7306         <code>JNI_TRUE</code> if the "class" is actually an interface,
7307         <code>JNI_FALSE</code> otherwise. 
7308       </description>
7309       <origin>jvmdi</origin>
7310       <capabilities>
7311       </capabilities>
7312       <parameters>
7313         <param id="klass">
7314           <jclass/>
7315             <description>
7316               The class to query.
7317             </description>
7318         </param>
7319         <param id="is_interface_ptr">
7320           <outptr><jboolean/></outptr>
7321           <description>
7322             On return, points to the boolean result of this function.
7323 
7324           </description>
7325         </param>
7326       </parameters>
7327       <errors>
7328       </errors>
7329     </function>
7330 
7331     <function id="IsArrayClass" phase="start" num="56">
7332       <synopsis>Is Array Class</synopsis>
7333       <description>
7334         Determines whether a class object reference represents an array.
7335         The <code>jboolean</code> result is
7336         <code>JNI_TRUE</code> if the class is an array,
7337         <code>JNI_FALSE</code> otherwise. 
7338       </description>
7339       <origin>jvmdi</origin>
7340       <capabilities>
7341       </capabilities>
7342       <parameters>
7343         <param id="klass">
7344           <jclass/>
7345             <description>
7346               The class to query.
7347             </description>
7348         </param>
7349         <param id="is_array_class_ptr">
7350           <outptr><jboolean/></outptr>
7351           <description>
7352             On return, points to the boolean result of this function.
7353 
7354           </description>
7355         </param>
7356       </parameters>
7357       <errors>
7358       </errors>
7359     </function>
7360 
7361     <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
7362       <synopsis>Is Modifiable Class</synopsis>
7363       <description>
7364         Determines whether a class is modifiable.
7365         If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
7366         returns <code>JNI_TRUE</code>) the class can be
7367         redefined with <functionlink id="RedefineClasses"/> (assuming 
7368         the agent possesses the
7369         <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
7370         capability) or
7371         retransformed with <functionlink id="RetransformClasses"/> (assuming 
7372         the agent possesses the
7373         <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
7374         capability).
7375         If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
7376         returns <code>JNI_FALSE</code>) the class can be neither
7377         redefined nor retransformed.
7378         <p/>
7379         Primitive classes (for example, <code>java.lang.Integer.TYPE</code>),
7380         array classes, and some implementation defined classes are never modifiable. 
7381         <p/>
7382       </description>
7383       <origin>new</origin>
7384       <capabilities>
7385         <capability id="can_redefine_any_class">
7386           If possessed then all classes (except primitive, array, and some implementation defined
7387           classes) are modifiable (redefine or retransform).
7388         </capability>
7389         <capability id="can_retransform_any_class">
7390           If possessed then all classes (except primitive, array, and some implementation defined
7391           classes) are modifiable with <functionlink id="RetransformClasses"/>.
7392         </capability>
7393         <capability id="can_redefine_classes">
7394           No effect on the result of the function.
7395           But must additionally be possessed to modify the class with
7396           <functionlink id="RedefineClasses"/>.
7397         </capability>
7398         <capability id="can_retransform_classes">
7399           No effect on the result of the function.
7400           But must additionally be possessed to modify the class with
7401           <functionlink id="RetransformClasses"/>.
7402         </capability>
7403       </capabilities>
7404       <parameters>
7405         <param id="klass">
7406           <jclass/>
7407             <description>
7408               The class to query.
7409             </description>
7410         </param>
7411         <param id="is_modifiable_class_ptr">
7412           <outptr><jboolean/></outptr>
7413           <description>
7414             On return, points to the boolean result of this function.
7415           </description>
7416         </param>
7417       </parameters>
7418       <errors>
7419       </errors>
7420     </function>
7421 
7422     <function id="GetClassLoader" phase="start" num="57">
7423       <synopsis>Get Class Loader</synopsis>
7424       <description>
7425         For the class indicated by <code>klass</code>, return via
7426         <code>classloader_ptr</code> a reference to the class loader for the
7427         class.
7428       </description>
7429       <origin>jvmdi</origin>
7430       <capabilities>
7431       </capabilities>
7432       <parameters>
7433         <param id="klass">
7434           <jclass/>
7435             <description>
7436               The class to query.
7437             </description>
7438         </param>
7439         <param id="classloader_ptr">
7440           <outptr><jobject/></outptr>
7441             <description>
7442               On return, points to the class loader that loaded
7443               this class.
7444               If the class was not created by a class loader
7445               or if the class loader is the bootstrap class loader,
7446               points to <code>NULL</code>.
7447             </description>
7448         </param>
7449       </parameters>
7450       <errors>
7451       </errors>
7452 
7453     </function>
7454 
7455     <function id="GetSourceDebugExtension" phase="start" num="90">
7456       <synopsis>Get Source Debug Extension</synopsis>
7457       <description>
7458         For the class indicated by <code>klass</code>, return the debug 
7459         extension via <code>source_debug_extension_ptr</code>.
7460         The returned string 
7461         contains exactly the debug extension information present in the
7462         class file of <code>klass</code>. 
7463       </description>
7464       <origin>jvmdi</origin>
7465       <capabilities>
7466         <required id="can_get_source_debug_extension"></required>
7467       </capabilities>
7468       <parameters>
7469         <param id="klass">
7470           <jclass/>
7471             <description>
7472               The class to query.
7473             </description>
7474         </param>
7475         <param id="source_debug_extension_ptr">
7476           <allocbuf><char/></allocbuf>
7477           <description>
7478             On return, points to the class's debug extension, encoded as a
7479             <internallink id="mUTF">modified UTF-8</internallink> string.
7480           </description>
7481         </param>
7482       </parameters>
7483       <errors>
7484         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
7485           Class information does not include a debug extension.
7486         </error>
7487       </errors>
7488     </function>
7489 
7490     <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
7491       <synopsis>Retransform Classes</synopsis>
7492       <description>
7493         This function facilitates the 
7494         <internallink id="bci">bytecode instrumentation</internallink>
7495         of already loaded classes.
7496         To replace the class definition without reference to the existing
7497         bytecodes, as one might do when recompiling from source for 
7498         fix-and-continue debugging, <functionlink id="RedefineClasses"/>
7499         function should be used instead.
7500         <p/>
7501         When classes are initially loaded or when they are 
7502         <functionlink id="RedefineClasses">redefined</functionlink>,
7503         the initial class file bytes can be transformed with the
7504         <eventlink id="ClassFileLoadHook"/> event.
7505         This function reruns the transformation process
7506         (whether or not a transformation has previously occurred).
7507         This retransformation follows these steps:
7508         <ul>
7509           <li>starting from the initial class file bytes 
7510           </li>
7511           <li>for each <fieldlink id="can_retransform_classes"
7512                      struct="jvmtiCapabilities">retransformation
7513                                                 incapable</fieldlink>
7514             agent which received a
7515             <code>ClassFileLoadHook</code> event during the previous
7516             load or redefine, the bytes it returned 
7517             (via the <code>new_class_data</code> parameter)
7518             are reused as the output of the transformation; 
7519             note that this is equivalent to reapplying
7520             the previous transformation, unaltered. except that
7521             the <code>ClassFileLoadHook</code> event
7522             is <b>not</b> sent to these agents
7523           </li>
7524           <li>for each <fieldlink id="can_retransform_classes"
7525                      struct="jvmtiCapabilities">retransformation
7526                                                 capable</fieldlink>
7527             agent, the <code>ClassFileLoadHook</code> event is sent,
7528             allowing a new transformation to be applied
7529           </li>
7530           <li>the transformed class file bytes are installed as the new
7531             definition of the class
7532           </li>
7533         </ul>
7534         See the <eventlink id="ClassFileLoadHook"/> event for more details.
7535         <p/>
7536         The initial class file bytes represent the bytes passed to 
7537         <code>ClassLoader.defineClass</code>
7538         or <code>RedefineClasses</code> (before any transformations
7539         were applied), however they may not exactly match them.
7540         The constant pool may differ in ways described in
7541         <functionlink id="GetConstantPool"/>.
7542         Constant pool indices in the bytecodes of methods will correspond.
7543         Some attributes may not be present.
7544         Where order is not meaningful, for example the order of methods,
7545         order may not be preserved.
7546         <p/>
7547         Retransformation can cause new versions of methods to be installed.
7548         Old method versions may become 
7549         <internallink id="obsoleteMethods">obsolete</internallink>
7550         The new method version will be used on new invokes.  
7551         If a method has active stack frames, those active frames continue to
7552         run the bytecodes of the original method version. 
7553         <p/>
7554         This function does not cause any initialization except that which 
7555         would occur under the customary JVM semantics.
7556         In other words, retransforming a class does not cause its initializers to be
7557         run. The values of static fields will remain as they were
7558         prior to the call.
7559         <p/>
7560         Threads need not be suspended.
7561         <p/>
7562         All breakpoints in the class are cleared.
7563         <p/>
7564         All attributes are updated.
7565         <p/>
7566         Instances of the retransformed class are not affected -- fields retain their
7567         previous values.  
7568         <functionlink id="GetTag">Tags</functionlink> on the instances are
7569         also unaffected.
7570         <p/>
7571         In response to this call, no events other than the
7572         <eventlink id="ClassFileLoadHook"/> event
7573         will be sent.
7574         <p/>
7575         The retransformation may change method bodies, the constant pool and attributes.
7576         The retransformation must not add, remove or rename fields or methods, change the 
7577         signatures of methods, change modifiers, or change inheritance.  
7578         These restrictions may be lifted in future versions.
7579         See the error return description below for information on error codes
7580         returned if an unsupported retransformation is attempted.
7581         The class file bytes are not verified or installed until they have passed
7582         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7583         returned error code reflects the result of the transformations.
7584         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7585         none of the classes to be retransformed will have a new definition installed.
7586         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7587         all of the classes to be retransformed will have their new definitions installed.        
7588       </description>
7589       <origin>new</origin>
7590       <capabilities>
7591         <required id="can_retransform_classes"></required>
7592         <capability id="can_retransform_any_class"></capability>
7593       </capabilities>
7594       <parameters>
7595         <param id="class_count">
7596           <jint min="0"/>
7597           <description>
7598             The number of classes to be retransformed.
7599           </description>
7600         </param>
7601         <param id="classes">
7602           <inbuf incount="class_count"><jclass/></inbuf>
7603           <description>
7604             The array of classes to be retransformed.
7605           </description>
7606         </param>
7607       </parameters>
7608       <errors>
7609         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7610           One of the <paramlink id="classes"/> cannot be modified. 
7611           See <functionlink id="IsModifiableClass"/>.
7612         </error>
7613         <error id="JVMTI_ERROR_INVALID_CLASS">
7614           One of the <paramlink id="classes"/> is not a valid class.
7615         </error>
7616         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7617           A retransformed class file has a version number not supported by this VM.
7618         </error>
7619         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7620           A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>).
7621         </error>
7622         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7623           The retransformed class file definitions would lead to a circular definition 
7624           (the VM would return a <code>ClassCircularityError</code>).
7625         </error>
7626         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7627           The retransformed class file bytes fail verification.
7628         </error>
7629         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7630           The class name defined in a retransformed class file is
7631           different from the name in the old class object.
7632         </error>
7633         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7634           A retransformed class file would require adding a method.
7635         </error>
7636         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7637           A retransformed class file changes a field.
7638         </error>
7639         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7640           A direct superclass is different for a retransformed class file,
7641           or the set of directly implemented
7642           interfaces is different.
7643         </error>
7644         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7645           A retransformed class file does not declare a method
7646           declared in the old class version.
7647         </error>
7648         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7649           A retransformed class file has different class modifiers.
7650         </error>
7651         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7652           A method in the retransformed class file has different modifiers
7653           than its counterpart in the old class version.
7654         </error>
7655       </errors>
7656     </function>
7657 
7658     <function id="RedefineClasses" jkernel="yes" num="87">
7659       <synopsis>Redefine Classes</synopsis>
7660       <typedef id="jvmtiClassDefinition" label="Class redefinition description">
7661         <field id="klass">
7662           <jclass/>
7663             <description>
7664               Class object for this class
7665             </description>
7666         </field>
7667         <field id="class_byte_count">
7668           <jint/>
7669           <description>
7670             Number of bytes defining class (below)
7671           </description>
7672         </field>
7673         <field id="class_bytes">
7674           <inbuf incount="class_byte_count"><uchar/></inbuf>
7675           <description>
7676             Bytes defining class (in <vmspec chapter="4"/>)
7677           </description>
7678         </field>
7679       </typedef>
7680       <description>
7681         All classes given are redefined according to the definitions
7682         supplied.
7683         This function is used to replace the definition of a class
7684         with a new definition, as might be needed in fix-and-continue
7685         debugging.
7686         Where the existing class file bytes are to be transformed, for 
7687         example in
7688         <internallink id="bci">bytecode instrumentation</internallink>,
7689         <functionlink id="RetransformClasses"/> should be used.
7690         <p/>
7691         Redefinition can cause new versions of methods to be installed.
7692         Old method versions may become 
7693         <internallink id="obsoleteMethods">obsolete</internallink>
7694         The new method version will be used on new invokes.  
7695         If a method has active stack frames, those active frames continue to
7696         run the bytecodes of the original method version. 
7697         If resetting of stack frames is desired, use 
7698         <functionlink id="PopFrame"></functionlink>
7699         to pop frames with obsolete method versions.
7700         <p/>
7701         This function does not cause any initialization except that which 
7702         would occur under the customary JVM semantics.
7703         In other words, redefining a class does not cause its initializers to be
7704         run. The values of static fields will remain as they were
7705         prior to the call.
7706         <p/>
7707         Threads need not be suspended.
7708         <p/>
7709         All breakpoints in the class are cleared.
7710         <p/>
7711         All attributes are updated.
7712         <p/>
7713         Instances of the redefined class are not affected -- fields retain their
7714         previous values.  
7715         <functionlink id="GetTag">Tags</functionlink> on the instances are
7716         also unaffected.
7717         <p/>
7718         In response to this call, the <jvmti/> event
7719         <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
7720         will be sent (if enabled), but no other <jvmti/> events will be sent.
7721         <p/>
7722         The redefinition may change method bodies, the constant pool and attributes.
7723         The redefinition must not add, remove or rename fields or methods, change the 
7724         signatures of methods, change modifiers, or change inheritance.  
7725         These restrictions may be lifted in future versions.
7726         See the error return description below for information on error codes
7727         returned if an unsupported redefinition is attempted.
7728         The class file bytes are not verified or installed until they have passed
7729         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7730         returned error code reflects the result of the transformations applied
7731         to the bytes passed into <paramlink id="class_definitions"/>.
7732         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7733         none of the classes to be redefined will have a new definition installed.
7734         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7735         all of the classes to be redefined will have their new definitions installed.        
7736       </description>
7737       <origin>jvmdi</origin>
7738       <capabilities>
7739         <required id="can_redefine_classes"></required>
7740         <capability id="can_redefine_any_class"></capability>
7741       </capabilities>
7742       <parameters>
7743         <param id="class_count">
7744           <jint min="0"/>
7745           <description>
7746             The number of classes specified in <code>class_definitions</code>
7747           </description>
7748         </param>
7749         <param id="class_definitions">
7750           <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
7751           <description>
7752             The array of new class definitions
7753           </description>
7754         </param>
7755       </parameters>
7756       <errors>
7757         <error id="JVMTI_ERROR_NULL_POINTER">
7758           One of <code>class_bytes</code> is <code>NULL</code>.
7759         </error>
7760         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7761           An element of <code>class_definitions</code> cannot be modified.
7762           See <functionlink id="IsModifiableClass"/>.
7763         </error>
7764         <error id="JVMTI_ERROR_INVALID_CLASS">
7765           An element of <code>class_definitions</code> is not a valid class.
7766         </error>
7767         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7768           A new class file has a version number not supported by this VM.
7769         </error>
7770         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7771           A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
7772         </error>
7773         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7774           The new class file definitions would lead to a circular definition 
7775           (the VM would return a <code>ClassCircularityError</code>).
7776         </error>
7777         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7778           The class bytes fail verification.
7779         </error>
7780         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7781           The class name defined in a new class file is
7782           different from the name in the old class object.
7783         </error>
7784         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7785           A new class file would require adding a method.
7786         </error>
7787         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7788           A new class version changes a field.
7789         </error>
7790         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7791           A direct superclass is different for a new class
7792           version, or the set of directly implemented
7793           interfaces is different.
7794         </error>
7795         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7796           A new class version does not declare a method
7797           declared in the old class version.
7798         </error>
7799         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7800           A new class version has different modifiers.
7801         </error>
7802         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7803           A method in the new class version has different modifiers
7804           than its counterpart in the old class version.
7805         </error>
7806       </errors>
7807     </function>
7808 
7809   </category>
7810 
7811   <category id="object" label="Object">
7812 
7813     <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
7814       <synopsis>Get Object Size</synopsis>
7815       <description>
7816         For the object indicated by <code>object</code>,
7817         return via <code>size_ptr</code> the size of the object.
7818         This size is an implementation-specific approximation of
7819         the amount of storage consumed by this object. 
7820         It may include some or all of the object's overhead, and thus
7821         is useful for comparison within an implementation but not
7822         between implementations.
7823         The estimate may change during a single invocation of the JVM.
7824       </description>
7825       <origin>new</origin>
7826       <capabilities>
7827       </capabilities>
7828       <parameters>
7829         <param id="object">
7830           <jobject/>
7831             <description>
7832               The object to query.
7833             </description>
7834         </param>
7835         <param id="size_ptr">
7836           <outptr><jlong/></outptr>
7837           <description>
7838             On return, points to the object's size in bytes.
7839           </description>
7840         </param>
7841       </parameters>
7842       <errors>
7843       </errors>
7844     </function>
7845 
7846     <function id="GetObjectHashCode" phase="start" num="58">
7847       <synopsis>Get Object Hash Code</synopsis>
7848       <description>
7849         For the object indicated by <code>object</code>,
7850         return via <code>hash_code_ptr</code> a hash code.
7851         This hash code could be used to maintain a hash table of object references,
7852         however, on some implementations this can cause significant performance 
7853         impacts--in most cases 
7854         <internallink id="Heap">tags</internallink> 
7855         will be a more efficient means of associating information with objects.
7856         This function guarantees 
7857         the same hash code value for a particular object throughout its life
7858       </description>
7859       <origin>jvmdi</origin>
7860       <capabilities>
7861       </capabilities>
7862       <parameters>
7863         <param id="object">
7864           <jobject/>
7865             <description>
7866               The object to query.
7867             </description>
7868         </param>
7869         <param id="hash_code_ptr">
7870           <outptr><jint/></outptr>
7871           <description>
7872             On return, points to the object's hash code.
7873           </description>
7874         </param>
7875       </parameters>
7876       <errors>
7877       </errors>
7878     </function>
7879 
7880     <function id="GetObjectMonitorUsage" num="59">
7881       <synopsis>Get Object Monitor Usage</synopsis>
7882       <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
7883         <field id="owner">
7884           <jthread/>
7885             <description>
7886               The thread owning this monitor, or <code>NULL</code> if unused
7887             </description>
7888         </field>
7889         <field id="entry_count">
7890           <jint/>
7891           <description>
7892             The number of times the owning thread has entered the monitor
7893           </description>
7894         </field>
7895         <field id="waiter_count">
7896           <jint/>
7897           <description>
7898             The number of threads waiting to own this monitor
7899           </description>
7900         </field>
7901         <field id="waiters">
7902           <allocfieldbuf><jthread/></allocfieldbuf>
7903             <description>
7904               The <code>waiter_count</code> waiting threads
7905             </description>
7906         </field>
7907         <field id="notify_waiter_count">
7908           <jint/>
7909           <description>
7910             The number of threads waiting to be notified by this monitor
7911           </description>
7912         </field>
7913         <field id="notify_waiters">
7914           <allocfieldbuf><jthread/></allocfieldbuf>
7915             <description>
7916               The <code>notify_waiter_count</code> threads waiting to be notified
7917             </description>
7918         </field>
7919       </typedef>
7920       <description>
7921         Get information about the object's monitor.
7922         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 
7923         are filled in with information about usage of the monitor.
7924           <todo>
7925             Decide and then clarify suspend requirements.
7926           </todo>
7927       </description>
7928       <origin>jvmdi</origin>
7929       <capabilities>
7930         <required id="can_get_monitor_info"></required>
7931       </capabilities>
7932       <parameters>
7933         <param id="object">
7934           <jobject/>
7935             <description>
7936               The object to query.
7937             </description>
7938         </param>
7939         <param id="info_ptr">
7940           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
7941           <description>
7942             On return, filled with monitor information for the 
7943             specified object.
7944           </description>
7945         </param>
7946       </parameters>
7947       <errors>
7948       </errors>
7949     </function>
7950 
7951     <elide>
7952     <function id="GetObjectMonitors" num="116">
7953       <synopsis>Get Object Monitors</synopsis>
7954       <description>
7955         Return the list of object monitors.
7956         <p/>
7957         Note: details about each monitor can be examined with 
7958         <functionlink id="GetObjectMonitorUsage"></functionlink>.
7959       </description>
7960       <origin>new</origin>
7961       <capabilities>
7962         <required id="can_get_monitor_info"></required>
7963       </capabilities>
7964       <parameters>
7965         <param id="monitorCnt">
7966           <outptr><jint/></outptr>
7967           <description>
7968             On return, pointer to the number 
7969             of monitors returned in <code>monitors_ptr</code>.
7970           </description>
7971         </param>
7972         <param id="monitors_ptr">
7973           <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
7974             <description>
7975               On return, pointer to the monitor list.
7976             </description>
7977         </param>
7978       </parameters>
7979       <errors>
7980       </errors>
7981     </function>
7982     </elide>
7983 
7984   </category>
7985 
7986   <category id="fieldCategory" label="Field">
7987 
7988     <intro>
7989     </intro>
7990 
7991     <function id="GetFieldName" phase="start" num="60">
7992       <synopsis>Get Field Name (and Signature)</synopsis>
7993       <description>
7994         For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
7995         return the field name via <paramlink id="name_ptr"/> and field signature via
7996         <paramlink id="signature_ptr"/>.
7997         <p/>
7998         Field signatures are defined in the
7999         <externallink id="docs/technotes/guides/jni/spec/jniTOC.html">JNI Specification</externallink>
8000         and are referred to as <code>field descriptors</code> in
8001         <vmspec chapter="4.3.2"/>.
8002       </description>
8003       <origin>jvmdiClone</origin>
8004       <capabilities>
8005       </capabilities>
8006       <parameters>
8007         <param id="klass">
8008           <jclass field="field"/>
8009             <description>
8010               The class of the field to query.
8011             </description>
8012         </param>
8013         <param id="field">
8014           <jfieldID class="klass"/>
8015             <description>
8016               The field to query.
8017             </description>
8018         </param>
8019         <param id="name_ptr">
8020           <allocbuf>
8021             <char/>
8022             <nullok>the name is not returned</nullok>
8023           </allocbuf>
8024           <description>
8025             On return, points to the field name, encoded as a
8026             <internallink id="mUTF">modified UTF-8</internallink> string.
8027           </description>
8028         </param>
8029         <param id="signature_ptr">
8030           <allocbuf>
8031             <char/>
8032             <nullok>the signature is not returned</nullok>
8033           </allocbuf>
8034           <description>
8035             On return, points to the field signature, encoded as a
8036             <internallink id="mUTF">modified UTF-8</internallink> string.
8037           </description>
8038         </param>
8039         <param id="generic_ptr">
8040           <allocbuf>
8041             <char/>           
8042             <nullok>the generic signature is not returned</nullok>
8043           </allocbuf>
8044           <description>
8045             On return, points to the generic signature of the field, encoded as a
8046             <internallink id="mUTF">modified UTF-8</internallink> string.
8047             If there is no generic signature attribute for the field, then,
8048             on return, points to <code>NULL</code>. 
8049           </description>
8050         </param>
8051       </parameters>
8052       <errors>
8053       </errors>
8054     </function>
8055 
8056     <function id="GetFieldDeclaringClass" phase="start" num="61">
8057       <synopsis>Get Field Declaring Class</synopsis>
8058       <description>
8059         For the field indicated by <code>klass</code> and <code>field</code>
8060         return the class that defined it via <code>declaring_class_ptr</code>.
8061         The declaring class will either be <code>klass</code>, a superclass, or
8062         an implemented interface.
8063       </description>
8064       <origin>jvmdi</origin>
8065       <capabilities>
8066       </capabilities>
8067       <parameters>
8068         <param id="klass">
8069           <jclass field="field"/>
8070             <description>
8071               The class to query.
8072             </description>
8073         </param>
8074         <param id="field">
8075           <jfieldID class="klass"/>
8076             <description>
8077               The field to query.
8078             </description>
8079         </param>
8080         <param id="declaring_class_ptr">
8081           <outptr><jclass/></outptr>
8082             <description>
8083               On return, points to the declaring class
8084             </description>
8085         </param>
8086       </parameters>
8087       <errors>
8088       </errors>
8089     </function>
8090 
8091     <function id="GetFieldModifiers" phase="start" num="62">
8092       <synopsis>Get Field Modifiers</synopsis>
8093       <description>
8094         For the field indicated by <code>klass</code> and <code>field</code>
8095         return the access flags via <code>modifiers_ptr</code>.
8096         Access flags are defined in <vmspec chapter="4"/>.
8097       </description>
8098       <origin>jvmdi</origin>
8099       <capabilities>
8100       </capabilities>
8101       <parameters>
8102         <param id="klass">
8103           <jclass field="field"/>
8104             <description>
8105               The class to query.
8106             </description>
8107         </param>
8108         <param id="field">
8109           <jfieldID class="klass"/>
8110             <description>
8111               The field to query.
8112             </description>
8113         </param>
8114         <param id="modifiers_ptr">
8115           <outptr><jint/></outptr>
8116           <description>
8117             On return, points to the access flags.
8118           </description>
8119         </param>
8120       </parameters>
8121       <errors>
8122       </errors>
8123     </function>
8124 
8125     <function id="IsFieldSynthetic" phase="start" num="63">
8126       <synopsis>Is Field Synthetic</synopsis>
8127       <description>
8128         For the field indicated by <code>klass</code> and <code>field</code>, return a
8129         value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
8130         Synthetic fields are generated by the compiler but not present in the 
8131         original source code.
8132       </description>
8133       <origin>jvmdi</origin>
8134       <capabilities>
8135         <required id="can_get_synthetic_attribute"></required>
8136       </capabilities>
8137       <parameters>
8138         <param id="klass">
8139           <jclass field="field"/>
8140             <description>
8141               The class of the field to query.
8142             </description>
8143         </param>
8144         <param id="field">
8145           <jfieldID class="klass"/>
8146             <description>
8147               The field to query.
8148             </description>
8149         </param>
8150         <param id="is_synthetic_ptr">
8151           <outptr><jboolean/></outptr>
8152           <description>
8153             On return, points to the boolean result of this function.
8154           </description>
8155         </param>
8156       </parameters>
8157       <errors>
8158       </errors>
8159     </function>
8160 
8161   </category>
8162 
8163   <category id="method" label="Method">
8164 
8165     <intro>
8166       These functions provide information about a method (represented as a
8167       <typelink id="jmethodID"/>) and set how methods are processed.
8168     </intro>
8169 
8170     <intro id="obsoleteMethods" label="Obsolete Methods">
8171       The functions <functionlink id="RetransformClasses"/> and
8172       <functionlink id="RedefineClasses"/> can cause new versions
8173       of methods to be installed.
8174       An original version of a method is considered equivalent
8175       to the new version if:
8176       <ul>
8177         <li>their bytecodes are the same except for indices into the
8178           constant pool and </li>
8179         <li>the referenced constants are equal.</li>
8180       </ul>
8181       An original method version which is not equivalent to the
8182       new method version is called obsolete and is assigned a new method ID;
8183       the original method ID now refers to the new method version.
8184       A method ID can be tested for obsolescence with 
8185       <functionlink id="IsMethodObsolete"/>.
8186     </intro>
8187 
8188     <function id="GetMethodName" phase="start" num="64">
8189       <synopsis>Get Method Name (and Signature)</synopsis>
8190       <description>
8191         For the method indicated by <code>method</code>,
8192         return the method name via <code>name_ptr</code> and method signature via
8193         <code>signature_ptr</code>.
8194         <p/>
8195         Method signatures are defined in the
8196         <externallink id="docs/technotes/guides/jni/spec/jniTOC.html">JNI Specification</externallink>
8197         and are referred to as <code>method descriptors</code> in 
8198         <vmspec chapter="4.3.3"/>.
8199         Note this is different
8200         than method signatures as defined in the <i>Java Language Specification</i>.
8201       </description>
8202       <origin>jvmdiClone</origin>
8203       <capabilities>
8204       </capabilities>
8205       <parameters>
8206         <param id="method">
8207           <jmethodID/>
8208             <description>
8209               The method to query.
8210             </description>
8211         </param>
8212         <param id="name_ptr">
8213           <allocbuf>
8214             <char/>
8215             <nullok>the name is not returned</nullok>
8216           </allocbuf>
8217           <description>
8218             On return, points to the method name, encoded as a
8219             <internallink id="mUTF">modified UTF-8</internallink> string.
8220           </description>
8221         </param>
8222         <param id="signature_ptr">
8223           <allocbuf>
8224             <char/>
8225             <nullok>the signature is not returned</nullok>
8226           </allocbuf>
8227           <description>
8228             On return, points to the method signature, encoded as a
8229             <internallink id="mUTF">modified UTF-8</internallink> string.
8230           </description>
8231         </param>
8232         <param id="generic_ptr">
8233           <allocbuf>
8234             <char/>           
8235             <nullok>the generic signature is not returned</nullok>
8236           </allocbuf>
8237           <description>
8238             On return, points to the generic signature of the method, encoded as a
8239             <internallink id="mUTF">modified UTF-8</internallink> string.
8240             If there is no generic signature attribute for the method, then,
8241             on return, points to <code>NULL</code>. 
8242           </description>
8243         </param>
8244       </parameters>
8245       <errors>
8246       </errors>
8247     </function>
8248 
8249     <function id="GetMethodDeclaringClass" phase="start" num="65">
8250       <synopsis>Get Method Declaring Class</synopsis>
8251       <description>
8252         For the method indicated by <code>method</code>,
8253         return the class that defined it via <code>declaring_class_ptr</code>.
8254       </description>
8255       <origin>jvmdi</origin>
8256       <capabilities>
8257       </capabilities>
8258       <parameters>
8259         <param id="klass">
8260           <jclass method="method"/>
8261             <description>
8262               The class to query.
8263             </description>
8264         </param>
8265         <param id="method">
8266           <jmethodID class="klass"/>
8267             <description>
8268               The method to query.
8269             </description>
8270         </param>
8271         <param id="declaring_class_ptr">
8272           <outptr><jclass/></outptr>
8273             <description>
8274               On return, points to the declaring class
8275             </description>
8276         </param>
8277       </parameters>
8278       <errors>
8279       </errors>
8280     </function>
8281 
8282     <function id="GetMethodModifiers" phase="start" num="66">
8283       <synopsis>Get Method Modifiers</synopsis>
8284       <description>
8285         For the method indicated by <code>method</code>,
8286         return the access flags via <code>modifiers_ptr</code>.
8287         Access flags are defined in <vmspec chapter="4"/>.
8288       </description>
8289       <origin>jvmdi</origin>
8290       <capabilities>
8291       </capabilities>
8292       <parameters>
8293         <param id="klass">
8294           <jclass method="method"/>
8295             <description>
8296               The class to query.
8297             </description>
8298         </param>
8299         <param id="method">
8300           <jmethodID class="klass"/>
8301             <description>
8302               The method to query.
8303             </description>
8304         </param>
8305         <param id="modifiers_ptr">
8306           <outptr><jint/></outptr>
8307           <description>
8308             On return, points to the access flags.
8309           </description>
8310         </param>
8311       </parameters>
8312       <errors>
8313       </errors>
8314     </function>
8315 
8316     <function id="GetMaxLocals" phase="start" num="68">
8317       <synopsis>Get Max Locals</synopsis>
8318       <description>
8319           For the method indicated by <code>method</code>,
8320           return the number of local variable slots used by the method,
8321           including the local variables used to pass parameters to the
8322           method on its invocation. 
8323           <p/>
8324           See <code>max_locals</code> in <vmspec chapter="4.7.3"/>.
8325       </description>
8326       <origin>jvmdi</origin>
8327       <capabilities>
8328       </capabilities>
8329       <parameters>
8330         <param id="klass">
8331           <jclass method="method"/>
8332             <description>
8333               The class to query.
8334             </description>
8335         </param>
8336         <param id="method">
8337           <jmethodID class="klass" native="error"/>
8338             <description>
8339               The method to query.
8340             </description>
8341         </param>
8342         <param id="max_ptr">
8343           <outptr><jint/></outptr>
8344           <description>
8345             On return, points to the maximum number of local slots
8346           </description>
8347         </param>
8348       </parameters>
8349       <errors>
8350       </errors>
8351     </function>
8352 
8353     <function id="GetArgumentsSize" phase="start" num="69">
8354       <synopsis>Get Arguments Size</synopsis>
8355       <description>
8356         For the method indicated by <code>method</code>,
8357         return via <code>max_ptr</code> the number of local variable slots used
8358         by the method's arguments.
8359         Note that two-word arguments use two slots.
8360       </description>
8361       <origin>jvmdi</origin>
8362       <capabilities>
8363       </capabilities>
8364       <parameters>
8365         <param id="klass">
8366           <jclass method="method"/>
8367             <description>
8368               The class to query.
8369             </description>
8370         </param>
8371         <param id="method">
8372           <jmethodID class="klass" native="error"/>
8373             <description>
8374               The method to query.
8375             </description>
8376         </param>
8377         <param id="size_ptr">
8378           <outptr><jint/></outptr>
8379           <description>
8380             On return, points to the number of argument slots
8381           </description>
8382         </param>
8383       </parameters>
8384       <errors>
8385       </errors>
8386     </function>
8387 
8388     <function id="GetLineNumberTable" phase="start" num="70">
8389       <synopsis>Get Line Number Table</synopsis>
8390       <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
8391         <field id="start_location">
8392           <jlocation/>
8393           <description>
8394             the <datalink id="jlocation"></datalink> where the line begins
8395           </description>
8396         </field>
8397         <field id="line_number">
8398           <jint/>
8399           <description>
8400             the line number
8401           </description>
8402         </field>
8403       </typedef>
8404       <description>
8405         For the method indicated by <code>method</code>,
8406         return a table of source line number entries. The size of the table is
8407         returned via <code>entry_count_ptr</code> and the table itself is
8408         returned via <code>table_ptr</code>. 
8409       </description>
8410       <origin>jvmdi</origin>
8411       <capabilities>
8412         <required id="can_get_line_numbers"></required>
8413       </capabilities>
8414       <parameters>
8415         <param id="klass">
8416           <jclass method="method"/>
8417             <description>
8418               The class to query.
8419             </description>
8420         </param>
8421         <param id="method">
8422           <jmethodID class="klass" native="error"/>
8423             <description>
8424               The method to query.
8425             </description>
8426         </param>
8427         <param id="entry_count_ptr">
8428           <outptr><jint/></outptr>
8429           <description>
8430             On return, points to the number of entries in the table
8431           </description>
8432         </param>
8433         <param id="table_ptr">
8434           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
8435           <description>
8436             On return, points to the line number table pointer.
8437           </description>
8438         </param>
8439       </parameters>
8440       <errors>
8441         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
8442           Class information does not include line numbers.
8443         </error>
8444       </errors>
8445     </function>
8446 
8447     <function id="GetMethodLocation" phase="start" num="71">
8448       <synopsis>Get Method Location</synopsis>
8449       <description>
8450         For the method indicated by <code>method</code>,
8451         return the beginning and ending addresses through
8452         <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
8453         conventional byte code indexing scheme, 
8454         <code>start_location_ptr</code> will always point to zero
8455         and <code>end_location_ptr</code> 
8456         will always point to the byte code count minus one. 
8457       </description>
8458       <origin>jvmdi</origin>
8459       <capabilities>
8460       </capabilities>
8461       <parameters>
8462         <param id="klass">
8463           <jclass method="method"/>
8464             <description>
8465               The class to query.
8466             </description>
8467         </param>
8468         <param id="method">
8469           <jmethodID class="klass" native="error"/>
8470             <description>
8471               The method to query.
8472             </description>
8473         </param>
8474         <param id="start_location_ptr">
8475           <outptr><jlocation/></outptr>
8476           <description>
8477             On return, points to the first location, or 
8478             <code>-1</code> if location information is not available.
8479             If the information is available and 
8480             <functionlink id="GetJLocationFormat"></functionlink>
8481             returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
8482             then this will always be zero.
8483           </description>
8484         </param>
8485         <param id="end_location_ptr">
8486           <outptr><jlocation/></outptr>
8487           <description>
8488             On return, points to the last location,
8489             or <code>-1</code> if location information is not available.
8490           </description>
8491         </param>
8492       </parameters>
8493       <errors>
8494         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
8495           Class information does not include method sizes.
8496         </error>
8497       </errors>
8498     </function>
8499 
8500     <function id="GetLocalVariableTable" num="72">
8501       <synopsis>Get Local Variable Table</synopsis>
8502       <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
8503         <field id="start_location">
8504           <jlocation/>
8505           <description>
8506             The code array index where the local variable is first valid
8507             (that is, where it must have a value).
8508           </description>
8509         </field>
8510         <field id="length">
8511           <jint/>
8512           <description>
8513             The length of the valid section for this local variable.
8514             The last code array index where the local variable is valid 
8515             is <code>start_location + length</code>.
8516           </description>
8517         </field>
8518         <field id="name">
8519           <allocfieldbuf><char/></allocfieldbuf>
8520           <description>
8521             The local variable name, encoded as a
8522             <internallink id="mUTF">modified UTF-8</internallink> string.
8523           </description>
8524         </field>
8525         <field id="signature">
8526           <allocfieldbuf><char/></allocfieldbuf>
8527           <description>
8528             The local variable's type signature, encoded as a
8529             <internallink id="mUTF">modified UTF-8</internallink> string.
8530             The signature format is the same as that defined in
8531             <vmspec chapter="4.3.2"/>.
8532           </description>
8533         </field>
8534         <field id="generic_signature">
8535           <allocfieldbuf><char/></allocfieldbuf>
8536           <description>
8537             The local variable's generic signature, encoded as a
8538             <internallink id="mUTF">modified UTF-8</internallink> string.
8539             The value of this field will be <code>NULL</code> for any local 
8540             variable which does not have a generic type.
8541           </description>
8542         </field>
8543         <field id="slot">
8544           <jint/>
8545           <description>
8546             The local variable's slot.  See <internallink id="local">Local Variables</internallink>.
8547           </description>
8548         </field>
8549       </typedef>
8550       <description>
8551         Return local variable information.
8552       </description>
8553       <origin>jvmdiClone</origin>
8554       <capabilities>
8555         <required id="can_access_local_variables"></required>
8556       </capabilities>
8557       <parameters>
8558         <param id="method">
8559           <jmethodID native="error"/>
8560             <description>
8561               The method to query.
8562             </description>
8563         </param>
8564         <param id="entry_count_ptr">
8565           <outptr><jint/></outptr>
8566           <description>
8567             On return, points to the number of entries in the table
8568           </description>
8569         </param>
8570         <param id="table_ptr">
8571           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
8572           <description>
8573             On return, points to an array of local variable table entries.
8574           </description>
8575         </param>
8576       </parameters>
8577       <errors>
8578         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8579           Class information does not include local variable
8580           information.
8581         </error>
8582       </errors>
8583     </function>
8584 
8585     <function id="GetBytecodes" phase="start" num="75">
8586       <synopsis>Get Bytecodes</synopsis>
8587       <description>
8588         For the method indicated by <code>method</code>,
8589         return the byte codes that implement the method. The number of
8590         bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes
8591         themselves are returned via <code>bytecodes_ptr</code>.
8592       </description>
8593       <origin>jvmdi</origin>
8594       <capabilities>
8595         <required id="can_get_bytecodes"></required>
8596       </capabilities>
8597       <parameters>
8598         <param id="klass">
8599           <jclass method="method"/>
8600             <description>
8601               The class to query.
8602             </description>
8603         </param>
8604         <param id="method">
8605           <jmethodID class="klass" native="error"/>
8606             <description>
8607               The method to query.
8608             </description>
8609         </param>
8610         <param id="bytecode_count_ptr">
8611           <outptr><jint/></outptr>
8612           <description>
8613             On return, points to the length of the byte code array
8614           </description>
8615         </param>
8616         <param id="bytecodes_ptr">
8617           <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
8618           <description>
8619             On return, points to the pointer to the byte code array
8620           </description>
8621         </param>
8622       </parameters>
8623       <errors>
8624       </errors>
8625     </function>
8626 
8627     <function id="IsMethodNative" phase="start" num="76">
8628       <synopsis>Is Method Native</synopsis>
8629       <description>
8630         For the method indicated by <code>method</code>, return a
8631         value indicating whether the method is native via <code>is_native_ptr</code>
8632       </description>
8633       <origin>jvmdi</origin>
8634       <capabilities>
8635       </capabilities>
8636       <parameters>
8637         <param id="klass">
8638           <jclass method="method"/>
8639             <description>
8640               The class to query.
8641             </description>
8642         </param>
8643         <param id="method">
8644           <jmethodID class="klass"/>
8645             <description>
8646               The method to query.
8647             </description>
8648         </param>
8649         <param id="is_native_ptr">
8650           <outptr><jboolean/></outptr>
8651           <description>
8652             On return, points to the boolean result of this function.
8653           </description>
8654         </param>
8655       </parameters>
8656       <errors>
8657       </errors>
8658     </function>
8659 
8660     <function id="IsMethodSynthetic" phase="start" num="77">
8661       <synopsis>Is Method Synthetic</synopsis>
8662       <description>
8663         For the method indicated by <code>method</code>, return a
8664         value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
8665         Synthetic methods are generated by the compiler but not present in the 
8666         original source code.
8667       </description>
8668       <origin>jvmdi</origin>
8669       <capabilities>
8670         <required id="can_get_synthetic_attribute"></required>
8671       </capabilities>
8672       <parameters>
8673         <param id="klass">
8674           <jclass method="method"/>
8675             <description>
8676               The class to query.
8677             </description>
8678         </param>
8679         <param id="method">
8680           <jmethodID class="klass"/>
8681             <description>
8682               The method to query.
8683             </description>
8684         </param>
8685         <param id="is_synthetic_ptr">
8686           <outptr><jboolean/></outptr>
8687           <description>
8688             On return, points to the boolean result of this function.
8689           </description>
8690         </param>
8691       </parameters>
8692       <errors>
8693       </errors>
8694     </function>
8695 
8696     <function id="IsMethodObsolete" phase="start" num="91">
8697       <synopsis>Is Method Obsolete</synopsis>
8698       <description>
8699         Determine if a method ID refers to an
8700         <internallink id="obsoleteMethods">obsolete</internallink>
8701         method version.
8702       </description>
8703       <origin>jvmdi</origin>
8704       <capabilities>
8705       </capabilities>
8706       <parameters>
8707         <param id="klass">
8708           <jclass method="method"/>
8709             <description>
8710               The class to query.
8711             </description>
8712         </param>
8713         <param id="method">
8714           <jmethodID class="klass"/>
8715             <description>
8716               The method ID to query.
8717             </description>
8718         </param>
8719         <param id="is_obsolete_ptr">
8720           <outptr><jboolean/></outptr>
8721           <description>
8722             On return, points to the boolean result of this function.
8723           </description>
8724         </param>
8725       </parameters>
8726       <errors>
8727       </errors>
8728     </function>
8729 
8730     <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
8731       <synopsis>Set Native Method Prefix</synopsis>
8732       <description>
8733         This function modifies the failure handling of
8734         native method resolution by allowing retry
8735         with a prefix applied to the name.
8736         When used with the 
8737         <eventlink id="ClassFileLoadHook">ClassFileLoadHook
8738         event</eventlink>, it enables native methods to be
8739         <internallink id="bci">instrumented</internallink>.
8740         <p/>
8741         Since native methods cannot be directly instrumented
8742         (they have no bytecodes), they must be wrapped with
8743         a non-native method which can be instrumented.
8744         For example, if we had:
8745         <example>
8746 native boolean foo(int x);</example>
8747         <p/>
8748         We could transform the class file (with the 
8749         ClassFileLoadHook event) so that this becomes:
8750         <example>
8751 boolean foo(int x) {
8752   <i>... record entry to foo ...</i>
8753   return wrapped_foo(x);
8754 }
8755 
8756 native boolean wrapped_foo(int x);</example>
8757         <p/>
8758         Where foo becomes a wrapper for the actual native method
8759         with the appended prefix "wrapped_".  Note that
8760         "wrapped_" would be a poor choice of prefix since it
8761         might conceivably form the name of an existing method
8762         thus something like "$$$MyAgentWrapped$$$_" would be
8763         better but would make these examples less readable.
8764         <p/>
8765         The wrapper will allow data to be collected on the native
8766         method call, but now the problem becomes linking up the  
8767         wrapped method with the native implementation.  
8768         That is, the method <code>wrapped_foo</code> needs to be 
8769         resolved to the native implementation of <code>foo</code>,
8770         which might be:
8771         <example>
8772 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
8773         <p/>
8774         This function allows the prefix to be specified and the
8775         proper resolution to occur.  
8776         Specifically, when the standard resolution fails, the
8777         resolution is retried taking the prefix into consideration.
8778         There are two ways that resolution occurs, explicit
8779         resolution with the JNI function <code>RegisterNatives</code>
8780         and the normal automatic resolution.  For 
8781         <code>RegisterNatives</code>, the VM will attempt this 
8782         association:
8783         <example>
8784 method(foo) -> nativeImplementation(foo)</example>
8785         <p/>
8786         When this fails, the resolution will be retried with
8787         the specified prefix prepended to the method name, 
8788         yielding the correct resolution:
8789         <example>
8790 method(wrapped_foo) -> nativeImplementation(foo)</example>
8791         <p/>
8792         For automatic resolution, the VM will attempt:
8793         <example>
8794 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
8795         <p/>
8796         When this fails, the resolution will be retried with
8797         the specified prefix deleted from the implementation name, 
8798         yielding the correct resolution:
8799         <example>
8800 method(wrapped_foo) -> nativeImplementation(foo)</example>
8801         <p/>
8802         Note that since the prefix is only used when standard
8803         resolution fails, native methods can be wrapped selectively.
8804         <p/>
8805         Since each <jvmti/> environment is independent and
8806         can do its own transformation of the bytecodes, more 
8807         than one layer of wrappers may be applied. Thus each
8808         environment needs its own prefix.  Since transformations
8809         are applied in order, the prefixes, if applied, will
8810         be applied in the same order.
8811         The order of transformation application is described in
8812         the <eventlink id="ClassFileLoadHook"/> event.
8813         Thus if three environments applied
8814         wrappers, <code>foo</code> might become 
8815         <code>$env3_$env2_$env1_foo</code>.  But if, say,
8816         the second environment did not apply a wrapper to
8817         <code>foo</code> it would be just 
8818         <code>$env3_$env1_foo</code>.  To be able to 
8819         efficiently determine the sequence of prefixes,
8820         an intermediate prefix is only applied if its non-native
8821         wrapper exists.  Thus, in the last example, even though 
8822         <code>$env1_foo</code> is not a native method, the
8823         <code>$env1_</code> prefix is applied since 
8824         <code>$env1_foo</code> exists.
8825         <p/>
8826         Since the prefixes are used at resolution time
8827         and since resolution may be arbitrarily delayed, a
8828         native method prefix must remain set as long as there 
8829         are corresponding prefixed native methods.
8830       </description>
8831       <origin>new</origin>
8832       <capabilities>
8833         <required id="can_set_native_method_prefix"></required>
8834       </capabilities>
8835       <parameters>
8836         <param id="prefix">
8837           <inbuf>
8838             <char/>
8839             <nullok>
8840               any existing prefix in this environment is cancelled
8841             </nullok>
8842           </inbuf>
8843           <description>
8844             The prefix to apply, encoded as a
8845             <internallink id="mUTF">modified UTF-8</internallink> string.
8846           </description>
8847         </param>
8848       </parameters>
8849       <errors>
8850       </errors>
8851     </function>
8852 
8853     <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
8854       <synopsis>Set Native Method Prefixes</synopsis>
8855       <description>
8856          For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
8857          will provide all needed native method prefixing.
8858          For a meta-agent that performs multiple independent class
8859          file transformations (for example as a proxy for another
8860          layer of agents) this function allows each transformation
8861          to have its own prefix.  
8862          The prefixes are applied in the order supplied and are
8863          processed in the same manor as described for the
8864          application of prefixes from multiple <jvmti/> environments
8865          in <functionlink id="SetNativeMethodPrefix"/>.
8866          <p/>
8867          Any previous prefixes are replaced.  Thus, calling this
8868          function with a <paramlink id="prefix_count"/> of <code>0</code>
8869          disables prefixing in this environment.
8870          <p/>
8871          <functionlink id="SetNativeMethodPrefix"/> and this function
8872          are the two ways to set the prefixes.  
8873          Calling <code>SetNativeMethodPrefix</code> with 
8874          a prefix is the same as calling this function with 
8875          <paramlink id="prefix_count"/> of <code>1</code>. 
8876          Calling <code>SetNativeMethodPrefix</code> with 
8877          <code>NULL</code> is the same as calling this function with 
8878          <paramlink id="prefix_count"/> of <code>0</code>. 
8879       </description>
8880       <origin>new</origin>
8881       <capabilities>
8882         <required id="can_set_native_method_prefix"></required>
8883       </capabilities>
8884       <parameters>
8885         <param id="prefix_count">
8886           <jint min="0"/>
8887             <description>
8888               The number of prefixes to apply.
8889             </description>
8890         </param>
8891         <param id="prefixes">
8892           <agentbuf>
8893             <char/>
8894           </agentbuf>
8895           <description>
8896             The prefixes to apply for this environment, each encoded as a
8897             <internallink id="mUTF">modified UTF-8</internallink> string.
8898           </description>
8899         </param>
8900       </parameters>
8901       <errors>
8902       </errors>
8903     </function>
8904 
8905   </category>
8906 
8907   <category id="RawMonitors" label="Raw Monitor">
8908 
8909     <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
8910       <synopsis>Create Raw Monitor</synopsis>
8911       <description>
8912         Create a raw monitor.
8913       </description>
8914       <origin>jvmdi</origin>
8915       <capabilities>
8916       </capabilities>
8917       <parameters>
8918         <param id="name">
8919           <inbuf><char/></inbuf>
8920           <description>
8921             A name to identify the monitor, encoded as a
8922             <internallink id="mUTF">modified UTF-8</internallink> string.
8923           </description>
8924         </param>
8925         <param id="monitor_ptr">
8926           <outptr><jrawMonitorID/></outptr>
8927           <description>
8928             On return, points to the created monitor.
8929           </description>
8930         </param>
8931       </parameters>
8932       <errors>
8933       </errors>
8934     </function>
8935 
8936     <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
8937       <synopsis>Destroy Raw Monitor</synopsis>
8938       <description>
8939         Destroy the raw monitor.
8940         If the monitor being destroyed has been entered by this thread, it will be
8941         exited before it is destroyed.
8942         If the monitor being destroyed has been entered by another thread,
8943         an error will be returned and the monitor will not be destroyed.
8944       </description>
8945       <origin>jvmdi</origin>
8946       <capabilities>
8947       </capabilities>
8948       <parameters>
8949         <param id="monitor">
8950           <jrawMonitorID/>
8951           <description>
8952             The monitor
8953           </description>
8954         </param>
8955       </parameters>
8956       <errors>
8957         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8958           Not monitor owner
8959         </error>        
8960       </errors>
8961     </function>
8962 
8963     <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
8964       <synopsis>Raw Monitor Enter</synopsis>
8965       <description>
8966         Gain exclusive ownership of a raw monitor.  
8967         The same thread may enter a monitor more then once.
8968         The thread must
8969         <functionlink id="RawMonitorExit">exit</functionlink>
8970         the monitor the same number of times as it is entered.
8971         If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
8972         and has not exited when attached threads come into existence, the enter
8973         is considered to have occurred on the main thread.
8974       </description>
8975       <origin>jvmdi</origin>
8976       <capabilities>
8977       </capabilities>
8978       <parameters>
8979         <param id="monitor">
8980           <jrawMonitorID/>
8981           <description>
8982             The monitor
8983           </description>
8984         </param>
8985       </parameters>
8986       <errors>
8987       </errors>
8988     </function>
8989 
8990     <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
8991       <synopsis>Raw Monitor Exit</synopsis>
8992       <description>
8993         Release exclusive ownership of a raw monitor.
8994       </description>
8995       <origin>jvmdi</origin>
8996       <capabilities>
8997       </capabilities>
8998       <parameters>
8999         <param id="monitor">
9000           <jrawMonitorID/>
9001           <description>
9002             The monitor
9003           </description>
9004         </param>
9005       </parameters>
9006       <errors>
9007         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
9008           Not monitor owner
9009         </error>
9010       </errors>
9011     </function>
9012 
9013     <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
9014       <synopsis>Raw Monitor Wait</synopsis>
9015       <description>
9016         Wait for notification of the raw monitor.
9017         <p/>
9018         Causes the current thread to wait until either another thread calls 
9019         <functionlink id="RawMonitorNotify"/> or 
9020         <functionlink id="RawMonitorNotifyAll"/> 
9021         for the specified raw monitor, or the specified
9022         <paramlink id="millis">timeout</paramlink>
9023         has elapsed.
9024       </description>
9025       <origin>jvmdi</origin>
9026       <capabilities>
9027       </capabilities>
9028       <parameters>
9029         <param id="monitor">
9030           <jrawMonitorID/>
9031           <description>
9032             The monitor
9033           </description>
9034         </param>
9035         <param id="millis">
9036           <jlong/>
9037           <description>
9038             The timeout, in milliseconds.  If the timeout is
9039             zero, then real time is not taken into consideration
9040             and the thread simply waits until notified.
9041           </description>
9042         </param>
9043       </parameters>
9044       <errors>
9045         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
9046           Not monitor owner
9047         </error>
9048         <error id="JVMTI_ERROR_INTERRUPT"> 
9049           Wait was interrupted, try again
9050         </error>
9051       </errors>
9052     </function>
9053 
9054     <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
9055       <synopsis>Raw Monitor Notify</synopsis>
9056       <description>
9057         Notify a single thread waiting on the raw monitor.
9058       </description>
9059       <origin>jvmdi</origin>
9060       <capabilities>
9061       </capabilities>
9062       <parameters>
9063         <param id="monitor">
9064           <jrawMonitorID/>
9065           <description>
9066             The monitor
9067           </description>
9068         </param>
9069       </parameters>
9070       <errors>
9071         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9072           Not monitor owner
9073         </error>
9074       </errors>
9075     </function>
9076 
9077     <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
9078       <synopsis>Raw Monitor Notify All</synopsis>
9079       <description>
9080         Notify all threads waiting on the raw monitor.
9081       </description>
9082       <origin>jvmdi</origin>
9083       <capabilities>
9084       </capabilities>
9085       <parameters>
9086         <param id="monitor">
9087           <jrawMonitorID/>
9088           <description>
9089             The monitor
9090           </description>
9091         </param>
9092       </parameters>
9093       <errors>
9094         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
9095           Not monitor owner
9096         </error>
9097       </errors>
9098     </function>
9099 
9100    <elide>
9101     <function id="GetRawMonitorUse" num="118">
9102       <synopsis>Get Raw Monitor Use</synopsis>
9103       <description>
9104         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 
9105         are filled in with information about usage of the raw monitor.
9106       </description>
9107       <origin>new</origin>
9108       <capabilities>
9109         <required id="can_get_raw_monitor_usage"></required>
9110       </capabilities>
9111       <parameters>
9112         <param id="monitor">
9113           <jrawMonitorID/>
9114           <description>
9115             the raw monitor to query.
9116           </description>
9117         </param>
9118         <param id="info_ptr">
9119           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
9120           <description>
9121             On return, filled with monitor information for the 
9122             specified raw monitor.
9123           </description>
9124         </param>
9125       </parameters>
9126       <errors>
9127       </errors>
9128     </function>
9129 
9130     <function id="GetRawMonitors" num="119">
9131       <synopsis>Get Raw Monitors</synopsis>
9132       <description>
9133         Return the list of raw monitors.
9134         <p/>
9135         Note: details about each monitor can be examined with 
9136         <functionlink id="GetRawMonitorUse"></functionlink>.
9137       </description>
9138       <origin>new</origin>
9139       <capabilities>
9140         <required id="can_get_raw_monitor_usage"></required>
9141       </capabilities>
9142       <parameters>
9143         <param id="monitorCnt">
9144           <outptr><jint/></outptr>
9145           <description>
9146             On return, pointer to the number 
9147             of monitors returned in <code>monitors_ptr</code>.
9148           </description>
9149         </param>
9150         <param id="monitors_ptr">
9151           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
9152           <description>
9153             On return, pointer to the monitor list.
9154           </description>
9155         </param>
9156       </parameters>
9157       <errors>
9158       </errors>
9159     </function>
9160     </elide>
9161   </category>
9162 
9163   <category id="jniIntercept" label="JNI Function Interception">
9164 
9165     <intro>
9166       Provides the ability to intercept and resend 
9167       Java Native Interface (JNI) function calls
9168       by manipulating the JNI function table.
9169       See <externallink id="docs/technotes/guides/jni/spec/functions.html">JNI
9170         Functions</externallink> in the <i>Java Native Interface Specification</i>.
9171       <p/>
9172       The following example illustrates intercepting the 
9173       <code>NewGlobalRef</code> JNI call in order to count reference
9174       creation.
9175       <example>
9176 JNIEnv original_jni_Functions;
9177 JNIEnv redirected_jni_Functions;
9178 int my_global_ref_count = 0;
9179 
9180 jobject
9181 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
9182    ++my_global_ref_count;
9183    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
9184 }
9185 
9186 void
9187 myInit() {
9188    jvmtiError err;
9189 
9190    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;original_jni_Functions);
9191    if (err != JVMTI_ERROR_NONE) {
9192       die();
9193    }
9194    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;redirected_jni_Functions);
9195    if (err != JVMTI_ERROR_NONE) {
9196       die();
9197    }
9198    redirectedJNIFunctions-&gt;NewGlobalRef = MyNewGlobalRef;
9199       err = (*jvmti_env)-&gt;SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
9200    if (err != JVMTI_ERROR_NONE) {
9201       die();
9202    }
9203 }
9204       </example>
9205       Sometime after <code>myInit</code> is called the user's JNI
9206       code is executed which makes the call to create a new global
9207       reference.  Instead of going to the normal JNI implementation
9208       the call goes to <code>myNewGlobalRef</code>.  Note that a
9209       copy of the original function table is kept so that the normal
9210       JNI function can be called after the data is collected.
9211       Note also that any JNI functions which are not overwritten
9212       will behave normally.
9213       <todo>
9214         check that the example compiles and executes.
9215       </todo>
9216     </intro>
9217     
9218     <function id="SetJNIFunctionTable" phase="start" num="120">
9219       <synopsis>Set JNI Function Table</synopsis>
9220       <description>
9221         Set the JNI function table 
9222         in all current and future JNI environments.
9223         As a result, all future JNI calls are directed to the specified functions.
9224         Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
9225         function table to pass to this function.
9226         For this function to take effect the the updated table entries must be 
9227         used by the JNI clients.
9228         Since the table is defined <code>const</code> some compilers may optimize
9229         away the access to the table, thus preventing this function from taking 
9230         effect.
9231         The table is copied--changes to the local copy of the
9232         table have no effect.
9233         This function affects only the function table, all other aspects of the environment are
9234         unaffected.
9235         See the examples <internallink id="jniIntercept">above</internallink>.
9236       </description>
9237       <origin>new</origin>
9238       <capabilities>
9239       </capabilities>
9240       <parameters>
9241         <param id="function_table">
9242           <inptr>
9243             <struct>jniNativeInterface</struct>
9244           </inptr>
9245           <description>
9246             Points to the new JNI function table.
9247           </description>
9248         </param>
9249       </parameters>
9250       <errors>
9251       </errors>
9252     </function>
9253     
9254     <function id="GetJNIFunctionTable" phase="start" num="121">
9255       <synopsis>Get JNI Function Table</synopsis>
9256       <description>
9257         Get the JNI function table.
9258         The JNI function table is copied into allocated memory.
9259         If <functionlink id="SetJNIFunctionTable"></functionlink> 
9260         has been called, the modified (not the original) function
9261         table is returned.
9262         Only the function table is copied, no other aspects of the environment 
9263         are copied.
9264         See the examples <internallink id="jniIntercept">above</internallink>.
9265       </description>
9266       <origin>new</origin>
9267       <capabilities>
9268       </capabilities>
9269       <parameters>
9270         <param id="function_table">
9271           <allocbuf>
9272             <struct>jniNativeInterface</struct>
9273           </allocbuf>
9274           <description>
9275             On return, <code>*function_table</code> 
9276             points a newly allocated copy of the JNI function table.
9277           </description>
9278         </param>
9279       </parameters>
9280       <errors>
9281       </errors>
9282     </function>
9283 
9284   </category>
9285 
9286   <category id="eventManagement" label="Event Management">
9287 
9288     <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
9289       <synopsis>Set Event Callbacks</synopsis>
9290       <description>
9291         Set the functions to be called for each event.
9292         The callbacks are specified by supplying a replacement function table.
9293         The function table is copied--changes to the local copy of the
9294         table have no effect.
9295         This is an atomic action, all callbacks are set at once.
9296         No events are sent before this function is called.
9297         When an entry is <code>NULL</code> or when the event is beyond 
9298         <paramlink id="size_of_callbacks"></paramlink> no event is sent.
9299         Details on events are 
9300         described <internallink id="EventSection">later</internallink> in this document.
9301         An event must be enabled and have a callback in order to be
9302         sent--the order in which this function and 
9303         <functionlink id="SetEventNotificationMode"></functionlink> 
9304         are called does not affect the result.
9305       </description>
9306       <origin>new</origin>
9307       <capabilities>
9308       </capabilities>
9309       <parameters>
9310         <param id="callbacks">
9311           <inptr>
9312             <struct>jvmtiEventCallbacks</struct>
9313             <nullok>remove the existing callbacks</nullok>
9314           </inptr>
9315           <description>
9316             The new event callbacks.
9317           </description>
9318         </param>
9319         <param id="size_of_callbacks">
9320           <jint min="0"/>
9321           <description>
9322             <code>sizeof(jvmtiEventCallbacks)</code>--for version
9323             compatibility.
9324           </description>
9325         </param>
9326       </parameters>
9327       <errors>
9328       </errors>
9329     </function>
9330 
9331     <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
9332       <synopsis>Set Event Notification Mode</synopsis>
9333       <description>
9334         Control the generation of events. 
9335         <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
9336           <constant id="JVMTI_ENABLE" num="1">
9337             If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, 
9338             the event <paramlink id="event_type"></paramlink> will be enabled
9339           </constant>
9340           <constant id="JVMTI_DISABLE" num="0">
9341             If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, 
9342             the event <paramlink id="event_type"></paramlink> will be disabled
9343           </constant>
9344         </constants>
9345         If <code>thread</code> is <code>NULL</code>,
9346         the event is enabled or disabled globally; otherwise, it is 
9347         enabled or disabled for a particular thread. 
9348         An event is generated for 
9349         a particular thread if it is enabled either at the thread or global
9350         levels. 
9351         <p/>
9352         See <internallink id="EventIndex">below</internallink> for information on specific events.
9353         <p/>
9354         The following events cannot be controlled at the thread
9355         level through this function. 
9356         <ul>
9357           <li><eventlink id="VMInit"></eventlink></li>
9358           <li><eventlink id="VMStart"></eventlink></li>
9359           <li><eventlink id="VMDeath"></eventlink></li>
9360           <li><eventlink id="ThreadStart"></eventlink></li>
9361           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9362           <li><eventlink id="CompiledMethodUnload"></eventlink></li>
9363           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9364           <li><eventlink id="DataDumpRequest"></eventlink></li>
9365         </ul>
9366         <p/>
9367         Initially, no events are enabled at either the thread level 
9368         or the global level.
9369         <p/>
9370         Any needed capabilities (see Event Enabling Capabilities below) must be possessed
9371         before calling this function.
9372         <p/>
9373         Details on events are 
9374         described <internallink id="EventSection">below</internallink>.
9375       </description>
9376       <origin>jvmdiClone</origin>
9377       <eventcapabilities></eventcapabilities>
9378       <parameters>
9379         <param id="mode">
9380           <enum>jvmtiEventMode</enum>
9381           <description>
9382             <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
9383           </description>
9384         </param>
9385         <param id="event_type">
9386           <enum>jvmtiEvent</enum>
9387           <description>
9388             the event to control
9389           </description>
9390         </param>
9391         <param id="event_thread">
9392           <ptrtype>
9393             <jthread impl="noconvert"/>
9394             <nullok>event is controlled at the global level</nullok>
9395           </ptrtype>
9396             <description>
9397               The thread to control
9398             </description>
9399         </param>
9400         <param id="...">
9401           <varargs/>
9402             <description>
9403               for future expansion
9404             </description>
9405         </param>
9406       </parameters>
9407       <errors>
9408         <error id="JVMTI_ERROR_INVALID_THREAD">
9409           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
9410         </error>
9411         <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
9412           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead).
9413         </error>
9414         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9415           thread level control was attempted on events which do not 
9416           permit thread level control.
9417         </error>
9418         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 
9419           The Required Event Enabling Capability is not possessed.
9420         </error>
9421       </errors>
9422     </function>
9423 
9424     <function id="GenerateEvents" num="123">
9425       <synopsis>Generate Events</synopsis>
9426       <description>
9427         Generate events to represent the current state of the VM.  
9428         For example, if <paramlink id="event_type"/> is 
9429         <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
9430         a <eventlink id="CompiledMethodLoad"></eventlink> event will be
9431         sent for each currently compiled method.
9432         Methods that were loaded and now have been unloaded are not sent.
9433         The history of what events have previously been sent does not 
9434         effect what events are sent by this function--for example, 
9435         all currently compiled methods
9436         will be sent each time this function is called.
9437         <p/>
9438         This function is useful when
9439         events may have been missed due to the agent attaching after program
9440         execution begins; this function generates the missed events.
9441         <p/>
9442         Attempts to execute Java programming language code or
9443         JNI functions may be paused until this function returns -
9444         so neither should be called from the thread sending the event.
9445         This function returns only after the missed events have been 
9446         sent, processed and have returned.
9447         The event may be sent on a different thread than the thread
9448         on which the event occurred.
9449         The callback for the event must be set with 
9450         <functionlink id="SetEventCallbacks"></functionlink> 
9451         and the event must be enabled with
9452         <functionlink id="SetEventNotificationMode"></functionlink> 
9453         or the events will not occur.
9454         If the VM no longer has the information to generate some or
9455         all of the requested events, the events are simply not sent -
9456         no error is returned.
9457         <p/>
9458         Only the following events are supported:
9459         <ul>
9460           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9461           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9462         </ul>
9463       </description>
9464       <origin>new</origin>
9465       <capabilities>
9466         <capability id="can_generate_compiled_method_load_events"></capability>
9467       </capabilities>
9468       <parameters>
9469         <param id="event_type">
9470           <enum>jvmtiEvent</enum>
9471           <description>
9472             The type of event to generate.  Must be one of these:
9473             <ul>
9474               <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
9475               <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
9476             </ul>
9477           </description>
9478         </param>
9479       </parameters>
9480       <errors>
9481         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 
9482           <paramlink id="event_type"/> is 
9483           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9484           and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
9485           is <code>false</code>.
9486         </error>
9487         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 
9488           <paramlink id="event_type"/> is other than
9489           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9490           or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
9491         </error>
9492       </errors>
9493     </function>
9494 
9495   </category>
9496 
9497     <category id="extension" label="Extension Mechanism">
9498 
9499       <intro>
9500         These functions
9501         allow a <jvmti/> implementation to provide functions and events
9502         beyond those defined in this specification.
9503         <p/>
9504         Both extension functions and extension events have parameters
9505         each of which has a 'type' and 'kind' chosen from the following tables:
9506 
9507         <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
9508           <constant id="JVMTI_TYPE_JBYTE" num="101">
9509             Java programming language primitive type - <code>byte</code>. 
9510             JNI type <code>jbyte</code>.
9511           </constant>
9512           <constant id="JVMTI_TYPE_JCHAR" num="102">
9513             Java programming language primitive type - <code>char</code>. 
9514             JNI type <code>jchar</code>.
9515           </constant>
9516           <constant id="JVMTI_TYPE_JSHORT" num="103">
9517             Java programming language primitive type - <code>short</code>. 
9518             JNI type <code>jshort</code>.
9519           </constant>
9520           <constant id="JVMTI_TYPE_JINT" num="104">
9521             Java programming language primitive type - <code>int</code>. 
9522             JNI type <datalink id="jint"></datalink>.
9523           </constant>
9524           <constant id="JVMTI_TYPE_JLONG" num="105">
9525             Java programming language primitive type - <code>long</code>. 
9526             JNI type <datalink id="jlong"></datalink>.
9527           </constant>
9528           <constant id="JVMTI_TYPE_JFLOAT" num="106">
9529             Java programming language primitive type - <code>float</code>. 
9530             JNI type <datalink id="jfloat"></datalink>.
9531           </constant>
9532           <constant id="JVMTI_TYPE_JDOUBLE" num="107">
9533             Java programming language primitive type - <code>double</code>. 
9534             JNI type <datalink id="jdouble"></datalink>.
9535           </constant>
9536           <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
9537             Java programming language primitive type - <code>boolean</code>. 
9538             JNI type <datalink id="jboolean"></datalink>.
9539           </constant>
9540           <constant id="JVMTI_TYPE_JOBJECT" num="109">
9541             Java programming language object type - <code>java.lang.Object</code>. 
9542             JNI type <datalink id="jobject"></datalink>.
9543             Returned values are JNI local references and must be managed.
9544           </constant>
9545           <constant id="JVMTI_TYPE_JTHREAD" num="110">
9546             Java programming language object type - <code>java.lang.Thread</code>. 
9547             <jvmti/> type <datalink id="jthread"></datalink>.
9548             Returned values are JNI local references and must be managed.
9549           </constant>
9550           <constant id="JVMTI_TYPE_JCLASS" num="111">
9551             Java programming language object type - <code>java.lang.Class</code>. 
9552             JNI type <datalink id="jclass"></datalink>.
9553             Returned values are JNI local references and must be managed.
9554           </constant>
9555           <constant id="JVMTI_TYPE_JVALUE" num="112">
9556             Union of all Java programming language primitive and object types - 
9557             JNI type <datalink id="jvalue"></datalink>.
9558             Returned values which represent object types are JNI local references and must be managed.
9559           </constant>
9560           <constant id="JVMTI_TYPE_JFIELDID" num="113">
9561             Java programming language field identifier - 
9562             JNI type <datalink id="jfieldID"></datalink>.
9563           </constant>
9564           <constant id="JVMTI_TYPE_JMETHODID" num="114">
9565             Java programming language method identifier - 
9566             JNI type <datalink id="jmethodID"></datalink>.
9567           </constant>
9568           <constant id="JVMTI_TYPE_CCHAR" num="115">
9569             C programming language type - <code>char</code>.
9570           </constant>
9571           <constant id="JVMTI_TYPE_CVOID" num="116">
9572             C programming language type - <code>void</code>.
9573           </constant>
9574           <constant id="JVMTI_TYPE_JNIENV" num="117">
9575             JNI environment - <code>JNIEnv</code>.
9576             Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
9577           </constant>
9578         </constants>
9579 
9580         <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
9581           <constant id="JVMTI_KIND_IN" num="91">
9582             Ingoing argument - <code>foo</code>.
9583           </constant>
9584           <constant id="JVMTI_KIND_IN_PTR" num="92">
9585             Ingoing pointer argument - <code>const foo*</code>.
9586           </constant>
9587           <constant id="JVMTI_KIND_IN_BUF" num="93">
9588             Ingoing array argument - <code>const foo*</code>.
9589           </constant>
9590           <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
9591             Outgoing allocated array argument -  <code>foo**</code>.
9592             Free with <code>Deallocate</code>.
9593           </constant>
9594           <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
9595             Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
9596             Free with <code>Deallocate</code>.
9597           </constant>
9598           <constant id="JVMTI_KIND_OUT" num="96">
9599             Outgoing argument - <code>foo*</code>.
9600           </constant>
9601           <constant id="JVMTI_KIND_OUT_BUF" num="97">
9602             Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
9603             Do not <code>Deallocate</code>.
9604           </constant>
9605         </constants>
9606 
9607       </intro>
9608 
9609       <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
9610         <field id="name">
9611           <allocfieldbuf><char/></allocfieldbuf>
9612             <description>
9613               The parameter name, encoded as a
9614               <internallink id="mUTF">modified UTF-8</internallink> string
9615             </description>
9616         </field>
9617         <field id="kind">
9618           <enum>jvmtiParamKind</enum>
9619           <description>
9620             The kind of the parameter - type modifiers
9621           </description>
9622         </field>
9623         <field id="base_type">
9624           <enum>jvmtiParamTypes</enum>
9625           <description>
9626             The base type of the parameter -  modified by <code>kind</code>
9627           </description>
9628         </field>
9629         <field id="null_ok">
9630           <jboolean/>
9631             <description>
9632               Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
9633             </description>
9634         </field>
9635       </typedef>
9636 
9637       <callback id="jvmtiExtensionFunction">
9638         <enum>jvmtiError</enum>
9639           <synopsis>Extension Function</synopsis>
9640         <description>
9641           This is the implementation-specific extension function.
9642         </description>
9643         <parameters>
9644           <param id="jvmti_env">
9645             <outptr>
9646               <struct>jvmtiEnv</struct>
9647             </outptr>
9648             <description>
9649               The <jvmti/> environment is the only fixed parameter for extension functions.
9650             </description>
9651           </param>
9652           <param id="...">
9653             <varargs/>
9654               <description>
9655                 The extension function-specific parameters
9656               </description>
9657           </param>
9658         </parameters>
9659       </callback>
9660 
9661       <function id="GetExtensionFunctions" phase="onload" num="124">
9662         <synopsis>Get Extension Functions</synopsis>
9663 
9664         <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
9665           <field id="func">
9666             <ptrtype>
9667               <struct>jvmtiExtensionFunction</struct>
9668             </ptrtype>
9669             <description>
9670               The actual function to call
9671             </description>
9672           </field>
9673           <field id="id">
9674             <allocfieldbuf><char/></allocfieldbuf>
9675               <description>
9676                 The identifier for the extension function, encoded as a
9677                 <internallink id="mUTF">modified UTF-8</internallink> string.
9678                 Uses package name conventions.
9679                 For example, <code>com.sun.hotspot.bar</code>
9680               </description>
9681           </field>
9682           <field id="short_description">
9683             <allocfieldbuf><char/></allocfieldbuf>
9684               <description>
9685                 A one sentence description of the function, encoded as a
9686                 <internallink id="mUTF">modified UTF-8</internallink> string.
9687               </description>
9688           </field>
9689           <field id="param_count">
9690             <jint/>
9691               <description>
9692                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9693               </description>
9694           </field>
9695           <field id="params">
9696             <allocfieldbuf outcount="param_count">
9697               <struct>jvmtiParamInfo</struct>
9698             </allocfieldbuf>
9699             <description>
9700               Array of 
9701               <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9702               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9703             </description>
9704           </field>
9705           <field id="error_count">
9706             <jint/>
9707               <description>
9708                 The number of possible error returns (excluding universal errors)
9709               </description>
9710           </field>
9711           <field id="errors">
9712             <allocfieldbuf outcount="error_count">
9713               <enum>jvmtiError</enum>
9714             </allocfieldbuf>
9715             <description>
9716               Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9717               possible errors
9718             </description>
9719           </field>
9720         </typedef>
9721 
9722         <description>
9723           Returns the set of extension functions.
9724         </description>
9725         <origin>new</origin>
9726         <capabilities>
9727         </capabilities>
9728         <parameters>
9729           <param id="extension_count_ptr">
9730             <outptr><jint/></outptr>
9731               <description>
9732                 On return, points to the number of extension functions
9733               </description>
9734           </param>
9735           <param id="extensions">
9736             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
9737             <description>
9738               Returns an array of extension function info, one per function
9739             </description>
9740           </param>
9741         </parameters>
9742         <errors>
9743         </errors>
9744       </function>
9745 
9746       <function id="GetExtensionEvents" phase="onload" num="125">
9747         <synopsis>Get Extension Events</synopsis>
9748 
9749         <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
9750           <field id="extension_event_index">
9751             <jint/>
9752             <description>
9753               The identifying index of the event
9754             </description>
9755           </field>
9756           <field id="id">
9757             <allocfieldbuf><char/></allocfieldbuf>
9758               <description>
9759                 The identifier for the extension event, encoded as a
9760                 <internallink id="mUTF">modified UTF-8</internallink> string.
9761                 Uses package name conventions.
9762                 For example, <code>com.sun.hotspot.bar</code>
9763               </description>
9764           </field>
9765           <field id="short_description">
9766             <allocfieldbuf><char/></allocfieldbuf>
9767               <description>
9768                 A one sentence description of the event, encoded as a
9769                 <internallink id="mUTF">modified UTF-8</internallink> string.
9770               </description>
9771           </field>
9772           <field id="param_count">
9773             <jint/>
9774               <description>
9775                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9776               </description>
9777           </field>
9778           <field id="params">
9779             <allocfieldbuf outcount="param_count">
9780               <struct>jvmtiParamInfo</struct>
9781             </allocfieldbuf>
9782             <description>
9783               Array of 
9784               <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
9785               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9786             </description>
9787           </field>
9788         </typedef>
9789 
9790         <description>
9791           Returns the set of extension events.
9792         </description>
9793         <origin>new</origin>
9794         <capabilities>
9795         </capabilities>
9796         <parameters>
9797           <param id="extension_count_ptr">
9798             <outptr><jint/></outptr>
9799               <description>
9800                 On return, points to the number of extension events
9801               </description>
9802           </param>
9803           <param id="extensions">
9804             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
9805             <description>
9806               Returns an array of extension event info, one per event
9807             </description>
9808           </param>
9809         </parameters>
9810         <errors>
9811         </errors>
9812       </function>
9813 
9814       <callback id="jvmtiExtensionEvent">
9815         <void/>
9816           <synopsis>Extension Event</synopsis>
9817         <description>
9818           This is the implementation-specific event.
9819           The event handler is set with 
9820           <functionlink id="SetExtensionEventCallback"/>.
9821           <p/>
9822           Event handlers for extension events must be declared varargs to match this definition.
9823           Failure to do so could result in calling convention mismatch and undefined behavior
9824           on some platforms.
9825           <p/>
9826           For example, if the <code>jvmtiParamInfo</code>
9827           returned by <functionlink id="GetExtensionEvents"/> indicates that
9828           there is a <code>jint</code> parameter, the event handler should be
9829           declared:
9830 <example>
9831     void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...)
9832 </example>
9833           Note the terminal "<code>...</code>" which indicates varargs.
9834         </description>
9835         <parameters>
9836           <param id="jvmti_env">
9837             <outptr>
9838               <struct>jvmtiEnv</struct>
9839             </outptr>
9840             <description>
9841               The <jvmti/> environment is the only fixed parameter for extension events.
9842             </description>
9843           </param>
9844           <param id="...">
9845             <varargs/>
9846               <description>
9847                 The extension event-specific parameters
9848               </description>
9849           </param>
9850         </parameters>
9851       </callback>
9852 
9853       <function id="SetExtensionEventCallback" phase="onload" num="126">
9854         <synopsis>Set Extension Event Callback</synopsis>
9855 
9856         <description>
9857           Sets the callback function for an extension event and
9858           enables the event. Or, if the callback is <code>NULL</code>, disables
9859           the event.  Note that unlike standard events, setting
9860           the callback and enabling the event are a single operation.
9861         </description>
9862         <origin>new</origin>
9863         <capabilities>
9864         </capabilities>
9865         <parameters>
9866           <param id="extension_event_index">
9867             <jint/>
9868               <description>
9869                 Identifies which callback to set.
9870                 This index is the 
9871                 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
9872                 field of 
9873                 <datalink id="jvmtiExtensionEventInfo"/>.
9874               </description>
9875           </param>
9876           <param id="callback">
9877             <ptrtype>
9878               <struct>jvmtiExtensionEvent</struct>
9879               <nullok>disable the event</nullok>
9880             </ptrtype>
9881             <description>
9882               If <code>callback</code> is non-<code>NULL</code>, 
9883               set <code>callback</code> to be the event callback function
9884               and enable the event.
9885             </description>
9886           </param>
9887         </parameters>
9888         <errors>
9889         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 
9890             <paramlink id="extension_event_index"/> is not an
9891             <fieldlink id="extension_event_index" 
9892                        struct="jvmtiExtensionEventInfo"/>
9893             returned by 
9894             <functionlink id="GetExtensionEvents"/>
9895         </error>
9896         </errors>
9897       </function>
9898 
9899     </category>
9900 
9901   <category id="capability" label="Capability">
9902 
9903     <intro>
9904       The capabilities functions allow you to change the
9905       functionality available to <jvmti/>--that is, 
9906       which <jvmti/> 
9907       functions can be called, what events can be generated,
9908       and what functionality these events and functions can
9909       provide.
9910       <p/>
9911         The "Capabilities" section of each function and event describe which 
9912         capabilities, if any, they are associated with. "Required Functionality"
9913         means it is available for use and no capabilities must be added to use it.
9914         "Optional Functionality" means the agent must possess the capability
9915         before it can be used.  
9916         To possess a capability, the agent must
9917         <functionlink id="AddCapabilities">add the capability</functionlink>.
9918         "Optional Features" describe capabilities which,
9919         if added, extend the feature set.
9920         <p/>
9921         The potentially available capabilities of each <jvmti/> implementation are different.  
9922         Depending on the implementation, a capability:
9923         <ul>
9924           <li>may never be added</li>
9925           <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
9926           <li>may be added only during the <code>OnLoad</code> phase</li>
9927           <li>may be possessed by only one environment at a time</li>
9928           <li>may be possessed by only one environment at a time, 
9929               and only during the <code>OnLoad</code> phase</li>
9930           <li>and so on ...</li>
9931         </ul>
9932       Frequently, the addition of a capability may incur a cost in execution speed, start up
9933       time, and/or memory footprint.  Note that the overhead of using a capability
9934       is completely different than the overhead of possessing a capability.
9935       Take single stepping as an example. When single stepping is on (that
9936       is, when the event is enabled and thus actively sending events) 
9937       the overhead of sending and processing an event 
9938       on each instruction is huge in any implementation. 
9939       However, the overhead of possessing the capability may be small or large, 
9940       depending on the implementation.  Also, when and if a capability is potentially
9941       available depends on the implementation.  Some examples:
9942       <ul>
9943         <li>One VM might perform all execution by compiling bytecodes into 
9944           native code and be unable to generate single step instructions.
9945           In this implementation the capability can not be added.</li>
9946         <li>Another VM may be able to switch execution to a single stepping
9947           interpreter at any time.  In this implementation, having the capability has no 
9948           overhead and could be added at any time.</li>
9949         <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
9950           execution engine at start up, but be unable to switch between them.
9951           In this implementation the capability would need to be added 
9952           during the <code>OnLoad</code> phase (before bytecode
9953           execution begins) and would have a large impact on execution speed 
9954           even if single stepping was never used.</li>
9955         <li>Still another VM might be able to add an "is single stepping on" check
9956           into compiled bytecodes or a generated interpreter.  Again in this implementation
9957           the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
9958           and branch on each instruction) would be considerably less.</li>
9959       </ul>
9960       <p/>
9961       Each <jvmti/> <internallink id="environments">environment</internallink>
9962       has its own set of capabilities.  
9963       Initially, that set is empty.
9964       Any desired capability must be added.
9965       If possible, capabilities should be added during the <code>OnLoad</code> phase.  For most 
9966       virtual machines certain capabilities require special set up for 
9967       the virtual machine and this set up must happen
9968       during the <code>OnLoad</code> phase, before the virtual machine begins execution. 
9969       Once a capability is added, it can
9970       only be removed if explicitly relinquished by the environment.
9971       <p/>
9972       The agent can, 
9973       <functionlink id="GetPotentialCapabilities">determine what
9974         capabilities this VM can potentially provide</functionlink>,
9975       <functionlink id="AddCapabilities">add the capabilities
9976         to be used</functionlink>,
9977       <functionlink id="RelinquishCapabilities">release capabilities
9978         which are no longer needed</functionlink>, and
9979       <functionlink id="GetCapabilities">examine the currently available 
9980         capabilities</functionlink>.
9981     </intro>
9982 
9983     <intro id="capabilityExamples" label="Capability Examples">
9984       For example, a freshly started agent (in the <code>OnLoad</code> function)
9985       wants to enable all possible capabilities.  
9986       Note that, in general, this is not advisable as the agent may suffer
9987       a performance penalty for functionality it is not using.
9988       The code might look like this in C:
9989       <example>
9990         jvmtiCapabilities capa;
9991         jvmtiError err;
9992 
9993         err = (*jvmti)-&gt;GetPotentialCapabilities(jvmti, &amp;capa);
9994         if (err == JVMTI_ERROR_NONE) {
9995            err = (*jvmti)-&gt;AddCapabilities(jvmti, &amp;capa);
9996       </example>
9997       For example, if an  agent wants to check if it can get
9998       the bytecodes of a method (that is, it wants to check 
9999       if it previously added this capability and has not 
10000       relinquished it), the code might 
10001       look like this in C:
10002       <example>
10003         jvmtiCapabilities capa;
10004         jvmtiError err;
10005 
10006         err = (*jvmti)-&gt;GetCapabilities(jvmti, &amp;capa);
10007         if (err == JVMTI_ERROR_NONE) {
10008            if (capa.can_get_bytecodes) { ... } } 
10009       </example>
10010     </intro>
10011 
10012     <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
10013       <description>
10014         The functions in this category use this capabilities structure 
10015         which contains boolean flags corresponding to each capability:
10016       </description>
10017       <capabilityfield id="can_tag_objects">
10018         <description>
10019           Can set and get tags, as described in the
10020           <internallink id="Heap">Heap category</internallink>.
10021         </description>
10022       </capabilityfield>
10023       <capabilityfield id="can_generate_field_modification_events">
10024         <description>
10025           Can set watchpoints on field modification -
10026           <functionlink id="SetFieldModificationWatch"></functionlink>
10027         </description>
10028       </capabilityfield>
10029       <capabilityfield id="can_generate_field_access_events">
10030         <description>
10031           Can set watchpoints on field access -
10032           <functionlink id="SetFieldAccessWatch"></functionlink>
10033         </description>
10034       </capabilityfield>
10035       <capabilityfield id="can_get_bytecodes">
10036         <description>
10037           Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
10038         </description>
10039       </capabilityfield>
10040       <capabilityfield id="can_get_synthetic_attribute">
10041         <description>
10042           Can test if a field or method is synthetic - 
10043           <functionlink id="IsFieldSynthetic"></functionlink> and
10044           <functionlink id="IsMethodSynthetic"></functionlink>
10045         </description>
10046       </capabilityfield>
10047       <capabilityfield id="can_get_owned_monitor_info">
10048         <description>
10049           Can get information about ownership of monitors - 
10050           <functionlink id="GetOwnedMonitorInfo"></functionlink>
10051         </description>
10052       </capabilityfield>
10053       <capabilityfield id="can_get_current_contended_monitor">
10054         <description>
10055           Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
10056         </description>
10057       </capabilityfield>
10058       <capabilityfield id="can_get_monitor_info">
10059       <description>
10060         Can <functionlink id="GetObjectMonitorUsage"></functionlink>
10061       </description>
10062       </capabilityfield>
10063       <capabilityfield id="can_pop_frame">
10064         <description>
10065           Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
10066         </description>
10067       </capabilityfield>
10068       <capabilityfield id="can_redefine_classes">
10069         <description>
10070           Can redefine classes with <functionlink id="RedefineClasses"/>.
10071         </description>
10072       </capabilityfield>
10073       <capabilityfield id="can_signal_thread">
10074         <description>
10075           Can send stop or interrupt to threads
10076         </description>
10077       </capabilityfield>
10078       <capabilityfield id="can_get_source_file_name">
10079         <description>
10080           Can get the source file name of a class
10081         </description>
10082       </capabilityfield>
10083       <capabilityfield id="can_get_line_numbers">
10084         <description>
10085           Can get the line number table of a method
10086         </description>
10087       </capabilityfield>
10088       <capabilityfield id="can_get_source_debug_extension">
10089         <description>
10090           Can get the source debug extension of a class
10091         </description>
10092       </capabilityfield>
10093       <capabilityfield id="can_access_local_variables">
10094         <description>
10095           Can set and get local variables
10096         </description>
10097       </capabilityfield>
10098       <capabilityfield id="can_maintain_original_method_order">
10099         <description>
10100           Can return methods in the order they occur in the class file
10101         </description>
10102       </capabilityfield>
10103       <capabilityfield id="can_generate_single_step_events">
10104         <description>
10105           Can get <eventlink id="SingleStep">single step</eventlink> events
10106         </description>
10107       </capabilityfield>
10108       <capabilityfield id="can_generate_exception_events">
10109         <description>
10110           Can get <eventlink id="Exception">exception thrown</eventlink> and 
10111             <eventlink id="ExceptionCatch">exception catch</eventlink> events
10112         </description>
10113       </capabilityfield>
10114       <capabilityfield id="can_generate_frame_pop_events">
10115         <description>
10116           Can <functionlink id="NotifyFramePop">set</functionlink> and thus get 
10117             <eventlink id="FramePop"></eventlink> events
10118         </description>
10119       </capabilityfield>
10120       <capabilityfield id="can_generate_breakpoint_events">
10121         <description>
10122           Can <functionlink id="SetBreakpoint">set</functionlink> and thus get 
10123             <eventlink id="Breakpoint"></eventlink> events
10124         </description>
10125       </capabilityfield>
10126       <capabilityfield id="can_suspend">
10127         <description>
10128           Can suspend and resume threads
10129         </description>
10130       </capabilityfield>
10131       <capabilityfield id="can_redefine_any_class">
10132         <description>
10133           Can modify (retransform or redefine) any modifiable class.
10134           See <functionlink id="IsModifiableClass"/>.
10135         </description>
10136       </capabilityfield>
10137       <capabilityfield id="can_get_current_thread_cpu_time">
10138         <description>
10139           Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
10140           current thread CPU time
10141         </description>
10142       </capabilityfield>
10143       <capabilityfield id="can_get_thread_cpu_time">
10144         <description>
10145           Can <functionlink id="GetThreadCpuTime">get</functionlink>
10146           thread CPU time
10147         </description>
10148       </capabilityfield>
10149       <capabilityfield id="can_generate_method_entry_events" 
10150                        disp1="can_generate" disp2="_method_entry_events" 
10151                        >
10152         <description>
10153           Can generate method entry events on entering a method
10154         </description>
10155       </capabilityfield>
10156       <capabilityfield id="can_generate_method_exit_events" 
10157                        disp1="can_generate" disp2="_method_exit_events" 
10158                        >
10159         <description>
10160           Can generate method exit events on leaving a method
10161         </description>
10162       </capabilityfield>
10163       <capabilityfield id="can_generate_all_class_hook_events" 
10164                        disp1="can_generate" disp2="_all_class_hook_events" 
10165                        >
10166         <description>
10167           Can generate ClassFileLoadHook events for every loaded class.
10168         </description>
10169       </capabilityfield>
10170       <capabilityfield id="can_generate_compiled_method_load_events" 
10171                        disp1="can_generate" disp2="_compiled_method_load_events" 
10172                        >
10173         <description>
10174           Can generate events when a method is compiled or unloaded
10175         </description>
10176       </capabilityfield>
10177       <capabilityfield id="can_generate_monitor_events" 
10178                        disp1="can_generate" disp2="_monitor_events" 
10179                        >
10180         <description>
10181           Can generate events on monitor activity
10182         </description>
10183       </capabilityfield>
10184       <capabilityfield id="can_generate_vm_object_alloc_events" 
10185                        disp1="can_generate" disp2="_vm_object_alloc_events" 
10186                        >
10187         <description>
10188           Can generate events on VM allocation of an object
10189         </description>
10190       </capabilityfield>
10191       <capabilityfield id="can_generate_native_method_bind_events" 
10192                        disp1="can_generate" disp2="_native_method_bind_events" 
10193                        >
10194         <description>
10195           Can generate events when a native method is bound to its
10196           implementation
10197         </description>
10198       </capabilityfield>
10199       <capabilityfield id="can_generate_garbage_collection_events" 
10200                        disp1="can_generate" disp2="_garbage_collection_events" 
10201                        >
10202         <description>
10203           Can generate events when garbage collection begins or ends
10204         </description>
10205       </capabilityfield>
10206       <capabilityfield id="can_generate_object_free_events" 
10207                        disp1="can_generate" disp2="_object_free_events" 
10208                        >
10209         <description>
10210           Can generate events when the garbage collector frees an object
10211         </description>
10212       </capabilityfield>
10213       <capabilityfield id="can_force_early_return" since="1.1">
10214         <description>
10215           Can return early from a method, as described in the
10216           <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
10217         </description>
10218       </capabilityfield>
10219       <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
10220         <description>
10221           Can get information about owned monitors with stack depth -
10222           <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
10223         </description>
10224       </capabilityfield>
10225       <capabilityfield id="can_get_constant_pool" since="1.1">
10226         <description>
10227           Can get the constant pool of a class -
10228           <functionlink id="GetConstantPool"></functionlink>
10229         </description>
10230       </capabilityfield>
10231       <capabilityfield id="can_set_native_method_prefix" since="1.1">
10232         <description>
10233           Can set prefix to be applied when native method cannot be resolved -
10234           <functionlink id="SetNativeMethodPrefix"/> and
10235           <functionlink id="SetNativeMethodPrefixes"/>
10236         </description>
10237       </capabilityfield>
10238       <capabilityfield id="can_retransform_classes" since="1.1">
10239         <description>
10240           Can retransform classes with <functionlink id="RetransformClasses"/>.
10241           In addition to the restrictions imposed by the specific 
10242           implementation on this capability (see the
10243           <internallink id="capability">Capability</internallink> section),
10244           this capability must be set before the 
10245           <eventlink id="ClassFileLoadHook"/> event is enabled for the
10246           first time in this environment.
10247           An environment that possesses this capability at the time that 
10248           <code>ClassFileLoadHook</code> is enabled for the first time is
10249           said to be <i>retransformation capable</i>.
10250           An environment that does not possess this capability at the time that 
10251           <code>ClassFileLoadHook</code> is enabled for the first time is
10252           said to be <i>retransformation incapable</i>.
10253         </description>
10254       </capabilityfield>
10255       <capabilityfield id="can_retransform_any_class" since="1.1">
10256         <description>
10257           <functionlink id="RetransformClasses"/> can be called on any modifiable class.
10258           See <functionlink id="IsModifiableClass"/>.
10259           (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
10260           must also be set)
10261         </description>
10262       </capabilityfield>
10263       <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
10264         <description>
10265           Can generate events when the VM is unable to allocate memory from 
10266           the <tm>Java</tm> platform heap.
10267           See <eventlink id="ResourceExhausted"/>.
10268         </description>
10269       </capabilityfield>
10270       <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
10271         <description>
10272           Can generate events when the VM is unable to create a thread.
10273           See <eventlink id="ResourceExhausted"/>.
10274         </description>
10275       </capabilityfield>
10276       <capabilityfield id="can_generate_early_vmstart" since="9">
10277         <description>
10278           Can generate the <code>VMStart</code> event early.
10279           See <eventlink id="VMStart"/>.
10280         </description>
10281       </capabilityfield>
10282       <capabilityfield id="can_generate_early_class_hook_events" since="9">
10283         <description>
10284           Can generate the <eventlink id="ClassFileLoadHook"/> events
10285           in the primordial phase. If this capability and
10286           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10287           <code>can_generate_all_class_hook_events</code></internallink>
10288           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10289           can be posted for classes loaded in the primordial phase.
10290           See <eventlink id="ClassFileLoadHook"/>.
10291         </description>
10292       </capabilityfield>
10293     </capabilitiestypedef>
10294 
10295     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10296       <synopsis>Get Potential Capabilities</synopsis>
10297       <description>
10298         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> 
10299         features that can potentially be possessed by this environment
10300         at this time.
10301         The returned capabilities differ from the complete set of capabilities
10302         implemented by the VM in two cases: another environment possesses 
10303         capabilities that can only be possessed by one environment, or the
10304         current <functionlink id="GetPhase">phase</functionlink> is live,
10305         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10306         The <functionlink id="AddCapabilities"></functionlink> function
10307         may be used to set any or all or these capabilities.
10308         Currently possessed capabilities are included.
10309         <p/>
10310         Typically this function is used in the <code>OnLoad</code> function.
10311         Some virtual machines may allow a limited set of capabilities to be
10312         added in the live phase.
10313         In this case, the set of potentially available capabilities
10314         will likely differ from the <code>OnLoad</code> phase set.
10315         <p/>
10316         See the
10317         <internallink id="capabilityExamples">Capability Examples</internallink>.
10318       </description>
10319       <origin>new</origin>
10320       <capabilities>
10321       </capabilities>
10322       <parameters>
10323         <param id="capabilities_ptr">
10324           <outptr><struct>jvmtiCapabilities</struct></outptr>
10325           <description>
10326             On return, points to the <jvmti/> capabilities that may be added.
10327           </description>
10328         </param>
10329       </parameters>
10330       <errors>
10331       </errors>
10332     </function>
10333 
10334     <elide>
10335     <function id="EstimateCostOfCapabilities" phase="onload" num="141">
10336       <synopsis>Estimate Cost Of Capabilities</synopsis>
10337       <description>
10338         <issue>There is strong opposition to this function.  The concern is
10339           that it would be difficult or impossible to provide meaningful
10340           numbers, as the amount of impact is conditional on many factors
10341           that a single number could not represent.  There is doubt that
10342           conditional implementations would be used or are even a good idea.
10343           The thought is that release documentation for the implementation
10344           would be the best means of exposing this information.
10345           Unless new arguments are presented, I intend to remove this 
10346           function in the next revision.
10347         </issue>
10348         <p/>
10349         Return via the <paramlink id="time_impact_ptr"></paramlink> and
10350         <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
10351         of adding the capabilities pointed to by
10352         <paramlink id="capabilities_ptr"></paramlink>.
10353         The returned estimates are in percentage of additional overhead, thus
10354         a time impact of 100 mean the application might run
10355         at half the speed.  
10356         The estimates are very rough approximations and are not guaranteed.
10357         Note also, that the estimates are of the impact of having the
10358         capability available--when and if it is used the impact may be
10359         much greater.
10360         Estimates can be for a single capability or for a set of 
10361         capabilities.  Note that the costs are not necessarily additive,
10362         adding support for one capability might make another available 
10363         for free or conversely having two capabilities at once may 
10364         have multiplicative impact.
10365         Estimates are relative to the current set of capabilities -
10366         that is, how much more impact given the currently possessed capabilities.
10367         <p/>
10368         Typically this function is used in the OnLoad function,
10369         some virtual machines may allow a limited set of capabilities to be
10370         added in the live phase.
10371         In this case, the set of potentially available capabilities
10372         will likely differ from the OnLoad phase set.
10373         <p/>
10374         See the
10375         <internallink id="capabilityExamples">Capability Examples</internallink>.
10376       </description>
10377       <origin>new</origin>
10378       <capabilities>
10379       </capabilities>
10380       <parameters>
10381         <param id="capabilities_ptr">
10382           <inptr><struct>jvmtiCapabilities</struct></inptr>
10383           <description>
10384             points to the <jvmti/> capabilities to evaluate.
10385           </description>
10386         </param>
10387         <param id="time_impact_ptr">
10388           <outptr><jint/></outptr>
10389           <description>
10390             On return, points to the estimated percentage increase in
10391             run time if this capability was added.
10392           </description>
10393         </param>
10394         <param id="space_impact_ptr">
10395           <outptr><jint/></outptr>
10396           <description>
10397             On return, points to the estimated percentage increase in
10398             memory space used if this capability was added.
10399           </description>
10400         </param>
10401       </parameters>
10402       <errors>
10403         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10404           The desired capabilities are not even potentially available.
10405         </error>
10406       </errors>
10407     </function>
10408     </elide>
10409 
10410     <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
10411       <synopsis>Add Capabilities</synopsis>
10412       <description>
10413         Set new capabilities by adding the capabilities 
10414         whose values are set to one (<code>1</code>) in
10415         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10416         All previous capabilities are retained.
10417         Typically this function is used in the <code>OnLoad</code> function.
10418         Some virtual machines may allow a limited set of capabilities to be
10419         added in the live phase.
10420         <p/>
10421         See the
10422         <internallink id="capabilityExamples">Capability Examples</internallink>.
10423       </description>
10424       <origin>new</origin>
10425       <capabilities>
10426       </capabilities>
10427       <parameters>
10428         <param id="capabilities_ptr">
10429           <inptr><struct>jvmtiCapabilities</struct></inptr>
10430           <description>
10431             Points to the <jvmti/> capabilities to add.
10432           </description>
10433         </param>
10434       </parameters>
10435       <errors>
10436         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10437           The desired capabilities are not even potentially available.
10438         </error>
10439       </errors>
10440     </function>
10441 
10442 
10443     <function id="RelinquishCapabilities" phase="onload" num="143">
10444       <synopsis>Relinquish Capabilities</synopsis>
10445       <description>
10446         Relinquish the capabilities
10447         whose values are set to one (<code>1</code>) in
10448         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10449         Some implementations may allow only one environment to have a capability
10450         (see the <internallink id="capability">capability introduction</internallink>).
10451         This function releases capabilities
10452         so that they may be used by other agents.
10453         All other capabilities are retained.
10454         The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
10455         Attempting to relinquish a capability that the agent does not possess is not an error.
10456           <issue>
10457             It is possible for the agent to be actively using capabilities
10458             which are being relinquished.  For example, a thread is currently
10459             suspended and can_suspend is being relinquished or an event is currently
10460             enabled and can_generate_whatever is being relinquished.
10461             There are three possible ways we could spec this:
10462             <ul>
10463               <li>relinquish automatically releases them</li>
10464               <li>relinquish checks and returns some error code if held</li>
10465               <li>it is the agent's responsibility and it is not checked</li>
10466             </ul>
10467             One of these should be chosen.
10468           </issue>
10469       </description>
10470       <origin>new</origin>
10471       <capabilities>
10472       </capabilities>
10473       <parameters>
10474         <param id="capabilities_ptr">
10475           <inptr><struct>jvmtiCapabilities</struct></inptr>
10476           <description>
10477             Points to the <jvmti/> capabilities to relinquish.
10478           </description>
10479         </param>
10480       </parameters>
10481       <errors>
10482       </errors>
10483     </function>
10484 
10485 
10486 
10487     <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
10488       <synopsis>Get Capabilities</synopsis>
10489         <description>
10490           Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> 
10491           features which this environment currently possesses.
10492           Each possessed capability is indicated by a one (<code>1</code>) in the
10493           corresponding field of the <internallink id="jvmtiCapabilities">capabilities
10494           structure</internallink>.
10495           An environment does not possess a capability unless it has been successfully added with
10496           <functionlink id="AddCapabilities"/>.
10497           An environment only loses possession of a capability if it has been relinquished with
10498           <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
10499           of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
10500           have been made.
10501           <p/>
10502           See the
10503           <internallink id="capabilityExamples">Capability Examples</internallink>.
10504         </description>
10505       <origin>jvmdiClone</origin>
10506       <capabilities>
10507       </capabilities>
10508       <parameters>
10509         <param id="capabilities_ptr">
10510           <outptr><struct>jvmtiCapabilities</struct></outptr>
10511           <description>
10512             On return, points to the <jvmti/> capabilities.
10513           </description>
10514         </param>
10515       </parameters>
10516       <errors>
10517       </errors>
10518     </function>
10519 
10520   </category>
10521   
10522   
10523   <category id="timers" label="Timers">
10524 
10525       <intro>
10526         These functions provide timing information.
10527         The resolution at which the time is updated is not specified. 
10528         They provides nanosecond precision, but not necessarily nanosecond accuracy. 
10529         Details about the timers, such as their maximum values, can be accessed with
10530         the timer information functions.  
10531       </intro>
10532 
10533       <typedef id="jvmtiTimerInfo" label="Timer Info">
10534         <description>
10535           The information function for each timer returns this data structure.
10536         </description>
10537         <field id="max_value">
10538           <jlong/>
10539             <description>
10540               The maximum value the timer can reach.
10541               After this value is reached the timer wraps back to zero.
10542               This is an unsigned value.  If tested or printed as a jlong (signed value)
10543               it may appear to be a negative number.
10544             </description>
10545         </field>
10546         <field id="may_skip_forward">
10547           <jboolean/>
10548           <description>
10549             If true, the timer can be externally adjusted and as a result skip forward.
10550             If false, the timer value will never increase faster than real time.
10551           </description>
10552         </field>
10553         <field id="may_skip_backward">
10554           <jboolean/>
10555           <description>
10556             If true, the timer can be externally adjusted and as a result skip backward.
10557             If false, the timer value will be monotonically increasing.
10558           </description>
10559         </field>
10560         <field id="kind">
10561           <enum>jvmtiTimerKind</enum>
10562           <description>
10563             The kind of timer.
10564             On a platform that does not distinguish between user and system time, <datalink 
10565                  id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
10566             is returned.
10567           </description>
10568         </field>
10569         <field id="reserved1">
10570           <jlong/>
10571             <description>
10572               Reserved for future use.
10573             </description>
10574         </field>
10575         <field id="reserved2">
10576           <jlong/>
10577             <description>
10578               Reserved for future use.
10579             </description>
10580         </field>
10581       </typedef>
10582 
10583       <intro>
10584         Where the timer kind is --
10585 
10586         <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
10587           <constant id="JVMTI_TIMER_USER_CPU" num="30">
10588             CPU time that a thread is in user mode.
10589           </constant>
10590           <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
10591             CPU time that a thread is in user or system mode.
10592           </constant>
10593           <constant id="JVMTI_TIMER_ELAPSED" num="32">
10594             Elapsed time.
10595           </constant>
10596         </constants>
10597       </intro>
10598 
10599     <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe"  impl="innative notrace" phase="start" num="134">
10600       <synopsis>Get Current Thread CPU Timer Information</synopsis>
10601       <description>
10602         Get information about the 
10603         <functionlink id="GetCurrentThreadCpuTime"/> timer. 
10604         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10605         are filled in with details about the timer.
10606         This information is specific to the platform and the implementation of
10607         <functionlink id="GetCurrentThreadCpuTime"/> and thus 
10608         does not vary by thread nor does it vary
10609         during a particular invocation of the VM.
10610         <p/>
10611         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10612         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10613         returned by <code>GetCurrentThreadCpuTimerInfo</code>
10614         and <functionlink id="GetThreadCpuTimerInfo"/>
10615         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10616       </description>
10617       <origin>new</origin>
10618       <capabilities>
10619         <required id="can_get_current_thread_cpu_time">
10620             Can get current thread CPU time.
10621         </required>
10622       </capabilities>
10623       <parameters>
10624         <param id="info_ptr">
10625           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10626           <description>
10627             On return, filled with information describing the time
10628             returned by <functionlink id="GetCurrentThreadCpuTime"/>.
10629           </description>
10630         </param>
10631       </parameters>
10632       <errors>
10633       </errors>
10634     </function>
10635 
10636     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10637       <synopsis>Get Current Thread CPU Time</synopsis>
10638       <description>
10639             Return the CPU time utilized by the current thread.  
10640             <p/>
10641             Note that the <functionlink id="GetThreadCpuTime"/>
10642             function provides CPU time for any thread, including
10643             the current thread. <code>GetCurrentThreadCpuTime</code> 
10644             exists to support platforms which cannot
10645             supply CPU time for threads other than the current 
10646             thread or which have more accurate information for
10647             the current thread (see 
10648             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10649             <functionlink id="GetThreadCpuTimerInfo"/>).
10650             On many platforms this call will be equivalent to:
10651 <example>
10652   GetThreadCpuTime(env, NULL, nanos_ptr)
10653 </example>
10654       </description>
10655       <origin>new</origin>
10656       <capabilities>
10657         <required id="can_get_current_thread_cpu_time">
10658             Can get current thread CPU time.
10659             <p/>
10660             If this capability is enabled after threads have started, 
10661             the implementation may choose any time up
10662             to and including the time that the capability is enabled 
10663             as the point where CPU time collection starts.
10664             <p/>
10665             This capability must be potentially available on any 
10666             platform where 
10667             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10668             is potentially available.
10669         </required>
10670       </capabilities>
10671       <parameters>
10672         <param id="nanos_ptr">
10673           <outptr><jlong/></outptr>
10674           <description>
10675             On return, points to the CPU time used by this thread
10676             in nanoseconds.  
10677             This is an unsigned value.  If tested or printed as a jlong (signed value)
10678             it may appear to be a negative number.
10679           </description>
10680         </param>
10681       </parameters>
10682       <errors>
10683       </errors>
10684     </function>
10685 
10686     <function id="GetThreadCpuTimerInfo" num="136">
10687       <synopsis>Get Thread CPU Timer Information</synopsis>
10688       <description>
10689         Get information about the 
10690         <functionlink id="GetThreadCpuTime"/> timer. 
10691         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10692         are filled in with details about the timer.
10693         This information is specific to the platform and the implementation of
10694         <functionlink id="GetThreadCpuTime"/> and thus 
10695         does not vary by thread nor does it vary
10696         during a particular invocation of the VM.
10697         <p/>
10698         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10699         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10700         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
10701         and <code>GetThreadCpuTimerInfo</code>
10702         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10703       </description>
10704       <origin>new</origin>
10705       <capabilities>
10706         <required id="can_get_thread_cpu_time">
10707             Can get thread CPU time.
10708         </required>
10709       </capabilities>
10710       <parameters>
10711         <param id="info_ptr">
10712           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10713           <description>
10714             On return, filled with information describing the time
10715             returned by <functionlink id="GetThreadCpuTime"/>.
10716           </description>
10717         </param>
10718       </parameters>
10719       <errors>
10720       </errors>
10721     </function>
10722 
10723     <function id="GetThreadCpuTime" num="137">
10724       <synopsis>Get Thread CPU Time</synopsis>
10725       <description>
10726           Return the CPU time utilized by the specified thread. 
10727           <p/>
10728           Get information about this timer with
10729           <functionlink id="GetThreadCpuTimerInfo"/>. 
10730       </description>
10731       <origin>new</origin>
10732       <capabilities>
10733         <required id="can_get_thread_cpu_time">
10734             Can get thread CPU time.
10735             <p/>
10736             If this capability is enabled after threads have started, 
10737             the implementation may choose any time up
10738             to and including the time that the capability is enabled 
10739             as the point where CPU time collection starts.
10740         </required>
10741       </capabilities>
10742       <parameters>
10743         <param id="thread">
10744           <jthread null="current"/>
10745             <description>
10746               The thread to query.
10747             </description>
10748         </param>
10749         <param id="nanos_ptr">
10750           <outptr><jlong/></outptr>
10751           <description>
10752             On return, points to the CPU time used by the specified thread
10753             in nanoseconds.  
10754             This is an unsigned value.  If tested or printed as a jlong (signed value)
10755             it may appear to be a negative number.
10756           </description>
10757         </param>
10758       </parameters>
10759       <errors>
10760       </errors>
10761     </function>
10762 
10763     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
10764       <synopsis>Get Timer Information</synopsis>
10765       <description>
10766         Get information about the 
10767         <functionlink id="GetTime"/> timer. 
10768         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10769         are filled in with details about the timer.
10770         This information will not change during a particular invocation of the VM.
10771       </description>
10772       <origin>new</origin>
10773       <capabilities>
10774       </capabilities>
10775       <parameters>
10776         <param id="info_ptr">
10777           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10778           <description>
10779             On return, filled with information describing the time
10780             returned by <functionlink id="GetTime"/>.
10781           </description>
10782         </param>
10783       </parameters>
10784       <errors>
10785       </errors>
10786     </function>
10787 
10788     <function id="GetTime" phase="any" callbacksafe="safe" num="139">
10789       <synopsis>Get Time</synopsis>
10790       <description>
10791           Return the current value of the system timer, in nanoseconds. 
10792           <p/>
10793           The value returned represents nanoseconds since some fixed but
10794           arbitrary time (perhaps in the future, so values may be
10795           negative).  This function provides nanosecond precision, but not
10796           necessarily nanosecond accuracy. No guarantees are made about
10797           how frequently values change.
10798           <p/>
10799           Get information about this timer with
10800           <functionlink id="GetTimerInfo"/>. 
10801       </description>
10802       <origin>new</origin>
10803       <capabilities>
10804       </capabilities>
10805       <parameters>
10806         <param id="nanos_ptr">
10807           <outptr><jlong/></outptr>
10808           <description>
10809             On return, points to the time in nanoseconds.  
10810             This is an unsigned value.  If tested or printed as a jlong (signed value)
10811             it may appear to be a negative number.
10812           </description>
10813         </param>
10814       </parameters>
10815       <errors>
10816       </errors>
10817     </function>
10818 
10819     <function id="GetAvailableProcessors" phase="any" num="144">
10820       <synopsis>Get Available Processors</synopsis>
10821       <description>
10822           Returns the number of processors available to the Java virtual machine.
10823           <p/>
10824           This value may change during a particular invocation of the virtual machine. 
10825           Applications that are sensitive to the number of available processors should
10826           therefore occasionally poll this property.
10827       </description>
10828       <origin>new</origin>
10829       <capabilities>
10830       </capabilities>
10831       <parameters>
10832         <param id="processor_count_ptr">
10833           <outptr><jint/></outptr>
10834           <description>
10835             On return, points to the maximum number of processors available to the
10836             virtual machine; never smaller than one.  
10837           </description>
10838         </param>
10839       </parameters>
10840       <errors>
10841       </errors>
10842     </function>
10843 
10844   </category>
10845 
10846 
10847   <category id="classLoaderSearch" label="Class Loader Search">
10848 
10849     <intro>
10850       These functions allow the agent to add to the locations that a class loader searches for a class.
10851       This is useful for installing instrumentation under the correct class loader.
10852     </intro>
10853 
10854     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
10855       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
10856       <description>
10857           This function can be used to cause instrumentation classes to be defined by the 
10858           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
10859           After the bootstrap
10860           class loader unsuccessfully searches for a class, the specified platform-dependent 
10861           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in 
10862           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, 
10863           the segments will be searched in the order that this function was called.
10864           <p/>
10865           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10866           search path segment to be searched after the bootstrap class loader unsuccessfully searches
10867           for a class. The segment is typically a directory or JAR file.
10868           <p/>      
10869           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
10870           path to a <externallink id="docs/technotes/guides/jar/jar.html">
10871           JAR file</externallink>. The agent should take care that the JAR file does not
10872           contain any classes or resources other than those to be defined by the bootstrap
10873           class loader for the purposes of instrumentation.
10874           <p/>
10875           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10876           reference that the Java virtual machine has previously unsuccessfully attempted
10877           to resolve always fails with the same error that was thrown as a result of the
10878           initial resolution attempt. Consequently, if the JAR file contains an entry
10879           that corresponds to a class for which the Java virtual machine has
10880           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10881           resolve that reference will fail with the same error as the initial attempt.
10882       </description>
10883       <origin>new</origin>
10884       <capabilities>
10885       </capabilities>
10886       <parameters>
10887         <param id="segment">
10888           <inbuf><char/></inbuf>
10889           <description>
10890             The platform-dependent search path segment, encoded as a
10891             <internallink id="mUTF">modified UTF-8</internallink> string.
10892           </description>
10893         </param>
10894       </parameters>
10895       <errors>
10896         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">   
10897           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10898            existing JAR file is an invalid path.
10899         </error>
10900       </errors>
10901     </function>
10902 
10903     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
10904       <synopsis>Add To System Class Loader Search</synopsis>
10905       <description>
10906           This function can be used to cause instrumentation classes to be
10907           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
10908           After the class loader unsuccessfully searches for a class, the specified platform-dependent search 
10909           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the 
10910           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the 
10911           segments will be searched in the order that this function was called.
10912           <p/>
10913           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10914           search path segment to be searched after the system class loader unsuccessfully searches
10915           for a class. The segment is typically a directory or JAR file.
10916           <p/>      
10917           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a
10918           <externallink id="docs/technotes/guides/jar/jar.html">JAR file</externallink> to be
10919           searched after the system class loader unsuccessfully searches for a class. The agent should
10920           take care that the JAR file does not contain any classes or resources other than those to be
10921           defined by the system class loader for the purposes of instrumentation.
10922           <p/>
10923           In the live phase the system class loader supports adding a JAR file to be searched if
10924           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> 
10925           which takes a single parameter of type <code>java.lang.String</code>. The method is not required 
10926           to have <code>public</code> access. 
10927           <p/>
10928           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10929           reference that the Java virtual machine has previously unsuccessfully attempted
10930           to resolve always fails with the same error that was thrown as a result of the
10931           initial resolution attempt. Consequently, if the JAR file contains an entry
10932           that corresponds to a class for which the Java virtual machine has
10933           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10934           resolve that reference will fail with the same error as the initial attempt.
10935       </description>
10936       <origin>new</origin>
10937       <capabilities>
10938       </capabilities>
10939       <parameters>
10940         <param id="segment">
10941           <inbuf><char/></inbuf>
10942           <description>
10943             The platform-dependent search path segment, encoded as a
10944             <internallink id="mUTF">modified UTF-8</internallink> string.
10945           </description>
10946         </param>
10947       </parameters>
10948       <errors>
10949         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
10950           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10951            existing JAR file is an invalid path.
10952         </error>
10953         <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
10954           Operation not supported by the system class loader.
10955         </error>                                                                                         
10956       </errors>
10957     </function>
10958 
10959   </category>
10960 
10961 
10962   <category id="props" label="System Properties">
10963 
10964     <intro>
10965       These functions get and set system properties.
10966     </intro>
10967 
10968     <function id="GetSystemProperties" phase="onload" num="130">
10969       <synopsis>Get System Properties</synopsis>
10970       <description>
10971         The list of VM system property keys which may be used with 
10972         <functionlink id="GetSystemProperty"/> is returned.
10973         It is strongly recommended that virtual machines provide the
10974         following property keys:
10975         <ul>
10976           <li><code>java.vm.vendor</code></li>
10977           <li><code>java.vm.version</code></li>
10978           <li><code>java.vm.name</code></li>
10979           <li><code>java.vm.info</code></li>
10980           <li><code>java.library.path</code></li>
10981           <li><code>java.class.path</code></li>
10982         </ul>
10983         Provides access to system properties defined by and used
10984         by the VM.
10985         Properties set on the command-line are included.
10986         This allows getting and setting of these properties 
10987         before the VM even begins executing bytecodes.
10988         Since this is a VM view of system properties, the set of available 
10989         properties will usually be different than that
10990         in <code>java.lang.System.getProperties</code>.
10991         JNI method invocation may be used to access 
10992         <code>java.lang.System.getProperties</code>.
10993         <p/>
10994         The set of properties may grow during execution.          
10995       </description>
10996       <origin>new</origin>
10997       <capabilities>
10998       </capabilities>
10999       <parameters>
11000         <param id="count_ptr">
11001           <outptr><jint/></outptr>
11002           <description>
11003             On return, points to the number of property keys returned.
11004           </description>
11005         </param>
11006         <param id="property_ptr">
11007           <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
11008           <description>
11009             On return, points to an array of property keys, encoded as 
11010             <internallink id="mUTF">modified UTF-8</internallink> strings.
11011           </description>
11012         </param>
11013       </parameters>
11014       <errors>
11015       </errors>
11016     </function>
11017 
11018     <function id="GetSystemProperty" phase="onload" num="131">
11019       <synopsis>Get System Property</synopsis>
11020       <description>
11021         Return a VM system property value given the property key.  
11022         <p/>
11023         The function <functionlink id="GetSystemProperties"/>
11024         returns the set of property keys which may be used.
11025         The properties which can be retrieved may grow during
11026         execution.
11027         <p/>
11028         Since this is a VM view of system properties, the values 
11029         of properties may differ from that returned by 
11030         <code>java.lang.System.getProperty(String)</code>.
11031         A typical VM might copy the values of the VM system 
11032         properties into the <code>Properties</code> held by
11033         <code>java.lang.System</code> during the initialization
11034         of that class. Thereafter any changes to the VM system
11035         properties (with <functionlink id="SetSystemProperty"/>) 
11036         or the <code>java.lang.System</code> system properties
11037         (with <code>java.lang.System.setProperty(String,String)</code>)
11038         would cause the values to diverge.
11039         JNI method invocation may be used to access 
11040         <code>java.lang.System.getProperty(String)</code>.
11041       </description>
11042       <origin>new</origin>
11043       <capabilities>
11044       </capabilities>
11045       <parameters>
11046         <param id="property">
11047           <inbuf><char/></inbuf>
11048           <description>
11049             The key of the property to retrieve, encoded as a
11050             <internallink id="mUTF">modified UTF-8</internallink> string.
11051           </description>
11052         </param>
11053         <param id="value_ptr">
11054           <allocbuf><char/></allocbuf>
11055           <description>
11056             On return, points to the property value, encoded as a
11057             <internallink id="mUTF">modified UTF-8</internallink> string.
11058           </description>
11059         </param>
11060       </parameters>
11061       <errors>
11062         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
11063           This property is not available.
11064           Use <functionlink id="GetSystemProperties"/> to find available properties.
11065         </error>
11066       </errors>
11067     </function>
11068 
11069     <function id="SetSystemProperty" phase="onloadOnly" num="132">
11070       <synopsis>Set System Property</synopsis>
11071       <description>
11072         Set a VM system property value.  
11073         <p/>
11074         The function <functionlink id="GetSystemProperties"/>
11075         returns the set of property keys, some of these may be settable.
11076         See <functionlink id="GetSystemProperty"/>.
11077       </description>
11078       <origin>new</origin>
11079       <capabilities>
11080       </capabilities>
11081       <parameters>
11082         <param id="property">
11083           <inbuf><char/></inbuf>
11084           <description>
11085             The key of the property, encoded as a
11086             <internallink id="mUTF">modified UTF-8</internallink> string.
11087           </description>
11088         </param>
11089         <param id="value_ptr">
11090           <inbuf>
11091             <char/>
11092             <nullok>
11093               do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
11094               if the property is not writeable
11095             </nullok>
11096           </inbuf>
11097           <description>
11098             The property value to set, encoded as a
11099             <internallink id="mUTF">modified UTF-8</internallink> string.
11100           </description>
11101         </param>
11102       </parameters>
11103       <errors>
11104         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
11105           This property is not available or is not writeable.
11106         </error>
11107       </errors>
11108     </function>
11109 
11110   </category>
11111 
11112   <category id="general" label="General">
11113 
11114     <intro>
11115     </intro>
11116 
11117     <function id="GetPhase" jkernel="yes" phase="any" num="133">
11118       <synopsis>Get Phase</synopsis>
11119       <description>
11120           Return the current phase of VM execution.  
11121           The phases proceed in sequence:
11122           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
11123             <constant id="JVMTI_PHASE_ONLOAD" num="1">
11124               <code>OnLoad</code> phase: while in the
11125               <internallink id="onload"><code>Agent_OnLoad</code></internallink>
11126               or, for statically linked agents, the <internallink id="onload">
11127               <code>Agent_OnLoad_&lt;agent-lib-name&gt;
11128               </code></internallink> function.
11129             </constant>
11130             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
11131               Primordial phase: between return from <code>Agent_OnLoad</code>
11132               or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> and the
11133               <code>VMStart</code> event.
11134             </constant>
11135             <constant id="JVMTI_PHASE_START" num="6">
11136               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event 
11137               is sent and until the <code>VMInit</code> event is sent.
11138             </constant>
11139             <constant id="JVMTI_PHASE_LIVE" num="4">
11140               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
11141               and until the <eventlink id="VMDeath"></eventlink> event returns.
11142             </constant>
11143             <constant id="JVMTI_PHASE_DEAD" num="8">
11144               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
11145               start-up failure.
11146             </constant>
11147           </constants>
11148           In the case of start-up failure the VM will proceed directly to the dead
11149           phase skipping intermediate phases and neither a <code>VMInit</code> nor
11150           <code>VMDeath</code> event will be sent.
11151           <p/>
11152           Most <jvmti/> functions operate only in the live phase.
11153           The following functions operate in either the <code>OnLoad</code> or live phases:
11154           <functionphaselist phase="onload"/>
11155           The following functions operate in only the <code>OnLoad</code> phase:
11156           <functionphaselist phase="onloadOnly"/>
11157           The following functions operate in the start or live phases:
11158           <functionphaselist phase="start"/>
11159           The following functions operate in any phase:
11160           <functionphaselist phase="any"/>
11161           JNI functions (except the Invocation API) must only be used in the start or live phases.
11162           <p/>
11163           Most <jvmti/> events are sent only in the live phase.
11164           The following events operate in others phases:
11165           <eventphaselist phase="start"/>          
11166           <eventphaselist phase="any"/>          
11167       </description>
11168       <origin>new</origin>
11169       <capabilities>
11170       </capabilities>
11171       <parameters>
11172         <param id="phase_ptr">
11173           <outptr><enum>jvmtiPhase</enum></outptr>
11174           <description>
11175             On return, points to the phase.
11176           </description>
11177         </param>
11178       </parameters>
11179       <errors>
11180       </errors>
11181     </function>
11182 
11183     <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
11184       <synopsis>Dispose Environment</synopsis>
11185       <description>
11186         Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
11187         (see <internallink id="environments"><jvmti/> Environments</internallink>).
11188         Dispose of any resources held by the environment.  
11189         <issue>
11190             What resources are reclaimed? What is undone?
11191             Breakpoints,watchpoints removed?
11192         </issue>
11193         Threads suspended by this environment are not resumed by this call,
11194         this must be done explicitly by the agent.
11195         Memory allocated by this environment via calls to <jvmti/> functions
11196         is not released, this can be done explicitly by the agent
11197         by calling <functionlink id="Deallocate"/>.
11198         Raw monitors created by this environment are not destroyed, 
11199         this can be done explicitly by the agent
11200         by calling <functionlink id="DestroyRawMonitor"/>.
11201         The state of threads waiting on raw monitors created by this environment
11202         are not affected.
11203         <p/>
11204         Any <functionlink id="SetNativeMethodPrefix">native method
11205         prefixes</functionlink> for this environment will be unset;
11206         the agent must remove any prefixed native methods before
11207         dispose is called.
11208         <p/>
11209         Any <internallink id="capability">capabilities</internallink>
11210         held by this environment are relinquished.
11211         <p/>
11212         Events enabled by this environment will no longer be sent, however
11213         event handlers currently running will continue to run.  Caution must
11214         be exercised in the design of event handlers whose environment may
11215         be disposed and thus become invalid during their execution.
11216         <p/>
11217         This environment may not be used after this call.
11218         This call returns to the caller.
11219       </description>
11220       <origin>new</origin>
11221       <capabilities>
11222       </capabilities>
11223       <parameters>
11224       </parameters>
11225       <errors>
11226       </errors>
11227     </function>
11228 
11229     <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
11230       <synopsis>Set Environment Local Storage</synopsis>
11231       <description>
11232         The VM stores a pointer value associated with each environment.
11233         This pointer value is called <i>environment-local storage</i>.
11234         This value is <code>NULL</code> unless set with this function.
11235         Agents can allocate memory in which they store environment specific
11236         information. By setting environment-local storage it can then be
11237         accessed with 
11238         <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
11239         <p/>
11240         Called by the agent to set the value of the <jvmti/>
11241         environment-local storage. <jvmti/> supplies to the agent a pointer-size
11242         environment-local storage that can be used to record per-environment
11243         information.
11244       </description>
11245       <origin>new</origin>
11246       <capabilities>
11247       </capabilities>
11248       <parameters>
11249         <param id="data">
11250           <inbuf> 
11251             <void/> 
11252             <nullok>value is set to <code>NULL</code></nullok> 
11253           </inbuf> 
11254           <description>
11255             The value to be entered into the environment-local storage.
11256           </description>
11257         </param>
11258       </parameters>
11259       <errors>
11260       </errors>
11261     </function>
11262 
11263     <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
11264       <synopsis>Get Environment Local Storage</synopsis>
11265       <description>
11266         Called by the agent to get the value of the <jvmti/> environment-local
11267         storage. 
11268       </description>
11269       <origin>new</origin>
11270       <capabilities>
11271       </capabilities>
11272       <parameters>
11273         <param id="data_ptr">
11274           <agentbuf><void/></agentbuf>
11275           <description>
11276             Pointer through which the value of the environment local 
11277             storage is returned.
11278             If environment-local storage has not been set with
11279             <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned 
11280             pointer is <code>NULL</code>.
11281           </description>
11282         </param>
11283       </parameters>
11284       <errors>
11285       </errors>
11286     </function>
11287 
11288     <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
11289       <synopsis>Get Version Number</synopsis>
11290       <description>
11291         Return the <jvmti/> version via <code>version_ptr</code>.
11292         The return value is the version identifier. 
11293         The version identifier includes major, minor and micro
11294         version as well as the interface type.
11295         <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
11296           <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
11297             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
11298           </constant>
11299           <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
11300             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
11301           </constant>
11302         </constants>
11303         <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
11304           <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
11305             Mask to extract interface type.  
11306             The value of the version returned by this function masked with
11307             <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
11308             <code>JVMTI_VERSION_INTERFACE_JVMTI</code> 
11309             since this is a <jvmti/> function.
11310           </constant>
11311           <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
11312             Mask to extract major version number.
11313           </constant>
11314           <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
11315             Mask to extract minor version number.
11316           </constant>
11317           <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
11318             Mask to extract micro version number.
11319           </constant>
11320         </constants>
11321         <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
11322           <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
11323             Shift to extract major version number.
11324           </constant>
11325           <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
11326             Shift to extract minor version number.
11327           </constant>
11328           <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
11329             Shift to extract micro version number.
11330           </constant>
11331         </constants>
11332       </description>
11333       <origin>jvmdi</origin>
11334       <capabilities>
11335       </capabilities>
11336       <parameters>
11337         <param id="version_ptr">
11338           <outptr><jint/></outptr>
11339           <description>
11340             On return, points to the <jvmti/> version.
11341           </description>
11342         </param>
11343       </parameters>
11344       <errors>
11345       </errors>
11346     </function>
11347 
11348 
11349     <function id="GetErrorName" phase="any" num="128">
11350       <synopsis>Get Error Name</synopsis>
11351       <description>
11352         Return the symbolic name for an 
11353           <internallink id="ErrorSection">error code</internallink>.  
11354         <p/>
11355         For example 
11356         <code>GetErrorName(env, JVMTI_ERROR_NONE, &amp;err_name)</code> 
11357         would return in <code>err_name</code> the string
11358         <code>"JVMTI_ERROR_NONE"</code>.
11359       </description>
11360       <origin>new</origin>
11361       <capabilities>
11362       </capabilities>
11363       <parameters>
11364         <param id="error">
11365           <enum>jvmtiError</enum>
11366           <description>
11367             The error code.
11368           </description>
11369         </param>
11370         <param id="name_ptr">
11371           <allocbuf><char/></allocbuf>
11372           <description>
11373             On return, points to the error name.
11374             The name is encoded as a
11375             <internallink id="mUTF">modified UTF-8</internallink> string,
11376             but is restricted to the ASCII subset.
11377           </description>
11378         </param>
11379       </parameters>
11380       <errors>
11381       </errors>
11382     </function>
11383 
11384     <function id="SetVerboseFlag" phase="any" num="150">
11385       <synopsis>Set Verbose Flag</synopsis>
11386       <description>
11387         <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
11388           <constant id="JVMTI_VERBOSE_OTHER" num="0">
11389             Verbose output other than the below.
11390           </constant>
11391           <constant id="JVMTI_VERBOSE_GC" num="1">
11392             Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
11393           </constant>
11394           <constant id="JVMTI_VERBOSE_CLASS" num="2">
11395             Verbose class loading output, like that specified with <code>-verbose:class</code>.
11396           </constant>
11397           <constant id="JVMTI_VERBOSE_JNI" num="4">
11398             Verbose JNI output, like that specified with <code>-verbose:jni</code>.
11399           </constant>
11400         </constants>
11401         Control verbose output.
11402         This is the output which typically is sent to <code>stderr</code>. 
11403       </description>
11404       <origin>new</origin>
11405       <capabilities>
11406       </capabilities>
11407       <parameters>
11408         <param id="flag">
11409           <enum>jvmtiVerboseFlag</enum>
11410           <description>
11411             Which verbose flag to set.
11412           </description>
11413         </param>
11414         <param id="value">
11415           <jboolean/>
11416           <description>
11417             New value of the flag.
11418           </description>
11419         </param>
11420       </parameters>
11421       <errors>
11422       </errors>
11423     </function>
11424 
11425 
11426     <function id="GetJLocationFormat" phase="any" num="129">
11427       <synopsis>Get JLocation Format</synopsis>
11428       <description>
11429         Although the greatest functionality is achieved with location information
11430         referencing the virtual machine bytecode index, the definition of
11431         <code>jlocation</code> has intentionally been left unconstrained to allow VM 
11432         implementations that do not have this information.
11433         <p/>
11434         This function describes the representation of <code>jlocation</code> used in this VM.
11435         If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, 
11436         <code>jlocation</code>s can
11437         be used as in indices into the array returned by
11438         <functionlink id="GetBytecodes"></functionlink>.  
11439         <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
11440           <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
11441             <code>jlocation</code> values represent virtual machine 
11442             bytecode indices--that is, offsets into the 
11443             virtual machine code for a method.
11444           </constant>
11445           <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
11446             <code>jlocation</code> values represent native machine
11447             program counter values.
11448           </constant>
11449           <constant id="JVMTI_JLOCATION_OTHER" num="0">
11450             <code>jlocation</code> values have some other representation.
11451           </constant>
11452         </constants>
11453       </description>
11454       <origin>new</origin>
11455       <capabilities>
11456       </capabilities>
11457       <parameters>
11458         <param id="format_ptr">
11459           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11460           <description>
11461             On return, points to the format identifier for <code>jlocation</code> values.
11462           </description>
11463         </param>
11464       </parameters>
11465       <errors>
11466       </errors>
11467     </function>
11468 
11469   </category>
11470 
11471 </functionsection>
11472 
11473 <errorsection label="Error Reference">
11474   <intro>
11475     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11476     <p/>
11477     It is the responsibility of the agent to call <jvmti/> functions with 
11478     valid parameters and in the proper context (calling thread is attached,
11479     phase is correct, etc.).  
11480     Detecting some error conditions may be difficult, inefficient, or 
11481     impossible for an implementation.
11482     The errors listed in 
11483     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11484     must be detected by the implementation.
11485     All other errors represent the recommended response to the error
11486     condition. 
11487   </intro>
11488 
11489   <errorcategory id="universal-error" label="Universal Errors">
11490     <intro>
11491       The following errors may be returned by any function
11492     </intro>
11493 
11494     <errorid id="JVMTI_ERROR_NONE" num="0">
11495       No error has occurred.  This is the error code that is returned
11496       on successful completion of the function.
11497     </errorid>
11498     <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
11499       Pointer is unexpectedly <code>NULL</code>.
11500     </errorid>
11501     <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
11502       The function attempted to allocate memory and no more memory was 
11503       available for allocation.
11504     </errorid>
11505     <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
11506       The desired functionality has not been enabled in this virtual machine.
11507     </errorid>
11508     <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
11509       The thread being used to call this function is not attached
11510       to the virtual machine.  Calls must be made from attached threads.
11511       See <code>AttachCurrentThread</code> in the JNI invocation API.
11512     </errorid>
11513     <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
11514       The <jvmti/> environment provided is no longer connected or is
11515       not an environment.
11516     </errorid>
11517     <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
11518       The desired functionality is not available in the current
11519         <functionlink id="GetPhase">phase</functionlink>.
11520       Always returned if the virtual machine has completed running.
11521     </errorid>
11522     <errorid id="JVMTI_ERROR_INTERNAL" num="113">
11523       An unexpected internal error has occurred.
11524     </errorid>
11525   </errorcategory>
11526 
11527   <errorcategory id="reqerrors" label="Function Specific Required Errors">
11528     <intro>
11529       The following errors are returned by some <jvmti/> functions and must
11530       be returned by the implementation when the condition occurs.
11531     </intro>
11532 
11533     <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
11534       Invalid priority.
11535     </errorid>
11536     <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
11537       Thread was not suspended.
11538     </errorid>
11539     <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
11540       Thread already suspended.
11541     </errorid>
11542     <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
11543       This operation requires the thread to be alive--that is,
11544       it must be started and not yet have died.
11545     </errorid>
11546     <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
11547       The class has been loaded but not yet prepared.
11548     </errorid>
11549     <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
11550       There are no Java programming language or JNI stack frames at the specified depth.
11551     </errorid>
11552     <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
11553       Information about the frame is not available (e.g. for native frames).
11554     </errorid>
11555     <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
11556       Item already set.
11557     </errorid>
11558     <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
11559       Desired element (e.g. field or breakpoint) not found
11560     </errorid>
11561     <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
11562       This thread doesn't own the raw monitor.
11563     </errorid>
11564     <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
11565       The call has been interrupted before completion.
11566     </errorid>
11567     <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
11568       The class cannot be modified.
11569     </errorid>
11570     <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
11571       The functionality is not available in this virtual machine.
11572     </errorid>
11573     <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
11574       The requested information is not available.
11575     </errorid>
11576     <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
11577       The specified event type ID is not recognized.
11578     </errorid>
11579     <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
11580       The requested information is not available for native method.
11581     </errorid>
11582     <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
11583       The class loader does not support this operation.
11584     </errorid>
11585   </errorcategory>
11586 
11587   <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
11588     <intro>
11589       The following errors are returned by some <jvmti/> functions.
11590       They are returned in the event of invalid parameters passed by the
11591       agent or usage in an invalid context.  
11592       An implementation is not required to detect these errors.
11593     </intro>
11594 
11595     <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
11596       The passed thread is not a valid thread.
11597     </errorid>
11598     <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
11599       Invalid field.
11600     </errorid>
11601     <errorid id="JVMTI_ERROR_INVALID_MODULE" num="26">
11602       Invalid module.
11603     </errorid>
11604     <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
11605       Invalid method.
11606     </errorid>
11607     <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
11608       Invalid location.
11609     </errorid>
11610     <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
11611       Invalid object.
11612     </errorid>
11613     <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
11614       Invalid class.
11615     </errorid>
11616     <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
11617       The variable is not an appropriate type for the function used.
11618     </errorid>
11619     <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
11620       Invalid slot.
11621     </errorid>
11622     <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
11623       The capability being used is false in this environment.
11624     </errorid>
11625     <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
11626       Thread group invalid.
11627     </errorid>
11628     <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
11629       Invalid raw monitor.
11630     </errorid>
11631     <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
11632       Illegal argument.
11633     </errorid>
11634     <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
11635       The state of the thread has been modified, and is now inconsistent.
11636     </errorid>
11637     <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
11638       A new class file has a version number not supported by this VM.
11639     </errorid>
11640     <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
11641       A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
11642     </errorid>
11643     <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
11644       The new class file definitions would lead to a circular
11645       definition (the VM would return a <code>ClassCircularityError</code>).
11646     </errorid>
11647     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
11648       A new class file would require adding a method.
11649     </errorid>
11650     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
11651       A new class version changes a field.
11652     </errorid>
11653     <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
11654       The class bytes fail verification.
11655     </errorid>
11656     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
11657       A direct superclass is different for the new class
11658       version, or the set of directly implemented
11659       interfaces is different.
11660     </errorid>
11661     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
11662       A new class version does not declare a method
11663       declared in the old class version.
11664     </errorid>
11665     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
11666       The class name defined in the new class file is 
11667       different from the name in the old class object.
11668     </errorid>
11669     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
11670       A new class version has different modifiers.
11671     </errorid>
11672     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
11673       A method in the new class version has different modifiers
11674       than its counterpart in the old class version.
11675     </errorid>
11676   </errorcategory>
11677 </errorsection>
11678 
11679 <eventsection label="Events">
11680   <intro label="Handling Events" id="eventIntro">
11681     Agents can be informed of many events that occur in application
11682     programs.
11683     <p/>
11684     To handle events, designate a set of callback functions with
11685     <functionlink id="SetEventCallbacks"></functionlink>. 
11686     For each event the corresponding callback function will be 
11687     called.
11688     Arguments to the callback function provide additional
11689     information about the event. 
11690     <p/>
11691     The callback function is usually called from within an application 
11692     thread. The <jvmti/> implementation does not 
11693     queue events in any way. This means
11694     that event callback functions must be written 
11695     carefully. Here are some general guidelines. See 
11696     the individual event descriptions for further
11697     suggestions.
11698     <p/>
11699     <ul>
11700       <li>Any exception thrown during the execution of an event callback can 
11701         overwrite any current pending exception in the current application thread.
11702         Care must be taken to preserve a pending exception
11703         when an event callback makes a JNI call that might generate an exception.
11704       </li>
11705       <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
11706         not queue events. If an agent needs to process events one at a time, it 
11707         can use a raw monitor inside the 
11708         event callback functions to serialize event processing.
11709       </li>
11710       <li>Event callback functions that execute JNI's FindClass function to load
11711         classes need to note that FindClass locates the class loader associated 
11712         with the current native method. For the purposes of class loading, an
11713         event callback that includes a JNI environment as a parameter to the
11714         callback will treated as if it is a native call, where the native method
11715         is in the class of the event thread's current frame.
11716       </li>
11717     </ul>
11718     <p/>
11719     Some <jvmti/> events identify objects with JNI references. 
11720     All references 
11721     in <jvmti/> events are JNI local references and will become invalid
11722     after the event callback returns.
11723     Unless stated otherwise, memory referenced by pointers sent in event
11724     callbacks may not be referenced after the event callback returns.
11725     <p/>
11726     Except where stated otherwise, events are delivered on the thread
11727     that caused the event.
11728     Events are sent at the time they occur.
11729     The specification for each event includes the set of
11730     <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
11731     if an event triggering activity occurs during another phase, no event 
11732     is sent. 
11733     <p/>
11734     A thread that generates an event does not change its execution status
11735     (for example, the event does not cause the thread to be suspended).
11736     If an agent wishes the event to result in suspension, then the agent
11737     is responsible for explicitly suspending the thread with 
11738     <functionlink id="SuspendThread"></functionlink>.
11739     <p/>
11740     If an event is enabled in multiple environments, the event will be sent
11741     to each agent in the order that the environments were created.
11742   </intro>
11743 
11744   <intro label="Enabling Events" id="enablingevents">
11745     All events are initially disabled.  In order to receive any
11746     event:
11747       <ul>
11748         <li>
11749           If the event requires a capability, that capability must
11750           be added with 
11751           <functionlink id="AddCapabilities"></functionlink>.
11752         </li>
11753         <li>
11754           A callback for the event must be set with 
11755           <functionlink id="SetEventCallbacks"></functionlink>.
11756         </li>
11757         <li>
11758           The event must be enabled with
11759           <functionlink id="SetEventNotificationMode"></functionlink>. 
11760         </li>
11761       </ul>
11762   </intro>
11763 
11764   <intro label="Multiple Co-located Events" id="eventorder">
11765     In many situations it is possible for multiple events to occur 
11766     at the same location in one thread. When this happens, all the events 
11767     are reported through the event callbacks in the order specified in this section.
11768     <p/>
11769     If the current location is at the entry point of a method, the 
11770     <eventlink id="MethodEntry"></eventlink> event is reported before
11771     any other event at the current location in the same thread.
11772     <p/>
11773     If an exception catch has been detected at the current location,
11774     either because it is the beginning of a catch clause or a native method
11775     that cleared a pending exception has returned, the
11776     <code>exceptionCatch</code> event is reported before
11777     any other event at the current location in the same thread.
11778     <p/>
11779     If a <code>singleStep</code> event or 
11780     <code>breakpoint</code> event is triggered at the 
11781     current location, the event is defined to occur 
11782     immediately before the code at the current location is executed. 
11783     These events are reported before any events which are triggered 
11784     by the execution of code at the current location in the same 
11785     thread (specifically: 
11786     <code>exception</code>,
11787     <code>fieldAccess</code>, and
11788     <code>fieldModification</code>).
11789     If both a step and breakpoint event are triggered for the same thread and 
11790     location, the step event is reported before the breakpoint event.
11791     <p/>
11792     If the current location is the exit point of a method (that is, the last
11793     location before returning to the caller), the 
11794     <eventlink id="MethodExit"></eventlink> event and 
11795     the <eventlink id="FramePop"></eventlink> event (if requested)
11796     are reported after all other events at the current location in the same
11797     thread. There is no specified ordering of these two events 
11798     with respect to each other.
11799     <p/>
11800     Co-located events can be triggered during the processing of some other
11801     event by the agent at the same location in the same thread.
11802     If such an event, of type <i>y</i>, is triggered during the processing of 
11803     an event of type <i>x</i>, and if <i>x</i> 
11804     precedes <i>y</i> in the ordering specified above, the co-located event 
11805     <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
11806     <i>y</i>, <i>y</i> is not reported for the current thread and location.
11807     For example, if a breakpoint is set at the current location 
11808     during the processing of <eventlink id="SingleStep"></eventlink>,
11809     that breakpoint will be reported before the thread moves off the current 
11810     location.
11811     <p/>The following events are never considered to be co-located with 
11812     other events.
11813     <ul>
11814       <li><eventlink id="VMStart"></eventlink></li>
11815       <li><eventlink id="VMInit"></eventlink></li>
11816       <li><eventlink id="VMDeath"></eventlink></li>
11817       <li><eventlink id="ThreadStart"></eventlink></li>
11818       <li><eventlink id="ThreadEnd"></eventlink></li>
11819       <li><eventlink id="ClassLoad"></eventlink></li>
11820       <li><eventlink id="ClassPrepare"></eventlink></li>
11821     </ul>
11822   </intro>
11823 
11824   <intro label="Event Callbacks" id="jvmtiEventCallbacks">
11825       The event callback structure below is used to specify the handler function
11826       for events.  It is set with the
11827       <functionlink id="SetEventCallbacks"></functionlink> function. 
11828   </intro>
11829 
11830   <event label="Single Step"
11831          id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
11832     <description>
11833       Single step events allow the agent to trace thread execution
11834       at the finest granularity allowed by the VM. A single step event is
11835       generated whenever a thread reaches a new location. 
11836       Typically, single step events represent the completion of one VM 
11837       instruction as defined in <vmspec/>. However, some implementations 
11838       may define locations differently. In any case the 
11839       <code>method</code> and <code>location</code>
11840       parameters  uniquely identify the current location and allow
11841       the mapping to source file and line number when that information is 
11842       available.
11843       <p/>
11844       No single step events are generated from within native methods.
11845     </description>
11846     <origin>jvmdi</origin>
11847     <capabilities>
11848       <required id="can_generate_single_step_events"></required>
11849     </capabilities>
11850     <parameters> 
11851       <param id="jni_env">
11852         <outptr>
11853           <struct>JNIEnv</struct>
11854         </outptr>
11855           <description>
11856             The JNI environment of the event (current) thread
11857           </description>
11858       </param>
11859       <param id="thread">
11860         <jthread/>
11861           <description>
11862             Thread about to execution a new instruction
11863           </description>
11864       </param>
11865       <param id="klass">
11866         <jclass method="method"/>
11867           <description>
11868             Class of the method about to execute a new instruction
11869           </description>
11870       </param>
11871       <param id="method">
11872         <jmethodID class="klass"/>
11873           <description>
11874             Method about to execute a new instruction
11875           </description>
11876       </param>
11877       <param id="location">
11878         <jlocation/>
11879         <description>
11880           Location of the new instruction
11881         </description>
11882       </param>
11883     </parameters>
11884   </event>
11885 
11886   <event label="Breakpoint"
11887          id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
11888     <description>
11889       Breakpoint events are generated whenever a thread reaches a location
11890       designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
11891       The <code>method</code> and <code>location</code>
11892       parameters uniquely identify the current location and allow
11893       the mapping to source file and line number when that information is 
11894       available.
11895     </description>
11896     <origin>jvmdi</origin>
11897     <capabilities>
11898       <required id="can_generate_breakpoint_events"></required>
11899     </capabilities>
11900     <parameters> 
11901       <param id="jni_env">
11902         <outptr>
11903           <struct>JNIEnv</struct>
11904         </outptr>
11905           <description>
11906             The JNI environment of the event (current) thread.
11907           </description>
11908       </param>
11909       <param id="thread">
11910         <jthread/>
11911           <description>
11912             Thread that hit the breakpoint
11913           </description>
11914       </param>
11915       <param id="klass">
11916         <jclass method="method"/>
11917           <description>
11918             Class of the method that hit the breakpoint
11919           </description>
11920       </param>
11921       <param id="method">
11922         <jmethodID class="klass"/>
11923           <description>
11924             Method that hit the breakpoint
11925           </description>
11926       </param>
11927       <param id="location">
11928         <jlocation/>
11929         <description>
11930           location of the breakpoint
11931         </description>
11932       </param>
11933     </parameters>
11934   </event>
11935 
11936   <event label="Field Access"
11937          id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
11938     <description>
11939       Field access events are generated whenever a thread accesses
11940       a field that was designated as a watchpoint 
11941       with <functionlink id="SetFieldAccessWatch"></functionlink>.
11942       The <code>method</code> and <code>location</code> 
11943       parameters uniquely identify the current location and allow
11944       the mapping to source file and line number when that information is 
11945       available. 
11946     </description>
11947     <origin>jvmdi</origin>
11948     <capabilities>
11949       <required id="can_generate_field_access_events"></required>
11950     </capabilities>
11951     <parameters> 
11952       <param id="jni_env">
11953         <outptr>
11954           <struct>JNIEnv</struct>
11955         </outptr>
11956           <description>
11957             The JNI environment of the event (current) thread
11958           </description>
11959       </param>
11960       <param id="thread">
11961         <jthread/>
11962           <description>
11963             Thread accessing the field
11964           </description>
11965       </param>
11966       <param id="klass">
11967         <jclass method="method"/>
11968           <description>
11969             Class of the method where the access is occurring
11970           </description>
11971       </param>
11972       <param id="method">
11973         <jmethodID class="klass"/>
11974           <description>
11975             Method where the access is occurring
11976           </description>
11977       </param>
11978       <param id="location">
11979         <jlocation/>
11980         <description>
11981           Location where the access is occurring
11982         </description>
11983       </param>
11984       <param id="field_klass">
11985         <jclass field="field"/>
11986           <description>
11987             Class of the field being accessed
11988           </description>
11989       </param>
11990       <param id="object">
11991         <jobject/>
11992           <description>
11993             Object with the field being accessed if the field is an
11994             instance field; <code>NULL</code> otherwise
11995           </description>
11996       </param>
11997       <param id="field">
11998         <jfieldID class="field_klass"/>
11999           <description>
12000             Field being accessed
12001           </description>
12002       </param>
12003     </parameters>
12004   </event>
12005 
12006   <event label="Field Modification"
12007          id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
12008     <description>
12009       Field modification events are generated whenever a thread modifies
12010       a field that was designated as a watchpoint 
12011       with <functionlink id="SetFieldModificationWatch"></functionlink>.
12012       The <code>method</code> and <code>location</code> 
12013       parameters uniquely identify the current location and allow
12014       the mapping to source file and line number when that information is 
12015       available. 
12016     </description>
12017     <origin>jvmdi</origin>
12018     <capabilities>
12019       <required id="can_generate_field_modification_events"></required>
12020     </capabilities>
12021     <parameters> 
12022       <param id="jni_env">
12023         <outptr>
12024           <struct>JNIEnv</struct>
12025         </outptr>
12026           <description>
12027             The JNI environment of the event (current) thread
12028           </description>
12029       </param>
12030       <param id="thread">
12031         <jthread/>
12032           <description>
12033             Thread modifying the field
12034           </description>
12035       </param>
12036       <param id="klass">
12037         <jclass method="method"/>
12038           <description>
12039             Class of the method where the modification is occurring
12040           </description>
12041       </param>
12042       <param id="method">
12043         <jmethodID class="klass"/>
12044           <description>
12045             Method where the modification is occurring
12046           </description>
12047       </param>
12048       <param id="location">
12049         <jlocation/>
12050         <description>
12051           Location where the modification is occurring
12052         </description>
12053       </param>
12054       <param id="field_klass">
12055         <jclass field="field"/>
12056           <description>
12057             Class of the field being modified
12058           </description>
12059       </param>
12060       <param id="object">
12061         <jobject/>
12062           <description>
12063             Object with the field being modified if the field is an
12064             instance field; <code>NULL</code> otherwise
12065           </description>
12066       </param>
12067       <param id="field">
12068         <jfieldID class="field_klass"/>
12069           <description>
12070             Field being modified
12071           </description>
12072       </param>
12073       <param id="signature_type">
12074         <char/>
12075         <description>
12076           Signature type of the new value
12077         </description>
12078       </param>
12079       <param id="new_value">
12080         <jvalue/>
12081         <description>
12082           The new value
12083         </description>
12084       </param>
12085     </parameters>
12086   </event>
12087 
12088   <event label="Frame Pop"
12089          id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
12090     <description>
12091       Frame pop events are generated upon exit from a single method 
12092       in a single frame as specified
12093       in a call to <functionlink id="NotifyFramePop"></functionlink>.
12094       This is true whether termination is caused by
12095       executing its return instruction
12096       or by throwing an exception to its caller 
12097       (see <paramlink id="was_popped_by_exception"></paramlink>).
12098       However, frame pops caused by the <functionlink id="PopFrame"/> 
12099       function are not reported.
12100       <p/>
12101       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12102       identifies the executable location in the returning method, 
12103       immediately prior to the return. 
12104     </description>
12105     <origin>jvmdi</origin>
12106     <capabilities>
12107       <required id="can_generate_frame_pop_events"></required>
12108     </capabilities>
12109     <parameters> 
12110       <param id="jni_env">
12111         <outptr>
12112           <struct>JNIEnv</struct>
12113         </outptr>
12114           <description>
12115             The JNI environment of the event (current) thread
12116           </description>
12117       </param>
12118       <param id="thread">
12119         <jthread/>
12120           <description>
12121             Thread that is popping the frame
12122           </description>
12123       </param>
12124       <param id="klass">
12125         <jclass method="method"/>
12126           <description>
12127             Class of the method being popped
12128           </description>
12129       </param>
12130       <param id="method">
12131         <jmethodID class="klass"/>
12132           <description>
12133             Method being popped
12134           </description>
12135       </param>
12136       <param id="was_popped_by_exception">
12137         <jboolean/>
12138         <description>
12139           True if frame was popped by a thrown exception.
12140           False if method exited through its return instruction.
12141         </description>
12142       </param>
12143     </parameters>
12144   </event>
12145 
12146   <event label="Method Entry"
12147          id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
12148     <description>
12149       Method entry events are generated upon entry of Java 
12150       programming language methods (including native methods).
12151       <p/>
12152       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12153       identifies the initial executable location in
12154       the method. 
12155       <p/>
12156       Enabling method
12157       entry or exit events will significantly degrade performance on many platforms and is thus
12158       not advised for performance critical usage (such as profiling).
12159       <internallink id="bci">Bytecode instrumentation</internallink> should be 
12160       used in these cases.
12161     </description>
12162     <origin>jvmdi</origin>
12163     <capabilities>
12164       <required id="can_generate_method_entry_events"></required>
12165     </capabilities>
12166     <parameters> 
12167       <param id="jni_env">
12168         <outptr>
12169           <struct>JNIEnv</struct>
12170         </outptr>
12171           <description>
12172             The JNI environment of the event (current) thread
12173           </description>
12174       </param>
12175       <param id="thread">
12176         <jthread/>
12177           <description>
12178             Thread entering the method
12179           </description>
12180       </param>
12181       <param id="klass">
12182         <jclass method="method"/>
12183           <description>
12184             Class of the method being entered
12185           </description>
12186       </param>
12187       <param id="method">
12188         <jmethodID class="klass"/>
12189           <description>
12190             Method being entered
12191           </description>
12192       </param>
12193     </parameters>
12194   </event>
12195 
12196   <event label="Method Exit"
12197          id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
12198     <description>
12199       Method exit events are generated upon exit from Java 
12200       programming language methods (including native methods).
12201       This is true whether termination is caused by
12202       executing its return instruction
12203       or by throwing an exception to its caller 
12204       (see <paramlink id="was_popped_by_exception"></paramlink>).
12205       <p/>
12206       The <code>method</code> field uniquely identifies the
12207       method being entered or exited. The <code>frame</code> field provides 
12208       access to the stack frame for the method.
12209       <p/>
12210       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12211       identifies the executable location in the returning method 
12212       immediately prior to the return. 
12213       <p/>
12214         Enabling method
12215         entry or exit events will significantly degrade performance on many platforms and is thus
12216         not advised for performance critical usage (such as profiling).
12217         <internallink id="bci">Bytecode instrumentation</internallink> should be 
12218         used in these cases.
12219     </description>
12220     <origin>jvmdi</origin>
12221     <capabilities>
12222       <required id="can_generate_method_exit_events"></required>
12223     </capabilities>
12224     <parameters>
12225       <param id="jni_env">
12226         <outptr>
12227           <struct>JNIEnv</struct>
12228         </outptr>
12229           <description>
12230             The JNI environment of the event (current) thread
12231           </description>
12232       </param>
12233       <param id="thread">
12234         <jthread/>
12235           <description>
12236             Thread exiting the method
12237           </description>
12238       </param>
12239       <param id="klass">
12240         <jclass method="method"/>
12241           <description>
12242             Class of the method being exited
12243           </description>
12244       </param>
12245       <param id="method">
12246         <jmethodID class="klass"/>
12247           <description>
12248             Method being exited
12249           </description>
12250       </param>
12251       <param id="was_popped_by_exception">
12252         <jboolean/>
12253         <description>
12254           True if frame was popped by a thrown exception.
12255           False if method exited through its return instruction.
12256         </description>
12257       </param>
12258       <param id="return_value">
12259         <jvalue/>
12260         <description>
12261           The return value of the method being exited.
12262           Undefined and should not be used if 
12263           <paramlink id="was_popped_by_exception"></paramlink>
12264           is true.
12265         </description>
12266       </param>
12267     </parameters>
12268   </event>
12269 
12270   <event label="Native Method Bind" phase="any"
12271          id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
12272     <description>
12273       A Native Method Bind event is sent when a VM binds a 
12274       Java programming language native method
12275       to the address of a function that implements the native method. 
12276       This will occur when the native method is called for the first time
12277       and also occurs when the JNI function <code>RegisterNatives</code> is called.
12278       This event allows the bind to be redirected to an agent-specified
12279       proxy function. 
12280       This event is not sent when the native method is unbound.
12281       Typically, this proxy function will need to be specific to a 
12282       particular method or, to handle the general case, automatically
12283       generated assembly code, since after instrumentation code is 
12284       executed the function at the original binding 
12285       address will usually be invoked.
12286       The original binding can be restored or the redirection changed
12287       by use of the JNI function <code>RegisterNatives</code>.
12288       Some events may be sent during the primordial phase, JNI and
12289       most of <jvmti/> cannot be used at this time but the method and
12290       address can be saved for use later.
12291     </description>
12292     <origin>new</origin>
12293     <capabilities>
12294       <required id="can_generate_native_method_bind_events"></required>
12295     </capabilities>
12296     <parameters>
12297       <param id="jni_env">
12298         <outptr>
12299           <struct>JNIEnv</struct>
12300         </outptr>
12301           <description>
12302             The JNI environment of the event (current) thread
12303             Will be <code>NULL</code> if sent during the primordial 
12304             <functionlink id="GetPhase">phase</functionlink>.
12305           </description>
12306       </param>
12307       <param id="thread">
12308         <jthread/>
12309           <description>
12310             Thread requesting the bind
12311           </description>
12312       </param>
12313       <param id="klass">
12314         <jclass method="method"/>
12315           <description>
12316             Class of the method being bound
12317           </description>
12318       </param>
12319       <param id="method">
12320         <jmethodID class="klass"/>
12321           <description>
12322             Native method being bound
12323           </description>
12324       </param>
12325       <param id="address">
12326         <outptr><void/></outptr>
12327         <description>
12328           The address the VM is about to bind to--that is, the
12329           address of the implementation of the native method
12330         </description>
12331       </param>
12332       <param id="new_address_ptr">
12333         <agentbuf><void/></agentbuf>
12334         <description>
12335           if the referenced address is changed (that is, if
12336           <code>*new_address_ptr</code> is set), the binding
12337           will instead be made to the supplied address.
12338         </description>
12339       </param>
12340     </parameters>
12341   </event>
12342 
12343   <event label="Exception"
12344          id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
12345     <description>
12346       Exception events are generated whenever an exception is first detected
12347       in a Java programming language method. 
12348       Where "exception" means any <code>java.lang.Throwable</code>.
12349       The exception may have been thrown by a Java programming language or native
12350       method, but in the case of native methods, the event is not generated
12351       until the exception is first seen by a Java programming language method. If an exception is
12352       set and cleared in a native method (and thus is never visible to Java programming language code),
12353       no exception event is generated.
12354       <p/>
12355       The <code>method</code> and <code>location</code>
12356       parameters  uniquely identify the current location 
12357       (where the exception was detected) and allow
12358       the mapping to source file and line number when that information is 
12359       available. The <code>exception</code> field identifies the thrown
12360       exception object. The <code>catch_method</code>
12361       and <code>catch_location</code> identify the location of the catch clause,
12362       if any, that handles the thrown exception. If there is no such catch clause,
12363       each field is set to 0. There is no guarantee that the thread will ever
12364       reach this catch clause. If there are native methods on the call stack
12365       between the throw location and the catch clause, the exception may 
12366       be reset by one of those native methods.
12367       Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
12368       et al. set to 0) may in fact be caught by native code.
12369       Agents can check for these occurrences by monitoring 
12370       <eventlink id="ExceptionCatch"></eventlink> events.
12371       Note that finally clauses are implemented as catch and re-throw. Therefore they
12372       will be reported in the catch location.
12373     </description>
12374     <origin>jvmdi</origin>
12375     <capabilities>
12376       <required id="can_generate_exception_events"></required>
12377     </capabilities>
12378     <parameters> 
12379       <param id="jni_env">
12380         <outptr>
12381           <struct>JNIEnv</struct>
12382         </outptr>
12383           <description>
12384             The JNI environment of the event (current) thread
12385           </description>
12386       </param>
12387       <param id="thread">
12388         <jthread/>
12389           <description>
12390             Thread generating the exception
12391           </description>
12392       </param>
12393       <param id="klass">
12394         <jclass method="method"/>
12395           <description>
12396             Class generating the exception
12397           </description>
12398       </param>
12399       <param id="method">
12400         <jmethodID class="klass"/>
12401           <description>
12402             Method generating the exception
12403           </description>
12404       </param>
12405       <param id="location">
12406         <jlocation/>
12407         <description>
12408           Location where exception occurred
12409         </description>
12410       </param>
12411       <param id="exception">
12412         <jobject/>
12413           <description>
12414             The exception being thrown
12415           </description>
12416       </param>
12417       <param id="catch_klass">
12418         <jclass method="catch_method"/>
12419           <description>
12420             Class that will catch the exception, or <code>NULL</code> if no known catch
12421           </description>
12422       </param>
12423       <param id="catch_method">
12424         <jmethodID class="catch_klass"/>
12425           <description>
12426             Method that will catch the exception, or <code>NULL</code> if no known catch
12427           </description>
12428       </param>
12429       <param id="catch_location">
12430         <jlocation/>
12431         <description>
12432           location which will catch the exception or zero if no known catch
12433         </description>
12434       </param>
12435     </parameters>
12436   </event>
12437 
12438   <event label="Exception Catch"
12439          id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
12440     <description>
12441       Exception catch events are generated whenever a thrown exception is caught.
12442       Where "exception" means any <code>java.lang.Throwable</code>.
12443       If the exception is caught in a Java programming language method, the event is generated
12444       when the catch clause is reached. If the exception is caught in a native
12445       method, the event is generated as soon as control is returned to a Java programming language 
12446       method. Exception catch events are generated for any exception for which
12447       a throw was detected in a Java programming language method.
12448       Note that finally clauses are implemented as catch and re-throw. Therefore they
12449       will generate exception catch events.
12450       <p/>
12451       The <code>method</code> and <code>location</code>
12452       parameters uniquely identify the current location 
12453       and allow the mapping to source file and line number when that information is 
12454       available. For exceptions caught in a Java programming language method, the 
12455       <code>exception</code> object identifies the exception object. Exceptions
12456       caught in native methods are not necessarily available by the time the 
12457       exception catch is reported, so the <code>exception</code> field is set
12458       to <code>NULL</code>.
12459     </description>
12460     <origin>jvmdi</origin>
12461     <capabilities>
12462       <required id="can_generate_exception_events"></required>
12463     </capabilities>
12464     <parameters> 
12465       <param id="jni_env">
12466         <outptr>
12467           <struct>JNIEnv</struct>
12468         </outptr>
12469           <description>
12470             The JNI environment of the event (current) thread
12471           </description>
12472       </param>
12473       <param id="thread">
12474         <jthread/>
12475           <description>
12476             Thread catching the exception
12477           </description>
12478       </param>
12479       <param id="klass">
12480         <jclass method="method"/>
12481           <description>
12482             Class catching the exception
12483           </description>
12484       </param>
12485       <param id="method">
12486         <jmethodID class="klass"/>
12487           <description>
12488             Method catching the exception
12489           </description>
12490       </param>
12491       <param id="location">
12492         <jlocation/>
12493         <description>
12494           Location where exception is being caught
12495         </description>
12496       </param>
12497       <param id="exception">
12498         <jobject/>
12499           <description>
12500             Exception being caught
12501           </description>
12502       </param>
12503     </parameters>
12504   </event>
12505 
12506   <event label="Thread Start"
12507          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12508     <description>
12509       Thread start events are generated by a new thread before its initial
12510       method executes. 
12511       <p/>
12512       A thread may be listed in the array returned by
12513       <functionlink id="GetAllThreads"></functionlink>
12514       before its thread start event is generated. 
12515       It is possible for other events to be generated
12516       on a thread before its thread start event.
12517       <p/>
12518       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12519     </description>
12520     <origin>jvmdi</origin>
12521     <capabilities>
12522     </capabilities>
12523     <parameters> 
12524       <param id="jni_env">
12525         <outptr>
12526           <struct>JNIEnv</struct>
12527         </outptr>
12528           <description>
12529             The JNI environment of the event (current) thread.
12530           </description>
12531       </param>
12532       <param id="thread">
12533         <jthread/>
12534           <description>
12535             Thread starting
12536           </description>
12537       </param>
12538     </parameters>
12539   </event>
12540 
12541   <event label="Thread End"
12542          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> 
12543     <description>
12544       Thread end events are generated by a terminating thread
12545       after its initial method has finished execution. 
12546       <p/>
12547       A thread may be listed in the array returned by
12548       <functionlink id="GetAllThreads"></functionlink>
12549       after its thread end event is generated. 
12550       No events are generated on a thread
12551       after its thread end event.
12552       <p/>
12553       The event is sent on the dying <paramlink id="thread"></paramlink>.
12554     </description>
12555     <origin>jvmdi</origin>
12556     <capabilities>
12557     </capabilities>
12558     <parameters> 
12559       <param id="jni_env">
12560         <outptr>
12561           <struct>JNIEnv</struct>
12562         </outptr>
12563           <description>
12564             The JNI environment of the event (current) thread.
12565           </description>
12566       </param>
12567       <param id="thread">
12568         <jthread/>
12569           <description>
12570             Thread ending
12571           </description>
12572       </param>
12573     </parameters>
12574   </event>
12575 
12576   <event label="Class Load"
12577          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
12578     <description>
12579       A class load event is generated when a class is first loaded. The order
12580       of class load events generated by a particular thread are guaranteed
12581       to match the order of class loading within that thread. 
12582       Array class creation does not generate a class load event.
12583       The creation of a primitive class (for example, java.lang.Integer.TYPE) 
12584       does not generate a class load event.
12585       <p/>
12586       This event is sent at an early stage in loading the class. As
12587       a result the class should be used carefully.  Note, for example,
12588       that methods and fields are not yet loaded, so queries for methods,
12589       fields, subclasses, and so on will not give correct results. 
12590       See "Loading of Classes and Interfaces" in the <i>Java Language
12591       Specification</i>.  For most
12592       purposes the <eventlink id="ClassPrepare"></eventlink> event will
12593       be more useful.
12594     </description>
12595     <origin>jvmdi</origin>
12596     <capabilities>
12597     </capabilities>
12598     <parameters> 
12599       <param id="jni_env">
12600         <outptr>
12601           <struct>JNIEnv</struct>
12602         </outptr>
12603           <description>
12604             The JNI environment of the event (current) thread
12605           </description>
12606       </param>
12607       <param id="thread">
12608         <jthread/>
12609           <description>
12610             Thread loading the class
12611           </description>
12612       </param>
12613       <param id="klass">
12614         <jclass/>
12615           <description>
12616             Class being loaded
12617           </description>
12618       </param>
12619     </parameters>
12620   </event>
12621 
12622   <elide>
12623   <event label="Class Unload"
12624          id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
12625     <description>
12626       A class unload event is generated when the class is about to be unloaded.
12627       Class unload events take place during garbage collection and must be 
12628       handled extremely carefully. The garbage collector holds many locks
12629       and has suspended all other threads, so the event handler cannot depend
12630       on the ability to acquire any locks. The class unload event handler should
12631       do as little as possible, perhaps by queuing information to be processed
12632       later.  In particular, the <code>jclass</code> should be used only in
12633       the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
12634       <ul>
12635         <li><functionlink id="GetClassSignature"></functionlink></li>
12636         <li><functionlink id="GetSourceFileName"></functionlink></li>
12637         <li><functionlink id="IsInterface"></functionlink></li>
12638         <li><functionlink id="IsArrayClass"></functionlink></li>
12639       </ul>
12640     </description>
12641     <origin>jvmdi</origin>
12642     <capabilities>
12643     </capabilities>
12644     <parameters> 
12645       <param id="jni_env">
12646         <outptr>
12647           <struct>JNIEnv</struct>
12648         </outptr>
12649           <description>
12650             The JNI environment of the event (current) thread
12651           </description>
12652       </param>
12653       <param id="thread">
12654         <jthread/>
12655           <description>
12656             Thread generating the class unload
12657           </description>
12658       </param>
12659       <param id="klass">
12660         <jclass/>
12661           <description>
12662             Class being unloaded
12663           </description>
12664       </param>
12665     </parameters>
12666   </event>
12667   </elide>
12668 
12669   <event label="Class Prepare"
12670          id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
12671     <description>
12672       A class prepare event is generated when class preparation is complete.
12673       At this point, class fields, methods, and implemented interfaces are 
12674       available, and no code from the class has been executed. Since array 
12675       classes never have fields or methods, class prepare events are not 
12676       generated for them. Class prepare events are not generated for 
12677       primitive classes (for example, <code>java.lang.Integer.TYPE</code>). 
12678     </description>
12679     <origin>jvmdi</origin>
12680     <capabilities>
12681     </capabilities>
12682     <parameters> 
12683       <param id="jni_env">
12684         <outptr>
12685           <struct>JNIEnv</struct>
12686         </outptr>
12687           <description>
12688             The JNI environment of the event (current) thread
12689           </description>
12690       </param>
12691       <param id="thread">
12692         <jthread/>
12693           <description>
12694             Thread generating the class prepare
12695           </description>
12696       </param>
12697       <param id="klass">
12698         <jclass/>
12699           <description>
12700             Class being prepared
12701           </description>
12702       </param>
12703     </parameters>
12704   </event>
12705 
12706   <event label="Class File Load Hook" phase="any"
12707          id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
12708     <description>
12709       This event is sent when the VM obtains class file data,
12710       but before it constructs
12711       the in-memory representation for that class. 
12712       This event is also sent when the class is being modified by the 
12713       <functionlink id="RetransformClasses"/> function or
12714       the <functionlink id="RedefineClasses"/> function,
12715       called in any <jvmti/> environment.
12716       The agent can instrument
12717       the existing class file data sent by the VM to include profiling/debugging hooks.
12718       See the description of 
12719       <internallink id="bci">bytecode instrumentation</internallink>
12720       for usage information.
12721       <p/>
12722     When the capabilities
12723     <internallink id="jvmtiCapabilities.can_generate_early_class_hook_events">
12724     <code>can_generate_early_class_hook_events</code></internallink> and
12725     <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
12726     <code>can_generate_all_class_hook_events</code></internallink>
12727     are enabled then this event may be sent in the primordial phase.
12728     Otherwise, this event may be sent before the VM is initialized (the start 
12729     <functionlink id="GetPhase">phase</functionlink>).
12730     Some classes might not be compatible
12731     with the function (eg. ROMized classes or implementation defined classes) and this event will
12732     not be generated for these classes.
12733     <p/>
12734     The agent must allocate the space for the modified 
12735     class file data buffer
12736     using the memory allocation function 
12737     <functionlink id="Allocate"></functionlink> because the
12738     VM is responsible for freeing the new class file data buffer
12739     using <functionlink id="Deallocate"></functionlink>.
12740     <p/>
12741     If the agent wishes to modify the class file, it must set 
12742     <code>new_class_data</code> to point
12743     to the newly instrumented class file data buffer and set
12744     <code>new_class_data_len</code> to the length of that 
12745     buffer before returning
12746     from this call.  If no modification is desired, the agent simply
12747     does not set <code>new_class_data</code>.  If multiple agents
12748     have enabled this event the results are chained. That is, if
12749     <code>new_class_data</code> has been set, it becomes the 
12750     <code>class_data</code> for the next agent.
12751     <p/>
12752     When handling a class load in the live phase, then the
12753     <functionlink id="GetNamedModule"></functionlink>
12754     function can be used to map class loader and a package name to a module.
12755     When a class is being redefined or retransformed then
12756     <code>class_being_redefined</code> is non <code>NULL</code> and so
12757     the JNI <code>GetModule</code> function can also be used
12758     to obtain the Module.
12759     <p/>
12760     The order that this event is sent to each environment differs
12761     from other events.
12762     This event is sent to environments in the following order:
12763     <ul>
12764       <li><fieldlink id="can_retransform_classes"
12765                      struct="jvmtiCapabilities">retransformation
12766                                                 incapable</fieldlink>
12767           environments, in the 
12768           order in which they were created
12769       </li>
12770       <li><fieldlink id="can_retransform_classes"
12771                      struct="jvmtiCapabilities">retransformation
12772                                                 capable</fieldlink>
12773           environments, in the 
12774           order in which they were created
12775       </li>
12776     </ul>
12777     When triggered by <functionlink id="RetransformClasses"/>,
12778     this event is sent only to <fieldlink id="can_retransform_classes"
12779                      struct="jvmtiCapabilities">retransformation
12780                                                 capable</fieldlink>
12781     environments.
12782   </description>
12783   <origin>jvmpi</origin>
12784     <capabilities>
12785       <capability id="can_generate_all_class_hook_events"></capability>
12786       <capability id="can_generate_early_class_hook_events"></capability>
12787     </capabilities>
12788     <parameters>
12789       <param id="jni_env">
12790         <outptr>
12791           <struct>JNIEnv</struct>
12792         </outptr>
12793           <description>
12794             The JNI environment of the event (current) thread.
12795           </description>
12796       </param>
12797       <param id="class_being_redefined">
12798         <jclass/>
12799         <description>
12800           The class being
12801           <functionlink id="RedefineClasses">redefined</functionlink> or
12802           <functionlink id="RetransformClasses">retransformed</functionlink>.
12803           <code>NULL</code> if sent by class load.
12804         </description>
12805       </param>
12806       <param id="loader">
12807         <jobject/>
12808           <description>
12809             The class loader loading the class.  
12810             <code>NULL</code> if the bootstrap class loader.
12811           </description>
12812       </param>
12813       <param id="name">
12814         <vmbuf><char/></vmbuf>
12815         <description>
12816             Name of class being loaded as a VM internal qualified name
12817             (for example, "java/util/List"), encoded as a
12818             <internallink id="mUTF">modified UTF-8</internallink> string.
12819             Note: if the class is defined with a <code>NULL</code> name or
12820             without a name specified, <code>name</code> will be <code>NULL</code>.
12821         </description>
12822       </param>
12823       <param id="protection_domain">
12824         <jobject/>
12825         <description>
12826           The <code>ProtectionDomain</code> of the class.
12827         </description>
12828       </param>
12829       <param id="class_data_len">
12830         <jint/>
12831         <description>
12832           Length of current class file data buffer.
12833         </description>
12834       </param>
12835       <param id="class_data">
12836         <vmbuf><uchar/></vmbuf>
12837         <description>
12838           Pointer to the current class file data buffer.
12839         </description>
12840       </param>
12841       <param id="new_class_data_len">
12842         <outptr><jint/></outptr>
12843         <description>
12844           Pointer to the length of the new class file data buffer.
12845         </description>
12846       </param>
12847       <param id="new_class_data">
12848         <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
12849         <description>
12850           Pointer to the pointer to the instrumented class file data buffer.
12851         </description>
12852       </param>
12853     </parameters>
12854   </event>
12855 
12856   <event label="VM Start Event"
12857          id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
12858     <description>
12859       The VM start event signals the start of the VM.
12860       At this time JNI is live but the VM is not yet fully initialized.
12861       Once this event is generated, the agent is free to call any JNI function.
12862       This event signals the beginning of the start phase,
12863       <jvmti/> functions permitted in the start phase may be called.
12864       <p/>
12865       The timing of this event may depend on whether the agent has added the
12866       <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
12867       <code>can_generate_early_vmstart</code></internallink> capability or not.
12868       If the capability has been added then the VM posts the event as early
12869       as possible. The VM is capable of executing bytecode but it may not have
12870       initialized to the point where it can load classes in modules other than
12871       <code>java.base</code>, or even arbitrary classes in <code>java.base</code>.
12872       Agents that do load-time instrumentation in this
12873       phase must take great care when instrumenting code that potentially
12874       executes in this phase. Extreme care should also be taken with JNI
12875       <code>FindClass</code> as it may not be possible to load classes and attempts
12876       to do so may result in unpredictable behavior, maybe even stability issues
12877       on some VM implementations.
12878       If the capability has not been added then the VM delays posting this
12879       event until it is capable of loading classes in modules other than
12880       <code>java.base</code> or the VM has completed its initialization.
12881       Agents that create more than one JVM TI environment, where the
12882       capability is added to some but not all environments, may observe the
12883       start phase beginning earlier in the JVM TI environments that possess
12884       the capabilty.
12885       <p/>
12886       In the case of VM start-up failure, this event will not be sent.
12887     </description>
12888     <origin>jvmdi</origin>
12889     <capabilities>
12890     </capabilities>
12891     <parameters>
12892       <param id="jni_env">
12893         <outptr>
12894           <struct>JNIEnv</struct>
12895         </outptr>
12896           <description>
12897             The JNI environment of the event (current) thread.
12898           </description>
12899       </param>
12900     </parameters>
12901   </event>
12902 
12903   <event label="VM Initialization Event"
12904          id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
12905     <description>
12906       The VM initialization event signals the completion of VM initialization. Once
12907       this event is generated, the agent is free to call any JNI or <jvmti/>
12908       function. The VM initialization event can be preceded by or can be concurrent
12909       with other events, but
12910       the preceding events should be handled carefully, if at all, because the
12911       VM has not completed its initialization. The thread start event for the
12912       main application thread is guaranteed not to occur until after the 
12913       handler for the VM initialization event returns.
12914       <p/>
12915       In the case of VM start-up failure, this event will not be sent.
12916     </description>
12917     <origin>jvmdi</origin>
12918     <capabilities>
12919     </capabilities>
12920     <parameters>
12921       <param id="jni_env">
12922         <outptr>
12923           <struct>JNIEnv</struct>
12924         </outptr>
12925           <description>
12926             The JNI environment of the event (current) thread.
12927           </description>
12928       </param>
12929       <param id="thread">
12930         <jthread/>
12931           <description>
12932             The initial thread
12933           </description>
12934       </param>
12935     </parameters>
12936   </event>
12937 
12938   <event label="VM Death Event"
12939          id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
12940     <description>
12941       The VM death event notifies the agent of the termination of the VM. 
12942       No events will occur after the VMDeath event.
12943       <p/>
12944       In the case of VM start-up failure, this event will not be sent.
12945       Note that <internallink id="onunload">Agent_OnUnload</internallink>
12946       will still be called in these cases.
12947     </description>
12948     <origin>jvmdi</origin>
12949     <capabilities>
12950     </capabilities>
12951     <parameters>
12952       <param id="jni_env">
12953         <outptr>
12954           <struct>JNIEnv</struct>
12955         </outptr>
12956           <description>
12957             The JNI environment of the event (current) thread
12958           </description>
12959       </param>
12960     </parameters>
12961   </event>
12962 
12963   <event label="Compiled Method Load" phase="start"
12964          id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
12965     <description>
12966       Sent when a method is compiled and loaded into memory by the VM.
12967       If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
12968       If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
12969       followed by a new <code>CompiledMethodLoad</code> event.
12970       Note that a single method may have multiple compiled forms, and that
12971       this event will be sent for each form.
12972       Note also that several methods may be inlined into a single 
12973       address range, and that this event will be sent for each method.
12974       <p/>
12975       These events can be sent after their initial occurrence with
12976       <functionlink id="GenerateEvents"></functionlink>.
12977     </description>
12978     <origin>jvmpi</origin>
12979     <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
12980       <field id="start_address">
12981         <vmbuf><void/></vmbuf>
12982         <description>
12983           Starting native address of code corresponding to a location
12984         </description>
12985       </field>
12986       <field id="location">
12987         <jlocation/>
12988         <description>
12989           Corresponding location. See 
12990           <functionlink id="GetJLocationFormat"></functionlink>
12991           for the meaning of location.
12992         </description>
12993       </field>
12994     </typedef>
12995     <capabilities>
12996       <required id="can_generate_compiled_method_load_events"></required>
12997     </capabilities>
12998     <parameters>
12999       <param id="klass">
13000         <jclass method="method"/>
13001           <description>
13002             Class of the method being compiled and loaded
13003           </description>
13004       </param>
13005       <param id="method">
13006         <jmethodID class="klass"/>
13007           <description>
13008             Method being compiled and loaded
13009           </description>
13010       </param>
13011       <param id="code_size">
13012         <jint/>
13013         <description>
13014           Size of compiled code
13015         </description>
13016       </param>
13017       <param id="code_addr">
13018         <vmbuf><void/></vmbuf>
13019         <description>
13020           Address where compiled method code is loaded
13021         </description>
13022       </param>
13023       <param id="map_length">
13024         <jint/>
13025         <description>
13026           Number of <typelink id="jvmtiAddrLocationMap"></typelink>
13027           entries in the address map.
13028           Zero if mapping information cannot be supplied.
13029         </description>
13030       </param>
13031       <param id="map">
13032         <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
13033         <description>
13034           Map from native addresses to location.
13035           The native address range of each entry is from 
13036           <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
13037           to <code>start_address-1</code> of the next entry.
13038           <code>NULL</code> if mapping information cannot be supplied.
13039         </description>
13040       </param>
13041       <param id="compile_info">
13042         <vmbuf><void/></vmbuf>
13043         <description>
13044           VM-specific compilation information.  
13045           The referenced compile information is managed by the VM
13046           and must not depend on the agent for collection.
13047           A VM implementation defines the content and lifetime 
13048           of the information.
13049         </description>
13050       </param>
13051     </parameters>
13052   </event>
13053 
13054   <event label="Compiled Method Unload" phase="start"
13055          id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
13056     <description>
13057       Sent when a compiled method is unloaded from memory.
13058       This event might not be sent on the thread which performed the unload.
13059       This event may be sent sometime after the unload occurs, but 
13060       will be sent before the memory is reused
13061       by a newly generated compiled method. This event may be sent after 
13062       the class is unloaded.
13063     </description>
13064     <origin>jvmpi</origin>
13065     <capabilities>
13066       <required id="can_generate_compiled_method_load_events"></required>
13067     </capabilities>
13068     <parameters>
13069       <param id="klass">
13070         <jclass method="method"/>
13071           <description>
13072             Class of the compiled method being unloaded.
13073           </description>
13074       </param>
13075       <param id="method">
13076         <jmethodID class="klass"/>
13077           <description>
13078             Compiled method being unloaded.
13079             For identification of the compiled method only -- the class 
13080             may be unloaded and therefore the method should not be used
13081             as an argument to further JNI or <jvmti/> functions.
13082           </description>
13083       </param>
13084       <param id="code_addr">
13085         <vmbuf><void/></vmbuf>
13086         <description>
13087           Address where compiled method code was loaded.
13088           For identification of the compiled method only -- 
13089           the space may have been reclaimed.
13090         </description>
13091       </param>
13092     </parameters>
13093   </event>
13094 
13095   <event label="Dynamic Code Generated" phase="any"
13096          id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
13097     <description>
13098       Sent when a component of the virtual machine is generated dynamically.
13099       This does not correspond to Java programming language code that is
13100       compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
13101       This is for native code--for example, an interpreter that is generated
13102       differently depending on command-line options.
13103       <p/>
13104       Note that this event has no controlling capability.
13105       If a VM cannot generate these events, it simply does not send any.
13106       <p/>
13107       These events can be sent after their initial occurrence with
13108       <functionlink id="GenerateEvents"></functionlink>.
13109     </description>
13110     <origin>jvmpi</origin>
13111     <capabilities>
13112     </capabilities>
13113     <parameters>
13114       <param id="name">
13115         <vmbuf><char/></vmbuf>
13116         <description>
13117           Name of the code, encoded as a
13118           <internallink id="mUTF">modified UTF-8</internallink> string.
13119           Intended for display to an end-user.
13120           The name might not be unique.
13121         </description>
13122       </param>
13123       <param id="address">
13124         <vmbuf><void/></vmbuf>
13125         <description>
13126           Native address of the code
13127         </description>
13128       </param>
13129       <param id="length">
13130         <jint/>
13131         <description>
13132           Length in bytes of the code
13133         </description>
13134       </param>
13135     </parameters>
13136   </event>
13137 
13138   <event label="Data Dump Request"
13139          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
13140     <description>
13141       Sent by the VM to request the agent to dump its data.  This
13142       is just a hint and the agent need not react to this event.
13143       This is useful for processing command-line signals from users.  For
13144       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris
13145       causes the VM to send this event to the agent.
13146     </description>
13147     <origin>jvmpi</origin>
13148     <capabilities>
13149     </capabilities>
13150     <parameters>
13151     </parameters>
13152   </event>
13153 
13154   <event label="Monitor Contended Enter"
13155          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
13156     <description>
13157       Sent when a thread is attempting to enter a Java programming language
13158       monitor already acquired by another thread.
13159     </description>
13160     <origin>jvmpi</origin>
13161     <capabilities>
13162       <required id="can_generate_monitor_events"></required>
13163     </capabilities>
13164     <parameters>
13165       <param id="jni_env">
13166         <outptr>
13167           <struct>JNIEnv</struct>
13168         </outptr>
13169           <description>
13170             The JNI environment of the event (current) thread
13171           </description>
13172       </param>
13173       <param id="thread">
13174         <jthread/>
13175           <description>
13176             JNI local reference to the thread 
13177             attempting to enter the monitor
13178           </description>
13179       </param>
13180       <param id="object">
13181         <jobject/>
13182           <description>
13183             JNI local reference to the monitor
13184           </description>
13185       </param>
13186     </parameters>
13187   </event>
13188 
13189   <event label="Monitor Contended Entered"
13190          id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
13191     <description>
13192       Sent when a thread enters a Java programming language
13193       monitor after waiting for it to be released by another thread.
13194     </description>
13195     <origin>jvmpi</origin>
13196     <capabilities>
13197       <required id="can_generate_monitor_events"></required>
13198     </capabilities>
13199     <parameters>
13200       <param id="jni_env">
13201         <outptr>
13202           <struct>JNIEnv</struct>
13203         </outptr>
13204           <description>
13205             The JNI environment of the event (current) thread
13206           </description>
13207       </param>
13208       <param id="thread">
13209         <jthread/>
13210           <description>
13211             JNI local reference to the thread entering
13212             the monitor
13213           </description>
13214       </param>
13215       <param id="object">
13216         <jobject/>
13217           <description>
13218             JNI local reference to the monitor
13219           </description>
13220       </param>
13221     </parameters>
13222   </event>
13223 
13224   <event label="Monitor Wait"
13225          id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
13226     <description>
13227       Sent when a thread is about to wait on an object.
13228     </description>
13229     <origin>jvmpi</origin>
13230     <capabilities>
13231       <required id="can_generate_monitor_events"></required>
13232     </capabilities>
13233     <parameters>
13234       <param id="jni_env">
13235         <outptr>
13236           <struct>JNIEnv</struct>
13237         </outptr>
13238           <description>
13239             The JNI environment of the event (current) thread
13240           </description>
13241       </param>
13242       <param id="thread">
13243         <jthread/>
13244           <description>
13245             JNI local reference to the thread about to wait
13246           </description>
13247       </param>
13248       <param id="object">
13249         <jobject/>
13250           <description>
13251             JNI local reference to the monitor
13252           </description>
13253       </param>
13254       <param id="timeout">
13255         <jlong/>
13256         <description>
13257           The number of milliseconds the thread will wait
13258         </description>
13259       </param>
13260     </parameters>
13261   </event>
13262 
13263   <event label="Monitor Waited"
13264          id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
13265     <description>
13266       Sent when a thread finishes waiting on an object.
13267     </description>
13268     <origin>jvmpi</origin>
13269     <capabilities>
13270       <required id="can_generate_monitor_events"></required>
13271     </capabilities>
13272     <parameters>
13273       <param id="jni_env">
13274         <outptr>
13275           <struct>JNIEnv</struct>
13276         </outptr>
13277           <description>
13278             The JNI environment of the event (current) thread
13279           </description>
13280       </param>
13281       <param id="thread">
13282         <jthread/>
13283           <description>
13284             JNI local reference to the thread that was finished waiting
13285           </description>
13286       </param>
13287       <param id="object">
13288         <jobject/>
13289           <description>
13290             JNI local reference to the monitor.
13291           </description>
13292       </param>
13293       <param id="timed_out">
13294         <jboolean/>
13295         <description>
13296           True if the monitor timed out
13297         </description>
13298       </param>
13299     </parameters>
13300   </event>
13301 
13302   <event label="Resource Exhausted"
13303          id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
13304          since="1.1">
13305     <description>
13306       Sent when a VM resource needed by a running application has been exhausted.
13307       Except as required by the optional capabilities, the set of resources 
13308       which report exhaustion is implementation dependent.
13309       <p/>
13310       The following bit flags define the properties of the resource exhaustion:
13311       <constants id="jvmtiResourceExhaustionFlags" 
13312                  label="Resource Exhaustion Flags" 
13313                  kind="bits" 
13314                  since="1.1">
13315         <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
13316           After this event returns, the VM will throw a
13317           <code>java.lang.OutOfMemoryError</code>.
13318         </constant>         
13319         <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
13320           The VM was unable to allocate memory from the <tm>Java</tm> 
13321           platform <i>heap</i>.
13322           The <i>heap</i> is the runtime
13323           data area from which memory for all class instances and
13324           arrays are allocated.
13325         </constant>         
13326         <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
13327           The VM was unable to create a thread.
13328         </constant>         
13329       </constants>
13330     </description>
13331     <origin>new</origin>
13332     <capabilities>
13333       <capability id="can_generate_resource_exhaustion_heap_events">
13334         Can generate events when the VM is unable to allocate memory from the
13335         <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
13336       </capability>
13337       <capability id="can_generate_resource_exhaustion_threads_events">
13338         Can generate events when the VM is unable to 
13339         <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
13340         a thread</internallink>.
13341       </capability>
13342     </capabilities>
13343     <parameters>
13344       <param id="jni_env">
13345         <outptr>
13346           <struct>JNIEnv</struct>
13347         </outptr>
13348           <description>
13349             The JNI environment of the event (current) thread
13350           </description>
13351       </param>
13352       <param id="flags">
13353         <jint/>
13354         <description>
13355           Flags defining the properties of the of resource exhaustion
13356           as specified by the 
13357           <internallink id="jvmtiResourceExhaustionFlags">Resource 
13358           Exhaustion Flags</internallink>.
13359           </description>
13360         </param>
13361       <param id="reserved">
13362         <vmbuf><void/></vmbuf>
13363         <description>
13364           Reserved.
13365         </description>
13366       </param>
13367       <param id="description">
13368         <vmbuf><char/></vmbuf>
13369         <description>
13370           Description of the resource exhaustion, encoded as a
13371           <internallink id="mUTF">modified UTF-8</internallink> string.
13372         </description>
13373       </param>
13374     </parameters>
13375   </event>
13376 
13377   <event label="VM Object Allocation"
13378          id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
13379     <description>
13380       Sent when a method causes the virtual machine to allocate an 
13381       Object visible to Java programming language code and the
13382       allocation is not detectable by other intrumentation mechanisms.
13383       Generally object allocation should be detected by instrumenting
13384       the bytecodes of allocating methods.
13385       Object allocation generated in native code by JNI function
13386       calls should be detected using 
13387       <internallink id="jniIntercept">JNI function interception</internallink>.
13388       Some methods might not have associated bytecodes and are not 
13389       native methods, they instead are executed directly by the 
13390       VM. These methods should send this event.
13391       Virtual machines which are incapable of bytecode instrumentation
13392       for some or all of their methods can send this event.
13393       <p/>
13394       Typical examples where this event might be sent:
13395       <ul>
13396         <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
13397         <li>Methods not represented by bytecodes -- for example, VM intrinsics and
13398             J2ME preloaded classes</li>
13399       </ul>
13400       Cases where this event would not be generated:
13401       <ul>
13402         <li>Allocation due to bytecodes -- for example, the <code>new</code>
13403             and <code>newarray</code> VM instructions</li>
13404         <li>Allocation due to JNI function calls -- for example,
13405             <code>AllocObject</code></li>
13406         <li>Allocations during VM initialization</li>
13407         <li>VM internal objects</li>
13408       </ul>
13409     </description>
13410     <origin>new</origin>
13411     <capabilities>
13412       <required id="can_generate_vm_object_alloc_events"></required>
13413     </capabilities>
13414     <parameters>
13415       <param id="jni_env">
13416         <outptr>
13417           <struct>JNIEnv</struct>
13418         </outptr>
13419           <description>
13420             The JNI environment of the event (current) thread
13421           </description>
13422       </param>
13423       <param id="thread">
13424         <jthread/>
13425           <description>
13426             Thread allocating the object.
13427           </description>
13428       </param>
13429       <param id="object">
13430         <jobject/>
13431           <description>
13432             JNI local reference to the object that was allocated
13433           </description>
13434       </param>
13435       <param id="object_klass">
13436         <jclass/>
13437           <description>
13438             JNI local reference to the class of the object
13439           </description>
13440       </param>
13441       <param id="size">
13442         <jlong/>
13443         <description>
13444             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13445         </description>
13446       </param>
13447     </parameters>
13448   </event>
13449 
13450   <event label="Object Free"
13451          id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13452     <description>
13453       An Object Free event is sent when the garbage collector frees an object.
13454       Events are only sent for tagged objects--see
13455       <internallink id="Heap">heap functions</internallink>.
13456       <p/>
13457       The event handler must not use JNI functions and
13458       must not use <jvmti/> functions except those which
13459       specifically allow such use (see the raw monitor, memory management,
13460       and environment local storage functions).
13461     </description>
13462     <origin>new</origin>
13463     <capabilities>
13464       <required id="can_generate_object_free_events"></required>
13465     </capabilities>
13466     <parameters>
13467       <param id="tag">
13468         <jlong/>
13469         <description>
13470           The freed object's tag
13471         </description>
13472       </param>
13473     </parameters>
13474   </event>
13475 
13476   <event label="Garbage Collection Start"
13477          id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
13478     <description>
13479       A Garbage Collection Start event is sent when a 
13480       garbage collection pause begins.
13481       Only stop-the-world collections are reported--that is, collections during
13482       which all threads cease to modify the state of the Java virtual machine.
13483       This means that some collectors will never generate these events.
13484       This event is sent while the VM is still stopped, thus
13485       the event handler must not use JNI functions and
13486       must not use <jvmti/> functions except those which
13487       specifically allow such use (see the raw monitor, memory management,
13488       and environment local storage functions).
13489       <p/>
13490       This event is always sent as a matched pair with 
13491       <eventlink id="GarbageCollectionFinish"/> 
13492       (assuming both events are enabled) and no garbage collection
13493       events will occur between them.
13494     </description>
13495     <origin>new</origin>
13496     <capabilities>
13497       <required id="can_generate_garbage_collection_events"></required>
13498     </capabilities>
13499     <parameters>
13500     </parameters>
13501   </event>
13502 
13503   <event label="Garbage Collection Finish"
13504          id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
13505     <description>
13506       A Garbage Collection Finish event is sent when a
13507       garbage collection pause ends.
13508       This event is sent while the VM is still stopped, thus
13509       the event handler must not use JNI functions and
13510       must not use <jvmti/> functions except those which
13511       specifically allow such use (see the raw monitor, memory management,
13512       and environment local storage functions).
13513       <p/>
13514       Some agents may need to do post garbage collection operations that
13515       require the use of the disallowed <jvmti/> or JNI functions. For these
13516       cases an agent thread can be created which waits on a raw monitor,
13517       and the handler for the Garbage Collection Finish event simply
13518       notifies the raw monitor
13519       <p/>
13520       This event is always sent as a matched pair with 
13521       <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
13522       <issue>
13523         The most important use of this event is to provide timing information,
13524         and thus additional information is not required.  However,  
13525         information about the collection which is "free" should be included -
13526         what that information is needs to be determined.
13527       </issue>
13528     </description>
13529     <origin>new</origin>
13530     <capabilities>
13531       <required id="can_generate_garbage_collection_events"></required>
13532     </capabilities>
13533     <parameters>
13534     </parameters>
13535   </event>
13536 
13537   <elide>
13538   <event label="Verbose Output" phase="any"
13539          id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
13540     <description>
13541       Send verbose messages as strings.
13542         <issue>
13543           This format is extremely fragile, as it can change with each
13544           platform, collector and version.  Alternatives include:
13545           <ul>
13546             <li>building off Java programming language M and M APIs</li>
13547             <li>XML</li>
13548             <li>key/value pairs</li>
13549             <li>removing it</li>
13550           </ul>
13551         </issue>
13552         <issue>
13553           Though this seemed trivial to implement.  
13554           In the RI it appears this will be quite complex.
13555         </issue>
13556     </description>
13557     <origin>new</origin>
13558     <capabilities>
13559     </capabilities>
13560     <parameters>
13561       <param id="flag">
13562         <enum>jvmtiVerboseFlag</enum>
13563         <description>
13564           Which verbose output is being sent.
13565         </description>
13566       </param>
13567       <param id="message">
13568         <vmbuf><char/></vmbuf>
13569         <description>
13570           Message text, encoded as a
13571           <internallink id="mUTF">modified UTF-8</internallink> string.
13572         </description>
13573       </param>
13574     </parameters>
13575   </event>
13576   </elide>
13577 
13578 </eventsection>
13579 
13580 <datasection>
13581   <intro>
13582     <jvmti/> extends the data types defined by JNI.
13583   </intro>
13584   <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
13585     <basetype id="jboolean">
13586       <description>
13587         Holds a Java programming language <code>boolean</code>.
13588         Unsigned 8 bits.
13589       </description>
13590     </basetype>
13591     <basetype id="jchar">
13592       <description>
13593         Holds a Java programming language <code>char</code>.
13594         Unsigned 16 bits.
13595       </description>
13596     </basetype>
13597     <basetype id="jint">
13598       <description>
13599         Holds a Java programming language <code>int</code>. 
13600         Signed 32 bits.
13601       </description>
13602     </basetype>
13603     <basetype id="jlong">
13604       <description>
13605         Holds a Java programming language <code>long</code>. 
13606         Signed 64 bits.
13607       </description>
13608     </basetype>
13609     <basetype id="jfloat">
13610       <description>
13611         Holds a Java programming language <code>float</code>. 
13612         32 bits.
13613       </description>
13614     </basetype>
13615     <basetype id="jdouble">
13616       <description>
13617         Holds a Java programming language <code>double</code>. 
13618         64 bits.
13619       </description>
13620     </basetype>
13621     <basetype id="jobject">
13622       <description>
13623         Holds a Java programming language object. 
13624       </description>
13625     </basetype>
13626     <basetype id="jclass">
13627       <description>
13628         Holds a Java programming language class. 
13629       </description>
13630     </basetype>
13631     <basetype id="jvalue">
13632       <description>
13633         Is a union of all primitive types and <code>jobject</code>.  Thus, holds any Java 
13634         programming language value. 
13635       </description>
13636     </basetype>
13637     <basetype id="jfieldID">
13638       <description>
13639         Identifies a Java programming language field. 
13640         <code>jfieldID</code>s returned by <jvmti/> functions and events may be
13641         safely stored.
13642       </description>
13643     </basetype>
13644     <basetype id="jmethodID">
13645       <description>
13646         Identifies a Java programming language method, initializer, or constructor. 
13647         <code>jmethodID</code>s returned by <jvmti/> functions and events may be
13648         safely stored.  However, if the class is unloaded, they become invalid
13649         and must not be used.
13650       </description>
13651     </basetype>
13652     <basetype id="JNIEnv">
13653       <description>
13654         Pointer to the JNI function table.  Pointer to this (<code>JNIEnv *</code>)
13655         is a JNI environment. 
13656       </description>
13657     </basetype>
13658   </basetypes>
13659 
13660   <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
13661     <basetype id="jvmtiEnv">
13662       <description>
13663         The <jvmti/> <internallink id="environments">environment</internallink> pointer. 
13664         See the <internallink id="FunctionSection">Function Section</internallink>.
13665         <code>jvmtiEnv</code> points to the 
13666         <internallink id="FunctionTable">function table</internallink> pointer.
13667       </description>
13668     </basetype>
13669     <basetype id="jthread">
13670       <definition>typedef jobject jthread;</definition>
13671       <description>
13672         Subtype of <datalink id="jobject"></datalink> that holds a thread.
13673       </description>
13674     </basetype>
13675     <basetype id="jthreadGroup">
13676       <definition>typedef jobject jthreadGroup;</definition>
13677       <description>
13678         Subtype of <datalink id="jobject"></datalink> that holds a thread group.
13679       </description>
13680     </basetype>
13681     <basetype id="jlocation">
13682       <definition>typedef jlong jlocation;</definition>
13683       <description>
13684         A 64 bit value, representing a monotonically increasing 
13685         executable position within a method. 
13686         <code>-1</code> indicates a native method.
13687         See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
13688         given VM.
13689       </description>
13690     </basetype>
13691     <basetype id="jrawMonitorID">
13692       <definition>struct _jrawMonitorID;
13693 typedef struct _jrawMonitorID *jrawMonitorID;</definition>
13694       <description>
13695         A raw monitor.
13696       </description>
13697     </basetype>
13698     <basetype id="jvmtiError">
13699       <description>
13700         Holds an error return code.
13701         See the <internallink id="ErrorSection">Error section</internallink> for possible values.
13702         <example>
13703 typedef enum { 
13704     JVMTI_ERROR_NONE = 0,  
13705     JVMTI_ERROR_INVALID_THREAD = 10,
13706       ... 
13707 } jvmtiError;
13708 </example>
13709       </description>
13710     </basetype>
13711     <basetype id="jvmtiEvent">
13712       <description>
13713         An identifier for an event type.
13714         See the <internallink id="EventSection">Event section</internallink> for possible values.
13715         It is guaranteed that future versions of this specification will 
13716         never assign zero as an event type identifier.
13717 <example>
13718 typedef enum { 
13719     JVMTI_EVENT_SINGLE_STEP = 1, 
13720     JVMTI_EVENT_BREAKPOINT = 2, 
13721       ... 
13722 } jvmtiEvent;
13723 </example>
13724       </description>
13725     </basetype>
13726     <basetype id="jvmtiEventCallbacks">
13727       <description>
13728         The callbacks used for events.
13729 <example>
13730 typedef struct {
13731     jvmtiEventVMInit VMInit;
13732     jvmtiEventVMDeath VMDeath;
13733       ... 
13734 } jvmtiEventCallbacks;
13735 </example>
13736         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> 
13737         for the complete structure.
13738         <p/>
13739         Where, for example, the VM initialization callback is defined:
13740 <example>
13741 typedef void (JNICALL *jvmtiEventVMInit)
13742     (jvmtiEnv *jvmti_env, 
13743      JNIEnv* jni_env,
13744      jthread thread);
13745 </example>
13746         See the individual events for the callback function definition.
13747       </description>
13748     </basetype>
13749     <basetype id="jniNativeInterface">
13750       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
13751       <description>
13752         Typedef for the JNI function table <code>JNINativeInterface</code>
13753         defined in the 
13754         <externallink id="docs/technotes/guides/jni/spec/functions.html#interface_function_table">
13755           JNI Specification</externallink>.
13756         The JNI reference implementation defines this with an underscore.
13757       </description>
13758     </basetype>
13759   </basetypes>
13760 
13761 </datasection>
13762 
13763 <issuessection label="Issues">
13764   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
13765     JVMDI requires that the agent suspend threads before calling
13766     certain sensitive functions.  JVMPI requires garbage collection to be 
13767     disabled before calling certain sensitive functions. 
13768     It was suggested that rather than have this requirement, that
13769     VM place itself in a suitable state before performing an
13770     operation.  This makes considerable sense since each VM
13771     knows its requirements and can most easily arrange a
13772     safe state.  
13773     <p/>
13774     The ability to externally suspend/resume threads will, of
13775     course, remain.  The ability to enable/disable garbage collection will not.
13776     <p/>
13777     This issue is resolved--suspend will not
13778     be required.  The spec has been updated to reflect this.
13779   </intro>
13780   
13781   <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
13782     There are a variety of approaches to sampling call stacks.
13783     The biggest bifurcation is between VM controlled and agent
13784     controlled.  
13785     <p/>
13786     This issue is resolved--agent controlled
13787     sampling will be the approach.
13788   </intro>
13789   
13790   <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
13791     JVMDI represents threads as jthread.  JVMPI primarily
13792     uses JNIEnv* to represent threads.  
13793     <p/>
13794     The Expert Group has chosen jthread as the representation
13795     for threads in <jvmti/>.
13796     JNIEnv* is sent by
13797     events since it is needed to JNI functions.  JNIEnv, per the
13798     JNI spec, are not supposed to be used outside their thread.
13799   </intro>
13800 
13801   <intro id="design" label="Resolved Issue: Method Representation">
13802     The JNI spec allows an implementation to depend on jclass/jmethodID
13803     pairs, rather than simply a jmethodID, to reference a method.  
13804     JVMDI, for consistency, choose the same representation.  
13805     JVMPI, however, specifies that a jmethodID alone maps to a
13806     method.  Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
13807     pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
13808     In fact, any JVM implementation that supports JVMPI must have
13809     such a representation.  
13810     <jvmti/> will use jmethodID as a unique representation of a method
13811     (no jclass is used).
13812     There should be efficiency gains, particularly in 
13813     functionality like stack dumping, to this representation.
13814     <p/>
13815     Note that fields were not used in JVMPI and that the access profile
13816     of fields differs from methods--for implementation efficiency 
13817     reasons, a jclass/jfieldID pair will still be needed for field 
13818     reference.
13819   </intro>
13820 
13821   <intro id="localReferenceIssue" label="Resolved Issue: Local References">
13822     Functions return local references. 
13823   </intro>
13824 
13825   <intro id="frameRep" label="Resolved Issue: Representation of frames">
13826     In JVMDI, a frame ID is used to represent a frame.  Problem with this
13827     is that a VM must track when a frame becomes invalid, a far better
13828     approach, and the one used in <jvmti/>, is to reference frames by depth.
13829   </intro>
13830 
13831   <intro id="requiredCapabilities" label="Issue: Required Capabilities">
13832     Currently, having a required capabilities means that the functionality
13833     is optional.   Capabilities are useful even for required functionality
13834     since they can inform the VM is needed set-up.  Thus, there should be
13835     a set of capabilities that a conformant implementation must provide
13836     (if requested during Agent_OnLoad).
13837   </intro>
13838 
13839   <intro id="taghint" label="Proposal: add tag hint function">
13840     A hint of the percentage of objects that will be tagged would 
13841     help the VM pick a good implementation.
13842   </intro>
13843 
13844   <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
13845   How difficult or easy would be to extend the monitor_info category to include 
13846     <pre>
13847   - current number of monitors 
13848   - enumeration of monitors 
13849   - enumeration of threads waiting on a given monitor 
13850     </pre>
13851   The reason for my question is the fact that current get_monitor_info support 
13852   requires the agent to specify a given thread to get the info which is probably 
13853   OK in the profiling/debugging space, while in the monitoring space the agent 
13854   could be watching the monitor list and then decide which thread to ask for 
13855   the info. You might ask why is this important for monitoring .... I think it 
13856   can aid in the detection/prediction of application contention caused by hot-locks.
13857   </intro>
13858 </issuessection>
13859 
13860 <changehistory id="ChangeHistory" update="09/05/07">
13861   <intro>
13862     The <jvmti/> specification is an evolving document with major, minor, 
13863     and micro version numbers.
13864     A released version of the specification is uniquely identified
13865     by its major and minor version.
13866     The functions, events, and capabilities in this specification 
13867     indicate a "Since" value which is the major and minor version in
13868     which it was introduced.
13869     The version of the specification implemented by the VM can 
13870     be retrieved at runtime with the <functionlink id="GetVersionNumber"/> 
13871     function.
13872   </intro>
13873   <change date="14 Nov 2002">
13874     Converted to XML document.
13875   </change>
13876   <change date="14 Nov 2002">
13877     Elided heap dump functions (for now) since what was there
13878     was wrong.
13879   </change>
13880   <change date="18 Nov 2002">
13881     Added detail throughout.
13882   </change>
13883   <change date="18 Nov 2002">
13884     Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
13885   </change>
13886   <change date="19 Nov 2002">
13887     Added AsyncGetStackTrace.
13888   </change>
13889   <change date="19 Nov 2002">
13890     Added jframeID return to GetStackTrace.
13891   </change>
13892   <change date="19 Nov 2002">
13893     Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
13894     since they are redundant with GetStackTrace.
13895   </change>
13896   <change date="19 Nov 2002">
13897     Elided ClearAllBreakpoints since it has always been redundant.
13898   </change>
13899   <change date="19 Nov 2002">
13900     Added GetSystemProperties.
13901   </change>
13902   <change date="19 Nov 2002">
13903     Changed the thread local storage functions to use jthread.
13904   </change>
13905   <change date="20 Nov 2002">
13906     Added GetJLocationFormat.
13907   </change>
13908   <change date="22 Nov 2002">
13909     Added events and introductory text.
13910   </change>
13911   <change date="22 Nov 2002">
13912     Cross reference type and constant definitions.
13913   </change>
13914   <change date="24 Nov 2002">
13915     Added DTD.
13916   </change>
13917   <change date="24 Nov 2002">
13918     Added capabilities function section.
13919   </change>
13920   <change date="29 Nov 2002">
13921     Assign capabilities to each function and event.
13922   </change>
13923   <change date="29 Nov 2002">
13924     Add <internallink id="jniIntercept">JNI interception functions</internallink>.
13925   </change>
13926   <change date="30 Nov 2002">
13927     Auto generate SetEventNotificationMode capabilities.
13928   </change>
13929   <change date="30 Nov 2002">
13930     Add <eventlink id="VMObjectAlloc"></eventlink> event.
13931   </change>
13932   <change date="30 Nov 2002">
13933     Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
13934   </change>
13935   <change date="30 Nov 2002">
13936     Add const to declarations.
13937   </change>
13938   <change date="30 Nov 2002">
13939     Change method exit and frame pop to send on exception.
13940   </change>
13941   <change date="1 Dec 2002">
13942     Add ForceGarbageCollection.
13943   </change>
13944   <change date="2 Dec 2002">
13945     Redo Xrun section; clarify GetStackTrace and add example;
13946     Fix width problems; use "agent" consistently.
13947   </change>
13948   <change date="8 Dec 2002">
13949     Remove previous start-up intro.
13950     Add <internallink id="environments"><jvmti/> Environments</internallink>
13951     section.
13952   </change>
13953   <change date="8 Dec 2002">
13954     Add <functionlink id="DisposeEnvironment"></functionlink>.
13955   </change>
13956   <change date="9 Dec 2002">
13957     Numerous minor updates.
13958   </change>
13959   <change date="15 Dec 2002">
13960     Add heap profiling functions added:
13961     get/set annotation, iterate live objects/heap.
13962     Add heap profiling functions place holder added:
13963     heap roots.
13964     Heap profiling event added: object free. 
13965     Heap profiling event redesigned: vm object allocation. 
13966     Heap profiling event placeholders added: garbage collection start/finish. 
13967     Native method bind event added.
13968   </change>
13969   <change date="19 Dec 2002">
13970     Revamp suspend/resume functions.
13971     Add origin information with jvmdi tag.
13972     Misc fixes.
13973   </change>
13974   <change date="24 Dec 2002">
13975     Add semantics to types.
13976   </change>
13977   <change date="27 Dec 2002">
13978     Add local reference section.
13979     Autogenerate parameter descriptions from types.
13980   </change>
13981   <change date="28 Dec 2002">
13982     Document that RunAgentThread sends threadStart.
13983   </change>
13984   <change date="29 Dec 2002">
13985     Remove redundant local ref and dealloc warning.
13986     Convert GetRawMonitorName to allocated buffer.
13987     Add GenerateEvents.
13988   </change>
13989   <change date="30 Dec 2002">
13990     Make raw monitors a type and rename to "jrawMonitorID".
13991   </change>
13992   <change date="1 Jan 2003">
13993     Include origin information.
13994     Clean-up JVMDI issue references.
13995     Remove Deallocate warnings which are now automatically generated.
13996   </change>
13997   <change date="2 Jan 2003">
13998     Fix representation issues for jthread.
13999   </change>
14000   <change date="3 Jan 2003">
14001     Make capabilities buffered out to 64 bits - and do it automatically.
14002   </change>
14003   <change date="4 Jan 2003">
14004     Make constants which are enumeration into enum types.
14005     Parameters now of enum type.
14006     Clean-up and index type section.
14007     Replace remaining datadef entities with callback.
14008   </change>
14009   <change date="7 Jan 2003">
14010     Correct GenerateEvents description.
14011     More internal semantics work.
14012   </change>
14013   <change date="9 Jan 2003">
14014     Replace previous GetSystemProperties with two functions
14015     which use allocated information instead fixed.
14016     Add SetSystemProperty.
14017     More internal semantics work.
14018   </change>
14019   <change date="12 Jan 2003">
14020     Add varargs to end of SetEventNotificationMode.
14021   </change>
14022   <change date="20 Jan 2003">
14023     Finish fixing spec to reflect that alloc sizes are jlong.
14024   </change>
14025   <change date="22 Jan 2003">
14026     Allow NULL as RunAgentThread arg.
14027   </change>
14028   <change date="22 Jan 2003">
14029     Fixed names to standardized naming convention
14030     Removed AsyncGetStackTrace.
14031   </change>
14032   <change date="29 Jan 2003">
14033     Since we are using jthread, removed GetThread.
14034   </change>
14035   <change date="31 Jan 2003">
14036     Change GetFieldName to allow NULLs like GetMethodName.
14037   </change>
14038   <change date="29 Feb 2003" version="v40">
14039       Rewrite the introductory text, adding sections on
14040       start-up, environments and bytecode instrumentation.
14041       Change the command line arguments per EG discussions.
14042       Add an introduction to the capabilities section.
14043       Add the extension mechanism category and functions.
14044       Mark for deletion, but clarified anyhow, SuspendAllThreads.
14045       Rename IterateOverLiveObjects to IterateOverReachableObjects and
14046       change the text accordingly.
14047       Clarify IterateOverHeap.
14048       Clarify CompiledMethodLoad.
14049       Discuss prerequisite state for Calling Functions.
14050       Clarify SetAllocationHooks.
14051       Added issues ("To be resolved:") through-out.
14052       And so on...
14053   </change>
14054   <change date="6 Mar 2003" version="v41">
14055       Remove struct from the call to GetOwnedMonitorInfo.
14056       Automatically generate most error documentation, remove
14057       (rather broken) hand written error doc.
14058       Better describe capability use (empty initial set).
14059       Add min value to jint params.
14060       Remove the capability can_access_thread_local_storage.
14061       Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
14062       same for *NOT_IMPLEMENTED.
14063       Description fixes.
14064   </change>
14065   <change date="8 Mar 2003" version="v42">
14066       Rename GetClassSignature to GetClassName.
14067       Rename IterateOverClassObjects to IterateOverInstancesOfClass.
14068       Remove GetMaxStack (operand stack isn't used in <jvmti/>).
14069       Description fixes: define launch-time, remove native frame pop
14070       from PopFrame, and assorted clarifications.
14071   </change>
14072   <change date="8 Mar 2003" version="v43">
14073       Fix minor editing problem.
14074   </change>
14075   <change date="10 Mar 2003" version="v44">
14076       Add phase information.
14077       Remap (compact) event numbers.
14078   </change>
14079   <change date="11 Mar 2003" version="v45">
14080       More phase information - allow "any".
14081       Elide raw monitor queries and events.
14082       Minor description fixes.
14083   </change>
14084   <change date="12 Mar 2003" version="v46">
14085       Add GetPhase.
14086       Use "phase" through document.
14087       Elide GetRawMonitorName.
14088       Elide GetObjectMonitors.
14089   </change>
14090   <change date="12 Mar 2003" version="v47">
14091       Fixes from link, XML, and spell checking.
14092       Auto-generate the callback structure.
14093   </change>
14094   <change date="13 Mar 2003" version="v48">
14095       One character XML fix.
14096   </change>
14097   <change date="13 Mar 2003" version="v49">
14098       Change function parameter names to be consistent with 
14099       event parameters (fooBarBaz becomes foo_bar_baz).
14100   </change>
14101   <change date="14 Mar 2003" version="v50">
14102       Fix broken link.  Fix thread markers.
14103   </change>
14104   <change date="14 Mar 2003" version="v51">
14105       Change constants so they are under 128 to workaround
14106       compiler problems.
14107   </change>
14108   <change date="23 Mar 2003" version="v52">
14109       Overhaul capabilities.  Separate GetStackTrace into
14110       GetStackTrace and GetStackFrames.
14111   </change>
14112   <change date="8 Apr 2003" version="v54">
14113       Use depth instead of jframeID to reference frames.
14114       Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
14115       Remove frame arg from events.
14116   </change>
14117   <change date="9 Apr 2003" version="v55">
14118       Remove GetObjectWithAnnotation since tests show bufferred approach more efficient.
14119       Add missing annotation_count to GetObjectsWithAnnotations
14120   </change>
14121   <change date="10 Apr 2003" version="v56">
14122       Remove confusing parenthetical statement in GetObjectsWithAnnotations
14123   </change>
14124   <change date="13 Apr 2003" version="v58">
14125       Replace jclass/jmethodID representation of method with simply jmethodID;
14126       Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
14127       Replace can_access_frames with can_access_local_variables; remove from purely stack access.
14128       Use can_get_synthetic_attribute; fix description.
14129       Clarify that zero length arrays must be deallocated.
14130       Clarify RelinquishCapabilities.
14131       Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
14132   </change>
14133   <change date="27 Apr 2003" version="v59">
14134       Remove lingering indirect references to OBSOLETE_METHOD_ID.
14135   </change>
14136   <change date="4 May 2003" version="v60">
14137       Allow DestroyRawMonitor during OnLoad.
14138   </change>
14139   <change date="7 May 2003" version="v61">
14140       Added not monitor owner error return to DestroyRawMonitor.
14141   </change>
14142   <change date="13 May 2003" version="v62">
14143       Clarify semantics of raw monitors.
14144       Change flags on <code>GetThreadStatus</code>.
14145       <code>GetClassLoader</code> return NULL for the bootstrap class loader.
14146       Add <code>GetClassName</code> issue.
14147       Define local variable signature.
14148       Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
14149       Remove over specification in <code>GetObjectsWithAnnotations</code>.
14150       Elide <code>SetAllocationHooks</code>.
14151       Elide <code>SuspendAllThreads</code>.
14152   </change>
14153   <change date="14 May 2003" version="v63">
14154       Define the data type <code>jvmtiEventCallbacks</code>.
14155       Zero length allocations return NULL.  
14156       Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.  
14157       Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
14158   </change>
14159   <change date="15 May 2003" version="v64">
14160       Better wording, per review.
14161   </change>
14162   <change date="15 May 2003" version="v65">
14163       First Alpha.
14164       Make jmethodID and jfieldID unique, jclass not used.
14165   </change>
14166   <change date="27 May 2003" version="v66">
14167       Fix minor XSLT errors.
14168   </change>
14169   <change date="13 June 2003" version="v67">
14170       Undo making jfieldID unique (jmethodID still is).
14171   </change>
14172   <change date="17 June 2003" version="v68">
14173       Changes per June 11th Expert Group meeting --
14174       Overhaul Heap functionality: single callback, 
14175       remove GetHeapRoots, add reachable iterators,
14176       and rename "annotation" to "tag".
14177       NULL thread parameter on most functions is current
14178       thread.
14179       Add timers.
14180       Remove ForceExit.
14181       Add GetEnvironmentLocalStorage.
14182       Add verbose flag and event.
14183       Add AddToBootstrapClassLoaderSearch.
14184       Update ClassFileLoadHook.
14185   </change>
14186   <change date="18 June 2003" version="v69">
14187       Clean up issues sections.
14188       Rename GetClassName back to GetClassSignature and
14189       fix description.
14190       Add generic signature to GetClassSignature, 
14191       GetFieldSignature, GetMethodSignature, and 
14192       GetLocalVariableTable.
14193       Elide EstimateCostOfCapabilities.
14194       Clarify that the system property functions operate
14195       on the VM view of system properties.
14196       Clarify Agent_OnLoad.
14197       Remove "const" from JNIEnv* in events.
14198       Add metadata accessors.
14199   </change>
14200   <change date="18 June 2003" version="v70">
14201       Add start_depth to GetStackTrace.
14202       Move system properties to a new category.
14203       Add GetObjectSize.
14204       Remove "X" from command line flags.
14205       XML, HTML, and spell check corrections.
14206   </change>
14207   <change date="19 June 2003" version="v71">
14208       Fix JVMTI_HEAP_ROOT_THREAD to be 6.
14209       Make each synopsis match the function name.
14210       Fix unclear wording.
14211   </change>
14212   <change date="26 June 2003" version="v72">
14213       SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
14214       to be set to NULL.
14215       NotifyFramePop, GetFrameLocationm and all the local variable operations
14216       needed to have their wording about frames fixed.
14217       Grammar and clarity need to be fixed throughout.
14218       Capitalization and puntuation need to be consistent.
14219       Need micro version number and masks for accessing major, minor, and micro.
14220       The error code lists should indicate which must be returned by
14221       an implementation.
14222       The command line properties should be visible in the properties functions.
14223       Disallow popping from the current thread.
14224       Allow implementations to return opaque frame error when they cannot pop.
14225       The NativeMethodBind event should be sent during any phase.
14226       The DynamicCodeGenerated event should be sent during any phase.
14227       The following functions should be allowed to operate before VMInit:
14228         Set/GetEnvironmentLocalStorage
14229         GetMethodDeclaringClass
14230         GetClassSignature
14231         GetClassModifiers
14232         IsInterface
14233         IsArrayClass
14234         GetMethodName
14235         GetMethodModifiers
14236         GetMaxLocals
14237         GetArgumentsSize
14238         GetLineNumberTable
14239         GetMethodLocation
14240         IsMethodNative
14241         IsMethodSynthetic.
14242       Other changes (to XSL):
14243       Argument description should show asterisk after not before pointers.
14244       NotifyFramePop, GetFrameLocationm and all the local variable operations
14245       should hsve the NO_MORE_FRAMES error added.
14246       Not alive threads should have a different error return than invalid thread.
14247   </change>
14248   <change date="7 July 2003" version="v73">
14249       VerboseOutput event was missing message parameter.
14250       Minor fix-ups.
14251   </change>
14252   <change date="14 July 2003" version="v74">
14253       Technical Publications Department corrections.
14254       Allow thread and environment local storage to be set to NULL.
14255   </change>
14256   <change date="23 July 2003" version="v75">
14257       Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
14258       Add JNICALL to callbacks (XSL).
14259       Document JNICALL requirement for both events and callbacks (XSL).
14260       Restrict RedefineClasses to methods and attributes.
14261       Elide the VerboseOutput event.
14262       VMObjectAlloc: restrict when event is sent and remove method parameter.
14263       Finish loose ends from Tech Pubs edit.
14264   </change>
14265   <change date="24 July 2003" version="v76">
14266       Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
14267   </change>
14268   <change date="24 July 2003" version="v77">
14269       XML fixes.
14270       Minor text clarifications and corrections.
14271   </change>
14272   <change date="24 July 2003" version="v78">
14273       Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
14274       Clarify that stack frames are JVM Spec frames.
14275       Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
14276       and can_get_source_debug_extension.
14277       PopFrame cannot have a native calling method.
14278       Removed incorrect statement in GetClassloaderClasses 
14279       (see <vmspec chapter="4.4"/>).
14280   </change>
14281   <change date="24 July 2003" version="v79">
14282       XML and text fixes.
14283       Move stack frame description into Stack Frame category.
14284   </change>
14285   <change date="26 July 2003" version="v80">
14286       Allow NULL (means bootstrap loader) for GetClassloaderClasses.
14287       Add new heap reference kinds for references from classes.
14288       Add timer information struct and query functions.
14289       Add AvailableProcessors.
14290       Rename GetOtherThreadCpuTime to GetThreadCpuTime.
14291       Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
14292       to SetEventNotification mode.
14293       Add initial thread to the VM_INIT event.
14294       Remove platform assumptions from AddToBootstrapClassLoaderSearch.
14295   </change>
14296   <change date="26 July 2003" version="v81">
14297       Grammar and clarity changes per review.
14298   </change>
14299   <change date="27 July 2003" version="v82">
14300       More grammar and clarity changes per review.
14301       Add Agent_OnUnload.
14302   </change>
14303   <change date="28 July 2003" version="v83">
14304       Change return type of Agent_OnUnload to void.
14305   </change>
14306   <change date="28 July 2003" version="v84">
14307       Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
14308   </change>
14309   <change date="28 July 2003" version="v85">
14310       Steal java.lang.Runtime.availableProcessors() wording for 
14311       AvailableProcessors().
14312       Guarantee that zero will never be an event ID.
14313       Remove some issues which are no longer issues.
14314       Per review, rename and more completely document the timer
14315       information functions.
14316   </change>
14317   <change date="29 July 2003" version="v86">
14318       Non-spec visible change to XML controlled implementation:
14319         SetThreadLocalStorage must run in VM mode.
14320   </change>
14321   <change date="5 August 2003" version="0.1.87">
14322       Add GetErrorName.
14323       Add varargs warning to jvmtiExtensionEvent.
14324       Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
14325       Remove unused can_get_exception_info capability.
14326       Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
14327       Fix jvmtiExtensionFunctionInfo.func declared type.
14328       Extension function returns error code.
14329       Use new version numbering.
14330   </change>
14331   <change date="5 August 2003" version="0.2.88">
14332       Remove the ClassUnload event.
14333   </change>
14334   <change date="8 August 2003" version="0.2.89">
14335       Heap reference iterator callbacks return an enum that 
14336       allows outgoing object references to be ignored.
14337       Allow JNIEnv as a param type to extension events/functions.
14338   </change>
14339   <change date="15 August 2003" version="0.2.90">
14340       Fix a typo.
14341   </change>
14342   <change date="2 September 2003" version="0.2.91">
14343       Remove all metadata functions: GetClassMetadata, 
14344       GetFieldMetadata, and GetMethodMetadata.
14345   </change>
14346   <change date="1 October 2003" version="0.2.92">
14347       Mark the functions Allocate. Deallocate, RawMonitor*, 
14348       SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage 
14349       as safe for use in heap callbacks and GC events.
14350   </change>
14351   <change date="24 November 2003" version="0.2.93">
14352       Add pass through opaque user data pointer to heap iterate 
14353       functions and callbacks.
14354       In the CompiledMethodUnload event, send the code address.
14355       Add GarbageCollectionOccurred event.
14356       Add constant pool reference kind.
14357       Mark the functions CreateRawMonitor and DestroyRawMonitor
14358       as safe for use in heap callbacks and GC events.
14359       Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, 
14360       GetThreadCpuTimerInfo, IterateOverReachableObjects,
14361       IterateOverObjectsReachableFromObject, GetTime and
14362       JVMTI_ERROR_NULL_POINTER.
14363       Add missing errors to: GenerateEvents and
14364       AddToBootstrapClassLoaderSearch.
14365       Fix description of ClassFileLoadHook name parameter.
14366       In heap callbacks and GC/ObjectFree events, specify
14367       that only explicitly allowed functions can be called.
14368       Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
14369       GetTimerInfo, and GetTime during callback.
14370       Allow calling SetTag/GetTag during the onload phase.
14371       SetEventNotificationMode, add: error attempted inappropriate
14372       thread level control.
14373       Remove jvmtiExceptionHandlerEntry.
14374       Fix handling of native methods on the stack -- 
14375       location_ptr param of GetFrameLocation, remove 
14376       JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
14377       jvmtiFrameInfo.location, and jlocation.
14378       Remove typo (from JVMPI) implying that the MonitorWaited
14379       event is sent on sleep.
14380   </change>
14381   <change date="25 November 2003" version="0.2.94">
14382       Clarifications and typos.
14383   </change>
14384   <change date="3 December 2003" version="0.2.95">
14385       Allow NULL user_data in heap iterators.
14386   </change>
14387   <change date="28 January 2004" version="0.2.97">
14388       Add GetThreadState, deprecate GetThreadStatus.
14389   </change>
14390   <change date="29 January 2004" version="0.2.98">
14391       INVALID_SLOT and TYPE_MISMATCH errors should be optional.
14392   </change>
14393   <change date="12 February 2004" version="0.2.102">
14394       Remove MonitorContendedExit.
14395       Added JNIEnv parameter to VMObjectAlloc.
14396       Clarified definition of class_tag and referrer_index 
14397       parameters to heap callbacks.
14398   </change>
14399   <change date="16 Febuary 2004" version="0.2.103">
14400       Document JAVA_TOOL_OPTIONS.
14401   </change>
14402   <change date="17 Febuary 2004" version="0.2.105">
14403       Divide start phase into primordial and start.
14404       Add VMStart event
14405       Change phase associations of functions and events.
14406   </change>
14407   <change date="18 Febuary 2004" version="0.3.6">
14408       Elide deprecated GetThreadStatus.
14409       Bump minor version, subtract 100 from micro version
14410   </change>
14411   <change date="18 Febuary 2004" version="0.3.7">
14412       Document that timer nanosecond values are unsigned.
14413       Clarify text having to do with native methods.
14414   </change>
14415   <change date="19 Febuary 2004" version="0.3.8">
14416       Fix typos.
14417       Remove elided deprecated GetThreadStatus.
14418   </change>
14419   <change date="23 Febuary 2004" version="0.3.9">
14420       Require NotifyFramePop to act on suspended threads.
14421   </change>
14422   <change date="24 Febuary 2004" version="0.3.10">
14423       Add capabilities 
14424         (<internallink id="jvmtiCapabilities.can_redefine_any_class"
14425          ><code>can_redefine_any_class</code></internallink>
14426       and 
14427          <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
14428          ><code>can_generate_all_class_hook_events</code></internallink>) 
14429       and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) 
14430       which allow some classes to be unmodifiable.
14431   </change>
14432   <change date="28 Febuary 2004" version="0.3.11">
14433       Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
14434   </change>
14435   <change date="8 March 2004" version="0.3.12">
14436       Clarified CompiledMethodUnload so that it is clear the event
14437       may be posted after the class has been unloaded.
14438   </change>
14439   <change date="5 March 2004" version="0.3.13">
14440       Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
14441   </change>
14442   <change date="13 March 2004" version="0.3.14">
14443       Added guideline for the use of the JNI FindClass function in event
14444       callback functions.
14445   </change>
14446   <change date="15 March 2004" version="0.3.15">
14447       Add GetAllStackTraces and GetThreadListStackTraces.
14448   </change>
14449   <change date="19 March 2004" version="0.3.16">
14450       ClassLoad and ClassPrepare events can be posted during start phase.
14451   </change>
14452   <change date="25 March 2004" version="0.3.17">
14453       Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
14454       GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
14455   </change>
14456   <change date="29 March 2004" version="0.3.18">
14457       Return the timer kind in the timer information structure.
14458   </change>
14459   <change date="31 March 2004" version="0.3.19">
14460       Spec clarifications:
14461       JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
14462       ForceGarbageCollection does not run finalizers.
14463       The context of the specification is the Java platform.
14464       Warn about early instrumentation.
14465   </change>
14466   <change date="1 April 2004" version="0.3.20">
14467       Refinements to the above clarifications and
14468       Clarify that an error returned by Agent_OnLoad terminates the VM.
14469   </change>
14470   <change date="1 April 2004" version="0.3.21">
14471       Array class creation does not generate a class load event.
14472   </change>
14473   <change date="7 April 2004" version="0.3.22">
14474       Align thread state hierarchy more closely with java.lang.Thread.State.
14475   </change>
14476   <change date="12 April 2004" version="0.3.23">
14477       Clarify the documentation of thread state.
14478   </change>
14479   <change date="19 April 2004" version="0.3.24">
14480       Remove GarbageCollectionOccurred event -- can be done by agent.
14481   </change>
14482   <change date="22 April 2004" version="0.3.25">
14483       Define "command-line option".
14484   </change>
14485   <change date="29 April 2004" version="0.3.26">
14486       Describe the intended use of bytecode instrumentation.
14487       Fix description of extension event first parameter.
14488   </change>
14489   <change date="30 April 2004" version="0.3.27">
14490       Clarification and typos.
14491   </change>
14492   <change date="18 May 2004" version="0.3.28">
14493       Remove DataDumpRequest event.
14494   </change>
14495   <change date="18 May 2004" version="0.3.29">
14496       Clarify RawMonitorWait with zero timeout.
14497       Clarify thread state after RunAgentThread.
14498   </change>
14499   <change date="24 May 2004" version="0.3.30">
14500       Clean-up: fix bad/old links, etc.
14501   </change>
14502   <change date="30 May 2004" version="0.3.31">
14503       Clarifications including:
14504       All character strings are modified UTF-8.
14505       Agent thread visibiity.
14506       Meaning of obsolete method version.
14507       Thread invoking heap callbacks,
14508   </change>
14509   <change date="1 June 2004" version="1.0.32">
14510       Bump major.minor version numbers to "1.0".
14511   </change>
14512   <change date="2 June 2004" version="1.0.33">
14513       Clarify interaction between ForceGarbageCollection 
14514       and ObjectFree.
14515   </change>
14516   <change date="6 June 2004" version="1.0.34">
14517       Restrict AddToBootstrapClassLoaderSearch and 
14518       SetSystemProperty to the OnLoad phase only.
14519   </change>
14520   <change date="11 June 2004" version="1.0.35">
14521       Fix typo in SetTag.
14522   </change>
14523   <change date="18 June 2004" version="1.0.36">
14524       Fix trademarks.
14525       Add missing parameter in example GetThreadState usage.
14526   </change>
14527   <change date="4 August 2004" version="1.0.37">
14528       Copyright updates.
14529   </change>
14530   <change date="5 November 2004" version="1.0.38">
14531       Add missing function table layout.
14532       Add missing description of C++ member function format of functions.
14533       Clarify that name in CFLH can be NULL.
14534       Released as part of <tm>J2SE</tm> 5.0.
14535   </change>
14536   <change date="24 April 2005" version="1.1.47">
14537       Bump major.minor version numbers to "1.1".
14538       Add ForceEarlyReturn* functions.
14539       Add GetOwnedMonitorStackDepthInfo function.
14540       Add GetCurrentThread function.
14541       Add "since" version marker.
14542       Add AddToSystemClassLoaderSearch.
14543       Allow AddToBootstrapClassLoaderSearch be used in live phase.
14544       Fix historic rubbish in the descriptions of the heap_object_callback 
14545       parameter of IterateOverHeap and IterateOverInstancesOfClass functions; 
14546       disallow NULL for this parameter.
14547       Clarify, correct and make consistent: wording about current thread,
14548       opaque frames and insufficient number of frames in PopFrame.
14549       Consistently use "current frame" rather than "topmost".
14550       Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
14551       by making them compatible with those in ForceEarlyReturn*.
14552       Many other clarifications and wording clean ups.
14553   </change>
14554   <change date="25 April 2005" version="1.1.48">
14555       Add GetConstantPool.
14556       Switch references to the first edition of the VM Spec, to the seconds edition.
14557   </change>
14558   <change date="26 April 2005" version="1.1.49">
14559       Clarify minor/major version order in GetConstantPool.
14560   </change>
14561   <change date="26 April 2005" version="1.1.50">
14562       Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
14563       Reassign GetOwnedMonitorStackDepthInfo to position 153.
14564       Break out Class Loader Search in its own documentation category.
14565       Deal with overly long lines in XML source.
14566   </change>
14567   <change date="29 April 2005" version="1.1.51">
14568       Allow agents be started in the live phase.
14569       Added paragraph about deploying agents.  
14570   </change>
14571   <change date="30 April 2005" version="1.1.52">
14572       Add specification description to SetNativeMethodPrefix(es).
14573       Better define the conditions on GetConstantPool.  
14574   </change>
14575   <change date="30 April 2005" version="1.1.53">
14576       Break out the GetClassVersionNumber function from GetConstantPool.
14577       Clean-up the references to the VM Spec.  
14578   </change>
14579   <change date="1 May 2005" version="1.1.54">
14580       Allow SetNativeMethodPrefix(es) in any phase.
14581       Add clarifications about the impact of redefinition on GetConstantPool.  
14582   </change>
14583   <change date="2 May 2005" version="1.1.56">
14584       Various clarifications to SetNativeMethodPrefix(es).
14585   </change>
14586   <change date="2 May 2005" version="1.1.57">
14587       Add missing performance warning to the method entry event.
14588   </change>
14589   <change date="5 May 2005" version="1.1.58">
14590       Remove internal JVMDI support.
14591   </change>
14592   <change date="8 May 2005" version="1.1.59">
14593       Add <functionlink id="RetransformClasses"/>.
14594       Revamp the bytecode instrumentation documentation.
14595       Change <functionlink id="IsMethodObsolete"/> to no longer 
14596       require the can_redefine_classes capability.
14597   </change>
14598   <change date="11 May 2005" version="1.1.63">
14599       Clarifications for retransformation.
14600   </change>
14601   <change date="11 May 2005" version="1.1.64">
14602       Clarifications for retransformation, per review.
14603       Lock "retransformation (in)capable" at class load enable time.
14604   </change>
14605   <change date="4 June 2005" version="1.1.67">
14606       Add new heap functionity which supports reporting primitive values,
14607       allows setting the referrer tag, and has more powerful filtering:
14608       FollowReferences, IterateThroughHeap, and their associated 
14609       callbacks, structs, enums, and constants.
14610   </change>
14611   <change date="4 June 2005" version="1.1.68">
14612       Clarification.
14613   </change>
14614   <change date="6 June 2005" version="1.1.69">
14615       FollowReferences, IterateThroughHeap: Put callbacks in a struct;
14616       Add missing error codes; reduce bits in the visit control flags.
14617   </change>
14618   <change date="14 June 2005" version="1.1.70">
14619       More on new heap functionity: spec clean-up per review.
14620   </change>
14621   <change date="15 June 2005" version="1.1.71">
14622       More on new heap functionity: Rename old heap section to Heap (1.0).
14623   </change>
14624   <change date="21 June 2005" version="1.1.72">
14625       Fix typos.
14626   </change>
14627   <change date="27 June 2005" version="1.1.73">
14628       Make referrer info structure a union.
14629   </change>
14630   <change date="9 September 2005" version="1.1.74">
14631       In new heap functions:
14632       Add missing superclass reference kind.
14633       Use a single scheme for computing field indexes.
14634       Remove outdated references to struct based referrer info.
14635   </change>
14636   <change date="12 September 2005" version="1.1.75">
14637       Don't callback during FollowReferences on frivolous java.lang.Object superclass.
14638   </change>
14639   <change date="13 September 2005" version="1.1.76">
14640       In string primitive callback, length now Unicode length.
14641       In array and string primitive callbacks, value now "const".
14642       Note possible compiler impacts on setting JNI function table.
14643   </change>
14644   <change date="13 September 2005" version="1.1.77">
14645       GetClassVersionNumbers() and GetConstantPool() should return
14646       error on array or primitive class.
14647   </change>
14648   <change date="14 September 2005" version="1.1.78">
14649       Grammar fixes.
14650   </change>
14651   <change date="26 September 2005" version="1.1.79">
14652       Add IsModifiableClass query.
14653   </change>
14654   <change date="9 February 2006" version="1.1.81">
14655       Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
14656   </change>
14657   <change date="13 February 2006" version="1.1.82">
14658       Doc fixes: update can_redefine_any_class to include retransform.
14659       Clarify that exception events cover all Throwables.
14660       In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
14661       Clarify fields reported in Primitive Field Callback -- static vs instance.
14662       Repair confusing names of heap types, including callback names.
14663       Require consistent usage of stack depth in the face of thread launch methods.
14664       Note incompatibility of <jvmti/> memory management with other systems.
14665   </change>
14666   <change date="14 February 2006" version="1.1.85">
14667       Fix typos and missing renames.
14668   </change>
14669   <change date="13 March 2006" version="1.1.86">
14670       Clarify that jmethodIDs and jfieldIDs can be saved.
14671       Clarify that Iterate Over Instances Of Class includes subclasses.
14672   </change>
14673   <change date="14 March 2006" version="1.1.87">
14674       Better phrasing.
14675   </change>
14676   <change date="16 March 2006" version="1.1.88">
14677       Match the referrer_index for static fields in Object Reference Callback 
14678       with the Reference Implementation (and all other known implementations);
14679       that is, make it match the definition for instance fields.
14680       In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover 
14681       an invalid thread in the list; and specify that not started threads
14682       return empty stacks.
14683   </change>
14684   <change date="17 March 2006" version="1.1.89">
14685       Typo.
14686   </change>
14687   <change date="25 March 2006" version="1.1.90">
14688       Typo.
14689   </change>
14690   <change date="6 April 2006" version="1.1.91">
14691       Remove restrictions on AddToBootstrapClassLoaderSearch and
14692       AddToSystemClassLoaderSearch.
14693   </change>
14694   <change date="1 May 2006" version="1.1.93">
14695       Changed spec to return -1 for monitor stack depth for the
14696       implementation which can not determine stack depth. 
14697   </change>
14698   <change date="3 May 2006" version="1.1.94">
14699       Corrections for readability and accuracy courtesy of Alan Pratt of IBM. 
14700       List the object relationships reported in FollowReferences.
14701   </change>
14702   <change date="5 May 2006" version="1.1.95">
14703       Clarify the object relationships reported in FollowReferences.
14704   </change>
14705   <change date="28 June 2006" version="1.1.98">
14706       Clarify DisposeEnvironment; add warning.
14707       Fix typos in SetLocalXXX "retrieve" => "set".
14708       Clarify that native method prefixes must remain set while used.
14709       Clarify that exactly one Agent_OnXXX is called per agent.
14710       Clarify that library loading is independent from start-up.
14711       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14712   </change>
14713   <change date="31 July 2006" version="1.1.99">
14714       Clarify the interaction between functions and exceptions.
14715       Clarify and give examples of field indices.
14716       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14717       Update links to point to Java 6.
14718   </change>
14719   <change date="6 August 2006" version="1.1.102">
14720       Add ResourceExhaustedEvent.
14721   </change>
14722   <change date="11 October 2012" version="1.2.2">
14723       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14724   </change>
14725   <change date="19 June 2013" version="1.2.3">
14726       Added support for statically linked agents.
14727   </change>
14728   <change date="13 October 2016" version="9.0.0">
14729       Support for modules:
14730        - The majorversion is 9 now
14731        - The ClassFileLoadHook events are not sent during the primordial phase anymore.
14732        - Allow CompiledMethodLoad events at start phase
14733        - Add new capabilities:
14734           - can_generate_early_vmstart
14735           - can_generate_early_class_hook_events
14736        - Add new functions:
14737           - GetAllModules
14738           - AddModuleReads, AddModuleExports, AddModuleOpens, AddModuleUses, AddModuleProvides
14739       Clarified can_redefine_any_classes, can_retransform_any_classes and IsModifiableClass API to
14740       disallow some implementation defined classes.
14741   </change>
14742   <change date="12 February 2017" version="9.0.0">
14743       Minor update for GetCurrentThread function:
14744        - The function may return NULL in the start phase if the
14745          can_generate_early_vmstart capability is enabled.
14746   </change>
14747 </changehistory>
14748 
14749 </specification>
14750 <!-- Keep this comment at the end of the file
14751 Local variables:
14752 mode: sgml
14753 sgml-omittag:t
14754 sgml-shorttag:t
14755 sgml-namecase-general:t
14756 sgml-general-insert-case:lower
14757 sgml-minimize-attributes:nil
14758 sgml-always-quote-attributes:t
14759 sgml-indent-step:2
14760 sgml-indent-data:t
14761 sgml-parent-document:nil
14762 sgml-exposed-tags:nil
14763 sgml-local-catalogs:nil
14764 sgml-local-ecat-files:nil
14765 End:
14766 -->