1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
   3 <!--
   4  Copyright (c) 2002, 2016, Oracle and/or its affiliates. All rights reserved.
   5  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6 
   7  This code is free software; you can redistribute it and/or modify it
   8  under the terms of the GNU General Public License version 2 only, as
   9  published by the Free Software Foundation.
  10 
  11  This code is distributed in the hope that it will be useful, but WITHOUT
  12  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  version 2 for more details (a copy is included in the LICENSE file that
  15  accompanied this code).
  16 
  17  You should have received a copy of the GNU General Public License version
  18  2 along with this work; if not, write to the Free Software Foundation,
  19  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20 
  21  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  or visit www.oracle.com if you need additional information or have any
  23  questions.
  24 
  25 -->
  26 
  27 <!DOCTYPE specification [
  28    <!ELEMENT specification (title, intro*, functionsection, errorsection, 
  29                             eventsection, datasection, issuessection, changehistory)>
  30    <!ATTLIST specification label CDATA #REQUIRED 
  31                            majorversion CDATA #REQUIRED 
  32                            minorversion CDATA #REQUIRED 
  33                            microversion CDATA #REQUIRED>
  34 
  35    <!ELEMENT title (#PCDATA|jvmti|tm)*>
  36    <!ATTLIST title subtitle CDATA #REQUIRED>
  37 
  38    <!ELEMENT intro ANY>
  39    <!ATTLIST intro id CDATA #IMPLIED
  40                    label CDATA "">
  41 
  42    <!ELEMENT functionsection (intro*, category*)>
  43    <!ATTLIST functionsection label CDATA #REQUIRED>
  44 
  45    <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*, 
  46                           (function|callback|elide)*)>
  47    <!ATTLIST category id CDATA #REQUIRED
  48                       label CDATA #REQUIRED>
  49 
  50    <!ELEMENT function (synopsis, typedef*, description?, origin,
  51                          (capabilities|eventcapabilities), 
  52                          parameters, errors)>
  53    <!ATTLIST function id CDATA #REQUIRED
  54                       num CDATA #REQUIRED
  55                       phase (onload|onloadOnly|start|live|any) #IMPLIED
  56                       callbacksafe (safe|unsafe) #IMPLIED
  57                       impl CDATA #IMPLIED
  58                       hide CDATA #IMPLIED
  59                       jkernel (yes|no) #IMPLIED
  60                       since CDATA "1.0">
  61 
  62    <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  63                         jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
  64                         synopsis, description?, parameters)>
  65    <!ATTLIST callback id CDATA #REQUIRED
  66                       since CDATA "1.0">
  67 
  68    <!ELEMENT synopsis (#PCDATA|jvmti)*>
  69 
  70    <!ELEMENT typedef (description?, field*)>
  71    <!ATTLIST typedef id CDATA #REQUIRED
  72                      label CDATA #REQUIRED
  73                      since CDATA "1.0">
  74 
  75    <!ELEMENT uniontypedef (description?, field*)>
  76    <!ATTLIST uniontypedef id CDATA #REQUIRED
  77                      label CDATA #REQUIRED
  78                      since CDATA "1.0">
  79 
  80    <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  81                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct), 
  82                     description)>
  83    <!ATTLIST field id CDATA #REQUIRED>
  84 
  85    <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
  86    <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
  87                      label CDATA #REQUIRED>
  88 
  89    <!ELEMENT capabilityfield (description)>
  90    <!ATTLIST capabilityfield id CDATA #REQUIRED
  91                    disp1 CDATA ""
  92                    disp2 CDATA ""
  93                    since CDATA "1.0">
  94 
  95    <!ELEMENT description ANY>
  96 
  97    <!ELEMENT capabilities (required*, capability*)>
  98 
  99    <!ELEMENT eventcapabilities EMPTY>
 100 
 101    <!ELEMENT required ANY>
 102    <!ATTLIST required id CDATA #REQUIRED>
 103 
 104    <!ELEMENT capability ANY>
 105    <!ATTLIST capability id CDATA #REQUIRED>
 106 
 107    <!ELEMENT parameters (param*)>
 108 
 109    <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
 110                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
 111                      outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf), 
 112                     description)>
 113    <!ATTLIST param id CDATA #REQUIRED>
 114 
 115    <!ELEMENT jmethodID EMPTY>
 116    <!ATTLIST jmethodID class  CDATA #IMPLIED
 117                        native CDATA #IMPLIED>
 118 
 119    <!ELEMENT jfieldID EMPTY>
 120    <!ATTLIST jfieldID class CDATA #IMPLIED>
 121 
 122    <!ELEMENT jclass EMPTY>
 123    <!ATTLIST jclass method CDATA #IMPLIED
 124                     field  CDATA #IMPLIED>
 125 
 126    <!ELEMENT jframeID EMPTY>
 127    <!ATTLIST jframeID thread CDATA #IMPLIED>
 128 
 129    <!ELEMENT jrawMonitorID EMPTY>
 130 
 131    <!ELEMENT jthread EMPTY>
 132    <!ATTLIST jthread started CDATA #IMPLIED
 133                      null CDATA #IMPLIED
 134                      frame CDATA #IMPLIED
 135                      impl CDATA #IMPLIED>
 136 
 137    <!ELEMENT varargs EMPTY>
 138 
 139    <!ELEMENT jthreadGroup EMPTY>
 140    <!ELEMENT jobject EMPTY>
 141    <!ELEMENT jvalue EMPTY>
 142    <!ELEMENT jchar EMPTY>
 143    <!ELEMENT jint EMPTY>
 144    <!ATTLIST jint min CDATA #IMPLIED>
 145    <!ELEMENT jlong EMPTY>
 146    <!ELEMENT jfloat EMPTY>
 147    <!ELEMENT jdouble EMPTY>
 148    <!ELEMENT jlocation EMPTY>
 149    <!ELEMENT jboolean EMPTY>
 150    <!ELEMENT char EMPTY>
 151    <!ELEMENT uchar EMPTY>
 152    <!ELEMENT size_t EMPTY>
 153    <!ELEMENT void EMPTY>
 154    <!ELEMENT enum (#PCDATA)*>
 155    <!ELEMENT struct (#PCDATA)*>
 156 
 157    <!ELEMENT nullok ANY>
 158 
 159    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 160                                    jthreadGroup|jobject|jvalue), nullok?)>
 161 
 162    <!ELEMENT outptr     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 163                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 164                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 165 
 166    <!ELEMENT allocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 167                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 168                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 169    <!ATTLIST allocbuf incount CDATA #IMPLIED
 170                       outcount CDATA #IMPLIED>
 171 
 172    <!ELEMENT allocallocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 173                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 174                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 175    <!ATTLIST allocallocbuf incount CDATA #IMPLIED
 176                       outcount CDATA #IMPLIED>
 177 
 178    <!ELEMENT inptr      (struct, nullok?)>
 179 
 180    <!ELEMENT inbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 181                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 182                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 183    <!ATTLIST inbuf    incount CDATA #IMPLIED>
 184 
 185    <!ELEMENT outbuf     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 186                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 187                                    jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
 188    <!ATTLIST outbuf   incount CDATA #IMPLIED
 189                       outcount CDATA #IMPLIED>
 190 
 191    <!ELEMENT vmbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 192                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 193                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 194    <!ATTLIST vmbuf    incount CDATA #IMPLIED
 195                       outcount CDATA #IMPLIED>
 196 
 197    <!ELEMENT agentbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 198                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 199                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 200    <!ATTLIST agentbuf incount CDATA #IMPLIED
 201                       outcount CDATA #IMPLIED>
 202 
 203    <!ELEMENT allocfieldbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 204                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 205                                    jlocation|jboolean|char|uchar|size_t|void))>
 206    <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
 207 
 208    <!ELEMENT errors (error*)>
 209 
 210    <!ELEMENT error ANY>
 211    <!ATTLIST error id CDATA #REQUIRED>
 212 
 213    <!ELEMENT errorsection (intro*, errorcategory*)>
 214    <!ATTLIST errorsection label CDATA #REQUIRED>
 215 
 216    <!ELEMENT errorcategory (intro*, errorid*)>
 217    <!ATTLIST errorcategory id CDATA #REQUIRED
 218                            label CDATA #REQUIRED>
 219 
 220    <!ELEMENT errorid ANY>
 221    <!ATTLIST errorid id CDATA #REQUIRED
 222                      num CDATA #REQUIRED>
 223 
 224    <!ELEMENT datasection (intro*, basetypes*)>
 225 
 226    <!ELEMENT basetypes (intro*, basetype*)>
 227    <!ATTLIST basetypes id CDATA #REQUIRED
 228                        label CDATA #REQUIRED>
 229 
 230    <!ELEMENT basetype (definition?,description)>
 231    <!ATTLIST basetype id CDATA #REQUIRED>
 232 
 233    <!ELEMENT definition (#PCDATA|jvmti)*>
 234 
 235    <!ELEMENT eventsection (intro*, (event|elide)*)>
 236    <!ATTLIST eventsection label CDATA #REQUIRED>
 237 
 238    <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
 239    <!ATTLIST event id CDATA #REQUIRED
 240                    label CDATA #REQUIRED
 241                    const CDATA #REQUIRED
 242                    num CDATA #REQUIRED
 243                    phase (onload|start|live|any) #IMPLIED
 244                    filtered (thread|global) #IMPLIED
 245                    since CDATA "1.0">
 246 
 247    <!ELEMENT issuessection (intro*)>
 248    <!ATTLIST issuessection label CDATA #REQUIRED>
 249 
 250    <!ELEMENT changehistory (intro*, change*)>
 251    <!ATTLIST changehistory update CDATA #REQUIRED
 252                            id CDATA #REQUIRED>
 253 
 254    <!ELEMENT change ANY>
 255    <!ATTLIST change date CDATA #REQUIRED
 256                     version CDATA #IMPLIED>
 257 
 258    <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
 259    <!ATTLIST functionlink id CDATA #REQUIRED>
 260 
 261    <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
 262    <!ATTLIST datalink id CDATA #REQUIRED>
 263 
 264    <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
 265    <!ATTLIST typelink id CDATA #REQUIRED>
 266 
 267    <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
 268    <!ATTLIST fieldlink id CDATA #REQUIRED
 269                        struct CDATA #REQUIRED>
 270 
 271    <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
 272    <!ATTLIST paramlink id CDATA #REQUIRED>
 273 
 274    <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
 275    <!ATTLIST eventlink id CDATA #REQUIRED>
 276 
 277    <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
 278    <!ATTLIST errorlink id CDATA #REQUIRED>
 279 
 280    <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
 281    <!ATTLIST externallink id CDATA #REQUIRED>
 282 
 283    <!ELEMENT vmspec EMPTY>
 284    <!ATTLIST vmspec chapter CDATA #IMPLIED>
 285 
 286    <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
 287    <!ATTLIST internallink id CDATA #REQUIRED>
 288 
 289    <!ELEMENT functionphaselist EMPTY>
 290    <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
 291 
 292    <!ELEMENT eventphaselist EMPTY>
 293    <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
 294 
 295    <!ELEMENT issue ANY>
 296    
 297    <!ELEMENT rationale ANY>
 298    
 299    <!ELEMENT todo ANY>
 300    
 301    <!ELEMENT origin (#PCDATA)*>
 302 
 303    <!ELEMENT elide (intro|function|callback|event)*>
 304    <!ATTLIST elide why CDATA #IMPLIED>
 305    
 306    <!ELEMENT constants (constant*)>
 307    <!ATTLIST constants id CDATA #REQUIRED
 308                        label CDATA #REQUIRED
 309                        kind (enum|bits|const) #REQUIRED
 310                        since CDATA "1.0">
 311 
 312    <!ELEMENT constant ANY>
 313    <!ATTLIST constant id CDATA #REQUIRED
 314                       num CDATA #REQUIRED>
 315 
 316    <!ELEMENT tm (#PCDATA)>
 317 
 318    <!ELEMENT i (#PCDATA|jvmti|tm)*>
 319 
 320    <!ELEMENT b (#PCDATA|jvmti|code)*>
 321 
 322    <!ELEMENT code (#PCDATA|space)*>
 323 
 324    <!ELEMENT pre ANY>
 325 
 326    <!ELEMENT space EMPTY>
 327 
 328    <!ELEMENT jvmti EMPTY>
 329 
 330    <!ELEMENT example (#PCDATA|i)*>
 331 
 332    <!ELEMENT br EMPTY>
 333 
 334    <!ELEMENT p EMPTY>
 335 
 336    <!ELEMENT dl  (dt|dd)+>
 337 
 338    <!ELEMENT dd  ANY>
 339 
 340    <!ELEMENT dt  (#PCDATA|jvmti|code|i|b)*>
 341 
 342    <!ELEMENT table  (tr)+>
 343 
 344    <!ELEMENT tr  (td|th)*>
 345 
 346    <!ELEMENT td  ANY>
 347    <!ATTLIST td align (left|right|center) "center">
 348 
 349    <!ELEMENT th  ANY>
 350    <!ATTLIST th align (left|right|center) "center">
 351 
 352    <!ELEMENT ul  (li)+>
 353    <!ATTLIST ul type (disc|circle|square) "disc">
 354 
 355    <!ELEMENT li  ANY>
 356  ]>
 357 
 358 <specification label="JVM(TM) Tool Interface"
 359         majorversion="9"
 360         minorversion="0"
 361         microversion="0">
 362   <title subtitle="Version">
 363     <tm>JVM</tm> Tool Interface
 364   </title>
 365   
 366   <intro id="whatIs" label="What is the JVM Tool Interface?">
 367     The <tm>JVM</tm> Tool Interface (<jvmti/>) 
 368     is a programming interface used by development and monitoring tools. 
 369     It provides both a way to inspect the state and 
 370     to control the execution of applications running in the
 371     <tm>Java</tm> virtual machine (VM).
 372     <p/>
 373     <jvmti/> is intended to provide a VM interface for the full breadth of tools
 374     that need access to VM state, including but not limited to: profiling,
 375     debugging, monitoring, thread analysis, and coverage analysis tools.
 376     <p/>
 377     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
 378     machine.
 379     <p/>
 380     <jvmti/> is a two-way interface. 
 381     A client of <jvmti/>, hereafter called an <i>agent</i>,
 382     can be notified of
 383     interesting occurrences through <internallink id="EventSection">events</internallink>. 
 384     <jvmti/>
 385     can query and control the application through many 
 386     <internallink id="FunctionSection">functions</internallink>, 
 387     either in response to events or 
 388     independent of them.
 389     <p/>
 390     Agents run in the same process with and communicate directly with 
 391     the virtual machine executing
 392     the application being examined.  This communication is
 393     through a native interface (<jvmti/>). The native in-process interface allows
 394     maximal control with minimal intrusion on the part of a tool. 
 395     Typically, agents are relatively compact. They can be controlled
 396     by a separate process which implements the bulk of a tool's
 397     function without interfering with the target application's normal execution.
 398   </intro>
 399 
 400   <intro id="architecture" label="Architecture">
 401     Tools can be written directly to <jvmti/> or indirectly
 402     through higher level interfaces.
 403     The Java Platform Debugger Architecture includes <jvmti/>, but also
 404     contains higher-level, out-of-process debugger interfaces. The higher-level 
 405     interfaces are more appropriate than <jvmti/> for many tools. 
 406     For more information on the Java Platform Debugger Architecture, 
 407     see the 
 408     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">Java 
 409       Platform Debugger Architecture website</externallink>. 
 410   </intro>
 411 
 412   <intro id="writingAgents" label="Writing Agents">
 413     Agents can be written in any native language that supports C
 414     language calling conventions and C or C++
 415     definitions.
 416     <p/>
 417     The function, event, data type, and constant definitions needed for
 418     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 419     To use these definitions add the <tm>J2SE</tm> include directory
 420     to your include path and add
 421     <example>
 422 #include &lt;jvmti.h&gt;
 423     </example>
 424     to your source code.
 425   </intro>
 426 
 427   <intro id="deployingAgents" label="Deploying Agents">
 428     An agent is deployed in a platform specific manner but is typically the 
 429     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating 
 430     system, for example, an agent library is a "Dynamic Linked Library" (DLL). 
 431     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
 432     object (<code>.so</code> file).
 433     <p/>
 434 
 435     An agent may be started at VM startup by specifying the agent library
 436     name using a <internallink id="starting">command line option</internallink>.
 437     Some implementations may support a mechanism to <internallink id="onattach"> 
 438     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
 439     The details of how this is initiated are implementation specific.
 440   </intro>
 441 
 442     <intro id="entry point" label="Statically Linked Agents (since version 1.2.3)">
 443 
 444       A native JVMTI Agent may be <i>statically linked</i> with the VM.
 445       The manner in which the library and VM image are combined is
 446       implementation-dependent.
 447       An agent L whose image has been combined with the VM is defined as
 448       <i>statically linked</i> if and only if the agent exports a function
 449       called Agent_OnLoad_L.
 450 <p/>
 451       If a <i>statically linked</i> agent L exports a function called
 452       Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
 453       function will be ignored.
 454       If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
 455       function will be invoked with the same arguments and expected return
 456       value as specified for the Agent_OnLoad function.
 457       An agent L that is <i>statically linked</i> will prohibit an agent of
 458       the same name from being loaded dynamically.
 459 <p/>
 460       The VM will invoke the Agent_OnUnload_L function of the agent, if such
 461       a function is exported, at the same point during VM execution as it would
 462       have called the dynamic entry point Agent_OnUnLoad. A statically loaded
 463       agent cannot be unloaded. The Agent_OnUnload_L function will still be
 464       called to do any other agent shutdown related tasks. 
 465       If a <i>statically linked</i> agent L exports a function called
 466       Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
 467       function will be ignored.
 468 <p/>
 469       If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
 470       will be invoked with the same arguments and expected return value as
 471       specified for the Agent_OnAttach function.
 472       If a <i>statically linked</i> agent L exports a function called
 473       Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
 474       function will be ignored.
 475 </intro>
 476   
 477   <intro id="starting" label="Agent Command Line Options">
 478     The term "command-line option" is used below to
 479     mean options supplied in the <code>JavaVMInitArgs</code> argument
 480     to the <code>JNI_CreateJavaVM</code> function of the JNI
 481     Invocation API.
 482     <p/>
 483     One of the two following 
 484     command-line options is used on VM startup to 
 485     properly load and run agents.
 486     These arguments identify the library containing 
 487     the agent as well as an options
 488     string to be passed in at startup. 
 489     <dl>
 490       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 491       <dd>
 492         The name following <code>-agentlib:</code> is the name of the
 493         library to load.  Lookup of the library, both its full name and location,
 494         proceeds in a platform-specific manner.
 495         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
 496         operating system specific file name.
 497         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 498         For example, if the option 
 499         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to 
 500         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
 501         under <tm>Windows</tm> or <code>libfoo.so</code> from the 
 502         <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating
 503         environment.
 504         If the agent library is statically linked into the executable
 505         then no actual loading takes place.
 506     <p/>
 507       </dd>
 508       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 509       <dd>
 510         The path following <code>-agentpath:</code> is the absolute path from which
 511         to load the library.
 512         No library name expansion will occur.
 513         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 514         For example, if the option 
 515         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to 
 516         load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
 517         library is statically linked into the executable
 518         then no actual loading takes place.
 519     <p/>
 520       </dd>
 521     </dl>
 522     For a dynamic shared library agent, the start-up routine
 523     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 524     in the library will be invoked. If the agent library is statically linked
 525     into the executable then the system will attempt to invoke the
 526     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> entry point where
 527     &lt;agent-lib-name&gt; is the basename of the 
 528     agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
 529     the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
 530     <p/>
 531     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
 532     will be searched for JNI native method implementations to facilitate the
 533     use of Java programming language code in tools, as is needed for 
 534     <internallink id="bci">bytecode instrumentation</internallink>.
 535     <p/>
 536     The agent libraries will be searched after all other libraries have been
 537     searched (agents wishing to override or intercept the native method
 538     implementations of non-agent methods can use the
 539     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
 540     <p/>
 541     These switches do the above and nothing more - they do not change the 
 542     state of the VM or <jvmti/>.  No command line options are needed 
 543     to enable <jvmti/> 
 544     or aspects of <jvmti/>, this is handled programmatically
 545     by the use of 
 546     <internallink id="capability">capabilities</internallink>.
 547   </intro>
 548 
 549   <intro id="startup" label="Agent Start-Up">
 550     The VM starts each agent by invoking a start-up function.
 551     If the agent is started in the <code>OnLoad</code>
 552     <functionlink id="GetPhase">phase</functionlink> the function
 553     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 554     or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
 555     for statically linked agents will be invoked.
 556     If the agent is started in the live
 557     <functionlink id="GetPhase">phase</functionlink> the function
 558     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
 559     or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
 560     for statically linked agents will be invoked.
 561     Exactly one call to a start-up function is made per agent.  
 562   </intro>
 563 
 564   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
 565     If an agent is started during the <code>OnLoad</code> phase then its
 566     agent library must export a start-up function with the following prototype:
 567     <example>
 568 JNIEXPORT jint JNICALL 
 569 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
 570     Or for a statically linked agent named 'L':
 571     <example>
 572 JNIEXPORT jint JNICALL 
 573 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
 574 
 575     The VM will start the agent by calling this function.  
 576     It will be called early enough in VM initialization that:
 577     <ul>
 578       <li><functionlink id="SetSystemProperty">system properties</functionlink>
 579         may be set before they have been used in the start-up of the VM</li>
 580       <li>the full set of 
 581         <internallink id="capability">capabilities</internallink>
 582         is still available (note that capabilities that configure the VM
 583         may only be available at this time--see the 
 584         <internallink id="capability">Capability function section</internallink>)</li>
 585       <li>no bytecodes have executed</li>
 586       <li>no classes have been loaded</li>
 587       <li>no objects have been created</li>
 588     </ul>
 589     <p/>
 590     The VM will call the <code>Agent_OnLoad</code> or
 591     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> function with
 592     <i>&lt;options&gt;</i> as the second argument - 
 593     that is, using the command-line option examples,
 594     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> 
 595     argument of <code>Agent_OnLoad</code>.
 596     The <code>options</code> argument is encoded as a
 597     <internallink id="mUTF">modified UTF-8</internallink> string.
 598     If <i>=&lt;options&gt;</i> is not specified, 
 599     a zero length string is passed to <code>options</code>.
 600     The lifespan of the <code>options</code> string is the
 601     <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code>
 602     call.  If needed beyond this time the string or parts of the string must
 603     be copied.
 604     The period between when <code>Agent_OnLoad</code> is called and when it
 605     returns is called the <i>OnLoad phase</i>.
 606     Since the VM is not initialized during the OnLoad 
 607     <functionlink id="GetPhase">phase</functionlink>,
 608     the set of allowed operations 
 609     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
 610     functionality available at this time). 
 611     The agent can safely process the options and set 
 612     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once  
 613     the VM initialization event is received 
 614     (that is, the <eventlink id="VMInit">VMInit</eventlink> 
 615     callback is invoked), the agent
 616     can complete its initialization.
 617     <rationale>
 618       Early startup is required so that agents can set the desired capabilities,
 619       many of which must be set before the VM is initialized.
 620       In JVMDI, the -Xdebug command-line option provided 
 621       very coarse-grain control of capabilities. 
 622       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
 623       No reasonable command-line 
 624       option could provide the fine-grain of control required to balance needed capabilities vs
 625       performance impact.  
 626       Early startup is also needed so that agents can control the execution
 627       environment - modifying the file system and system properties to install
 628       their functionality.
 629     </rationale>
 630     <p/>
 631     The return value from <code>Agent_OnLoad</code> or
 632     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> is used to indicate an error.
 633     Any value other than zero indicates an error and causes termination of the VM.
 634   </intro>
 635   
 636   <intro id="onattach" label="Agent Start-Up (Live phase)">
 637     A VM may support a mechanism that allows agents to be started in the VM during the live 
 638     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
 639     are implementation specific. For example, a tool may use some platform specific mechanism, 
 640     or implementation specific API, to attach to the running VM, and request it start a given
 641     agent.
 642     <p/>
 643     If an agent is started during the live phase then its agent library
 644     must export a start-up function 
 645     with the following prototype:
 646     <example>
 647 JNIEXPORT jint JNICALL 
 648 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
 649 Or for a statically linked agent named 'L':
 650     <example>
 651 JNIEXPORT jint JNICALL 
 652 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
 653 
 654     <p/>         
 655     The VM will start the agent by calling this function.  
 656     It will be called in the context of a thread
 657     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
 658     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
 659     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
 660     </internallink> string.
 661     If startup options were not provided, a zero length string is passed to 
 662     <code>options</code>. The lifespan of the <code>options</code> string is the 
 663     <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> call.
 664     If needed beyond this time the string or parts of the string must be copied.
 665     <p/>
 666     Note that some <internallink id="capability">capabilities</internallink> 
 667     may not be available in the live phase.
 668     <p/>
 669     The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name
 670     &gt;</code> function initializes the agent and returns a value
 671     to the VM to indicate if an error occurred. Any value other than zero indicates an error. 
 672     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes 
 673     some implementation specific action -- for example it might print an error to standard error, 
 674     or record the error in a system log.
 675   </intro>
 676 
 677   <intro id="onunload" label="Agent Shutdown">
 678     The library may optionally export a 
 679     shutdown function with the following prototype:
 680     <example>
 681 JNIEXPORT void JNICALL 
 682 Agent_OnUnload(JavaVM *vm)</example>
 683     Or for a statically linked agent named 'L':
 684     <example>
 685 JNIEXPORT void JNICALL 
 686 Agent_OnUnload_L(JavaVM *vm)</example>
 687 
 688     This function will be called by the VM when the library is about to be unloaded.
 689     The library will be unloaded (unless it is statically linked into the
 690     executable) and this function will be called if some platform specific 
 691     mechanism causes the unload (an unload mechanism is not specified in this document)
 692     or the library is (in effect) unloaded by the termination of the VM whether through 
 693     normal termination or VM failure, including start-up failure.
 694     Uncontrolled shutdown is, of couse, an exception to this rule.
 695     Note the distinction between this function and the 
 696     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
 697     to be sent, the VM must have run at least to the point of initialization and a valid 
 698     <jvmti/> environment must exist which has set a callback for VMDeath
 699     and enabled the event.
 700     None of these are required for <code>Agent_OnUnload</code> or
 701     <code>Agent_OnUnload_&lt;agent-lib-name&gt;</code> and this function
 702     is also called if the library is unloaded for other reasons.
 703     In the case that a VM Death event is sent, it will be sent before this 
 704     function is called (assuming this function is called due to VM termination).
 705     This function can be used to clean-up resources allocated by the agent.
 706   </intro>
 707 
 708   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
 709     Since the command-line cannot always be accessed or modified, for example in embedded VMs
 710     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
 711     provided so that agents may be launched in these cases.
 712     <p/>
 713     Platforms which support environment variables or other named strings, may support the 
 714     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space 
 715     boundaries.  White-space characters include space, tab, carriage-return, new-line, 
 716     vertical-tab, and form-feed.  Sequences of white-space characters are considered 
 717     equivalent to a single white-space character.  No white-space is included in the options 
 718     unless quoted.  Quoting is as follows:
 719     <ul>
 720         <li>All characters enclosed between a pair of single quote marks (''), except a single 
 721         quote, are quoted.</li>
 722         <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
 723         <li>All characters enclosed between a pair of double quote marks (""), except a double 
 724         quote, are quoted.</li>
 725         <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
 726         <li>A quoted part can start or end anywhere in the variable.</li>
 727         <li>White-space characters have no special meaning when quoted -- they are included in
 728         the option like any other character and do not mark white-space boundaries.</li>
 729         <li>The pair of quote marks is not included in the option.</li>
 730     </ul>
 731     <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied 
 732     in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is 
 733     a concern; for example, the Reference Implementation disables this feature on Unix systems when 
 734     the effective user or group ID differs from the real ID.  
 735     This feature is intended to support the initialization of tools -- specifically including the 
 736     launching of native or Java programming language agents.  Multiple tools may wish to use this 
 737     feature, so the variable should not be overwritten, instead,  options should be appended to 
 738     the variable.  Note that since the variable is processed at the time of the JNI Invocation 
 739     API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
 740   </intro>
 741 
 742   <intro id="environments" label="Environments">
 743     The <jvmti/> specification supports the use of multiple simultaneous
 744     <jvmti/> agents.
 745     Each agent has its own <jvmti/> environment.  
 746     That is, the <jvmti/> state is
 747     separate for each agent - changes to one environment do not affect the
 748     others.  The state of a <jvmti/> 
 749     environment includes:
 750     <ul>
 751       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
 752       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
 753       <li><internallink id="capability">the capabilities</internallink></li>
 754       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
 755     </ul>
 756     Although their <jvmti/> state 
 757     is separate, agents inspect and modify the shared state
 758     of the VM, they also share the native environment in which they execute.
 759     As such, an agent can perturb the results of other agents or cause them
 760     to fail.  It is the responsibility of the agent writer to specify the level
 761     of compatibility with other agents.  <jvmti/> implementations are not capable
 762     of preventing destructive interactions between agents. Techniques to reduce
 763     the likelihood of these occurrences are beyond the scope of this document.
 764     <p/>
 765     An agent creates a <jvmti/> environment 
 766     by passing a <jvmti/> version 
 767     as the interface ID to the JNI Invocation API function 
 768     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><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 that instrument code in named modules may need to arrange for those
 868   modules to read other modules. If code is instrumented to invoke a method
 869   in a support class in another module, then the module of the instrumented
 870   code should read the module of the supporting class. Furthermore, the
 871   supporting class will only be accessible to the instrumented code if
 872   it is <code>public</code> and in a package that is exported by its module.
 873   Agents can use the JNI functions <code>CanReadModule</code> and
 874   <code>AddModuleReads</code> to test and update a module to read another.
 875   <p/>
 876   As an aid to agents that deploy supporting classes on the search path of
 877   the bootstrap class loader, or the search path of the class loader that
 878   loads the main class, the Java virtual machine arranges for the module
 879   of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
 880   read the unnamed module of both class loaders.
 881 </intro>
 882 
 883   <intro id="mUTF" label="Modified UTF-8 String Encoding">
 884     <jvmti/> uses modified UTF-8 to encode character strings.
 885     This is the same encoding used by JNI.
 886     Modified UTF-8 differs 
 887     from standard UTF-8 in the representation of supplementary characters 
 888     and of the null character. See the
 889     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542">
 890       Modified UTF-8 Strings</externallink>
 891     section of the JNI specification for details.
 892   </intro>
 893 
 894   <intro id="context" label="Specification Context">
 895     Since this interface provides access to the state of applications running in the
 896     Java virtual machine; 
 897     terminology refers to the Java platform and not the native
 898     platform (unless stated otherwise).  For example:
 899     <ul>
 900       <li>"thread" means Java programming language thread.</li>
 901       <li>"stack frame" means Java virtual machine stack frame.</li>
 902       <li>"class" means Java programming language class.</li>
 903       <li>"heap" means Java virtual machine heap.</li>
 904       <li>"monitor" means Java programming language object monitor.</li>
 905     </ul>
 906     <p/>
 907     Sun, Sun Microsystems, the Sun logo, Java, and JVM
 908     are trademarks or registered trademarks of Oracle 
 909     and/or its affiliates, in the U.S. and other countries.
 910   </intro>
 911 
 912 
 913 <functionsection label="Functions">
 914   <intro id="jvmtiEnvAccess" label="Accessing Functions">
 915     Native code accesses <jvmti/> features 
 916     by calling <jvmti/> functions. 
 917     Access to <jvmti/> functions is by use of an interface pointer
 918     in the same manner as 
 919     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java 
 920       Native Interface (JNI) functions</externallink> are accessed.
 921     The <jvmti/> interface pointer is called the 
 922     <i>environment pointer</i>.
 923     <p/>
 924     An environment pointer is a pointer to an environment and has
 925     the type <code>jvmtiEnv*</code>.
 926     An environment has information about its <jvmti/> connection.
 927     The first value in the environment is a pointer to the function table.
 928     The function table is an array of pointers to <jvmti/> functions.
 929     Every function pointer is at a predefined offset inside the 
 930     array. 
 931     <p/>
 932     When used from the C language:
 933     double indirection is used to access the functions;
 934     the environment pointer provides context and is the first
 935     parameter of each function call; for example:
 936     <example>
 937 jvmtiEnv *jvmti;
 938 ...
 939 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);
 940     </example>
 941     <p/>
 942     When used from the C++ language:
 943     functions are accessed as member functions of <code>jvmtiEnv</code>;
 944     the environment pointer is not passed to the function call; for example:
 945     <example>
 946 jvmtiEnv *jvmti;
 947 ...
 948 jvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);
 949     </example>
 950     Unless otherwise stated, all examples and declarations in this 
 951     specification use the C language.
 952     <p/>
 953     A <jvmti/> environment can be obtained through the JNI Invocation API
 954     <code>GetEnv</code> function:
 955     <example>
 956 jvmtiEnv *jvmti;
 957 ...
 958 (*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);
 959     </example>
 960     Each call to <code>GetEnv</code> 
 961     creates a new <jvmti/> connection and thus
 962     a new <jvmti/> environment. 
 963     The <code>version</code> argument of <code>GetEnv</code> must be
 964     a <jvmti/> version.
 965     The returned environment may have a different version than the
 966     requested version but the returned environment must be compatible.
 967     <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a 
 968     compatible version is not available, if <jvmti/> is not supported or
 969     <jvmti/> is not supported in the current VM configuration.
 970     Other interfaces may be added for creating <jvmti/> environments
 971     in specific contexts.
 972     Each environment has its own state (for example,
 973     <functionlink id="SetEventNotificationMode">desired events</functionlink>, 
 974     <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and 
 975     <functionlink id="AddCapabilities">capabilities</functionlink>). 
 976     An environment is released with 
 977     <functionlink id="DisposeEnvironment"></functionlink>. 
 978     Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
 979     across threads and are created dynamically.
 980   </intro>
 981 
 982   <intro id="functionReturn" label="Function Return Values">
 983     <jvmti/> functions always return an
 984     <internallink id="ErrorSection">error code</internallink> via the
 985     <datalink id="jvmtiError"/> function return value. 
 986     Some functions can return additional
 987     values through pointers provided by the calling function. 
 988     In some cases, <jvmti/> functions allocate memory that your program must
 989     explicitly deallocate. This is indicated in the individual <jvmti/>
 990     function descriptions.  Empty lists, arrays, sequences, etc are 
 991     returned as <code>NULL</code>.
 992     <p/>
 993     In the event that the <jvmti/> function encounters
 994     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
 995     of memory referenced by argument pointers is undefined, but no memory
 996     will have been allocated and no global references will have been allocated.
 997     If the error occurs because of invalid input, no action will have occurred.
 998   </intro>
 999 
1000 <intro id="refs" label="Managing JNI Object References">
1001     <jvmti/> functions identify objects with JNI references 
1002     (<datalink id="jobject"/> and <datalink id="jclass"/>)
1003     and their derivatives
1004     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
1005     References passed to 
1006     <jvmti/> functions can be either global or local, but they must be 
1007     strong references. All references returned by <jvmti/> functions are 
1008     local references--these local references are created 
1009     during the <jvmti/> call.
1010     Local references are a resource that must be managed (see the 
1011     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>).  
1012     When threads return from native code all local references
1013     are freed.  Note that some threads, including typical
1014     agent threads, will never return from native code.
1015     A thread is ensured the ability to create sixteen local 
1016     references without the need for any explicit management.
1017     For threads executing a limited number of <jvmti/> calls before
1018     returning from native code
1019     (for example, threads processing events), 
1020     it may be determined that no explicit management
1021     is needed.
1022     However, long running agent threads will need explicit
1023     local reference management--usually with the JNI functions
1024     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
1025     Conversely, to preserve references beyond the
1026     return from native code, they must be converted to global references.
1027     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> 
1028     as they are not <datalink id="jobject"/>s.
1029 </intro>
1030 
1031     <intro id="prereqState" label="Prerequisite State for Calling Functions">
1032       Unless the function explicitly states that the agent must bring
1033       a thread or the VM to a particular state (for example, suspended),
1034       the <jvmti/> implementation is responsible for bringing the VM to a
1035       safe and consistent state for performing the function.
1036     </intro>
1037 
1038     <intro id="functionsExceptions" label="Exceptions and Functions">
1039       <jvmti/> functions never throw exceptions; error conditions are 
1040       communicated via the 
1041       <internallink id="functionReturn">function return value</internallink>.
1042       Any existing exception state is preserved across a call to a 
1043       <jvmti/> function.
1044       See the
1045       <externallink 
1046         id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770"
1047              >Java Exceptions</externallink>
1048       section of the JNI specification for information on handling exceptions.
1049     </intro>
1050 
1051   <category id="memory" label="Memory Management">
1052     <intro>
1053       These functions provide for the allocation and deallocation of 
1054       memory used by <jvmti/> functionality and can be used to provide
1055       working memory for agents.
1056       Memory managed by <jvmti/> is not compatible with other memory
1057       allocation libraries and mechanisms.
1058     </intro>
1059 
1060     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
1061       <synopsis>Allocate</synopsis>
1062       <description>
1063         Allocate an area of memory through the <jvmti/> allocator. 
1064         The allocated
1065         memory should be freed with <functionlink id="Deallocate"></functionlink>.
1066       </description>
1067       <origin>jvmdi</origin>
1068       <capabilities>
1069       </capabilities>
1070       <parameters>
1071         <param id="size">
1072           <jlong/>
1073           <description>
1074             The number of bytes to allocate.
1075             <rationale>
1076               <code>jlong</code> is used for compatibility with JVMDI.
1077             </rationale>
1078           </description>
1079         </param>
1080         <param id="mem_ptr">
1081           <allocbuf incount="size"><uchar/></allocbuf>
1082           <description>
1083             On return, a pointer to the beginning of the allocated memory.
1084             If <code>size</code> is zero, <code>NULL</code> is returned.
1085           </description>
1086         </param>
1087       </parameters>
1088       <errors>
1089         <error id="JVMTI_ERROR_OUT_OF_MEMORY">
1090           Memory request cannot be honored.
1091         </error>
1092         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
1093           <paramlink id="size"></paramlink> is less than zero.
1094         </error>
1095       </errors>
1096     </function>
1097 
1098     <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
1099       <synopsis>Deallocate</synopsis>
1100       <description>
1101         Deallocate <code>mem</code>  using the <jvmti/> allocator. 
1102         This function should
1103         be used to deallocate any memory allocated and returned 
1104         by a <jvmti/> function
1105         (including memory allocated with <functionlink id="Allocate"></functionlink>).
1106         All allocated memory must be deallocated
1107         or the memory cannot be reclaimed.
1108       </description>
1109       <origin>jvmdi</origin>
1110       <capabilities>
1111       </capabilities>
1112       <parameters>
1113         <param id="mem">
1114           <outbuf>
1115             <uchar/>
1116             <nullok>the call is ignored</nullok>
1117           </outbuf>
1118           <description>
1119             A pointer to the beginning of the allocated memory.
1120             Please ignore "On return, the elements are set."
1121               <todo>keep it from generating "On return, the elements are set"</todo>
1122           </description>
1123         </param>
1124       </parameters>
1125       <errors>
1126       </errors>
1127     </function>
1128   </category>
1129 
1130   <category id="threadCategory" label="Thread">
1131     <intro>
1132     </intro>
1133 
1134     <function id="GetThreadState" num="17">
1135       <synopsis>Get Thread State</synopsis>
1136       <description>
1137         Get the state of a thread.  The state of the thread is represented by the
1138         answers to the hierarchical set of questions below:
1139           <ul type="circle">
1140             <li><i>Alive?</i>
1141               <ul>
1142                 <li>Not alive.
1143                   <ul type="circle">
1144                     <li><i>Why not alive?</i>
1145                       <ul>
1146                         <li>New.</li>
1147                         <li>Terminated (<datalink 
1148                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
1149                       </ul>
1150                     </li>
1151                   </ul>
1152                 </li>
1153                 <li>Alive (<datalink 
1154                     id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
1155                   <ul type="circle">
1156                     <li><i>Suspended?</i>
1157                       <ul>
1158                         <li>Suspended (<datalink 
1159                             id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
1160                         <li>Not suspended</li>
1161                       </ul>
1162                     </li>
1163                     <li><i>Interrupted?</i>
1164                       <ul>
1165                         <li>Interrupted (<datalink 
1166                             id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
1167                         <li>Not interrupted.</li>
1168                       </ul>
1169                     </li>
1170                     <li><i>In native?</i>
1171                       <ul>
1172                         <li>In native code (<datalink 
1173                             id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
1174                         <li>In Java programming language code</li>
1175                       </ul>
1176                     </li>
1177                     <li><i>What alive state?</i>
1178                       <ul>
1179                         <li>Runnable (<datalink 
1180                             id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
1181                         <li>Blocked (<datalink 
1182                             id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
1183                         <li>Waiting (<datalink 
1184                             id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
1185                           <ul type="circle">
1186                             <li><i>Timed wait?</i>
1187                               <ul>
1188                                 <li>Indefinite (<datalink 
1189                                     id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
1190                                 <li>Timed (<datalink 
1191                                     id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
1192                               </ul>
1193                             </li>
1194                             <li><i>Why waiting?</i>
1195                               <ul>
1196                                 <li>Object.wait (<datalink 
1197                                     id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
1198                                 <li>LockSupport.park (<datalink 
1199                                     id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
1200                                 <li>Sleeping (<datalink 
1201                                     id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
1202                               </ul>
1203                             </li>
1204                           </ul>
1205                         </li>
1206                       </ul>
1207                     </li>
1208                   </ul>
1209                 </li>
1210               </ul>
1211             </li>
1212           </ul>
1213         <p/>
1214         The answers are represented by the following bit vector. 
1215         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
1216           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
1217             Thread is alive. Zero if thread is new (not started) or terminated.
1218           </constant>
1219           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
1220             Thread has completed execution.
1221           </constant>
1222           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
1223             Thread is runnable.
1224           </constant>
1225           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
1226             Thread is waiting to enter a synchronization block/method or,
1227             after an <code>Object.wait()</code>, waiting to re-enter a 
1228             synchronization block/method.
1229           </constant>
1230           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
1231             Thread is waiting.
1232           </constant>
1233           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
1234             Thread is waiting without a timeout.
1235             For example, <code>Object.wait()</code>.
1236           </constant>
1237           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
1238             Thread is waiting with a maximum time to wait specified.
1239             For example, <code>Object.wait(long)</code>.
1240           </constant>
1241           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
1242             Thread is sleeping -- <code>Thread.sleep(long)</code>.
1243           </constant>
1244           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
1245             Thread is waiting on an object monitor -- <code>Object.wait</code>.
1246           </constant>
1247           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
1248             Thread is parked, for example: <code>LockSupport.park</code>,
1249             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
1250           </constant>
1251           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
1252             Thread suspended.
1253             <code>java.lang.Thread.suspend()</code>
1254             or a <jvmti/> suspend function 
1255             (such as <functionlink id="SuspendThread"></functionlink>) 
1256             has been called on the thread. If this bit
1257             is set, the other bits refer to the thread state before suspension.
1258           </constant>
1259           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
1260             Thread has been interrupted.
1261           </constant>
1262           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
1263             Thread is in native code--that is, a native method is running
1264             which has not called back into the VM or Java programming
1265             language code.
1266             <p/>
1267             This flag is not set when running VM compiled Java programming
1268             language code nor is it set when running VM code or
1269             VM support code. Native VM interface functions, such as JNI and
1270             <jvmti/> functions, may be implemented as VM code.
1271           </constant>
1272           <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
1273             Defined by VM vendor.
1274           </constant>
1275           <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
1276             Defined by VM vendor.
1277           </constant>
1278           <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
1279             Defined by VM vendor.
1280           </constant>
1281         </constants>
1282         The following definitions are used to convert <jvmti/> thread state
1283         to <code>java.lang.Thread.State</code> style states.
1284         <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
1285           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
1286                      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">
1287             Mask the state with this before comparison
1288           </constant>
1289           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
1290                      num="0">
1291             <code>java.lang.Thread.State.NEW</code>
1292           </constant>
1293           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
1294                      num="JVMTI_THREAD_STATE_TERMINATED">
1295             <code>java.lang.Thread.State.TERMINATED</code>
1296           </constant>
1297           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
1298                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
1299             <code>java.lang.Thread.State.RUNNABLE</code>
1300           </constant>
1301           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
1302                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
1303             <code>java.lang.Thread.State.BLOCKED</code>
1304           </constant>
1305           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
1306                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
1307             <code>java.lang.Thread.State.WAITING</code>
1308           </constant>
1309           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
1310                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1311             <code>java.lang.Thread.State.TIMED_WAITING</code>
1312           </constant>
1313         </constants>
1314         <b>Rules</b>
1315         <p/>
1316         There can be no more than one answer to a question, although there can be no
1317         answer (because the answer is unknown, does not apply, or none of the answers is 
1318         correct).  An answer is set only when the enclosing answers match.
1319         That is, no more than one of
1320           <ul type="circle">
1321               <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
1322               <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
1323               <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
1324           </ul>
1325         can be set (a <tm>J2SE</tm> compliant implementation will always set
1326         one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). 
1327         And if any of these are set, the enclosing answer 
1328         <code>JVMTI_THREAD_STATE_ALIVE</code> is set. 
1329         No more than one of
1330           <ul type="circle">
1331               <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
1332               <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
1333           </ul>
1334         can be set (a <tm>J2SE</tm> compliant implementation will always set
1335         one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). 
1336         And if either is set, the enclosing answers 
1337         <code>JVMTI_THREAD_STATE_ALIVE</code> and 
1338         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 
1339         No more than one of
1340           <ul type="circle">
1341               <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
1342               <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
1343               <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
1344           </ul>
1345         can be set. And if any of these is set, the enclosing answers 
1346         <code>JVMTI_THREAD_STATE_ALIVE</code> and 
1347         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 
1348         Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
1349         then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
1350         If a state <i>A</i> is implemented using the mechanism of 
1351         state <i>B</i> then it is state <i>A</i> which 
1352         is returned by this function.
1353         For example, if <code>Thread.sleep(long)</code>
1354         is implemented using <code>Object.wait(long)</code>
1355         then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
1356         which is returned.
1357         More than one of
1358           <ul type="circle">
1359               <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
1360               <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
1361               <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
1362           </ul>
1363         can be set, but if any is set,
1364         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1365         <p/>
1366         And finally,
1367         <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
1368         <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.  
1369         <p/>
1370         The thread state representation is designed for extension in future versions
1371         of the specification; thread state values should be used accordingly, that is
1372         they should not be used as ordinals.  
1373         Most queries can be made by testing a single bit, if use in a switch statement is desired,
1374         the state bits should be masked with the interesting bits.
1375         All bits not defined above are reserved for future use.  
1376         A VM, compliant to the current specification, must set reserved bits to zero.
1377         An agent should ignore reserved bits -- 
1378         they should not be assumed to be zero and thus should not be included in comparisons.
1379         <p/>
1380         <b>Examples</b>
1381         <p/>
1382         Note that the values below exclude reserved and vendor bits.
1383         <p/>
1384         The state of a thread blocked at a <code>synchronized</code>-statement would be:
1385         <example>
1386             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
1387         </example>
1388         The state of a thread which hasn't started yet would be:
1389         <example>
1390             0
1391         </example>
1392         The state of a thread at a <code>Object.wait(3000)</code> would be:
1393         <example>
1394             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + 
1395                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + 
1396                 JVMTI_THREAD_STATE_MONITOR_WAITING
1397         </example>
1398         The state of a thread suspended while runnable would be:
1399         <example>
1400             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
1401         </example>
1402         <p/>
1403         <b>Testing the State</b>
1404         <p/>
1405         In most cases, the thread state can be determined by testing the one bit corresponding
1406         to that question.  For example, the code to test if a thread is sleeping:
1407         <example>
1408         jint state;
1409         jvmtiError err;
1410 
1411         err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1412         if (err == JVMTI_ERROR_NONE) {
1413            if (state &amp; JVMTI_THREAD_STATE_SLEEPING) {  ...
1414         </example>
1415         <p/>
1416         For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
1417         <example>
1418            if (state &amp; JVMTI_THREAD_STATE_WAITING) {  ...
1419         </example>
1420         For some states, more than one bit will need to be tested as is the case
1421         when testing if a thread has not yet been started:
1422         <example>
1423            if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
1424         </example>
1425         To distinguish timed from untimed <code>Object.wait</code>:
1426         <example>
1427            if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {  
1428              if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
1429                printf("in Object.wait(long timeout)\n");
1430              } else {
1431                printf("in Object.wait()\n");
1432              }
1433            }
1434         </example>
1435         <p/>
1436         <b>Relationship to <code>java.lang.Thread.State</code></b>
1437         <p/>
1438         The thread state represented by <code>java.lang.Thread.State</code>
1439         returned from <code>java.lang.Thread.getState()</code> is a subset of the
1440         information returned from this function.  
1441         The corresponding <code>java.lang.Thread.State</code> can be determined
1442         by using the provided conversion masks.
1443         For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
1444         <example>
1445             err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1446             abortOnError(err);
1447             switch (state &amp; JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
1448             case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
1449               return "NEW";
1450             case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
1451               return "TERMINATED";
1452             case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
1453               return "RUNNABLE";
1454             case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
1455               return "BLOCKED";
1456             case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
1457               return "WAITING";
1458             case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
1459               return "TIMED_WAITING";
1460             }
1461         </example>
1462       </description>
1463       <origin>new</origin>
1464       <capabilities>
1465       </capabilities>
1466       <parameters>
1467         <param id="thread">
1468           <jthread null="current" started="maybe" impl="noconvert"/>
1469             <description>
1470               The thread to query. 
1471             </description>
1472         </param>
1473         <param id="thread_state_ptr">
1474           <outptr><jint/></outptr>
1475           <description>
1476             On return, points to state flags,
1477             as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
1478           </description>
1479         </param>
1480       </parameters>
1481       <errors>
1482       </errors>
1483     </function>
1484 
1485     <function id="GetCurrentThread" phase="start" num="18" since="1.1">
1486       <synopsis>Get Current Thread</synopsis>
1487       <description>
1488         Get the current thread.  
1489         The current thread is the Java programming language thread which has called the function.
1490         <p/>
1491         Note that most <jvmti/> functions that take a thread 
1492         as an argument will accept <code>NULL</code> to mean 
1493         the current thread.
1494       </description>
1495       <origin>new</origin>
1496       <capabilities>
1497       </capabilities>
1498       <parameters>
1499         <param id="thread_ptr">
1500           <outptr><jthread/></outptr>
1501           <description>
1502              On return, points to the current thread.
1503           </description>
1504         </param>
1505       </parameters>
1506       <errors>
1507       </errors>
1508     </function>
1509 
1510     <function id="GetAllThreads" num="4">
1511       <synopsis>Get All Threads</synopsis>
1512       <description>
1513         Get all live threads.
1514         The threads are Java programming language threads;
1515         that is, threads that are attached to the VM.
1516         A thread is live if <code>java.lang.Thread.isAlive()</code> 
1517         would return <code>true</code>, that is, the thread has
1518         been started and has not yet died.
1519         The universe of threads is determined by the context of the <jvmti/>
1520         environment, which typically is all threads attached to the VM.
1521         Note that this includes <jvmti/> agent threads 
1522         (see <functionlink id="RunAgentThread"/>).
1523       </description>
1524       <origin>jvmdi</origin>
1525       <capabilities>
1526       </capabilities>
1527       <parameters>
1528         <param id="threads_count_ptr">
1529           <outptr><jint/></outptr>
1530           <description>
1531             On return, points to the number of running threads.
1532           </description>
1533         </param>
1534         <param id="threads_ptr">
1535           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
1536             <description>
1537               On return, points to an array of references, one
1538               for each running thread.
1539             </description>
1540         </param>
1541       </parameters>
1542       <errors>
1543       </errors>
1544     </function>
1545 
1546     <function id="SuspendThread" num="5">
1547       <synopsis>Suspend Thread</synopsis>
1548       <description>
1549         Suspend the specified thread. If the calling thread is specified, 
1550         this function will not return until some other thread calls 
1551         <functionlink id="ResumeThread"></functionlink>.
1552         If the thread is currently suspended, this function
1553         does nothing and returns an error.
1554       </description>
1555       <origin>jvmdi</origin>
1556       <capabilities>
1557         <required id="can_suspend"></required>
1558       </capabilities>
1559       <parameters>
1560         <param id="thread">
1561           <jthread null="current"/>
1562             <description>
1563               The thread to suspend. 
1564             </description>
1565         </param>
1566       </parameters>
1567       <errors>
1568         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
1569           Thread already suspended.
1570         </error>
1571       </errors>
1572     </function>
1573 
1574     <elide>
1575     <function id="SuspendAllThreads" num="101">
1576       <synopsis>Suspend All Threads</synopsis>
1577       <description>
1578         <issue>
1579             There has been no explicit call for this function, and it will
1580             thus be removed if there is no interest.
1581         </issue>
1582         Suspend all live threads except:
1583         <ul>
1584           <li>already suspended threads</li>
1585           <li>those listed in <paramlink id="except_list"></paramlink></li>
1586           <li>certain system (non application) threads, as determined
1587             by the VM implementation</li>
1588         </ul>
1589         The threads are Java programming language threads;
1590         native threads which are not attached to the VM are not
1591         Java programming language threads.
1592         A thread is live if <code>java.lang.Thread.isAlive()</code> 
1593         would return <code>true</code>, that is, the thread has
1594         been started and has not yet died.
1595         The universe of threads is determined 
1596         by the context of the <jvmti/>
1597         environment, which, typically, is all threads attached to the VM,
1598         except critical VM internal threads and <jvmti/> agent threads 
1599         (see <functionlink id="RunAgentThread"/>).
1600         <p/>
1601         If the calling thread is specified, 
1602         all other threads are suspended first then the caller thread is suspended -
1603         this function will not return until some other thread calls 
1604         <functionlink id="ResumeThread"></functionlink>.
1605         <p/>
1606         The list of actually
1607         suspended threads is returned in 
1608         <paramlink id="suspended_list_ptr"></paramlink>.
1609         Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
1610         <functionlink id="ResumeThreadList"></functionlink>
1611         can be used to resume the suspended threads.
1612       </description>
1613       <origin>new</origin>
1614       <capabilities>
1615         <required id="can_suspend"></required>
1616       </capabilities>
1617       <parameters>
1618         <param id="except_count">
1619           <jint min="0"/>
1620           <description>
1621             The number of threads in the list of threads not to be suspended.
1622           </description>
1623         </param>
1624         <param id="except_list">
1625             <inbuf incount="except_count">
1626               <jthread/>
1627               <nullok>not an error if <code>except_count == 0</code></nullok>
1628             </inbuf>
1629             <description>
1630               The list of threads not to be suspended.
1631             </description>
1632         </param>
1633         <param id="suspended_count_ptr">
1634           <outptr><jint/></outptr>
1635           <description>
1636             On return, points to the number of threads suspended by this call.
1637           </description>
1638         </param>
1639         <param id="suspended_list_ptr">
1640           <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
1641             <description>
1642               On return, points to an array of references, one
1643               for each thread suspended.
1644             </description>
1645         </param>
1646       </parameters>
1647       <errors>
1648         <error id="JVMTI_ERROR_INVALID_THREAD">
1649           A thread in <paramlink id="except_list"></paramlink> was invalid.
1650         </error>
1651         <error id="JVMTI_ERROR_NULL_POINTER">
1652           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1653           and <paramlink id="except_count"></paramlink> was non-zero.
1654         </error>
1655       </errors>
1656     </function>
1657     </elide>
1658 
1659     <function id="SuspendThreadList" num="92">
1660       <synopsis>Suspend Thread List</synopsis>
1661       <description>
1662         Suspend the <paramlink id="request_count"></paramlink> 
1663         threads specified in the 
1664         <paramlink id="request_list"></paramlink> array. 
1665         Threads may be resumed with
1666         <functionlink id="ResumeThreadList"></functionlink> or
1667         <functionlink id="ResumeThread"></functionlink>.
1668         If the calling thread is specified in the 
1669         <paramlink id="request_list"></paramlink> array, this function will
1670         not return until some other thread resumes it.
1671         Errors encountered in the suspension of a thread
1672         are returned in the <paramlink id="results"></paramlink>
1673         array, <b>not</b> in the return value of this function.
1674         Threads that are currently suspended do not change state.
1675       </description>
1676       <origin>jvmdi</origin>
1677       <capabilities>
1678         <required id="can_suspend"></required>
1679       </capabilities>
1680       <parameters>
1681         <param id="request_count">
1682           <jint min="0"/>
1683           <description>
1684             The number of threads to suspend.
1685           </description>
1686         </param>
1687         <param id="request_list">
1688           <inbuf incount="request_count"><jthread/></inbuf>
1689             <description>
1690               The list of threads to suspend.
1691             </description>
1692         </param>
1693         <param id="results">
1694           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1695           <description>
1696             An agent supplied array of 
1697             <paramlink id="request_count"></paramlink> elements.
1698             On return, filled with the error code for
1699             the suspend of the corresponding thread.
1700             The error code will be 
1701             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1702             if the thread was suspended by this call.
1703             Possible error codes are those specified
1704             for <functionlink id="SuspendThread"></functionlink>.
1705           </description>
1706         </param>
1707       </parameters>
1708       <errors>
1709       </errors>
1710     </function>
1711 
1712     <function id="ResumeThread" num="6">
1713       <synopsis>Resume Thread</synopsis>
1714       <description>
1715         Resume a suspended thread. 
1716         Any threads currently suspended through
1717         a <jvmti/> suspend function (eg.
1718         <functionlink id="SuspendThread"></functionlink>) 
1719         or <code>java.lang.Thread.suspend()</code>
1720         will resume execution;  
1721         all other threads are unaffected.
1722       </description>
1723       <origin>jvmdi</origin>
1724       <capabilities>
1725         <required id="can_suspend"></required>
1726       </capabilities>
1727       <parameters>
1728         <param id="thread">
1729           <jthread/>
1730             <description>
1731               The thread to resume.
1732             </description>
1733         </param>
1734       </parameters>
1735       <errors>
1736         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
1737           Thread was not suspended.
1738         </error>
1739         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
1740           The state of the thread has been modified, and is now inconsistent. 
1741         </error>
1742       </errors>
1743     </function>
1744 
1745     <function id="ResumeThreadList" num="93">
1746       <synopsis>Resume Thread List</synopsis>
1747       <description>
1748         Resume the <paramlink id="request_count"></paramlink> 
1749         threads specified in the 
1750         <paramlink id="request_list"></paramlink> array. 
1751         Any thread suspended through
1752         a <jvmti/> suspend function (eg.
1753         <functionlink id="SuspendThreadList"></functionlink>) 
1754         or <code>java.lang.Thread.suspend()</code>
1755         will resume execution.
1756       </description>
1757       <origin>jvmdi</origin>
1758       <capabilities>
1759         <required id="can_suspend"></required>
1760       </capabilities>
1761       <parameters>
1762         <param id="request_count">
1763           <jint min="0"/>
1764           <description>
1765             The number of threads to resume.
1766           </description>
1767         </param>
1768         <param id="request_list">
1769           <inbuf incount="request_count"><jthread/></inbuf>
1770             <description>
1771               The threads to resume.
1772             </description>
1773         </param>
1774         <param id="results">
1775           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1776           <description>
1777             An agent supplied array of 
1778             <paramlink id="request_count"></paramlink> elements.
1779             On return, filled with the error code for
1780             the resume of the corresponding thread.
1781             The error code will be 
1782             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1783             if the thread was suspended by this call.
1784             Possible error codes are those specified
1785             for <functionlink id="ResumeThread"></functionlink>.
1786           </description>
1787         </param>
1788       </parameters>
1789       <errors>
1790       </errors>
1791     </function>
1792 
1793     <function id="StopThread" num="7">
1794       <synopsis>Stop Thread</synopsis>
1795       <description>
1796         Send the specified asynchronous exception to the specified thread 
1797         (similar to <code>java.lang.Thread.stop</code>).
1798         Normally, this function is used to kill the specified thread with an 
1799         instance of the exception <code>ThreadDeath</code>.
1800       </description>
1801       <origin>jvmdi</origin>
1802       <capabilities>
1803         <required id="can_signal_thread"></required>
1804       </capabilities>
1805       <parameters>
1806         <param id="thread">
1807           <jthread/>
1808             <description>
1809               The thread to stop.
1810             </description>
1811         </param>
1812         <param id="exception">
1813           <jobject/>
1814             <description>
1815               The asynchronous exception object.
1816             </description>
1817         </param>
1818       </parameters>
1819       <errors>
1820       </errors>
1821     </function>
1822 
1823     <function id="InterruptThread" num="8">
1824       <synopsis>Interrupt Thread</synopsis>
1825       <description>
1826         Interrupt the specified thread
1827         (similar to <code>java.lang.Thread.interrupt</code>).
1828       </description>
1829       <origin>jvmdi</origin>
1830       <capabilities>
1831         <required id="can_signal_thread"></required>
1832       </capabilities>
1833       <parameters>
1834         <param id="thread">
1835           <jthread impl="noconvert"/>
1836             <description>
1837               The thread to interrupt.
1838             </description>
1839         </param>
1840       </parameters>
1841       <errors>
1842       </errors>
1843     </function>
1844 
1845     <function id="GetThreadInfo" num="9">
1846       <synopsis>Get Thread Info</synopsis>
1847       <typedef id="jvmtiThreadInfo" label="Thread information structure">
1848         <field id="name">
1849           <allocfieldbuf><char/></allocfieldbuf>
1850           <description>
1851             The thread name, encoded as a
1852             <internallink id="mUTF">modified UTF-8</internallink> string.
1853           </description>
1854         </field>
1855         <field id="priority">
1856           <jint/>
1857           <description>
1858             The thread priority.  See the thread priority constants:
1859             <datalink id="jvmtiThreadPriority"></datalink>.
1860           </description>
1861         </field>
1862         <field id="is_daemon">
1863           <jboolean/>
1864           <description>
1865             Is this a daemon thread?
1866           </description>
1867         </field>
1868         <field id="thread_group">
1869           <jthreadGroup/>
1870           <description>
1871             The thread group to which this thread belongs.
1872             <code>NULL</code> if the thread has died.
1873           </description>
1874         </field>
1875         <field id="context_class_loader">
1876           <jobject/>
1877             <description>
1878               The context class loader associated with this thread.
1879             </description>
1880         </field>
1881       </typedef>
1882       <description>
1883         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure 
1884         are filled in with details of the specified thread.
1885       </description>
1886       <origin>jvmdi</origin>
1887       <capabilities>
1888       </capabilities>
1889       <parameters>
1890         <param id="thread">
1891           <jthread null="current" impl="noconvert" started="maybe"/>
1892             <description>
1893               The thread to query.
1894             </description>
1895         </param>
1896         <param id="info_ptr">
1897           <outptr><struct>jvmtiThreadInfo</struct></outptr>
1898           <description>
1899             On return, filled with information describing the specified thread.
1900           </description>
1901         </param>
1902       </parameters>
1903       <errors>
1904       </errors>
1905     </function>
1906 
1907     <function id="GetOwnedMonitorInfo" num="10">
1908       <synopsis>Get Owned Monitor Info</synopsis>
1909       <description>
1910         Get information about the monitors owned by the 
1911         specified thread. 
1912       </description>
1913       <origin>jvmdiClone</origin>
1914       <capabilities>
1915         <required id="can_get_owned_monitor_info"></required>
1916       </capabilities>
1917       <parameters>
1918         <param id="thread">
1919           <jthread null="current"/>
1920             <description>
1921               The thread to query.
1922             </description>
1923         </param>
1924         <param id="owned_monitor_count_ptr">
1925           <outptr><jint/></outptr>
1926           <description>
1927             The number of monitors returned.
1928           </description>
1929         </param>
1930         <param id="owned_monitors_ptr">
1931           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
1932             <description>
1933               The array of owned monitors.
1934             </description>
1935         </param>
1936       </parameters>
1937       <errors>
1938       </errors>
1939     </function>
1940 
1941     <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
1942       <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
1943       <typedef id="jvmtiMonitorStackDepthInfo" 
1944                label="Monitor stack depth information structure">
1945         <field id="monitor">
1946           <jobject/>
1947             <description>
1948               The owned monitor.
1949             </description>
1950         </field>
1951         <field id="stack_depth">
1952           <jint/>
1953           <description>
1954             The stack depth.  Corresponds to the stack depth used in the 
1955             <internallink id="stack">Stack Frame functions</internallink>.
1956             That is, zero is the current frame, one is the frame which
1957             called the current frame. And it is negative one if the 
1958             implementation cannot determine the stack depth (e.g., for 
1959             monitors acquired by JNI <code>MonitorEnter</code>).
1960           </description>
1961         </field>
1962       </typedef>
1963       <description>
1964         Get information about the monitors owned by the 
1965         specified thread and the depth of the stack frame which locked them. 
1966       </description>
1967       <origin>new</origin>
1968       <capabilities>
1969         <required id="can_get_owned_monitor_stack_depth_info"></required>
1970       </capabilities>
1971       <parameters>
1972         <param id="thread">
1973           <jthread null="current"/>
1974             <description>
1975               The thread to query.
1976             </description>
1977         </param>
1978         <param id="monitor_info_count_ptr">
1979           <outptr><jint/></outptr>
1980           <description>
1981             The number of monitors returned.
1982           </description>
1983         </param>
1984         <param id="monitor_info_ptr">
1985           <allocbuf outcount="monitor_info_count_ptr">
1986             <struct>jvmtiMonitorStackDepthInfo</struct>
1987           </allocbuf>
1988           <description>
1989             The array of owned monitor depth information.
1990           </description>
1991         </param>
1992       </parameters>
1993       <errors>
1994       </errors>
1995     </function>
1996 
1997     <function id="GetCurrentContendedMonitor" num="11">
1998       <synopsis>Get Current Contended Monitor</synopsis>
1999       <description>
2000         Get the object, if any, whose monitor the specified thread is waiting to 
2001         enter or waiting to regain through <code>java.lang.Object.wait</code>.
2002       </description>
2003       <origin>jvmdi</origin>
2004       <capabilities>
2005         <required id="can_get_current_contended_monitor"></required>
2006       </capabilities>
2007       <parameters>
2008         <param id="thread">
2009           <jthread null="current"/>
2010             <description>
2011               The thread to query.
2012             </description>
2013         </param>
2014         <param id="monitor_ptr">
2015           <outptr><jobject/></outptr>
2016             <description>
2017               On return, filled with the current contended monitor, or
2018               NULL if there is none.
2019             </description>
2020         </param>
2021       </parameters>
2022       <errors>
2023       </errors>
2024     </function>
2025 
2026     <callback id="jvmtiStartFunction">
2027       <void/>
2028       <synopsis>Agent Start Function</synopsis>
2029       <description>
2030         Agent supplied callback function.
2031         This function is the entry point for an agent thread
2032         started with
2033         <functionlink id="RunAgentThread"></functionlink>.
2034       </description>
2035       <parameters>
2036           <param id="jvmti_env">
2037             <outptr>
2038               <struct>jvmtiEnv</struct>
2039             </outptr>
2040             <description>
2041               The <jvmti/> environment.
2042             </description>
2043           </param>
2044           <param id="jni_env">
2045             <outptr>
2046               <struct>JNIEnv</struct>
2047             </outptr>
2048             <description>
2049               The JNI environment.
2050             </description>
2051           </param>
2052           <param id="arg">
2053             <outptr>
2054               <void/>
2055             </outptr>
2056               <description>
2057                 The <code>arg</code> parameter passed to 
2058                 <functionlink id="RunAgentThread"></functionlink>.
2059               </description>
2060           </param>
2061       </parameters>
2062     </callback>
2063 
2064     <function id="RunAgentThread" num="12">
2065       <synopsis>Run Agent Thread</synopsis>
2066       <description>
2067         Starts the execution of an agent thread. with the specified native function.
2068         The parameter <paramlink id="arg"></paramlink> is forwarded on to the
2069         <functionlink id="jvmtiStartFunction">start function</functionlink>
2070         (specified with <paramlink id="proc"></paramlink>) as its single argument.
2071         This function allows the creation of agent threads 
2072         for handling communication with another process or for handling events 
2073         without the need to load a special subclass of <code>java.lang.Thread</code> or 
2074         implementer of <code>java.lang.Runnable</code>. 
2075         Instead, the created thread can run entirely in native code.
2076         However, the created thread does require a newly created instance
2077         of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to 
2078         which it will be associated.
2079         The thread object can be created with JNI calls.
2080         <p/>
2081         The following common thread priorities are provided for your convenience:
2082         <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
2083           <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
2084             Minimum possible thread priority
2085           </constant>
2086           <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
2087             Normal thread priority
2088           </constant>
2089           <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
2090             Maximum possible thread priority
2091           </constant>
2092         </constants>
2093         <p/>
2094         The new thread is started as a daemon thread with the specified
2095         <paramlink id="priority"></paramlink>.
2096         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2097         <p/>
2098         Since the thread has been started, the thread will be live when this function
2099         returns, unless the thread has died immediately.
2100         <p/>
2101         The thread group of the thread is ignored -- specifically, the thread is not
2102         added to the thread group and the thread is not seen on queries of the thread
2103         group at either the Java programming language or <jvmti/> levels.
2104         <p/>
2105         The thread is not visible to Java programming language queries but is 
2106         included in <jvmti/> queries (for example, 
2107         <functionlink id="GetAllThreads"/> and
2108         <functionlink id="GetAllStackTraces"/>).
2109         <p/>
2110         Upon execution of <code>proc</code>, the new thread will be attached to the
2111         VM--see the JNI documentation on 
2112         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060"
2113                       >Attaching to the VM</externallink>.
2114       </description>
2115       <origin>jvmdiClone</origin>
2116       <capabilities>
2117       </capabilities>
2118       <parameters>
2119         <param id="thread">
2120           <jthread impl="noconvert" started="no"/>
2121             <description>
2122               The thread to run.
2123             </description>
2124         </param>
2125         <param id="proc">
2126           <ptrtype>
2127             <struct>jvmtiStartFunction</struct>
2128           </ptrtype>
2129           <description>
2130             The start function.
2131           </description>
2132         </param>
2133         <param id="arg">
2134           <inbuf>
2135             <void/>
2136             <nullok><code>NULL</code> is passed to the start function</nullok>
2137           </inbuf>
2138           <description>
2139             The argument to the start function.
2140           </description>
2141         </param>
2142         <param id="priority">
2143           <jint/>
2144           <description>
2145             The priority of the started thread. Any thread
2146             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
2147             those in <datalink id="jvmtiThreadPriority"></datalink>.
2148           </description>
2149         </param>
2150       </parameters>
2151       <errors>
2152         <error id="JVMTI_ERROR_INVALID_PRIORITY"> 
2153             <paramlink id="priority"/> is less than 
2154             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
2155               or greater than
2156             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
2157         </error>
2158       </errors>
2159     </function>
2160 
2161     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
2162       <synopsis>Set Thread Local Storage</synopsis>
2163       <description>
2164         The VM stores a pointer value associated with each environment-thread
2165         pair. This pointer value is called <i>thread-local storage</i>.
2166         This value is <code>NULL</code> unless set with this function.
2167         Agents can allocate memory in which they store thread specific
2168         information. By setting thread-local storage it can then be
2169         accessed with 
2170         <functionlink id="GetThreadLocalStorage"></functionlink>.
2171         <p/>
2172         This function is called by the agent to set the value of the <jvmti/>
2173         thread-local storage. <jvmti/> supplies to the agent a pointer-size
2174         thread-local storage that can be used to record per-thread
2175         information.
2176       </description>
2177       <origin>jvmpi</origin>
2178       <capabilities>
2179       </capabilities>
2180       <parameters>
2181         <param id="thread">
2182           <jthread null="current"/>
2183             <description>
2184               Store to this thread.
2185             </description>
2186         </param>
2187         <param id="data">
2188           <inbuf> 
2189             <void/> 
2190             <nullok>value is set to <code>NULL</code></nullok> 
2191           </inbuf> 
2192           <description>
2193             The value to be entered into the thread-local storage.
2194           </description>
2195         </param>
2196       </parameters>
2197       <errors>
2198       </errors>
2199     </function>
2200 
2201     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
2202       <synopsis>Get Thread Local Storage</synopsis>
2203       <description>
2204         Called by the agent to get the value of the <jvmti/> thread-local
2205         storage. 
2206       </description>
2207       <origin>jvmpi</origin>
2208       <capabilities>
2209       </capabilities>
2210       <parameters>
2211         <param id="thread">
2212           <jthread null="current" impl="noconvert"/>
2213             <description>
2214               Retrieve from this thread.
2215             </description>
2216         </param>
2217         <param id="data_ptr">
2218           <agentbuf><void/></agentbuf>
2219           <description>
2220             Pointer through which the value of the thread local 
2221             storage is returned.
2222             If thread-local storage has not been set with
2223             <functionlink id="SetThreadLocalStorage"></functionlink> the returned 
2224             pointer is <code>NULL</code>.
2225           </description>
2226         </param>
2227       </parameters>
2228       <errors>
2229       </errors>
2230     </function>
2231 
2232   </category>
2233 
2234   <category id="thread_groups" label="Thread Group">
2235     <intro>
2236     </intro>
2237 
2238     <function id="GetTopThreadGroups" num="13">
2239       <synopsis>Get Top Thread Groups</synopsis>
2240       <description>
2241         Return all top-level (parentless) thread groups in the VM.
2242       </description>
2243       <origin>jvmdi</origin>
2244       <capabilities>
2245       </capabilities>
2246       <parameters>
2247         <param id="group_count_ptr">
2248           <outptr><jint/></outptr>
2249           <description>
2250             On return, points to the number of top-level thread groups.
2251           </description>
2252         </param>
2253         <param id="groups_ptr">
2254           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2255             <description>
2256               On return, refers to a pointer to the top-level thread group array.
2257             </description>
2258         </param>
2259       </parameters>
2260       <errors>
2261       </errors>
2262     </function>
2263 
2264     <function id="GetThreadGroupInfo" num="14">
2265       <synopsis>Get Thread Group Info</synopsis>
2266       <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
2267         <field id="parent">
2268           <jthreadGroup/>
2269           <description>
2270             The parent thread group.
2271           </description>
2272         </field>
2273         <field id="name">
2274           <allocfieldbuf><char/></allocfieldbuf>
2275           <description>
2276             The thread group's name, encoded as a
2277             <internallink id="mUTF">modified UTF-8</internallink> string.
2278           </description>
2279         </field>
2280         <field id="max_priority">
2281           <jint/>
2282           <description>
2283             The maximum priority for this thread group.
2284           </description>
2285         </field>
2286         <field id="is_daemon">
2287           <jboolean/>
2288           <description>
2289             Is this a daemon thread group?
2290           </description>
2291         </field>
2292       </typedef>
2293       <description>
2294         Get information about the thread group. The fields of the 
2295         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure 
2296         are filled in with details of the specified thread group.
2297       </description>
2298       <origin>jvmdi</origin>
2299       <capabilities>
2300       </capabilities>
2301       <parameters>
2302         <param id="group">
2303           <jthreadGroup/>
2304           <description>
2305             The thread group to query.
2306           </description>
2307         </param>
2308         <param id="info_ptr">
2309           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
2310           <description>
2311             On return, filled with information describing the specified
2312             thread group. 
2313           </description>
2314         </param>
2315       </parameters>
2316       <errors>
2317       </errors>
2318     </function>
2319 
2320     <function id="GetThreadGroupChildren" num="15">
2321       <synopsis>Get Thread Group Children</synopsis>
2322       <description>
2323         Get the live threads and active subgroups in this thread group.
2324       </description>
2325       <origin>jvmdi</origin>
2326       <capabilities>
2327       </capabilities>
2328       <parameters>
2329         <param id="group">
2330           <jthreadGroup/>
2331           <description>
2332             The group to query.
2333           </description>
2334         </param>
2335         <param id="thread_count_ptr">
2336           <outptr><jint/></outptr>
2337           <description>
2338             On return, points to the number of live threads in this thread group.
2339           </description>
2340         </param>
2341         <param id="threads_ptr">
2342           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
2343             <description>
2344               On return, points to an array of the live threads in this thread group.
2345             </description>
2346         </param>
2347         <param id="group_count_ptr">
2348           <outptr><jint/></outptr>
2349           <description>
2350             On return, points to the number of active child thread groups
2351           </description>
2352         </param>
2353         <param id="groups_ptr">
2354           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2355             <description>
2356               On return, points to an array of the active child thread groups.
2357             </description>
2358         </param>
2359       </parameters>
2360       <errors>
2361       </errors>
2362     </function>
2363   </category>
2364 
2365   <category id="stack" label="Stack Frame">
2366     <intro>
2367         These functions provide information about the stack of a thread.
2368         Stack frames are referenced by depth.
2369         The frame at depth zero is the current frame.
2370         <p/>
2371         Stack frames are as described in
2372         <vmspec chapter="3.6"/>,
2373         That is, they correspond to method 
2374         invocations (including native methods) but do not correspond to platform native or 
2375         VM internal frames.
2376         <p/>
2377         A <jvmti/> implementation may use method invocations to launch a thread and
2378         the corresponding frames may be included in the stack as presented by these functions --
2379         that is, there may be frames shown
2380         deeper than <code>main()</code> and <code>run()</code>.
2381         However this presentation must be consistent across all <jvmti/> functionality which 
2382         uses stack frames or stack depth.
2383     </intro>
2384 
2385       <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
2386         <description>
2387           Information about a stack frame is returned in this structure.
2388         </description>
2389         <field id="method">
2390           <jmethodID/>
2391             <description>
2392               The method executing in this frame.
2393             </description>
2394         </field>
2395         <field id="location">
2396           <jlocation/>
2397           <description>
2398             The index of the instruction executing in this frame.
2399             <code>-1</code> if the frame is executing a native method.
2400           </description>
2401         </field>
2402       </typedef>
2403 
2404       <typedef id="jvmtiStackInfo" label="Stack information structure">
2405         <description>
2406           Information about a set of stack frames is returned in this structure.
2407         </description>
2408         <field id="thread">
2409           <jthread/>
2410           <description>
2411             On return, the thread traced.
2412           </description>
2413         </field>
2414         <field id="state">
2415           <jint/>
2416           <description>
2417             On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
2418           </description>
2419         </field>
2420         <field id="frame_buffer">
2421           <outbuf incount="max_frame_count">
2422             <struct>jvmtiFrameInfo</struct>
2423           </outbuf>
2424             <description>
2425               On return, this agent allocated buffer is filled 
2426               with stack frame information.  
2427             </description>
2428         </field>
2429         <field id="frame_count">
2430           <jint/>
2431           <description>
2432             On return, the number of records filled into 
2433             <code>frame_buffer</code>.
2434             This will be 
2435             min(<code>max_frame_count</code>, <i>stackDepth</i>).
2436           </description>
2437         </field>
2438       </typedef>
2439 
2440     <function id="GetStackTrace" num="104">
2441       <synopsis>Get Stack Trace</synopsis>
2442       <description>
2443         Get information about the stack of a thread.
2444         If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
2445         the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, 
2446         otherwise the entire stack is returned.
2447         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2448         <p/>
2449         The following example causes up to five of the topmost frames
2450         to be returned and (if there are any frames) the currently
2451         executing method name to be printed.
2452         <example>
2453 jvmtiFrameInfo frames[5];
2454 jint count;
2455 jvmtiError err;
2456 
2457 err = (*jvmti)-&gt;GetStackTrace(jvmti, aThread, 0, 5, 
2458                                frames, &amp;count);
2459 if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
2460    char *methodName;
2461    err = (*jvmti)-&gt;GetMethodName(jvmti, frames[0].method, 
2462                        &amp;methodName, NULL, NULL);
2463    if (err == JVMTI_ERROR_NONE) {
2464       printf("Executing method: %s", methodName);
2465    }
2466 }
2467         </example>
2468         <todo> 
2469           check example code.
2470         </todo>
2471         <p/>
2472         The <paramlink id="thread"></paramlink> need not be suspended
2473         to call this function.  
2474         <p/>
2475         The <functionlink id="GetLineNumberTable"></functionlink>
2476         function can be used to map locations to line numbers. Note that
2477         this mapping can be done lazily.
2478       </description>
2479       <origin>jvmpi</origin>
2480       <capabilities>
2481       </capabilities>
2482       <parameters>
2483         <param id="thread">
2484           <jthread null="current"/>
2485             <description>
2486               Fetch the stack trace of this thread.
2487             </description>
2488         </param>
2489         <param id="start_depth">
2490           <jint/>
2491           <description>
2492             Begin retrieving frames at this depth.  
2493             If non-negative, count from the current frame, 
2494             the first frame retrieved is at depth <code>start_depth</code>.  
2495             For example, if zero, start from the current frame; if one, start from the
2496             caller of the current frame; if two, start from the caller of the
2497             caller of the current frame; and so on.
2498             If negative, count from below the oldest frame,
2499             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,  
2500             where <i>stackDepth</i> is the count of frames on the stack.  
2501             For example, if negative one, only the oldest frame is retrieved;
2502             if negative two, start from the frame called by the oldest frame.
2503           </description>
2504         </param>
2505         <param id="max_frame_count">
2506           <jint min="0"/>
2507           <description>
2508             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2509           </description>
2510         </param>
2511         <param id="frame_buffer">
2512           <outbuf incount="max_frame_count" outcount="count_ptr">
2513             <struct>jvmtiFrameInfo</struct>
2514           </outbuf>
2515             <description>
2516               On return, this agent allocated buffer is filled 
2517               with stack frame information.  
2518             </description>
2519         </param>
2520         <param id="count_ptr">
2521           <outptr><jint/></outptr>
2522           <description>
2523             On return, points to the number of records filled in.
2524             For non-negative <code>start_depth</code>, this will be 
2525             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
2526             For negative <code>start_depth</code>, this will be 
2527             min(<code>max_frame_count</code>, <code>-start_depth</code>).
2528           </description>
2529         </param>
2530       </parameters>
2531       <errors>
2532         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
2533           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
2534           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
2535         </error>
2536       </errors>
2537     </function>
2538 
2539 
2540     <function id="GetAllStackTraces" num="100">
2541       <synopsis>Get All Stack Traces</synopsis>
2542       <description>
2543         Get information about the stacks of all live threads
2544         (including <internallink id="RunAgentThread">agent threads</internallink>).
2545         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2546         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 
2547         otherwise the entire stack is returned.
2548         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2549         <p/>
2550         All stacks are collected simultaneously, that is, no changes will occur to the 
2551         thread state or stacks between the sampling of one thread and the next.
2552         The threads need not be suspended.
2553         
2554         <example>
2555 jvmtiStackInfo *stack_info;
2556 jint thread_count;
2557 int ti;
2558 jvmtiError err;
2559 
2560 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count); 
2561 if (err != JVMTI_ERROR_NONE) {
2562    ...   
2563 }
2564 for (ti = 0; ti &lt; thread_count; ++ti) {
2565    jvmtiStackInfo *infop = &amp;stack_info[ti];
2566    jthread thread = infop-&gt;thread;
2567    jint state = infop-&gt;state;
2568    jvmtiFrameInfo *frames = infop-&gt;frame_buffer;
2569    int fi;
2570 
2571    myThreadAndStatePrinter(thread, state);
2572    for (fi = 0; fi &lt; infop-&gt;frame_count; fi++) {
2573       myFramePrinter(frames[fi].method, frames[fi].location);
2574    }
2575 }
2576 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
2577 err = (*jvmti)-&gt;Deallocate(jvmti, stack_info); 
2578         </example>
2579         <todo> 
2580           check example code.
2581         </todo>
2582 
2583       </description>
2584       <origin>new</origin>
2585       <capabilities>
2586       </capabilities>
2587       <parameters>
2588         <param id="max_frame_count">
2589           <jint min="0"/>
2590           <description>
2591             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2592           </description>
2593         </param>
2594         <param id="stack_info_ptr">
2595           <allocbuf>
2596             <struct>jvmtiStackInfo</struct>
2597           </allocbuf>
2598             <description>
2599               On return, this buffer is filled 
2600               with stack information for each thread.  
2601               The number of <datalink id="jvmtiStackInfo"/> records is determined 
2602               by <paramlink id="thread_count_ptr"/>.
2603               <p/>
2604               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 
2605               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2606               These buffers must not be separately deallocated.
2607             </description>
2608         </param>
2609         <param id="thread_count_ptr">
2610           <outptr><jint/></outptr>
2611           <description>
2612             The number of threads traced.
2613           </description>
2614         </param>
2615       </parameters>
2616       <errors>
2617       </errors>
2618     </function>
2619 
2620     <function id="GetThreadListStackTraces" num="101">
2621       <synopsis>Get Thread List Stack Traces</synopsis>
2622       <description>
2623         Get information about the stacks of the supplied threads.
2624         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2625         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 
2626         otherwise the entire stack is returned.
2627         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2628         <p/>
2629         All stacks are collected simultaneously, that is, no changes will occur to the 
2630         thread state or stacks between the sampling one thread and the next.
2631         The threads need not be suspended.
2632         <p/>
2633         If a thread has not yet started or terminates before the stack information is collected,
2634         a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
2635         will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
2636         <p/>
2637         See the example for the similar function
2638         <functionlink id="GetAllStackTraces"/>.
2639       </description>
2640       <origin>new</origin>
2641       <capabilities>
2642       </capabilities>
2643       <parameters>
2644         <param id="thread_count">
2645           <jint min="0"/>
2646           <description>
2647             The number of threads to trace.
2648           </description>
2649         </param>
2650         <param id="thread_list">
2651           <inbuf incount="thread_count"><jthread/></inbuf>
2652             <description>
2653               The list of threads to trace.
2654             </description>
2655         </param>
2656         <param id="max_frame_count">
2657           <jint min="0"/>
2658           <description>
2659             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2660           </description>
2661         </param>
2662         <param id="stack_info_ptr">
2663           <allocbuf outcount="thread_count">
2664             <struct>jvmtiStackInfo</struct>
2665           </allocbuf>
2666             <description>
2667               On return, this buffer is filled 
2668               with stack information for each thread.  
2669               The number of <datalink id="jvmtiStackInfo"/> records is determined 
2670               by <paramlink id="thread_count"/>.
2671               <p/>
2672               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 
2673               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2674               These buffers must not be separately deallocated.
2675             </description>
2676         </param>
2677       </parameters>
2678       <errors>
2679         <error id="JVMTI_ERROR_INVALID_THREAD">
2680           An element in <paramlink id="thread_list"/> is not a thread object.
2681         </error>
2682       </errors>
2683     </function>
2684 
2685     <elide>
2686     <function id="AsyncGetStackTrace" num="1000">
2687       <synopsis>Get Stack Trace--Asynchronous</synopsis>
2688       <description>
2689         Get information about the entire stack of a thread (or a sub-section of it).
2690         This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
2691         and is reentrant and safe to call
2692         from asynchronous signal handlers.
2693         The stack trace is returned only for the calling thread.
2694         <p/>
2695         The <functionlink id="GetLineNumberTable"></functionlink>
2696         function can be used to map locations to line numbers. Note that
2697         this mapping can be done lazily.
2698       </description>
2699       <origin>jvmpi</origin>
2700       <capabilities>
2701         <required id="can_get_async_stack_trace"></required>
2702         <capability id="can_show_JVM_spec_async_frames">
2703           If <code>false</code>, 
2704           <paramlink id="use_java_stack"></paramlink> 
2705           must be <code>false</code>.
2706         </capability>
2707       </capabilities>
2708       <parameters>
2709         <param id="use_java_stack">
2710           <jboolean/>
2711           <description>
2712             Return the stack showing <vmspec/>
2713             model of the stack; 
2714             otherwise, show the internal representation of the stack with
2715             inlined and optimized methods missing.  If the virtual machine
2716             is using the <i>Java Virtual Machine Specification</i> stack model
2717             internally, this flag is ignored.
2718           </description>
2719         </param>
2720         <param id="max_count">
2721           <jint min="0"/>
2722           <description>
2723             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2724             Retrieve this many unless the stack depth is less than <code>max_count</code>.
2725           </description>
2726         </param>
2727         <param id="frame_buffer">
2728           <outbuf incount="max_count" outcount="count_ptr">
2729             <struct>jvmtiFrameInfo</struct>
2730             <nullok>this information is not returned</nullok>
2731           </outbuf>
2732             <description>
2733               The agent passes in a buffer
2734               large enough to hold <code>max_count</code> records of 
2735               <datalink id="jvmtiFrameInfo"></datalink>.  This buffer must be
2736               pre-allocated by the agent.  
2737             </description>
2738         </param>
2739         <param id="count_ptr">
2740           <outptr><jint/></outptr>
2741           <description>
2742             On return, points to the number of records filled in..
2743           </description>
2744         </param>
2745       </parameters>
2746       <errors>
2747         <error id="JVMTI_ERROR_UNATTACHED_THREAD">
2748           The thread being used to call this function is not attached
2749           to the virtual machine.  Calls must be made from attached threads.
2750         </error>
2751       </errors>
2752     </function>
2753     </elide>
2754 
2755     <function id="GetFrameCount" num="16">
2756       <synopsis>Get Frame Count</synopsis>
2757       <description>
2758         Get the number of frames currently in the specified thread's call stack.
2759         <p/>
2760         If this function is called for a thread actively executing bytecodes (for example,
2761         not the current thread and not suspended), the information returned is transient.
2762       </description>
2763       <origin>jvmdi</origin>
2764       <capabilities>
2765       </capabilities>
2766       <parameters>
2767         <param id="thread">
2768           <jthread null="current"/>
2769             <description>
2770               The thread to query.
2771             </description>
2772         </param>
2773         <param id="count_ptr">
2774           <outptr><jint/></outptr>
2775           <description>
2776             On return, points to the number of frames in the call stack.
2777           </description>
2778         </param>
2779       </parameters>
2780       <errors>
2781       </errors>
2782     </function>
2783 
2784     <function id="PopFrame" num="80">
2785       <synopsis>Pop Frame</synopsis>
2786       <description>
2787         Pop the current frame of <code>thread</code>'s stack.
2788         Popping a frame takes you to the previous frame.  
2789         When the thread is resumed, the execution 
2790         state of the thread is reset to the state
2791         immediately before the called method was invoked.
2792         That is (using <vmspec/> terminology):
2793           <ul>
2794             <li>the current frame is discarded as the previous frame becomes the current one</li>
2795             <li>the operand stack is restored--the argument values are added back
2796               and if the invoke was not <code>invokestatic</code>, 
2797               <code>objectref</code> is added back as well</li>
2798             <li>the Java virtual machine PC is restored to the opcode
2799               of the invoke instruction</li>
2800           </ul>
2801         Note however, that any changes to the arguments, which
2802         occurred in the called method, remain; 
2803         when execution continues, the first instruction to 
2804         execute will be the invoke.  
2805         <p/>
2806         Between calling <code>PopFrame</code> and resuming the 
2807         thread the state of the stack is undefined.  
2808         To pop frames beyond the first, 
2809         these three steps must be repeated:
2810         <ul>
2811           <li>suspend the thread via an event (step, breakpoint, ...)</li>
2812           <li>call <code>PopFrame</code></li>
2813           <li>resume the thread</li>
2814         </ul>
2815         <p/>
2816         A lock acquired by calling the called method 
2817         (if it is a <code>synchronized</code>  method) 
2818         and locks acquired by entering <code>synchronized</code>
2819         blocks within the called method are released. 
2820         Note: this does not apply to native locks or 
2821         <code>java.util.concurrent.locks</code> locks.
2822         <p/>
2823         Finally blocks are not executed.
2824         <p/>
2825         Changes to global state are not addressed and thus remain changed.
2826         <p/>
2827         The specified thread must be suspended (which implies it cannot be the current thread).
2828         <p/>
2829         Both the called method and calling method must be non-native Java programming 
2830         language methods.
2831         <p/>
2832         No <jvmti/> events are generated by this function.
2833       </description>
2834       <origin>jvmdi</origin>
2835       <capabilities>
2836         <required id="can_pop_frame"></required>
2837       </capabilities>
2838       <parameters>
2839         <param id="thread">
2840           <jthread/>
2841             <description>
2842               The thread whose current frame is to be popped.
2843             </description>
2844         </param>
2845       </parameters>
2846       <errors>
2847         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2848           Called or calling method is a native method.
2849           The implementation is unable to pop this frame.
2850         </error>
2851         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2852           Thread was not suspended.
2853         </error>
2854         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2855           There are less than two stack frames on the call stack.
2856         </error>
2857       </errors>
2858     </function>
2859 
2860     <function id="GetFrameLocation" num="19">
2861       <synopsis>Get Frame Location</synopsis>
2862       <description>
2863         <p/>
2864         For a Java programming language frame, return the location of the instruction
2865         currently executing.
2866       </description>
2867       <origin>jvmdiClone</origin>
2868       <capabilities>
2869       </capabilities>
2870       <parameters>
2871         <param id="thread">
2872           <jthread null="current" frame="frame"/>
2873           <description>
2874             The thread of the frame to query.
2875           </description>
2876         </param>
2877         <param id="depth">
2878           <jframeID thread="thread"/>
2879           <description>
2880             The depth of the frame to query.
2881           </description>
2882         </param>
2883         <param id="method_ptr">
2884           <outptr><jmethodID/></outptr>
2885             <description>
2886               On return, points to the method for the current location.
2887             </description>
2888         </param>
2889         <param id="location_ptr">
2890           <outptr><jlocation/></outptr>
2891           <description>
2892             On return, points to the index of the currently 
2893             executing instruction.
2894             Is set to <code>-1</code> if the frame is executing
2895             a native method.
2896           </description>
2897         </param>
2898       </parameters>
2899       <errors>
2900       </errors>
2901     </function>
2902 
2903     <function id="NotifyFramePop" num="20">
2904       <synopsis>Notify Frame Pop</synopsis>
2905       <description>
2906         When the frame that is currently at <paramlink id="depth"></paramlink> 
2907         is popped from the stack, generate a
2908         <eventlink id="FramePop"></eventlink> event.  See the 
2909         <eventlink id="FramePop"></eventlink> event for details.
2910         Only frames corresponding to non-native Java programming language 
2911         methods can receive notification.
2912         <p/>
2913         The specified thread must either be the current thread
2914         or the thread must be suspended.
2915       </description>
2916       <origin>jvmdi</origin>
2917       <capabilities>
2918         <required id="can_generate_frame_pop_events"></required>
2919       </capabilities>
2920       <parameters>
2921         <param id="thread">
2922           <jthread null="current" frame="depth"/>   
2923           <description>
2924             The thread of the frame for which the frame pop event will be generated.
2925           </description>
2926         </param>
2927         <param id="depth">
2928           <jframeID thread="thread"/>
2929           <description>
2930             The depth of the frame for which the frame pop event will be generated.
2931           </description>
2932         </param>
2933       </parameters>
2934       <errors>
2935         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
2936           The frame at <code>depth</code> is executing a
2937           native method.
2938         </error>
2939         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2940           Thread was not suspended and was not the current thread.
2941         </error>
2942       </errors>
2943     </function>
2944 
2945   </category>
2946 
2947   <category id="ForceEarlyReturn" label="Force Early Return">
2948     <intro>
2949       These functions allow an agent to force a method
2950       to return at any point during its execution.
2951       The method which will return early is referred to as the <i>called method</i>.
2952       The called method is the current method
2953       (as defined by
2954       <vmspec chapter="3.6"/>) 
2955       for the specified thread at
2956       the time the function is called.
2957       <p/>
2958       The specified thread must be suspended or must be the current thread.
2959       The return occurs when execution of Java programming
2960       language code is resumed on this thread.
2961       Between calling one of these functions and resumption
2962       of thread execution, the state of the stack is undefined.  
2963       <p/>
2964       No further instructions are executed in the called method.  
2965       Specifically, finally blocks are not executed.
2966       Note: this can cause inconsistent states in the application.
2967       <p/>
2968       A lock acquired by calling the called method 
2969       (if it is a <code>synchronized</code>  method) 
2970       and locks acquired by entering <code>synchronized</code>
2971       blocks within the called method are released. 
2972       Note: this does not apply to native locks or 
2973       <code>java.util.concurrent.locks</code> locks.
2974       <p/>
2975       Events, such as <eventlink id="MethodExit"></eventlink>,
2976       are generated as they would be in a normal return.
2977       <p/>
2978       The called method must be a non-native Java programming
2979       language method.
2980       Forcing return on a thread with only one frame on the
2981       stack causes the thread to exit when resumed.
2982     </intro>
2983 
2984     <function id="ForceEarlyReturnObject" num="81" since="1.1">
2985       <synopsis>Force Early Return - Object</synopsis>
2986       <description>
2987         This function can be used to return from a method whose
2988         result type is <code>Object</code>
2989         or a subclass of <code>Object</code>. 
2990       </description>
2991       <origin>new</origin>
2992       <capabilities>
2993         <required id="can_force_early_return"></required>
2994       </capabilities>
2995       <parameters>
2996         <param id="thread">
2997           <jthread null="current"/>
2998           <description>
2999             The thread whose current frame is to return early.
3000           </description>
3001         </param>
3002         <param id="value">
3003           <jobject/>
3004           <description>
3005             The return value for the called frame. 
3006             An object or <code>NULL</code>.
3007           </description>
3008         </param>
3009       </parameters>
3010       <errors>
3011         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3012           Attempted to return early from a frame
3013           corresponding to a native method.
3014           Or the implementation is unable to provide
3015           this functionality on this frame.
3016         </error>
3017         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3018           The result type of the called method is not 
3019           <code>Object</code> or a subclass of <code>Object</code>.
3020         </error>
3021         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3022           The supplied <paramlink id="value"/> is not compatible with the 
3023           result type of the called method.
3024         </error>
3025         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3026           Thread was not the current thread and was not suspended.
3027         </error>
3028         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3029           There are no more frames on the call stack.
3030         </error>
3031       </errors>
3032     </function>
3033 
3034     <function id="ForceEarlyReturnInt" num="82" since="1.1">
3035       <synopsis>Force Early Return - Int</synopsis>
3036       <description>
3037         This function can be used to return from a method whose
3038         result type is <code>int</code>, <code>short</code>,
3039         <code>char</code>, <code>byte</code>, or 
3040         <code>boolean</code>. 
3041       </description>
3042       <origin>new</origin>
3043       <capabilities>
3044         <required id="can_force_early_return"></required>
3045       </capabilities>
3046       <parameters>
3047         <param id="thread">
3048           <jthread null="current"/>
3049           <description>
3050             The thread whose current frame is to return early.
3051           </description>
3052         </param>
3053         <param id="value">
3054           <jint/>
3055           <description>
3056             The return value for the called frame.
3057           </description>
3058         </param>
3059       </parameters>
3060       <errors>
3061         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3062           Attempted to return early from a frame
3063           corresponding to a native method.
3064           Or the implementation is unable to provide
3065           this functionality on this frame.
3066         </error>
3067         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3068           The result type of the called method is not 
3069           <code>int</code>, <code>short</code>,
3070           <code>char</code>, <code>byte</code>, or 
3071           <code>boolean</code>.
3072         </error>
3073         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3074           Thread was not the current thread and was not suspended.
3075         </error>
3076         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3077           There are no frames on the call stack.
3078         </error>
3079       </errors>
3080     </function>
3081 
3082     <function id="ForceEarlyReturnLong" num="83" since="1.1">
3083       <synopsis>Force Early Return - Long</synopsis>
3084       <description>
3085         This function can be used to return from a method whose
3086         result type is <code>long</code>.
3087       </description>
3088       <origin>new</origin>
3089       <capabilities>
3090         <required id="can_force_early_return"></required>
3091       </capabilities>
3092       <parameters>
3093         <param id="thread">
3094           <jthread null="current"/>
3095           <description>
3096             The thread whose current frame is to return early.
3097           </description>
3098         </param>
3099         <param id="value">
3100           <jlong/>
3101           <description>
3102             The return value for the called frame.
3103           </description>
3104         </param>
3105       </parameters>
3106       <errors>
3107         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3108           Attempted to return early from a frame
3109           corresponding to a native method.
3110           Or the implementation is unable to provide
3111           this functionality on this frame.
3112         </error>
3113         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3114           The result type of the called method is not <code>long</code>.
3115         </error>
3116         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3117           Thread was not the current thread and was not suspended.
3118         </error>
3119         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3120           There are no frames on the call stack.
3121         </error>
3122       </errors>
3123     </function>
3124 
3125     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
3126       <synopsis>Force Early Return - Float</synopsis>
3127       <description>
3128         This function can be used to return from a method whose
3129         result type is <code>float</code>.
3130       </description>
3131       <origin>new</origin>
3132       <capabilities>
3133         <required id="can_force_early_return"></required>
3134       </capabilities>
3135       <parameters>
3136         <param id="thread">
3137           <jthread null="current"/>
3138           <description>
3139             The thread whose current frame is to return early.
3140           </description>
3141         </param>
3142         <param id="value">
3143           <jfloat/>
3144           <description>
3145             The return value for the called frame.
3146           </description>
3147         </param>
3148       </parameters>
3149       <errors>
3150         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3151           Attempted to return early from a frame
3152           corresponding to a native method.
3153           Or the implementation is unable to provide
3154           this functionality on this frame.
3155         </error>
3156         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3157           The result type of the called method is not <code>float</code>.
3158         </error>
3159         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3160           Thread was not the current thread and was not suspended.
3161         </error>
3162         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3163           There are no frames on the call stack.
3164         </error>
3165       </errors>
3166     </function>
3167 
3168     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
3169       <synopsis>Force Early Return - Double</synopsis>
3170       <description>
3171         This function can be used to return from a method whose
3172         result type is <code>double</code>.
3173       </description>
3174       <origin>new</origin>
3175       <capabilities>
3176         <required id="can_force_early_return"></required>
3177       </capabilities>
3178       <parameters>
3179         <param id="thread">
3180           <jthread null="current"/>
3181           <description>
3182             The thread whose current frame is to return early.
3183           </description>
3184         </param>
3185         <param id="value">
3186           <jdouble/>
3187           <description>
3188             The return value for the called frame.
3189           </description>
3190         </param>
3191       </parameters>
3192       <errors>
3193         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3194           Attempted to return early from a frame corresponding to a native method.
3195           Or the implementation is unable to provide this functionality on this frame.
3196         </error>
3197         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3198           The result type of the called method is not <code>double</code>.
3199         </error>
3200         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3201           Thread was not the current thread and was not suspended.
3202         </error>
3203         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3204           There are no frames on the call stack.
3205         </error>
3206       </errors>
3207     </function>
3208 
3209     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3210       <synopsis>Force Early Return - Void</synopsis>
3211       <description>
3212         This function can be used to return from a method with no result type.
3213         That is, the called method must be declared <code>void</code>.
3214       </description>
3215       <origin>new</origin>
3216       <capabilities>
3217         <required id="can_force_early_return"></required>
3218       </capabilities>
3219       <parameters>
3220         <param id="thread">
3221           <jthread null="current"/>
3222           <description>
3223             The thread whose current frame is to return early.
3224           </description>
3225         </param>
3226       </parameters>
3227       <errors>
3228         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3229           Attempted to return early from a frame
3230           corresponding to a native method.
3231           Or the implementation is unable to provide
3232           this functionality on this frame.
3233         </error>
3234         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3235           The called method has a result type.  
3236         </error>
3237         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3238           Thread was not the current thread and was not suspended.
3239         </error>
3240         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3241           There are no frames on the call stack.
3242         </error>
3243       </errors>
3244     </function>
3245 
3246   </category>
3247 
3248   <category id="Heap" label="Heap">
3249     <intro>
3250       These functions are used to analyze the heap.
3251       Functionality includes the ability to view the objects in the
3252       heap and to tag these objects.
3253     </intro>
3254    
3255     <intro id="objectTags" label="Object Tags">
3256       A <i>tag</i> is a value associated with an object.
3257       Tags are explicitly set by the agent using the
3258       <functionlink id="SetTag"></functionlink> function or by
3259       callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.    
3260       <p/>
3261       Tags are local to the environment; that is, the tags of one
3262       environment are not visible in another.
3263       <p/>
3264       Tags are <code>jlong</code> values which can be used
3265       simply to mark an object or to store a pointer to more detailed
3266       information.  Objects which have not been tagged have a
3267       tag of zero.  
3268       Setting a tag to zero makes the object untagged.
3269     </intro>
3270    
3271     <intro id="heapCallbacks" label="Heap Callback Functions">
3272         Heap functions which iterate through the heap and recursively
3273         follow object references use agent supplied callback functions
3274         to deliver the information.
3275         <p/>
3276         These heap callback functions must adhere to the following restrictions --
3277         These callbacks must not use JNI functions.
3278         These callbacks must not use <jvmti/> functions except 
3279         <i>callback safe</i> functions which
3280         specifically allow such use (see the raw monitor, memory management,
3281         and environment local storage functions).
3282         <p/>
3283         An implementation may invoke a callback on an internal thread or
3284         the thread which called the iteration function.
3285         Heap callbacks are single threaded -- no more than one callback will
3286         be invoked at a time.
3287         <p/>
3288         The Heap Filter Flags can be used to prevent reporting
3289         based on the tag status of an object or its class.  
3290         If no flags are set (the <code>jint</code> is zero), objects
3291         will not be filtered out.
3292 
3293         <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
3294           <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
3295             Filter out tagged objects. Objects which are tagged are not included.
3296           </constant>
3297           <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
3298             Filter out untagged objects. Objects which are not tagged are not included.
3299           </constant>
3300           <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
3301             Filter out objects with tagged classes. Objects whose class is tagged are not included.
3302           </constant>
3303           <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
3304             Filter out objects with untagged classes. Objects whose class is not tagged are not included.
3305           </constant>
3306         </constants>
3307 
3308         <p/>
3309         The Heap Visit Control Flags are returned by the heap callbacks
3310         and can be used to abort the iteration.  For the 
3311         <functionlink id="jvmtiHeapReferenceCallback">Heap 
3312         Reference Callback</functionlink>, it can also be used 
3313         to prune the graph of traversed references
3314         (<code>JVMTI_VISIT_OBJECTS</code> is not set).
3315 
3316         <constants id="jvmtiHeapVisitControl" 
3317                    label="Heap Visit Control Flags" 
3318                    kind="bits" 
3319                    since="1.1">
3320           <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
3321             If we are visiting an object and if this callback
3322             was initiated by <functionlink id="FollowReferences"/>, 
3323             traverse the references of this object.
3324             Otherwise ignored.
3325           </constant>       
3326           <constant id="JVMTI_VISIT_ABORT" num="0x8000">
3327             Abort the iteration.  Ignore all other bits.
3328           </constant>
3329         </constants>
3330 
3331         <p/>
3332         The Heap Reference Enumeration is provided by the 
3333         <functionlink id="jvmtiHeapReferenceCallback">Heap 
3334         Reference Callback</functionlink> and 
3335         <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field 
3336         Callback</functionlink> to 
3337         describe the kind of reference
3338         being reported.
3339 
3340         <constants id="jvmtiHeapReferenceKind" 
3341                    label="Heap Reference Enumeration" 
3342                    kind="enum" 
3343                    since="1.1">
3344           <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
3345             Reference from an object to its class.
3346           </constant>       
3347           <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
3348             Reference from an object to the value of one of its instance fields.
3349           </constant>
3350           <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
3351             Reference from an array to one of its elements.
3352           </constant>
3353           <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
3354             Reference from a class to its class loader.
3355           </constant>
3356           <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
3357             Reference from a class to its signers array.
3358           </constant>
3359           <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
3360             Reference from a class to its protection domain.
3361           </constant>       
3362           <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
3363             Reference from a class to one of its interfaces. 
3364             Note: interfaces are defined via a constant pool reference,
3365             so the referenced interfaces may also be reported with a 
3366             <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3367           </constant>
3368           <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
3369             Reference from a class to the value of one of its static fields.
3370           </constant>
3371           <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
3372             Reference from a class to a resolved entry in the constant pool.
3373           </constant>
3374           <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
3375             Reference from a class to its superclass. 
3376             A callback is bot sent if the superclass is <code>java.lang.Object</code>.
3377             Note: loaded classes define superclasses via a constant pool
3378             reference, so the referenced superclass may also be reported with 
3379             a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3380           </constant>
3381           <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
3382             Heap root reference: JNI global reference.
3383           </constant>
3384           <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
3385             Heap root reference: System class.
3386           </constant>
3387           <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
3388             Heap root reference: monitor.
3389           </constant>
3390           <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
3391             Heap root reference: local variable on the stack.
3392           </constant>
3393           <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
3394             Heap root reference: JNI local reference.
3395           </constant>
3396           <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
3397             Heap root reference: Thread.
3398           </constant>
3399           <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
3400             Heap root reference: other heap root reference.
3401           </constant>
3402         </constants>
3403 
3404         <p/>
3405         Definitions for the single character type descriptors of
3406         primitive types.
3407 
3408         <constants id="jvmtiPrimitiveType" 
3409                    label="Primitive Type Enumeration" 
3410                    kind="enum" 
3411                    since="1.1">
3412           <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
3413             'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
3414           </constant>       
3415           <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
3416             'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
3417           </constant>       
3418           <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
3419             'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
3420           </constant>       
3421           <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
3422             'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
3423           </constant>       
3424           <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
3425             'I' - Java programming language <code>int</code> - JNI <code>jint</code>
3426           </constant>       
3427           <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
3428             'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
3429           </constant>       
3430           <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
3431             'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
3432           </constant>       
3433           <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
3434             'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
3435           </constant>       
3436         </constants>
3437     </intro>
3438 
3439       <typedef id="jvmtiHeapReferenceInfoField" 
3440                label="Reference information structure for Field references" 
3441                since="1.1">
3442         <description>
3443           Reference information returned for 
3444           <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and 
3445           <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3446         </description>
3447         <field id="index">
3448           <jint/>
3449           <description>       
3450             For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the 
3451             referrer object is not a class or an inteface.  
3452             In this case, <code>index</code> is the index of the field 
3453             in the class of the referrer object.  
3454             This class is referred to below as <i>C</i>.
3455             <p/>
3456             For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
3457             the referrer object is a class (referred to below as <i>C</i>)
3458             or an interface (referred to below as <i>I</i>).
3459             In this case, <code>index</code> is the index of the field in 
3460             that class or interface.
3461             <p/>
3462             If the referrer object is not an interface, then the field 
3463             indices are determined as follows: 
3464             <ul>
3465               <li>make a list of all the fields in <i>C</i> and its
3466                   superclasses, starting with all the fields in 
3467                   <code>java.lang.Object</code> and ending with all the
3468                   fields in <i>C</i>.</li>
3469               <li>Within this list, put 
3470                   the fields for a given class in the order returned by
3471                   <functionlink id="GetClassFields"/>.</li>
3472               <li>Assign the fields in this list indices 
3473                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 
3474                   is the count of the fields in all the interfaces
3475                   implemented by <i>C</i>. 
3476                   Note that <i>C</i> implements all interfaces 
3477                   directly implemented by its superclasses; as well
3478                   as all superinterfaces of these interfaces.</li>
3479             </ul>
3480             If the referrer object is an interface, then the field 
3481             indices are determined as follows:
3482             <ul>
3483               <li>make a list of the fields directly declared in 
3484                   <i>I</i>.</li>
3485               <li>Within this list, put 
3486                   the fields in the order returned by
3487                   <functionlink id="GetClassFields"/>.</li>
3488               <li>Assign the fields in this list indices 
3489                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 
3490                   is the count of the fields in all the superinterfaces
3491                   of <i>I</i>.</li>
3492             </ul>
3493             All fields are included in this computation, regardless of
3494             field modifier (static, public, private, etc).
3495             <p/>
3496             For example, given the following classes and interfaces:
3497             <example>
3498 interface I0 {
3499     int p = 0;
3500 }
3501 
3502 interface I1 extends I0 {
3503     int x = 1;
3504 }
3505 
3506 interface I2 extends I0 {
3507     int y = 2;
3508 }
3509 
3510 class C1 implements I1 {
3511     public static int a = 3;
3512     private int b = 4;
3513 }
3514 
3515 class C2 extends C1 implements I2 {
3516     static int q = 5;
3517     final int r = 6;
3518 }
3519             </example>
3520             Assume that <functionlink id="GetClassFields"/> called on
3521             <code>C1</code> returns the fields of <code>C1</code> in the
3522             order: a, b; and that the fields of <code>C2</code> are 
3523             returned in the order: q, r.
3524             An instance of class <code>C1</code> will have the
3525             following field indices:
3526             <dl><dd><table>
3527               <tr>
3528                 <td>
3529                   a
3530                 </td>
3531                 <td>
3532                   2
3533                 </td>
3534                 <td align="left">
3535                   The count of the fields in the interfaces
3536                   implemented by <code>C1</code> is two (<i>n</i>=2):
3537                   <code>p</code> of <code>I0</code>
3538                   and <code>x</code> of <code>I1</code>.
3539                 </td>
3540               </tr>
3541               <tr>
3542                 <td>
3543                   b
3544                 </td>
3545                 <td>
3546                   3
3547                 </td>
3548                 <td align="left">
3549                   the subsequent index.
3550                 </td>
3551               </tr>
3552             </table></dd></dl>
3553             The class <code>C1</code> will have the same field indices.
3554             <p/>
3555             An instance of class <code>C2</code> will have the
3556             following field indices:
3557             <dl><dd><table>
3558               <tr>
3559                 <td>
3560                   a
3561                 </td>
3562                 <td>
3563                   3
3564                 </td>
3565                 <td align="left">
3566                   The count of the fields in the interfaces
3567                   implemented by <code>C2</code> is three (<i>n</i>=3):
3568                   <code>p</code> of <code>I0</code>,
3569                   <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> 
3570                   (an interface of <code>C2</code>).  Note that the field <code>p</code>
3571                   of <code>I0</code> is only included once.
3572                 </td>
3573               </tr>
3574               <tr>
3575                 <td>
3576                   b
3577                 </td>
3578                 <td>
3579                   4
3580                 </td>
3581                 <td align="left">
3582                   the subsequent index to "a".
3583                 </td>
3584               </tr>
3585               <tr>
3586                 <td>
3587                   q
3588                 </td>
3589                 <td>
3590                   5
3591                 </td>
3592                 <td align="left">
3593                   the subsequent index to "b".
3594                 </td>
3595               </tr>
3596               <tr>
3597                 <td>
3598                   r
3599                 </td>
3600                 <td>
3601                   6
3602                 </td>
3603                 <td align="left">
3604                   the subsequent index to "q".
3605                 </td>
3606               </tr>
3607             </table></dd></dl>
3608             The class <code>C2</code> will have the same field indices.
3609             Note that a field may have a different index depending on the
3610             object that is viewing it -- for example field "a" above.
3611             Note also: not all field indices may be visible from the 
3612             callbacks, but all indices are shown for illustrative purposes.
3613             <p/>
3614             The interface <code>I1</code> will have the
3615             following field indices:
3616             <dl><dd><table>
3617               <tr>
3618                 <td>
3619                   x
3620                 </td>
3621                 <td>
3622                   1
3623                 </td>
3624                 <td align="left">
3625                   The count of the fields in the superinterfaces
3626                   of <code>I1</code> is one (<i>n</i>=1):
3627                   <code>p</code> of <code>I0</code>.
3628                 </td>
3629               </tr>
3630             </table></dd></dl>
3631           </description>      
3632         </field>
3633       </typedef>
3634 
3635       <typedef id="jvmtiHeapReferenceInfoArray" 
3636                label="Reference information structure for Array references" 
3637                since="1.1">
3638         <description>
3639           Reference information returned for 
3640          <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3641         </description>
3642         <field id="index">
3643           <jint/>
3644           <description>       
3645             The array index.
3646           </description>
3647         </field>
3648       </typedef>
3649 
3650       <typedef id="jvmtiHeapReferenceInfoConstantPool" 
3651                label="Reference information structure for Constant Pool references" 
3652                since="1.1">
3653         <description>
3654           Reference information returned for 
3655           <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3656         </description>
3657         <field id="index">
3658           <jint/>
3659           <description>       
3660             The index into the constant pool of the class. See the description in 
3661       <vmspec chapter="4.4"/>.
3662           </description>
3663         </field>
3664       </typedef>
3665 
3666       <typedef id="jvmtiHeapReferenceInfoStackLocal" 
3667                label="Reference information structure for Local Variable references" 
3668                since="1.1">
3669         <description>
3670           Reference information returned for 
3671           <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3672         </description>
3673         <field id="thread_tag">
3674           <jlong/>
3675           <description>
3676             The tag of the thread corresponding to this stack, zero if not tagged.
3677           </description>
3678         </field>
3679         <field id="thread_id">
3680           <jlong/>
3681           <description>
3682             The unique thread ID of the thread corresponding to this stack.
3683           </description>
3684         </field>
3685         <field id="depth">
3686           <jint/>
3687           <description>
3688             The depth of the frame. 
3689           </description>
3690         </field>
3691         <field id="method">
3692           <jmethodID/>
3693           <description>
3694             The method executing in this frame.
3695           </description>
3696         </field>
3697         <field id="location">
3698           <jlocation/>
3699           <description>
3700             The currently executing location in this frame.
3701           </description>
3702         </field>
3703         <field id="slot">
3704           <jint/>
3705           <description>
3706             The slot number of the local variable.
3707           </description>
3708         </field>
3709       </typedef>
3710 
3711       <typedef id="jvmtiHeapReferenceInfoJniLocal" 
3712                label="Reference information structure for JNI local references" 
3713                since="1.1">
3714         <description>
3715           Reference information returned for 
3716           <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3717         </description>
3718         <field id="thread_tag">
3719           <jlong/>
3720           <description>
3721             The tag of the thread corresponding to this stack, zero if not tagged.
3722           </description>
3723         </field>
3724         <field id="thread_id">
3725           <jlong/>
3726           <description>
3727             The unique thread ID of the thread corresponding to this stack.
3728           </description>
3729         </field>
3730         <field id="depth">
3731           <jint/>
3732           <description>
3733             The depth of the frame. 
3734           </description>
3735         </field>
3736         <field id="method">
3737           <jmethodID/>
3738           <description>
3739             The method executing in this frame.
3740           </description>
3741         </field>
3742       </typedef>
3743 
3744       <typedef id="jvmtiHeapReferenceInfoReserved" 
3745                label="Reference information structure for Other references" 
3746                since="1.1">
3747         <description>
3748           Reference information returned for other references.
3749         </description>
3750         <field id="reserved1">
3751           <jlong/>
3752           <description>
3753             reserved for future use.
3754           </description>
3755         </field>
3756         <field id="reserved2">
3757           <jlong/>
3758           <description>
3759             reserved for future use.
3760           </description>
3761         </field>
3762         <field id="reserved3">
3763           <jlong/>
3764           <description>
3765             reserved for future use.
3766           </description>
3767         </field>
3768         <field id="reserved4">
3769           <jlong/>
3770           <description>
3771             reserved for future use.
3772           </description>
3773         </field>
3774         <field id="reserved5">
3775           <jlong/>
3776           <description>
3777             reserved for future use.
3778           </description>
3779         </field>
3780         <field id="reserved6">
3781           <jlong/>
3782           <description>
3783             reserved for future use.
3784           </description>
3785         </field>
3786         <field id="reserved7">
3787           <jlong/>
3788           <description>
3789             reserved for future use.
3790           </description>
3791         </field>
3792         <field id="reserved8">
3793           <jlong/>
3794           <description>
3795             reserved for future use.
3796           </description>
3797         </field>
3798       </typedef>
3799 
3800       <uniontypedef id="jvmtiHeapReferenceInfo" 
3801                label="Reference information structure" 
3802                since="1.1">
3803         <description>
3804           The information returned about referrers.
3805           Represented as a union of the various kinds of reference information.
3806         </description>
3807         <field id="field">
3808           <struct>jvmtiHeapReferenceInfoField</struct>
3809           <description>       
3810             The referrer information for 
3811             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> 
3812             and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3813           </description>
3814         </field>
3815         <field id="array">
3816           <struct>jvmtiHeapReferenceInfoArray</struct>
3817           <description>       
3818             The referrer information for 
3819             For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3820           </description>
3821         </field>
3822         <field id="constant_pool">
3823           <struct>jvmtiHeapReferenceInfoConstantPool</struct>
3824           <description>       
3825             The referrer information for 
3826             For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3827           </description>
3828         </field>
3829         <field id="stack_local">
3830           <struct>jvmtiHeapReferenceInfoStackLocal</struct>
3831           <description>       
3832             The referrer information for 
3833             For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3834           </description>
3835         </field>
3836         <field id="jni_local">
3837           <struct>jvmtiHeapReferenceInfoJniLocal</struct>
3838           <description>       
3839             The referrer information for 
3840             For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3841           </description>
3842         </field>
3843         <field id="other">
3844           <struct>jvmtiHeapReferenceInfoReserved</struct>
3845           <description>       
3846             reserved for future use.
3847           </description>
3848         </field>
3849       </uniontypedef>
3850 
3851       <typedef id="jvmtiHeapCallbacks" 
3852                label="Heap callback function structure" 
3853                since="1.1">
3854         <field id="heap_iteration_callback">
3855           <ptrtype>
3856             <struct>jvmtiHeapIterationCallback</struct>
3857           </ptrtype>
3858           <description>
3859             The callback to be called to describe an
3860             object in the heap. Used by the 
3861             <functionlink id="IterateThroughHeap"/> function, ignored by the
3862             <functionlink id="FollowReferences"/> function.
3863           </description>
3864         </field>            
3865         <field id="heap_reference_callback">
3866           <ptrtype>
3867             <struct>jvmtiHeapReferenceCallback</struct>
3868           </ptrtype>
3869           <description>
3870             The callback to be called to describe an
3871             object reference.  Used by the 
3872             <functionlink id="FollowReferences"/> function, ignored by the
3873             <functionlink id="IterateThroughHeap"/> function.
3874           </description>
3875         </field>            
3876         <field id="primitive_field_callback">
3877           <ptrtype>
3878             <struct>jvmtiPrimitiveFieldCallback</struct>
3879           </ptrtype>
3880           <description>
3881             The callback to be called to describe a
3882             primitive field.
3883           </description>
3884         </field>            
3885         <field id="array_primitive_value_callback">
3886           <ptrtype>
3887             <struct>jvmtiArrayPrimitiveValueCallback</struct>
3888           </ptrtype>
3889           <description>
3890             The callback to be called to describe an
3891             array of primitive values.
3892           </description>
3893         </field>            
3894         <field id="string_primitive_value_callback">
3895           <ptrtype>
3896             <struct>jvmtiStringPrimitiveValueCallback</struct>
3897           </ptrtype>
3898           <description>
3899             The callback to be called to describe a String value.
3900           </description>
3901         </field>            
3902         <field id="reserved5">
3903           <ptrtype>
3904             <struct>jvmtiReservedCallback</struct>
3905           </ptrtype>
3906           <description>
3907             Reserved for future use..
3908           </description>
3909         </field>            
3910         <field id="reserved6">
3911           <ptrtype>
3912             <struct>jvmtiReservedCallback</struct>
3913           </ptrtype>
3914           <description>
3915             Reserved for future use..
3916           </description>
3917         </field>            
3918         <field id="reserved7">
3919           <ptrtype>
3920             <struct>jvmtiReservedCallback</struct>
3921           </ptrtype>
3922           <description>
3923             Reserved for future use..
3924           </description>
3925         </field>            
3926         <field id="reserved8">
3927           <ptrtype>
3928             <struct>jvmtiReservedCallback</struct>
3929           </ptrtype>
3930           <description>
3931             Reserved for future use..
3932           </description>
3933         </field>            
3934         <field id="reserved9">
3935           <ptrtype>
3936             <struct>jvmtiReservedCallback</struct>
3937           </ptrtype>
3938           <description>
3939             Reserved for future use..
3940           </description>
3941         </field>            
3942         <field id="reserved10">
3943           <ptrtype>
3944             <struct>jvmtiReservedCallback</struct>
3945           </ptrtype>
3946           <description>
3947             Reserved for future use..
3948           </description>
3949         </field>            
3950         <field id="reserved11">
3951           <ptrtype>
3952             <struct>jvmtiReservedCallback</struct>
3953           </ptrtype>
3954           <description>
3955             Reserved for future use..
3956           </description>
3957         </field>            
3958         <field id="reserved12">
3959           <ptrtype>
3960             <struct>jvmtiReservedCallback</struct>
3961           </ptrtype>
3962           <description>
3963             Reserved for future use..
3964           </description>
3965         </field>            
3966         <field id="reserved13">
3967           <ptrtype>
3968             <struct>jvmtiReservedCallback</struct>
3969           </ptrtype>
3970           <description>
3971             Reserved for future use..
3972           </description>
3973         </field>            
3974         <field id="reserved14">
3975           <ptrtype>
3976             <struct>jvmtiReservedCallback</struct>
3977           </ptrtype>
3978           <description>
3979             Reserved for future use..
3980           </description>
3981         </field>            
3982         <field id="reserved15">
3983           <ptrtype>
3984             <struct>jvmtiReservedCallback</struct>
3985           </ptrtype>
3986           <description>
3987             Reserved for future use..
3988           </description>
3989         </field>            
3990       </typedef>
3991 
3992 
3993     <intro>
3994       <rationale>
3995         The heap dumping functionality (below) uses a callback
3996         for each object.  While it would seem that a buffered approach
3997         would provide better throughput, tests do
3998         not show this to be the case--possibly due to locality of
3999         memory reference or array access overhead.
4000       </rationale>
4001 
4002       <issue>
4003         Still under investigation as to if java.lang.ref references
4004         are reported as a different type of reference.
4005       </issue>
4006 
4007       <issue>
4008         Should or can an indication of the cost or relative cost of
4009         these operations be included?
4010       </issue>
4011 
4012     </intro>
4013 
4014     <callback id="jvmtiHeapIterationCallback" since="1.1">
4015       <jint/>
4016       <synopsis>Heap Iteration Callback</synopsis>
4017       <description>
4018         Agent supplied callback function.
4019         Describes (but does not pass in) an object in the heap.
4020         <p/>
4021         This function should return a bit vector of the desired
4022         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4023         This will determine if the entire iteration should be aborted
4024         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4025         <p/>
4026         See the <internallink id="heapCallbacks">heap callback
4027         function restrictions</internallink>.
4028       </description>
4029       <parameters>
4030         <param id="class_tag">
4031           <jlong/>
4032           <description>
4033             The tag of the class of object (zero if the class is not tagged). 
4034             If the object represents a runtime class, 
4035             the <code>class_tag</code> is the tag 
4036             associated with <code>java.lang.Class</code> 
4037             (zero if <code>java.lang.Class</code> is not tagged).
4038           </description>
4039         </param>
4040         <param id="size">
4041           <jlong/>
4042           <description>
4043             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
4044           </description>
4045         </param>
4046         <param id="tag_ptr">
4047           <outptr><jlong/></outptr>
4048           <description>
4049             The object tag value, or zero if the object is not tagged.
4050             To set the tag value to be associated with the object
4051             the agent sets the <code>jlong</code> pointed to by the parameter. 
4052           </description>
4053         </param>
4054         <param id="length">
4055           <jint/>
4056           <description>
4057             If this object is an array, the length of the array. Otherwise negative one (-1).
4058           </description>
4059         </param>
4060         <param id="user_data">
4061           <outptr><void/></outptr>
4062           <description>
4063             The user supplied data that was passed into the iteration function. 
4064           </description>
4065         </param>
4066       </parameters>
4067     </callback>  
4068 
4069     <callback id="jvmtiHeapReferenceCallback" since="1.1">
4070       <jint/>
4071       <synopsis>Heap Reference Callback</synopsis>
4072       <description>
4073         Agent supplied callback function.       
4074         Describes a reference from an object or the VM (the referrer) to another object
4075         (the referree) or a heap root to a referree.
4076         <p/>
4077         This function should return a bit vector of the desired
4078         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4079         This will determine if the objects referenced by the referree
4080         should be visited or if the entire iteration should be aborted.
4081         <p/>
4082         See the <internallink id="heapCallbacks">heap callback
4083         function restrictions</internallink>.
4084       </description>
4085       <parameters>
4086         <param id="reference_kind">
4087           <enum>jvmtiHeapReferenceKind</enum>
4088           <description>
4089             The kind of reference.
4090           </description>
4091         </param>
4092         <param id="reference_info">
4093           <inptr>
4094             <struct>jvmtiHeapReferenceInfo</struct>
4095           </inptr>
4096           <description>
4097             Details about the reference. 
4098             Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is
4099             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
4100             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
4101             <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
4102             <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, 
4103             <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
4104             or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
4105             Otherwise <code>NULL</code>.
4106           </description>
4107         </param>
4108         <param id="class_tag">
4109           <jlong/>
4110           <description>
4111             The tag of the class of referree object (zero if the class is not tagged). 
4112             If the referree object represents a runtime class, 
4113             the <code>class_tag</code> is the tag 
4114             associated with <code>java.lang.Class</code>
4115             (zero if <code>java.lang.Class</code> is not tagged).
4116           </description>
4117         </param>
4118         <param id="referrer_class_tag">
4119           <jlong/>
4120           <description>
4121             The tag of the class of the referrer object (zero if the class is not tagged
4122             or the referree is a heap root). If the referrer object represents a runtime
4123             class, the <code>referrer_class_tag</code> is the tag associated with
4124             the <code>java.lang.Class</code>
4125             (zero if <code>java.lang.Class</code> is not tagged).
4126           </description>
4127         </param>
4128         <param id="size">
4129           <jlong/>
4130           <description>
4131             Size of the referree object (in bytes). 
4132             See <functionlink id="GetObjectSize"/>.
4133           </description>
4134         </param>
4135         <param id="tag_ptr">
4136           <outptr><jlong/></outptr>
4137           <description>
4138             Points to the referree object tag value, or zero if the object is not 
4139             tagged.
4140             To set the tag value to be associated with the object
4141             the agent sets the <code>jlong</code> pointed to by the parameter.
4142           </description>
4143         </param>
4144         <param id="referrer_tag_ptr">
4145           <outptr><jlong/></outptr>
4146           <description>
4147             Points to the tag of the referrer object, or 
4148             points to the zero if the referrer
4149             object is not tagged. 
4150             <code>NULL</code> if the referrer in not an object (that is,
4151             this callback is reporting a heap root).
4152             To set the tag value to be associated with the referrer object
4153             the agent sets the <code>jlong</code> pointed to by the parameter.
4154             If this callback is reporting a reference from an object to itself, 
4155             <code>referrer_tag_ptr == tag_ptr</code>.
4156           </description>
4157         </param>
4158         <param id="length">
4159           <jint/>
4160           <description>
4161             If this object is an array, the length of the array. Otherwise negative one (-1).
4162           </description>
4163         </param>
4164         <param id="user_data">
4165           <outptr><void/></outptr>
4166           <description>
4167             The user supplied data that was passed into the iteration function. 
4168           </description>
4169         </param>
4170       </parameters>
4171     </callback>
4172 
4173     <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
4174       <jint/>
4175       <synopsis>Primitive Field Callback</synopsis>
4176       <description>
4177         Agent supplied callback function which  
4178         describes a primitive field of an object (<i>the object</i>).
4179         A primitive field is a field whose type is a primitive type.
4180         This callback will describe a static field if the object is a class,
4181         and otherwise will describe an instance field.
4182         <p/>
4183         This function should return a bit vector of the desired
4184         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4185         This will determine if the entire iteration should be aborted
4186         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4187         <p/>
4188         See the <internallink id="heapCallbacks">heap callback
4189         function restrictions</internallink>.
4190       </description>
4191       <parameters>
4192         <param id="kind">
4193           <enum>jvmtiHeapReferenceKind</enum>
4194           <description>
4195             The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or 
4196             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
4197           </description>
4198         </param>
4199         <param id="info">
4200           <inptr>
4201             <struct>jvmtiHeapReferenceInfo</struct>
4202           </inptr>
4203           <description>
4204             Which field (the field index).
4205           </description>
4206         </param>
4207         <param id="object_class_tag">
4208           <jlong/>
4209           <description>
4210             The tag of the class of the object (zero if the class is not tagged). 
4211             If the object represents a runtime class, the 
4212             <code>object_class_tag</code> is the tag 
4213             associated with <code>java.lang.Class</code> 
4214             (zero if <code>java.lang.Class</code> is not tagged).
4215           </description>
4216         </param>
4217         <param id="object_tag_ptr">
4218           <outptr><jlong/></outptr>
4219           <description>
4220             Points to the tag of the object, or zero if the object is not 
4221             tagged.
4222             To set the tag value to be associated with the object
4223             the agent sets the <code>jlong</code> pointed to by the parameter.
4224           </description>
4225         </param>
4226         <param id="value">
4227           <jvalue/>
4228           <description>
4229             The value of the field.
4230           </description>
4231         </param>
4232         <param id="value_type">
4233           <enum>jvmtiPrimitiveType</enum>
4234           <description>
4235             The type of the field.
4236           </description>
4237         </param>
4238         <param id="user_data">
4239           <outptr><void/></outptr>
4240           <description>
4241             The user supplied data that was passed into the iteration function. 
4242           </description>
4243         </param>
4244       </parameters>
4245     </callback>
4246 
4247     <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
4248       <jint/>
4249       <synopsis>Array Primitive Value Callback</synopsis>
4250       <description>
4251         Agent supplied callback function.       
4252         Describes the values in an array of a primitive type.
4253         <p/>
4254         This function should return a bit vector of the desired
4255         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4256         This will determine if the entire iteration should be aborted
4257         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4258         <p/>
4259         See the <internallink id="heapCallbacks">heap callback
4260         function restrictions</internallink>.
4261       </description>
4262       <parameters>
4263         <param id="class_tag">
4264           <jlong/>
4265           <description>
4266             The tag of the class of the array object (zero if the class is not tagged). 
4267           </description>
4268         </param>
4269         <param id="size">
4270           <jlong/>
4271           <description>
4272             Size of the array (in bytes). 
4273             See <functionlink id="GetObjectSize"/>.
4274           </description>
4275         </param>
4276         <param id="tag_ptr">
4277           <outptr><jlong/></outptr>
4278           <description>
4279             Points to the tag of the array object, or zero if the object is not 
4280             tagged.
4281             To set the tag value to be associated with the object
4282             the agent sets the <code>jlong</code> pointed to by the parameter.
4283           </description>
4284         </param>
4285         <param id="element_count">
4286           <jint/>
4287           <description>
4288             The length of the primitive array.
4289           </description>
4290         </param>
4291         <param id="element_type">
4292           <enum>jvmtiPrimitiveType</enum>
4293           <description>
4294             The type of the elements of the array.
4295           </description>
4296         </param>
4297         <param id="elements">
4298           <vmbuf><void/></vmbuf>
4299           <description>
4300             The elements of the array in a packed array of <code>element_count</code>
4301             items of <code>element_type</code> size each.
4302           </description>
4303         </param>
4304         <param id="user_data">
4305           <outptr><void/></outptr>
4306           <description>
4307             The user supplied data that was passed into the iteration function. 
4308           </description>
4309         </param>
4310       </parameters>
4311     </callback>
4312 
4313     <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
4314       <jint/>
4315       <synopsis>String Primitive Value Callback</synopsis>
4316       <description>
4317         Agent supplied callback function.       
4318         Describes the value of a java.lang.String.
4319         <p/>
4320         This function should return a bit vector of the desired
4321         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4322         This will determine if the entire iteration should be aborted
4323         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4324         <p/>
4325         See the <internallink id="heapCallbacks">heap callback
4326         function restrictions</internallink>.
4327       </description>
4328       <parameters>
4329         <param id="class_tag">
4330           <jlong/>
4331           <description>
4332             The tag of the class of the String class (zero if the class is not tagged). 
4333             <issue>Is this needed?</issue>
4334           </description>
4335         </param>
4336         <param id="size">
4337           <jlong/>
4338           <description>
4339             Size of the string (in bytes). 
4340             See <functionlink id="GetObjectSize"/>.
4341           </description>
4342         </param>
4343         <param id="tag_ptr">
4344           <outptr><jlong/></outptr>
4345           <description>
4346             Points to the tag of the String object, or zero if the object is not 
4347             tagged.
4348             To set the tag value to be associated with the object
4349             the agent sets the <code>jlong</code> pointed to by the parameter.
4350           </description>
4351         </param>
4352         <param id="value">
4353           <vmbuf><jchar/></vmbuf>
4354           <description>
4355             The value of the String, encoded as a Unicode string.
4356           </description>
4357         </param>
4358         <param id="value_length">
4359           <jint/>
4360           <description>
4361             The length of the string. 
4362             The length is equal to the number of 16-bit Unicode 
4363             characters in the string.
4364           </description>
4365         </param>
4366         <param id="user_data">
4367           <outptr><void/></outptr>
4368           <description>
4369             The user supplied data that was passed into the iteration function. 
4370           </description>
4371         </param>
4372       </parameters>
4373     </callback>
4374 
4375 
4376     <callback id="jvmtiReservedCallback" since="1.1">
4377       <jint/>
4378       <synopsis>reserved for future use Callback</synopsis>
4379       <description>
4380         Placeholder -- reserved for future use.
4381       </description>
4382       <parameters>
4383       </parameters>
4384     </callback>
4385 
4386     <function id="FollowReferences" num="115" since="1.1">
4387       <synopsis>Follow References</synopsis>
4388       <description>       
4389         This function initiates a traversal over the objects that are 
4390         directly and indirectly reachable from the specified object or,
4391         if <code>initial_object</code> is not specified, all objects 
4392         reachable from the heap roots.
4393         The heap root are the set of system classes, 
4394         JNI globals, references from thread stacks, and other objects used as roots 
4395         for the purposes of garbage collection. 
4396         <p/>
4397         This function operates by traversing the reference graph.
4398         Let <i>A</i>, <i>B</i>, ... represent objects.
4399         When a reference from <i>A</i> to <i>B</i> is traversed,
4400         when a reference from a heap root to <i>B</i> is traversed, 
4401         or when <i>B</i> is specified as the <paramlink id="initial_object"/>, 
4402         then <i>B</i> is said to be <i>visited</i>.
4403         A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> 
4404         is visited.
4405         References are reported in the same order that the references are traversed.
4406         Object references are reported by invoking the agent supplied  
4407         callback function <functionlink id="jvmtiHeapReferenceCallback"/>.
4408         In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known 
4409         as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
4410         The callback is invoked exactly once for each reference from a referrer;
4411         this is true even if there are reference cycles or multiple paths to
4412         the referrer.
4413         There may be more than one reference between a referrer and a referree,
4414         each reference is reported.
4415         These references may be distinguished by examining the
4416         <datalink 
4417          id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
4418          and
4419         <datalink 
4420          id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
4421         parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
4422         <p/>
4423         This function reports a Java programming language view of object references,
4424         not a virtual machine implementation view. The following object references
4425         are reported when they are non-null:
4426         <ul>
4427           <li>Instance objects report references to each non-primitive instance fields
4428               (including inherited fields).</li>
4429           <li>Instance objects report a reference to the object type (class).</li>
4430           <li>Classes report a reference to the superclass and directly
4431               implemented/extended interfaces.</li>
4432           <li>Classes report a reference to the class loader, protection domain,
4433               signers, and resolved entries in the constant pool.</li>
4434           <li>Classes report a reference to each directly declared non-primitive
4435               static field.</li>
4436           <li>Arrays report a reference to the array type (class) and each
4437               array element.</li>
4438           <li>Primitive arrays report a reference to the array type.</li>
4439         </ul>
4440         <p/>
4441         This function can also be used to examine primitive (non-object) values.
4442         The primitive value of an array or String
4443         is reported after the object has been visited;
4444         it is reported by invoking the agent supplied callback function
4445         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4446         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4447         A primitive field
4448         is reported after the object with that field is visited;
4449         it is reported by invoking the agent supplied callback function
4450         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4451         <p/>
4452         Whether a callback is provided or is <code>NULL</code> only determines
4453         whether the callback will be invoked, it does not influence
4454         which objects are visited nor does it influence whether other callbacks
4455         will be invoked.
4456         However, the 
4457         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
4458         returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4459         do determine if the objects referenced by the 
4460         current object as visited.
4461         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4462         and <paramlink id="klass"/> provided as parameters to this function
4463         do not control which objects are visited but they do control which
4464         objects and primitive values are reported by the callbacks.
4465         For example, if the only callback that was set is
4466         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4467         is set to the array of bytes class, then only arrays of byte will be
4468         reported.  
4469         The table below summarizes this:
4470         <p/>
4471         <table>
4472           <tr>
4473             <th/>
4474             <th>
4475               Controls objects visited
4476             </th>
4477             <th>
4478               Controls objects reported
4479             </th>
4480             <th>
4481               Controls primitives reported
4482             </th>
4483           </tr>
4484           <tr>
4485             <th align="left">
4486               the
4487               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4488               returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4489             </th>
4490             <td>
4491               <b>Yes</b>
4492             </td>
4493             <td>
4494               <b>Yes</b>, since visits are controlled
4495             </td>
4496             <td>
4497               <b>Yes</b>, since visits are controlled
4498             </td>
4499           </tr>
4500           <tr>
4501             <th align="left">
4502               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4503               in <paramlink id="callbacks"/> set
4504             </th>
4505             <td>
4506               No
4507             </td>
4508             <td>
4509               <b>Yes</b>
4510             </td>
4511             <td>
4512               No
4513             </td>
4514           </tr>
4515           <tr>
4516             <th align="left">
4517               <paramlink id="heap_filter"/>
4518             </th>
4519             <td>
4520               No
4521             </td>
4522             <td>
4523               <b>Yes</b>
4524             </td>
4525             <td>
4526               <b>Yes</b>
4527             </td>
4528           </tr>
4529           <tr>
4530             <th align="left">
4531               <paramlink id="klass"/>
4532             </th>
4533             <td>
4534               No
4535             </td>
4536             <td>
4537               <b>Yes</b>
4538             </td>
4539             <td>
4540               <b>Yes</b>
4541             </td>
4542           </tr>
4543         </table>
4544         <p/>
4545         During the execution of this function the state of the heap
4546         does not change: no objects are allocated, no objects are
4547         garbage collected, and the state of objects (including 
4548         held values) does not change. 
4549         As a result, threads executing Java 
4550         programming language code, threads attempting to resume the
4551         execution of Java programming language code, and threads 
4552         attempting to execute JNI functions are typically stalled.
4553       </description>
4554       <origin>new</origin>
4555       <capabilities>
4556         <required id="can_tag_objects"></required>
4557       </capabilities>
4558       <parameters>             
4559         <param id="heap_filter">
4560           <jint/>
4561           <description>
4562             This bit vector of 
4563             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4564             restricts the objects for which the callback function is called.
4565             This applies to both the object and primitive callbacks.
4566           </description>
4567         </param>
4568         <param id="klass">
4569           <ptrtype>
4570             <jclass/>
4571             <nullok>callbacks are not limited to instances of a particular
4572                     class</nullok>
4573           </ptrtype>
4574           <description>
4575             Callbacks are only reported when the object is an instance of 
4576             this class.
4577             Objects which are instances of a subclass of <code>klass</code>
4578             are not reported.
4579             If <code>klass</code> is an interface, no objects are reported.
4580             This applies to both the object and primitive callbacks.
4581           </description>
4582         </param>
4583         <param id="initial_object">
4584           <ptrtype>
4585             <jobject/>
4586             <nullok>references are followed from the heap roots</nullok>
4587           </ptrtype>
4588           <description>
4589             The object to follow
4590           </description>
4591         </param>
4592         <param id="callbacks">
4593           <inptr>
4594             <struct>jvmtiHeapCallbacks</struct>
4595           </inptr>
4596           <description>
4597             Structure defining the set of callback functions.
4598           </description>
4599         </param>                  
4600         <param id="user_data">
4601           <inbuf>
4602             <void/>
4603             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4604           </inbuf>
4605           <description>
4606             User supplied data to be passed to the callback. 
4607           </description>
4608         </param>
4609       </parameters>
4610       <errors>
4611         <error id="JVMTI_ERROR_INVALID_CLASS">
4612           <paramlink id="klass"/> is not a valid class.
4613         </error>
4614         <error id="JVMTI_ERROR_INVALID_OBJECT">
4615           <paramlink id="initial_object"/> is not a valid object.
4616         </error>
4617       </errors>
4618     </function>
4619 
4620 
4621     <function id="IterateThroughHeap" num="116" since="1.1">
4622       <synopsis>Iterate Through Heap</synopsis>
4623       <description>        
4624         Initiate an iteration over all objects in the heap. 
4625         This includes both reachable and 
4626         unreachable objects. Objects are visited in no particular order.
4627         <p/>
4628         Heap objects are reported by invoking the agent supplied 
4629         callback function <functionlink id="jvmtiHeapIterationCallback"/>.
4630         References between objects are not reported.
4631         If only reachable objects are desired, or if object reference information
4632         is needed, use <functionlink id="FollowReferences"/>.
4633         <p/>
4634         This function can also be used to examine primitive (non-object) values.
4635         The primitive value of an array or String
4636         is reported after the object has been visited;
4637         it is reported by invoking the agent supplied callback function
4638         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4639         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4640         A primitive field
4641         is reported after the object with that field is visited;
4642         it is reported by invoking the agent supplied 
4643         callback function
4644         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4645         <p/>
4646         Unless the iteration is aborted by the
4647         <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4648         returned by a callback, all objects in the heap are visited.
4649         Whether a callback is provided or is <code>NULL</code> only determines
4650         whether the callback will be invoked, it does not influence
4651         which objects are visited nor does it influence whether other callbacks
4652         will be invoked.
4653         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4654         and <paramlink id="klass"/> provided as parameters to this function
4655         do not control which objects are visited but they do control which
4656         objects and primitive values are reported by the callbacks.
4657         For example, if the only callback that was set is
4658         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4659         is set to the array of bytes class, then only arrays of byte will be
4660         reported. The table below summarizes this (contrast this with 
4661         <functionlink id="FollowReferences"/>):
4662         <p/>
4663         <table>
4664           <tr>
4665             <th/>
4666             <th>
4667               Controls objects visited
4668             </th>
4669             <th>
4670               Controls objects reported
4671             </th>
4672             <th>
4673               Controls primitives reported
4674             </th>
4675           </tr>
4676           <tr>
4677             <th align="left">
4678               the
4679               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4680               returned by <functionlink id="jvmtiHeapIterationCallback"/>
4681             </th>
4682             <td>
4683               No<br/>(unless they abort the iteration)
4684             </td>
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           </tr>
4692           <tr>
4693             <th align="left">
4694               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4695               in <paramlink id="callbacks"/> set
4696             </th>
4697             <td>
4698               No
4699             </td>
4700             <td>
4701               <b>Yes</b>
4702             </td>
4703             <td>
4704               No
4705             </td>
4706           </tr>
4707           <tr>
4708             <th align="left">
4709               <paramlink id="heap_filter"/>
4710             </th>
4711             <td>
4712               No
4713             </td>
4714             <td>
4715               <b>Yes</b>
4716             </td>
4717             <td>
4718               <b>Yes</b>
4719             </td>
4720           </tr>
4721           <tr>
4722             <th align="left">
4723               <paramlink id="klass"/>
4724             </th>
4725             <td>
4726               No
4727             </td>
4728             <td>
4729               <b>Yes</b>
4730             </td>
4731             <td>
4732               <b>Yes</b>
4733             </td>
4734           </tr>
4735         </table>
4736         <p/>
4737         During the execution of this function the state of the heap
4738         does not change: no objects are allocated, no objects are
4739         garbage collected, and the state of objects (including 
4740         held values) does not change. 
4741         As a result, threads executing Java 
4742         programming language code, threads attempting to resume the
4743         execution of Java programming language code, and threads 
4744         attempting to execute JNI functions are typically stalled.
4745       </description>
4746       <origin>new</origin>
4747       <capabilities>
4748         <required id="can_tag_objects"></required>
4749       </capabilities>
4750       <parameters>
4751         <param id="heap_filter">
4752           <jint/>
4753           <description>
4754             This bit vector of 
4755             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4756             restricts the objects for which the callback function is called.
4757             This applies to both the object and primitive callbacks.
4758           </description>
4759         </param>
4760         <param id="klass">
4761           <ptrtype>
4762             <jclass/>
4763             <nullok>callbacks are not limited to instances of a particular class</nullok>
4764           </ptrtype>
4765           <description>
4766             Callbacks are only reported when the object is an instance of 
4767             this class.
4768             Objects which are instances of a subclass of <code>klass</code>
4769             are not reported.
4770             If <code>klass</code> is an interface, no objects are reported.
4771             This applies to both the object and primitive callbacks.
4772           </description>
4773         </param>
4774         <param id="callbacks">
4775           <inptr>
4776             <struct>jvmtiHeapCallbacks</struct>
4777           </inptr>
4778           <description>
4779             Structure defining the set callback functions.
4780           </description>
4781         </param>                  
4782         <param id="user_data">
4783           <inbuf>
4784             <void/>
4785             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4786           </inbuf>
4787           <description>
4788             User supplied data to be passed to the callback. 
4789           </description>
4790         </param>
4791       </parameters>
4792       <errors>
4793         <error id="JVMTI_ERROR_INVALID_CLASS">
4794           <paramlink id="klass"/> is not a valid class.
4795         </error>
4796       </errors>
4797     </function>
4798 
4799     <function id="GetTag" phase="start" num="106">
4800       <synopsis>Get Tag</synopsis>
4801       <description>
4802         Retrieve the tag associated with an object.
4803         The tag is a long value typically used to store a 
4804         unique identifier or pointer to object information.
4805         The tag is set with
4806         <functionlink id="SetTag"></functionlink>.
4807         Objects for which no tags have been set return a
4808         tag value of zero.
4809       </description>
4810       <origin>new</origin>
4811       <capabilities>
4812         <required id="can_tag_objects"></required>
4813       </capabilities>
4814       <parameters>
4815         <param id="object">
4816           <jobject/>
4817             <description>
4818               The object whose tag is to be retrieved.
4819             </description>
4820         </param>
4821         <param id="tag_ptr">
4822           <outptr><jlong/></outptr>
4823           <description>
4824             On return, the referenced long is set to the value 
4825             of the tag.
4826           </description>
4827         </param>
4828       </parameters>
4829       <errors>
4830       </errors>
4831     </function>
4832 
4833     <function id="SetTag" phase="start" num="107">
4834       <synopsis>Set Tag</synopsis>
4835       <description>
4836         Set the tag associated with an object.
4837         The tag is a long value typically used to store a 
4838         unique identifier or pointer to object information.
4839         The tag is visible with
4840         <functionlink id="GetTag"></functionlink>.
4841       </description>
4842       <origin>new</origin>
4843       <capabilities>
4844         <required id="can_tag_objects"></required>
4845       </capabilities>
4846       <parameters>
4847         <param id="object">
4848           <jobject/>
4849             <description>
4850               The object whose tag is to be set.
4851             </description>
4852         </param>
4853         <param id="tag">
4854           <jlong/>
4855           <description>
4856             The new value of the tag.
4857           </description>
4858         </param>
4859       </parameters>
4860       <errors>
4861       </errors>
4862     </function>
4863 
4864     <function id="GetObjectsWithTags" num="114">
4865       <synopsis>Get Objects With Tags</synopsis>
4866       <description>
4867         Return objects in the heap with the specified tags.
4868         The format is parallel arrays of objects and tags.
4869       </description>
4870       <origin>new</origin>
4871       <capabilities>
4872         <required id="can_tag_objects"></required>
4873       </capabilities>
4874       <parameters>
4875         <param id="tag_count">
4876           <jint min="0"/>
4877             <description>
4878               Number of tags to scan for.
4879             </description>
4880         </param>
4881         <param id="tags">
4882           <inbuf incount="tag_count">
4883             <jlong/>
4884           </inbuf>
4885             <description>
4886               Scan for objects with these tags.
4887               Zero is not permitted in this array.
4888             </description>
4889         </param>
4890         <param id="count_ptr">
4891           <outptr>
4892             <jint/>
4893           </outptr>
4894             <description>
4895               Return the number of objects with any of the tags 
4896               in <paramlink id="tags"/>.
4897             </description>
4898         </param>
4899         <param id="object_result_ptr">
4900           <allocbuf outcount="count_ptr">
4901             <jobject/>
4902             <nullok>this information is not returned</nullok>
4903           </allocbuf>
4904             <description>
4905               Returns the array of objects with any of the tags 
4906               in <paramlink id="tags"/>.
4907             </description>
4908         </param>
4909         <param id="tag_result_ptr">
4910           <allocbuf outcount="count_ptr">
4911             <jlong/>
4912             <nullok>this information is not returned</nullok>
4913           </allocbuf>
4914             <description>
4915               For each object in <paramlink id="object_result_ptr"/>,
4916               return the tag at the corresponding index.
4917             </description>
4918         </param>
4919       </parameters>
4920       <errors>
4921         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
4922           Zero is present in <paramlink id="tags"></paramlink>.
4923         </error>
4924       </errors>
4925     </function>
4926 
4927     <function id="ForceGarbageCollection" num="108">
4928       <synopsis>Force Garbage Collection</synopsis>
4929       <description>
4930         Force the VM to perform a garbage collection.
4931         The garbage collection is as complete as possible.
4932         This function does not cause finalizers to be run.
4933         This function does not return until the garbage collection
4934         is finished.
4935         <p/>
4936         Although garbage collection is as complete 
4937         as possible there is no guarantee that all 
4938         <eventlink id="ObjectFree"/>
4939         events will have been 
4940         sent by the time that this function 
4941         returns. In particular, an object may be 
4942         prevented from being freed because it 
4943         is awaiting finalization.
4944       </description>
4945       <origin>new</origin>
4946       <capabilities>
4947       </capabilities>
4948       <parameters>
4949       </parameters>
4950       <errors>
4951       </errors>
4952     </function>
4953 
4954 
4955   </category>
4956 
4957   <category id="Heap_1_0" label="Heap (1.0)">
4958     <intro>
4959       <b>
4960         These functions and data types were introduced in the original 
4961         <jvmti/> version 1.0 and have been superseded by more
4962       </b>
4963       <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
4964       <b>
4965         which:
4966       </b>
4967       <ul>
4968         <li>
4969           <b>
4970             Allow access to primitive values (the value of Strings, arrays, 
4971             and primitive fields)
4972           </b>
4973         </li>
4974         <li>
4975           <b>
4976             Allow the tag of the referrer to be set, thus enabling more
4977             efficient localized reference graph building
4978           </b>
4979         </li>
4980         <li>
4981           <b>
4982             Provide more extensive filtering abilities
4983           </b>
4984         </li>
4985         <li>
4986           <b>
4987             Are extensible, allowing their abilities to grow in future versions of <jvmti/>
4988           </b>
4989         </li>
4990       </ul>
4991       <p/>
4992       <b>Please use the </b>
4993       <internallink id="Heap"><b>current Heap functions</b></internallink>.
4994         <p/>
4995         <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
4996           <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
4997             Tagged objects only.
4998           </constant>
4999           <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
5000             Untagged objects only.
5001           </constant>
5002           <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
5003             Either tagged or untagged objects.
5004           </constant>
5005         </constants>
5006 
5007         <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
5008           <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
5009             JNI global reference.
5010           </constant>
5011           <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
5012             System class.
5013           </constant>
5014           <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
5015             Monitor.
5016           </constant>
5017           <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
5018             Stack local.
5019           </constant>
5020           <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
5021             JNI local reference.
5022           </constant>
5023           <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
5024             Thread.
5025           </constant>
5026           <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
5027             Other.
5028           </constant>
5029         </constants>
5030 
5031         <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
5032           <constant id="JVMTI_REFERENCE_CLASS" num="1">
5033             Reference from an object to its class.
5034           </constant>       
5035           <constant id="JVMTI_REFERENCE_FIELD" num="2">
5036             Reference from an object to the value of one of its instance fields.
5037             For references of this kind the <code>referrer_index</code>
5038             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5039             jvmtiObjectReferenceCallback</internallink> is the index of the
5040             the instance field. The index is based on the order of all the 
5041             object's fields. This includes all fields of the directly declared
5042             static and instance fields in the class, and includes all fields (both
5043             public and private) fields declared in superclasses and superinterfaces.
5044             The index is thus calculated by summing the index of the field in the directly
5045             declared class (see <functionlink id="GetClassFields"/>), with the total
5046             number of fields (both public and private) declared in all superclasses
5047             and superinterfaces. The index starts at zero.
5048           </constant>
5049           <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
5050             Reference from an array to one of its elements.
5051             For references of this kind the <code>referrer_index</code>
5052             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5053             jvmtiObjectReferenceCallback</internallink> is the array index.
5054           </constant>
5055           <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
5056             Reference from a class to its class loader.
5057           </constant>
5058           <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
5059             Reference from a class to its signers array.
5060           </constant>
5061           <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
5062             Reference from a class to its protection domain.
5063           </constant>       
5064           <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
5065             Reference from a class to one of its interfaces.
5066           </constant>
5067           <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
5068             Reference from a class to the value of one of its static fields.
5069             For references of this kind the <code>referrer_index</code>
5070             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5071             jvmtiObjectReferenceCallback</internallink> is the index of the
5072             the static field. The index is based on the order of all the 
5073             object's fields. This includes all fields of the directly declared
5074             static and instance fields in the class, and includes all fields (both
5075             public and private) fields declared in superclasses and superinterfaces.
5076             The index is thus calculated by summing the index of the field in the directly
5077             declared class (see <functionlink id="GetClassFields"/>), with the total
5078             number of fields (both public and private) declared in all superclasses
5079             and superinterfaces. The index starts at zero.
5080             Note: this definition differs from that in the <jvmti/> 1.0 Specification.
5081             <rationale>No known implementations used the 1.0 definition.</rationale>
5082           </constant>
5083           <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
5084             Reference from a class to a resolved entry in the constant pool.
5085             For references of this kind the <code>referrer_index</code>
5086             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5087             jvmtiObjectReferenceCallback</internallink> is the index into
5088             constant pool table of the class, starting at 1. See
5089             <vmspec chapter="4.4"/>.
5090           </constant>
5091         </constants>
5092 
5093         <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
5094           <constant id="JVMTI_ITERATION_CONTINUE" num="1">
5095             Continue the iteration.  
5096             If this is a reference iteration, follow the references of this object.
5097           </constant>       
5098           <constant id="JVMTI_ITERATION_IGNORE" num="2">
5099             Continue the iteration.  
5100             If this is a reference iteration, ignore the references of this object.
5101           </constant>
5102           <constant id="JVMTI_ITERATION_ABORT" num="0">
5103             Abort the iteration.
5104           </constant>
5105         </constants>
5106     </intro>
5107 
5108     <callback id="jvmtiHeapObjectCallback">
5109       <enum>jvmtiIterationControl</enum>
5110       <synopsis>Heap Object Callback</synopsis>
5111       <description>
5112         Agent supplied callback function.
5113         Describes (but does not pass in) an object in the heap.
5114         <p/>
5115         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5116         or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5117         <p/>
5118         See the <internallink id="heapCallbacks">heap callback
5119         function restrictions</internallink>.
5120       </description>
5121       <parameters>
5122         <param id="class_tag">
5123           <jlong/>
5124           <description>
5125             The tag of the class of object (zero if the class is not tagged). 
5126             If the object represents a runtime class, 
5127             the <code>class_tag</code> is the tag 
5128             associated with <code>java.lang.Class</code>
5129             (zero if <code>java.lang.Class</code> is not tagged).
5130           </description>
5131         </param>
5132         <param id="size">
5133           <jlong/>
5134           <description>
5135             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5136           </description>
5137         </param>
5138         <param id="tag_ptr">
5139           <outptr><jlong/></outptr>
5140           <description>
5141             The object tag value, or zero if the object is not tagged.
5142             To set the tag value to be associated with the object
5143             the agent sets the <code>jlong</code> pointed to by the parameter. 
5144           </description>
5145         </param>
5146         <param id="user_data">
5147           <outptr><void/></outptr>
5148           <description>
5149             The user supplied data that was passed into the iteration function. 
5150           </description>
5151         </param>
5152       </parameters>
5153     </callback>  
5154 
5155     <callback id="jvmtiHeapRootCallback">
5156       <enum>jvmtiIterationControl</enum>
5157       <synopsis>Heap Root Object Callback</synopsis>
5158       <description>
5159         Agent supplied callback function.
5160         Describes (but does not pass in) an object that is a root for the purposes
5161         of garbage collection.
5162         <p/>
5163         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5164         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5165         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5166         <p/>
5167         See the <internallink id="heapCallbacks">heap callback
5168         function restrictions</internallink>.
5169       </description>
5170       <parameters>
5171         <param id="root_kind">
5172           <enum>jvmtiHeapRootKind</enum>
5173           <description>
5174             The kind of heap root.
5175           </description>
5176         </param>
5177         <param id="class_tag">
5178           <jlong/>
5179           <description>
5180             The tag of the class of object (zero if the class is not tagged). 
5181             If the object represents a runtime class, the <code>class_tag</code> is the tag 
5182             associated with <code>java.lang.Class</code> 
5183             (zero if <code>java.lang.Class</code> is not tagged).
5184           </description>
5185         </param>
5186         <param id="size">
5187           <jlong/>
5188           <description>
5189             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5190           </description>
5191         </param>
5192         <param id="tag_ptr">
5193           <outptr><jlong/></outptr>
5194           <description>
5195             The object tag value, or zero if the object is not tagged.
5196             To set the tag value to be associated with the object
5197             the agent sets the <code>jlong</code> pointed to by the parameter.
5198           </description>
5199         </param>
5200         <param id="user_data">
5201           <outptr><void/></outptr>
5202           <description>
5203             The user supplied data that was passed into the iteration function. 
5204           </description>
5205         </param>
5206       </parameters>
5207     </callback> 
5208 
5209     <callback id="jvmtiStackReferenceCallback">
5210       <enum>jvmtiIterationControl</enum>
5211       <synopsis>Stack Reference Object Callback</synopsis>
5212       <description>
5213         Agent supplied callback function.
5214         Describes (but does not pass in) an object on the stack that is a root for 
5215         the purposes of garbage collection.
5216         <p/>
5217         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5218         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5219         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5220         <p/>
5221         See the <internallink id="heapCallbacks">heap callback
5222         function restrictions</internallink>.
5223       </description>
5224       <parameters>
5225         <param id="root_kind">
5226           <enum>jvmtiHeapRootKind</enum>
5227           <description>
5228             The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5229             <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
5230           </description>
5231         </param>
5232         <param id="class_tag">
5233           <jlong/>
5234           <description>
5235            The tag of the class of object (zero if the class is not tagged). 
5236            If the object represents a runtime class, the  <code>class_tag</code> is the tag 
5237            associated with <code>java.lang.Class</code> 
5238            (zero if <code>java.lang.Class</code> is not tagged).
5239           </description>
5240         </param>
5241         <param id="size">
5242           <jlong/>
5243           <description>
5244             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5245           </description>
5246         </param>
5247         <param id="tag_ptr">
5248           <outptr><jlong/></outptr>
5249           <description>
5250             The object tag value, or zero if the object is not tagged.
5251             To set the tag value to be associated with the object
5252             the agent sets the <code>jlong</code> pointed to by the parameter.
5253           </description>
5254         </param>
5255         <param id="thread_tag">
5256           <jlong/>
5257           <description>
5258             The tag of the thread corresponding to this stack, zero if not tagged.
5259           </description>
5260         </param>
5261         <param id="depth">
5262           <jint/>
5263           <description>
5264             The depth of the frame. 
5265           </description>
5266         </param>
5267         <param id="method">
5268           <jmethodID/>
5269           <description>
5270             The method executing in this frame.
5271           </description>
5272         </param>
5273         <param id="slot">
5274           <jint/>
5275           <description>
5276             The slot number.
5277           </description>
5278         </param>
5279         <param id="user_data">
5280           <outptr><void/></outptr>
5281           <description>
5282             The user supplied data that was passed into the iteration function. 
5283           </description>
5284         </param>
5285       </parameters>
5286     </callback>
5287 
5288     <callback id="jvmtiObjectReferenceCallback">
5289       <enum>jvmtiIterationControl</enum>
5290       <synopsis>Object Reference Callback</synopsis>
5291       <description>
5292         Agent supplied callback function.       
5293         Describes a reference from an object (the referrer) to another object
5294         (the referree).
5295         <p/>
5296         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5297         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5298         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5299         <p/>
5300         See the <internallink id="heapCallbacks">heap callback
5301         function restrictions</internallink>.
5302       </description>
5303       <parameters>
5304         <param id="reference_kind">
5305           <enum>jvmtiObjectReferenceKind</enum>
5306           <description>
5307             The type of reference.
5308           </description>
5309         </param>
5310         <param id="class_tag">
5311           <jlong/>
5312           <description>
5313             The tag of the class of referree object (zero if the class is not tagged). 
5314             If the referree object represents a runtime class,
5315             the  <code>class_tag</code> is the tag 
5316             associated with <code>java.lang.Class</code> 
5317             (zero if <code>java.lang.Class</code> is not tagged).
5318           </description>
5319         </param>
5320         <param id="size">
5321           <jlong/>
5322           <description>
5323             Size of the referree object (in bytes). 
5324             See <functionlink id="GetObjectSize"/>.
5325           </description>
5326         </param>
5327         <param id="tag_ptr">
5328           <outptr><jlong/></outptr>
5329           <description>
5330             The referree object tag value, or zero if the object is not 
5331             tagged.
5332             To set the tag value to be associated with the object
5333             the agent sets the <code>jlong</code> pointed to by the parameter.
5334           </description>
5335         </param>
5336         <param id="referrer_tag">
5337           <jlong/>
5338           <description>
5339             The tag of the referrer object, or zero if the referrer
5340             object is not tagged.
5341           </description>
5342         </param>
5343         <param id="referrer_index">
5344           <jint/>
5345           <description>       
5346             For references of type <code>JVMTI_REFERENCE_FIELD</code> or
5347             <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
5348             of the field in the referrer object. The index is based on the 
5349             order of all the object's fields - see <internallink 
5350             id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
5351             or <internallink
5352             id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
5353             </internallink> for further description.
5354             <p/>
5355             For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
5356             the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
5357             JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
5358             <p/>
5359             For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
5360             the index into the constant pool of the class - see
5361             <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
5362             JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further 
5363             description.
5364             <p/>
5365             For references of other kinds the <code>referrer_index</code> is
5366             <code>-1</code>.
5367           </description>
5368         </param>
5369         <param id="user_data">
5370           <outptr><void/></outptr>
5371           <description>
5372             The user supplied data that was passed into the iteration function. 
5373           </description>
5374         </param>
5375       </parameters>
5376     </callback>
5377 
5378     <function id="IterateOverObjectsReachableFromObject" num="109">
5379       <synopsis>Iterate Over Objects Reachable From Object</synopsis>
5380       <description>       
5381         This function iterates over all objects that are directly
5382         and indirectly reachable from the specified object.
5383         For each object <i>A</i> (known
5384         as the referrer) with a reference to object <i>B</i> the specified 
5385         callback function is called to describe the object reference.
5386         The callback is called exactly once for each reference from a referrer;
5387         this is true even if there are reference cycles or multiple paths to
5388         the referrer.
5389         There may be more than one reference between a referrer and a referree,
5390         These may be distinguished by the 
5391         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5392         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5393         The callback for an object will always occur after the callback for
5394         its referrer.
5395         <p/>
5396         See <functionlink id="FollowReferences"/> for the object
5397         references which are reported.
5398         <p/>
5399         During the execution of this function the state of the heap
5400         does not change: no objects are allocated, no objects are
5401         garbage collected, and the state of objects (including 
5402         held values) does not change. 
5403         As a result, threads executing Java 
5404         programming language code, threads attempting to resume the
5405         execution of Java programming language code, and threads 
5406         attempting to execute JNI functions are typically stalled.
5407       </description>
5408       <origin>new</origin>
5409       <capabilities>
5410         <required id="can_tag_objects"></required>
5411       </capabilities>
5412       <parameters>             
5413         <param id="object">
5414           <jobject/>
5415             <description>
5416               The object
5417             </description>
5418         </param>
5419         <param id="object_reference_callback">
5420           <ptrtype>
5421             <struct>jvmtiObjectReferenceCallback</struct>
5422           </ptrtype>
5423             <description>
5424               The callback to be called to describe each
5425               object reference.
5426             </description>
5427         </param>            
5428         <param id="user_data">
5429           <inbuf>
5430             <void/>
5431             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5432           </inbuf>
5433           <description>
5434             User supplied data to be passed to the callback. 
5435           </description>
5436         </param>
5437       </parameters>
5438       <errors>
5439       </errors>
5440     </function>
5441 
5442     <function id="IterateOverReachableObjects" num="110">
5443       <synopsis>Iterate Over Reachable Objects</synopsis>
5444       <description>
5445         This function iterates over the root objects and all objects that
5446         are directly and indirectly reachable from the root objects.
5447         The root objects comprise the set of system classes, 
5448         JNI globals, references from thread stacks, and other objects used as roots 
5449         for the purposes of garbage collection. 
5450         <p/>
5451         For each root the <paramlink id="heap_root_callback"></paramlink>
5452         or <paramlink id="stack_ref_callback"></paramlink> callback is called.
5453         An object can be a root object for more than one reason and in that case
5454         the appropriate callback is called for each reason.
5455         <p/>
5456         For each object reference the <paramlink id="object_ref_callback"></paramlink>
5457         callback function is called to describe the object reference.
5458         The callback is called exactly once for each reference from a referrer;
5459         this is true even if there are reference cycles or multiple paths to
5460         the referrer.
5461         There may be more than one reference between a referrer and a referree,
5462         These may be distinguished by the 
5463         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5464         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5465         The callback for an object will always occur after the callback for
5466         its referrer.
5467         <p/>
5468         See <functionlink id="FollowReferences"/> for the object
5469         references which are reported.
5470         <p/>
5471         Roots are always reported to the profiler before any object references
5472         are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> 
5473         callback will not be called until the appropriate callback has been called
5474         for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is 
5475         specified as <code>NULL</code> then this function returns after
5476         reporting the root objects to the profiler.
5477         <p/>
5478         During the execution of this function the state of the heap
5479         does not change: no objects are allocated, no objects are
5480         garbage collected, and the state of objects (including 
5481         held values) does not change. 
5482         As a result, threads executing Java 
5483         programming language code, threads attempting to resume the
5484         execution of Java programming language code, and threads 
5485         attempting to execute JNI functions are typically stalled.
5486       </description>
5487       <origin>new</origin>
5488       <capabilities>
5489         <required id="can_tag_objects"></required>
5490       </capabilities>
5491       <parameters>        
5492         <param id="heap_root_callback">
5493           <ptrtype>
5494             <struct>jvmtiHeapRootCallback</struct>
5495             <nullok>do not report heap roots</nullok>
5496           </ptrtype>
5497             <description>
5498               The callback function to be called for each heap root of type
5499               <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
5500               <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
5501               <code>JVMTI_HEAP_ROOT_MONITOR</code>,
5502               <code>JVMTI_HEAP_ROOT_THREAD</code>, or 
5503               <code>JVMTI_HEAP_ROOT_OTHER</code>.
5504             </description>
5505         </param>
5506         <param id="stack_ref_callback">
5507           <ptrtype>
5508             <struct>jvmtiStackReferenceCallback</struct>
5509             <nullok>do not report stack references</nullok>
5510           </ptrtype>
5511             <description>
5512               The callback function to be called for each heap root of
5513               <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5514               <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
5515             </description>
5516         </param>
5517         <param id="object_ref_callback">
5518           <ptrtype>
5519             <struct>jvmtiObjectReferenceCallback</struct>
5520             <nullok>do not follow references from the root objects</nullok>
5521           </ptrtype>
5522             <description>
5523               The callback function to be called for each object reference.
5524             </description>
5525         </param>
5526         <param id="user_data">
5527           <inbuf>
5528             <void/>
5529             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5530           </inbuf>
5531           <description>
5532             User supplied data to be passed to the callback. 
5533           </description>
5534         </param>
5535       </parameters>
5536       <errors>
5537       </errors>
5538     </function>
5539 
5540     <function id="IterateOverHeap" num="111">
5541       <synopsis>Iterate Over Heap</synopsis>
5542       <description>        
5543         Iterate over all objects in the heap. This includes both reachable and 
5544         unreachable objects.
5545         <p/>
5546         The <paramlink id="object_filter"></paramlink> parameter indicates the
5547         objects for which the callback function is called. If this parameter
5548         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 
5549         called for every object that is tagged. If the parameter is 
5550         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5551         for objects that are not tagged. If the parameter
5552         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5553         called for every object in the heap, irrespective of whether it is
5554         tagged or not.
5555         <p/>
5556         During the execution of this function the state of the heap
5557         does not change: no objects are allocated, no objects are
5558         garbage collected, and the state of objects (including 
5559         held values) does not change. 
5560         As a result, threads executing Java 
5561         programming language code, threads attempting to resume the
5562         execution of Java programming language code, and threads 
5563         attempting to execute JNI functions are typically stalled.
5564       </description>
5565       <origin>new</origin>
5566       <capabilities>
5567         <required id="can_tag_objects"></required>
5568       </capabilities>
5569       <parameters>
5570         <param id="object_filter">
5571           <enum>jvmtiHeapObjectFilter</enum>
5572           <description>
5573             Indicates the objects for which the callback function is called.
5574           </description>
5575         </param>
5576         <param id="heap_object_callback">
5577           <ptrtype>
5578             <struct>jvmtiHeapObjectCallback</struct>
5579           </ptrtype>
5580             <description>
5581               The iterator function to be called for each
5582               object matching the <paramlink id="object_filter"/>.
5583             </description>
5584         </param>
5585         <param id="user_data">
5586           <inbuf>
5587             <void/>
5588             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5589           </inbuf>
5590           <description>
5591             User supplied data to be passed to the callback. 
5592           </description>
5593         </param>
5594       </parameters>
5595       <errors>
5596       </errors>
5597     </function>
5598 
5599     <function id="IterateOverInstancesOfClass" num="112">
5600       <synopsis>Iterate Over Instances Of Class</synopsis>
5601       <description>
5602         Iterate over all objects in the heap that are instances of the specified class. 
5603         This includes direct instances of the specified class and 
5604         instances of all subclasses of the specified class.
5605         This includes both reachable and unreachable objects.
5606         <p/>
5607         The <paramlink id="object_filter"></paramlink> parameter indicates the
5608         objects for which the callback function is called. If this parameter
5609         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 
5610         called for every object that is tagged. If the parameter is 
5611         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5612         called for objects that are not tagged. If the parameter
5613         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5614         called for every object in the heap, irrespective of whether it is
5615         tagged or not.
5616         <p/>
5617         During the execution of this function the state of the heap
5618         does not change: no objects are allocated, no objects are
5619         garbage collected, and the state of objects (including 
5620         held values) does not change. 
5621         As a result, threads executing Java 
5622         programming language code, threads attempting to resume the
5623         execution of Java programming language code, and threads 
5624         attempting to execute JNI functions are typically stalled.
5625       </description>
5626       <origin>new</origin>
5627       <capabilities>
5628         <required id="can_tag_objects"></required>
5629       </capabilities>
5630       <parameters>
5631         <param id="klass">
5632           <jclass/>
5633             <description>
5634               Iterate over objects of this class only.
5635             </description>
5636         </param>
5637         <param id="object_filter">
5638           <enum>jvmtiHeapObjectFilter</enum>
5639           <description>
5640             Indicates the objects for which the callback function is called.
5641           </description>
5642         </param>
5643         <param id="heap_object_callback">
5644           <ptrtype>
5645             <struct>jvmtiHeapObjectCallback</struct>
5646           </ptrtype>
5647             <description>
5648               The iterator function to be called for each
5649               <paramlink id="klass"/> instance matching 
5650               the <paramlink id="object_filter"/>.
5651             </description>
5652         </param>
5653         <param id="user_data">
5654           <inbuf>
5655             <void/>
5656             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5657           </inbuf>
5658           <description>
5659             User supplied data to be passed to the callback. 
5660           </description>
5661         </param>
5662       </parameters>
5663       <errors>
5664       </errors>
5665     </function>
5666 
5667   </category>
5668 
5669   <category id="local" label="Local Variable">
5670 
5671     <intro>
5672       These functions are used to retrieve or set the value of a local variable. 
5673       The variable is identified by the depth of the frame containing its
5674       value and the variable's slot number within that frame. 
5675       The mapping of variables to 
5676       slot numbers can be obtained with the function 
5677       <functionlink id="GetLocalVariableTable"></functionlink>.
5678     </intro>
5679 
5680     <function id="GetLocalObject" num="21">
5681       <synopsis>Get Local Variable - Object</synopsis>
5682       <description>
5683         This function can be used to retrieve the value of a local 
5684         variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 
5685       </description>
5686       <origin>jvmdi</origin>
5687       <capabilities>
5688         <required id="can_access_local_variables"></required>
5689       </capabilities>
5690       <parameters>
5691         <param id="thread">
5692           <jthread null="current" frame="frame"/>
5693           <description>
5694             The thread of the frame containing the variable's value.
5695           </description>
5696         </param>
5697         <param id="depth">
5698           <jframeID thread="thread"/>
5699           <description>
5700             The depth of the frame containing the variable's value.
5701           </description>
5702         </param>
5703         <param id="slot">
5704           <jint/>
5705           <description>
5706             The variable's slot number.
5707           </description>
5708         </param>
5709         <param id="value_ptr">
5710           <outptr><jobject/></outptr>
5711             <description>
5712               On return, points to the variable's value. 
5713             </description>
5714         </param>
5715       </parameters>
5716       <errors>
5717         <error id="JVMTI_ERROR_INVALID_SLOT">
5718           Invalid <code>slot</code>.
5719         </error>
5720         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5721           The variable type is not
5722           <code>Object</code> or a subclass of <code>Object</code>.
5723         </error>
5724         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5725           Not a visible frame
5726         </error>
5727       </errors>
5728     </function>
5729 
5730     <function id="GetLocalInstance" num="155" since="1.2">
5731       <synopsis>Get Local Instance</synopsis>
5732       <description>
5733         This function can be used to retrieve the value of the local object
5734         variable at slot 0 (the "<code>this</code>" object) from non-static
5735         frames.  This function can retrieve the "<code>this</code>" object from
5736         native method frames, whereas <code>GetLocalObject()</code> would 
5737         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5738       </description>
5739       <origin>new</origin>
5740       <capabilities>
5741         <required id="can_access_local_variables"></required>
5742       </capabilities>
5743       <parameters>
5744         <param id="thread">
5745           <jthread null="current" frame="frame"/>
5746           <description>
5747             The thread of the frame containing the variable's value.
5748           </description>
5749         </param>
5750         <param id="depth">
5751           <jframeID thread="thread"/>
5752           <description>
5753             The depth of the frame containing the variable's value.
5754           </description>
5755         </param>
5756         <param id="value_ptr">
5757           <outptr><jobject/></outptr>
5758             <description>
5759               On return, points to the variable's value. 
5760             </description>
5761         </param>
5762       </parameters>
5763       <errors>
5764         <error id="JVMTI_ERROR_INVALID_SLOT">
5765           If the specified frame is a static method frame.
5766         </error>
5767       </errors>
5768     </function>
5769     <function id="GetLocalInt" num="22">
5770       <synopsis>Get Local Variable - Int</synopsis>
5771       <description>
5772         This function can be used to retrieve the value of a local 
5773         variable whose type is <code>int</code>,
5774         <code>short</code>, <code>char</code>, <code>byte</code>, or 
5775         <code>boolean</code>. 
5776       </description>
5777       <origin>jvmdi</origin>
5778       <capabilities>
5779         <required id="can_access_local_variables"></required>
5780       </capabilities>
5781       <parameters>
5782         <param id="thread">
5783           <jthread null="current" frame="frame"/>
5784           <description>
5785             The thread of the frame containing the variable's value.
5786           </description>
5787         </param>
5788         <param id="depth">
5789           <jframeID thread="thread"/>
5790           <description>
5791             The depth of the frame containing the variable's value.
5792           </description>
5793         </param>
5794         <param id="slot">
5795           <jint/>
5796           <description>
5797             The variable's slot number.
5798           </description>
5799         </param>
5800         <param id="value_ptr">
5801           <outptr><jint/></outptr>
5802           <description>
5803             On return, points to the variable's value. 
5804           </description>
5805         </param>
5806       </parameters>
5807       <errors>
5808         <error id="JVMTI_ERROR_INVALID_SLOT">
5809           Invalid <code>slot</code>.
5810         </error>
5811         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5812           The variable type is not 
5813           <code>int</code>, <code>short</code>,
5814           <code>char</code>, <code>byte</code>, or 
5815           <code>boolean</code>.
5816         </error>
5817         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5818           Not a visible frame
5819         </error>
5820       </errors>
5821     </function>
5822 
5823     <function id="GetLocalLong" num="23">
5824       <synopsis>Get Local Variable - Long</synopsis>
5825       <description>
5826         This function can be used to retrieve the value of a local 
5827         variable whose type is <code>long</code>. 
5828       </description>
5829       <origin>jvmdi</origin>
5830       <capabilities>
5831         <required id="can_access_local_variables"></required>
5832       </capabilities>
5833       <parameters>
5834         <param id="thread">
5835           <jthread null="current" frame="frame"/>
5836           <description>
5837             The thread of the frame containing the variable's value.
5838           </description>
5839         </param>
5840         <param id="depth">
5841           <jframeID thread="thread"/>
5842           <description>
5843             The depth of the frame containing the variable's value.
5844           </description>
5845         </param>
5846         <param id="slot">
5847           <jint/>
5848           <description>
5849             The variable's slot number.
5850           </description>
5851         </param>
5852         <param id="value_ptr">
5853           <outptr><jlong/></outptr>
5854           <description>
5855             On return, points to the variable's value. 
5856           </description>
5857         </param>
5858       </parameters>
5859       <errors>
5860         <error id="JVMTI_ERROR_INVALID_SLOT">
5861           Invalid <code>slot</code>.
5862         </error>
5863         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5864           The variable type is not <code>long</code>.
5865         </error>
5866         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5867           Not a visible frame
5868         </error>
5869       </errors>
5870     </function>
5871 
5872     <function id="GetLocalFloat" num="24">
5873       <synopsis>Get Local Variable - Float</synopsis>
5874       <description>
5875         This function can be used to retrieve the value of a local 
5876         variable whose type is <code>float</code>. 
5877       </description>
5878       <origin>jvmdi</origin>
5879       <capabilities>
5880         <required id="can_access_local_variables"></required>
5881       </capabilities>
5882       <parameters>
5883         <param id="thread">
5884           <jthread null="current" frame="frame"/>
5885           <description>
5886             The thread of the frame containing the variable's value.
5887           </description>
5888         </param>
5889         <param id="depth">
5890           <jframeID thread="thread"/>
5891           <description>
5892             The depth of the frame containing the variable's value.
5893           </description>
5894         </param>
5895         <param id="slot">
5896           <jint/>
5897           <description>
5898             The variable's slot number.
5899           </description>
5900         </param>
5901         <param id="value_ptr">
5902           <outptr><jfloat/></outptr>
5903           <description>
5904             On return, points to the variable's value. 
5905           </description>
5906         </param>
5907       </parameters>
5908       <errors>
5909         <error id="JVMTI_ERROR_INVALID_SLOT">
5910           Invalid <code>slot</code>.
5911         </error>
5912         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5913           The variable type is not <code>float</code>.
5914         </error>
5915         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5916           Not a visible frame
5917         </error>
5918       </errors>
5919     </function>
5920 
5921     <function id="GetLocalDouble" num="25">
5922       <synopsis>Get Local Variable - Double</synopsis>
5923       <description>
5924         This function can be used to retrieve the value of a local 
5925         variable whose type is <code>long</code>. 
5926       </description>
5927       <origin>jvmdi</origin>
5928       <capabilities>
5929         <required id="can_access_local_variables"></required>
5930       </capabilities>
5931       <parameters>
5932         <param id="thread">
5933           <jthread null="current" frame="frame"/>
5934           <description>
5935             The thread of the frame containing the variable's value.
5936           </description>
5937         </param>
5938         <param id="depth">
5939           <jframeID thread="thread"/>
5940           <description>
5941             The depth of the frame containing the variable's value.
5942           </description>
5943         </param>
5944         <param id="slot">
5945           <jint/>
5946           <description>
5947             The variable's slot number.
5948           </description>
5949         </param>
5950         <param id="value_ptr">
5951           <outptr><jdouble/></outptr>
5952           <description>
5953             On return, points to the variable's value. 
5954           </description>
5955         </param>
5956       </parameters>
5957       <errors>
5958         <error id="JVMTI_ERROR_INVALID_SLOT">
5959           Invalid <code>slot</code>.
5960         </error>
5961         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5962           The variable type is not <code>double</code>.
5963         </error>
5964         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5965           Not a visible frame
5966         </error>
5967       </errors>
5968     </function>
5969 
5970     <function id="SetLocalObject" num="26">
5971       <synopsis>Set Local Variable - Object</synopsis>
5972       <description>
5973         This function can be used to set the value of a local 
5974         variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 
5975       </description>
5976       <origin>jvmdi</origin>
5977       <capabilities>
5978         <required id="can_access_local_variables"></required>
5979       </capabilities>
5980       <parameters>
5981         <param id="thread">
5982           <jthread null="current" frame="frame"/>
5983           <description>
5984             The thread of the frame containing the variable's value.
5985           </description>
5986         </param>
5987         <param id="depth">
5988           <jframeID thread="thread"/>
5989           <description>
5990             The depth of the frame containing the variable's value.
5991           </description>
5992         </param>
5993         <param id="slot">
5994           <jint/>
5995           <description>
5996             The variable's slot number.
5997           </description>
5998         </param>
5999         <param id="value">
6000           <jobject/>
6001             <description>
6002               The new value for the variable.
6003             </description>
6004         </param>
6005       </parameters>
6006       <errors>
6007         <error id="JVMTI_ERROR_INVALID_SLOT">
6008           Invalid <code>slot</code>.
6009         </error>
6010         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6011           The variable type is not
6012           <code>Object</code> or a subclass of <code>Object</code>.
6013         </error>
6014         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6015           The supplied <paramlink id="value"/> is not compatible 
6016           with the variable type.
6017         </error>
6018         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6019           Not a visible frame
6020         </error>
6021       </errors>
6022     </function>
6023 
6024     <function id="SetLocalInt" num="27">
6025       <synopsis>Set Local Variable - Int</synopsis>
6026       <description>
6027         This function can be used to set the value of a local 
6028         variable whose type is <code>int</code>,
6029         <code>short</code>, <code>char</code>, <code>byte</code>, or 
6030         <code>boolean</code>. 
6031       </description>
6032       <origin>jvmdi</origin>
6033       <capabilities>
6034         <required id="can_access_local_variables"></required>
6035       </capabilities>
6036       <parameters>
6037         <param id="thread">
6038           <jthread null="current" frame="frame"/>
6039           <description>
6040             The thread of the frame containing the variable's value.
6041           </description>
6042         </param>
6043         <param id="depth">
6044           <jframeID thread="thread"/>
6045           <description>
6046             The depth of the frame containing the variable's value.
6047           </description>
6048         </param>
6049         <param id="slot">
6050           <jint/>
6051           <description>
6052             The variable's slot number.
6053           </description>
6054         </param>
6055         <param id="value">
6056           <jint/>
6057           <description>
6058             The new value for the variable.
6059           </description>
6060         </param>
6061       </parameters>
6062       <errors>
6063         <error id="JVMTI_ERROR_INVALID_SLOT">
6064           Invalid <code>slot</code>.
6065         </error>
6066         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6067           The variable type is not 
6068           <code>int</code>, <code>short</code>,
6069           <code>char</code>, <code>byte</code>, or 
6070           <code>boolean</code>.
6071         </error>
6072         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6073           Not a visible frame
6074         </error>
6075       </errors>
6076     </function>
6077 
6078     <function id="SetLocalLong" num="28">
6079       <synopsis>Set Local Variable - Long</synopsis>
6080       <description>
6081         This function can be used to set the value of a local 
6082         variable whose type is <code>long</code>. 
6083       </description>
6084       <origin>jvmdi</origin>
6085       <capabilities>
6086         <required id="can_access_local_variables"></required>
6087       </capabilities>
6088       <parameters>
6089         <param id="thread">
6090           <jthread null="current" frame="frame"/>
6091           <description>
6092             The thread of the frame containing the variable's value.
6093           </description>
6094         </param>
6095         <param id="depth">
6096           <jframeID thread="thread"/>
6097           <description>
6098             The depth of the frame containing the variable's value.
6099           </description>
6100         </param>
6101         <param id="slot">
6102           <jint/>
6103           <description>
6104             The variable's slot number.
6105           </description>
6106         </param>
6107         <param id="value">
6108           <jlong/>
6109           <description>
6110             The new value for the variable.
6111           </description>
6112         </param>
6113       </parameters>
6114       <errors>
6115         <error id="JVMTI_ERROR_INVALID_SLOT">
6116           Invalid <code>slot</code>.
6117         </error>
6118         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6119           The variable type is not <code>long</code>.
6120         </error>
6121         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6122           Not a visible frame
6123         </error>
6124       </errors>
6125     </function>
6126 
6127     <function id="SetLocalFloat" num="29">
6128       <synopsis>Set Local Variable - Float</synopsis>
6129       <description>
6130         This function can be used to set the value of a local 
6131         variable whose type is <code>float</code>. 
6132       </description>
6133       <origin>jvmdi</origin>
6134       <capabilities>
6135         <required id="can_access_local_variables"></required>
6136       </capabilities>
6137       <parameters>
6138         <param id="thread">
6139           <jthread null="current" frame="frame"/>
6140           <description>
6141             The thread of the frame containing the variable's value.
6142           </description>
6143         </param>
6144         <param id="depth">
6145           <jframeID thread="thread"/>
6146           <description>
6147             The depth of the frame containing the variable's value.
6148           </description>
6149         </param>
6150         <param id="slot">
6151           <jint/>
6152           <description>
6153             The variable's slot number.
6154           </description>
6155         </param>
6156         <param id="value">
6157           <jfloat/>
6158           <description>
6159             The new value for the variable.
6160           </description>
6161         </param>
6162       </parameters>
6163       <errors>
6164         <error id="JVMTI_ERROR_INVALID_SLOT">
6165           Invalid <code>slot</code>.
6166         </error>
6167         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6168           The variable type is not <code>float</code>.
6169         </error>
6170         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6171           Not a visible frame
6172         </error>
6173       </errors>
6174     </function>
6175 
6176     <function id="SetLocalDouble" num="30">
6177       <synopsis>Set Local Variable - Double</synopsis>
6178       <description>
6179         This function can be used to set the value of a local 
6180         variable whose type is <code>double</code>. 
6181       </description>
6182       <origin>jvmdi</origin>
6183       <capabilities>
6184         <required id="can_access_local_variables"></required>
6185       </capabilities>
6186       <parameters>
6187         <param id="thread">
6188           <jthread null="current" frame="frame"/>
6189           <description>
6190             The thread of the frame containing the variable's value.
6191           </description>
6192         </param>
6193         <param id="depth">
6194           <jframeID thread="thread"/>
6195           <description>
6196             The depth of the frame containing the variable's value.
6197           </description>
6198         </param>
6199         <param id="slot">
6200           <jint/>
6201           <description>
6202             The variable's slot number.
6203           </description>
6204         </param>
6205         <param id="value">
6206           <jdouble/>
6207           <description>
6208             The new value for the variable.
6209           </description>
6210         </param>
6211       </parameters>
6212       <errors>
6213         <error id="JVMTI_ERROR_INVALID_SLOT">
6214           Invalid <code>slot</code>.
6215         </error>
6216         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6217           The variable type is not <code>double</code>.
6218         </error>
6219         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6220           Not a visible frame
6221         </error>
6222       </errors>
6223     </function>
6224   </category>
6225 
6226   <category id="breakpointCategory" label="Breakpoint">
6227 
6228     <intro>
6229     </intro>
6230 
6231     <function id="SetBreakpoint" num="38">
6232       <synopsis>Set Breakpoint</synopsis>
6233       <description>
6234         Set a breakpoint at the instruction indicated by
6235         <code>method</code> and <code>location</code>.
6236         An instruction can only have one breakpoint.
6237         <p/>
6238         Whenever the designated instruction is about to be executed, a
6239         <eventlink id="Breakpoint"></eventlink> event is generated.
6240       </description>
6241       <origin>jvmdi</origin>
6242       <capabilities>
6243         <required id="can_generate_breakpoint_events"></required>
6244       </capabilities>
6245       <parameters>
6246         <param id="klass">
6247           <jclass method="method"/>
6248             <description>
6249               The class in which to set the breakpoint
6250             </description>
6251         </param>
6252         <param id="method">
6253           <jmethodID class="klass"/>
6254             <description>
6255               The method in which to set the breakpoint
6256             </description>
6257         </param>
6258         <param id="location">
6259           <jlocation/>
6260           <description>
6261             the index of the instruction at which to set the breakpoint
6262 
6263           </description>
6264         </param>
6265       </parameters>
6266       <errors>
6267         <error id="JVMTI_ERROR_DUPLICATE"> 
6268           The designated bytecode already has a breakpoint.
6269         </error>
6270       </errors>
6271     </function>
6272 
6273     <function id="ClearBreakpoint" num="39">
6274       <synopsis>Clear Breakpoint</synopsis>
6275       <description>
6276         Clear the breakpoint at the bytecode indicated by
6277         <code>method</code> and <code>location</code>.
6278       </description>
6279       <origin>jvmdi</origin>
6280       <capabilities>
6281         <required id="can_generate_breakpoint_events"></required>
6282       </capabilities>
6283       <parameters>
6284         <param id="klass">
6285           <jclass method="method"/>
6286             <description>
6287               The class in which to clear the breakpoint
6288             </description>
6289         </param>
6290         <param id="method">
6291           <jmethodID class="klass"/>
6292             <description>
6293               The method in which to clear the breakpoint
6294             </description>
6295         </param>
6296         <param id="location">
6297           <jlocation/>
6298           <description>
6299             the index of the instruction at which to clear the breakpoint
6300           </description>
6301         </param>
6302       </parameters>
6303       <errors>
6304         <error id="JVMTI_ERROR_NOT_FOUND"> 
6305           There's no breakpoint at the designated bytecode.
6306         </error>
6307       </errors>
6308     </function>
6309 
6310   </category>
6311 
6312   <category id="fieldWatch" label="Watched Field">
6313 
6314     <intro>
6315     </intro>
6316 
6317     <function id="SetFieldAccessWatch" num="41">
6318       <synopsis>Set Field Access Watch</synopsis>
6319       <description>
6320         Generate a <eventlink id="FieldAccess"></eventlink> event
6321         when the field specified
6322         by <code>klass</code> and
6323         <code>field</code> is about to be accessed.
6324         An event will be generated for each access of the field
6325         until it is canceled with 
6326         <functionlink id="ClearFieldAccessWatch"></functionlink>.
6327         Field accesses from Java programming language code or from JNI code are watched,
6328         fields modified by other means are not watched.
6329         Note that <jvmti/> users should be aware that their own field accesses
6330         will trigger the watch.
6331         A field can only have one field access watch set.
6332         Modification of a field is not considered an access--use 
6333         <functionlink id="SetFieldModificationWatch"></functionlink>
6334         to monitor modifications.
6335       </description>
6336       <origin>jvmdi</origin>
6337       <capabilities>
6338         <required id="can_generate_field_access_events"></required>
6339       </capabilities>
6340       <parameters>
6341         <param id="klass">
6342           <jclass field="field"/>
6343             <description>
6344               The class containing the field to watch
6345             </description>
6346         </param>
6347         <param id="field">
6348           <jfieldID class="klass"/>
6349             <description>
6350               The field to watch
6351 
6352             </description>
6353         </param>
6354       </parameters>
6355       <errors>
6356         <error id="JVMTI_ERROR_DUPLICATE"> 
6357           The designated field is already being watched for accesses.
6358         </error>
6359       </errors>
6360     </function>
6361 
6362     <function id="ClearFieldAccessWatch" num="42">
6363       <synopsis>Clear Field Access Watch</synopsis>
6364       <description>
6365         Cancel a field access watch previously set by 
6366         <functionlink id="SetFieldAccessWatch"></functionlink>, on the 
6367         field specified
6368         by <code>klass</code> and
6369         <code>field</code>.
6370       </description>
6371       <origin>jvmdi</origin>
6372       <capabilities>
6373         <required id="can_generate_field_access_events"></required>
6374       </capabilities>
6375       <parameters>
6376         <param id="klass">
6377           <jclass field="field"/>
6378             <description>
6379               The class containing the field to watch
6380             </description>
6381         </param>
6382         <param id="field">
6383           <jfieldID class="klass"/>
6384             <description>
6385               The field to watch
6386 
6387             </description>
6388         </param>
6389       </parameters>
6390       <errors>
6391         <error id="JVMTI_ERROR_NOT_FOUND"> 
6392           The designated field is not being watched for accesses.
6393         </error>
6394       </errors>
6395     </function>
6396 
6397     <function id="SetFieldModificationWatch" num="43">
6398       <synopsis>Set Field Modification Watch</synopsis>
6399       <description>
6400         Generate a <eventlink id="FieldModification"></eventlink> event
6401         when the field specified
6402         by <code>klass</code> and
6403         <code>field</code> is about to be modified.
6404         An event will be generated for each modification of the field
6405         until it is canceled with 
6406         <functionlink id="ClearFieldModificationWatch"></functionlink>.
6407         Field modifications from Java programming language code or from JNI code are watched,
6408         fields modified by other means are not watched.
6409         Note that <jvmti/> users should be aware that their own field modifications
6410         will trigger the watch.
6411         A field can only have one field modification watch set.
6412       </description>
6413       <origin>jvmdi</origin>
6414       <capabilities>
6415         <required id="can_generate_field_modification_events"></required>
6416       </capabilities>
6417       <parameters>
6418         <param id="klass">
6419           <jclass field="field"/>
6420             <description>
6421               The class containing the field to watch
6422             </description>
6423         </param>
6424         <param id="field">
6425           <jfieldID class="klass"/>
6426             <description>
6427               The field to watch
6428 
6429             </description>
6430         </param>
6431       </parameters>
6432       <errors>
6433         <error id="JVMTI_ERROR_DUPLICATE"> 
6434           The designated field is already being watched for modifications.
6435         </error>
6436       </errors>
6437     </function>
6438 
6439     <function id="ClearFieldModificationWatch" num="44">
6440       <synopsis>Clear Field Modification Watch</synopsis>
6441       <description>
6442 
6443         Cancel a field modification watch previously set by 
6444         <functionlink id="SetFieldModificationWatch"></functionlink>, on the 
6445         field specified
6446         by <code>klass</code> and
6447         <code>field</code>.
6448       </description>
6449       <origin>jvmdi</origin>
6450       <capabilities>
6451         <required id="can_generate_field_modification_events"></required>
6452       </capabilities>
6453       <parameters>
6454         <param id="klass">
6455           <jclass field="field"/>
6456             <description>
6457               The class containing the field to watch
6458             </description>
6459         </param>
6460         <param id="field">
6461           <jfieldID class="klass"/>
6462             <description>
6463               The field to watch
6464 
6465             </description>
6466         </param>
6467       </parameters>
6468       <errors>
6469         <error id="JVMTI_ERROR_NOT_FOUND"> 
6470           The designated field is not being watched for modifications.
6471         </error>
6472       </errors>
6473     </function>
6474   </category>
6475 
6476   <category id="module" label="Module">
6477 
6478     <intro>
6479     </intro>
6480 
6481     <function id="GetAllModules" num="3" since="9">
6482       <synopsis>Get All Modules</synopsis>
6483       <description>
6484         Return an array of all modules loaded in the virtual machine.
6485         The number of modules in the array is returned via
6486         <code>module_count_ptr</code>, and the array itself via
6487         <code>modules_ptr</code>.
6488         <p/>
6489       </description>
6490       <origin>new</origin>
6491       <capabilities>
6492       </capabilities>
6493       <parameters>
6494         <param id="module_count_ptr">
6495           <outptr><jint/></outptr>
6496           <description>
6497             On return, points to the number of returned modules.
6498           </description>
6499         </param>
6500         <param id="modules_ptr">
6501           <allocbuf outcount="module_count_ptr"><jobject/></allocbuf>
6502             <description>
6503               On return, points to an array of references, one
6504               for each module.
6505             </description>
6506         </param>
6507       </parameters>
6508       <errors>
6509       </errors>
6510     </function>
6511   </category>
6512 
6513   <category id="class" label="Class">
6514 
6515     <intro>
6516     </intro>
6517 
6518     <function id="GetLoadedClasses" jkernel="yes" num="78">
6519       <synopsis>Get Loaded Classes</synopsis>
6520       <description>
6521         Return an array of all classes loaded in the virtual machine.
6522         The number of classes in the array is returned via
6523         <code>class_count_ptr</code>, and the array itself via
6524         <code>classes_ptr</code>.
6525         <p/>
6526         Array classes of all types (including arrays of primitive types) are 
6527         included in the returned list. Primitive classes (for example, 
6528         <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. 
6529       </description>
6530       <origin>jvmdi</origin>
6531       <capabilities>
6532       </capabilities>
6533       <parameters>
6534         <param id="class_count_ptr">
6535           <outptr><jint/></outptr>
6536           <description>
6537             On return, points to the number of classes.
6538           </description>
6539         </param>
6540         <param id="classes_ptr">
6541           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6542             <description>
6543               On return, points to an array of references, one
6544               for each class.
6545             </description>
6546         </param>
6547       </parameters>
6548       <errors>
6549       </errors>
6550     </function>
6551 
6552     <function id="GetClassLoaderClasses" jkernel="yes" num="79">
6553       <synopsis>Get Classloader Classes</synopsis>
6554       <description>
6555         Returns an array of those classes for which this class loader has
6556         been recorded as an initiating loader. Each 
6557         class in the returned array was created by this class loader, 
6558         either by defining it directly or by delegation to another class loader.
6559         See <vmspec chapter="5.3"/>.
6560         <p/>
6561         The number of classes in the array is returned via
6562         <code>class_count_ptr</code>, and the array itself via
6563         <code>classes_ptr</code>.
6564       </description>
6565       <origin>jvmdi</origin>
6566       <capabilities>
6567       </capabilities>
6568       <parameters>
6569         <param id="initiating_loader">
6570           <ptrtype>
6571             <jobject/>
6572             <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
6573           </ptrtype>
6574             <description>
6575               An initiating class loader.
6576             </description>
6577         </param>
6578         <param id="class_count_ptr">
6579           <outptr><jint/></outptr>
6580           <description>
6581             On return, points to the number of classes.
6582           </description>
6583         </param>
6584         <param id="classes_ptr">
6585           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6586             <description>
6587               On return, points to an array of references, one
6588               for each class.
6589             </description>
6590         </param>
6591       </parameters>
6592       <errors>
6593       </errors>
6594     </function>
6595 
6596     <function id="GetClassSignature" phase="start" num="48">
6597       <synopsis>Get Class Signature</synopsis>
6598       <description>
6599         For the class indicated by <code>klass</code>, return the 
6600         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI 
6601             type signature</externallink> 
6602         and the generic signature of the class.
6603         For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
6604         and <code>int[]</code> is <code>"[I"</code>
6605         The returned name for primitive classes
6606         is the type signature character of the corresponding primitive type. 
6607         For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
6608       </description>
6609       <origin>jvmdiClone</origin>
6610       <capabilities>
6611       </capabilities>
6612       <parameters>
6613         <param id="klass">
6614           <jclass/>
6615             <description>
6616               The class to query.
6617             </description>
6618         </param>
6619         <param id="signature_ptr">
6620           <allocbuf>
6621             <char/>           
6622             <nullok>the signature is not returned</nullok>
6623           </allocbuf>
6624           <description>
6625             On return, points to the JNI type signature of the class, encoded as a
6626             <internallink id="mUTF">modified UTF-8</internallink> string.
6627           </description>
6628         </param>
6629         <param id="generic_ptr">
6630           <allocbuf>
6631             <char/>           
6632             <nullok>the generic signature is not returned</nullok>
6633           </allocbuf>
6634           <description>
6635             On return, points to the generic signature of the class, encoded as a
6636             <internallink id="mUTF">modified UTF-8</internallink> string.
6637             If there is no generic signature attribute for the class, then,
6638             on return, points to <code>NULL</code>. 
6639           </description>
6640         </param>
6641       </parameters>
6642       <errors>
6643       </errors>
6644     </function>
6645 
6646     <function id="GetClassStatus" phase="start" num="49">
6647       <synopsis>Get Class Status</synopsis>
6648       <description>
6649         Get the status of the class. Zero or more of the following bits can be 
6650         set.
6651         <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
6652           <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
6653             Class bytecodes have been verified
6654           </constant>
6655           <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
6656             Class preparation is complete
6657           </constant>
6658           <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
6659             Class initialization is complete. Static initializer has been run.
6660           </constant>
6661           <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
6662             Error during initialization makes class unusable
6663           </constant>
6664           <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
6665             Class is an array.  If set, all other bits are zero.
6666           </constant>
6667           <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
6668             Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).  
6669             If set, all other bits are zero.
6670           </constant>
6671         </constants>
6672       </description>
6673       <origin>jvmdi</origin>
6674       <capabilities>
6675       </capabilities>
6676       <parameters>
6677         <param id="klass">
6678           <jclass/>
6679             <description>
6680               The class to query.
6681             </description>
6682         </param>
6683         <param id="status_ptr">
6684           <outptr><jint/></outptr>
6685           <description>
6686             On return, points to the current state of this class as one or 
6687             more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
6688           </description>
6689         </param>
6690       </parameters>
6691       <errors>
6692       </errors>
6693     </function>
6694 
6695     <function id="GetSourceFileName" phase="start" num="50">
6696       <synopsis>Get Source File Name</synopsis>
6697       <description>
6698         For the class indicated by <code>klass</code>, return the source file
6699         name via <code>source_name_ptr</code>. The returned string 
6700         is a file name only and never contains a directory name. 
6701         <p/>
6702         For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) 
6703         and for arrays this function returns 
6704         <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
6705       </description>
6706       <origin>jvmdi</origin>
6707       <capabilities>
6708         <required id="can_get_source_file_name"></required>
6709       </capabilities>
6710       <parameters>
6711         <param id="klass">
6712           <jclass/>
6713             <description>
6714               The class to query.
6715             </description>
6716         </param>
6717         <param id="source_name_ptr">
6718           <allocbuf><char/></allocbuf>
6719           <description>
6720             On return, points to the class's source file name, encoded as a
6721             <internallink id="mUTF">modified UTF-8</internallink> string.
6722           </description>
6723         </param>
6724       </parameters>
6725       <errors>
6726         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
6727           Class information does not include a source file name. This includes
6728           cases where the class is an array class or primitive class.
6729         </error>
6730       </errors>
6731     </function>
6732 
6733     <function id="GetClassModifiers" phase="start" num="51">
6734       <synopsis>Get Class Modifiers</synopsis>
6735       <description>
6736         For the class indicated by <code>klass</code>, return the access
6737         flags
6738         via <code>modifiers_ptr</code>.
6739         Access flags are defined in <vmspec chapter="4"/>.
6740         <p/>
6741         If the class is an array class, then its public, private, and protected 
6742         modifiers are the same as those of its component type. For arrays of 
6743         primitives, this component type is represented by one of the primitive 
6744         classes (for example, <code>java.lang.Integer.TYPE</code>). 
6745         <p/>
6746         If the class is a primitive class, its public modifier is always true, 
6747         and its protected and private modifiers are always false. 
6748         <p/>
6749         If the class is an array class or a primitive class then its final 
6750         modifier is always true and its interface modifier is always false. 
6751         The values of its other modifiers are not determined by this specification. 
6752 
6753       </description>
6754       <origin>jvmdi</origin>
6755       <capabilities>
6756       </capabilities>
6757       <parameters>
6758         <param id="klass">
6759           <jclass/>
6760             <description>
6761               The class to query.
6762             </description>
6763         </param>
6764         <param id="modifiers_ptr">
6765           <outptr><jint/></outptr>
6766           <description>
6767             On return, points to the current access flags of this class.
6768 
6769           </description>
6770         </param>
6771       </parameters>
6772       <errors>
6773       </errors>
6774     </function>
6775 
6776     <function id="GetClassMethods" phase="start" num="52">
6777       <synopsis>Get Class Methods</synopsis>
6778       <description>
6779         For the class indicated by <code>klass</code>, return a count of
6780         methods via <code>method_count_ptr</code> and a list of
6781         method IDs via <code>methods_ptr</code>. The method list contains 
6782         constructors and static initializers as well as true methods.
6783         Only directly declared methods are returned (not inherited methods).
6784         An empty method list is returned for array classes and primitive classes
6785         (for example, <code>java.lang.Integer.TYPE</code>).
6786       </description>
6787       <origin>jvmdi</origin>
6788       <capabilities>
6789         <capability id="can_maintain_original_method_order"/>
6790       </capabilities>
6791       <parameters>
6792         <param id="klass">
6793           <jclass/>
6794             <description>
6795               The class to query.
6796             </description>
6797         </param>
6798         <param id="method_count_ptr">
6799           <outptr><jint/></outptr>
6800           <description>
6801             On return, points to the number of methods declared in this class.
6802           </description>
6803         </param>
6804         <param id="methods_ptr">
6805           <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
6806             <description>
6807               On return, points to the method ID array.
6808             </description>
6809         </param>
6810       </parameters>
6811       <errors>
6812         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
6813           <paramlink id="klass"></paramlink> is not prepared.
6814         </error>
6815       </errors>
6816     </function>
6817 
6818     <function id="GetClassFields" phase="start" num="53">
6819       <synopsis>Get Class Fields</synopsis>
6820       <description>
6821         For the class indicated by <code>klass</code>, return a count of fields
6822         via <code>field_count_ptr</code> and a list of field IDs via
6823         <code>fields_ptr</code>.
6824         Only directly declared fields are returned (not inherited fields).
6825         Fields are returned in the order they occur in the class file.
6826         An empty field list is returned for array classes and primitive classes
6827         (for example, <code>java.lang.Integer.TYPE</code>).
6828         Use JNI to determine the length of an array.
6829       </description>
6830       <origin>jvmdi</origin>
6831       <capabilities>
6832       </capabilities>
6833       <parameters>
6834         <param id="klass">
6835           <jclass/>
6836             <description>
6837               The class to query.
6838             </description>
6839         </param>
6840         <param id="field_count_ptr">
6841           <outptr><jint/></outptr>
6842           <description>
6843             On return, points to the number of fields declared in this class.
6844           </description>
6845         </param>
6846         <param id="fields_ptr">
6847           <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
6848             <description>
6849               On return, points to the field ID array.
6850             </description>
6851         </param>
6852       </parameters>
6853       <errors>
6854         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 
6855           <paramlink id="klass"></paramlink> is not prepared.
6856         </error>
6857       </errors>
6858     </function>
6859 
6860     <function id="GetImplementedInterfaces" phase="start" num="54">
6861       <synopsis>Get Implemented Interfaces</synopsis>
6862       <description>
6863         Return the direct super-interfaces of this class. For a class, this 
6864         function returns the interfaces declared in its <code>implements</code>
6865         clause. For an interface, this function returns the interfaces declared in
6866         its <code>extends</code> clause.
6867         An empty interface list is returned for array classes and primitive classes
6868         (for example, <code>java.lang.Integer.TYPE</code>).
6869       </description>
6870       <origin>jvmdi</origin>
6871       <capabilities>
6872       </capabilities>
6873       <parameters>
6874         <param id="klass">
6875           <jclass/>
6876             <description>
6877               The class to query.
6878             </description>
6879         </param>
6880         <param id="interface_count_ptr">
6881           <outptr><jint/></outptr>
6882           <description>
6883             On return, points to the number of interfaces.
6884           </description>
6885         </param>
6886         <param id="interfaces_ptr">
6887           <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
6888             <description>
6889               On return, points to the interface array.
6890             </description>
6891         </param>
6892       </parameters>
6893       <errors>
6894         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 
6895           <paramlink id="klass"></paramlink> is not prepared.
6896         </error>
6897       </errors>
6898     </function>
6899 
6900     <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
6901       <synopsis>Get Class Version Numbers</synopsis>
6902       <description>
6903         For the class indicated by <code>klass</code>, 
6904         return the minor and major version numbers,
6905         as defined in
6906         <vmspec chapter="4"/>. 
6907       </description>
6908       <origin>new</origin>
6909       <capabilities>
6910       </capabilities>
6911       <parameters>
6912         <param id="klass">
6913           <jclass/>
6914             <description>
6915               The class to query.
6916             </description>
6917         </param>
6918         <param id="minor_version_ptr">
6919           <outptr><jint/></outptr>
6920           <description>
6921             On return, points to the value of the
6922             <code>minor_version</code> item of the 
6923             Class File Format.
6924             Note: to be consistent with the Class File Format,
6925             the minor version number is the first parameter.
6926           </description>
6927         </param>
6928         <param id="major_version_ptr">
6929           <outptr><jint/></outptr>
6930           <description>
6931             On return, points to the value of the
6932             <code>major_version</code> item of the 
6933             Class File Format.
6934           </description>
6935         </param>
6936       </parameters>
6937       <errors>
6938         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
6939           The class is a primitive or array class.
6940         </error>
6941       </errors>
6942     </function>
6943 
6944     <function id="GetConstantPool" phase="start" num="146" since="1.1">
6945       <synopsis>Get Constant Pool</synopsis>
6946       <description>
6947         For the class indicated by <code>klass</code>, 
6948         return the raw bytes of the constant pool in the format of the
6949         <code>constant_pool</code> item of 
6950         <vmspec chapter="4"/>.
6951         The format of the constant pool may differ between versions
6952         of the Class File Format, so, the 
6953         <functionlink id="GetClassVersionNumbers">minor and major 
6954         class version numbers</functionlink> should be checked for
6955         compatibility.
6956         <p/>
6957         The returned constant pool might not have the same layout or
6958         contents as the constant pool in the defining class file.
6959         The constant pool returned by GetConstantPool() may have
6960         more or fewer entries than the defining constant pool.
6961         Entries may be in a different order.
6962         The constant pool returned by GetConstantPool() will match the
6963         constant pool used by 
6964         <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
6965         That is, the bytecodes returned by GetBytecodes() will have
6966         constant pool indices which refer to constant pool entries returned
6967         by GetConstantPool().
6968         Note that since <functionlink id="RetransformClasses"/> 
6969         and <functionlink id="RedefineClasses"/> can change 
6970         the constant pool, the constant pool returned by this function
6971         can change accordingly.  Thus, the correspondence between 
6972         GetConstantPool() and GetBytecodes() does not hold if there
6973         is an intervening class retransformation or redefinition. 
6974         The value of a constant pool entry used by a given bytecode will
6975         match that of the defining class file (even if the indices don't match).
6976         Constant pool entries which are not used directly or indirectly by
6977         bytecodes (for example,  UTF-8 strings associated with annotations) are
6978         not  required to exist in the returned constant pool.
6979       </description>
6980       <origin>new</origin>
6981       <capabilities>
6982         <required id="can_get_constant_pool"></required>
6983       </capabilities>
6984       <parameters>
6985         <param id="klass">
6986           <jclass/>
6987             <description>
6988               The class to query.
6989             </description>
6990         </param>
6991         <param id="constant_pool_count_ptr">
6992           <outptr><jint/></outptr>
6993           <description>
6994             On return, points to the number of entries
6995             in the constant pool table plus one.
6996             This corresponds to the <code>constant_pool_count</code>
6997             item of the Class File Format.
6998           </description>
6999         </param>
7000         <param id="constant_pool_byte_count_ptr">
7001           <outptr><jint/></outptr>
7002           <description>
7003             On return, points to the number of bytes
7004             in the returned raw constant pool.
7005           </description>
7006         </param>
7007         <param id="constant_pool_bytes_ptr">
7008           <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
7009             <description>
7010               On return, points to the raw constant pool, that is the bytes
7011               defined by the <code>constant_pool</code> item of the 
7012               Class File Format
7013             </description>
7014         </param>
7015       </parameters>
7016       <errors>
7017         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
7018           The class is a primitive or array class.
7019         </error>
7020       </errors>
7021     </function>
7022 
7023     <function id="IsInterface" phase="start" num="55">
7024       <synopsis>Is Interface</synopsis>
7025       <description>
7026         Determines whether a class object reference represents an interface.
7027         The <code>jboolean</code> result is
7028         <code>JNI_TRUE</code> if the "class" is actually an interface,
7029         <code>JNI_FALSE</code> otherwise. 
7030       </description>
7031       <origin>jvmdi</origin>
7032       <capabilities>
7033       </capabilities>
7034       <parameters>
7035         <param id="klass">
7036           <jclass/>
7037             <description>
7038               The class to query.
7039             </description>
7040         </param>
7041         <param id="is_interface_ptr">
7042           <outptr><jboolean/></outptr>
7043           <description>
7044             On return, points to the boolean result of this function.
7045 
7046           </description>
7047         </param>
7048       </parameters>
7049       <errors>
7050       </errors>
7051     </function>
7052 
7053     <function id="IsArrayClass" phase="start" num="56">
7054       <synopsis>Is Array Class</synopsis>
7055       <description>
7056         Determines whether a class object reference represents an array.
7057         The <code>jboolean</code> result is
7058         <code>JNI_TRUE</code> if the class is an array,
7059         <code>JNI_FALSE</code> otherwise. 
7060       </description>
7061       <origin>jvmdi</origin>
7062       <capabilities>
7063       </capabilities>
7064       <parameters>
7065         <param id="klass">
7066           <jclass/>
7067             <description>
7068               The class to query.
7069             </description>
7070         </param>
7071         <param id="is_array_class_ptr">
7072           <outptr><jboolean/></outptr>
7073           <description>
7074             On return, points to the boolean result of this function.
7075 
7076           </description>
7077         </param>
7078       </parameters>
7079       <errors>
7080       </errors>
7081     </function>
7082 
7083     <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
7084       <synopsis>Is Modifiable Class</synopsis>
7085       <description>
7086         Determines whether a class is modifiable.
7087         If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
7088         returns <code>JNI_TRUE</code>) the class can be
7089         redefined with <functionlink id="RedefineClasses"/> (assuming 
7090         the agent possesses the
7091         <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
7092         capability) or
7093         retransformed with <functionlink id="RetransformClasses"/> (assuming 
7094         the agent possesses the
7095         <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
7096         capability).
7097         If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
7098         returns <code>JNI_FALSE</code>) the class can be neither
7099         redefined nor retransformed.
7100         <p/>
7101         Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) 
7102         and array classes are never modifiable. 
7103         <p/>
7104       </description>
7105       <origin>new</origin>
7106       <capabilities>
7107         <capability id="can_redefine_any_class">
7108           If possessed then all classes (except primitive and array classes) 
7109           are modifiable.
7110         </capability>
7111         <capability id="can_redefine_classes">
7112           No effect on the result of the function.
7113           But must additionally be possessed to modify the class with
7114           <functionlink id="RedefineClasses"/>.
7115         </capability>
7116         <capability id="can_retransform_classes">
7117           No effect on the result of the function.
7118           But must additionally be possessed to modify the class with
7119           <functionlink id="RetransformClasses"/>.
7120         </capability>
7121       </capabilities>
7122       <parameters>
7123         <param id="klass">
7124           <jclass/>
7125             <description>
7126               The class to query.
7127             </description>
7128         </param>
7129         <param id="is_modifiable_class_ptr">
7130           <outptr><jboolean/></outptr>
7131           <description>
7132             On return, points to the boolean result of this function.
7133           </description>
7134         </param>
7135       </parameters>
7136       <errors>
7137       </errors>
7138     </function>
7139 
7140     <function id="GetClassLoader" phase="start" num="57">
7141       <synopsis>Get Class Loader</synopsis>
7142       <description>
7143         For the class indicated by <code>klass</code>, return via
7144         <code>classloader_ptr</code> a reference to the class loader for the
7145         class.
7146       </description>
7147       <origin>jvmdi</origin>
7148       <capabilities>
7149       </capabilities>
7150       <parameters>
7151         <param id="klass">
7152           <jclass/>
7153             <description>
7154               The class to query.
7155             </description>
7156         </param>
7157         <param id="classloader_ptr">
7158           <outptr><jobject/></outptr>
7159             <description>
7160               On return, points to the class loader that loaded
7161               this class.
7162               If the class was not created by a class loader
7163               or if the class loader is the bootstrap class loader,
7164               points to <code>NULL</code>.
7165             </description>
7166         </param>
7167       </parameters>
7168       <errors>
7169       </errors>
7170 
7171     </function>
7172 
7173     <function id="GetSourceDebugExtension" phase="start" num="90">
7174       <synopsis>Get Source Debug Extension</synopsis>
7175       <description>
7176         For the class indicated by <code>klass</code>, return the debug 
7177         extension via <code>source_debug_extension_ptr</code>.
7178         The returned string 
7179         contains exactly the debug extension information present in the
7180         class file of <code>klass</code>. 
7181       </description>
7182       <origin>jvmdi</origin>
7183       <capabilities>
7184         <required id="can_get_source_debug_extension"></required>
7185       </capabilities>
7186       <parameters>
7187         <param id="klass">
7188           <jclass/>
7189             <description>
7190               The class to query.
7191             </description>
7192         </param>
7193         <param id="source_debug_extension_ptr">
7194           <allocbuf><char/></allocbuf>
7195           <description>
7196             On return, points to the class's debug extension, encoded as a
7197             <internallink id="mUTF">modified UTF-8</internallink> string.
7198           </description>
7199         </param>
7200       </parameters>
7201       <errors>
7202         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
7203           Class information does not include a debug extension.
7204         </error>
7205       </errors>
7206     </function>
7207 
7208     <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
7209       <synopsis>Retransform Classes</synopsis>
7210       <description>
7211         This function facilitates the 
7212         <internallink id="bci">bytecode instrumentation</internallink>
7213         of already loaded classes.
7214         To replace the class definition without reference to the existing
7215         bytecodes, as one might do when recompiling from source for 
7216         fix-and-continue debugging, <functionlink id="RedefineClasses"/>
7217         function should be used instead.
7218         <p/>
7219         When classes are initially loaded or when they are 
7220         <functionlink id="RedefineClasses">redefined</functionlink>,
7221         the initial class file bytes can be transformed with the
7222         <eventlink id="ClassFileLoadHook"/> event.
7223         This function reruns the transformation process
7224         (whether or not a transformation has previously occurred).
7225         This retransformation follows these steps:
7226         <ul>
7227           <li>starting from the initial class file bytes 
7228           </li>
7229           <li>for each <fieldlink id="can_retransform_classes"
7230                      struct="jvmtiCapabilities">retransformation
7231                                                 incapable</fieldlink>
7232             agent which received a
7233             <code>ClassFileLoadHook</code> event during the previous
7234             load or redefine, the bytes it returned 
7235             (via the <code>new_class_data</code> parameter)
7236             are reused as the output of the transformation; 
7237             note that this is equivalent to reapplying
7238             the previous transformation, unaltered. except that
7239             the <code>ClassFileLoadHook</code> event
7240             is <b>not</b> sent to these agents
7241           </li>
7242           <li>for each <fieldlink id="can_retransform_classes"
7243                      struct="jvmtiCapabilities">retransformation
7244                                                 capable</fieldlink>
7245             agent, the <code>ClassFileLoadHook</code> event is sent,
7246             allowing a new transformation to be applied
7247           </li>
7248           <li>the transformed class file bytes are installed as the new
7249             definition of the class
7250           </li>
7251         </ul>
7252         See the <eventlink id="ClassFileLoadHook"/> event for more details.
7253         <p/>
7254         The initial class file bytes represent the bytes passed to 
7255         <code>ClassLoader.defineClass</code>
7256         or <code>RedefineClasses</code> (before any transformations
7257         were applied), however they may not exactly match them.
7258         The constant pool may differ in ways described in
7259         <functionlink id="GetConstantPool"/>.
7260         Constant pool indices in the bytecodes of methods will correspond.
7261         Some attributes may not be present.
7262         Where order is not meaningful, for example the order of methods,
7263         order may not be preserved.
7264         <p/>
7265         Retransformation can cause new versions of methods to be installed.
7266         Old method versions may become 
7267         <internallink id="obsoleteMethods">obsolete</internallink>
7268         The new method version will be used on new invokes.  
7269         If a method has active stack frames, those active frames continue to
7270         run the bytecodes of the original method version. 
7271         <p/>
7272         This function does not cause any initialization except that which 
7273         would occur under the customary JVM semantics.
7274         In other words, retransforming a class does not cause its initializers to be
7275         run. The values of static fields will remain as they were
7276         prior to the call.
7277         <p/>
7278         Threads need not be suspended.
7279         <p/>
7280         All breakpoints in the class are cleared.
7281         <p/>
7282         All attributes are updated.
7283         <p/>
7284         Instances of the retransformed class are not affected -- fields retain their
7285         previous values.  
7286         <functionlink id="GetTag">Tags</functionlink> on the instances are
7287         also unaffected.
7288         <p/>
7289         In response to this call, no events other than the
7290         <eventlink id="ClassFileLoadHook"/> event
7291         will be sent.
7292         <p/>
7293         The retransformation may change method bodies, the constant pool and attributes.
7294         The retransformation must not add, remove or rename fields or methods, change the 
7295         signatures of methods, change modifiers, or change inheritance.  
7296         These restrictions may be lifted in future versions.
7297         See the error return description below for information on error codes
7298         returned if an unsupported retransformation is attempted.
7299         The class file bytes are not verified or installed until they have passed
7300         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7301         returned error code reflects the result of the transformations.
7302         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7303         none of the classes to be retransformed will have a new definition installed.
7304         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7305         all of the classes to be retransformed will have their new definitions installed.        
7306       </description>
7307       <origin>new</origin>
7308       <capabilities>
7309         <required id="can_retransform_classes"></required>
7310         <capability id="can_retransform_any_class"></capability>
7311       </capabilities>
7312       <parameters>
7313         <param id="class_count">
7314           <jint min="0"/>
7315           <description>
7316             The number of classes to be retransformed.
7317           </description>
7318         </param>
7319         <param id="classes">
7320           <inbuf incount="class_count"><jclass/></inbuf>
7321           <description>
7322             The array of classes to be retransformed.
7323           </description>
7324         </param>
7325       </parameters>
7326       <errors>
7327         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7328           One of the <paramlink id="classes"/> cannot be modified. 
7329           See <functionlink id="IsModifiableClass"/>.
7330         </error>
7331         <error id="JVMTI_ERROR_INVALID_CLASS">
7332           One of the <paramlink id="classes"/> is not a valid class.
7333         </error>
7334         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7335           A retransformed class file has a version number not supported by this VM.
7336         </error>
7337         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7338           A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>).
7339         </error>
7340         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7341           The retransformed class file definitions would lead to a circular definition 
7342           (the VM would return a <code>ClassCircularityError</code>).
7343         </error>
7344         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7345           The retransformed class file bytes fail verification.
7346         </error>
7347         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7348           The class name defined in a retransformed class file is
7349           different from the name in the old class object.
7350         </error>
7351         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7352           A retransformed class file would require adding a method.
7353         </error>
7354         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7355           A retransformed class file changes a field.
7356         </error>
7357         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7358           A direct superclass is different for a retransformed class file,
7359           or the set of directly implemented
7360           interfaces is different.
7361         </error>
7362         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7363           A retransformed class file does not declare a method
7364           declared in the old class version.
7365         </error>
7366         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7367           A retransformed class file has different class modifiers.
7368         </error>
7369         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7370           A method in the retransformed class file has different modifiers
7371           than its counterpart in the old class version.
7372         </error>
7373       </errors>
7374     </function>
7375 
7376     <function id="RedefineClasses" jkernel="yes" num="87">
7377       <synopsis>Redefine Classes</synopsis>
7378       <typedef id="jvmtiClassDefinition" label="Class redefinition description">
7379         <field id="klass">
7380           <jclass/>
7381             <description>
7382               Class object for this class
7383             </description>
7384         </field>
7385         <field id="class_byte_count">
7386           <jint/>
7387           <description>
7388             Number of bytes defining class (below)
7389           </description>
7390         </field>
7391         <field id="class_bytes">
7392           <inbuf incount="class_byte_count"><uchar/></inbuf>
7393           <description>
7394             Bytes defining class (in <vmspec chapter="4"/>)
7395           </description>
7396         </field>
7397       </typedef>
7398       <description>
7399         All classes given are redefined according to the definitions
7400         supplied.
7401         This function is used to replace the definition of a class
7402         with a new definition, as might be needed in fix-and-continue
7403         debugging.
7404         Where the existing class file bytes are to be transformed, for 
7405         example in
7406         <internallink id="bci">bytecode instrumentation</internallink>,
7407         <functionlink id="RetransformClasses"/> should be used.
7408         <p/>
7409         Redefinition can cause new versions of methods to be installed.
7410         Old method versions may become 
7411         <internallink id="obsoleteMethods">obsolete</internallink>
7412         The new method version will be used on new invokes.  
7413         If a method has active stack frames, those active frames continue to
7414         run the bytecodes of the original method version. 
7415         If resetting of stack frames is desired, use 
7416         <functionlink id="PopFrame"></functionlink>
7417         to pop frames with obsolete method versions.
7418         <p/>
7419         This function does not cause any initialization except that which 
7420         would occur under the customary JVM semantics.
7421         In other words, redefining a class does not cause its initializers to be
7422         run. The values of static fields will remain as they were
7423         prior to the call.
7424         <p/>
7425         Threads need not be suspended.
7426         <p/>
7427         All breakpoints in the class are cleared.
7428         <p/>
7429         All attributes are updated.
7430         <p/>
7431         Instances of the redefined class are not affected -- fields retain their
7432         previous values.  
7433         <functionlink id="GetTag">Tags</functionlink> on the instances are
7434         also unaffected.
7435         <p/>
7436         In response to this call, the <jvmti/> event
7437         <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
7438         will be sent (if enabled), but no other <jvmti/> events will be sent.
7439         <p/>
7440         The redefinition may change method bodies, the constant pool and attributes.
7441         The redefinition must not add, remove or rename fields or methods, change the 
7442         signatures of methods, change modifiers, or change inheritance.  
7443         These restrictions may be lifted in future versions.
7444         See the error return description below for information on error codes
7445         returned if an unsupported redefinition is attempted.
7446         The class file bytes are not verified or installed until they have passed
7447         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7448         returned error code reflects the result of the transformations applied
7449         to the bytes passed into <paramlink id="class_definitions"/>.
7450         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7451         none of the classes to be redefined will have a new definition installed.
7452         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7453         all of the classes to be redefined will have their new definitions installed.        
7454       </description>
7455       <origin>jvmdi</origin>
7456       <capabilities>
7457         <required id="can_redefine_classes"></required>
7458         <capability id="can_redefine_any_class"></capability>
7459       </capabilities>
7460       <parameters>
7461         <param id="class_count">
7462           <jint min="0"/>
7463           <description>
7464             The number of classes specified in <code>class_definitions</code>
7465           </description>
7466         </param>
7467         <param id="class_definitions">
7468           <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
7469           <description>
7470             The array of new class definitions
7471           </description>
7472         </param>
7473       </parameters>
7474       <errors>
7475         <error id="JVMTI_ERROR_NULL_POINTER">
7476           One of <code>class_bytes</code> is <code>NULL</code>.
7477         </error>
7478         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7479           An element of <code>class_definitions</code> cannot be modified.
7480           See <functionlink id="IsModifiableClass"/>.
7481         </error>
7482         <error id="JVMTI_ERROR_INVALID_CLASS">
7483           An element of <code>class_definitions</code> is not a valid class.
7484         </error>
7485         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7486           A new class file has a version number not supported by this VM.
7487         </error>
7488         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7489           A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
7490         </error>
7491         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7492           The new class file definitions would lead to a circular definition 
7493           (the VM would return a <code>ClassCircularityError</code>).
7494         </error>
7495         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7496           The class bytes fail verification.
7497         </error>
7498         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7499           The class name defined in a new class file is
7500           different from the name in the old class object.
7501         </error>
7502         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7503           A new class file would require adding a method.
7504         </error>
7505         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7506           A new class version changes a field.
7507         </error>
7508         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7509           A direct superclass is different for a new class
7510           version, or the set of directly implemented
7511           interfaces is different.
7512         </error>
7513         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7514           A new class version does not declare a method
7515           declared in the old class version.
7516         </error>
7517         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7518           A new class version has different modifiers.
7519         </error>
7520         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7521           A method in the new class version has different modifiers
7522           than its counterpart in the old class version.
7523         </error>
7524       </errors>
7525     </function>
7526 
7527   </category>
7528 
7529   <category id="object" label="Object">
7530 
7531     <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
7532       <synopsis>Get Object Size</synopsis>
7533       <description>
7534         For the object indicated by <code>object</code>,
7535         return via <code>size_ptr</code> the size of the object.
7536         This size is an implementation-specific approximation of
7537         the amount of storage consumed by this object. 
7538         It may include some or all of the object's overhead, and thus
7539         is useful for comparison within an implementation but not
7540         between implementations.
7541         The estimate may change during a single invocation of the JVM.
7542       </description>
7543       <origin>new</origin>
7544       <capabilities>
7545       </capabilities>
7546       <parameters>
7547         <param id="object">
7548           <jobject/>
7549             <description>
7550               The object to query.
7551             </description>
7552         </param>
7553         <param id="size_ptr">
7554           <outptr><jlong/></outptr>
7555           <description>
7556             On return, points to the object's size in bytes.
7557           </description>
7558         </param>
7559       </parameters>
7560       <errors>
7561       </errors>
7562     </function>
7563 
7564     <function id="GetObjectHashCode" phase="start" num="58">
7565       <synopsis>Get Object Hash Code</synopsis>
7566       <description>
7567         For the object indicated by <code>object</code>,
7568         return via <code>hash_code_ptr</code> a hash code.
7569         This hash code could be used to maintain a hash table of object references,
7570         however, on some implementations this can cause significant performance 
7571         impacts--in most cases 
7572         <internallink id="Heap">tags</internallink> 
7573         will be a more efficient means of associating information with objects.
7574         This function guarantees 
7575         the same hash code value for a particular object throughout its life
7576       </description>
7577       <origin>jvmdi</origin>
7578       <capabilities>
7579       </capabilities>
7580       <parameters>
7581         <param id="object">
7582           <jobject/>
7583             <description>
7584               The object to query.
7585             </description>
7586         </param>
7587         <param id="hash_code_ptr">
7588           <outptr><jint/></outptr>
7589           <description>
7590             On return, points to the object's hash code.
7591           </description>
7592         </param>
7593       </parameters>
7594       <errors>
7595       </errors>
7596     </function>
7597 
7598     <function id="GetObjectMonitorUsage" num="59">
7599       <synopsis>Get Object Monitor Usage</synopsis>
7600       <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
7601         <field id="owner">
7602           <jthread/>
7603             <description>
7604               The thread owning this monitor, or <code>NULL</code> if unused
7605             </description>
7606         </field>
7607         <field id="entry_count">
7608           <jint/>
7609           <description>
7610             The number of times the owning thread has entered the monitor
7611           </description>
7612         </field>
7613         <field id="waiter_count">
7614           <jint/>
7615           <description>
7616             The number of threads waiting to own this monitor
7617           </description>
7618         </field>
7619         <field id="waiters">
7620           <allocfieldbuf><jthread/></allocfieldbuf>
7621             <description>
7622               The <code>waiter_count</code> waiting threads
7623             </description>
7624         </field>
7625         <field id="notify_waiter_count">
7626           <jint/>
7627           <description>
7628             The number of threads waiting to be notified by this monitor
7629           </description>
7630         </field>
7631         <field id="notify_waiters">
7632           <allocfieldbuf><jthread/></allocfieldbuf>
7633             <description>
7634               The <code>notify_waiter_count</code> threads waiting to be notified
7635             </description>
7636         </field>
7637       </typedef>
7638       <description>
7639         Get information about the object's monitor.
7640         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 
7641         are filled in with information about usage of the monitor.
7642           <todo>
7643             Decide and then clarify suspend requirements.
7644           </todo>
7645       </description>
7646       <origin>jvmdi</origin>
7647       <capabilities>
7648         <required id="can_get_monitor_info"></required>
7649       </capabilities>
7650       <parameters>
7651         <param id="object">
7652           <jobject/>
7653             <description>
7654               The object to query.
7655             </description>
7656         </param>
7657         <param id="info_ptr">
7658           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
7659           <description>
7660             On return, filled with monitor information for the 
7661             specified object.
7662           </description>
7663         </param>
7664       </parameters>
7665       <errors>
7666       </errors>
7667     </function>
7668 
7669     <elide>
7670     <function id="GetObjectMonitors" num="116">
7671       <synopsis>Get Object Monitors</synopsis>
7672       <description>
7673         Return the list of object monitors.
7674         <p/>
7675         Note: details about each monitor can be examined with 
7676         <functionlink id="GetObjectMonitorUsage"></functionlink>.
7677       </description>
7678       <origin>new</origin>
7679       <capabilities>
7680         <required id="can_get_monitor_info"></required>
7681       </capabilities>
7682       <parameters>
7683         <param id="monitorCnt">
7684           <outptr><jint/></outptr>
7685           <description>
7686             On return, pointer to the number 
7687             of monitors returned in <code>monitors_ptr</code>.
7688           </description>
7689         </param>
7690         <param id="monitors_ptr">
7691           <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
7692             <description>
7693               On return, pointer to the monitor list.
7694             </description>
7695         </param>
7696       </parameters>
7697       <errors>
7698       </errors>
7699     </function>
7700     </elide>
7701 
7702   </category>
7703 
7704   <category id="fieldCategory" label="Field">
7705 
7706     <intro>
7707     </intro>
7708 
7709     <function id="GetFieldName" phase="start" num="60">
7710       <synopsis>Get Field Name (and Signature)</synopsis>
7711       <description>
7712         For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
7713         return the field name via <paramlink id="name_ptr"/> and field signature via
7714         <paramlink id="signature_ptr"/>.
7715         <p/>
7716         Field signatures are defined in the JNI Specification and 
7717         are referred to as <code>field descriptors</code> in
7718         <vmspec chapter="4.3.2"/>.
7719       </description>
7720       <origin>jvmdiClone</origin>
7721       <capabilities>
7722       </capabilities>
7723       <parameters>
7724         <param id="klass">
7725           <jclass field="field"/>
7726             <description>
7727               The class of the field to query.
7728             </description>
7729         </param>
7730         <param id="field">
7731           <jfieldID class="klass"/>
7732             <description>
7733               The field to query.
7734             </description>
7735         </param>
7736         <param id="name_ptr">
7737           <allocbuf>
7738             <char/>
7739             <nullok>the name is not returned</nullok>
7740           </allocbuf>
7741           <description>
7742             On return, points to the field name, encoded as a
7743             <internallink id="mUTF">modified UTF-8</internallink> string.
7744           </description>
7745         </param>
7746         <param id="signature_ptr">
7747           <allocbuf>
7748             <char/>
7749             <nullok>the signature is not returned</nullok>
7750           </allocbuf>
7751           <description>
7752             On return, points to the field signature, encoded as a
7753             <internallink id="mUTF">modified UTF-8</internallink> string.
7754           </description>
7755         </param>
7756         <param id="generic_ptr">
7757           <allocbuf>
7758             <char/>           
7759             <nullok>the generic signature is not returned</nullok>
7760           </allocbuf>
7761           <description>
7762             On return, points to the generic signature of the field, encoded as a
7763             <internallink id="mUTF">modified UTF-8</internallink> string.
7764             If there is no generic signature attribute for the field, then,
7765             on return, points to <code>NULL</code>. 
7766           </description>
7767         </param>
7768       </parameters>
7769       <errors>
7770       </errors>
7771     </function>
7772 
7773     <function id="GetFieldDeclaringClass" phase="start" num="61">
7774       <synopsis>Get Field Declaring Class</synopsis>
7775       <description>
7776         For the field indicated by <code>klass</code> and <code>field</code>
7777         return the class that defined it via <code>declaring_class_ptr</code>.
7778         The declaring class will either be <code>klass</code>, a superclass, or
7779         an implemented interface.
7780       </description>
7781       <origin>jvmdi</origin>
7782       <capabilities>
7783       </capabilities>
7784       <parameters>
7785         <param id="klass">
7786           <jclass field="field"/>
7787             <description>
7788               The class to query.
7789             </description>
7790         </param>
7791         <param id="field">
7792           <jfieldID class="klass"/>
7793             <description>
7794               The field to query.
7795             </description>
7796         </param>
7797         <param id="declaring_class_ptr">
7798           <outptr><jclass/></outptr>
7799             <description>
7800               On return, points to the declaring class
7801             </description>
7802         </param>
7803       </parameters>
7804       <errors>
7805       </errors>
7806     </function>
7807 
7808     <function id="GetFieldModifiers" phase="start" num="62">
7809       <synopsis>Get Field Modifiers</synopsis>
7810       <description>
7811         For the field indicated by <code>klass</code> and <code>field</code>
7812         return the access flags via <code>modifiers_ptr</code>.
7813         Access flags are defined in <vmspec chapter="4"/>.
7814       </description>
7815       <origin>jvmdi</origin>
7816       <capabilities>
7817       </capabilities>
7818       <parameters>
7819         <param id="klass">
7820           <jclass field="field"/>
7821             <description>
7822               The class to query.
7823             </description>
7824         </param>
7825         <param id="field">
7826           <jfieldID class="klass"/>
7827             <description>
7828               The field to query.
7829             </description>
7830         </param>
7831         <param id="modifiers_ptr">
7832           <outptr><jint/></outptr>
7833           <description>
7834             On return, points to the access flags.
7835           </description>
7836         </param>
7837       </parameters>
7838       <errors>
7839       </errors>
7840     </function>
7841 
7842     <function id="IsFieldSynthetic" phase="start" num="63">
7843       <synopsis>Is Field Synthetic</synopsis>
7844       <description>
7845         For the field indicated by <code>klass</code> and <code>field</code>, return a
7846         value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
7847         Synthetic fields are generated by the compiler but not present in the 
7848         original source code.
7849       </description>
7850       <origin>jvmdi</origin>
7851       <capabilities>
7852         <required id="can_get_synthetic_attribute"></required>
7853       </capabilities>
7854       <parameters>
7855         <param id="klass">
7856           <jclass field="field"/>
7857             <description>
7858               The class of the field to query.
7859             </description>
7860         </param>
7861         <param id="field">
7862           <jfieldID class="klass"/>
7863             <description>
7864               The field to query.
7865             </description>
7866         </param>
7867         <param id="is_synthetic_ptr">
7868           <outptr><jboolean/></outptr>
7869           <description>
7870             On return, points to the boolean result of this function.
7871           </description>
7872         </param>
7873       </parameters>
7874       <errors>
7875       </errors>
7876     </function>
7877 
7878   </category>
7879 
7880   <category id="method" label="Method">
7881 
7882     <intro>
7883       These functions provide information about a method (represented as a
7884       <typelink id="jmethodID"/>) and set how methods are processed.
7885     </intro>
7886 
7887     <intro id="obsoleteMethods" label="Obsolete Methods">
7888       The functions <functionlink id="RetransformClasses"/> and
7889       <functionlink id="RedefineClasses"/> can cause new versions
7890       of methods to be installed.
7891       An original version of a method is considered equivalent
7892       to the new version if:
7893       <ul>
7894         <li>their bytecodes are the same except for indices into the
7895           constant pool and </li>
7896         <li>the referenced constants are equal.</li>
7897       </ul>
7898       An original method version which is not equivalent to the
7899       new method version is called obsolete and is assigned a new method ID;
7900       the original method ID now refers to the new method version.
7901       A method ID can be tested for obsolescence with 
7902       <functionlink id="IsMethodObsolete"/>.
7903     </intro>
7904 
7905     <function id="GetMethodName" phase="start" num="64">
7906       <synopsis>Get Method Name (and Signature)</synopsis>
7907       <description>
7908         For the method indicated by <code>method</code>,
7909         return the method name via <code>name_ptr</code> and method signature via
7910         <code>signature_ptr</code>.
7911         <p/>
7912         Method signatures are defined in the JNI Specification and are 
7913         referred to as <code>method descriptors</code> in 
7914         <vmspec chapter="4.3.3"/>.
7915         Note this is different
7916         than method signatures as defined in the <i>Java Language Specification</i>.
7917       </description>
7918       <origin>jvmdiClone</origin>
7919       <capabilities>
7920       </capabilities>
7921       <parameters>
7922         <param id="method">
7923           <jmethodID/>
7924             <description>
7925               The method to query.
7926             </description>
7927         </param>
7928         <param id="name_ptr">
7929           <allocbuf>
7930             <char/>
7931             <nullok>the name is not returned</nullok>
7932           </allocbuf>
7933           <description>
7934             On return, points to the method name, encoded as a
7935             <internallink id="mUTF">modified UTF-8</internallink> string.
7936           </description>
7937         </param>
7938         <param id="signature_ptr">
7939           <allocbuf>
7940             <char/>
7941             <nullok>the signature is not returned</nullok>
7942           </allocbuf>
7943           <description>
7944             On return, points to the method signature, encoded as a
7945             <internallink id="mUTF">modified UTF-8</internallink> string.
7946           </description>
7947         </param>
7948         <param id="generic_ptr">
7949           <allocbuf>
7950             <char/>           
7951             <nullok>the generic signature is not returned</nullok>
7952           </allocbuf>
7953           <description>
7954             On return, points to the generic signature of the method, encoded as a
7955             <internallink id="mUTF">modified UTF-8</internallink> string.
7956             If there is no generic signature attribute for the method, then,
7957             on return, points to <code>NULL</code>. 
7958           </description>
7959         </param>
7960       </parameters>
7961       <errors>
7962       </errors>
7963     </function>
7964 
7965     <function id="GetMethodDeclaringClass" phase="start" num="65">
7966       <synopsis>Get Method Declaring Class</synopsis>
7967       <description>
7968         For the method indicated by <code>method</code>,
7969         return the class that defined it via <code>declaring_class_ptr</code>.
7970       </description>
7971       <origin>jvmdi</origin>
7972       <capabilities>
7973       </capabilities>
7974       <parameters>
7975         <param id="klass">
7976           <jclass method="method"/>
7977             <description>
7978               The class to query.
7979             </description>
7980         </param>
7981         <param id="method">
7982           <jmethodID class="klass"/>
7983             <description>
7984               The method to query.
7985             </description>
7986         </param>
7987         <param id="declaring_class_ptr">
7988           <outptr><jclass/></outptr>
7989             <description>
7990               On return, points to the declaring class
7991             </description>
7992         </param>
7993       </parameters>
7994       <errors>
7995       </errors>
7996     </function>
7997 
7998     <function id="GetMethodModifiers" phase="start" num="66">
7999       <synopsis>Get Method Modifiers</synopsis>
8000       <description>
8001         For the method indicated by <code>method</code>,
8002         return the access flags via <code>modifiers_ptr</code>.
8003         Access flags are defined in <vmspec chapter="4"/>.
8004       </description>
8005       <origin>jvmdi</origin>
8006       <capabilities>
8007       </capabilities>
8008       <parameters>
8009         <param id="klass">
8010           <jclass method="method"/>
8011             <description>
8012               The class to query.
8013             </description>
8014         </param>
8015         <param id="method">
8016           <jmethodID class="klass"/>
8017             <description>
8018               The method to query.
8019             </description>
8020         </param>
8021         <param id="modifiers_ptr">
8022           <outptr><jint/></outptr>
8023           <description>
8024             On return, points to the access flags.
8025           </description>
8026         </param>
8027       </parameters>
8028       <errors>
8029       </errors>
8030     </function>
8031 
8032     <function id="GetMaxLocals" phase="start" num="68">
8033       <synopsis>Get Max Locals</synopsis>
8034       <description>
8035           For the method indicated by <code>method</code>,
8036           return the number of local variable slots used by the method,
8037           including the local variables used to pass parameters to the
8038           method on its invocation. 
8039           <p/>
8040           See <code>max_locals</code> in <vmspec chapter="4.7.3"/>.
8041       </description>
8042       <origin>jvmdi</origin>
8043       <capabilities>
8044       </capabilities>
8045       <parameters>
8046         <param id="klass">
8047           <jclass method="method"/>
8048             <description>
8049               The class to query.
8050             </description>
8051         </param>
8052         <param id="method">
8053           <jmethodID class="klass" native="error"/>
8054             <description>
8055               The method to query.
8056             </description>
8057         </param>
8058         <param id="max_ptr">
8059           <outptr><jint/></outptr>
8060           <description>
8061             On return, points to the maximum number of local slots
8062           </description>
8063         </param>
8064       </parameters>
8065       <errors>
8066       </errors>
8067     </function>
8068 
8069     <function id="GetArgumentsSize" phase="start" num="69">
8070       <synopsis>Get Arguments Size</synopsis>
8071       <description>
8072         For the method indicated by <code>method</code>,
8073         return via <code>max_ptr</code> the number of local variable slots used
8074         by the method's arguments.
8075         Note that two-word arguments use two slots.
8076       </description>
8077       <origin>jvmdi</origin>
8078       <capabilities>
8079       </capabilities>
8080       <parameters>
8081         <param id="klass">
8082           <jclass method="method"/>
8083             <description>
8084               The class to query.
8085             </description>
8086         </param>
8087         <param id="method">
8088           <jmethodID class="klass" native="error"/>
8089             <description>
8090               The method to query.
8091             </description>
8092         </param>
8093         <param id="size_ptr">
8094           <outptr><jint/></outptr>
8095           <description>
8096             On return, points to the number of argument slots
8097           </description>
8098         </param>
8099       </parameters>
8100       <errors>
8101       </errors>
8102     </function>
8103 
8104     <function id="GetLineNumberTable" phase="start" num="70">
8105       <synopsis>Get Line Number Table</synopsis>
8106       <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
8107         <field id="start_location">
8108           <jlocation/>
8109           <description>
8110             the <datalink id="jlocation"></datalink> where the line begins
8111           </description>
8112         </field>
8113         <field id="line_number">
8114           <jint/>
8115           <description>
8116             the line number
8117           </description>
8118         </field>
8119       </typedef>
8120       <description>
8121         For the method indicated by <code>method</code>,
8122         return a table of source line number entries. The size of the table is
8123         returned via <code>entry_count_ptr</code> and the table itself is
8124         returned via <code>table_ptr</code>. 
8125       </description>
8126       <origin>jvmdi</origin>
8127       <capabilities>
8128         <required id="can_get_line_numbers"></required>
8129       </capabilities>
8130       <parameters>
8131         <param id="klass">
8132           <jclass method="method"/>
8133             <description>
8134               The class to query.
8135             </description>
8136         </param>
8137         <param id="method">
8138           <jmethodID class="klass" native="error"/>
8139             <description>
8140               The method to query.
8141             </description>
8142         </param>
8143         <param id="entry_count_ptr">
8144           <outptr><jint/></outptr>
8145           <description>
8146             On return, points to the number of entries in the table
8147           </description>
8148         </param>
8149         <param id="table_ptr">
8150           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
8151           <description>
8152             On return, points to the line number table pointer.
8153           </description>
8154         </param>
8155       </parameters>
8156       <errors>
8157         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
8158           Class information does not include line numbers.
8159         </error>
8160       </errors>
8161     </function>
8162 
8163     <function id="GetMethodLocation" phase="start" num="71">
8164       <synopsis>Get Method Location</synopsis>
8165       <description>
8166         For the method indicated by <code>method</code>,
8167         return the beginning and ending addresses through
8168         <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
8169         conventional byte code indexing scheme, 
8170         <code>start_location_ptr</code> will always point to zero
8171         and <code>end_location_ptr</code> 
8172         will always point to the byte code count minus one. 
8173       </description>
8174       <origin>jvmdi</origin>
8175       <capabilities>
8176       </capabilities>
8177       <parameters>
8178         <param id="klass">
8179           <jclass method="method"/>
8180             <description>
8181               The class to query.
8182             </description>
8183         </param>
8184         <param id="method">
8185           <jmethodID class="klass" native="error"/>
8186             <description>
8187               The method to query.
8188             </description>
8189         </param>
8190         <param id="start_location_ptr">
8191           <outptr><jlocation/></outptr>
8192           <description>
8193             On return, points to the first location, or 
8194             <code>-1</code> if location information is not available.
8195             If the information is available and 
8196             <functionlink id="GetJLocationFormat"></functionlink>
8197             returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
8198             then this will always be zero.
8199           </description>
8200         </param>
8201         <param id="end_location_ptr">
8202           <outptr><jlocation/></outptr>
8203           <description>
8204             On return, points to the last location,
8205             or <code>-1</code> if location information is not available.
8206           </description>
8207         </param>
8208       </parameters>
8209       <errors>
8210         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
8211           Class information does not include method sizes.
8212         </error>
8213       </errors>
8214     </function>
8215 
8216     <function id="GetLocalVariableTable" num="72">
8217       <synopsis>Get Local Variable Table</synopsis>
8218       <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
8219         <field id="start_location">
8220           <jlocation/>
8221           <description>
8222             The code array index where the local variable is first valid
8223             (that is, where it must have a value).
8224           </description>
8225         </field>
8226         <field id="length">
8227           <jint/>
8228           <description>
8229             The length of the valid section for this local variable.
8230             The last code array index where the local variable is valid 
8231             is <code>start_location + length</code>.
8232           </description>
8233         </field>
8234         <field id="name">
8235           <allocfieldbuf><char/></allocfieldbuf>
8236           <description>
8237             The local variable name, encoded as a
8238             <internallink id="mUTF">modified UTF-8</internallink> string.
8239           </description>
8240         </field>
8241         <field id="signature">
8242           <allocfieldbuf><char/></allocfieldbuf>
8243           <description>
8244             The local variable's type signature, encoded as a
8245             <internallink id="mUTF">modified UTF-8</internallink> string.
8246             The signature format is the same as that defined in
8247             <vmspec chapter="4.3.2"/>.
8248           </description>
8249         </field>
8250         <field id="generic_signature">
8251           <allocfieldbuf><char/></allocfieldbuf>
8252           <description>
8253             The local variable's generic signature, encoded as a
8254             <internallink id="mUTF">modified UTF-8</internallink> string.
8255             The value of this field will be <code>NULL</code> for any local 
8256             variable which does not have a generic type.
8257           </description>
8258         </field>
8259         <field id="slot">
8260           <jint/>
8261           <description>
8262             The local variable's slot.  See <internallink id="local">Local Variables</internallink>.
8263           </description>
8264         </field>
8265       </typedef>
8266       <description>
8267         Return local variable information.
8268       </description>
8269       <origin>jvmdiClone</origin>
8270       <capabilities>
8271         <required id="can_access_local_variables"></required>
8272       </capabilities>
8273       <parameters>
8274         <param id="method">
8275           <jmethodID native="error"/>
8276             <description>
8277               The method to query.
8278             </description>
8279         </param>
8280         <param id="entry_count_ptr">
8281           <outptr><jint/></outptr>
8282           <description>
8283             On return, points to the number of entries in the table
8284           </description>
8285         </param>
8286         <param id="table_ptr">
8287           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
8288           <description>
8289             On return, points to an array of local variable table entries.
8290           </description>
8291         </param>
8292       </parameters>
8293       <errors>
8294         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8295           Class information does not include local variable
8296           information.
8297         </error>
8298       </errors>
8299     </function>
8300 
8301     <function id="GetBytecodes" phase="start" num="75">
8302       <synopsis>Get Bytecodes</synopsis>
8303       <description>
8304         For the method indicated by <code>method</code>,
8305         return the byte codes that implement the method. The number of
8306         bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes
8307         themselves are returned via <code>bytecodes_ptr</code>.
8308       </description>
8309       <origin>jvmdi</origin>
8310       <capabilities>
8311         <required id="can_get_bytecodes"></required>
8312       </capabilities>
8313       <parameters>
8314         <param id="klass">
8315           <jclass method="method"/>
8316             <description>
8317               The class to query.
8318             </description>
8319         </param>
8320         <param id="method">
8321           <jmethodID class="klass" native="error"/>
8322             <description>
8323               The method to query.
8324             </description>
8325         </param>
8326         <param id="bytecode_count_ptr">
8327           <outptr><jint/></outptr>
8328           <description>
8329             On return, points to the length of the byte code array
8330           </description>
8331         </param>
8332         <param id="bytecodes_ptr">
8333           <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
8334           <description>
8335             On return, points to the pointer to the byte code array
8336           </description>
8337         </param>
8338       </parameters>
8339       <errors>
8340       </errors>
8341     </function>
8342 
8343     <function id="IsMethodNative" phase="start" num="76">
8344       <synopsis>Is Method Native</synopsis>
8345       <description>
8346         For the method indicated by <code>method</code>, return a
8347         value indicating whether the method is native via <code>is_native_ptr</code>
8348       </description>
8349       <origin>jvmdi</origin>
8350       <capabilities>
8351       </capabilities>
8352       <parameters>
8353         <param id="klass">
8354           <jclass method="method"/>
8355             <description>
8356               The class to query.
8357             </description>
8358         </param>
8359         <param id="method">
8360           <jmethodID class="klass"/>
8361             <description>
8362               The method to query.
8363             </description>
8364         </param>
8365         <param id="is_native_ptr">
8366           <outptr><jboolean/></outptr>
8367           <description>
8368             On return, points to the boolean result of this function.
8369           </description>
8370         </param>
8371       </parameters>
8372       <errors>
8373       </errors>
8374     </function>
8375 
8376     <function id="IsMethodSynthetic" phase="start" num="77">
8377       <synopsis>Is Method Synthetic</synopsis>
8378       <description>
8379         For the method indicated by <code>method</code>, return a
8380         value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
8381         Synthetic methods are generated by the compiler but not present in the 
8382         original source code.
8383       </description>
8384       <origin>jvmdi</origin>
8385       <capabilities>
8386         <required id="can_get_synthetic_attribute"></required>
8387       </capabilities>
8388       <parameters>
8389         <param id="klass">
8390           <jclass method="method"/>
8391             <description>
8392               The class to query.
8393             </description>
8394         </param>
8395         <param id="method">
8396           <jmethodID class="klass"/>
8397             <description>
8398               The method to query.
8399             </description>
8400         </param>
8401         <param id="is_synthetic_ptr">
8402           <outptr><jboolean/></outptr>
8403           <description>
8404             On return, points to the boolean result of this function.
8405           </description>
8406         </param>
8407       </parameters>
8408       <errors>
8409       </errors>
8410     </function>
8411 
8412     <function id="IsMethodObsolete" phase="start" num="91">
8413       <synopsis>Is Method Obsolete</synopsis>
8414       <description>
8415         Determine if a method ID refers to an
8416         <internallink id="obsoleteMethods">obsolete</internallink>
8417         method version.
8418       </description>
8419       <origin>jvmdi</origin>
8420       <capabilities>
8421       </capabilities>
8422       <parameters>
8423         <param id="klass">
8424           <jclass method="method"/>
8425             <description>
8426               The class to query.
8427             </description>
8428         </param>
8429         <param id="method">
8430           <jmethodID class="klass"/>
8431             <description>
8432               The method ID to query.
8433             </description>
8434         </param>
8435         <param id="is_obsolete_ptr">
8436           <outptr><jboolean/></outptr>
8437           <description>
8438             On return, points to the boolean result of this function.
8439           </description>
8440         </param>
8441       </parameters>
8442       <errors>
8443       </errors>
8444     </function>
8445 
8446     <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
8447       <synopsis>Set Native Method Prefix</synopsis>
8448       <description>
8449         This function modifies the failure handling of
8450         native method resolution by allowing retry
8451         with a prefix applied to the name.
8452         When used with the 
8453         <eventlink id="ClassFileLoadHook">ClassFileLoadHook
8454         event</eventlink>, it enables native methods to be
8455         <internallink id="bci">instrumented</internallink>.
8456         <p/>
8457         Since native methods cannot be directly instrumented
8458         (they have no bytecodes), they must be wrapped with
8459         a non-native method which can be instrumented.
8460         For example, if we had:
8461         <example>
8462 native boolean foo(int x);</example>
8463         <p/>
8464         We could transform the class file (with the 
8465         ClassFileLoadHook event) so that this becomes:
8466         <example>
8467 boolean foo(int x) {
8468   <i>... record entry to foo ...</i>
8469   return wrapped_foo(x);
8470 }
8471 
8472 native boolean wrapped_foo(int x);</example>
8473         <p/>
8474         Where foo becomes a wrapper for the actual native method
8475         with the appended prefix "wrapped_".  Note that
8476         "wrapped_" would be a poor choice of prefix since it
8477         might conceivably form the name of an existing method
8478         thus something like "$$$MyAgentWrapped$$$_" would be
8479         better but would make these examples less readable.
8480         <p/>
8481         The wrapper will allow data to be collected on the native
8482         method call, but now the problem becomes linking up the  
8483         wrapped method with the native implementation.  
8484         That is, the method <code>wrapped_foo</code> needs to be 
8485         resolved to the native implementation of <code>foo</code>,
8486         which might be:
8487         <example>
8488 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
8489         <p/>
8490         This function allows the prefix to be specified and the
8491         proper resolution to occur.  
8492         Specifically, when the standard resolution fails, the
8493         resolution is retried taking the prefix into consideration.
8494         There are two ways that resolution occurs, explicit
8495         resolution with the JNI function <code>RegisterNatives</code>
8496         and the normal automatic resolution.  For 
8497         <code>RegisterNatives</code>, the VM will attempt this 
8498         association:
8499         <example>
8500 method(foo) -> nativeImplementation(foo)</example>
8501         <p/>
8502         When this fails, the resolution will be retried with
8503         the specified prefix prepended to the method name, 
8504         yielding the correct resolution:
8505         <example>
8506 method(wrapped_foo) -> nativeImplementation(foo)</example>
8507         <p/>
8508         For automatic resolution, the VM will attempt:
8509         <example>
8510 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
8511         <p/>
8512         When this fails, the resolution will be retried with
8513         the specified prefix deleted from the implementation name, 
8514         yielding the correct resolution:
8515         <example>
8516 method(wrapped_foo) -> nativeImplementation(foo)</example>
8517         <p/>
8518         Note that since the prefix is only used when standard
8519         resolution fails, native methods can be wrapped selectively.
8520         <p/>
8521         Since each <jvmti/> environment is independent and
8522         can do its own transformation of the bytecodes, more 
8523         than one layer of wrappers may be applied. Thus each
8524         environment needs its own prefix.  Since transformations
8525         are applied in order, the prefixes, if applied, will
8526         be applied in the same order.
8527         The order of transformation application is described in
8528         the <eventlink id="ClassFileLoadHook"/> event.
8529         Thus if three environments applied
8530         wrappers, <code>foo</code> might become 
8531         <code>$env3_$env2_$env1_foo</code>.  But if, say,
8532         the second environment did not apply a wrapper to
8533         <code>foo</code> it would be just 
8534         <code>$env3_$env1_foo</code>.  To be able to 
8535         efficiently determine the sequence of prefixes,
8536         an intermediate prefix is only applied if its non-native
8537         wrapper exists.  Thus, in the last example, even though 
8538         <code>$env1_foo</code> is not a native method, the
8539         <code>$env1_</code> prefix is applied since 
8540         <code>$env1_foo</code> exists.
8541         <p/>
8542         Since the prefixes are used at resolution time
8543         and since resolution may be arbitrarily delayed, a
8544         native method prefix must remain set as long as there 
8545         are corresponding prefixed native methods.
8546       </description>
8547       <origin>new</origin>
8548       <capabilities>
8549         <required id="can_set_native_method_prefix"></required>
8550       </capabilities>
8551       <parameters>
8552         <param id="prefix">
8553           <inbuf>
8554             <char/>
8555             <nullok>
8556               any existing prefix in this environment is cancelled
8557             </nullok>
8558           </inbuf>
8559           <description>
8560             The prefix to apply, encoded as a
8561             <internallink id="mUTF">modified UTF-8</internallink> string.
8562           </description>
8563         </param>
8564       </parameters>
8565       <errors>
8566       </errors>
8567     </function>
8568 
8569     <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
8570       <synopsis>Set Native Method Prefixes</synopsis>
8571       <description>
8572          For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
8573          will provide all needed native method prefixing.
8574          For a meta-agent that performs multiple independent class
8575          file transformations (for example as a proxy for another
8576          layer of agents) this function allows each transformation
8577          to have its own prefix.  
8578          The prefixes are applied in the order supplied and are
8579          processed in the same manor as described for the
8580          application of prefixes from multiple <jvmti/> environments
8581          in <functionlink id="SetNativeMethodPrefix"/>.
8582          <p/>
8583          Any previous prefixes are replaced.  Thus, calling this
8584          function with a <paramlink id="prefix_count"/> of <code>0</code>
8585          disables prefixing in this environment.
8586          <p/>
8587          <functionlink id="SetNativeMethodPrefix"/> and this function
8588          are the two ways to set the prefixes.  
8589          Calling <code>SetNativeMethodPrefix</code> with 
8590          a prefix is the same as calling this function with 
8591          <paramlink id="prefix_count"/> of <code>1</code>. 
8592          Calling <code>SetNativeMethodPrefix</code> with 
8593          <code>NULL</code> is the same as calling this function with 
8594          <paramlink id="prefix_count"/> of <code>0</code>. 
8595       </description>
8596       <origin>new</origin>
8597       <capabilities>
8598         <required id="can_set_native_method_prefix"></required>
8599       </capabilities>
8600       <parameters>
8601         <param id="prefix_count">
8602           <jint min="0"/>
8603             <description>
8604               The number of prefixes to apply.
8605             </description>
8606         </param>
8607         <param id="prefixes">
8608           <agentbuf>
8609             <char/>
8610           </agentbuf>
8611           <description>
8612             The prefixes to apply for this environment, each encoded as a
8613             <internallink id="mUTF">modified UTF-8</internallink> string.
8614           </description>
8615         </param>
8616       </parameters>
8617       <errors>
8618       </errors>
8619     </function>
8620 
8621   </category>
8622 
8623   <category id="RawMonitors" label="Raw Monitor">
8624 
8625     <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
8626       <synopsis>Create Raw Monitor</synopsis>
8627       <description>
8628         Create a raw monitor.
8629       </description>
8630       <origin>jvmdi</origin>
8631       <capabilities>
8632       </capabilities>
8633       <parameters>
8634         <param id="name">
8635           <inbuf><char/></inbuf>
8636           <description>
8637             A name to identify the monitor, encoded as a
8638             <internallink id="mUTF">modified UTF-8</internallink> string.
8639           </description>
8640         </param>
8641         <param id="monitor_ptr">
8642           <outptr><jrawMonitorID/></outptr>
8643           <description>
8644             On return, points to the created monitor.
8645           </description>
8646         </param>
8647       </parameters>
8648       <errors>
8649       </errors>
8650     </function>
8651 
8652     <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
8653       <synopsis>Destroy Raw Monitor</synopsis>
8654       <description>
8655         Destroy the raw monitor.
8656         If the monitor being destroyed has been entered by this thread, it will be
8657         exited before it is destroyed.
8658         If the monitor being destroyed has been entered by another thread,
8659         an error will be returned and the monitor will not be destroyed.
8660       </description>
8661       <origin>jvmdi</origin>
8662       <capabilities>
8663       </capabilities>
8664       <parameters>
8665         <param id="monitor">
8666           <jrawMonitorID/>
8667           <description>
8668             The monitor
8669           </description>
8670         </param>
8671       </parameters>
8672       <errors>
8673         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8674           Not monitor owner
8675         </error>        
8676       </errors>
8677     </function>
8678 
8679     <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
8680       <synopsis>Raw Monitor Enter</synopsis>
8681       <description>
8682         Gain exclusive ownership of a raw monitor.  
8683         The same thread may enter a monitor more then once.
8684         The thread must
8685         <functionlink id="RawMonitorExit">exit</functionlink>
8686         the monitor the same number of times as it is entered.
8687         If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
8688         and has not exited when attached threads come into existence, the enter
8689         is considered to have occurred on the main thread.
8690       </description>
8691       <origin>jvmdi</origin>
8692       <capabilities>
8693       </capabilities>
8694       <parameters>
8695         <param id="monitor">
8696           <jrawMonitorID/>
8697           <description>
8698             The monitor
8699           </description>
8700         </param>
8701       </parameters>
8702       <errors>
8703       </errors>
8704     </function>
8705 
8706     <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
8707       <synopsis>Raw Monitor Exit</synopsis>
8708       <description>
8709         Release exclusive ownership of a raw monitor.
8710       </description>
8711       <origin>jvmdi</origin>
8712       <capabilities>
8713       </capabilities>
8714       <parameters>
8715         <param id="monitor">
8716           <jrawMonitorID/>
8717           <description>
8718             The monitor
8719           </description>
8720         </param>
8721       </parameters>
8722       <errors>
8723         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8724           Not monitor owner
8725         </error>
8726       </errors>
8727     </function>
8728 
8729     <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
8730       <synopsis>Raw Monitor Wait</synopsis>
8731       <description>
8732         Wait for notification of the raw monitor.
8733         <p/>
8734         Causes the current thread to wait until either another thread calls 
8735         <functionlink id="RawMonitorNotify"/> or 
8736         <functionlink id="RawMonitorNotifyAll"/> 
8737         for the specified raw monitor, or the specified
8738         <paramlink id="millis">timeout</paramlink>
8739         has elapsed.
8740       </description>
8741       <origin>jvmdi</origin>
8742       <capabilities>
8743       </capabilities>
8744       <parameters>
8745         <param id="monitor">
8746           <jrawMonitorID/>
8747           <description>
8748             The monitor
8749           </description>
8750         </param>
8751         <param id="millis">
8752           <jlong/>
8753           <description>
8754             The timeout, in milliseconds.  If the timeout is
8755             zero, then real time is not taken into consideration
8756             and the thread simply waits until notified.
8757           </description>
8758         </param>
8759       </parameters>
8760       <errors>
8761         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8762           Not monitor owner
8763         </error>
8764         <error id="JVMTI_ERROR_INTERRUPT"> 
8765           Wait was interrupted, try again
8766         </error>
8767       </errors>
8768     </function>
8769 
8770     <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
8771       <synopsis>Raw Monitor Notify</synopsis>
8772       <description>
8773         Notify a single thread waiting on the raw monitor.
8774       </description>
8775       <origin>jvmdi</origin>
8776       <capabilities>
8777       </capabilities>
8778       <parameters>
8779         <param id="monitor">
8780           <jrawMonitorID/>
8781           <description>
8782             The monitor
8783           </description>
8784         </param>
8785       </parameters>
8786       <errors>
8787         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
8788           Not monitor owner
8789         </error>
8790       </errors>
8791     </function>
8792 
8793     <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
8794       <synopsis>Raw Monitor Notify All</synopsis>
8795       <description>
8796         Notify all threads waiting on the raw monitor.
8797       </description>
8798       <origin>jvmdi</origin>
8799       <capabilities>
8800       </capabilities>
8801       <parameters>
8802         <param id="monitor">
8803           <jrawMonitorID/>
8804           <description>
8805             The monitor
8806           </description>
8807         </param>
8808       </parameters>
8809       <errors>
8810         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8811           Not monitor owner
8812         </error>
8813       </errors>
8814     </function>
8815 
8816    <elide>
8817     <function id="GetRawMonitorUse" num="118">
8818       <synopsis>Get Raw Monitor Use</synopsis>
8819       <description>
8820         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 
8821         are filled in with information about usage of the raw monitor.
8822       </description>
8823       <origin>new</origin>
8824       <capabilities>
8825         <required id="can_get_raw_monitor_usage"></required>
8826       </capabilities>
8827       <parameters>
8828         <param id="monitor">
8829           <jrawMonitorID/>
8830           <description>
8831             the raw monitor to query.
8832           </description>
8833         </param>
8834         <param id="info_ptr">
8835           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
8836           <description>
8837             On return, filled with monitor information for the 
8838             specified raw monitor.
8839           </description>
8840         </param>
8841       </parameters>
8842       <errors>
8843       </errors>
8844     </function>
8845 
8846     <function id="GetRawMonitors" num="119">
8847       <synopsis>Get Raw Monitors</synopsis>
8848       <description>
8849         Return the list of raw monitors.
8850         <p/>
8851         Note: details about each monitor can be examined with 
8852         <functionlink id="GetRawMonitorUse"></functionlink>.
8853       </description>
8854       <origin>new</origin>
8855       <capabilities>
8856         <required id="can_get_raw_monitor_usage"></required>
8857       </capabilities>
8858       <parameters>
8859         <param id="monitorCnt">
8860           <outptr><jint/></outptr>
8861           <description>
8862             On return, pointer to the number 
8863             of monitors returned in <code>monitors_ptr</code>.
8864           </description>
8865         </param>
8866         <param id="monitors_ptr">
8867           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
8868           <description>
8869             On return, pointer to the monitor list.
8870           </description>
8871         </param>
8872       </parameters>
8873       <errors>
8874       </errors>
8875     </function>
8876     </elide>
8877   </category>
8878 
8879   <category id="jniIntercept" label="JNI Function Interception">
8880 
8881     <intro>
8882       Provides the ability to intercept and resend 
8883       Java Native Interface (JNI) function calls
8884       by manipulating the JNI function table.
8885       See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI
8886         Functions</externallink> in the <i>Java Native Interface Specification</i>.
8887       <p/>
8888       The following example illustrates intercepting the 
8889       <code>NewGlobalRef</code> JNI call in order to count reference
8890       creation.
8891       <example>
8892 JNIEnv original_jni_Functions;
8893 JNIEnv redirected_jni_Functions;
8894 int my_global_ref_count = 0;
8895 
8896 jobject
8897 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
8898    ++my_global_ref_count;
8899    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
8900 }
8901 
8902 void
8903 myInit() {
8904    jvmtiError err;
8905 
8906    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;original_jni_Functions);
8907    if (err != JVMTI_ERROR_NONE) {
8908       die();
8909    }
8910    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;redirected_jni_Functions);
8911    if (err != JVMTI_ERROR_NONE) {
8912       die();
8913    }
8914    redirectedJNIFunctions-&gt;NewGlobalRef = MyNewGlobalRef;
8915       err = (*jvmti_env)-&gt;SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
8916    if (err != JVMTI_ERROR_NONE) {
8917       die();
8918    }
8919 }
8920       </example>
8921       Sometime after <code>myInit</code> is called the user's JNI
8922       code is executed which makes the call to create a new global
8923       reference.  Instead of going to the normal JNI implementation
8924       the call goes to <code>myNewGlobalRef</code>.  Note that a
8925       copy of the original function table is kept so that the normal
8926       JNI function can be called after the data is collected.
8927       Note also that any JNI functions which are not overwritten
8928       will behave normally.
8929       <todo>
8930         check that the example compiles and executes.
8931       </todo>
8932     </intro>
8933     
8934     <function id="SetJNIFunctionTable" phase="start" num="120">
8935       <synopsis>Set JNI Function Table</synopsis>
8936       <description>
8937         Set the JNI function table 
8938         in all current and future JNI environments.
8939         As a result, all future JNI calls are directed to the specified functions.
8940         Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
8941         function table to pass to this function.
8942         For this function to take effect the the updated table entries must be 
8943         used by the JNI clients.
8944         Since the table is defined <code>const</code> some compilers may optimize
8945         away the access to the table, thus preventing this function from taking 
8946         effect.
8947         The table is copied--changes to the local copy of the
8948         table have no effect.
8949         This function affects only the function table, all other aspects of the environment are
8950         unaffected.
8951         See the examples <internallink id="jniIntercept">above</internallink>.
8952       </description>
8953       <origin>new</origin>
8954       <capabilities>
8955       </capabilities>
8956       <parameters>
8957         <param id="function_table">
8958           <inptr>
8959             <struct>jniNativeInterface</struct>
8960           </inptr>
8961           <description>
8962             Points to the new JNI function table.
8963           </description>
8964         </param>
8965       </parameters>
8966       <errors>
8967       </errors>
8968     </function>
8969     
8970     <function id="GetJNIFunctionTable" phase="start" num="121">
8971       <synopsis>Get JNI Function Table</synopsis>
8972       <description>
8973         Get the JNI function table.
8974         The JNI function table is copied into allocated memory.
8975         If <functionlink id="SetJNIFunctionTable"></functionlink> 
8976         has been called, the modified (not the original) function
8977         table is returned.
8978         Only the function table is copied, no other aspects of the environment 
8979         are copied.
8980         See the examples <internallink id="jniIntercept">above</internallink>.
8981       </description>
8982       <origin>new</origin>
8983       <capabilities>
8984       </capabilities>
8985       <parameters>
8986         <param id="function_table">
8987           <allocbuf>
8988             <struct>jniNativeInterface</struct>
8989           </allocbuf>
8990           <description>
8991             On return, <code>*function_table</code> 
8992             points a newly allocated copy of the JNI function table.
8993           </description>
8994         </param>
8995       </parameters>
8996       <errors>
8997       </errors>
8998     </function>
8999 
9000   </category>
9001 
9002   <category id="eventManagement" label="Event Management">
9003 
9004     <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
9005       <synopsis>Set Event Callbacks</synopsis>
9006       <description>
9007         Set the functions to be called for each event.
9008         The callbacks are specified by supplying a replacement function table.
9009         The function table is copied--changes to the local copy of the
9010         table have no effect.
9011         This is an atomic action, all callbacks are set at once.
9012         No events are sent before this function is called.
9013         When an entry is <code>NULL</code> or when the event is beyond 
9014         <paramlink id="size_of_callbacks"></paramlink> no event is sent.
9015         Details on events are 
9016         described <internallink id="EventSection">later</internallink> in this document.
9017         An event must be enabled and have a callback in order to be
9018         sent--the order in which this function and 
9019         <functionlink id="SetEventNotificationMode"></functionlink> 
9020         are called does not affect the result.
9021       </description>
9022       <origin>new</origin>
9023       <capabilities>
9024       </capabilities>
9025       <parameters>
9026         <param id="callbacks">
9027           <inptr>
9028             <struct>jvmtiEventCallbacks</struct>
9029             <nullok>remove the existing callbacks</nullok>
9030           </inptr>
9031           <description>
9032             The new event callbacks.
9033           </description>
9034         </param>
9035         <param id="size_of_callbacks">
9036           <jint min="0"/>
9037           <description>
9038             <code>sizeof(jvmtiEventCallbacks)</code>--for version
9039             compatibility.
9040           </description>
9041         </param>
9042       </parameters>
9043       <errors>
9044       </errors>
9045     </function>
9046 
9047     <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
9048       <synopsis>Set Event Notification Mode</synopsis>
9049       <description>
9050         Control the generation of events. 
9051         <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
9052           <constant id="JVMTI_ENABLE" num="1">
9053             If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, 
9054             the event <paramlink id="event_type"></paramlink> will be enabled
9055           </constant>
9056           <constant id="JVMTI_DISABLE" num="0">
9057             If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, 
9058             the event <paramlink id="event_type"></paramlink> will be disabled
9059           </constant>
9060         </constants>
9061         If <code>thread</code> is <code>NULL</code>,
9062         the event is enabled or disabled globally; otherwise, it is 
9063         enabled or disabled for a particular thread. 
9064         An event is generated for 
9065         a particular thread if it is enabled either at the thread or global
9066         levels. 
9067         <p/>
9068         See <internallink id="EventIndex">below</internallink> for information on specific events.
9069         <p/>
9070         The following events cannot be controlled at the thread
9071         level through this function. 
9072         <ul>
9073           <li><eventlink id="VMInit"></eventlink></li>
9074           <li><eventlink id="VMStart"></eventlink></li>
9075           <li><eventlink id="VMDeath"></eventlink></li>
9076           <li><eventlink id="ThreadStart"></eventlink></li>
9077           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9078           <li><eventlink id="CompiledMethodUnload"></eventlink></li>
9079           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9080           <li><eventlink id="DataDumpRequest"></eventlink></li>
9081         </ul>
9082         <p/>
9083         Initially, no events are enabled at either the thread level 
9084         or the global level.
9085         <p/>
9086         Any needed capabilities (see Event Enabling Capabilities below) must be possessed
9087         before calling this function.
9088         <p/>
9089         Details on events are 
9090         described <internallink id="EventSection">below</internallink>.
9091       </description>
9092       <origin>jvmdiClone</origin>
9093       <eventcapabilities></eventcapabilities>
9094       <parameters>
9095         <param id="mode">
9096           <enum>jvmtiEventMode</enum>
9097           <description>
9098             <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
9099           </description>
9100         </param>
9101         <param id="event_type">
9102           <enum>jvmtiEvent</enum>
9103           <description>
9104             the event to control
9105           </description>
9106         </param>
9107         <param id="event_thread">
9108           <ptrtype>
9109             <jthread impl="noconvert"/>
9110             <nullok>event is controlled at the global level</nullok>
9111           </ptrtype>
9112             <description>
9113               The thread to control
9114             </description>
9115         </param>
9116         <param id="...">
9117           <varargs/>
9118             <description>
9119               for future expansion
9120             </description>
9121         </param>
9122       </parameters>
9123       <errors>
9124         <error id="JVMTI_ERROR_INVALID_THREAD">
9125           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
9126         </error>
9127         <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
9128           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead).
9129         </error>
9130         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9131           thread level control was attempted on events which do not 
9132           permit thread level control.
9133         </error>
9134         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 
9135           The Required Event Enabling Capability is not possessed.
9136         </error>
9137       </errors>
9138     </function>
9139 
9140     <function id="GenerateEvents" num="123">
9141       <synopsis>Generate Events</synopsis>
9142       <description>
9143         Generate events to represent the current state of the VM.  
9144         For example, if <paramlink id="event_type"/> is 
9145         <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
9146         a <eventlink id="CompiledMethodLoad"></eventlink> event will be
9147         sent for each currently compiled method.
9148         Methods that were loaded and now have been unloaded are not sent.
9149         The history of what events have previously been sent does not 
9150         effect what events are sent by this function--for example, 
9151         all currently compiled methods
9152         will be sent each time this function is called.
9153         <p/>
9154         This function is useful when
9155         events may have been missed due to the agent attaching after program
9156         execution begins; this function generates the missed events.
9157         <p/>
9158         Attempts to execute Java programming language code or
9159         JNI functions may be paused until this function returns -
9160         so neither should be called from the thread sending the event.
9161         This function returns only after the missed events have been 
9162         sent, processed and have returned.
9163         The event may be sent on a different thread than the thread
9164         on which the event occurred.
9165         The callback for the event must be set with 
9166         <functionlink id="SetEventCallbacks"></functionlink> 
9167         and the event must be enabled with
9168         <functionlink id="SetEventNotificationMode"></functionlink> 
9169         or the events will not occur.
9170         If the VM no longer has the information to generate some or
9171         all of the requested events, the events are simply not sent -
9172         no error is returned.
9173         <p/>
9174         Only the following events are supported:
9175         <ul>
9176           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9177           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9178         </ul>
9179       </description>
9180       <origin>new</origin>
9181       <capabilities>
9182         <capability id="can_generate_compiled_method_load_events"></capability>
9183       </capabilities>
9184       <parameters>
9185         <param id="event_type">
9186           <enum>jvmtiEvent</enum>
9187           <description>
9188             The type of event to generate.  Must be one of these:
9189             <ul>
9190               <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
9191               <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
9192             </ul>
9193           </description>
9194         </param>
9195       </parameters>
9196       <errors>
9197         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 
9198           <paramlink id="event_type"/> is 
9199           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9200           and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
9201           is <code>false</code>.
9202         </error>
9203         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 
9204           <paramlink id="event_type"/> is other than
9205           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9206           or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
9207         </error>
9208       </errors>
9209     </function>
9210 
9211   </category>
9212 
9213     <category id="extension" label="Extension Mechanism">
9214 
9215       <intro>
9216         These functions
9217         allow a <jvmti/> implementation to provide functions and events
9218         beyond those defined in this specification.
9219         <p/>
9220         Both extension functions and extension events have parameters
9221         each of which has a 'type' and 'kind' chosen from the following tables:
9222 
9223         <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
9224           <constant id="JVMTI_TYPE_JBYTE" num="101">
9225             Java programming language primitive type - <code>byte</code>. 
9226             JNI type <code>jbyte</code>.
9227           </constant>
9228           <constant id="JVMTI_TYPE_JCHAR" num="102">
9229             Java programming language primitive type - <code>char</code>. 
9230             JNI type <code>jchar</code>.
9231           </constant>
9232           <constant id="JVMTI_TYPE_JSHORT" num="103">
9233             Java programming language primitive type - <code>short</code>. 
9234             JNI type <code>jshort</code>.
9235           </constant>
9236           <constant id="JVMTI_TYPE_JINT" num="104">
9237             Java programming language primitive type - <code>int</code>. 
9238             JNI type <datalink id="jint"></datalink>.
9239           </constant>
9240           <constant id="JVMTI_TYPE_JLONG" num="105">
9241             Java programming language primitive type - <code>long</code>. 
9242             JNI type <datalink id="jlong"></datalink>.
9243           </constant>
9244           <constant id="JVMTI_TYPE_JFLOAT" num="106">
9245             Java programming language primitive type - <code>float</code>. 
9246             JNI type <datalink id="jfloat"></datalink>.
9247           </constant>
9248           <constant id="JVMTI_TYPE_JDOUBLE" num="107">
9249             Java programming language primitive type - <code>double</code>. 
9250             JNI type <datalink id="jdouble"></datalink>.
9251           </constant>
9252           <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
9253             Java programming language primitive type - <code>boolean</code>. 
9254             JNI type <datalink id="jboolean"></datalink>.
9255           </constant>
9256           <constant id="JVMTI_TYPE_JOBJECT" num="109">
9257             Java programming language object type - <code>java.lang.Object</code>. 
9258             JNI type <datalink id="jobject"></datalink>.
9259             Returned values are JNI local references and must be managed.
9260           </constant>
9261           <constant id="JVMTI_TYPE_JTHREAD" num="110">
9262             Java programming language object type - <code>java.lang.Thread</code>. 
9263             <jvmti/> type <datalink id="jthread"></datalink>.
9264             Returned values are JNI local references and must be managed.
9265           </constant>
9266           <constant id="JVMTI_TYPE_JCLASS" num="111">
9267             Java programming language object type - <code>java.lang.Class</code>. 
9268             JNI type <datalink id="jclass"></datalink>.
9269             Returned values are JNI local references and must be managed.
9270           </constant>
9271           <constant id="JVMTI_TYPE_JVALUE" num="112">
9272             Union of all Java programming language primitive and object types - 
9273             JNI type <datalink id="jvalue"></datalink>.
9274             Returned values which represent object types are JNI local references and must be managed.
9275           </constant>
9276           <constant id="JVMTI_TYPE_JFIELDID" num="113">
9277             Java programming language field identifier - 
9278             JNI type <datalink id="jfieldID"></datalink>.
9279           </constant>
9280           <constant id="JVMTI_TYPE_JMETHODID" num="114">
9281             Java programming language method identifier - 
9282             JNI type <datalink id="jmethodID"></datalink>.
9283           </constant>
9284           <constant id="JVMTI_TYPE_CCHAR" num="115">
9285             C programming language type - <code>char</code>.
9286           </constant>
9287           <constant id="JVMTI_TYPE_CVOID" num="116">
9288             C programming language type - <code>void</code>.
9289           </constant>
9290           <constant id="JVMTI_TYPE_JNIENV" num="117">
9291             JNI environment - <code>JNIEnv</code>.
9292             Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
9293           </constant>
9294         </constants>
9295 
9296         <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
9297           <constant id="JVMTI_KIND_IN" num="91">
9298             Ingoing argument - <code>foo</code>.
9299           </constant>
9300           <constant id="JVMTI_KIND_IN_PTR" num="92">
9301             Ingoing pointer argument - <code>const foo*</code>.
9302           </constant>
9303           <constant id="JVMTI_KIND_IN_BUF" num="93">
9304             Ingoing array argument - <code>const foo*</code>.
9305           </constant>
9306           <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
9307             Outgoing allocated array argument -  <code>foo**</code>.
9308             Free with <code>Deallocate</code>.
9309           </constant>
9310           <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
9311             Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
9312             Free with <code>Deallocate</code>.
9313           </constant>
9314           <constant id="JVMTI_KIND_OUT" num="96">
9315             Outgoing argument - <code>foo*</code>.
9316           </constant>
9317           <constant id="JVMTI_KIND_OUT_BUF" num="97">
9318             Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
9319             Do not <code>Deallocate</code>.
9320           </constant>
9321         </constants>
9322 
9323       </intro>
9324 
9325       <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
9326         <field id="name">
9327           <allocfieldbuf><char/></allocfieldbuf>
9328             <description>
9329               The parameter name, encoded as a
9330               <internallink id="mUTF">modified UTF-8</internallink> string
9331             </description>
9332         </field>
9333         <field id="kind">
9334           <enum>jvmtiParamKind</enum>
9335           <description>
9336             The kind of the parameter - type modifiers
9337           </description>
9338         </field>
9339         <field id="base_type">
9340           <enum>jvmtiParamTypes</enum>
9341           <description>
9342             The base type of the parameter -  modified by <code>kind</code>
9343           </description>
9344         </field>
9345         <field id="null_ok">
9346           <jboolean/>
9347             <description>
9348               Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
9349             </description>
9350         </field>
9351       </typedef>
9352 
9353       <callback id="jvmtiExtensionFunction">
9354         <enum>jvmtiError</enum>
9355           <synopsis>Extension Function</synopsis>
9356         <description>
9357           This is the implementation-specific extension function.
9358         </description>
9359         <parameters>
9360           <param id="jvmti_env">
9361             <outptr>
9362               <struct>jvmtiEnv</struct>
9363             </outptr>
9364             <description>
9365               The <jvmti/> environment is the only fixed parameter for extension functions.
9366             </description>
9367           </param>
9368           <param id="...">
9369             <varargs/>
9370               <description>
9371                 The extension function-specific parameters
9372               </description>
9373           </param>
9374         </parameters>
9375       </callback>
9376 
9377       <function id="GetExtensionFunctions" phase="onload" num="124">
9378         <synopsis>Get Extension Functions</synopsis>
9379 
9380         <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
9381           <field id="func">
9382             <ptrtype>
9383               <struct>jvmtiExtensionFunction</struct>
9384             </ptrtype>
9385             <description>
9386               The actual function to call
9387             </description>
9388           </field>
9389           <field id="id">
9390             <allocfieldbuf><char/></allocfieldbuf>
9391               <description>
9392                 The identifier for the extension function, encoded as a
9393                 <internallink id="mUTF">modified UTF-8</internallink> string.
9394                 Uses package name conventions.
9395                 For example, <code>com.sun.hotspot.bar</code>
9396               </description>
9397           </field>
9398           <field id="short_description">
9399             <allocfieldbuf><char/></allocfieldbuf>
9400               <description>
9401                 A one sentence description of the function, encoded as a
9402                 <internallink id="mUTF">modified UTF-8</internallink> string.
9403               </description>
9404           </field>
9405           <field id="param_count">
9406             <jint/>
9407               <description>
9408                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9409               </description>
9410           </field>
9411           <field id="params">
9412             <allocfieldbuf outcount="param_count">
9413               <struct>jvmtiParamInfo</struct>
9414             </allocfieldbuf>
9415             <description>
9416               Array of 
9417               <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9418               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9419             </description>
9420           </field>
9421           <field id="error_count">
9422             <jint/>
9423               <description>
9424                 The number of possible error returns (excluding universal errors)
9425               </description>
9426           </field>
9427           <field id="errors">
9428             <allocfieldbuf outcount="error_count">
9429               <enum>jvmtiError</enum>
9430             </allocfieldbuf>
9431             <description>
9432               Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9433               possible errors
9434             </description>
9435           </field>
9436         </typedef>
9437 
9438         <description>
9439           Returns the set of extension functions.
9440         </description>
9441         <origin>new</origin>
9442         <capabilities>
9443         </capabilities>
9444         <parameters>
9445           <param id="extension_count_ptr">
9446             <outptr><jint/></outptr>
9447               <description>
9448                 On return, points to the number of extension functions
9449               </description>
9450           </param>
9451           <param id="extensions">
9452             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
9453             <description>
9454               Returns an array of extension function info, one per function
9455             </description>
9456           </param>
9457         </parameters>
9458         <errors>
9459         </errors>
9460       </function>
9461 
9462       <function id="GetExtensionEvents" phase="onload" num="125">
9463         <synopsis>Get Extension Events</synopsis>
9464 
9465         <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
9466           <field id="extension_event_index">
9467             <jint/>
9468             <description>
9469               The identifying index of the event
9470             </description>
9471           </field>
9472           <field id="id">
9473             <allocfieldbuf><char/></allocfieldbuf>
9474               <description>
9475                 The identifier for the extension event, encoded as a
9476                 <internallink id="mUTF">modified UTF-8</internallink> string.
9477                 Uses package name conventions.
9478                 For example, <code>com.sun.hotspot.bar</code>
9479               </description>
9480           </field>
9481           <field id="short_description">
9482             <allocfieldbuf><char/></allocfieldbuf>
9483               <description>
9484                 A one sentence description of the event, encoded as a
9485                 <internallink id="mUTF">modified UTF-8</internallink> string.
9486               </description>
9487           </field>
9488           <field id="param_count">
9489             <jint/>
9490               <description>
9491                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9492               </description>
9493           </field>
9494           <field id="params">
9495             <allocfieldbuf outcount="param_count">
9496               <struct>jvmtiParamInfo</struct>
9497             </allocfieldbuf>
9498             <description>
9499               Array of 
9500               <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
9501               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9502             </description>
9503           </field>
9504         </typedef>
9505 
9506         <description>
9507           Returns the set of extension events.
9508         </description>
9509         <origin>new</origin>
9510         <capabilities>
9511         </capabilities>
9512         <parameters>
9513           <param id="extension_count_ptr">
9514             <outptr><jint/></outptr>
9515               <description>
9516                 On return, points to the number of extension events
9517               </description>
9518           </param>
9519           <param id="extensions">
9520             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
9521             <description>
9522               Returns an array of extension event info, one per event
9523             </description>
9524           </param>
9525         </parameters>
9526         <errors>
9527         </errors>
9528       </function>
9529 
9530       <callback id="jvmtiExtensionEvent">
9531         <void/>
9532           <synopsis>Extension Event</synopsis>
9533         <description>
9534           This is the implementation-specific event.
9535           The event handler is set with 
9536           <functionlink id="SetExtensionEventCallback"/>.
9537           <p/>
9538           Event handlers for extension events must be declared varargs to match this definition.
9539           Failure to do so could result in calling convention mismatch and undefined behavior
9540           on some platforms.
9541           <p/>
9542           For example, if the <code>jvmtiParamInfo</code>
9543           returned by <functionlink id="GetExtensionEvents"/> indicates that
9544           there is a <code>jint</code> parameter, the event handler should be
9545           declared:
9546 <example>
9547     void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...)
9548 </example>
9549           Note the terminal "<code>...</code>" which indicates varargs.
9550         </description>
9551         <parameters>
9552           <param id="jvmti_env">
9553             <outptr>
9554               <struct>jvmtiEnv</struct>
9555             </outptr>
9556             <description>
9557               The <jvmti/> environment is the only fixed parameter for extension events.
9558             </description>
9559           </param>
9560           <param id="...">
9561             <varargs/>
9562               <description>
9563                 The extension event-specific parameters
9564               </description>
9565           </param>
9566         </parameters>
9567       </callback>
9568 
9569       <function id="SetExtensionEventCallback" phase="onload" num="126">
9570         <synopsis>Set Extension Event Callback</synopsis>
9571 
9572         <description>
9573           Sets the callback function for an extension event and
9574           enables the event. Or, if the callback is <code>NULL</code>, disables
9575           the event.  Note that unlike standard events, setting
9576           the callback and enabling the event are a single operation.
9577         </description>
9578         <origin>new</origin>
9579         <capabilities>
9580         </capabilities>
9581         <parameters>
9582           <param id="extension_event_index">
9583             <jint/>
9584               <description>
9585                 Identifies which callback to set.
9586                 This index is the 
9587                 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
9588                 field of 
9589                 <datalink id="jvmtiExtensionEventInfo"/>.
9590               </description>
9591           </param>
9592           <param id="callback">
9593             <ptrtype>
9594               <struct>jvmtiExtensionEvent</struct>
9595               <nullok>disable the event</nullok>
9596             </ptrtype>
9597             <description>
9598               If <code>callback</code> is non-<code>NULL</code>, 
9599               set <code>callback</code> to be the event callback function
9600               and enable the event.
9601             </description>
9602           </param>
9603         </parameters>
9604         <errors>
9605         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 
9606             <paramlink id="extension_event_index"/> is not an
9607             <fieldlink id="extension_event_index" 
9608                        struct="jvmtiExtensionEventInfo"/>
9609             returned by 
9610             <functionlink id="GetExtensionEvents"/>
9611         </error>
9612         </errors>
9613       </function>
9614 
9615     </category>
9616 
9617   <category id="capability" label="Capability">
9618 
9619     <intro>
9620       The capabilities functions allow you to change the
9621       functionality available to <jvmti/>--that is, 
9622       which <jvmti/> 
9623       functions can be called, what events can be generated,
9624       and what functionality these events and functions can
9625       provide.
9626       <p/>
9627         The "Capabilities" section of each function and event describe which 
9628         capabilities, if any, they are associated with. "Required Functionality"
9629         means it is available for use and no capabilities must be added to use it.
9630         "Optional Functionality" means the agent must possess the capability
9631         before it can be used.  
9632         To possess a capability, the agent must
9633         <functionlink id="AddCapabilities">add the capability</functionlink>.
9634         "Optional Features" describe capabilities which,
9635         if added, extend the feature set.
9636         <p/>
9637         The potentially available capabilities of each <jvmti/> implementation are different.  
9638         Depending on the implementation, a capability:
9639         <ul>
9640           <li>may never be added</li>
9641           <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
9642           <li>may be added only during the <code>OnLoad</code> phase</li>
9643           <li>may be possessed by only one environment at a time</li>
9644           <li>may be possessed by only one environment at a time, 
9645               and only during the <code>OnLoad</code> phase</li>
9646           <li>and so on ...</li>
9647         </ul>
9648       Frequently, the addition of a capability may incur a cost in execution speed, start up
9649       time, and/or memory footprint.  Note that the overhead of using a capability
9650       is completely different than the overhead of possessing a capability.
9651       Take single stepping as an example. When single stepping is on (that
9652       is, when the event is enabled and thus actively sending events) 
9653       the overhead of sending and processing an event 
9654       on each instruction is huge in any implementation. 
9655       However, the overhead of possessing the capability may be small or large, 
9656       depending on the implementation.  Also, when and if a capability is potentially
9657       available depends on the implementation.  Some examples:
9658       <ul>
9659         <li>One VM might perform all execution by compiling bytecodes into 
9660           native code and be unable to generate single step instructions.
9661           In this implementation the capability can not be added.</li>
9662         <li>Another VM may be able to switch execution to a single stepping
9663           interpreter at any time.  In this implementation, having the capability has no 
9664           overhead and could be added at any time.</li>
9665         <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
9666           execution engine at start up, but be unable to switch between them.
9667           In this implementation the capability would need to be added 
9668           during the <code>OnLoad</code> phase (before bytecode
9669           execution begins) and would have a large impact on execution speed 
9670           even if single stepping was never used.</li>
9671         <li>Still another VM might be able to add an "is single stepping on" check
9672           into compiled bytecodes or a generated interpreter.  Again in this implementation
9673           the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
9674           and branch on each instruction) would be considerably less.</li>
9675       </ul>
9676       <p/>
9677       Each <jvmti/> <internallink id="environments">environment</internallink>
9678       has its own set of capabilities.  
9679       Initially, that set is empty.
9680       Any desired capability must be added.
9681       If possible, capabilities should be added during the <code>OnLoad</code> phase.  For most 
9682       virtual machines certain capabilities require special set up for 
9683       the virtual machine and this set up must happen
9684       during the <code>OnLoad</code> phase, before the virtual machine begins execution. 
9685       Once a capability is added, it can
9686       only be removed if explicitly relinquished by the environment.
9687       <p/>
9688       The agent can, 
9689       <functionlink id="GetPotentialCapabilities">determine what
9690         capabilities this VM can potentially provide</functionlink>,
9691       <functionlink id="AddCapabilities">add the capabilities
9692         to be used</functionlink>,
9693       <functionlink id="RelinquishCapabilities">release capabilities
9694         which are no longer needed</functionlink>, and
9695       <functionlink id="GetCapabilities">examine the currently available 
9696         capabilities</functionlink>.
9697     </intro>
9698 
9699     <intro id="capabilityExamples" label="Capability Examples">
9700       For example, a freshly started agent (in the <code>OnLoad</code> function)
9701       wants to enable all possible capabilities.  
9702       Note that, in general, this is not advisable as the agent may suffer
9703       a performance penalty for functionality it is not using.
9704       The code might look like this in C:
9705       <example>
9706         jvmtiCapabilities capa;
9707         jvmtiError err;
9708 
9709         err = (*jvmti)-&gt;GetPotentialCapabilities(jvmti, &amp;capa);
9710         if (err == JVMTI_ERROR_NONE) {
9711            err = (*jvmti)-&gt;AddCapabilities(jvmti, &amp;capa);
9712       </example>
9713       For example, if an  agent wants to check if it can get
9714       the bytecodes of a method (that is, it wants to check 
9715       if it previously added this capability and has not 
9716       relinquished it), the code might 
9717       look like this in C:
9718       <example>
9719         jvmtiCapabilities capa;
9720         jvmtiError err;
9721 
9722         err = (*jvmti)-&gt;GetCapabilities(jvmti, &amp;capa);
9723         if (err == JVMTI_ERROR_NONE) {
9724            if (capa.can_get_bytecodes) { ... } } 
9725       </example>
9726     </intro>
9727 
9728     <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
9729       <description>
9730         The functions in this category use this capabilities structure 
9731         which contains boolean flags corresponding to each capability:
9732       </description>
9733       <capabilityfield id="can_tag_objects">
9734         <description>
9735           Can set and get tags, as described in the
9736           <internallink id="Heap">Heap category</internallink>.
9737         </description>
9738       </capabilityfield>
9739       <capabilityfield id="can_generate_field_modification_events">
9740         <description>
9741           Can set watchpoints on field modification -
9742           <functionlink id="SetFieldModificationWatch"></functionlink>
9743         </description>
9744       </capabilityfield>
9745       <capabilityfield id="can_generate_field_access_events">
9746         <description>
9747           Can set watchpoints on field access -
9748           <functionlink id="SetFieldAccessWatch"></functionlink>
9749         </description>
9750       </capabilityfield>
9751       <capabilityfield id="can_get_bytecodes">
9752         <description>
9753           Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
9754         </description>
9755       </capabilityfield>
9756       <capabilityfield id="can_get_synthetic_attribute">
9757         <description>
9758           Can test if a field or method is synthetic - 
9759           <functionlink id="IsFieldSynthetic"></functionlink> and
9760           <functionlink id="IsMethodSynthetic"></functionlink>
9761         </description>
9762       </capabilityfield>
9763       <capabilityfield id="can_get_owned_monitor_info">
9764         <description>
9765           Can get information about ownership of monitors - 
9766           <functionlink id="GetOwnedMonitorInfo"></functionlink>
9767         </description>
9768       </capabilityfield>
9769       <capabilityfield id="can_get_current_contended_monitor">
9770         <description>
9771           Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
9772         </description>
9773       </capabilityfield>
9774       <capabilityfield id="can_get_monitor_info">
9775       <description>
9776         Can <functionlink id="GetObjectMonitorUsage"></functionlink>
9777       </description>
9778       </capabilityfield>
9779       <capabilityfield id="can_pop_frame">
9780         <description>
9781           Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
9782         </description>
9783       </capabilityfield>
9784       <capabilityfield id="can_redefine_classes">
9785         <description>
9786           Can redefine classes with <functionlink id="RedefineClasses"/>.
9787         </description>
9788       </capabilityfield>
9789       <capabilityfield id="can_signal_thread">
9790         <description>
9791           Can send stop or interrupt to threads
9792         </description>
9793       </capabilityfield>
9794       <capabilityfield id="can_get_source_file_name">
9795         <description>
9796           Can get the source file name of a class
9797         </description>
9798       </capabilityfield>
9799       <capabilityfield id="can_get_line_numbers">
9800         <description>
9801           Can get the line number table of a method
9802         </description>
9803       </capabilityfield>
9804       <capabilityfield id="can_get_source_debug_extension">
9805         <description>
9806           Can get the source debug extension of a class
9807         </description>
9808       </capabilityfield>
9809       <capabilityfield id="can_access_local_variables">
9810         <description>
9811           Can set and get local variables
9812         </description>
9813       </capabilityfield>
9814       <capabilityfield id="can_maintain_original_method_order">
9815         <description>
9816           Can return methods in the order they occur in the class file
9817         </description>
9818       </capabilityfield>
9819       <capabilityfield id="can_generate_single_step_events">
9820         <description>
9821           Can get <eventlink id="SingleStep">single step</eventlink> events
9822         </description>
9823       </capabilityfield>
9824       <capabilityfield id="can_generate_exception_events">
9825         <description>
9826           Can get <eventlink id="Exception">exception thrown</eventlink> and 
9827             <eventlink id="ExceptionCatch">exception catch</eventlink> events
9828         </description>
9829       </capabilityfield>
9830       <capabilityfield id="can_generate_frame_pop_events">
9831         <description>
9832           Can <functionlink id="NotifyFramePop">set</functionlink> and thus get 
9833             <eventlink id="FramePop"></eventlink> events
9834         </description>
9835       </capabilityfield>
9836       <capabilityfield id="can_generate_breakpoint_events">
9837         <description>
9838           Can <functionlink id="SetBreakpoint">set</functionlink> and thus get 
9839             <eventlink id="Breakpoint"></eventlink> events
9840         </description>
9841       </capabilityfield>
9842       <capabilityfield id="can_suspend">
9843         <description>
9844           Can suspend and resume threads
9845         </description>
9846       </capabilityfield>
9847       <capabilityfield id="can_redefine_any_class">
9848         <description>
9849           Can modify (retransform or redefine) any non-primitive non-array class.
9850           See <functionlink id="IsModifiableClass"/>.
9851         </description>
9852       </capabilityfield>
9853       <capabilityfield id="can_get_current_thread_cpu_time">
9854         <description>
9855           Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
9856           current thread CPU time
9857         </description>
9858       </capabilityfield>
9859       <capabilityfield id="can_get_thread_cpu_time">
9860         <description>
9861           Can <functionlink id="GetThreadCpuTime">get</functionlink>
9862           thread CPU time
9863         </description>
9864       </capabilityfield>
9865       <capabilityfield id="can_generate_method_entry_events" 
9866                        disp1="can_generate" disp2="_method_entry_events" 
9867                        >
9868         <description>
9869           Can generate method entry events on entering a method
9870         </description>
9871       </capabilityfield>
9872       <capabilityfield id="can_generate_method_exit_events" 
9873                        disp1="can_generate" disp2="_method_exit_events" 
9874                        >
9875         <description>
9876           Can generate method exit events on leaving a method
9877         </description>
9878       </capabilityfield>
9879       <capabilityfield id="can_generate_all_class_hook_events" 
9880                        disp1="can_generate" disp2="_all_class_hook_events" 
9881                        >
9882         <description>
9883           Can generate ClassFileLoadHook events for every loaded class.
9884         </description>
9885       </capabilityfield>
9886       <capabilityfield id="can_generate_compiled_method_load_events" 
9887                        disp1="can_generate" disp2="_compiled_method_load_events" 
9888                        >
9889         <description>
9890           Can generate events when a method is compiled or unloaded
9891         </description>
9892       </capabilityfield>
9893       <capabilityfield id="can_generate_monitor_events" 
9894                        disp1="can_generate" disp2="_monitor_events" 
9895                        >
9896         <description>
9897           Can generate events on monitor activity
9898         </description>
9899       </capabilityfield>
9900       <capabilityfield id="can_generate_vm_object_alloc_events" 
9901                        disp1="can_generate" disp2="_vm_object_alloc_events" 
9902                        >
9903         <description>
9904           Can generate events on VM allocation of an object
9905         </description>
9906       </capabilityfield>
9907       <capabilityfield id="can_generate_native_method_bind_events" 
9908                        disp1="can_generate" disp2="_native_method_bind_events" 
9909                        >
9910         <description>
9911           Can generate events when a native method is bound to its
9912           implementation
9913         </description>
9914       </capabilityfield>
9915       <capabilityfield id="can_generate_garbage_collection_events" 
9916                        disp1="can_generate" disp2="_garbage_collection_events" 
9917                        >
9918         <description>
9919           Can generate events when garbage collection begins or ends
9920         </description>
9921       </capabilityfield>
9922       <capabilityfield id="can_generate_object_free_events" 
9923                        disp1="can_generate" disp2="_object_free_events" 
9924                        >
9925         <description>
9926           Can generate events when the garbage collector frees an object
9927         </description>
9928       </capabilityfield>
9929       <capabilityfield id="can_force_early_return" since="1.1">
9930         <description>
9931           Can return early from a method, as described in the
9932           <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
9933         </description>
9934       </capabilityfield>
9935       <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
9936         <description>
9937           Can get information about owned monitors with stack depth -
9938           <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
9939         </description>
9940       </capabilityfield>
9941       <capabilityfield id="can_get_constant_pool" since="1.1">
9942         <description>
9943           Can get the constant pool of a class -
9944           <functionlink id="GetConstantPool"></functionlink>
9945         </description>
9946       </capabilityfield>
9947       <capabilityfield id="can_set_native_method_prefix" since="1.1">
9948         <description>
9949           Can set prefix to be applied when native method cannot be resolved -
9950           <functionlink id="SetNativeMethodPrefix"/> and
9951           <functionlink id="SetNativeMethodPrefixes"/>
9952         </description>
9953       </capabilityfield>
9954       <capabilityfield id="can_retransform_classes" since="1.1">
9955         <description>
9956           Can retransform classes with <functionlink id="RetransformClasses"/>.
9957           In addition to the restrictions imposed by the specific 
9958           implementation on this capability (see the
9959           <internallink id="capability">Capability</internallink> section),
9960           this capability must be set before the 
9961           <eventlink id="ClassFileLoadHook"/> event is enabled for the
9962           first time in this environment.
9963           An environment that possesses this capability at the time that 
9964           <code>ClassFileLoadHook</code> is enabled for the first time is
9965           said to be <i>retransformation capable</i>.
9966           An environment that does not possess this capability at the time that 
9967           <code>ClassFileLoadHook</code> is enabled for the first time is
9968           said to be <i>retransformation incapable</i>.
9969         </description>
9970       </capabilityfield>
9971       <capabilityfield id="can_retransform_any_class" since="1.1">
9972         <description>
9973           <functionlink id="RetransformClasses"/> can be called on any class 
9974           (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
9975           must also be set)
9976         </description>
9977       </capabilityfield>
9978       <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
9979         <description>
9980           Can generate events when the VM is unable to allocate memory from 
9981           the <tm>Java</tm> platform heap.
9982           See <eventlink id="ResourceExhausted"/>.
9983         </description>
9984       </capabilityfield>
9985       <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
9986         <description>
9987           Can generate events when the VM is unable to create a thread.
9988           See <eventlink id="ResourceExhausted"/>.
9989         </description>
9990       </capabilityfield>
9991       <capabilityfield id="can_generate_early_vmstart" since="9">
9992         <description>
9993           Can generate the <code>VMStart</code> event early.
9994           See <eventlink id="VMStart"/>.
9995         </description>
9996       </capabilityfield>
9997       <capabilityfield id="can_generate_early_class_hook_events" since="9">
9998         <description>
9999           Can generate the <eventlink id="ClassFileLoadHook"/> events early.
10000           If this capability and
10001           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
10002           ><code>can_generate_all_class_hook_events</code></internallink>
10003           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10004           could be posted for classes loaded in the primordial phase.
10005           See <eventlink id="ClassFileLoadHook"/>.
10006         </description>
10007       </capabilityfield>
10008     </capabilitiestypedef>
10009 
10010     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10011       <synopsis>Get Potential Capabilities</synopsis>
10012       <description>
10013         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> 
10014         features that can potentially be possessed by this environment
10015         at this time.
10016         The returned capabilities differ from the complete set of capabilities
10017         implemented by the VM in two cases: another environment possesses 
10018         capabilities that can only be possessed by one environment, or the
10019         current <functionlink id="GetPhase">phase</functionlink> is live,
10020         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10021         The <functionlink id="AddCapabilities"></functionlink> function
10022         may be used to set any or all or these capabilities.
10023         Currently possessed capabilities are included.
10024         <p/>
10025         Typically this function is used in the <code>OnLoad</code> function.
10026         Some virtual machines may allow a limited set of capabilities to be
10027         added in the live phase.
10028         In this case, the set of potentially available capabilities
10029         will likely differ from the <code>OnLoad</code> phase set.
10030         <p/>
10031         See the
10032         <internallink id="capabilityExamples">Capability Examples</internallink>.
10033       </description>
10034       <origin>new</origin>
10035       <capabilities>
10036       </capabilities>
10037       <parameters>
10038         <param id="capabilities_ptr">
10039           <outptr><struct>jvmtiCapabilities</struct></outptr>
10040           <description>
10041             On return, points to the <jvmti/> capabilities that may be added.
10042           </description>
10043         </param>
10044       </parameters>
10045       <errors>
10046       </errors>
10047     </function>
10048 
10049     <elide>
10050     <function id="EstimateCostOfCapabilities" phase="onload" num="141">
10051       <synopsis>Estimate Cost Of Capabilities</synopsis>
10052       <description>
10053         <issue>There is strong opposition to this function.  The concern is
10054           that it would be difficult or impossible to provide meaningful
10055           numbers, as the amount of impact is conditional on many factors
10056           that a single number could not represent.  There is doubt that
10057           conditional implementations would be used or are even a good idea.
10058           The thought is that release documentation for the implementation
10059           would be the best means of exposing this information.
10060           Unless new arguments are presented, I intend to remove this 
10061           function in the next revision.
10062         </issue>
10063         <p/>
10064         Return via the <paramlink id="time_impact_ptr"></paramlink> and
10065         <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
10066         of adding the capabilities pointed to by
10067         <paramlink id="capabilities_ptr"></paramlink>.
10068         The returned estimates are in percentage of additional overhead, thus
10069         a time impact of 100 mean the application might run
10070         at half the speed.  
10071         The estimates are very rough approximations and are not guaranteed.
10072         Note also, that the estimates are of the impact of having the
10073         capability available--when and if it is used the impact may be
10074         much greater.
10075         Estimates can be for a single capability or for a set of 
10076         capabilities.  Note that the costs are not necessarily additive,
10077         adding support for one capability might make another available 
10078         for free or conversely having two capabilities at once may 
10079         have multiplicative impact.
10080         Estimates are relative to the current set of capabilities -
10081         that is, how much more impact given the currently possessed capabilities.
10082         <p/>
10083         Typically this function is used in the OnLoad function,
10084         some virtual machines may allow a limited set of capabilities to be
10085         added in the live phase.
10086         In this case, the set of potentially available capabilities
10087         will likely differ from the OnLoad phase set.
10088         <p/>
10089         See the
10090         <internallink id="capabilityExamples">Capability Examples</internallink>.
10091       </description>
10092       <origin>new</origin>
10093       <capabilities>
10094       </capabilities>
10095       <parameters>
10096         <param id="capabilities_ptr">
10097           <inptr><struct>jvmtiCapabilities</struct></inptr>
10098           <description>
10099             points to the <jvmti/> capabilities to evaluate.
10100           </description>
10101         </param>
10102         <param id="time_impact_ptr">
10103           <outptr><jint/></outptr>
10104           <description>
10105             On return, points to the estimated percentage increase in
10106             run time if this capability was added.
10107           </description>
10108         </param>
10109         <param id="space_impact_ptr">
10110           <outptr><jint/></outptr>
10111           <description>
10112             On return, points to the estimated percentage increase in
10113             memory space used if this capability was added.
10114           </description>
10115         </param>
10116       </parameters>
10117       <errors>
10118         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10119           The desired capabilities are not even potentially available.
10120         </error>
10121       </errors>
10122     </function>
10123     </elide>
10124 
10125     <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
10126       <synopsis>Add Capabilities</synopsis>
10127       <description>
10128         Set new capabilities by adding the capabilities 
10129         whose values are set to one (<code>1</code>) in
10130         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10131         All previous capabilities are retained.
10132         Typically this function is used in the <code>OnLoad</code> function.
10133         Some virtual machines may allow a limited set of capabilities to be
10134         added in the live phase.
10135         <p/>
10136         See the
10137         <internallink id="capabilityExamples">Capability Examples</internallink>.
10138       </description>
10139       <origin>new</origin>
10140       <capabilities>
10141       </capabilities>
10142       <parameters>
10143         <param id="capabilities_ptr">
10144           <inptr><struct>jvmtiCapabilities</struct></inptr>
10145           <description>
10146             Points to the <jvmti/> capabilities to add.
10147           </description>
10148         </param>
10149       </parameters>
10150       <errors>
10151         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10152           The desired capabilities are not even potentially available.
10153         </error>
10154       </errors>
10155     </function>
10156 
10157 
10158     <function id="RelinquishCapabilities" phase="onload" num="143">
10159       <synopsis>Relinquish Capabilities</synopsis>
10160       <description>
10161         Relinquish the capabilities
10162         whose values are set to one (<code>1</code>) in
10163         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10164         Some implementations may allow only one environment to have a capability
10165         (see the <internallink id="capability">capability introduction</internallink>).
10166         This function releases capabilities
10167         so that they may be used by other agents.
10168         All other capabilities are retained.
10169         The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
10170         Attempting to relinquish a capability that the agent does not possess is not an error.
10171           <issue>
10172             It is possible for the agent to be actively using capabilities
10173             which are being relinquished.  For example, a thread is currently
10174             suspended and can_suspend is being relinquished or an event is currently
10175             enabled and can_generate_whatever is being relinquished.
10176             There are three possible ways we could spec this:
10177             <ul>
10178               <li>relinquish automatically releases them</li>
10179               <li>relinquish checks and returns some error code if held</li>
10180               <li>it is the agent's responsibility and it is not checked</li>
10181             </ul>
10182             One of these should be chosen.
10183           </issue>
10184       </description>
10185       <origin>new</origin>
10186       <capabilities>
10187       </capabilities>
10188       <parameters>
10189         <param id="capabilities_ptr">
10190           <inptr><struct>jvmtiCapabilities</struct></inptr>
10191           <description>
10192             Points to the <jvmti/> capabilities to relinquish.
10193           </description>
10194         </param>
10195       </parameters>
10196       <errors>
10197       </errors>
10198     </function>
10199 
10200 
10201 
10202     <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
10203       <synopsis>Get Capabilities</synopsis>
10204         <description>
10205           Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> 
10206           features which this environment currently possesses.
10207           Each possessed capability is indicated by a one (<code>1</code>) in the
10208           corresponding field of the <internallink id="jvmtiCapabilities">capabilities
10209           structure</internallink>.
10210           An environment does not possess a capability unless it has been successfully added with
10211           <functionlink id="AddCapabilities"/>.
10212           An environment only loses possession of a capability if it has been relinquished with
10213           <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
10214           of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
10215           have been made.
10216           <p/>
10217           See the
10218           <internallink id="capabilityExamples">Capability Examples</internallink>.
10219         </description>
10220       <origin>jvmdiClone</origin>
10221       <capabilities>
10222       </capabilities>
10223       <parameters>
10224         <param id="capabilities_ptr">
10225           <outptr><struct>jvmtiCapabilities</struct></outptr>
10226           <description>
10227             On return, points to the <jvmti/> capabilities.
10228           </description>
10229         </param>
10230       </parameters>
10231       <errors>
10232       </errors>
10233     </function>
10234 
10235   </category>
10236   
10237   
10238   <category id="timers" label="Timers">
10239 
10240       <intro>
10241         These functions provide timing information.
10242         The resolution at which the time is updated is not specified. 
10243         They provides nanosecond precision, but not necessarily nanosecond accuracy. 
10244         Details about the timers, such as their maximum values, can be accessed with
10245         the timer information functions.  
10246       </intro>
10247 
10248       <typedef id="jvmtiTimerInfo" label="Timer Info">
10249         <description>
10250           The information function for each timer returns this data structure.
10251         </description>
10252         <field id="max_value">
10253           <jlong/>
10254             <description>
10255               The maximum value the timer can reach.
10256               After this value is reached the timer wraps back to zero.
10257               This is an unsigned value.  If tested or printed as a jlong (signed value)
10258               it may appear to be a negative number.
10259             </description>
10260         </field>
10261         <field id="may_skip_forward">
10262           <jboolean/>
10263           <description>
10264             If true, the timer can be externally adjusted and as a result skip forward.
10265             If false, the timer value will never increase faster than real time.
10266           </description>
10267         </field>
10268         <field id="may_skip_backward">
10269           <jboolean/>
10270           <description>
10271             If true, the timer can be externally adjusted and as a result skip backward.
10272             If false, the timer value will be monotonically increasing.
10273           </description>
10274         </field>
10275         <field id="kind">
10276           <enum>jvmtiTimerKind</enum>
10277           <description>
10278             The kind of timer.
10279             On a platform that does not distinguish between user and system time, <datalink 
10280                  id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
10281             is returned.
10282           </description>
10283         </field>
10284         <field id="reserved1">
10285           <jlong/>
10286             <description>
10287               Reserved for future use.
10288             </description>
10289         </field>
10290         <field id="reserved2">
10291           <jlong/>
10292             <description>
10293               Reserved for future use.
10294             </description>
10295         </field>
10296       </typedef>
10297 
10298       <intro>
10299         Where the timer kind is --
10300 
10301         <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
10302           <constant id="JVMTI_TIMER_USER_CPU" num="30">
10303             CPU time that a thread is in user mode.
10304           </constant>
10305           <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
10306             CPU time that a thread is in user or system mode.
10307           </constant>
10308           <constant id="JVMTI_TIMER_ELAPSED" num="32">
10309             Elapsed time.
10310           </constant>
10311         </constants>
10312       </intro>
10313 
10314     <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe"  impl="innative notrace" phase="start" num="134">
10315       <synopsis>Get Current Thread CPU Timer Information</synopsis>
10316       <description>
10317         Get information about the 
10318         <functionlink id="GetCurrentThreadCpuTime"/> timer. 
10319         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10320         are filled in with details about the timer.
10321         This information is specific to the platform and the implementation of
10322         <functionlink id="GetCurrentThreadCpuTime"/> and thus 
10323         does not vary by thread nor does it vary
10324         during a particular invocation of the VM.
10325         <p/>
10326         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10327         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10328         returned by <code>GetCurrentThreadCpuTimerInfo</code>
10329         and <functionlink id="GetThreadCpuTimerInfo"/>
10330         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10331       </description>
10332       <origin>new</origin>
10333       <capabilities>
10334         <required id="can_get_current_thread_cpu_time">
10335             Can get current thread CPU time.
10336         </required>
10337       </capabilities>
10338       <parameters>
10339         <param id="info_ptr">
10340           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10341           <description>
10342             On return, filled with information describing the time
10343             returned by <functionlink id="GetCurrentThreadCpuTime"/>.
10344           </description>
10345         </param>
10346       </parameters>
10347       <errors>
10348       </errors>
10349     </function>
10350 
10351     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10352       <synopsis>Get Current Thread CPU Time</synopsis>
10353       <description>
10354             Return the CPU time utilized by the current thread.  
10355             <p/>
10356             Note that the <functionlink id="GetThreadCpuTime"/>
10357             function provides CPU time for any thread, including
10358             the current thread. <code>GetCurrentThreadCpuTime</code> 
10359             exists to support platforms which cannot
10360             supply CPU time for threads other than the current 
10361             thread or which have more accurate information for
10362             the current thread (see 
10363             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10364             <functionlink id="GetThreadCpuTimerInfo"/>).
10365             On many platforms this call will be equivalent to:
10366 <example>
10367   GetThreadCpuTime(env, NULL, nanos_ptr)
10368 </example>
10369       </description>
10370       <origin>new</origin>
10371       <capabilities>
10372         <required id="can_get_current_thread_cpu_time">
10373             Can get current thread CPU time.
10374             <p/>
10375             If this capability is enabled after threads have started, 
10376             the implementation may choose any time up
10377             to and including the time that the capability is enabled 
10378             as the point where CPU time collection starts.
10379             <p/>
10380             This capability must be potentially available on any 
10381             platform where 
10382             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10383             is potentially available.
10384         </required>
10385       </capabilities>
10386       <parameters>
10387         <param id="nanos_ptr">
10388           <outptr><jlong/></outptr>
10389           <description>
10390             On return, points to the CPU time used by this thread
10391             in nanoseconds.  
10392             This is an unsigned value.  If tested or printed as a jlong (signed value)
10393             it may appear to be a negative number.
10394           </description>
10395         </param>
10396       </parameters>
10397       <errors>
10398       </errors>
10399     </function>
10400 
10401     <function id="GetThreadCpuTimerInfo" num="136">
10402       <synopsis>Get Thread CPU Timer Information</synopsis>
10403       <description>
10404         Get information about the 
10405         <functionlink id="GetThreadCpuTime"/> timer. 
10406         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10407         are filled in with details about the timer.
10408         This information is specific to the platform and the implementation of
10409         <functionlink id="GetThreadCpuTime"/> and thus 
10410         does not vary by thread nor does it vary
10411         during a particular invocation of the VM.
10412         <p/>
10413         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10414         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10415         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
10416         and <code>GetThreadCpuTimerInfo</code>
10417         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10418       </description>
10419       <origin>new</origin>
10420       <capabilities>
10421         <required id="can_get_thread_cpu_time">
10422             Can get thread CPU time.
10423         </required>
10424       </capabilities>
10425       <parameters>
10426         <param id="info_ptr">
10427           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10428           <description>
10429             On return, filled with information describing the time
10430             returned by <functionlink id="GetThreadCpuTime"/>.
10431           </description>
10432         </param>
10433       </parameters>
10434       <errors>
10435       </errors>
10436     </function>
10437 
10438     <function id="GetThreadCpuTime" num="137">
10439       <synopsis>Get Thread CPU Time</synopsis>
10440       <description>
10441           Return the CPU time utilized by the specified thread. 
10442           <p/>
10443           Get information about this timer with
10444           <functionlink id="GetThreadCpuTimerInfo"/>. 
10445       </description>
10446       <origin>new</origin>
10447       <capabilities>
10448         <required id="can_get_thread_cpu_time">
10449             Can get thread CPU time.
10450             <p/>
10451             If this capability is enabled after threads have started, 
10452             the implementation may choose any time up
10453             to and including the time that the capability is enabled 
10454             as the point where CPU time collection starts.
10455         </required>
10456       </capabilities>
10457       <parameters>
10458         <param id="thread">
10459           <jthread null="current"/>
10460             <description>
10461               The thread to query.
10462             </description>
10463         </param>
10464         <param id="nanos_ptr">
10465           <outptr><jlong/></outptr>
10466           <description>
10467             On return, points to the CPU time used by the specified thread
10468             in nanoseconds.  
10469             This is an unsigned value.  If tested or printed as a jlong (signed value)
10470             it may appear to be a negative number.
10471           </description>
10472         </param>
10473       </parameters>
10474       <errors>
10475       </errors>
10476     </function>
10477 
10478     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
10479       <synopsis>Get Timer Information</synopsis>
10480       <description>
10481         Get information about the 
10482         <functionlink id="GetTime"/> timer. 
10483         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10484         are filled in with details about the timer.
10485         This information will not change during a particular invocation of the VM.
10486       </description>
10487       <origin>new</origin>
10488       <capabilities>
10489       </capabilities>
10490       <parameters>
10491         <param id="info_ptr">
10492           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10493           <description>
10494             On return, filled with information describing the time
10495             returned by <functionlink id="GetTime"/>.
10496           </description>
10497         </param>
10498       </parameters>
10499       <errors>
10500       </errors>
10501     </function>
10502 
10503     <function id="GetTime" phase="any" callbacksafe="safe" num="139">
10504       <synopsis>Get Time</synopsis>
10505       <description>
10506           Return the current value of the system timer, in nanoseconds. 
10507           <p/>
10508           The value returned represents nanoseconds since some fixed but
10509           arbitrary time (perhaps in the future, so values may be
10510           negative).  This function provides nanosecond precision, but not
10511           necessarily nanosecond accuracy. No guarantees are made about
10512           how frequently values change.
10513           <p/>
10514           Get information about this timer with
10515           <functionlink id="GetTimerInfo"/>. 
10516       </description>
10517       <origin>new</origin>
10518       <capabilities>
10519       </capabilities>
10520       <parameters>
10521         <param id="nanos_ptr">
10522           <outptr><jlong/></outptr>
10523           <description>
10524             On return, points to the time in nanoseconds.  
10525             This is an unsigned value.  If tested or printed as a jlong (signed value)
10526             it may appear to be a negative number.
10527           </description>
10528         </param>
10529       </parameters>
10530       <errors>
10531       </errors>
10532     </function>
10533 
10534     <function id="GetAvailableProcessors" phase="any" num="144">
10535       <synopsis>Get Available Processors</synopsis>
10536       <description>
10537           Returns the number of processors available to the Java virtual machine.
10538           <p/>
10539           This value may change during a particular invocation of the virtual machine. 
10540           Applications that are sensitive to the number of available processors should
10541           therefore occasionally poll this property.
10542       </description>
10543       <origin>new</origin>
10544       <capabilities>
10545       </capabilities>
10546       <parameters>
10547         <param id="processor_count_ptr">
10548           <outptr><jint/></outptr>
10549           <description>
10550             On return, points to the maximum number of processors available to the
10551             virtual machine; never smaller than one.  
10552           </description>
10553         </param>
10554       </parameters>
10555       <errors>
10556       </errors>
10557     </function>
10558 
10559   </category>
10560 
10561 
10562   <category id="classLoaderSearch" label="Class Loader Search">
10563 
10564     <intro>
10565       These functions allow the agent to add to the locations that a class loader searches for a class.
10566       This is useful for installing instrumentation under the correct class loader.
10567     </intro>
10568 
10569     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
10570       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
10571       <description>
10572           This function can be used to cause instrumentation classes to be defined by the 
10573           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
10574           After the bootstrap
10575           class loader unsuccessfully searches for a class, the specified platform-dependent 
10576           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in 
10577           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, 
10578           the segments will be searched in the order that this function was called.
10579           <p/>
10580           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10581           search path segment to be searched after the bootstrap class loader unsuccessfully searches
10582           for a class. The segment is typically a directory or JAR file.
10583           <p/>      
10584           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
10585           path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">
10586           JAR file</externallink>. The agent should take care that the JAR file does not
10587           contain any classes or resources other than those to be defined by the bootstrap
10588           class loader for the purposes of instrumentation.
10589           <p/>
10590           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10591           reference that the Java virtual machine has previously unsuccessfully attempted
10592           to resolve always fails with the same error that was thrown as a result of the
10593           initial resolution attempt. Consequently, if the JAR file contains an entry
10594           that corresponds to a class for which the Java virtual machine has
10595           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10596           resolve that reference will fail with the same error as the initial attempt.
10597       </description>
10598       <origin>new</origin>
10599       <capabilities>
10600       </capabilities>
10601       <parameters>
10602         <param id="segment">
10603           <inbuf><char/></inbuf>
10604           <description>
10605             The platform-dependent search path segment, encoded as a
10606             <internallink id="mUTF">modified UTF-8</internallink> string.
10607           </description>
10608         </param>
10609       </parameters>
10610       <errors>
10611         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">   
10612           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10613            existing JAR file is an invalid path.
10614         </error>
10615       </errors>
10616     </function>
10617 
10618     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
10619       <synopsis>Add To System Class Loader Search</synopsis>
10620       <description>
10621           This function can be used to cause instrumentation classes to be
10622           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
10623           After the class loader unsuccessfully searches for a class, the specified platform-dependent search 
10624           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the 
10625           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the 
10626           segments will be searched in the order that this function was called.
10627           <p/>
10628           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10629           search path segment to be searched after the system class loader unsuccessfully searches
10630           for a class. The segment is typically a directory or JAR file.
10631           <p/>      
10632           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink 
10633           id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be
10634           searched after the system class loader unsuccessfully searches for a class. The agent should
10635           take care that the JAR file does not contain any classes or resources other than those to be
10636           defined by the system class loader for the purposes of instrumentation.
10637           <p/>
10638           In the live phase the system class loader supports adding a JAR file to be searched if
10639           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> 
10640           which takes a single parameter of type <code>java.lang.String</code>. The method is not required 
10641           to have <code>public</code> access. 
10642           <p/>
10643           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10644           reference that the Java virtual machine has previously unsuccessfully attempted
10645           to resolve always fails with the same error that was thrown as a result of the
10646           initial resolution attempt. Consequently, if the JAR file contains an entry
10647           that corresponds to a class for which the Java virtual machine has
10648           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10649           resolve that reference will fail with the same error as the initial attempt.
10650       </description>
10651       <origin>new</origin>
10652       <capabilities>
10653       </capabilities>
10654       <parameters>
10655         <param id="segment">
10656           <inbuf><char/></inbuf>
10657           <description>
10658             The platform-dependent search path segment, encoded as a
10659             <internallink id="mUTF">modified UTF-8</internallink> string.
10660           </description>
10661         </param>
10662       </parameters>
10663       <errors>
10664         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
10665           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10666            existing JAR file is an invalid path.
10667         </error>
10668         <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
10669           Operation not supported by the system class loader.
10670         </error>                                                                                         
10671       </errors>
10672     </function>
10673 
10674   </category>
10675 
10676 
10677   <category id="props" label="System Properties">
10678 
10679     <intro>
10680       These functions get and set system properties.
10681     </intro>
10682 
10683     <function id="GetSystemProperties" phase="onload" num="130">
10684       <synopsis>Get System Properties</synopsis>
10685       <description>
10686         The list of VM system property keys which may be used with 
10687         <functionlink id="GetSystemProperty"/> is returned.
10688         It is strongly recommended that virtual machines provide the
10689         following property keys:
10690         <ul>
10691           <li><code>java.vm.vendor</code></li>
10692           <li><code>java.vm.version</code></li>
10693           <li><code>java.vm.name</code></li>
10694           <li><code>java.vm.info</code></li>
10695           <li><code>java.library.path</code></li>
10696           <li><code>java.class.path</code></li>
10697         </ul>
10698         Provides access to system properties defined by and used
10699         by the VM.
10700         Properties set on the command-line are included.
10701         This allows getting and setting of these properties 
10702         before the VM even begins executing bytecodes.
10703         Since this is a VM view of system properties, the set of available 
10704         properties will usually be different than that
10705         in <code>java.lang.System.getProperties</code>.
10706         JNI method invocation may be used to access 
10707         <code>java.lang.System.getProperties</code>.
10708         <p/>
10709         The set of properties may grow during execution.          
10710       </description>
10711       <origin>new</origin>
10712       <capabilities>
10713       </capabilities>
10714       <parameters>
10715         <param id="count_ptr">
10716           <outptr><jint/></outptr>
10717           <description>
10718             On return, points to the number of property keys returned.
10719           </description>
10720         </param>
10721         <param id="property_ptr">
10722           <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
10723           <description>
10724             On return, points to an array of property keys, encoded as 
10725             <internallink id="mUTF">modified UTF-8</internallink> strings.
10726           </description>
10727         </param>
10728       </parameters>
10729       <errors>
10730       </errors>
10731     </function>
10732 
10733     <function id="GetSystemProperty" phase="onload" num="131">
10734       <synopsis>Get System Property</synopsis>
10735       <description>
10736         Return a VM system property value given the property key.  
10737         <p/>
10738         The function <functionlink id="GetSystemProperties"/>
10739         returns the set of property keys which may be used.
10740         The properties which can be retrieved may grow during
10741         execution.
10742         <p/>
10743         Since this is a VM view of system properties, the values 
10744         of properties may differ from that returned by 
10745         <code>java.lang.System.getProperty(String)</code>.
10746         A typical VM might copy the values of the VM system 
10747         properties into the <code>Properties</code> held by
10748         <code>java.lang.System</code> during the initialization
10749         of that class. Thereafter any changes to the VM system
10750         properties (with <functionlink id="SetSystemProperty"/>) 
10751         or the <code>java.lang.System</code> system properties
10752         (with <code>java.lang.System.setProperty(String,String)</code>)
10753         would cause the values to diverge.
10754         JNI method invocation may be used to access 
10755         <code>java.lang.System.getProperty(String)</code>.
10756       </description>
10757       <origin>new</origin>
10758       <capabilities>
10759       </capabilities>
10760       <parameters>
10761         <param id="property">
10762           <inbuf><char/></inbuf>
10763           <description>
10764             The key of the property to retrieve, encoded as a
10765             <internallink id="mUTF">modified UTF-8</internallink> string.
10766           </description>
10767         </param>
10768         <param id="value_ptr">
10769           <allocbuf><char/></allocbuf>
10770           <description>
10771             On return, points to the property value, encoded as a
10772             <internallink id="mUTF">modified UTF-8</internallink> string.
10773           </description>
10774         </param>
10775       </parameters>
10776       <errors>
10777         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10778           This property is not available.
10779           Use <functionlink id="GetSystemProperties"/> to find available properties.
10780         </error>
10781       </errors>
10782     </function>
10783 
10784     <function id="SetSystemProperty" phase="onloadOnly" num="132">
10785       <synopsis>Set System Property</synopsis>
10786       <description>
10787         Set a VM system property value.  
10788         <p/>
10789         The function <functionlink id="GetSystemProperties"/>
10790         returns the set of property keys, some of these may be settable.
10791         See <functionlink id="GetSystemProperty"/>.
10792       </description>
10793       <origin>new</origin>
10794       <capabilities>
10795       </capabilities>
10796       <parameters>
10797         <param id="property">
10798           <inbuf><char/></inbuf>
10799           <description>
10800             The key of the property, encoded as a
10801             <internallink id="mUTF">modified UTF-8</internallink> string.
10802           </description>
10803         </param>
10804         <param id="value_ptr">
10805           <inbuf>
10806             <char/>
10807             <nullok>
10808               do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
10809               if the property is not writeable
10810             </nullok>
10811           </inbuf>
10812           <description>
10813             The property value to set, encoded as a
10814             <internallink id="mUTF">modified UTF-8</internallink> string.
10815           </description>
10816         </param>
10817       </parameters>
10818       <errors>
10819         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10820           This property is not available or is not writeable.
10821         </error>
10822       </errors>
10823     </function>
10824 
10825   </category>
10826 
10827   <category id="general" label="General">
10828 
10829     <intro>
10830     </intro>
10831 
10832     <function id="GetPhase" jkernel="yes" phase="any" num="133">
10833       <synopsis>Get Phase</synopsis>
10834       <description>
10835           Return the current phase of VM execution.  
10836           The phases proceed in sequence:
10837           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
10838             <constant id="JVMTI_PHASE_ONLOAD" num="1">
10839               <code>OnLoad</code> phase: while in the
10840               <internallink id="onload"><code>Agent_OnLoad</code></internallink>
10841               or, for statically linked agents, the <internallink id="onload">
10842               <code>Agent_OnLoad_&lt;agent-lib-name&gt;
10843               </code></internallink> function.
10844             </constant>
10845             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
10846               Primordial phase: between return from <code>Agent_OnLoad</code>
10847               or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> and the
10848               <code>VMStart</code> event.
10849             </constant>
10850             <constant id="JVMTI_PHASE_START" num="6">
10851               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event 
10852               is sent and until the <code>VMInit</code> event is sent.
10853             </constant>
10854             <constant id="JVMTI_PHASE_LIVE" num="4">
10855               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
10856               and until the <eventlink id="VMDeath"></eventlink> event returns.
10857             </constant>
10858             <constant id="JVMTI_PHASE_DEAD" num="8">
10859               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
10860               start-up failure.
10861             </constant>
10862           </constants>
10863           In the case of start-up failure the VM will proceed directly to the dead
10864           phase skipping intermediate phases and neither a <code>VMInit</code> nor
10865           <code>VMDeath</code> event will be sent.
10866           <p/>
10867           Most <jvmti/> functions operate only in the live phase.
10868           The following functions operate in either the <code>OnLoad</code> or live phases:
10869           <functionphaselist phase="onload"/>
10870           The following functions operate in only the <code>OnLoad</code> phase:
10871           <functionphaselist phase="onloadOnly"/>
10872           The following functions operate in the start or live phases:
10873           <functionphaselist phase="start"/>
10874           The following functions operate in any phase:
10875           <functionphaselist phase="any"/>
10876           JNI functions (except the Invocation API) must only be used in the start or live phases.
10877           <p/>
10878           Most <jvmti/> events are sent only in the live phase.
10879           The following events operate in others phases:
10880           <eventphaselist phase="start"/>          
10881           <eventphaselist phase="any"/>          
10882       </description>
10883       <origin>new</origin>
10884       <capabilities>
10885       </capabilities>
10886       <parameters>
10887         <param id="phase_ptr">
10888           <outptr><enum>jvmtiPhase</enum></outptr>
10889           <description>
10890             On return, points to the phase.
10891           </description>
10892         </param>
10893       </parameters>
10894       <errors>
10895       </errors>
10896     </function>
10897 
10898     <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
10899       <synopsis>Dispose Environment</synopsis>
10900       <description>
10901         Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
10902         (see <internallink id="environments"><jvmti/> Environments</internallink>).
10903         Dispose of any resources held by the environment.  
10904         <issue>
10905             What resources are reclaimed? What is undone?
10906             Breakpoints,watchpoints removed?
10907         </issue>
10908         Threads suspended by this environment are not resumed by this call,
10909         this must be done explicitly by the agent.
10910         Memory allocated by this environment via calls to <jvmti/> functions
10911         is not released, this can be done explicitly by the agent
10912         by calling <functionlink id="Deallocate"/>.
10913         Raw monitors created by this environment are not destroyed, 
10914         this can be done explicitly by the agent
10915         by calling <functionlink id="DestroyRawMonitor"/>.
10916         The state of threads waiting on raw monitors created by this environment
10917         are not affected.
10918         <p/>
10919         Any <functionlink id="SetNativeMethodPrefix">native method
10920         prefixes</functionlink> for this environment will be unset;
10921         the agent must remove any prefixed native methods before
10922         dispose is called.
10923         <p/>
10924         Any <internallink id="capability">capabilities</internallink>
10925         held by this environment are relinquished.
10926         <p/>
10927         Events enabled by this environment will no longer be sent, however
10928         event handlers currently running will continue to run.  Caution must
10929         be exercised in the design of event handlers whose environment may
10930         be disposed and thus become invalid during their execution.
10931         <p/>
10932         This environment may not be used after this call.
10933         This call returns to the caller.
10934       </description>
10935       <origin>new</origin>
10936       <capabilities>
10937       </capabilities>
10938       <parameters>
10939       </parameters>
10940       <errors>
10941       </errors>
10942     </function>
10943 
10944     <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
10945       <synopsis>Set Environment Local Storage</synopsis>
10946       <description>
10947         The VM stores a pointer value associated with each environment.
10948         This pointer value is called <i>environment-local storage</i>.
10949         This value is <code>NULL</code> unless set with this function.
10950         Agents can allocate memory in which they store environment specific
10951         information. By setting environment-local storage it can then be
10952         accessed with 
10953         <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
10954         <p/>
10955         Called by the agent to set the value of the <jvmti/>
10956         environment-local storage. <jvmti/> supplies to the agent a pointer-size
10957         environment-local storage that can be used to record per-environment
10958         information.
10959       </description>
10960       <origin>new</origin>
10961       <capabilities>
10962       </capabilities>
10963       <parameters>
10964         <param id="data">
10965           <inbuf> 
10966             <void/> 
10967             <nullok>value is set to <code>NULL</code></nullok> 
10968           </inbuf> 
10969           <description>
10970             The value to be entered into the environment-local storage.
10971           </description>
10972         </param>
10973       </parameters>
10974       <errors>
10975       </errors>
10976     </function>
10977 
10978     <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
10979       <synopsis>Get Environment Local Storage</synopsis>
10980       <description>
10981         Called by the agent to get the value of the <jvmti/> environment-local
10982         storage. 
10983       </description>
10984       <origin>new</origin>
10985       <capabilities>
10986       </capabilities>
10987       <parameters>
10988         <param id="data_ptr">
10989           <agentbuf><void/></agentbuf>
10990           <description>
10991             Pointer through which the value of the environment local 
10992             storage is returned.
10993             If environment-local storage has not been set with
10994             <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned 
10995             pointer is <code>NULL</code>.
10996           </description>
10997         </param>
10998       </parameters>
10999       <errors>
11000       </errors>
11001     </function>
11002 
11003     <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
11004       <synopsis>Get Version Number</synopsis>
11005       <description>
11006         Return the <jvmti/> version via <code>version_ptr</code>.
11007         The return value is the version identifier. 
11008         The version identifier includes major, minor and micro
11009         version as well as the interface type.
11010         <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
11011           <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
11012             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
11013           </constant>
11014           <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
11015             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
11016           </constant>
11017         </constants>
11018         <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
11019           <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
11020             Mask to extract interface type.  
11021             The value of the version returned by this function masked with
11022             <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
11023             <code>JVMTI_VERSION_INTERFACE_JVMTI</code> 
11024             since this is a <jvmti/> function.
11025           </constant>
11026           <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
11027             Mask to extract major version number.
11028           </constant>
11029           <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
11030             Mask to extract minor version number.
11031           </constant>
11032           <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
11033             Mask to extract micro version number.
11034           </constant>
11035         </constants>
11036         <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
11037           <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
11038             Shift to extract major version number.
11039           </constant>
11040           <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
11041             Shift to extract minor version number.
11042           </constant>
11043           <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
11044             Shift to extract micro version number.
11045           </constant>
11046         </constants>
11047       </description>
11048       <origin>jvmdi</origin>
11049       <capabilities>
11050       </capabilities>
11051       <parameters>
11052         <param id="version_ptr">
11053           <outptr><jint/></outptr>
11054           <description>
11055             On return, points to the <jvmti/> version.
11056           </description>
11057         </param>
11058       </parameters>
11059       <errors>
11060       </errors>
11061     </function>
11062 
11063 
11064     <function id="GetErrorName" phase="any" num="128">
11065       <synopsis>Get Error Name</synopsis>
11066       <description>
11067         Return the symbolic name for an 
11068           <internallink id="ErrorSection">error code</internallink>.  
11069         <p/>
11070         For example 
11071         <code>GetErrorName(env, JVMTI_ERROR_NONE, &amp;err_name)</code> 
11072         would return in <code>err_name</code> the string
11073         <code>"JVMTI_ERROR_NONE"</code>.
11074       </description>
11075       <origin>new</origin>
11076       <capabilities>
11077       </capabilities>
11078       <parameters>
11079         <param id="error">
11080           <enum>jvmtiError</enum>
11081           <description>
11082             The error code.
11083           </description>
11084         </param>
11085         <param id="name_ptr">
11086           <allocbuf><char/></allocbuf>
11087           <description>
11088             On return, points to the error name.
11089             The name is encoded as a
11090             <internallink id="mUTF">modified UTF-8</internallink> string,
11091             but is restricted to the ASCII subset.
11092           </description>
11093         </param>
11094       </parameters>
11095       <errors>
11096       </errors>
11097     </function>
11098 
11099     <function id="SetVerboseFlag" phase="any" num="150">
11100       <synopsis>Set Verbose Flag</synopsis>
11101       <description>
11102         <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
11103           <constant id="JVMTI_VERBOSE_OTHER" num="0">
11104             Verbose output other than the below.
11105           </constant>
11106           <constant id="JVMTI_VERBOSE_GC" num="1">
11107             Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
11108           </constant>
11109           <constant id="JVMTI_VERBOSE_CLASS" num="2">
11110             Verbose class loading output, like that specified with <code>-verbose:class</code>.
11111           </constant>
11112           <constant id="JVMTI_VERBOSE_JNI" num="4">
11113             Verbose JNI output, like that specified with <code>-verbose:jni</code>.
11114           </constant>
11115         </constants>
11116         Control verbose output.
11117         This is the output which typically is sent to <code>stderr</code>. 
11118       </description>
11119       <origin>new</origin>
11120       <capabilities>
11121       </capabilities>
11122       <parameters>
11123         <param id="flag">
11124           <enum>jvmtiVerboseFlag</enum>
11125           <description>
11126             Which verbose flag to set.
11127           </description>
11128         </param>
11129         <param id="value">
11130           <jboolean/>
11131           <description>
11132             New value of the flag.
11133           </description>
11134         </param>
11135       </parameters>
11136       <errors>
11137       </errors>
11138     </function>
11139 
11140 
11141     <function id="GetJLocationFormat" phase="any" num="129">
11142       <synopsis>Get JLocation Format</synopsis>
11143       <description>
11144         Although the greatest functionality is achieved with location information
11145         referencing the virtual machine bytecode index, the definition of
11146         <code>jlocation</code> has intentionally been left unconstrained to allow VM 
11147         implementations that do not have this information.
11148         <p/>
11149         This function describes the representation of <code>jlocation</code> used in this VM.
11150         If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, 
11151         <code>jlocation</code>s can
11152         be used as in indices into the array returned by
11153         <functionlink id="GetBytecodes"></functionlink>.  
11154         <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
11155           <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
11156             <code>jlocation</code> values represent virtual machine 
11157             bytecode indices--that is, offsets into the 
11158             virtual machine code for a method.
11159           </constant>
11160           <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
11161             <code>jlocation</code> values represent native machine
11162             program counter values.
11163           </constant>
11164           <constant id="JVMTI_JLOCATION_OTHER" num="0">
11165             <code>jlocation</code> values have some other representation.
11166           </constant>
11167         </constants>
11168       </description>
11169       <origin>new</origin>
11170       <capabilities>
11171       </capabilities>
11172       <parameters>
11173         <param id="format_ptr">
11174           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11175           <description>
11176             On return, points to the format identifier for <code>jlocation</code> values.
11177           </description>
11178         </param>
11179       </parameters>
11180       <errors>
11181       </errors>
11182     </function>
11183 
11184   </category>
11185 
11186 </functionsection>
11187 
11188 <errorsection label="Error Reference">
11189   <intro>
11190     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11191     <p/>
11192     It is the responsibility of the agent to call <jvmti/> functions with 
11193     valid parameters and in the proper context (calling thread is attached,
11194     phase is correct, etc.).  
11195     Detecting some error conditions may be difficult, inefficient, or 
11196     impossible for an implementation.
11197     The errors listed in 
11198     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11199     must be detected by the implementation.
11200     All other errors represent the recommended response to the error
11201     condition. 
11202   </intro>
11203 
11204   <errorcategory id="universal-error" label="Universal Errors">
11205     <intro>
11206       The following errors may be returned by any function
11207     </intro>
11208 
11209     <errorid id="JVMTI_ERROR_NONE" num="0">
11210       No error has occurred.  This is the error code that is returned
11211       on successful completion of the function.
11212     </errorid>
11213     <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
11214       Pointer is unexpectedly <code>NULL</code>.
11215     </errorid>
11216     <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
11217       The function attempted to allocate memory and no more memory was 
11218       available for allocation.
11219     </errorid>
11220     <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
11221       The desired functionality has not been enabled in this virtual machine.
11222     </errorid>
11223     <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
11224       The thread being used to call this function is not attached
11225       to the virtual machine.  Calls must be made from attached threads.
11226       See <code>AttachCurrentThread</code> in the JNI invocation API.
11227     </errorid>
11228     <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
11229       The <jvmti/> environment provided is no longer connected or is
11230       not an environment.
11231     </errorid>
11232     <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
11233       The desired functionality is not available in the current
11234         <functionlink id="GetPhase">phase</functionlink>.
11235       Always returned if the virtual machine has completed running.
11236     </errorid>
11237     <errorid id="JVMTI_ERROR_INTERNAL" num="113">
11238       An unexpected internal error has occurred.
11239     </errorid>
11240   </errorcategory>
11241 
11242   <errorcategory id="reqerrors" label="Function Specific Required Errors">
11243     <intro>
11244       The following errors are returned by some <jvmti/> functions and must
11245       be returned by the implementation when the condition occurs.
11246     </intro>
11247 
11248     <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
11249       Invalid priority.
11250     </errorid>
11251     <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
11252       Thread was not suspended.
11253     </errorid>
11254     <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
11255       Thread already suspended.
11256     </errorid>
11257     <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
11258       This operation requires the thread to be alive--that is,
11259       it must be started and not yet have died.
11260     </errorid>
11261     <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
11262       The class has been loaded but not yet prepared.
11263     </errorid>
11264     <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
11265       There are no Java programming language or JNI stack frames at the specified depth.
11266     </errorid>
11267     <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
11268       Information about the frame is not available (e.g. for native frames).
11269     </errorid>
11270     <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
11271       Item already set.
11272     </errorid>
11273     <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
11274       Desired element (e.g. field or breakpoint) not found
11275     </errorid>
11276     <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
11277       This thread doesn't own the raw monitor.
11278     </errorid>
11279     <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
11280       The call has been interrupted before completion.
11281     </errorid>
11282     <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
11283       The class cannot be modified.
11284     </errorid>
11285     <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
11286       The functionality is not available in this virtual machine.
11287     </errorid>
11288     <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
11289       The requested information is not available.
11290     </errorid>
11291     <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
11292       The specified event type ID is not recognized.
11293     </errorid>
11294     <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
11295       The requested information is not available for native method.
11296     </errorid>
11297     <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
11298       The class loader does not support this operation.
11299     </errorid>
11300   </errorcategory>
11301 
11302   <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
11303     <intro>
11304       The following errors are returned by some <jvmti/> functions.
11305       They are returned in the event of invalid parameters passed by the
11306       agent or usage in an invalid context.  
11307       An implementation is not required to detect these errors.
11308     </intro>
11309 
11310     <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
11311       The passed thread is not a valid thread.
11312     </errorid>
11313     <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
11314       Invalid field.
11315     </errorid>
11316     <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
11317       Invalid method.
11318     </errorid>
11319     <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
11320       Invalid location.
11321     </errorid>
11322     <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
11323       Invalid object.
11324     </errorid>
11325     <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
11326       Invalid class.
11327     </errorid>
11328     <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
11329       The variable is not an appropriate type for the function used.
11330     </errorid>
11331     <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
11332       Invalid slot.
11333     </errorid>
11334     <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
11335       The capability being used is false in this environment.
11336     </errorid>
11337     <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
11338       Thread group invalid.
11339     </errorid>
11340     <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
11341       Invalid raw monitor.
11342     </errorid>
11343     <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
11344       Illegal argument.
11345     </errorid>
11346     <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
11347       The state of the thread has been modified, and is now inconsistent.
11348     </errorid>
11349     <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
11350       A new class file has a version number not supported by this VM.
11351     </errorid>
11352     <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
11353       A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
11354     </errorid>
11355     <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
11356       The new class file definitions would lead to a circular
11357       definition (the VM would return a <code>ClassCircularityError</code>).
11358     </errorid>
11359     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
11360       A new class file would require adding a method.
11361     </errorid>
11362     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
11363       A new class version changes a field.
11364     </errorid>
11365     <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
11366       The class bytes fail verification.
11367     </errorid>
11368     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
11369       A direct superclass is different for the new class
11370       version, or the set of directly implemented
11371       interfaces is different.
11372     </errorid>
11373     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
11374       A new class version does not declare a method
11375       declared in the old class version.
11376     </errorid>
11377     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
11378       The class name defined in the new class file is 
11379       different from the name in the old class object.
11380     </errorid>
11381     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
11382       A new class version has different modifiers.
11383     </errorid>
11384     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
11385       A method in the new class version has different modifiers
11386       than its counterpart in the old class version.
11387     </errorid>
11388   </errorcategory>
11389 </errorsection>
11390 
11391 <eventsection label="Events">
11392   <intro label="Handling Events" id="eventIntro">
11393     Agents can be informed of many events that occur in application
11394     programs.
11395     <p/>
11396     To handle events, designate a set of callback functions with
11397     <functionlink id="SetEventCallbacks"></functionlink>. 
11398     For each event the corresponding callback function will be 
11399     called.
11400     Arguments to the callback function provide additional
11401     information about the event. 
11402     <p/>
11403     The callback function is usually called from within an application 
11404     thread. The <jvmti/> implementation does not 
11405     queue events in any way. This means
11406     that event callback functions must be written 
11407     carefully. Here are some general guidelines. See 
11408     the individual event descriptions for further
11409     suggestions.
11410     <p/>
11411     <ul>
11412       <li>Any exception thrown during the execution of an event callback can 
11413         overwrite any current pending exception in the current application thread.
11414         Care must be taken to preserve a pending exception
11415         when an event callback makes a JNI call that might generate an exception.
11416       </li>
11417       <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
11418         not queue events. If an agent needs to process events one at a time, it 
11419         can use a raw monitor inside the 
11420         event callback functions to serialize event processing.
11421       </li>
11422       <li>Event callback functions that execute JNI's FindClass function to load
11423         classes need to note that FindClass locates the class loader associated 
11424         with the current native method. For the purposes of class loading, an
11425         event callback that includes a JNI environment as a parameter to the
11426         callback will treated as if it is a native call, where the native method
11427         is in the class of the event thread's current frame.
11428       </li>
11429     </ul>
11430     <p/>
11431     Some <jvmti/> events identify objects with JNI references. 
11432     All references 
11433     in <jvmti/> events are JNI local references and will become invalid
11434     after the event callback returns.
11435     Unless stated otherwise, memory referenced by pointers sent in event
11436     callbacks may not be referenced after the event callback returns.
11437     <p/>
11438     Except where stated otherwise, events are delivered on the thread
11439     that caused the event.
11440     Events are sent at the time they occur.
11441     The specification for each event includes the set of
11442     <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
11443     if an event triggering activity occurs during another phase, no event 
11444     is sent. 
11445     <p/>
11446     A thread that generates an event does not change its execution status
11447     (for example, the event does not cause the thread to be suspended).
11448     If an agent wishes the event to result in suspension, then the agent
11449     is responsible for explicitly suspending the thread with 
11450     <functionlink id="SuspendThread"></functionlink>.
11451     <p/>
11452     If an event is enabled in multiple environments, the event will be sent
11453     to each agent in the order that the environments were created.
11454   </intro>
11455 
11456   <intro label="Enabling Events" id="enablingevents">
11457     All events are initially disabled.  In order to receive any
11458     event:
11459       <ul>
11460         <li>
11461           If the event requires a capability, that capability must
11462           be added with 
11463           <functionlink id="AddCapabilities"></functionlink>.
11464         </li>
11465         <li>
11466           A callback for the event must be set with 
11467           <functionlink id="SetEventCallbacks"></functionlink>.
11468         </li>
11469         <li>
11470           The event must be enabled with
11471           <functionlink id="SetEventNotificationMode"></functionlink>. 
11472         </li>
11473       </ul>
11474   </intro>
11475 
11476   <intro label="Multiple Co-located Events" id="eventorder">
11477     In many situations it is possible for multiple events to occur 
11478     at the same location in one thread. When this happens, all the events 
11479     are reported through the event callbacks in the order specified in this section.
11480     <p/>
11481     If the current location is at the entry point of a method, the 
11482     <eventlink id="MethodEntry"></eventlink> event is reported before
11483     any other event at the current location in the same thread.
11484     <p/>
11485     If an exception catch has been detected at the current location,
11486     either because it is the beginning of a catch clause or a native method
11487     that cleared a pending exception has returned, the
11488     <code>exceptionCatch</code> event is reported before
11489     any other event at the current location in the same thread.
11490     <p/>
11491     If a <code>singleStep</code> event or 
11492     <code>breakpoint</code> event is triggered at the 
11493     current location, the event is defined to occur 
11494     immediately before the code at the current location is executed. 
11495     These events are reported before any events which are triggered 
11496     by the execution of code at the current location in the same 
11497     thread (specifically: 
11498     <code>exception</code>,
11499     <code>fieldAccess</code>, and
11500     <code>fieldModification</code>).
11501     If both a step and breakpoint event are triggered for the same thread and 
11502     location, the step event is reported before the breakpoint event.
11503     <p/>
11504     If the current location is the exit point of a method (that is, the last
11505     location before returning to the caller), the 
11506     <eventlink id="MethodExit"></eventlink> event and 
11507     the <eventlink id="FramePop"></eventlink> event (if requested)
11508     are reported after all other events at the current location in the same
11509     thread. There is no specified ordering of these two events 
11510     with respect to each other.
11511     <p/>
11512     Co-located events can be triggered during the processing of some other
11513     event by the agent at the same location in the same thread.
11514     If such an event, of type <i>y</i>, is triggered during the processing of 
11515     an event of type <i>x</i>, and if <i>x</i> 
11516     precedes <i>y</i> in the ordering specified above, the co-located event 
11517     <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
11518     <i>y</i>, <i>y</i> is not reported for the current thread and location.
11519     For example, if a breakpoint is set at the current location 
11520     during the processing of <eventlink id="SingleStep"></eventlink>,
11521     that breakpoint will be reported before the thread moves off the current 
11522     location.
11523     <p/>The following events are never considered to be co-located with 
11524     other events.
11525     <ul>
11526       <li><eventlink id="VMStart"></eventlink></li>
11527       <li><eventlink id="VMInit"></eventlink></li>
11528       <li><eventlink id="VMDeath"></eventlink></li>
11529       <li><eventlink id="ThreadStart"></eventlink></li>
11530       <li><eventlink id="ThreadEnd"></eventlink></li>
11531       <li><eventlink id="ClassLoad"></eventlink></li>
11532       <li><eventlink id="ClassPrepare"></eventlink></li>
11533     </ul>
11534   </intro>
11535 
11536   <intro label="Event Callbacks" id="jvmtiEventCallbacks">
11537       The event callback structure below is used to specify the handler function
11538       for events.  It is set with the
11539       <functionlink id="SetEventCallbacks"></functionlink> function. 
11540   </intro>
11541 
11542   <event label="Single Step"
11543          id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
11544     <description>
11545       Single step events allow the agent to trace thread execution
11546       at the finest granularity allowed by the VM. A single step event is
11547       generated whenever a thread reaches a new location. 
11548       Typically, single step events represent the completion of one VM 
11549       instruction as defined in <vmspec/>. However, some implementations 
11550       may define locations differently. In any case the 
11551       <code>method</code> and <code>location</code>
11552       parameters  uniquely identify the current location and allow
11553       the mapping to source file and line number when that information is 
11554       available.
11555       <p/>
11556       No single step events are generated from within native methods.
11557     </description>
11558     <origin>jvmdi</origin>
11559     <capabilities>
11560       <required id="can_generate_single_step_events"></required>
11561     </capabilities>
11562     <parameters> 
11563       <param id="jni_env">
11564         <outptr>
11565           <struct>JNIEnv</struct>
11566         </outptr>
11567           <description>
11568             The JNI environment of the event (current) thread
11569           </description>
11570       </param>
11571       <param id="thread">
11572         <jthread/>
11573           <description>
11574             Thread about to execution a new instruction
11575           </description>
11576       </param>
11577       <param id="klass">
11578         <jclass method="method"/>
11579           <description>
11580             Class of the method about to execute a new instruction
11581           </description>
11582       </param>
11583       <param id="method">
11584         <jmethodID class="klass"/>
11585           <description>
11586             Method about to execute a new instruction
11587           </description>
11588       </param>
11589       <param id="location">
11590         <jlocation/>
11591         <description>
11592           Location of the new instruction
11593         </description>
11594       </param>
11595     </parameters>
11596   </event>
11597 
11598   <event label="Breakpoint"
11599          id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
11600     <description>
11601       Breakpoint events are generated whenever a thread reaches a location
11602       designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
11603       The <code>method</code> and <code>location</code>
11604       parameters uniquely identify the current location and allow
11605       the mapping to source file and line number when that information is 
11606       available.
11607     </description>
11608     <origin>jvmdi</origin>
11609     <capabilities>
11610       <required id="can_generate_breakpoint_events"></required>
11611     </capabilities>
11612     <parameters> 
11613       <param id="jni_env">
11614         <outptr>
11615           <struct>JNIEnv</struct>
11616         </outptr>
11617           <description>
11618             The JNI environment of the event (current) thread.
11619           </description>
11620       </param>
11621       <param id="thread">
11622         <jthread/>
11623           <description>
11624             Thread that hit the breakpoint
11625           </description>
11626       </param>
11627       <param id="klass">
11628         <jclass method="method"/>
11629           <description>
11630             Class of the method that hit the breakpoint
11631           </description>
11632       </param>
11633       <param id="method">
11634         <jmethodID class="klass"/>
11635           <description>
11636             Method that hit the breakpoint
11637           </description>
11638       </param>
11639       <param id="location">
11640         <jlocation/>
11641         <description>
11642           location of the breakpoint
11643         </description>
11644       </param>
11645     </parameters>
11646   </event>
11647 
11648   <event label="Field Access"
11649          id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
11650     <description>
11651       Field access events are generated whenever a thread accesses
11652       a field that was designated as a watchpoint 
11653       with <functionlink id="SetFieldAccessWatch"></functionlink>.
11654       The <code>method</code> and <code>location</code> 
11655       parameters uniquely identify the current location and allow
11656       the mapping to source file and line number when that information is 
11657       available. 
11658     </description>
11659     <origin>jvmdi</origin>
11660     <capabilities>
11661       <required id="can_generate_field_access_events"></required>
11662     </capabilities>
11663     <parameters> 
11664       <param id="jni_env">
11665         <outptr>
11666           <struct>JNIEnv</struct>
11667         </outptr>
11668           <description>
11669             The JNI environment of the event (current) thread
11670           </description>
11671       </param>
11672       <param id="thread">
11673         <jthread/>
11674           <description>
11675             Thread accessing the field
11676           </description>
11677       </param>
11678       <param id="klass">
11679         <jclass method="method"/>
11680           <description>
11681             Class of the method where the access is occurring
11682           </description>
11683       </param>
11684       <param id="method">
11685         <jmethodID class="klass"/>
11686           <description>
11687             Method where the access is occurring
11688           </description>
11689       </param>
11690       <param id="location">
11691         <jlocation/>
11692         <description>
11693           Location where the access is occurring
11694         </description>
11695       </param>
11696       <param id="field_klass">
11697         <jclass field="field"/>
11698           <description>
11699             Class of the field being accessed
11700           </description>
11701       </param>
11702       <param id="object">
11703         <jobject/>
11704           <description>
11705             Object with the field being accessed if the field is an
11706             instance field; <code>NULL</code> otherwise
11707           </description>
11708       </param>
11709       <param id="field">
11710         <jfieldID class="field_klass"/>
11711           <description>
11712             Field being accessed
11713           </description>
11714       </param>
11715     </parameters>
11716   </event>
11717 
11718   <event label="Field Modification"
11719          id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
11720     <description>
11721       Field modification events are generated whenever a thread modifies
11722       a field that was designated as a watchpoint 
11723       with <functionlink id="SetFieldModificationWatch"></functionlink>.
11724       The <code>method</code> and <code>location</code> 
11725       parameters uniquely identify the current location and allow
11726       the mapping to source file and line number when that information is 
11727       available. 
11728     </description>
11729     <origin>jvmdi</origin>
11730     <capabilities>
11731       <required id="can_generate_field_modification_events"></required>
11732     </capabilities>
11733     <parameters> 
11734       <param id="jni_env">
11735         <outptr>
11736           <struct>JNIEnv</struct>
11737         </outptr>
11738           <description>
11739             The JNI environment of the event (current) thread
11740           </description>
11741       </param>
11742       <param id="thread">
11743         <jthread/>
11744           <description>
11745             Thread modifying the field
11746           </description>
11747       </param>
11748       <param id="klass">
11749         <jclass method="method"/>
11750           <description>
11751             Class of the method where the modification is occurring
11752           </description>
11753       </param>
11754       <param id="method">
11755         <jmethodID class="klass"/>
11756           <description>
11757             Method where the modification is occurring
11758           </description>
11759       </param>
11760       <param id="location">
11761         <jlocation/>
11762         <description>
11763           Location where the modification is occurring
11764         </description>
11765       </param>
11766       <param id="field_klass">
11767         <jclass field="field"/>
11768           <description>
11769             Class of the field being modified
11770           </description>
11771       </param>
11772       <param id="object">
11773         <jobject/>
11774           <description>
11775             Object with the field being modified if the field is an
11776             instance field; <code>NULL</code> otherwise
11777           </description>
11778       </param>
11779       <param id="field">
11780         <jfieldID class="field_klass"/>
11781           <description>
11782             Field being modified
11783           </description>
11784       </param>
11785       <param id="signature_type">
11786         <char/>
11787         <description>
11788           Signature type of the new value
11789         </description>
11790       </param>
11791       <param id="new_value">
11792         <jvalue/>
11793         <description>
11794           The new value
11795         </description>
11796       </param>
11797     </parameters>
11798   </event>
11799 
11800   <event label="Frame Pop"
11801          id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
11802     <description>
11803       Frame pop events are generated upon exit from a single method 
11804       in a single frame as specified
11805       in a call to <functionlink id="NotifyFramePop"></functionlink>.
11806       This is true whether termination is caused by
11807       executing its return instruction
11808       or by throwing an exception to its caller 
11809       (see <paramlink id="was_popped_by_exception"></paramlink>).
11810       However, frame pops caused by the <functionlink id="PopFrame"/> 
11811       function are not reported.
11812       <p/>
11813       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11814       identifies the executable location in the returning method, 
11815       immediately prior to the return. 
11816     </description>
11817     <origin>jvmdi</origin>
11818     <capabilities>
11819       <required id="can_generate_frame_pop_events"></required>
11820     </capabilities>
11821     <parameters> 
11822       <param id="jni_env">
11823         <outptr>
11824           <struct>JNIEnv</struct>
11825         </outptr>
11826           <description>
11827             The JNI environment of the event (current) thread
11828           </description>
11829       </param>
11830       <param id="thread">
11831         <jthread/>
11832           <description>
11833             Thread that is popping the frame
11834           </description>
11835       </param>
11836       <param id="klass">
11837         <jclass method="method"/>
11838           <description>
11839             Class of the method being popped
11840           </description>
11841       </param>
11842       <param id="method">
11843         <jmethodID class="klass"/>
11844           <description>
11845             Method being popped
11846           </description>
11847       </param>
11848       <param id="was_popped_by_exception">
11849         <jboolean/>
11850         <description>
11851           True if frame was popped by a thrown exception.
11852           False if method exited through its return instruction.
11853         </description>
11854       </param>
11855     </parameters>
11856   </event>
11857 
11858   <event label="Method Entry"
11859          id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
11860     <description>
11861       Method entry events are generated upon entry of Java 
11862       programming language methods (including native methods).
11863       <p/>
11864       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11865       identifies the initial executable location in
11866       the method. 
11867       <p/>
11868       Enabling method
11869       entry or exit events will significantly degrade performance on many platforms and is thus
11870       not advised for performance critical usage (such as profiling).
11871       <internallink id="bci">Bytecode instrumentation</internallink> should be 
11872       used in these cases.
11873     </description>
11874     <origin>jvmdi</origin>
11875     <capabilities>
11876       <required id="can_generate_method_entry_events"></required>
11877     </capabilities>
11878     <parameters> 
11879       <param id="jni_env">
11880         <outptr>
11881           <struct>JNIEnv</struct>
11882         </outptr>
11883           <description>
11884             The JNI environment of the event (current) thread
11885           </description>
11886       </param>
11887       <param id="thread">
11888         <jthread/>
11889           <description>
11890             Thread entering the method
11891           </description>
11892       </param>
11893       <param id="klass">
11894         <jclass method="method"/>
11895           <description>
11896             Class of the method being entered
11897           </description>
11898       </param>
11899       <param id="method">
11900         <jmethodID class="klass"/>
11901           <description>
11902             Method being entered
11903           </description>
11904       </param>
11905     </parameters>
11906   </event>
11907 
11908   <event label="Method Exit"
11909          id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
11910     <description>
11911       Method exit events are generated upon exit from Java 
11912       programming language methods (including native methods).
11913       This is true whether termination is caused by
11914       executing its return instruction
11915       or by throwing an exception to its caller 
11916       (see <paramlink id="was_popped_by_exception"></paramlink>).
11917       <p/>
11918       The <code>method</code> field uniquely identifies the
11919       method being entered or exited. The <code>frame</code> field provides 
11920       access to the stack frame for the method.
11921       <p/>
11922       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11923       identifies the executable location in the returning method 
11924       immediately prior to the return. 
11925       <p/>
11926         Enabling method
11927         entry or exit events will significantly degrade performance on many platforms and is thus
11928         not advised for performance critical usage (such as profiling).
11929         <internallink id="bci">Bytecode instrumentation</internallink> should be 
11930         used in these cases.
11931     </description>
11932     <origin>jvmdi</origin>
11933     <capabilities>
11934       <required id="can_generate_method_exit_events"></required>
11935     </capabilities>
11936     <parameters>
11937       <param id="jni_env">
11938         <outptr>
11939           <struct>JNIEnv</struct>
11940         </outptr>
11941           <description>
11942             The JNI environment of the event (current) thread
11943           </description>
11944       </param>
11945       <param id="thread">
11946         <jthread/>
11947           <description>
11948             Thread exiting the method
11949           </description>
11950       </param>
11951       <param id="klass">
11952         <jclass method="method"/>
11953           <description>
11954             Class of the method being exited
11955           </description>
11956       </param>
11957       <param id="method">
11958         <jmethodID class="klass"/>
11959           <description>
11960             Method being exited
11961           </description>
11962       </param>
11963       <param id="was_popped_by_exception">
11964         <jboolean/>
11965         <description>
11966           True if frame was popped by a thrown exception.
11967           False if method exited through its return instruction.
11968         </description>
11969       </param>
11970       <param id="return_value">
11971         <jvalue/>
11972         <description>
11973           The return value of the method being exited.
11974           Undefined and should not be used if 
11975           <paramlink id="was_popped_by_exception"></paramlink>
11976           is true.
11977         </description>
11978       </param>
11979     </parameters>
11980   </event>
11981 
11982   <event label="Native Method Bind" phase="any"
11983          id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
11984     <description>
11985       A Native Method Bind event is sent when a VM binds a 
11986       Java programming language native method
11987       to the address of a function that implements the native method. 
11988       This will occur when the native method is called for the first time
11989       and also occurs when the JNI function <code>RegisterNatives</code> is called.
11990       This event allows the bind to be redirected to an agent-specified
11991       proxy function. 
11992       This event is not sent when the native method is unbound.
11993       Typically, this proxy function will need to be specific to a 
11994       particular method or, to handle the general case, automatically
11995       generated assembly code, since after instrumentation code is 
11996       executed the function at the original binding 
11997       address will usually be invoked.
11998       The original binding can be restored or the redirection changed
11999       by use of the JNI function <code>RegisterNatives</code>.
12000       Some events may be sent during the primordial phase, JNI and
12001       most of <jvmti/> cannot be used at this time but the method and
12002       address can be saved for use later.
12003     </description>
12004     <origin>new</origin>
12005     <capabilities>
12006       <required id="can_generate_native_method_bind_events"></required>
12007     </capabilities>
12008     <parameters>
12009       <param id="jni_env">
12010         <outptr>
12011           <struct>JNIEnv</struct>
12012         </outptr>
12013           <description>
12014             The JNI environment of the event (current) thread
12015             Will be <code>NULL</code> if sent during the primordial 
12016             <functionlink id="GetPhase">phase</functionlink>.
12017           </description>
12018       </param>
12019       <param id="thread">
12020         <jthread/>
12021           <description>
12022             Thread requesting the bind
12023           </description>
12024       </param>
12025       <param id="klass">
12026         <jclass method="method"/>
12027           <description>
12028             Class of the method being bound
12029           </description>
12030       </param>
12031       <param id="method">
12032         <jmethodID class="klass"/>
12033           <description>
12034             Native method being bound
12035           </description>
12036       </param>
12037       <param id="address">
12038         <outptr><void/></outptr>
12039         <description>
12040           The address the VM is about to bind to--that is, the
12041           address of the implementation of the native method
12042         </description>
12043       </param>
12044       <param id="new_address_ptr">
12045         <agentbuf><void/></agentbuf>
12046         <description>
12047           if the referenced address is changed (that is, if
12048           <code>*new_address_ptr</code> is set), the binding
12049           will instead be made to the supplied address.
12050         </description>
12051       </param>
12052     </parameters>
12053   </event>
12054 
12055   <event label="Exception"
12056          id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
12057     <description>
12058       Exception events are generated whenever an exception is first detected
12059       in a Java programming language method. 
12060       Where "exception" means any <code>java.lang.Throwable</code>.
12061       The exception may have been thrown by a Java programming language or native
12062       method, but in the case of native methods, the event is not generated
12063       until the exception is first seen by a Java programming language method. If an exception is
12064       set and cleared in a native method (and thus is never visible to Java programming language code),
12065       no exception event is generated.
12066       <p/>
12067       The <code>method</code> and <code>location</code>
12068       parameters  uniquely identify the current location 
12069       (where the exception was detected) and allow
12070       the mapping to source file and line number when that information is 
12071       available. The <code>exception</code> field identifies the thrown
12072       exception object. The <code>catch_method</code>
12073       and <code>catch_location</code> identify the location of the catch clause,
12074       if any, that handles the thrown exception. If there is no such catch clause,
12075       each field is set to 0. There is no guarantee that the thread will ever
12076       reach this catch clause. If there are native methods on the call stack
12077       between the throw location and the catch clause, the exception may 
12078       be reset by one of those native methods.
12079       Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
12080       et al. set to 0) may in fact be caught by native code.
12081       Agents can check for these occurrences by monitoring 
12082       <eventlink id="ExceptionCatch"></eventlink> events.
12083       Note that finally clauses are implemented as catch and re-throw. Therefore they
12084       will be reported in the catch location.
12085     </description>
12086     <origin>jvmdi</origin>
12087     <capabilities>
12088       <required id="can_generate_exception_events"></required>
12089     </capabilities>
12090     <parameters> 
12091       <param id="jni_env">
12092         <outptr>
12093           <struct>JNIEnv</struct>
12094         </outptr>
12095           <description>
12096             The JNI environment of the event (current) thread
12097           </description>
12098       </param>
12099       <param id="thread">
12100         <jthread/>
12101           <description>
12102             Thread generating the exception
12103           </description>
12104       </param>
12105       <param id="klass">
12106         <jclass method="method"/>
12107           <description>
12108             Class generating the exception
12109           </description>
12110       </param>
12111       <param id="method">
12112         <jmethodID class="klass"/>
12113           <description>
12114             Method generating the exception
12115           </description>
12116       </param>
12117       <param id="location">
12118         <jlocation/>
12119         <description>
12120           Location where exception occurred
12121         </description>
12122       </param>
12123       <param id="exception">
12124         <jobject/>
12125           <description>
12126             The exception being thrown
12127           </description>
12128       </param>
12129       <param id="catch_klass">
12130         <jclass method="catch_method"/>
12131           <description>
12132             Class that will catch the exception, or <code>NULL</code> if no known catch
12133           </description>
12134       </param>
12135       <param id="catch_method">
12136         <jmethodID class="catch_klass"/>
12137           <description>
12138             Method that will catch the exception, or <code>NULL</code> if no known catch
12139           </description>
12140       </param>
12141       <param id="catch_location">
12142         <jlocation/>
12143         <description>
12144           location which will catch the exception or zero if no known catch
12145         </description>
12146       </param>
12147     </parameters>
12148   </event>
12149 
12150   <event label="Exception Catch"
12151          id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
12152     <description>
12153       Exception catch events are generated whenever a thrown exception is caught.
12154       Where "exception" means any <code>java.lang.Throwable</code>.
12155       If the exception is caught in a Java programming language method, the event is generated
12156       when the catch clause is reached. If the exception is caught in a native
12157       method, the event is generated as soon as control is returned to a Java programming language 
12158       method. Exception catch events are generated for any exception for which
12159       a throw was detected in a Java programming language method.
12160       Note that finally clauses are implemented as catch and re-throw. Therefore they
12161       will generate exception catch events.
12162       <p/>
12163       The <code>method</code> and <code>location</code>
12164       parameters uniquely identify the current location 
12165       and allow the mapping to source file and line number when that information is 
12166       available. For exceptions caught in a Java programming language method, the 
12167       <code>exception</code> object identifies the exception object. Exceptions
12168       caught in native methods are not necessarily available by the time the 
12169       exception catch is reported, so the <code>exception</code> field is set
12170       to <code>NULL</code>.
12171     </description>
12172     <origin>jvmdi</origin>
12173     <capabilities>
12174       <required id="can_generate_exception_events"></required>
12175     </capabilities>
12176     <parameters> 
12177       <param id="jni_env">
12178         <outptr>
12179           <struct>JNIEnv</struct>
12180         </outptr>
12181           <description>
12182             The JNI environment of the event (current) thread
12183           </description>
12184       </param>
12185       <param id="thread">
12186         <jthread/>
12187           <description>
12188             Thread catching the exception
12189           </description>
12190       </param>
12191       <param id="klass">
12192         <jclass method="method"/>
12193           <description>
12194             Class catching the exception
12195           </description>
12196       </param>
12197       <param id="method">
12198         <jmethodID class="klass"/>
12199           <description>
12200             Method catching the exception
12201           </description>
12202       </param>
12203       <param id="location">
12204         <jlocation/>
12205         <description>
12206           Location where exception is being caught
12207         </description>
12208       </param>
12209       <param id="exception">
12210         <jobject/>
12211           <description>
12212             Exception being caught
12213           </description>
12214       </param>
12215     </parameters>
12216   </event>
12217 
12218   <event label="Thread Start"
12219          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12220     <description>
12221       Thread start events are generated by a new thread before its initial
12222       method executes. 
12223       <p/>
12224       A thread may be listed in the array returned by
12225       <functionlink id="GetAllThreads"></functionlink>
12226       before its thread start event is generated. 
12227       It is possible for other events to be generated
12228       on a thread before its thread start event.
12229       <p/>
12230       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12231     </description>
12232     <origin>jvmdi</origin>
12233     <capabilities>
12234     </capabilities>
12235     <parameters> 
12236       <param id="jni_env">
12237         <outptr>
12238           <struct>JNIEnv</struct>
12239         </outptr>
12240           <description>
12241             The JNI environment of the event (current) thread.
12242           </description>
12243       </param>
12244       <param id="thread">
12245         <jthread/>
12246           <description>
12247             Thread starting
12248           </description>
12249       </param>
12250     </parameters>
12251   </event>
12252 
12253   <event label="Thread End"
12254          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> 
12255     <description>
12256       Thread end events are generated by a terminating thread
12257       after its initial method has finished execution. 
12258       <p/>
12259       A thread may be listed in the array returned by
12260       <functionlink id="GetAllThreads"></functionlink>
12261       after its thread end event is generated. 
12262       No events are generated on a thread
12263       after its thread end event.
12264       <p/>
12265       The event is sent on the dying <paramlink id="thread"></paramlink>.
12266     </description>
12267     <origin>jvmdi</origin>
12268     <capabilities>
12269     </capabilities>
12270     <parameters> 
12271       <param id="jni_env">
12272         <outptr>
12273           <struct>JNIEnv</struct>
12274         </outptr>
12275           <description>
12276             The JNI environment of the event (current) thread.
12277           </description>
12278       </param>
12279       <param id="thread">
12280         <jthread/>
12281           <description>
12282             Thread ending
12283           </description>
12284       </param>
12285     </parameters>
12286   </event>
12287 
12288   <event label="Class Load"
12289          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
12290     <description>
12291       A class load event is generated when a class is first loaded. The order
12292       of class load events generated by a particular thread are guaranteed
12293       to match the order of class loading within that thread. 
12294       Array class creation does not generate a class load event.
12295       The creation of a primitive class (for example, java.lang.Integer.TYPE) 
12296       does not generate a class load event.
12297       <p/>
12298       This event is sent at an early stage in loading the class. As
12299       a result the class should be used carefully.  Note, for example,
12300       that methods and fields are not yet loaded, so queries for methods,
12301       fields, subclasses, and so on will not give correct results. 
12302       See "Loading of Classes and Interfaces" in the <i>Java Language
12303       Specification</i>.  For most
12304       purposes the <eventlink id="ClassPrepare"></eventlink> event will
12305       be more useful.
12306     </description>
12307     <origin>jvmdi</origin>
12308     <capabilities>
12309     </capabilities>
12310     <parameters> 
12311       <param id="jni_env">
12312         <outptr>
12313           <struct>JNIEnv</struct>
12314         </outptr>
12315           <description>
12316             The JNI environment of the event (current) thread
12317           </description>
12318       </param>
12319       <param id="thread">
12320         <jthread/>
12321           <description>
12322             Thread loading the class
12323           </description>
12324       </param>
12325       <param id="klass">
12326         <jclass/>
12327           <description>
12328             Class being loaded
12329           </description>
12330       </param>
12331     </parameters>
12332   </event>
12333 
12334   <elide>
12335   <event label="Class Unload"
12336          id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
12337     <description>
12338       A class unload event is generated when the class is about to be unloaded.
12339       Class unload events take place during garbage collection and must be 
12340       handled extremely carefully. The garbage collector holds many locks
12341       and has suspended all other threads, so the event handler cannot depend
12342       on the ability to acquire any locks. The class unload event handler should
12343       do as little as possible, perhaps by queuing information to be processed
12344       later.  In particular, the <code>jclass</code> should be used only in
12345       the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
12346       <ul>
12347         <li><functionlink id="GetClassSignature"></functionlink></li>
12348         <li><functionlink id="GetSourceFileName"></functionlink></li>
12349         <li><functionlink id="IsInterface"></functionlink></li>
12350         <li><functionlink id="IsArrayClass"></functionlink></li>
12351       </ul>
12352     </description>
12353     <origin>jvmdi</origin>
12354     <capabilities>
12355     </capabilities>
12356     <parameters> 
12357       <param id="jni_env">
12358         <outptr>
12359           <struct>JNIEnv</struct>
12360         </outptr>
12361           <description>
12362             The JNI environment of the event (current) thread
12363           </description>
12364       </param>
12365       <param id="thread">
12366         <jthread/>
12367           <description>
12368             Thread generating the class unload
12369           </description>
12370       </param>
12371       <param id="klass">
12372         <jclass/>
12373           <description>
12374             Class being unloaded
12375           </description>
12376       </param>
12377     </parameters>
12378   </event>
12379   </elide>
12380 
12381   <event label="Class Prepare"
12382          id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
12383     <description>
12384       A class prepare event is generated when class preparation is complete.
12385       At this point, class fields, methods, and implemented interfaces are 
12386       available, and no code from the class has been executed. Since array 
12387       classes never have fields or methods, class prepare events are not 
12388       generated for them. Class prepare events are not generated for 
12389       primitive classes (for example, <code>java.lang.Integer.TYPE</code>). 
12390     </description>
12391     <origin>jvmdi</origin>
12392     <capabilities>
12393     </capabilities>
12394     <parameters> 
12395       <param id="jni_env">
12396         <outptr>
12397           <struct>JNIEnv</struct>
12398         </outptr>
12399           <description>
12400             The JNI environment of the event (current) thread
12401           </description>
12402       </param>
12403       <param id="thread">
12404         <jthread/>
12405           <description>
12406             Thread generating the class prepare
12407           </description>
12408       </param>
12409       <param id="klass">
12410         <jclass/>
12411           <description>
12412             Class being prepared
12413           </description>
12414       </param>
12415     </parameters>
12416   </event>
12417 
12418   <event label="Class File Load Hook" phase="any"
12419          id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
12420     <description>
12421       This event is sent when the VM obtains class file data,
12422       but before it constructs
12423       the in-memory representation for that class. 
12424       This event is also sent when the class is being modified by the 
12425       <functionlink id="RetransformClasses"/> function or
12426       the <functionlink id="RedefineClasses"/> function,
12427       called in any <jvmti/> environment.
12428       The agent can instrument
12429       the existing class file data sent by the VM to include profiling/debugging hooks.
12430       See the description of 
12431       <internallink id="bci">bytecode instrumentation</internallink>
12432       for usage information.
12433       <p/>
12434     The timing of this event may depend on whether the agent has added the
12435     <internallink id="jvmtiCapabilities.can_generate_early_class_hook_events">
12436     <code>can_generate_early_class_hook_events</code></internallink>
12437     capability or not.
12438     If the capability has been added then the VM posts the events in the primordial phase.
12439     Otherwise, this event may be sent before the VM is initialized (the start 
12440     <functionlink id="GetPhase">phase</functionlink>).
12441     Some classes might not be compatible
12442     with the function (eg. ROMized classes) and this event will not be
12443     generated for these classes.
12444     <p/>
12445     The agent must allocate the space for the modified 
12446     class file data buffer
12447     using the memory allocation function 
12448     <functionlink id="Allocate"></functionlink> because the
12449     VM is responsible for freeing the new class file data buffer
12450     using <functionlink id="Deallocate"></functionlink>.
12451     <p/>
12452     If the agent wishes to modify the class file, it must set 
12453     <code>new_class_data</code> to point
12454     to the newly instrumented class file data buffer and set
12455     <code>new_class_data_len</code> to the length of that 
12456     buffer before returning
12457     from this call.  If no modification is desired, the agent simply
12458     does not set <code>new_class_data</code>.  If multiple agents
12459     have enabled this event the results are chained. That is, if
12460     <code>new_class_data</code> has been set, it becomes the 
12461     <code>class_data</code> for the next agent.
12462     <p/>
12463     The order that this event is sent to each environment differs
12464     from other events.
12465     This event is sent to environments in the following order:
12466     <ul>
12467       <li><fieldlink id="can_retransform_classes"
12468                      struct="jvmtiCapabilities">retransformation
12469                                                 incapable</fieldlink>
12470           environments, in the 
12471           order in which they were created
12472       </li>
12473       <li><fieldlink id="can_retransform_classes"
12474                      struct="jvmtiCapabilities">retransformation
12475                                                 capable</fieldlink>
12476           environments, in the 
12477           order in which they were created
12478       </li>
12479     </ul>
12480     When triggered by <functionlink id="RetransformClasses"/>,
12481     this event is sent only to <fieldlink id="can_retransform_classes"
12482                      struct="jvmtiCapabilities">retransformation
12483                                                 capable</fieldlink>
12484     environments.
12485   </description>
12486   <origin>jvmpi</origin>
12487     <capabilities>
12488       <capability id="can_generate_all_class_hook_events"></capability>
12489       <capability id="can_generate_early_class_hook_events"></capability>
12490     </capabilities>
12491     <parameters>
12492       <param id="jni_env">
12493         <outptr>
12494           <struct>JNIEnv</struct>
12495         </outptr>
12496           <description>
12497             The JNI environment of the event (current) thread.
12498           </description>
12499       </param>
12500       <param id="class_being_redefined">
12501         <jclass/>
12502         <description>
12503           The class being
12504           <functionlink id="RedefineClasses">redefined</functionlink> or
12505           <functionlink id="RetransformClasses">retransformed</functionlink>.
12506           <code>NULL</code> if sent by class load.
12507         </description>
12508       </param>
12509       <param id="loader">
12510         <jobject/>
12511           <description>
12512             The class loader loading the class.  
12513             <code>NULL</code> if the bootstrap class loader.
12514           </description>
12515       </param>
12516       <param id="name">
12517         <vmbuf><char/></vmbuf>
12518         <description>
12519             Name of class being loaded as a VM internal qualified name
12520             (for example, "java/util/List"), encoded as a
12521             <internallink id="mUTF">modified UTF-8</internallink> string.
12522             Note: if the class is defined with a <code>NULL</code> name or
12523             without a name specified, <code>name</code> will be <code>NULL</code>.
12524         </description>
12525       </param>
12526       <param id="protection_domain">
12527         <jobject/>
12528         <description>
12529           The <code>ProtectionDomain</code> of the class.
12530         </description>
12531       </param>
12532       <param id="class_data_len">
12533         <jint/>
12534         <description>
12535           Length of current class file data buffer.
12536         </description>
12537       </param>
12538       <param id="class_data">
12539         <vmbuf><uchar/></vmbuf>
12540         <description>
12541           Pointer to the current class file data buffer.
12542         </description>
12543       </param>
12544       <param id="new_class_data_len">
12545         <outptr><jint/></outptr>
12546         <description>
12547           Pointer to the length of the new class file data buffer.
12548         </description>
12549       </param>
12550       <param id="new_class_data">
12551         <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
12552         <description>
12553           Pointer to the pointer to the instrumented class file data buffer.
12554         </description>
12555       </param>
12556     </parameters>
12557   </event>
12558 
12559   <event label="VM Start Event"
12560          id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
12561     <description>
12562       The VM start event signals the start of the VM.
12563       At this time JNI is live but the VM is not yet fully initialized.
12564       Once this event is generated, the agent is free to call any JNI function.
12565       This event signals the beginning of the start phase,
12566       <jvmti/> functions permitted in the start phase may be called.
12567       <p/>
12568       The timing of this event may depend on whether the agent has added the
12569       <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
12570       <code>can_generate_early_vmstart</code></internallink> capability or not.
12571       If the capability has been added then the VM posts the event as early
12572       as possible. The VM is capable of executing bytecode but it may not have
12573       initialized to the point where it can load classes in modules other than
12574       <code>java.base</code>. Agents that do load-time instrumentation in this
12575       phase must take great care when instrumenting code that potentially
12576       executes in this phase. Care should also be taken with JNI
12577       <code>FindClass</code> as it may not be possible to load classes that are
12578       not in the <code>java.base</code> module.
12579       If the capability has not been added then the VM delays posting this
12580       event until it is capable of loading classes in modules other than
12581       <code>java.base</code> or the VM has completed its initialization.
12582       Agents that create more than one JVM TI environment, where the
12583       capability is added to some but not all environments, may observe the
12584       start phase beginning earlier in the JVM TI environments that possess
12585       the capabilty.
12586       <p/>
12587       In the case of VM start-up failure, this event will not be sent.
12588     </description>
12589     <origin>jvmdi</origin>
12590     <capabilities>
12591     </capabilities>
12592     <parameters>
12593       <param id="jni_env">
12594         <outptr>
12595           <struct>JNIEnv</struct>
12596         </outptr>
12597           <description>
12598             The JNI environment of the event (current) thread.
12599           </description>
12600       </param>
12601     </parameters>
12602   </event>
12603 
12604   <event label="VM Initialization Event"
12605          id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
12606     <description>
12607       The VM initialization event signals the completion of VM initialization. Once
12608       this event is generated, the agent is free to call any JNI or <jvmti/>
12609       function. The VM initialization event can be preceded by or can be concurrent
12610       with other events, but
12611       the preceding events should be handled carefully, if at all, because the
12612       VM has not completed its initialization. The thread start event for the
12613       main application thread is guaranteed not to occur until after the 
12614       handler for the VM initialization event returns.
12615       <p/>
12616       In the case of VM start-up failure, this event will not be sent.
12617     </description>
12618     <origin>jvmdi</origin>
12619     <capabilities>
12620     </capabilities>
12621     <parameters>
12622       <param id="jni_env">
12623         <outptr>
12624           <struct>JNIEnv</struct>
12625         </outptr>
12626           <description>
12627             The JNI environment of the event (current) thread.
12628           </description>
12629       </param>
12630       <param id="thread">
12631         <jthread/>
12632           <description>
12633             The initial thread
12634           </description>
12635       </param>
12636     </parameters>
12637   </event>
12638 
12639   <event label="VM Death Event"
12640          id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
12641     <description>
12642       The VM death event notifies the agent of the termination of the VM. 
12643       No events will occur after the VMDeath event.
12644       <p/>
12645       In the case of VM start-up failure, this event will not be sent.
12646       Note that <internallink id="onunload">Agent_OnUnload</internallink>
12647       will still be called in these cases.
12648     </description>
12649     <origin>jvmdi</origin>
12650     <capabilities>
12651     </capabilities>
12652     <parameters>
12653       <param id="jni_env">
12654         <outptr>
12655           <struct>JNIEnv</struct>
12656         </outptr>
12657           <description>
12658             The JNI environment of the event (current) thread
12659           </description>
12660       </param>
12661     </parameters>
12662   </event>
12663 
12664   <event label="Compiled Method Load" phase="start"
12665          id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
12666     <description>
12667       Sent when a method is compiled and loaded into memory by the VM.
12668       If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
12669       If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
12670       followed by a new <code>CompiledMethodLoad</code> event.
12671       Note that a single method may have multiple compiled forms, and that
12672       this event will be sent for each form.
12673       Note also that several methods may be inlined into a single 
12674       address range, and that this event will be sent for each method.
12675       <p/>
12676       These events can be sent after their initial occurrence with
12677       <functionlink id="GenerateEvents"></functionlink>.
12678     </description>
12679     <origin>jvmpi</origin>
12680     <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
12681       <field id="start_address">
12682         <vmbuf><void/></vmbuf>
12683         <description>
12684           Starting native address of code corresponding to a location
12685         </description>
12686       </field>
12687       <field id="location">
12688         <jlocation/>
12689         <description>
12690           Corresponding location. See 
12691           <functionlink id="GetJLocationFormat"></functionlink>
12692           for the meaning of location.
12693         </description>
12694       </field>
12695     </typedef>
12696     <capabilities>
12697       <required id="can_generate_compiled_method_load_events"></required>
12698     </capabilities>
12699     <parameters>
12700       <param id="klass">
12701         <jclass method="method"/>
12702           <description>
12703             Class of the method being compiled and loaded
12704           </description>
12705       </param>
12706       <param id="method">
12707         <jmethodID class="klass"/>
12708           <description>
12709             Method being compiled and loaded
12710           </description>
12711       </param>
12712       <param id="code_size">
12713         <jint/>
12714         <description>
12715           Size of compiled code
12716         </description>
12717       </param>
12718       <param id="code_addr">
12719         <vmbuf><void/></vmbuf>
12720         <description>
12721           Address where compiled method code is loaded
12722         </description>
12723       </param>
12724       <param id="map_length">
12725         <jint/>
12726         <description>
12727           Number of <typelink id="jvmtiAddrLocationMap"></typelink>
12728           entries in the address map.
12729           Zero if mapping information cannot be supplied.
12730         </description>
12731       </param>
12732       <param id="map">
12733         <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
12734         <description>
12735           Map from native addresses to location.
12736           The native address range of each entry is from 
12737           <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
12738           to <code>start_address-1</code> of the next entry.
12739           <code>NULL</code> if mapping information cannot be supplied.
12740         </description>
12741       </param>
12742       <param id="compile_info">
12743         <vmbuf><void/></vmbuf>
12744         <description>
12745           VM-specific compilation information.  
12746           The referenced compile information is managed by the VM
12747           and must not depend on the agent for collection.
12748           A VM implementation defines the content and lifetime 
12749           of the information.
12750         </description>
12751       </param>
12752     </parameters>
12753   </event>
12754 
12755   <event label="Compiled Method Unload" phase="start"
12756          id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
12757     <description>
12758       Sent when a compiled method is unloaded from memory.
12759       This event might not be sent on the thread which performed the unload.
12760       This event may be sent sometime after the unload occurs, but 
12761       will be sent before the memory is reused
12762       by a newly generated compiled method. This event may be sent after 
12763       the class is unloaded.
12764     </description>
12765     <origin>jvmpi</origin>
12766     <capabilities>
12767       <required id="can_generate_compiled_method_load_events"></required>
12768     </capabilities>
12769     <parameters>
12770       <param id="klass">
12771         <jclass method="method"/>
12772           <description>
12773             Class of the compiled method being unloaded.
12774           </description>
12775       </param>
12776       <param id="method">
12777         <jmethodID class="klass"/>
12778           <description>
12779             Compiled method being unloaded.
12780             For identification of the compiled method only -- the class 
12781             may be unloaded and therefore the method should not be used
12782             as an argument to further JNI or <jvmti/> functions.
12783           </description>
12784       </param>
12785       <param id="code_addr">
12786         <vmbuf><void/></vmbuf>
12787         <description>
12788           Address where compiled method code was loaded.
12789           For identification of the compiled method only -- 
12790           the space may have been reclaimed.
12791         </description>
12792       </param>
12793     </parameters>
12794   </event>
12795 
12796   <event label="Dynamic Code Generated" phase="any"
12797          id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
12798     <description>
12799       Sent when a component of the virtual machine is generated dynamically.
12800       This does not correspond to Java programming language code that is
12801       compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
12802       This is for native code--for example, an interpreter that is generated
12803       differently depending on command-line options.
12804       <p/>
12805       Note that this event has no controlling capability.
12806       If a VM cannot generate these events, it simply does not send any.
12807       <p/>
12808       These events can be sent after their initial occurrence with
12809       <functionlink id="GenerateEvents"></functionlink>.
12810     </description>
12811     <origin>jvmpi</origin>
12812     <capabilities>
12813     </capabilities>
12814     <parameters>
12815       <param id="name">
12816         <vmbuf><char/></vmbuf>
12817         <description>
12818           Name of the code, encoded as a
12819           <internallink id="mUTF">modified UTF-8</internallink> string.
12820           Intended for display to an end-user.
12821           The name might not be unique.
12822         </description>
12823       </param>
12824       <param id="address">
12825         <vmbuf><void/></vmbuf>
12826         <description>
12827           Native address of the code
12828         </description>
12829       </param>
12830       <param id="length">
12831         <jint/>
12832         <description>
12833           Length in bytes of the code
12834         </description>
12835       </param>
12836     </parameters>
12837   </event>
12838 
12839   <event label="Data Dump Request"
12840          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
12841     <description>
12842       Sent by the VM to request the agent to dump its data.  This
12843       is just a hint and the agent need not react to this event.
12844       This is useful for processing command-line signals from users.  For
12845       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris
12846       causes the VM to send this event to the agent.
12847     </description>
12848     <origin>jvmpi</origin>
12849     <capabilities>
12850     </capabilities>
12851     <parameters>
12852     </parameters>
12853   </event>
12854 
12855   <event label="Monitor Contended Enter"
12856          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
12857     <description>
12858       Sent when a thread is attempting to enter a Java programming language
12859       monitor already acquired by another thread.
12860     </description>
12861     <origin>jvmpi</origin>
12862     <capabilities>
12863       <required id="can_generate_monitor_events"></required>
12864     </capabilities>
12865     <parameters>
12866       <param id="jni_env">
12867         <outptr>
12868           <struct>JNIEnv</struct>
12869         </outptr>
12870           <description>
12871             The JNI environment of the event (current) thread
12872           </description>
12873       </param>
12874       <param id="thread">
12875         <jthread/>
12876           <description>
12877             JNI local reference to the thread 
12878             attempting to enter the monitor
12879           </description>
12880       </param>
12881       <param id="object">
12882         <jobject/>
12883           <description>
12884             JNI local reference to the monitor
12885           </description>
12886       </param>
12887     </parameters>
12888   </event>
12889 
12890   <event label="Monitor Contended Entered"
12891          id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
12892     <description>
12893       Sent when a thread enters a Java programming language
12894       monitor after waiting for it to be released by another thread.
12895     </description>
12896     <origin>jvmpi</origin>
12897     <capabilities>
12898       <required id="can_generate_monitor_events"></required>
12899     </capabilities>
12900     <parameters>
12901       <param id="jni_env">
12902         <outptr>
12903           <struct>JNIEnv</struct>
12904         </outptr>
12905           <description>
12906             The JNI environment of the event (current) thread
12907           </description>
12908       </param>
12909       <param id="thread">
12910         <jthread/>
12911           <description>
12912             JNI local reference to the thread entering
12913             the monitor
12914           </description>
12915       </param>
12916       <param id="object">
12917         <jobject/>
12918           <description>
12919             JNI local reference to the monitor
12920           </description>
12921       </param>
12922     </parameters>
12923   </event>
12924 
12925   <event label="Monitor Wait"
12926          id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
12927     <description>
12928       Sent when a thread is about to wait on an object.
12929     </description>
12930     <origin>jvmpi</origin>
12931     <capabilities>
12932       <required id="can_generate_monitor_events"></required>
12933     </capabilities>
12934     <parameters>
12935       <param id="jni_env">
12936         <outptr>
12937           <struct>JNIEnv</struct>
12938         </outptr>
12939           <description>
12940             The JNI environment of the event (current) thread
12941           </description>
12942       </param>
12943       <param id="thread">
12944         <jthread/>
12945           <description>
12946             JNI local reference to the thread about to wait
12947           </description>
12948       </param>
12949       <param id="object">
12950         <jobject/>
12951           <description>
12952             JNI local reference to the monitor
12953           </description>
12954       </param>
12955       <param id="timeout">
12956         <jlong/>
12957         <description>
12958           The number of milliseconds the thread will wait
12959         </description>
12960       </param>
12961     </parameters>
12962   </event>
12963 
12964   <event label="Monitor Waited"
12965          id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
12966     <description>
12967       Sent when a thread finishes waiting on an object.
12968     </description>
12969     <origin>jvmpi</origin>
12970     <capabilities>
12971       <required id="can_generate_monitor_events"></required>
12972     </capabilities>
12973     <parameters>
12974       <param id="jni_env">
12975         <outptr>
12976           <struct>JNIEnv</struct>
12977         </outptr>
12978           <description>
12979             The JNI environment of the event (current) thread
12980           </description>
12981       </param>
12982       <param id="thread">
12983         <jthread/>
12984           <description>
12985             JNI local reference to the thread that was finished waiting
12986           </description>
12987       </param>
12988       <param id="object">
12989         <jobject/>
12990           <description>
12991             JNI local reference to the monitor.
12992           </description>
12993       </param>
12994       <param id="timed_out">
12995         <jboolean/>
12996         <description>
12997           True if the monitor timed out
12998         </description>
12999       </param>
13000     </parameters>
13001   </event>
13002 
13003   <event label="Resource Exhausted"
13004          id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
13005          since="1.1">
13006     <description>
13007       Sent when a VM resource needed by a running application has been exhausted.
13008       Except as required by the optional capabilities, the set of resources 
13009       which report exhaustion is implementation dependent.
13010       <p/>
13011       The following bit flags define the properties of the resource exhaustion:
13012       <constants id="jvmtiResourceExhaustionFlags" 
13013                  label="Resource Exhaustion Flags" 
13014                  kind="bits" 
13015                  since="1.1">
13016         <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
13017           After this event returns, the VM will throw a
13018           <code>java.lang.OutOfMemoryError</code>.
13019         </constant>         
13020         <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
13021           The VM was unable to allocate memory from the <tm>Java</tm> 
13022           platform <i>heap</i>.
13023           The <i>heap</i> is the runtime
13024           data area from which memory for all class instances and
13025           arrays are allocated.
13026         </constant>         
13027         <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
13028           The VM was unable to create a thread.
13029         </constant>         
13030       </constants>
13031     </description>
13032     <origin>new</origin>
13033     <capabilities>
13034       <capability id="can_generate_resource_exhaustion_heap_events">
13035         Can generate events when the VM is unable to allocate memory from the
13036         <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
13037       </capability>
13038       <capability id="can_generate_resource_exhaustion_threads_events">
13039         Can generate events when the VM is unable to 
13040         <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
13041         a thread</internallink>.
13042       </capability>
13043     </capabilities>
13044     <parameters>
13045       <param id="jni_env">
13046         <outptr>
13047           <struct>JNIEnv</struct>
13048         </outptr>
13049           <description>
13050             The JNI environment of the event (current) thread
13051           </description>
13052       </param>
13053       <param id="flags">
13054         <jint/>
13055         <description>
13056           Flags defining the properties of the of resource exhaustion
13057           as specified by the 
13058           <internallink id="jvmtiResourceExhaustionFlags">Resource 
13059           Exhaustion Flags</internallink>.
13060           </description>
13061         </param>
13062       <param id="reserved">
13063         <vmbuf><void/></vmbuf>
13064         <description>
13065           Reserved.
13066         </description>
13067       </param>
13068       <param id="description">
13069         <vmbuf><char/></vmbuf>
13070         <description>
13071           Description of the resource exhaustion, encoded as a
13072           <internallink id="mUTF">modified UTF-8</internallink> string.
13073         </description>
13074       </param>
13075     </parameters>
13076   </event>
13077 
13078   <event label="VM Object Allocation"
13079          id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
13080     <description>
13081       Sent when a method causes the virtual machine to allocate an 
13082       Object visible to Java programming language code and the
13083       allocation is not detectable by other intrumentation mechanisms.
13084       Generally object allocation should be detected by instrumenting
13085       the bytecodes of allocating methods.
13086       Object allocation generated in native code by JNI function
13087       calls should be detected using 
13088       <internallink id="jniIntercept">JNI function interception</internallink>.
13089       Some methods might not have associated bytecodes and are not 
13090       native methods, they instead are executed directly by the 
13091       VM. These methods should send this event.
13092       Virtual machines which are incapable of bytecode instrumentation
13093       for some or all of their methods can send this event.
13094       <p/>
13095       Typical examples where this event might be sent:
13096       <ul>
13097         <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
13098         <li>Methods not represented by bytecodes -- for example, VM intrinsics and
13099             J2ME preloaded classes</li>
13100       </ul>
13101       Cases where this event would not be generated:
13102       <ul>
13103         <li>Allocation due to bytecodes -- for example, the <code>new</code>
13104             and <code>newarray</code> VM instructions</li>
13105         <li>Allocation due to JNI function calls -- for example,
13106             <code>AllocObject</code></li>
13107         <li>Allocations during VM initialization</li>
13108         <li>VM internal objects</li>
13109       </ul>
13110     </description>
13111     <origin>new</origin>
13112     <capabilities>
13113       <required id="can_generate_vm_object_alloc_events"></required>
13114     </capabilities>
13115     <parameters>
13116       <param id="jni_env">
13117         <outptr>
13118           <struct>JNIEnv</struct>
13119         </outptr>
13120           <description>
13121             The JNI environment of the event (current) thread
13122           </description>
13123       </param>
13124       <param id="thread">
13125         <jthread/>
13126           <description>
13127             Thread allocating the object.
13128           </description>
13129       </param>
13130       <param id="object">
13131         <jobject/>
13132           <description>
13133             JNI local reference to the object that was allocated
13134           </description>
13135       </param>
13136       <param id="object_klass">
13137         <jclass/>
13138           <description>
13139             JNI local reference to the class of the object
13140           </description>
13141       </param>
13142       <param id="size">
13143         <jlong/>
13144         <description>
13145             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13146         </description>
13147       </param>
13148     </parameters>
13149   </event>
13150 
13151   <event label="Object Free"
13152          id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13153     <description>
13154       An Object Free event is sent when the garbage collector frees an object.
13155       Events are only sent for tagged objects--see
13156       <internallink id="Heap">heap functions</internallink>.
13157       <p/>
13158       The event handler must not use JNI functions and
13159       must not use <jvmti/> functions except those which
13160       specifically allow such use (see the raw monitor, memory management,
13161       and environment local storage functions).
13162     </description>
13163     <origin>new</origin>
13164     <capabilities>
13165       <required id="can_generate_object_free_events"></required>
13166     </capabilities>
13167     <parameters>
13168       <param id="tag">
13169         <jlong/>
13170         <description>
13171           The freed object's tag
13172         </description>
13173       </param>
13174     </parameters>
13175   </event>
13176 
13177   <event label="Garbage Collection Start"
13178          id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
13179     <description>
13180       A Garbage Collection Start event is sent when a 
13181       garbage collection pause begins.
13182       Only stop-the-world collections are reported--that is, collections during
13183       which all threads cease to modify the state of the Java virtual machine.
13184       This means that some collectors will never generate these events.
13185       This event is sent while the VM is still stopped, thus
13186       the event handler must not use JNI functions and
13187       must not use <jvmti/> functions except those which
13188       specifically allow such use (see the raw monitor, memory management,
13189       and environment local storage functions).
13190       <p/>
13191       This event is always sent as a matched pair with 
13192       <eventlink id="GarbageCollectionFinish"/> 
13193       (assuming both events are enabled) and no garbage collection
13194       events will occur between them.
13195     </description>
13196     <origin>new</origin>
13197     <capabilities>
13198       <required id="can_generate_garbage_collection_events"></required>
13199     </capabilities>
13200     <parameters>
13201     </parameters>
13202   </event>
13203 
13204   <event label="Garbage Collection Finish"
13205          id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
13206     <description>
13207       A Garbage Collection Finish event is sent when a
13208       garbage collection pause ends.
13209       This event is sent while the VM is still stopped, thus
13210       the event handler must not use JNI functions and
13211       must not use <jvmti/> functions except those which
13212       specifically allow such use (see the raw monitor, memory management,
13213       and environment local storage functions).
13214       <p/>
13215       Some agents may need to do post garbage collection operations that
13216       require the use of the disallowed <jvmti/> or JNI functions. For these
13217       cases an agent thread can be created which waits on a raw monitor,
13218       and the handler for the Garbage Collection Finish event simply
13219       notifies the raw monitor
13220       <p/>
13221       This event is always sent as a matched pair with 
13222       <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
13223       <issue>
13224         The most important use of this event is to provide timing information,
13225         and thus additional information is not required.  However,  
13226         information about the collection which is "free" should be included -
13227         what that information is needs to be determined.
13228       </issue>
13229     </description>
13230     <origin>new</origin>
13231     <capabilities>
13232       <required id="can_generate_garbage_collection_events"></required>
13233     </capabilities>
13234     <parameters>
13235     </parameters>
13236   </event>
13237 
13238   <elide>
13239   <event label="Verbose Output" phase="any"
13240          id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
13241     <description>
13242       Send verbose messages as strings.
13243         <issue>
13244           This format is extremely fragile, as it can change with each
13245           platform, collector and version.  Alternatives include:
13246           <ul>
13247             <li>building off Java programming language M and M APIs</li>
13248             <li>XML</li>
13249             <li>key/value pairs</li>
13250             <li>removing it</li>
13251           </ul>
13252         </issue>
13253         <issue>
13254           Though this seemed trivial to implement.  
13255           In the RI it appears this will be quite complex.
13256         </issue>
13257     </description>
13258     <origin>new</origin>
13259     <capabilities>
13260     </capabilities>
13261     <parameters>
13262       <param id="flag">
13263         <enum>jvmtiVerboseFlag</enum>
13264         <description>
13265           Which verbose output is being sent.
13266         </description>
13267       </param>
13268       <param id="message">
13269         <vmbuf><char/></vmbuf>
13270         <description>
13271           Message text, encoded as a
13272           <internallink id="mUTF">modified UTF-8</internallink> string.
13273         </description>
13274       </param>
13275     </parameters>
13276   </event>
13277   </elide>
13278 
13279 </eventsection>
13280 
13281 <datasection>
13282   <intro>
13283     <jvmti/> extends the data types defined by JNI.
13284   </intro>
13285   <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
13286     <basetype id="jboolean">
13287       <description>
13288         Holds a Java programming language <code>boolean</code>.
13289         Unsigned 8 bits.
13290       </description>
13291     </basetype>
13292     <basetype id="jchar">
13293       <description>
13294         Holds a Java programming language <code>char</code>.
13295         Unsigned 16 bits.
13296       </description>
13297     </basetype>
13298     <basetype id="jint">
13299       <description>
13300         Holds a Java programming language <code>int</code>. 
13301         Signed 32 bits.
13302       </description>
13303     </basetype>
13304     <basetype id="jlong">
13305       <description>
13306         Holds a Java programming language <code>long</code>. 
13307         Signed 64 bits.
13308       </description>
13309     </basetype>
13310     <basetype id="jfloat">
13311       <description>
13312         Holds a Java programming language <code>float</code>. 
13313         32 bits.
13314       </description>
13315     </basetype>
13316     <basetype id="jdouble">
13317       <description>
13318         Holds a Java programming language <code>double</code>. 
13319         64 bits.
13320       </description>
13321     </basetype>
13322     <basetype id="jobject">
13323       <description>
13324         Holds a Java programming language object. 
13325       </description>
13326     </basetype>
13327     <basetype id="jclass">
13328       <description>
13329         Holds a Java programming language class. 
13330       </description>
13331     </basetype>
13332     <basetype id="jvalue">
13333       <description>
13334         Is a union of all primitive types and <code>jobject</code>.  Thus, holds any Java 
13335         programming language value. 
13336       </description>
13337     </basetype>
13338     <basetype id="jfieldID">
13339       <description>
13340         Identifies a Java programming language field. 
13341         <code>jfieldID</code>s returned by <jvmti/> functions and events may be
13342         safely stored.
13343       </description>
13344     </basetype>
13345     <basetype id="jmethodID">
13346       <description>
13347         Identifies a Java programming language method, initializer, or constructor. 
13348         <code>jmethodID</code>s returned by <jvmti/> functions and events may be
13349         safely stored.  However, if the class is unloaded, they become invalid
13350         and must not be used.
13351       </description>
13352     </basetype>
13353     <basetype id="JNIEnv">
13354       <description>
13355         Pointer to the JNI function table.  Pointer to this (<code>JNIEnv *</code>)
13356         is a JNI environment. 
13357       </description>
13358     </basetype>
13359   </basetypes>
13360 
13361   <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
13362     <basetype id="jvmtiEnv">
13363       <description>
13364         The <jvmti/> <internallink id="environments">environment</internallink> pointer. 
13365         See the <internallink id="FunctionSection">Function Section</internallink>.
13366         <code>jvmtiEnv</code> points to the 
13367         <internallink id="FunctionTable">function table</internallink> pointer.
13368       </description>
13369     </basetype>
13370     <basetype id="jthread">
13371       <definition>typedef jobject jthread;</definition>
13372       <description>
13373         Subtype of <datalink id="jobject"></datalink> that holds a thread.
13374       </description>
13375     </basetype>
13376     <basetype id="jthreadGroup">
13377       <definition>typedef jobject jthreadGroup;</definition>
13378       <description>
13379         Subtype of <datalink id="jobject"></datalink> that holds a thread group.
13380       </description>
13381     </basetype>
13382     <basetype id="jlocation">
13383       <definition>typedef jlong jlocation;</definition>
13384       <description>
13385         A 64 bit value, representing a monotonically increasing 
13386         executable position within a method. 
13387         <code>-1</code> indicates a native method.
13388         See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
13389         given VM.
13390       </description>
13391     </basetype>
13392     <basetype id="jrawMonitorID">
13393       <definition>struct _jrawMonitorID;
13394 typedef struct _jrawMonitorID *jrawMonitorID;</definition>
13395       <description>
13396         A raw monitor.
13397       </description>
13398     </basetype>
13399     <basetype id="jvmtiError">
13400       <description>
13401         Holds an error return code.
13402         See the <internallink id="ErrorSection">Error section</internallink> for possible values.
13403         <example>
13404 typedef enum { 
13405     JVMTI_ERROR_NONE = 0,  
13406     JVMTI_ERROR_INVALID_THREAD = 10,
13407       ... 
13408 } jvmtiError;
13409 </example>
13410       </description>
13411     </basetype>
13412     <basetype id="jvmtiEvent">
13413       <description>
13414         An identifier for an event type.
13415         See the <internallink id="EventSection">Event section</internallink> for possible values.
13416         It is guaranteed that future versions of this specification will 
13417         never assign zero as an event type identifier.
13418 <example>
13419 typedef enum { 
13420     JVMTI_EVENT_SINGLE_STEP = 1, 
13421     JVMTI_EVENT_BREAKPOINT = 2, 
13422       ... 
13423 } jvmtiEvent;
13424 </example>
13425       </description>
13426     </basetype>
13427     <basetype id="jvmtiEventCallbacks">
13428       <description>
13429         The callbacks used for events.
13430 <example>
13431 typedef struct {
13432     jvmtiEventVMInit VMInit;
13433     jvmtiEventVMDeath VMDeath;
13434       ... 
13435 } jvmtiEventCallbacks;
13436 </example>
13437         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> 
13438         for the complete structure.
13439         <p/>
13440         Where, for example, the VM initialization callback is defined:
13441 <example>
13442 typedef void (JNICALL *jvmtiEventVMInit)
13443     (jvmtiEnv *jvmti_env, 
13444      JNIEnv* jni_env,
13445      jthread thread);
13446 </example>
13447         See the individual events for the callback function definition.
13448       </description>
13449     </basetype>
13450     <basetype id="jniNativeInterface">
13451       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
13452       <description>
13453         Typedef for the JNI function table <code>JNINativeInterface</code>
13454         defined in the 
13455         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>.
13456         The JNI reference implementation defines this with an underscore.
13457       </description>
13458     </basetype>
13459   </basetypes>
13460 
13461 </datasection>
13462 
13463 <issuessection label="Issues">
13464   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
13465     JVMDI requires that the agent suspend threads before calling
13466     certain sensitive functions.  JVMPI requires garbage collection to be 
13467     disabled before calling certain sensitive functions. 
13468     It was suggested that rather than have this requirement, that
13469     VM place itself in a suitable state before performing an
13470     operation.  This makes considerable sense since each VM
13471     knows its requirements and can most easily arrange a
13472     safe state.  
13473     <p/>
13474     The ability to externally suspend/resume threads will, of
13475     course, remain.  The ability to enable/disable garbage collection will not.
13476     <p/>
13477     This issue is resolved--suspend will not
13478     be required.  The spec has been updated to reflect this.
13479   </intro>
13480   
13481   <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
13482     There are a variety of approaches to sampling call stacks.
13483     The biggest bifurcation is between VM controlled and agent
13484     controlled.  
13485     <p/>
13486     This issue is resolved--agent controlled
13487     sampling will be the approach.
13488   </intro>
13489   
13490   <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
13491     JVMDI represents threads as jthread.  JVMPI primarily
13492     uses JNIEnv* to represent threads.  
13493     <p/>
13494     The Expert Group has chosen jthread as the representation
13495     for threads in <jvmti/>.
13496     JNIEnv* is sent by
13497     events since it is needed to JNI functions.  JNIEnv, per the
13498     JNI spec, are not supposed to be used outside their thread.
13499   </intro>
13500 
13501   <intro id="design" label="Resolved Issue: Method Representation">
13502     The JNI spec allows an implementation to depend on jclass/jmethodID
13503     pairs, rather than simply a jmethodID, to reference a method.  
13504     JVMDI, for consistency, choose the same representation.  
13505     JVMPI, however, specifies that a jmethodID alone maps to a
13506     method.  Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
13507     pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
13508     In fact, any JVM implementation that supports JVMPI must have
13509     such a representation.  
13510     <jvmti/> will use jmethodID as a unique representation of a method
13511     (no jclass is used).
13512     There should be efficiency gains, particularly in 
13513     functionality like stack dumping, to this representation.
13514     <p/>
13515     Note that fields were not used in JVMPI and that the access profile
13516     of fields differs from methods--for implementation efficiency 
13517     reasons, a jclass/jfieldID pair will still be needed for field 
13518     reference.
13519   </intro>
13520 
13521   <intro id="localReferenceIssue" label="Resolved Issue: Local References">
13522     Functions return local references. 
13523   </intro>
13524 
13525   <intro id="frameRep" label="Resolved Issue: Representation of frames">
13526     In JVMDI, a frame ID is used to represent a frame.  Problem with this
13527     is that a VM must track when a frame becomes invalid, a far better
13528     approach, and the one used in <jvmti/>, is to reference frames by depth.
13529   </intro>
13530 
13531   <intro id="requiredCapabilities" label="Issue: Required Capabilities">
13532     Currently, having a required capabilities means that the functionality
13533     is optional.   Capabilities are useful even for required functionality
13534     since they can inform the VM is needed set-up.  Thus, there should be
13535     a set of capabilities that a conformant implementation must provide
13536     (if requested during Agent_OnLoad).
13537   </intro>
13538 
13539   <intro id="taghint" label="Proposal: add tag hint function">
13540     A hint of the percentage of objects that will be tagged would 
13541     help the VM pick a good implementation.
13542   </intro>
13543 
13544   <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
13545   How difficult or easy would be to extend the monitor_info category to include 
13546     <pre>
13547   - current number of monitors 
13548   - enumeration of monitors 
13549   - enumeration of threads waiting on a given monitor 
13550     </pre>
13551   The reason for my question is the fact that current get_monitor_info support 
13552   requires the agent to specify a given thread to get the info which is probably 
13553   OK in the profiling/debugging space, while in the monitoring space the agent 
13554   could be watching the monitor list and then decide which thread to ask for 
13555   the info. You might ask why is this important for monitoring .... I think it 
13556   can aid in the detection/prediction of application contention caused by hot-locks.
13557   </intro>
13558 </issuessection>
13559 
13560 <changehistory id="ChangeHistory" update="09/05/07">
13561   <intro>
13562     The <jvmti/> specification is an evolving document with major, minor, 
13563     and micro version numbers.
13564     A released version of the specification is uniquely identified
13565     by its major and minor version.
13566     The functions, events, and capabilities in this specification 
13567     indicate a "Since" value which is the major and minor version in
13568     which it was introduced.
13569     The version of the specification implemented by the VM can 
13570     be retrieved at runtime with the <functionlink id="GetVersionNumber"/> 
13571     function.
13572   </intro>
13573   <change date="14 Nov 2002">
13574     Converted to XML document.
13575   </change>
13576   <change date="14 Nov 2002">
13577     Elided heap dump functions (for now) since what was there
13578     was wrong.
13579   </change>
13580   <change date="18 Nov 2002">
13581     Added detail throughout.
13582   </change>
13583   <change date="18 Nov 2002">
13584     Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
13585   </change>
13586   <change date="19 Nov 2002">
13587     Added AsyncGetStackTrace.
13588   </change>
13589   <change date="19 Nov 2002">
13590     Added jframeID return to GetStackTrace.
13591   </change>
13592   <change date="19 Nov 2002">
13593     Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
13594     since they are redundant with GetStackTrace.
13595   </change>
13596   <change date="19 Nov 2002">
13597     Elided ClearAllBreakpoints since it has always been redundant.
13598   </change>
13599   <change date="19 Nov 2002">
13600     Added GetSystemProperties.
13601   </change>
13602   <change date="19 Nov 2002">
13603     Changed the thread local storage functions to use jthread.
13604   </change>
13605   <change date="20 Nov 2002">
13606     Added GetJLocationFormat.
13607   </change>
13608   <change date="22 Nov 2002">
13609     Added events and introductory text.
13610   </change>
13611   <change date="22 Nov 2002">
13612     Cross reference type and constant definitions.
13613   </change>
13614   <change date="24 Nov 2002">
13615     Added DTD.
13616   </change>
13617   <change date="24 Nov 2002">
13618     Added capabilities function section.
13619   </change>
13620   <change date="29 Nov 2002">
13621     Assign capabilities to each function and event.
13622   </change>
13623   <change date="29 Nov 2002">
13624     Add <internallink id="jniIntercept">JNI interception functions</internallink>.
13625   </change>
13626   <change date="30 Nov 2002">
13627     Auto generate SetEventNotificationMode capabilities.
13628   </change>
13629   <change date="30 Nov 2002">
13630     Add <eventlink id="VMObjectAlloc"></eventlink> event.
13631   </change>
13632   <change date="30 Nov 2002">
13633     Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
13634   </change>
13635   <change date="30 Nov 2002">
13636     Add const to declarations.
13637   </change>
13638   <change date="30 Nov 2002">
13639     Change method exit and frame pop to send on exception.
13640   </change>
13641   <change date="1 Dec 2002">
13642     Add ForceGarbageCollection.
13643   </change>
13644   <change date="2 Dec 2002">
13645     Redo Xrun section; clarify GetStackTrace and add example;
13646     Fix width problems; use "agent" consistently.
13647   </change>
13648   <change date="8 Dec 2002">
13649     Remove previous start-up intro.
13650     Add <internallink id="environments"><jvmti/> Environments</internallink>
13651     section.
13652   </change>
13653   <change date="8 Dec 2002">
13654     Add <functionlink id="DisposeEnvironment"></functionlink>.
13655   </change>
13656   <change date="9 Dec 2002">
13657     Numerous minor updates.
13658   </change>
13659   <change date="15 Dec 2002">
13660     Add heap profiling functions added:
13661     get/set annotation, iterate live objects/heap.
13662     Add heap profiling functions place holder added:
13663     heap roots.
13664     Heap profiling event added: object free. 
13665     Heap profiling event redesigned: vm object allocation. 
13666     Heap profiling event placeholders added: garbage collection start/finish. 
13667     Native method bind event added.
13668   </change>
13669   <change date="19 Dec 2002">
13670     Revamp suspend/resume functions.
13671     Add origin information with jvmdi tag.
13672     Misc fixes.
13673   </change>
13674   <change date="24 Dec 2002">
13675     Add semantics to types.
13676   </change>
13677   <change date="27 Dec 2002">
13678     Add local reference section.
13679     Autogenerate parameter descriptions from types.
13680   </change>
13681   <change date="28 Dec 2002">
13682     Document that RunAgentThread sends threadStart.
13683   </change>
13684   <change date="29 Dec 2002">
13685     Remove redundant local ref and dealloc warning.
13686     Convert GetRawMonitorName to allocated buffer.
13687     Add GenerateEvents.
13688   </change>
13689   <change date="30 Dec 2002">
13690     Make raw monitors a type and rename to "jrawMonitorID".
13691   </change>
13692   <change date="1 Jan 2003">
13693     Include origin information.
13694     Clean-up JVMDI issue references.
13695     Remove Deallocate warnings which are now automatically generated.
13696   </change>
13697   <change date="2 Jan 2003">
13698     Fix representation issues for jthread.
13699   </change>
13700   <change date="3 Jan 2003">
13701     Make capabilities buffered out to 64 bits - and do it automatically.
13702   </change>
13703   <change date="4 Jan 2003">
13704     Make constants which are enumeration into enum types.
13705     Parameters now of enum type.
13706     Clean-up and index type section.
13707     Replace remaining datadef entities with callback.
13708   </change>
13709   <change date="7 Jan 2003">
13710     Correct GenerateEvents description.
13711     More internal semantics work.
13712   </change>
13713   <change date="9 Jan 2003">
13714     Replace previous GetSystemProperties with two functions
13715     which use allocated information instead fixed.
13716     Add SetSystemProperty.
13717     More internal semantics work.
13718   </change>
13719   <change date="12 Jan 2003">
13720     Add varargs to end of SetEventNotificationMode.
13721   </change>
13722   <change date="20 Jan 2003">
13723     Finish fixing spec to reflect that alloc sizes are jlong.
13724   </change>
13725   <change date="22 Jan 2003">
13726     Allow NULL as RunAgentThread arg.
13727   </change>
13728   <change date="22 Jan 2003">
13729     Fixed names to standardized naming convention
13730     Removed AsyncGetStackTrace.
13731   </change>
13732   <change date="29 Jan 2003">
13733     Since we are using jthread, removed GetThread.
13734   </change>
13735   <change date="31 Jan 2003">
13736     Change GetFieldName to allow NULLs like GetMethodName.
13737   </change>
13738   <change date="29 Feb 2003" version="v40">
13739       Rewrite the introductory text, adding sections on
13740       start-up, environments and bytecode instrumentation.
13741       Change the command line arguments per EG discussions.
13742       Add an introduction to the capabilities section.
13743       Add the extension mechanism category and functions.
13744       Mark for deletion, but clarified anyhow, SuspendAllThreads.
13745       Rename IterateOverLiveObjects to IterateOverReachableObjects and
13746       change the text accordingly.
13747       Clarify IterateOverHeap.
13748       Clarify CompiledMethodLoad.
13749       Discuss prerequisite state for Calling Functions.
13750       Clarify SetAllocationHooks.
13751       Added issues ("To be resolved:") through-out.
13752       And so on...
13753   </change>
13754   <change date="6 Mar 2003" version="v41">
13755       Remove struct from the call to GetOwnedMonitorInfo.
13756       Automatically generate most error documentation, remove
13757       (rather broken) hand written error doc.
13758       Better describe capability use (empty initial set).
13759       Add min value to jint params.
13760       Remove the capability can_access_thread_local_storage.
13761       Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
13762       same for *NOT_IMPLEMENTED.
13763       Description fixes.
13764   </change>
13765   <change date="8 Mar 2003" version="v42">
13766       Rename GetClassSignature to GetClassName.
13767       Rename IterateOverClassObjects to IterateOverInstancesOfClass.
13768       Remove GetMaxStack (operand stack isn't used in <jvmti/>).
13769       Description fixes: define launch-time, remove native frame pop
13770       from PopFrame, and assorted clarifications.
13771   </change>
13772   <change date="8 Mar 2003" version="v43">
13773       Fix minor editing problem.
13774   </change>
13775   <change date="10 Mar 2003" version="v44">
13776       Add phase information.
13777       Remap (compact) event numbers.
13778   </change>
13779   <change date="11 Mar 2003" version="v45">
13780       More phase information - allow "any".
13781       Elide raw monitor queries and events.
13782       Minor description fixes.
13783   </change>
13784   <change date="12 Mar 2003" version="v46">
13785       Add GetPhase.
13786       Use "phase" through document.
13787       Elide GetRawMonitorName.
13788       Elide GetObjectMonitors.
13789   </change>
13790   <change date="12 Mar 2003" version="v47">
13791       Fixes from link, XML, and spell checking.
13792       Auto-generate the callback structure.
13793   </change>
13794   <change date="13 Mar 2003" version="v48">
13795       One character XML fix.
13796   </change>
13797   <change date="13 Mar 2003" version="v49">
13798       Change function parameter names to be consistent with 
13799       event parameters (fooBarBaz becomes foo_bar_baz).
13800   </change>
13801   <change date="14 Mar 2003" version="v50">
13802       Fix broken link.  Fix thread markers.
13803   </change>
13804   <change date="14 Mar 2003" version="v51">
13805       Change constants so they are under 128 to workaround
13806       compiler problems.
13807   </change>
13808   <change date="23 Mar 2003" version="v52">
13809       Overhaul capabilities.  Separate GetStackTrace into
13810       GetStackTrace and GetStackFrames.
13811   </change>
13812   <change date="8 Apr 2003" version="v54">
13813       Use depth instead of jframeID to reference frames.
13814       Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
13815       Remove frame arg from events.
13816   </change>
13817   <change date="9 Apr 2003" version="v55">
13818       Remove GetObjectWithAnnotation since tests show bufferred approach more efficient.
13819       Add missing annotation_count to GetObjectsWithAnnotations
13820   </change>
13821   <change date="10 Apr 2003" version="v56">
13822       Remove confusing parenthetical statement in GetObjectsWithAnnotations
13823   </change>
13824   <change date="13 Apr 2003" version="v58">
13825       Replace jclass/jmethodID representation of method with simply jmethodID;
13826       Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
13827       Replace can_access_frames with can_access_local_variables; remove from purely stack access.
13828       Use can_get_synthetic_attribute; fix description.
13829       Clarify that zero length arrays must be deallocated.
13830       Clarify RelinquishCapabilities.
13831       Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
13832   </change>
13833   <change date="27 Apr 2003" version="v59">
13834       Remove lingering indirect references to OBSOLETE_METHOD_ID.
13835   </change>
13836   <change date="4 May 2003" version="v60">
13837       Allow DestroyRawMonitor during OnLoad.
13838   </change>
13839   <change date="7 May 2003" version="v61">
13840       Added not monitor owner error return to DestroyRawMonitor.
13841   </change>
13842   <change date="13 May 2003" version="v62">
13843       Clarify semantics of raw monitors.
13844       Change flags on <code>GetThreadStatus</code>.
13845       <code>GetClassLoader</code> return NULL for the bootstrap class loader.
13846       Add <code>GetClassName</code> issue.
13847       Define local variable signature.
13848       Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
13849       Remove over specification in <code>GetObjectsWithAnnotations</code>.
13850       Elide <code>SetAllocationHooks</code>.
13851       Elide <code>SuspendAllThreads</code>.
13852   </change>
13853   <change date="14 May 2003" version="v63">
13854       Define the data type <code>jvmtiEventCallbacks</code>.
13855       Zero length allocations return NULL.  
13856       Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.  
13857       Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
13858   </change>
13859   <change date="15 May 2003" version="v64">
13860       Better wording, per review.
13861   </change>
13862   <change date="15 May 2003" version="v65">
13863       First Alpha.
13864       Make jmethodID and jfieldID unique, jclass not used.
13865   </change>
13866   <change date="27 May 2003" version="v66">
13867       Fix minor XSLT errors.
13868   </change>
13869   <change date="13 June 2003" version="v67">
13870       Undo making jfieldID unique (jmethodID still is).
13871   </change>
13872   <change date="17 June 2003" version="v68">
13873       Changes per June 11th Expert Group meeting --
13874       Overhaul Heap functionality: single callback, 
13875       remove GetHeapRoots, add reachable iterators,
13876       and rename "annotation" to "tag".
13877       NULL thread parameter on most functions is current
13878       thread.
13879       Add timers.
13880       Remove ForceExit.
13881       Add GetEnvironmentLocalStorage.
13882       Add verbose flag and event.
13883       Add AddToBootstrapClassLoaderSearch.
13884       Update ClassFileLoadHook.
13885   </change>
13886   <change date="18 June 2003" version="v69">
13887       Clean up issues sections.
13888       Rename GetClassName back to GetClassSignature and
13889       fix description.
13890       Add generic signature to GetClassSignature, 
13891       GetFieldSignature, GetMethodSignature, and 
13892       GetLocalVariableTable.
13893       Elide EstimateCostOfCapabilities.
13894       Clarify that the system property functions operate
13895       on the VM view of system properties.
13896       Clarify Agent_OnLoad.
13897       Remove "const" from JNIEnv* in events.
13898       Add metadata accessors.
13899   </change>
13900   <change date="18 June 2003" version="v70">
13901       Add start_depth to GetStackTrace.
13902       Move system properties to a new category.
13903       Add GetObjectSize.
13904       Remove "X" from command line flags.
13905       XML, HTML, and spell check corrections.
13906   </change>
13907   <change date="19 June 2003" version="v71">
13908       Fix JVMTI_HEAP_ROOT_THREAD to be 6.
13909       Make each synopsis match the function name.
13910       Fix unclear wording.
13911   </change>
13912   <change date="26 June 2003" version="v72">
13913       SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
13914       to be set to NULL.
13915       NotifyFramePop, GetFrameLocationm and all the local variable operations
13916       needed to have their wording about frames fixed.
13917       Grammar and clarity need to be fixed throughout.
13918       Capitalization and puntuation need to be consistent.
13919       Need micro version number and masks for accessing major, minor, and micro.
13920       The error code lists should indicate which must be returned by
13921       an implementation.
13922       The command line properties should be visible in the properties functions.
13923       Disallow popping from the current thread.
13924       Allow implementations to return opaque frame error when they cannot pop.
13925       The NativeMethodBind event should be sent during any phase.
13926       The DynamicCodeGenerated event should be sent during any phase.
13927       The following functions should be allowed to operate before VMInit:
13928         Set/GetEnvironmentLocalStorage
13929         GetMethodDeclaringClass
13930         GetClassSignature
13931         GetClassModifiers
13932         IsInterface
13933         IsArrayClass
13934         GetMethodName
13935         GetMethodModifiers
13936         GetMaxLocals
13937         GetArgumentsSize
13938         GetLineNumberTable
13939         GetMethodLocation
13940         IsMethodNative
13941         IsMethodSynthetic.
13942       Other changes (to XSL):
13943       Argument description should show asterisk after not before pointers.
13944       NotifyFramePop, GetFrameLocationm and all the local variable operations
13945       should hsve the NO_MORE_FRAMES error added.
13946       Not alive threads should have a different error return than invalid thread.
13947   </change>
13948   <change date="7 July 2003" version="v73">
13949       VerboseOutput event was missing message parameter.
13950       Minor fix-ups.
13951   </change>
13952   <change date="14 July 2003" version="v74">
13953       Technical Publications Department corrections.
13954       Allow thread and environment local storage to be set to NULL.
13955   </change>
13956   <change date="23 July 2003" version="v75">
13957       Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
13958       Add JNICALL to callbacks (XSL).
13959       Document JNICALL requirement for both events and callbacks (XSL).
13960       Restrict RedefineClasses to methods and attributes.
13961       Elide the VerboseOutput event.
13962       VMObjectAlloc: restrict when event is sent and remove method parameter.
13963       Finish loose ends from Tech Pubs edit.
13964   </change>
13965   <change date="24 July 2003" version="v76">
13966       Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
13967   </change>
13968   <change date="24 July 2003" version="v77">
13969       XML fixes.
13970       Minor text clarifications and corrections.
13971   </change>
13972   <change date="24 July 2003" version="v78">
13973       Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
13974       Clarify that stack frames are JVM Spec frames.
13975       Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
13976       and can_get_source_debug_extension.
13977       PopFrame cannot have a native calling method.
13978       Removed incorrect statement in GetClassloaderClasses 
13979       (see <vmspec chapter="4.4"/>).
13980   </change>
13981   <change date="24 July 2003" version="v79">
13982       XML and text fixes.
13983       Move stack frame description into Stack Frame category.
13984   </change>
13985   <change date="26 July 2003" version="v80">
13986       Allow NULL (means bootstrap loader) for GetClassloaderClasses.
13987       Add new heap reference kinds for references from classes.
13988       Add timer information struct and query functions.
13989       Add AvailableProcessors.
13990       Rename GetOtherThreadCpuTime to GetThreadCpuTime.
13991       Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
13992       to SetEventNotification mode.
13993       Add initial thread to the VM_INIT event.
13994       Remove platform assumptions from AddToBootstrapClassLoaderSearch.
13995   </change>
13996   <change date="26 July 2003" version="v81">
13997       Grammar and clarity changes per review.
13998   </change>
13999   <change date="27 July 2003" version="v82">
14000       More grammar and clarity changes per review.
14001       Add Agent_OnUnload.
14002   </change>
14003   <change date="28 July 2003" version="v83">
14004       Change return type of Agent_OnUnload to void.
14005   </change>
14006   <change date="28 July 2003" version="v84">
14007       Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
14008   </change>
14009   <change date="28 July 2003" version="v85">
14010       Steal java.lang.Runtime.availableProcessors() wording for 
14011       AvailableProcessors().
14012       Guarantee that zero will never be an event ID.
14013       Remove some issues which are no longer issues.
14014       Per review, rename and more completely document the timer
14015       information functions.
14016   </change>
14017   <change date="29 July 2003" version="v86">
14018       Non-spec visible change to XML controlled implementation:
14019         SetThreadLocalStorage must run in VM mode.
14020   </change>
14021   <change date="5 August 2003" version="0.1.87">
14022       Add GetErrorName.
14023       Add varargs warning to jvmtiExtensionEvent.
14024       Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
14025       Remove unused can_get_exception_info capability.
14026       Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
14027       Fix jvmtiExtensionFunctionInfo.func declared type.
14028       Extension function returns error code.
14029       Use new version numbering.
14030   </change>
14031   <change date="5 August 2003" version="0.2.88">
14032       Remove the ClassUnload event.
14033   </change>
14034   <change date="8 August 2003" version="0.2.89">
14035       Heap reference iterator callbacks return an enum that 
14036       allows outgoing object references to be ignored.
14037       Allow JNIEnv as a param type to extension events/functions.
14038   </change>
14039   <change date="15 August 2003" version="0.2.90">
14040       Fix a typo.
14041   </change>
14042   <change date="2 September 2003" version="0.2.91">
14043       Remove all metadata functions: GetClassMetadata, 
14044       GetFieldMetadata, and GetMethodMetadata.
14045   </change>
14046   <change date="1 October 2003" version="0.2.92">
14047       Mark the functions Allocate. Deallocate, RawMonitor*, 
14048       SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage 
14049       as safe for use in heap callbacks and GC events.
14050   </change>
14051   <change date="24 November 2003" version="0.2.93">
14052       Add pass through opaque user data pointer to heap iterate 
14053       functions and callbacks.
14054       In the CompiledMethodUnload event, send the code address.
14055       Add GarbageCollectionOccurred event.
14056       Add constant pool reference kind.
14057       Mark the functions CreateRawMonitor and DestroyRawMonitor
14058       as safe for use in heap callbacks and GC events.
14059       Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, 
14060       GetThreadCpuTimerInfo, IterateOverReachableObjects,
14061       IterateOverObjectsReachableFromObject, GetTime and
14062       JVMTI_ERROR_NULL_POINTER.
14063       Add missing errors to: GenerateEvents and
14064       AddToBootstrapClassLoaderSearch.
14065       Fix description of ClassFileLoadHook name parameter.
14066       In heap callbacks and GC/ObjectFree events, specify
14067       that only explicitly allowed functions can be called.
14068       Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
14069       GetTimerInfo, and GetTime during callback.
14070       Allow calling SetTag/GetTag during the onload phase.
14071       SetEventNotificationMode, add: error attempted inappropriate
14072       thread level control.
14073       Remove jvmtiExceptionHandlerEntry.
14074       Fix handling of native methods on the stack -- 
14075       location_ptr param of GetFrameLocation, remove 
14076       JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
14077       jvmtiFrameInfo.location, and jlocation.
14078       Remove typo (from JVMPI) implying that the MonitorWaited
14079       event is sent on sleep.
14080   </change>
14081   <change date="25 November 2003" version="0.2.94">
14082       Clarifications and typos.
14083   </change>
14084   <change date="3 December 2003" version="0.2.95">
14085       Allow NULL user_data in heap iterators.
14086   </change>
14087   <change date="28 January 2004" version="0.2.97">
14088       Add GetThreadState, deprecate GetThreadStatus.
14089   </change>
14090   <change date="29 January 2004" version="0.2.98">
14091       INVALID_SLOT and TYPE_MISMATCH errors should be optional.
14092   </change>
14093   <change date="12 February 2004" version="0.2.102">
14094       Remove MonitorContendedExit.
14095       Added JNIEnv parameter to VMObjectAlloc.
14096       Clarified definition of class_tag and referrer_index 
14097       parameters to heap callbacks.
14098   </change>
14099   <change date="16 Febuary 2004" version="0.2.103">
14100       Document JAVA_TOOL_OPTIONS.
14101   </change>
14102   <change date="17 Febuary 2004" version="0.2.105">
14103       Divide start phase into primordial and start.
14104       Add VMStart event
14105       Change phase associations of functions and events.
14106   </change>
14107   <change date="18 Febuary 2004" version="0.3.6">
14108       Elide deprecated GetThreadStatus.
14109       Bump minor version, subtract 100 from micro version
14110   </change>
14111   <change date="18 Febuary 2004" version="0.3.7">
14112       Document that timer nanosecond values are unsigned.
14113       Clarify text having to do with native methods.
14114   </change>
14115   <change date="19 Febuary 2004" version="0.3.8">
14116       Fix typos.
14117       Remove elided deprecated GetThreadStatus.
14118   </change>
14119   <change date="23 Febuary 2004" version="0.3.9">
14120       Require NotifyFramePop to act on suspended threads.
14121   </change>
14122   <change date="24 Febuary 2004" version="0.3.10">
14123       Add capabilities 
14124         (<internallink id="jvmtiCapabilities.can_redefine_any_class"
14125          ><code>can_redefine_any_class</code></internallink>
14126       and 
14127          <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
14128          ><code>can_generate_all_class_hook_events</code></internallink>) 
14129       and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) 
14130       which allow some classes to be unmodifiable.
14131   </change>
14132   <change date="28 Febuary 2004" version="0.3.11">
14133       Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
14134   </change>
14135   <change date="8 March 2004" version="0.3.12">
14136       Clarified CompiledMethodUnload so that it is clear the event
14137       may be posted after the class has been unloaded.
14138   </change>
14139   <change date="5 March 2004" version="0.3.13">
14140       Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
14141   </change>
14142   <change date="13 March 2004" version="0.3.14">
14143       Added guideline for the use of the JNI FindClass function in event
14144       callback functions.
14145   </change>
14146   <change date="15 March 2004" version="0.3.15">
14147       Add GetAllStackTraces and GetThreadListStackTraces.
14148   </change>
14149   <change date="19 March 2004" version="0.3.16">
14150       ClassLoad and ClassPrepare events can be posted during start phase.
14151   </change>
14152   <change date="25 March 2004" version="0.3.17">
14153       Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
14154       GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
14155   </change>
14156   <change date="29 March 2004" version="0.3.18">
14157       Return the timer kind in the timer information structure.
14158   </change>
14159   <change date="31 March 2004" version="0.3.19">
14160       Spec clarifications:
14161       JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
14162       ForceGarbageCollection does not run finalizers.
14163       The context of the specification is the Java platform.
14164       Warn about early instrumentation.
14165   </change>
14166   <change date="1 April 2004" version="0.3.20">
14167       Refinements to the above clarifications and
14168       Clarify that an error returned by Agent_OnLoad terminates the VM.
14169   </change>
14170   <change date="1 April 2004" version="0.3.21">
14171       Array class creation does not generate a class load event.
14172   </change>
14173   <change date="7 April 2004" version="0.3.22">
14174       Align thread state hierarchy more closely with java.lang.Thread.State.
14175   </change>
14176   <change date="12 April 2004" version="0.3.23">
14177       Clarify the documentation of thread state.
14178   </change>
14179   <change date="19 April 2004" version="0.3.24">
14180       Remove GarbageCollectionOccurred event -- can be done by agent.
14181   </change>
14182   <change date="22 April 2004" version="0.3.25">
14183       Define "command-line option".
14184   </change>
14185   <change date="29 April 2004" version="0.3.26">
14186       Describe the intended use of bytecode instrumentation.
14187       Fix description of extension event first parameter.
14188   </change>
14189   <change date="30 April 2004" version="0.3.27">
14190       Clarification and typos.
14191   </change>
14192   <change date="18 May 2004" version="0.3.28">
14193       Remove DataDumpRequest event.
14194   </change>
14195   <change date="18 May 2004" version="0.3.29">
14196       Clarify RawMonitorWait with zero timeout.
14197       Clarify thread state after RunAgentThread.
14198   </change>
14199   <change date="24 May 2004" version="0.3.30">
14200       Clean-up: fix bad/old links, etc.
14201   </change>
14202   <change date="30 May 2004" version="0.3.31">
14203       Clarifications including:
14204       All character strings are modified UTF-8.
14205       Agent thread visibiity.
14206       Meaning of obsolete method version.
14207       Thread invoking heap callbacks,
14208   </change>
14209   <change date="1 June 2004" version="1.0.32">
14210       Bump major.minor version numbers to "1.0".
14211   </change>
14212   <change date="2 June 2004" version="1.0.33">
14213       Clarify interaction between ForceGarbageCollection 
14214       and ObjectFree.
14215   </change>
14216   <change date="6 June 2004" version="1.0.34">
14217       Restrict AddToBootstrapClassLoaderSearch and 
14218       SetSystemProperty to the OnLoad phase only.
14219   </change>
14220   <change date="11 June 2004" version="1.0.35">
14221       Fix typo in SetTag.
14222   </change>
14223   <change date="18 June 2004" version="1.0.36">
14224       Fix trademarks.
14225       Add missing parameter in example GetThreadState usage.
14226   </change>
14227   <change date="4 August 2004" version="1.0.37">
14228       Copyright updates.
14229   </change>
14230   <change date="5 November 2004" version="1.0.38">
14231       Add missing function table layout.
14232       Add missing description of C++ member function format of functions.
14233       Clarify that name in CFLH can be NULL.
14234       Released as part of <tm>J2SE</tm> 5.0.
14235   </change>
14236   <change date="24 April 2005" version="1.1.47">
14237       Bump major.minor version numbers to "1.1".
14238       Add ForceEarlyReturn* functions.
14239       Add GetOwnedMonitorStackDepthInfo function.
14240       Add GetCurrentThread function.
14241       Add "since" version marker.
14242       Add AddToSystemClassLoaderSearch.
14243       Allow AddToBootstrapClassLoaderSearch be used in live phase.
14244       Fix historic rubbish in the descriptions of the heap_object_callback 
14245       parameter of IterateOverHeap and IterateOverInstancesOfClass functions; 
14246       disallow NULL for this parameter.
14247       Clarify, correct and make consistent: wording about current thread,
14248       opaque frames and insufficient number of frames in PopFrame.
14249       Consistently use "current frame" rather than "topmost".
14250       Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
14251       by making them compatible with those in ForceEarlyReturn*.
14252       Many other clarifications and wording clean ups.
14253   </change>
14254   <change date="25 April 2005" version="1.1.48">
14255       Add GetConstantPool.
14256       Switch references to the first edition of the VM Spec, to the seconds edition.
14257   </change>
14258   <change date="26 April 2005" version="1.1.49">
14259       Clarify minor/major version order in GetConstantPool.
14260   </change>
14261   <change date="26 April 2005" version="1.1.50">
14262       Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
14263       Reassign GetOwnedMonitorStackDepthInfo to position 153.
14264       Break out Class Loader Search in its own documentation category.
14265       Deal with overly long lines in XML source.
14266   </change>
14267   <change date="29 April 2005" version="1.1.51">
14268       Allow agents be started in the live phase.
14269       Added paragraph about deploying agents.  
14270   </change>
14271   <change date="30 April 2005" version="1.1.52">
14272       Add specification description to SetNativeMethodPrefix(es).
14273       Better define the conditions on GetConstantPool.  
14274   </change>
14275   <change date="30 April 2005" version="1.1.53">
14276       Break out the GetClassVersionNumber function from GetConstantPool.
14277       Clean-up the references to the VM Spec.  
14278   </change>
14279   <change date="1 May 2005" version="1.1.54">
14280       Allow SetNativeMethodPrefix(es) in any phase.
14281       Add clarifications about the impact of redefinition on GetConstantPool.  
14282   </change>
14283   <change date="2 May 2005" version="1.1.56">
14284       Various clarifications to SetNativeMethodPrefix(es).
14285   </change>
14286   <change date="2 May 2005" version="1.1.57">
14287       Add missing performance warning to the method entry event.
14288   </change>
14289   <change date="5 May 2005" version="1.1.58">
14290       Remove internal JVMDI support.
14291   </change>
14292   <change date="8 May 2005" version="1.1.59">
14293       Add <functionlink id="RetransformClasses"/>.
14294       Revamp the bytecode instrumentation documentation.
14295       Change <functionlink id="IsMethodObsolete"/> to no longer 
14296       require the can_redefine_classes capability.
14297   </change>
14298   <change date="11 May 2005" version="1.1.63">
14299       Clarifications for retransformation.
14300   </change>
14301   <change date="11 May 2005" version="1.1.64">
14302       Clarifications for retransformation, per review.
14303       Lock "retransformation (in)capable" at class load enable time.
14304   </change>
14305   <change date="4 June 2005" version="1.1.67">
14306       Add new heap functionity which supports reporting primitive values,
14307       allows setting the referrer tag, and has more powerful filtering:
14308       FollowReferences, IterateThroughHeap, and their associated 
14309       callbacks, structs, enums, and constants.
14310   </change>
14311   <change date="4 June 2005" version="1.1.68">
14312       Clarification.
14313   </change>
14314   <change date="6 June 2005" version="1.1.69">
14315       FollowReferences, IterateThroughHeap: Put callbacks in a struct;
14316       Add missing error codes; reduce bits in the visit control flags.
14317   </change>
14318   <change date="14 June 2005" version="1.1.70">
14319       More on new heap functionity: spec clean-up per review.
14320   </change>
14321   <change date="15 June 2005" version="1.1.71">
14322       More on new heap functionity: Rename old heap section to Heap (1.0).
14323   </change>
14324   <change date="21 June 2005" version="1.1.72">
14325       Fix typos.
14326   </change>
14327   <change date="27 June 2005" version="1.1.73">
14328       Make referrer info structure a union.
14329   </change>
14330   <change date="9 September 2005" version="1.1.74">
14331       In new heap functions:
14332       Add missing superclass reference kind.
14333       Use a single scheme for computing field indexes.
14334       Remove outdated references to struct based referrer info.
14335   </change>
14336   <change date="12 September 2005" version="1.1.75">
14337       Don't callback during FollowReferences on frivolous java.lang.Object superclass.
14338   </change>
14339   <change date="13 September 2005" version="1.1.76">
14340       In string primitive callback, length now Unicode length.
14341       In array and string primitive callbacks, value now "const".
14342       Note possible compiler impacts on setting JNI function table.
14343   </change>
14344   <change date="13 September 2005" version="1.1.77">
14345       GetClassVersionNumbers() and GetConstantPool() should return
14346       error on array or primitive class.
14347   </change>
14348   <change date="14 September 2005" version="1.1.78">
14349       Grammar fixes.
14350   </change>
14351   <change date="26 September 2005" version="1.1.79">
14352       Add IsModifiableClass query.
14353   </change>
14354   <change date="9 February 2006" version="1.1.81">
14355       Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
14356   </change>
14357   <change date="13 February 2006" version="1.1.82">
14358       Doc fixes: update can_redefine_any_class to include retransform.
14359       Clarify that exception events cover all Throwables.
14360       In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
14361       Clarify fields reported in Primitive Field Callback -- static vs instance.
14362       Repair confusing names of heap types, including callback names.
14363       Require consistent usage of stack depth in the face of thread launch methods.
14364       Note incompatibility of <jvmti/> memory management with other systems.
14365   </change>
14366   <change date="14 February 2006" version="1.1.85">
14367       Fix typos and missing renames.
14368   </change>
14369   <change date="13 March 2006" version="1.1.86">
14370       Clarify that jmethodIDs and jfieldIDs can be saved.
14371       Clarify that Iterate Over Instances Of Class includes subclasses.
14372   </change>
14373   <change date="14 March 2006" version="1.1.87">
14374       Better phrasing.
14375   </change>
14376   <change date="16 March 2006" version="1.1.88">
14377       Match the referrer_index for static fields in Object Reference Callback 
14378       with the Reference Implementation (and all other known implementations);
14379       that is, make it match the definition for instance fields.
14380       In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover 
14381       an invalid thread in the list; and specify that not started threads
14382       return empty stacks.
14383   </change>
14384   <change date="17 March 2006" version="1.1.89">
14385       Typo.
14386   </change>
14387   <change date="25 March 2006" version="1.1.90">
14388       Typo.
14389   </change>
14390   <change date="6 April 2006" version="1.1.91">
14391       Remove restrictions on AddToBootstrapClassLoaderSearch and
14392       AddToSystemClassLoaderSearch.
14393   </change>
14394   <change date="1 May 2006" version="1.1.93">
14395       Changed spec to return -1 for monitor stack depth for the
14396       implementation which can not determine stack depth. 
14397   </change>
14398   <change date="3 May 2006" version="1.1.94">
14399       Corrections for readability and accuracy courtesy of Alan Pratt of IBM. 
14400       List the object relationships reported in FollowReferences.
14401   </change>
14402   <change date="5 May 2006" version="1.1.95">
14403       Clarify the object relationships reported in FollowReferences.
14404   </change>
14405   <change date="28 June 2006" version="1.1.98">
14406       Clarify DisposeEnvironment; add warning.
14407       Fix typos in SetLocalXXX "retrieve" => "set".
14408       Clarify that native method prefixes must remain set while used.
14409       Clarify that exactly one Agent_OnXXX is called per agent.
14410       Clarify that library loading is independent from start-up.
14411       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14412   </change>
14413   <change date="31 July 2006" version="1.1.99">
14414       Clarify the interaction between functions and exceptions.
14415       Clarify and give examples of field indices.
14416       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14417       Update links to point to Java 6.
14418   </change>
14419   <change date="6 August 2006" version="1.1.102">
14420       Add ResourceExhaustedEvent.
14421   </change>
14422   <change date="11 October 2012" version="1.2.2">
14423       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14424   </change>
14425   <change date="19 June 2013" version="1.2.3">
14426       Added support for statically linked agents.
14427   </change>
14428   <change date="20 January 2016" version="9.0.0">
14429       Support for modules:
14430        - The majorversion is 9 now
14431        - The ClassFileLoadHook events are not sent during the primordial phase anymore.
14432        - Add new function GetAllModules
14433   </change>
14434   <change date="17 February 2016" version="9.0.0">
14435       Support for modules:
14436        - Add new capability can_generate_early_vmstart
14437        - Allow CompiledMethodLoad events at start phase
14438   </change>
14439   <change date="14 April 2016" version="9.0.0">
14440       Support for modules:
14441        - Add new capability can_generate_early_class_hook_events
14442   </change>
14443 </changehistory>
14444 
14445 </specification>
14446 <!-- Keep this comment at the end of the file
14447 Local variables:
14448 mode: sgml
14449 sgml-omittag:t
14450 sgml-shorttag:t
14451 sgml-namecase-general:t
14452 sgml-general-insert-case:lower
14453 sgml-minimize-attributes:nil
14454 sgml-always-quote-attributes:t
14455 sgml-indent-step:2
14456 sgml-indent-data:t
14457 sgml-parent-document:nil
14458 sgml-exposed-tags:nil
14459 sgml-local-catalogs:nil
14460 sgml-local-ecat-files:nil
14461 End:
14462 -->