1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
   3 <!--
   4  Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved.
   5  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6 
   7  This code is free software; you can redistribute it and/or modify it
   8  under the terms of the GNU General Public License version 2 only, as
   9  published by the Free Software Foundation.
  10 
  11  This code is distributed in the hope that it will be useful, but WITHOUT
  12  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  version 2 for more details (a copy is included in the LICENSE file that
  15  accompanied this code).
  16 
  17  You should have received a copy of the GNU General Public License version
  18  2 along with this work; if not, write to the Free Software Foundation,
  19  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20 
  21  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  or visit www.oracle.com if you need additional information or have any
  23  questions.
  24   
  25 -->
  26 
  27 <!DOCTYPE specification [
  28    <!ELEMENT specification (title, intro*, functionsection, errorsection, 
  29                             eventsection, datasection, issuessection, changehistory)>
  30    <!ATTLIST specification label CDATA #REQUIRED 
  31                            majorversion CDATA #REQUIRED 
  32                            minorversion CDATA #REQUIRED 
  33                            microversion CDATA #REQUIRED>
  34 
  35    <!ELEMENT title (#PCDATA|jvmti|tm)*>
  36    <!ATTLIST title subtitle CDATA #REQUIRED>
  37 
  38    <!ELEMENT intro ANY>
  39    <!ATTLIST intro id CDATA #IMPLIED
  40                    label CDATA "">
  41 
  42    <!ELEMENT functionsection (intro*, category*)>
  43    <!ATTLIST functionsection label CDATA #REQUIRED>
  44 
  45    <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*, 
  46                           (function|callback|elide)*)>
  47    <!ATTLIST category id CDATA #REQUIRED
  48                       label CDATA #REQUIRED>
  49 
  50    <!ELEMENT function (synopsis, typedef*, description?, origin,
  51                          (capabilities|eventcapabilities), 
  52                          parameters, errors)>
  53    <!ATTLIST function id CDATA #REQUIRED
  54                       num CDATA #REQUIRED
  55                       phase (onload|onloadOnly|start|live|any) #IMPLIED
  56                       callbacksafe (safe|unsafe) #IMPLIED
  57                       impl CDATA #IMPLIED
  58                       hide CDATA #IMPLIED
  59                       jkernel (yes|no) #IMPLIED
  60                       since CDATA "1.0">
  61 
  62    <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  63                         jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
  64                         synopsis, description?, parameters)>
  65    <!ATTLIST callback id CDATA #REQUIRED
  66                       since CDATA "1.0">
  67 
  68    <!ELEMENT synopsis (#PCDATA|jvmti)*>
  69 
  70    <!ELEMENT typedef (description?, field*)>
  71    <!ATTLIST typedef id CDATA #REQUIRED
  72                      label CDATA #REQUIRED
  73                      since CDATA "1.0">
  74 
  75    <!ELEMENT uniontypedef (description?, field*)>
  76    <!ATTLIST uniontypedef id CDATA #REQUIRED
  77                      label CDATA #REQUIRED
  78                      since CDATA "1.0">
  79 
  80    <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  81                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct), 
  82                     description)>
  83    <!ATTLIST field id CDATA #REQUIRED>
  84 
  85    <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
  86    <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
  87                      label CDATA #REQUIRED>
  88 
  89    <!ELEMENT capabilityfield (description)>
  90    <!ATTLIST capabilityfield id CDATA #REQUIRED
  91                    disp1 CDATA ""
  92                    disp2 CDATA ""
  93                    since CDATA "1.0">
  94 
  95    <!ELEMENT description ANY>
  96 
  97    <!ELEMENT capabilities (required*, capability*)>
  98 
  99    <!ELEMENT eventcapabilities EMPTY>
 100 
 101    <!ELEMENT required ANY>
 102    <!ATTLIST required id CDATA #REQUIRED>
 103 
 104    <!ELEMENT capability ANY>
 105    <!ATTLIST capability id CDATA #REQUIRED>
 106 
 107    <!ELEMENT parameters (param*)>
 108 
 109    <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
 110                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
 111                      outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf), 
 112                     description)>
 113    <!ATTLIST param id CDATA #REQUIRED>
 114 
 115    <!ELEMENT jmethodID EMPTY>
 116    <!ATTLIST jmethodID class  CDATA #IMPLIED
 117                        native CDATA #IMPLIED>
 118 
 119    <!ELEMENT jfieldID EMPTY>
 120    <!ATTLIST jfieldID class CDATA #IMPLIED>
 121 
 122    <!ELEMENT jclass EMPTY>
 123    <!ATTLIST jclass method CDATA #IMPLIED
 124                     field  CDATA #IMPLIED>
 125 
 126    <!ELEMENT jframeID EMPTY>
 127    <!ATTLIST jframeID thread CDATA #IMPLIED>
 128 
 129    <!ELEMENT jrawMonitorID EMPTY>
 130 
 131    <!ELEMENT jthread EMPTY>
 132    <!ATTLIST jthread started CDATA #IMPLIED
 133                      null CDATA #IMPLIED
 134                      frame CDATA #IMPLIED
 135                      impl CDATA #IMPLIED>
 136 
 137    <!ELEMENT varargs EMPTY>
 138 
 139    <!ELEMENT jthreadGroup EMPTY>
 140    <!ELEMENT jobject EMPTY>
 141    <!ELEMENT jvalue EMPTY>
 142    <!ELEMENT jchar EMPTY>
 143    <!ELEMENT jint EMPTY>
 144    <!ATTLIST jint min CDATA #IMPLIED>
 145    <!ELEMENT jlong EMPTY>
 146    <!ELEMENT jfloat EMPTY>
 147    <!ELEMENT jdouble EMPTY>
 148    <!ELEMENT jlocation EMPTY>
 149    <!ELEMENT jboolean EMPTY>
 150    <!ELEMENT char EMPTY>
 151    <!ELEMENT uchar EMPTY>
 152    <!ELEMENT size_t EMPTY>
 153    <!ELEMENT void EMPTY>
 154    <!ELEMENT enum (#PCDATA)*>
 155    <!ELEMENT struct (#PCDATA)*>
 156 
 157    <!ELEMENT nullok ANY>
 158 
 159    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 160                                    jthreadGroup|jobject|jvalue), nullok?)>
 161 
 162    <!ELEMENT outptr     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 163                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 164                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 165 
 166    <!ELEMENT allocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 167                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 168                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 169    <!ATTLIST allocbuf incount CDATA #IMPLIED
 170                       outcount CDATA #IMPLIED>
 171 
 172    <!ELEMENT allocallocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 173                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 174                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 175    <!ATTLIST allocallocbuf incount CDATA #IMPLIED
 176                       outcount CDATA #IMPLIED>
 177 
 178    <!ELEMENT inptr      (struct, nullok?)>
 179 
 180    <!ELEMENT inbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 181                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 182                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 183    <!ATTLIST inbuf    incount CDATA #IMPLIED>
 184 
 185    <!ELEMENT outbuf     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 186                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 187                                    jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
 188    <!ATTLIST outbuf   incount CDATA #IMPLIED
 189                       outcount CDATA #IMPLIED>
 190 
 191    <!ELEMENT vmbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 192                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 193                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 194    <!ATTLIST vmbuf    incount CDATA #IMPLIED
 195                       outcount CDATA #IMPLIED>
 196 
 197    <!ELEMENT agentbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 198                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 199                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 200    <!ATTLIST agentbuf incount CDATA #IMPLIED
 201                       outcount CDATA #IMPLIED>
 202 
 203    <!ELEMENT allocfieldbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 204                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 205                                    jlocation|jboolean|char|uchar|size_t|void))>
 206    <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
 207 
 208    <!ELEMENT errors (error*)>
 209 
 210    <!ELEMENT error ANY>
 211    <!ATTLIST error id CDATA #REQUIRED>
 212 
 213    <!ELEMENT errorsection (intro*, errorcategory*)>
 214    <!ATTLIST errorsection label CDATA #REQUIRED>
 215 
 216    <!ELEMENT errorcategory (intro*, errorid*)>
 217    <!ATTLIST errorcategory id CDATA #REQUIRED
 218                            label CDATA #REQUIRED>
 219 
 220    <!ELEMENT errorid ANY>
 221    <!ATTLIST errorid id CDATA #REQUIRED
 222                      num CDATA #REQUIRED>
 223 
 224    <!ELEMENT datasection (intro*, basetypes*)>
 225 
 226    <!ELEMENT basetypes (intro*, basetype*)>
 227    <!ATTLIST basetypes id CDATA #REQUIRED
 228                        label CDATA #REQUIRED>
 229 
 230    <!ELEMENT basetype (definition?,description)>
 231    <!ATTLIST basetype id CDATA #REQUIRED>
 232 
 233    <!ELEMENT definition (#PCDATA|jvmti)*>
 234 
 235    <!ELEMENT eventsection (intro*, (event|elide)*)>
 236    <!ATTLIST eventsection label CDATA #REQUIRED>
 237 
 238    <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
 239    <!ATTLIST event id CDATA #REQUIRED
 240                    label CDATA #REQUIRED
 241                    const CDATA #REQUIRED
 242                    num CDATA #REQUIRED
 243                    phase (onload|start|live|any) #IMPLIED
 244                    filtered (thread|global) #IMPLIED
 245                    since CDATA "1.0">
 246 
 247    <!ELEMENT issuessection (intro*)>
 248    <!ATTLIST issuessection label CDATA #REQUIRED>
 249 
 250    <!ELEMENT changehistory (intro*, change*)>
 251    <!ATTLIST changehistory update CDATA #REQUIRED
 252                            id CDATA #REQUIRED>
 253 
 254    <!ELEMENT change ANY>
 255    <!ATTLIST change date CDATA #REQUIRED
 256                     version CDATA #IMPLIED>
 257 
 258    <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
 259    <!ATTLIST functionlink id CDATA #REQUIRED>
 260 
 261    <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
 262    <!ATTLIST datalink id CDATA #REQUIRED>
 263 
 264    <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
 265    <!ATTLIST typelink id CDATA #REQUIRED>
 266 
 267    <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
 268    <!ATTLIST fieldlink id CDATA #REQUIRED
 269                        struct CDATA #REQUIRED>
 270 
 271    <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
 272    <!ATTLIST paramlink id CDATA #REQUIRED>
 273 
 274    <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
 275    <!ATTLIST eventlink id CDATA #REQUIRED>
 276 
 277    <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
 278    <!ATTLIST errorlink id CDATA #REQUIRED>
 279 
 280    <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
 281    <!ATTLIST externallink id CDATA #REQUIRED>
 282 
 283    <!ELEMENT vmspec EMPTY>
 284    <!ATTLIST vmspec chapter CDATA #IMPLIED>
 285 
 286    <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
 287    <!ATTLIST internallink id CDATA #REQUIRED>
 288 
 289    <!ELEMENT functionphaselist EMPTY>
 290    <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
 291 
 292    <!ELEMENT eventphaselist EMPTY>
 293    <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
 294 
 295    <!ELEMENT issue ANY>
 296    
 297    <!ELEMENT rationale ANY>
 298    
 299    <!ELEMENT todo ANY>
 300    
 301    <!ELEMENT origin (#PCDATA)*>
 302 
 303    <!ELEMENT elide (intro|function|callback|event)*>
 304    <!ATTLIST elide why CDATA #IMPLIED>
 305    
 306    <!ELEMENT constants (constant*)>
 307    <!ATTLIST constants id CDATA #REQUIRED
 308                        label CDATA #REQUIRED
 309                        kind (enum|bits|const) #REQUIRED
 310                        since CDATA "1.0">
 311 
 312    <!ELEMENT constant ANY>
 313    <!ATTLIST constant id CDATA #REQUIRED
 314                       num CDATA #REQUIRED>
 315 
 316    <!ELEMENT tm (#PCDATA)>
 317 
 318    <!ELEMENT i (#PCDATA|jvmti|tm)*>
 319 
 320    <!ELEMENT b (#PCDATA|jvmti|code)*>
 321 
 322    <!ELEMENT code (#PCDATA|space)*>
 323 
 324    <!ELEMENT pre ANY>
 325 
 326    <!ELEMENT space EMPTY>
 327 
 328    <!ELEMENT jvmti EMPTY>
 329 
 330    <!ELEMENT example (#PCDATA|i)*>
 331 
 332    <!ELEMENT br EMPTY>
 333 
 334    <!ELEMENT p EMPTY>
 335 
 336    <!ELEMENT dl  (dt|dd)+>
 337 
 338    <!ELEMENT dd  ANY>
 339 
 340    <!ELEMENT dt  (#PCDATA|jvmti|code|i|b)*>
 341 
 342    <!ELEMENT table  (tr)+>
 343 
 344    <!ELEMENT tr  (td|th)*>
 345 
 346    <!ELEMENT td  ANY>
 347    <!ATTLIST td align (left|right|center) "center">
 348 
 349    <!ELEMENT th  ANY>
 350    <!ATTLIST th align (left|right|center) "center">
 351 
 352    <!ELEMENT ul  (li)+>
 353    <!ATTLIST ul type (disc|circle|square) "disc">
 354 
 355    <!ELEMENT li  ANY>
 356  ]>
 357 
 358 <specification label="JVM(TM) Tool Interface"
 359         majorversion="1"
 360         minorversion="2"
 361         microversion="3">
 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 startup as it would
 462       have called the dynamic entry point Agent_OnUnLoad.
 463       If a <i>statically linked</i> agent L exports a function called
 464       Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
 465       function will be ignored.
 466 <p/>
 467       If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
 468       will be invoked with the same arguments and expected return value as
 469       specified for the Agent_OnAttach function.
 470       If a <i>statically linked</i> agent L exports a function called
 471       Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
 472       function will be ignored.
 473 </intro>
 474   
 475   <intro id="starting" label="Agent Command Line Options">
 476     The term "command-line option" is used below to
 477     mean options supplied in the <code>JavaVMInitArgs</code> argument
 478     to the <code>JNI_CreateJavaVM</code> function of the JNI
 479     Invocation API.
 480     <p/>
 481     One of the two following 
 482     command-line options is used on VM startup to 
 483     properly load and run agents.
 484     These arguments identify the library containing 
 485     the agent as well as an options
 486     string to be passed in at startup. 
 487     <dl>
 488       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 489       <dd>
 490         The name following <code>-agentlib:</code> is the name of the
 491         library to load.  Lookup of the library, both its full name and location,
 492         proceeds in a platform-specific manner.
 493         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
 494         operating system specific file name.
 495         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 496         For example, if the option 
 497         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to 
 498         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
 499         under <tm>Windows</tm> or <code>libfoo.so</code> from the 
 500         <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating
 501         environment.
 502         If the agent library is statically linked into the executable
 503         then no actual loading takes place.
 504     <p/>
 505       </dd>
 506       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 507       <dd>
 508         The path following <code>-agentpath:</code> is the absolute path from which
 509         to load the library.
 510         No library name expansion will occur.
 511         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 512         For example, if the option 
 513         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to 
 514         load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
 515         library is statically linked into the executable
 516         then no actual loading takes place.
 517     <p/>
 518       </dd>
 519     </dl>
 520     For a dynamic shared library agent, the start-up routine
 521     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 522     in the library will be invoked. If the agent library is statically linked
 523     into the executable then the system will attempt to invoke the
 524     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> entry point where
 525     &lt;agent-lib-name&gt; is the basename of the 
 526     agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
 527     the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
 528     <p/>
 529     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
 530     will be searched for JNI native method implementations to facilitate the
 531     use of Java programming language code in tools, as is needed for 
 532     <internallink id="bci">bytecode instrumentation</internallink>.
 533     <p/>
 534     The agent libraries will be searched after all other libraries have been
 535     searched (agents wishing to override or intercept the native method
 536     implementations of non-agent methods can use the
 537     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
 538     <p/>
 539     These switches do the above and nothing more - they do not change the 
 540     state of the VM or <jvmti/>.  No command line options are needed 
 541     to enable <jvmti/> 
 542     or aspects of <jvmti/>, this is handled programmatically
 543     by the use of 
 544     <internallink id="capability">capabilities</internallink>.
 545   </intro>
 546 
 547   <intro id="startup" label="Agent Start-Up">
 548     The VM starts each agent by invoking a start-up function.
 549     If the agent is started in the <code>OnLoad</code>
 550     <functionlink id="GetPhase">phase</functionlink> the function
 551     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 552     or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
 553     for statically linked agents will be invoked.
 554     If the agent is started in the live
 555     <functionlink id="GetPhase">phase</functionlink> the function
 556     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
 557     or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
 558     for statically linked agents will be invoked.
 559     Exactly one call to a start-up function is made per agent.  
 560   </intro>
 561 
 562   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
 563     If an agent is started during the <code>OnLoad</code> phase then its
 564     agent library must export a start-up function with the following prototype:
 565     <example>
 566 JNIEXPORT jint JNICALL 
 567 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
 568     Or for a statically linked agent named 'L':
 569     <example>
 570 JNIEXPORT jint JNICALL 
 571 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
 572 
 573     The VM will start the agent by calling this function.  
 574     It will be called early enough in VM initialization that:
 575     <ul>
 576       <li><functionlink id="SetSystemProperty">system properties</functionlink>
 577         may be set before they have been used in the start-up of the VM</li>
 578       <li>the full set of 
 579         <internallink id="capability">capabilities</internallink>
 580         is still available (note that capabilities that configure the VM
 581         may only be available at this time--see the 
 582         <internallink id="capability">Capability function section</internallink>)</li>
 583       <li>no bytecodes have executed</li>
 584       <li>no classes have been loaded</li>
 585       <li>no objects have been created</li>
 586     </ul>
 587     <p/>
 588     The VM will call the <code>Agent_OnLoad</code> or
 589     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> function with
 590     <i>&lt;options&gt;</i> as the second argument - 
 591     that is, using the command-line option examples,
 592     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> 
 593     argument of <code>Agent_OnLoad</code>.
 594     The <code>options</code> argument is encoded as a
 595     <internallink id="mUTF">modified UTF-8</internallink> string.
 596     If <i>=&lt;options&gt;</i> is not specified, 
 597     a zero length string is passed to <code>options</code>.
 598     The lifespan of the <code>options</code> string is the
 599     <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code>
 600     call.  If needed beyond this time the string or parts of the string must
 601     be copied.
 602     The period between when <code>Agent_OnLoad</code> is called and when it
 603     returns is called the <i>OnLoad phase</i>.
 604     Since the VM is not initialized during the OnLoad 
 605     <functionlink id="GetPhase">phase</functionlink>,
 606     the set of allowed operations 
 607     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
 608     functionality available at this time). 
 609     The agent can safely process the options and set 
 610     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once  
 611     the VM initialization event is received 
 612     (that is, the <eventlink id="VMInit">VMInit</eventlink> 
 613     callback is invoked), the agent
 614     can complete its initialization.
 615     <rationale>
 616       Early startup is required so that agents can set the desired capabilities,
 617       many of which must be set before the VM is initialized.
 618       In JVMDI, the -Xdebug command-line option provided 
 619       very coarse-grain control of capabilities. 
 620       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
 621       No reasonable command-line 
 622       option could provide the fine-grain of control required to balance needed capabilities vs
 623       performance impact.  
 624       Early startup is also needed so that agents can control the execution
 625       environment - modifying the file system and system properties to install
 626       their functionality.
 627     </rationale>
 628     <p/>
 629     The return value from <code>Agent_OnLoad</code> or
 630     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> is used to indicate an error.
 631     Any value other than zero indicates an error and causes termination of the VM.
 632   </intro>
 633   
 634   <intro id="onattach" label="Agent Start-Up (Live phase)">
 635     A VM may support a mechanism that allows agents to be started in the VM during the live 
 636     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
 637     are implementation specific. For example, a tool may use some platform specific mechanism, 
 638     or implementation specific API, to attach to the running VM, and request it start a given
 639     agent.
 640     <p/>
 641     If an agent is started during the live phase then its agent library
 642     must export a start-up function 
 643     with the following prototype:
 644     <example>
 645 JNIEXPORT jint JNICALL 
 646 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
 647 Or for a statically linked agent named 'L':
 648     <example>
 649 JNIEXPORT jint JNICALL 
 650 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
 651 
 652     <p/>         
 653     The VM will start the agent by calling this function.  
 654     It will be called in the context of a thread
 655     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
 656     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
 657     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
 658     </internallink> string.
 659     If startup options were not provided, a zero length string is passed to 
 660     <code>options</code>. The lifespan of the <code>options</code> string is the 
 661     <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> call.
 662     If needed beyond this time the string or parts of the string must be copied.
 663     <p/>
 664     Note that some <internallink id="capability">capabilities</internallink> 
 665     may not be available in the live phase.
 666     <p/>
 667     The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> function initializes the agent and returns a value
 668     to the VM to indicate if an error occurred. Any value other than zero indicates an error. 
 669     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes 
 670     some implementation specific action -- for example it might print an error to standard error, 
 671     or record the error in a system log.
 672   </intro>
 673 
 674   <intro id="onunload" label="Agent Shutdown">
 675     The library may optionally export a 
 676     shutdown function with the following prototype:
 677     <example>
 678 JNIEXPORT void JNICALL 
 679 Agent_OnUnload(JavaVM *vm)</example>
 680     Or for a statically linked agent named 'L':
 681     <example>
 682 JNIEXPORT void JNICALL 
 683 Agent_OnUnload_L(JavaVM *vm)</example>
 684 
 685     This function will be called by the VM when the library is about to be unloaded.
 686     The library will be unloaded (unless it is statically linked into the
 687     executable) and this function will be called if some platform specific 
 688     mechanism causes the unload (an unload mechanism is not specified in this document)
 689     or the library is (in effect) unloaded by the termination of the VM whether through 
 690     normal termination or VM failure, including start-up failure.
 691     Uncontrolled shutdown is, of couse, an exception to this rule.
 692     Note the distinction between this function and the 
 693     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
 694     to be sent, the VM must have run at least to the point of initialization and a valid 
 695     <jvmti/> environment must exist which has set a callback for VMDeath
 696     and enabled the event.
 697     None of these are required for <code>Agent_OnUnload</code> or
 698     <code>Agent_OnUnload_&lt;agent-lib-name&gt;</code> and this function
 699     is also called if the library is unloaded for other reasons.
 700     In the case that a VM Death event is sent, it will be sent before this 
 701     function is called (assuming this function is called due to VM termination).
 702     This function can be used to clean-up resources allocated by the agent.
 703   </intro>
 704 
 705   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
 706     Since the command-line cannot always be accessed or modified, for example in embedded VMs
 707     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
 708     provided so that agents may be launched in these cases.
 709     <p/>
 710     Platforms which support environment variables or other named strings, may support the 
 711     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space 
 712     boundaries.  White-space characters include space, tab, carriage-return, new-line, 
 713     vertical-tab, and form-feed.  Sequences of white-space characters are considered 
 714     equivalent to a single white-space character.  No white-space is included in the options 
 715     unless quoted.  Quoting is as follows:
 716     <ul>
 717         <li>All characters enclosed between a pair of single quote marks (''), except a single 
 718         quote, are quoted.</li>
 719         <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
 720         <li>All characters enclosed between a pair of double quote marks (""), except a double 
 721         quote, are quoted.</li>
 722         <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
 723         <li>A quoted part can start or end anywhere in the variable.</li>
 724         <li>White-space characters have no special meaning when quoted -- they are included in
 725         the option like any other character and do not mark white-space boundaries.</li>
 726         <li>The pair of quote marks is not included in the option.</li>
 727     </ul>
 728     <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied 
 729     in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is 
 730     a concern; for example, the Reference Implementation disables this feature on Unix systems when 
 731     the effective user or group ID differs from the real ID.  
 732     This feature is intended to support the initialization of tools -- specifically including the 
 733     launching of native or Java programming language agents.  Multiple tools may wish to use this 
 734     feature, so the variable should not be overwritten, instead,  options should be appended to 
 735     the variable.  Note that since the variable is processed at the time of the JNI Invocation 
 736     API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
 737   </intro>
 738 
 739   <intro id="environments" label="Environments">
 740     The <jvmti/> specification supports the use of multiple simultaneous
 741     <jvmti/> agents.
 742     Each agent has its own <jvmti/> environment.  
 743     That is, the <jvmti/> state is
 744     separate for each agent - changes to one environment do not affect the
 745     others.  The state of a <jvmti/> 
 746     environment includes:
 747     <ul>
 748       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
 749       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
 750       <li><internallink id="capability">the capabilities</internallink></li>
 751       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
 752     </ul>
 753     Although their <jvmti/> state 
 754     is separate, agents inspect and modify the shared state
 755     of the VM, they also share the native environment in which they execute.
 756     As such, an agent can perturb the results of other agents or cause them
 757     to fail.  It is the responsibility of the agent writer to specify the level
 758     of compatibility with other agents.  <jvmti/> implementations are not capable
 759     of preventing destructive interactions between agents. Techniques to reduce
 760     the likelihood of these occurrences are beyond the scope of this document.
 761     <p/>
 762     An agent creates a <jvmti/> environment 
 763     by passing a <jvmti/> version 
 764     as the interface ID to the JNI Invocation API function 
 765     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>.
 766     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
 767     for more details on the creation and use of 
 768     <jvmti/> environments.
 769     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from 
 770     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
 771   </intro>
 772 
 773   <intro id="bci" label="Bytecode Instrumentation">
 774     This interface does not include some events that one might expect in an interface with
 775     profiling support.  Some examples include object allocation events and full speed
 776     method enter and exit events.  The interface instead provides support for 
 777     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
 778     bytecode instructions which comprise the target program.  Typically, these alterations
 779     are to add "events" to the code of a method - for example, to add, at the beginning of a method,
 780     a call to <code>MyProfiler.methodEntered()</code>.  
 781     Since the changes are purely additive, they do not modify application
 782     state or behavior.
 783     Because the inserted agent code is standard bytecodes, the VM can run at full speed,
 784     optimizing not only the target program but also the instrumentation.  If the 
 785     instrumentation does not involve switching from bytecode execution, no expensive
 786     state transitions are needed.  The result is high performance events.
 787     This approach also provides complete control to the agent: instrumentation can be
 788     restricted to "interesting" portions of the code (e.g., the end user's code) and
 789     can be conditional.  Instrumentation can run entirely in Java programming language
 790     code or can call into the native agent.  Instrumentation can simply maintain
 791     counters or can statistically sample events.
 792     <p/>  
 793     Instrumentation can be inserted in one of three ways:
 794     <ul>
 795       <li>
 796         Static Instrumentation: The class file is instrumented before it
 797         is loaded into the VM - for example, by creating a duplicate directory of
 798         <code>*.class</code> files which have been modified to add the instrumentation.
 799         This method is extremely awkward and, in general, an agent cannot know 
 800         the origin of the class files which will be loaded.
 801       </li>
 802       <li>
 803         Load-Time Instrumentation: When a class file is loaded by the VM, the raw
 804         bytes of the class file are sent for instrumentation to the agent.
 805         The <eventlink id="ClassFileLoadHook"/>
 806         event, triggered by the class load,
 807         provides this functionality.  This mechanism provides efficient
 808         and complete access to one-time instrumentation.
 809       </li>
 810       <li>
 811         Dynamic Instrumentation: A class which is already loaded (and possibly
 812         even running) is modified.  This optional feature is provided by the
 813         <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
 814         <functionlink id="RetransformClasses"/> function.
 815         Classes can be modified multiple times and can be returned to their
 816         original state.
 817         The mechanism allows instrumentation which changes during the 
 818         course of execution.
 819       </li>
 820     </ul>
 821     <p/>  
 822     The class modification functionality provided in this interface
 823     is intended to provide a mechanism for instrumentation
 824     (the <eventlink id="ClassFileLoadHook"/> event
 825     and the <functionlink id="RetransformClasses"/> function)
 826     and, during development, for fix-and-continue debugging
 827     (the <functionlink id="RedefineClasses"/> function).
 828     <p/>  
 829     Care must be taken to avoid perturbing dependencies, especially when 
 830     instrumenting core classes.  For example, an approach to getting notification
 831     of every object allocation is to instrument the constructor on 
 832     <code>Object</code>.  Assuming that the constructor is initially
 833     empty, the constructor could be changed to:
 834     <example>
 835       public Object() {
 836         MyProfiler.allocationTracker(this);
 837       }
 838     </example>
 839     However, if this change was made using the 
 840     <eventlink id="ClassFileLoadHook"/>
 841     event then this might impact a typical VM as follows: 
 842     the first created object will call the constructor causing a class load of
 843     <code>MyProfiler</code>; which will then cause
 844     object creation, and since <code>MyProfiler</code> isn't loaded yet,
 845     infinite recursion; resulting in a stack overflow.  A refinement of this
 846     would be to delay invoking the tracking method until a safe time.  For
 847     example, <code>trackAllocations</code> could be set in the 
 848     handler for the <code>VMInit</code> event.
 849     <example>
 850       static boolean trackAllocations = false;
 851 
 852       public Object() {
 853         if (trackAllocations) {
 854           MyProfiler.allocationTracker(this);
 855         }
 856       }
 857     </example>
 858     <p/>
 859     The <functionlink id="SetNativeMethodPrefix"/> allows native methods
 860     to be instrumented by the use of wrapper methods.
 861   </intro>
 862 
 863   <intro id="mUTF" label="Modified UTF-8 String Encoding">
 864     <jvmti/> uses modified UTF-8 to encode character strings.
 865     This is the same encoding used by JNI.
 866     Modified UTF-8 differs 
 867     from standard UTF-8 in the representation of supplementary characters 
 868     and of the null character. See the
 869     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16542">
 870       Modified UTF-8 Strings</externallink>
 871     section of the JNI specification for details.
 872   </intro>
 873 
 874   <intro id="context" label="Specification Context">
 875     Since this interface provides access to the state of applications running in the
 876     Java virtual machine; 
 877     terminology refers to the Java platform and not the native
 878     platform (unless stated otherwise).  For example:
 879     <ul>
 880       <li>"thread" means Java programming language thread.</li>
 881       <li>"stack frame" means Java virtual machine stack frame.</li>
 882       <li>"class" means Java programming language class.</li>
 883       <li>"heap" means Java virtual machine heap.</li>
 884       <li>"monitor" means Java programming language object monitor.</li>
 885     </ul>
 886     <p/>
 887     Sun, Sun Microsystems, the Sun logo, Java, and JVM
 888     are trademarks or registered trademarks of Oracle 
 889     and/or its affiliates, in the U.S. and other countries.
 890   </intro>
 891 
 892 
 893 <functionsection label="Functions">
 894   <intro id="jvmtiEnvAccess" label="Accessing Functions">
 895     Native code accesses <jvmti/> features 
 896     by calling <jvmti/> functions. 
 897     Access to <jvmti/> functions is by use of an interface pointer
 898     in the same manner as 
 899     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html">Java 
 900       Native Interface (JNI) functions</externallink> are accessed.
 901     The <jvmti/> interface pointer is called the 
 902     <i>environment pointer</i>.
 903     <p/>
 904     An environment pointer is a pointer to an environment and has
 905     the type <code>jvmtiEnv*</code>.
 906     An environment has information about its <jvmti/> connection.
 907     The first value in the environment is a pointer to the function table.
 908     The function table is an array of pointers to <jvmti/> functions.
 909     Every function pointer is at a predefined offset inside the 
 910     array. 
 911     <p/>
 912     When used from the C language:
 913     double indirection is used to access the functions;
 914     the environment pointer provides context and is the first
 915     parameter of each function call; for example:
 916     <example>
 917 jvmtiEnv *jvmti;
 918 ...
 919 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);
 920     </example>
 921     <p/>
 922     When used from the C++ language:
 923     functions are accessed as member functions of <code>jvmtiEnv</code>;
 924     the environment pointer is not passed to the function call; for example:
 925     <example>
 926 jvmtiEnv *jvmti;
 927 ...
 928 jvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);
 929     </example>
 930     Unless otherwise stated, all examples and declarations in this 
 931     specification use the C language.
 932     <p/>
 933     A <jvmti/> environment can be obtained through the JNI Invocation API
 934     <code>GetEnv</code> function:
 935     <example>
 936 jvmtiEnv *jvmti;
 937 ...
 938 (*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);
 939     </example>
 940     Each call to <code>GetEnv</code> 
 941     creates a new <jvmti/> connection and thus
 942     a new <jvmti/> environment. 
 943     The <code>version</code> argument of <code>GetEnv</code> must be
 944     a <jvmti/> version.
 945     The returned environment may have a different version than the
 946     requested version but the returned environment must be compatible.
 947     <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a 
 948     compatible version is not available, if <jvmti/> is not supported or
 949     <jvmti/> is not supported in the current VM configuration.
 950     Other interfaces may be added for creating <jvmti/> environments
 951     in specific contexts.
 952     Each environment has its own state (for example,
 953     <functionlink id="SetEventNotificationMode">desired events</functionlink>, 
 954     <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and 
 955     <functionlink id="AddCapabilities">capabilities</functionlink>). 
 956     An environment is released with 
 957     <functionlink id="DisposeEnvironment"></functionlink>. 
 958     Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
 959     across threads and are created dynamically.
 960   </intro>
 961 
 962   <intro id="functionReturn" label="Function Return Values">
 963     <jvmti/> functions always return an
 964     <internallink id="ErrorSection">error code</internallink> via the
 965     <datalink id="jvmtiError"/> function return value. 
 966     Some functions can return additional
 967     values through pointers provided by the calling function. 
 968     In some cases, <jvmti/> functions allocate memory that your program must
 969     explicitly deallocate. This is indicated in the individual <jvmti/>
 970     function descriptions.  Empty lists, arrays, sequences, etc are 
 971     returned as <code>NULL</code>.
 972     <p/>
 973     In the event that the <jvmti/> function encounters
 974     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
 975     of memory referenced by argument pointers is undefined, but no memory
 976     will have been allocated and no global references will have been allocated.
 977     If the error occurs because of invalid input, no action will have occurred.
 978   </intro>
 979 
 980 <intro id="refs" label="Managing JNI Object References">
 981     <jvmti/> functions identify objects with JNI references 
 982     (<datalink id="jobject"/> and <datalink id="jclass"/>)
 983     and their derivatives
 984     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
 985     References passed to 
 986     <jvmti/> functions can be either global or local, but they must be 
 987     strong references. All references returned by <jvmti/> functions are 
 988     local references--these local references are created 
 989     during the <jvmti/> call.
 990     Local references are a resource that must be managed (see the 
 991     <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp18654">JNI Documentation</externallink>).  
 992     When threads return from native code all local references
 993     are freed.  Note that some threads, including typical
 994     agent threads, will never return from native code.
 995     A thread is ensured the ability to create sixteen local 
 996     references without the need for any explicit management.
 997     For threads executing a limited number of <jvmti/> calls before
 998     returning from native code
 999     (for example, threads processing events), 
1000     it may be determined that no explicit management
1001     is needed.
1002     However, long running agent threads will need explicit
1003     local reference management--usually with the JNI functions
1004     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
1005     Conversely, to preserve references beyond the
1006     return from native code, they must be converted to global references.
1007     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> 
1008     as they are not <datalink id="jobject"/>s.
1009 </intro>
1010 
1011     <intro id="prereqState" label="Prerequisite State for Calling Functions">
1012       Unless the function explicitly states that the agent must bring
1013       a thread or the VM to a particular state (for example, suspended),
1014       the <jvmti/> implementation is responsible for bringing the VM to a
1015       safe and consistent state for performing the function.
1016     </intro>
1017 
1018     <intro id="functionsExceptions" label="Exceptions and Functions">
1019       <jvmti/> functions never throw exceptions; error conditions are 
1020       communicated via the 
1021       <internallink id="functionReturn">function return value</internallink>.
1022       Any existing exception state is preserved across a call to a 
1023       <jvmti/> function.
1024       See the
1025       <externallink 
1026         id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp770"
1027              >Java Exceptions</externallink>
1028       section of the JNI specification for information on handling exceptions.
1029     </intro>
1030 
1031   <category id="memory" label="Memory Management">
1032     <intro>
1033       These functions provide for the allocation and deallocation of 
1034       memory used by <jvmti/> functionality and can be used to provide
1035       working memory for agents.
1036       Memory managed by <jvmti/> is not compatible with other memory
1037       allocation libraries and mechanisms.
1038     </intro>
1039 
1040     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
1041       <synopsis>Allocate</synopsis>
1042       <description>
1043         Allocate an area of memory through the <jvmti/> allocator. 
1044         The allocated
1045         memory should be freed with <functionlink id="Deallocate"></functionlink>.
1046       </description>
1047       <origin>jvmdi</origin>
1048       <capabilities>
1049       </capabilities>
1050       <parameters>
1051         <param id="size">
1052           <jlong/>
1053           <description>
1054             The number of bytes to allocate.
1055             <rationale>
1056               <code>jlong</code> is used for compatibility with JVMDI.
1057             </rationale>
1058           </description>
1059         </param>
1060         <param id="mem_ptr">
1061           <allocbuf incount="size"><uchar/></allocbuf>
1062           <description>
1063             On return, a pointer to the beginning of the allocated memory.
1064             If <code>size</code> is zero, <code>NULL</code> is returned.
1065           </description>
1066         </param>
1067       </parameters>
1068       <errors>
1069         <error id="JVMTI_ERROR_OUT_OF_MEMORY">
1070           Memory request cannot be honored.
1071         </error>
1072         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
1073           <paramlink id="size"></paramlink> is less than zero.
1074         </error>
1075       </errors>
1076     </function>
1077 
1078     <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
1079       <synopsis>Deallocate</synopsis>
1080       <description>
1081         Deallocate <code>mem</code>  using the <jvmti/> allocator. 
1082         This function should
1083         be used to deallocate any memory allocated and returned 
1084         by a <jvmti/> function
1085         (including memory allocated with <functionlink id="Allocate"></functionlink>).
1086         All allocated memory must be deallocated
1087         or the memory cannot be reclaimed.
1088       </description>
1089       <origin>jvmdi</origin>
1090       <capabilities>
1091       </capabilities>
1092       <parameters>
1093         <param id="mem">
1094           <outbuf>
1095             <uchar/>
1096             <nullok>the call is ignored</nullok>
1097           </outbuf>
1098           <description>
1099             A pointer to the beginning of the allocated memory.
1100             Please ignore "On return, the elements are set."
1101               <todo>keep it from generating "On return, the elements are set"</todo>
1102           </description>
1103         </param>
1104       </parameters>
1105       <errors>
1106       </errors>
1107     </function>
1108   </category>
1109 
1110   <category id="threadCategory" label="Thread">
1111     <intro>
1112     </intro>
1113 
1114     <function id="GetThreadState" num="17">
1115       <synopsis>Get Thread State</synopsis>
1116       <description>
1117         Get the state of a thread.  The state of the thread is represented by the
1118         answers to the hierarchical set of questions below:
1119           <ul type="circle">
1120             <li><i>Alive?</i>
1121               <ul>
1122                 <li>Not alive.
1123                   <ul type="circle">
1124                     <li><i>Why not alive?</i>
1125                       <ul>
1126                         <li>New.</li>
1127                         <li>Terminated (<datalink 
1128                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
1129                       </ul>
1130                     </li>
1131                   </ul>
1132                 </li>
1133                 <li>Alive (<datalink 
1134                     id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
1135                   <ul type="circle">
1136                     <li><i>Suspended?</i>
1137                       <ul>
1138                         <li>Suspended (<datalink 
1139                             id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
1140                         <li>Not suspended</li>
1141                       </ul>
1142                     </li>
1143                     <li><i>Interrupted?</i>
1144                       <ul>
1145                         <li>Interrupted (<datalink 
1146                             id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
1147                         <li>Not interrupted.</li>
1148                       </ul>
1149                     </li>
1150                     <li><i>In native?</i>
1151                       <ul>
1152                         <li>In native code (<datalink 
1153                             id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
1154                         <li>In Java programming language code</li>
1155                       </ul>
1156                     </li>
1157                     <li><i>What alive state?</i>
1158                       <ul>
1159                         <li>Runnable (<datalink 
1160                             id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
1161                         <li>Blocked (<datalink 
1162                             id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
1163                         <li>Waiting (<datalink 
1164                             id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
1165                           <ul type="circle">
1166                             <li><i>Timed wait?</i>
1167                               <ul>
1168                                 <li>Indefinite (<datalink 
1169                                     id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
1170                                 <li>Timed (<datalink 
1171                                     id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
1172                               </ul>
1173                             </li>
1174                             <li><i>Why waiting?</i>
1175                               <ul>
1176                                 <li>Object.wait (<datalink 
1177                                     id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
1178                                 <li>LockSupport.park (<datalink 
1179                                     id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
1180                                 <li>Sleeping (<datalink 
1181                                     id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
1182                               </ul>
1183                             </li>
1184                           </ul>
1185                         </li>
1186                       </ul>
1187                     </li>
1188                   </ul>
1189                 </li>
1190               </ul>
1191             </li>
1192           </ul>
1193         <p/>
1194         The answers are represented by the following bit vector. 
1195         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
1196           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
1197             Thread is alive. Zero if thread is new (not started) or terminated.
1198           </constant>
1199           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
1200             Thread has completed execution.
1201           </constant>
1202           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
1203             Thread is runnable.
1204           </constant>
1205           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
1206             Thread is waiting to enter a synchronization block/method or,
1207             after an <code>Object.wait()</code>, waiting to re-enter a 
1208             synchronization block/method.
1209           </constant>
1210           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
1211             Thread is waiting.
1212           </constant>
1213           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
1214             Thread is waiting without a timeout.
1215             For example, <code>Object.wait()</code>.
1216           </constant>
1217           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
1218             Thread is waiting with a maximum time to wait specified.
1219             For example, <code>Object.wait(long)</code>.
1220           </constant>
1221           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
1222             Thread is sleeping -- <code>Thread.sleep(long)</code>.
1223           </constant>
1224           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
1225             Thread is waiting on an object monitor -- <code>Object.wait</code>.
1226           </constant>
1227           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
1228             Thread is parked, for example: <code>LockSupport.park</code>,
1229             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
1230           </constant>
1231           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
1232             Thread suspended.
1233             <code>java.lang.Thread.suspend()</code>
1234             or a <jvmti/> suspend function 
1235             (such as <functionlink id="SuspendThread"></functionlink>) 
1236             has been called on the thread. If this bit
1237             is set, the other bits refer to the thread state before suspension.
1238           </constant>
1239           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
1240             Thread has been interrupted.
1241           </constant>
1242           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
1243             Thread is in native code--that is, a native method is running
1244             which has not called back into the VM or Java programming
1245             language code.
1246             <p/>
1247             This flag is not set when running VM compiled Java programming
1248             language code nor is it set when running VM code or
1249             VM support code. Native VM interface functions, such as JNI and
1250             <jvmti/> functions, may be implemented as VM code.
1251           </constant>
1252           <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
1253             Defined by VM vendor.
1254           </constant>
1255           <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
1256             Defined by VM vendor.
1257           </constant>
1258           <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
1259             Defined by VM vendor.
1260           </constant>
1261         </constants>
1262         The following definitions are used to convert <jvmti/> thread state
1263         to <code>java.lang.Thread.State</code> style states.
1264         <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
1265           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
1266                      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">
1267             Mask the state with this before comparison
1268           </constant>
1269           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
1270                      num="0">
1271             <code>java.lang.Thread.State.NEW</code>
1272           </constant>
1273           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
1274                      num="JVMTI_THREAD_STATE_TERMINATED">
1275             <code>java.lang.Thread.State.TERMINATED</code>
1276           </constant>
1277           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
1278                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
1279             <code>java.lang.Thread.State.RUNNABLE</code>
1280           </constant>
1281           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
1282                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
1283             <code>java.lang.Thread.State.BLOCKED</code>
1284           </constant>
1285           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
1286                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
1287             <code>java.lang.Thread.State.WAITING</code>
1288           </constant>
1289           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
1290                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1291             <code>java.lang.Thread.State.TIMED_WAITING</code>
1292           </constant>
1293         </constants>
1294         <b>Rules</b>
1295         <p/>
1296         There can be no more than one answer to a question, although there can be no
1297         answer (because the answer is unknown, does not apply, or none of the answers is 
1298         correct).  An answer is set only when the enclosing answers match.
1299         That is, no more than one of
1300           <ul type="circle">
1301               <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
1302               <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
1303               <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
1304           </ul>
1305         can be set (a <tm>J2SE</tm> compliant implementation will always set
1306         one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). 
1307         And if any of these are set, the enclosing answer 
1308         <code>JVMTI_THREAD_STATE_ALIVE</code> is set. 
1309         No more than one of
1310           <ul type="circle">
1311               <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
1312               <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
1313           </ul>
1314         can be set (a <tm>J2SE</tm> compliant implementation will always set
1315         one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). 
1316         And if either is set, the enclosing answers 
1317         <code>JVMTI_THREAD_STATE_ALIVE</code> and 
1318         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 
1319         No more than one of
1320           <ul type="circle">
1321               <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
1322               <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
1323               <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
1324           </ul>
1325         can be set. And if any of these is set, the enclosing answers 
1326         <code>JVMTI_THREAD_STATE_ALIVE</code> and 
1327         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 
1328         Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
1329         then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
1330         If a state <i>A</i> is implemented using the mechanism of 
1331         state <i>B</i> then it is state <i>A</i> which 
1332         is returned by this function.
1333         For example, if <code>Thread.sleep(long)</code>
1334         is implemented using <code>Object.wait(long)</code>
1335         then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
1336         which is returned.
1337         More than one of
1338           <ul type="circle">
1339               <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
1340               <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
1341               <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
1342           </ul>
1343         can be set, but if any is set,
1344         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1345         <p/>
1346         And finally,
1347         <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
1348         <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.  
1349         <p/>
1350         The thread state representation is designed for extension in future versions
1351         of the specification; thread state values should be used accordingly, that is
1352         they should not be used as ordinals.  
1353         Most queries can be made by testing a single bit, if use in a switch statement is desired,
1354         the state bits should be masked with the interesting bits.
1355         All bits not defined above are reserved for future use.  
1356         A VM, compliant to the current specification, must set reserved bits to zero.
1357         An agent should ignore reserved bits -- 
1358         they should not be assumed to be zero and thus should not be included in comparisons.
1359         <p/>
1360         <b>Examples</b>
1361         <p/>
1362         Note that the values below exclude reserved and vendor bits.
1363         <p/>
1364         The state of a thread blocked at a <code>synchronized</code>-statement would be:
1365         <example>
1366             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
1367         </example>
1368         The state of a thread which hasn't started yet would be:
1369         <example>
1370             0
1371         </example>
1372         The state of a thread at a <code>Object.wait(3000)</code> would be:
1373         <example>
1374             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + 
1375                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + 
1376                 JVMTI_THREAD_STATE_MONITOR_WAITING
1377         </example>
1378         The state of a thread suspended while runnable would be:
1379         <example>
1380             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
1381         </example>
1382         <p/>
1383         <b>Testing the State</b>
1384         <p/>
1385         In most cases, the thread state can be determined by testing the one bit corresponding
1386         to that question.  For example, the code to test if a thread is sleeping:
1387         <example>
1388         jint state;
1389         jvmtiError err;
1390 
1391         err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1392         if (err == JVMTI_ERROR_NONE) {
1393            if (state &amp; JVMTI_THREAD_STATE_SLEEPING) {  ...
1394         </example>
1395         <p/>
1396         For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
1397         <example>
1398            if (state &amp; JVMTI_THREAD_STATE_WAITING) {  ...
1399         </example>
1400         For some states, more than one bit will need to be tested as is the case
1401         when testing if a thread has not yet been started:
1402         <example>
1403            if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
1404         </example>
1405         To distinguish timed from untimed <code>Object.wait</code>:
1406         <example>
1407            if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {  
1408              if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
1409                printf("in Object.wait(long timeout)\n");
1410              } else {
1411                printf("in Object.wait()\n");
1412              }
1413            }
1414         </example>
1415         <p/>
1416         <b>Relationship to <code>java.lang.Thread.State</code></b>
1417         <p/>
1418         The thread state represented by <code>java.lang.Thread.State</code>
1419         returned from <code>java.lang.Thread.getState()</code> is a subset of the
1420         information returned from this function.  
1421         The corresponding <code>java.lang.Thread.State</code> can be determined
1422         by using the provided conversion masks.
1423         For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
1424         <example>
1425             err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1426             abortOnError(err);
1427             switch (state &amp; JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
1428             case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
1429               return "NEW";
1430             case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
1431               return "TERMINATED";
1432             case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
1433               return "RUNNABLE";
1434             case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
1435               return "BLOCKED";
1436             case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
1437               return "WAITING";
1438             case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
1439               return "TIMED_WAITING";
1440             }
1441         </example>
1442       </description>
1443       <origin>new</origin>
1444       <capabilities>
1445       </capabilities>
1446       <parameters>
1447         <param id="thread">
1448           <jthread null="current" started="maybe" impl="noconvert"/>
1449             <description>
1450               The thread to query. 
1451             </description>
1452         </param>
1453         <param id="thread_state_ptr">
1454           <outptr><jint/></outptr>
1455           <description>
1456             On return, points to state flags,
1457             as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
1458           </description>
1459         </param>
1460       </parameters>
1461       <errors>
1462       </errors>
1463     </function>
1464 
1465     <function id="GetCurrentThread" phase="start" num="18" since="1.1">
1466       <synopsis>Get Current Thread</synopsis>
1467       <description>
1468         Get the current thread.  
1469         The current thread is the Java programming language thread which has called the function.
1470         <p/>
1471         Note that most <jvmti/> functions that take a thread 
1472         as an argument will accept <code>NULL</code> to mean 
1473         the current thread.
1474       </description>
1475       <origin>new</origin>
1476       <capabilities>
1477       </capabilities>
1478       <parameters>
1479         <param id="thread_ptr">
1480           <outptr><jthread/></outptr>
1481           <description>
1482              On return, points to the current thread.
1483           </description>
1484         </param>
1485       </parameters>
1486       <errors>
1487       </errors>
1488     </function>
1489 
1490     <function id="GetAllThreads" num="4">
1491       <synopsis>Get All Threads</synopsis>
1492       <description>
1493         Get all live threads.
1494         The threads are Java programming language threads;
1495         that is, threads that are attached to the VM.
1496         A thread is live if <code>java.lang.Thread.isAlive()</code> 
1497         would return <code>true</code>, that is, the thread has
1498         been started and has not yet died.
1499         The universe of threads is determined by the context of the <jvmti/>
1500         environment, which typically is all threads attached to the VM.
1501         Note that this includes <jvmti/> agent threads 
1502         (see <functionlink id="RunAgentThread"/>).
1503       </description>
1504       <origin>jvmdi</origin>
1505       <capabilities>
1506       </capabilities>
1507       <parameters>
1508         <param id="threads_count_ptr">
1509           <outptr><jint/></outptr>
1510           <description>
1511             On return, points to the number of running threads.
1512           </description>
1513         </param>
1514         <param id="threads_ptr">
1515           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
1516             <description>
1517               On return, points to an array of references, one
1518               for each running thread.
1519             </description>
1520         </param>
1521       </parameters>
1522       <errors>
1523       </errors>
1524     </function>
1525 
1526     <function id="SuspendThread" num="5">
1527       <synopsis>Suspend Thread</synopsis>
1528       <description>
1529         Suspend the specified thread. If the calling thread is specified, 
1530         this function will not return until some other thread calls 
1531         <functionlink id="ResumeThread"></functionlink>.
1532         If the thread is currently suspended, this function
1533         does nothing and returns an error.
1534       </description>
1535       <origin>jvmdi</origin>
1536       <capabilities>
1537         <required id="can_suspend"></required>
1538       </capabilities>
1539       <parameters>
1540         <param id="thread">
1541           <jthread null="current"/>
1542             <description>
1543               The thread to suspend. 
1544             </description>
1545         </param>
1546       </parameters>
1547       <errors>
1548         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
1549           Thread already suspended.
1550         </error>
1551       </errors>
1552     </function>
1553 
1554     <elide>
1555     <function id="SuspendAllThreads" num="101">
1556       <synopsis>Suspend All Threads</synopsis>
1557       <description>
1558         <issue>
1559             There has been no explicit call for this function, and it will
1560             thus be removed if there is no interest.
1561         </issue>
1562         Suspend all live threads except:
1563         <ul>
1564           <li>already suspended threads</li>
1565           <li>those listed in <paramlink id="except_list"></paramlink></li>
1566           <li>certain system (non application) threads, as determined
1567             by the VM implementation</li>
1568         </ul>
1569         The threads are Java programming language threads;
1570         native threads which are not attached to the VM are not
1571         Java programming language threads.
1572         A thread is live if <code>java.lang.Thread.isAlive()</code> 
1573         would return <code>true</code>, that is, the thread has
1574         been started and has not yet died.
1575         The universe of threads is determined 
1576         by the context of the <jvmti/>
1577         environment, which, typically, is all threads attached to the VM,
1578         except critical VM internal threads and <jvmti/> agent threads 
1579         (see <functionlink id="RunAgentThread"/>).
1580         <p/>
1581         If the calling thread is specified, 
1582         all other threads are suspended first then the caller thread is suspended -
1583         this function will not return until some other thread calls 
1584         <functionlink id="ResumeThread"></functionlink>.
1585         <p/>
1586         The list of actually
1587         suspended threads is returned in 
1588         <paramlink id="suspended_list_ptr"></paramlink>.
1589         Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
1590         <functionlink id="ResumeThreadList"></functionlink>
1591         can be used to resume the suspended threads.
1592       </description>
1593       <origin>new</origin>
1594       <capabilities>
1595         <required id="can_suspend"></required>
1596       </capabilities>
1597       <parameters>
1598         <param id="except_count">
1599           <jint min="0"/>
1600           <description>
1601             The number of threads in the list of threads not to be suspended.
1602           </description>
1603         </param>
1604         <param id="except_list">
1605             <inbuf incount="except_count">
1606               <jthread/>
1607               <nullok>not an error if <code>except_count == 0</code></nullok>
1608             </inbuf>
1609             <description>
1610               The list of threads not to be suspended.
1611             </description>
1612         </param>
1613         <param id="suspended_count_ptr">
1614           <outptr><jint/></outptr>
1615           <description>
1616             On return, points to the number of threads suspended by this call.
1617           </description>
1618         </param>
1619         <param id="suspended_list_ptr">
1620           <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
1621             <description>
1622               On return, points to an array of references, one
1623               for each thread suspended.
1624             </description>
1625         </param>
1626       </parameters>
1627       <errors>
1628         <error id="JVMTI_ERROR_INVALID_THREAD">
1629           A thread in <paramlink id="except_list"></paramlink> was invalid.
1630         </error>
1631         <error id="JVMTI_ERROR_NULL_POINTER">
1632           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1633           and <paramlink id="except_count"></paramlink> was non-zero.
1634         </error>
1635       </errors>
1636     </function>
1637     </elide>
1638 
1639     <function id="SuspendThreadList" num="92">
1640       <synopsis>Suspend Thread List</synopsis>
1641       <description>
1642         Suspend the <paramlink id="request_count"></paramlink> 
1643         threads specified in the 
1644         <paramlink id="request_list"></paramlink> array. 
1645         Threads may be resumed with
1646         <functionlink id="ResumeThreadList"></functionlink> or
1647         <functionlink id="ResumeThread"></functionlink>.
1648         If the calling thread is specified in the 
1649         <paramlink id="request_list"></paramlink> array, this function will
1650         not return until some other thread resumes it.
1651         Errors encountered in the suspension of a thread
1652         are returned in the <paramlink id="results"></paramlink>
1653         array, <b>not</b> in the return value of this function.
1654         Threads that are currently suspended do not change state.
1655       </description>
1656       <origin>jvmdi</origin>
1657       <capabilities>
1658         <required id="can_suspend"></required>
1659       </capabilities>
1660       <parameters>
1661         <param id="request_count">
1662           <jint min="0"/>
1663           <description>
1664             The number of threads to suspend.
1665           </description>
1666         </param>
1667         <param id="request_list">
1668           <inbuf incount="request_count"><jthread/></inbuf>
1669             <description>
1670               The list of threads to suspend.
1671             </description>
1672         </param>
1673         <param id="results">
1674           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1675           <description>
1676             An agent supplied array of 
1677             <paramlink id="request_count"></paramlink> elements.
1678             On return, filled with the error code for
1679             the suspend of the corresponding thread.
1680             The error code will be 
1681             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1682             if the thread was suspended by this call.
1683             Possible error codes are those specified
1684             for <functionlink id="SuspendThread"></functionlink>.
1685           </description>
1686         </param>
1687       </parameters>
1688       <errors>
1689       </errors>
1690     </function>
1691 
1692     <function id="ResumeThread" num="6">
1693       <synopsis>Resume Thread</synopsis>
1694       <description>
1695         Resume a suspended thread. 
1696         Any threads currently suspended through
1697         a <jvmti/> suspend function (eg.
1698         <functionlink id="SuspendThread"></functionlink>) 
1699         or <code>java.lang.Thread.suspend()</code>
1700         will resume execution;  
1701         all other threads are unaffected.
1702       </description>
1703       <origin>jvmdi</origin>
1704       <capabilities>
1705         <required id="can_suspend"></required>
1706       </capabilities>
1707       <parameters>
1708         <param id="thread">
1709           <jthread/>
1710             <description>
1711               The thread to resume.
1712             </description>
1713         </param>
1714       </parameters>
1715       <errors>
1716         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
1717           Thread was not suspended.
1718         </error>
1719         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
1720           The state of the thread has been modified, and is now inconsistent. 
1721         </error>
1722       </errors>
1723     </function>
1724 
1725     <function id="ResumeThreadList" num="93">
1726       <synopsis>Resume Thread List</synopsis>
1727       <description>
1728         Resume the <paramlink id="request_count"></paramlink> 
1729         threads specified in the 
1730         <paramlink id="request_list"></paramlink> array. 
1731         Any thread suspended through
1732         a <jvmti/> suspend function (eg.
1733         <functionlink id="SuspendThreadList"></functionlink>) 
1734         or <code>java.lang.Thread.suspend()</code>
1735         will resume execution.
1736       </description>
1737       <origin>jvmdi</origin>
1738       <capabilities>
1739         <required id="can_suspend"></required>
1740       </capabilities>
1741       <parameters>
1742         <param id="request_count">
1743           <jint min="0"/>
1744           <description>
1745             The number of threads to resume.
1746           </description>
1747         </param>
1748         <param id="request_list">
1749           <inbuf incount="request_count"><jthread/></inbuf>
1750             <description>
1751               The threads to resume.
1752             </description>
1753         </param>
1754         <param id="results">
1755           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1756           <description>
1757             An agent supplied array of 
1758             <paramlink id="request_count"></paramlink> elements.
1759             On return, filled with the error code for
1760             the resume of the corresponding thread.
1761             The error code will be 
1762             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1763             if the thread was suspended by this call.
1764             Possible error codes are those specified
1765             for <functionlink id="ResumeThread"></functionlink>.
1766           </description>
1767         </param>
1768       </parameters>
1769       <errors>
1770       </errors>
1771     </function>
1772 
1773     <function id="StopThread" num="7">
1774       <synopsis>Stop Thread</synopsis>
1775       <description>
1776         Send the specified asynchronous exception to the specified thread 
1777         (similar to <code>java.lang.Thread.stop</code>).
1778         Normally, this function is used to kill the specified thread with an 
1779         instance of the exception <code>ThreadDeath</code>.
1780       </description>
1781       <origin>jvmdi</origin>
1782       <capabilities>
1783         <required id="can_signal_thread"></required>
1784       </capabilities>
1785       <parameters>
1786         <param id="thread">
1787           <jthread/>
1788             <description>
1789               The thread to stop.
1790             </description>
1791         </param>
1792         <param id="exception">
1793           <jobject/>
1794             <description>
1795               The asynchronous exception object.
1796             </description>
1797         </param>
1798       </parameters>
1799       <errors>
1800       </errors>
1801     </function>
1802 
1803     <function id="InterruptThread" num="8">
1804       <synopsis>Interrupt Thread</synopsis>
1805       <description>
1806         Interrupt the specified thread
1807         (similar to <code>java.lang.Thread.interrupt</code>).
1808       </description>
1809       <origin>jvmdi</origin>
1810       <capabilities>
1811         <required id="can_signal_thread"></required>
1812       </capabilities>
1813       <parameters>
1814         <param id="thread">
1815           <jthread impl="noconvert"/>
1816             <description>
1817               The thread to interrupt.
1818             </description>
1819         </param>
1820       </parameters>
1821       <errors>
1822       </errors>
1823     </function>
1824 
1825     <function id="GetThreadInfo" num="9">
1826       <synopsis>Get Thread Info</synopsis>
1827       <typedef id="jvmtiThreadInfo" label="Thread information structure">
1828         <field id="name">
1829           <allocfieldbuf><char/></allocfieldbuf>
1830           <description>
1831             The thread name, encoded as a
1832             <internallink id="mUTF">modified UTF-8</internallink> string.
1833           </description>
1834         </field>
1835         <field id="priority">
1836           <jint/>
1837           <description>
1838             The thread priority.  See the thread priority constants:
1839             <datalink id="jvmtiThreadPriority"></datalink>.
1840           </description>
1841         </field>
1842         <field id="is_daemon">
1843           <jboolean/>
1844           <description>
1845             Is this a daemon thread?
1846           </description>
1847         </field>
1848         <field id="thread_group">
1849           <jthreadGroup/>
1850           <description>
1851             The thread group to which this thread belongs.
1852             <code>NULL</code> if the thread has died.
1853           </description>
1854         </field>
1855         <field id="context_class_loader">
1856           <jobject/>
1857             <description>
1858               The context class loader associated with this thread.
1859             </description>
1860         </field>
1861       </typedef>
1862       <description>
1863         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure 
1864         are filled in with details of the specified thread.
1865       </description>
1866       <origin>jvmdi</origin>
1867       <capabilities>
1868       </capabilities>
1869       <parameters>
1870         <param id="thread">
1871           <jthread null="current" impl="noconvert" started="maybe"/>
1872             <description>
1873               The thread to query.
1874             </description>
1875         </param>
1876         <param id="info_ptr">
1877           <outptr><struct>jvmtiThreadInfo</struct></outptr>
1878           <description>
1879             On return, filled with information describing the specified thread.
1880             <p/>
1881             For JDK 1.1 implementations that don't
1882             recognize context class loaders, 
1883             the <code>context_class_loader</code> field will be NULL.
1884           </description>
1885         </param>
1886       </parameters>
1887       <errors>
1888       </errors>
1889     </function>
1890 
1891     <function id="GetOwnedMonitorInfo" num="10">
1892       <synopsis>Get Owned Monitor Info</synopsis>
1893       <description>
1894         Get information about the monitors owned by the 
1895         specified thread. 
1896       </description>
1897       <origin>jvmdiClone</origin>
1898       <capabilities>
1899         <required id="can_get_owned_monitor_info"></required>
1900       </capabilities>
1901       <parameters>
1902         <param id="thread">
1903           <jthread null="current"/>
1904             <description>
1905               The thread to query.
1906             </description>
1907         </param>
1908         <param id="owned_monitor_count_ptr">
1909           <outptr><jint/></outptr>
1910           <description>
1911             The number of monitors returned.
1912           </description>
1913         </param>
1914         <param id="owned_monitors_ptr">
1915           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
1916             <description>
1917               The array of owned monitors.
1918             </description>
1919         </param>
1920       </parameters>
1921       <errors>
1922       </errors>
1923     </function>
1924 
1925     <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
1926       <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
1927       <typedef id="jvmtiMonitorStackDepthInfo" 
1928                label="Monitor stack depth information structure">
1929         <field id="monitor">
1930           <jobject/>
1931             <description>
1932               The owned monitor.
1933             </description>
1934         </field>
1935         <field id="stack_depth">
1936           <jint/>
1937           <description>
1938             The stack depth.  Corresponds to the stack depth used in the 
1939             <internallink id="stack">Stack Frame functions</internallink>.
1940             That is, zero is the current frame, one is the frame which
1941             called the current frame. And it is negative one if the 
1942             implementation cannot determine the stack depth (e.g., for 
1943             monitors acquired by JNI <code>MonitorEnter</code>).
1944           </description>
1945         </field>
1946       </typedef>
1947       <description>
1948         Get information about the monitors owned by the 
1949         specified thread and the depth of the stack frame which locked them. 
1950       </description>
1951       <origin>new</origin>
1952       <capabilities>
1953         <required id="can_get_owned_monitor_stack_depth_info"></required>
1954       </capabilities>
1955       <parameters>
1956         <param id="thread">
1957           <jthread null="current"/>
1958             <description>
1959               The thread to query.
1960             </description>
1961         </param>
1962         <param id="monitor_info_count_ptr">
1963           <outptr><jint/></outptr>
1964           <description>
1965             The number of monitors returned.
1966           </description>
1967         </param>
1968         <param id="monitor_info_ptr">
1969           <allocbuf outcount="monitor_info_count_ptr">
1970             <struct>jvmtiMonitorStackDepthInfo</struct>
1971           </allocbuf>
1972           <description>
1973             The array of owned monitor depth information.
1974           </description>
1975         </param>
1976       </parameters>
1977       <errors>
1978       </errors>
1979     </function>
1980 
1981     <function id="GetCurrentContendedMonitor" num="11">
1982       <synopsis>Get Current Contended Monitor</synopsis>
1983       <description>
1984         Get the object, if any, whose monitor the specified thread is waiting to 
1985         enter or waiting to regain through <code>java.lang.Object.wait</code>.
1986       </description>
1987       <origin>jvmdi</origin>
1988       <capabilities>
1989         <required id="can_get_current_contended_monitor"></required>
1990       </capabilities>
1991       <parameters>
1992         <param id="thread">
1993           <jthread null="current"/>
1994             <description>
1995               The thread to query.
1996             </description>
1997         </param>
1998         <param id="monitor_ptr">
1999           <outptr><jobject/></outptr>
2000             <description>
2001               On return, filled with the current contended monitor, or
2002               NULL if there is none.
2003             </description>
2004         </param>
2005       </parameters>
2006       <errors>
2007       </errors>
2008     </function>
2009 
2010     <callback id="jvmtiStartFunction">
2011       <void/>
2012       <synopsis>Agent Start Function</synopsis>
2013       <description>
2014         Agent supplied callback function.
2015         This function is the entry point for an agent thread
2016         started with
2017         <functionlink id="RunAgentThread"></functionlink>.
2018       </description>
2019       <parameters>
2020           <param id="jvmti_env">
2021             <outptr>
2022               <struct>jvmtiEnv</struct>
2023             </outptr>
2024             <description>
2025               The <jvmti/> environment.
2026             </description>
2027           </param>
2028           <param id="jni_env">
2029             <outptr>
2030               <struct>JNIEnv</struct>
2031             </outptr>
2032             <description>
2033               The JNI environment.
2034             </description>
2035           </param>
2036           <param id="arg">
2037             <outptr>
2038               <void/>
2039             </outptr>
2040               <description>
2041                 The <code>arg</code> parameter passed to 
2042                 <functionlink id="RunAgentThread"></functionlink>.
2043               </description>
2044           </param>
2045       </parameters>
2046     </callback>
2047 
2048     <function id="RunAgentThread" num="12">
2049       <synopsis>Run Agent Thread</synopsis>
2050       <description>
2051         Starts the execution of an agent thread. with the specified native function.
2052         The parameter <paramlink id="arg"></paramlink> is forwarded on to the
2053         <functionlink id="jvmtiStartFunction">start function</functionlink>
2054         (specified with <paramlink id="proc"></paramlink>) as its single argument.
2055         This function allows the creation of agent threads 
2056         for handling communication with another process or for handling events 
2057         without the need to load a special subclass of <code>java.lang.Thread</code> or 
2058         implementer of <code>java.lang.Runnable</code>. 
2059         Instead, the created thread can run entirely in native code.
2060         However, the created thread does require a newly created instance
2061         of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to 
2062         which it will be associated.
2063         The thread object can be created with JNI calls.
2064         <p/>
2065         The following common thread priorities are provided for your convenience:
2066         <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
2067           <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
2068             Minimum possible thread priority
2069           </constant>
2070           <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
2071             Normal thread priority
2072           </constant>
2073           <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
2074             Maximum possible thread priority
2075           </constant>
2076         </constants>
2077         <p/>
2078         The new thread is started as a daemon thread with the specified
2079         <paramlink id="priority"></paramlink>.
2080         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2081         <p/>
2082         Since the thread has been started, the thread will be live when this function
2083         returns, unless the thread has died immediately.
2084         <p/>
2085         The thread group of the thread is ignored -- specifically, the thread is not
2086         added to the thread group and the thread is not seen on queries of the thread
2087         group at either the Java programming language or <jvmti/> levels.
2088         <p/>
2089         The thread is not visible to Java programming language queries but is 
2090         included in <jvmti/> queries (for example, 
2091         <functionlink id="GetAllThreads"/> and
2092         <functionlink id="GetAllStackTraces"/>).
2093         <p/>
2094         Upon execution of <code>proc</code>, the new thread will be attached to the
2095         VM--see the JNI documentation on 
2096         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/invocation.html#wp1060"
2097                       >Attaching to the VM</externallink>.
2098       </description>
2099       <origin>jvmdiClone</origin>
2100       <capabilities>
2101       </capabilities>
2102       <parameters>
2103         <param id="thread">
2104           <jthread impl="noconvert" started="no"/>
2105             <description>
2106               The thread to run.
2107             </description>
2108         </param>
2109         <param id="proc">
2110           <ptrtype>
2111             <struct>jvmtiStartFunction</struct>
2112           </ptrtype>
2113           <description>
2114             The start function.
2115           </description>
2116         </param>
2117         <param id="arg">
2118           <inbuf>
2119             <void/>
2120             <nullok><code>NULL</code> is passed to the start function</nullok>
2121           </inbuf>
2122           <description>
2123             The argument to the start function.
2124           </description>
2125         </param>
2126         <param id="priority">
2127           <jint/>
2128           <description>
2129             The priority of the started thread. Any thread
2130             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
2131             those in <datalink id="jvmtiThreadPriority"></datalink>.
2132           </description>
2133         </param>
2134       </parameters>
2135       <errors>
2136         <error id="JVMTI_ERROR_INVALID_PRIORITY"> 
2137             <paramlink id="priority"/> is less than 
2138             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
2139               or greater than
2140             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
2141         </error>
2142       </errors>
2143     </function>
2144 
2145     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
2146       <synopsis>Set Thread Local Storage</synopsis>
2147       <description>
2148         The VM stores a pointer value associated with each environment-thread
2149         pair. This pointer value is called <i>thread-local storage</i>.
2150         This value is <code>NULL</code> unless set with this function.
2151         Agents can allocate memory in which they store thread specific
2152         information. By setting thread-local storage it can then be
2153         accessed with 
2154         <functionlink id="GetThreadLocalStorage"></functionlink>.
2155         <p/>
2156         This function is called by the agent to set the value of the <jvmti/>
2157         thread-local storage. <jvmti/> supplies to the agent a pointer-size
2158         thread-local storage that can be used to record per-thread
2159         information.
2160       </description>
2161       <origin>jvmpi</origin>
2162       <capabilities>
2163       </capabilities>
2164       <parameters>
2165         <param id="thread">
2166           <jthread null="current"/>
2167             <description>
2168               Store to this thread.
2169             </description>
2170         </param>
2171         <param id="data">
2172           <inbuf> 
2173             <void/> 
2174             <nullok>value is set to <code>NULL</code></nullok> 
2175           </inbuf> 
2176           <description>
2177             The value to be entered into the thread-local storage.
2178           </description>
2179         </param>
2180       </parameters>
2181       <errors>
2182       </errors>
2183     </function>
2184 
2185     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
2186       <synopsis>Get Thread Local Storage</synopsis>
2187       <description>
2188         Called by the agent to get the value of the <jvmti/> thread-local
2189         storage. 
2190       </description>
2191       <origin>jvmpi</origin>
2192       <capabilities>
2193       </capabilities>
2194       <parameters>
2195         <param id="thread">
2196           <jthread null="current" impl="noconvert"/>
2197             <description>
2198               Retrieve from this thread.
2199             </description>
2200         </param>
2201         <param id="data_ptr">
2202           <agentbuf><void/></agentbuf>
2203           <description>
2204             Pointer through which the value of the thread local 
2205             storage is returned.
2206             If thread-local storage has not been set with
2207             <functionlink id="SetThreadLocalStorage"></functionlink> the returned 
2208             pointer is <code>NULL</code>.
2209           </description>
2210         </param>
2211       </parameters>
2212       <errors>
2213       </errors>
2214     </function>
2215 
2216   </category>
2217 
2218   <category id="thread_groups" label="Thread Group">
2219     <intro>
2220     </intro>
2221 
2222     <function id="GetTopThreadGroups" num="13">
2223       <synopsis>Get Top Thread Groups</synopsis>
2224       <description>
2225         Return all top-level (parentless) thread groups in the VM.
2226       </description>
2227       <origin>jvmdi</origin>
2228       <capabilities>
2229       </capabilities>
2230       <parameters>
2231         <param id="group_count_ptr">
2232           <outptr><jint/></outptr>
2233           <description>
2234             On return, points to the number of top-level thread groups.
2235           </description>
2236         </param>
2237         <param id="groups_ptr">
2238           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2239             <description>
2240               On return, refers to a pointer to the top-level thread group array.
2241             </description>
2242         </param>
2243       </parameters>
2244       <errors>
2245       </errors>
2246     </function>
2247 
2248     <function id="GetThreadGroupInfo" num="14">
2249       <synopsis>Get Thread Group Info</synopsis>
2250       <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
2251         <field id="parent">
2252           <jthreadGroup/>
2253           <description>
2254             The parent thread group.
2255           </description>
2256         </field>
2257         <field id="name">
2258           <allocfieldbuf><char/></allocfieldbuf>
2259           <description>
2260             The thread group's name, encoded as a
2261             <internallink id="mUTF">modified UTF-8</internallink> string.
2262           </description>
2263         </field>
2264         <field id="max_priority">
2265           <jint/>
2266           <description>
2267             The maximum priority for this thread group.
2268           </description>
2269         </field>
2270         <field id="is_daemon">
2271           <jboolean/>
2272           <description>
2273             Is this a daemon thread group?
2274           </description>
2275         </field>
2276       </typedef>
2277       <description>
2278         Get information about the thread group. The fields of the 
2279         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure 
2280         are filled in with details of the specified thread group.
2281       </description>
2282       <origin>jvmdi</origin>
2283       <capabilities>
2284       </capabilities>
2285       <parameters>
2286         <param id="group">
2287           <jthreadGroup/>
2288           <description>
2289             The thread group to query.
2290           </description>
2291         </param>
2292         <param id="info_ptr">
2293           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
2294           <description>
2295             On return, filled with information describing the specified
2296             thread group. 
2297           </description>
2298         </param>
2299       </parameters>
2300       <errors>
2301       </errors>
2302     </function>
2303 
2304     <function id="GetThreadGroupChildren" num="15">
2305       <synopsis>Get Thread Group Children</synopsis>
2306       <description>
2307         Get the live threads and active subgroups in this thread group.
2308       </description>
2309       <origin>jvmdi</origin>
2310       <capabilities>
2311       </capabilities>
2312       <parameters>
2313         <param id="group">
2314           <jthreadGroup/>
2315           <description>
2316             The group to query.
2317           </description>
2318         </param>
2319         <param id="thread_count_ptr">
2320           <outptr><jint/></outptr>
2321           <description>
2322             On return, points to the number of live threads in this thread group.
2323           </description>
2324         </param>
2325         <param id="threads_ptr">
2326           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
2327             <description>
2328               On return, points to an array of the live threads in this thread group.
2329             </description>
2330         </param>
2331         <param id="group_count_ptr">
2332           <outptr><jint/></outptr>
2333           <description>
2334             On return, points to the number of active child thread groups
2335           </description>
2336         </param>
2337         <param id="groups_ptr">
2338           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2339             <description>
2340               On return, points to an array of the active child thread groups.
2341             </description>
2342         </param>
2343       </parameters>
2344       <errors>
2345       </errors>
2346     </function>
2347   </category>
2348 
2349   <category id="stack" label="Stack Frame">
2350     <intro>
2351         These functions provide information about the stack of a thread.
2352         Stack frames are referenced by depth.
2353         The frame at depth zero is the current frame.
2354         <p/>
2355         Stack frames are as described in
2356         <vmspec chapter="3.6"/>,
2357         That is, they correspond to method 
2358         invocations (including native methods) but do not correspond to platform native or 
2359         VM internal frames.
2360         <p/>
2361         A <jvmti/> implementation may use method invocations to launch a thread and
2362         the corresponding frames may be included in the stack as presented by these functions --
2363         that is, there may be frames shown
2364         deeper than <code>main()</code> and <code>run()</code>.
2365         However this presentation must be consistent across all <jvmti/> functionality which 
2366         uses stack frames or stack depth.
2367     </intro>
2368 
2369       <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
2370         <description>
2371           Information about a stack frame is returned in this structure.
2372         </description>
2373         <field id="method">
2374           <jmethodID/>
2375             <description>
2376               The method executing in this frame.
2377             </description>
2378         </field>
2379         <field id="location">
2380           <jlocation/>
2381           <description>
2382             The index of the instruction executing in this frame.
2383             <code>-1</code> if the frame is executing a native method.
2384           </description>
2385         </field>
2386       </typedef>
2387 
2388       <typedef id="jvmtiStackInfo" label="Stack information structure">
2389         <description>
2390           Information about a set of stack frames is returned in this structure.
2391         </description>
2392         <field id="thread">
2393           <jthread/>
2394           <description>
2395             On return, the thread traced.
2396           </description>
2397         </field>
2398         <field id="state">
2399           <jint/>
2400           <description>
2401             On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
2402           </description>
2403         </field>
2404         <field id="frame_buffer">
2405           <outbuf incount="max_frame_count">
2406             <struct>jvmtiFrameInfo</struct>
2407           </outbuf>
2408             <description>
2409               On return, this agent allocated buffer is filled 
2410               with stack frame information.  
2411             </description>
2412         </field>
2413         <field id="frame_count">
2414           <jint/>
2415           <description>
2416             On return, the number of records filled into 
2417             <code>frame_buffer</code>.
2418             This will be 
2419             min(<code>max_frame_count</code>, <i>stackDepth</i>).
2420           </description>
2421         </field>
2422       </typedef>
2423 
2424     <function id="GetStackTrace" num="104">
2425       <synopsis>Get Stack Trace</synopsis>
2426       <description>
2427         Get information about the stack of a thread.
2428         If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
2429         the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, 
2430         otherwise the entire stack is returned.
2431         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2432         <p/>
2433         The following example causes up to five of the topmost frames
2434         to be returned and (if there are any frames) the currently
2435         executing method name to be printed.
2436         <example>
2437 jvmtiFrameInfo frames[5];
2438 jint count;
2439 jvmtiError err;
2440 
2441 err = (*jvmti)-&gt;GetStackTrace(jvmti, aThread, 0, 5, 
2442                                frames, &amp;count);
2443 if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
2444    char *methodName;
2445    err = (*jvmti)-&gt;GetMethodName(jvmti, frames[0].method, 
2446                        &amp;methodName, NULL, NULL);
2447    if (err == JVMTI_ERROR_NONE) {
2448       printf("Executing method: %s", methodName);
2449    }
2450 }
2451         </example>
2452         <todo> 
2453           check example code.
2454         </todo>
2455         <p/>
2456         The <paramlink id="thread"></paramlink> need not be suspended
2457         to call this function.  
2458         <p/>
2459         The <functionlink id="GetLineNumberTable"></functionlink>
2460         function can be used to map locations to line numbers. Note that
2461         this mapping can be done lazily.
2462       </description>
2463       <origin>jvmpi</origin>
2464       <capabilities>
2465       </capabilities>
2466       <parameters>
2467         <param id="thread">
2468           <jthread null="current"/>
2469             <description>
2470               Fetch the stack trace of this thread.
2471             </description>
2472         </param>
2473         <param id="start_depth">
2474           <jint/>
2475           <description>
2476             Begin retrieving frames at this depth.  
2477             If non-negative, count from the current frame, 
2478             the first frame retrieved is at depth <code>start_depth</code>.  
2479             For example, if zero, start from the current frame; if one, start from the
2480             caller of the current frame; if two, start from the caller of the
2481             caller of the current frame; and so on.
2482             If negative, count from below the oldest frame,
2483             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,  
2484             where <i>stackDepth</i> is the count of frames on the stack.  
2485             For example, if negative one, only the oldest frame is retrieved;
2486             if negative two, start from the frame called by the oldest frame.
2487           </description>
2488         </param>
2489         <param id="max_frame_count">
2490           <jint min="0"/>
2491           <description>
2492             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2493           </description>
2494         </param>
2495         <param id="frame_buffer">
2496           <outbuf incount="max_frame_count" outcount="count_ptr">
2497             <struct>jvmtiFrameInfo</struct>
2498           </outbuf>
2499             <description>
2500               On return, this agent allocated buffer is filled 
2501               with stack frame information.  
2502             </description>
2503         </param>
2504         <param id="count_ptr">
2505           <outptr><jint/></outptr>
2506           <description>
2507             On return, points to the number of records filled in.
2508             For non-negative <code>start_depth</code>, this will be 
2509             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
2510             For negative <code>start_depth</code>, this will be 
2511             min(<code>max_frame_count</code>, <code>-start_depth</code>).
2512           </description>
2513         </param>
2514       </parameters>
2515       <errors>
2516         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
2517           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
2518           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
2519         </error>
2520       </errors>
2521     </function>
2522 
2523 
2524     <function id="GetAllStackTraces" num="100">
2525       <synopsis>Get All Stack Traces</synopsis>
2526       <description>
2527         Get information about the stacks of all live threads
2528         (including <internallink id="RunAgentThread">agent threads</internallink>).
2529         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2530         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 
2531         otherwise the entire stack is returned.
2532         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2533         <p/>
2534         All stacks are collected simultaneously, that is, no changes will occur to the 
2535         thread state or stacks between the sampling of one thread and the next.
2536         The threads need not be suspended.
2537         
2538         <example>
2539 jvmtiStackInfo *stack_info;
2540 jint thread_count;
2541 int ti;
2542 jvmtiError err;
2543 
2544 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count); 
2545 if (err != JVMTI_ERROR_NONE) {
2546    ...   
2547 }
2548 for (ti = 0; ti &lt; thread_count; ++ti) {
2549    jvmtiStackInfo *infop = &amp;stack_info[ti];
2550    jthread thread = infop-&gt;thread;
2551    jint state = infop-&gt;state;
2552    jvmtiFrameInfo *frames = infop-&gt;frame_buffer;
2553    int fi;
2554 
2555    myThreadAndStatePrinter(thread, state);
2556    for (fi = 0; fi &lt; infop-&gt;frame_count; fi++) {
2557       myFramePrinter(frames[fi].method, frames[fi].location);
2558    }
2559 }
2560 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
2561 err = (*jvmti)-&gt;Deallocate(jvmti, stack_info); 
2562         </example>
2563         <todo> 
2564           check example code.
2565         </todo>
2566 
2567       </description>
2568       <origin>new</origin>
2569       <capabilities>
2570       </capabilities>
2571       <parameters>
2572         <param id="max_frame_count">
2573           <jint min="0"/>
2574           <description>
2575             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2576           </description>
2577         </param>
2578         <param id="stack_info_ptr">
2579           <allocbuf>
2580             <struct>jvmtiStackInfo</struct>
2581           </allocbuf>
2582             <description>
2583               On return, this buffer is filled 
2584               with stack information for each thread.  
2585               The number of <datalink id="jvmtiStackInfo"/> records is determined 
2586               by <paramlink id="thread_count_ptr"/>.
2587               <p/>
2588               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 
2589               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2590               These buffers must not be separately deallocated.
2591             </description>
2592         </param>
2593         <param id="thread_count_ptr">
2594           <outptr><jint/></outptr>
2595           <description>
2596             The number of threads traced.
2597           </description>
2598         </param>
2599       </parameters>
2600       <errors>
2601       </errors>
2602     </function>
2603 
2604     <function id="GetThreadListStackTraces" num="101">
2605       <synopsis>Get Thread List Stack Traces</synopsis>
2606       <description>
2607         Get information about the stacks of the supplied threads.
2608         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2609         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 
2610         otherwise the entire stack is returned.
2611         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2612         <p/>
2613         All stacks are collected simultaneously, that is, no changes will occur to the 
2614         thread state or stacks between the sampling one thread and the next.
2615         The threads need not be suspended.
2616         <p/>
2617         If a thread has not yet started or terminates before the stack information is collected,
2618         a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
2619         will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
2620         <p/>
2621         See the example for the similar function
2622         <functionlink id="GetAllStackTraces"/>.
2623       </description>
2624       <origin>new</origin>
2625       <capabilities>
2626       </capabilities>
2627       <parameters>
2628         <param id="thread_count">
2629           <jint min="0"/>
2630           <description>
2631             The number of threads to trace.
2632           </description>
2633         </param>
2634         <param id="thread_list">
2635           <inbuf incount="thread_count"><jthread/></inbuf>
2636             <description>
2637               The list of threads to trace.
2638             </description>
2639         </param>
2640         <param id="max_frame_count">
2641           <jint min="0"/>
2642           <description>
2643             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2644           </description>
2645         </param>
2646         <param id="stack_info_ptr">
2647           <allocbuf outcount="thread_count">
2648             <struct>jvmtiStackInfo</struct>
2649           </allocbuf>
2650             <description>
2651               On return, this buffer is filled 
2652               with stack information for each thread.  
2653               The number of <datalink id="jvmtiStackInfo"/> records is determined 
2654               by <paramlink id="thread_count"/>.
2655               <p/>
2656               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 
2657               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2658               These buffers must not be separately deallocated.
2659             </description>
2660         </param>
2661       </parameters>
2662       <errors>
2663         <error id="JVMTI_ERROR_INVALID_THREAD">
2664           An element in <paramlink id="thread_list"/> is not a thread object.
2665         </error>
2666       </errors>
2667     </function>
2668 
2669     <elide>
2670     <function id="AsyncGetStackTrace" num="1000">
2671       <synopsis>Get Stack Trace--Asynchronous</synopsis>
2672       <description>
2673         Get information about the entire stack of a thread (or a sub-section of it).
2674         This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
2675         and is reentrant and safe to call
2676         from asynchronous signal handlers.
2677         The stack trace is returned only for the calling thread.
2678         <p/>
2679         The <functionlink id="GetLineNumberTable"></functionlink>
2680         function can be used to map locations to line numbers. Note that
2681         this mapping can be done lazily.
2682       </description>
2683       <origin>jvmpi</origin>
2684       <capabilities>
2685         <required id="can_get_async_stack_trace"></required>
2686         <capability id="can_show_JVM_spec_async_frames">
2687           If <code>false</code>, 
2688           <paramlink id="use_java_stack"></paramlink> 
2689           must be <code>false</code>.
2690         </capability>
2691       </capabilities>
2692       <parameters>
2693         <param id="use_java_stack">
2694           <jboolean/>
2695           <description>
2696             Return the stack showing <vmspec/>
2697             model of the stack; 
2698             otherwise, show the internal representation of the stack with
2699             inlined and optimized methods missing.  If the virtual machine
2700             is using the <i>Java Virtual Machine Specification</i> stack model
2701             internally, this flag is ignored.
2702           </description>
2703         </param>
2704         <param id="max_count">
2705           <jint min="0"/>
2706           <description>
2707             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2708             Retrieve this many unless the stack depth is less than <code>max_count</code>.
2709           </description>
2710         </param>
2711         <param id="frame_buffer">
2712           <outbuf incount="max_count" outcount="count_ptr">
2713             <struct>jvmtiFrameInfo</struct>
2714             <nullok>this information is not returned</nullok>
2715           </outbuf>
2716             <description>
2717               The agent passes in a buffer
2718               large enough to hold <code>max_count</code> records of 
2719               <datalink id="jvmtiFrameInfo"></datalink>.  This buffer must be
2720               pre-allocated by the agent.  
2721             </description>
2722         </param>
2723         <param id="count_ptr">
2724           <outptr><jint/></outptr>
2725           <description>
2726             On return, points to the number of records filled in..
2727           </description>
2728         </param>
2729       </parameters>
2730       <errors>
2731         <error id="JVMTI_ERROR_UNATTACHED_THREAD">
2732           The thread being used to call this function is not attached
2733           to the virtual machine.  Calls must be made from attached threads.
2734         </error>
2735       </errors>
2736     </function>
2737     </elide>
2738 
2739     <function id="GetFrameCount" num="16">
2740       <synopsis>Get Frame Count</synopsis>
2741       <description>
2742         Get the number of frames currently in the specified thread's call stack.
2743         <p/>
2744         If this function is called for a thread actively executing bytecodes (for example,
2745         not the current thread and not suspended), the information returned is transient.
2746       </description>
2747       <origin>jvmdi</origin>
2748       <capabilities>
2749       </capabilities>
2750       <parameters>
2751         <param id="thread">
2752           <jthread null="current"/>
2753             <description>
2754               The thread to query.
2755             </description>
2756         </param>
2757         <param id="count_ptr">
2758           <outptr><jint/></outptr>
2759           <description>
2760             On return, points to the number of frames in the call stack.
2761           </description>
2762         </param>
2763       </parameters>
2764       <errors>
2765       </errors>
2766     </function>
2767 
2768     <function id="PopFrame" num="80">
2769       <synopsis>Pop Frame</synopsis>
2770       <description>
2771         Pop the current frame of <code>thread</code>'s stack.
2772         Popping a frame takes you to the previous frame.  
2773         When the thread is resumed, the execution 
2774         state of the thread is reset to the state
2775         immediately before the called method was invoked.
2776         That is (using <vmspec/> terminology):
2777           <ul>
2778             <li>the current frame is discarded as the previous frame becomes the current one</li>
2779             <li>the operand stack is restored--the argument values are added back
2780               and if the invoke was not <code>invokestatic</code>, 
2781               <code>objectref</code> is added back as well</li>
2782             <li>the Java virtual machine PC is restored to the opcode
2783               of the invoke instruction</li>
2784           </ul>
2785         Note however, that any changes to the arguments, which
2786         occurred in the called method, remain; 
2787         when execution continues, the first instruction to 
2788         execute will be the invoke.  
2789         <p/>
2790         Between calling <code>PopFrame</code> and resuming the 
2791         thread the state of the stack is undefined.  
2792         To pop frames beyond the first, 
2793         these three steps must be repeated:
2794         <ul>
2795           <li>suspend the thread via an event (step, breakpoint, ...)</li>
2796           <li>call <code>PopFrame</code></li>
2797           <li>resume the thread</li>
2798         </ul>
2799         <p/>
2800         A lock acquired by calling the called method 
2801         (if it is a <code>synchronized</code>  method) 
2802         and locks acquired by entering <code>synchronized</code>
2803         blocks within the called method are released. 
2804         Note: this does not apply to native locks or 
2805         <code>java.util.concurrent.locks</code> locks.
2806         <p/>
2807         Finally blocks are not executed.
2808         <p/>
2809         Changes to global state are not addressed and thus remain changed.
2810         <p/>
2811         The specified thread must be suspended (which implies it cannot be the current thread).
2812         <p/>
2813         Both the called method and calling method must be non-native Java programming 
2814         language methods.
2815         <p/>
2816         No <jvmti/> events are generated by this function.
2817       </description>
2818       <origin>jvmdi</origin>
2819       <capabilities>
2820         <required id="can_pop_frame"></required>
2821       </capabilities>
2822       <parameters>
2823         <param id="thread">
2824           <jthread/>
2825             <description>
2826               The thread whose current frame is to be popped.
2827             </description>
2828         </param>
2829       </parameters>
2830       <errors>
2831         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2832           Called or calling method is a native method.
2833           The implementation is unable to pop this frame.
2834         </error>
2835         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2836           Thread was not suspended.
2837         </error>
2838         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2839           There are less than two stack frames on the call stack.
2840         </error>
2841       </errors>
2842     </function>
2843 
2844     <function id="GetFrameLocation" num="19">
2845       <synopsis>Get Frame Location</synopsis>
2846       <description>
2847         <p/>
2848         For a Java programming language frame, return the location of the instruction
2849         currently executing.
2850       </description>
2851       <origin>jvmdiClone</origin>
2852       <capabilities>
2853       </capabilities>
2854       <parameters>
2855         <param id="thread">
2856           <jthread null="current" frame="frame"/>
2857           <description>
2858             The thread of the frame to query.
2859           </description>
2860         </param>
2861         <param id="depth">
2862           <jframeID thread="thread"/>
2863           <description>
2864             The depth of the frame to query.
2865           </description>
2866         </param>
2867         <param id="method_ptr">
2868           <outptr><jmethodID/></outptr>
2869             <description>
2870               On return, points to the method for the current location.
2871             </description>
2872         </param>
2873         <param id="location_ptr">
2874           <outptr><jlocation/></outptr>
2875           <description>
2876             On return, points to the index of the currently 
2877             executing instruction.
2878             Is set to <code>-1</code> if the frame is executing
2879             a native method.
2880           </description>
2881         </param>
2882       </parameters>
2883       <errors>
2884       </errors>
2885     </function>
2886 
2887     <function id="NotifyFramePop" num="20">
2888       <synopsis>Notify Frame Pop</synopsis>
2889       <description>
2890         When the frame that is currently at <paramlink id="depth"></paramlink> 
2891         is popped from the stack, generate a
2892         <eventlink id="FramePop"></eventlink> event.  See the 
2893         <eventlink id="FramePop"></eventlink> event for details.
2894         Only frames corresponding to non-native Java programming language 
2895         methods can receive notification.
2896         <p/>
2897         The specified thread must either be the current thread
2898         or the thread must be suspended.
2899       </description>
2900       <origin>jvmdi</origin>
2901       <capabilities>
2902         <required id="can_generate_frame_pop_events"></required>
2903       </capabilities>
2904       <parameters>
2905         <param id="thread">
2906           <jthread null="current" frame="depth"/>   
2907           <description>
2908             The thread of the frame for which the frame pop event will be generated.
2909           </description>
2910         </param>
2911         <param id="depth">
2912           <jframeID thread="thread"/>
2913           <description>
2914             The depth of the frame for which the frame pop event will be generated.
2915           </description>
2916         </param>
2917       </parameters>
2918       <errors>
2919         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
2920           The frame at <code>depth</code> is executing a
2921           native method.
2922         </error>
2923         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2924           Thread was not suspended and was not the current thread.
2925         </error>
2926       </errors>
2927     </function>
2928 
2929   </category>
2930 
2931   <category id="ForceEarlyReturn" label="Force Early Return">
2932     <intro>
2933       These functions allow an agent to force a method
2934       to return at any point during its execution.
2935       The method which will return early is referred to as the <i>called method</i>.
2936       The called method is the current method
2937       (as defined by
2938       <vmspec chapter="3.6"/>) 
2939       for the specified thread at
2940       the time the function is called.
2941       <p/>
2942       The specified thread must be suspended or must be the current thread.
2943       The return occurs when execution of Java programming
2944       language code is resumed on this thread.
2945       Between calling one of these functions and resumption
2946       of thread execution, the state of the stack is undefined.  
2947       <p/>
2948       No further instructions are executed in the called method.  
2949       Specifically, finally blocks are not executed.
2950       Note: this can cause inconsistent states in the application.
2951       <p/>
2952       A lock acquired by calling the called method 
2953       (if it is a <code>synchronized</code>  method) 
2954       and locks acquired by entering <code>synchronized</code>
2955       blocks within the called method are released. 
2956       Note: this does not apply to native locks or 
2957       <code>java.util.concurrent.locks</code> locks.
2958       <p/>
2959       Events, such as <eventlink id="MethodExit"></eventlink>,
2960       are generated as they would be in a normal return.
2961       <p/>
2962       The called method must be a non-native Java programming
2963       language method.
2964       Forcing return on a thread with only one frame on the
2965       stack causes the thread to exit when resumed.
2966     </intro>
2967 
2968     <function id="ForceEarlyReturnObject" num="81" since="1.1">
2969       <synopsis>Force Early Return - Object</synopsis>
2970       <description>
2971         This function can be used to return from a method whose
2972         result type is <code>Object</code>
2973         or a subclass of <code>Object</code>. 
2974       </description>
2975       <origin>new</origin>
2976       <capabilities>
2977         <required id="can_force_early_return"></required>
2978       </capabilities>
2979       <parameters>
2980         <param id="thread">
2981           <jthread null="current"/>
2982           <description>
2983             The thread whose current frame is to return early.
2984           </description>
2985         </param>
2986         <param id="value">
2987           <jobject/>
2988           <description>
2989             The return value for the called frame. 
2990             An object or <code>NULL</code>.
2991           </description>
2992         </param>
2993       </parameters>
2994       <errors>
2995         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2996           Attempted to return early from a frame
2997           corresponding to a native method.
2998           Or the implementation is unable to provide
2999           this functionality on this frame.
3000         </error>
3001         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3002           The result type of the called method is not 
3003           <code>Object</code> or a subclass of <code>Object</code>.
3004         </error>
3005         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3006           The supplied <paramlink id="value"/> is not compatible with the 
3007           result type of the called method.
3008         </error>
3009         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3010           Thread was not the current thread and was not suspended.
3011         </error>
3012         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3013           There are no more frames on the call stack.
3014         </error>
3015       </errors>
3016     </function>
3017 
3018     <function id="ForceEarlyReturnInt" num="82" since="1.1">
3019       <synopsis>Force Early Return - Int</synopsis>
3020       <description>
3021         This function can be used to return from a method whose
3022         result type is <code>int</code>, <code>short</code>,
3023         <code>char</code>, <code>byte</code>, or 
3024         <code>boolean</code>. 
3025       </description>
3026       <origin>new</origin>
3027       <capabilities>
3028         <required id="can_force_early_return"></required>
3029       </capabilities>
3030       <parameters>
3031         <param id="thread">
3032           <jthread null="current"/>
3033           <description>
3034             The thread whose current frame is to return early.
3035           </description>
3036         </param>
3037         <param id="value">
3038           <jint/>
3039           <description>
3040             The return value for the called frame.
3041           </description>
3042         </param>
3043       </parameters>
3044       <errors>
3045         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3046           Attempted to return early from a frame
3047           corresponding to a native method.
3048           Or the implementation is unable to provide
3049           this functionality on this frame.
3050         </error>
3051         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3052           The result type of the called method is not 
3053           <code>int</code>, <code>short</code>,
3054           <code>char</code>, <code>byte</code>, or 
3055           <code>boolean</code>.
3056         </error>
3057         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3058           Thread was not the current thread and was not suspended.
3059         </error>
3060         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3061           There are no frames on the call stack.
3062         </error>
3063       </errors>
3064     </function>
3065 
3066     <function id="ForceEarlyReturnLong" num="83" since="1.1">
3067       <synopsis>Force Early Return - Long</synopsis>
3068       <description>
3069         This function can be used to return from a method whose
3070         result type is <code>long</code>.
3071       </description>
3072       <origin>new</origin>
3073       <capabilities>
3074         <required id="can_force_early_return"></required>
3075       </capabilities>
3076       <parameters>
3077         <param id="thread">
3078           <jthread null="current"/>
3079           <description>
3080             The thread whose current frame is to return early.
3081           </description>
3082         </param>
3083         <param id="value">
3084           <jlong/>
3085           <description>
3086             The return value for the called frame.
3087           </description>
3088         </param>
3089       </parameters>
3090       <errors>
3091         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3092           Attempted to return early from a frame
3093           corresponding to a native method.
3094           Or the implementation is unable to provide
3095           this functionality on this frame.
3096         </error>
3097         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3098           The result type of the called method is not <code>long</code>.
3099         </error>
3100         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3101           Thread was not the current thread and was not suspended.
3102         </error>
3103         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3104           There are no frames on the call stack.
3105         </error>
3106       </errors>
3107     </function>
3108 
3109     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
3110       <synopsis>Force Early Return - Float</synopsis>
3111       <description>
3112         This function can be used to return from a method whose
3113         result type is <code>float</code>.
3114       </description>
3115       <origin>new</origin>
3116       <capabilities>
3117         <required id="can_force_early_return"></required>
3118       </capabilities>
3119       <parameters>
3120         <param id="thread">
3121           <jthread null="current"/>
3122           <description>
3123             The thread whose current frame is to return early.
3124           </description>
3125         </param>
3126         <param id="value">
3127           <jfloat/>
3128           <description>
3129             The return value for the called frame.
3130           </description>
3131         </param>
3132       </parameters>
3133       <errors>
3134         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3135           Attempted to return early from a frame
3136           corresponding to a native method.
3137           Or the implementation is unable to provide
3138           this functionality on this frame.
3139         </error>
3140         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3141           The result type of the called method is not <code>float</code>.
3142         </error>
3143         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3144           Thread was not the current thread and was not suspended.
3145         </error>
3146         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3147           There are no frames on the call stack.
3148         </error>
3149       </errors>
3150     </function>
3151 
3152     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
3153       <synopsis>Force Early Return - Double</synopsis>
3154       <description>
3155         This function can be used to return from a method whose
3156         result type is <code>double</code>.
3157       </description>
3158       <origin>new</origin>
3159       <capabilities>
3160         <required id="can_force_early_return"></required>
3161       </capabilities>
3162       <parameters>
3163         <param id="thread">
3164           <jthread null="current"/>
3165           <description>
3166             The thread whose current frame is to return early.
3167           </description>
3168         </param>
3169         <param id="value">
3170           <jdouble/>
3171           <description>
3172             The return value for the called frame.
3173           </description>
3174         </param>
3175       </parameters>
3176       <errors>
3177         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3178           Attempted to return early from a frame corresponding to a native method.
3179           Or the implementation is unable to provide this functionality on this frame.
3180         </error>
3181         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3182           The result type of the called method is not <code>double</code>.
3183         </error>
3184         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3185           Thread was not the current thread and was not suspended.
3186         </error>
3187         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3188           There are no frames on the call stack.
3189         </error>
3190       </errors>
3191     </function>
3192 
3193     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3194       <synopsis>Force Early Return - Void</synopsis>
3195       <description>
3196         This function can be used to return from a method with no result type.
3197         That is, the called method must be declared <code>void</code>.
3198       </description>
3199       <origin>new</origin>
3200       <capabilities>
3201         <required id="can_force_early_return"></required>
3202       </capabilities>
3203       <parameters>
3204         <param id="thread">
3205           <jthread null="current"/>
3206           <description>
3207             The thread whose current frame is to return early.
3208           </description>
3209         </param>
3210       </parameters>
3211       <errors>
3212         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3213           Attempted to return early from a frame
3214           corresponding to a native method.
3215           Or the implementation is unable to provide
3216           this functionality on this frame.
3217         </error>
3218         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
3219           The called method has a result type.  
3220         </error>
3221         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3222           Thread was not the current thread and was not suspended.
3223         </error>
3224         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3225           There are no frames on the call stack.
3226         </error>
3227       </errors>
3228     </function>
3229 
3230   </category>
3231 
3232   <category id="Heap" label="Heap">
3233     <intro>
3234       These functions are used to analyze the heap.
3235       Functionality includes the ability to view the objects in the
3236       heap and to tag these objects.
3237     </intro>
3238    
3239     <intro id="objectTags" label="Object Tags">
3240       A <i>tag</i> is a value associated with an object.
3241       Tags are explicitly set by the agent using the
3242       <functionlink id="SetTag"></functionlink> function or by
3243       callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.    
3244       <p/>
3245       Tags are local to the environment; that is, the tags of one
3246       environment are not visible in another.
3247       <p/>
3248       Tags are <code>jlong</code> values which can be used
3249       simply to mark an object or to store a pointer to more detailed
3250       information.  Objects which have not been tagged have a
3251       tag of zero.  
3252       Setting a tag to zero makes the object untagged.
3253     </intro>
3254    
3255     <intro id="heapCallbacks" label="Heap Callback Functions">
3256         Heap functions which iterate through the heap and recursively
3257         follow object references use agent supplied callback functions
3258         to deliver the information.
3259         <p/>
3260         These heap callback functions must adhere to the following restrictions --
3261         These callbacks must not use JNI functions.
3262         These callbacks must not use <jvmti/> functions except 
3263         <i>callback safe</i> functions which
3264         specifically allow such use (see the raw monitor, memory management,
3265         and environment local storage functions).
3266         <p/>
3267         An implementation may invoke a callback on an internal thread or
3268         the thread which called the iteration function.
3269         Heap callbacks are single threaded -- no more than one callback will
3270         be invoked at a time.
3271         <p/>
3272         The Heap Filter Flags can be used to prevent reporting
3273         based on the tag status of an object or its class.  
3274         If no flags are set (the <code>jint</code> is zero), objects
3275         will not be filtered out.
3276 
3277         <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
3278           <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
3279             Filter out tagged objects. Objects which are tagged are not included.
3280           </constant>
3281           <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
3282             Filter out untagged objects. Objects which are not tagged are not included.
3283           </constant>
3284           <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
3285             Filter out objects with tagged classes. Objects whose class is tagged are not included.
3286           </constant>
3287           <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
3288             Filter out objects with untagged classes. Objects whose class is not tagged are not included.
3289           </constant>
3290         </constants>
3291 
3292         <p/>
3293         The Heap Visit Control Flags are returned by the heap callbacks
3294         and can be used to abort the iteration.  For the 
3295         <functionlink id="jvmtiHeapReferenceCallback">Heap 
3296         Reference Callback</functionlink>, it can also be used 
3297         to prune the graph of traversed references
3298         (<code>JVMTI_VISIT_OBJECTS</code> is not set).
3299 
3300         <constants id="jvmtiHeapVisitControl" 
3301                    label="Heap Visit Control Flags" 
3302                    kind="bits" 
3303                    since="1.1">
3304           <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
3305             If we are visiting an object and if this callback
3306             was initiated by <functionlink id="FollowReferences"/>, 
3307             traverse the references of this object.
3308             Otherwise ignored.
3309           </constant>       
3310           <constant id="JVMTI_VISIT_ABORT" num="0x8000">
3311             Abort the iteration.  Ignore all other bits.
3312           </constant>
3313         </constants>
3314 
3315         <p/>
3316         The Heap Reference Enumeration is provided by the 
3317         <functionlink id="jvmtiHeapReferenceCallback">Heap 
3318         Reference Callback</functionlink> and 
3319         <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field 
3320         Callback</functionlink> to 
3321         describe the kind of reference
3322         being reported.
3323 
3324         <constants id="jvmtiHeapReferenceKind" 
3325                    label="Heap Reference Enumeration" 
3326                    kind="enum" 
3327                    since="1.1">
3328           <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
3329             Reference from an object to its class.
3330           </constant>       
3331           <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
3332             Reference from an object to the value of one of its instance fields.
3333           </constant>
3334           <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
3335             Reference from an array to one of its elements.
3336           </constant>
3337           <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
3338             Reference from a class to its class loader.
3339           </constant>
3340           <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
3341             Reference from a class to its signers array.
3342           </constant>
3343           <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
3344             Reference from a class to its protection domain.
3345           </constant>       
3346           <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
3347             Reference from a class to one of its interfaces. 
3348             Note: interfaces are defined via a constant pool reference,
3349             so the referenced interfaces may also be reported with a 
3350             <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3351           </constant>
3352           <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
3353             Reference from a class to the value of one of its static fields.
3354           </constant>
3355           <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
3356             Reference from a class to a resolved entry in the constant pool.
3357           </constant>
3358           <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
3359             Reference from a class to its superclass. 
3360             A callback is bot sent if the superclass is <code>java.lang.Object</code>.
3361             Note: loaded classes define superclasses via a constant pool
3362             reference, so the referenced superclass may also be reported with 
3363             a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3364           </constant>
3365           <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
3366             Heap root reference: JNI global reference.
3367           </constant>
3368           <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
3369             Heap root reference: System class.
3370           </constant>
3371           <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
3372             Heap root reference: monitor.
3373           </constant>
3374           <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
3375             Heap root reference: local variable on the stack.
3376           </constant>
3377           <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
3378             Heap root reference: JNI local reference.
3379           </constant>
3380           <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
3381             Heap root reference: Thread.
3382           </constant>
3383           <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
3384             Heap root reference: other heap root reference.
3385           </constant>
3386         </constants>
3387 
3388         <p/>
3389         Definitions for the single character type descriptors of
3390         primitive types.
3391 
3392         <constants id="jvmtiPrimitiveType" 
3393                    label="Primitive Type Enumeration" 
3394                    kind="enum" 
3395                    since="1.1">
3396           <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
3397             'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
3398           </constant>       
3399           <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
3400             'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
3401           </constant>       
3402           <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
3403             'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
3404           </constant>       
3405           <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
3406             'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
3407           </constant>       
3408           <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
3409             'I' - Java programming language <code>int</code> - JNI <code>jint</code>
3410           </constant>       
3411           <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
3412             'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
3413           </constant>       
3414           <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
3415             'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
3416           </constant>       
3417           <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
3418             'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
3419           </constant>       
3420         </constants>
3421     </intro>
3422 
3423       <typedef id="jvmtiHeapReferenceInfoField" 
3424                label="Reference information structure for Field references" 
3425                since="1.1">
3426         <description>
3427           Reference information returned for 
3428           <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and 
3429           <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3430         </description>
3431         <field id="index">
3432           <jint/>
3433           <description>       
3434             For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the 
3435             referrer object is not a class or an inteface.  
3436             In this case, <code>index</code> is the index of the field 
3437             in the class of the referrer object.  
3438             This class is referred to below as <i>C</i>.
3439             <p/>
3440             For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
3441             the referrer object is a class (referred to below as <i>C</i>)
3442             or an interface (referred to below as <i>I</i>).
3443             In this case, <code>index</code> is the index of the field in 
3444             that class or interface.
3445             <p/>
3446             If the referrer object is not an interface, then the field 
3447             indices are determined as follows: 
3448             <ul>
3449               <li>make a list of all the fields in <i>C</i> and its
3450                   superclasses, starting with all the fields in 
3451                   <code>java.lang.Object</code> and ending with all the
3452                   fields in <i>C</i>.</li>
3453               <li>Within this list, put 
3454                   the fields for a given class in the order returned by
3455                   <functionlink id="GetClassFields"/>.</li>
3456               <li>Assign the fields in this list indices 
3457                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i> 
3458                   is the count of the fields in all the interfaces
3459                   implemented by <i>C</i>. 
3460                   Note that <i>C</i> implements all interfaces 
3461                   directly implemented by its superclasses; as well
3462                   as all superinterfaces of these interfaces.</li>
3463             </ul>
3464             If the referrer object is an interface, then the field 
3465             indices are determined as follows:
3466             <ul>
3467               <li>make a list of the fields directly declared in 
3468                   <i>I</i>.</li>
3469               <li>Within this list, put 
3470                   the fields 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 superinterfaces
3475                   of <i>I</i>.</li>
3476             </ul>
3477             All fields are included in this computation, regardless of
3478             field modifier (static, public, private, etc).
3479             <p/>
3480             For example, given the following classes and interfaces:
3481             <example>
3482 interface I0 {
3483     int p = 0;
3484 }
3485 
3486 interface I1 extends I0 {
3487     int x = 1;
3488 }
3489 
3490 interface I2 extends I0 {
3491     int y = 2;
3492 }
3493 
3494 class C1 implements I1 {
3495     public static int a = 3;
3496     private int b = 4;
3497 }
3498 
3499 class C2 extends C1 implements I2 {
3500     static int q = 5;
3501     final int r = 6;
3502 }
3503             </example>
3504             Assume that <functionlink id="GetClassFields"/> called on
3505             <code>C1</code> returns the fields of <code>C1</code> in the
3506             order: a, b; and that the fields of <code>C2</code> are 
3507             returned in the order: q, r.
3508             An instance of class <code>C1</code> will have the
3509             following field indices:
3510             <dl><dd><table>
3511               <tr>
3512                 <td>
3513                   a
3514                 </td>
3515                 <td>
3516                   2
3517                 </td>
3518                 <td align="left">
3519                   The count of the fields in the interfaces
3520                   implemented by <code>C1</code> is two (<i>n</i>=2):
3521                   <code>p</code> of <code>I0</code>
3522                   and <code>x</code> of <code>I1</code>.
3523                 </td>
3524               </tr>
3525               <tr>
3526                 <td>
3527                   b
3528                 </td>
3529                 <td>
3530                   3
3531                 </td>
3532                 <td align="left">
3533                   the subsequent index.
3534                 </td>
3535               </tr>
3536             </table></dd></dl>
3537             The class <code>C1</code> will have the same field indices.
3538             <p/>
3539             An instance of class <code>C2</code> will have the
3540             following field indices:
3541             <dl><dd><table>
3542               <tr>
3543                 <td>
3544                   a
3545                 </td>
3546                 <td>
3547                   3
3548                 </td>
3549                 <td align="left">
3550                   The count of the fields in the interfaces
3551                   implemented by <code>C2</code> is three (<i>n</i>=3):
3552                   <code>p</code> of <code>I0</code>,
3553                   <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code> 
3554                   (an interface of <code>C2</code>).  Note that the field <code>p</code>
3555                   of <code>I0</code> is only included once.
3556                 </td>
3557               </tr>
3558               <tr>
3559                 <td>
3560                   b
3561                 </td>
3562                 <td>
3563                   4
3564                 </td>
3565                 <td align="left">
3566                   the subsequent index to "a".
3567                 </td>
3568               </tr>
3569               <tr>
3570                 <td>
3571                   q
3572                 </td>
3573                 <td>
3574                   5
3575                 </td>
3576                 <td align="left">
3577                   the subsequent index to "b".
3578                 </td>
3579               </tr>
3580               <tr>
3581                 <td>
3582                   r
3583                 </td>
3584                 <td>
3585                   6
3586                 </td>
3587                 <td align="left">
3588                   the subsequent index to "q".
3589                 </td>
3590               </tr>
3591             </table></dd></dl>
3592             The class <code>C2</code> will have the same field indices.
3593             Note that a field may have a different index depending on the
3594             object that is viewing it -- for example field "a" above.
3595             Note also: not all field indices may be visible from the 
3596             callbacks, but all indices are shown for illustrative purposes.
3597             <p/>
3598             The interface <code>I1</code> will have the
3599             following field indices:
3600             <dl><dd><table>
3601               <tr>
3602                 <td>
3603                   x
3604                 </td>
3605                 <td>
3606                   1
3607                 </td>
3608                 <td align="left">
3609                   The count of the fields in the superinterfaces
3610                   of <code>I1</code> is one (<i>n</i>=1):
3611                   <code>p</code> of <code>I0</code>.
3612                 </td>
3613               </tr>
3614             </table></dd></dl>
3615           </description>      
3616         </field>
3617       </typedef>
3618 
3619       <typedef id="jvmtiHeapReferenceInfoArray" 
3620                label="Reference information structure for Array references" 
3621                since="1.1">
3622         <description>
3623           Reference information returned for 
3624          <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3625         </description>
3626         <field id="index">
3627           <jint/>
3628           <description>       
3629             The array index.
3630           </description>
3631         </field>
3632       </typedef>
3633 
3634       <typedef id="jvmtiHeapReferenceInfoConstantPool" 
3635                label="Reference information structure for Constant Pool references" 
3636                since="1.1">
3637         <description>
3638           Reference information returned for 
3639           <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3640         </description>
3641         <field id="index">
3642           <jint/>
3643           <description>       
3644             The index into the constant pool of the class. See the description in 
3645       <vmspec chapter="4.4"/>.
3646           </description>
3647         </field>
3648       </typedef>
3649 
3650       <typedef id="jvmtiHeapReferenceInfoStackLocal" 
3651                label="Reference information structure for Local Variable references" 
3652                since="1.1">
3653         <description>
3654           Reference information returned for 
3655           <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3656         </description>
3657         <field id="thread_tag">
3658           <jlong/>
3659           <description>
3660             The tag of the thread corresponding to this stack, zero if not tagged.
3661           </description>
3662         </field>
3663         <field id="thread_id">
3664           <jlong/>
3665           <description>
3666             The unique thread ID of the thread corresponding to this stack.
3667           </description>
3668         </field>
3669         <field id="depth">
3670           <jint/>
3671           <description>
3672             The depth of the frame. 
3673           </description>
3674         </field>
3675         <field id="method">
3676           <jmethodID/>
3677           <description>
3678             The method executing in this frame.
3679           </description>
3680         </field>
3681         <field id="location">
3682           <jlocation/>
3683           <description>
3684             The currently executing location in this frame.
3685           </description>
3686         </field>
3687         <field id="slot">
3688           <jint/>
3689           <description>
3690             The slot number of the local variable.
3691           </description>
3692         </field>
3693       </typedef>
3694 
3695       <typedef id="jvmtiHeapReferenceInfoJniLocal" 
3696                label="Reference information structure for JNI local references" 
3697                since="1.1">
3698         <description>
3699           Reference information returned for 
3700           <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3701         </description>
3702         <field id="thread_tag">
3703           <jlong/>
3704           <description>
3705             The tag of the thread corresponding to this stack, zero if not tagged.
3706           </description>
3707         </field>
3708         <field id="thread_id">
3709           <jlong/>
3710           <description>
3711             The unique thread ID of the thread corresponding to this stack.
3712           </description>
3713         </field>
3714         <field id="depth">
3715           <jint/>
3716           <description>
3717             The depth of the frame. 
3718           </description>
3719         </field>
3720         <field id="method">
3721           <jmethodID/>
3722           <description>
3723             The method executing in this frame.
3724           </description>
3725         </field>
3726       </typedef>
3727 
3728       <typedef id="jvmtiHeapReferenceInfoReserved" 
3729                label="Reference information structure for Other references" 
3730                since="1.1">
3731         <description>
3732           Reference information returned for other references.
3733         </description>
3734         <field id="reserved1">
3735           <jlong/>
3736           <description>
3737             reserved for future use.
3738           </description>
3739         </field>
3740         <field id="reserved2">
3741           <jlong/>
3742           <description>
3743             reserved for future use.
3744           </description>
3745         </field>
3746         <field id="reserved3">
3747           <jlong/>
3748           <description>
3749             reserved for future use.
3750           </description>
3751         </field>
3752         <field id="reserved4">
3753           <jlong/>
3754           <description>
3755             reserved for future use.
3756           </description>
3757         </field>
3758         <field id="reserved5">
3759           <jlong/>
3760           <description>
3761             reserved for future use.
3762           </description>
3763         </field>
3764         <field id="reserved6">
3765           <jlong/>
3766           <description>
3767             reserved for future use.
3768           </description>
3769         </field>
3770         <field id="reserved7">
3771           <jlong/>
3772           <description>
3773             reserved for future use.
3774           </description>
3775         </field>
3776         <field id="reserved8">
3777           <jlong/>
3778           <description>
3779             reserved for future use.
3780           </description>
3781         </field>
3782       </typedef>
3783 
3784       <uniontypedef id="jvmtiHeapReferenceInfo" 
3785                label="Reference information structure" 
3786                since="1.1">
3787         <description>
3788           The information returned about referrers.
3789           Represented as a union of the various kinds of reference information.
3790         </description>
3791         <field id="field">
3792           <struct>jvmtiHeapReferenceInfoField</struct>
3793           <description>       
3794             The referrer information for 
3795             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> 
3796             and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3797           </description>
3798         </field>
3799         <field id="array">
3800           <struct>jvmtiHeapReferenceInfoArray</struct>
3801           <description>       
3802             The referrer information for 
3803             For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3804           </description>
3805         </field>
3806         <field id="constant_pool">
3807           <struct>jvmtiHeapReferenceInfoConstantPool</struct>
3808           <description>       
3809             The referrer information for 
3810             For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3811           </description>
3812         </field>
3813         <field id="stack_local">
3814           <struct>jvmtiHeapReferenceInfoStackLocal</struct>
3815           <description>       
3816             The referrer information for 
3817             For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3818           </description>
3819         </field>
3820         <field id="jni_local">
3821           <struct>jvmtiHeapReferenceInfoJniLocal</struct>
3822           <description>       
3823             The referrer information for 
3824             For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3825           </description>
3826         </field>
3827         <field id="other">
3828           <struct>jvmtiHeapReferenceInfoReserved</struct>
3829           <description>       
3830             reserved for future use.
3831           </description>
3832         </field>
3833       </uniontypedef>
3834 
3835       <typedef id="jvmtiHeapCallbacks" 
3836                label="Heap callback function structure" 
3837                since="1.1">
3838         <field id="heap_iteration_callback">
3839           <ptrtype>
3840             <struct>jvmtiHeapIterationCallback</struct>
3841           </ptrtype>
3842           <description>
3843             The callback to be called to describe an
3844             object in the heap. Used by the 
3845             <functionlink id="IterateThroughHeap"/> function, ignored by the
3846             <functionlink id="FollowReferences"/> function.
3847           </description>
3848         </field>            
3849         <field id="heap_reference_callback">
3850           <ptrtype>
3851             <struct>jvmtiHeapReferenceCallback</struct>
3852           </ptrtype>
3853           <description>
3854             The callback to be called to describe an
3855             object reference.  Used by the 
3856             <functionlink id="FollowReferences"/> function, ignored by the
3857             <functionlink id="IterateThroughHeap"/> function.
3858           </description>
3859         </field>            
3860         <field id="primitive_field_callback">
3861           <ptrtype>
3862             <struct>jvmtiPrimitiveFieldCallback</struct>
3863           </ptrtype>
3864           <description>
3865             The callback to be called to describe a
3866             primitive field.
3867           </description>
3868         </field>            
3869         <field id="array_primitive_value_callback">
3870           <ptrtype>
3871             <struct>jvmtiArrayPrimitiveValueCallback</struct>
3872           </ptrtype>
3873           <description>
3874             The callback to be called to describe an
3875             array of primitive values.
3876           </description>
3877         </field>            
3878         <field id="string_primitive_value_callback">
3879           <ptrtype>
3880             <struct>jvmtiStringPrimitiveValueCallback</struct>
3881           </ptrtype>
3882           <description>
3883             The callback to be called to describe a String value.
3884           </description>
3885         </field>            
3886         <field id="reserved5">
3887           <ptrtype>
3888             <struct>jvmtiReservedCallback</struct>
3889           </ptrtype>
3890           <description>
3891             Reserved for future use..
3892           </description>
3893         </field>            
3894         <field id="reserved6">
3895           <ptrtype>
3896             <struct>jvmtiReservedCallback</struct>
3897           </ptrtype>
3898           <description>
3899             Reserved for future use..
3900           </description>
3901         </field>            
3902         <field id="reserved7">
3903           <ptrtype>
3904             <struct>jvmtiReservedCallback</struct>
3905           </ptrtype>
3906           <description>
3907             Reserved for future use..
3908           </description>
3909         </field>            
3910         <field id="reserved8">
3911           <ptrtype>
3912             <struct>jvmtiReservedCallback</struct>
3913           </ptrtype>
3914           <description>
3915             Reserved for future use..
3916           </description>
3917         </field>            
3918         <field id="reserved9">
3919           <ptrtype>
3920             <struct>jvmtiReservedCallback</struct>
3921           </ptrtype>
3922           <description>
3923             Reserved for future use..
3924           </description>
3925         </field>            
3926         <field id="reserved10">
3927           <ptrtype>
3928             <struct>jvmtiReservedCallback</struct>
3929           </ptrtype>
3930           <description>
3931             Reserved for future use..
3932           </description>
3933         </field>            
3934         <field id="reserved11">
3935           <ptrtype>
3936             <struct>jvmtiReservedCallback</struct>
3937           </ptrtype>
3938           <description>
3939             Reserved for future use..
3940           </description>
3941         </field>            
3942         <field id="reserved12">
3943           <ptrtype>
3944             <struct>jvmtiReservedCallback</struct>
3945           </ptrtype>
3946           <description>
3947             Reserved for future use..
3948           </description>
3949         </field>            
3950         <field id="reserved13">
3951           <ptrtype>
3952             <struct>jvmtiReservedCallback</struct>
3953           </ptrtype>
3954           <description>
3955             Reserved for future use..
3956           </description>
3957         </field>            
3958         <field id="reserved14">
3959           <ptrtype>
3960             <struct>jvmtiReservedCallback</struct>
3961           </ptrtype>
3962           <description>
3963             Reserved for future use..
3964           </description>
3965         </field>            
3966         <field id="reserved15">
3967           <ptrtype>
3968             <struct>jvmtiReservedCallback</struct>
3969           </ptrtype>
3970           <description>
3971             Reserved for future use..
3972           </description>
3973         </field>            
3974       </typedef>
3975 
3976 
3977     <intro>
3978       <rationale>
3979         The heap dumping functionality (below) uses a callback
3980         for each object.  While it would seem that a buffered approach
3981         would provide better throughput, tests do
3982         not show this to be the case--possibly due to locality of
3983         memory reference or array access overhead.
3984       </rationale>
3985 
3986       <issue>
3987         Still under investigation as to if java.lang.ref references
3988         are reported as a different type of reference.
3989       </issue>
3990 
3991       <issue>
3992         Should or can an indication of the cost or relative cost of
3993         these operations be included?
3994       </issue>
3995 
3996     </intro>
3997 
3998     <callback id="jvmtiHeapIterationCallback" since="1.1">
3999       <jint/>
4000       <synopsis>Heap Iteration Callback</synopsis>
4001       <description>
4002         Agent supplied callback function.
4003         Describes (but does not pass in) an object in the heap.
4004         <p/>
4005         This function should return a bit vector of the desired
4006         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4007         This will determine if the entire iteration should be aborted
4008         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4009         <p/>
4010         See the <internallink id="heapCallbacks">heap callback
4011         function restrictions</internallink>.
4012       </description>
4013       <parameters>
4014         <param id="class_tag">
4015           <jlong/>
4016           <description>
4017             The tag of the class of object (zero if the class is not tagged). 
4018             If the object represents a runtime class, 
4019             the <code>class_tag</code> is the tag 
4020             associated with <code>java.lang.Class</code> 
4021             (zero if <code>java.lang.Class</code> is not tagged).
4022           </description>
4023         </param>
4024         <param id="size">
4025           <jlong/>
4026           <description>
4027             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
4028           </description>
4029         </param>
4030         <param id="tag_ptr">
4031           <outptr><jlong/></outptr>
4032           <description>
4033             The object tag value, or zero if the object is not tagged.
4034             To set the tag value to be associated with the object
4035             the agent sets the <code>jlong</code> pointed to by the parameter. 
4036           </description>
4037         </param>
4038         <param id="length">
4039           <jint/>
4040           <description>
4041             If this object is an array, the length of the array. Otherwise negative one (-1).
4042           </description>
4043         </param>
4044         <param id="user_data">
4045           <outptr><void/></outptr>
4046           <description>
4047             The user supplied data that was passed into the iteration function. 
4048           </description>
4049         </param>
4050       </parameters>
4051     </callback>  
4052 
4053     <callback id="jvmtiHeapReferenceCallback" since="1.1">
4054       <jint/>
4055       <synopsis>Heap Reference Callback</synopsis>
4056       <description>
4057         Agent supplied callback function.       
4058         Describes a reference from an object or the VM (the referrer) to another object
4059         (the referree) or a heap root to a referree.
4060         <p/>
4061         This function should return a bit vector of the desired
4062         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4063         This will determine if the objects referenced by the referree
4064         should be visited or if the entire iteration should be aborted.
4065         <p/>
4066         See the <internallink id="heapCallbacks">heap callback
4067         function restrictions</internallink>.
4068       </description>
4069       <parameters>
4070         <param id="reference_kind">
4071           <enum>jvmtiHeapReferenceKind</enum>
4072           <description>
4073             The kind of reference.
4074           </description>
4075         </param>
4076         <param id="reference_info">
4077           <inptr>
4078             <struct>jvmtiHeapReferenceInfo</struct>
4079           </inptr>
4080           <description>
4081             Details about the reference. 
4082             Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is
4083             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
4084             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
4085             <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
4086             <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>, 
4087             <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
4088             or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
4089             Otherwise <code>NULL</code>.
4090           </description>
4091         </param>
4092         <param id="class_tag">
4093           <jlong/>
4094           <description>
4095             The tag of the class of referree object (zero if the class is not tagged). 
4096             If the referree object represents a runtime class, 
4097             the <code>class_tag</code> is the tag 
4098             associated with <code>java.lang.Class</code>
4099             (zero if <code>java.lang.Class</code> is not tagged).
4100           </description>
4101         </param>
4102         <param id="referrer_class_tag">
4103           <jlong/>
4104           <description>
4105             The tag of the class of the referrer object (zero if the class is not tagged
4106             or the referree is a heap root). If the referrer object represents a runtime
4107             class, the <code>referrer_class_tag</code> is the tag associated with
4108             the <code>java.lang.Class</code>
4109             (zero if <code>java.lang.Class</code> is not tagged).
4110           </description>
4111         </param>
4112         <param id="size">
4113           <jlong/>
4114           <description>
4115             Size of the referree object (in bytes). 
4116             See <functionlink id="GetObjectSize"/>.
4117           </description>
4118         </param>
4119         <param id="tag_ptr">
4120           <outptr><jlong/></outptr>
4121           <description>
4122             Points to the referree object tag value, or zero if the object is not 
4123             tagged.
4124             To set the tag value to be associated with the object
4125             the agent sets the <code>jlong</code> pointed to by the parameter.
4126           </description>
4127         </param>
4128         <param id="referrer_tag_ptr">
4129           <outptr><jlong/></outptr>
4130           <description>
4131             Points to the tag of the referrer object, or 
4132             points to the zero if the referrer
4133             object is not tagged. 
4134             <code>NULL</code> if the referrer in not an object (that is,
4135             this callback is reporting a heap root).
4136             To set the tag value to be associated with the referrer object
4137             the agent sets the <code>jlong</code> pointed to by the parameter.
4138             If this callback is reporting a reference from an object to itself, 
4139             <code>referrer_tag_ptr == tag_ptr</code>.
4140           </description>
4141         </param>
4142         <param id="length">
4143           <jint/>
4144           <description>
4145             If this object is an array, the length of the array. Otherwise negative one (-1).
4146           </description>
4147         </param>
4148         <param id="user_data">
4149           <outptr><void/></outptr>
4150           <description>
4151             The user supplied data that was passed into the iteration function. 
4152           </description>
4153         </param>
4154       </parameters>
4155     </callback>
4156 
4157     <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
4158       <jint/>
4159       <synopsis>Primitive Field Callback</synopsis>
4160       <description>
4161         Agent supplied callback function which  
4162         describes a primitive field of an object (<i>the object</i>).
4163         A primitive field is a field whose type is a primitive type.
4164         This callback will describe a static field if the object is a class,
4165         and otherwise will describe an instance field.
4166         <p/>
4167         This function should return a bit vector of the desired
4168         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4169         This will determine if the entire iteration should be aborted
4170         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4171         <p/>
4172         See the <internallink id="heapCallbacks">heap callback
4173         function restrictions</internallink>.
4174       </description>
4175       <parameters>
4176         <param id="kind">
4177           <enum>jvmtiHeapReferenceKind</enum>
4178           <description>
4179             The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or 
4180             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
4181           </description>
4182         </param>
4183         <param id="info">
4184           <inptr>
4185             <struct>jvmtiHeapReferenceInfo</struct>
4186           </inptr>
4187           <description>
4188             Which field (the field index).
4189           </description>
4190         </param>
4191         <param id="object_class_tag">
4192           <jlong/>
4193           <description>
4194             The tag of the class of the object (zero if the class is not tagged). 
4195             If the object represents a runtime class, the 
4196             <code>object_class_tag</code> is the tag 
4197             associated with <code>java.lang.Class</code> 
4198             (zero if <code>java.lang.Class</code> is not tagged).
4199           </description>
4200         </param>
4201         <param id="object_tag_ptr">
4202           <outptr><jlong/></outptr>
4203           <description>
4204             Points to the tag of the object, or zero if the object is not 
4205             tagged.
4206             To set the tag value to be associated with the object
4207             the agent sets the <code>jlong</code> pointed to by the parameter.
4208           </description>
4209         </param>
4210         <param id="value">
4211           <jvalue/>
4212           <description>
4213             The value of the field.
4214           </description>
4215         </param>
4216         <param id="value_type">
4217           <enum>jvmtiPrimitiveType</enum>
4218           <description>
4219             The type of the field.
4220           </description>
4221         </param>
4222         <param id="user_data">
4223           <outptr><void/></outptr>
4224           <description>
4225             The user supplied data that was passed into the iteration function. 
4226           </description>
4227         </param>
4228       </parameters>
4229     </callback>
4230 
4231     <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
4232       <jint/>
4233       <synopsis>Array Primitive Value Callback</synopsis>
4234       <description>
4235         Agent supplied callback function.       
4236         Describes the values in an array of a primitive type.
4237         <p/>
4238         This function should return a bit vector of the desired
4239         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4240         This will determine if the entire iteration should be aborted
4241         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4242         <p/>
4243         See the <internallink id="heapCallbacks">heap callback
4244         function restrictions</internallink>.
4245       </description>
4246       <parameters>
4247         <param id="class_tag">
4248           <jlong/>
4249           <description>
4250             The tag of the class of the array object (zero if the class is not tagged). 
4251           </description>
4252         </param>
4253         <param id="size">
4254           <jlong/>
4255           <description>
4256             Size of the array (in bytes). 
4257             See <functionlink id="GetObjectSize"/>.
4258           </description>
4259         </param>
4260         <param id="tag_ptr">
4261           <outptr><jlong/></outptr>
4262           <description>
4263             Points to the tag of the array object, or zero if the object is not 
4264             tagged.
4265             To set the tag value to be associated with the object
4266             the agent sets the <code>jlong</code> pointed to by the parameter.
4267           </description>
4268         </param>
4269         <param id="element_count">
4270           <jint/>
4271           <description>
4272             The length of the primitive array.
4273           </description>
4274         </param>
4275         <param id="element_type">
4276           <enum>jvmtiPrimitiveType</enum>
4277           <description>
4278             The type of the elements of the array.
4279           </description>
4280         </param>
4281         <param id="elements">
4282           <vmbuf><void/></vmbuf>
4283           <description>
4284             The elements of the array in a packed array of <code>element_count</code>
4285             items of <code>element_type</code> size each.
4286           </description>
4287         </param>
4288         <param id="user_data">
4289           <outptr><void/></outptr>
4290           <description>
4291             The user supplied data that was passed into the iteration function. 
4292           </description>
4293         </param>
4294       </parameters>
4295     </callback>
4296 
4297     <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
4298       <jint/>
4299       <synopsis>String Primitive Value Callback</synopsis>
4300       <description>
4301         Agent supplied callback function.       
4302         Describes the value of a java.lang.String.
4303         <p/>
4304         This function should return a bit vector of the desired
4305         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4306         This will determine if the entire iteration should be aborted
4307         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4308         <p/>
4309         See the <internallink id="heapCallbacks">heap callback
4310         function restrictions</internallink>.
4311       </description>
4312       <parameters>
4313         <param id="class_tag">
4314           <jlong/>
4315           <description>
4316             The tag of the class of the String class (zero if the class is not tagged). 
4317             <issue>Is this needed?</issue>
4318           </description>
4319         </param>
4320         <param id="size">
4321           <jlong/>
4322           <description>
4323             Size of the string (in bytes). 
4324             See <functionlink id="GetObjectSize"/>.
4325           </description>
4326         </param>
4327         <param id="tag_ptr">
4328           <outptr><jlong/></outptr>
4329           <description>
4330             Points to the tag of the String object, or zero if the object is not 
4331             tagged.
4332             To set the tag value to be associated with the object
4333             the agent sets the <code>jlong</code> pointed to by the parameter.
4334           </description>
4335         </param>
4336         <param id="value">
4337           <vmbuf><jchar/></vmbuf>
4338           <description>
4339             The value of the String, encoded as a Unicode string.
4340           </description>
4341         </param>
4342         <param id="value_length">
4343           <jint/>
4344           <description>
4345             The length of the string. 
4346             The length is equal to the number of 16-bit Unicode 
4347             characters in the string.
4348           </description>
4349         </param>
4350         <param id="user_data">
4351           <outptr><void/></outptr>
4352           <description>
4353             The user supplied data that was passed into the iteration function. 
4354           </description>
4355         </param>
4356       </parameters>
4357     </callback>
4358 
4359 
4360     <callback id="jvmtiReservedCallback" since="1.1">
4361       <jint/>
4362       <synopsis>reserved for future use Callback</synopsis>
4363       <description>
4364         Placeholder -- reserved for future use.
4365       </description>
4366       <parameters>
4367       </parameters>
4368     </callback>
4369 
4370     <function id="FollowReferences" num="115" since="1.1">
4371       <synopsis>Follow References</synopsis>
4372       <description>       
4373         This function initiates a traversal over the objects that are 
4374         directly and indirectly reachable from the specified object or,
4375         if <code>initial_object</code> is not specified, all objects 
4376         reachable from the heap roots.
4377         The heap root are the set of system classes, 
4378         JNI globals, references from thread stacks, and other objects used as roots 
4379         for the purposes of garbage collection. 
4380         <p/>
4381         This function operates by traversing the reference graph.
4382         Let <i>A</i>, <i>B</i>, ... represent objects.
4383         When a reference from <i>A</i> to <i>B</i> is traversed,
4384         when a reference from a heap root to <i>B</i> is traversed, 
4385         or when <i>B</i> is specified as the <paramlink id="initial_object"/>, 
4386         then <i>B</i> is said to be <i>visited</i>.
4387         A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i> 
4388         is visited.
4389         References are reported in the same order that the references are traversed.
4390         Object references are reported by invoking the agent supplied  
4391         callback function <functionlink id="jvmtiHeapReferenceCallback"/>.
4392         In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known 
4393         as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
4394         The callback is invoked exactly once for each reference from a referrer;
4395         this is true even if there are reference cycles or multiple paths to
4396         the referrer.
4397         There may be more than one reference between a referrer and a referree,
4398         each reference is reported.
4399         These references may be distinguished by examining the
4400         <datalink 
4401          id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
4402          and
4403         <datalink 
4404          id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
4405         parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
4406         <p/>
4407         This function reports a Java programming language view of object references,
4408         not a virtual machine implementation view. The following object references
4409         are reported when they are non-null:
4410         <ul>
4411           <li>Instance objects report references to each non-primitive instance fields
4412               (including inherited fields).</li>
4413           <li>Instance objects report a reference to the object type (class).</li>
4414           <li>Classes report a reference to the superclass and directly
4415               implemented/extended interfaces.</li>
4416           <li>Classes report a reference to the class loader, protection domain,
4417               signers, and resolved entries in the constant pool.</li>
4418           <li>Classes report a reference to each directly declared non-primitive
4419               static field.</li>
4420           <li>Arrays report a reference to the array type (class) and each
4421               array element.</li>
4422           <li>Primitive arrays report a reference to the array type.</li>
4423         </ul>
4424         <p/>
4425         This function can also be used to examine primitive (non-object) values.
4426         The primitive value of an array or String
4427         is reported after the object has been visited;
4428         it is reported by invoking the agent supplied callback function
4429         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4430         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4431         A primitive field
4432         is reported after the object with that field is visited;
4433         it is reported by invoking the agent supplied callback function
4434         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4435         <p/>
4436         Whether a callback is provided or is <code>NULL</code> only determines
4437         whether the callback will be invoked, it does not influence
4438         which objects are visited nor does it influence whether other callbacks
4439         will be invoked.
4440         However, the 
4441         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
4442         returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4443         do determine if the objects referenced by the 
4444         current object as visited.
4445         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4446         and <paramlink id="klass"/> provided as parameters to this function
4447         do not control which objects are visited but they do control which
4448         objects and primitive values are reported by the callbacks.
4449         For example, if the only callback that was set is
4450         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4451         is set to the array of bytes class, then only arrays of byte will be
4452         reported.  
4453         The table below summarizes this:
4454         <p/>
4455         <table>
4456           <tr>
4457             <th/>
4458             <th>
4459               Controls objects visited
4460             </th>
4461             <th>
4462               Controls objects reported
4463             </th>
4464             <th>
4465               Controls primitives reported
4466             </th>
4467           </tr>
4468           <tr>
4469             <th align="left">
4470               the
4471               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4472               returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4473             </th>
4474             <td>
4475               <b>Yes</b>
4476             </td>
4477             <td>
4478               <b>Yes</b>, since visits are controlled
4479             </td>
4480             <td>
4481               <b>Yes</b>, since visits are controlled
4482             </td>
4483           </tr>
4484           <tr>
4485             <th align="left">
4486               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4487               in <paramlink id="callbacks"/> set
4488             </th>
4489             <td>
4490               No
4491             </td>
4492             <td>
4493               <b>Yes</b>
4494             </td>
4495             <td>
4496               No
4497             </td>
4498           </tr>
4499           <tr>
4500             <th align="left">
4501               <paramlink id="heap_filter"/>
4502             </th>
4503             <td>
4504               No
4505             </td>
4506             <td>
4507               <b>Yes</b>
4508             </td>
4509             <td>
4510               <b>Yes</b>
4511             </td>
4512           </tr>
4513           <tr>
4514             <th align="left">
4515               <paramlink id="klass"/>
4516             </th>
4517             <td>
4518               No
4519             </td>
4520             <td>
4521               <b>Yes</b>
4522             </td>
4523             <td>
4524               <b>Yes</b>
4525             </td>
4526           </tr>
4527         </table>
4528         <p/>
4529         During the execution of this function the state of the heap
4530         does not change: no objects are allocated, no objects are
4531         garbage collected, and the state of objects (including 
4532         held values) does not change. 
4533         As a result, threads executing Java 
4534         programming language code, threads attempting to resume the
4535         execution of Java programming language code, and threads 
4536         attempting to execute JNI functions are typically stalled.
4537       </description>
4538       <origin>new</origin>
4539       <capabilities>
4540         <required id="can_tag_objects"></required>
4541       </capabilities>
4542       <parameters>             
4543         <param id="heap_filter">
4544           <jint/>
4545           <description>
4546             This bit vector of 
4547             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4548             restricts the objects for which the callback function is called.
4549             This applies to both the object and primitive callbacks.
4550           </description>
4551         </param>
4552         <param id="klass">
4553           <ptrtype>
4554             <jclass/>
4555             <nullok>callbacks are not limited to instances of a particular
4556                     class</nullok>
4557           </ptrtype>
4558           <description>
4559             Callbacks are only reported when the object is an instance of 
4560             this class.
4561             Objects which are instances of a subclass of <code>klass</code>
4562             are not reported.
4563             If <code>klass</code> is an interface, no objects are reported.
4564             This applies to both the object and primitive callbacks.
4565           </description>
4566         </param>
4567         <param id="initial_object">
4568           <ptrtype>
4569             <jobject/>
4570             <nullok>references are followed from the heap roots</nullok>
4571           </ptrtype>
4572           <description>
4573             The object to follow
4574           </description>
4575         </param>
4576         <param id="callbacks">
4577           <inptr>
4578             <struct>jvmtiHeapCallbacks</struct>
4579           </inptr>
4580           <description>
4581             Structure defining the set of callback functions.
4582           </description>
4583         </param>                  
4584         <param id="user_data">
4585           <inbuf>
4586             <void/>
4587             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4588           </inbuf>
4589           <description>
4590             User supplied data to be passed to the callback. 
4591           </description>
4592         </param>
4593       </parameters>
4594       <errors>
4595         <error id="JVMTI_ERROR_INVALID_CLASS">
4596           <paramlink id="klass"/> is not a valid class.
4597         </error>
4598         <error id="JVMTI_ERROR_INVALID_OBJECT">
4599           <paramlink id="initial_object"/> is not a valid object.
4600         </error>
4601       </errors>
4602     </function>
4603 
4604 
4605     <function id="IterateThroughHeap" num="116" since="1.1">
4606       <synopsis>Iterate Through Heap</synopsis>
4607       <description>        
4608         Initiate an iteration over all objects in the heap. 
4609         This includes both reachable and 
4610         unreachable objects. Objects are visited in no particular order.
4611         <p/>
4612         Heap objects are reported by invoking the agent supplied 
4613         callback function <functionlink id="jvmtiHeapIterationCallback"/>.
4614         References between objects are not reported.
4615         If only reachable objects are desired, or if object reference information
4616         is needed, use <functionlink id="FollowReferences"/>.
4617         <p/>
4618         This function can also be used to examine primitive (non-object) values.
4619         The primitive value of an array or String
4620         is reported after the object has been visited;
4621         it is reported by invoking the agent supplied callback function
4622         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4623         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4624         A primitive field
4625         is reported after the object with that field is visited;
4626         it is reported by invoking the agent supplied 
4627         callback function
4628         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4629         <p/>
4630         Unless the iteration is aborted by the
4631         <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4632         returned by a callback, all objects in the heap are visited.
4633         Whether a callback is provided or is <code>NULL</code> only determines
4634         whether the callback will be invoked, it does not influence
4635         which objects are visited nor does it influence whether other callbacks
4636         will be invoked.
4637         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4638         and <paramlink id="klass"/> provided as parameters to this function
4639         do not control which objects are visited but they do control which
4640         objects and primitive values are reported by the callbacks.
4641         For example, if the only callback that was set is
4642         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4643         is set to the array of bytes class, then only arrays of byte will be
4644         reported. The table below summarizes this (contrast this with 
4645         <functionlink id="FollowReferences"/>):
4646         <p/>
4647         <table>
4648           <tr>
4649             <th/>
4650             <th>
4651               Controls objects visited
4652             </th>
4653             <th>
4654               Controls objects reported
4655             </th>
4656             <th>
4657               Controls primitives reported
4658             </th>
4659           </tr>
4660           <tr>
4661             <th align="left">
4662               the
4663               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4664               returned by <functionlink id="jvmtiHeapIterationCallback"/>
4665             </th>
4666             <td>
4667               No<br/>(unless they abort the iteration)
4668             </td>
4669             <td>
4670               No<br/>(unless they abort the iteration)
4671             </td>
4672             <td>
4673               No<br/>(unless they abort the iteration)
4674             </td>
4675           </tr>
4676           <tr>
4677             <th align="left">
4678               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4679               in <paramlink id="callbacks"/> set
4680             </th>
4681             <td>
4682               No
4683             </td>
4684             <td>
4685               <b>Yes</b>
4686             </td>
4687             <td>
4688               No
4689             </td>
4690           </tr>
4691           <tr>
4692             <th align="left">
4693               <paramlink id="heap_filter"/>
4694             </th>
4695             <td>
4696               No
4697             </td>
4698             <td>
4699               <b>Yes</b>
4700             </td>
4701             <td>
4702               <b>Yes</b>
4703             </td>
4704           </tr>
4705           <tr>
4706             <th align="left">
4707               <paramlink id="klass"/>
4708             </th>
4709             <td>
4710               No
4711             </td>
4712             <td>
4713               <b>Yes</b>
4714             </td>
4715             <td>
4716               <b>Yes</b>
4717             </td>
4718           </tr>
4719         </table>
4720         <p/>
4721         During the execution of this function the state of the heap
4722         does not change: no objects are allocated, no objects are
4723         garbage collected, and the state of objects (including 
4724         held values) does not change. 
4725         As a result, threads executing Java 
4726         programming language code, threads attempting to resume the
4727         execution of Java programming language code, and threads 
4728         attempting to execute JNI functions are typically stalled.
4729       </description>
4730       <origin>new</origin>
4731       <capabilities>
4732         <required id="can_tag_objects"></required>
4733       </capabilities>
4734       <parameters>
4735         <param id="heap_filter">
4736           <jint/>
4737           <description>
4738             This bit vector of 
4739             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4740             restricts the objects for which the callback function is called.
4741             This applies to both the object and primitive callbacks.
4742           </description>
4743         </param>
4744         <param id="klass">
4745           <ptrtype>
4746             <jclass/>
4747             <nullok>callbacks are not limited to instances of a particular class</nullok>
4748           </ptrtype>
4749           <description>
4750             Callbacks are only reported when the object is an instance of 
4751             this class.
4752             Objects which are instances of a subclass of <code>klass</code>
4753             are not reported.
4754             If <code>klass</code> is an interface, no objects are reported.
4755             This applies to both the object and primitive callbacks.
4756           </description>
4757         </param>
4758         <param id="callbacks">
4759           <inptr>
4760             <struct>jvmtiHeapCallbacks</struct>
4761           </inptr>
4762           <description>
4763             Structure defining the set callback functions.
4764           </description>
4765         </param>                  
4766         <param id="user_data">
4767           <inbuf>
4768             <void/>
4769             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4770           </inbuf>
4771           <description>
4772             User supplied data to be passed to the callback. 
4773           </description>
4774         </param>
4775       </parameters>
4776       <errors>
4777         <error id="JVMTI_ERROR_INVALID_CLASS">
4778           <paramlink id="klass"/> is not a valid class.
4779         </error>
4780       </errors>
4781     </function>
4782 
4783     <function id="GetTag" phase="start" num="106">
4784       <synopsis>Get Tag</synopsis>
4785       <description>
4786         Retrieve the tag associated with an object.
4787         The tag is a long value typically used to store a 
4788         unique identifier or pointer to object information.
4789         The tag is set with
4790         <functionlink id="SetTag"></functionlink>.
4791         Objects for which no tags have been set return a
4792         tag value of zero.
4793       </description>
4794       <origin>new</origin>
4795       <capabilities>
4796         <required id="can_tag_objects"></required>
4797       </capabilities>
4798       <parameters>
4799         <param id="object">
4800           <jobject/>
4801             <description>
4802               The object whose tag is to be retrieved.
4803             </description>
4804         </param>
4805         <param id="tag_ptr">
4806           <outptr><jlong/></outptr>
4807           <description>
4808             On return, the referenced long is set to the value 
4809             of the tag.
4810           </description>
4811         </param>
4812       </parameters>
4813       <errors>
4814       </errors>
4815     </function>
4816 
4817     <function id="SetTag" phase="start" num="107">
4818       <synopsis>Set Tag</synopsis>
4819       <description>
4820         Set the tag associated with an object.
4821         The tag is a long value typically used to store a 
4822         unique identifier or pointer to object information.
4823         The tag is visible with
4824         <functionlink id="GetTag"></functionlink>.
4825       </description>
4826       <origin>new</origin>
4827       <capabilities>
4828         <required id="can_tag_objects"></required>
4829       </capabilities>
4830       <parameters>
4831         <param id="object">
4832           <jobject/>
4833             <description>
4834               The object whose tag is to be set.
4835             </description>
4836         </param>
4837         <param id="tag">
4838           <jlong/>
4839           <description>
4840             The new value of the tag.
4841           </description>
4842         </param>
4843       </parameters>
4844       <errors>
4845       </errors>
4846     </function>
4847 
4848     <function id="GetObjectsWithTags" num="114">
4849       <synopsis>Get Objects With Tags</synopsis>
4850       <description>
4851         Return objects in the heap with the specified tags.
4852         The format is parallel arrays of objects and tags.
4853       </description>
4854       <origin>new</origin>
4855       <capabilities>
4856         <required id="can_tag_objects"></required>
4857       </capabilities>
4858       <parameters>
4859         <param id="tag_count">
4860           <jint min="0"/>
4861             <description>
4862               Number of tags to scan for.
4863             </description>
4864         </param>
4865         <param id="tags">
4866           <inbuf incount="tag_count">
4867             <jlong/>
4868           </inbuf>
4869             <description>
4870               Scan for objects with these tags.
4871               Zero is not permitted in this array.
4872             </description>
4873         </param>
4874         <param id="count_ptr">
4875           <outptr>
4876             <jint/>
4877           </outptr>
4878             <description>
4879               Return the number of objects with any of the tags 
4880               in <paramlink id="tags"/>.
4881             </description>
4882         </param>
4883         <param id="object_result_ptr">
4884           <allocbuf outcount="count_ptr">
4885             <jobject/>
4886             <nullok>this information is not returned</nullok>
4887           </allocbuf>
4888             <description>
4889               Returns the array of objects with any of the tags 
4890               in <paramlink id="tags"/>.
4891             </description>
4892         </param>
4893         <param id="tag_result_ptr">
4894           <allocbuf outcount="count_ptr">
4895             <jlong/>
4896             <nullok>this information is not returned</nullok>
4897           </allocbuf>
4898             <description>
4899               For each object in <paramlink id="object_result_ptr"/>,
4900               return the tag at the corresponding index.
4901             </description>
4902         </param>
4903       </parameters>
4904       <errors>
4905         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
4906           Zero is present in <paramlink id="tags"></paramlink>.
4907         </error>
4908       </errors>
4909     </function>
4910 
4911     <function id="ForceGarbageCollection" num="108">
4912       <synopsis>Force Garbage Collection</synopsis>
4913       <description>
4914         Force the VM to perform a garbage collection.
4915         The garbage collection is as complete as possible.
4916         This function does not cause finalizers to be run.
4917         This function does not return until the garbage collection
4918         is finished.
4919         <p/>
4920         Although garbage collection is as complete 
4921         as possible there is no guarantee that all 
4922         <eventlink id="ObjectFree"/>
4923         events will have been 
4924         sent by the time that this function 
4925         returns. In particular, an object may be 
4926         prevented from being freed because it 
4927         is awaiting finalization.
4928       </description>
4929       <origin>new</origin>
4930       <capabilities>
4931       </capabilities>
4932       <parameters>
4933       </parameters>
4934       <errors>
4935       </errors>
4936     </function>
4937 
4938 
4939   </category>
4940 
4941   <category id="Heap_1_0" label="Heap (1.0)">
4942     <intro>
4943       <b>
4944         These functions and data types were introduced in the original 
4945         <jvmti/> version 1.0 and have been superseded by more
4946       </b>
4947       <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
4948       <b>
4949         which:
4950       </b>
4951       <ul>
4952         <li>
4953           <b>
4954             Allow access to primitive values (the value of Strings, arrays, 
4955             and primitive fields)
4956           </b>
4957         </li>
4958         <li>
4959           <b>
4960             Allow the tag of the referrer to be set, thus enabling more
4961             efficient localized reference graph building
4962           </b>
4963         </li>
4964         <li>
4965           <b>
4966             Provide more extensive filtering abilities
4967           </b>
4968         </li>
4969         <li>
4970           <b>
4971             Are extensible, allowing their abilities to grow in future versions of <jvmti/>
4972           </b>
4973         </li>
4974       </ul>
4975       <p/>
4976       <b>Please use the </b>
4977       <internallink id="Heap"><b>current Heap functions</b></internallink>.
4978         <p/>
4979         <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
4980           <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
4981             Tagged objects only.
4982           </constant>
4983           <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
4984             Untagged objects only.
4985           </constant>
4986           <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
4987             Either tagged or untagged objects.
4988           </constant>
4989         </constants>
4990 
4991         <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
4992           <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
4993             JNI global reference.
4994           </constant>
4995           <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
4996             System class.
4997           </constant>
4998           <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
4999             Monitor.
5000           </constant>
5001           <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
5002             Stack local.
5003           </constant>
5004           <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
5005             JNI local reference.
5006           </constant>
5007           <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
5008             Thread.
5009           </constant>
5010           <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
5011             Other.
5012           </constant>
5013         </constants>
5014 
5015         <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
5016           <constant id="JVMTI_REFERENCE_CLASS" num="1">
5017             Reference from an object to its class.
5018           </constant>       
5019           <constant id="JVMTI_REFERENCE_FIELD" num="2">
5020             Reference from an object to the value of one of its instance fields.
5021             For references of this kind the <code>referrer_index</code>
5022             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5023             jvmtiObjectReferenceCallback</internallink> is the index of the
5024             the instance field. The index is based on the order of all the 
5025             object's fields. This includes all fields of the directly declared
5026             static and instance fields in the class, and includes all fields (both
5027             public and private) fields declared in superclasses and superinterfaces.
5028             The index is thus calculated by summing the index of the field in the directly
5029             declared class (see <functionlink id="GetClassFields"/>), with the total
5030             number of fields (both public and private) declared in all superclasses
5031             and superinterfaces. The index starts at zero.
5032           </constant>
5033           <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
5034             Reference from an array to one of its elements.
5035             For references of this kind the <code>referrer_index</code>
5036             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5037             jvmtiObjectReferenceCallback</internallink> is the array index.
5038           </constant>
5039           <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
5040             Reference from a class to its class loader.
5041           </constant>
5042           <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
5043             Reference from a class to its signers array.
5044           </constant>
5045           <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
5046             Reference from a class to its protection domain.
5047           </constant>       
5048           <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
5049             Reference from a class to one of its interfaces.
5050           </constant>
5051           <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
5052             Reference from a class to the value of one of its static fields.
5053             For references of this kind the <code>referrer_index</code>
5054             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5055             jvmtiObjectReferenceCallback</internallink> is the index of the
5056             the static field. The index is based on the order of all the 
5057             object's fields. This includes all fields of the directly declared
5058             static and instance fields in the class, and includes all fields (both
5059             public and private) fields declared in superclasses and superinterfaces.
5060             The index is thus calculated by summing the index of the field in the directly
5061             declared class (see <functionlink id="GetClassFields"/>), with the total
5062             number of fields (both public and private) declared in all superclasses
5063             and superinterfaces. The index starts at zero.
5064             Note: this definition differs from that in the <jvmti/> 1.0 Specification.
5065             <rationale>No known implementations used the 1.0 definition.</rationale>
5066           </constant>
5067           <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
5068             Reference from a class to a resolved entry in the constant pool.
5069             For references of this kind the <code>referrer_index</code>
5070             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5071             jvmtiObjectReferenceCallback</internallink> is the index into
5072             constant pool table of the class, starting at 1. See
5073             <vmspec chapter="4.4"/>.
5074           </constant>
5075         </constants>
5076 
5077         <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
5078           <constant id="JVMTI_ITERATION_CONTINUE" num="1">
5079             Continue the iteration.  
5080             If this is a reference iteration, follow the references of this object.
5081           </constant>       
5082           <constant id="JVMTI_ITERATION_IGNORE" num="2">
5083             Continue the iteration.  
5084             If this is a reference iteration, ignore the references of this object.
5085           </constant>
5086           <constant id="JVMTI_ITERATION_ABORT" num="0">
5087             Abort the iteration.
5088           </constant>
5089         </constants>
5090     </intro>
5091 
5092     <callback id="jvmtiHeapObjectCallback">
5093       <enum>jvmtiIterationControl</enum>
5094       <synopsis>Heap Object Callback</synopsis>
5095       <description>
5096         Agent supplied callback function.
5097         Describes (but does not pass in) an object in the heap.
5098         <p/>
5099         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5100         or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5101         <p/>
5102         See the <internallink id="heapCallbacks">heap callback
5103         function restrictions</internallink>.
5104       </description>
5105       <parameters>
5106         <param id="class_tag">
5107           <jlong/>
5108           <description>
5109             The tag of the class of object (zero if the class is not tagged). 
5110             If the object represents a runtime class, 
5111             the <code>class_tag</code> is the tag 
5112             associated with <code>java.lang.Class</code>
5113             (zero if <code>java.lang.Class</code> is not tagged).
5114           </description>
5115         </param>
5116         <param id="size">
5117           <jlong/>
5118           <description>
5119             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5120           </description>
5121         </param>
5122         <param id="tag_ptr">
5123           <outptr><jlong/></outptr>
5124           <description>
5125             The object tag value, or zero if the object is not tagged.
5126             To set the tag value to be associated with the object
5127             the agent sets the <code>jlong</code> pointed to by the parameter. 
5128           </description>
5129         </param>
5130         <param id="user_data">
5131           <outptr><void/></outptr>
5132           <description>
5133             The user supplied data that was passed into the iteration function. 
5134           </description>
5135         </param>
5136       </parameters>
5137     </callback>  
5138 
5139     <callback id="jvmtiHeapRootCallback">
5140       <enum>jvmtiIterationControl</enum>
5141       <synopsis>Heap Root Object Callback</synopsis>
5142       <description>
5143         Agent supplied callback function.
5144         Describes (but does not pass in) an object that is a root for the purposes
5145         of garbage collection.
5146         <p/>
5147         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5148         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5149         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5150         <p/>
5151         See the <internallink id="heapCallbacks">heap callback
5152         function restrictions</internallink>.
5153       </description>
5154       <parameters>
5155         <param id="root_kind">
5156           <enum>jvmtiHeapRootKind</enum>
5157           <description>
5158             The kind of heap root.
5159           </description>
5160         </param>
5161         <param id="class_tag">
5162           <jlong/>
5163           <description>
5164             The tag of the class of object (zero if the class is not tagged). 
5165             If the object represents a runtime class, the <code>class_tag</code> is the tag 
5166             associated with <code>java.lang.Class</code> 
5167             (zero if <code>java.lang.Class</code> is not tagged).
5168           </description>
5169         </param>
5170         <param id="size">
5171           <jlong/>
5172           <description>
5173             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5174           </description>
5175         </param>
5176         <param id="tag_ptr">
5177           <outptr><jlong/></outptr>
5178           <description>
5179             The object tag value, or zero if the object is not tagged.
5180             To set the tag value to be associated with the object
5181             the agent sets the <code>jlong</code> pointed to by the parameter.
5182           </description>
5183         </param>
5184         <param id="user_data">
5185           <outptr><void/></outptr>
5186           <description>
5187             The user supplied data that was passed into the iteration function. 
5188           </description>
5189         </param>
5190       </parameters>
5191     </callback> 
5192 
5193     <callback id="jvmtiStackReferenceCallback">
5194       <enum>jvmtiIterationControl</enum>
5195       <synopsis>Stack Reference Object Callback</synopsis>
5196       <description>
5197         Agent supplied callback function.
5198         Describes (but does not pass in) an object on the stack that is a root for 
5199         the purposes of garbage collection.
5200         <p/>
5201         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5202         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5203         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5204         <p/>
5205         See the <internallink id="heapCallbacks">heap callback
5206         function restrictions</internallink>.
5207       </description>
5208       <parameters>
5209         <param id="root_kind">
5210           <enum>jvmtiHeapRootKind</enum>
5211           <description>
5212             The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5213             <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
5214           </description>
5215         </param>
5216         <param id="class_tag">
5217           <jlong/>
5218           <description>
5219            The tag of the class of object (zero if the class is not tagged). 
5220            If the object represents a runtime class, the  <code>class_tag</code> is the tag 
5221            associated with <code>java.lang.Class</code> 
5222            (zero if <code>java.lang.Class</code> is not tagged).
5223           </description>
5224         </param>
5225         <param id="size">
5226           <jlong/>
5227           <description>
5228             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5229           </description>
5230         </param>
5231         <param id="tag_ptr">
5232           <outptr><jlong/></outptr>
5233           <description>
5234             The object tag value, or zero if the object is not tagged.
5235             To set the tag value to be associated with the object
5236             the agent sets the <code>jlong</code> pointed to by the parameter.
5237           </description>
5238         </param>
5239         <param id="thread_tag">
5240           <jlong/>
5241           <description>
5242             The tag of the thread corresponding to this stack, zero if not tagged.
5243           </description>
5244         </param>
5245         <param id="depth">
5246           <jint/>
5247           <description>
5248             The depth of the frame. 
5249           </description>
5250         </param>
5251         <param id="method">
5252           <jmethodID/>
5253           <description>
5254             The method executing in this frame.
5255           </description>
5256         </param>
5257         <param id="slot">
5258           <jint/>
5259           <description>
5260             The slot number.
5261           </description>
5262         </param>
5263         <param id="user_data">
5264           <outptr><void/></outptr>
5265           <description>
5266             The user supplied data that was passed into the iteration function. 
5267           </description>
5268         </param>
5269       </parameters>
5270     </callback>
5271 
5272     <callback id="jvmtiObjectReferenceCallback">
5273       <enum>jvmtiIterationControl</enum>
5274       <synopsis>Object Reference Callback</synopsis>
5275       <description>
5276         Agent supplied callback function.       
5277         Describes a reference from an object (the referrer) to another object
5278         (the referree).
5279         <p/>
5280         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5281         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing 
5282         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5283         <p/>
5284         See the <internallink id="heapCallbacks">heap callback
5285         function restrictions</internallink>.
5286       </description>
5287       <parameters>
5288         <param id="reference_kind">
5289           <enum>jvmtiObjectReferenceKind</enum>
5290           <description>
5291             The type of reference.
5292           </description>
5293         </param>
5294         <param id="class_tag">
5295           <jlong/>
5296           <description>
5297             The tag of the class of referree object (zero if the class is not tagged). 
5298             If the referree object represents a runtime class,
5299             the  <code>class_tag</code> is the tag 
5300             associated with <code>java.lang.Class</code> 
5301             (zero if <code>java.lang.Class</code> is not tagged).
5302           </description>
5303         </param>
5304         <param id="size">
5305           <jlong/>
5306           <description>
5307             Size of the referree object (in bytes). 
5308             See <functionlink id="GetObjectSize"/>.
5309           </description>
5310         </param>
5311         <param id="tag_ptr">
5312           <outptr><jlong/></outptr>
5313           <description>
5314             The referree object tag value, or zero if the object is not 
5315             tagged.
5316             To set the tag value to be associated with the object
5317             the agent sets the <code>jlong</code> pointed to by the parameter.
5318           </description>
5319         </param>
5320         <param id="referrer_tag">
5321           <jlong/>
5322           <description>
5323             The tag of the referrer object, or zero if the referrer
5324             object is not tagged.
5325           </description>
5326         </param>
5327         <param id="referrer_index">
5328           <jint/>
5329           <description>       
5330             For references of type <code>JVMTI_REFERENCE_FIELD</code> or
5331             <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
5332             of the field in the referrer object. The index is based on the 
5333             order of all the object's fields - see <internallink 
5334             id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
5335             or <internallink
5336             id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
5337             </internallink> for further description.
5338             <p/>
5339             For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
5340             the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
5341             JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
5342             <p/>
5343             For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
5344             the index into the constant pool of the class - see
5345             <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
5346             JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further 
5347             description.
5348             <p/>
5349             For references of other kinds the <code>referrer_index</code> is
5350             <code>-1</code>.
5351           </description>
5352         </param>
5353         <param id="user_data">
5354           <outptr><void/></outptr>
5355           <description>
5356             The user supplied data that was passed into the iteration function. 
5357           </description>
5358         </param>
5359       </parameters>
5360     </callback>
5361 
5362     <function id="IterateOverObjectsReachableFromObject" num="109">
5363       <synopsis>Iterate Over Objects Reachable From Object</synopsis>
5364       <description>       
5365         This function iterates over all objects that are directly
5366         and indirectly reachable from the specified object.
5367         For each object <i>A</i> (known
5368         as the referrer) with a reference to object <i>B</i> the specified 
5369         callback function is called to describe the object reference.
5370         The callback is called exactly once for each reference from a referrer;
5371         this is true even if there are reference cycles or multiple paths to
5372         the referrer.
5373         There may be more than one reference between a referrer and a referree,
5374         These may be distinguished by the 
5375         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5376         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5377         The callback for an object will always occur after the callback for
5378         its referrer.
5379         <p/>
5380         See <functionlink id="FollowReferences"/> for the object
5381         references which are reported.
5382         <p/>
5383         During the execution of this function the state of the heap
5384         does not change: no objects are allocated, no objects are
5385         garbage collected, and the state of objects (including 
5386         held values) does not change. 
5387         As a result, threads executing Java 
5388         programming language code, threads attempting to resume the
5389         execution of Java programming language code, and threads 
5390         attempting to execute JNI functions are typically stalled.
5391       </description>
5392       <origin>new</origin>
5393       <capabilities>
5394         <required id="can_tag_objects"></required>
5395       </capabilities>
5396       <parameters>             
5397         <param id="object">
5398           <jobject/>
5399             <description>
5400               The object
5401             </description>
5402         </param>
5403         <param id="object_reference_callback">
5404           <ptrtype>
5405             <struct>jvmtiObjectReferenceCallback</struct>
5406           </ptrtype>
5407             <description>
5408               The callback to be called to describe each
5409               object reference.
5410             </description>
5411         </param>            
5412         <param id="user_data">
5413           <inbuf>
5414             <void/>
5415             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5416           </inbuf>
5417           <description>
5418             User supplied data to be passed to the callback. 
5419           </description>
5420         </param>
5421       </parameters>
5422       <errors>
5423       </errors>
5424     </function>
5425 
5426     <function id="IterateOverReachableObjects" num="110">
5427       <synopsis>Iterate Over Reachable Objects</synopsis>
5428       <description>
5429         This function iterates over the root objects and all objects that
5430         are directly and indirectly reachable from the root objects.
5431         The root objects comprise the set of system classes, 
5432         JNI globals, references from thread stacks, and other objects used as roots 
5433         for the purposes of garbage collection. 
5434         <p/>
5435         For each root the <paramlink id="heap_root_callback"></paramlink>
5436         or <paramlink id="stack_ref_callback"></paramlink> callback is called.
5437         An object can be a root object for more than one reason and in that case
5438         the appropriate callback is called for each reason.
5439         <p/>
5440         For each object reference the <paramlink id="object_ref_callback"></paramlink>
5441         callback function is called to describe the object reference.
5442         The callback is called exactly once for each reference from a referrer;
5443         this is true even if there are reference cycles or multiple paths to
5444         the referrer.
5445         There may be more than one reference between a referrer and a referree,
5446         These may be distinguished by the 
5447         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5448         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5449         The callback for an object will always occur after the callback for
5450         its referrer.
5451         <p/>
5452         See <functionlink id="FollowReferences"/> for the object
5453         references which are reported.
5454         <p/>
5455         Roots are always reported to the profiler before any object references
5456         are reported. In other words, the <paramlink id="object_ref_callback"></paramlink> 
5457         callback will not be called until the appropriate callback has been called
5458         for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is 
5459         specified as <code>NULL</code> then this function returns after
5460         reporting the root objects to the profiler.
5461         <p/>
5462         During the execution of this function the state of the heap
5463         does not change: no objects are allocated, no objects are
5464         garbage collected, and the state of objects (including 
5465         held values) does not change. 
5466         As a result, threads executing Java 
5467         programming language code, threads attempting to resume the
5468         execution of Java programming language code, and threads 
5469         attempting to execute JNI functions are typically stalled.
5470       </description>
5471       <origin>new</origin>
5472       <capabilities>
5473         <required id="can_tag_objects"></required>
5474       </capabilities>
5475       <parameters>        
5476         <param id="heap_root_callback">
5477           <ptrtype>
5478             <struct>jvmtiHeapRootCallback</struct>
5479             <nullok>do not report heap roots</nullok>
5480           </ptrtype>
5481             <description>
5482               The callback function to be called for each heap root of type
5483               <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
5484               <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
5485               <code>JVMTI_HEAP_ROOT_MONITOR</code>,
5486               <code>JVMTI_HEAP_ROOT_THREAD</code>, or 
5487               <code>JVMTI_HEAP_ROOT_OTHER</code>.
5488             </description>
5489         </param>
5490         <param id="stack_ref_callback">
5491           <ptrtype>
5492             <struct>jvmtiStackReferenceCallback</struct>
5493             <nullok>do not report stack references</nullok>
5494           </ptrtype>
5495             <description>
5496               The callback function to be called for each heap root of
5497               <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5498               <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
5499             </description>
5500         </param>
5501         <param id="object_ref_callback">
5502           <ptrtype>
5503             <struct>jvmtiObjectReferenceCallback</struct>
5504             <nullok>do not follow references from the root objects</nullok>
5505           </ptrtype>
5506             <description>
5507               The callback function to be called for each object reference.
5508             </description>
5509         </param>
5510         <param id="user_data">
5511           <inbuf>
5512             <void/>
5513             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5514           </inbuf>
5515           <description>
5516             User supplied data to be passed to the callback. 
5517           </description>
5518         </param>
5519       </parameters>
5520       <errors>
5521       </errors>
5522     </function>
5523 
5524     <function id="IterateOverHeap" num="111">
5525       <synopsis>Iterate Over Heap</synopsis>
5526       <description>        
5527         Iterate over all objects in the heap. This includes both reachable and 
5528         unreachable objects.
5529         <p/>
5530         The <paramlink id="object_filter"></paramlink> parameter indicates the
5531         objects for which the callback function is called. If this parameter
5532         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 
5533         called for every object that is tagged. If the parameter is 
5534         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5535         for objects that are not tagged. If the parameter
5536         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5537         called for every object in the heap, irrespective of whether it is
5538         tagged or not.
5539         <p/>
5540         During the execution of this function the state of the heap
5541         does not change: no objects are allocated, no objects are
5542         garbage collected, and the state of objects (including 
5543         held values) does not change. 
5544         As a result, threads executing Java 
5545         programming language code, threads attempting to resume the
5546         execution of Java programming language code, and threads 
5547         attempting to execute JNI functions are typically stalled.
5548       </description>
5549       <origin>new</origin>
5550       <capabilities>
5551         <required id="can_tag_objects"></required>
5552       </capabilities>
5553       <parameters>
5554         <param id="object_filter">
5555           <enum>jvmtiHeapObjectFilter</enum>
5556           <description>
5557             Indicates the objects for which the callback function is called.
5558           </description>
5559         </param>
5560         <param id="heap_object_callback">
5561           <ptrtype>
5562             <struct>jvmtiHeapObjectCallback</struct>
5563           </ptrtype>
5564             <description>
5565               The iterator function to be called for each
5566               object matching the <paramlink id="object_filter"/>.
5567             </description>
5568         </param>
5569         <param id="user_data">
5570           <inbuf>
5571             <void/>
5572             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5573           </inbuf>
5574           <description>
5575             User supplied data to be passed to the callback. 
5576           </description>
5577         </param>
5578       </parameters>
5579       <errors>
5580       </errors>
5581     </function>
5582 
5583     <function id="IterateOverInstancesOfClass" num="112">
5584       <synopsis>Iterate Over Instances Of Class</synopsis>
5585       <description>
5586         Iterate over all objects in the heap that are instances of the specified class. 
5587         This includes direct instances of the specified class and 
5588         instances of all subclasses of the specified class.
5589         This includes both reachable and unreachable objects.
5590         <p/>
5591         The <paramlink id="object_filter"></paramlink> parameter indicates the
5592         objects for which the callback function is called. If this parameter
5593         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be 
5594         called for every object that is tagged. If the parameter is 
5595         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5596         called for objects that are not tagged. If the parameter
5597         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5598         called for every object in the heap, irrespective of whether it is
5599         tagged or not.
5600         <p/>
5601         During the execution of this function the state of the heap
5602         does not change: no objects are allocated, no objects are
5603         garbage collected, and the state of objects (including 
5604         held values) does not change. 
5605         As a result, threads executing Java 
5606         programming language code, threads attempting to resume the
5607         execution of Java programming language code, and threads 
5608         attempting to execute JNI functions are typically stalled.
5609       </description>
5610       <origin>new</origin>
5611       <capabilities>
5612         <required id="can_tag_objects"></required>
5613       </capabilities>
5614       <parameters>
5615         <param id="klass">
5616           <jclass/>
5617             <description>
5618               Iterate over objects of this class only.
5619             </description>
5620         </param>
5621         <param id="object_filter">
5622           <enum>jvmtiHeapObjectFilter</enum>
5623           <description>
5624             Indicates the objects for which the callback function is called.
5625           </description>
5626         </param>
5627         <param id="heap_object_callback">
5628           <ptrtype>
5629             <struct>jvmtiHeapObjectCallback</struct>
5630           </ptrtype>
5631             <description>
5632               The iterator function to be called for each
5633               <paramlink id="klass"/> instance matching 
5634               the <paramlink id="object_filter"/>.
5635             </description>
5636         </param>
5637         <param id="user_data">
5638           <inbuf>
5639             <void/>
5640             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5641           </inbuf>
5642           <description>
5643             User supplied data to be passed to the callback. 
5644           </description>
5645         </param>
5646       </parameters>
5647       <errors>
5648       </errors>
5649     </function>
5650 
5651   </category>
5652 
5653   <category id="local" label="Local Variable">
5654 
5655     <intro>
5656       These functions are used to retrieve or set the value of a local variable. 
5657       The variable is identified by the depth of the frame containing its
5658       value and the variable's slot number within that frame. 
5659       The mapping of variables to 
5660       slot numbers can be obtained with the function 
5661       <functionlink id="GetLocalVariableTable"></functionlink>.
5662     </intro>
5663 
5664     <function id="GetLocalObject" num="21">
5665       <synopsis>Get Local Variable - Object</synopsis>
5666       <description>
5667         This function can be used to retrieve the value of a local 
5668         variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 
5669       </description>
5670       <origin>jvmdi</origin>
5671       <capabilities>
5672         <required id="can_access_local_variables"></required>
5673       </capabilities>
5674       <parameters>
5675         <param id="thread">
5676           <jthread null="current" frame="frame"/>
5677           <description>
5678             The thread of the frame containing the variable's value.
5679           </description>
5680         </param>
5681         <param id="depth">
5682           <jframeID thread="thread"/>
5683           <description>
5684             The depth of the frame containing the variable's value.
5685           </description>
5686         </param>
5687         <param id="slot">
5688           <jint/>
5689           <description>
5690             The variable's slot number.
5691           </description>
5692         </param>
5693         <param id="value_ptr">
5694           <outptr><jobject/></outptr>
5695             <description>
5696               On return, points to the variable's value. 
5697             </description>
5698         </param>
5699       </parameters>
5700       <errors>
5701         <error id="JVMTI_ERROR_INVALID_SLOT">
5702           Invalid <code>slot</code>.
5703         </error>
5704         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5705           The variable type is not
5706           <code>Object</code> or a subclass of <code>Object</code>.
5707         </error>
5708         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5709           Not a visible frame
5710         </error>
5711       </errors>
5712     </function>
5713 
5714     <function id="GetLocalInstance" num="155" since="1.2">
5715       <synopsis>Get Local Instance</synopsis>
5716       <description>
5717         This function can be used to retrieve the value of the local object
5718         variable at slot 0 (the "<code>this</code>" object) from non-static
5719         frames.  This function can retrieve the "<code>this</code>" object from
5720         native method frames, whereas <code>GetLocalObject()</code> would 
5721         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5722       </description>
5723       <origin>new</origin>
5724       <capabilities>
5725         <required id="can_access_local_variables"></required>
5726       </capabilities>
5727       <parameters>
5728         <param id="thread">
5729           <jthread null="current" frame="frame"/>
5730           <description>
5731             The thread of the frame containing the variable's value.
5732           </description>
5733         </param>
5734         <param id="depth">
5735           <jframeID thread="thread"/>
5736           <description>
5737             The depth of the frame containing the variable's value.
5738           </description>
5739         </param>
5740         <param id="value_ptr">
5741           <outptr><jobject/></outptr>
5742             <description>
5743               On return, points to the variable's value. 
5744             </description>
5745         </param>
5746       </parameters>
5747       <errors>
5748         <error id="JVMTI_ERROR_INVALID_SLOT">
5749           If the specified frame is a static method frame.
5750         </error>
5751       </errors>
5752     </function>
5753     <function id="GetLocalInt" num="22">
5754       <synopsis>Get Local Variable - Int</synopsis>
5755       <description>
5756         This function can be used to retrieve the value of a local 
5757         variable whose type is <code>int</code>,
5758         <code>short</code>, <code>char</code>, <code>byte</code>, or 
5759         <code>boolean</code>. 
5760       </description>
5761       <origin>jvmdi</origin>
5762       <capabilities>
5763         <required id="can_access_local_variables"></required>
5764       </capabilities>
5765       <parameters>
5766         <param id="thread">
5767           <jthread null="current" frame="frame"/>
5768           <description>
5769             The thread of the frame containing the variable's value.
5770           </description>
5771         </param>
5772         <param id="depth">
5773           <jframeID thread="thread"/>
5774           <description>
5775             The depth of the frame containing the variable's value.
5776           </description>
5777         </param>
5778         <param id="slot">
5779           <jint/>
5780           <description>
5781             The variable's slot number.
5782           </description>
5783         </param>
5784         <param id="value_ptr">
5785           <outptr><jint/></outptr>
5786           <description>
5787             On return, points to the variable's value. 
5788           </description>
5789         </param>
5790       </parameters>
5791       <errors>
5792         <error id="JVMTI_ERROR_INVALID_SLOT">
5793           Invalid <code>slot</code>.
5794         </error>
5795         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5796           The variable type is not 
5797           <code>int</code>, <code>short</code>,
5798           <code>char</code>, <code>byte</code>, or 
5799           <code>boolean</code>.
5800         </error>
5801         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5802           Not a visible frame
5803         </error>
5804       </errors>
5805     </function>
5806 
5807     <function id="GetLocalLong" num="23">
5808       <synopsis>Get Local Variable - Long</synopsis>
5809       <description>
5810         This function can be used to retrieve the value of a local 
5811         variable whose type is <code>long</code>. 
5812       </description>
5813       <origin>jvmdi</origin>
5814       <capabilities>
5815         <required id="can_access_local_variables"></required>
5816       </capabilities>
5817       <parameters>
5818         <param id="thread">
5819           <jthread null="current" frame="frame"/>
5820           <description>
5821             The thread of the frame containing the variable's value.
5822           </description>
5823         </param>
5824         <param id="depth">
5825           <jframeID thread="thread"/>
5826           <description>
5827             The depth of the frame containing the variable's value.
5828           </description>
5829         </param>
5830         <param id="slot">
5831           <jint/>
5832           <description>
5833             The variable's slot number.
5834           </description>
5835         </param>
5836         <param id="value_ptr">
5837           <outptr><jlong/></outptr>
5838           <description>
5839             On return, points to the variable's value. 
5840           </description>
5841         </param>
5842       </parameters>
5843       <errors>
5844         <error id="JVMTI_ERROR_INVALID_SLOT">
5845           Invalid <code>slot</code>.
5846         </error>
5847         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5848           The variable type is not <code>long</code>.
5849         </error>
5850         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5851           Not a visible frame
5852         </error>
5853       </errors>
5854     </function>
5855 
5856     <function id="GetLocalFloat" num="24">
5857       <synopsis>Get Local Variable - Float</synopsis>
5858       <description>
5859         This function can be used to retrieve the value of a local 
5860         variable whose type is <code>float</code>. 
5861       </description>
5862       <origin>jvmdi</origin>
5863       <capabilities>
5864         <required id="can_access_local_variables"></required>
5865       </capabilities>
5866       <parameters>
5867         <param id="thread">
5868           <jthread null="current" frame="frame"/>
5869           <description>
5870             The thread of the frame containing the variable's value.
5871           </description>
5872         </param>
5873         <param id="depth">
5874           <jframeID thread="thread"/>
5875           <description>
5876             The depth of the frame containing the variable's value.
5877           </description>
5878         </param>
5879         <param id="slot">
5880           <jint/>
5881           <description>
5882             The variable's slot number.
5883           </description>
5884         </param>
5885         <param id="value_ptr">
5886           <outptr><jfloat/></outptr>
5887           <description>
5888             On return, points to the variable's value. 
5889           </description>
5890         </param>
5891       </parameters>
5892       <errors>
5893         <error id="JVMTI_ERROR_INVALID_SLOT">
5894           Invalid <code>slot</code>.
5895         </error>
5896         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5897           The variable type is not <code>float</code>.
5898         </error>
5899         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5900           Not a visible frame
5901         </error>
5902       </errors>
5903     </function>
5904 
5905     <function id="GetLocalDouble" num="25">
5906       <synopsis>Get Local Variable - Double</synopsis>
5907       <description>
5908         This function can be used to retrieve the value of a local 
5909         variable whose type is <code>long</code>. 
5910       </description>
5911       <origin>jvmdi</origin>
5912       <capabilities>
5913         <required id="can_access_local_variables"></required>
5914       </capabilities>
5915       <parameters>
5916         <param id="thread">
5917           <jthread null="current" frame="frame"/>
5918           <description>
5919             The thread of the frame containing the variable's value.
5920           </description>
5921         </param>
5922         <param id="depth">
5923           <jframeID thread="thread"/>
5924           <description>
5925             The depth of the frame containing the variable's value.
5926           </description>
5927         </param>
5928         <param id="slot">
5929           <jint/>
5930           <description>
5931             The variable's slot number.
5932           </description>
5933         </param>
5934         <param id="value_ptr">
5935           <outptr><jdouble/></outptr>
5936           <description>
5937             On return, points to the variable's value. 
5938           </description>
5939         </param>
5940       </parameters>
5941       <errors>
5942         <error id="JVMTI_ERROR_INVALID_SLOT">
5943           Invalid <code>slot</code>.
5944         </error>
5945         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
5946           The variable type is not <code>double</code>.
5947         </error>
5948         <error id="JVMTI_ERROR_OPAQUE_FRAME"> 
5949           Not a visible frame
5950         </error>
5951       </errors>
5952     </function>
5953 
5954     <function id="SetLocalObject" num="26">
5955       <synopsis>Set Local Variable - Object</synopsis>
5956       <description>
5957         This function can be used to set the value of a local 
5958         variable whose type is <code>Object</code> or a subclass of <code>Object</code>. 
5959       </description>
5960       <origin>jvmdi</origin>
5961       <capabilities>
5962         <required id="can_access_local_variables"></required>
5963       </capabilities>
5964       <parameters>
5965         <param id="thread">
5966           <jthread null="current" frame="frame"/>
5967           <description>
5968             The thread of the frame containing the variable's value.
5969           </description>
5970         </param>
5971         <param id="depth">
5972           <jframeID thread="thread"/>
5973           <description>
5974             The depth of the frame containing the variable's value.
5975           </description>
5976         </param>
5977         <param id="slot">
5978           <jint/>
5979           <description>
5980             The variable's slot number.
5981           </description>
5982         </param>
5983         <param id="value">
5984           <jobject/>
5985             <description>
5986               The new value for the variable.
5987             </description>
5988         </param>
5989       </parameters>
5990       <errors>
5991         <error id="JVMTI_ERROR_INVALID_SLOT">
5992           Invalid <code>slot</code>.
5993         </error>
5994         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5995           The variable type is not
5996           <code>Object</code> or a subclass of <code>Object</code>.
5997         </error>
5998         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5999           The supplied <paramlink id="value"/> is not compatible 
6000           with the variable type.
6001         </error>
6002         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6003           Not a visible frame
6004         </error>
6005       </errors>
6006     </function>
6007 
6008     <function id="SetLocalInt" num="27">
6009       <synopsis>Set Local Variable - Int</synopsis>
6010       <description>
6011         This function can be used to set the value of a local 
6012         variable whose type is <code>int</code>,
6013         <code>short</code>, <code>char</code>, <code>byte</code>, or 
6014         <code>boolean</code>. 
6015       </description>
6016       <origin>jvmdi</origin>
6017       <capabilities>
6018         <required id="can_access_local_variables"></required>
6019       </capabilities>
6020       <parameters>
6021         <param id="thread">
6022           <jthread null="current" frame="frame"/>
6023           <description>
6024             The thread of the frame containing the variable's value.
6025           </description>
6026         </param>
6027         <param id="depth">
6028           <jframeID thread="thread"/>
6029           <description>
6030             The depth of the frame containing the variable's value.
6031           </description>
6032         </param>
6033         <param id="slot">
6034           <jint/>
6035           <description>
6036             The variable's slot number.
6037           </description>
6038         </param>
6039         <param id="value">
6040           <jint/>
6041           <description>
6042             The new value for the variable.
6043           </description>
6044         </param>
6045       </parameters>
6046       <errors>
6047         <error id="JVMTI_ERROR_INVALID_SLOT">
6048           Invalid <code>slot</code>.
6049         </error>
6050         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6051           The variable type is not 
6052           <code>int</code>, <code>short</code>,
6053           <code>char</code>, <code>byte</code>, or 
6054           <code>boolean</code>.
6055         </error>
6056         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6057           Not a visible frame
6058         </error>
6059       </errors>
6060     </function>
6061 
6062     <function id="SetLocalLong" num="28">
6063       <synopsis>Set Local Variable - Long</synopsis>
6064       <description>
6065         This function can be used to set the value of a local 
6066         variable whose type is <code>long</code>. 
6067       </description>
6068       <origin>jvmdi</origin>
6069       <capabilities>
6070         <required id="can_access_local_variables"></required>
6071       </capabilities>
6072       <parameters>
6073         <param id="thread">
6074           <jthread null="current" frame="frame"/>
6075           <description>
6076             The thread of the frame containing the variable's value.
6077           </description>
6078         </param>
6079         <param id="depth">
6080           <jframeID thread="thread"/>
6081           <description>
6082             The depth of the frame containing the variable's value.
6083           </description>
6084         </param>
6085         <param id="slot">
6086           <jint/>
6087           <description>
6088             The variable's slot number.
6089           </description>
6090         </param>
6091         <param id="value">
6092           <jlong/>
6093           <description>
6094             The new value for the variable.
6095           </description>
6096         </param>
6097       </parameters>
6098       <errors>
6099         <error id="JVMTI_ERROR_INVALID_SLOT">
6100           Invalid <code>slot</code>.
6101         </error>
6102         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6103           The variable type is not <code>long</code>.
6104         </error>
6105         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6106           Not a visible frame
6107         </error>
6108       </errors>
6109     </function>
6110 
6111     <function id="SetLocalFloat" num="29">
6112       <synopsis>Set Local Variable - Float</synopsis>
6113       <description>
6114         This function can be used to set the value of a local 
6115         variable whose type is <code>float</code>. 
6116       </description>
6117       <origin>jvmdi</origin>
6118       <capabilities>
6119         <required id="can_access_local_variables"></required>
6120       </capabilities>
6121       <parameters>
6122         <param id="thread">
6123           <jthread null="current" frame="frame"/>
6124           <description>
6125             The thread of the frame containing the variable's value.
6126           </description>
6127         </param>
6128         <param id="depth">
6129           <jframeID thread="thread"/>
6130           <description>
6131             The depth of the frame containing the variable's value.
6132           </description>
6133         </param>
6134         <param id="slot">
6135           <jint/>
6136           <description>
6137             The variable's slot number.
6138           </description>
6139         </param>
6140         <param id="value">
6141           <jfloat/>
6142           <description>
6143             The new value for the variable.
6144           </description>
6145         </param>
6146       </parameters>
6147       <errors>
6148         <error id="JVMTI_ERROR_INVALID_SLOT">
6149           Invalid <code>slot</code>.
6150         </error>
6151         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6152           The variable type is not <code>float</code>.
6153         </error>
6154         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6155           Not a visible frame
6156         </error>
6157       </errors>
6158     </function>
6159 
6160     <function id="SetLocalDouble" num="30">
6161       <synopsis>Set Local Variable - Double</synopsis>
6162       <description>
6163         This function can be used to set the value of a local 
6164         variable whose type is <code>double</code>. 
6165       </description>
6166       <origin>jvmdi</origin>
6167       <capabilities>
6168         <required id="can_access_local_variables"></required>
6169       </capabilities>
6170       <parameters>
6171         <param id="thread">
6172           <jthread null="current" frame="frame"/>
6173           <description>
6174             The thread of the frame containing the variable's value.
6175           </description>
6176         </param>
6177         <param id="depth">
6178           <jframeID thread="thread"/>
6179           <description>
6180             The depth of the frame containing the variable's value.
6181           </description>
6182         </param>
6183         <param id="slot">
6184           <jint/>
6185           <description>
6186             The variable's slot number.
6187           </description>
6188         </param>
6189         <param id="value">
6190           <jdouble/>
6191           <description>
6192             The new value for the variable.
6193           </description>
6194         </param>
6195       </parameters>
6196       <errors>
6197         <error id="JVMTI_ERROR_INVALID_SLOT">
6198           Invalid <code>slot</code>.
6199         </error>
6200         <error id="JVMTI_ERROR_TYPE_MISMATCH"> 
6201           The variable type is not <code>double</code>.
6202         </error>
6203         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6204           Not a visible frame
6205         </error>
6206       </errors>
6207     </function>
6208   </category>
6209 
6210   <category id="breakpointCategory" label="Breakpoint">
6211 
6212     <intro>
6213     </intro>
6214 
6215     <function id="SetBreakpoint" num="38">
6216       <synopsis>Set Breakpoint</synopsis>
6217       <description>
6218         Set a breakpoint at the instruction indicated by
6219         <code>method</code> and <code>location</code>.
6220         An instruction can only have one breakpoint.
6221         <p/>
6222         Whenever the designated instruction is about to be executed, a
6223         <eventlink id="Breakpoint"></eventlink> event is generated.
6224       </description>
6225       <origin>jvmdi</origin>
6226       <capabilities>
6227         <required id="can_generate_breakpoint_events"></required>
6228       </capabilities>
6229       <parameters>
6230         <param id="klass">
6231           <jclass method="method"/>
6232             <description>
6233               The class in which to set the breakpoint
6234             </description>
6235         </param>
6236         <param id="method">
6237           <jmethodID class="klass"/>
6238             <description>
6239               The method in which to set the breakpoint
6240             </description>
6241         </param>
6242         <param id="location">
6243           <jlocation/>
6244           <description>
6245             the index of the instruction at which to set the breakpoint
6246 
6247           </description>
6248         </param>
6249       </parameters>
6250       <errors>
6251         <error id="JVMTI_ERROR_DUPLICATE"> 
6252           The designated bytecode already has a breakpoint.
6253         </error>
6254       </errors>
6255     </function>
6256 
6257     <function id="ClearBreakpoint" num="39">
6258       <synopsis>Clear Breakpoint</synopsis>
6259       <description>
6260         Clear the breakpoint at the bytecode indicated by
6261         <code>method</code> and <code>location</code>.
6262       </description>
6263       <origin>jvmdi</origin>
6264       <capabilities>
6265         <required id="can_generate_breakpoint_events"></required>
6266       </capabilities>
6267       <parameters>
6268         <param id="klass">
6269           <jclass method="method"/>
6270             <description>
6271               The class in which to clear the breakpoint
6272             </description>
6273         </param>
6274         <param id="method">
6275           <jmethodID class="klass"/>
6276             <description>
6277               The method in which to clear the breakpoint
6278             </description>
6279         </param>
6280         <param id="location">
6281           <jlocation/>
6282           <description>
6283             the index of the instruction at which to clear the breakpoint
6284           </description>
6285         </param>
6286       </parameters>
6287       <errors>
6288         <error id="JVMTI_ERROR_NOT_FOUND"> 
6289           There's no breakpoint at the designated bytecode.
6290         </error>
6291       </errors>
6292     </function>
6293 
6294   </category>
6295 
6296   <category id="fieldWatch" label="Watched Field">
6297 
6298     <intro>
6299     </intro>
6300 
6301     <function id="SetFieldAccessWatch" num="41">
6302       <synopsis>Set Field Access Watch</synopsis>
6303       <description>
6304         Generate a <eventlink id="FieldAccess"></eventlink> event
6305         when the field specified
6306         by <code>klass</code> and
6307         <code>field</code> is about to be accessed.
6308         An event will be generated for each access of the field
6309         until it is canceled with 
6310         <functionlink id="ClearFieldAccessWatch"></functionlink>.
6311         Field accesses from Java programming language code or from JNI code are watched,
6312         fields modified by other means are not watched.
6313         Note that <jvmti/> users should be aware that their own field accesses
6314         will trigger the watch.
6315         A field can only have one field access watch set.
6316         Modification of a field is not considered an access--use 
6317         <functionlink id="SetFieldModificationWatch"></functionlink>
6318         to monitor modifications.
6319       </description>
6320       <origin>jvmdi</origin>
6321       <capabilities>
6322         <required id="can_generate_field_access_events"></required>
6323       </capabilities>
6324       <parameters>
6325         <param id="klass">
6326           <jclass field="field"/>
6327             <description>
6328               The class containing the field to watch
6329             </description>
6330         </param>
6331         <param id="field">
6332           <jfieldID class="klass"/>
6333             <description>
6334               The field to watch
6335 
6336             </description>
6337         </param>
6338       </parameters>
6339       <errors>
6340         <error id="JVMTI_ERROR_DUPLICATE"> 
6341           The designated field is already being watched for accesses.
6342         </error>
6343       </errors>
6344     </function>
6345 
6346     <function id="ClearFieldAccessWatch" num="42">
6347       <synopsis>Clear Field Access Watch</synopsis>
6348       <description>
6349         Cancel a field access watch previously set by 
6350         <functionlink id="SetFieldAccessWatch"></functionlink>, on the 
6351         field specified
6352         by <code>klass</code> and
6353         <code>field</code>.
6354       </description>
6355       <origin>jvmdi</origin>
6356       <capabilities>
6357         <required id="can_generate_field_access_events"></required>
6358       </capabilities>
6359       <parameters>
6360         <param id="klass">
6361           <jclass field="field"/>
6362             <description>
6363               The class containing the field to watch
6364             </description>
6365         </param>
6366         <param id="field">
6367           <jfieldID class="klass"/>
6368             <description>
6369               The field to watch
6370 
6371             </description>
6372         </param>
6373       </parameters>
6374       <errors>
6375         <error id="JVMTI_ERROR_NOT_FOUND"> 
6376           The designated field is not being watched for accesses.
6377         </error>
6378       </errors>
6379     </function>
6380 
6381     <function id="SetFieldModificationWatch" num="43">
6382       <synopsis>Set Field Modification Watch</synopsis>
6383       <description>
6384         Generate a <eventlink id="FieldModification"></eventlink> event
6385         when the field specified
6386         by <code>klass</code> and
6387         <code>field</code> is about to be modified.
6388         An event will be generated for each modification of the field
6389         until it is canceled with 
6390         <functionlink id="ClearFieldModificationWatch"></functionlink>.
6391         Field modifications from Java programming language code or from JNI code are watched,
6392         fields modified by other means are not watched.
6393         Note that <jvmti/> users should be aware that their own field modifications
6394         will trigger the watch.
6395         A field can only have one field modification watch set.
6396       </description>
6397       <origin>jvmdi</origin>
6398       <capabilities>
6399         <required id="can_generate_field_modification_events"></required>
6400       </capabilities>
6401       <parameters>
6402         <param id="klass">
6403           <jclass field="field"/>
6404             <description>
6405               The class containing the field to watch
6406             </description>
6407         </param>
6408         <param id="field">
6409           <jfieldID class="klass"/>
6410             <description>
6411               The field to watch
6412 
6413             </description>
6414         </param>
6415       </parameters>
6416       <errors>
6417         <error id="JVMTI_ERROR_DUPLICATE"> 
6418           The designated field is already being watched for modifications.
6419         </error>
6420       </errors>
6421     </function>
6422 
6423     <function id="ClearFieldModificationWatch" num="44">
6424       <synopsis>Clear Field Modification Watch</synopsis>
6425       <description>
6426 
6427         Cancel a field modification watch previously set by 
6428         <functionlink id="SetFieldModificationWatch"></functionlink>, on the 
6429         field specified
6430         by <code>klass</code> and
6431         <code>field</code>.
6432       </description>
6433       <origin>jvmdi</origin>
6434       <capabilities>
6435         <required id="can_generate_field_modification_events"></required>
6436       </capabilities>
6437       <parameters>
6438         <param id="klass">
6439           <jclass field="field"/>
6440             <description>
6441               The class containing the field to watch
6442             </description>
6443         </param>
6444         <param id="field">
6445           <jfieldID class="klass"/>
6446             <description>
6447               The field to watch
6448 
6449             </description>
6450         </param>
6451       </parameters>
6452       <errors>
6453         <error id="JVMTI_ERROR_NOT_FOUND"> 
6454           The designated field is not being watched for modifications.
6455         </error>
6456       </errors>
6457     </function>
6458   </category>
6459 
6460   <category id="class" label="Class">
6461 
6462     <intro>
6463     </intro>
6464 
6465     <function id="GetLoadedClasses" jkernel="yes" num="78">
6466       <synopsis>Get Loaded Classes</synopsis>
6467       <description>
6468         Return an array of all classes loaded in the virtual machine.
6469         The number of classes in the array is returned via
6470         <code>class_count_ptr</code>, and the array itself via
6471         <code>classes_ptr</code>.
6472         <p/>
6473         Array classes of all types (including arrays of primitive types) are 
6474         included in the returned list. Primitive classes (for example, 
6475         <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list. 
6476       </description>
6477       <origin>jvmdi</origin>
6478       <capabilities>
6479       </capabilities>
6480       <parameters>
6481         <param id="class_count_ptr">
6482           <outptr><jint/></outptr>
6483           <description>
6484             On return, points to the number of classes.
6485           </description>
6486         </param>
6487         <param id="classes_ptr">
6488           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6489             <description>
6490               On return, points to an array of references, one
6491               for each class.
6492             </description>
6493         </param>
6494       </parameters>
6495       <errors>
6496       </errors>
6497     </function>
6498 
6499     <function id="GetClassLoaderClasses" jkernel="yes" num="79">
6500       <synopsis>Get Classloader Classes</synopsis>
6501       <description>
6502         Returns an array of those classes for which this class loader has
6503         been recorded as an initiating loader. Each 
6504         class in the returned array was created by this class loader, 
6505         either by defining it directly or by delegation to another class loader.
6506         See <vmspec chapter="5.3"/>.
6507         <p/>
6508         For JDK version 1.1 implementations that don't
6509         recognize the distinction between initiating and defining class loaders,
6510         this function should return all classes loaded in the virtual machine.
6511         The number of classes in the array is returned via
6512         <code>class_count_ptr</code>, and the array itself via
6513         <code>classes_ptr</code>.
6514       </description>
6515       <origin>jvmdi</origin>
6516       <capabilities>
6517       </capabilities>
6518       <parameters>
6519         <param id="initiating_loader">
6520           <ptrtype>
6521             <jobject/>
6522             <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
6523           </ptrtype>
6524             <description>
6525               An initiating class loader.
6526             </description>
6527         </param>
6528         <param id="class_count_ptr">
6529           <outptr><jint/></outptr>
6530           <description>
6531             On return, points to the number of classes.
6532           </description>
6533         </param>
6534         <param id="classes_ptr">
6535           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6536             <description>
6537               On return, points to an array of references, one
6538               for each class.
6539             </description>
6540         </param>
6541       </parameters>
6542       <errors>
6543       </errors>
6544     </function>
6545 
6546     <function id="GetClassSignature" phase="start" num="48">
6547       <synopsis>Get Class Signature</synopsis>
6548       <description>
6549         For the class indicated by <code>klass</code>, return the 
6550         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp16432">JNI 
6551             type signature</externallink> 
6552         and the generic signature of the class.
6553         For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
6554         and <code>int[]</code> is <code>"[I"</code>
6555         The returned name for primitive classes
6556         is the type signature character of the corresponding primitive type. 
6557         For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
6558       </description>
6559       <origin>jvmdiClone</origin>
6560       <capabilities>
6561       </capabilities>
6562       <parameters>
6563         <param id="klass">
6564           <jclass/>
6565             <description>
6566               The class to query.
6567             </description>
6568         </param>
6569         <param id="signature_ptr">
6570           <allocbuf>
6571             <char/>           
6572             <nullok>the signature is not returned</nullok>
6573           </allocbuf>
6574           <description>
6575             On return, points to the JNI type signature of the class, encoded as a
6576             <internallink id="mUTF">modified UTF-8</internallink> string.
6577           </description>
6578         </param>
6579         <param id="generic_ptr">
6580           <allocbuf>
6581             <char/>           
6582             <nullok>the generic signature is not returned</nullok>
6583           </allocbuf>
6584           <description>
6585             On return, points to the generic signature of the class, encoded as a
6586             <internallink id="mUTF">modified UTF-8</internallink> string.
6587             If there is no generic signature attribute for the class, then,
6588             on return, points to <code>NULL</code>. 
6589           </description>
6590         </param>
6591       </parameters>
6592       <errors>
6593       </errors>
6594     </function>
6595 
6596     <function id="GetClassStatus" phase="start" num="49">
6597       <synopsis>Get Class Status</synopsis>
6598       <description>
6599         Get the status of the class. Zero or more of the following bits can be 
6600         set.
6601         <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
6602           <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
6603             Class bytecodes have been verified
6604           </constant>
6605           <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
6606             Class preparation is complete
6607           </constant>
6608           <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
6609             Class initialization is complete. Static initializer has been run.
6610           </constant>
6611           <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
6612             Error during initialization makes class unusable
6613           </constant>
6614           <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
6615             Class is an array.  If set, all other bits are zero.
6616           </constant>
6617           <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
6618             Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).  
6619             If set, all other bits are zero.
6620           </constant>
6621         </constants>
6622       </description>
6623       <origin>jvmdi</origin>
6624       <capabilities>
6625       </capabilities>
6626       <parameters>
6627         <param id="klass">
6628           <jclass/>
6629             <description>
6630               The class to query.
6631             </description>
6632         </param>
6633         <param id="status_ptr">
6634           <outptr><jint/></outptr>
6635           <description>
6636             On return, points to the current state of this class as one or 
6637             more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
6638           </description>
6639         </param>
6640       </parameters>
6641       <errors>
6642       </errors>
6643     </function>
6644 
6645     <function id="GetSourceFileName" phase="start" num="50">
6646       <synopsis>Get Source File Name</synopsis>
6647       <description>
6648         For the class indicated by <code>klass</code>, return the source file
6649         name via <code>source_name_ptr</code>. The returned string 
6650         is a file name only and never contains a directory name. 
6651         <p/>
6652         For primitive classes (for example, <code>java.lang.Integer.TYPE</code>) 
6653         and for arrays this function returns 
6654         <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
6655       </description>
6656       <origin>jvmdi</origin>
6657       <capabilities>
6658         <required id="can_get_source_file_name"></required>
6659       </capabilities>
6660       <parameters>
6661         <param id="klass">
6662           <jclass/>
6663             <description>
6664               The class to query.
6665             </description>
6666         </param>
6667         <param id="source_name_ptr">
6668           <allocbuf><char/></allocbuf>
6669           <description>
6670             On return, points to the class's source file name, encoded as a
6671             <internallink id="mUTF">modified UTF-8</internallink> string.
6672           </description>
6673         </param>
6674       </parameters>
6675       <errors>
6676         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
6677           Class information does not include a source file name. This includes
6678           cases where the class is an array class or primitive class.
6679         </error>
6680       </errors>
6681     </function>
6682 
6683     <function id="GetClassModifiers" phase="start" num="51">
6684       <synopsis>Get Class Modifiers</synopsis>
6685       <description>
6686         For the class indicated by <code>klass</code>, return the access
6687         flags
6688         via <code>modifiers_ptr</code>.
6689         Access flags are defined in <vmspec chapter="4"/>.
6690         <p/>
6691         If the class is an array class, then its public, private, and protected 
6692         modifiers are the same as those of its component type. For arrays of 
6693         primitives, this component type is represented by one of the primitive 
6694         classes (for example, <code>java.lang.Integer.TYPE</code>). 
6695         <p/>
6696         If the class is a primitive class, its public modifier is always true, 
6697         and its protected and private modifiers are always false. 
6698         <p/>
6699         If the class is an array class or a primitive class then its final 
6700         modifier is always true and its interface modifier is always false. 
6701         The values of its other modifiers are not determined by this specification. 
6702 
6703       </description>
6704       <origin>jvmdi</origin>
6705       <capabilities>
6706       </capabilities>
6707       <parameters>
6708         <param id="klass">
6709           <jclass/>
6710             <description>
6711               The class to query.
6712             </description>
6713         </param>
6714         <param id="modifiers_ptr">
6715           <outptr><jint/></outptr>
6716           <description>
6717             On return, points to the current access flags of this class.
6718 
6719           </description>
6720         </param>
6721       </parameters>
6722       <errors>
6723       </errors>
6724     </function>
6725 
6726     <function id="GetClassMethods" phase="start" num="52">
6727       <synopsis>Get Class Methods</synopsis>
6728       <description>
6729         For the class indicated by <code>klass</code>, return a count of
6730         methods via <code>method_count_ptr</code> and a list of
6731         method IDs via <code>methods_ptr</code>. The method list contains 
6732         constructors and static initializers as well as true methods.
6733         Only directly declared methods are returned (not inherited methods).
6734         An empty method list is returned for array classes and primitive classes
6735         (for example, <code>java.lang.Integer.TYPE</code>).
6736       </description>
6737       <origin>jvmdi</origin>
6738       <capabilities>
6739         <capability id="can_maintain_original_method_order"/>
6740       </capabilities>
6741       <parameters>
6742         <param id="klass">
6743           <jclass/>
6744             <description>
6745               The class to query.
6746             </description>
6747         </param>
6748         <param id="method_count_ptr">
6749           <outptr><jint/></outptr>
6750           <description>
6751             On return, points to the number of methods declared in this class.
6752           </description>
6753         </param>
6754         <param id="methods_ptr">
6755           <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
6756             <description>
6757               On return, points to the method ID array.
6758             </description>
6759         </param>
6760       </parameters>
6761       <errors>
6762         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
6763           <paramlink id="klass"></paramlink> is not prepared.
6764         </error>
6765       </errors>
6766     </function>
6767 
6768     <function id="GetClassFields" phase="start" num="53">
6769       <synopsis>Get Class Fields</synopsis>
6770       <description>
6771         For the class indicated by <code>klass</code>, return a count of fields
6772         via <code>field_count_ptr</code> and a list of field IDs via
6773         <code>fields_ptr</code>.
6774         Only directly declared fields are returned (not inherited fields).
6775         Fields are returned in the order they occur in the class file.
6776         An empty field list is returned for array classes and primitive classes
6777         (for example, <code>java.lang.Integer.TYPE</code>).
6778         Use JNI to determine the length of an array.
6779       </description>
6780       <origin>jvmdi</origin>
6781       <capabilities>
6782       </capabilities>
6783       <parameters>
6784         <param id="klass">
6785           <jclass/>
6786             <description>
6787               The class to query.
6788             </description>
6789         </param>
6790         <param id="field_count_ptr">
6791           <outptr><jint/></outptr>
6792           <description>
6793             On return, points to the number of fields declared in this class.
6794           </description>
6795         </param>
6796         <param id="fields_ptr">
6797           <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
6798             <description>
6799               On return, points to the field ID array.
6800             </description>
6801         </param>
6802       </parameters>
6803       <errors>
6804         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 
6805           <paramlink id="klass"></paramlink> is not prepared.
6806         </error>
6807       </errors>
6808     </function>
6809 
6810     <function id="GetImplementedInterfaces" phase="start" num="54">
6811       <synopsis>Get Implemented Interfaces</synopsis>
6812       <description>
6813         Return the direct super-interfaces of this class. For a class, this 
6814         function returns the interfaces declared in its <code>implements</code>
6815         clause. For an interface, this function returns the interfaces declared in
6816         its <code>extends</code> clause.
6817         An empty interface list is returned for array classes and primitive classes
6818         (for example, <code>java.lang.Integer.TYPE</code>).
6819       </description>
6820       <origin>jvmdi</origin>
6821       <capabilities>
6822       </capabilities>
6823       <parameters>
6824         <param id="klass">
6825           <jclass/>
6826             <description>
6827               The class to query.
6828             </description>
6829         </param>
6830         <param id="interface_count_ptr">
6831           <outptr><jint/></outptr>
6832           <description>
6833             On return, points to the number of interfaces.
6834           </description>
6835         </param>
6836         <param id="interfaces_ptr">
6837           <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
6838             <description>
6839               On return, points to the interface array.
6840             </description>
6841         </param>
6842       </parameters>
6843       <errors>
6844         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED"> 
6845           <paramlink id="klass"></paramlink> is not prepared.
6846         </error>
6847       </errors>
6848     </function>
6849 
6850     <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
6851       <synopsis>Get Class Version Numbers</synopsis>
6852       <description>
6853         For the class indicated by <code>klass</code>, 
6854         return the minor and major version numbers,
6855         as defined in
6856         <vmspec chapter="4"/>. 
6857       </description>
6858       <origin>new</origin>
6859       <capabilities>
6860       </capabilities>
6861       <parameters>
6862         <param id="klass">
6863           <jclass/>
6864             <description>
6865               The class to query.
6866             </description>
6867         </param>
6868         <param id="minor_version_ptr">
6869           <outptr><jint/></outptr>
6870           <description>
6871             On return, points to the value of the
6872             <code>minor_version</code> item of the 
6873             Class File Format.
6874             Note: to be consistent with the Class File Format,
6875             the minor version number is the first parameter.
6876           </description>
6877         </param>
6878         <param id="major_version_ptr">
6879           <outptr><jint/></outptr>
6880           <description>
6881             On return, points to the value of the
6882             <code>major_version</code> item of the 
6883             Class File Format.
6884           </description>
6885         </param>
6886       </parameters>
6887       <errors>
6888         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
6889           The class is a primitive or array class.
6890         </error>
6891       </errors>
6892     </function>
6893 
6894     <function id="GetConstantPool" phase="start" num="146" since="1.1">
6895       <synopsis>Get Constant Pool</synopsis>
6896       <description>
6897         For the class indicated by <code>klass</code>, 
6898         return the raw bytes of the constant pool in the format of the
6899         <code>constant_pool</code> item of 
6900         <vmspec chapter="4"/>.
6901         The format of the constant pool may differ between versions
6902         of the Class File Format, so, the 
6903         <functionlink id="GetClassVersionNumbers">minor and major 
6904         class version numbers</functionlink> should be checked for
6905         compatibility.
6906         <p/>
6907         The returned constant pool might not have the same layout or
6908         contents as the constant pool in the defining class file.
6909         The constant pool returned by GetConstantPool() may have
6910         more or fewer entries than the defining constant pool.
6911         Entries may be in a different order.
6912         The constant pool returned by GetConstantPool() will match the
6913         constant pool used by 
6914         <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
6915         That is, the bytecodes returned by GetBytecodes() will have
6916         constant pool indices which refer to constant pool entries returned
6917         by GetConstantPool().
6918         Note that since <functionlink id="RetransformClasses"/> 
6919         and <functionlink id="RedefineClasses"/> can change 
6920         the constant pool, the constant pool returned by this function
6921         can change accordingly.  Thus, the correspondence between 
6922         GetConstantPool() and GetBytecodes() does not hold if there
6923         is an intervening class retransformation or redefinition. 
6924         The value of a constant pool entry used by a given bytecode will
6925         match that of the defining class file (even if the indices don't match).
6926         Constant pool entries which are not used directly or indirectly by
6927         bytecodes (for example,  UTF-8 strings associated with annotations) are
6928         not  required to exist in the returned constant pool.
6929       </description>
6930       <origin>new</origin>
6931       <capabilities>
6932         <required id="can_get_constant_pool"></required>
6933       </capabilities>
6934       <parameters>
6935         <param id="klass">
6936           <jclass/>
6937             <description>
6938               The class to query.
6939             </description>
6940         </param>
6941         <param id="constant_pool_count_ptr">
6942           <outptr><jint/></outptr>
6943           <description>
6944             On return, points to the number of entries
6945             in the constant pool table plus one.
6946             This corresponds to the <code>constant_pool_count</code>
6947             item of the Class File Format.
6948           </description>
6949         </param>
6950         <param id="constant_pool_byte_count_ptr">
6951           <outptr><jint/></outptr>
6952           <description>
6953             On return, points to the number of bytes
6954             in the returned raw constant pool.
6955           </description>
6956         </param>
6957         <param id="constant_pool_bytes_ptr">
6958           <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
6959             <description>
6960               On return, points to the raw constant pool, that is the bytes
6961               defined by the <code>constant_pool</code> item of the 
6962               Class File Format
6963             </description>
6964         </param>
6965       </parameters>
6966       <errors>
6967         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
6968           The class is a primitive or array class.
6969         </error>
6970       </errors>
6971     </function>
6972 
6973     <function id="IsInterface" phase="start" num="55">
6974       <synopsis>Is Interface</synopsis>
6975       <description>
6976         Determines whether a class object reference represents an interface.
6977         The <code>jboolean</code> result is
6978         <code>JNI_TRUE</code> if the "class" is actually an interface,
6979         <code>JNI_FALSE</code> otherwise. 
6980       </description>
6981       <origin>jvmdi</origin>
6982       <capabilities>
6983       </capabilities>
6984       <parameters>
6985         <param id="klass">
6986           <jclass/>
6987             <description>
6988               The class to query.
6989             </description>
6990         </param>
6991         <param id="is_interface_ptr">
6992           <outptr><jboolean/></outptr>
6993           <description>
6994             On return, points to the boolean result of this function.
6995 
6996           </description>
6997         </param>
6998       </parameters>
6999       <errors>
7000       </errors>
7001     </function>
7002 
7003     <function id="IsArrayClass" phase="start" num="56">
7004       <synopsis>Is Array Class</synopsis>
7005       <description>
7006         Determines whether a class object reference represents an array.
7007         The <code>jboolean</code> result is
7008         <code>JNI_TRUE</code> if the class is an array,
7009         <code>JNI_FALSE</code> otherwise. 
7010       </description>
7011       <origin>jvmdi</origin>
7012       <capabilities>
7013       </capabilities>
7014       <parameters>
7015         <param id="klass">
7016           <jclass/>
7017             <description>
7018               The class to query.
7019             </description>
7020         </param>
7021         <param id="is_array_class_ptr">
7022           <outptr><jboolean/></outptr>
7023           <description>
7024             On return, points to the boolean result of this function.
7025 
7026           </description>
7027         </param>
7028       </parameters>
7029       <errors>
7030       </errors>
7031     </function>
7032 
7033     <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
7034       <synopsis>Is Modifiable Class</synopsis>
7035       <description>
7036         Determines whether a class is modifiable.
7037         If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
7038         returns <code>JNI_TRUE</code>) the class can be
7039         redefined with <functionlink id="RedefineClasses"/> (assuming 
7040         the agent possesses the
7041         <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
7042         capability) or
7043         retransformed with <functionlink id="RetransformClasses"/> (assuming 
7044         the agent possesses the
7045         <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
7046         capability).
7047         If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
7048         returns <code>JNI_FALSE</code>) the class can be neither
7049         redefined nor retransformed.
7050         <p/>
7051         Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) 
7052         and array classes are never modifiable. 
7053         <p/>
7054       </description>
7055       <origin>new</origin>
7056       <capabilities>
7057         <capability id="can_redefine_any_class">
7058           If possessed then all classes (except primitive and array classes) 
7059           are modifiable.
7060         </capability>
7061         <capability id="can_redefine_classes">
7062           No effect on the result of the function.
7063           But must additionally be possessed to modify the class with
7064           <functionlink id="RedefineClasses"/>.
7065         </capability>
7066         <capability id="can_retransform_classes">
7067           No effect on the result of the function.
7068           But must additionally be possessed to modify the class with
7069           <functionlink id="RetransformClasses"/>.
7070         </capability>
7071       </capabilities>
7072       <parameters>
7073         <param id="klass">
7074           <jclass/>
7075             <description>
7076               The class to query.
7077             </description>
7078         </param>
7079         <param id="is_modifiable_class_ptr">
7080           <outptr><jboolean/></outptr>
7081           <description>
7082             On return, points to the boolean result of this function.
7083           </description>
7084         </param>
7085       </parameters>
7086       <errors>
7087       </errors>
7088     </function>
7089 
7090     <function id="GetClassLoader" phase="start" num="57">
7091       <synopsis>Get Class Loader</synopsis>
7092       <description>
7093         For the class indicated by <code>klass</code>, return via
7094         <code>classloader_ptr</code> a reference to the class loader for the
7095         class.
7096       </description>
7097       <origin>jvmdi</origin>
7098       <capabilities>
7099       </capabilities>
7100       <parameters>
7101         <param id="klass">
7102           <jclass/>
7103             <description>
7104               The class to query.
7105             </description>
7106         </param>
7107         <param id="classloader_ptr">
7108           <outptr><jobject/></outptr>
7109             <description>
7110               On return, points to the class loader that loaded
7111               this class.
7112               If the class was not created by a class loader
7113               or if the class loader is the bootstrap class loader,
7114               points to <code>NULL</code>.
7115             </description>
7116         </param>
7117       </parameters>
7118       <errors>
7119       </errors>
7120 
7121     </function>
7122 
7123     <function id="GetSourceDebugExtension" phase="start" num="90">
7124       <synopsis>Get Source Debug Extension</synopsis>
7125       <description>
7126         For the class indicated by <code>klass</code>, return the debug 
7127         extension via <code>source_debug_extension_ptr</code>.
7128         The returned string 
7129         contains exactly the debug extension information present in the
7130         class file of <code>klass</code>. 
7131       </description>
7132       <origin>jvmdi</origin>
7133       <capabilities>
7134         <required id="can_get_source_debug_extension"></required>
7135       </capabilities>
7136       <parameters>
7137         <param id="klass">
7138           <jclass/>
7139             <description>
7140               The class to query.
7141             </description>
7142         </param>
7143         <param id="source_debug_extension_ptr">
7144           <allocbuf><char/></allocbuf>
7145           <description>
7146             On return, points to the class's debug extension, encoded as a
7147             <internallink id="mUTF">modified UTF-8</internallink> string.
7148           </description>
7149         </param>
7150       </parameters>
7151       <errors>
7152         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
7153           Class information does not include a debug extension.
7154         </error>
7155       </errors>
7156     </function>
7157 
7158     <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
7159       <synopsis>Retransform Classes</synopsis>
7160       <description>
7161         This function facilitates the 
7162         <internallink id="bci">bytecode instrumentation</internallink>
7163         of already loaded classes.
7164         To replace the class definition without reference to the existing
7165         bytecodes, as one might do when recompiling from source for 
7166         fix-and-continue debugging, <functionlink id="RedefineClasses"/>
7167         function should be used instead.
7168         <p/>
7169         When classes are initially loaded or when they are 
7170         <functionlink id="RedefineClasses">redefined</functionlink>,
7171         the initial class file bytes can be transformed with the
7172         <eventlink id="ClassFileLoadHook"/> event.
7173         This function reruns the transformation process
7174         (whether or not a transformation has previously occurred).
7175         This retransformation follows these steps:
7176         <ul>
7177           <li>starting from the initial class file bytes 
7178           </li>
7179           <li>for each <fieldlink id="can_retransform_classes"
7180                      struct="jvmtiCapabilities">retransformation
7181                                                 incapable</fieldlink>
7182             agent which received a
7183             <code>ClassFileLoadHook</code> event during the previous
7184             load or redefine, the bytes it returned 
7185             (via the <code>new_class_data</code> parameter)
7186             are reused as the output of the transformation; 
7187             note that this is equivalent to reapplying
7188             the previous transformation, unaltered. except that
7189             the <code>ClassFileLoadHook</code> event
7190             is <b>not</b> sent to these agents
7191           </li>
7192           <li>for each <fieldlink id="can_retransform_classes"
7193                      struct="jvmtiCapabilities">retransformation
7194                                                 capable</fieldlink>
7195             agent, the <code>ClassFileLoadHook</code> event is sent,
7196             allowing a new transformation to be applied
7197           </li>
7198           <li>the transformed class file bytes are installed as the new
7199             definition of the class
7200           </li>
7201         </ul>
7202         See the <eventlink id="ClassFileLoadHook"/> event for more details.
7203         <p/>
7204         The initial class file bytes represent the bytes passed to 
7205         <code>ClassLoader.defineClass</code>
7206         or <code>RedefineClasses</code> (before any transformations
7207         were applied), however they may not exactly match them.
7208         The constant pool may differ in ways described in
7209         <functionlink id="GetConstantPool"/>.
7210         Constant pool indices in the bytecodes of methods will correspond.
7211         Some attributes may not be present.
7212         Where order is not meaningful, for example the order of methods,
7213         order may not be preserved.
7214         <p/>
7215         Retransformation can cause new versions of methods to be installed.
7216         Old method versions may become 
7217         <internallink id="obsoleteMethods">obsolete</internallink>
7218         The new method version will be used on new invokes.  
7219         If a method has active stack frames, those active frames continue to
7220         run the bytecodes of the original method version. 
7221         <p/>
7222         This function does not cause any initialization except that which 
7223         would occur under the customary JVM semantics.
7224         In other words, retransforming a class does not cause its initializers to be
7225         run. The values of static fields will remain as they were
7226         prior to the call.
7227         <p/>
7228         Threads need not be suspended.
7229         <p/>
7230         All breakpoints in the class are cleared.
7231         <p/>
7232         All attributes are updated.
7233         <p/>
7234         Instances of the retransformed class are not affected -- fields retain their
7235         previous values.  
7236         <functionlink id="GetTag">Tags</functionlink> on the instances are
7237         also unaffected.
7238         <p/>
7239         In response to this call, no events other than the
7240         <eventlink id="ClassFileLoadHook"/> event
7241         will be sent.
7242         <p/>
7243         The retransformation may change method bodies, the constant pool and attributes.
7244         The retransformation must not add, remove or rename fields or methods, change the 
7245         signatures of methods, change modifiers, or change inheritance.  
7246         These restrictions may be lifted in future versions.
7247         See the error return description below for information on error codes
7248         returned if an unsupported retransformation is attempted.
7249         The class file bytes are not verified or installed until they have passed
7250         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7251         returned error code reflects the result of the transformations.
7252         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7253         none of the classes to be retransformed will have a new definition installed.
7254         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7255         all of the classes to be retransformed will have their new definitions installed.        
7256       </description>
7257       <origin>new</origin>
7258       <capabilities>
7259         <required id="can_retransform_classes"></required>
7260         <capability id="can_retransform_any_class"></capability>
7261       </capabilities>
7262       <parameters>
7263         <param id="class_count">
7264           <jint min="0"/>
7265           <description>
7266             The number of classes to be retransformed.
7267           </description>
7268         </param>
7269         <param id="classes">
7270           <inbuf incount="class_count"><jclass/></inbuf>
7271           <description>
7272             The array of classes to be retransformed.
7273           </description>
7274         </param>
7275       </parameters>
7276       <errors>
7277         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7278           One of the <paramlink id="classes"/> cannot be modified. 
7279           See <functionlink id="IsModifiableClass"/>.
7280         </error>
7281         <error id="JVMTI_ERROR_INVALID_CLASS">
7282           One of the <paramlink id="classes"/> is not a valid class.
7283         </error>
7284         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7285           A retransformed class file has a version number not supported by this VM.
7286         </error>
7287         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7288           A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>).
7289         </error>
7290         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7291           The retransformed class file definitions would lead to a circular definition 
7292           (the VM would return a <code>ClassCircularityError</code>).
7293         </error>
7294         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7295           The retransformed class file bytes fail verification.
7296         </error>
7297         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7298           The class name defined in a retransformed class file is
7299           different from the name in the old class object.
7300         </error>
7301         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7302           A retransformed class file would require adding a method.
7303         </error>
7304         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7305           A retransformed class file changes a field.
7306         </error>
7307         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7308           A direct superclass is different for a retransformed class file,
7309           or the set of directly implemented
7310           interfaces is different.
7311         </error>
7312         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7313           A retransformed class file does not declare a method
7314           declared in the old class version.
7315         </error>
7316         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7317           A retransformed class file has different class modifiers.
7318         </error>
7319         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7320           A method in the retransformed class file has different modifiers
7321           than its counterpart in the old class version.
7322         </error>
7323       </errors>
7324     </function>
7325 
7326     <function id="RedefineClasses" jkernel="yes" num="87">
7327       <synopsis>Redefine Classes</synopsis>
7328       <typedef id="jvmtiClassDefinition" label="Class redefinition description">
7329         <field id="klass">
7330           <jclass/>
7331             <description>
7332               Class object for this class
7333             </description>
7334         </field>
7335         <field id="class_byte_count">
7336           <jint/>
7337           <description>
7338             Number of bytes defining class (below)
7339           </description>
7340         </field>
7341         <field id="class_bytes">
7342           <inbuf incount="class_byte_count"><uchar/></inbuf>
7343           <description>
7344             Bytes defining class (in <vmspec chapter="4"/>)
7345           </description>
7346         </field>
7347       </typedef>
7348       <description>
7349         All classes given are redefined according to the definitions
7350         supplied.
7351         This function is used to replace the definition of a class
7352         with a new definition, as might be needed in fix-and-continue
7353         debugging.
7354         Where the existing class file bytes are to be transformed, for 
7355         example in
7356         <internallink id="bci">bytecode instrumentation</internallink>,
7357         <functionlink id="RetransformClasses"/> should be used.
7358         <p/>
7359         Redefinition can cause new versions of methods to be installed.
7360         Old method versions may become 
7361         <internallink id="obsoleteMethods">obsolete</internallink>
7362         The new method version will be used on new invokes.  
7363         If a method has active stack frames, those active frames continue to
7364         run the bytecodes of the original method version. 
7365         If resetting of stack frames is desired, use 
7366         <functionlink id="PopFrame"></functionlink>
7367         to pop frames with obsolete method versions.
7368         <p/>
7369         This function does not cause any initialization except that which 
7370         would occur under the customary JVM semantics.
7371         In other words, redefining a class does not cause its initializers to be
7372         run. The values of static fields will remain as they were
7373         prior to the call.
7374         <p/>
7375         Threads need not be suspended.
7376         <p/>
7377         All breakpoints in the class are cleared.
7378         <p/>
7379         All attributes are updated.
7380         <p/>
7381         Instances of the redefined class are not affected -- fields retain their
7382         previous values.  
7383         <functionlink id="GetTag">Tags</functionlink> on the instances are
7384         also unaffected.
7385         <p/>
7386         In response to this call, the <jvmti/> event
7387         <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
7388         will be sent (if enabled), but no other <jvmti/> events will be sent.
7389         <p/>
7390         The redefinition may change method bodies, the constant pool and attributes.
7391         The redefinition must not add, remove or rename fields or methods, change the 
7392         signatures of methods, change modifiers, or change inheritance.  
7393         These restrictions may be lifted in future versions.
7394         See the error return description below for information on error codes
7395         returned if an unsupported redefinition is attempted.
7396         The class file bytes are not verified or installed until they have passed
7397         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7398         returned error code reflects the result of the transformations applied
7399         to the bytes passed into <paramlink id="class_definitions"/>.
7400         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7401         none of the classes to be redefined will have a new definition installed.
7402         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7403         all of the classes to be redefined will have their new definitions installed.        
7404       </description>
7405       <origin>jvmdi</origin>
7406       <capabilities>
7407         <required id="can_redefine_classes"></required>
7408         <capability id="can_redefine_any_class"></capability>
7409       </capabilities>
7410       <parameters>
7411         <param id="class_count">
7412           <jint min="0"/>
7413           <description>
7414             The number of classes specified in <code>class_definitions</code>
7415           </description>
7416         </param>
7417         <param id="class_definitions">
7418           <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
7419           <description>
7420             The array of new class definitions
7421           </description>
7422         </param>
7423       </parameters>
7424       <errors>
7425         <error id="JVMTI_ERROR_NULL_POINTER">
7426           One of <code>class_bytes</code> is <code>NULL</code>.
7427         </error>
7428         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7429           An element of <code>class_definitions</code> cannot be modified.
7430           See <functionlink id="IsModifiableClass"/>.
7431         </error>
7432         <error id="JVMTI_ERROR_INVALID_CLASS">
7433           An element of <code>class_definitions</code> is not a valid class.
7434         </error>
7435         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7436           A new class file has a version number not supported by this VM.
7437         </error>
7438         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7439           A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
7440         </error>
7441         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7442           The new class file definitions would lead to a circular definition 
7443           (the VM would return a <code>ClassCircularityError</code>).
7444         </error>
7445         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7446           The class bytes fail verification.
7447         </error>
7448         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7449           The class name defined in a new class file is
7450           different from the name in the old class object.
7451         </error>
7452         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7453           A new class file would require adding a method.
7454         </error>
7455         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7456           A new class version changes a field.
7457         </error>
7458         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7459           A direct superclass is different for a new class
7460           version, or the set of directly implemented
7461           interfaces is different.
7462         </error>
7463         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7464           A new class version does not declare a method
7465           declared in the old class version.
7466         </error>
7467         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7468           A new class version has different modifiers.
7469         </error>
7470         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7471           A method in the new class version has different modifiers
7472           than its counterpart in the old class version.
7473         </error>
7474       </errors>
7475     </function>
7476 
7477   </category>
7478 
7479   <category id="object" label="Object">
7480 
7481     <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
7482       <synopsis>Get Object Size</synopsis>
7483       <description>
7484         For the object indicated by <code>object</code>,
7485         return via <code>size_ptr</code> the size of the object.
7486         This size is an implementation-specific approximation of
7487         the amount of storage consumed by this object. 
7488         It may include some or all of the object's overhead, and thus
7489         is useful for comparison within an implementation but not
7490         between implementations.
7491         The estimate may change during a single invocation of the JVM.
7492       </description>
7493       <origin>new</origin>
7494       <capabilities>
7495       </capabilities>
7496       <parameters>
7497         <param id="object">
7498           <jobject/>
7499             <description>
7500               The object to query.
7501             </description>
7502         </param>
7503         <param id="size_ptr">
7504           <outptr><jlong/></outptr>
7505           <description>
7506             On return, points to the object's size in bytes.
7507           </description>
7508         </param>
7509       </parameters>
7510       <errors>
7511       </errors>
7512     </function>
7513 
7514     <function id="GetObjectHashCode" phase="start" num="58">
7515       <synopsis>Get Object Hash Code</synopsis>
7516       <description>
7517         For the object indicated by <code>object</code>,
7518         return via <code>hash_code_ptr</code> a hash code.
7519         This hash code could be used to maintain a hash table of object references,
7520         however, on some implementations this can cause significant performance 
7521         impacts--in most cases 
7522         <internallink id="Heap">tags</internallink> 
7523         will be a more efficient means of associating information with objects.
7524         This function guarantees 
7525         the same hash code value for a particular object throughout its life
7526       </description>
7527       <origin>jvmdi</origin>
7528       <capabilities>
7529       </capabilities>
7530       <parameters>
7531         <param id="object">
7532           <jobject/>
7533             <description>
7534               The object to query.
7535             </description>
7536         </param>
7537         <param id="hash_code_ptr">
7538           <outptr><jint/></outptr>
7539           <description>
7540             On return, points to the object's hash code.
7541           </description>
7542         </param>
7543       </parameters>
7544       <errors>
7545       </errors>
7546     </function>
7547 
7548     <function id="GetObjectMonitorUsage" num="59">
7549       <synopsis>Get Object Monitor Usage</synopsis>
7550       <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
7551         <field id="owner">
7552           <jthread/>
7553             <description>
7554               The thread owning this monitor, or <code>NULL</code> if unused
7555             </description>
7556         </field>
7557         <field id="entry_count">
7558           <jint/>
7559           <description>
7560             The number of times the owning thread has entered the monitor
7561           </description>
7562         </field>
7563         <field id="waiter_count">
7564           <jint/>
7565           <description>
7566             The number of threads waiting to own this monitor
7567           </description>
7568         </field>
7569         <field id="waiters">
7570           <allocfieldbuf><jthread/></allocfieldbuf>
7571             <description>
7572               The <code>waiter_count</code> waiting threads
7573             </description>
7574         </field>
7575         <field id="notify_waiter_count">
7576           <jint/>
7577           <description>
7578             The number of threads waiting to be notified by this monitor
7579           </description>
7580         </field>
7581         <field id="notify_waiters">
7582           <allocfieldbuf><jthread/></allocfieldbuf>
7583             <description>
7584               The <code>notify_waiter_count</code> threads waiting to be notified
7585             </description>
7586         </field>
7587       </typedef>
7588       <description>
7589         Get information about the object's monitor.
7590         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 
7591         are filled in with information about usage of the monitor.
7592           <todo>
7593             Decide and then clarify suspend requirements.
7594           </todo>
7595       </description>
7596       <origin>jvmdi</origin>
7597       <capabilities>
7598         <required id="can_get_monitor_info"></required>
7599       </capabilities>
7600       <parameters>
7601         <param id="object">
7602           <jobject/>
7603             <description>
7604               The object to query.
7605             </description>
7606         </param>
7607         <param id="info_ptr">
7608           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
7609           <description>
7610             On return, filled with monitor information for the 
7611             specified object.
7612           </description>
7613         </param>
7614       </parameters>
7615       <errors>
7616       </errors>
7617     </function>
7618 
7619     <elide>
7620     <function id="GetObjectMonitors" num="116">
7621       <synopsis>Get Object Monitors</synopsis>
7622       <description>
7623         Return the list of object monitors.
7624         <p/>
7625         Note: details about each monitor can be examined with 
7626         <functionlink id="GetObjectMonitorUsage"></functionlink>.
7627       </description>
7628       <origin>new</origin>
7629       <capabilities>
7630         <required id="can_get_monitor_info"></required>
7631       </capabilities>
7632       <parameters>
7633         <param id="monitorCnt">
7634           <outptr><jint/></outptr>
7635           <description>
7636             On return, pointer to the number 
7637             of monitors returned in <code>monitors_ptr</code>.
7638           </description>
7639         </param>
7640         <param id="monitors_ptr">
7641           <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
7642             <description>
7643               On return, pointer to the monitor list.
7644             </description>
7645         </param>
7646       </parameters>
7647       <errors>
7648       </errors>
7649     </function>
7650     </elide>
7651 
7652   </category>
7653 
7654   <category id="fieldCategory" label="Field">
7655 
7656     <intro>
7657     </intro>
7658 
7659     <function id="GetFieldName" phase="start" num="60">
7660       <synopsis>Get Field Name (and Signature)</synopsis>
7661       <description>
7662         For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
7663         return the field name via <paramlink id="name_ptr"/> and field signature via
7664         <paramlink id="signature_ptr"/>.
7665         <p/>
7666         Field signatures are defined in the JNI Specification and 
7667         are referred to as <code>field descriptors</code> in
7668         <vmspec chapter="4.3.2"/>.
7669       </description>
7670       <origin>jvmdiClone</origin>
7671       <capabilities>
7672       </capabilities>
7673       <parameters>
7674         <param id="klass">
7675           <jclass field="field"/>
7676             <description>
7677               The class of the field to query.
7678             </description>
7679         </param>
7680         <param id="field">
7681           <jfieldID class="klass"/>
7682             <description>
7683               The field to query.
7684             </description>
7685         </param>
7686         <param id="name_ptr">
7687           <allocbuf>
7688             <char/>
7689             <nullok>the name is not returned</nullok>
7690           </allocbuf>
7691           <description>
7692             On return, points to the field name, encoded as a
7693             <internallink id="mUTF">modified UTF-8</internallink> string.
7694           </description>
7695         </param>
7696         <param id="signature_ptr">
7697           <allocbuf>
7698             <char/>
7699             <nullok>the signature is not returned</nullok>
7700           </allocbuf>
7701           <description>
7702             On return, points to the field signature, encoded as a
7703             <internallink id="mUTF">modified UTF-8</internallink> string.
7704           </description>
7705         </param>
7706         <param id="generic_ptr">
7707           <allocbuf>
7708             <char/>           
7709             <nullok>the generic signature is not returned</nullok>
7710           </allocbuf>
7711           <description>
7712             On return, points to the generic signature of the field, encoded as a
7713             <internallink id="mUTF">modified UTF-8</internallink> string.
7714             If there is no generic signature attribute for the field, then,
7715             on return, points to <code>NULL</code>. 
7716           </description>
7717         </param>
7718       </parameters>
7719       <errors>
7720       </errors>
7721     </function>
7722 
7723     <function id="GetFieldDeclaringClass" phase="start" num="61">
7724       <synopsis>Get Field Declaring Class</synopsis>
7725       <description>
7726         For the field indicated by <code>klass</code> and <code>field</code>
7727         return the class that defined it via <code>declaring_class_ptr</code>.
7728         The declaring class will either be <code>klass</code>, a superclass, or
7729         an implemented interface.
7730       </description>
7731       <origin>jvmdi</origin>
7732       <capabilities>
7733       </capabilities>
7734       <parameters>
7735         <param id="klass">
7736           <jclass field="field"/>
7737             <description>
7738               The class to query.
7739             </description>
7740         </param>
7741         <param id="field">
7742           <jfieldID class="klass"/>
7743             <description>
7744               The field to query.
7745             </description>
7746         </param>
7747         <param id="declaring_class_ptr">
7748           <outptr><jclass/></outptr>
7749             <description>
7750               On return, points to the declaring class
7751             </description>
7752         </param>
7753       </parameters>
7754       <errors>
7755       </errors>
7756     </function>
7757 
7758     <function id="GetFieldModifiers" phase="start" num="62">
7759       <synopsis>Get Field Modifiers</synopsis>
7760       <description>
7761         For the field indicated by <code>klass</code> and <code>field</code>
7762         return the access flags via <code>modifiers_ptr</code>.
7763         Access flags are defined in <vmspec chapter="4"/>.
7764       </description>
7765       <origin>jvmdi</origin>
7766       <capabilities>
7767       </capabilities>
7768       <parameters>
7769         <param id="klass">
7770           <jclass field="field"/>
7771             <description>
7772               The class to query.
7773             </description>
7774         </param>
7775         <param id="field">
7776           <jfieldID class="klass"/>
7777             <description>
7778               The field to query.
7779             </description>
7780         </param>
7781         <param id="modifiers_ptr">
7782           <outptr><jint/></outptr>
7783           <description>
7784             On return, points to the access flags.
7785           </description>
7786         </param>
7787       </parameters>
7788       <errors>
7789       </errors>
7790     </function>
7791 
7792     <function id="IsFieldSynthetic" phase="start" num="63">
7793       <synopsis>Is Field Synthetic</synopsis>
7794       <description>
7795         For the field indicated by <code>klass</code> and <code>field</code>, return a
7796         value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
7797         Synthetic fields are generated by the compiler but not present in the 
7798         original source code.
7799       </description>
7800       <origin>jvmdi</origin>
7801       <capabilities>
7802         <required id="can_get_synthetic_attribute"></required>
7803       </capabilities>
7804       <parameters>
7805         <param id="klass">
7806           <jclass field="field"/>
7807             <description>
7808               The class of the field to query.
7809             </description>
7810         </param>
7811         <param id="field">
7812           <jfieldID class="klass"/>
7813             <description>
7814               The field to query.
7815             </description>
7816         </param>
7817         <param id="is_synthetic_ptr">
7818           <outptr><jboolean/></outptr>
7819           <description>
7820             On return, points to the boolean result of this function.
7821           </description>
7822         </param>
7823       </parameters>
7824       <errors>
7825       </errors>
7826     </function>
7827 
7828   </category>
7829 
7830   <category id="method" label="Method">
7831 
7832     <intro>
7833       These functions provide information about a method (represented as a
7834       <typelink id="jmethodID"/>) and set how methods are processed.
7835     </intro>
7836 
7837     <intro id="obsoleteMethods" label="Obsolete Methods">
7838       The functions <functionlink id="RetransformClasses"/> and
7839       <functionlink id="RedefineClasses"/> can cause new versions
7840       of methods to be installed.
7841       An original version of a method is considered equivalent
7842       to the new version if:
7843       <ul>
7844         <li>their bytecodes are the same except for indices into the
7845           constant pool and </li>
7846         <li>the referenced constants are equal.</li>
7847       </ul>
7848       An original method version which is not equivalent to the
7849       new method version is called obsolete and is assigned a new method ID;
7850       the original method ID now refers to the new method version.
7851       A method ID can be tested for obsolescence with 
7852       <functionlink id="IsMethodObsolete"/>.
7853     </intro>
7854 
7855     <function id="GetMethodName" phase="start" num="64">
7856       <synopsis>Get Method Name (and Signature)</synopsis>
7857       <description>
7858         For the method indicated by <code>method</code>,
7859         return the method name via <code>name_ptr</code> and method signature via
7860         <code>signature_ptr</code>.
7861         <p/>
7862         Method signatures are defined in the JNI Specification and are 
7863         referred to as <code>method descriptors</code> in 
7864         <vmspec chapter="4.3.3"/>.
7865         Note this is different
7866         than method signatures as defined in the <i>Java Language Specification</i>.
7867       </description>
7868       <origin>jvmdiClone</origin>
7869       <capabilities>
7870       </capabilities>
7871       <parameters>
7872         <param id="method">
7873           <jmethodID/>
7874             <description>
7875               The method to query.
7876             </description>
7877         </param>
7878         <param id="name_ptr">
7879           <allocbuf>
7880             <char/>
7881             <nullok>the name is not returned</nullok>
7882           </allocbuf>
7883           <description>
7884             On return, points to the method name, encoded as a
7885             <internallink id="mUTF">modified UTF-8</internallink> string.
7886           </description>
7887         </param>
7888         <param id="signature_ptr">
7889           <allocbuf>
7890             <char/>
7891             <nullok>the signature is not returned</nullok>
7892           </allocbuf>
7893           <description>
7894             On return, points to the method signature, encoded as a
7895             <internallink id="mUTF">modified UTF-8</internallink> string.
7896           </description>
7897         </param>
7898         <param id="generic_ptr">
7899           <allocbuf>
7900             <char/>           
7901             <nullok>the generic signature is not returned</nullok>
7902           </allocbuf>
7903           <description>
7904             On return, points to the generic signature of the method, encoded as a
7905             <internallink id="mUTF">modified UTF-8</internallink> string.
7906             If there is no generic signature attribute for the method, then,
7907             on return, points to <code>NULL</code>. 
7908           </description>
7909         </param>
7910       </parameters>
7911       <errors>
7912       </errors>
7913     </function>
7914 
7915     <function id="GetMethodDeclaringClass" phase="start" num="65">
7916       <synopsis>Get Method Declaring Class</synopsis>
7917       <description>
7918         For the method indicated by <code>method</code>,
7919         return the class that defined it via <code>declaring_class_ptr</code>.
7920       </description>
7921       <origin>jvmdi</origin>
7922       <capabilities>
7923       </capabilities>
7924       <parameters>
7925         <param id="klass">
7926           <jclass method="method"/>
7927             <description>
7928               The class to query.
7929             </description>
7930         </param>
7931         <param id="method">
7932           <jmethodID class="klass"/>
7933             <description>
7934               The method to query.
7935             </description>
7936         </param>
7937         <param id="declaring_class_ptr">
7938           <outptr><jclass/></outptr>
7939             <description>
7940               On return, points to the declaring class
7941             </description>
7942         </param>
7943       </parameters>
7944       <errors>
7945       </errors>
7946     </function>
7947 
7948     <function id="GetMethodModifiers" phase="start" num="66">
7949       <synopsis>Get Method Modifiers</synopsis>
7950       <description>
7951         For the method indicated by <code>method</code>,
7952         return the access flags via <code>modifiers_ptr</code>.
7953         Access flags are defined in <vmspec chapter="4"/>.
7954       </description>
7955       <origin>jvmdi</origin>
7956       <capabilities>
7957       </capabilities>
7958       <parameters>
7959         <param id="klass">
7960           <jclass method="method"/>
7961             <description>
7962               The class to query.
7963             </description>
7964         </param>
7965         <param id="method">
7966           <jmethodID class="klass"/>
7967             <description>
7968               The method to query.
7969             </description>
7970         </param>
7971         <param id="modifiers_ptr">
7972           <outptr><jint/></outptr>
7973           <description>
7974             On return, points to the access flags.
7975           </description>
7976         </param>
7977       </parameters>
7978       <errors>
7979       </errors>
7980     </function>
7981 
7982     <function id="GetMaxLocals" phase="start" num="68">
7983       <synopsis>Get Max Locals</synopsis>
7984       <description>
7985           For the method indicated by <code>method</code>,
7986           return the number of local variable slots used by the method,
7987           including the local variables used to pass parameters to the
7988           method on its invocation. 
7989           <p/>
7990           See <code>max_locals</code> in <vmspec chapter="4.7.3"/>.
7991       </description>
7992       <origin>jvmdi</origin>
7993       <capabilities>
7994       </capabilities>
7995       <parameters>
7996         <param id="klass">
7997           <jclass method="method"/>
7998             <description>
7999               The class to query.
8000             </description>
8001         </param>
8002         <param id="method">
8003           <jmethodID class="klass" native="error"/>
8004             <description>
8005               The method to query.
8006             </description>
8007         </param>
8008         <param id="max_ptr">
8009           <outptr><jint/></outptr>
8010           <description>
8011             On return, points to the maximum number of local slots
8012           </description>
8013         </param>
8014       </parameters>
8015       <errors>
8016       </errors>
8017     </function>
8018 
8019     <function id="GetArgumentsSize" phase="start" num="69">
8020       <synopsis>Get Arguments Size</synopsis>
8021       <description>
8022         For the method indicated by <code>method</code>,
8023         return via <code>max_ptr</code> the number of local variable slots used
8024         by the method's arguments.
8025         Note that two-word arguments use two slots.
8026       </description>
8027       <origin>jvmdi</origin>
8028       <capabilities>
8029       </capabilities>
8030       <parameters>
8031         <param id="klass">
8032           <jclass method="method"/>
8033             <description>
8034               The class to query.
8035             </description>
8036         </param>
8037         <param id="method">
8038           <jmethodID class="klass" native="error"/>
8039             <description>
8040               The method to query.
8041             </description>
8042         </param>
8043         <param id="size_ptr">
8044           <outptr><jint/></outptr>
8045           <description>
8046             On return, points to the number of argument slots
8047           </description>
8048         </param>
8049       </parameters>
8050       <errors>
8051       </errors>
8052     </function>
8053 
8054     <function id="GetLineNumberTable" phase="start" num="70">
8055       <synopsis>Get Line Number Table</synopsis>
8056       <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
8057         <field id="start_location">
8058           <jlocation/>
8059           <description>
8060             the <datalink id="jlocation"></datalink> where the line begins
8061           </description>
8062         </field>
8063         <field id="line_number">
8064           <jint/>
8065           <description>
8066             the line number
8067           </description>
8068         </field>
8069       </typedef>
8070       <description>
8071         For the method indicated by <code>method</code>,
8072         return a table of source line number entries. The size of the table is
8073         returned via <code>entry_count_ptr</code> and the table itself is
8074         returned via <code>table_ptr</code>. 
8075       </description>
8076       <origin>jvmdi</origin>
8077       <capabilities>
8078         <required id="can_get_line_numbers"></required>
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="entry_count_ptr">
8094           <outptr><jint/></outptr>
8095           <description>
8096             On return, points to the number of entries in the table
8097           </description>
8098         </param>
8099         <param id="table_ptr">
8100           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
8101           <description>
8102             On return, points to the line number table pointer.
8103           </description>
8104         </param>
8105       </parameters>
8106       <errors>
8107         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
8108           Class information does not include line numbers.
8109         </error>
8110       </errors>
8111     </function>
8112 
8113     <function id="GetMethodLocation" phase="start" num="71">
8114       <synopsis>Get Method Location</synopsis>
8115       <description>
8116         For the method indicated by <code>method</code>,
8117         return the beginning and ending addresses through
8118         <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
8119         conventional byte code indexing scheme, 
8120         <code>start_location_ptr</code> will always point to zero
8121         and <code>end_location_ptr</code> 
8122         will always point to the byte code count minus one. 
8123       </description>
8124       <origin>jvmdi</origin>
8125       <capabilities>
8126       </capabilities>
8127       <parameters>
8128         <param id="klass">
8129           <jclass method="method"/>
8130             <description>
8131               The class to query.
8132             </description>
8133         </param>
8134         <param id="method">
8135           <jmethodID class="klass" native="error"/>
8136             <description>
8137               The method to query.
8138             </description>
8139         </param>
8140         <param id="start_location_ptr">
8141           <outptr><jlocation/></outptr>
8142           <description>
8143             On return, points to the first location, or 
8144             <code>-1</code> if location information is not available.
8145             If the information is available and 
8146             <functionlink id="GetJLocationFormat"></functionlink>
8147             returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
8148             then this will always be zero.
8149           </description>
8150         </param>
8151         <param id="end_location_ptr">
8152           <outptr><jlocation/></outptr>
8153           <description>
8154             On return, points to the last location,
8155             or <code>-1</code> if location information is not available.
8156           </description>
8157         </param>
8158       </parameters>
8159       <errors>
8160         <error id="JVMTI_ERROR_ABSENT_INFORMATION"> 
8161           Class information does not include method sizes.
8162         </error>
8163       </errors>
8164     </function>
8165 
8166     <function id="GetLocalVariableTable" num="72">
8167       <synopsis>Get Local Variable Table</synopsis>
8168       <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
8169         <field id="start_location">
8170           <jlocation/>
8171           <description>
8172             The code array index where the local variable is first valid
8173             (that is, where it must have a value).
8174           </description>
8175         </field>
8176         <field id="length">
8177           <jint/>
8178           <description>
8179             The length of the valid section for this local variable.
8180             The last code array index where the local variable is valid 
8181             is <code>start_location + length</code>.
8182           </description>
8183         </field>
8184         <field id="name">
8185           <allocfieldbuf><char/></allocfieldbuf>
8186           <description>
8187             The local variable name, encoded as a
8188             <internallink id="mUTF">modified UTF-8</internallink> string.
8189           </description>
8190         </field>
8191         <field id="signature">
8192           <allocfieldbuf><char/></allocfieldbuf>
8193           <description>
8194             The local variable's type signature, encoded as a
8195             <internallink id="mUTF">modified UTF-8</internallink> string.
8196             The signature format is the same as that defined in
8197             <vmspec chapter="4.3.2"/>.
8198           </description>
8199         </field>
8200         <field id="generic_signature">
8201           <allocfieldbuf><char/></allocfieldbuf>
8202           <description>
8203             The local variable's generic signature, encoded as a
8204             <internallink id="mUTF">modified UTF-8</internallink> string.
8205             The value of this field will be <code>NULL</code> for any local 
8206             variable which does not have a generic type.
8207           </description>
8208         </field>
8209         <field id="slot">
8210           <jint/>
8211           <description>
8212             The local variable's slot.  See <internallink id="local">Local Variables</internallink>.
8213           </description>
8214         </field>
8215       </typedef>
8216       <description>
8217         Return local variable information.
8218       </description>
8219       <origin>jvmdiClone</origin>
8220       <capabilities>
8221         <required id="can_access_local_variables"></required>
8222       </capabilities>
8223       <parameters>
8224         <param id="method">
8225           <jmethodID native="error"/>
8226             <description>
8227               The method to query.
8228             </description>
8229         </param>
8230         <param id="entry_count_ptr">
8231           <outptr><jint/></outptr>
8232           <description>
8233             On return, points to the number of entries in the table
8234           </description>
8235         </param>
8236         <param id="table_ptr">
8237           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
8238           <description>
8239             On return, points to an array of local variable table entries.
8240           </description>
8241         </param>
8242       </parameters>
8243       <errors>
8244         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8245           Class information does not include local variable
8246           information.
8247         </error>
8248       </errors>
8249     </function>
8250 
8251     <function id="GetBytecodes" phase="start" num="75">
8252       <synopsis>Get Bytecodes</synopsis>
8253       <description>
8254         For the method indicated by <code>method</code>,
8255         return the byte codes that implement the method. The number of
8256         bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes
8257         themselves are returned via <code>bytecodes_ptr</code>.
8258       </description>
8259       <origin>jvmdi</origin>
8260       <capabilities>
8261         <required id="can_get_bytecodes"></required>
8262       </capabilities>
8263       <parameters>
8264         <param id="klass">
8265           <jclass method="method"/>
8266             <description>
8267               The class to query.
8268             </description>
8269         </param>
8270         <param id="method">
8271           <jmethodID class="klass" native="error"/>
8272             <description>
8273               The method to query.
8274             </description>
8275         </param>
8276         <param id="bytecode_count_ptr">
8277           <outptr><jint/></outptr>
8278           <description>
8279             On return, points to the length of the byte code array
8280           </description>
8281         </param>
8282         <param id="bytecodes_ptr">
8283           <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
8284           <description>
8285             On return, points to the pointer to the byte code array
8286           </description>
8287         </param>
8288       </parameters>
8289       <errors>
8290       </errors>
8291     </function>
8292 
8293     <function id="IsMethodNative" phase="start" num="76">
8294       <synopsis>Is Method Native</synopsis>
8295       <description>
8296         For the method indicated by <code>method</code>, return a
8297         value indicating whether the method is native via <code>is_native_ptr</code>
8298       </description>
8299       <origin>jvmdi</origin>
8300       <capabilities>
8301       </capabilities>
8302       <parameters>
8303         <param id="klass">
8304           <jclass method="method"/>
8305             <description>
8306               The class to query.
8307             </description>
8308         </param>
8309         <param id="method">
8310           <jmethodID class="klass"/>
8311             <description>
8312               The method to query.
8313             </description>
8314         </param>
8315         <param id="is_native_ptr">
8316           <outptr><jboolean/></outptr>
8317           <description>
8318             On return, points to the boolean result of this function.
8319           </description>
8320         </param>
8321       </parameters>
8322       <errors>
8323       </errors>
8324     </function>
8325 
8326     <function id="IsMethodSynthetic" phase="start" num="77">
8327       <synopsis>Is Method Synthetic</synopsis>
8328       <description>
8329         For the method indicated by <code>method</code>, return a
8330         value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
8331         Synthetic methods are generated by the compiler but not present in the 
8332         original source code.
8333       </description>
8334       <origin>jvmdi</origin>
8335       <capabilities>
8336         <required id="can_get_synthetic_attribute"></required>
8337       </capabilities>
8338       <parameters>
8339         <param id="klass">
8340           <jclass method="method"/>
8341             <description>
8342               The class to query.
8343             </description>
8344         </param>
8345         <param id="method">
8346           <jmethodID class="klass"/>
8347             <description>
8348               The method to query.
8349             </description>
8350         </param>
8351         <param id="is_synthetic_ptr">
8352           <outptr><jboolean/></outptr>
8353           <description>
8354             On return, points to the boolean result of this function.
8355           </description>
8356         </param>
8357       </parameters>
8358       <errors>
8359       </errors>
8360     </function>
8361 
8362     <function id="IsMethodObsolete" phase="start" num="91">
8363       <synopsis>Is Method Obsolete</synopsis>
8364       <description>
8365         Determine if a method ID refers to an
8366         <internallink id="obsoleteMethods">obsolete</internallink>
8367         method version.
8368       </description>
8369       <origin>jvmdi</origin>
8370       <capabilities>
8371       </capabilities>
8372       <parameters>
8373         <param id="klass">
8374           <jclass method="method"/>
8375             <description>
8376               The class to query.
8377             </description>
8378         </param>
8379         <param id="method">
8380           <jmethodID class="klass"/>
8381             <description>
8382               The method ID to query.
8383             </description>
8384         </param>
8385         <param id="is_obsolete_ptr">
8386           <outptr><jboolean/></outptr>
8387           <description>
8388             On return, points to the boolean result of this function.
8389           </description>
8390         </param>
8391       </parameters>
8392       <errors>
8393       </errors>
8394     </function>
8395 
8396     <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
8397       <synopsis>Set Native Method Prefix</synopsis>
8398       <description>
8399         This function modifies the failure handling of
8400         native method resolution by allowing retry
8401         with a prefix applied to the name.
8402         When used with the 
8403         <eventlink id="ClassFileLoadHook">ClassFileLoadHook
8404         event</eventlink>, it enables native methods to be
8405         <internallink id="bci">instrumented</internallink>.
8406         <p/>
8407         Since native methods cannot be directly instrumented
8408         (they have no bytecodes), they must be wrapped with
8409         a non-native method which can be instrumented.
8410         For example, if we had:
8411         <example>
8412 native boolean foo(int x);</example>
8413         <p/>
8414         We could transform the class file (with the 
8415         ClassFileLoadHook event) so that this becomes:
8416         <example>
8417 boolean foo(int x) {
8418   <i>... record entry to foo ...</i>
8419   return wrapped_foo(x);
8420 }
8421 
8422 native boolean wrapped_foo(int x);</example>
8423         <p/>
8424         Where foo becomes a wrapper for the actual native method
8425         with the appended prefix "wrapped_".  Note that
8426         "wrapped_" would be a poor choice of prefix since it
8427         might conceivably form the name of an existing method
8428         thus something like "$$$MyAgentWrapped$$$_" would be
8429         better but would make these examples less readable.
8430         <p/>
8431         The wrapper will allow data to be collected on the native
8432         method call, but now the problem becomes linking up the  
8433         wrapped method with the native implementation.  
8434         That is, the method <code>wrapped_foo</code> needs to be 
8435         resolved to the native implementation of <code>foo</code>,
8436         which might be:
8437         <example>
8438 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
8439         <p/>
8440         This function allows the prefix to be specified and the
8441         proper resolution to occur.  
8442         Specifically, when the standard resolution fails, the
8443         resolution is retried taking the prefix into consideration.
8444         There are two ways that resolution occurs, explicit
8445         resolution with the JNI function <code>RegisterNatives</code>
8446         and the normal automatic resolution.  For 
8447         <code>RegisterNatives</code>, the VM will attempt this 
8448         association:
8449         <example>
8450 method(foo) -> nativeImplementation(foo)</example>
8451         <p/>
8452         When this fails, the resolution will be retried with
8453         the specified prefix prepended to the method name, 
8454         yielding the correct resolution:
8455         <example>
8456 method(wrapped_foo) -> nativeImplementation(foo)</example>
8457         <p/>
8458         For automatic resolution, the VM will attempt:
8459         <example>
8460 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
8461         <p/>
8462         When this fails, the resolution will be retried with
8463         the specified prefix deleted from the implementation name, 
8464         yielding the correct resolution:
8465         <example>
8466 method(wrapped_foo) -> nativeImplementation(foo)</example>
8467         <p/>
8468         Note that since the prefix is only used when standard
8469         resolution fails, native methods can be wrapped selectively.
8470         <p/>
8471         Since each <jvmti/> environment is independent and
8472         can do its own transformation of the bytecodes, more 
8473         than one layer of wrappers may be applied. Thus each
8474         environment needs its own prefix.  Since transformations
8475         are applied in order, the prefixes, if applied, will
8476         be applied in the same order.
8477         The order of transformation application is described in
8478         the <eventlink id="ClassFileLoadHook"/> event.
8479         Thus if three environments applied
8480         wrappers, <code>foo</code> might become 
8481         <code>$env3_$env2_$env1_foo</code>.  But if, say,
8482         the second environment did not apply a wrapper to
8483         <code>foo</code> it would be just 
8484         <code>$env3_$env1_foo</code>.  To be able to 
8485         efficiently determine the sequence of prefixes,
8486         an intermediate prefix is only applied if its non-native
8487         wrapper exists.  Thus, in the last example, even though 
8488         <code>$env1_foo</code> is not a native method, the
8489         <code>$env1_</code> prefix is applied since 
8490         <code>$env1_foo</code> exists.
8491         <p/>
8492         Since the prefixes are used at resolution time
8493         and since resolution may be arbitrarily delayed, a
8494         native method prefix must remain set as long as there 
8495         are corresponding prefixed native methods.
8496       </description>
8497       <origin>new</origin>
8498       <capabilities>
8499         <required id="can_set_native_method_prefix"></required>
8500       </capabilities>
8501       <parameters>
8502         <param id="prefix">
8503           <inbuf>
8504             <char/>
8505             <nullok>
8506               any existing prefix in this environment is cancelled
8507             </nullok>
8508           </inbuf>
8509           <description>
8510             The prefix to apply, encoded as a
8511             <internallink id="mUTF">modified UTF-8</internallink> string.
8512           </description>
8513         </param>
8514       </parameters>
8515       <errors>
8516       </errors>
8517     </function>
8518 
8519     <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
8520       <synopsis>Set Native Method Prefixes</synopsis>
8521       <description>
8522          For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
8523          will provide all needed native method prefixing.
8524          For a meta-agent that performs multiple independent class
8525          file transformations (for example as a proxy for another
8526          layer of agents) this function allows each transformation
8527          to have its own prefix.  
8528          The prefixes are applied in the order supplied and are
8529          processed in the same manor as described for the
8530          application of prefixes from multiple <jvmti/> environments
8531          in <functionlink id="SetNativeMethodPrefix"/>.
8532          <p/>
8533          Any previous prefixes are replaced.  Thus, calling this
8534          function with a <paramlink id="prefix_count"/> of <code>0</code>
8535          disables prefixing in this environment.
8536          <p/>
8537          <functionlink id="SetNativeMethodPrefix"/> and this function
8538          are the two ways to set the prefixes.  
8539          Calling <code>SetNativeMethodPrefix</code> with 
8540          a prefix is the same as calling this function with 
8541          <paramlink id="prefix_count"/> of <code>1</code>. 
8542          Calling <code>SetNativeMethodPrefix</code> with 
8543          <code>NULL</code> is the same as calling this function with 
8544          <paramlink id="prefix_count"/> of <code>0</code>. 
8545       </description>
8546       <origin>new</origin>
8547       <capabilities>
8548         <required id="can_set_native_method_prefix"></required>
8549       </capabilities>
8550       <parameters>
8551         <param id="prefix_count">
8552           <jint min="0"/>
8553             <description>
8554               The number of prefixes to apply.
8555             </description>
8556         </param>
8557         <param id="prefixes">
8558           <agentbuf>
8559             <char/>
8560           </agentbuf>
8561           <description>
8562             The prefixes to apply for this environment, each encoded as a
8563             <internallink id="mUTF">modified UTF-8</internallink> string.
8564           </description>
8565         </param>
8566       </parameters>
8567       <errors>
8568       </errors>
8569     </function>
8570 
8571   </category>
8572 
8573   <category id="RawMonitors" label="Raw Monitor">
8574 
8575     <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
8576       <synopsis>Create Raw Monitor</synopsis>
8577       <description>
8578         Create a raw monitor.
8579       </description>
8580       <origin>jvmdi</origin>
8581       <capabilities>
8582       </capabilities>
8583       <parameters>
8584         <param id="name">
8585           <inbuf><char/></inbuf>
8586           <description>
8587             A name to identify the monitor, encoded as a
8588             <internallink id="mUTF">modified UTF-8</internallink> string.
8589           </description>
8590         </param>
8591         <param id="monitor_ptr">
8592           <outptr><jrawMonitorID/></outptr>
8593           <description>
8594             On return, points to the created monitor.
8595           </description>
8596         </param>
8597       </parameters>
8598       <errors>
8599       </errors>
8600     </function>
8601 
8602     <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
8603       <synopsis>Destroy Raw Monitor</synopsis>
8604       <description>
8605         Destroy the raw monitor.
8606         If the monitor being destroyed has been entered by this thread, it will be
8607         exited before it is destroyed.
8608         If the monitor being destroyed has been entered by another thread,
8609         an error will be returned and the monitor will not be destroyed.
8610       </description>
8611       <origin>jvmdi</origin>
8612       <capabilities>
8613       </capabilities>
8614       <parameters>
8615         <param id="monitor">
8616           <jrawMonitorID/>
8617           <description>
8618             The monitor
8619           </description>
8620         </param>
8621       </parameters>
8622       <errors>
8623         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8624           Not monitor owner
8625         </error>        
8626       </errors>
8627     </function>
8628 
8629     <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
8630       <synopsis>Raw Monitor Enter</synopsis>
8631       <description>
8632         Gain exclusive ownership of a raw monitor.  
8633         The same thread may enter a monitor more then once.
8634         The thread must
8635         <functionlink id="RawMonitorExit">exit</functionlink>
8636         the monitor the same number of times as it is entered.
8637         If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
8638         and has not exited when attached threads come into existence, the enter
8639         is considered to have occurred on the main thread.
8640       </description>
8641       <origin>jvmdi</origin>
8642       <capabilities>
8643       </capabilities>
8644       <parameters>
8645         <param id="monitor">
8646           <jrawMonitorID/>
8647           <description>
8648             The monitor
8649           </description>
8650         </param>
8651       </parameters>
8652       <errors>
8653       </errors>
8654     </function>
8655 
8656     <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
8657       <synopsis>Raw Monitor Exit</synopsis>
8658       <description>
8659         Release exclusive ownership of a raw monitor.
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="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
8680       <synopsis>Raw Monitor Wait</synopsis>
8681       <description>
8682         Wait for notification of the raw monitor.
8683         <p/>
8684         Causes the current thread to wait until either another thread calls 
8685         <functionlink id="RawMonitorNotify"/> or 
8686         <functionlink id="RawMonitorNotifyAll"/> 
8687         for the specified raw monitor, or the specified
8688         <paramlink id="millis">timeout</paramlink>
8689         has elapsed.
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         <param id="millis">
8702           <jlong/>
8703           <description>
8704             The timeout, in milliseconds.  If the timeout is
8705             zero, then real time is not taken into consideration
8706             and the thread simply waits until notified.
8707           </description>
8708         </param>
8709       </parameters>
8710       <errors>
8711         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8712           Not monitor owner
8713         </error>
8714         <error id="JVMTI_ERROR_INTERRUPT"> 
8715           Wait was interrupted, try again
8716         </error>
8717       </errors>
8718     </function>
8719 
8720     <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
8721       <synopsis>Raw Monitor Notify</synopsis>
8722       <description>
8723         Notify a single thread waiting on the raw monitor.
8724       </description>
8725       <origin>jvmdi</origin>
8726       <capabilities>
8727       </capabilities>
8728       <parameters>
8729         <param id="monitor">
8730           <jrawMonitorID/>
8731           <description>
8732             The monitor
8733           </description>
8734         </param>
8735       </parameters>
8736       <errors>
8737         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
8738           Not monitor owner
8739         </error>
8740       </errors>
8741     </function>
8742 
8743     <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
8744       <synopsis>Raw Monitor Notify All</synopsis>
8745       <description>
8746         Notify all threads waiting on the raw monitor.
8747       </description>
8748       <origin>jvmdi</origin>
8749       <capabilities>
8750       </capabilities>
8751       <parameters>
8752         <param id="monitor">
8753           <jrawMonitorID/>
8754           <description>
8755             The monitor
8756           </description>
8757         </param>
8758       </parameters>
8759       <errors>
8760         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER"> 
8761           Not monitor owner
8762         </error>
8763       </errors>
8764     </function>
8765 
8766    <elide>
8767     <function id="GetRawMonitorUse" num="118">
8768       <synopsis>Get Raw Monitor Use</synopsis>
8769       <description>
8770         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure 
8771         are filled in with information about usage of the raw monitor.
8772       </description>
8773       <origin>new</origin>
8774       <capabilities>
8775         <required id="can_get_raw_monitor_usage"></required>
8776       </capabilities>
8777       <parameters>
8778         <param id="monitor">
8779           <jrawMonitorID/>
8780           <description>
8781             the raw monitor to query.
8782           </description>
8783         </param>
8784         <param id="info_ptr">
8785           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
8786           <description>
8787             On return, filled with monitor information for the 
8788             specified raw monitor.
8789           </description>
8790         </param>
8791       </parameters>
8792       <errors>
8793       </errors>
8794     </function>
8795 
8796     <function id="GetRawMonitors" num="119">
8797       <synopsis>Get Raw Monitors</synopsis>
8798       <description>
8799         Return the list of raw monitors.
8800         <p/>
8801         Note: details about each monitor can be examined with 
8802         <functionlink id="GetRawMonitorUse"></functionlink>.
8803       </description>
8804       <origin>new</origin>
8805       <capabilities>
8806         <required id="can_get_raw_monitor_usage"></required>
8807       </capabilities>
8808       <parameters>
8809         <param id="monitorCnt">
8810           <outptr><jint/></outptr>
8811           <description>
8812             On return, pointer to the number 
8813             of monitors returned in <code>monitors_ptr</code>.
8814           </description>
8815         </param>
8816         <param id="monitors_ptr">
8817           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
8818           <description>
8819             On return, pointer to the monitor list.
8820           </description>
8821         </param>
8822       </parameters>
8823       <errors>
8824       </errors>
8825     </function>
8826     </elide>
8827   </category>
8828 
8829   <category id="jniIntercept" label="JNI Function Interception">
8830 
8831     <intro>
8832       Provides the ability to intercept and resend 
8833       Java Native Interface (JNI) function calls
8834       by manipulating the JNI function table.
8835       See <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html">JNI
8836         Functions</externallink> in the <i>Java Native Interface Specification</i>.
8837       <p/>
8838       The following example illustrates intercepting the 
8839       <code>NewGlobalRef</code> JNI call in order to count reference
8840       creation.
8841       <example>
8842 JNIEnv original_jni_Functions;
8843 JNIEnv redirected_jni_Functions;
8844 int my_global_ref_count = 0;
8845 
8846 jobject
8847 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
8848    ++my_global_ref_count;
8849    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
8850 }
8851 
8852 void
8853 myInit() {
8854    jvmtiError err;
8855 
8856    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;original_jni_Functions);
8857    if (err != JVMTI_ERROR_NONE) {
8858       die();
8859    }
8860    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;redirected_jni_Functions);
8861    if (err != JVMTI_ERROR_NONE) {
8862       die();
8863    }
8864    redirectedJNIFunctions-&gt;NewGlobalRef = MyNewGlobalRef;
8865       err = (*jvmti_env)-&gt;SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
8866    if (err != JVMTI_ERROR_NONE) {
8867       die();
8868    }
8869 }
8870       </example>
8871       Sometime after <code>myInit</code> is called the user's JNI
8872       code is executed which makes the call to create a new global
8873       reference.  Instead of going to the normal JNI implementation
8874       the call goes to <code>myNewGlobalRef</code>.  Note that a
8875       copy of the original function table is kept so that the normal
8876       JNI function can be called after the data is collected.
8877       Note also that any JNI functions which are not overwritten
8878       will behave normally.
8879       <todo>
8880         check that the example compiles and executes.
8881       </todo>
8882     </intro>
8883     
8884     <function id="SetJNIFunctionTable" phase="start" num="120">
8885       <synopsis>Set JNI Function Table</synopsis>
8886       <description>
8887         Set the JNI function table 
8888         in all current and future JNI environments.
8889         As a result, all future JNI calls are directed to the specified functions.
8890         Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
8891         function table to pass to this function.
8892         For this function to take effect the the updated table entries must be 
8893         used by the JNI clients.
8894         Since the table is defined <code>const</code> some compilers may optimize
8895         away the access to the table, thus preventing this function from taking 
8896         effect.
8897         The table is copied--changes to the local copy of the
8898         table have no effect.
8899         This function affects only the function table, all other aspects of the environment are
8900         unaffected.
8901         See the examples <internallink id="jniIntercept">above</internallink>.
8902       </description>
8903       <origin>new</origin>
8904       <capabilities>
8905       </capabilities>
8906       <parameters>
8907         <param id="function_table">
8908           <inptr>
8909             <struct>jniNativeInterface</struct>
8910           </inptr>
8911           <description>
8912             Points to the new JNI function table.
8913           </description>
8914         </param>
8915       </parameters>
8916       <errors>
8917       </errors>
8918     </function>
8919     
8920     <function id="GetJNIFunctionTable" phase="start" num="121">
8921       <synopsis>Get JNI Function Table</synopsis>
8922       <description>
8923         Get the JNI function table.
8924         The JNI function table is copied into allocated memory.
8925         If <functionlink id="SetJNIFunctionTable"></functionlink> 
8926         has been called, the modified (not the original) function
8927         table is returned.
8928         Only the function table is copied, no other aspects of the environment 
8929         are copied.
8930         See the examples <internallink id="jniIntercept">above</internallink>.
8931       </description>
8932       <origin>new</origin>
8933       <capabilities>
8934       </capabilities>
8935       <parameters>
8936         <param id="function_table">
8937           <allocbuf>
8938             <struct>jniNativeInterface</struct>
8939           </allocbuf>
8940           <description>
8941             On return, <code>*function_table</code> 
8942             points a newly allocated copy of the JNI function table.
8943           </description>
8944         </param>
8945       </parameters>
8946       <errors>
8947       </errors>
8948     </function>
8949 
8950   </category>
8951 
8952   <category id="eventManagement" label="Event Management">
8953 
8954     <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
8955       <synopsis>Set Event Callbacks</synopsis>
8956       <description>
8957         Set the functions to be called for each event.
8958         The callbacks are specified by supplying a replacement function table.
8959         The function table is copied--changes to the local copy of the
8960         table have no effect.
8961         This is an atomic action, all callbacks are set at once.
8962         No events are sent before this function is called.
8963         When an entry is <code>NULL</code> or when the event is beyond 
8964         <paramlink id="size_of_callbacks"></paramlink> no event is sent.
8965         Details on events are 
8966         described <internallink id="EventSection">later</internallink> in this document.
8967         An event must be enabled and have a callback in order to be
8968         sent--the order in which this function and 
8969         <functionlink id="SetEventNotificationMode"></functionlink> 
8970         are called does not affect the result.
8971       </description>
8972       <origin>new</origin>
8973       <capabilities>
8974       </capabilities>
8975       <parameters>
8976         <param id="callbacks">
8977           <inptr>
8978             <struct>jvmtiEventCallbacks</struct>
8979             <nullok>remove the existing callbacks</nullok>
8980           </inptr>
8981           <description>
8982             The new event callbacks.
8983           </description>
8984         </param>
8985         <param id="size_of_callbacks">
8986           <jint min="0"/>
8987           <description>
8988             <code>sizeof(jvmtiEventCallbacks)</code>--for version
8989             compatibility.
8990           </description>
8991         </param>
8992       </parameters>
8993       <errors>
8994       </errors>
8995     </function>
8996 
8997     <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
8998       <synopsis>Set Event Notification Mode</synopsis>
8999       <description>
9000         Control the generation of events. 
9001         <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
9002           <constant id="JVMTI_ENABLE" num="1">
9003             If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>, 
9004             the event <paramlink id="event_type"></paramlink> will be enabled
9005           </constant>
9006           <constant id="JVMTI_DISABLE" num="0">
9007             If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>, 
9008             the event <paramlink id="event_type"></paramlink> will be disabled
9009           </constant>
9010         </constants>
9011         If <code>thread</code> is <code>NULL</code>,
9012         the event is enabled or disabled globally; otherwise, it is 
9013         enabled or disabled for a particular thread. 
9014         An event is generated for 
9015         a particular thread if it is enabled either at the thread or global
9016         levels. 
9017         <p/>
9018         See <internallink id="EventIndex">below</internallink> for information on specific events.
9019         <p/>
9020         The following events cannot be controlled at the thread
9021         level through this function. 
9022         <ul>
9023           <li><eventlink id="VMInit"></eventlink></li>
9024           <li><eventlink id="VMStart"></eventlink></li>
9025           <li><eventlink id="VMDeath"></eventlink></li>
9026           <li><eventlink id="ThreadStart"></eventlink></li>
9027           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9028           <li><eventlink id="CompiledMethodUnload"></eventlink></li>
9029           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9030           <li><eventlink id="DataDumpRequest"></eventlink></li>
9031         </ul>
9032         <p/>
9033         Initially, no events are enabled at either the thread level 
9034         or the global level.
9035         <p/>
9036         Any needed capabilities (see Event Enabling Capabilities below) must be possessed
9037         before calling this function.
9038         <p/>
9039         Details on events are 
9040         described <internallink id="EventSection">below</internallink>.
9041       </description>
9042       <origin>jvmdiClone</origin>
9043       <eventcapabilities></eventcapabilities>
9044       <parameters>
9045         <param id="mode">
9046           <enum>jvmtiEventMode</enum>
9047           <description>
9048             <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
9049           </description>
9050         </param>
9051         <param id="event_type">
9052           <enum>jvmtiEvent</enum>
9053           <description>
9054             the event to control
9055           </description>
9056         </param>
9057         <param id="event_thread">
9058           <ptrtype>
9059             <jthread impl="noconvert"/>
9060             <nullok>event is controlled at the global level</nullok>
9061           </ptrtype>
9062             <description>
9063               The thread to control
9064             </description>
9065         </param>
9066         <param id="...">
9067           <varargs/>
9068             <description>
9069               for future expansion
9070             </description>
9071         </param>
9072       </parameters>
9073       <errors>
9074         <error id="JVMTI_ERROR_INVALID_THREAD">
9075           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
9076         </error>
9077         <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
9078           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead).
9079         </error>
9080         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9081           thread level control was attempted on events which do not 
9082           permit thread level control.
9083         </error>
9084         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 
9085           The Required Event Enabling Capability is not possessed.
9086         </error>
9087       </errors>
9088     </function>
9089 
9090     <function id="GenerateEvents" num="123">
9091       <synopsis>Generate Events</synopsis>
9092       <description>
9093         Generate events to represent the current state of the VM.  
9094         For example, if <paramlink id="event_type"/> is 
9095         <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
9096         a <eventlink id="CompiledMethodLoad"></eventlink> event will be
9097         sent for each currently compiled method.
9098         Methods that were loaded and now have been unloaded are not sent.
9099         The history of what events have previously been sent does not 
9100         effect what events are sent by this function--for example, 
9101         all currently compiled methods
9102         will be sent each time this function is called.
9103         <p/>
9104         This function is useful when
9105         events may have been missed due to the agent attaching after program
9106         execution begins; this function generates the missed events.
9107         <p/>
9108         Attempts to execute Java programming language code or
9109         JNI functions may be paused until this function returns -
9110         so neither should be called from the thread sending the event.
9111         This function returns only after the missed events have been 
9112         sent, processed and have returned.
9113         The event may be sent on a different thread than the thread
9114         on which the event occurred.
9115         The callback for the event must be set with 
9116         <functionlink id="SetEventCallbacks"></functionlink> 
9117         and the event must be enabled with
9118         <functionlink id="SetEventNotificationMode"></functionlink> 
9119         or the events will not occur.
9120         If the VM no longer has the information to generate some or
9121         all of the requested events, the events are simply not sent -
9122         no error is returned.
9123         <p/>
9124         Only the following events are supported:
9125         <ul>
9126           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9127           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9128         </ul>
9129       </description>
9130       <origin>new</origin>
9131       <capabilities>
9132         <capability id="can_generate_compiled_method_load_events"></capability>
9133       </capabilities>
9134       <parameters>
9135         <param id="event_type">
9136           <enum>jvmtiEvent</enum>
9137           <description>
9138             The type of event to generate.  Must be one of these:
9139             <ul>
9140               <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
9141               <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
9142             </ul>
9143           </description>
9144         </param>
9145       </parameters>
9146       <errors>
9147         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY"> 
9148           <paramlink id="event_type"/> is 
9149           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9150           and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
9151           is <code>false</code>.
9152         </error>
9153         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 
9154           <paramlink id="event_type"/> is other than
9155           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9156           or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
9157         </error>
9158       </errors>
9159     </function>
9160 
9161   </category>
9162 
9163     <category id="extension" label="Extension Mechanism">
9164 
9165       <intro>
9166         These functions
9167         allow a <jvmti/> implementation to provide functions and events
9168         beyond those defined in this specification.
9169         <p/>
9170         Both extension functions and extension events have parameters
9171         each of which has a 'type' and 'kind' chosen from the following tables:
9172 
9173         <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
9174           <constant id="JVMTI_TYPE_JBYTE" num="101">
9175             Java programming language primitive type - <code>byte</code>. 
9176             JNI type <code>jbyte</code>.
9177           </constant>
9178           <constant id="JVMTI_TYPE_JCHAR" num="102">
9179             Java programming language primitive type - <code>char</code>. 
9180             JNI type <code>jchar</code>.
9181           </constant>
9182           <constant id="JVMTI_TYPE_JSHORT" num="103">
9183             Java programming language primitive type - <code>short</code>. 
9184             JNI type <code>jshort</code>.
9185           </constant>
9186           <constant id="JVMTI_TYPE_JINT" num="104">
9187             Java programming language primitive type - <code>int</code>. 
9188             JNI type <datalink id="jint"></datalink>.
9189           </constant>
9190           <constant id="JVMTI_TYPE_JLONG" num="105">
9191             Java programming language primitive type - <code>long</code>. 
9192             JNI type <datalink id="jlong"></datalink>.
9193           </constant>
9194           <constant id="JVMTI_TYPE_JFLOAT" num="106">
9195             Java programming language primitive type - <code>float</code>. 
9196             JNI type <datalink id="jfloat"></datalink>.
9197           </constant>
9198           <constant id="JVMTI_TYPE_JDOUBLE" num="107">
9199             Java programming language primitive type - <code>double</code>. 
9200             JNI type <datalink id="jdouble"></datalink>.
9201           </constant>
9202           <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
9203             Java programming language primitive type - <code>boolean</code>. 
9204             JNI type <datalink id="jboolean"></datalink>.
9205           </constant>
9206           <constant id="JVMTI_TYPE_JOBJECT" num="109">
9207             Java programming language object type - <code>java.lang.Object</code>. 
9208             JNI type <datalink id="jobject"></datalink>.
9209             Returned values are JNI local references and must be managed.
9210           </constant>
9211           <constant id="JVMTI_TYPE_JTHREAD" num="110">
9212             Java programming language object type - <code>java.lang.Thread</code>. 
9213             <jvmti/> type <datalink id="jthread"></datalink>.
9214             Returned values are JNI local references and must be managed.
9215           </constant>
9216           <constant id="JVMTI_TYPE_JCLASS" num="111">
9217             Java programming language object type - <code>java.lang.Class</code>. 
9218             JNI type <datalink id="jclass"></datalink>.
9219             Returned values are JNI local references and must be managed.
9220           </constant>
9221           <constant id="JVMTI_TYPE_JVALUE" num="112">
9222             Union of all Java programming language primitive and object types - 
9223             JNI type <datalink id="jvalue"></datalink>.
9224             Returned values which represent object types are JNI local references and must be managed.
9225           </constant>
9226           <constant id="JVMTI_TYPE_JFIELDID" num="113">
9227             Java programming language field identifier - 
9228             JNI type <datalink id="jfieldID"></datalink>.
9229           </constant>
9230           <constant id="JVMTI_TYPE_JMETHODID" num="114">
9231             Java programming language method identifier - 
9232             JNI type <datalink id="jmethodID"></datalink>.
9233           </constant>
9234           <constant id="JVMTI_TYPE_CCHAR" num="115">
9235             C programming language type - <code>char</code>.
9236           </constant>
9237           <constant id="JVMTI_TYPE_CVOID" num="116">
9238             C programming language type - <code>void</code>.
9239           </constant>
9240           <constant id="JVMTI_TYPE_JNIENV" num="117">
9241             JNI environment - <code>JNIEnv</code>.
9242             Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
9243           </constant>
9244         </constants>
9245 
9246         <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
9247           <constant id="JVMTI_KIND_IN" num="91">
9248             Ingoing argument - <code>foo</code>.
9249           </constant>
9250           <constant id="JVMTI_KIND_IN_PTR" num="92">
9251             Ingoing pointer argument - <code>const foo*</code>.
9252           </constant>
9253           <constant id="JVMTI_KIND_IN_BUF" num="93">
9254             Ingoing array argument - <code>const foo*</code>.
9255           </constant>
9256           <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
9257             Outgoing allocated array argument -  <code>foo**</code>.
9258             Free with <code>Deallocate</code>.
9259           </constant>
9260           <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
9261             Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
9262             Free with <code>Deallocate</code>.
9263           </constant>
9264           <constant id="JVMTI_KIND_OUT" num="96">
9265             Outgoing argument - <code>foo*</code>.
9266           </constant>
9267           <constant id="JVMTI_KIND_OUT_BUF" num="97">
9268             Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
9269             Do not <code>Deallocate</code>.
9270           </constant>
9271         </constants>
9272 
9273       </intro>
9274 
9275       <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
9276         <field id="name">
9277           <allocfieldbuf><char/></allocfieldbuf>
9278             <description>
9279               The parameter name, encoded as a
9280               <internallink id="mUTF">modified UTF-8</internallink> string
9281             </description>
9282         </field>
9283         <field id="kind">
9284           <enum>jvmtiParamKind</enum>
9285           <description>
9286             The kind of the parameter - type modifiers
9287           </description>
9288         </field>
9289         <field id="base_type">
9290           <enum>jvmtiParamTypes</enum>
9291           <description>
9292             The base type of the parameter -  modified by <code>kind</code>
9293           </description>
9294         </field>
9295         <field id="null_ok">
9296           <jboolean/>
9297             <description>
9298               Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
9299             </description>
9300         </field>
9301       </typedef>
9302 
9303       <callback id="jvmtiExtensionFunction">
9304         <enum>jvmtiError</enum>
9305           <synopsis>Extension Function</synopsis>
9306         <description>
9307           This is the implementation-specific extension function.
9308         </description>
9309         <parameters>
9310           <param id="jvmti_env">
9311             <outptr>
9312               <struct>jvmtiEnv</struct>
9313             </outptr>
9314             <description>
9315               The <jvmti/> environment is the only fixed parameter for extension functions.
9316             </description>
9317           </param>
9318           <param id="...">
9319             <varargs/>
9320               <description>
9321                 The extension function-specific parameters
9322               </description>
9323           </param>
9324         </parameters>
9325       </callback>
9326 
9327       <function id="GetExtensionFunctions" phase="onload" num="124">
9328         <synopsis>Get Extension Functions</synopsis>
9329 
9330         <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
9331           <field id="func">
9332             <ptrtype>
9333               <struct>jvmtiExtensionFunction</struct>
9334             </ptrtype>
9335             <description>
9336               The actual function to call
9337             </description>
9338           </field>
9339           <field id="id">
9340             <allocfieldbuf><char/></allocfieldbuf>
9341               <description>
9342                 The identifier for the extension function, encoded as a
9343                 <internallink id="mUTF">modified UTF-8</internallink> string.
9344                 Uses package name conventions.
9345                 For example, <code>com.sun.hotspot.bar</code>
9346               </description>
9347           </field>
9348           <field id="short_description">
9349             <allocfieldbuf><char/></allocfieldbuf>
9350               <description>
9351                 A one sentence description of the function, encoded as a
9352                 <internallink id="mUTF">modified UTF-8</internallink> string.
9353               </description>
9354           </field>
9355           <field id="param_count">
9356             <jint/>
9357               <description>
9358                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9359               </description>
9360           </field>
9361           <field id="params">
9362             <allocfieldbuf outcount="param_count">
9363               <struct>jvmtiParamInfo</struct>
9364             </allocfieldbuf>
9365             <description>
9366               Array of 
9367               <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9368               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9369             </description>
9370           </field>
9371           <field id="error_count">
9372             <jint/>
9373               <description>
9374                 The number of possible error returns (excluding universal errors)
9375               </description>
9376           </field>
9377           <field id="errors">
9378             <allocfieldbuf outcount="error_count">
9379               <enum>jvmtiError</enum>
9380             </allocfieldbuf>
9381             <description>
9382               Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9383               possible errors
9384             </description>
9385           </field>
9386         </typedef>
9387 
9388         <description>
9389           Returns the set of extension functions.
9390         </description>
9391         <origin>new</origin>
9392         <capabilities>
9393         </capabilities>
9394         <parameters>
9395           <param id="extension_count_ptr">
9396             <outptr><jint/></outptr>
9397               <description>
9398                 On return, points to the number of extension functions
9399               </description>
9400           </param>
9401           <param id="extensions">
9402             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
9403             <description>
9404               Returns an array of extension function info, one per function
9405             </description>
9406           </param>
9407         </parameters>
9408         <errors>
9409         </errors>
9410       </function>
9411 
9412       <function id="GetExtensionEvents" phase="onload" num="125">
9413         <synopsis>Get Extension Events</synopsis>
9414 
9415         <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
9416           <field id="extension_event_index">
9417             <jint/>
9418             <description>
9419               The identifying index of the event
9420             </description>
9421           </field>
9422           <field id="id">
9423             <allocfieldbuf><char/></allocfieldbuf>
9424               <description>
9425                 The identifier for the extension event, encoded as a
9426                 <internallink id="mUTF">modified UTF-8</internallink> string.
9427                 Uses package name conventions.
9428                 For example, <code>com.sun.hotspot.bar</code>
9429               </description>
9430           </field>
9431           <field id="short_description">
9432             <allocfieldbuf><char/></allocfieldbuf>
9433               <description>
9434                 A one sentence description of the event, encoded as a
9435                 <internallink id="mUTF">modified UTF-8</internallink> string.
9436               </description>
9437           </field>
9438           <field id="param_count">
9439             <jint/>
9440               <description>
9441                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9442               </description>
9443           </field>
9444           <field id="params">
9445             <allocfieldbuf outcount="param_count">
9446               <struct>jvmtiParamInfo</struct>
9447             </allocfieldbuf>
9448             <description>
9449               Array of 
9450               <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
9451               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9452             </description>
9453           </field>
9454         </typedef>
9455 
9456         <description>
9457           Returns the set of extension events.
9458         </description>
9459         <origin>new</origin>
9460         <capabilities>
9461         </capabilities>
9462         <parameters>
9463           <param id="extension_count_ptr">
9464             <outptr><jint/></outptr>
9465               <description>
9466                 On return, points to the number of extension events
9467               </description>
9468           </param>
9469           <param id="extensions">
9470             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
9471             <description>
9472               Returns an array of extension event info, one per event
9473             </description>
9474           </param>
9475         </parameters>
9476         <errors>
9477         </errors>
9478       </function>
9479 
9480       <callback id="jvmtiExtensionEvent">
9481         <void/>
9482           <synopsis>Extension Event</synopsis>
9483         <description>
9484           This is the implementation-specific event.
9485           The event handler is set with 
9486           <functionlink id="SetExtensionEventCallback"/>.
9487           <p/>
9488           Event handlers for extension events must be declared varargs to match this definition.
9489           Failure to do so could result in calling convention mismatch and undefined behavior
9490           on some platforms.
9491           <p/>
9492           For example, if the <code>jvmtiParamInfo</code>
9493           returned by <functionlink id="GetExtensionEvents"/> indicates that
9494           there is a <code>jint</code> parameter, the event handler should be
9495           declared:
9496 <example>
9497     void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...)
9498 </example>
9499           Note the terminal "<code>...</code>" which indicates varargs.
9500         </description>
9501         <parameters>
9502           <param id="jvmti_env">
9503             <outptr>
9504               <struct>jvmtiEnv</struct>
9505             </outptr>
9506             <description>
9507               The <jvmti/> environment is the only fixed parameter for extension events.
9508             </description>
9509           </param>
9510           <param id="...">
9511             <varargs/>
9512               <description>
9513                 The extension event-specific parameters
9514               </description>
9515           </param>
9516         </parameters>
9517       </callback>
9518 
9519       <function id="SetExtensionEventCallback" phase="onload" num="126">
9520         <synopsis>Set Extension Event Callback</synopsis>
9521 
9522         <description>
9523           Sets the callback function for an extension event and
9524           enables the event. Or, if the callback is <code>NULL</code>, disables
9525           the event.  Note that unlike standard events, setting
9526           the callback and enabling the event are a single operation.
9527         </description>
9528         <origin>new</origin>
9529         <capabilities>
9530         </capabilities>
9531         <parameters>
9532           <param id="extension_event_index">
9533             <jint/>
9534               <description>
9535                 Identifies which callback to set.
9536                 This index is the 
9537                 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
9538                 field of 
9539                 <datalink id="jvmtiExtensionEventInfo"/>.
9540               </description>
9541           </param>
9542           <param id="callback">
9543             <ptrtype>
9544               <struct>jvmtiExtensionEvent</struct>
9545               <nullok>disable the event</nullok>
9546             </ptrtype>
9547             <description>
9548               If <code>callback</code> is non-<code>NULL</code>, 
9549               set <code>callback</code> to be the event callback function
9550               and enable the event.
9551             </description>
9552           </param>
9553         </parameters>
9554         <errors>
9555         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT"> 
9556             <paramlink id="extension_event_index"/> is not an
9557             <fieldlink id="extension_event_index" 
9558                        struct="jvmtiExtensionEventInfo"/>
9559             returned by 
9560             <functionlink id="GetExtensionEvents"/>
9561         </error>
9562         </errors>
9563       </function>
9564 
9565     </category>
9566 
9567   <category id="capability" label="Capability">
9568 
9569     <intro>
9570       The capabilities functions allow you to change the
9571       functionality available to <jvmti/>--that is, 
9572       which <jvmti/> 
9573       functions can be called, what events can be generated,
9574       and what functionality these events and functions can
9575       provide.
9576       <p/>
9577         The "Capabilities" section of each function and event describe which 
9578         capabilities, if any, they are associated with. "Required Functionality"
9579         means it is available for use and no capabilities must be added to use it.
9580         "Optional Functionality" means the agent must possess the capability
9581         before it can be used.  
9582         To possess a capability, the agent must
9583         <functionlink id="AddCapabilities">add the capability</functionlink>.
9584         "Optional Features" describe capabilities which,
9585         if added, extend the feature set.
9586         <p/>
9587         The potentially available capabilities of each <jvmti/> implementation are different.  
9588         Depending on the implementation, a capability:
9589         <ul>
9590           <li>may never be added</li>
9591           <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
9592           <li>may be added only during the <code>OnLoad</code> phase</li>
9593           <li>may be possessed by only one environment at a time</li>
9594           <li>may be possessed by only one environment at a time, 
9595               and only during the <code>OnLoad</code> phase</li>
9596           <li>and so on ...</li>
9597         </ul>
9598       Frequently, the addition of a capability may incur a cost in execution speed, start up
9599       time, and/or memory footprint.  Note that the overhead of using a capability
9600       is completely different than the overhead of possessing a capability.
9601       Take single stepping as an example. When single stepping is on (that
9602       is, when the event is enabled and thus actively sending events) 
9603       the overhead of sending and processing an event 
9604       on each instruction is huge in any implementation. 
9605       However, the overhead of possessing the capability may be small or large, 
9606       depending on the implementation.  Also, when and if a capability is potentially
9607       available depends on the implementation.  Some examples:
9608       <ul>
9609         <li>One VM might perform all execution by compiling bytecodes into 
9610           native code and be unable to generate single step instructions.
9611           In this implementation the capability can not be added.</li>
9612         <li>Another VM may be able to switch execution to a single stepping
9613           interpreter at any time.  In this implementation, having the capability has no 
9614           overhead and could be added at any time.</li>
9615         <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
9616           execution engine at start up, but be unable to switch between them.
9617           In this implementation the capability would need to be added 
9618           during the <code>OnLoad</code> phase (before bytecode
9619           execution begins) and would have a large impact on execution speed 
9620           even if single stepping was never used.</li>
9621         <li>Still another VM might be able to add an "is single stepping on" check
9622           into compiled bytecodes or a generated interpreter.  Again in this implementation
9623           the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
9624           and branch on each instruction) would be considerably less.</li>
9625       </ul>
9626       <p/>
9627       Each <jvmti/> <internallink id="environments">environment</internallink>
9628       has its own set of capabilities.  
9629       Initially, that set is empty.
9630       Any desired capability must be added.
9631       If possible, capabilities should be added during the <code>OnLoad</code> phase.  For most 
9632       virtual machines certain capabilities require special set up for 
9633       the virtual machine and this set up must happen
9634       during the <code>OnLoad</code> phase, before the virtual machine begins execution. 
9635       Once a capability is added, it can
9636       only be removed if explicitly relinquished by the environment.
9637       <p/>
9638       The agent can, 
9639       <functionlink id="GetPotentialCapabilities">determine what
9640         capabilities this VM can potentially provide</functionlink>,
9641       <functionlink id="AddCapabilities">add the capabilities
9642         to be used</functionlink>,
9643       <functionlink id="RelinquishCapabilities">release capabilities
9644         which are no longer needed</functionlink>, and
9645       <functionlink id="GetCapabilities">examine the currently available 
9646         capabilities</functionlink>.
9647     </intro>
9648 
9649     <intro id="capabilityExamples" label="Capability Examples">
9650       For example, a freshly started agent (in the <code>OnLoad</code> function)
9651       wants to enable all possible capabilities.  
9652       Note that, in general, this is not advisable as the agent may suffer
9653       a performance penalty for functionality it is not using.
9654       The code might look like this in C:
9655       <example>
9656         jvmtiCapabilities capa;
9657         jvmtiError err;
9658 
9659         err = (*jvmti)-&gt;GetPotentialCapabilities(jvmti, &amp;capa);
9660         if (err == JVMTI_ERROR_NONE) {
9661            err = (*jvmti)-&gt;AddCapabilities(jvmti, &amp;capa);
9662       </example>
9663       For example, if an  agent wants to check if it can get
9664       the bytecodes of a method (that is, it wants to check 
9665       if it previously added this capability and has not 
9666       relinquished it), the code might 
9667       look like this in C:
9668       <example>
9669         jvmtiCapabilities capa;
9670         jvmtiError err;
9671 
9672         err = (*jvmti)-&gt;GetCapabilities(jvmti, &amp;capa);
9673         if (err == JVMTI_ERROR_NONE) {
9674            if (capa.can_get_bytecodes) { ... } } 
9675       </example>
9676     </intro>
9677 
9678     <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
9679       <description>
9680         The functions in this category use this capabilities structure 
9681         which contains boolean flags corresponding to each capability:
9682       </description>
9683       <capabilityfield id="can_tag_objects">
9684         <description>
9685           Can set and get tags, as described in the
9686           <internallink id="Heap">Heap category</internallink>.
9687         </description>
9688       </capabilityfield>
9689       <capabilityfield id="can_generate_field_modification_events">
9690         <description>
9691           Can set watchpoints on field modification -
9692           <functionlink id="SetFieldModificationWatch"></functionlink>
9693         </description>
9694       </capabilityfield>
9695       <capabilityfield id="can_generate_field_access_events">
9696         <description>
9697           Can set watchpoints on field access -
9698           <functionlink id="SetFieldAccessWatch"></functionlink>
9699         </description>
9700       </capabilityfield>
9701       <capabilityfield id="can_get_bytecodes">
9702         <description>
9703           Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
9704         </description>
9705       </capabilityfield>
9706       <capabilityfield id="can_get_synthetic_attribute">
9707         <description>
9708           Can test if a field or method is synthetic - 
9709           <functionlink id="IsFieldSynthetic"></functionlink> and
9710           <functionlink id="IsMethodSynthetic"></functionlink>
9711         </description>
9712       </capabilityfield>
9713       <capabilityfield id="can_get_owned_monitor_info">
9714         <description>
9715           Can get information about ownership of monitors - 
9716           <functionlink id="GetOwnedMonitorInfo"></functionlink>
9717         </description>
9718       </capabilityfield>
9719       <capabilityfield id="can_get_current_contended_monitor">
9720         <description>
9721           Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
9722         </description>
9723       </capabilityfield>
9724       <capabilityfield id="can_get_monitor_info">
9725       <description>
9726         Can <functionlink id="GetObjectMonitorUsage"></functionlink>
9727       </description>
9728       </capabilityfield>
9729       <capabilityfield id="can_pop_frame">
9730         <description>
9731           Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
9732         </description>
9733       </capabilityfield>
9734       <capabilityfield id="can_redefine_classes">
9735         <description>
9736           Can redefine classes with <functionlink id="RedefineClasses"/>.
9737         </description>
9738       </capabilityfield>
9739       <capabilityfield id="can_signal_thread">
9740         <description>
9741           Can send stop or interrupt to threads
9742         </description>
9743       </capabilityfield>
9744       <capabilityfield id="can_get_source_file_name">
9745         <description>
9746           Can get the source file name of a class
9747         </description>
9748       </capabilityfield>
9749       <capabilityfield id="can_get_line_numbers">
9750         <description>
9751           Can get the line number table of a method
9752         </description>
9753       </capabilityfield>
9754       <capabilityfield id="can_get_source_debug_extension">
9755         <description>
9756           Can get the source debug extension of a class
9757         </description>
9758       </capabilityfield>
9759       <capabilityfield id="can_access_local_variables">
9760         <description>
9761           Can set and get local variables
9762         </description>
9763       </capabilityfield>
9764       <capabilityfield id="can_maintain_original_method_order">
9765         <description>
9766           Can return methods in the order they occur in the class file
9767         </description>
9768       </capabilityfield>
9769       <capabilityfield id="can_generate_single_step_events">
9770         <description>
9771           Can get <eventlink id="SingleStep">single step</eventlink> events
9772         </description>
9773       </capabilityfield>
9774       <capabilityfield id="can_generate_exception_events">
9775         <description>
9776           Can get <eventlink id="Exception">exception thrown</eventlink> and 
9777             <eventlink id="ExceptionCatch">exception catch</eventlink> events
9778         </description>
9779       </capabilityfield>
9780       <capabilityfield id="can_generate_frame_pop_events">
9781         <description>
9782           Can <functionlink id="NotifyFramePop">set</functionlink> and thus get 
9783             <eventlink id="FramePop"></eventlink> events
9784         </description>
9785       </capabilityfield>
9786       <capabilityfield id="can_generate_breakpoint_events">
9787         <description>
9788           Can <functionlink id="SetBreakpoint">set</functionlink> and thus get 
9789             <eventlink id="Breakpoint"></eventlink> events
9790         </description>
9791       </capabilityfield>
9792       <capabilityfield id="can_suspend">
9793         <description>
9794           Can suspend and resume threads
9795         </description>
9796       </capabilityfield>
9797       <capabilityfield id="can_redefine_any_class">
9798         <description>
9799           Can modify (retransform or redefine) any non-primitive non-array class.
9800           See <functionlink id="IsModifiableClass"/>.
9801         </description>
9802       </capabilityfield>
9803       <capabilityfield id="can_get_current_thread_cpu_time">
9804         <description>
9805           Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
9806           current thread CPU time
9807         </description>
9808       </capabilityfield>
9809       <capabilityfield id="can_get_thread_cpu_time">
9810         <description>
9811           Can <functionlink id="GetThreadCpuTime">get</functionlink>
9812           thread CPU time
9813         </description>
9814       </capabilityfield>
9815       <capabilityfield id="can_generate_method_entry_events" 
9816                        disp1="can_generate" disp2="_method_entry_events" 
9817                        >
9818         <description>
9819           Can generate method entry events on entering a method
9820         </description>
9821       </capabilityfield>
9822       <capabilityfield id="can_generate_method_exit_events" 
9823                        disp1="can_generate" disp2="_method_exit_events" 
9824                        >
9825         <description>
9826           Can generate method exit events on leaving a method
9827         </description>
9828       </capabilityfield>
9829       <capabilityfield id="can_generate_all_class_hook_events" 
9830                        disp1="can_generate" disp2="_all_class_hook_events" 
9831                        >
9832         <description>
9833           Can generate ClassFileLoadHook events for every loaded class.
9834         </description>
9835       </capabilityfield>
9836       <capabilityfield id="can_generate_compiled_method_load_events" 
9837                        disp1="can_generate" disp2="_compiled_method_load_events" 
9838                        >
9839         <description>
9840           Can generate events when a method is compiled or unloaded
9841         </description>
9842       </capabilityfield>
9843       <capabilityfield id="can_generate_monitor_events" 
9844                        disp1="can_generate" disp2="_monitor_events" 
9845                        >
9846         <description>
9847           Can generate events on monitor activity
9848         </description>
9849       </capabilityfield>
9850       <capabilityfield id="can_generate_vm_object_alloc_events" 
9851                        disp1="can_generate" disp2="_vm_object_alloc_events" 
9852                        >
9853         <description>
9854           Can generate events on VM allocation of an object
9855         </description>
9856       </capabilityfield>
9857       <capabilityfield id="can_generate_native_method_bind_events" 
9858                        disp1="can_generate" disp2="_native_method_bind_events" 
9859                        >
9860         <description>
9861           Can generate events when a native method is bound to its
9862           implementation
9863         </description>
9864       </capabilityfield>
9865       <capabilityfield id="can_generate_garbage_collection_events" 
9866                        disp1="can_generate" disp2="_garbage_collection_events" 
9867                        >
9868         <description>
9869           Can generate events when garbage collection begins or ends
9870         </description>
9871       </capabilityfield>
9872       <capabilityfield id="can_generate_object_free_events" 
9873                        disp1="can_generate" disp2="_object_free_events" 
9874                        >
9875         <description>
9876           Can generate events when the garbage collector frees an object
9877         </description>
9878       </capabilityfield>
9879       <capabilityfield id="can_force_early_return" since="1.1">
9880         <description>
9881           Can return early from a method, as described in the
9882           <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
9883         </description>
9884       </capabilityfield>
9885       <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
9886         <description>
9887           Can get information about owned monitors with stack depth -
9888           <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
9889         </description>
9890       </capabilityfield>
9891       <capabilityfield id="can_get_constant_pool" since="1.1">
9892         <description>
9893           Can get the constant pool of a class -
9894           <functionlink id="GetConstantPool"></functionlink>
9895         </description>
9896       </capabilityfield>
9897       <capabilityfield id="can_set_native_method_prefix" since="1.1">
9898         <description>
9899           Can set prefix to be applied when native method cannot be resolved -
9900           <functionlink id="SetNativeMethodPrefix"/> and
9901           <functionlink id="SetNativeMethodPrefixes"/>
9902         </description>
9903       </capabilityfield>
9904       <capabilityfield id="can_retransform_classes" since="1.1">
9905         <description>
9906           Can retransform classes with <functionlink id="RetransformClasses"/>.
9907           In addition to the restrictions imposed by the specific 
9908           implementation on this capability (see the
9909           <internallink id="capability">Capability</internallink> section),
9910           this capability must be set before the 
9911           <eventlink id="ClassFileLoadHook"/> event is enabled for the
9912           first time in this environment.
9913           An environment that possesses this capability at the time that 
9914           <code>ClassFileLoadHook</code> is enabled for the first time is
9915           said to be <i>retransformation capable</i>.
9916           An environment that does not possess this capability at the time that 
9917           <code>ClassFileLoadHook</code> is enabled for the first time is
9918           said to be <i>retransformation incapable</i>.
9919         </description>
9920       </capabilityfield>
9921       <capabilityfield id="can_retransform_any_class" since="1.1">
9922         <description>
9923           <functionlink id="RetransformClasses"/> can be called on any class 
9924           (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
9925           must also be set)
9926         </description>
9927       </capabilityfield>
9928       <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
9929         <description>
9930           Can generate events when the VM is unable to allocate memory from 
9931           the <tm>Java</tm> platform heap.
9932           See <eventlink id="ResourceExhausted"/>.
9933         </description>
9934       </capabilityfield>
9935       <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
9936         <description>
9937           Can generate events when the VM is unable to create a thread.
9938           See <eventlink id="ResourceExhausted"/>.
9939         </description>
9940       </capabilityfield>
9941     </capabilitiestypedef>
9942 
9943     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
9944       <synopsis>Get Potential Capabilities</synopsis>
9945       <description>
9946         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/> 
9947         features that can potentially be possessed by this environment
9948         at this time.
9949         The returned capabilities differ from the complete set of capabilities
9950         implemented by the VM in two cases: another environment possesses 
9951         capabilities that can only be possessed by one environment, or the
9952         current <functionlink id="GetPhase">phase</functionlink> is live,
9953         and certain capabilities can only be added during the <code>OnLoad</code> phase.
9954         The <functionlink id="AddCapabilities"></functionlink> function
9955         may be used to set any or all or these capabilities.
9956         Currently possessed capabilities are included.
9957         <p/>
9958         Typically this function is used in the <code>OnLoad</code> function.
9959         Some virtual machines may allow a limited set of capabilities to be
9960         added in the live phase.
9961         In this case, the set of potentially available capabilities
9962         will likely differ from the <code>OnLoad</code> phase set.
9963         <p/>
9964         See the
9965         <internallink id="capabilityExamples">Capability Examples</internallink>.
9966       </description>
9967       <origin>new</origin>
9968       <capabilities>
9969       </capabilities>
9970       <parameters>
9971         <param id="capabilities_ptr">
9972           <outptr><struct>jvmtiCapabilities</struct></outptr>
9973           <description>
9974             On return, points to the <jvmti/> capabilities that may be added.
9975           </description>
9976         </param>
9977       </parameters>
9978       <errors>
9979       </errors>
9980     </function>
9981 
9982     <elide>
9983     <function id="EstimateCostOfCapabilities" phase="onload" num="141">
9984       <synopsis>Estimate Cost Of Capabilities</synopsis>
9985       <description>
9986         <issue>There is strong opposition to this function.  The concern is
9987           that it would be difficult or impossible to provide meaningful
9988           numbers, as the amount of impact is conditional on many factors
9989           that a single number could not represent.  There is doubt that
9990           conditional implementations would be used or are even a good idea.
9991           The thought is that release documentation for the implementation
9992           would be the best means of exposing this information.
9993           Unless new arguments are presented, I intend to remove this 
9994           function in the next revision.
9995         </issue>
9996         <p/>
9997         Return via the <paramlink id="time_impact_ptr"></paramlink> and
9998         <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
9999         of adding the capabilities pointed to by
10000         <paramlink id="capabilities_ptr"></paramlink>.
10001         The returned estimates are in percentage of additional overhead, thus
10002         a time impact of 100 mean the application might run
10003         at half the speed.  
10004         The estimates are very rough approximations and are not guaranteed.
10005         Note also, that the estimates are of the impact of having the
10006         capability available--when and if it is used the impact may be
10007         much greater.
10008         Estimates can be for a single capability or for a set of 
10009         capabilities.  Note that the costs are not necessarily additive,
10010         adding support for one capability might make another available 
10011         for free or conversely having two capabilities at once may 
10012         have multiplicative impact.
10013         Estimates are relative to the current set of capabilities -
10014         that is, how much more impact given the currently possessed capabilities.
10015         <p/>
10016         Typically this function is used in the OnLoad function,
10017         some virtual machines may allow a limited set of capabilities to be
10018         added in the live phase.
10019         In this case, the set of potentially available capabilities
10020         will likely differ from the OnLoad phase set.
10021         <p/>
10022         See the
10023         <internallink id="capabilityExamples">Capability Examples</internallink>.
10024       </description>
10025       <origin>new</origin>
10026       <capabilities>
10027       </capabilities>
10028       <parameters>
10029         <param id="capabilities_ptr">
10030           <inptr><struct>jvmtiCapabilities</struct></inptr>
10031           <description>
10032             points to the <jvmti/> capabilities to evaluate.
10033           </description>
10034         </param>
10035         <param id="time_impact_ptr">
10036           <outptr><jint/></outptr>
10037           <description>
10038             On return, points to the estimated percentage increase in
10039             run time if this capability was added.
10040           </description>
10041         </param>
10042         <param id="space_impact_ptr">
10043           <outptr><jint/></outptr>
10044           <description>
10045             On return, points to the estimated percentage increase in
10046             memory space used if this capability was added.
10047           </description>
10048         </param>
10049       </parameters>
10050       <errors>
10051         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10052           The desired capabilities are not even potentially available.
10053         </error>
10054       </errors>
10055     </function>
10056     </elide>
10057 
10058     <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
10059       <synopsis>Add Capabilities</synopsis>
10060       <description>
10061         Set new capabilities by adding the capabilities 
10062         whose values are set to one (<code>1</code>) in
10063         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10064         All previous capabilities are retained.
10065         Typically this function is used in the <code>OnLoad</code> function.
10066         Some virtual machines may allow a limited set of capabilities to be
10067         added in the live phase.
10068         <p/>
10069         See the
10070         <internallink id="capabilityExamples">Capability Examples</internallink>.
10071       </description>
10072       <origin>new</origin>
10073       <capabilities>
10074       </capabilities>
10075       <parameters>
10076         <param id="capabilities_ptr">
10077           <inptr><struct>jvmtiCapabilities</struct></inptr>
10078           <description>
10079             Points to the <jvmti/> capabilities to add.
10080           </description>
10081         </param>
10082       </parameters>
10083       <errors>
10084         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10085           The desired capabilities are not even potentially available.
10086         </error>
10087       </errors>
10088     </function>
10089 
10090 
10091     <function id="RelinquishCapabilities" phase="onload" num="143">
10092       <synopsis>Relinquish Capabilities</synopsis>
10093       <description>
10094         Relinquish the capabilities
10095         whose values are set to one (<code>1</code>) in
10096         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10097         Some implementations may allow only one environment to have a capability
10098         (see the <internallink id="capability">capability introduction</internallink>).
10099         This function releases capabilities
10100         so that they may be used by other agents.
10101         All other capabilities are retained.
10102         The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
10103         Attempting to relinquish a capability that the agent does not possess is not an error.
10104           <issue>
10105             It is possible for the agent to be actively using capabilities
10106             which are being relinquished.  For example, a thread is currently
10107             suspended and can_suspend is being relinquished or an event is currently
10108             enabled and can_generate_whatever is being relinquished.
10109             There are three possible ways we could spec this:
10110             <ul>
10111               <li>relinquish automatically releases them</li>
10112               <li>relinquish checks and returns some error code if held</li>
10113               <li>it is the agent's responsibility and it is not checked</li>
10114             </ul>
10115             One of these should be chosen.
10116           </issue>
10117       </description>
10118       <origin>new</origin>
10119       <capabilities>
10120       </capabilities>
10121       <parameters>
10122         <param id="capabilities_ptr">
10123           <inptr><struct>jvmtiCapabilities</struct></inptr>
10124           <description>
10125             Points to the <jvmti/> capabilities to relinquish.
10126           </description>
10127         </param>
10128       </parameters>
10129       <errors>
10130       </errors>
10131     </function>
10132 
10133 
10134 
10135     <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
10136       <synopsis>Get Capabilities</synopsis>
10137         <description>
10138           Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/> 
10139           features which this environment currently possesses.
10140           Each possessed capability is indicated by a one (<code>1</code>) in the
10141           corresponding field of the <internallink id="jvmtiCapabilities">capabilities
10142           structure</internallink>.
10143           An environment does not possess a capability unless it has been successfully added with
10144           <functionlink id="AddCapabilities"/>.
10145           An environment only loses possession of a capability if it has been relinquished with
10146           <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
10147           of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
10148           have been made.
10149           <p/>
10150           See the
10151           <internallink id="capabilityExamples">Capability Examples</internallink>.
10152         </description>
10153       <origin>jvmdiClone</origin>
10154       <capabilities>
10155       </capabilities>
10156       <parameters>
10157         <param id="capabilities_ptr">
10158           <outptr><struct>jvmtiCapabilities</struct></outptr>
10159           <description>
10160             On return, points to the <jvmti/> capabilities.
10161           </description>
10162         </param>
10163       </parameters>
10164       <errors>
10165       </errors>
10166     </function>
10167 
10168   </category>
10169   
10170   
10171   <category id="timers" label="Timers">
10172 
10173       <intro>
10174         These functions provide timing information.
10175         The resolution at which the time is updated is not specified. 
10176         They provides nanosecond precision, but not necessarily nanosecond accuracy. 
10177         Details about the timers, such as their maximum values, can be accessed with
10178         the timer information functions.  
10179       </intro>
10180 
10181       <typedef id="jvmtiTimerInfo" label="Timer Info">
10182         <description>
10183           The information function for each timer returns this data structure.
10184         </description>
10185         <field id="max_value">
10186           <jlong/>
10187             <description>
10188               The maximum value the timer can reach.
10189               After this value is reached the timer wraps back to zero.
10190               This is an unsigned value.  If tested or printed as a jlong (signed value)
10191               it may appear to be a negative number.
10192             </description>
10193         </field>
10194         <field id="may_skip_forward">
10195           <jboolean/>
10196           <description>
10197             If true, the timer can be externally adjusted and as a result skip forward.
10198             If false, the timer value will never increase faster than real time.
10199           </description>
10200         </field>
10201         <field id="may_skip_backward">
10202           <jboolean/>
10203           <description>
10204             If true, the timer can be externally adjusted and as a result skip backward.
10205             If false, the timer value will be monotonically increasing.
10206           </description>
10207         </field>
10208         <field id="kind">
10209           <enum>jvmtiTimerKind</enum>
10210           <description>
10211             The kind of timer.
10212             On a platform that does not distinguish between user and system time, <datalink 
10213                  id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
10214             is returned.
10215           </description>
10216         </field>
10217         <field id="reserved1">
10218           <jlong/>
10219             <description>
10220               Reserved for future use.
10221             </description>
10222         </field>
10223         <field id="reserved2">
10224           <jlong/>
10225             <description>
10226               Reserved for future use.
10227             </description>
10228         </field>
10229       </typedef>
10230 
10231       <intro>
10232         Where the timer kind is --
10233 
10234         <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
10235           <constant id="JVMTI_TIMER_USER_CPU" num="30">
10236             CPU time that a thread is in user mode.
10237           </constant>
10238           <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
10239             CPU time that a thread is in user or system mode.
10240           </constant>
10241           <constant id="JVMTI_TIMER_ELAPSED" num="32">
10242             Elapsed time.
10243           </constant>
10244         </constants>
10245       </intro>
10246 
10247     <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe"  impl="innative notrace" phase="start" num="134">
10248       <synopsis>Get Current Thread CPU Timer Information</synopsis>
10249       <description>
10250         Get information about the 
10251         <functionlink id="GetCurrentThreadCpuTime"/> timer. 
10252         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10253         are filled in with details about the timer.
10254         This information is specific to the platform and the implementation of
10255         <functionlink id="GetCurrentThreadCpuTime"/> and thus 
10256         does not vary by thread nor does it vary
10257         during a particular invocation of the VM.
10258         <p/>
10259         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10260         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10261         returned by <code>GetCurrentThreadCpuTimerInfo</code>
10262         and <functionlink id="GetThreadCpuTimerInfo"/>
10263         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10264       </description>
10265       <origin>new</origin>
10266       <capabilities>
10267         <required id="can_get_current_thread_cpu_time">
10268             Can get current thread CPU time.
10269         </required>
10270       </capabilities>
10271       <parameters>
10272         <param id="info_ptr">
10273           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10274           <description>
10275             On return, filled with information describing the time
10276             returned by <functionlink id="GetCurrentThreadCpuTime"/>.
10277           </description>
10278         </param>
10279       </parameters>
10280       <errors>
10281       </errors>
10282     </function>
10283 
10284     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10285       <synopsis>Get Current Thread CPU Time</synopsis>
10286       <description>
10287             Return the CPU time utilized by the current thread.  
10288             <p/>
10289             Note that the <functionlink id="GetThreadCpuTime"/>
10290             function provides CPU time for any thread, including
10291             the current thread. <code>GetCurrentThreadCpuTime</code> 
10292             exists to support platforms which cannot
10293             supply CPU time for threads other than the current 
10294             thread or which have more accurate information for
10295             the current thread (see 
10296             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10297             <functionlink id="GetThreadCpuTimerInfo"/>).
10298             On many platforms this call will be equivalent to:
10299 <example>
10300   GetThreadCpuTime(env, NULL, nanos_ptr)
10301 </example>
10302       </description>
10303       <origin>new</origin>
10304       <capabilities>
10305         <required id="can_get_current_thread_cpu_time">
10306             Can get current thread CPU time.
10307             <p/>
10308             If this capability is enabled after threads have started, 
10309             the implementation may choose any time up
10310             to and including the time that the capability is enabled 
10311             as the point where CPU time collection starts.
10312             <p/>
10313             This capability must be potentially available on any 
10314             platform where 
10315             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10316             is potentially available.
10317         </required>
10318       </capabilities>
10319       <parameters>
10320         <param id="nanos_ptr">
10321           <outptr><jlong/></outptr>
10322           <description>
10323             On return, points to the CPU time used by this thread
10324             in nanoseconds.  
10325             This is an unsigned value.  If tested or printed as a jlong (signed value)
10326             it may appear to be a negative number.
10327           </description>
10328         </param>
10329       </parameters>
10330       <errors>
10331       </errors>
10332     </function>
10333 
10334     <function id="GetThreadCpuTimerInfo" num="136">
10335       <synopsis>Get Thread CPU Timer Information</synopsis>
10336       <description>
10337         Get information about the 
10338         <functionlink id="GetThreadCpuTime"/> timer. 
10339         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10340         are filled in with details about the timer.
10341         This information is specific to the platform and the implementation of
10342         <functionlink id="GetThreadCpuTime"/> and thus 
10343         does not vary by thread nor does it vary
10344         during a particular invocation of the VM.
10345         <p/>
10346         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10347         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10348         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
10349         and <code>GetThreadCpuTimerInfo</code>
10350         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10351       </description>
10352       <origin>new</origin>
10353       <capabilities>
10354         <required id="can_get_thread_cpu_time">
10355             Can get thread CPU time.
10356         </required>
10357       </capabilities>
10358       <parameters>
10359         <param id="info_ptr">
10360           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10361           <description>
10362             On return, filled with information describing the time
10363             returned by <functionlink id="GetThreadCpuTime"/>.
10364           </description>
10365         </param>
10366       </parameters>
10367       <errors>
10368       </errors>
10369     </function>
10370 
10371     <function id="GetThreadCpuTime" num="137">
10372       <synopsis>Get Thread CPU Time</synopsis>
10373       <description>
10374           Return the CPU time utilized by the specified thread. 
10375           <p/>
10376           Get information about this timer with
10377           <functionlink id="GetThreadCpuTimerInfo"/>. 
10378       </description>
10379       <origin>new</origin>
10380       <capabilities>
10381         <required id="can_get_thread_cpu_time">
10382             Can get thread CPU time.
10383             <p/>
10384             If this capability is enabled after threads have started, 
10385             the implementation may choose any time up
10386             to and including the time that the capability is enabled 
10387             as the point where CPU time collection starts.
10388         </required>
10389       </capabilities>
10390       <parameters>
10391         <param id="thread">
10392           <jthread null="current"/>
10393             <description>
10394               The thread to query.
10395             </description>
10396         </param>
10397         <param id="nanos_ptr">
10398           <outptr><jlong/></outptr>
10399           <description>
10400             On return, points to the CPU time used by the specified thread
10401             in nanoseconds.  
10402             This is an unsigned value.  If tested or printed as a jlong (signed value)
10403             it may appear to be a negative number.
10404           </description>
10405         </param>
10406       </parameters>
10407       <errors>
10408       </errors>
10409     </function>
10410 
10411     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
10412       <synopsis>Get Timer Information</synopsis>
10413       <description>
10414         Get information about the 
10415         <functionlink id="GetTime"/> timer. 
10416         The fields of the <datalink id="jvmtiTimerInfo"/> structure 
10417         are filled in with details about the timer.
10418         This information will not change during a particular invocation of the VM.
10419       </description>
10420       <origin>new</origin>
10421       <capabilities>
10422       </capabilities>
10423       <parameters>
10424         <param id="info_ptr">
10425           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10426           <description>
10427             On return, filled with information describing the time
10428             returned by <functionlink id="GetTime"/>.
10429           </description>
10430         </param>
10431       </parameters>
10432       <errors>
10433       </errors>
10434     </function>
10435 
10436     <function id="GetTime" phase="any" callbacksafe="safe" num="139">
10437       <synopsis>Get Time</synopsis>
10438       <description>
10439           Return the current value of the system timer, in nanoseconds. 
10440           <p/>
10441           The value returned represents nanoseconds since some fixed but
10442           arbitrary time (perhaps in the future, so values may be
10443           negative).  This function provides nanosecond precision, but not
10444           necessarily nanosecond accuracy. No guarantees are made about
10445           how frequently values change.
10446           <p/>
10447           Get information about this timer with
10448           <functionlink id="GetTimerInfo"/>. 
10449       </description>
10450       <origin>new</origin>
10451       <capabilities>
10452       </capabilities>
10453       <parameters>
10454         <param id="nanos_ptr">
10455           <outptr><jlong/></outptr>
10456           <description>
10457             On return, points to the time in nanoseconds.  
10458             This is an unsigned value.  If tested or printed as a jlong (signed value)
10459             it may appear to be a negative number.
10460           </description>
10461         </param>
10462       </parameters>
10463       <errors>
10464       </errors>
10465     </function>
10466 
10467     <function id="GetAvailableProcessors" phase="any" num="144">
10468       <synopsis>Get Available Processors</synopsis>
10469       <description>
10470           Returns the number of processors available to the Java virtual machine.
10471           <p/>
10472           This value may change during a particular invocation of the virtual machine. 
10473           Applications that are sensitive to the number of available processors should
10474           therefore occasionally poll this property.
10475       </description>
10476       <origin>new</origin>
10477       <capabilities>
10478       </capabilities>
10479       <parameters>
10480         <param id="processor_count_ptr">
10481           <outptr><jint/></outptr>
10482           <description>
10483             On return, points to the maximum number of processors available to the
10484             virtual machine; never smaller than one.  
10485           </description>
10486         </param>
10487       </parameters>
10488       <errors>
10489       </errors>
10490     </function>
10491 
10492   </category>
10493 
10494 
10495   <category id="classLoaderSearch" label="Class Loader Search">
10496 
10497     <intro>
10498       These functions allow the agent to add to the locations that a class loader searches for a class.
10499       This is useful for installing instrumentation under the correct class loader.
10500     </intro>
10501 
10502     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
10503       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
10504       <description>
10505           This function can be used to cause instrumentation classes to be defined by the 
10506           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
10507           After the bootstrap
10508           class loader unsuccessfully searches for a class, the specified platform-dependent 
10509           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in 
10510           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, 
10511           the segments will be searched in the order that this function was called.
10512           <p/>
10513           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10514           search path segment to be searched after the bootstrap class loader unsuccessfully searches
10515           for a class. The segment is typically a directory or JAR file.
10516           <p/>      
10517           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
10518           path to a <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">
10519           JAR file</externallink>. The agent should take care that the JAR file does not
10520           contain any classes or resources other than those to be defined by the bootstrap
10521           class loader for the purposes of instrumentation.
10522           <p/>
10523           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10524           reference that the Java virtual machine has previously unsuccessfully attempted
10525           to resolve always fails with the same error that was thrown as a result of the
10526           initial resolution attempt. Consequently, if the JAR file contains an entry
10527           that corresponds to a class for which the Java virtual machine has
10528           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10529           resolve that reference will fail with the same error as the initial attempt.
10530       </description>
10531       <origin>new</origin>
10532       <capabilities>
10533       </capabilities>
10534       <parameters>
10535         <param id="segment">
10536           <inbuf><char/></inbuf>
10537           <description>
10538             The platform-dependent search path segment, encoded as a
10539             <internallink id="mUTF">modified UTF-8</internallink> string.
10540           </description>
10541         </param>
10542       </parameters>
10543       <errors>
10544         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">   
10545           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10546            existing JAR file is an invalid path.
10547         </error>
10548       </errors>
10549     </function>
10550 
10551     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
10552       <synopsis>Add To System Class Loader Search</synopsis>
10553       <description>
10554           This function can be used to cause instrumentation classes to be
10555           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
10556           After the class loader unsuccessfully searches for a class, the specified platform-dependent search 
10557           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the 
10558           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the 
10559           segments will be searched in the order that this function was called.
10560           <p/>
10561           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent 
10562           search path segment to be searched after the system class loader unsuccessfully searches
10563           for a class. The segment is typically a directory or JAR file.
10564           <p/>      
10565           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a <externallink 
10566           id="http://docs.oracle.com/javase/7/docs/technotes/guides/jar/jar.html">JAR file</externallink> to be
10567           searched after the system class loader unsuccessfully searches for a class. The agent should
10568           take care that the JAR file does not contain any classes or resources other than those to be
10569           defined by the system class loader for the purposes of instrumentation.
10570           <p/>
10571           In the live phase the system class loader supports adding a JAR file to be searched if
10572           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code> 
10573           which takes a single parameter of type <code>java.lang.String</code>. The method is not required 
10574           to have <code>public</code> access. 
10575           <p/>
10576           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10577           reference that the Java virtual machine has previously unsuccessfully attempted
10578           to resolve always fails with the same error that was thrown as a result of the
10579           initial resolution attempt. Consequently, if the JAR file contains an entry
10580           that corresponds to a class for which the Java virtual machine has
10581           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10582           resolve that reference will fail with the same error as the initial attempt.
10583       </description>
10584       <origin>new</origin>
10585       <capabilities>
10586       </capabilities>
10587       <parameters>
10588         <param id="segment">
10589           <inbuf><char/></inbuf>
10590           <description>
10591             The platform-dependent search path segment, encoded as a
10592             <internallink id="mUTF">modified UTF-8</internallink> string.
10593           </description>
10594         </param>
10595       </parameters>
10596       <errors>
10597         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
10598           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10599            existing JAR file is an invalid path.
10600         </error>
10601         <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
10602           Operation not supported by the system class loader.
10603         </error>                                                                                         
10604       </errors>
10605     </function>
10606 
10607   </category>
10608 
10609 
10610   <category id="props" label="System Properties">
10611 
10612     <intro>
10613       These functions get and set system properties.
10614     </intro>
10615 
10616     <function id="GetSystemProperties" phase="onload" num="130">
10617       <synopsis>Get System Properties</synopsis>
10618       <description>
10619         The list of VM system property keys which may be used with 
10620         <functionlink id="GetSystemProperty"/> is returned.
10621         It is strongly recommended that virtual machines provide the
10622         following property keys:
10623         <ul>
10624           <li><code>java.vm.vendor</code></li>
10625           <li><code>java.vm.version</code></li>
10626           <li><code>java.vm.name</code></li>
10627           <li><code>java.vm.info</code></li>
10628           <li><code>java.library.path</code></li>
10629           <li><code>java.class.path</code></li>
10630         </ul>
10631         Provides access to system properties defined by and used
10632         by the VM.
10633         Properties set on the command-line are included.
10634         This allows getting and setting of these properties 
10635         before the VM even begins executing bytecodes.
10636         Since this is a VM view of system properties, the set of available 
10637         properties will usually be different than that
10638         in <code>java.lang.System.getProperties</code>.
10639         JNI method invocation may be used to access 
10640         <code>java.lang.System.getProperties</code>.
10641         <p/>
10642         The set of properties may grow during execution.          
10643       </description>
10644       <origin>new</origin>
10645       <capabilities>
10646       </capabilities>
10647       <parameters>
10648         <param id="count_ptr">
10649           <outptr><jint/></outptr>
10650           <description>
10651             On return, points to the number of property keys returned.
10652           </description>
10653         </param>
10654         <param id="property_ptr">
10655           <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
10656           <description>
10657             On return, points to an array of property keys, encoded as 
10658             <internallink id="mUTF">modified UTF-8</internallink> strings.
10659           </description>
10660         </param>
10661       </parameters>
10662       <errors>
10663       </errors>
10664     </function>
10665 
10666     <function id="GetSystemProperty" phase="onload" num="131">
10667       <synopsis>Get System Property</synopsis>
10668       <description>
10669         Return a VM system property value given the property key.  
10670         <p/>
10671         The function <functionlink id="GetSystemProperties"/>
10672         returns the set of property keys which may be used.
10673         The properties which can be retrieved may grow during
10674         execution.
10675         <p/>
10676         Since this is a VM view of system properties, the values 
10677         of properties may differ from that returned by 
10678         <code>java.lang.System.getProperty(String)</code>.
10679         A typical VM might copy the values of the VM system 
10680         properties into the <code>Properties</code> held by
10681         <code>java.lang.System</code> during the initialization
10682         of that class. Thereafter any changes to the VM system
10683         properties (with <functionlink id="SetSystemProperty"/>) 
10684         or the <code>java.lang.System</code> system properties
10685         (with <code>java.lang.System.setProperty(String,String)</code>)
10686         would cause the values to diverge.
10687         JNI method invocation may be used to access 
10688         <code>java.lang.System.getProperty(String)</code>.
10689       </description>
10690       <origin>new</origin>
10691       <capabilities>
10692       </capabilities>
10693       <parameters>
10694         <param id="property">
10695           <inbuf><char/></inbuf>
10696           <description>
10697             The key of the property to retrieve, encoded as a
10698             <internallink id="mUTF">modified UTF-8</internallink> string.
10699           </description>
10700         </param>
10701         <param id="value_ptr">
10702           <allocbuf><char/></allocbuf>
10703           <description>
10704             On return, points to the property value, encoded as a
10705             <internallink id="mUTF">modified UTF-8</internallink> string.
10706           </description>
10707         </param>
10708       </parameters>
10709       <errors>
10710         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10711           This property is not available.
10712           Use <functionlink id="GetSystemProperties"/> to find available properties.
10713         </error>
10714       </errors>
10715     </function>
10716 
10717     <function id="SetSystemProperty" phase="onloadOnly" num="132">
10718       <synopsis>Set System Property</synopsis>
10719       <description>
10720         Set a VM system property value.  
10721         <p/>
10722         The function <functionlink id="GetSystemProperties"/>
10723         returns the set of property keys, some of these may be settable.
10724         See <functionlink id="GetSystemProperty"/>.
10725       </description>
10726       <origin>new</origin>
10727       <capabilities>
10728       </capabilities>
10729       <parameters>
10730         <param id="property">
10731           <inbuf><char/></inbuf>
10732           <description>
10733             The key of the property, encoded as a
10734             <internallink id="mUTF">modified UTF-8</internallink> string.
10735           </description>
10736         </param>
10737         <param id="value_ptr">
10738           <inbuf>
10739             <char/>
10740             <nullok>
10741               do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
10742               if the property is not writeable
10743             </nullok>
10744           </inbuf>
10745           <description>
10746             The property value to set, encoded as a
10747             <internallink id="mUTF">modified UTF-8</internallink> string.
10748           </description>
10749         </param>
10750       </parameters>
10751       <errors>
10752         <error id="JVMTI_ERROR_NOT_AVAILABLE"> 
10753           This property is not available or is not writeable.
10754         </error>
10755       </errors>
10756     </function>
10757 
10758   </category>
10759 
10760   <category id="general" label="General">
10761 
10762     <intro>
10763     </intro>
10764 
10765     <function id="GetPhase" jkernel="yes" phase="any" num="133">
10766       <synopsis>Get Phase</synopsis>
10767       <description>
10768           Return the current phase of VM execution.  
10769           The phases proceed in sequence:
10770           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
10771             <constant id="JVMTI_PHASE_ONLOAD" num="1">
10772               <code>OnLoad</code> phase: while in the
10773               <internallink id="onload"><code>Agent_OnLoad</code></internallink> or, for statically linked agents, the <internallink id="onload"><code>Agent_OnLoad_&lt;agent-lib-name&gt;</code></internallink> function.
10774             </constant>
10775             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
10776               Primordial phase: between return from <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> and the
10777               <code>VMStart</code> event.
10778             </constant>
10779             <constant id="JVMTI_PHASE_START" num="6">
10780               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event 
10781               is sent and until the <code>VMInit</code> event is sent.
10782             </constant>
10783             <constant id="JVMTI_PHASE_LIVE" num="4">
10784               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
10785               and until the <eventlink id="VMDeath"></eventlink> event returns.
10786             </constant>
10787             <constant id="JVMTI_PHASE_DEAD" num="8">
10788               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
10789               start-up failure.
10790             </constant>
10791           </constants>
10792           In the case of start-up failure the VM will proceed directly to the dead
10793           phase skipping intermediate phases and neither a <code>VMInit</code> nor
10794           <code>VMDeath</code> event will be sent.
10795           <p/>
10796           Most <jvmti/> functions operate only in the live phase.
10797           The following functions operate in either the <code>OnLoad</code> or live phases:
10798           <functionphaselist phase="onload"/>
10799           The following functions operate in only the <code>OnLoad</code> phase:
10800           <functionphaselist phase="onloadOnly"/>
10801           The following functions operate in the start or live phases:
10802           <functionphaselist phase="start"/>
10803           The following functions operate in any phase:
10804           <functionphaselist phase="any"/>
10805           JNI functions (except the Invocation API) must only be used in the start or live phases.
10806           <p/>
10807           Most <jvmti/> events are sent only in the live phase.
10808           The following events operate in others phases:
10809           <eventphaselist phase="start"/>          
10810           <eventphaselist phase="any"/>          
10811       </description>
10812       <origin>new</origin>
10813       <capabilities>
10814       </capabilities>
10815       <parameters>
10816         <param id="phase_ptr">
10817           <outptr><enum>jvmtiPhase</enum></outptr>
10818           <description>
10819             On return, points to the phase.
10820           </description>
10821         </param>
10822       </parameters>
10823       <errors>
10824       </errors>
10825     </function>
10826 
10827     <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
10828       <synopsis>Dispose Environment</synopsis>
10829       <description>
10830         Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
10831         (see <internallink id="environments"><jvmti/> Environments</internallink>).
10832         Dispose of any resources held by the environment.  
10833         <issue>
10834             What resources are reclaimed? What is undone?
10835             Breakpoints,watchpoints removed?
10836         </issue>
10837         Threads suspended by this environment are not resumed by this call,
10838         this must be done explicitly by the agent.
10839         Memory allocated by this environment via calls to <jvmti/> functions
10840         is not released, this can be done explicitly by the agent
10841         by calling <functionlink id="Deallocate"/>.
10842         Raw monitors created by this environment are not destroyed, 
10843         this can be done explicitly by the agent
10844         by calling <functionlink id="DestroyRawMonitor"/>.
10845         The state of threads waiting on raw monitors created by this environment
10846         are not affected.
10847         <p/>
10848         Any <functionlink id="SetNativeMethodPrefix">native method
10849         prefixes</functionlink> for this environment will be unset;
10850         the agent must remove any prefixed native methods before
10851         dispose is called.
10852         <p/>
10853         Any <internallink id="capability">capabilities</internallink>
10854         held by this environment are relinquished.
10855         <p/>
10856         Events enabled by this environment will no longer be sent, however
10857         event handlers currently running will continue to run.  Caution must
10858         be exercised in the design of event handlers whose environment may
10859         be disposed and thus become invalid during their execution.
10860         <p/>
10861         This environment may not be used after this call.
10862         This call returns to the caller.
10863       </description>
10864       <origin>new</origin>
10865       <capabilities>
10866       </capabilities>
10867       <parameters>
10868       </parameters>
10869       <errors>
10870       </errors>
10871     </function>
10872 
10873     <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
10874       <synopsis>Set Environment Local Storage</synopsis>
10875       <description>
10876         The VM stores a pointer value associated with each environment.
10877         This pointer value is called <i>environment-local storage</i>.
10878         This value is <code>NULL</code> unless set with this function.
10879         Agents can allocate memory in which they store environment specific
10880         information. By setting environment-local storage it can then be
10881         accessed with 
10882         <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
10883         <p/>
10884         Called by the agent to set the value of the <jvmti/>
10885         environment-local storage. <jvmti/> supplies to the agent a pointer-size
10886         environment-local storage that can be used to record per-environment
10887         information.
10888       </description>
10889       <origin>new</origin>
10890       <capabilities>
10891       </capabilities>
10892       <parameters>
10893         <param id="data">
10894           <inbuf> 
10895             <void/> 
10896             <nullok>value is set to <code>NULL</code></nullok> 
10897           </inbuf> 
10898           <description>
10899             The value to be entered into the environment-local storage.
10900           </description>
10901         </param>
10902       </parameters>
10903       <errors>
10904       </errors>
10905     </function>
10906 
10907     <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
10908       <synopsis>Get Environment Local Storage</synopsis>
10909       <description>
10910         Called by the agent to get the value of the <jvmti/> environment-local
10911         storage. 
10912       </description>
10913       <origin>new</origin>
10914       <capabilities>
10915       </capabilities>
10916       <parameters>
10917         <param id="data_ptr">
10918           <agentbuf><void/></agentbuf>
10919           <description>
10920             Pointer through which the value of the environment local 
10921             storage is returned.
10922             If environment-local storage has not been set with
10923             <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned 
10924             pointer is <code>NULL</code>.
10925           </description>
10926         </param>
10927       </parameters>
10928       <errors>
10929       </errors>
10930     </function>
10931 
10932     <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
10933       <synopsis>Get Version Number</synopsis>
10934       <description>
10935         Return the <jvmti/> version via <code>version_ptr</code>.
10936         The return value is the version identifier. 
10937         The version identifier includes major, minor and micro
10938         version as well as the interface type.
10939         <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
10940           <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
10941             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
10942           </constant>
10943           <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
10944             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
10945           </constant>
10946         </constants>
10947         <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
10948           <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
10949             Mask to extract interface type.  
10950             The value of the version returned by this function masked with
10951             <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
10952             <code>JVMTI_VERSION_INTERFACE_JVMTI</code> 
10953             since this is a <jvmti/> function.
10954           </constant>
10955           <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
10956             Mask to extract major version number.
10957           </constant>
10958           <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
10959             Mask to extract minor version number.
10960           </constant>
10961           <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
10962             Mask to extract micro version number.
10963           </constant>
10964         </constants>
10965         <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
10966           <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
10967             Shift to extract major version number.
10968           </constant>
10969           <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
10970             Shift to extract minor version number.
10971           </constant>
10972           <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
10973             Shift to extract micro version number.
10974           </constant>
10975         </constants>
10976       </description>
10977       <origin>jvmdi</origin>
10978       <capabilities>
10979       </capabilities>
10980       <parameters>
10981         <param id="version_ptr">
10982           <outptr><jint/></outptr>
10983           <description>
10984             On return, points to the <jvmti/> version.
10985           </description>
10986         </param>
10987       </parameters>
10988       <errors>
10989       </errors>
10990     </function>
10991 
10992 
10993     <function id="GetErrorName" phase="any" num="128">
10994       <synopsis>Get Error Name</synopsis>
10995       <description>
10996         Return the symbolic name for an 
10997           <internallink id="ErrorSection">error code</internallink>.  
10998         <p/>
10999         For example 
11000         <code>GetErrorName(env, JVMTI_ERROR_NONE, &amp;err_name)</code> 
11001         would return in <code>err_name</code> the string
11002         <code>"JVMTI_ERROR_NONE"</code>.
11003       </description>
11004       <origin>new</origin>
11005       <capabilities>
11006       </capabilities>
11007       <parameters>
11008         <param id="error">
11009           <enum>jvmtiError</enum>
11010           <description>
11011             The error code.
11012           </description>
11013         </param>
11014         <param id="name_ptr">
11015           <allocbuf><char/></allocbuf>
11016           <description>
11017             On return, points to the error name.
11018             The name is encoded as a
11019             <internallink id="mUTF">modified UTF-8</internallink> string,
11020             but is restricted to the ASCII subset.
11021           </description>
11022         </param>
11023       </parameters>
11024       <errors>
11025       </errors>
11026     </function>
11027 
11028     <function id="SetVerboseFlag" phase="any" num="150">
11029       <synopsis>Set Verbose Flag</synopsis>
11030       <description>
11031         <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
11032           <constant id="JVMTI_VERBOSE_OTHER" num="0">
11033             Verbose output other than the below.
11034           </constant>
11035           <constant id="JVMTI_VERBOSE_GC" num="1">
11036             Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
11037           </constant>
11038           <constant id="JVMTI_VERBOSE_CLASS" num="2">
11039             Verbose class loading output, like that specified with <code>-verbose:class</code>.
11040           </constant>
11041           <constant id="JVMTI_VERBOSE_JNI" num="4">
11042             Verbose JNI output, like that specified with <code>-verbose:jni</code>.
11043           </constant>
11044         </constants>
11045         Control verbose output.
11046         This is the output which typically is sent to <code>stderr</code>. 
11047       </description>
11048       <origin>new</origin>
11049       <capabilities>
11050       </capabilities>
11051       <parameters>
11052         <param id="flag">
11053           <enum>jvmtiVerboseFlag</enum>
11054           <description>
11055             Which verbose flag to set.
11056           </description>
11057         </param>
11058         <param id="value">
11059           <jboolean/>
11060           <description>
11061             New value of the flag.
11062           </description>
11063         </param>
11064       </parameters>
11065       <errors>
11066       </errors>
11067     </function>
11068 
11069 
11070     <function id="GetJLocationFormat" phase="any" num="129">
11071       <synopsis>Get JLocation Format</synopsis>
11072       <description>
11073         Although the greatest functionality is achieved with location information
11074         referencing the virtual machine bytecode index, the definition of
11075         <code>jlocation</code> has intentionally been left unconstrained to allow VM 
11076         implementations that do not have this information.
11077         <p/>
11078         This function describes the representation of <code>jlocation</code> used in this VM.
11079         If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>, 
11080         <code>jlocation</code>s can
11081         be used as in indices into the array returned by
11082         <functionlink id="GetBytecodes"></functionlink>.  
11083         <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
11084           <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
11085             <code>jlocation</code> values represent virtual machine 
11086             bytecode indices--that is, offsets into the 
11087             virtual machine code for a method.
11088           </constant>
11089           <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
11090             <code>jlocation</code> values represent native machine
11091             program counter values.
11092           </constant>
11093           <constant id="JVMTI_JLOCATION_OTHER" num="0">
11094             <code>jlocation</code> values have some other representation.
11095           </constant>
11096         </constants>
11097       </description>
11098       <origin>new</origin>
11099       <capabilities>
11100       </capabilities>
11101       <parameters>
11102         <param id="format_ptr">
11103           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11104           <description>
11105             On return, points to the format identifier for <code>jlocation</code> values.
11106           </description>
11107         </param>
11108       </parameters>
11109       <errors>
11110       </errors>
11111     </function>
11112 
11113   </category>
11114 
11115 </functionsection>
11116 
11117 <errorsection label="Error Reference">
11118   <intro>
11119     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11120     <p/>
11121     It is the responsibility of the agent to call <jvmti/> functions with 
11122     valid parameters and in the proper context (calling thread is attached,
11123     phase is correct, etc.).  
11124     Detecting some error conditions may be difficult, inefficient, or 
11125     impossible for an implementation.
11126     The errors listed in 
11127     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11128     must be detected by the implementation.
11129     All other errors represent the recommended response to the error
11130     condition. 
11131   </intro>
11132 
11133   <errorcategory id="universal-error" label="Universal Errors">
11134     <intro>
11135       The following errors may be returned by any function
11136     </intro>
11137 
11138     <errorid id="JVMTI_ERROR_NONE" num="0">
11139       No error has occurred.  This is the error code that is returned
11140       on successful completion of the function.
11141     </errorid>
11142     <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
11143       Pointer is unexpectedly <code>NULL</code>.
11144     </errorid>
11145     <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
11146       The function attempted to allocate memory and no more memory was 
11147       available for allocation.
11148     </errorid>
11149     <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
11150       The desired functionality has not been enabled in this virtual machine.
11151     </errorid>
11152     <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
11153       The thread being used to call this function is not attached
11154       to the virtual machine.  Calls must be made from attached threads.
11155       See <code>AttachCurrentThread</code> in the JNI invocation API.
11156     </errorid>
11157     <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
11158       The <jvmti/> environment provided is no longer connected or is
11159       not an environment.
11160     </errorid>
11161     <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
11162       The desired functionality is not available in the current
11163         <functionlink id="GetPhase">phase</functionlink>.
11164       Always returned if the virtual machine has completed running.
11165     </errorid>
11166     <errorid id="JVMTI_ERROR_INTERNAL" num="113">
11167       An unexpected internal error has occurred.
11168     </errorid>
11169   </errorcategory>
11170 
11171   <errorcategory id="reqerrors" label="Function Specific Required Errors">
11172     <intro>
11173       The following errors are returned by some <jvmti/> functions and must
11174       be returned by the implementation when the condition occurs.
11175     </intro>
11176 
11177     <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
11178       Invalid priority.
11179     </errorid>
11180     <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
11181       Thread was not suspended.
11182     </errorid>
11183     <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
11184       Thread already suspended.
11185     </errorid>
11186     <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
11187       This operation requires the thread to be alive--that is,
11188       it must be started and not yet have died.
11189     </errorid>
11190     <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
11191       The class has been loaded but not yet prepared.
11192     </errorid>
11193     <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
11194       There are no Java programming language or JNI stack frames at the specified depth.
11195     </errorid>
11196     <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
11197       Information about the frame is not available (e.g. for native frames).
11198     </errorid>
11199     <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
11200       Item already set.
11201     </errorid>
11202     <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
11203       Desired element (e.g. field or breakpoint) not found
11204     </errorid>
11205     <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
11206       This thread doesn't own the raw monitor.
11207     </errorid>
11208     <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
11209       The call has been interrupted before completion.
11210     </errorid>
11211     <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
11212       The class cannot be modified.
11213     </errorid>
11214     <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
11215       The functionality is not available in this virtual machine.
11216     </errorid>
11217     <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
11218       The requested information is not available.
11219     </errorid>
11220     <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
11221       The specified event type ID is not recognized.
11222     </errorid>
11223     <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
11224       The requested information is not available for native method.
11225     </errorid>
11226     <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
11227       The class loader does not support this operation.
11228     </errorid>
11229   </errorcategory>
11230 
11231   <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
11232     <intro>
11233       The following errors are returned by some <jvmti/> functions.
11234       They are returned in the event of invalid parameters passed by the
11235       agent or usage in an invalid context.  
11236       An implementation is not required to detect these errors.
11237     </intro>
11238 
11239     <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
11240       The passed thread is not a valid thread.
11241     </errorid>
11242     <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
11243       Invalid field.
11244     </errorid>
11245     <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
11246       Invalid method.
11247     </errorid>
11248     <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
11249       Invalid location.
11250     </errorid>
11251     <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
11252       Invalid object.
11253     </errorid>
11254     <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
11255       Invalid class.
11256     </errorid>
11257     <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
11258       The variable is not an appropriate type for the function used.
11259     </errorid>
11260     <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
11261       Invalid slot.
11262     </errorid>
11263     <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
11264       The capability being used is false in this environment.
11265     </errorid>
11266     <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
11267       Thread group invalid.
11268     </errorid>
11269     <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
11270       Invalid raw monitor.
11271     </errorid>
11272     <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
11273       Illegal argument.
11274     </errorid>
11275     <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
11276       The state of the thread has been modified, and is now inconsistent.
11277     </errorid>
11278     <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
11279       A new class file has a version number not supported by this VM.
11280     </errorid>
11281     <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
11282       A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
11283     </errorid>
11284     <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
11285       The new class file definitions would lead to a circular
11286       definition (the VM would return a <code>ClassCircularityError</code>).
11287     </errorid>
11288     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
11289       A new class file would require adding a method.
11290     </errorid>
11291     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
11292       A new class version changes a field.
11293     </errorid>
11294     <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
11295       The class bytes fail verification.
11296     </errorid>
11297     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
11298       A direct superclass is different for the new class
11299       version, or the set of directly implemented
11300       interfaces is different.
11301     </errorid>
11302     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
11303       A new class version does not declare a method
11304       declared in the old class version.
11305     </errorid>
11306     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
11307       The class name defined in the new class file is 
11308       different from the name in the old class object.
11309     </errorid>
11310     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
11311       A new class version has different modifiers.
11312     </errorid>
11313     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
11314       A method in the new class version has different modifiers
11315       than its counterpart in the old class version.
11316     </errorid>
11317   </errorcategory>
11318 </errorsection>
11319 
11320 <eventsection label="Events">
11321   <intro label="Handling Events" id="eventIntro">
11322     Agents can be informed of many events that occur in application
11323     programs.
11324     <p/>
11325     To handle events, designate a set of callback functions with
11326     <functionlink id="SetEventCallbacks"></functionlink>. 
11327     For each event the corresponding callback function will be 
11328     called.
11329     Arguments to the callback function provide additional
11330     information about the event. 
11331     <p/>
11332     The callback function is usually called from within an application 
11333     thread. The <jvmti/> implementation does not 
11334     queue events in any way. This means
11335     that event callback functions must be written 
11336     carefully. Here are some general guidelines. See 
11337     the individual event descriptions for further
11338     suggestions.
11339     <p/>
11340     <ul>
11341       <li>Any exception thrown during the execution of an event callback can 
11342         overwrite any current pending exception in the current application thread.
11343         Care must be taken to preserve a pending exception
11344         when an event callback makes a JNI call that might generate an exception.
11345       </li>
11346       <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
11347         not queue events. If an agent needs to process events one at a time, it 
11348         can use a raw monitor inside the 
11349         event callback functions to serialize event processing.
11350       </li>
11351       <li>Event callback functions that execute JNI's FindClass function to load
11352         classes need to note that FindClass locates the class loader associated 
11353         with the current native method. For the purposes of class loading, an
11354         event callback that includes a JNI environment as a parameter to the
11355         callback will treated as if it is a native call, where the native method
11356         is in the class of the event thread's current frame.
11357       </li>
11358     </ul>
11359     <p/>
11360     Some <jvmti/> events identify objects with JNI references. 
11361     All references 
11362     in <jvmti/> events are JNI local references and will become invalid
11363     after the event callback returns.
11364     Unless stated otherwise, memory referenced by pointers sent in event
11365     callbacks may not be referenced after the event callback returns.
11366     <p/>
11367     Except where stated otherwise, events are delivered on the thread
11368     that caused the event.
11369     Events are sent at the time they occur.
11370     The specification for each event includes the set of
11371     <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
11372     if an event triggering activity occurs during another phase, no event 
11373     is sent. 
11374     <p/>
11375     A thread that generates an event does not change its execution status
11376     (for example, the event does not cause the thread to be suspended).
11377     If an agent wishes the event to result in suspension, then the agent
11378     is responsible for explicitly suspending the thread with 
11379     <functionlink id="SuspendThread"></functionlink>.
11380     <p/>
11381     If an event is enabled in multiple environments, the event will be sent
11382     to each agent in the order that the environments were created.
11383   </intro>
11384 
11385   <intro label="Enabling Events" id="enablingevents">
11386     All events are initially disabled.  In order to receive any
11387     event:
11388       <ul>
11389         <li>
11390           If the event requires a capability, that capability must
11391           be added with 
11392           <functionlink id="AddCapabilities"></functionlink>.
11393         </li>
11394         <li>
11395           A callback for the event must be set with 
11396           <functionlink id="SetEventCallbacks"></functionlink>.
11397         </li>
11398         <li>
11399           The event must be enabled with
11400           <functionlink id="SetEventNotificationMode"></functionlink>. 
11401         </li>
11402       </ul>
11403   </intro>
11404 
11405   <intro label="Multiple Co-located Events" id="eventorder">
11406     In many situations it is possible for multiple events to occur 
11407     at the same location in one thread. When this happens, all the events 
11408     are reported through the event callbacks in the order specified in this section.
11409     <p/>
11410     If the current location is at the entry point of a method, the 
11411     <eventlink id="MethodEntry"></eventlink> event is reported before
11412     any other event at the current location in the same thread.
11413     <p/>
11414     If an exception catch has been detected at the current location,
11415     either because it is the beginning of a catch clause or a native method
11416     that cleared a pending exception has returned, the
11417     <code>exceptionCatch</code> event is reported before
11418     any other event at the current location in the same thread.
11419     <p/>
11420     If a <code>singleStep</code> event or 
11421     <code>breakpoint</code> event is triggered at the 
11422     current location, the event is defined to occur 
11423     immediately before the code at the current location is executed. 
11424     These events are reported before any events which are triggered 
11425     by the execution of code at the current location in the same 
11426     thread (specifically: 
11427     <code>exception</code>,
11428     <code>fieldAccess</code>, and
11429     <code>fieldModification</code>).
11430     If both a step and breakpoint event are triggered for the same thread and 
11431     location, the step event is reported before the breakpoint event.
11432     <p/>
11433     If the current location is the exit point of a method (that is, the last
11434     location before returning to the caller), the 
11435     <eventlink id="MethodExit"></eventlink> event and 
11436     the <eventlink id="FramePop"></eventlink> event (if requested)
11437     are reported after all other events at the current location in the same
11438     thread. There is no specified ordering of these two events 
11439     with respect to each other.
11440     <p/>
11441     Co-located events can be triggered during the processing of some other
11442     event by the agent at the same location in the same thread.
11443     If such an event, of type <i>y</i>, is triggered during the processing of 
11444     an event of type <i>x</i>, and if <i>x</i> 
11445     precedes <i>y</i> in the ordering specified above, the co-located event 
11446     <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
11447     <i>y</i>, <i>y</i> is not reported for the current thread and location.
11448     For example, if a breakpoint is set at the current location 
11449     during the processing of <eventlink id="SingleStep"></eventlink>,
11450     that breakpoint will be reported before the thread moves off the current 
11451     location.
11452     <p/>The following events are never considered to be co-located with 
11453     other events.
11454     <ul>
11455       <li><eventlink id="VMStart"></eventlink></li>
11456       <li><eventlink id="VMInit"></eventlink></li>
11457       <li><eventlink id="VMDeath"></eventlink></li>
11458       <li><eventlink id="ThreadStart"></eventlink></li>
11459       <li><eventlink id="ThreadEnd"></eventlink></li>
11460       <li><eventlink id="ClassLoad"></eventlink></li>
11461       <li><eventlink id="ClassPrepare"></eventlink></li>
11462     </ul>
11463   </intro>
11464 
11465   <intro label="Event Callbacks" id="jvmtiEventCallbacks">
11466       The event callback structure below is used to specify the handler function
11467       for events.  It is set with the
11468       <functionlink id="SetEventCallbacks"></functionlink> function. 
11469   </intro>
11470 
11471   <event label="Single Step"
11472          id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
11473     <description>
11474       Single step events allow the agent to trace thread execution
11475       at the finest granularity allowed by the VM. A single step event is
11476       generated whenever a thread reaches a new location. 
11477       Typically, single step events represent the completion of one VM 
11478       instruction as defined in <vmspec/>. However, some implementations 
11479       may define locations differently. In any case the 
11480       <code>method</code> and <code>location</code>
11481       parameters  uniquely identify the current location and allow
11482       the mapping to source file and line number when that information is 
11483       available.
11484       <p/>
11485       No single step events are generated from within native methods.
11486     </description>
11487     <origin>jvmdi</origin>
11488     <capabilities>
11489       <required id="can_generate_single_step_events"></required>
11490     </capabilities>
11491     <parameters> 
11492       <param id="jni_env">
11493         <outptr>
11494           <struct>JNIEnv</struct>
11495         </outptr>
11496           <description>
11497             The JNI environment of the event (current) thread
11498           </description>
11499       </param>
11500       <param id="thread">
11501         <jthread/>
11502           <description>
11503             Thread about to execution a new instruction
11504           </description>
11505       </param>
11506       <param id="klass">
11507         <jclass method="method"/>
11508           <description>
11509             Class of the method about to execute a new instruction
11510           </description>
11511       </param>
11512       <param id="method">
11513         <jmethodID class="klass"/>
11514           <description>
11515             Method about to execute a new instruction
11516           </description>
11517       </param>
11518       <param id="location">
11519         <jlocation/>
11520         <description>
11521           Location of the new instruction
11522         </description>
11523       </param>
11524     </parameters>
11525   </event>
11526 
11527   <event label="Breakpoint"
11528          id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
11529     <description>
11530       Breakpoint events are generated whenever a thread reaches a location
11531       designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
11532       The <code>method</code> and <code>location</code>
11533       parameters uniquely identify the current location and allow
11534       the mapping to source file and line number when that information is 
11535       available.
11536     </description>
11537     <origin>jvmdi</origin>
11538     <capabilities>
11539       <required id="can_generate_breakpoint_events"></required>
11540     </capabilities>
11541     <parameters> 
11542       <param id="jni_env">
11543         <outptr>
11544           <struct>JNIEnv</struct>
11545         </outptr>
11546           <description>
11547             The JNI environment of the event (current) thread.
11548           </description>
11549       </param>
11550       <param id="thread">
11551         <jthread/>
11552           <description>
11553             Thread that hit the breakpoint
11554           </description>
11555       </param>
11556       <param id="klass">
11557         <jclass method="method"/>
11558           <description>
11559             Class of the method that hit the breakpoint
11560           </description>
11561       </param>
11562       <param id="method">
11563         <jmethodID class="klass"/>
11564           <description>
11565             Method that hit the breakpoint
11566           </description>
11567       </param>
11568       <param id="location">
11569         <jlocation/>
11570         <description>
11571           location of the breakpoint
11572         </description>
11573       </param>
11574     </parameters>
11575   </event>
11576 
11577   <event label="Field Access"
11578          id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
11579     <description>
11580       Field access events are generated whenever a thread accesses
11581       a field that was designated as a watchpoint 
11582       with <functionlink id="SetFieldAccessWatch"></functionlink>.
11583       The <code>method</code> and <code>location</code> 
11584       parameters uniquely identify the current location and allow
11585       the mapping to source file and line number when that information is 
11586       available. 
11587     </description>
11588     <origin>jvmdi</origin>
11589     <capabilities>
11590       <required id="can_generate_field_access_events"></required>
11591     </capabilities>
11592     <parameters> 
11593       <param id="jni_env">
11594         <outptr>
11595           <struct>JNIEnv</struct>
11596         </outptr>
11597           <description>
11598             The JNI environment of the event (current) thread
11599           </description>
11600       </param>
11601       <param id="thread">
11602         <jthread/>
11603           <description>
11604             Thread accessing the field
11605           </description>
11606       </param>
11607       <param id="klass">
11608         <jclass method="method"/>
11609           <description>
11610             Class of the method where the access is occurring
11611           </description>
11612       </param>
11613       <param id="method">
11614         <jmethodID class="klass"/>
11615           <description>
11616             Method where the access is occurring
11617           </description>
11618       </param>
11619       <param id="location">
11620         <jlocation/>
11621         <description>
11622           Location where the access is occurring
11623         </description>
11624       </param>
11625       <param id="field_klass">
11626         <jclass field="field"/>
11627           <description>
11628             Class of the field being accessed
11629           </description>
11630       </param>
11631       <param id="object">
11632         <jobject/>
11633           <description>
11634             Object with the field being accessed if the field is an
11635             instance field; <code>NULL</code> otherwise
11636           </description>
11637       </param>
11638       <param id="field">
11639         <jfieldID class="field_klass"/>
11640           <description>
11641             Field being accessed
11642           </description>
11643       </param>
11644     </parameters>
11645   </event>
11646 
11647   <event label="Field Modification"
11648          id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
11649     <description>
11650       Field modification events are generated whenever a thread modifies
11651       a field that was designated as a watchpoint 
11652       with <functionlink id="SetFieldModificationWatch"></functionlink>.
11653       The <code>method</code> and <code>location</code> 
11654       parameters uniquely identify the current location and allow
11655       the mapping to source file and line number when that information is 
11656       available. 
11657     </description>
11658     <origin>jvmdi</origin>
11659     <capabilities>
11660       <required id="can_generate_field_modification_events"></required>
11661     </capabilities>
11662     <parameters> 
11663       <param id="jni_env">
11664         <outptr>
11665           <struct>JNIEnv</struct>
11666         </outptr>
11667           <description>
11668             The JNI environment of the event (current) thread
11669           </description>
11670       </param>
11671       <param id="thread">
11672         <jthread/>
11673           <description>
11674             Thread modifying the field
11675           </description>
11676       </param>
11677       <param id="klass">
11678         <jclass method="method"/>
11679           <description>
11680             Class of the method where the modification is occurring
11681           </description>
11682       </param>
11683       <param id="method">
11684         <jmethodID class="klass"/>
11685           <description>
11686             Method where the modification is occurring
11687           </description>
11688       </param>
11689       <param id="location">
11690         <jlocation/>
11691         <description>
11692           Location where the modification is occurring
11693         </description>
11694       </param>
11695       <param id="field_klass">
11696         <jclass field="field"/>
11697           <description>
11698             Class of the field being modified
11699           </description>
11700       </param>
11701       <param id="object">
11702         <jobject/>
11703           <description>
11704             Object with the field being modified if the field is an
11705             instance field; <code>NULL</code> otherwise
11706           </description>
11707       </param>
11708       <param id="field">
11709         <jfieldID class="field_klass"/>
11710           <description>
11711             Field being modified
11712           </description>
11713       </param>
11714       <param id="signature_type">
11715         <char/>
11716         <description>
11717           Signature type of the new value
11718         </description>
11719       </param>
11720       <param id="new_value">
11721         <jvalue/>
11722         <description>
11723           The new value
11724         </description>
11725       </param>
11726     </parameters>
11727   </event>
11728 
11729   <event label="Frame Pop"
11730          id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
11731     <description>
11732       Frame pop events are generated upon exit from a single method 
11733       in a single frame as specified
11734       in a call to <functionlink id="NotifyFramePop"></functionlink>.
11735       This is true whether termination is caused by
11736       executing its return instruction
11737       or by throwing an exception to its caller 
11738       (see <paramlink id="was_popped_by_exception"></paramlink>).
11739       However, frame pops caused by the <functionlink id="PopFrame"/> 
11740       function are not reported.
11741       <p/>
11742       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11743       identifies the executable location in the returning method, 
11744       immediately prior to the return. 
11745     </description>
11746     <origin>jvmdi</origin>
11747     <capabilities>
11748       <required id="can_generate_frame_pop_events"></required>
11749     </capabilities>
11750     <parameters> 
11751       <param id="jni_env">
11752         <outptr>
11753           <struct>JNIEnv</struct>
11754         </outptr>
11755           <description>
11756             The JNI environment of the event (current) thread
11757           </description>
11758       </param>
11759       <param id="thread">
11760         <jthread/>
11761           <description>
11762             Thread that is popping the frame
11763           </description>
11764       </param>
11765       <param id="klass">
11766         <jclass method="method"/>
11767           <description>
11768             Class of the method being popped
11769           </description>
11770       </param>
11771       <param id="method">
11772         <jmethodID class="klass"/>
11773           <description>
11774             Method being popped
11775           </description>
11776       </param>
11777       <param id="was_popped_by_exception">
11778         <jboolean/>
11779         <description>
11780           True if frame was popped by a thrown exception.
11781           False if method exited through its return instruction.
11782         </description>
11783       </param>
11784     </parameters>
11785   </event>
11786 
11787   <event label="Method Entry"
11788          id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
11789     <description>
11790       Method entry events are generated upon entry of Java 
11791       programming language methods (including native methods).
11792       <p/>
11793       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11794       identifies the initial executable location in
11795       the method. 
11796       <p/>
11797       Enabling method
11798       entry or exit events will significantly degrade performance on many platforms and is thus
11799       not advised for performance critical usage (such as profiling).
11800       <internallink id="bci">Bytecode instrumentation</internallink> should be 
11801       used in these cases.
11802     </description>
11803     <origin>jvmdi</origin>
11804     <capabilities>
11805       <required id="can_generate_method_entry_events"></required>
11806     </capabilities>
11807     <parameters> 
11808       <param id="jni_env">
11809         <outptr>
11810           <struct>JNIEnv</struct>
11811         </outptr>
11812           <description>
11813             The JNI environment of the event (current) thread
11814           </description>
11815       </param>
11816       <param id="thread">
11817         <jthread/>
11818           <description>
11819             Thread entering the method
11820           </description>
11821       </param>
11822       <param id="klass">
11823         <jclass method="method"/>
11824           <description>
11825             Class of the method being entered
11826           </description>
11827       </param>
11828       <param id="method">
11829         <jmethodID class="klass"/>
11830           <description>
11831             Method being entered
11832           </description>
11833       </param>
11834     </parameters>
11835   </event>
11836 
11837   <event label="Method Exit"
11838          id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
11839     <description>
11840       Method exit events are generated upon exit from Java 
11841       programming language methods (including native methods).
11842       This is true whether termination is caused by
11843       executing its return instruction
11844       or by throwing an exception to its caller 
11845       (see <paramlink id="was_popped_by_exception"></paramlink>).
11846       <p/>
11847       The <code>method</code> field uniquely identifies the
11848       method being entered or exited. The <code>frame</code> field provides 
11849       access to the stack frame for the method.
11850       <p/>
11851       The location reported by <functionlink id="GetFrameLocation"></functionlink>
11852       identifies the executable location in the returning method 
11853       immediately prior to the return. 
11854       <p/>
11855         Enabling method
11856         entry or exit events will significantly degrade performance on many platforms and is thus
11857         not advised for performance critical usage (such as profiling).
11858         <internallink id="bci">Bytecode instrumentation</internallink> should be 
11859         used in these cases.
11860     </description>
11861     <origin>jvmdi</origin>
11862     <capabilities>
11863       <required id="can_generate_method_exit_events"></required>
11864     </capabilities>
11865     <parameters>
11866       <param id="jni_env">
11867         <outptr>
11868           <struct>JNIEnv</struct>
11869         </outptr>
11870           <description>
11871             The JNI environment of the event (current) thread
11872           </description>
11873       </param>
11874       <param id="thread">
11875         <jthread/>
11876           <description>
11877             Thread exiting the method
11878           </description>
11879       </param>
11880       <param id="klass">
11881         <jclass method="method"/>
11882           <description>
11883             Class of the method being exited
11884           </description>
11885       </param>
11886       <param id="method">
11887         <jmethodID class="klass"/>
11888           <description>
11889             Method being exited
11890           </description>
11891       </param>
11892       <param id="was_popped_by_exception">
11893         <jboolean/>
11894         <description>
11895           True if frame was popped by a thrown exception.
11896           False if method exited through its return instruction.
11897         </description>
11898       </param>
11899       <param id="return_value">
11900         <jvalue/>
11901         <description>
11902           The return value of the method being exited.
11903           Undefined and should not be used if 
11904           <paramlink id="was_popped_by_exception"></paramlink>
11905           is true.
11906         </description>
11907       </param>
11908     </parameters>
11909   </event>
11910 
11911   <event label="Native Method Bind" phase="any"
11912          id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
11913     <description>
11914       A Native Method Bind event is sent when a VM binds a 
11915       Java programming language native method
11916       to the address of a function that implements the native method. 
11917       This will occur when the native method is called for the first time
11918       and also occurs when the JNI function <code>RegisterNatives</code> is called.
11919       This event allows the bind to be redirected to an agent-specified
11920       proxy function. 
11921       This event is not sent when the native method is unbound.
11922       Typically, this proxy function will need to be specific to a 
11923       particular method or, to handle the general case, automatically
11924       generated assembly code, since after instrumentation code is 
11925       executed the function at the original binding 
11926       address will usually be invoked.
11927       The original binding can be restored or the redirection changed
11928       by use of the JNI function <code>RegisterNatives</code>.
11929       Some events may be sent during the primordial phase, JNI and
11930       most of <jvmti/> cannot be used at this time but the method and
11931       address can be saved for use later.
11932     </description>
11933     <origin>new</origin>
11934     <capabilities>
11935       <required id="can_generate_native_method_bind_events"></required>
11936     </capabilities>
11937     <parameters>
11938       <param id="jni_env">
11939         <outptr>
11940           <struct>JNIEnv</struct>
11941         </outptr>
11942           <description>
11943             The JNI environment of the event (current) thread
11944             Will be <code>NULL</code> if sent during the primordial 
11945             <functionlink id="GetPhase">phase</functionlink>.
11946           </description>
11947       </param>
11948       <param id="thread">
11949         <jthread/>
11950           <description>
11951             Thread requesting the bind
11952           </description>
11953       </param>
11954       <param id="klass">
11955         <jclass method="method"/>
11956           <description>
11957             Class of the method being bound
11958           </description>
11959       </param>
11960       <param id="method">
11961         <jmethodID class="klass"/>
11962           <description>
11963             Native method being bound
11964           </description>
11965       </param>
11966       <param id="address">
11967         <outptr><void/></outptr>
11968         <description>
11969           The address the VM is about to bind to--that is, the
11970           address of the implementation of the native method
11971         </description>
11972       </param>
11973       <param id="new_address_ptr">
11974         <agentbuf><void/></agentbuf>
11975         <description>
11976           if the referenced address is changed (that is, if
11977           <code>*new_address_ptr</code> is set), the binding
11978           will instead be made to the supplied address.
11979         </description>
11980       </param>
11981     </parameters>
11982   </event>
11983 
11984   <event label="Exception"
11985          id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
11986     <description>
11987       Exception events are generated whenever an exception is first detected
11988       in a Java programming language method. 
11989       Where "exception" means any <code>java.lang.Throwable</code>.
11990       The exception may have been thrown by a Java programming language or native
11991       method, but in the case of native methods, the event is not generated
11992       until the exception is first seen by a Java programming language method. If an exception is
11993       set and cleared in a native method (and thus is never visible to Java programming language code),
11994       no exception event is generated.
11995       <p/>
11996       The <code>method</code> and <code>location</code>
11997       parameters  uniquely identify the current location 
11998       (where the exception was detected) and allow
11999       the mapping to source file and line number when that information is 
12000       available. The <code>exception</code> field identifies the thrown
12001       exception object. The <code>catch_method</code>
12002       and <code>catch_location</code> identify the location of the catch clause,
12003       if any, that handles the thrown exception. If there is no such catch clause,
12004       each field is set to 0. There is no guarantee that the thread will ever
12005       reach this catch clause. If there are native methods on the call stack
12006       between the throw location and the catch clause, the exception may 
12007       be reset by one of those native methods.
12008       Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
12009       et al. set to 0) may in fact be caught by native code.
12010       Agents can check for these occurrences by monitoring 
12011       <eventlink id="ExceptionCatch"></eventlink> events.
12012       Note that finally clauses are implemented as catch and re-throw. Therefore they
12013       will be reported in the catch location.
12014     </description>
12015     <origin>jvmdi</origin>
12016     <capabilities>
12017       <required id="can_generate_exception_events"></required>
12018     </capabilities>
12019     <parameters> 
12020       <param id="jni_env">
12021         <outptr>
12022           <struct>JNIEnv</struct>
12023         </outptr>
12024           <description>
12025             The JNI environment of the event (current) thread
12026           </description>
12027       </param>
12028       <param id="thread">
12029         <jthread/>
12030           <description>
12031             Thread generating the exception
12032           </description>
12033       </param>
12034       <param id="klass">
12035         <jclass method="method"/>
12036           <description>
12037             Class generating the exception
12038           </description>
12039       </param>
12040       <param id="method">
12041         <jmethodID class="klass"/>
12042           <description>
12043             Method generating the exception
12044           </description>
12045       </param>
12046       <param id="location">
12047         <jlocation/>
12048         <description>
12049           Location where exception occurred
12050         </description>
12051       </param>
12052       <param id="exception">
12053         <jobject/>
12054           <description>
12055             The exception being thrown
12056           </description>
12057       </param>
12058       <param id="catch_klass">
12059         <jclass method="catch_method"/>
12060           <description>
12061             Class that will catch the exception, or <code>NULL</code> if no known catch
12062           </description>
12063       </param>
12064       <param id="catch_method">
12065         <jmethodID class="catch_klass"/>
12066           <description>
12067             Method that will catch the exception, or <code>NULL</code> if no known catch
12068           </description>
12069       </param>
12070       <param id="catch_location">
12071         <jlocation/>
12072         <description>
12073           location which will catch the exception or zero if no known catch
12074         </description>
12075       </param>
12076     </parameters>
12077   </event>
12078 
12079   <event label="Exception Catch"
12080          id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
12081     <description>
12082       Exception catch events are generated whenever a thrown exception is caught.
12083       Where "exception" means any <code>java.lang.Throwable</code>.
12084       If the exception is caught in a Java programming language method, the event is generated
12085       when the catch clause is reached. If the exception is caught in a native
12086       method, the event is generated as soon as control is returned to a Java programming language 
12087       method. Exception catch events are generated for any exception for which
12088       a throw was detected in a Java programming language method.
12089       Note that finally clauses are implemented as catch and re-throw. Therefore they
12090       will generate exception catch events.
12091       <p/>
12092       The <code>method</code> and <code>location</code>
12093       parameters uniquely identify the current location 
12094       and allow the mapping to source file and line number when that information is 
12095       available. For exceptions caught in a Java programming language method, the 
12096       <code>exception</code> object identifies the exception object. Exceptions
12097       caught in native methods are not necessarily available by the time the 
12098       exception catch is reported, so the <code>exception</code> field is set
12099       to <code>NULL</code>.
12100     </description>
12101     <origin>jvmdi</origin>
12102     <capabilities>
12103       <required id="can_generate_exception_events"></required>
12104     </capabilities>
12105     <parameters> 
12106       <param id="jni_env">
12107         <outptr>
12108           <struct>JNIEnv</struct>
12109         </outptr>
12110           <description>
12111             The JNI environment of the event (current) thread
12112           </description>
12113       </param>
12114       <param id="thread">
12115         <jthread/>
12116           <description>
12117             Thread catching the exception
12118           </description>
12119       </param>
12120       <param id="klass">
12121         <jclass method="method"/>
12122           <description>
12123             Class catching the exception
12124           </description>
12125       </param>
12126       <param id="method">
12127         <jmethodID class="klass"/>
12128           <description>
12129             Method catching the exception
12130           </description>
12131       </param>
12132       <param id="location">
12133         <jlocation/>
12134         <description>
12135           Location where exception is being caught
12136         </description>
12137       </param>
12138       <param id="exception">
12139         <jobject/>
12140           <description>
12141             Exception being caught
12142           </description>
12143       </param>
12144     </parameters>
12145   </event>
12146 
12147   <event label="Thread Start"
12148          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12149     <description>
12150       Thread start events are generated by a new thread before its initial
12151       method executes. 
12152       <p/>
12153       A thread may be listed in the array returned by
12154       <functionlink id="GetAllThreads"></functionlink>
12155       before its thread start event is generated. 
12156       It is possible for other events to be generated
12157       on a thread before its thread start event.
12158       <p/>
12159       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12160     </description>
12161     <origin>jvmdi</origin>
12162     <capabilities>
12163     </capabilities>
12164     <parameters> 
12165       <param id="jni_env">
12166         <outptr>
12167           <struct>JNIEnv</struct>
12168         </outptr>
12169           <description>
12170             The JNI environment of the event (current) thread.
12171           </description>
12172       </param>
12173       <param id="thread">
12174         <jthread/>
12175           <description>
12176             Thread starting
12177           </description>
12178       </param>
12179     </parameters>
12180   </event>
12181 
12182   <event label="Thread End"
12183          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start"> 
12184     <description>
12185       Thread end events are generated by a terminating thread
12186       after its initial method has finished execution. 
12187       <p/>
12188       A thread may be listed in the array returned by
12189       <functionlink id="GetAllThreads"></functionlink>
12190       after its thread end event is generated. 
12191       No events are generated on a thread
12192       after its thread end event.
12193       <p/>
12194       The event is sent on the dying <paramlink id="thread"></paramlink>.
12195     </description>
12196     <origin>jvmdi</origin>
12197     <capabilities>
12198     </capabilities>
12199     <parameters> 
12200       <param id="jni_env">
12201         <outptr>
12202           <struct>JNIEnv</struct>
12203         </outptr>
12204           <description>
12205             The JNI environment of the event (current) thread.
12206           </description>
12207       </param>
12208       <param id="thread">
12209         <jthread/>
12210           <description>
12211             Thread ending
12212           </description>
12213       </param>
12214     </parameters>
12215   </event>
12216 
12217   <event label="Class Load"
12218          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
12219     <description>
12220       A class load event is generated when a class is first loaded. The order
12221       of class load events generated by a particular thread are guaranteed
12222       to match the order of class loading within that thread. 
12223       Array class creation does not generate a class load event.
12224       The creation of a primitive class (for example, java.lang.Integer.TYPE) 
12225       does not generate a class load event.
12226       <p/>
12227       This event is sent at an early stage in loading the class. As
12228       a result the class should be used carefully.  Note, for example,
12229       that methods and fields are not yet loaded, so queries for methods,
12230       fields, subclasses, and so on will not give correct results. 
12231       See "Loading of Classes and Interfaces" in the <i>Java Language
12232       Specification</i>.  For most
12233       purposes the <eventlink id="ClassPrepare"></eventlink> event will
12234       be more useful.
12235     </description>
12236     <origin>jvmdi</origin>
12237     <capabilities>
12238     </capabilities>
12239     <parameters> 
12240       <param id="jni_env">
12241         <outptr>
12242           <struct>JNIEnv</struct>
12243         </outptr>
12244           <description>
12245             The JNI environment of the event (current) thread
12246           </description>
12247       </param>
12248       <param id="thread">
12249         <jthread/>
12250           <description>
12251             Thread loading the class
12252           </description>
12253       </param>
12254       <param id="klass">
12255         <jclass/>
12256           <description>
12257             Class being loaded
12258           </description>
12259       </param>
12260     </parameters>
12261   </event>
12262 
12263   <elide>
12264   <event label="Class Unload"
12265          id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
12266     <description>
12267       A class unload event is generated when the class is about to be unloaded.
12268       Class unload events take place during garbage collection and must be 
12269       handled extremely carefully. The garbage collector holds many locks
12270       and has suspended all other threads, so the event handler cannot depend
12271       on the ability to acquire any locks. The class unload event handler should
12272       do as little as possible, perhaps by queuing information to be processed
12273       later.  In particular, the <code>jclass</code> should be used only in
12274       the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
12275       <ul>
12276         <li><functionlink id="GetClassSignature"></functionlink></li>
12277         <li><functionlink id="GetSourceFileName"></functionlink></li>
12278         <li><functionlink id="IsInterface"></functionlink></li>
12279         <li><functionlink id="IsArrayClass"></functionlink></li>
12280       </ul>
12281     </description>
12282     <origin>jvmdi</origin>
12283     <capabilities>
12284     </capabilities>
12285     <parameters> 
12286       <param id="jni_env">
12287         <outptr>
12288           <struct>JNIEnv</struct>
12289         </outptr>
12290           <description>
12291             The JNI environment of the event (current) thread
12292           </description>
12293       </param>
12294       <param id="thread">
12295         <jthread/>
12296           <description>
12297             Thread generating the class unload
12298           </description>
12299       </param>
12300       <param id="klass">
12301         <jclass/>
12302           <description>
12303             Class being unloaded
12304           </description>
12305       </param>
12306     </parameters>
12307   </event>
12308   </elide>
12309 
12310   <event label="Class Prepare"
12311          id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
12312     <description>
12313       A class prepare event is generated when class preparation is complete.
12314       At this point, class fields, methods, and implemented interfaces are 
12315       available, and no code from the class has been executed. Since array 
12316       classes never have fields or methods, class prepare events are not 
12317       generated for them. Class prepare events are not generated for 
12318       primitive classes (for example, <code>java.lang.Integer.TYPE</code>). 
12319     </description>
12320     <origin>jvmdi</origin>
12321     <capabilities>
12322     </capabilities>
12323     <parameters> 
12324       <param id="jni_env">
12325         <outptr>
12326           <struct>JNIEnv</struct>
12327         </outptr>
12328           <description>
12329             The JNI environment of the event (current) thread
12330           </description>
12331       </param>
12332       <param id="thread">
12333         <jthread/>
12334           <description>
12335             Thread generating the class prepare
12336           </description>
12337       </param>
12338       <param id="klass">
12339         <jclass/>
12340           <description>
12341             Class being prepared
12342           </description>
12343       </param>
12344     </parameters>
12345   </event>
12346 
12347   <event label="Class File Load Hook" phase="any"
12348          id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
12349     <description>
12350       This event is sent when the VM obtains class file data,
12351       but before it constructs
12352       the in-memory representation for that class. 
12353       This event is also sent when the class is being modified by the 
12354       <functionlink id="RetransformClasses"/> function or
12355       the <functionlink id="RedefineClasses"/> function,
12356       called in any <jvmti/> environment.
12357       The agent can instrument
12358       the existing class file data sent by the VM to include profiling/debugging hooks.
12359       See the description of 
12360       <internallink id="bci">bytecode instrumentation</internallink>
12361       for usage information.
12362       <p/>
12363     This event may be sent before the VM is initialized (the primordial 
12364     <functionlink id="GetPhase">phase</functionlink>). During this time
12365     no VM resources should be created.  Some classes might not be compatible
12366     with the function (eg. ROMized classes) and this event will not be
12367     generated for these classes.
12368     <p/>
12369     The agent must allocate the space for the modified 
12370     class file data buffer
12371     using the memory allocation function 
12372     <functionlink id="Allocate"></functionlink> because the
12373     VM is responsible for freeing the new class file data buffer
12374     using <functionlink id="Deallocate"></functionlink>.  
12375     Note that <functionlink id="Allocate"></functionlink>
12376     is permitted during the primordial phase.
12377     <p/>
12378     If the agent wishes to modify the class file, it must set 
12379     <code>new_class_data</code> to point
12380     to the newly instrumented class file data buffer and set
12381     <code>new_class_data_len</code> to the length of that 
12382     buffer before returning
12383     from this call.  If no modification is desired, the agent simply
12384     does not set <code>new_class_data</code>.  If multiple agents
12385     have enabled this event the results are chained. That is, if
12386     <code>new_class_data</code> has been set, it becomes the 
12387     <code>class_data</code> for the next agent.
12388     <p/>
12389     The order that this event is sent to each environment differs
12390     from other events.
12391     This event is sent to environments in the following order:
12392     <ul>
12393       <li><fieldlink id="can_retransform_classes"
12394                      struct="jvmtiCapabilities">retransformation
12395                                                 incapable</fieldlink>
12396           environments, in the 
12397           order in which they were created
12398       </li>
12399       <li><fieldlink id="can_retransform_classes"
12400                      struct="jvmtiCapabilities">retransformation
12401                                                 capable</fieldlink>
12402           environments, in the 
12403           order in which they were created
12404       </li>
12405     </ul>
12406     When triggered by <functionlink id="RetransformClasses"/>,
12407     this event is sent only to <fieldlink id="can_retransform_classes"
12408                      struct="jvmtiCapabilities">retransformation
12409                                                 capable</fieldlink>
12410     environments.
12411   </description>
12412   <origin>jvmpi</origin>
12413     <capabilities>
12414       <capability id="can_generate_all_class_hook_events"></capability>
12415     </capabilities>
12416     <parameters>
12417       <param id="jni_env">
12418         <outptr>
12419           <struct>JNIEnv</struct>
12420         </outptr>
12421           <description>
12422             The JNI environment of the event (current) thread.
12423             Will be <code>NULL</code> if sent during the primordial 
12424             <functionlink id="GetPhase">phase</functionlink>.
12425           </description>
12426       </param>
12427       <param id="class_being_redefined">
12428         <jclass/>
12429         <description>
12430           The class being
12431           <functionlink id="RedefineClasses">redefined</functionlink> or
12432           <functionlink id="RetransformClasses">retransformed</functionlink>.
12433           <code>NULL</code> if sent by class load.
12434         </description>
12435       </param>
12436       <param id="loader">
12437         <jobject/>
12438           <description>
12439             The class loader loading the class.  
12440             <code>NULL</code> if the bootstrap class loader.
12441           </description>
12442       </param>
12443       <param id="name">
12444         <vmbuf><char/></vmbuf>
12445         <description>
12446             Name of class being loaded as a VM internal qualified name
12447             (for example, "java/util/List"), encoded as a
12448             <internallink id="mUTF">modified UTF-8</internallink> string.
12449             Note: if the class is defined with a <code>NULL</code> name or
12450             without a name specified, <code>name</code> will be <code>NULL</code>.
12451         </description>
12452       </param>
12453       <param id="protection_domain">
12454         <jobject/>
12455         <description>
12456           The <code>ProtectionDomain</code> of the class.
12457         </description>
12458       </param>
12459       <param id="class_data_len">
12460         <jint/>
12461         <description>
12462           Length of current class file data buffer.
12463         </description>
12464       </param>
12465       <param id="class_data">
12466         <vmbuf><uchar/></vmbuf>
12467         <description>
12468           Pointer to the current class file data buffer.
12469         </description>
12470       </param>
12471       <param id="new_class_data_len">
12472         <outptr><jint/></outptr>
12473         <description>
12474           Pointer to the length of the new class file data buffer.
12475         </description>
12476       </param>
12477       <param id="new_class_data">
12478         <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
12479         <description>
12480           Pointer to the pointer to the instrumented class file data buffer.
12481         </description>
12482       </param>
12483     </parameters>
12484   </event>
12485 
12486   <event label="VM Start Event"
12487          id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
12488     <description>
12489       The VM initialization event signals the start of the VM.
12490       At this time JNI is live but the VM is not yet fully initialized.
12491       Once this event is generated, the agent is free to call any JNI function.
12492       This event signals the beginning of the start phase, 
12493       <jvmti/> functions permitted in the start phase may be called.
12494       <p/>
12495       In the case of VM start-up failure, this event will not be sent.
12496     </description>
12497     <origin>jvmdi</origin>
12498     <capabilities>
12499     </capabilities>
12500     <parameters>
12501       <param id="jni_env">
12502         <outptr>
12503           <struct>JNIEnv</struct>
12504         </outptr>
12505           <description>
12506             The JNI environment of the event (current) thread.
12507           </description>
12508       </param>
12509     </parameters>
12510   </event>
12511 
12512   <event label="VM Initialization Event"
12513          id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
12514     <description>
12515       The VM initialization event signals the completion of VM initialization. Once
12516       this event is generated, the agent is free to call any JNI or <jvmti/>
12517       function. The VM initialization event can be preceded by or can be concurrent
12518       with other events, but
12519       the preceding events should be handled carefully, if at all, because the
12520       VM has not completed its initialization. The thread start event for the
12521       main application thread is guaranteed not to occur until after the 
12522       handler for the VM initialization event returns.
12523       <p/>
12524       In the case of VM start-up failure, this event will not be sent.
12525     </description>
12526     <origin>jvmdi</origin>
12527     <capabilities>
12528     </capabilities>
12529     <parameters>
12530       <param id="jni_env">
12531         <outptr>
12532           <struct>JNIEnv</struct>
12533         </outptr>
12534           <description>
12535             The JNI environment of the event (current) thread.
12536           </description>
12537       </param>
12538       <param id="thread">
12539         <jthread/>
12540           <description>
12541             The initial thread
12542           </description>
12543       </param>
12544     </parameters>
12545   </event>
12546 
12547   <event label="VM Death Event"
12548          id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
12549     <description>
12550       The VM death event notifies the agent of the termination of the VM. 
12551       No events will occur after the VMDeath event.
12552       <p/>
12553       In the case of VM start-up failure, this event will not be sent.
12554       Note that <internallink id="onunload">Agent_OnUnload</internallink>
12555       will still be called in these cases.
12556     </description>
12557     <origin>jvmdi</origin>
12558     <capabilities>
12559     </capabilities>
12560     <parameters>
12561       <param id="jni_env">
12562         <outptr>
12563           <struct>JNIEnv</struct>
12564         </outptr>
12565           <description>
12566             The JNI environment of the event (current) thread
12567           </description>
12568       </param>
12569     </parameters>
12570   </event>
12571 
12572   <event label="Compiled Method Load"
12573          id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
12574     <description>
12575       Sent when a method is compiled and loaded into memory by the VM.
12576       If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
12577       If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
12578       followed by a new <code>CompiledMethodLoad</code> event.
12579       Note that a single method may have multiple compiled forms, and that
12580       this event will be sent for each form.
12581       Note also that several methods may be inlined into a single 
12582       address range, and that this event will be sent for each method.
12583       <p/>
12584       These events can be sent after their initial occurrence with
12585       <functionlink id="GenerateEvents"></functionlink>.
12586     </description>
12587     <origin>jvmpi</origin>
12588     <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
12589       <field id="start_address">
12590         <vmbuf><void/></vmbuf>
12591         <description>
12592           Starting native address of code corresponding to a location
12593         </description>
12594       </field>
12595       <field id="location">
12596         <jlocation/>
12597         <description>
12598           Corresponding location. See 
12599           <functionlink id="GetJLocationFormat"></functionlink>
12600           for the meaning of location.
12601         </description>
12602       </field>
12603     </typedef>
12604     <capabilities>
12605       <required id="can_generate_compiled_method_load_events"></required>
12606     </capabilities>
12607     <parameters>
12608       <param id="klass">
12609         <jclass method="method"/>
12610           <description>
12611             Class of the method being compiled and loaded
12612           </description>
12613       </param>
12614       <param id="method">
12615         <jmethodID class="klass"/>
12616           <description>
12617             Method being compiled and loaded
12618           </description>
12619       </param>
12620       <param id="code_size">
12621         <jint/>
12622         <description>
12623           Size of compiled code
12624         </description>
12625       </param>
12626       <param id="code_addr">
12627         <vmbuf><void/></vmbuf>
12628         <description>
12629           Address where compiled method code is loaded
12630         </description>
12631       </param>
12632       <param id="map_length">
12633         <jint/>
12634         <description>
12635           Number of <typelink id="jvmtiAddrLocationMap"></typelink>
12636           entries in the address map.
12637           Zero if mapping information cannot be supplied.
12638         </description>
12639       </param>
12640       <param id="map">
12641         <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
12642         <description>
12643           Map from native addresses to location.
12644           The native address range of each entry is from 
12645           <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
12646           to <code>start_address-1</code> of the next entry.
12647           <code>NULL</code> if mapping information cannot be supplied.
12648         </description>
12649       </param>
12650       <param id="compile_info">
12651         <vmbuf><void/></vmbuf>
12652         <description>
12653           VM-specific compilation information.  
12654           The referenced compile information is managed by the VM
12655           and must not depend on the agent for collection.
12656           A VM implementation defines the content and lifetime 
12657           of the information.
12658         </description>
12659       </param>
12660     </parameters>
12661   </event>
12662 
12663   <event label="Compiled Method Unload"
12664          id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
12665     <description>
12666       Sent when a compiled method is unloaded from memory.
12667       This event might not be sent on the thread which performed the unload.
12668       This event may be sent sometime after the unload occurs, but 
12669       will be sent before the memory is reused
12670       by a newly generated compiled method. This event may be sent after 
12671       the class is unloaded.
12672     </description>
12673     <origin>jvmpi</origin>
12674     <capabilities>
12675       <required id="can_generate_compiled_method_load_events"></required>
12676     </capabilities>
12677     <parameters>
12678       <param id="klass">
12679         <jclass method="method"/>
12680           <description>
12681             Class of the compiled method being unloaded.
12682           </description>
12683       </param>
12684       <param id="method">
12685         <jmethodID class="klass"/>
12686           <description>
12687             Compiled method being unloaded.
12688             For identification of the compiled method only -- the class 
12689             may be unloaded and therefore the method should not be used
12690             as an argument to further JNI or <jvmti/> functions.
12691           </description>
12692       </param>
12693       <param id="code_addr">
12694         <vmbuf><void/></vmbuf>
12695         <description>
12696           Address where compiled method code was loaded.
12697           For identification of the compiled method only -- 
12698           the space may have been reclaimed.
12699         </description>
12700       </param>
12701     </parameters>
12702   </event>
12703 
12704   <event label="Dynamic Code Generated" phase="any"
12705          id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
12706     <description>
12707       Sent when a component of the virtual machine is generated dynamically.
12708       This does not correspond to Java programming language code that is
12709       compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
12710       This is for native code--for example, an interpreter that is generated
12711       differently depending on command-line options.
12712       <p/>
12713       Note that this event has no controlling capability.
12714       If a VM cannot generate these events, it simply does not send any.
12715       <p/>
12716       These events can be sent after their initial occurrence with
12717       <functionlink id="GenerateEvents"></functionlink>.
12718     </description>
12719     <origin>jvmpi</origin>
12720     <capabilities>
12721     </capabilities>
12722     <parameters>
12723       <param id="name">
12724         <vmbuf><char/></vmbuf>
12725         <description>
12726           Name of the code, encoded as a
12727           <internallink id="mUTF">modified UTF-8</internallink> string.
12728           Intended for display to an end-user.
12729           The name might not be unique.
12730         </description>
12731       </param>
12732       <param id="address">
12733         <vmbuf><void/></vmbuf>
12734         <description>
12735           Native address of the code
12736         </description>
12737       </param>
12738       <param id="length">
12739         <jint/>
12740         <description>
12741           Length in bytes of the code
12742         </description>
12743       </param>
12744     </parameters>
12745   </event>
12746 
12747   <event label="Data Dump Request"
12748          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
12749     <description>
12750       Sent by the VM to request the agent to dump its data.  This
12751       is just a hint and the agent need not react to this event.
12752       This is useful for processing command-line signals from users.  For
12753       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris
12754       causes the VM to send this event to the agent.
12755     </description>
12756     <origin>jvmpi</origin>
12757     <capabilities>
12758     </capabilities>
12759     <parameters>
12760     </parameters>
12761   </event>
12762 
12763   <event label="Monitor Contended Enter"
12764          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
12765     <description>
12766       Sent when a thread is attempting to enter a Java programming language
12767       monitor already acquired by another thread.
12768     </description>
12769     <origin>jvmpi</origin>
12770     <capabilities>
12771       <required id="can_generate_monitor_events"></required>
12772     </capabilities>
12773     <parameters>
12774       <param id="jni_env">
12775         <outptr>
12776           <struct>JNIEnv</struct>
12777         </outptr>
12778           <description>
12779             The JNI environment of the event (current) thread
12780           </description>
12781       </param>
12782       <param id="thread">
12783         <jthread/>
12784           <description>
12785             JNI local reference to the thread 
12786             attempting to enter the monitor
12787           </description>
12788       </param>
12789       <param id="object">
12790         <jobject/>
12791           <description>
12792             JNI local reference to the monitor
12793           </description>
12794       </param>
12795     </parameters>
12796   </event>
12797 
12798   <event label="Monitor Contended Entered"
12799          id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
12800     <description>
12801       Sent when a thread enters a Java programming language
12802       monitor after waiting for it to be released by another thread.
12803     </description>
12804     <origin>jvmpi</origin>
12805     <capabilities>
12806       <required id="can_generate_monitor_events"></required>
12807     </capabilities>
12808     <parameters>
12809       <param id="jni_env">
12810         <outptr>
12811           <struct>JNIEnv</struct>
12812         </outptr>
12813           <description>
12814             The JNI environment of the event (current) thread
12815           </description>
12816       </param>
12817       <param id="thread">
12818         <jthread/>
12819           <description>
12820             JNI local reference to the thread entering
12821             the monitor
12822           </description>
12823       </param>
12824       <param id="object">
12825         <jobject/>
12826           <description>
12827             JNI local reference to the monitor
12828           </description>
12829       </param>
12830     </parameters>
12831   </event>
12832 
12833   <event label="Monitor Wait"
12834          id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
12835     <description>
12836       Sent when a thread is about to wait on an object.
12837     </description>
12838     <origin>jvmpi</origin>
12839     <capabilities>
12840       <required id="can_generate_monitor_events"></required>
12841     </capabilities>
12842     <parameters>
12843       <param id="jni_env">
12844         <outptr>
12845           <struct>JNIEnv</struct>
12846         </outptr>
12847           <description>
12848             The JNI environment of the event (current) thread
12849           </description>
12850       </param>
12851       <param id="thread">
12852         <jthread/>
12853           <description>
12854             JNI local reference to the thread about to wait
12855           </description>
12856       </param>
12857       <param id="object">
12858         <jobject/>
12859           <description>
12860             JNI local reference to the monitor
12861           </description>
12862       </param>
12863       <param id="timeout">
12864         <jlong/>
12865         <description>
12866           The number of milliseconds the thread will wait
12867         </description>
12868       </param>
12869     </parameters>
12870   </event>
12871 
12872   <event label="Monitor Waited"
12873          id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
12874     <description>
12875       Sent when a thread finishes waiting on an object.
12876     </description>
12877     <origin>jvmpi</origin>
12878     <capabilities>
12879       <required id="can_generate_monitor_events"></required>
12880     </capabilities>
12881     <parameters>
12882       <param id="jni_env">
12883         <outptr>
12884           <struct>JNIEnv</struct>
12885         </outptr>
12886           <description>
12887             The JNI environment of the event (current) thread
12888           </description>
12889       </param>
12890       <param id="thread">
12891         <jthread/>
12892           <description>
12893             JNI local reference to the thread that was finished waiting
12894           </description>
12895       </param>
12896       <param id="object">
12897         <jobject/>
12898           <description>
12899             JNI local reference to the monitor.
12900           </description>
12901       </param>
12902       <param id="timed_out">
12903         <jboolean/>
12904         <description>
12905           True if the monitor timed out
12906         </description>
12907       </param>
12908     </parameters>
12909   </event>
12910 
12911   <event label="Resource Exhausted"
12912          id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
12913          since="1.1">
12914     <description>
12915       Sent when a VM resource needed by a running application has been exhausted.
12916       Except as required by the optional capabilities, the set of resources 
12917       which report exhaustion is implementation dependent.
12918       <p/>
12919       The following bit flags define the properties of the resource exhaustion:
12920       <constants id="jvmtiResourceExhaustionFlags" 
12921                  label="Resource Exhaustion Flags" 
12922                  kind="bits" 
12923                  since="1.1">
12924         <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
12925           After this event returns, the VM will throw a
12926           <code>java.lang.OutOfMemoryError</code>.
12927         </constant>         
12928         <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
12929           The VM was unable to allocate memory from the <tm>Java</tm> 
12930           platform <i>heap</i>.
12931           The <i>heap</i> is the runtime
12932           data area from which memory for all class instances and
12933           arrays are allocated.
12934         </constant>         
12935         <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
12936           The VM was unable to create a thread.
12937         </constant>         
12938       </constants>
12939     </description>
12940     <origin>new</origin>
12941     <capabilities>
12942       <capability id="can_generate_resource_exhaustion_heap_events">
12943         Can generate events when the VM is unable to allocate memory from the
12944         <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
12945       </capability>
12946       <capability id="can_generate_resource_exhaustion_threads_events">
12947         Can generate events when the VM is unable to 
12948         <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
12949         a thread</internallink>.
12950       </capability>
12951     </capabilities>
12952     <parameters>
12953       <param id="jni_env">
12954         <outptr>
12955           <struct>JNIEnv</struct>
12956         </outptr>
12957           <description>
12958             The JNI environment of the event (current) thread
12959           </description>
12960       </param>
12961       <param id="flags">
12962         <jint/>
12963         <description>
12964           Flags defining the properties of the of resource exhaustion
12965           as specified by the 
12966           <internallink id="jvmtiResourceExhaustionFlags">Resource 
12967           Exhaustion Flags</internallink>.
12968           </description>
12969         </param>
12970       <param id="reserved">
12971         <vmbuf><void/></vmbuf>
12972         <description>
12973           Reserved.
12974         </description>
12975       </param>
12976       <param id="description">
12977         <vmbuf><char/></vmbuf>
12978         <description>
12979           Description of the resource exhaustion, encoded as a
12980           <internallink id="mUTF">modified UTF-8</internallink> string.
12981         </description>
12982       </param>
12983     </parameters>
12984   </event>
12985 
12986   <event label="VM Object Allocation"
12987          id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
12988     <description>
12989       Sent when a method causes the virtual machine to allocate an 
12990       Object visible to Java programming language code and the
12991       allocation is not detectable by other intrumentation mechanisms.
12992       Generally object allocation should be detected by instrumenting
12993       the bytecodes of allocating methods.
12994       Object allocation generated in native code by JNI function
12995       calls should be detected using 
12996       <internallink id="jniIntercept">JNI function interception</internallink>.
12997       Some methods might not have associated bytecodes and are not 
12998       native methods, they instead are executed directly by the 
12999       VM. These methods should send this event.
13000       Virtual machines which are incapable of bytecode instrumentation
13001       for some or all of their methods can send this event.
13002       <p/>
13003       Typical examples where this event might be sent:
13004       <ul>
13005         <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
13006         <li>Methods not represented by bytecodes -- for example, VM intrinsics and
13007             J2ME preloaded classes</li>
13008       </ul>
13009       Cases where this event would not be generated:
13010       <ul>
13011         <li>Allocation due to bytecodes -- for example, the <code>new</code>
13012             and <code>newarray</code> VM instructions</li>
13013         <li>Allocation due to JNI function calls -- for example,
13014             <code>AllocObject</code></li>
13015         <li>Allocations during VM initialization</li>
13016         <li>VM internal objects</li>
13017       </ul>
13018     </description>
13019     <origin>new</origin>
13020     <capabilities>
13021       <required id="can_generate_vm_object_alloc_events"></required>
13022     </capabilities>
13023     <parameters>
13024       <param id="jni_env">
13025         <outptr>
13026           <struct>JNIEnv</struct>
13027         </outptr>
13028           <description>
13029             The JNI environment of the event (current) thread
13030           </description>
13031       </param>
13032       <param id="thread">
13033         <jthread/>
13034           <description>
13035             Thread allocating the object.
13036           </description>
13037       </param>
13038       <param id="object">
13039         <jobject/>
13040           <description>
13041             JNI local reference to the object that was allocated
13042           </description>
13043       </param>
13044       <param id="object_klass">
13045         <jclass/>
13046           <description>
13047             JNI local reference to the class of the object
13048           </description>
13049       </param>
13050       <param id="size">
13051         <jlong/>
13052         <description>
13053             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13054         </description>
13055       </param>
13056     </parameters>
13057   </event>
13058 
13059   <event label="Object Free"
13060          id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13061     <description>
13062       An Object Free event is sent when the garbage collector frees an object.
13063       Events are only sent for tagged objects--see
13064       <internallink id="Heap">heap functions</internallink>.
13065       <p/>
13066       The event handler must not use JNI functions and
13067       must not use <jvmti/> functions except those which
13068       specifically allow such use (see the raw monitor, memory management,
13069       and environment local storage functions).
13070     </description>
13071     <origin>new</origin>
13072     <capabilities>
13073       <required id="can_generate_object_free_events"></required>
13074     </capabilities>
13075     <parameters>
13076       <param id="tag">
13077         <jlong/>
13078         <description>
13079           The freed object's tag
13080         </description>
13081       </param>
13082     </parameters>
13083   </event>
13084 
13085   <event label="Garbage Collection Start"
13086          id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
13087     <description>
13088       A Garbage Collection Start event is sent when a 
13089       garbage collection pause begins.
13090       Only stop-the-world collections are reported--that is, collections during
13091       which all threads cease to modify the state of the Java virtual machine.
13092       This means that some collectors will never generate these events.
13093       This event is sent while the VM is still stopped, thus
13094       the event handler must not use JNI functions and
13095       must not use <jvmti/> functions except those which
13096       specifically allow such use (see the raw monitor, memory management,
13097       and environment local storage functions).
13098       <p/>
13099       This event is always sent as a matched pair with 
13100       <eventlink id="GarbageCollectionFinish"/> 
13101       (assuming both events are enabled) and no garbage collection
13102       events will occur between them.
13103     </description>
13104     <origin>new</origin>
13105     <capabilities>
13106       <required id="can_generate_garbage_collection_events"></required>
13107     </capabilities>
13108     <parameters>
13109     </parameters>
13110   </event>
13111 
13112   <event label="Garbage Collection Finish"
13113          id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
13114     <description>
13115       A Garbage Collection Finish event is sent when a
13116       garbage collection pause ends.
13117       This event is sent while the VM is still stopped, thus
13118       the event handler must not use JNI functions and
13119       must not use <jvmti/> functions except those which
13120       specifically allow such use (see the raw monitor, memory management,
13121       and environment local storage functions).
13122       <p/>
13123       Some agents may need to do post garbage collection operations that
13124       require the use of the disallowed <jvmti/> or JNI functions. For these
13125       cases an agent thread can be created which waits on a raw monitor,
13126       and the handler for the Garbage Collection Finish event simply
13127       notifies the raw monitor
13128       <p/>
13129       This event is always sent as a matched pair with 
13130       <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
13131       <issue>
13132         The most important use of this event is to provide timing information,
13133         and thus additional information is not required.  However,  
13134         information about the collection which is "free" should be included -
13135         what that information is needs to be determined.
13136       </issue>
13137     </description>
13138     <origin>new</origin>
13139     <capabilities>
13140       <required id="can_generate_garbage_collection_events"></required>
13141     </capabilities>
13142     <parameters>
13143     </parameters>
13144   </event>
13145 
13146   <elide>
13147   <event label="Verbose Output" phase="any"
13148          id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
13149     <description>
13150       Send verbose messages as strings.
13151         <issue>
13152           This format is extremely fragile, as it can change with each
13153           platform, collector and version.  Alternatives include:
13154           <ul>
13155             <li>building off Java programming language M and M APIs</li>
13156             <li>XML</li>
13157             <li>key/value pairs</li>
13158             <li>removing it</li>
13159           </ul>
13160         </issue>
13161         <issue>
13162           Though this seemed trivial to implement.  
13163           In the RI it appears this will be quite complex.
13164         </issue>
13165     </description>
13166     <origin>new</origin>
13167     <capabilities>
13168     </capabilities>
13169     <parameters>
13170       <param id="flag">
13171         <enum>jvmtiVerboseFlag</enum>
13172         <description>
13173           Which verbose output is being sent.
13174         </description>
13175       </param>
13176       <param id="message">
13177         <vmbuf><char/></vmbuf>
13178         <description>
13179           Message text, encoded as a
13180           <internallink id="mUTF">modified UTF-8</internallink> string.
13181         </description>
13182       </param>
13183     </parameters>
13184   </event>
13185   </elide>
13186 
13187 </eventsection>
13188 
13189 <datasection>
13190   <intro>
13191     <jvmti/> extends the data types defined by JNI.
13192   </intro>
13193   <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
13194     <basetype id="jboolean">
13195       <description>
13196         Holds a Java programming language <code>boolean</code>.
13197         Unsigned 8 bits.
13198       </description>
13199     </basetype>
13200     <basetype id="jchar">
13201       <description>
13202         Holds a Java programming language <code>char</code>.
13203         Unsigned 16 bits.
13204       </description>
13205     </basetype>
13206     <basetype id="jint">
13207       <description>
13208         Holds a Java programming language <code>int</code>. 
13209         Signed 32 bits.
13210       </description>
13211     </basetype>
13212     <basetype id="jlong">
13213       <description>
13214         Holds a Java programming language <code>long</code>. 
13215         Signed 64 bits.
13216       </description>
13217     </basetype>
13218     <basetype id="jfloat">
13219       <description>
13220         Holds a Java programming language <code>float</code>. 
13221         32 bits.
13222       </description>
13223     </basetype>
13224     <basetype id="jdouble">
13225       <description>
13226         Holds a Java programming language <code>double</code>. 
13227         64 bits.
13228       </description>
13229     </basetype>
13230     <basetype id="jobject">
13231       <description>
13232         Holds a Java programming language object. 
13233       </description>
13234     </basetype>
13235     <basetype id="jclass">
13236       <description>
13237         Holds a Java programming language class. 
13238       </description>
13239     </basetype>
13240     <basetype id="jvalue">
13241       <description>
13242         Is a union of all primitive types and <code>jobject</code>.  Thus, holds any Java 
13243         programming language value. 
13244       </description>
13245     </basetype>
13246     <basetype id="jfieldID">
13247       <description>
13248         Identifies a Java programming language field. 
13249         <code>jfieldID</code>s returned by <jvmti/> functions and events may be
13250         safely stored.
13251       </description>
13252     </basetype>
13253     <basetype id="jmethodID">
13254       <description>
13255         Identifies a Java programming language method, initializer, or constructor. 
13256         <code>jmethodID</code>s returned by <jvmti/> functions and events may be
13257         safely stored.  However, if the class is unloaded, they become invalid
13258         and must not be used.
13259       </description>
13260     </basetype>
13261     <basetype id="JNIEnv">
13262       <description>
13263         Pointer to the JNI function table.  Pointer to this (<code>JNIEnv *</code>)
13264         is a JNI environment. 
13265       </description>
13266     </basetype>
13267   </basetypes>
13268 
13269   <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
13270     <basetype id="jvmtiEnv">
13271       <description>
13272         The <jvmti/> <internallink id="environments">environment</internallink> pointer. 
13273         See the <internallink id="FunctionSection">Function Section</internallink>.
13274         <code>jvmtiEnv</code> points to the 
13275         <internallink id="FunctionTable">function table</internallink> pointer.
13276       </description>
13277     </basetype>
13278     <basetype id="jthread">
13279       <definition>typedef jobject jthread;</definition>
13280       <description>
13281         Subtype of <datalink id="jobject"></datalink> that holds a thread.
13282       </description>
13283     </basetype>
13284     <basetype id="jthreadGroup">
13285       <definition>typedef jobject jthreadGroup;</definition>
13286       <description>
13287         Subtype of <datalink id="jobject"></datalink> that holds a thread group.
13288       </description>
13289     </basetype>
13290     <basetype id="jlocation">
13291       <definition>typedef jlong jlocation;</definition>
13292       <description>
13293         A 64 bit value, representing a monotonically increasing 
13294         executable position within a method. 
13295         <code>-1</code> indicates a native method.
13296         See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
13297         given VM.
13298       </description>
13299     </basetype>
13300     <basetype id="jrawMonitorID">
13301       <definition>struct _jrawMonitorID;
13302 typedef struct _jrawMonitorID *jrawMonitorID;</definition>
13303       <description>
13304         A raw monitor.
13305       </description>
13306     </basetype>
13307     <basetype id="jvmtiError">
13308       <description>
13309         Holds an error return code.
13310         See the <internallink id="ErrorSection">Error section</internallink> for possible values.
13311         <example>
13312 typedef enum { 
13313     JVMTI_ERROR_NONE = 0,  
13314     JVMTI_ERROR_INVALID_THREAD = 10,
13315       ... 
13316 } jvmtiError;
13317 </example>
13318       </description>
13319     </basetype>
13320     <basetype id="jvmtiEvent">
13321       <description>
13322         An identifier for an event type.
13323         See the <internallink id="EventSection">Event section</internallink> for possible values.
13324         It is guaranteed that future versions of this specification will 
13325         never assign zero as an event type identifier.
13326 <example>
13327 typedef enum { 
13328     JVMTI_EVENT_SINGLE_STEP = 1, 
13329     JVMTI_EVENT_BREAKPOINT = 2, 
13330       ... 
13331 } jvmtiEvent;
13332 </example>
13333       </description>
13334     </basetype>
13335     <basetype id="jvmtiEventCallbacks">
13336       <description>
13337         The callbacks used for events.
13338 <example>
13339 typedef struct {
13340     jvmtiEventVMInit VMInit;
13341     jvmtiEventVMDeath VMDeath;
13342       ... 
13343 } jvmtiEventCallbacks;
13344 </example>
13345         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink> 
13346         for the complete structure.
13347         <p/>
13348         Where, for example, the VM initialization callback is defined:
13349 <example>
13350 typedef void (JNICALL *jvmtiEventVMInit)
13351     (jvmtiEnv *jvmti_env, 
13352      JNIEnv* jni_env,
13353      jthread thread);
13354 </example>
13355         See the individual events for the callback function definition.
13356       </description>
13357     </basetype>
13358     <basetype id="jniNativeInterface">
13359       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
13360       <description>
13361         Typedef for the JNI function table <code>JNINativeInterface</code>
13362         defined in the 
13363         <externallink id="http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp23720">JNI Specification</externallink>.
13364         The JNI reference implementation defines this with an underscore.
13365       </description>
13366     </basetype>
13367   </basetypes>
13368 
13369 </datasection>
13370 
13371 <issuessection label="Issues">
13372   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
13373     JVMDI requires that the agent suspend threads before calling
13374     certain sensitive functions.  JVMPI requires garbage collection to be 
13375     disabled before calling certain sensitive functions. 
13376     It was suggested that rather than have this requirement, that
13377     VM place itself in a suitable state before performing an
13378     operation.  This makes considerable sense since each VM
13379     knows its requirements and can most easily arrange a
13380     safe state.  
13381     <p/>
13382     The ability to externally suspend/resume threads will, of
13383     course, remain.  The ability to enable/disable garbage collection will not.
13384     <p/>
13385     This issue is resolved--suspend will not
13386     be required.  The spec has been updated to reflect this.
13387   </intro>
13388   
13389   <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
13390     There are a variety of approaches to sampling call stacks.
13391     The biggest bifurcation is between VM controlled and agent
13392     controlled.  
13393     <p/>
13394     This issue is resolved--agent controlled
13395     sampling will be the approach.
13396   </intro>
13397   
13398   <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
13399     JVMDI represents threads as jthread.  JVMPI primarily
13400     uses JNIEnv* to represent threads.  
13401     <p/>
13402     The Expert Group has chosen jthread as the representation
13403     for threads in <jvmti/>.
13404     JNIEnv* is sent by
13405     events since it is needed to JNI functions.  JNIEnv, per the
13406     JNI spec, are not supposed to be used outside their thread.
13407   </intro>
13408 
13409   <intro id="design" label="Resolved Issue: Method Representation">
13410     The JNI spec allows an implementation to depend on jclass/jmethodID
13411     pairs, rather than simply a jmethodID, to reference a method.  
13412     JVMDI, for consistency, choose the same representation.  
13413     JVMPI, however, specifies that a jmethodID alone maps to a
13414     method.  Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
13415     pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
13416     In fact, any JVM implementation that supports JVMPI must have
13417     such a representation.  
13418     <jvmti/> will use jmethodID as a unique representation of a method
13419     (no jclass is used).
13420     There should be efficiency gains, particularly in 
13421     functionality like stack dumping, to this representation.
13422     <p/>
13423     Note that fields were not used in JVMPI and that the access profile
13424     of fields differs from methods--for implementation efficiency 
13425     reasons, a jclass/jfieldID pair will still be needed for field 
13426     reference.
13427   </intro>
13428 
13429   <intro id="localReferenceIssue" label="Resolved Issue: Local References">
13430     Functions return local references. 
13431   </intro>
13432 
13433   <intro id="frameRep" label="Resolved Issue: Representation of frames">
13434     In JVMDI, a frame ID is used to represent a frame.  Problem with this
13435     is that a VM must track when a frame becomes invalid, a far better
13436     approach, and the one used in <jvmti/>, is to reference frames by depth.
13437   </intro>
13438 
13439   <intro id="requiredCapabilities" label="Issue: Required Capabilities">
13440     Currently, having a required capabilities means that the functionality
13441     is optional.   Capabilities are useful even for required functionality
13442     since they can inform the VM is needed set-up.  Thus, there should be
13443     a set of capabilities that a conformant implementation must provide
13444     (if requested during Agent_OnLoad).
13445   </intro>
13446 
13447   <intro id="taghint" label="Proposal: add tag hint function">
13448     A hint of the percentage of objects that will be tagged would 
13449     help the VM pick a good implementation.
13450   </intro>
13451 
13452   <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
13453   How difficult or easy would be to extend the monitor_info category to include 
13454     <pre>
13455   - current number of monitors 
13456   - enumeration of monitors 
13457   - enumeration of threads waiting on a given monitor 
13458     </pre>
13459   The reason for my question is the fact that current get_monitor_info support 
13460   requires the agent to specify a given thread to get the info which is probably 
13461   OK in the profiling/debugging space, while in the monitoring space the agent 
13462   could be watching the monitor list and then decide which thread to ask for 
13463   the info. You might ask why is this important for monitoring .... I think it 
13464   can aid in the detection/prediction of application contention caused by hot-locks.
13465   </intro>
13466 </issuessection>
13467 
13468 <changehistory id="ChangeHistory" update="09/05/07">
13469   <intro>
13470     The <jvmti/> specification is an evolving document with major, minor, 
13471     and micro version numbers.
13472     A released version of the specification is uniquely identified
13473     by its major and minor version.
13474     The functions, events, and capabilities in this specification 
13475     indicate a "Since" value which is the major and minor version in
13476     which it was introduced.
13477     The version of the specification implemented by the VM can 
13478     be retrieved at runtime with the <functionlink id="GetVersionNumber"/> 
13479     function.
13480   </intro>
13481   <change date="14 Nov 2002">
13482     Converted to XML document.
13483   </change>
13484   <change date="14 Nov 2002">
13485     Elided heap dump functions (for now) since what was there
13486     was wrong.
13487   </change>
13488   <change date="18 Nov 2002">
13489     Added detail throughout.
13490   </change>
13491   <change date="18 Nov 2002">
13492     Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
13493   </change>
13494   <change date="19 Nov 2002">
13495     Added AsyncGetStackTrace.
13496   </change>
13497   <change date="19 Nov 2002">
13498     Added jframeID return to GetStackTrace.
13499   </change>
13500   <change date="19 Nov 2002">
13501     Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
13502     since they are redundant with GetStackTrace.
13503   </change>
13504   <change date="19 Nov 2002">
13505     Elided ClearAllBreakpoints since it has always been redundant.
13506   </change>
13507   <change date="19 Nov 2002">
13508     Added GetSystemProperties.
13509   </change>
13510   <change date="19 Nov 2002">
13511     Changed the thread local storage functions to use jthread.
13512   </change>
13513   <change date="20 Nov 2002">
13514     Added GetJLocationFormat.
13515   </change>
13516   <change date="22 Nov 2002">
13517     Added events and introductory text.
13518   </change>
13519   <change date="22 Nov 2002">
13520     Cross reference type and constant definitions.
13521   </change>
13522   <change date="24 Nov 2002">
13523     Added DTD.
13524   </change>
13525   <change date="24 Nov 2002">
13526     Added capabilities function section.
13527   </change>
13528   <change date="29 Nov 2002">
13529     Assign capabilities to each function and event.
13530   </change>
13531   <change date="29 Nov 2002">
13532     Add <internallink id="jniIntercept">JNI interception functions</internallink>.
13533   </change>
13534   <change date="30 Nov 2002">
13535     Auto generate SetEventNotificationMode capabilities.
13536   </change>
13537   <change date="30 Nov 2002">
13538     Add <eventlink id="VMObjectAlloc"></eventlink> event.
13539   </change>
13540   <change date="30 Nov 2002">
13541     Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
13542   </change>
13543   <change date="30 Nov 2002">
13544     Add const to declarations.
13545   </change>
13546   <change date="30 Nov 2002">
13547     Change method exit and frame pop to send on exception.
13548   </change>
13549   <change date="1 Dec 2002">
13550     Add ForceGarbageCollection.
13551   </change>
13552   <change date="2 Dec 2002">
13553     Redo Xrun section; clarify GetStackTrace and add example;
13554     Fix width problems; use "agent" consistently.
13555   </change>
13556   <change date="8 Dec 2002">
13557     Remove previous start-up intro.
13558     Add <internallink id="environments"><jvmti/> Environments</internallink>
13559     section.
13560   </change>
13561   <change date="8 Dec 2002">
13562     Add <functionlink id="DisposeEnvironment"></functionlink>.
13563   </change>
13564   <change date="9 Dec 2002">
13565     Numerous minor updates.
13566   </change>
13567   <change date="15 Dec 2002">
13568     Add heap profiling functions added:
13569     get/set annotation, iterate live objects/heap.
13570     Add heap profiling functions place holder added:
13571     heap roots.
13572     Heap profiling event added: object free. 
13573     Heap profiling event redesigned: vm object allocation. 
13574     Heap profiling event placeholders added: garbage collection start/finish. 
13575     Native method bind event added.
13576   </change>
13577   <change date="19 Dec 2002">
13578     Revamp suspend/resume functions.
13579     Add origin information with jvmdi tag.
13580     Misc fixes.
13581   </change>
13582   <change date="24 Dec 2002">
13583     Add semantics to types.
13584   </change>
13585   <change date="27 Dec 2002">
13586     Add local reference section.
13587     Autogenerate parameter descriptions from types.
13588   </change>
13589   <change date="28 Dec 2002">
13590     Document that RunAgentThread sends threadStart.
13591   </change>
13592   <change date="29 Dec 2002">
13593     Remove redundant local ref and dealloc warning.
13594     Convert GetRawMonitorName to allocated buffer.
13595     Add GenerateEvents.
13596   </change>
13597   <change date="30 Dec 2002">
13598     Make raw monitors a type and rename to "jrawMonitorID".
13599   </change>
13600   <change date="1 Jan 2003">
13601     Include origin information.
13602     Clean-up JVMDI issue references.
13603     Remove Deallocate warnings which are now automatically generated.
13604   </change>
13605   <change date="2 Jan 2003">
13606     Fix representation issues for jthread.
13607   </change>
13608   <change date="3 Jan 2003">
13609     Make capabilities buffered out to 64 bits - and do it automatically.
13610   </change>
13611   <change date="4 Jan 2003">
13612     Make constants which are enumeration into enum types.
13613     Parameters now of enum type.
13614     Clean-up and index type section.
13615     Replace remaining datadef entities with callback.
13616   </change>
13617   <change date="7 Jan 2003">
13618     Correct GenerateEvents description.
13619     More internal semantics work.
13620   </change>
13621   <change date="9 Jan 2003">
13622     Replace previous GetSystemProperties with two functions
13623     which use allocated information instead fixed.
13624     Add SetSystemProperty.
13625     More internal semantics work.
13626   </change>
13627   <change date="12 Jan 2003">
13628     Add varargs to end of SetEventNotificationMode.
13629   </change>
13630   <change date="20 Jan 2003">
13631     Finish fixing spec to reflect that alloc sizes are jlong.
13632   </change>
13633   <change date="22 Jan 2003">
13634     Allow NULL as RunAgentThread arg.
13635   </change>
13636   <change date="22 Jan 2003">
13637     Fixed names to standardized naming convention
13638     Removed AsyncGetStackTrace.
13639   </change>
13640   <change date="29 Jan 2003">
13641     Since we are using jthread, removed GetThread.
13642   </change>
13643   <change date="31 Jan 2003">
13644     Change GetFieldName to allow NULLs like GetMethodName.
13645   </change>
13646   <change date="29 Feb 2003" version="v40">
13647       Rewrite the introductory text, adding sections on
13648       start-up, environments and bytecode instrumentation.
13649       Change the command line arguments per EG discussions.
13650       Add an introduction to the capabilities section.
13651       Add the extension mechanism category and functions.
13652       Mark for deletion, but clarified anyhow, SuspendAllThreads.
13653       Rename IterateOverLiveObjects to IterateOverReachableObjects and
13654       change the text accordingly.
13655       Clarify IterateOverHeap.
13656       Clarify CompiledMethodLoad.
13657       Discuss prerequisite state for Calling Functions.
13658       Clarify SetAllocationHooks.
13659       Added issues ("To be resolved:") through-out.
13660       And so on...
13661   </change>
13662   <change date="6 Mar 2003" version="v41">
13663       Remove struct from the call to GetOwnedMonitorInfo.
13664       Automatically generate most error documentation, remove
13665       (rather broken) hand written error doc.
13666       Better describe capability use (empty initial set).
13667       Add min value to jint params.
13668       Remove the capability can_access_thread_local_storage.
13669       Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
13670       same for *NOT_IMPLEMENTED.
13671       Description fixes.
13672   </change>
13673   <change date="8 Mar 2003" version="v42">
13674       Rename GetClassSignature to GetClassName.
13675       Rename IterateOverClassObjects to IterateOverInstancesOfClass.
13676       Remove GetMaxStack (operand stack isn't used in <jvmti/>).
13677       Description fixes: define launch-time, remove native frame pop
13678       from PopFrame, and assorted clarifications.
13679   </change>
13680   <change date="8 Mar 2003" version="v43">
13681       Fix minor editing problem.
13682   </change>
13683   <change date="10 Mar 2003" version="v44">
13684       Add phase information.
13685       Remap (compact) event numbers.
13686   </change>
13687   <change date="11 Mar 2003" version="v45">
13688       More phase information - allow "any".
13689       Elide raw monitor queries and events.
13690       Minor description fixes.
13691   </change>
13692   <change date="12 Mar 2003" version="v46">
13693       Add GetPhase.
13694       Use "phase" through document.
13695       Elide GetRawMonitorName.
13696       Elide GetObjectMonitors.
13697   </change>
13698   <change date="12 Mar 2003" version="v47">
13699       Fixes from link, XML, and spell checking.
13700       Auto-generate the callback structure.
13701   </change>
13702   <change date="13 Mar 2003" version="v48">
13703       One character XML fix.
13704   </change>
13705   <change date="13 Mar 2003" version="v49">
13706       Change function parameter names to be consistent with 
13707       event parameters (fooBarBaz becomes foo_bar_baz).
13708   </change>
13709   <change date="14 Mar 2003" version="v50">
13710       Fix broken link.  Fix thread markers.
13711   </change>
13712   <change date="14 Mar 2003" version="v51">
13713       Change constants so they are under 128 to workaround
13714       compiler problems.
13715   </change>
13716   <change date="23 Mar 2003" version="v52">
13717       Overhaul capabilities.  Separate GetStackTrace into
13718       GetStackTrace and GetStackFrames.
13719   </change>
13720   <change date="8 Apr 2003" version="v54">
13721       Use depth instead of jframeID to reference frames.
13722       Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
13723       Remove frame arg from events.
13724   </change>
13725   <change date="9 Apr 2003" version="v55">
13726       Remove GetObjectWithAnnotation since tests show bufferred approach more efficient.
13727       Add missing annotation_count to GetObjectsWithAnnotations
13728   </change>
13729   <change date="10 Apr 2003" version="v56">
13730       Remove confusing parenthetical statement in GetObjectsWithAnnotations
13731   </change>
13732   <change date="13 Apr 2003" version="v58">
13733       Replace jclass/jmethodID representation of method with simply jmethodID;
13734       Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
13735       Replace can_access_frames with can_access_local_variables; remove from purely stack access.
13736       Use can_get_synthetic_attribute; fix description.
13737       Clarify that zero length arrays must be deallocated.
13738       Clarify RelinquishCapabilities.
13739       Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
13740   </change>
13741   <change date="27 Apr 2003" version="v59">
13742       Remove lingering indirect references to OBSOLETE_METHOD_ID.
13743   </change>
13744   <change date="4 May 2003" version="v60">
13745       Allow DestroyRawMonitor during OnLoad.
13746   </change>
13747   <change date="7 May 2003" version="v61">
13748       Added not monitor owner error return to DestroyRawMonitor.
13749   </change>
13750   <change date="13 May 2003" version="v62">
13751       Clarify semantics of raw monitors.
13752       Change flags on <code>GetThreadStatus</code>.
13753       <code>GetClassLoader</code> return NULL for the bootstrap class loader.
13754       Add <code>GetClassName</code> issue.
13755       Define local variable signature.
13756       Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
13757       Remove over specification in <code>GetObjectsWithAnnotations</code>.
13758       Elide <code>SetAllocationHooks</code>.
13759       Elide <code>SuspendAllThreads</code>.
13760   </change>
13761   <change date="14 May 2003" version="v63">
13762       Define the data type <code>jvmtiEventCallbacks</code>.
13763       Zero length allocations return NULL.  
13764       Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.  
13765       Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
13766   </change>
13767   <change date="15 May 2003" version="v64">
13768       Better wording, per review.
13769   </change>
13770   <change date="15 May 2003" version="v65">
13771       First Alpha.
13772       Make jmethodID and jfieldID unique, jclass not used.
13773   </change>
13774   <change date="27 May 2003" version="v66">
13775       Fix minor XSLT errors.
13776   </change>
13777   <change date="13 June 2003" version="v67">
13778       Undo making jfieldID unique (jmethodID still is).
13779   </change>
13780   <change date="17 June 2003" version="v68">
13781       Changes per June 11th Expert Group meeting --
13782       Overhaul Heap functionality: single callback, 
13783       remove GetHeapRoots, add reachable iterators,
13784       and rename "annotation" to "tag".
13785       NULL thread parameter on most functions is current
13786       thread.
13787       Add timers.
13788       Remove ForceExit.
13789       Add GetEnvironmentLocalStorage.
13790       Add verbose flag and event.
13791       Add AddToBootstrapClassLoaderSearch.
13792       Update ClassFileLoadHook.
13793   </change>
13794   <change date="18 June 2003" version="v69">
13795       Clean up issues sections.
13796       Rename GetClassName back to GetClassSignature and
13797       fix description.
13798       Add generic signature to GetClassSignature, 
13799       GetFieldSignature, GetMethodSignature, and 
13800       GetLocalVariableTable.
13801       Elide EstimateCostOfCapabilities.
13802       Clarify that the system property functions operate
13803       on the VM view of system properties.
13804       Clarify Agent_OnLoad.
13805       Remove "const" from JNIEnv* in events.
13806       Add metadata accessors.
13807   </change>
13808   <change date="18 June 2003" version="v70">
13809       Add start_depth to GetStackTrace.
13810       Move system properties to a new category.
13811       Add GetObjectSize.
13812       Remove "X" from command line flags.
13813       XML, HTML, and spell check corrections.
13814   </change>
13815   <change date="19 June 2003" version="v71">
13816       Fix JVMTI_HEAP_ROOT_THREAD to be 6.
13817       Make each synopsis match the function name.
13818       Fix unclear wording.
13819   </change>
13820   <change date="26 June 2003" version="v72">
13821       SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
13822       to be set to NULL.
13823       NotifyFramePop, GetFrameLocationm and all the local variable operations
13824       needed to have their wording about frames fixed.
13825       Grammar and clarity need to be fixed throughout.
13826       Capitalization and puntuation need to be consistent.
13827       Need micro version number and masks for accessing major, minor, and micro.
13828       The error code lists should indicate which must be returned by
13829       an implementation.
13830       The command line properties should be visible in the properties functions.
13831       Disallow popping from the current thread.
13832       Allow implementations to return opaque frame error when they cannot pop.
13833       The NativeMethodBind event should be sent during any phase.
13834       The DynamicCodeGenerated event should be sent during any phase.
13835       The following functions should be allowed to operate before VMInit:
13836         Set/GetEnvironmentLocalStorage
13837         GetMethodDeclaringClass
13838         GetClassSignature
13839         GetClassModifiers
13840         IsInterface
13841         IsArrayClass
13842         GetMethodName
13843         GetMethodModifiers
13844         GetMaxLocals
13845         GetArgumentsSize
13846         GetLineNumberTable
13847         GetMethodLocation
13848         IsMethodNative
13849         IsMethodSynthetic.
13850       Other changes (to XSL):
13851       Argument description should show asterisk after not before pointers.
13852       NotifyFramePop, GetFrameLocationm and all the local variable operations
13853       should hsve the NO_MORE_FRAMES error added.
13854       Not alive threads should have a different error return than invalid thread.
13855   </change>
13856   <change date="7 July 2003" version="v73">
13857       VerboseOutput event was missing message parameter.
13858       Minor fix-ups.
13859   </change>
13860   <change date="14 July 2003" version="v74">
13861       Technical Publications Department corrections.
13862       Allow thread and environment local storage to be set to NULL.
13863   </change>
13864   <change date="23 July 2003" version="v75">
13865       Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
13866       Add JNICALL to callbacks (XSL).
13867       Document JNICALL requirement for both events and callbacks (XSL).
13868       Restrict RedefineClasses to methods and attributes.
13869       Elide the VerboseOutput event.
13870       VMObjectAlloc: restrict when event is sent and remove method parameter.
13871       Finish loose ends from Tech Pubs edit.
13872   </change>
13873   <change date="24 July 2003" version="v76">
13874       Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
13875   </change>
13876   <change date="24 July 2003" version="v77">
13877       XML fixes.
13878       Minor text clarifications and corrections.
13879   </change>
13880   <change date="24 July 2003" version="v78">
13881       Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
13882       Clarify that stack frames are JVM Spec frames.
13883       Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
13884       and can_get_source_debug_extension.
13885       PopFrame cannot have a native calling method.
13886       Removed incorrect statement in GetClassloaderClasses 
13887       (see <vmspec chapter="4.4"/>).
13888   </change>
13889   <change date="24 July 2003" version="v79">
13890       XML and text fixes.
13891       Move stack frame description into Stack Frame category.
13892   </change>
13893   <change date="26 July 2003" version="v80">
13894       Allow NULL (means bootstrap loader) for GetClassloaderClasses.
13895       Add new heap reference kinds for references from classes.
13896       Add timer information struct and query functions.
13897       Add AvailableProcessors.
13898       Rename GetOtherThreadCpuTime to GetThreadCpuTime.
13899       Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
13900       to SetEventNotification mode.
13901       Add initial thread to the VM_INIT event.
13902       Remove platform assumptions from AddToBootstrapClassLoaderSearch.
13903   </change>
13904   <change date="26 July 2003" version="v81">
13905       Grammar and clarity changes per review.
13906   </change>
13907   <change date="27 July 2003" version="v82">
13908       More grammar and clarity changes per review.
13909       Add Agent_OnUnload.
13910   </change>
13911   <change date="28 July 2003" version="v83">
13912       Change return type of Agent_OnUnload to void.
13913   </change>
13914   <change date="28 July 2003" version="v84">
13915       Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
13916   </change>
13917   <change date="28 July 2003" version="v85">
13918       Steal java.lang.Runtime.availableProcessors() wording for 
13919       AvailableProcessors().
13920       Guarantee that zero will never be an event ID.
13921       Remove some issues which are no longer issues.
13922       Per review, rename and more completely document the timer
13923       information functions.
13924   </change>
13925   <change date="29 July 2003" version="v86">
13926       Non-spec visible change to XML controlled implementation:
13927         SetThreadLocalStorage must run in VM mode.
13928   </change>
13929   <change date="5 August 2003" version="0.1.87">
13930       Add GetErrorName.
13931       Add varargs warning to jvmtiExtensionEvent.
13932       Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
13933       Remove unused can_get_exception_info capability.
13934       Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
13935       Fix jvmtiExtensionFunctionInfo.func declared type.
13936       Extension function returns error code.
13937       Use new version numbering.
13938   </change>
13939   <change date="5 August 2003" version="0.2.88">
13940       Remove the ClassUnload event.
13941   </change>
13942   <change date="8 August 2003" version="0.2.89">
13943       Heap reference iterator callbacks return an enum that 
13944       allows outgoing object references to be ignored.
13945       Allow JNIEnv as a param type to extension events/functions.
13946   </change>
13947   <change date="15 August 2003" version="0.2.90">
13948       Fix a typo.
13949   </change>
13950   <change date="2 September 2003" version="0.2.91">
13951       Remove all metadata functions: GetClassMetadata, 
13952       GetFieldMetadata, and GetMethodMetadata.
13953   </change>
13954   <change date="1 October 2003" version="0.2.92">
13955       Mark the functions Allocate. Deallocate, RawMonitor*, 
13956       SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage 
13957       as safe for use in heap callbacks and GC events.
13958   </change>
13959   <change date="24 November 2003" version="0.2.93">
13960       Add pass through opaque user data pointer to heap iterate 
13961       functions and callbacks.
13962       In the CompiledMethodUnload event, send the code address.
13963       Add GarbageCollectionOccurred event.
13964       Add constant pool reference kind.
13965       Mark the functions CreateRawMonitor and DestroyRawMonitor
13966       as safe for use in heap callbacks and GC events.
13967       Clarify: VMDeath, GetCurrentThreadCpuTimerInfo, 
13968       GetThreadCpuTimerInfo, IterateOverReachableObjects,
13969       IterateOverObjectsReachableFromObject, GetTime and
13970       JVMTI_ERROR_NULL_POINTER.
13971       Add missing errors to: GenerateEvents and
13972       AddToBootstrapClassLoaderSearch.
13973       Fix description of ClassFileLoadHook name parameter.
13974       In heap callbacks and GC/ObjectFree events, specify
13975       that only explicitly allowed functions can be called.
13976       Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
13977       GetTimerInfo, and GetTime during callback.
13978       Allow calling SetTag/GetTag during the onload phase.
13979       SetEventNotificationMode, add: error attempted inappropriate
13980       thread level control.
13981       Remove jvmtiExceptionHandlerEntry.
13982       Fix handling of native methods on the stack -- 
13983       location_ptr param of GetFrameLocation, remove 
13984       JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
13985       jvmtiFrameInfo.location, and jlocation.
13986       Remove typo (from JVMPI) implying that the MonitorWaited
13987       event is sent on sleep.
13988   </change>
13989   <change date="25 November 2003" version="0.2.94">
13990       Clarifications and typos.
13991   </change>
13992   <change date="3 December 2003" version="0.2.95">
13993       Allow NULL user_data in heap iterators.
13994   </change>
13995   <change date="28 January 2004" version="0.2.97">
13996       Add GetThreadState, deprecate GetThreadStatus.
13997   </change>
13998   <change date="29 January 2004" version="0.2.98">
13999       INVALID_SLOT and TYPE_MISMATCH errors should be optional.
14000   </change>
14001   <change date="12 February 2004" version="0.2.102">
14002       Remove MonitorContendedExit.
14003       Added JNIEnv parameter to VMObjectAlloc.
14004       Clarified definition of class_tag and referrer_index 
14005       parameters to heap callbacks.
14006   </change>
14007   <change date="16 Febuary 2004" version="0.2.103">
14008       Document JAVA_TOOL_OPTIONS.
14009   </change>
14010   <change date="17 Febuary 2004" version="0.2.105">
14011       Divide start phase into primordial and start.
14012       Add VMStart event
14013       Change phase associations of functions and events.
14014   </change>
14015   <change date="18 Febuary 2004" version="0.3.6">
14016       Elide deprecated GetThreadStatus.
14017       Bump minor version, subtract 100 from micro version
14018   </change>
14019   <change date="18 Febuary 2004" version="0.3.7">
14020       Document that timer nanosecond values are unsigned.
14021       Clarify text having to do with native methods.
14022   </change>
14023   <change date="19 Febuary 2004" version="0.3.8">
14024       Fix typos.
14025       Remove elided deprecated GetThreadStatus.
14026   </change>
14027   <change date="23 Febuary 2004" version="0.3.9">
14028       Require NotifyFramePop to act on suspended threads.
14029   </change>
14030   <change date="24 Febuary 2004" version="0.3.10">
14031       Add capabilities 
14032         (<internallink id="jvmtiCapabilities.can_redefine_any_class"
14033          ><code>can_redefine_any_class</code></internallink>
14034       and 
14035          <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
14036          ><code>can_generate_all_class_hook_events</code></internallink>) 
14037       and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>) 
14038       which allow some classes to be unmodifiable.
14039   </change>
14040   <change date="28 Febuary 2004" version="0.3.11">
14041       Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
14042   </change>
14043   <change date="8 March 2004" version="0.3.12">
14044       Clarified CompiledMethodUnload so that it is clear the event
14045       may be posted after the class has been unloaded.
14046   </change>
14047   <change date="5 March 2004" version="0.3.13">
14048       Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
14049   </change>
14050   <change date="13 March 2004" version="0.3.14">
14051       Added guideline for the use of the JNI FindClass function in event
14052       callback functions.
14053   </change>
14054   <change date="15 March 2004" version="0.3.15">
14055       Add GetAllStackTraces and GetThreadListStackTraces.
14056   </change>
14057   <change date="19 March 2004" version="0.3.16">
14058       ClassLoad and ClassPrepare events can be posted during start phase.
14059   </change>
14060   <change date="25 March 2004" version="0.3.17">
14061       Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
14062       GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
14063   </change>
14064   <change date="29 March 2004" version="0.3.18">
14065       Return the timer kind in the timer information structure.
14066   </change>
14067   <change date="31 March 2004" version="0.3.19">
14068       Spec clarifications:
14069       JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
14070       ForceGarbageCollection does not run finalizers.
14071       The context of the specification is the Java platform.
14072       Warn about early instrumentation.
14073   </change>
14074   <change date="1 April 2004" version="0.3.20">
14075       Refinements to the above clarifications and
14076       Clarify that an error returned by Agent_OnLoad terminates the VM.
14077   </change>
14078   <change date="1 April 2004" version="0.3.21">
14079       Array class creation does not generate a class load event.
14080   </change>
14081   <change date="7 April 2004" version="0.3.22">
14082       Align thread state hierarchy more closely with java.lang.Thread.State.
14083   </change>
14084   <change date="12 April 2004" version="0.3.23">
14085       Clarify the documentation of thread state.
14086   </change>
14087   <change date="19 April 2004" version="0.3.24">
14088       Remove GarbageCollectionOccurred event -- can be done by agent.
14089   </change>
14090   <change date="22 April 2004" version="0.3.25">
14091       Define "command-line option".
14092   </change>
14093   <change date="29 April 2004" version="0.3.26">
14094       Describe the intended use of bytecode instrumentation.
14095       Fix description of extension event first parameter.
14096   </change>
14097   <change date="30 April 2004" version="0.3.27">
14098       Clarification and typos.
14099   </change>
14100   <change date="18 May 2004" version="0.3.28">
14101       Remove DataDumpRequest event.
14102   </change>
14103   <change date="18 May 2004" version="0.3.29">
14104       Clarify RawMonitorWait with zero timeout.
14105       Clarify thread state after RunAgentThread.
14106   </change>
14107   <change date="24 May 2004" version="0.3.30">
14108       Clean-up: fix bad/old links, etc.
14109   </change>
14110   <change date="30 May 2004" version="0.3.31">
14111       Clarifications including:
14112       All character strings are modified UTF-8.
14113       Agent thread visibiity.
14114       Meaning of obsolete method version.
14115       Thread invoking heap callbacks,
14116   </change>
14117   <change date="1 June 2004" version="1.0.32">
14118       Bump major.minor version numbers to "1.0".
14119   </change>
14120   <change date="2 June 2004" version="1.0.33">
14121       Clarify interaction between ForceGarbageCollection 
14122       and ObjectFree.
14123   </change>
14124   <change date="6 June 2004" version="1.0.34">
14125       Restrict AddToBootstrapClassLoaderSearch and 
14126       SetSystemProperty to the OnLoad phase only.
14127   </change>
14128   <change date="11 June 2004" version="1.0.35">
14129       Fix typo in SetTag.
14130   </change>
14131   <change date="18 June 2004" version="1.0.36">
14132       Fix trademarks.
14133       Add missing parameter in example GetThreadState usage.
14134   </change>
14135   <change date="4 August 2004" version="1.0.37">
14136       Copyright updates.
14137   </change>
14138   <change date="5 November 2004" version="1.0.38">
14139       Add missing function table layout.
14140       Add missing description of C++ member function format of functions.
14141       Clarify that name in CFLH can be NULL.
14142       Released as part of <tm>J2SE</tm> 5.0.
14143   </change>
14144   <change date="24 April 2005" version="1.1.47">
14145       Bump major.minor version numbers to "1.1".
14146       Add ForceEarlyReturn* functions.
14147       Add GetOwnedMonitorStackDepthInfo function.
14148       Add GetCurrentThread function.
14149       Add "since" version marker.
14150       Add AddToSystemClassLoaderSearch.
14151       Allow AddToBootstrapClassLoaderSearch be used in live phase.
14152       Fix historic rubbish in the descriptions of the heap_object_callback 
14153       parameter of IterateOverHeap and IterateOverInstancesOfClass functions; 
14154       disallow NULL for this parameter.
14155       Clarify, correct and make consistent: wording about current thread,
14156       opaque frames and insufficient number of frames in PopFrame.
14157       Consistently use "current frame" rather than "topmost".
14158       Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
14159       by making them compatible with those in ForceEarlyReturn*.
14160       Many other clarifications and wording clean ups.
14161   </change>
14162   <change date="25 April 2005" version="1.1.48">
14163       Add GetConstantPool.
14164       Switch references to the first edition of the VM Spec, to the seconds edition.
14165   </change>
14166   <change date="26 April 2005" version="1.1.49">
14167       Clarify minor/major version order in GetConstantPool.
14168   </change>
14169   <change date="26 April 2005" version="1.1.50">
14170       Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
14171       Reassign GetOwnedMonitorStackDepthInfo to position 153.
14172       Break out Class Loader Search in its own documentation category.
14173       Deal with overly long lines in XML source.
14174   </change>
14175   <change date="29 April 2005" version="1.1.51">
14176       Allow agents be started in the live phase.
14177       Added paragraph about deploying agents.  
14178   </change>
14179   <change date="30 April 2005" version="1.1.52">
14180       Add specification description to SetNativeMethodPrefix(es).
14181       Better define the conditions on GetConstantPool.  
14182   </change>
14183   <change date="30 April 2005" version="1.1.53">
14184       Break out the GetClassVersionNumber function from GetConstantPool.
14185       Clean-up the references to the VM Spec.  
14186   </change>
14187   <change date="1 May 2005" version="1.1.54">
14188       Allow SetNativeMethodPrefix(es) in any phase.
14189       Add clarifications about the impact of redefinition on GetConstantPool.  
14190   </change>
14191   <change date="2 May 2005" version="1.1.56">
14192       Various clarifications to SetNativeMethodPrefix(es).
14193   </change>
14194   <change date="2 May 2005" version="1.1.57">
14195       Add missing performance warning to the method entry event.
14196   </change>
14197   <change date="5 May 2005" version="1.1.58">
14198       Remove internal JVMDI support.
14199   </change>
14200   <change date="8 May 2005" version="1.1.59">
14201       Add <functionlink id="RetransformClasses"/>.
14202       Revamp the bytecode instrumentation documentation.
14203       Change <functionlink id="IsMethodObsolete"/> to no longer 
14204       require the can_redefine_classes capability.
14205   </change>
14206   <change date="11 May 2005" version="1.1.63">
14207       Clarifications for retransformation.
14208   </change>
14209   <change date="11 May 2005" version="1.1.64">
14210       Clarifications for retransformation, per review.
14211       Lock "retransformation (in)capable" at class load enable time.
14212   </change>
14213   <change date="4 June 2005" version="1.1.67">
14214       Add new heap functionity which supports reporting primitive values,
14215       allows setting the referrer tag, and has more powerful filtering:
14216       FollowReferences, IterateThroughHeap, and their associated 
14217       callbacks, structs, enums, and constants.
14218   </change>
14219   <change date="4 June 2005" version="1.1.68">
14220       Clarification.
14221   </change>
14222   <change date="6 June 2005" version="1.1.69">
14223       FollowReferences, IterateThroughHeap: Put callbacks in a struct;
14224       Add missing error codes; reduce bits in the visit control flags.
14225   </change>
14226   <change date="14 June 2005" version="1.1.70">
14227       More on new heap functionity: spec clean-up per review.
14228   </change>
14229   <change date="15 June 2005" version="1.1.71">
14230       More on new heap functionity: Rename old heap section to Heap (1.0).
14231   </change>
14232   <change date="21 June 2005" version="1.1.72">
14233       Fix typos.
14234   </change>
14235   <change date="27 June 2005" version="1.1.73">
14236       Make referrer info structure a union.
14237   </change>
14238   <change date="9 September 2005" version="1.1.74">
14239       In new heap functions:
14240       Add missing superclass reference kind.
14241       Use a single scheme for computing field indexes.
14242       Remove outdated references to struct based referrer info.
14243   </change>
14244   <change date="12 September 2005" version="1.1.75">
14245       Don't callback during FollowReferences on frivolous java.lang.Object superclass.
14246   </change>
14247   <change date="13 September 2005" version="1.1.76">
14248       In string primitive callback, length now Unicode length.
14249       In array and string primitive callbacks, value now "const".
14250       Note possible compiler impacts on setting JNI function table.
14251   </change>
14252   <change date="13 September 2005" version="1.1.77">
14253       GetClassVersionNumbers() and GetConstantPool() should return
14254       error on array or primitive class.
14255   </change>
14256   <change date="14 September 2005" version="1.1.78">
14257       Grammar fixes.
14258   </change>
14259   <change date="26 September 2005" version="1.1.79">
14260       Add IsModifiableClass query.
14261   </change>
14262   <change date="9 February 2006" version="1.1.81">
14263       Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
14264   </change>
14265   <change date="13 February 2006" version="1.1.82">
14266       Doc fixes: update can_redefine_any_class to include retransform.
14267       Clarify that exception events cover all Throwables.
14268       In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
14269       Clarify fields reported in Primitive Field Callback -- static vs instance.
14270       Repair confusing names of heap types, including callback names.
14271       Require consistent usage of stack depth in the face of thread launch methods.
14272       Note incompatibility of <jvmti/> memory management with other systems.
14273   </change>
14274   <change date="14 February 2006" version="1.1.85">
14275       Fix typos and missing renames.
14276   </change>
14277   <change date="13 March 2006" version="1.1.86">
14278       Clarify that jmethodIDs and jfieldIDs can be saved.
14279       Clarify that Iterate Over Instances Of Class includes subclasses.
14280   </change>
14281   <change date="14 March 2006" version="1.1.87">
14282       Better phrasing.
14283   </change>
14284   <change date="16 March 2006" version="1.1.88">
14285       Match the referrer_index for static fields in Object Reference Callback 
14286       with the Reference Implementation (and all other known implementations);
14287       that is, make it match the definition for instance fields.
14288       In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover 
14289       an invalid thread in the list; and specify that not started threads
14290       return empty stacks.
14291   </change>
14292   <change date="17 March 2006" version="1.1.89">
14293       Typo.
14294   </change>
14295   <change date="25 March 2006" version="1.1.90">
14296       Typo.
14297   </change>
14298   <change date="6 April 2006" version="1.1.91">
14299       Remove restrictions on AddToBootstrapClassLoaderSearch and
14300       AddToSystemClassLoaderSearch.
14301   </change>
14302   <change date="1 May 2006" version="1.1.93">
14303       Changed spec to return -1 for monitor stack depth for the
14304       implementation which can not determine stack depth. 
14305   </change>
14306   <change date="3 May 2006" version="1.1.94">
14307       Corrections for readability and accuracy courtesy of Alan Pratt of IBM. 
14308       List the object relationships reported in FollowReferences.
14309   </change>
14310   <change date="5 May 2006" version="1.1.95">
14311       Clarify the object relationships reported in FollowReferences.
14312   </change>
14313   <change date="28 June 2006" version="1.1.98">
14314       Clarify DisposeEnvironment; add warning.
14315       Fix typos in SetLocalXXX "retrieve" => "set".
14316       Clarify that native method prefixes must remain set while used.
14317       Clarify that exactly one Agent_OnXXX is called per agent.
14318       Clarify that library loading is independent from start-up.
14319       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14320   </change>
14321   <change date="31 July 2006" version="1.1.99">
14322       Clarify the interaction between functions and exceptions.
14323       Clarify and give examples of field indices.
14324       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14325       Update links to point to Java 6.
14326   </change>
14327   <change date="6 August 2006" version="1.1.102">
14328       Add ResourceExhaustedEvent.
14329   </change>
14330   <change date="11 October 2012" version="1.2.2">
14331       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14332   </change>
14333   <change date="19 June 2013" version="1.2.3">
14334       Added support for statically linked agents.
14335   </change>
14336 </changehistory>
14337 
14338 </specification>
14339 <!-- Keep this comment at the end of the file
14340 Local variables:
14341 mode: sgml
14342 sgml-omittag:t
14343 sgml-shorttag:t
14344 sgml-namecase-general:t
14345 sgml-general-insert-case:lower
14346 sgml-minimize-attributes:nil
14347 sgml-always-quote-attributes:t
14348 sgml-indent-step:2
14349 sgml-indent-data:t
14350 sgml-parent-document:nil
14351 sgml-exposed-tags:nil
14352 sgml-local-catalogs:nil
14353 sgml-local-ecat-files:nil
14354 End:
14355 -->