1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
   3 <!--
   4  Copyright (c) 2002, 2017, Oracle and/or its affiliates. All rights reserved.
   5  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6 
   7  This code is free software; you can redistribute it and/or modify it
   8  under the terms of the GNU General Public License version 2 only, as
   9  published by the Free Software Foundation.
  10 
  11  This code is distributed in the hope that it will be useful, but WITHOUT
  12  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  version 2 for more details (a copy is included in the LICENSE file that
  15  accompanied this code).
  16 
  17  You should have received a copy of the GNU General Public License version
  18  2 along with this work; if not, write to the Free Software Foundation,
  19  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20 
  21  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  or visit www.oracle.com if you need additional information or have any
  23  questions.
  24 -->
  25 
  26 <!DOCTYPE specification [
  27    <!ELEMENT specification (title, intro*, functionsection, errorsection,
  28                             eventsection, datasection, issuessection, changehistory)>
  29    <!ATTLIST specification label CDATA #REQUIRED
  30                            majorversion CDATA #REQUIRED
  31                            minorversion CDATA #REQUIRED
  32                            microversion CDATA #REQUIRED>
  33 
  34    <!ELEMENT title (#PCDATA|jvmti|tm)*>
  35    <!ATTLIST title subtitle CDATA #REQUIRED>
  36 
  37    <!ELEMENT intro ANY>
  38    <!ATTLIST intro id CDATA #IMPLIED
  39                    label CDATA "">
  40 
  41    <!ELEMENT functionsection (intro*, category*)>
  42    <!ATTLIST functionsection label CDATA #REQUIRED>
  43 
  44    <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*,
  45                           (function|callback|elide)*)>
  46    <!ATTLIST category id CDATA #REQUIRED
  47                       label CDATA #REQUIRED>
  48 
  49    <!ELEMENT function (synopsis, typedef*, description?, origin,
  50                          (capabilities|eventcapabilities),
  51                          parameters, errors)>
  52    <!ATTLIST function id CDATA #REQUIRED
  53                       num CDATA #REQUIRED
  54                       phase (onload|onloadOnly|start|live|any) #IMPLIED
  55                       callbacksafe (safe|unsafe) #IMPLIED
  56                       impl CDATA #IMPLIED
  57                       hide CDATA #IMPLIED
  58                       jkernel (yes|no) #IMPLIED
  59                       since CDATA "1.0">
  60 
  61    <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  62                         jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
  63                         synopsis, description?, parameters)>
  64    <!ATTLIST callback id CDATA #REQUIRED
  65                       since CDATA "1.0">
  66 
  67    <!ELEMENT synopsis (#PCDATA|jvmti)*>
  68 
  69    <!ELEMENT typedef (description?, field*)>
  70    <!ATTLIST typedef id CDATA #REQUIRED
  71                      label CDATA #REQUIRED
  72                      since CDATA "1.0">
  73 
  74    <!ELEMENT uniontypedef (description?, field*)>
  75    <!ATTLIST uniontypedef id CDATA #REQUIRED
  76                      label CDATA #REQUIRED
  77                      since CDATA "1.0">
  78 
  79    <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  80                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct),
  81                     description)>
  82    <!ATTLIST field id CDATA #REQUIRED>
  83 
  84    <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
  85    <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
  86                      label CDATA #REQUIRED>
  87 
  88    <!ELEMENT capabilityfield (description)>
  89    <!ATTLIST capabilityfield id CDATA #REQUIRED
  90                    disp1 CDATA ""
  91                    disp2 CDATA ""
  92                    since CDATA "1.0">
  93 
  94    <!ELEMENT description ANY>
  95 
  96    <!ELEMENT capabilities (required*, capability*)>
  97 
  98    <!ELEMENT eventcapabilities EMPTY>
  99 
 100    <!ELEMENT required ANY>
 101    <!ATTLIST required id CDATA #REQUIRED>
 102 
 103    <!ELEMENT capability ANY>
 104    <!ATTLIST capability id CDATA #REQUIRED>
 105 
 106    <!ELEMENT parameters (param*)>
 107 
 108    <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
 109                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
 110                      outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf),
 111                     description)>
 112    <!ATTLIST param id CDATA #REQUIRED>
 113 
 114    <!ELEMENT jmethodID EMPTY>
 115    <!ATTLIST jmethodID class  CDATA #IMPLIED
 116                        native CDATA #IMPLIED>
 117 
 118    <!ELEMENT jfieldID EMPTY>
 119    <!ATTLIST jfieldID class CDATA #IMPLIED>
 120 
 121    <!ELEMENT jclass EMPTY>
 122    <!ATTLIST jclass method CDATA #IMPLIED
 123                     field  CDATA #IMPLIED>
 124 
 125    <!ELEMENT jframeID EMPTY>
 126    <!ATTLIST jframeID thread CDATA #IMPLIED>
 127 
 128    <!ELEMENT jrawMonitorID EMPTY>
 129 
 130    <!ELEMENT jthread EMPTY>
 131    <!ATTLIST jthread started CDATA #IMPLIED
 132                      null CDATA #IMPLIED
 133                      frame CDATA #IMPLIED
 134                      impl CDATA #IMPLIED>
 135 
 136    <!ELEMENT varargs EMPTY>
 137 
 138    <!ELEMENT jthreadGroup EMPTY>
 139    <!ELEMENT jobject EMPTY>
 140    <!ELEMENT jvalue EMPTY>
 141    <!ELEMENT jchar EMPTY>
 142    <!ELEMENT jint EMPTY>
 143    <!ATTLIST jint min CDATA #IMPLIED>
 144    <!ELEMENT jlong EMPTY>
 145    <!ELEMENT jfloat EMPTY>
 146    <!ELEMENT jdouble EMPTY>
 147    <!ELEMENT jlocation EMPTY>
 148    <!ELEMENT jboolean EMPTY>
 149    <!ELEMENT char EMPTY>
 150    <!ELEMENT uchar EMPTY>
 151    <!ELEMENT size_t EMPTY>
 152    <!ELEMENT void EMPTY>
 153    <!ELEMENT enum (#PCDATA)*>
 154    <!ELEMENT struct (#PCDATA)*>
 155 
 156    <!ELEMENT nullok ANY>
 157 
 158    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 159                                    jthreadGroup|jobject|jvalue), nullok?)>
 160 
 161    <!ELEMENT outptr     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 162                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 163                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 164 
 165    <!ELEMENT allocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 166                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 167                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 168    <!ATTLIST allocbuf incount CDATA #IMPLIED
 169                       outcount CDATA #IMPLIED>
 170 
 171    <!ELEMENT allocallocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 172                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 173                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 174    <!ATTLIST allocallocbuf incount CDATA #IMPLIED
 175                       outcount CDATA #IMPLIED>
 176 
 177    <!ELEMENT inptr      (struct, nullok?)>
 178 
 179    <!ELEMENT inbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 180                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 181                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 182    <!ATTLIST inbuf    incount CDATA #IMPLIED>
 183 
 184    <!ELEMENT outbuf     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 185                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 186                                    jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
 187    <!ATTLIST outbuf   incount CDATA #IMPLIED
 188                       outcount CDATA #IMPLIED>
 189 
 190    <!ELEMENT vmbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 191                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 192                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 193    <!ATTLIST vmbuf    incount CDATA #IMPLIED
 194                       outcount CDATA #IMPLIED>
 195 
 196    <!ELEMENT agentbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 197                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 198                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 199    <!ATTLIST agentbuf incount CDATA #IMPLIED
 200                       outcount CDATA #IMPLIED>
 201 
 202    <!ELEMENT allocfieldbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 203                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 204                                    jlocation|jboolean|char|uchar|size_t|void))>
 205    <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
 206 
 207    <!ELEMENT errors (error*)>
 208 
 209    <!ELEMENT error ANY>
 210    <!ATTLIST error id CDATA #REQUIRED>
 211 
 212    <!ELEMENT errorsection (intro*, errorcategory*)>
 213    <!ATTLIST errorsection label CDATA #REQUIRED>
 214 
 215    <!ELEMENT errorcategory (intro*, errorid*)>
 216    <!ATTLIST errorcategory id CDATA #REQUIRED
 217                            label CDATA #REQUIRED>
 218 
 219    <!ELEMENT errorid ANY>
 220    <!ATTLIST errorid id CDATA #REQUIRED
 221                      num CDATA #REQUIRED>
 222 
 223    <!ELEMENT datasection (intro*, basetypes*)>
 224 
 225    <!ELEMENT basetypes (intro*, basetype*)>
 226    <!ATTLIST basetypes id CDATA #REQUIRED
 227                        label CDATA #REQUIRED>
 228 
 229    <!ELEMENT basetype (definition?,description)>
 230    <!ATTLIST basetype id CDATA #REQUIRED>
 231 
 232    <!ELEMENT definition (#PCDATA|jvmti)*>
 233 
 234    <!ELEMENT eventsection (intro*, (event|elide)*)>
 235    <!ATTLIST eventsection label CDATA #REQUIRED>
 236 
 237    <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
 238    <!ATTLIST event id CDATA #REQUIRED
 239                    label CDATA #REQUIRED
 240                    const CDATA #REQUIRED
 241                    num CDATA #REQUIRED
 242                    phase (onload|start|live|any) #IMPLIED
 243                    filtered (thread|global) #IMPLIED
 244                    since CDATA "1.0">
 245 
 246    <!ELEMENT issuessection (intro*)>
 247    <!ATTLIST issuessection label CDATA #REQUIRED>
 248 
 249    <!ELEMENT changehistory (intro*, change*)>
 250    <!ATTLIST changehistory update CDATA #REQUIRED
 251                            id CDATA #REQUIRED>
 252 
 253    <!ELEMENT change ANY>
 254    <!ATTLIST change date CDATA #REQUIRED
 255                     version CDATA #IMPLIED>
 256 
 257    <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
 258    <!ATTLIST functionlink id CDATA #REQUIRED>
 259 
 260    <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
 261    <!ATTLIST datalink id CDATA #REQUIRED>
 262 
 263    <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
 264    <!ATTLIST typelink id CDATA #REQUIRED>
 265 
 266    <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
 267    <!ATTLIST fieldlink id CDATA #REQUIRED
 268                        struct CDATA #REQUIRED>
 269 
 270    <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
 271    <!ATTLIST paramlink id CDATA #REQUIRED>
 272 
 273    <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
 274    <!ATTLIST eventlink id CDATA #REQUIRED>
 275 
 276    <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
 277    <!ATTLIST errorlink id CDATA #REQUIRED>
 278 
 279    <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
 280    <!ATTLIST externallink id CDATA #REQUIRED>
 281 
 282    <!ELEMENT vmspec EMPTY>
 283    <!ATTLIST vmspec chapter CDATA #IMPLIED>
 284 
 285    <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
 286    <!ATTLIST internallink id CDATA #REQUIRED>
 287 
 288    <!ELEMENT functionphaselist EMPTY>
 289    <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
 290 
 291    <!ELEMENT eventphaselist EMPTY>
 292    <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
 293 
 294    <!ELEMENT issue ANY>
 295 
 296    <!ELEMENT rationale ANY>
 297 
 298    <!ELEMENT todo ANY>
 299 
 300    <!ELEMENT origin (#PCDATA)*>
 301 
 302    <!ELEMENT elide (intro|function|callback|event)*>
 303    <!ATTLIST elide why CDATA #IMPLIED>
 304 
 305    <!ELEMENT constants (constant*)>
 306    <!ATTLIST constants id CDATA #REQUIRED
 307                        label CDATA #REQUIRED
 308                        kind (enum|bits|const) #REQUIRED
 309                        since CDATA "1.0">
 310 
 311    <!ELEMENT constant ANY>
 312    <!ATTLIST constant id CDATA #REQUIRED
 313                       num CDATA #REQUIRED>
 314 
 315    <!ELEMENT tm (#PCDATA)>
 316 
 317    <!ELEMENT i (#PCDATA|jvmti|tm)*>
 318 
 319    <!ELEMENT b (#PCDATA|jvmti|code)*>
 320 
 321    <!ELEMENT code (#PCDATA|space)*>
 322 
 323    <!ELEMENT pre ANY>
 324 
 325    <!ELEMENT space EMPTY>
 326 
 327    <!ELEMENT jvmti EMPTY>
 328 
 329    <!ELEMENT example (#PCDATA|i)*>
 330 
 331    <!ELEMENT br EMPTY>
 332 
 333    <!ELEMENT p EMPTY>
 334 
 335    <!ELEMENT dl  (dt|dd)+>
 336 
 337    <!ELEMENT dd  ANY>
 338 
 339    <!ELEMENT dt  (#PCDATA|jvmti|code|i|b)*>
 340 
 341    <!ELEMENT table  (tr)+>
 342 
 343    <!ELEMENT tr  (td|th)*>
 344 
 345    <!ELEMENT td  ANY>
 346    <!ATTLIST td align (left|right|center) "center">
 347 
 348    <!ELEMENT th  ANY>
 349    <!ATTLIST th align (left|right|center) "center">
 350 
 351    <!ELEMENT ul  (li)+>
 352    <!ATTLIST ul type (disc|circle|square) "disc">
 353 
 354    <!ELEMENT li  ANY>
 355  ]>
 356 
 357 <specification label="JVM(TM) Tool Interface"
 358         majorversion="9"
 359         minorversion="0"
 360         microversion="0">
 361   <title subtitle="Version">
 362     <tm>JVM</tm> Tool Interface
 363   </title>
 364 
 365   <intro id="whatIs" label="What is the JVM Tool Interface?">
 366     The <tm>JVM</tm> Tool Interface (<jvmti/>)
 367     is a programming interface used by development and monitoring tools.
 368     It provides both a way to inspect the state and
 369     to control the execution of applications running in the
 370     <tm>Java</tm> virtual machine (VM).
 371     <p/>
 372     <jvmti/> is intended to provide a VM interface for the full breadth of tools
 373     that need access to VM state, including but not limited to: profiling,
 374     debugging, monitoring, thread analysis, and coverage analysis tools.
 375     <p/>
 376     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
 377     machine.
 378     <p/>
 379     <jvmti/> is a two-way interface.
 380     A client of <jvmti/>, hereafter called an <i>agent</i>,
 381     can be notified of
 382     interesting occurrences through <internallink id="EventSection">events</internallink>.
 383     <jvmti/>
 384     can query and control the application through many
 385     <internallink id="FunctionSection">functions</internallink>,
 386     either in response to events or
 387     independent of them.
 388     <p/>
 389     Agents run in the same process with and communicate directly with
 390     the virtual machine executing
 391     the application being examined.  This communication is
 392     through a native interface (<jvmti/>). The native in-process interface allows
 393     maximal control with minimal intrusion on the part of a tool.
 394     Typically, agents are relatively compact. They can be controlled
 395     by a separate process which implements the bulk of a tool's
 396     function without interfering with the target application's normal execution.
 397   </intro>
 398 
 399   <intro id="architecture" label="Architecture">
 400     Tools can be written directly to <jvmti/> or indirectly
 401     through higher level interfaces.
 402     The Java Platform Debugger Architecture includes <jvmti/>, but also
 403     contains higher-level, out-of-process debugger interfaces. The higher-level
 404     interfaces are more appropriate than <jvmti/> for many tools.
 405     For more information on the Java Platform Debugger Architecture,
 406     see the
 407     <externallink id="docs/technotes/guides/jpda/architecture.html">Java
 408       Platform Debugger Architecture website</externallink>.
 409   </intro>
 410 
 411   <intro id="writingAgents" label="Writing Agents">
 412     Agents can be written in any native language that supports C
 413     language calling conventions and C or C++
 414     definitions.
 415     <p/>
 416     The function, event, data type, and constant definitions needed for
 417     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 418     To use these definitions add the <tm>J2SE</tm> include directory
 419     to your include path and add
 420     <example>
 421 #include &lt;jvmti.h&gt;
 422     </example>
 423     to your source code.
 424   </intro>
 425 
 426   <intro id="deployingAgents" label="Deploying Agents">
 427     An agent is deployed in a platform specific manner but is typically the
 428     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating
 429     system, for example, an agent library is a "Dynamic Linked Library" (DLL).
 430     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
 431     object (<code>.so</code> file).
 432     <p/>
 433 
 434     An agent may be started at VM startup by specifying the agent library
 435     name using a <internallink id="starting">command line option</internallink>.
 436     Some implementations may support a mechanism to <internallink id="onattach">
 437     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
 438     The details of how this is initiated are implementation specific.
 439   </intro>
 440 
 441     <intro id="entry point" label="Statically Linked Agents (since version 1.2.3)">
 442 
 443       A native JVMTI Agent may be <i>statically linked</i> with the VM.
 444       The manner in which the library and VM image are combined is
 445       implementation-dependent.
 446       An agent L whose image has been combined with the VM is defined as
 447       <i>statically linked</i> if and only if the agent exports a function
 448       called Agent_OnLoad_L.
 449 <p/>
 450       If a <i>statically linked</i> agent L exports a function called
 451       Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
 452       function will be ignored.
 453       If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
 454       function will be invoked with the same arguments and expected return
 455       value as specified for the Agent_OnLoad function.
 456       An agent L that is <i>statically linked</i> will prohibit an agent of
 457       the same name from being loaded dynamically.
 458 <p/>
 459       The VM will invoke the Agent_OnUnload_L function of the agent, if such
 460       a function is exported, at the same point during VM execution as it would
 461       have called the dynamic entry point Agent_OnUnLoad. A statically loaded
 462       agent cannot be unloaded. The Agent_OnUnload_L function will still be
 463       called to do any other agent shutdown related tasks.
 464       If a <i>statically linked</i> agent L exports a function called
 465       Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
 466       function will be ignored.
 467 <p/>
 468       If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
 469       will be invoked with the same arguments and expected return value as
 470       specified for the Agent_OnAttach function.
 471       If a <i>statically linked</i> agent L exports a function called
 472       Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
 473       function will be ignored.
 474 </intro>
 475 
 476   <intro id="starting" label="Agent Command Line Options">
 477     The term "command-line option" is used below to
 478     mean options supplied in the <code>JavaVMInitArgs</code> argument
 479     to the <code>JNI_CreateJavaVM</code> function of the JNI
 480     Invocation API.
 481     <p/>
 482     One of the two following
 483     command-line options is used on VM startup to
 484     properly load and run agents.
 485     These arguments identify the library containing
 486     the agent as well as an options
 487     string to be passed in at startup.
 488     <dl>
 489       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 490       <dd>
 491         The name following <code>-agentlib:</code> is the name of the
 492         library to load.  Lookup of the library, both its full name and location,
 493         proceeds in a platform-specific manner.
 494         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
 495         operating system specific file name.
 496         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 497         For example, if the option
 498         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to
 499         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
 500         under <tm>Windows</tm> or <code>libfoo.so</code> from the
 501         <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating
 502         environment.
 503         If the agent library is statically linked into the executable
 504         then no actual loading takes place.
 505     <p/>
 506       </dd>
 507       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 508       <dd>
 509         The path following <code>-agentpath:</code> is the absolute path from which
 510         to load the library.
 511         No library name expansion will occur.
 512         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 513         For example, if the option
 514         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to
 515         load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
 516         library is statically linked into the executable
 517         then no actual loading takes place.
 518     <p/>
 519       </dd>
 520     </dl>
 521     For a dynamic shared library agent, the start-up routine
 522     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 523     in the library will be invoked. If the agent library is statically linked
 524     into the executable then the system will attempt to invoke the
 525     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> entry point where
 526     &lt;agent-lib-name&gt; is the basename of the
 527     agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
 528     the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
 529     <p/>
 530     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
 531     will be searched for JNI native method implementations to facilitate the
 532     use of Java programming language code in tools, as is needed for
 533     <internallink id="bci">bytecode instrumentation</internallink>.
 534     <p/>
 535     The agent libraries will be searched after all other libraries have been
 536     searched (agents wishing to override or intercept the native method
 537     implementations of non-agent methods can use the
 538     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
 539     <p/>
 540     These switches do the above and nothing more - they do not change the
 541     state of the VM or <jvmti/>.  No command line options are needed
 542     to enable <jvmti/>
 543     or aspects of <jvmti/>, this is handled programmatically
 544     by the use of
 545     <internallink id="capability">capabilities</internallink>.
 546   </intro>
 547 
 548   <intro id="startup" label="Agent Start-Up">
 549     The VM starts each agent by invoking a start-up function.
 550     If the agent is started in the <code>OnLoad</code>
 551     <functionlink id="GetPhase">phase</functionlink> the function
 552     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 553     or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
 554     for statically linked agents will be invoked.
 555     If the agent is started in the live
 556     <functionlink id="GetPhase">phase</functionlink> the function
 557     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
 558     or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
 559     for statically linked agents will be invoked.
 560     Exactly one call to a start-up function is made per agent.
 561   </intro>
 562 
 563   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
 564     If an agent is started during the <code>OnLoad</code> phase then its
 565     agent library must export a start-up function with the following prototype:
 566     <example>
 567 JNIEXPORT jint JNICALL
 568 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
 569     Or for a statically linked agent named 'L':
 570     <example>
 571 JNIEXPORT jint JNICALL
 572 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
 573 
 574     The VM will start the agent by calling this function.
 575     It will be called early enough in VM initialization that:
 576     <ul>
 577       <li><functionlink id="SetSystemProperty">system properties</functionlink>
 578         may be set before they have been used in the start-up of the VM</li>
 579       <li>the full set of
 580         <internallink id="capability">capabilities</internallink>
 581         is still available (note that capabilities that configure the VM
 582         may only be available at this time--see the
 583         <internallink id="capability">Capability function section</internallink>)</li>
 584       <li>no bytecodes have executed</li>
 585       <li>no classes have been loaded</li>
 586       <li>no objects have been created</li>
 587     </ul>
 588     <p/>
 589     The VM will call the <code>Agent_OnLoad</code> or
 590     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> function with
 591     <i>&lt;options&gt;</i> as the second argument -
 592     that is, using the command-line option examples,
 593     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
 594     argument of <code>Agent_OnLoad</code>.
 595     The <code>options</code> argument is encoded as a
 596     <internallink id="mUTF">modified UTF-8</internallink> string.
 597     If <i>=&lt;options&gt;</i> is not specified,
 598     a zero length string is passed to <code>options</code>.
 599     The lifespan of the <code>options</code> string is the
 600     <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code>
 601     call.  If needed beyond this time the string or parts of the string must
 602     be copied.
 603     The period between when <code>Agent_OnLoad</code> is called and when it
 604     returns is called the <i>OnLoad phase</i>.
 605     Since the VM is not initialized during the OnLoad
 606     <functionlink id="GetPhase">phase</functionlink>,
 607     the set of allowed operations
 608     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
 609     functionality available at this time).
 610     The agent can safely process the options and set
 611     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once
 612     the VM initialization event is received
 613     (that is, the <eventlink id="VMInit">VMInit</eventlink>
 614     callback is invoked), the agent
 615     can complete its initialization.
 616     <rationale>
 617       Early startup is required so that agents can set the desired capabilities,
 618       many of which must be set before the VM is initialized.
 619       In JVMDI, the -Xdebug command-line option provided
 620       very coarse-grain control of capabilities.
 621       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
 622       No reasonable command-line
 623       option could provide the fine-grain of control required to balance needed capabilities vs
 624       performance impact.
 625       Early startup is also needed so that agents can control the execution
 626       environment - modifying the file system and system properties to install
 627       their functionality.
 628     </rationale>
 629     <p/>
 630     The return value from <code>Agent_OnLoad</code> or
 631     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> is used to indicate an error.
 632     Any value other than zero indicates an error and causes termination of the VM.
 633   </intro>
 634 
 635   <intro id="onattach" label="Agent Start-Up (Live phase)">
 636     A VM may support a mechanism that allows agents to be started in the VM during the live
 637     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
 638     are implementation specific. For example, a tool may use some platform specific mechanism,
 639     or implementation specific API, to attach to the running VM, and request it start a given
 640     agent.
 641     <p/>
 642     If an agent is started during the live phase then its agent library
 643     must export a start-up function
 644     with the following prototype:
 645     <example>
 646 JNIEXPORT jint JNICALL
 647 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
 648 Or for a statically linked agent named 'L':
 649     <example>
 650 JNIEXPORT jint JNICALL
 651 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
 652 
 653     <p/>
 654     The VM will start the agent by calling this function.
 655     It will be called in the context of a thread
 656     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
 657     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
 658     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
 659     </internallink> string.
 660     If startup options were not provided, a zero length string is passed to
 661     <code>options</code>. The lifespan of the <code>options</code> string is the
 662     <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> call.
 663     If needed beyond this time the string or parts of the string must be copied.
 664     <p/>
 665     Note that some <internallink id="capability">capabilities</internallink>
 666     may not be available in the live phase.
 667     <p/>
 668     The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name
 669     &gt;</code> function initializes the agent and returns a value
 670     to the VM to indicate if an error occurred. Any value other than zero indicates an error.
 671     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes
 672     some implementation specific action -- for example it might print an error to standard error,
 673     or record the error in a system log.
 674   </intro>
 675 
 676   <intro id="onunload" label="Agent Shutdown">
 677     The library may optionally export a
 678     shutdown function with the following prototype:
 679     <example>
 680 JNIEXPORT void JNICALL
 681 Agent_OnUnload(JavaVM *vm)</example>
 682     Or for a statically linked agent named 'L':
 683     <example>
 684 JNIEXPORT void JNICALL
 685 Agent_OnUnload_L(JavaVM *vm)</example>
 686 
 687     This function will be called by the VM when the library is about to be unloaded.
 688     The library will be unloaded (unless it is statically linked into the
 689     executable) and this function will be called if some platform specific
 690     mechanism causes the unload (an unload mechanism is not specified in this document)
 691     or the library is (in effect) unloaded by the termination of the VM whether through
 692     normal termination or VM failure, including start-up failure.
 693     Uncontrolled shutdown is, of couse, an exception to this rule.
 694     Note the distinction between this function and the
 695     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
 696     to be sent, the VM must have run at least to the point of initialization and a valid
 697     <jvmti/> environment must exist which has set a callback for VMDeath
 698     and enabled the event.
 699     None of these are required for <code>Agent_OnUnload</code> or
 700     <code>Agent_OnUnload_&lt;agent-lib-name&gt;</code> and this function
 701     is also called if the library is unloaded for other reasons.
 702     In the case that a VM Death event is sent, it will be sent before this
 703     function is called (assuming this function is called due to VM termination).
 704     This function can be used to clean-up resources allocated by the agent.
 705   </intro>
 706 
 707   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
 708     Since the command-line cannot always be accessed or modified, for example in embedded VMs
 709     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
 710     provided so that agents may be launched in these cases.
 711     <p/>
 712     Platforms which support environment variables or other named strings, may support the
 713     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space
 714     boundaries.  White-space characters include space, tab, carriage-return, new-line,
 715     vertical-tab, and form-feed.  Sequences of white-space characters are considered
 716     equivalent to a single white-space character.  No white-space is included in the options
 717     unless quoted.  Quoting is as follows:
 718     <ul>
 719         <li>All characters enclosed between a pair of single quote marks (''), except a single
 720         quote, are quoted.</li>
 721         <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
 722         <li>All characters enclosed between a pair of double quote marks (""), except a double
 723         quote, are quoted.</li>
 724         <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
 725         <li>A quoted part can start or end anywhere in the variable.</li>
 726         <li>White-space characters have no special meaning when quoted -- they are included in
 727         the option like any other character and do not mark white-space boundaries.</li>
 728         <li>The pair of quote marks is not included in the option.</li>
 729     </ul>
 730     <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied
 731     in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is
 732     a concern; for example, the Reference Implementation disables this feature on Unix systems when
 733     the effective user or group ID differs from the real ID.
 734     This feature is intended to support the initialization of tools -- specifically including the
 735     launching of native or Java programming language agents.  Multiple tools may wish to use this
 736     feature, so the variable should not be overwritten, instead,  options should be appended to
 737     the variable.  Note that since the variable is processed at the time of the JNI Invocation
 738     API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
 739   </intro>
 740 
 741   <intro id="environments" label="Environments">
 742     The <jvmti/> specification supports the use of multiple simultaneous
 743     <jvmti/> agents.
 744     Each agent has its own <jvmti/> environment.
 745     That is, the <jvmti/> state is
 746     separate for each agent - changes to one environment do not affect the
 747     others.  The state of a <jvmti/>
 748     environment includes:
 749     <ul>
 750       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
 751       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
 752       <li><internallink id="capability">the capabilities</internallink></li>
 753       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
 754     </ul>
 755     Although their <jvmti/> state
 756     is separate, agents inspect and modify the shared state
 757     of the VM, they also share the native environment in which they execute.
 758     As such, an agent can perturb the results of other agents or cause them
 759     to fail.  It is the responsibility of the agent writer to specify the level
 760     of compatibility with other agents.  <jvmti/> implementations are not capable
 761     of preventing destructive interactions between agents. Techniques to reduce
 762     the likelihood of these occurrences are beyond the scope of this document.
 763     <p/>
 764     An agent creates a <jvmti/> environment
 765     by passing a <jvmti/> version
 766     as the interface ID to the JNI Invocation API function
 767     <externallink id="jni/invocation.html#getenv">
 768       <code>GetEnv</code></externallink>.
 769     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
 770     for more details on the creation and use of
 771     <jvmti/> environments.
 772     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from
 773     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
 774   </intro>
 775 
 776   <intro id="bci" label="Bytecode Instrumentation">
 777     This interface does not include some events that one might expect in an interface with
 778     profiling support.  Some examples include object allocation events and full speed
 779     method enter and exit events.  The interface instead provides support for
 780     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
 781     bytecode instructions which comprise the target program.  Typically, these alterations
 782     are to add "events" to the code of a method - for example, to add, at the beginning of a method,
 783     a call to <code>MyProfiler.methodEntered()</code>.
 784     Since the changes are purely additive, they do not modify application
 785     state or behavior.
 786     Because the inserted agent code is standard bytecodes, the VM can run at full speed,
 787     optimizing not only the target program but also the instrumentation.  If the
 788     instrumentation does not involve switching from bytecode execution, no expensive
 789     state transitions are needed.  The result is high performance events.
 790     This approach also provides complete control to the agent: instrumentation can be
 791     restricted to "interesting" portions of the code (e.g., the end user's code) and
 792     can be conditional.  Instrumentation can run entirely in Java programming language
 793     code or can call into the native agent.  Instrumentation can simply maintain
 794     counters or can statistically sample events.
 795     <p/>
 796     Instrumentation can be inserted in one of three ways:
 797     <ul>
 798       <li>
 799         Static Instrumentation: The class file is instrumented before it
 800         is loaded into the VM - for example, by creating a duplicate directory of
 801         <code>*.class</code> files which have been modified to add the instrumentation.
 802         This method is extremely awkward and, in general, an agent cannot know
 803         the origin of the class files which will be loaded.
 804       </li>
 805       <li>
 806         Load-Time Instrumentation: When a class file is loaded by the VM, the raw
 807         bytes of the class file are sent for instrumentation to the agent.
 808         The <eventlink id="ClassFileLoadHook"/>
 809         event, triggered by the class load,
 810         provides this functionality.  This mechanism provides efficient
 811         and complete access to one-time instrumentation.
 812       </li>
 813       <li>
 814         Dynamic Instrumentation: A class which is already loaded (and possibly
 815         even running) is modified.  This optional feature is provided by the
 816         <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
 817         <functionlink id="RetransformClasses"/> function.
 818         Classes can be modified multiple times and can be returned to their
 819         original state.
 820         The mechanism allows instrumentation which changes during the
 821         course of execution.
 822       </li>
 823     </ul>
 824     <p/>
 825     The class modification functionality provided in this interface
 826     is intended to provide a mechanism for instrumentation
 827     (the <eventlink id="ClassFileLoadHook"/> event
 828     and the <functionlink id="RetransformClasses"/> function)
 829     and, during development, for fix-and-continue debugging
 830     (the <functionlink id="RedefineClasses"/> function).
 831     <p/>
 832     Care must be taken to avoid perturbing dependencies, especially when
 833     instrumenting core classes.  For example, an approach to getting notification
 834     of every object allocation is to instrument the constructor on
 835     <code>Object</code>.  Assuming that the constructor is initially
 836     empty, the constructor could be changed to:
 837     <example>
 838       public Object() {
 839         MyProfiler.allocationTracker(this);
 840       }
 841     </example>
 842     However, if this change was made using the
 843     <eventlink id="ClassFileLoadHook"/>
 844     event then this might impact a typical VM as follows:
 845     the first created object will call the constructor causing a class load of
 846     <code>MyProfiler</code>; which will then cause
 847     object creation, and since <code>MyProfiler</code> isn't loaded yet,
 848     infinite recursion; resulting in a stack overflow.  A refinement of this
 849     would be to delay invoking the tracking method until a safe time.  For
 850     example, <code>trackAllocations</code> could be set in the
 851     handler for the <code>VMInit</code> event.
 852     <example>
 853       static boolean trackAllocations = false;
 854 
 855       public Object() {
 856         if (trackAllocations) {
 857           MyProfiler.allocationTracker(this);
 858         }
 859       }
 860     </example>
 861     <p/>
 862     The <functionlink id="SetNativeMethodPrefix"/> allows native methods
 863     to be instrumented by the use of wrapper methods.
 864   </intro>
 865 
 866 <intro id="bcimodules" label="Bytecode Instrumentation of code in modules">
 867   Agents can use the functions <functionlink id="AddModuleReads"/>,
 868   <functionlink id="AddModuleExports"/>, <functionlink id="AddModuleOpens"/>,
 869   <functionlink id="AddModuleUses"/> and <functionlink id="AddModuleProvides"/>
 870   to update a module to expand the set of modules that it reads, the set of
 871   packages that it exports or opens to other modules, or the services that it
 872   uses and provides.
 873   <p/>
 874   As an aid to agents that deploy supporting classes on the search path of
 875   the bootstrap class loader, or the search path of the class loader that
 876   loads the main class, the Java virtual machine arranges for the module
 877   of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
 878   read the unnamed module of both class loaders.
 879 </intro>
 880 
 881   <intro id="mUTF" label="Modified UTF-8 String Encoding">
 882     <jvmti/> uses modified UTF-8 to encode character strings.
 883     This is the same encoding used by JNI.
 884     Modified UTF-8 differs
 885     from standard UTF-8 in the representation of supplementary characters
 886     and of the null character. See the
 887     <externallink id="jni/types.html#modified-utf-8-strings">
 888       Modified UTF-8 Strings</externallink>
 889     section of the JNI specification for details.
 890   </intro>
 891 
 892   <intro id="context" label="Specification Context">
 893     Since this interface provides access to the state of applications running in the
 894     Java virtual machine;
 895     terminology refers to the Java platform and not the native
 896     platform (unless stated otherwise).  For example:
 897     <ul>
 898       <li>"thread" means Java programming language thread.</li>
 899       <li>"stack frame" means Java virtual machine stack frame.</li>
 900       <li>"class" means Java programming language class.</li>
 901       <li>"heap" means Java virtual machine heap.</li>
 902       <li>"monitor" means Java programming language object monitor.</li>
 903     </ul>
 904     <p/>
 905     Sun, Sun Microsystems, the Sun logo, Java, and JVM
 906     are trademarks or registered trademarks of Oracle
 907     and/or its affiliates, in the U.S. and other countries.
 908   </intro>
 909 
 910 
 911 <functionsection label="Functions">
 912   <intro id="jvmtiEnvAccess" label="Accessing Functions">
 913     Native code accesses <jvmti/> features
 914     by calling <jvmti/> functions.
 915     Access to <jvmti/> functions is by use of an interface pointer
 916     in the same manner as
 917     <externallink id="jni/design.html">Java
 918       Native Interface (JNI) functions</externallink> are accessed.
 919     The <jvmti/> interface pointer is called the
 920     <i>environment pointer</i>.
 921     <p/>
 922     An environment pointer is a pointer to an environment and has
 923     the type <code>jvmtiEnv*</code>.
 924     An environment has information about its <jvmti/> connection.
 925     The first value in the environment is a pointer to the function table.
 926     The function table is an array of pointers to <jvmti/> functions.
 927     Every function pointer is at a predefined offset inside the
 928     array.
 929     <p/>
 930     When used from the C language:
 931     double indirection is used to access the functions;
 932     the environment pointer provides context and is the first
 933     parameter of each function call; for example:
 934     <example>
 935 jvmtiEnv *jvmti;
 936 ...
 937 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);
 938     </example>
 939     <p/>
 940     When used from the C++ language:
 941     functions are accessed as member functions of <code>jvmtiEnv</code>;
 942     the environment pointer is not passed to the function call; for example:
 943     <example>
 944 jvmtiEnv *jvmti;
 945 ...
 946 jvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);
 947     </example>
 948     Unless otherwise stated, all examples and declarations in this
 949     specification use the C language.
 950     <p/>
 951     A <jvmti/> environment can be obtained through the JNI Invocation API
 952     <code>GetEnv</code> function:
 953     <example>
 954 jvmtiEnv *jvmti;
 955 ...
 956 (*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);
 957     </example>
 958     Each call to <code>GetEnv</code>
 959     creates a new <jvmti/> connection and thus
 960     a new <jvmti/> environment.
 961     The <code>version</code> argument of <code>GetEnv</code> must be
 962     a <jvmti/> version.
 963     The returned environment may have a different version than the
 964     requested version but the returned environment must be compatible.
 965     <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a
 966     compatible version is not available, if <jvmti/> is not supported or
 967     <jvmti/> is not supported in the current VM configuration.
 968     Other interfaces may be added for creating <jvmti/> environments
 969     in specific contexts.
 970     Each environment has its own state (for example,
 971     <functionlink id="SetEventNotificationMode">desired events</functionlink>,
 972     <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and
 973     <functionlink id="AddCapabilities">capabilities</functionlink>).
 974     An environment is released with
 975     <functionlink id="DisposeEnvironment"></functionlink>.
 976     Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
 977     across threads and are created dynamically.
 978   </intro>
 979 
 980   <intro id="functionReturn" label="Function Return Values">
 981     <jvmti/> functions always return an
 982     <internallink id="ErrorSection">error code</internallink> via the
 983     <datalink id="jvmtiError"/> function return value.
 984     Some functions can return additional
 985     values through pointers provided by the calling function.
 986     In some cases, <jvmti/> functions allocate memory that your program must
 987     explicitly deallocate. This is indicated in the individual <jvmti/>
 988     function descriptions.  Empty lists, arrays, sequences, etc are
 989     returned as <code>NULL</code>.
 990     <p/>
 991     In the event that the <jvmti/> function encounters
 992     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
 993     of memory referenced by argument pointers is undefined, but no memory
 994     will have been allocated and no global references will have been allocated.
 995     If the error occurs because of invalid input, no action will have occurred.
 996   </intro>
 997 
 998 <intro id="refs" label="Managing JNI Object References">
 999     <jvmti/> functions identify objects with JNI references
1000     (<datalink id="jobject"/> and <datalink id="jclass"/>)
1001     and their derivatives
1002     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
1003     References passed to
1004     <jvmti/> functions can be either global or local, but they must be
1005     strong references. All references returned by <jvmti/> functions are
1006     local references--these local references are created
1007     during the <jvmti/> call.
1008     Local references are a resource that must be managed (see the
1009     <externallink id="jni/functions.html#local-references">
1010       JNI Documentation</externallink>).
1011     When threads return from native code all local references
1012     are freed.  Note that some threads, including typical
1013     agent threads, will never return from native code.
1014     A thread is ensured the ability to create sixteen local
1015     references without the need for any explicit management.
1016     For threads executing a limited number of <jvmti/> calls before
1017     returning from native code
1018     (for example, threads processing events),
1019     it may be determined that no explicit management
1020     is needed.
1021     However, long running agent threads will need explicit
1022     local reference management--usually with the JNI functions
1023     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
1024     Conversely, to preserve references beyond the
1025     return from native code, they must be converted to global references.
1026     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/>
1027     as they are not <datalink id="jobject"/>s.
1028 </intro>
1029 
1030     <intro id="prereqState" label="Prerequisite State for Calling Functions">
1031       Unless the function explicitly states that the agent must bring
1032       a thread or the VM to a particular state (for example, suspended),
1033       the <jvmti/> implementation is responsible for bringing the VM to a
1034       safe and consistent state for performing the function.
1035     </intro>
1036 
1037     <intro id="functionsExceptions" label="Exceptions and Functions">
1038       <jvmti/> functions never throw exceptions; error conditions are
1039       communicated via the
1040       <internallink id="functionReturn">function return value</internallink>.
1041       Any existing exception state is preserved across a call to a
1042       <jvmti/> function.
1043       See the
1044       <externallink
1045         id="jni/design.html#java-exceptions"
1046              >Java Exceptions</externallink>
1047       section of the JNI specification for information on handling exceptions.
1048     </intro>
1049 
1050   <category id="memory" label="Memory Management">
1051     <intro>
1052       These functions provide for the allocation and deallocation of
1053       memory used by <jvmti/> functionality and can be used to provide
1054       working memory for agents.
1055       Memory managed by <jvmti/> is not compatible with other memory
1056       allocation libraries and mechanisms.
1057     </intro>
1058 
1059     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
1060       <synopsis>Allocate</synopsis>
1061       <description>
1062         Allocate an area of memory through the <jvmti/> allocator.
1063         The allocated
1064         memory should be freed with <functionlink id="Deallocate"></functionlink>.
1065       </description>
1066       <origin>jvmdi</origin>
1067       <capabilities>
1068       </capabilities>
1069       <parameters>
1070         <param id="size">
1071           <jlong/>
1072           <description>
1073             The number of bytes to allocate.
1074             <rationale>
1075               <code>jlong</code> is used for compatibility with JVMDI.
1076             </rationale>
1077           </description>
1078         </param>
1079         <param id="mem_ptr">
1080           <allocbuf incount="size"><uchar/></allocbuf>
1081           <description>
1082             On return, a pointer to the beginning of the allocated memory.
1083             If <code>size</code> is zero, <code>NULL</code> is returned.
1084           </description>
1085         </param>
1086       </parameters>
1087       <errors>
1088         <error id="JVMTI_ERROR_OUT_OF_MEMORY">
1089           Memory request cannot be honored.
1090         </error>
1091         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
1092           <paramlink id="size"></paramlink> is less than zero.
1093         </error>
1094       </errors>
1095     </function>
1096 
1097     <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
1098       <synopsis>Deallocate</synopsis>
1099       <description>
1100         Deallocate <code>mem</code>  using the <jvmti/> allocator.
1101         This function should
1102         be used to deallocate any memory allocated and returned
1103         by a <jvmti/> function
1104         (including memory allocated with <functionlink id="Allocate"></functionlink>).
1105         All allocated memory must be deallocated
1106         or the memory cannot be reclaimed.
1107       </description>
1108       <origin>jvmdi</origin>
1109       <capabilities>
1110       </capabilities>
1111       <parameters>
1112         <param id="mem">
1113           <outbuf>
1114             <uchar/>
1115             <nullok>the call is ignored</nullok>
1116           </outbuf>
1117           <description>
1118             A pointer to the beginning of the allocated memory.
1119             Please ignore "On return, the elements are set."
1120               <todo>keep it from generating "On return, the elements are set"</todo>
1121           </description>
1122         </param>
1123       </parameters>
1124       <errors>
1125       </errors>
1126     </function>
1127   </category>
1128 
1129   <category id="threadCategory" label="Thread">
1130     <intro>
1131     </intro>
1132 
1133     <function id="GetThreadState" num="17">
1134       <synopsis>Get Thread State</synopsis>
1135       <description>
1136         Get the state of a thread.  The state of the thread is represented by the
1137         answers to the hierarchical set of questions below:
1138           <ul type="circle">
1139             <li><i>Alive?</i>
1140               <ul>
1141                 <li>Not alive.
1142                   <ul type="circle">
1143                     <li><i>Why not alive?</i>
1144                       <ul>
1145                         <li>New.</li>
1146                         <li>Terminated (<datalink
1147                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
1148                       </ul>
1149                     </li>
1150                   </ul>
1151                 </li>
1152                 <li>Alive (<datalink
1153                     id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
1154                   <ul type="circle">
1155                     <li><i>Suspended?</i>
1156                       <ul>
1157                         <li>Suspended (<datalink
1158                             id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
1159                         <li>Not suspended</li>
1160                       </ul>
1161                     </li>
1162                     <li><i>Interrupted?</i>
1163                       <ul>
1164                         <li>Interrupted (<datalink
1165                             id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
1166                         <li>Not interrupted.</li>
1167                       </ul>
1168                     </li>
1169                     <li><i>In native?</i>
1170                       <ul>
1171                         <li>In native code (<datalink
1172                             id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
1173                         <li>In Java programming language code</li>
1174                       </ul>
1175                     </li>
1176                     <li><i>What alive state?</i>
1177                       <ul>
1178                         <li>Runnable (<datalink
1179                             id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
1180                         <li>Blocked (<datalink
1181                             id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
1182                         <li>Waiting (<datalink
1183                             id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
1184                           <ul type="circle">
1185                             <li><i>Timed wait?</i>
1186                               <ul>
1187                                 <li>Indefinite (<datalink
1188                                     id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
1189                                 <li>Timed (<datalink
1190                                     id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
1191                               </ul>
1192                             </li>
1193                             <li><i>Why waiting?</i>
1194                               <ul>
1195                                 <li>Object.wait (<datalink
1196                                     id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
1197                                 <li>LockSupport.park (<datalink
1198                                     id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
1199                                 <li>Sleeping (<datalink
1200                                     id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
1201                               </ul>
1202                             </li>
1203                           </ul>
1204                         </li>
1205                       </ul>
1206                     </li>
1207                   </ul>
1208                 </li>
1209               </ul>
1210             </li>
1211           </ul>
1212         <p/>
1213         The answers are represented by the following bit vector.
1214         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
1215           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
1216             Thread is alive. Zero if thread is new (not started) or terminated.
1217           </constant>
1218           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
1219             Thread has completed execution.
1220           </constant>
1221           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
1222             Thread is runnable.
1223           </constant>
1224           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
1225             Thread is waiting to enter a synchronization block/method or,
1226             after an <code>Object.wait()</code>, waiting to re-enter a
1227             synchronization block/method.
1228           </constant>
1229           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
1230             Thread is waiting.
1231           </constant>
1232           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
1233             Thread is waiting without a timeout.
1234             For example, <code>Object.wait()</code>.
1235           </constant>
1236           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
1237             Thread is waiting with a maximum time to wait specified.
1238             For example, <code>Object.wait(long)</code>.
1239           </constant>
1240           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
1241             Thread is sleeping -- <code>Thread.sleep(long)</code>.
1242           </constant>
1243           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
1244             Thread is waiting on an object monitor -- <code>Object.wait</code>.
1245           </constant>
1246           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
1247             Thread is parked, for example: <code>LockSupport.park</code>,
1248             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
1249           </constant>
1250           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
1251             Thread suspended.
1252             <code>java.lang.Thread.suspend()</code>
1253             or a <jvmti/> suspend function
1254             (such as <functionlink id="SuspendThread"></functionlink>)
1255             has been called on the thread. If this bit
1256             is set, the other bits refer to the thread state before suspension.
1257           </constant>
1258           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
1259             Thread has been interrupted.
1260           </constant>
1261           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
1262             Thread is in native code--that is, a native method is running
1263             which has not called back into the VM or Java programming
1264             language code.
1265             <p/>
1266             This flag is not set when running VM compiled Java programming
1267             language code nor is it set when running VM code or
1268             VM support code. Native VM interface functions, such as JNI and
1269             <jvmti/> functions, may be implemented as VM code.
1270           </constant>
1271           <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
1272             Defined by VM vendor.
1273           </constant>
1274           <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
1275             Defined by VM vendor.
1276           </constant>
1277           <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
1278             Defined by VM vendor.
1279           </constant>
1280         </constants>
1281         The following definitions are used to convert <jvmti/> thread state
1282         to <code>java.lang.Thread.State</code> style states.
1283         <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
1284           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
1285                      num="JVMTI_THREAD_STATE_TERMINATED | JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1286             Mask the state with this before comparison
1287           </constant>
1288           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
1289                      num="0">
1290             <code>java.lang.Thread.State.NEW</code>
1291           </constant>
1292           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
1293                      num="JVMTI_THREAD_STATE_TERMINATED">
1294             <code>java.lang.Thread.State.TERMINATED</code>
1295           </constant>
1296           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
1297                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
1298             <code>java.lang.Thread.State.RUNNABLE</code>
1299           </constant>
1300           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
1301                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
1302             <code>java.lang.Thread.State.BLOCKED</code>
1303           </constant>
1304           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
1305                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
1306             <code>java.lang.Thread.State.WAITING</code>
1307           </constant>
1308           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
1309                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1310             <code>java.lang.Thread.State.TIMED_WAITING</code>
1311           </constant>
1312         </constants>
1313         <b>Rules</b>
1314         <p/>
1315         There can be no more than one answer to a question, although there can be no
1316         answer (because the answer is unknown, does not apply, or none of the answers is
1317         correct).  An answer is set only when the enclosing answers match.
1318         That is, no more than one of
1319           <ul type="circle">
1320               <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
1321               <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
1322               <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
1323           </ul>
1324         can be set (a <tm>J2SE</tm> compliant implementation will always set
1325         one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set).
1326         And if any of these are set, the enclosing answer
1327         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1328         No more than one of
1329           <ul type="circle">
1330               <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
1331               <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
1332           </ul>
1333         can be set (a <tm>J2SE</tm> compliant implementation will always set
1334         one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set).
1335         And if either is set, the enclosing answers
1336         <code>JVMTI_THREAD_STATE_ALIVE</code> and
1337         <code>JVMTI_THREAD_STATE_WAITING</code> are set.
1338         No more than one of
1339           <ul type="circle">
1340               <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
1341               <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
1342               <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
1343           </ul>
1344         can be set. And if any of these is set, the enclosing answers
1345         <code>JVMTI_THREAD_STATE_ALIVE</code> and
1346         <code>JVMTI_THREAD_STATE_WAITING</code> are set.
1347         Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
1348         then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
1349         If a state <i>A</i> is implemented using the mechanism of
1350         state <i>B</i> then it is state <i>A</i> which
1351         is returned by this function.
1352         For example, if <code>Thread.sleep(long)</code>
1353         is implemented using <code>Object.wait(long)</code>
1354         then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
1355         which is returned.
1356         More than one of
1357           <ul type="circle">
1358               <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
1359               <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
1360               <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
1361           </ul>
1362         can be set, but if any is set,
1363         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1364         <p/>
1365         And finally,
1366         <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
1367         <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.
1368         <p/>
1369         The thread state representation is designed for extension in future versions
1370         of the specification; thread state values should be used accordingly, that is
1371         they should not be used as ordinals.
1372         Most queries can be made by testing a single bit, if use in a switch statement is desired,
1373         the state bits should be masked with the interesting bits.
1374         All bits not defined above are reserved for future use.
1375         A VM, compliant to the current specification, must set reserved bits to zero.
1376         An agent should ignore reserved bits --
1377         they should not be assumed to be zero and thus should not be included in comparisons.
1378         <p/>
1379         <b>Examples</b>
1380         <p/>
1381         Note that the values below exclude reserved and vendor bits.
1382         <p/>
1383         The state of a thread blocked at a <code>synchronized</code>-statement would be:
1384         <example>
1385             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
1386         </example>
1387         The state of a thread which hasn't started yet would be:
1388         <example>
1389             0
1390         </example>
1391         The state of a thread at a <code>Object.wait(3000)</code> would be:
1392         <example>
1393             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING +
1394                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT +
1395                 JVMTI_THREAD_STATE_MONITOR_WAITING
1396         </example>
1397         The state of a thread suspended while runnable would be:
1398         <example>
1399             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
1400         </example>
1401         <p/>
1402         <b>Testing the State</b>
1403         <p/>
1404         In most cases, the thread state can be determined by testing the one bit corresponding
1405         to that question.  For example, the code to test if a thread is sleeping:
1406         <example>
1407         jint state;
1408         jvmtiError err;
1409 
1410         err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1411         if (err == JVMTI_ERROR_NONE) {
1412            if (state &amp; JVMTI_THREAD_STATE_SLEEPING) {  ...
1413         </example>
1414         <p/>
1415         For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
1416         <example>
1417            if (state &amp; JVMTI_THREAD_STATE_WAITING) {  ...
1418         </example>
1419         For some states, more than one bit will need to be tested as is the case
1420         when testing if a thread has not yet been started:
1421         <example>
1422            if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
1423         </example>
1424         To distinguish timed from untimed <code>Object.wait</code>:
1425         <example>
1426            if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {
1427              if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
1428                printf("in Object.wait(long timeout)\n");
1429              } else {
1430                printf("in Object.wait()\n");
1431              }
1432            }
1433         </example>
1434         <p/>
1435         <b>Relationship to <code>java.lang.Thread.State</code></b>
1436         <p/>
1437         The thread state represented by <code>java.lang.Thread.State</code>
1438         returned from <code>java.lang.Thread.getState()</code> is a subset of the
1439         information returned from this function.
1440         The corresponding <code>java.lang.Thread.State</code> can be determined
1441         by using the provided conversion masks.
1442         For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
1443         <example>
1444             err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1445             abortOnError(err);
1446             switch (state &amp; JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
1447             case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
1448               return "NEW";
1449             case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
1450               return "TERMINATED";
1451             case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
1452               return "RUNNABLE";
1453             case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
1454               return "BLOCKED";
1455             case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
1456               return "WAITING";
1457             case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
1458               return "TIMED_WAITING";
1459             }
1460         </example>
1461       </description>
1462       <origin>new</origin>
1463       <capabilities>
1464       </capabilities>
1465       <parameters>
1466         <param id="thread">
1467           <jthread null="current" started="maybe" impl="noconvert"/>
1468             <description>
1469               The thread to query.
1470             </description>
1471         </param>
1472         <param id="thread_state_ptr">
1473           <outptr><jint/></outptr>
1474           <description>
1475             On return, points to state flags,
1476             as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
1477           </description>
1478         </param>
1479       </parameters>
1480       <errors>
1481       </errors>
1482     </function>
1483 
1484     <function id="GetCurrentThread" phase="start" num="18" since="1.1">
1485       <synopsis>Get Current Thread</synopsis>
1486       <description>
1487         Get the current thread.
1488         The current thread is the Java programming language thread which has called the function.
1489         The function may return <code>NULL</code> in the start phase if the
1490         <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
1491         <code>can_generate_early_vmstart</code></internallink> capability is enabled
1492         and the <code>java.lang.Thread</code> class has not been initialized yet.
1493         <p/>
1494         Note that most <jvmti/> functions that take a thread
1495         as an argument will accept <code>NULL</code> to mean
1496         the current thread.
1497       </description>
1498       <origin>new</origin>
1499       <capabilities>
1500       </capabilities>
1501       <parameters>
1502         <param id="thread_ptr">
1503           <outptr><jthread/></outptr>
1504           <description>
1505              On return, points to the current thread, or <code>NULL</code>.
1506           </description>
1507         </param>
1508       </parameters>
1509       <errors>
1510       </errors>
1511     </function>
1512 
1513     <function id="GetAllThreads" num="4">
1514       <synopsis>Get All Threads</synopsis>
1515       <description>
1516         Get all live threads.
1517         The threads are Java programming language threads;
1518         that is, threads that are attached to the VM.
1519         A thread is live if <code>java.lang.Thread.isAlive()</code>
1520         would return <code>true</code>, that is, the thread has
1521         been started and has not yet died.
1522         The universe of threads is determined by the context of the <jvmti/>
1523         environment, which typically is all threads attached to the VM.
1524         Note that this includes <jvmti/> agent threads
1525         (see <functionlink id="RunAgentThread"/>).
1526       </description>
1527       <origin>jvmdi</origin>
1528       <capabilities>
1529       </capabilities>
1530       <parameters>
1531         <param id="threads_count_ptr">
1532           <outptr><jint/></outptr>
1533           <description>
1534             On return, points to the number of running threads.
1535           </description>
1536         </param>
1537         <param id="threads_ptr">
1538           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
1539             <description>
1540               On return, points to an array of references, one
1541               for each running thread.
1542             </description>
1543         </param>
1544       </parameters>
1545       <errors>
1546       </errors>
1547     </function>
1548 
1549     <function id="SuspendThread" num="5">
1550       <synopsis>Suspend Thread</synopsis>
1551       <description>
1552         Suspend the specified thread. If the calling thread is specified,
1553         this function will not return until some other thread calls
1554         <functionlink id="ResumeThread"></functionlink>.
1555         If the thread is currently suspended, this function
1556         does nothing and returns an error.
1557       </description>
1558       <origin>jvmdi</origin>
1559       <capabilities>
1560         <required id="can_suspend"></required>
1561       </capabilities>
1562       <parameters>
1563         <param id="thread">
1564           <jthread null="current"/>
1565             <description>
1566               The thread to suspend.
1567             </description>
1568         </param>
1569       </parameters>
1570       <errors>
1571         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
1572           Thread already suspended.
1573         </error>
1574       </errors>
1575     </function>
1576 
1577     <elide>
1578     <function id="SuspendAllThreads" num="101">
1579       <synopsis>Suspend All Threads</synopsis>
1580       <description>
1581         <issue>
1582             There has been no explicit call for this function, and it will
1583             thus be removed if there is no interest.
1584         </issue>
1585         Suspend all live threads except:
1586         <ul>
1587           <li>already suspended threads</li>
1588           <li>those listed in <paramlink id="except_list"></paramlink></li>
1589           <li>certain system (non application) threads, as determined
1590             by the VM implementation</li>
1591         </ul>
1592         The threads are Java programming language threads;
1593         native threads which are not attached to the VM are not
1594         Java programming language threads.
1595         A thread is live if <code>java.lang.Thread.isAlive()</code>
1596         would return <code>true</code>, that is, the thread has
1597         been started and has not yet died.
1598         The universe of threads is determined
1599         by the context of the <jvmti/>
1600         environment, which, typically, is all threads attached to the VM,
1601         except critical VM internal threads and <jvmti/> agent threads
1602         (see <functionlink id="RunAgentThread"/>).
1603         <p/>
1604         If the calling thread is specified,
1605         all other threads are suspended first then the caller thread is suspended -
1606         this function will not return until some other thread calls
1607         <functionlink id="ResumeThread"></functionlink>.
1608         <p/>
1609         The list of actually
1610         suspended threads is returned in
1611         <paramlink id="suspended_list_ptr"></paramlink>.
1612         Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
1613         <functionlink id="ResumeThreadList"></functionlink>
1614         can be used to resume the suspended threads.
1615       </description>
1616       <origin>new</origin>
1617       <capabilities>
1618         <required id="can_suspend"></required>
1619       </capabilities>
1620       <parameters>
1621         <param id="except_count">
1622           <jint min="0"/>
1623           <description>
1624             The number of threads in the list of threads not to be suspended.
1625           </description>
1626         </param>
1627         <param id="except_list">
1628             <inbuf incount="except_count">
1629               <jthread/>
1630               <nullok>not an error if <code>except_count == 0</code></nullok>
1631             </inbuf>
1632             <description>
1633               The list of threads not to be suspended.
1634             </description>
1635         </param>
1636         <param id="suspended_count_ptr">
1637           <outptr><jint/></outptr>
1638           <description>
1639             On return, points to the number of threads suspended by this call.
1640           </description>
1641         </param>
1642         <param id="suspended_list_ptr">
1643           <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
1644             <description>
1645               On return, points to an array of references, one
1646               for each thread suspended.
1647             </description>
1648         </param>
1649       </parameters>
1650       <errors>
1651         <error id="JVMTI_ERROR_INVALID_THREAD">
1652           A thread in <paramlink id="except_list"></paramlink> was invalid.
1653         </error>
1654         <error id="JVMTI_ERROR_NULL_POINTER">
1655           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1656           and <paramlink id="except_count"></paramlink> was non-zero.
1657         </error>
1658       </errors>
1659     </function>
1660     </elide>
1661 
1662     <function id="SuspendThreadList" num="92">
1663       <synopsis>Suspend Thread List</synopsis>
1664       <description>
1665         Suspend the <paramlink id="request_count"></paramlink>
1666         threads specified in the
1667         <paramlink id="request_list"></paramlink> array.
1668         Threads may be resumed with
1669         <functionlink id="ResumeThreadList"></functionlink> or
1670         <functionlink id="ResumeThread"></functionlink>.
1671         If the calling thread is specified in the
1672         <paramlink id="request_list"></paramlink> array, this function will
1673         not return until some other thread resumes it.
1674         Errors encountered in the suspension of a thread
1675         are returned in the <paramlink id="results"></paramlink>
1676         array, <b>not</b> in the return value of this function.
1677         Threads that are currently suspended do not change state.
1678       </description>
1679       <origin>jvmdi</origin>
1680       <capabilities>
1681         <required id="can_suspend"></required>
1682       </capabilities>
1683       <parameters>
1684         <param id="request_count">
1685           <jint min="0"/>
1686           <description>
1687             The number of threads to suspend.
1688           </description>
1689         </param>
1690         <param id="request_list">
1691           <inbuf incount="request_count"><jthread/></inbuf>
1692             <description>
1693               The list of threads to suspend.
1694             </description>
1695         </param>
1696         <param id="results">
1697           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1698           <description>
1699             An agent supplied array of
1700             <paramlink id="request_count"></paramlink> elements.
1701             On return, filled with the error code for
1702             the suspend of the corresponding thread.
1703             The error code will be
1704             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1705             if the thread was suspended by this call.
1706             Possible error codes are those specified
1707             for <functionlink id="SuspendThread"></functionlink>.
1708           </description>
1709         </param>
1710       </parameters>
1711       <errors>
1712       </errors>
1713     </function>
1714 
1715     <function id="ResumeThread" num="6">
1716       <synopsis>Resume Thread</synopsis>
1717       <description>
1718         Resume a suspended thread.
1719         Any threads currently suspended through
1720         a <jvmti/> suspend function (eg.
1721         <functionlink id="SuspendThread"></functionlink>)
1722         or <code>java.lang.Thread.suspend()</code>
1723         will resume execution;
1724         all other threads are unaffected.
1725       </description>
1726       <origin>jvmdi</origin>
1727       <capabilities>
1728         <required id="can_suspend"></required>
1729       </capabilities>
1730       <parameters>
1731         <param id="thread">
1732           <jthread/>
1733             <description>
1734               The thread to resume.
1735             </description>
1736         </param>
1737       </parameters>
1738       <errors>
1739         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
1740           Thread was not suspended.
1741         </error>
1742         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
1743           The state of the thread has been modified, and is now inconsistent.
1744         </error>
1745       </errors>
1746     </function>
1747 
1748     <function id="ResumeThreadList" num="93">
1749       <synopsis>Resume Thread List</synopsis>
1750       <description>
1751         Resume the <paramlink id="request_count"></paramlink>
1752         threads specified in the
1753         <paramlink id="request_list"></paramlink> array.
1754         Any thread suspended through
1755         a <jvmti/> suspend function (eg.
1756         <functionlink id="SuspendThreadList"></functionlink>)
1757         or <code>java.lang.Thread.suspend()</code>
1758         will resume execution.
1759       </description>
1760       <origin>jvmdi</origin>
1761       <capabilities>
1762         <required id="can_suspend"></required>
1763       </capabilities>
1764       <parameters>
1765         <param id="request_count">
1766           <jint min="0"/>
1767           <description>
1768             The number of threads to resume.
1769           </description>
1770         </param>
1771         <param id="request_list">
1772           <inbuf incount="request_count"><jthread/></inbuf>
1773             <description>
1774               The threads to resume.
1775             </description>
1776         </param>
1777         <param id="results">
1778           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1779           <description>
1780             An agent supplied array of
1781             <paramlink id="request_count"></paramlink> elements.
1782             On return, filled with the error code for
1783             the resume of the corresponding thread.
1784             The error code will be
1785             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1786             if the thread was suspended by this call.
1787             Possible error codes are those specified
1788             for <functionlink id="ResumeThread"></functionlink>.
1789           </description>
1790         </param>
1791       </parameters>
1792       <errors>
1793       </errors>
1794     </function>
1795 
1796     <function id="StopThread" num="7">
1797       <synopsis>Stop Thread</synopsis>
1798       <description>
1799         Send the specified asynchronous exception to the specified thread
1800         (similar to <code>java.lang.Thread.stop</code>).
1801         Normally, this function is used to kill the specified thread with an
1802         instance of the exception <code>ThreadDeath</code>.
1803       </description>
1804       <origin>jvmdi</origin>
1805       <capabilities>
1806         <required id="can_signal_thread"></required>
1807       </capabilities>
1808       <parameters>
1809         <param id="thread">
1810           <jthread/>
1811             <description>
1812               The thread to stop.
1813             </description>
1814         </param>
1815         <param id="exception">
1816           <jobject/>
1817             <description>
1818               The asynchronous exception object.
1819             </description>
1820         </param>
1821       </parameters>
1822       <errors>
1823       </errors>
1824     </function>
1825 
1826     <function id="InterruptThread" num="8">
1827       <synopsis>Interrupt Thread</synopsis>
1828       <description>
1829         Interrupt the specified thread
1830         (similar to <code>java.lang.Thread.interrupt</code>).
1831       </description>
1832       <origin>jvmdi</origin>
1833       <capabilities>
1834         <required id="can_signal_thread"></required>
1835       </capabilities>
1836       <parameters>
1837         <param id="thread">
1838           <jthread impl="noconvert"/>
1839             <description>
1840               The thread to interrupt.
1841             </description>
1842         </param>
1843       </parameters>
1844       <errors>
1845       </errors>
1846     </function>
1847 
1848     <function id="GetThreadInfo" num="9">
1849       <synopsis>Get Thread Info</synopsis>
1850       <typedef id="jvmtiThreadInfo" label="Thread information structure">
1851         <field id="name">
1852           <allocfieldbuf><char/></allocfieldbuf>
1853           <description>
1854             The thread name, encoded as a
1855             <internallink id="mUTF">modified UTF-8</internallink> string.
1856           </description>
1857         </field>
1858         <field id="priority">
1859           <jint/>
1860           <description>
1861             The thread priority.  See the thread priority constants:
1862             <datalink id="jvmtiThreadPriority"></datalink>.
1863           </description>
1864         </field>
1865         <field id="is_daemon">
1866           <jboolean/>
1867           <description>
1868             Is this a daemon thread?
1869           </description>
1870         </field>
1871         <field id="thread_group">
1872           <jthreadGroup/>
1873           <description>
1874             The thread group to which this thread belongs.
1875             <code>NULL</code> if the thread has died.
1876           </description>
1877         </field>
1878         <field id="context_class_loader">
1879           <jobject/>
1880             <description>
1881               The context class loader associated with this thread.
1882             </description>
1883         </field>
1884       </typedef>
1885       <description>
1886         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure
1887         are filled in with details of the specified thread.
1888       </description>
1889       <origin>jvmdi</origin>
1890       <capabilities>
1891       </capabilities>
1892       <parameters>
1893         <param id="thread">
1894           <jthread null="current" impl="noconvert" started="maybe"/>
1895             <description>
1896               The thread to query.
1897             </description>
1898         </param>
1899         <param id="info_ptr">
1900           <outptr><struct>jvmtiThreadInfo</struct></outptr>
1901           <description>
1902             On return, filled with information describing the specified thread.
1903           </description>
1904         </param>
1905       </parameters>
1906       <errors>
1907       </errors>
1908     </function>
1909 
1910     <function id="GetOwnedMonitorInfo" num="10">
1911       <synopsis>Get Owned Monitor Info</synopsis>
1912       <description>
1913         Get information about the monitors owned by the
1914         specified thread.
1915       </description>
1916       <origin>jvmdiClone</origin>
1917       <capabilities>
1918         <required id="can_get_owned_monitor_info"></required>
1919       </capabilities>
1920       <parameters>
1921         <param id="thread">
1922           <jthread null="current"/>
1923             <description>
1924               The thread to query.
1925             </description>
1926         </param>
1927         <param id="owned_monitor_count_ptr">
1928           <outptr><jint/></outptr>
1929           <description>
1930             The number of monitors returned.
1931           </description>
1932         </param>
1933         <param id="owned_monitors_ptr">
1934           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
1935             <description>
1936               The array of owned monitors.
1937             </description>
1938         </param>
1939       </parameters>
1940       <errors>
1941       </errors>
1942     </function>
1943 
1944     <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
1945       <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
1946       <typedef id="jvmtiMonitorStackDepthInfo"
1947                label="Monitor stack depth information structure">
1948         <field id="monitor">
1949           <jobject/>
1950             <description>
1951               The owned monitor.
1952             </description>
1953         </field>
1954         <field id="stack_depth">
1955           <jint/>
1956           <description>
1957             The stack depth.  Corresponds to the stack depth used in the
1958             <internallink id="stack">Stack Frame functions</internallink>.
1959             That is, zero is the current frame, one is the frame which
1960             called the current frame. And it is negative one if the
1961             implementation cannot determine the stack depth (e.g., for
1962             monitors acquired by JNI <code>MonitorEnter</code>).
1963           </description>
1964         </field>
1965       </typedef>
1966       <description>
1967         Get information about the monitors owned by the
1968         specified thread and the depth of the stack frame which locked them.
1969       </description>
1970       <origin>new</origin>
1971       <capabilities>
1972         <required id="can_get_owned_monitor_stack_depth_info"></required>
1973       </capabilities>
1974       <parameters>
1975         <param id="thread">
1976           <jthread null="current"/>
1977             <description>
1978               The thread to query.
1979             </description>
1980         </param>
1981         <param id="monitor_info_count_ptr">
1982           <outptr><jint/></outptr>
1983           <description>
1984             The number of monitors returned.
1985           </description>
1986         </param>
1987         <param id="monitor_info_ptr">
1988           <allocbuf outcount="monitor_info_count_ptr">
1989             <struct>jvmtiMonitorStackDepthInfo</struct>
1990           </allocbuf>
1991           <description>
1992             The array of owned monitor depth information.
1993           </description>
1994         </param>
1995       </parameters>
1996       <errors>
1997       </errors>
1998     </function>
1999 
2000     <function id="GetCurrentContendedMonitor" num="11">
2001       <synopsis>Get Current Contended Monitor</synopsis>
2002       <description>
2003         Get the object, if any, whose monitor the specified thread is waiting to
2004         enter or waiting to regain through <code>java.lang.Object.wait</code>.
2005       </description>
2006       <origin>jvmdi</origin>
2007       <capabilities>
2008         <required id="can_get_current_contended_monitor"></required>
2009       </capabilities>
2010       <parameters>
2011         <param id="thread">
2012           <jthread null="current"/>
2013             <description>
2014               The thread to query.
2015             </description>
2016         </param>
2017         <param id="monitor_ptr">
2018           <outptr><jobject/></outptr>
2019             <description>
2020               On return, filled with the current contended monitor, or
2021               NULL if there is none.
2022             </description>
2023         </param>
2024       </parameters>
2025       <errors>
2026       </errors>
2027     </function>
2028 
2029     <callback id="jvmtiStartFunction">
2030       <void/>
2031       <synopsis>Agent Start Function</synopsis>
2032       <description>
2033         Agent supplied callback function.
2034         This function is the entry point for an agent thread
2035         started with
2036         <functionlink id="RunAgentThread"></functionlink>.
2037       </description>
2038       <parameters>
2039           <param id="jvmti_env">
2040             <outptr>
2041               <struct>jvmtiEnv</struct>
2042             </outptr>
2043             <description>
2044               The <jvmti/> environment.
2045             </description>
2046           </param>
2047           <param id="jni_env">
2048             <outptr>
2049               <struct>JNIEnv</struct>
2050             </outptr>
2051             <description>
2052               The JNI environment.
2053             </description>
2054           </param>
2055           <param id="arg">
2056             <outptr>
2057               <void/>
2058             </outptr>
2059               <description>
2060                 The <code>arg</code> parameter passed to
2061                 <functionlink id="RunAgentThread"></functionlink>.
2062               </description>
2063           </param>
2064       </parameters>
2065     </callback>
2066 
2067     <function id="RunAgentThread" num="12">
2068       <synopsis>Run Agent Thread</synopsis>
2069       <description>
2070         Starts the execution of an agent thread. with the specified native function.
2071         The parameter <paramlink id="arg"></paramlink> is forwarded on to the
2072         <functionlink id="jvmtiStartFunction">start function</functionlink>
2073         (specified with <paramlink id="proc"></paramlink>) as its single argument.
2074         This function allows the creation of agent threads
2075         for handling communication with another process or for handling events
2076         without the need to load a special subclass of <code>java.lang.Thread</code> or
2077         implementer of <code>java.lang.Runnable</code>.
2078         Instead, the created thread can run entirely in native code.
2079         However, the created thread does require a newly created instance
2080         of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to
2081         which it will be associated.
2082         The thread object can be created with JNI calls.
2083         <p/>
2084         The following common thread priorities are provided for your convenience:
2085         <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
2086           <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
2087             Minimum possible thread priority
2088           </constant>
2089           <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
2090             Normal thread priority
2091           </constant>
2092           <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
2093             Maximum possible thread priority
2094           </constant>
2095         </constants>
2096         <p/>
2097         The new thread is started as a daemon thread with the specified
2098         <paramlink id="priority"></paramlink>.
2099         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2100         <p/>
2101         Since the thread has been started, the thread will be live when this function
2102         returns, unless the thread has died immediately.
2103         <p/>
2104         The thread group of the thread is ignored -- specifically, the thread is not
2105         added to the thread group and the thread is not seen on queries of the thread
2106         group at either the Java programming language or <jvmti/> levels.
2107         <p/>
2108         The thread is not visible to Java programming language queries but is
2109         included in <jvmti/> queries (for example,
2110         <functionlink id="GetAllThreads"/> and
2111         <functionlink id="GetAllStackTraces"/>).
2112         <p/>
2113         Upon execution of <code>proc</code>, the new thread will be attached to the
2114         VM -- see the JNI documentation on
2115         <externallink id="jni/invocation.html#attaching-to-the-vm"
2116                       >Attaching to the VM</externallink>.
2117       </description>
2118       <origin>jvmdiClone</origin>
2119       <capabilities>
2120       </capabilities>
2121       <parameters>
2122         <param id="thread">
2123           <jthread impl="noconvert" started="no"/>
2124             <description>
2125               The thread to run.
2126             </description>
2127         </param>
2128         <param id="proc">
2129           <ptrtype>
2130             <struct>jvmtiStartFunction</struct>
2131           </ptrtype>
2132           <description>
2133             The start function.
2134           </description>
2135         </param>
2136         <param id="arg">
2137           <inbuf>
2138             <void/>
2139             <nullok><code>NULL</code> is passed to the start function</nullok>
2140           </inbuf>
2141           <description>
2142             The argument to the start function.
2143           </description>
2144         </param>
2145         <param id="priority">
2146           <jint/>
2147           <description>
2148             The priority of the started thread. Any thread
2149             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
2150             those in <datalink id="jvmtiThreadPriority"></datalink>.
2151           </description>
2152         </param>
2153       </parameters>
2154       <errors>
2155         <error id="JVMTI_ERROR_INVALID_PRIORITY">
2156             <paramlink id="priority"/> is less than
2157             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
2158               or greater than
2159             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
2160         </error>
2161       </errors>
2162     </function>
2163 
2164     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
2165       <synopsis>Set Thread Local Storage</synopsis>
2166       <description>
2167         The VM stores a pointer value associated with each environment-thread
2168         pair. This pointer value is called <i>thread-local storage</i>.
2169         This value is <code>NULL</code> unless set with this function.
2170         Agents can allocate memory in which they store thread specific
2171         information. By setting thread-local storage it can then be
2172         accessed with
2173         <functionlink id="GetThreadLocalStorage"></functionlink>.
2174         <p/>
2175         This function is called by the agent to set the value of the <jvmti/>
2176         thread-local storage. <jvmti/> supplies to the agent a pointer-size
2177         thread-local storage that can be used to record per-thread
2178         information.
2179       </description>
2180       <origin>jvmpi</origin>
2181       <capabilities>
2182       </capabilities>
2183       <parameters>
2184         <param id="thread">
2185           <jthread null="current"/>
2186             <description>
2187               Store to this thread.
2188             </description>
2189         </param>
2190         <param id="data">
2191           <inbuf>
2192             <void/>
2193             <nullok>value is set to <code>NULL</code></nullok>
2194           </inbuf>
2195           <description>
2196             The value to be entered into the thread-local storage.
2197           </description>
2198         </param>
2199       </parameters>
2200       <errors>
2201       </errors>
2202     </function>
2203 
2204     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
2205       <synopsis>Get Thread Local Storage</synopsis>
2206       <description>
2207         Called by the agent to get the value of the <jvmti/> thread-local
2208         storage.
2209       </description>
2210       <origin>jvmpi</origin>
2211       <capabilities>
2212       </capabilities>
2213       <parameters>
2214         <param id="thread">
2215           <jthread null="current" impl="noconvert"/>
2216             <description>
2217               Retrieve from this thread.
2218             </description>
2219         </param>
2220         <param id="data_ptr">
2221           <agentbuf><void/></agentbuf>
2222           <description>
2223             Pointer through which the value of the thread local
2224             storage is returned.
2225             If thread-local storage has not been set with
2226             <functionlink id="SetThreadLocalStorage"></functionlink> the returned
2227             pointer is <code>NULL</code>.
2228           </description>
2229         </param>
2230       </parameters>
2231       <errors>
2232       </errors>
2233     </function>
2234 
2235   </category>
2236 
2237   <category id="thread_groups" label="Thread Group">
2238     <intro>
2239     </intro>
2240 
2241     <function id="GetTopThreadGroups" num="13">
2242       <synopsis>Get Top Thread Groups</synopsis>
2243       <description>
2244         Return all top-level (parentless) thread groups in the VM.
2245       </description>
2246       <origin>jvmdi</origin>
2247       <capabilities>
2248       </capabilities>
2249       <parameters>
2250         <param id="group_count_ptr">
2251           <outptr><jint/></outptr>
2252           <description>
2253             On return, points to the number of top-level thread groups.
2254           </description>
2255         </param>
2256         <param id="groups_ptr">
2257           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2258             <description>
2259               On return, refers to a pointer to the top-level thread group array.
2260             </description>
2261         </param>
2262       </parameters>
2263       <errors>
2264       </errors>
2265     </function>
2266 
2267     <function id="GetThreadGroupInfo" num="14">
2268       <synopsis>Get Thread Group Info</synopsis>
2269       <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
2270         <field id="parent">
2271           <jthreadGroup/>
2272           <description>
2273             The parent thread group.
2274           </description>
2275         </field>
2276         <field id="name">
2277           <allocfieldbuf><char/></allocfieldbuf>
2278           <description>
2279             The thread group's name, encoded as a
2280             <internallink id="mUTF">modified UTF-8</internallink> string.
2281           </description>
2282         </field>
2283         <field id="max_priority">
2284           <jint/>
2285           <description>
2286             The maximum priority for this thread group.
2287           </description>
2288         </field>
2289         <field id="is_daemon">
2290           <jboolean/>
2291           <description>
2292             Is this a daemon thread group?
2293           </description>
2294         </field>
2295       </typedef>
2296       <description>
2297         Get information about the thread group. The fields of the
2298         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure
2299         are filled in with details of the specified thread group.
2300       </description>
2301       <origin>jvmdi</origin>
2302       <capabilities>
2303       </capabilities>
2304       <parameters>
2305         <param id="group">
2306           <jthreadGroup/>
2307           <description>
2308             The thread group to query.
2309           </description>
2310         </param>
2311         <param id="info_ptr">
2312           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
2313           <description>
2314             On return, filled with information describing the specified
2315             thread group.
2316           </description>
2317         </param>
2318       </parameters>
2319       <errors>
2320       </errors>
2321     </function>
2322 
2323     <function id="GetThreadGroupChildren" num="15">
2324       <synopsis>Get Thread Group Children</synopsis>
2325       <description>
2326         Get the live threads and active subgroups in this thread group.
2327       </description>
2328       <origin>jvmdi</origin>
2329       <capabilities>
2330       </capabilities>
2331       <parameters>
2332         <param id="group">
2333           <jthreadGroup/>
2334           <description>
2335             The group to query.
2336           </description>
2337         </param>
2338         <param id="thread_count_ptr">
2339           <outptr><jint/></outptr>
2340           <description>
2341             On return, points to the number of live threads in this thread group.
2342           </description>
2343         </param>
2344         <param id="threads_ptr">
2345           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
2346             <description>
2347               On return, points to an array of the live threads in this thread group.
2348             </description>
2349         </param>
2350         <param id="group_count_ptr">
2351           <outptr><jint/></outptr>
2352           <description>
2353             On return, points to the number of active child thread groups
2354           </description>
2355         </param>
2356         <param id="groups_ptr">
2357           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2358             <description>
2359               On return, points to an array of the active child thread groups.
2360             </description>
2361         </param>
2362       </parameters>
2363       <errors>
2364       </errors>
2365     </function>
2366   </category>
2367 
2368   <category id="stack" label="Stack Frame">
2369     <intro>
2370         These functions provide information about the stack of a thread.
2371         Stack frames are referenced by depth.
2372         The frame at depth zero is the current frame.
2373         <p/>
2374         Stack frames are as described in
2375         <vmspec chapter="3.6"/>,
2376         That is, they correspond to method
2377         invocations (including native methods) but do not correspond to platform native or
2378         VM internal frames.
2379         <p/>
2380         A <jvmti/> implementation may use method invocations to launch a thread and
2381         the corresponding frames may be included in the stack as presented by these functions --
2382         that is, there may be frames shown
2383         deeper than <code>main()</code> and <code>run()</code>.
2384         However this presentation must be consistent across all <jvmti/> functionality which
2385         uses stack frames or stack depth.
2386     </intro>
2387 
2388       <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
2389         <description>
2390           Information about a stack frame is returned in this structure.
2391         </description>
2392         <field id="method">
2393           <jmethodID/>
2394             <description>
2395               The method executing in this frame.
2396             </description>
2397         </field>
2398         <field id="location">
2399           <jlocation/>
2400           <description>
2401             The index of the instruction executing in this frame.
2402             <code>-1</code> if the frame is executing a native method.
2403           </description>
2404         </field>
2405       </typedef>
2406 
2407       <typedef id="jvmtiStackInfo" label="Stack information structure">
2408         <description>
2409           Information about a set of stack frames is returned in this structure.
2410         </description>
2411         <field id="thread">
2412           <jthread/>
2413           <description>
2414             On return, the thread traced.
2415           </description>
2416         </field>
2417         <field id="state">
2418           <jint/>
2419           <description>
2420             On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
2421           </description>
2422         </field>
2423         <field id="frame_buffer">
2424           <outbuf incount="max_frame_count">
2425             <struct>jvmtiFrameInfo</struct>
2426           </outbuf>
2427             <description>
2428               On return, this agent allocated buffer is filled
2429               with stack frame information.
2430             </description>
2431         </field>
2432         <field id="frame_count">
2433           <jint/>
2434           <description>
2435             On return, the number of records filled into
2436             <code>frame_buffer</code>.
2437             This will be
2438             min(<code>max_frame_count</code>, <i>stackDepth</i>).
2439           </description>
2440         </field>
2441       </typedef>
2442 
2443     <function id="GetStackTrace" num="104">
2444       <synopsis>Get Stack Trace</synopsis>
2445       <description>
2446         Get information about the stack of a thread.
2447         If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
2448         the <paramlink id="max_frame_count"></paramlink> topmost frames are returned,
2449         otherwise the entire stack is returned.
2450         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2451         <p/>
2452         The following example causes up to five of the topmost frames
2453         to be returned and (if there are any frames) the currently
2454         executing method name to be printed.
2455         <example>
2456 jvmtiFrameInfo frames[5];
2457 jint count;
2458 jvmtiError err;
2459 
2460 err = (*jvmti)-&gt;GetStackTrace(jvmti, aThread, 0, 5,
2461                                frames, &amp;count);
2462 if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
2463    char *methodName;
2464    err = (*jvmti)-&gt;GetMethodName(jvmti, frames[0].method,
2465                        &amp;methodName, NULL, NULL);
2466    if (err == JVMTI_ERROR_NONE) {
2467       printf("Executing method: %s", methodName);
2468    }
2469 }
2470         </example>
2471         <todo>
2472           check example code.
2473         </todo>
2474         <p/>
2475         The <paramlink id="thread"></paramlink> need not be suspended
2476         to call this function.
2477         <p/>
2478         The <functionlink id="GetLineNumberTable"></functionlink>
2479         function can be used to map locations to line numbers. Note that
2480         this mapping can be done lazily.
2481       </description>
2482       <origin>jvmpi</origin>
2483       <capabilities>
2484       </capabilities>
2485       <parameters>
2486         <param id="thread">
2487           <jthread null="current"/>
2488             <description>
2489               Fetch the stack trace of this thread.
2490             </description>
2491         </param>
2492         <param id="start_depth">
2493           <jint/>
2494           <description>
2495             Begin retrieving frames at this depth.
2496             If non-negative, count from the current frame,
2497             the first frame retrieved is at depth <code>start_depth</code>.
2498             For example, if zero, start from the current frame; if one, start from the
2499             caller of the current frame; if two, start from the caller of the
2500             caller of the current frame; and so on.
2501             If negative, count from below the oldest frame,
2502             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,
2503             where <i>stackDepth</i> is the count of frames on the stack.
2504             For example, if negative one, only the oldest frame is retrieved;
2505             if negative two, start from the frame called by the oldest frame.
2506           </description>
2507         </param>
2508         <param id="max_frame_count">
2509           <jint min="0"/>
2510           <description>
2511             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2512           </description>
2513         </param>
2514         <param id="frame_buffer">
2515           <outbuf incount="max_frame_count" outcount="count_ptr">
2516             <struct>jvmtiFrameInfo</struct>
2517           </outbuf>
2518             <description>
2519               On return, this agent allocated buffer is filled
2520               with stack frame information.
2521             </description>
2522         </param>
2523         <param id="count_ptr">
2524           <outptr><jint/></outptr>
2525           <description>
2526             On return, points to the number of records filled in.
2527             For non-negative <code>start_depth</code>, this will be
2528             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
2529             For negative <code>start_depth</code>, this will be
2530             min(<code>max_frame_count</code>, <code>-start_depth</code>).
2531           </description>
2532         </param>
2533       </parameters>
2534       <errors>
2535         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
2536           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
2537           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
2538         </error>
2539       </errors>
2540     </function>
2541 
2542 
2543     <function id="GetAllStackTraces" num="100">
2544       <synopsis>Get All Stack Traces</synopsis>
2545       <description>
2546         Get information about the stacks of all live threads
2547         (including <internallink id="RunAgentThread">agent threads</internallink>).
2548         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2549         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
2550         otherwise the entire stack is returned.
2551         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2552         <p/>
2553         All stacks are collected simultaneously, that is, no changes will occur to the
2554         thread state or stacks between the sampling of one thread and the next.
2555         The threads need not be suspended.
2556 
2557         <example>
2558 jvmtiStackInfo *stack_info;
2559 jint thread_count;
2560 int ti;
2561 jvmtiError err;
2562 
2563 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count);
2564 if (err != JVMTI_ERROR_NONE) {
2565    ...
2566 }
2567 for (ti = 0; ti &lt; thread_count; ++ti) {
2568    jvmtiStackInfo *infop = &amp;stack_info[ti];
2569    jthread thread = infop-&gt;thread;
2570    jint state = infop-&gt;state;
2571    jvmtiFrameInfo *frames = infop-&gt;frame_buffer;
2572    int fi;
2573 
2574    myThreadAndStatePrinter(thread, state);
2575    for (fi = 0; fi &lt; infop-&gt;frame_count; fi++) {
2576       myFramePrinter(frames[fi].method, frames[fi].location);
2577    }
2578 }
2579 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
2580 err = (*jvmti)-&gt;Deallocate(jvmti, stack_info);
2581         </example>
2582         <todo>
2583           check example code.
2584         </todo>
2585 
2586       </description>
2587       <origin>new</origin>
2588       <capabilities>
2589       </capabilities>
2590       <parameters>
2591         <param id="max_frame_count">
2592           <jint min="0"/>
2593           <description>
2594             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2595           </description>
2596         </param>
2597         <param id="stack_info_ptr">
2598           <allocbuf>
2599             <struct>jvmtiStackInfo</struct>
2600           </allocbuf>
2601             <description>
2602               On return, this buffer is filled
2603               with stack information for each thread.
2604               The number of <datalink id="jvmtiStackInfo"/> records is determined
2605               by <paramlink id="thread_count_ptr"/>.
2606               <p/>
2607               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
2608               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2609               These buffers must not be separately deallocated.
2610             </description>
2611         </param>
2612         <param id="thread_count_ptr">
2613           <outptr><jint/></outptr>
2614           <description>
2615             The number of threads traced.
2616           </description>
2617         </param>
2618       </parameters>
2619       <errors>
2620       </errors>
2621     </function>
2622 
2623     <function id="GetThreadListStackTraces" num="101">
2624       <synopsis>Get Thread List Stack Traces</synopsis>
2625       <description>
2626         Get information about the stacks of the supplied threads.
2627         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2628         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
2629         otherwise the entire stack is returned.
2630         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2631         <p/>
2632         All stacks are collected simultaneously, that is, no changes will occur to the
2633         thread state or stacks between the sampling one thread and the next.
2634         The threads need not be suspended.
2635         <p/>
2636         If a thread has not yet started or terminates before the stack information is collected,
2637         a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
2638         will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
2639         <p/>
2640         See the example for the similar function
2641         <functionlink id="GetAllStackTraces"/>.
2642       </description>
2643       <origin>new</origin>
2644       <capabilities>
2645       </capabilities>
2646       <parameters>
2647         <param id="thread_count">
2648           <jint min="0"/>
2649           <description>
2650             The number of threads to trace.
2651           </description>
2652         </param>
2653         <param id="thread_list">
2654           <inbuf incount="thread_count"><jthread/></inbuf>
2655             <description>
2656               The list of threads to trace.
2657             </description>
2658         </param>
2659         <param id="max_frame_count">
2660           <jint min="0"/>
2661           <description>
2662             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2663           </description>
2664         </param>
2665         <param id="stack_info_ptr">
2666           <allocbuf outcount="thread_count">
2667             <struct>jvmtiStackInfo</struct>
2668           </allocbuf>
2669             <description>
2670               On return, this buffer is filled
2671               with stack information for each thread.
2672               The number of <datalink id="jvmtiStackInfo"/> records is determined
2673               by <paramlink id="thread_count"/>.
2674               <p/>
2675               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
2676               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2677               These buffers must not be separately deallocated.
2678             </description>
2679         </param>
2680       </parameters>
2681       <errors>
2682         <error id="JVMTI_ERROR_INVALID_THREAD">
2683           An element in <paramlink id="thread_list"/> is not a thread object.
2684         </error>
2685       </errors>
2686     </function>
2687 
2688     <elide>
2689     <function id="AsyncGetStackTrace" num="1000">
2690       <synopsis>Get Stack Trace--Asynchronous</synopsis>
2691       <description>
2692         Get information about the entire stack of a thread (or a sub-section of it).
2693         This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
2694         and is reentrant and safe to call
2695         from asynchronous signal handlers.
2696         The stack trace is returned only for the calling thread.
2697         <p/>
2698         The <functionlink id="GetLineNumberTable"></functionlink>
2699         function can be used to map locations to line numbers. Note that
2700         this mapping can be done lazily.
2701       </description>
2702       <origin>jvmpi</origin>
2703       <capabilities>
2704         <required id="can_get_async_stack_trace"></required>
2705         <capability id="can_show_JVM_spec_async_frames">
2706           If <code>false</code>,
2707           <paramlink id="use_java_stack"></paramlink>
2708           must be <code>false</code>.
2709         </capability>
2710       </capabilities>
2711       <parameters>
2712         <param id="use_java_stack">
2713           <jboolean/>
2714           <description>
2715             Return the stack showing <vmspec/>
2716             model of the stack;
2717             otherwise, show the internal representation of the stack with
2718             inlined and optimized methods missing.  If the virtual machine
2719             is using the <i>Java Virtual Machine Specification</i> stack model
2720             internally, this flag is ignored.
2721           </description>
2722         </param>
2723         <param id="max_count">
2724           <jint min="0"/>
2725           <description>
2726             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2727             Retrieve this many unless the stack depth is less than <code>max_count</code>.
2728           </description>
2729         </param>
2730         <param id="frame_buffer">
2731           <outbuf incount="max_count" outcount="count_ptr">
2732             <struct>jvmtiFrameInfo</struct>
2733             <nullok>this information is not returned</nullok>
2734           </outbuf>
2735             <description>
2736               The agent passes in a buffer
2737               large enough to hold <code>max_count</code> records of
2738               <datalink id="jvmtiFrameInfo"></datalink>.  This buffer must be
2739               pre-allocated by the agent.
2740             </description>
2741         </param>
2742         <param id="count_ptr">
2743           <outptr><jint/></outptr>
2744           <description>
2745             On return, points to the number of records filled in..
2746           </description>
2747         </param>
2748       </parameters>
2749       <errors>
2750         <error id="JVMTI_ERROR_UNATTACHED_THREAD">
2751           The thread being used to call this function is not attached
2752           to the virtual machine.  Calls must be made from attached threads.
2753         </error>
2754       </errors>
2755     </function>
2756     </elide>
2757 
2758     <function id="GetFrameCount" num="16">
2759       <synopsis>Get Frame Count</synopsis>
2760       <description>
2761         Get the number of frames currently in the specified thread's call stack.
2762         <p/>
2763         If this function is called for a thread actively executing bytecodes (for example,
2764         not the current thread and not suspended), the information returned is transient.
2765       </description>
2766       <origin>jvmdi</origin>
2767       <capabilities>
2768       </capabilities>
2769       <parameters>
2770         <param id="thread">
2771           <jthread null="current"/>
2772             <description>
2773               The thread to query.
2774             </description>
2775         </param>
2776         <param id="count_ptr">
2777           <outptr><jint/></outptr>
2778           <description>
2779             On return, points to the number of frames in the call stack.
2780           </description>
2781         </param>
2782       </parameters>
2783       <errors>
2784       </errors>
2785     </function>
2786 
2787     <function id="PopFrame" num="80">
2788       <synopsis>Pop Frame</synopsis>
2789       <description>
2790         Pop the current frame of <code>thread</code>'s stack.
2791         Popping a frame takes you to the previous frame.
2792         When the thread is resumed, the execution
2793         state of the thread is reset to the state
2794         immediately before the called method was invoked.
2795         That is (using <vmspec/> terminology):
2796           <ul>
2797             <li>the current frame is discarded as the previous frame becomes the current one</li>
2798             <li>the operand stack is restored--the argument values are added back
2799               and if the invoke was not <code>invokestatic</code>,
2800               <code>objectref</code> is added back as well</li>
2801             <li>the Java virtual machine PC is restored to the opcode
2802               of the invoke instruction</li>
2803           </ul>
2804         Note however, that any changes to the arguments, which
2805         occurred in the called method, remain;
2806         when execution continues, the first instruction to
2807         execute will be the invoke.
2808         <p/>
2809         Between calling <code>PopFrame</code> and resuming the
2810         thread the state of the stack is undefined.
2811         To pop frames beyond the first,
2812         these three steps must be repeated:
2813         <ul>
2814           <li>suspend the thread via an event (step, breakpoint, ...)</li>
2815           <li>call <code>PopFrame</code></li>
2816           <li>resume the thread</li>
2817         </ul>
2818         <p/>
2819         A lock acquired by calling the called method
2820         (if it is a <code>synchronized</code>  method)
2821         and locks acquired by entering <code>synchronized</code>
2822         blocks within the called method are released.
2823         Note: this does not apply to native locks or
2824         <code>java.util.concurrent.locks</code> locks.
2825         <p/>
2826         Finally blocks are not executed.
2827         <p/>
2828         Changes to global state are not addressed and thus remain changed.
2829         <p/>
2830         The specified thread must be suspended (which implies it cannot be the current thread).
2831         <p/>
2832         Both the called method and calling method must be non-native Java programming
2833         language methods.
2834         <p/>
2835         No <jvmti/> events are generated by this function.
2836       </description>
2837       <origin>jvmdi</origin>
2838       <capabilities>
2839         <required id="can_pop_frame"></required>
2840       </capabilities>
2841       <parameters>
2842         <param id="thread">
2843           <jthread/>
2844             <description>
2845               The thread whose current frame is to be popped.
2846             </description>
2847         </param>
2848       </parameters>
2849       <errors>
2850         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2851           Called or calling method is a native method.
2852           The implementation is unable to pop this frame.
2853         </error>
2854         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2855           Thread was not suspended.
2856         </error>
2857         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2858           There are less than two stack frames on the call stack.
2859         </error>
2860       </errors>
2861     </function>
2862 
2863     <function id="GetFrameLocation" num="19">
2864       <synopsis>Get Frame Location</synopsis>
2865       <description>
2866         <p/>
2867         For a Java programming language frame, return the location of the instruction
2868         currently executing.
2869       </description>
2870       <origin>jvmdiClone</origin>
2871       <capabilities>
2872       </capabilities>
2873       <parameters>
2874         <param id="thread">
2875           <jthread null="current" frame="frame"/>
2876           <description>
2877             The thread of the frame to query.
2878           </description>
2879         </param>
2880         <param id="depth">
2881           <jframeID thread="thread"/>
2882           <description>
2883             The depth of the frame to query.
2884           </description>
2885         </param>
2886         <param id="method_ptr">
2887           <outptr><jmethodID/></outptr>
2888             <description>
2889               On return, points to the method for the current location.
2890             </description>
2891         </param>
2892         <param id="location_ptr">
2893           <outptr><jlocation/></outptr>
2894           <description>
2895             On return, points to the index of the currently
2896             executing instruction.
2897             Is set to <code>-1</code> if the frame is executing
2898             a native method.
2899           </description>
2900         </param>
2901       </parameters>
2902       <errors>
2903       </errors>
2904     </function>
2905 
2906     <function id="NotifyFramePop" num="20">
2907       <synopsis>Notify Frame Pop</synopsis>
2908       <description>
2909         When the frame that is currently at <paramlink id="depth"></paramlink>
2910         is popped from the stack, generate a
2911         <eventlink id="FramePop"></eventlink> event.  See the
2912         <eventlink id="FramePop"></eventlink> event for details.
2913         Only frames corresponding to non-native Java programming language
2914         methods can receive notification.
2915         <p/>
2916         The specified thread must either be the current thread
2917         or the thread must be suspended.
2918       </description>
2919       <origin>jvmdi</origin>
2920       <capabilities>
2921         <required id="can_generate_frame_pop_events"></required>
2922       </capabilities>
2923       <parameters>
2924         <param id="thread">
2925           <jthread null="current" frame="depth"/>
2926           <description>
2927             The thread of the frame for which the frame pop event will be generated.
2928           </description>
2929         </param>
2930         <param id="depth">
2931           <jframeID thread="thread"/>
2932           <description>
2933             The depth of the frame for which the frame pop event will be generated.
2934           </description>
2935         </param>
2936       </parameters>
2937       <errors>
2938         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2939           The frame at <code>depth</code> is executing a
2940           native method.
2941         </error>
2942         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2943           Thread was not suspended and was not the current thread.
2944         </error>
2945       </errors>
2946     </function>
2947 
2948   </category>
2949 
2950   <category id="ForceEarlyReturn" label="Force Early Return">
2951     <intro>
2952       These functions allow an agent to force a method
2953       to return at any point during its execution.
2954       The method which will return early is referred to as the <i>called method</i>.
2955       The called method is the current method
2956       (as defined by
2957       <vmspec chapter="3.6"/>)
2958       for the specified thread at
2959       the time the function is called.
2960       <p/>
2961       The specified thread must be suspended or must be the current thread.
2962       The return occurs when execution of Java programming
2963       language code is resumed on this thread.
2964       Between calling one of these functions and resumption
2965       of thread execution, the state of the stack is undefined.
2966       <p/>
2967       No further instructions are executed in the called method.
2968       Specifically, finally blocks are not executed.
2969       Note: this can cause inconsistent states in the application.
2970       <p/>
2971       A lock acquired by calling the called method
2972       (if it is a <code>synchronized</code>  method)
2973       and locks acquired by entering <code>synchronized</code>
2974       blocks within the called method are released.
2975       Note: this does not apply to native locks or
2976       <code>java.util.concurrent.locks</code> locks.
2977       <p/>
2978       Events, such as <eventlink id="MethodExit"></eventlink>,
2979       are generated as they would be in a normal return.
2980       <p/>
2981       The called method must be a non-native Java programming
2982       language method.
2983       Forcing return on a thread with only one frame on the
2984       stack causes the thread to exit when resumed.
2985     </intro>
2986 
2987     <function id="ForceEarlyReturnObject" num="81" since="1.1">
2988       <synopsis>Force Early Return - Object</synopsis>
2989       <description>
2990         This function can be used to return from a method whose
2991         result type is <code>Object</code>
2992         or a subclass of <code>Object</code>.
2993       </description>
2994       <origin>new</origin>
2995       <capabilities>
2996         <required id="can_force_early_return"></required>
2997       </capabilities>
2998       <parameters>
2999         <param id="thread">
3000           <jthread null="current"/>
3001           <description>
3002             The thread whose current frame is to return early.
3003           </description>
3004         </param>
3005         <param id="value">
3006           <jobject/>
3007           <description>
3008             The return value for the called frame.
3009             An object or <code>NULL</code>.
3010           </description>
3011         </param>
3012       </parameters>
3013       <errors>
3014         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3015           Attempted to return early from a frame
3016           corresponding to a native method.
3017           Or the implementation is unable to provide
3018           this functionality on this frame.
3019         </error>
3020         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3021           The result type of the called method is not
3022           <code>Object</code> or a subclass of <code>Object</code>.
3023         </error>
3024         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3025           The supplied <paramlink id="value"/> is not compatible with the
3026           result type of the called method.
3027         </error>
3028         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3029           Thread was not the current thread and was not suspended.
3030         </error>
3031         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3032           There are no more frames on the call stack.
3033         </error>
3034       </errors>
3035     </function>
3036 
3037     <function id="ForceEarlyReturnInt" num="82" since="1.1">
3038       <synopsis>Force Early Return - Int</synopsis>
3039       <description>
3040         This function can be used to return from a method whose
3041         result type is <code>int</code>, <code>short</code>,
3042         <code>char</code>, <code>byte</code>, or
3043         <code>boolean</code>.
3044       </description>
3045       <origin>new</origin>
3046       <capabilities>
3047         <required id="can_force_early_return"></required>
3048       </capabilities>
3049       <parameters>
3050         <param id="thread">
3051           <jthread null="current"/>
3052           <description>
3053             The thread whose current frame is to return early.
3054           </description>
3055         </param>
3056         <param id="value">
3057           <jint/>
3058           <description>
3059             The return value for the called frame.
3060           </description>
3061         </param>
3062       </parameters>
3063       <errors>
3064         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3065           Attempted to return early from a frame
3066           corresponding to a native method.
3067           Or the implementation is unable to provide
3068           this functionality on this frame.
3069         </error>
3070         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3071           The result type of the called method is not
3072           <code>int</code>, <code>short</code>,
3073           <code>char</code>, <code>byte</code>, or
3074           <code>boolean</code>.
3075         </error>
3076         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3077           Thread was not the current thread and was not suspended.
3078         </error>
3079         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3080           There are no frames on the call stack.
3081         </error>
3082       </errors>
3083     </function>
3084 
3085     <function id="ForceEarlyReturnLong" num="83" since="1.1">
3086       <synopsis>Force Early Return - Long</synopsis>
3087       <description>
3088         This function can be used to return from a method whose
3089         result type is <code>long</code>.
3090       </description>
3091       <origin>new</origin>
3092       <capabilities>
3093         <required id="can_force_early_return"></required>
3094       </capabilities>
3095       <parameters>
3096         <param id="thread">
3097           <jthread null="current"/>
3098           <description>
3099             The thread whose current frame is to return early.
3100           </description>
3101         </param>
3102         <param id="value">
3103           <jlong/>
3104           <description>
3105             The return value for the called frame.
3106           </description>
3107         </param>
3108       </parameters>
3109       <errors>
3110         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3111           Attempted to return early from a frame
3112           corresponding to a native method.
3113           Or the implementation is unable to provide
3114           this functionality on this frame.
3115         </error>
3116         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3117           The result type of the called method is not <code>long</code>.
3118         </error>
3119         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3120           Thread was not the current thread and was not suspended.
3121         </error>
3122         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3123           There are no frames on the call stack.
3124         </error>
3125       </errors>
3126     </function>
3127 
3128     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
3129       <synopsis>Force Early Return - Float</synopsis>
3130       <description>
3131         This function can be used to return from a method whose
3132         result type is <code>float</code>.
3133       </description>
3134       <origin>new</origin>
3135       <capabilities>
3136         <required id="can_force_early_return"></required>
3137       </capabilities>
3138       <parameters>
3139         <param id="thread">
3140           <jthread null="current"/>
3141           <description>
3142             The thread whose current frame is to return early.
3143           </description>
3144         </param>
3145         <param id="value">
3146           <jfloat/>
3147           <description>
3148             The return value for the called frame.
3149           </description>
3150         </param>
3151       </parameters>
3152       <errors>
3153         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3154           Attempted to return early from a frame
3155           corresponding to a native method.
3156           Or the implementation is unable to provide
3157           this functionality on this frame.
3158         </error>
3159         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3160           The result type of the called method is not <code>float</code>.
3161         </error>
3162         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3163           Thread was not the current thread and was not suspended.
3164         </error>
3165         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3166           There are no frames on the call stack.
3167         </error>
3168       </errors>
3169     </function>
3170 
3171     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
3172       <synopsis>Force Early Return - Double</synopsis>
3173       <description>
3174         This function can be used to return from a method whose
3175         result type is <code>double</code>.
3176       </description>
3177       <origin>new</origin>
3178       <capabilities>
3179         <required id="can_force_early_return"></required>
3180       </capabilities>
3181       <parameters>
3182         <param id="thread">
3183           <jthread null="current"/>
3184           <description>
3185             The thread whose current frame is to return early.
3186           </description>
3187         </param>
3188         <param id="value">
3189           <jdouble/>
3190           <description>
3191             The return value for the called frame.
3192           </description>
3193         </param>
3194       </parameters>
3195       <errors>
3196         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3197           Attempted to return early from a frame corresponding to a native method.
3198           Or the implementation is unable to provide this functionality on this frame.
3199         </error>
3200         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3201           The result type of the called method is not <code>double</code>.
3202         </error>
3203         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3204           Thread was not the current thread and was not suspended.
3205         </error>
3206         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3207           There are no frames on the call stack.
3208         </error>
3209       </errors>
3210     </function>
3211 
3212     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3213       <synopsis>Force Early Return - Void</synopsis>
3214       <description>
3215         This function can be used to return from a method with no result type.
3216         That is, the called method must be declared <code>void</code>.
3217       </description>
3218       <origin>new</origin>
3219       <capabilities>
3220         <required id="can_force_early_return"></required>
3221       </capabilities>
3222       <parameters>
3223         <param id="thread">
3224           <jthread null="current"/>
3225           <description>
3226             The thread whose current frame is to return early.
3227           </description>
3228         </param>
3229       </parameters>
3230       <errors>
3231         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3232           Attempted to return early from a frame
3233           corresponding to a native method.
3234           Or the implementation is unable to provide
3235           this functionality on this frame.
3236         </error>
3237         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3238           The called method has a result type.
3239         </error>
3240         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3241           Thread was not the current thread and was not suspended.
3242         </error>
3243         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3244           There are no frames on the call stack.
3245         </error>
3246       </errors>
3247     </function>
3248 
3249   </category>
3250 
3251   <category id="Heap" label="Heap">
3252     <intro>
3253       These functions are used to analyze the heap.
3254       Functionality includes the ability to view the objects in the
3255       heap and to tag these objects.
3256     </intro>
3257 
3258     <intro id="objectTags" label="Object Tags">
3259       A <i>tag</i> is a value associated with an object.
3260       Tags are explicitly set by the agent using the
3261       <functionlink id="SetTag"></functionlink> function or by
3262       callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.
3263       <p/>
3264       Tags are local to the environment; that is, the tags of one
3265       environment are not visible in another.
3266       <p/>
3267       Tags are <code>jlong</code> values which can be used
3268       simply to mark an object or to store a pointer to more detailed
3269       information.  Objects which have not been tagged have a
3270       tag of zero.
3271       Setting a tag to zero makes the object untagged.
3272     </intro>
3273 
3274     <intro id="heapCallbacks" label="Heap Callback Functions">
3275         Heap functions which iterate through the heap and recursively
3276         follow object references use agent supplied callback functions
3277         to deliver the information.
3278         <p/>
3279         These heap callback functions must adhere to the following restrictions --
3280         These callbacks must not use JNI functions.
3281         These callbacks must not use <jvmti/> functions except
3282         <i>callback safe</i> functions which
3283         specifically allow such use (see the raw monitor, memory management,
3284         and environment local storage functions).
3285         <p/>
3286         An implementation may invoke a callback on an internal thread or
3287         the thread which called the iteration function.
3288         Heap callbacks are single threaded -- no more than one callback will
3289         be invoked at a time.
3290         <p/>
3291         The Heap Filter Flags can be used to prevent reporting
3292         based on the tag status of an object or its class.
3293         If no flags are set (the <code>jint</code> is zero), objects
3294         will not be filtered out.
3295 
3296         <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
3297           <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
3298             Filter out tagged objects. Objects which are tagged are not included.
3299           </constant>
3300           <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
3301             Filter out untagged objects. Objects which are not tagged are not included.
3302           </constant>
3303           <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
3304             Filter out objects with tagged classes. Objects whose class is tagged are not included.
3305           </constant>
3306           <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
3307             Filter out objects with untagged classes. Objects whose class is not tagged are not included.
3308           </constant>
3309         </constants>
3310 
3311         <p/>
3312         The Heap Visit Control Flags are returned by the heap callbacks
3313         and can be used to abort the iteration.  For the
3314         <functionlink id="jvmtiHeapReferenceCallback">Heap
3315         Reference Callback</functionlink>, it can also be used
3316         to prune the graph of traversed references
3317         (<code>JVMTI_VISIT_OBJECTS</code> is not set).
3318 
3319         <constants id="jvmtiHeapVisitControl"
3320                    label="Heap Visit Control Flags"
3321                    kind="bits"
3322                    since="1.1">
3323           <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
3324             If we are visiting an object and if this callback
3325             was initiated by <functionlink id="FollowReferences"/>,
3326             traverse the references of this object.
3327             Otherwise ignored.
3328           </constant>
3329           <constant id="JVMTI_VISIT_ABORT" num="0x8000">
3330             Abort the iteration.  Ignore all other bits.
3331           </constant>
3332         </constants>
3333 
3334         <p/>
3335         The Heap Reference Enumeration is provided by the
3336         <functionlink id="jvmtiHeapReferenceCallback">Heap
3337         Reference Callback</functionlink> and
3338         <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field
3339         Callback</functionlink> to
3340         describe the kind of reference
3341         being reported.
3342 
3343         <constants id="jvmtiHeapReferenceKind"
3344                    label="Heap Reference Enumeration"
3345                    kind="enum"
3346                    since="1.1">
3347           <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
3348             Reference from an object to its class.
3349           </constant>
3350           <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
3351             Reference from an object to the value of one of its instance fields.
3352           </constant>
3353           <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
3354             Reference from an array to one of its elements.
3355           </constant>
3356           <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
3357             Reference from a class to its class loader.
3358           </constant>
3359           <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
3360             Reference from a class to its signers array.
3361           </constant>
3362           <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
3363             Reference from a class to its protection domain.
3364           </constant>
3365           <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
3366             Reference from a class to one of its interfaces.
3367             Note: interfaces are defined via a constant pool reference,
3368             so the referenced interfaces may also be reported with a
3369             <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3370           </constant>
3371           <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
3372             Reference from a class to the value of one of its static fields.
3373           </constant>
3374           <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
3375             Reference from a class to a resolved entry in the constant pool.
3376           </constant>
3377           <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
3378             Reference from a class to its superclass.
3379             A callback is not sent if the superclass is <code>java.lang.Object</code>.
3380             Note: loaded classes define superclasses via a constant pool
3381             reference, so the referenced superclass may also be reported with
3382             a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3383           </constant>
3384           <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
3385             Heap root reference: JNI global reference.
3386           </constant>
3387           <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
3388             Heap root reference: System class.
3389           </constant>
3390           <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
3391             Heap root reference: monitor.
3392           </constant>
3393           <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
3394             Heap root reference: local variable on the stack.
3395           </constant>
3396           <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
3397             Heap root reference: JNI local reference.
3398           </constant>
3399           <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
3400             Heap root reference: Thread.
3401           </constant>
3402           <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
3403             Heap root reference: other heap root reference.
3404           </constant>
3405         </constants>
3406 
3407         <p/>
3408         Definitions for the single character type descriptors of
3409         primitive types.
3410 
3411         <constants id="jvmtiPrimitiveType"
3412                    label="Primitive Type Enumeration"
3413                    kind="enum"
3414                    since="1.1">
3415           <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
3416             'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
3417           </constant>
3418           <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
3419             'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
3420           </constant>
3421           <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
3422             'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
3423           </constant>
3424           <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
3425             'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
3426           </constant>
3427           <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
3428             'I' - Java programming language <code>int</code> - JNI <code>jint</code>
3429           </constant>
3430           <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
3431             'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
3432           </constant>
3433           <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
3434             'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
3435           </constant>
3436           <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
3437             'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
3438           </constant>
3439         </constants>
3440     </intro>
3441 
3442       <typedef id="jvmtiHeapReferenceInfoField"
3443                label="Reference information structure for Field references"
3444                since="1.1">
3445         <description>
3446           Reference information returned for
3447           <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and
3448           <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3449         </description>
3450         <field id="index">
3451           <jint/>
3452           <description>
3453             For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the
3454             referrer object is not a class or an inteface.
3455             In this case, <code>index</code> is the index of the field
3456             in the class of the referrer object.
3457             This class is referred to below as <i>C</i>.
3458             <p/>
3459             For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
3460             the referrer object is a class (referred to below as <i>C</i>)
3461             or an interface (referred to below as <i>I</i>).
3462             In this case, <code>index</code> is the index of the field in
3463             that class or interface.
3464             <p/>
3465             If the referrer object is not an interface, then the field
3466             indices are determined as follows:
3467             <ul>
3468               <li>make a list of all the fields in <i>C</i> and its
3469                   superclasses, starting with all the fields in
3470                   <code>java.lang.Object</code> and ending with all the
3471                   fields in <i>C</i>.</li>
3472               <li>Within this list, put
3473                   the fields for a given class in the order returned by
3474                   <functionlink id="GetClassFields"/>.</li>
3475               <li>Assign the fields in this list indices
3476                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
3477                   is the count of the fields in all the interfaces
3478                   implemented by <i>C</i>.
3479                   Note that <i>C</i> implements all interfaces
3480                   directly implemented by its superclasses; as well
3481                   as all superinterfaces of these interfaces.</li>
3482             </ul>
3483             If the referrer object is an interface, then the field
3484             indices are determined as follows:
3485             <ul>
3486               <li>make a list of the fields directly declared in
3487                   <i>I</i>.</li>
3488               <li>Within this list, put
3489                   the fields in the order returned by
3490                   <functionlink id="GetClassFields"/>.</li>
3491               <li>Assign the fields in this list indices
3492                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
3493                   is the count of the fields in all the superinterfaces
3494                   of <i>I</i>.</li>
3495             </ul>
3496             All fields are included in this computation, regardless of
3497             field modifier (static, public, private, etc).
3498             <p/>
3499             For example, given the following classes and interfaces:
3500             <example>
3501 interface I0 {
3502     int p = 0;
3503 }
3504 
3505 interface I1 extends I0 {
3506     int x = 1;
3507 }
3508 
3509 interface I2 extends I0 {
3510     int y = 2;
3511 }
3512 
3513 class C1 implements I1 {
3514     public static int a = 3;
3515     private int b = 4;
3516 }
3517 
3518 class C2 extends C1 implements I2 {
3519     static int q = 5;
3520     final int r = 6;
3521 }
3522             </example>
3523             Assume that <functionlink id="GetClassFields"/> called on
3524             <code>C1</code> returns the fields of <code>C1</code> in the
3525             order: a, b; and that the fields of <code>C2</code> are
3526             returned in the order: q, r.
3527             An instance of class <code>C1</code> will have the
3528             following field indices:
3529             <dl><dd><table>
3530               <tr>
3531                 <td>
3532                   a
3533                 </td>
3534                 <td>
3535                   2
3536                 </td>
3537                 <td align="left">
3538                   The count of the fields in the interfaces
3539                   implemented by <code>C1</code> is two (<i>n</i>=2):
3540                   <code>p</code> of <code>I0</code>
3541                   and <code>x</code> of <code>I1</code>.
3542                 </td>
3543               </tr>
3544               <tr>
3545                 <td>
3546                   b
3547                 </td>
3548                 <td>
3549                   3
3550                 </td>
3551                 <td align="left">
3552                   the subsequent index.
3553                 </td>
3554               </tr>
3555             </table></dd></dl>
3556             The class <code>C1</code> will have the same field indices.
3557             <p/>
3558             An instance of class <code>C2</code> will have the
3559             following field indices:
3560             <dl><dd><table>
3561               <tr>
3562                 <td>
3563                   a
3564                 </td>
3565                 <td>
3566                   3
3567                 </td>
3568                 <td align="left">
3569                   The count of the fields in the interfaces
3570                   implemented by <code>C2</code> is three (<i>n</i>=3):
3571                   <code>p</code> of <code>I0</code>,
3572                   <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code>
3573                   (an interface of <code>C2</code>).  Note that the field <code>p</code>
3574                   of <code>I0</code> is only included once.
3575                 </td>
3576               </tr>
3577               <tr>
3578                 <td>
3579                   b
3580                 </td>
3581                 <td>
3582                   4
3583                 </td>
3584                 <td align="left">
3585                   the subsequent index to "a".
3586                 </td>
3587               </tr>
3588               <tr>
3589                 <td>
3590                   q
3591                 </td>
3592                 <td>
3593                   5
3594                 </td>
3595                 <td align="left">
3596                   the subsequent index to "b".
3597                 </td>
3598               </tr>
3599               <tr>
3600                 <td>
3601                   r
3602                 </td>
3603                 <td>
3604                   6
3605                 </td>
3606                 <td align="left">
3607                   the subsequent index to "q".
3608                 </td>
3609               </tr>
3610             </table></dd></dl>
3611             The class <code>C2</code> will have the same field indices.
3612             Note that a field may have a different index depending on the
3613             object that is viewing it -- for example field "a" above.
3614             Note also: not all field indices may be visible from the
3615             callbacks, but all indices are shown for illustrative purposes.
3616             <p/>
3617             The interface <code>I1</code> will have the
3618             following field indices:
3619             <dl><dd><table>
3620               <tr>
3621                 <td>
3622                   x
3623                 </td>
3624                 <td>
3625                   1
3626                 </td>
3627                 <td align="left">
3628                   The count of the fields in the superinterfaces
3629                   of <code>I1</code> is one (<i>n</i>=1):
3630                   <code>p</code> of <code>I0</code>.
3631                 </td>
3632               </tr>
3633             </table></dd></dl>
3634           </description>
3635         </field>
3636       </typedef>
3637 
3638       <typedef id="jvmtiHeapReferenceInfoArray"
3639                label="Reference information structure for Array references"
3640                since="1.1">
3641         <description>
3642           Reference information returned for
3643          <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3644         </description>
3645         <field id="index">
3646           <jint/>
3647           <description>
3648             The array index.
3649           </description>
3650         </field>
3651       </typedef>
3652 
3653       <typedef id="jvmtiHeapReferenceInfoConstantPool"
3654                label="Reference information structure for Constant Pool references"
3655                since="1.1">
3656         <description>
3657           Reference information returned for
3658           <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3659         </description>
3660         <field id="index">
3661           <jint/>
3662           <description>
3663             The index into the constant pool of the class. See the description in
3664       <vmspec chapter="4.4"/>.
3665           </description>
3666         </field>
3667       </typedef>
3668 
3669       <typedef id="jvmtiHeapReferenceInfoStackLocal"
3670                label="Reference information structure for Local Variable references"
3671                since="1.1">
3672         <description>
3673           Reference information returned for
3674           <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3675         </description>
3676         <field id="thread_tag">
3677           <jlong/>
3678           <description>
3679             The tag of the thread corresponding to this stack, zero if not tagged.
3680           </description>
3681         </field>
3682         <field id="thread_id">
3683           <jlong/>
3684           <description>
3685             The unique thread ID of the thread corresponding to this stack.
3686           </description>
3687         </field>
3688         <field id="depth">
3689           <jint/>
3690           <description>
3691             The depth of the frame.
3692           </description>
3693         </field>
3694         <field id="method">
3695           <jmethodID/>
3696           <description>
3697             The method executing in this frame.
3698           </description>
3699         </field>
3700         <field id="location">
3701           <jlocation/>
3702           <description>
3703             The currently executing location in this frame.
3704           </description>
3705         </field>
3706         <field id="slot">
3707           <jint/>
3708           <description>
3709             The slot number of the local variable.
3710           </description>
3711         </field>
3712       </typedef>
3713 
3714       <typedef id="jvmtiHeapReferenceInfoJniLocal"
3715                label="Reference information structure for JNI local references"
3716                since="1.1">
3717         <description>
3718           Reference information returned for
3719           <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3720         </description>
3721         <field id="thread_tag">
3722           <jlong/>
3723           <description>
3724             The tag of the thread corresponding to this stack, zero if not tagged.
3725           </description>
3726         </field>
3727         <field id="thread_id">
3728           <jlong/>
3729           <description>
3730             The unique thread ID of the thread corresponding to this stack.
3731           </description>
3732         </field>
3733         <field id="depth">
3734           <jint/>
3735           <description>
3736             The depth of the frame.
3737           </description>
3738         </field>
3739         <field id="method">
3740           <jmethodID/>
3741           <description>
3742             The method executing in this frame.
3743           </description>
3744         </field>
3745       </typedef>
3746 
3747       <typedef id="jvmtiHeapReferenceInfoReserved"
3748                label="Reference information structure for Other references"
3749                since="1.1">
3750         <description>
3751           Reference information returned for other references.
3752         </description>
3753         <field id="reserved1">
3754           <jlong/>
3755           <description>
3756             reserved for future use.
3757           </description>
3758         </field>
3759         <field id="reserved2">
3760           <jlong/>
3761           <description>
3762             reserved for future use.
3763           </description>
3764         </field>
3765         <field id="reserved3">
3766           <jlong/>
3767           <description>
3768             reserved for future use.
3769           </description>
3770         </field>
3771         <field id="reserved4">
3772           <jlong/>
3773           <description>
3774             reserved for future use.
3775           </description>
3776         </field>
3777         <field id="reserved5">
3778           <jlong/>
3779           <description>
3780             reserved for future use.
3781           </description>
3782         </field>
3783         <field id="reserved6">
3784           <jlong/>
3785           <description>
3786             reserved for future use.
3787           </description>
3788         </field>
3789         <field id="reserved7">
3790           <jlong/>
3791           <description>
3792             reserved for future use.
3793           </description>
3794         </field>
3795         <field id="reserved8">
3796           <jlong/>
3797           <description>
3798             reserved for future use.
3799           </description>
3800         </field>
3801       </typedef>
3802 
3803       <uniontypedef id="jvmtiHeapReferenceInfo"
3804                label="Reference information structure"
3805                since="1.1">
3806         <description>
3807           The information returned about referrers.
3808           Represented as a union of the various kinds of reference information.
3809         </description>
3810         <field id="field">
3811           <struct>jvmtiHeapReferenceInfoField</struct>
3812           <description>
3813             The referrer information for
3814             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>
3815             and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3816           </description>
3817         </field>
3818         <field id="array">
3819           <struct>jvmtiHeapReferenceInfoArray</struct>
3820           <description>
3821             The referrer information for
3822             For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3823           </description>
3824         </field>
3825         <field id="constant_pool">
3826           <struct>jvmtiHeapReferenceInfoConstantPool</struct>
3827           <description>
3828             The referrer information for
3829             For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3830           </description>
3831         </field>
3832         <field id="stack_local">
3833           <struct>jvmtiHeapReferenceInfoStackLocal</struct>
3834           <description>
3835             The referrer information for
3836             For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3837           </description>
3838         </field>
3839         <field id="jni_local">
3840           <struct>jvmtiHeapReferenceInfoJniLocal</struct>
3841           <description>
3842             The referrer information for
3843             For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3844           </description>
3845         </field>
3846         <field id="other">
3847           <struct>jvmtiHeapReferenceInfoReserved</struct>
3848           <description>
3849             reserved for future use.
3850           </description>
3851         </field>
3852       </uniontypedef>
3853 
3854       <typedef id="jvmtiHeapCallbacks"
3855                label="Heap callback function structure"
3856                since="1.1">
3857         <field id="heap_iteration_callback">
3858           <ptrtype>
3859             <struct>jvmtiHeapIterationCallback</struct>
3860           </ptrtype>
3861           <description>
3862             The callback to be called to describe an
3863             object in the heap. Used by the
3864             <functionlink id="IterateThroughHeap"/> function, ignored by the
3865             <functionlink id="FollowReferences"/> function.
3866           </description>
3867         </field>
3868         <field id="heap_reference_callback">
3869           <ptrtype>
3870             <struct>jvmtiHeapReferenceCallback</struct>
3871           </ptrtype>
3872           <description>
3873             The callback to be called to describe an
3874             object reference.  Used by the
3875             <functionlink id="FollowReferences"/> function, ignored by the
3876             <functionlink id="IterateThroughHeap"/> function.
3877           </description>
3878         </field>
3879         <field id="primitive_field_callback">
3880           <ptrtype>
3881             <struct>jvmtiPrimitiveFieldCallback</struct>
3882           </ptrtype>
3883           <description>
3884             The callback to be called to describe a
3885             primitive field.
3886           </description>
3887         </field>
3888         <field id="array_primitive_value_callback">
3889           <ptrtype>
3890             <struct>jvmtiArrayPrimitiveValueCallback</struct>
3891           </ptrtype>
3892           <description>
3893             The callback to be called to describe an
3894             array of primitive values.
3895           </description>
3896         </field>
3897         <field id="string_primitive_value_callback">
3898           <ptrtype>
3899             <struct>jvmtiStringPrimitiveValueCallback</struct>
3900           </ptrtype>
3901           <description>
3902             The callback to be called to describe a String value.
3903           </description>
3904         </field>
3905         <field id="reserved5">
3906           <ptrtype>
3907             <struct>jvmtiReservedCallback</struct>
3908           </ptrtype>
3909           <description>
3910             Reserved for future use..
3911           </description>
3912         </field>
3913         <field id="reserved6">
3914           <ptrtype>
3915             <struct>jvmtiReservedCallback</struct>
3916           </ptrtype>
3917           <description>
3918             Reserved for future use..
3919           </description>
3920         </field>
3921         <field id="reserved7">
3922           <ptrtype>
3923             <struct>jvmtiReservedCallback</struct>
3924           </ptrtype>
3925           <description>
3926             Reserved for future use..
3927           </description>
3928         </field>
3929         <field id="reserved8">
3930           <ptrtype>
3931             <struct>jvmtiReservedCallback</struct>
3932           </ptrtype>
3933           <description>
3934             Reserved for future use..
3935           </description>
3936         </field>
3937         <field id="reserved9">
3938           <ptrtype>
3939             <struct>jvmtiReservedCallback</struct>
3940           </ptrtype>
3941           <description>
3942             Reserved for future use..
3943           </description>
3944         </field>
3945         <field id="reserved10">
3946           <ptrtype>
3947             <struct>jvmtiReservedCallback</struct>
3948           </ptrtype>
3949           <description>
3950             Reserved for future use..
3951           </description>
3952         </field>
3953         <field id="reserved11">
3954           <ptrtype>
3955             <struct>jvmtiReservedCallback</struct>
3956           </ptrtype>
3957           <description>
3958             Reserved for future use..
3959           </description>
3960         </field>
3961         <field id="reserved12">
3962           <ptrtype>
3963             <struct>jvmtiReservedCallback</struct>
3964           </ptrtype>
3965           <description>
3966             Reserved for future use..
3967           </description>
3968         </field>
3969         <field id="reserved13">
3970           <ptrtype>
3971             <struct>jvmtiReservedCallback</struct>
3972           </ptrtype>
3973           <description>
3974             Reserved for future use..
3975           </description>
3976         </field>
3977         <field id="reserved14">
3978           <ptrtype>
3979             <struct>jvmtiReservedCallback</struct>
3980           </ptrtype>
3981           <description>
3982             Reserved for future use..
3983           </description>
3984         </field>
3985         <field id="reserved15">
3986           <ptrtype>
3987             <struct>jvmtiReservedCallback</struct>
3988           </ptrtype>
3989           <description>
3990             Reserved for future use..
3991           </description>
3992         </field>
3993       </typedef>
3994 
3995 
3996     <intro>
3997       <rationale>
3998         The heap dumping functionality (below) uses a callback
3999         for each object.  While it would seem that a buffered approach
4000         would provide better throughput, tests do
4001         not show this to be the case--possibly due to locality of
4002         memory reference or array access overhead.
4003       </rationale>
4004 
4005       <issue>
4006         Still under investigation as to if java.lang.ref references
4007         are reported as a different type of reference.
4008       </issue>
4009 
4010       <issue>
4011         Should or can an indication of the cost or relative cost of
4012         these operations be included?
4013       </issue>
4014 
4015     </intro>
4016 
4017     <callback id="jvmtiHeapIterationCallback" since="1.1">
4018       <jint/>
4019       <synopsis>Heap Iteration Callback</synopsis>
4020       <description>
4021         Agent supplied callback function.
4022         Describes (but does not pass in) an object in the heap.
4023         <p/>
4024         This function should return a bit vector of the desired
4025         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4026         This will determine if the entire iteration should be aborted
4027         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4028         <p/>
4029         See the <internallink id="heapCallbacks">heap callback
4030         function restrictions</internallink>.
4031       </description>
4032       <parameters>
4033         <param id="class_tag">
4034           <jlong/>
4035           <description>
4036             The tag of the class of object (zero if the class is not tagged).
4037             If the object represents a runtime class,
4038             the <code>class_tag</code> is the tag
4039             associated with <code>java.lang.Class</code>
4040             (zero if <code>java.lang.Class</code> is not tagged).
4041           </description>
4042         </param>
4043         <param id="size">
4044           <jlong/>
4045           <description>
4046             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
4047           </description>
4048         </param>
4049         <param id="tag_ptr">
4050           <outptr><jlong/></outptr>
4051           <description>
4052             The object tag value, or zero if the object is not tagged.
4053             To set the tag value to be associated with the object
4054             the agent sets the <code>jlong</code> pointed to by the parameter.
4055           </description>
4056         </param>
4057         <param id="length">
4058           <jint/>
4059           <description>
4060             If this object is an array, the length of the array. Otherwise negative one (-1).
4061           </description>
4062         </param>
4063         <param id="user_data">
4064           <outptr><void/></outptr>
4065           <description>
4066             The user supplied data that was passed into the iteration function.
4067           </description>
4068         </param>
4069       </parameters>
4070     </callback>
4071 
4072     <callback id="jvmtiHeapReferenceCallback" since="1.1">
4073       <jint/>
4074       <synopsis>Heap Reference Callback</synopsis>
4075       <description>
4076         Agent supplied callback function.
4077         Describes a reference from an object or the VM (the referrer) to another object
4078         (the referree) or a heap root to a referree.
4079         <p/>
4080         This function should return a bit vector of the desired
4081         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4082         This will determine if the objects referenced by the referree
4083         should be visited or if the entire iteration should be aborted.
4084         <p/>
4085         See the <internallink id="heapCallbacks">heap callback
4086         function restrictions</internallink>.
4087       </description>
4088       <parameters>
4089         <param id="reference_kind">
4090           <enum>jvmtiHeapReferenceKind</enum>
4091           <description>
4092             The kind of reference.
4093           </description>
4094         </param>
4095         <param id="reference_info">
4096           <inptr>
4097             <struct>jvmtiHeapReferenceInfo</struct>
4098           </inptr>
4099           <description>
4100             Details about the reference.
4101             Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is
4102             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
4103             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
4104             <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
4105             <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>,
4106             <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
4107             or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
4108             Otherwise <code>NULL</code>.
4109           </description>
4110         </param>
4111         <param id="class_tag">
4112           <jlong/>
4113           <description>
4114             The tag of the class of referree object (zero if the class is not tagged).
4115             If the referree object represents a runtime class,
4116             the <code>class_tag</code> is the tag
4117             associated with <code>java.lang.Class</code>
4118             (zero if <code>java.lang.Class</code> is not tagged).
4119           </description>
4120         </param>
4121         <param id="referrer_class_tag">
4122           <jlong/>
4123           <description>
4124             The tag of the class of the referrer object (zero if the class is not tagged
4125             or the referree is a heap root). If the referrer object represents a runtime
4126             class, the <code>referrer_class_tag</code> is the tag associated with
4127             the <code>java.lang.Class</code>
4128             (zero if <code>java.lang.Class</code> is not tagged).
4129           </description>
4130         </param>
4131         <param id="size">
4132           <jlong/>
4133           <description>
4134             Size of the referree object (in bytes).
4135             See <functionlink id="GetObjectSize"/>.
4136           </description>
4137         </param>
4138         <param id="tag_ptr">
4139           <outptr><jlong/></outptr>
4140           <description>
4141             Points to the referree object tag value, or zero if the object is not
4142             tagged.
4143             To set the tag value to be associated with the object
4144             the agent sets the <code>jlong</code> pointed to by the parameter.
4145           </description>
4146         </param>
4147         <param id="referrer_tag_ptr">
4148           <outptr><jlong/></outptr>
4149           <description>
4150             Points to the tag of the referrer object, or
4151             points to the zero if the referrer
4152             object is not tagged.
4153             <code>NULL</code> if the referrer in not an object (that is,
4154             this callback is reporting a heap root).
4155             To set the tag value to be associated with the referrer object
4156             the agent sets the <code>jlong</code> pointed to by the parameter.
4157             If this callback is reporting a reference from an object to itself,
4158             <code>referrer_tag_ptr == tag_ptr</code>.
4159           </description>
4160         </param>
4161         <param id="length">
4162           <jint/>
4163           <description>
4164             If this object is an array, the length of the array. Otherwise negative one (-1).
4165           </description>
4166         </param>
4167         <param id="user_data">
4168           <outptr><void/></outptr>
4169           <description>
4170             The user supplied data that was passed into the iteration function.
4171           </description>
4172         </param>
4173       </parameters>
4174     </callback>
4175 
4176     <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
4177       <jint/>
4178       <synopsis>Primitive Field Callback</synopsis>
4179       <description>
4180         Agent supplied callback function which
4181         describes a primitive field of an object (<i>the object</i>).
4182         A primitive field is a field whose type is a primitive type.
4183         This callback will describe a static field if the object is a class,
4184         and otherwise will describe an instance field.
4185         <p/>
4186         This function should return a bit vector of the desired
4187         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4188         This will determine if the entire iteration should be aborted
4189         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4190         <p/>
4191         See the <internallink id="heapCallbacks">heap callback
4192         function restrictions</internallink>.
4193       </description>
4194       <parameters>
4195         <param id="kind">
4196           <enum>jvmtiHeapReferenceKind</enum>
4197           <description>
4198             The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or
4199             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
4200           </description>
4201         </param>
4202         <param id="info">
4203           <inptr>
4204             <struct>jvmtiHeapReferenceInfo</struct>
4205           </inptr>
4206           <description>
4207             Which field (the field index).
4208           </description>
4209         </param>
4210         <param id="object_class_tag">
4211           <jlong/>
4212           <description>
4213             The tag of the class of the object (zero if the class is not tagged).
4214             If the object represents a runtime class, the
4215             <code>object_class_tag</code> is the tag
4216             associated with <code>java.lang.Class</code>
4217             (zero if <code>java.lang.Class</code> is not tagged).
4218           </description>
4219         </param>
4220         <param id="object_tag_ptr">
4221           <outptr><jlong/></outptr>
4222           <description>
4223             Points to the tag of the object, or zero if the object is not
4224             tagged.
4225             To set the tag value to be associated with the object
4226             the agent sets the <code>jlong</code> pointed to by the parameter.
4227           </description>
4228         </param>
4229         <param id="value">
4230           <jvalue/>
4231           <description>
4232             The value of the field.
4233           </description>
4234         </param>
4235         <param id="value_type">
4236           <enum>jvmtiPrimitiveType</enum>
4237           <description>
4238             The type of the field.
4239           </description>
4240         </param>
4241         <param id="user_data">
4242           <outptr><void/></outptr>
4243           <description>
4244             The user supplied data that was passed into the iteration function.
4245           </description>
4246         </param>
4247       </parameters>
4248     </callback>
4249 
4250     <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
4251       <jint/>
4252       <synopsis>Array Primitive Value Callback</synopsis>
4253       <description>
4254         Agent supplied callback function.
4255         Describes the values in an array of a primitive type.
4256         <p/>
4257         This function should return a bit vector of the desired
4258         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4259         This will determine if the entire iteration should be aborted
4260         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4261         <p/>
4262         See the <internallink id="heapCallbacks">heap callback
4263         function restrictions</internallink>.
4264       </description>
4265       <parameters>
4266         <param id="class_tag">
4267           <jlong/>
4268           <description>
4269             The tag of the class of the array object (zero if the class is not tagged).
4270           </description>
4271         </param>
4272         <param id="size">
4273           <jlong/>
4274           <description>
4275             Size of the array (in bytes).
4276             See <functionlink id="GetObjectSize"/>.
4277           </description>
4278         </param>
4279         <param id="tag_ptr">
4280           <outptr><jlong/></outptr>
4281           <description>
4282             Points to the tag of the array object, or zero if the object is not
4283             tagged.
4284             To set the tag value to be associated with the object
4285             the agent sets the <code>jlong</code> pointed to by the parameter.
4286           </description>
4287         </param>
4288         <param id="element_count">
4289           <jint/>
4290           <description>
4291             The length of the primitive array.
4292           </description>
4293         </param>
4294         <param id="element_type">
4295           <enum>jvmtiPrimitiveType</enum>
4296           <description>
4297             The type of the elements of the array.
4298           </description>
4299         </param>
4300         <param id="elements">
4301           <vmbuf><void/></vmbuf>
4302           <description>
4303             The elements of the array in a packed array of <code>element_count</code>
4304             items of <code>element_type</code> size each.
4305           </description>
4306         </param>
4307         <param id="user_data">
4308           <outptr><void/></outptr>
4309           <description>
4310             The user supplied data that was passed into the iteration function.
4311           </description>
4312         </param>
4313       </parameters>
4314     </callback>
4315 
4316     <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
4317       <jint/>
4318       <synopsis>String Primitive Value Callback</synopsis>
4319       <description>
4320         Agent supplied callback function.
4321         Describes the value of a java.lang.String.
4322         <p/>
4323         This function should return a bit vector of the desired
4324         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4325         This will determine if the entire iteration should be aborted
4326         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4327         <p/>
4328         See the <internallink id="heapCallbacks">heap callback
4329         function restrictions</internallink>.
4330       </description>
4331       <parameters>
4332         <param id="class_tag">
4333           <jlong/>
4334           <description>
4335             The tag of the class of the String class (zero if the class is not tagged).
4336             <issue>Is this needed?</issue>
4337           </description>
4338         </param>
4339         <param id="size">
4340           <jlong/>
4341           <description>
4342             Size of the string (in bytes).
4343             See <functionlink id="GetObjectSize"/>.
4344           </description>
4345         </param>
4346         <param id="tag_ptr">
4347           <outptr><jlong/></outptr>
4348           <description>
4349             Points to the tag of the String object, or zero if the object is not
4350             tagged.
4351             To set the tag value to be associated with the object
4352             the agent sets the <code>jlong</code> pointed to by the parameter.
4353           </description>
4354         </param>
4355         <param id="value">
4356           <vmbuf><jchar/></vmbuf>
4357           <description>
4358             The value of the String, encoded as a Unicode string.
4359           </description>
4360         </param>
4361         <param id="value_length">
4362           <jint/>
4363           <description>
4364             The length of the string.
4365             The length is equal to the number of 16-bit Unicode
4366             characters in the string.
4367           </description>
4368         </param>
4369         <param id="user_data">
4370           <outptr><void/></outptr>
4371           <description>
4372             The user supplied data that was passed into the iteration function.
4373           </description>
4374         </param>
4375       </parameters>
4376     </callback>
4377 
4378 
4379     <callback id="jvmtiReservedCallback" since="1.1">
4380       <jint/>
4381       <synopsis>reserved for future use Callback</synopsis>
4382       <description>
4383         Placeholder -- reserved for future use.
4384       </description>
4385       <parameters>
4386       </parameters>
4387     </callback>
4388 
4389     <function id="FollowReferences" num="115" since="1.1">
4390       <synopsis>Follow References</synopsis>
4391       <description>
4392         This function initiates a traversal over the objects that are
4393         directly and indirectly reachable from the specified object or,
4394         if <code>initial_object</code> is not specified, all objects
4395         reachable from the heap roots.
4396         The heap root are the set of system classes,
4397         JNI globals, references from thread stacks, and other objects used as roots
4398         for the purposes of garbage collection.
4399         <p/>
4400         This function operates by traversing the reference graph.
4401         Let <i>A</i>, <i>B</i>, ... represent objects.
4402         When a reference from <i>A</i> to <i>B</i> is traversed,
4403         when a reference from a heap root to <i>B</i> is traversed,
4404         or when <i>B</i> is specified as the <paramlink id="initial_object"/>,
4405         then <i>B</i> is said to be <i>visited</i>.
4406         A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i>
4407         is visited.
4408         References are reported in the same order that the references are traversed.
4409         Object references are reported by invoking the agent supplied
4410         callback function <functionlink id="jvmtiHeapReferenceCallback"/>.
4411         In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known
4412         as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
4413         The callback is invoked exactly once for each reference from a referrer;
4414         this is true even if there are reference cycles or multiple paths to
4415         the referrer.
4416         There may be more than one reference between a referrer and a referree,
4417         each reference is reported.
4418         These references may be distinguished by examining the
4419         <datalink
4420          id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
4421          and
4422         <datalink
4423          id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
4424         parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
4425         <p/>
4426         This function reports a Java programming language view of object references,
4427         not a virtual machine implementation view. The following object references
4428         are reported when they are non-null:
4429         <ul>
4430           <li>Instance objects report references to each non-primitive instance fields
4431               (including inherited fields).</li>
4432           <li>Instance objects report a reference to the object type (class).</li>
4433           <li>Classes report a reference to the superclass and directly
4434               implemented/extended interfaces.</li>
4435           <li>Classes report a reference to the class loader, protection domain,
4436               signers, and resolved entries in the constant pool.</li>
4437           <li>Classes report a reference to each directly declared non-primitive
4438               static field.</li>
4439           <li>Arrays report a reference to the array type (class) and each
4440               array element.</li>
4441           <li>Primitive arrays report a reference to the array type.</li>
4442         </ul>
4443         <p/>
4444         This function can also be used to examine primitive (non-object) values.
4445         The primitive value of an array or String
4446         is reported after the object has been visited;
4447         it is reported by invoking the agent supplied callback function
4448         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4449         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4450         A primitive field
4451         is reported after the object with that field is visited;
4452         it is reported by invoking the agent supplied callback function
4453         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4454         <p/>
4455         Whether a callback is provided or is <code>NULL</code> only determines
4456         whether the callback will be invoked, it does not influence
4457         which objects are visited nor does it influence whether other callbacks
4458         will be invoked.
4459         However, the
4460         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
4461         returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4462         do determine if the objects referenced by the
4463         current object as visited.
4464         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4465         and <paramlink id="klass"/> provided as parameters to this function
4466         do not control which objects are visited but they do control which
4467         objects and primitive values are reported by the callbacks.
4468         For example, if the only callback that was set is
4469         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4470         is set to the array of bytes class, then only arrays of byte will be
4471         reported.
4472         The table below summarizes this:
4473         <p/>
4474         <table>
4475           <tr>
4476             <th/>
4477             <th>
4478               Controls objects visited
4479             </th>
4480             <th>
4481               Controls objects reported
4482             </th>
4483             <th>
4484               Controls primitives reported
4485             </th>
4486           </tr>
4487           <tr>
4488             <th align="left">
4489               the
4490               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4491               returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4492             </th>
4493             <td>
4494               <b>Yes</b>
4495             </td>
4496             <td>
4497               <b>Yes</b>, since visits are controlled
4498             </td>
4499             <td>
4500               <b>Yes</b>, since visits are controlled
4501             </td>
4502           </tr>
4503           <tr>
4504             <th align="left">
4505               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4506               in <paramlink id="callbacks"/> set
4507             </th>
4508             <td>
4509               No
4510             </td>
4511             <td>
4512               <b>Yes</b>
4513             </td>
4514             <td>
4515               No
4516             </td>
4517           </tr>
4518           <tr>
4519             <th align="left">
4520               <paramlink id="heap_filter"/>
4521             </th>
4522             <td>
4523               No
4524             </td>
4525             <td>
4526               <b>Yes</b>
4527             </td>
4528             <td>
4529               <b>Yes</b>
4530             </td>
4531           </tr>
4532           <tr>
4533             <th align="left">
4534               <paramlink id="klass"/>
4535             </th>
4536             <td>
4537               No
4538             </td>
4539             <td>
4540               <b>Yes</b>
4541             </td>
4542             <td>
4543               <b>Yes</b>
4544             </td>
4545           </tr>
4546         </table>
4547         <p/>
4548         During the execution of this function the state of the heap
4549         does not change: no objects are allocated, no objects are
4550         garbage collected, and the state of objects (including
4551         held values) does not change.
4552         As a result, threads executing Java
4553         programming language code, threads attempting to resume the
4554         execution of Java programming language code, and threads
4555         attempting to execute JNI functions are typically stalled.
4556       </description>
4557       <origin>new</origin>
4558       <capabilities>
4559         <required id="can_tag_objects"></required>
4560       </capabilities>
4561       <parameters>
4562         <param id="heap_filter">
4563           <jint/>
4564           <description>
4565             This bit vector of
4566             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4567             restricts the objects for which the callback function is called.
4568             This applies to both the object and primitive callbacks.
4569           </description>
4570         </param>
4571         <param id="klass">
4572           <ptrtype>
4573             <jclass/>
4574             <nullok>callbacks are not limited to instances of a particular
4575                     class</nullok>
4576           </ptrtype>
4577           <description>
4578             Callbacks are only reported when the object is an instance of
4579             this class.
4580             Objects which are instances of a subclass of <code>klass</code>
4581             are not reported.
4582             If <code>klass</code> is an interface, no objects are reported.
4583             This applies to both the object and primitive callbacks.
4584           </description>
4585         </param>
4586         <param id="initial_object">
4587           <ptrtype>
4588             <jobject/>
4589             <nullok>references are followed from the heap roots</nullok>
4590           </ptrtype>
4591           <description>
4592             The object to follow
4593           </description>
4594         </param>
4595         <param id="callbacks">
4596           <inptr>
4597             <struct>jvmtiHeapCallbacks</struct>
4598           </inptr>
4599           <description>
4600             Structure defining the set of callback functions.
4601           </description>
4602         </param>
4603         <param id="user_data">
4604           <inbuf>
4605             <void/>
4606             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4607           </inbuf>
4608           <description>
4609             User supplied data to be passed to the callback.
4610           </description>
4611         </param>
4612       </parameters>
4613       <errors>
4614         <error id="JVMTI_ERROR_INVALID_CLASS">
4615           <paramlink id="klass"/> is not a valid class.
4616         </error>
4617         <error id="JVMTI_ERROR_INVALID_OBJECT">
4618           <paramlink id="initial_object"/> is not a valid object.
4619         </error>
4620       </errors>
4621     </function>
4622 
4623 
4624     <function id="IterateThroughHeap" num="116" since="1.1">
4625       <synopsis>Iterate Through Heap</synopsis>
4626       <description>
4627         Initiate an iteration over all objects in the heap.
4628         This includes both reachable and
4629         unreachable objects. Objects are visited in no particular order.
4630         <p/>
4631         Heap objects are reported by invoking the agent supplied
4632         callback function <functionlink id="jvmtiHeapIterationCallback"/>.
4633         References between objects are not reported.
4634         If only reachable objects are desired, or if object reference information
4635         is needed, use <functionlink id="FollowReferences"/>.
4636         <p/>
4637         This function can also be used to examine primitive (non-object) values.
4638         The primitive value of an array or String
4639         is reported after the object has been visited;
4640         it is reported by invoking the agent supplied callback function
4641         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4642         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4643         A primitive field
4644         is reported after the object with that field is visited;
4645         it is reported by invoking the agent supplied
4646         callback function
4647         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4648         <p/>
4649         Unless the iteration is aborted by the
4650         <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4651         returned by a callback, all objects in the heap are visited.
4652         Whether a callback is provided or is <code>NULL</code> only determines
4653         whether the callback will be invoked, it does not influence
4654         which objects are visited nor does it influence whether other callbacks
4655         will be invoked.
4656         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4657         and <paramlink id="klass"/> provided as parameters to this function
4658         do not control which objects are visited but they do control which
4659         objects and primitive values are reported by the callbacks.
4660         For example, if the only callback that was set is
4661         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4662         is set to the array of bytes class, then only arrays of byte will be
4663         reported. The table below summarizes this (contrast this with
4664         <functionlink id="FollowReferences"/>):
4665         <p/>
4666         <table>
4667           <tr>
4668             <th/>
4669             <th>
4670               Controls objects visited
4671             </th>
4672             <th>
4673               Controls objects reported
4674             </th>
4675             <th>
4676               Controls primitives reported
4677             </th>
4678           </tr>
4679           <tr>
4680             <th align="left">
4681               the
4682               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4683               returned by <functionlink id="jvmtiHeapIterationCallback"/>
4684             </th>
4685             <td>
4686               No<br/>(unless they abort the iteration)
4687             </td>
4688             <td>
4689               No<br/>(unless they abort the iteration)
4690             </td>
4691             <td>
4692               No<br/>(unless they abort the iteration)
4693             </td>
4694           </tr>
4695           <tr>
4696             <th align="left">
4697               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4698               in <paramlink id="callbacks"/> set
4699             </th>
4700             <td>
4701               No
4702             </td>
4703             <td>
4704               <b>Yes</b>
4705             </td>
4706             <td>
4707               No
4708             </td>
4709           </tr>
4710           <tr>
4711             <th align="left">
4712               <paramlink id="heap_filter"/>
4713             </th>
4714             <td>
4715               No
4716             </td>
4717             <td>
4718               <b>Yes</b>
4719             </td>
4720             <td>
4721               <b>Yes</b>
4722             </td>
4723           </tr>
4724           <tr>
4725             <th align="left">
4726               <paramlink id="klass"/>
4727             </th>
4728             <td>
4729               No
4730             </td>
4731             <td>
4732               <b>Yes</b>
4733             </td>
4734             <td>
4735               <b>Yes</b>
4736             </td>
4737           </tr>
4738         </table>
4739         <p/>
4740         During the execution of this function the state of the heap
4741         does not change: no objects are allocated, no objects are
4742         garbage collected, and the state of objects (including
4743         held values) does not change.
4744         As a result, threads executing Java
4745         programming language code, threads attempting to resume the
4746         execution of Java programming language code, and threads
4747         attempting to execute JNI functions are typically stalled.
4748       </description>
4749       <origin>new</origin>
4750       <capabilities>
4751         <required id="can_tag_objects"></required>
4752       </capabilities>
4753       <parameters>
4754         <param id="heap_filter">
4755           <jint/>
4756           <description>
4757             This bit vector of
4758             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4759             restricts the objects for which the callback function is called.
4760             This applies to both the object and primitive callbacks.
4761           </description>
4762         </param>
4763         <param id="klass">
4764           <ptrtype>
4765             <jclass/>
4766             <nullok>callbacks are not limited to instances of a particular class</nullok>
4767           </ptrtype>
4768           <description>
4769             Callbacks are only reported when the object is an instance of
4770             this class.
4771             Objects which are instances of a subclass of <code>klass</code>
4772             are not reported.
4773             If <code>klass</code> is an interface, no objects are reported.
4774             This applies to both the object and primitive callbacks.
4775           </description>
4776         </param>
4777         <param id="callbacks">
4778           <inptr>
4779             <struct>jvmtiHeapCallbacks</struct>
4780           </inptr>
4781           <description>
4782             Structure defining the set callback functions.
4783           </description>
4784         </param>
4785         <param id="user_data">
4786           <inbuf>
4787             <void/>
4788             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4789           </inbuf>
4790           <description>
4791             User supplied data to be passed to the callback.
4792           </description>
4793         </param>
4794       </parameters>
4795       <errors>
4796         <error id="JVMTI_ERROR_INVALID_CLASS">
4797           <paramlink id="klass"/> is not a valid class.
4798         </error>
4799       </errors>
4800     </function>
4801 
4802     <function id="GetTag" phase="start" num="106">
4803       <synopsis>Get Tag</synopsis>
4804       <description>
4805         Retrieve the tag associated with an object.
4806         The tag is a long value typically used to store a
4807         unique identifier or pointer to object information.
4808         The tag is set with
4809         <functionlink id="SetTag"></functionlink>.
4810         Objects for which no tags have been set return a
4811         tag value of zero.
4812       </description>
4813       <origin>new</origin>
4814       <capabilities>
4815         <required id="can_tag_objects"></required>
4816       </capabilities>
4817       <parameters>
4818         <param id="object">
4819           <jobject/>
4820             <description>
4821               The object whose tag is to be retrieved.
4822             </description>
4823         </param>
4824         <param id="tag_ptr">
4825           <outptr><jlong/></outptr>
4826           <description>
4827             On return, the referenced long is set to the value
4828             of the tag.
4829           </description>
4830         </param>
4831       </parameters>
4832       <errors>
4833       </errors>
4834     </function>
4835 
4836     <function id="SetTag" phase="start" num="107">
4837       <synopsis>Set Tag</synopsis>
4838       <description>
4839         Set the tag associated with an object.
4840         The tag is a long value typically used to store a
4841         unique identifier or pointer to object information.
4842         The tag is visible with
4843         <functionlink id="GetTag"></functionlink>.
4844       </description>
4845       <origin>new</origin>
4846       <capabilities>
4847         <required id="can_tag_objects"></required>
4848       </capabilities>
4849       <parameters>
4850         <param id="object">
4851           <jobject/>
4852             <description>
4853               The object whose tag is to be set.
4854             </description>
4855         </param>
4856         <param id="tag">
4857           <jlong/>
4858           <description>
4859             The new value of the tag.
4860           </description>
4861         </param>
4862       </parameters>
4863       <errors>
4864       </errors>
4865     </function>
4866 
4867     <function id="GetObjectsWithTags" num="114">
4868       <synopsis>Get Objects With Tags</synopsis>
4869       <description>
4870         Return objects in the heap with the specified tags.
4871         The format is parallel arrays of objects and tags.
4872       </description>
4873       <origin>new</origin>
4874       <capabilities>
4875         <required id="can_tag_objects"></required>
4876       </capabilities>
4877       <parameters>
4878         <param id="tag_count">
4879           <jint min="0"/>
4880             <description>
4881               Number of tags to scan for.
4882             </description>
4883         </param>
4884         <param id="tags">
4885           <inbuf incount="tag_count">
4886             <jlong/>
4887           </inbuf>
4888             <description>
4889               Scan for objects with these tags.
4890               Zero is not permitted in this array.
4891             </description>
4892         </param>
4893         <param id="count_ptr">
4894           <outptr>
4895             <jint/>
4896           </outptr>
4897             <description>
4898               Return the number of objects with any of the tags
4899               in <paramlink id="tags"/>.
4900             </description>
4901         </param>
4902         <param id="object_result_ptr">
4903           <allocbuf outcount="count_ptr">
4904             <jobject/>
4905             <nullok>this information is not returned</nullok>
4906           </allocbuf>
4907             <description>
4908               Returns the array of objects with any of the tags
4909               in <paramlink id="tags"/>.
4910             </description>
4911         </param>
4912         <param id="tag_result_ptr">
4913           <allocbuf outcount="count_ptr">
4914             <jlong/>
4915             <nullok>this information is not returned</nullok>
4916           </allocbuf>
4917             <description>
4918               For each object in <paramlink id="object_result_ptr"/>,
4919               return the tag at the corresponding index.
4920             </description>
4921         </param>
4922       </parameters>
4923       <errors>
4924         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
4925           Zero is present in <paramlink id="tags"></paramlink>.
4926         </error>
4927       </errors>
4928     </function>
4929 
4930     <function id="ForceGarbageCollection" num="108">
4931       <synopsis>Force Garbage Collection</synopsis>
4932       <description>
4933         Force the VM to perform a garbage collection.
4934         The garbage collection is as complete as possible.
4935         This function does not cause finalizers to be run.
4936         This function does not return until the garbage collection
4937         is finished.
4938         <p/>
4939         Although garbage collection is as complete
4940         as possible there is no guarantee that all
4941         <eventlink id="ObjectFree"/>
4942         events will have been
4943         sent by the time that this function
4944         returns. In particular, an object may be
4945         prevented from being freed because it
4946         is awaiting finalization.
4947       </description>
4948       <origin>new</origin>
4949       <capabilities>
4950       </capabilities>
4951       <parameters>
4952       </parameters>
4953       <errors>
4954       </errors>
4955     </function>
4956 
4957 
4958   </category>
4959 
4960   <category id="Heap_1_0" label="Heap (1.0)">
4961     <intro>
4962       <b>
4963         These functions and data types were introduced in the original
4964         <jvmti/> version 1.0 and have been superseded by more
4965       </b>
4966       <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
4967       <b>
4968         which:
4969       </b>
4970       <ul>
4971         <li>
4972           <b>
4973             Allow access to primitive values (the value of Strings, arrays,
4974             and primitive fields)
4975           </b>
4976         </li>
4977         <li>
4978           <b>
4979             Allow the tag of the referrer to be set, thus enabling more
4980             efficient localized reference graph building
4981           </b>
4982         </li>
4983         <li>
4984           <b>
4985             Provide more extensive filtering abilities
4986           </b>
4987         </li>
4988         <li>
4989           <b>
4990             Are extensible, allowing their abilities to grow in future versions of <jvmti/>
4991           </b>
4992         </li>
4993       </ul>
4994       <p/>
4995       <b>Please use the </b>
4996       <internallink id="Heap"><b>current Heap functions</b></internallink>.
4997         <p/>
4998         <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
4999           <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
5000             Tagged objects only.
5001           </constant>
5002           <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
5003             Untagged objects only.
5004           </constant>
5005           <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
5006             Either tagged or untagged objects.
5007           </constant>
5008         </constants>
5009 
5010         <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
5011           <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
5012             JNI global reference.
5013           </constant>
5014           <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
5015             System class.
5016           </constant>
5017           <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
5018             Monitor.
5019           </constant>
5020           <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
5021             Stack local.
5022           </constant>
5023           <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
5024             JNI local reference.
5025           </constant>
5026           <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
5027             Thread.
5028           </constant>
5029           <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
5030             Other.
5031           </constant>
5032         </constants>
5033 
5034         <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
5035           <constant id="JVMTI_REFERENCE_CLASS" num="1">
5036             Reference from an object to its class.
5037           </constant>
5038           <constant id="JVMTI_REFERENCE_FIELD" num="2">
5039             Reference from an object to the value of one of its instance fields.
5040             For references of this kind the <code>referrer_index</code>
5041             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5042             jvmtiObjectReferenceCallback</internallink> is the index of the
5043             the instance field. The index is based on the order of all the
5044             object's fields. This includes all fields of the directly declared
5045             static and instance fields in the class, and includes all fields (both
5046             public and private) fields declared in superclasses and superinterfaces.
5047             The index is thus calculated by summing the index of the field in the directly
5048             declared class (see <functionlink id="GetClassFields"/>), with the total
5049             number of fields (both public and private) declared in all superclasses
5050             and superinterfaces. The index starts at zero.
5051           </constant>
5052           <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
5053             Reference from an array to one of its elements.
5054             For references of this kind the <code>referrer_index</code>
5055             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5056             jvmtiObjectReferenceCallback</internallink> is the array index.
5057           </constant>
5058           <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
5059             Reference from a class to its class loader.
5060           </constant>
5061           <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
5062             Reference from a class to its signers array.
5063           </constant>
5064           <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
5065             Reference from a class to its protection domain.
5066           </constant>
5067           <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
5068             Reference from a class to one of its interfaces.
5069           </constant>
5070           <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
5071             Reference from a class to the value of one of its static fields.
5072             For references of this kind the <code>referrer_index</code>
5073             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5074             jvmtiObjectReferenceCallback</internallink> is the index of the
5075             the static field. The index is based on the order of all the
5076             object's fields. This includes all fields of the directly declared
5077             static and instance fields in the class, and includes all fields (both
5078             public and private) fields declared in superclasses and superinterfaces.
5079             The index is thus calculated by summing the index of the field in the directly
5080             declared class (see <functionlink id="GetClassFields"/>), with the total
5081             number of fields (both public and private) declared in all superclasses
5082             and superinterfaces. The index starts at zero.
5083             Note: this definition differs from that in the <jvmti/> 1.0 Specification.
5084             <rationale>No known implementations used the 1.0 definition.</rationale>
5085           </constant>
5086           <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
5087             Reference from a class to a resolved entry in the constant pool.
5088             For references of this kind the <code>referrer_index</code>
5089             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5090             jvmtiObjectReferenceCallback</internallink> is the index into
5091             constant pool table of the class, starting at 1. See
5092             <vmspec chapter="4.4"/>.
5093           </constant>
5094         </constants>
5095 
5096         <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
5097           <constant id="JVMTI_ITERATION_CONTINUE" num="1">
5098             Continue the iteration.
5099             If this is a reference iteration, follow the references of this object.
5100           </constant>
5101           <constant id="JVMTI_ITERATION_IGNORE" num="2">
5102             Continue the iteration.
5103             If this is a reference iteration, ignore the references of this object.
5104           </constant>
5105           <constant id="JVMTI_ITERATION_ABORT" num="0">
5106             Abort the iteration.
5107           </constant>
5108         </constants>
5109     </intro>
5110 
5111     <callback id="jvmtiHeapObjectCallback">
5112       <enum>jvmtiIterationControl</enum>
5113       <synopsis>Heap Object Callback</synopsis>
5114       <description>
5115         Agent supplied callback function.
5116         Describes (but does not pass in) an object in the heap.
5117         <p/>
5118         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5119         or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5120         <p/>
5121         See the <internallink id="heapCallbacks">heap callback
5122         function restrictions</internallink>.
5123       </description>
5124       <parameters>
5125         <param id="class_tag">
5126           <jlong/>
5127           <description>
5128             The tag of the class of object (zero if the class is not tagged).
5129             If the object represents a runtime class,
5130             the <code>class_tag</code> is the tag
5131             associated with <code>java.lang.Class</code>
5132             (zero if <code>java.lang.Class</code> is not tagged).
5133           </description>
5134         </param>
5135         <param id="size">
5136           <jlong/>
5137           <description>
5138             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5139           </description>
5140         </param>
5141         <param id="tag_ptr">
5142           <outptr><jlong/></outptr>
5143           <description>
5144             The object tag value, or zero if the object is not tagged.
5145             To set the tag value to be associated with the object
5146             the agent sets the <code>jlong</code> pointed to by the parameter.
5147           </description>
5148         </param>
5149         <param id="user_data">
5150           <outptr><void/></outptr>
5151           <description>
5152             The user supplied data that was passed into the iteration function.
5153           </description>
5154         </param>
5155       </parameters>
5156     </callback>
5157 
5158     <callback id="jvmtiHeapRootCallback">
5159       <enum>jvmtiIterationControl</enum>
5160       <synopsis>Heap Root Object Callback</synopsis>
5161       <description>
5162         Agent supplied callback function.
5163         Describes (but does not pass in) an object that is a root for the purposes
5164         of garbage collection.
5165         <p/>
5166         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5167         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5168         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5169         <p/>
5170         See the <internallink id="heapCallbacks">heap callback
5171         function restrictions</internallink>.
5172       </description>
5173       <parameters>
5174         <param id="root_kind">
5175           <enum>jvmtiHeapRootKind</enum>
5176           <description>
5177             The kind of heap root.
5178           </description>
5179         </param>
5180         <param id="class_tag">
5181           <jlong/>
5182           <description>
5183             The tag of the class of object (zero if the class is not tagged).
5184             If the object represents a runtime class, the <code>class_tag</code> is the tag
5185             associated with <code>java.lang.Class</code>
5186             (zero if <code>java.lang.Class</code> is not tagged).
5187           </description>
5188         </param>
5189         <param id="size">
5190           <jlong/>
5191           <description>
5192             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5193           </description>
5194         </param>
5195         <param id="tag_ptr">
5196           <outptr><jlong/></outptr>
5197           <description>
5198             The object tag value, or zero if the object is not tagged.
5199             To set the tag value to be associated with the object
5200             the agent sets the <code>jlong</code> pointed to by the parameter.
5201           </description>
5202         </param>
5203         <param id="user_data">
5204           <outptr><void/></outptr>
5205           <description>
5206             The user supplied data that was passed into the iteration function.
5207           </description>
5208         </param>
5209       </parameters>
5210     </callback>
5211 
5212     <callback id="jvmtiStackReferenceCallback">
5213       <enum>jvmtiIterationControl</enum>
5214       <synopsis>Stack Reference Object Callback</synopsis>
5215       <description>
5216         Agent supplied callback function.
5217         Describes (but does not pass in) an object on the stack that is a root for
5218         the purposes of garbage collection.
5219         <p/>
5220         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5221         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5222         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5223         <p/>
5224         See the <internallink id="heapCallbacks">heap callback
5225         function restrictions</internallink>.
5226       </description>
5227       <parameters>
5228         <param id="root_kind">
5229           <enum>jvmtiHeapRootKind</enum>
5230           <description>
5231             The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5232             <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
5233           </description>
5234         </param>
5235         <param id="class_tag">
5236           <jlong/>
5237           <description>
5238            The tag of the class of object (zero if the class is not tagged).
5239            If the object represents a runtime class, the  <code>class_tag</code> is the tag
5240            associated with <code>java.lang.Class</code>
5241            (zero if <code>java.lang.Class</code> is not tagged).
5242           </description>
5243         </param>
5244         <param id="size">
5245           <jlong/>
5246           <description>
5247             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5248           </description>
5249         </param>
5250         <param id="tag_ptr">
5251           <outptr><jlong/></outptr>
5252           <description>
5253             The object tag value, or zero if the object is not tagged.
5254             To set the tag value to be associated with the object
5255             the agent sets the <code>jlong</code> pointed to by the parameter.
5256           </description>
5257         </param>
5258         <param id="thread_tag">
5259           <jlong/>
5260           <description>
5261             The tag of the thread corresponding to this stack, zero if not tagged.
5262           </description>
5263         </param>
5264         <param id="depth">
5265           <jint/>
5266           <description>
5267             The depth of the frame.
5268           </description>
5269         </param>
5270         <param id="method">
5271           <jmethodID/>
5272           <description>
5273             The method executing in this frame.
5274           </description>
5275         </param>
5276         <param id="slot">
5277           <jint/>
5278           <description>
5279             The slot number.
5280           </description>
5281         </param>
5282         <param id="user_data">
5283           <outptr><void/></outptr>
5284           <description>
5285             The user supplied data that was passed into the iteration function.
5286           </description>
5287         </param>
5288       </parameters>
5289     </callback>
5290 
5291     <callback id="jvmtiObjectReferenceCallback">
5292       <enum>jvmtiIterationControl</enum>
5293       <synopsis>Object Reference Callback</synopsis>
5294       <description>
5295         Agent supplied callback function.
5296         Describes a reference from an object (the referrer) to another object
5297         (the referree).
5298         <p/>
5299         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5300         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5301         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5302         <p/>
5303         See the <internallink id="heapCallbacks">heap callback
5304         function restrictions</internallink>.
5305       </description>
5306       <parameters>
5307         <param id="reference_kind">
5308           <enum>jvmtiObjectReferenceKind</enum>
5309           <description>
5310             The type of reference.
5311           </description>
5312         </param>
5313         <param id="class_tag">
5314           <jlong/>
5315           <description>
5316             The tag of the class of referree object (zero if the class is not tagged).
5317             If the referree object represents a runtime class,
5318             the  <code>class_tag</code> is the tag
5319             associated with <code>java.lang.Class</code>
5320             (zero if <code>java.lang.Class</code> is not tagged).
5321           </description>
5322         </param>
5323         <param id="size">
5324           <jlong/>
5325           <description>
5326             Size of the referree object (in bytes).
5327             See <functionlink id="GetObjectSize"/>.
5328           </description>
5329         </param>
5330         <param id="tag_ptr">
5331           <outptr><jlong/></outptr>
5332           <description>
5333             The referree object tag value, or zero if the object is not
5334             tagged.
5335             To set the tag value to be associated with the object
5336             the agent sets the <code>jlong</code> pointed to by the parameter.
5337           </description>
5338         </param>
5339         <param id="referrer_tag">
5340           <jlong/>
5341           <description>
5342             The tag of the referrer object, or zero if the referrer
5343             object is not tagged.
5344           </description>
5345         </param>
5346         <param id="referrer_index">
5347           <jint/>
5348           <description>
5349             For references of type <code>JVMTI_REFERENCE_FIELD</code> or
5350             <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
5351             of the field in the referrer object. The index is based on the
5352             order of all the object's fields - see <internallink
5353             id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
5354             or <internallink
5355             id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
5356             </internallink> for further description.
5357             <p/>
5358             For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
5359             the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
5360             JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
5361             <p/>
5362             For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
5363             the index into the constant pool of the class - see
5364             <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
5365             JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further
5366             description.
5367             <p/>
5368             For references of other kinds the <code>referrer_index</code> is
5369             <code>-1</code>.
5370           </description>
5371         </param>
5372         <param id="user_data">
5373           <outptr><void/></outptr>
5374           <description>
5375             The user supplied data that was passed into the iteration function.
5376           </description>
5377         </param>
5378       </parameters>
5379     </callback>
5380 
5381     <function id="IterateOverObjectsReachableFromObject" num="109">
5382       <synopsis>Iterate Over Objects Reachable From Object</synopsis>
5383       <description>
5384         This function iterates over all objects that are directly
5385         and indirectly reachable from the specified object.
5386         For each object <i>A</i> (known
5387         as the referrer) with a reference to object <i>B</i> the specified
5388         callback function is called to describe the object reference.
5389         The callback is called exactly once for each reference from a referrer;
5390         this is true even if there are reference cycles or multiple paths to
5391         the referrer.
5392         There may be more than one reference between a referrer and a referree,
5393         These may be distinguished by the
5394         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5395         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5396         The callback for an object will always occur after the callback for
5397         its referrer.
5398         <p/>
5399         See <functionlink id="FollowReferences"/> for the object
5400         references which are reported.
5401         <p/>
5402         During the execution of this function the state of the heap
5403         does not change: no objects are allocated, no objects are
5404         garbage collected, and the state of objects (including
5405         held values) does not change.
5406         As a result, threads executing Java
5407         programming language code, threads attempting to resume the
5408         execution of Java programming language code, and threads
5409         attempting to execute JNI functions are typically stalled.
5410       </description>
5411       <origin>new</origin>
5412       <capabilities>
5413         <required id="can_tag_objects"></required>
5414       </capabilities>
5415       <parameters>
5416         <param id="object">
5417           <jobject/>
5418             <description>
5419               The object
5420             </description>
5421         </param>
5422         <param id="object_reference_callback">
5423           <ptrtype>
5424             <struct>jvmtiObjectReferenceCallback</struct>
5425           </ptrtype>
5426             <description>
5427               The callback to be called to describe each
5428               object reference.
5429             </description>
5430         </param>
5431         <param id="user_data">
5432           <inbuf>
5433             <void/>
5434             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5435           </inbuf>
5436           <description>
5437             User supplied data to be passed to the callback.
5438           </description>
5439         </param>
5440       </parameters>
5441       <errors>
5442       </errors>
5443     </function>
5444 
5445     <function id="IterateOverReachableObjects" num="110">
5446       <synopsis>Iterate Over Reachable Objects</synopsis>
5447       <description>
5448         This function iterates over the root objects and all objects that
5449         are directly and indirectly reachable from the root objects.
5450         The root objects comprise the set of system classes,
5451         JNI globals, references from thread stacks, and other objects used as roots
5452         for the purposes of garbage collection.
5453         <p/>
5454         For each root the <paramlink id="heap_root_callback"></paramlink>
5455         or <paramlink id="stack_ref_callback"></paramlink> callback is called.
5456         An object can be a root object for more than one reason and in that case
5457         the appropriate callback is called for each reason.
5458         <p/>
5459         For each object reference the <paramlink id="object_ref_callback"></paramlink>
5460         callback function is called to describe the object reference.
5461         The callback is called exactly once for each reference from a referrer;
5462         this is true even if there are reference cycles or multiple paths to
5463         the referrer.
5464         There may be more than one reference between a referrer and a referree,
5465         These may be distinguished by the
5466         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5467         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5468         The callback for an object will always occur after the callback for
5469         its referrer.
5470         <p/>
5471         See <functionlink id="FollowReferences"/> for the object
5472         references which are reported.
5473         <p/>
5474         Roots are always reported to the profiler before any object references
5475         are reported. In other words, the <paramlink id="object_ref_callback"></paramlink>
5476         callback will not be called until the appropriate callback has been called
5477         for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is
5478         specified as <code>NULL</code> then this function returns after
5479         reporting the root objects to the profiler.
5480         <p/>
5481         During the execution of this function the state of the heap
5482         does not change: no objects are allocated, no objects are
5483         garbage collected, and the state of objects (including
5484         held values) does not change.
5485         As a result, threads executing Java
5486         programming language code, threads attempting to resume the
5487         execution of Java programming language code, and threads
5488         attempting to execute JNI functions are typically stalled.
5489       </description>
5490       <origin>new</origin>
5491       <capabilities>
5492         <required id="can_tag_objects"></required>
5493       </capabilities>
5494       <parameters>
5495         <param id="heap_root_callback">
5496           <ptrtype>
5497             <struct>jvmtiHeapRootCallback</struct>
5498             <nullok>do not report heap roots</nullok>
5499           </ptrtype>
5500             <description>
5501               The callback function to be called for each heap root of type
5502               <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
5503               <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
5504               <code>JVMTI_HEAP_ROOT_MONITOR</code>,
5505               <code>JVMTI_HEAP_ROOT_THREAD</code>, or
5506               <code>JVMTI_HEAP_ROOT_OTHER</code>.
5507             </description>
5508         </param>
5509         <param id="stack_ref_callback">
5510           <ptrtype>
5511             <struct>jvmtiStackReferenceCallback</struct>
5512             <nullok>do not report stack references</nullok>
5513           </ptrtype>
5514             <description>
5515               The callback function to be called for each heap root of
5516               <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5517               <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
5518             </description>
5519         </param>
5520         <param id="object_ref_callback">
5521           <ptrtype>
5522             <struct>jvmtiObjectReferenceCallback</struct>
5523             <nullok>do not follow references from the root objects</nullok>
5524           </ptrtype>
5525             <description>
5526               The callback function to be called for each object reference.
5527             </description>
5528         </param>
5529         <param id="user_data">
5530           <inbuf>
5531             <void/>
5532             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5533           </inbuf>
5534           <description>
5535             User supplied data to be passed to the callback.
5536           </description>
5537         </param>
5538       </parameters>
5539       <errors>
5540       </errors>
5541     </function>
5542 
5543     <function id="IterateOverHeap" num="111">
5544       <synopsis>Iterate Over Heap</synopsis>
5545       <description>
5546         Iterate over all objects in the heap. This includes both reachable and
5547         unreachable objects.
5548         <p/>
5549         The <paramlink id="object_filter"></paramlink> parameter indicates the
5550         objects for which the callback function is called. If this parameter
5551         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
5552         called for every object that is tagged. If the parameter is
5553         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5554         for objects that are not tagged. If the parameter
5555         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5556         called for every object in the heap, irrespective of whether it is
5557         tagged or not.
5558         <p/>
5559         During the execution of this function the state of the heap
5560         does not change: no objects are allocated, no objects are
5561         garbage collected, and the state of objects (including
5562         held values) does not change.
5563         As a result, threads executing Java
5564         programming language code, threads attempting to resume the
5565         execution of Java programming language code, and threads
5566         attempting to execute JNI functions are typically stalled.
5567       </description>
5568       <origin>new</origin>
5569       <capabilities>
5570         <required id="can_tag_objects"></required>
5571       </capabilities>
5572       <parameters>
5573         <param id="object_filter">
5574           <enum>jvmtiHeapObjectFilter</enum>
5575           <description>
5576             Indicates the objects for which the callback function is called.
5577           </description>
5578         </param>
5579         <param id="heap_object_callback">
5580           <ptrtype>
5581             <struct>jvmtiHeapObjectCallback</struct>
5582           </ptrtype>
5583             <description>
5584               The iterator function to be called for each
5585               object matching the <paramlink id="object_filter"/>.
5586             </description>
5587         </param>
5588         <param id="user_data">
5589           <inbuf>
5590             <void/>
5591             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5592           </inbuf>
5593           <description>
5594             User supplied data to be passed to the callback.
5595           </description>
5596         </param>
5597       </parameters>
5598       <errors>
5599       </errors>
5600     </function>
5601 
5602     <function id="IterateOverInstancesOfClass" num="112">
5603       <synopsis>Iterate Over Instances Of Class</synopsis>
5604       <description>
5605         Iterate over all objects in the heap that are instances of the specified class.
5606         This includes direct instances of the specified class and
5607         instances of all subclasses of the specified class.
5608         This includes both reachable and unreachable objects.
5609         <p/>
5610         The <paramlink id="object_filter"></paramlink> parameter indicates the
5611         objects for which the callback function is called. If this parameter
5612         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
5613         called for every object that is tagged. If the parameter is
5614         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5615         called for objects that are not tagged. If the parameter
5616         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5617         called for every object in the heap, irrespective of whether it is
5618         tagged or not.
5619         <p/>
5620         During the execution of this function the state of the heap
5621         does not change: no objects are allocated, no objects are
5622         garbage collected, and the state of objects (including
5623         held values) does not change.
5624         As a result, threads executing Java
5625         programming language code, threads attempting to resume the
5626         execution of Java programming language code, and threads
5627         attempting to execute JNI functions are typically stalled.
5628       </description>
5629       <origin>new</origin>
5630       <capabilities>
5631         <required id="can_tag_objects"></required>
5632       </capabilities>
5633       <parameters>
5634         <param id="klass">
5635           <jclass/>
5636             <description>
5637               Iterate over objects of this class only.
5638             </description>
5639         </param>
5640         <param id="object_filter">
5641           <enum>jvmtiHeapObjectFilter</enum>
5642           <description>
5643             Indicates the objects for which the callback function is called.
5644           </description>
5645         </param>
5646         <param id="heap_object_callback">
5647           <ptrtype>
5648             <struct>jvmtiHeapObjectCallback</struct>
5649           </ptrtype>
5650             <description>
5651               The iterator function to be called for each
5652               <paramlink id="klass"/> instance matching
5653               the <paramlink id="object_filter"/>.
5654             </description>
5655         </param>
5656         <param id="user_data">
5657           <inbuf>
5658             <void/>
5659             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5660           </inbuf>
5661           <description>
5662             User supplied data to be passed to the callback.
5663           </description>
5664         </param>
5665       </parameters>
5666       <errors>
5667       </errors>
5668     </function>
5669 
5670   </category>
5671 
5672   <category id="local" label="Local Variable">
5673 
5674     <intro>
5675       These functions are used to retrieve or set the value of a local variable.
5676       The variable is identified by the depth of the frame containing its
5677       value and the variable's slot number within that frame.
5678       The mapping of variables to
5679       slot numbers can be obtained with the function
5680       <functionlink id="GetLocalVariableTable"></functionlink>.
5681     </intro>
5682 
5683     <function id="GetLocalObject" num="21">
5684       <synopsis>Get Local Variable - Object</synopsis>
5685       <description>
5686         This function can be used to retrieve the value of a local
5687         variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
5688       </description>
5689       <origin>jvmdi</origin>
5690       <capabilities>
5691         <required id="can_access_local_variables"></required>
5692       </capabilities>
5693       <parameters>
5694         <param id="thread">
5695           <jthread null="current" frame="frame"/>
5696           <description>
5697             The thread of the frame containing the variable's value.
5698           </description>
5699         </param>
5700         <param id="depth">
5701           <jframeID thread="thread"/>
5702           <description>
5703             The depth of the frame containing the variable's value.
5704           </description>
5705         </param>
5706         <param id="slot">
5707           <jint/>
5708           <description>
5709             The variable's slot number.
5710           </description>
5711         </param>
5712         <param id="value_ptr">
5713           <outptr><jobject/></outptr>
5714             <description>
5715               On return, points to the variable's value.
5716             </description>
5717         </param>
5718       </parameters>
5719       <errors>
5720         <error id="JVMTI_ERROR_INVALID_SLOT">
5721           Invalid <code>slot</code>.
5722         </error>
5723         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5724           The variable type is not
5725           <code>Object</code> or a subclass of <code>Object</code>.
5726         </error>
5727         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5728           Not a visible frame
5729         </error>
5730       </errors>
5731     </function>
5732 
5733     <function id="GetLocalInstance" num="155" since="1.2">
5734       <synopsis>Get Local Instance</synopsis>
5735       <description>
5736         This function can be used to retrieve the value of the local object
5737         variable at slot 0 (the "<code>this</code>" object) from non-static
5738         frames.  This function can retrieve the "<code>this</code>" object from
5739         native method frames, whereas <code>GetLocalObject()</code> would
5740         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5741       </description>
5742       <origin>new</origin>
5743       <capabilities>
5744         <required id="can_access_local_variables"></required>
5745       </capabilities>
5746       <parameters>
5747         <param id="thread">
5748           <jthread null="current" frame="frame"/>
5749           <description>
5750             The thread of the frame containing the variable's value.
5751           </description>
5752         </param>
5753         <param id="depth">
5754           <jframeID thread="thread"/>
5755           <description>
5756             The depth of the frame containing the variable's value.
5757           </description>
5758         </param>
5759         <param id="value_ptr">
5760           <outptr><jobject/></outptr>
5761             <description>
5762               On return, points to the variable's value.
5763             </description>
5764         </param>
5765       </parameters>
5766       <errors>
5767         <error id="JVMTI_ERROR_INVALID_SLOT">
5768           If the specified frame is a static method frame.
5769         </error>
5770       </errors>
5771     </function>
5772     <function id="GetLocalInt" num="22">
5773       <synopsis>Get Local Variable - Int</synopsis>
5774       <description>
5775         This function can be used to retrieve the value of a local
5776         variable whose type is <code>int</code>,
5777         <code>short</code>, <code>char</code>, <code>byte</code>, or
5778         <code>boolean</code>.
5779       </description>
5780       <origin>jvmdi</origin>
5781       <capabilities>
5782         <required id="can_access_local_variables"></required>
5783       </capabilities>
5784       <parameters>
5785         <param id="thread">
5786           <jthread null="current" frame="frame"/>
5787           <description>
5788             The thread of the frame containing the variable's value.
5789           </description>
5790         </param>
5791         <param id="depth">
5792           <jframeID thread="thread"/>
5793           <description>
5794             The depth of the frame containing the variable's value.
5795           </description>
5796         </param>
5797         <param id="slot">
5798           <jint/>
5799           <description>
5800             The variable's slot number.
5801           </description>
5802         </param>
5803         <param id="value_ptr">
5804           <outptr><jint/></outptr>
5805           <description>
5806             On return, points to the variable's value.
5807           </description>
5808         </param>
5809       </parameters>
5810       <errors>
5811         <error id="JVMTI_ERROR_INVALID_SLOT">
5812           Invalid <code>slot</code>.
5813         </error>
5814         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5815           The variable type is not
5816           <code>int</code>, <code>short</code>,
5817           <code>char</code>, <code>byte</code>, or
5818           <code>boolean</code>.
5819         </error>
5820         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5821           Not a visible frame
5822         </error>
5823       </errors>
5824     </function>
5825 
5826     <function id="GetLocalLong" num="23">
5827       <synopsis>Get Local Variable - Long</synopsis>
5828       <description>
5829         This function can be used to retrieve the value of a local
5830         variable whose type is <code>long</code>.
5831       </description>
5832       <origin>jvmdi</origin>
5833       <capabilities>
5834         <required id="can_access_local_variables"></required>
5835       </capabilities>
5836       <parameters>
5837         <param id="thread">
5838           <jthread null="current" frame="frame"/>
5839           <description>
5840             The thread of the frame containing the variable's value.
5841           </description>
5842         </param>
5843         <param id="depth">
5844           <jframeID thread="thread"/>
5845           <description>
5846             The depth of the frame containing the variable's value.
5847           </description>
5848         </param>
5849         <param id="slot">
5850           <jint/>
5851           <description>
5852             The variable's slot number.
5853           </description>
5854         </param>
5855         <param id="value_ptr">
5856           <outptr><jlong/></outptr>
5857           <description>
5858             On return, points to the variable's value.
5859           </description>
5860         </param>
5861       </parameters>
5862       <errors>
5863         <error id="JVMTI_ERROR_INVALID_SLOT">
5864           Invalid <code>slot</code>.
5865         </error>
5866         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5867           The variable type is not <code>long</code>.
5868         </error>
5869         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5870           Not a visible frame
5871         </error>
5872       </errors>
5873     </function>
5874 
5875     <function id="GetLocalFloat" num="24">
5876       <synopsis>Get Local Variable - Float</synopsis>
5877       <description>
5878         This function can be used to retrieve the value of a local
5879         variable whose type is <code>float</code>.
5880       </description>
5881       <origin>jvmdi</origin>
5882       <capabilities>
5883         <required id="can_access_local_variables"></required>
5884       </capabilities>
5885       <parameters>
5886         <param id="thread">
5887           <jthread null="current" frame="frame"/>
5888           <description>
5889             The thread of the frame containing the variable's value.
5890           </description>
5891         </param>
5892         <param id="depth">
5893           <jframeID thread="thread"/>
5894           <description>
5895             The depth of the frame containing the variable's value.
5896           </description>
5897         </param>
5898         <param id="slot">
5899           <jint/>
5900           <description>
5901             The variable's slot number.
5902           </description>
5903         </param>
5904         <param id="value_ptr">
5905           <outptr><jfloat/></outptr>
5906           <description>
5907             On return, points to the variable's value.
5908           </description>
5909         </param>
5910       </parameters>
5911       <errors>
5912         <error id="JVMTI_ERROR_INVALID_SLOT">
5913           Invalid <code>slot</code>.
5914         </error>
5915         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5916           The variable type is not <code>float</code>.
5917         </error>
5918         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5919           Not a visible frame
5920         </error>
5921       </errors>
5922     </function>
5923 
5924     <function id="GetLocalDouble" num="25">
5925       <synopsis>Get Local Variable - Double</synopsis>
5926       <description>
5927         This function can be used to retrieve the value of a local
5928         variable whose type is <code>long</code>.
5929       </description>
5930       <origin>jvmdi</origin>
5931       <capabilities>
5932         <required id="can_access_local_variables"></required>
5933       </capabilities>
5934       <parameters>
5935         <param id="thread">
5936           <jthread null="current" frame="frame"/>
5937           <description>
5938             The thread of the frame containing the variable's value.
5939           </description>
5940         </param>
5941         <param id="depth">
5942           <jframeID thread="thread"/>
5943           <description>
5944             The depth of the frame containing the variable's value.
5945           </description>
5946         </param>
5947         <param id="slot">
5948           <jint/>
5949           <description>
5950             The variable's slot number.
5951           </description>
5952         </param>
5953         <param id="value_ptr">
5954           <outptr><jdouble/></outptr>
5955           <description>
5956             On return, points to the variable's value.
5957           </description>
5958         </param>
5959       </parameters>
5960       <errors>
5961         <error id="JVMTI_ERROR_INVALID_SLOT">
5962           Invalid <code>slot</code>.
5963         </error>
5964         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5965           The variable type is not <code>double</code>.
5966         </error>
5967         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5968           Not a visible frame
5969         </error>
5970       </errors>
5971     </function>
5972 
5973     <function id="SetLocalObject" num="26">
5974       <synopsis>Set Local Variable - Object</synopsis>
5975       <description>
5976         This function can be used to set the value of a local
5977         variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
5978       </description>
5979       <origin>jvmdi</origin>
5980       <capabilities>
5981         <required id="can_access_local_variables"></required>
5982       </capabilities>
5983       <parameters>
5984         <param id="thread">
5985           <jthread null="current" frame="frame"/>
5986           <description>
5987             The thread of the frame containing the variable's value.
5988           </description>
5989         </param>
5990         <param id="depth">
5991           <jframeID thread="thread"/>
5992           <description>
5993             The depth of the frame containing the variable's value.
5994           </description>
5995         </param>
5996         <param id="slot">
5997           <jint/>
5998           <description>
5999             The variable's slot number.
6000           </description>
6001         </param>
6002         <param id="value">
6003           <jobject/>
6004             <description>
6005               The new value for the variable.
6006             </description>
6007         </param>
6008       </parameters>
6009       <errors>
6010         <error id="JVMTI_ERROR_INVALID_SLOT">
6011           Invalid <code>slot</code>.
6012         </error>
6013         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6014           The variable type is not
6015           <code>Object</code> or a subclass of <code>Object</code>.
6016         </error>
6017         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6018           The supplied <paramlink id="value"/> is not compatible
6019           with the variable type.
6020         </error>
6021         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6022           Not a visible frame
6023         </error>
6024       </errors>
6025     </function>
6026 
6027     <function id="SetLocalInt" num="27">
6028       <synopsis>Set Local Variable - Int</synopsis>
6029       <description>
6030         This function can be used to set the value of a local
6031         variable whose type is <code>int</code>,
6032         <code>short</code>, <code>char</code>, <code>byte</code>, or
6033         <code>boolean</code>.
6034       </description>
6035       <origin>jvmdi</origin>
6036       <capabilities>
6037         <required id="can_access_local_variables"></required>
6038       </capabilities>
6039       <parameters>
6040         <param id="thread">
6041           <jthread null="current" frame="frame"/>
6042           <description>
6043             The thread of the frame containing the variable's value.
6044           </description>
6045         </param>
6046         <param id="depth">
6047           <jframeID thread="thread"/>
6048           <description>
6049             The depth of the frame containing the variable's value.
6050           </description>
6051         </param>
6052         <param id="slot">
6053           <jint/>
6054           <description>
6055             The variable's slot number.
6056           </description>
6057         </param>
6058         <param id="value">
6059           <jint/>
6060           <description>
6061             The new value for the variable.
6062           </description>
6063         </param>
6064       </parameters>
6065       <errors>
6066         <error id="JVMTI_ERROR_INVALID_SLOT">
6067           Invalid <code>slot</code>.
6068         </error>
6069         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6070           The variable type is not
6071           <code>int</code>, <code>short</code>,
6072           <code>char</code>, <code>byte</code>, or
6073           <code>boolean</code>.
6074         </error>
6075         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6076           Not a visible frame
6077         </error>
6078       </errors>
6079     </function>
6080 
6081     <function id="SetLocalLong" num="28">
6082       <synopsis>Set Local Variable - Long</synopsis>
6083       <description>
6084         This function can be used to set the value of a local
6085         variable whose type is <code>long</code>.
6086       </description>
6087       <origin>jvmdi</origin>
6088       <capabilities>
6089         <required id="can_access_local_variables"></required>
6090       </capabilities>
6091       <parameters>
6092         <param id="thread">
6093           <jthread null="current" frame="frame"/>
6094           <description>
6095             The thread of the frame containing the variable's value.
6096           </description>
6097         </param>
6098         <param id="depth">
6099           <jframeID thread="thread"/>
6100           <description>
6101             The depth of the frame containing the variable's value.
6102           </description>
6103         </param>
6104         <param id="slot">
6105           <jint/>
6106           <description>
6107             The variable's slot number.
6108           </description>
6109         </param>
6110         <param id="value">
6111           <jlong/>
6112           <description>
6113             The new value for the variable.
6114           </description>
6115         </param>
6116       </parameters>
6117       <errors>
6118         <error id="JVMTI_ERROR_INVALID_SLOT">
6119           Invalid <code>slot</code>.
6120         </error>
6121         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6122           The variable type is not <code>long</code>.
6123         </error>
6124         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6125           Not a visible frame
6126         </error>
6127       </errors>
6128     </function>
6129 
6130     <function id="SetLocalFloat" num="29">
6131       <synopsis>Set Local Variable - Float</synopsis>
6132       <description>
6133         This function can be used to set the value of a local
6134         variable whose type is <code>float</code>.
6135       </description>
6136       <origin>jvmdi</origin>
6137       <capabilities>
6138         <required id="can_access_local_variables"></required>
6139       </capabilities>
6140       <parameters>
6141         <param id="thread">
6142           <jthread null="current" frame="frame"/>
6143           <description>
6144             The thread of the frame containing the variable's value.
6145           </description>
6146         </param>
6147         <param id="depth">
6148           <jframeID thread="thread"/>
6149           <description>
6150             The depth of the frame containing the variable's value.
6151           </description>
6152         </param>
6153         <param id="slot">
6154           <jint/>
6155           <description>
6156             The variable's slot number.
6157           </description>
6158         </param>
6159         <param id="value">
6160           <jfloat/>
6161           <description>
6162             The new value for the variable.
6163           </description>
6164         </param>
6165       </parameters>
6166       <errors>
6167         <error id="JVMTI_ERROR_INVALID_SLOT">
6168           Invalid <code>slot</code>.
6169         </error>
6170         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6171           The variable type is not <code>float</code>.
6172         </error>
6173         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6174           Not a visible frame
6175         </error>
6176       </errors>
6177     </function>
6178 
6179     <function id="SetLocalDouble" num="30">
6180       <synopsis>Set Local Variable - Double</synopsis>
6181       <description>
6182         This function can be used to set the value of a local
6183         variable whose type is <code>double</code>.
6184       </description>
6185       <origin>jvmdi</origin>
6186       <capabilities>
6187         <required id="can_access_local_variables"></required>
6188       </capabilities>
6189       <parameters>
6190         <param id="thread">
6191           <jthread null="current" frame="frame"/>
6192           <description>
6193             The thread of the frame containing the variable's value.
6194           </description>
6195         </param>
6196         <param id="depth">
6197           <jframeID thread="thread"/>
6198           <description>
6199             The depth of the frame containing the variable's value.
6200           </description>
6201         </param>
6202         <param id="slot">
6203           <jint/>
6204           <description>
6205             The variable's slot number.
6206           </description>
6207         </param>
6208         <param id="value">
6209           <jdouble/>
6210           <description>
6211             The new value for the variable.
6212           </description>
6213         </param>
6214       </parameters>
6215       <errors>
6216         <error id="JVMTI_ERROR_INVALID_SLOT">
6217           Invalid <code>slot</code>.
6218         </error>
6219         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6220           The variable type is not <code>double</code>.
6221         </error>
6222         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6223           Not a visible frame
6224         </error>
6225       </errors>
6226     </function>
6227   </category>
6228 
6229   <category id="breakpointCategory" label="Breakpoint">
6230 
6231     <intro>
6232     </intro>
6233 
6234     <function id="SetBreakpoint" num="38">
6235       <synopsis>Set Breakpoint</synopsis>
6236       <description>
6237         Set a breakpoint at the instruction indicated by
6238         <code>method</code> and <code>location</code>.
6239         An instruction can only have one breakpoint.
6240         <p/>
6241         Whenever the designated instruction is about to be executed, a
6242         <eventlink id="Breakpoint"></eventlink> event is generated.
6243       </description>
6244       <origin>jvmdi</origin>
6245       <capabilities>
6246         <required id="can_generate_breakpoint_events"></required>
6247       </capabilities>
6248       <parameters>
6249         <param id="klass">
6250           <jclass method="method"/>
6251             <description>
6252               The class in which to set the breakpoint
6253             </description>
6254         </param>
6255         <param id="method">
6256           <jmethodID class="klass"/>
6257             <description>
6258               The method in which to set the breakpoint
6259             </description>
6260         </param>
6261         <param id="location">
6262           <jlocation/>
6263           <description>
6264             the index of the instruction at which to set the breakpoint
6265 
6266           </description>
6267         </param>
6268       </parameters>
6269       <errors>
6270         <error id="JVMTI_ERROR_DUPLICATE">
6271           The designated bytecode already has a breakpoint.
6272         </error>
6273       </errors>
6274     </function>
6275 
6276     <function id="ClearBreakpoint" num="39">
6277       <synopsis>Clear Breakpoint</synopsis>
6278       <description>
6279         Clear the breakpoint at the bytecode indicated by
6280         <code>method</code> and <code>location</code>.
6281       </description>
6282       <origin>jvmdi</origin>
6283       <capabilities>
6284         <required id="can_generate_breakpoint_events"></required>
6285       </capabilities>
6286       <parameters>
6287         <param id="klass">
6288           <jclass method="method"/>
6289             <description>
6290               The class in which to clear the breakpoint
6291             </description>
6292         </param>
6293         <param id="method">
6294           <jmethodID class="klass"/>
6295             <description>
6296               The method in which to clear the breakpoint
6297             </description>
6298         </param>
6299         <param id="location">
6300           <jlocation/>
6301           <description>
6302             the index of the instruction at which to clear the breakpoint
6303           </description>
6304         </param>
6305       </parameters>
6306       <errors>
6307         <error id="JVMTI_ERROR_NOT_FOUND">
6308           There's no breakpoint at the designated bytecode.
6309         </error>
6310       </errors>
6311     </function>
6312 
6313   </category>
6314 
6315   <category id="fieldWatch" label="Watched Field">
6316 
6317     <intro>
6318     </intro>
6319 
6320     <function id="SetFieldAccessWatch" num="41">
6321       <synopsis>Set Field Access Watch</synopsis>
6322       <description>
6323         Generate a <eventlink id="FieldAccess"></eventlink> event
6324         when the field specified
6325         by <code>klass</code> and
6326         <code>field</code> is about to be accessed.
6327         An event will be generated for each access of the field
6328         until it is canceled with
6329         <functionlink id="ClearFieldAccessWatch"></functionlink>.
6330         Field accesses from Java programming language code or from JNI code are watched,
6331         fields modified by other means are not watched.
6332         Note that <jvmti/> users should be aware that their own field accesses
6333         will trigger the watch.
6334         A field can only have one field access watch set.
6335         Modification of a field is not considered an access--use
6336         <functionlink id="SetFieldModificationWatch"></functionlink>
6337         to monitor modifications.
6338       </description>
6339       <origin>jvmdi</origin>
6340       <capabilities>
6341         <required id="can_generate_field_access_events"></required>
6342       </capabilities>
6343       <parameters>
6344         <param id="klass">
6345           <jclass field="field"/>
6346             <description>
6347               The class containing the field to watch
6348             </description>
6349         </param>
6350         <param id="field">
6351           <jfieldID class="klass"/>
6352             <description>
6353               The field to watch
6354 
6355             </description>
6356         </param>
6357       </parameters>
6358       <errors>
6359         <error id="JVMTI_ERROR_DUPLICATE">
6360           The designated field is already being watched for accesses.
6361         </error>
6362       </errors>
6363     </function>
6364 
6365     <function id="ClearFieldAccessWatch" num="42">
6366       <synopsis>Clear Field Access Watch</synopsis>
6367       <description>
6368         Cancel a field access watch previously set by
6369         <functionlink id="SetFieldAccessWatch"></functionlink>, on the
6370         field specified
6371         by <code>klass</code> and
6372         <code>field</code>.
6373       </description>
6374       <origin>jvmdi</origin>
6375       <capabilities>
6376         <required id="can_generate_field_access_events"></required>
6377       </capabilities>
6378       <parameters>
6379         <param id="klass">
6380           <jclass field="field"/>
6381             <description>
6382               The class containing the field to watch
6383             </description>
6384         </param>
6385         <param id="field">
6386           <jfieldID class="klass"/>
6387             <description>
6388               The field to watch
6389 
6390             </description>
6391         </param>
6392       </parameters>
6393       <errors>
6394         <error id="JVMTI_ERROR_NOT_FOUND">
6395           The designated field is not being watched for accesses.
6396         </error>
6397       </errors>
6398     </function>
6399 
6400     <function id="SetFieldModificationWatch" num="43">
6401       <synopsis>Set Field Modification Watch</synopsis>
6402       <description>
6403         Generate a <eventlink id="FieldModification"></eventlink> event
6404         when the field specified
6405         by <code>klass</code> and
6406         <code>field</code> is about to be modified.
6407         An event will be generated for each modification of the field
6408         until it is canceled with
6409         <functionlink id="ClearFieldModificationWatch"></functionlink>.
6410         Field modifications from Java programming language code or from JNI code are watched,
6411         fields modified by other means are not watched.
6412         Note that <jvmti/> users should be aware that their own field modifications
6413         will trigger the watch.
6414         A field can only have one field modification watch set.
6415       </description>
6416       <origin>jvmdi</origin>
6417       <capabilities>
6418         <required id="can_generate_field_modification_events"></required>
6419       </capabilities>
6420       <parameters>
6421         <param id="klass">
6422           <jclass field="field"/>
6423             <description>
6424               The class containing the field to watch
6425             </description>
6426         </param>
6427         <param id="field">
6428           <jfieldID class="klass"/>
6429             <description>
6430               The field to watch
6431 
6432             </description>
6433         </param>
6434       </parameters>
6435       <errors>
6436         <error id="JVMTI_ERROR_DUPLICATE">
6437           The designated field is already being watched for modifications.
6438         </error>
6439       </errors>
6440     </function>
6441 
6442     <function id="ClearFieldModificationWatch" num="44">
6443       <synopsis>Clear Field Modification Watch</synopsis>
6444       <description>
6445 
6446         Cancel a field modification watch previously set by
6447         <functionlink id="SetFieldModificationWatch"></functionlink>, on the
6448         field specified
6449         by <code>klass</code> and
6450         <code>field</code>.
6451       </description>
6452       <origin>jvmdi</origin>
6453       <capabilities>
6454         <required id="can_generate_field_modification_events"></required>
6455       </capabilities>
6456       <parameters>
6457         <param id="klass">
6458           <jclass field="field"/>
6459             <description>
6460               The class containing the field to watch
6461             </description>
6462         </param>
6463         <param id="field">
6464           <jfieldID class="klass"/>
6465             <description>
6466               The field to watch
6467 
6468             </description>
6469         </param>
6470       </parameters>
6471       <errors>
6472         <error id="JVMTI_ERROR_NOT_FOUND">
6473           The designated field is not being watched for modifications.
6474         </error>
6475       </errors>
6476     </function>
6477   </category>
6478 
6479   <category id="module" label="Module">
6480 
6481     <intro>
6482     </intro>
6483 
6484     <function id="GetAllModules" num="3" since="9">
6485       <synopsis>Get All Modules</synopsis>
6486       <description>
6487         Return an array of all modules loaded in the virtual machine.
6488         The array includes the unnamed module for each class loader.
6489         The number of modules in the array is returned via
6490         <code>module_count_ptr</code>, and the array itself via
6491         <code>modules_ptr</code>.
6492         <p/>
6493       </description>
6494       <origin>new</origin>
6495       <capabilities>
6496       </capabilities>
6497       <parameters>
6498         <param id="module_count_ptr">
6499           <outptr><jint/></outptr>
6500           <description>
6501             On return, points to the number of returned modules.
6502           </description>
6503         </param>
6504         <param id="modules_ptr">
6505           <allocbuf outcount="module_count_ptr"><jobject/></allocbuf>
6506             <description>
6507               On return, points to an array of references, one
6508               for each module.
6509             </description>
6510         </param>
6511       </parameters>
6512       <errors>
6513       </errors>
6514     </function>
6515 
6516     <function id="GetNamedModule" num="40" since="9">
6517       <synopsis>Get Named Module</synopsis>
6518       <description>
6519         Return the <code>java.lang.Module</code> object for a named
6520         module defined to a class loader that contains a given package.
6521         The module is returned via <code>module_ptr</code>.
6522         <p/>
6523         If a named module is defined to the class loader and it
6524         contains the package then that named module is returned,
6525         otherwise <code>NULL</code> is returned.
6526         <p/>
6527       </description>
6528       <origin>new</origin>
6529       <capabilities>
6530       </capabilities>
6531       <parameters>
6532         <param id="class_loader">
6533           <ptrtype>
6534             <jobject/>
6535             <nullok>the bootstrap loader is assumed</nullok>
6536           </ptrtype>
6537           <description>
6538             A class loader.
6539             If the <code>class_loader</code> is not <code>NULL</code>
6540             or a subclass of <code>java.lang.ClassLoader</code>
6541             this function returns
6542             <errorlink id="JVMTI_ERROR_ILLEGAL_ARGUMENT"></errorlink>.
6543           </description>
6544         </param>
6545         <param id="package_name">
6546           <inbuf><char/></inbuf>
6547           <description>
6548             The name of the package, encoded as a
6549             <internallink id="mUTF">modified UTF-8</internallink> string.
6550             The package name is in internal form (JVMS 4.2.1);
6551             identifiers are separated by forward slashes rather than periods.
6552           </description>
6553         </param>
6554         <param id="module_ptr">
6555           <outptr><jobject/></outptr>
6556           <description>
6557             On return, points to a <code>java.lang.Module</code> object
6558             or points to <code>NULL</code>.
6559           </description>
6560         </param>
6561       </parameters>
6562       <errors>
6563         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6564           If class loader is not <code>NULL</code> and is not a class loader object.
6565         </error>
6566       </errors>
6567     </function>
6568 
6569     <function id="AddModuleReads" num="94" since="9">
6570       <synopsis>Add Module Reads</synopsis>
6571       <description>
6572          Update a module to read another module. This function is a no-op
6573          when <paramlink id="module"></paramlink> is an unnamed module.
6574          This function facilitates the instrumentation of code
6575          in named modules where that instrumentation requires
6576          expanding the set of modules that a module reads.
6577       </description>
6578       <origin>new</origin>
6579       <capabilities>
6580       </capabilities>
6581       <parameters>
6582         <param id="module">
6583           <ptrtype><jobject/></ptrtype>
6584           <description>
6585             The module to update.
6586           </description>
6587         </param>
6588         <param id="to_module">
6589           <ptrtype><jobject/></ptrtype>
6590           <description>
6591             The additional module to read.
6592           </description>
6593         </param>
6594       </parameters>
6595       <errors>
6596         <error id="JVMTI_ERROR_INVALID_MODULE">
6597           If <paramlink id="module"></paramlink> is not a module object.
6598         </error>
6599         <error id="JVMTI_ERROR_INVALID_MODULE">
6600           If <paramlink id="to_module"></paramlink> is not a module object.
6601         </error>
6602         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6603           if the module cannot be modified.
6604           See <functionlink id="IsModifiableModule"/>.
6605         </error>
6606       </errors>
6607     </function>
6608 
6609     <function id="AddModuleExports" num="95" since="9">
6610       <synopsis>Add Module Exports</synopsis>
6611       <description>
6612          Update a module to export a package to another module.
6613          This function is a no-op when <paramlink id="module"></paramlink>
6614          is an unnamed module or an open module.
6615          This function facilitates the instrumentation of code
6616          in named modules where that instrumentation requires
6617          expanding the set of packages that a module exports.
6618       </description>
6619       <origin>new</origin>
6620       <capabilities>
6621       </capabilities>
6622       <parameters>
6623         <param id="module">
6624           <ptrtype><jobject/></ptrtype>
6625           <description>
6626             The module to update.
6627           </description>
6628         </param>
6629         <param id="pkg_name">
6630           <inbuf><char/></inbuf>
6631           <description>
6632             The exported package name.
6633           </description>
6634         </param>
6635         <param id="to_module">
6636           <ptrtype><jobject/></ptrtype>
6637           <description>
6638             The module the package is exported to.
6639             If the <code>to_module</code> is not a subclass of
6640             <code>java.lang.Module</code> this function returns
6641             <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
6642           </description>
6643         </param>
6644       </parameters>
6645       <errors>
6646         <error id="JVMTI_ERROR_INVALID_MODULE">
6647           If <paramlink id="module"></paramlink> is not a module object.
6648         </error>
6649         <error id="JVMTI_ERROR_INVALID_MODULE">
6650           If <paramlink id="to_modules"></paramlink> is not a module object.
6651         </error>
6652         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6653           If the package <paramlink id="pkg_name"></paramlink>
6654           does not belong to the module.
6655         </error>
6656         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6657           if the module cannot be modified.
6658           See <functionlink id="IsModifiableModule"/>.
6659         </error>
6660       </errors>
6661     </function>
6662 
6663     <function id="AddModuleOpens" num="96" since="9">
6664       <synopsis>Add Module Opens</synopsis>
6665       <description>
6666          Update a module to open a package to another module.
6667          This function is a no-op when <paramlink id="module"></paramlink>
6668          is an unnamed module or an open module.
6669          This function facilitates the instrumentation of code
6670          in modules where that instrumentation requires
6671          expanding the set of packages that a module opens to
6672          other modules.
6673       </description>
6674       <origin>new</origin>
6675       <capabilities>
6676       </capabilities>
6677       <parameters>
6678         <param id="module">
6679           <ptrtype><jobject/></ptrtype>
6680           <description>
6681             The module to update.
6682           </description>
6683         </param>
6684         <param id="pkg_name">
6685           <inbuf><char/></inbuf>
6686           <description>
6687             The package name of the package to open.
6688           </description>
6689         </param>
6690         <param id="to_module">
6691           <ptrtype><jobject/></ptrtype>
6692           <description>
6693             The module with the package to open.
6694             If the <code>to_module</code> is not a subclass of
6695             <code>java.lang.Module</code> this function returns
6696             <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
6697           </description>
6698         </param>
6699       </parameters>
6700       <errors>
6701         <error id="JVMTI_ERROR_INVALID_MODULE">
6702           If <paramlink id="module"></paramlink> is not a module object.
6703         </error>
6704         <error id="JVMTI_ERROR_INVALID_MODULE">
6705           If <paramlink id="to_modules"></paramlink> is not a module object.
6706         </error>
6707         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6708           If the package <paramlink id="pkg_name"></paramlink>
6709           does not belong to the module.
6710         </error>
6711         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6712           if the module cannot be modified.
6713           See <functionlink id="IsModifiableModule"/>.
6714         </error>
6715       </errors>
6716     </function>
6717 
6718     <function id="AddModuleUses" num="97" since="9">
6719       <synopsis>Add Module Uses</synopsis>
6720       <description>
6721          Updates a module to add a service to the set of services that
6722          a module uses. This function is a no-op when the module
6723          is an unnamed module.
6724          This function facilitates the instrumentation of code
6725          in named modules where that instrumentation requires
6726          expanding the set of services that a module is using.
6727       </description>
6728       <origin>new</origin>
6729       <capabilities>
6730       </capabilities>
6731       <parameters>
6732         <param id="module">
6733           <ptrtype><jobject/></ptrtype>
6734           <description>
6735             The module to update.
6736           </description>
6737         </param>
6738         <param id="service">
6739           <ptrtype><jclass/></ptrtype>
6740           <description>
6741             The service to use.
6742           </description>
6743         </param>
6744       </parameters>
6745       <errors>
6746         <error id="JVMTI_ERROR_INVALID_MODULE">
6747           If <paramlink id="module"></paramlink> is not a module object.
6748         </error>
6749         <error id="JVMTI_ERROR_INVALID_CLASS">
6750           If <paramlink id="service"></paramlink> is not a class object.
6751         </error>
6752         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6753           if the module cannot be modified.
6754           See <functionlink id="IsModifiableModule"/>.
6755         </error>
6756       </errors>
6757     </function>
6758 
6759     <function id="AddModuleProvides" num="98" since="9">
6760       <synopsis>Add Module Provides</synopsis>
6761       <description>
6762          Updates a module to add a service to the set of services that
6763          a module provides. This function is a no-op when the module
6764          is an unnamed module.
6765          This function facilitates the instrumentation of code
6766          in named modules where that instrumentation requires
6767          changes to the services that are provided.
6768       </description>
6769       <origin>new</origin>
6770       <capabilities>
6771       </capabilities>
6772       <parameters>
6773         <param id="module">
6774           <ptrtype><jobject/></ptrtype>
6775           <description>
6776             The module to update.
6777           </description>
6778         </param>
6779         <param id="service">
6780           <ptrtype><jclass/></ptrtype>
6781           <description>
6782             The service to provide.
6783           </description>
6784         </param>
6785         <param id="impl_class">
6786           <ptrtype><jclass/></ptrtype>
6787           <description>
6788             The implementation class for the provided service.
6789           </description>
6790         </param>
6791       </parameters>
6792       <errors>
6793         <error id="JVMTI_ERROR_INVALID_MODULE">
6794           If <paramlink id="module"></paramlink> is not a module object.
6795         </error>
6796         <error id="JVMTI_ERROR_INVALID_CLASS">
6797           If <paramlink id="service"></paramlink> is not a class object.
6798         </error>
6799         <error id="JVMTI_ERROR_INVALID_CLASS">
6800           If <paramlink id="impl_class"></paramlink> is not a class object.
6801         </error>
6802         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6803           if the module cannot be modified.
6804           See <functionlink id="IsModifiableModule"/>.
6805         </error>
6806       </errors>
6807     </function>
6808 
6809     <function id="IsModifiableModule" num="99" since="9">
6810       <synopsis>Is Modifiable Module</synopsis>
6811       <description>
6812         Determines whether a module is modifiable.
6813         If a module is modifiable then this module can be updated with
6814         <functionlink id="AddModuleReads"/>, <functionlink id="AddModuleExports"/>,
6815         <functionlink id="AddModuleOpens"/>, <functionlink id="AddModuleUses"/>,
6816         and <functionlink id="AddModuleProvides"/>. If a module is not modifiable
6817         then the module can not be updated with these functions. The result of
6818         this function is always <code>JNI_TRUE</code> when called to determine
6819         if an unnamed module is modifiable.
6820       </description>
6821       <origin>new</origin>
6822       <capabilities>
6823       </capabilities>
6824       <parameters>
6825         <param id="module">
6826           <ptrtype><jobject/></ptrtype>
6827           <description>
6828             The module to query.
6829           </description>
6830         </param>
6831         <param id="is_modifiable_module_ptr">
6832           <outptr><jboolean/></outptr>
6833           <description>
6834             On return, points to the boolean result of this function.
6835           </description>
6836         </param>
6837       </parameters>
6838       <errors>
6839         <error id="JVMTI_ERROR_INVALID_MODULE">
6840           If <paramlink id="module"></paramlink> is not a module object.
6841         </error>
6842       </errors>
6843     </function>
6844 
6845   </category>
6846 
6847   <category id="class" label="Class">
6848 
6849     <intro>
6850     </intro>
6851 
6852     <function id="GetLoadedClasses" jkernel="yes" num="78">
6853       <synopsis>Get Loaded Classes</synopsis>
6854       <description>
6855         Return an array of all classes loaded in the virtual machine.
6856         The number of classes in the array is returned via
6857         <code>class_count_ptr</code>, and the array itself via
6858         <code>classes_ptr</code>.
6859         <p/>
6860         Array classes of all types (including arrays of primitive types) are
6861         included in the returned list. Primitive classes (for example,
6862         <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list.
6863       </description>
6864       <origin>jvmdi</origin>
6865       <capabilities>
6866       </capabilities>
6867       <parameters>
6868         <param id="class_count_ptr">
6869           <outptr><jint/></outptr>
6870           <description>
6871             On return, points to the number of classes.
6872           </description>
6873         </param>
6874         <param id="classes_ptr">
6875           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6876             <description>
6877               On return, points to an array of references, one
6878               for each class.
6879             </description>
6880         </param>
6881       </parameters>
6882       <errors>
6883       </errors>
6884     </function>
6885 
6886     <function id="GetClassLoaderClasses" jkernel="yes" num="79">
6887       <synopsis>Get Classloader Classes</synopsis>
6888       <description>
6889         Returns an array of those classes for which this class loader has
6890         been recorded as an initiating loader. Each
6891         class in the returned array was created by this class loader,
6892         either by defining it directly or by delegation to another class loader.
6893         See <vmspec chapter="5.3"/>.
6894         <p/>
6895         The number of classes in the array is returned via
6896         <code>class_count_ptr</code>, and the array itself via
6897         <code>classes_ptr</code>.
6898       </description>
6899       <origin>jvmdi</origin>
6900       <capabilities>
6901       </capabilities>
6902       <parameters>
6903         <param id="initiating_loader">
6904           <ptrtype>
6905             <jobject/>
6906             <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
6907           </ptrtype>
6908             <description>
6909               An initiating class loader.
6910             </description>
6911         </param>
6912         <param id="class_count_ptr">
6913           <outptr><jint/></outptr>
6914           <description>
6915             On return, points to the number of classes.
6916           </description>
6917         </param>
6918         <param id="classes_ptr">
6919           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6920             <description>
6921               On return, points to an array of references, one
6922               for each class.
6923             </description>
6924         </param>
6925       </parameters>
6926       <errors>
6927       </errors>
6928     </function>
6929 
6930     <function id="GetClassSignature" phase="start" num="48">
6931       <synopsis>Get Class Signature</synopsis>
6932       <description>
6933         For the class indicated by <code>klass</code>, return the
6934         <externallink id="jni/types.html#type-signatures">JNI
6935             type signature</externallink>
6936         and the generic signature of the class.
6937         For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
6938         and <code>int[]</code> is <code>"[I"</code>
6939         The returned name for primitive classes
6940         is the type signature character of the corresponding primitive type.
6941         For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
6942       </description>
6943       <origin>jvmdiClone</origin>
6944       <capabilities>
6945       </capabilities>
6946       <parameters>
6947         <param id="klass">
6948           <jclass/>
6949             <description>
6950               The class to query.
6951             </description>
6952         </param>
6953         <param id="signature_ptr">
6954           <allocbuf>
6955             <char/>
6956             <nullok>the signature is not returned</nullok>
6957           </allocbuf>
6958           <description>
6959             On return, points to the JNI type signature of the class, encoded as a
6960             <internallink id="mUTF">modified UTF-8</internallink> string.
6961           </description>
6962         </param>
6963         <param id="generic_ptr">
6964           <allocbuf>
6965             <char/>
6966             <nullok>the generic signature is not returned</nullok>
6967           </allocbuf>
6968           <description>
6969             On return, points to the generic signature of the class, encoded as a
6970             <internallink id="mUTF">modified UTF-8</internallink> string.
6971             If there is no generic signature attribute for the class, then,
6972             on return, points to <code>NULL</code>.
6973           </description>
6974         </param>
6975       </parameters>
6976       <errors>
6977       </errors>
6978     </function>
6979 
6980     <function id="GetClassStatus" phase="start" num="49">
6981       <synopsis>Get Class Status</synopsis>
6982       <description>
6983         Get the status of the class. Zero or more of the following bits can be
6984         set.
6985         <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
6986           <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
6987             Class bytecodes have been verified
6988           </constant>
6989           <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
6990             Class preparation is complete
6991           </constant>
6992           <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
6993             Class initialization is complete. Static initializer has been run.
6994           </constant>
6995           <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
6996             Error during initialization makes class unusable
6997           </constant>
6998           <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
6999             Class is an array.  If set, all other bits are zero.
7000           </constant>
7001           <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
7002             Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).
7003             If set, all other bits are zero.
7004           </constant>
7005         </constants>
7006       </description>
7007       <origin>jvmdi</origin>
7008       <capabilities>
7009       </capabilities>
7010       <parameters>
7011         <param id="klass">
7012           <jclass/>
7013             <description>
7014               The class to query.
7015             </description>
7016         </param>
7017         <param id="status_ptr">
7018           <outptr><jint/></outptr>
7019           <description>
7020             On return, points to the current state of this class as one or
7021             more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
7022           </description>
7023         </param>
7024       </parameters>
7025       <errors>
7026       </errors>
7027     </function>
7028 
7029     <function id="GetSourceFileName" phase="start" num="50">
7030       <synopsis>Get Source File Name</synopsis>
7031       <description>
7032         For the class indicated by <code>klass</code>, return the source file
7033         name via <code>source_name_ptr</code>. The returned string
7034         is a file name only and never contains a directory name.
7035         <p/>
7036         For primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
7037         and for arrays this function returns
7038         <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
7039       </description>
7040       <origin>jvmdi</origin>
7041       <capabilities>
7042         <required id="can_get_source_file_name"></required>
7043       </capabilities>
7044       <parameters>
7045         <param id="klass">
7046           <jclass/>
7047             <description>
7048               The class to query.
7049             </description>
7050         </param>
7051         <param id="source_name_ptr">
7052           <allocbuf><char/></allocbuf>
7053           <description>
7054             On return, points to the class's source file name, encoded as a
7055             <internallink id="mUTF">modified UTF-8</internallink> string.
7056           </description>
7057         </param>
7058       </parameters>
7059       <errors>
7060         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7061           Class information does not include a source file name. This includes
7062           cases where the class is an array class or primitive class.
7063         </error>
7064       </errors>
7065     </function>
7066 
7067     <function id="GetClassModifiers" phase="start" num="51">
7068       <synopsis>Get Class Modifiers</synopsis>
7069       <description>
7070         For the class indicated by <code>klass</code>, return the access
7071         flags
7072         via <code>modifiers_ptr</code>.
7073         Access flags are defined in <vmspec chapter="4"/>.
7074         <p/>
7075         If the class is an array class, then its public, private, and protected
7076         modifiers are the same as those of its component type. For arrays of
7077         primitives, this component type is represented by one of the primitive
7078         classes (for example, <code>java.lang.Integer.TYPE</code>).
7079         <p/>
7080         If the class is a primitive class, its public modifier is always true,
7081         and its protected and private modifiers are always false.
7082         <p/>
7083         If the class is an array class or a primitive class then its final
7084         modifier is always true and its interface modifier is always false.
7085         The values of its other modifiers are not determined by this specification.
7086 
7087       </description>
7088       <origin>jvmdi</origin>
7089       <capabilities>
7090       </capabilities>
7091       <parameters>
7092         <param id="klass">
7093           <jclass/>
7094             <description>
7095               The class to query.
7096             </description>
7097         </param>
7098         <param id="modifiers_ptr">
7099           <outptr><jint/></outptr>
7100           <description>
7101             On return, points to the current access flags of this class.
7102 
7103           </description>
7104         </param>
7105       </parameters>
7106       <errors>
7107       </errors>
7108     </function>
7109 
7110     <function id="GetClassMethods" phase="start" num="52">
7111       <synopsis>Get Class Methods</synopsis>
7112       <description>
7113         For the class indicated by <code>klass</code>, return a count of
7114         methods via <code>method_count_ptr</code> and a list of
7115         method IDs via <code>methods_ptr</code>. The method list contains
7116         constructors and static initializers as well as true methods.
7117         Only directly declared methods are returned (not inherited methods).
7118         An empty method list is returned for array classes and primitive classes
7119         (for example, <code>java.lang.Integer.TYPE</code>).
7120       </description>
7121       <origin>jvmdi</origin>
7122       <capabilities>
7123         <capability id="can_maintain_original_method_order"/>
7124       </capabilities>
7125       <parameters>
7126         <param id="klass">
7127           <jclass/>
7128             <description>
7129               The class to query.
7130             </description>
7131         </param>
7132         <param id="method_count_ptr">
7133           <outptr><jint/></outptr>
7134           <description>
7135             On return, points to the number of methods declared in this class.
7136           </description>
7137         </param>
7138         <param id="methods_ptr">
7139           <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
7140             <description>
7141               On return, points to the method ID array.
7142             </description>
7143         </param>
7144       </parameters>
7145       <errors>
7146         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7147           <paramlink id="klass"></paramlink> is not prepared.
7148         </error>
7149       </errors>
7150     </function>
7151 
7152     <function id="GetClassFields" phase="start" num="53">
7153       <synopsis>Get Class Fields</synopsis>
7154       <description>
7155         For the class indicated by <code>klass</code>, return a count of fields
7156         via <code>field_count_ptr</code> and a list of field IDs via
7157         <code>fields_ptr</code>.
7158         Only directly declared fields are returned (not inherited fields).
7159         Fields are returned in the order they occur in the class file.
7160         An empty field list is returned for array classes and primitive classes
7161         (for example, <code>java.lang.Integer.TYPE</code>).
7162         Use JNI to determine the length of an array.
7163       </description>
7164       <origin>jvmdi</origin>
7165       <capabilities>
7166       </capabilities>
7167       <parameters>
7168         <param id="klass">
7169           <jclass/>
7170             <description>
7171               The class to query.
7172             </description>
7173         </param>
7174         <param id="field_count_ptr">
7175           <outptr><jint/></outptr>
7176           <description>
7177             On return, points to the number of fields declared in this class.
7178           </description>
7179         </param>
7180         <param id="fields_ptr">
7181           <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
7182             <description>
7183               On return, points to the field ID array.
7184             </description>
7185         </param>
7186       </parameters>
7187       <errors>
7188         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7189           <paramlink id="klass"></paramlink> is not prepared.
7190         </error>
7191       </errors>
7192     </function>
7193 
7194     <function id="GetImplementedInterfaces" phase="start" num="54">
7195       <synopsis>Get Implemented Interfaces</synopsis>
7196       <description>
7197         Return the direct super-interfaces of this class. For a class, this
7198         function returns the interfaces declared in its <code>implements</code>
7199         clause. For an interface, this function returns the interfaces declared in
7200         its <code>extends</code> clause.
7201         An empty interface list is returned for array classes and primitive classes
7202         (for example, <code>java.lang.Integer.TYPE</code>).
7203       </description>
7204       <origin>jvmdi</origin>
7205       <capabilities>
7206       </capabilities>
7207       <parameters>
7208         <param id="klass">
7209           <jclass/>
7210             <description>
7211               The class to query.
7212             </description>
7213         </param>
7214         <param id="interface_count_ptr">
7215           <outptr><jint/></outptr>
7216           <description>
7217             On return, points to the number of interfaces.
7218           </description>
7219         </param>
7220         <param id="interfaces_ptr">
7221           <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
7222             <description>
7223               On return, points to the interface array.
7224             </description>
7225         </param>
7226       </parameters>
7227       <errors>
7228         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7229           <paramlink id="klass"></paramlink> is not prepared.
7230         </error>
7231       </errors>
7232     </function>
7233 
7234     <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
7235       <synopsis>Get Class Version Numbers</synopsis>
7236       <description>
7237         For the class indicated by <code>klass</code>,
7238         return the minor and major version numbers,
7239         as defined in
7240         <vmspec chapter="4"/>.
7241       </description>
7242       <origin>new</origin>
7243       <capabilities>
7244       </capabilities>
7245       <parameters>
7246         <param id="klass">
7247           <jclass/>
7248             <description>
7249               The class to query.
7250             </description>
7251         </param>
7252         <param id="minor_version_ptr">
7253           <outptr><jint/></outptr>
7254           <description>
7255             On return, points to the value of the
7256             <code>minor_version</code> item of the
7257             Class File Format.
7258             Note: to be consistent with the Class File Format,
7259             the minor version number is the first parameter.
7260           </description>
7261         </param>
7262         <param id="major_version_ptr">
7263           <outptr><jint/></outptr>
7264           <description>
7265             On return, points to the value of the
7266             <code>major_version</code> item of the
7267             Class File Format.
7268           </description>
7269         </param>
7270       </parameters>
7271       <errors>
7272         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7273           The class is a primitive or array class.
7274         </error>
7275       </errors>
7276     </function>
7277 
7278     <function id="GetConstantPool" phase="start" num="146" since="1.1">
7279       <synopsis>Get Constant Pool</synopsis>
7280       <description>
7281         For the class indicated by <code>klass</code>,
7282         return the raw bytes of the constant pool in the format of the
7283         <code>constant_pool</code> item of
7284         <vmspec chapter="4"/>.
7285         The format of the constant pool may differ between versions
7286         of the Class File Format, so, the
7287         <functionlink id="GetClassVersionNumbers">minor and major
7288         class version numbers</functionlink> should be checked for
7289         compatibility.
7290         <p/>
7291         The returned constant pool might not have the same layout or
7292         contents as the constant pool in the defining class file.
7293         The constant pool returned by GetConstantPool() may have
7294         more or fewer entries than the defining constant pool.
7295         Entries may be in a different order.
7296         The constant pool returned by GetConstantPool() will match the
7297         constant pool used by
7298         <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
7299         That is, the bytecodes returned by GetBytecodes() will have
7300         constant pool indices which refer to constant pool entries returned
7301         by GetConstantPool().
7302         Note that since <functionlink id="RetransformClasses"/>
7303         and <functionlink id="RedefineClasses"/> can change
7304         the constant pool, the constant pool returned by this function
7305         can change accordingly.  Thus, the correspondence between
7306         GetConstantPool() and GetBytecodes() does not hold if there
7307         is an intervening class retransformation or redefinition.
7308         The value of a constant pool entry used by a given bytecode will
7309         match that of the defining class file (even if the indices don't match).
7310         Constant pool entries which are not used directly or indirectly by
7311         bytecodes (for example,  UTF-8 strings associated with annotations) are
7312         not  required to exist in the returned constant pool.
7313       </description>
7314       <origin>new</origin>
7315       <capabilities>
7316         <required id="can_get_constant_pool"></required>
7317       </capabilities>
7318       <parameters>
7319         <param id="klass">
7320           <jclass/>
7321             <description>
7322               The class to query.
7323             </description>
7324         </param>
7325         <param id="constant_pool_count_ptr">
7326           <outptr><jint/></outptr>
7327           <description>
7328             On return, points to the number of entries
7329             in the constant pool table plus one.
7330             This corresponds to the <code>constant_pool_count</code>
7331             item of the Class File Format.
7332           </description>
7333         </param>
7334         <param id="constant_pool_byte_count_ptr">
7335           <outptr><jint/></outptr>
7336           <description>
7337             On return, points to the number of bytes
7338             in the returned raw constant pool.
7339           </description>
7340         </param>
7341         <param id="constant_pool_bytes_ptr">
7342           <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
7343             <description>
7344               On return, points to the raw constant pool, that is the bytes
7345               defined by the <code>constant_pool</code> item of the
7346               Class File Format
7347             </description>
7348         </param>
7349       </parameters>
7350       <errors>
7351         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7352           The class is a primitive or array class.
7353         </error>
7354       </errors>
7355     </function>
7356 
7357     <function id="IsInterface" phase="start" num="55">
7358       <synopsis>Is Interface</synopsis>
7359       <description>
7360         Determines whether a class object reference represents an interface.
7361         The <code>jboolean</code> result is
7362         <code>JNI_TRUE</code> if the "class" is actually an interface,
7363         <code>JNI_FALSE</code> otherwise.
7364       </description>
7365       <origin>jvmdi</origin>
7366       <capabilities>
7367       </capabilities>
7368       <parameters>
7369         <param id="klass">
7370           <jclass/>
7371             <description>
7372               The class to query.
7373             </description>
7374         </param>
7375         <param id="is_interface_ptr">
7376           <outptr><jboolean/></outptr>
7377           <description>
7378             On return, points to the boolean result of this function.
7379 
7380           </description>
7381         </param>
7382       </parameters>
7383       <errors>
7384       </errors>
7385     </function>
7386 
7387     <function id="IsArrayClass" phase="start" num="56">
7388       <synopsis>Is Array Class</synopsis>
7389       <description>
7390         Determines whether a class object reference represents an array.
7391         The <code>jboolean</code> result is
7392         <code>JNI_TRUE</code> if the class is an array,
7393         <code>JNI_FALSE</code> otherwise.
7394       </description>
7395       <origin>jvmdi</origin>
7396       <capabilities>
7397       </capabilities>
7398       <parameters>
7399         <param id="klass">
7400           <jclass/>
7401             <description>
7402               The class to query.
7403             </description>
7404         </param>
7405         <param id="is_array_class_ptr">
7406           <outptr><jboolean/></outptr>
7407           <description>
7408             On return, points to the boolean result of this function.
7409 
7410           </description>
7411         </param>
7412       </parameters>
7413       <errors>
7414       </errors>
7415     </function>
7416 
7417     <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
7418       <synopsis>Is Modifiable Class</synopsis>
7419       <description>
7420         Determines whether a class is modifiable.
7421         If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
7422         returns <code>JNI_TRUE</code>) the class can be
7423         redefined with <functionlink id="RedefineClasses"/> (assuming
7424         the agent possesses the
7425         <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
7426         capability) or
7427         retransformed with <functionlink id="RetransformClasses"/> (assuming
7428         the agent possesses the
7429         <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
7430         capability).
7431         If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
7432         returns <code>JNI_FALSE</code>) the class can be neither
7433         redefined nor retransformed.
7434         <p/>
7435         Primitive classes (for example, <code>java.lang.Integer.TYPE</code>),
7436         array classes, and some implementation defined classes are never modifiable.
7437         <p/>
7438       </description>
7439       <origin>new</origin>
7440       <capabilities>
7441         <capability id="can_redefine_any_class">
7442           If possessed then all classes (except primitive, array, and some implementation defined
7443           classes) are modifiable (redefine or retransform).
7444         </capability>
7445         <capability id="can_retransform_any_class">
7446           If possessed then all classes (except primitive, array, and some implementation defined
7447           classes) are modifiable with <functionlink id="RetransformClasses"/>.
7448         </capability>
7449         <capability id="can_redefine_classes">
7450           No effect on the result of the function.
7451           But must additionally be possessed to modify the class with
7452           <functionlink id="RedefineClasses"/>.
7453         </capability>
7454         <capability id="can_retransform_classes">
7455           No effect on the result of the function.
7456           But must additionally be possessed to modify the class with
7457           <functionlink id="RetransformClasses"/>.
7458         </capability>
7459       </capabilities>
7460       <parameters>
7461         <param id="klass">
7462           <jclass/>
7463             <description>
7464               The class to query.
7465             </description>
7466         </param>
7467         <param id="is_modifiable_class_ptr">
7468           <outptr><jboolean/></outptr>
7469           <description>
7470             On return, points to the boolean result of this function.
7471           </description>
7472         </param>
7473       </parameters>
7474       <errors>
7475       </errors>
7476     </function>
7477 
7478     <function id="GetClassLoader" phase="start" num="57">
7479       <synopsis>Get Class Loader</synopsis>
7480       <description>
7481         For the class indicated by <code>klass</code>, return via
7482         <code>classloader_ptr</code> a reference to the class loader for the
7483         class.
7484       </description>
7485       <origin>jvmdi</origin>
7486       <capabilities>
7487       </capabilities>
7488       <parameters>
7489         <param id="klass">
7490           <jclass/>
7491             <description>
7492               The class to query.
7493             </description>
7494         </param>
7495         <param id="classloader_ptr">
7496           <outptr><jobject/></outptr>
7497             <description>
7498               On return, points to the class loader that loaded
7499               this class.
7500               If the class was not created by a class loader
7501               or if the class loader is the bootstrap class loader,
7502               points to <code>NULL</code>.
7503             </description>
7504         </param>
7505       </parameters>
7506       <errors>
7507       </errors>
7508 
7509     </function>
7510 
7511     <function id="GetSourceDebugExtension" phase="start" num="90">
7512       <synopsis>Get Source Debug Extension</synopsis>
7513       <description>
7514         For the class indicated by <code>klass</code>, return the debug
7515         extension via <code>source_debug_extension_ptr</code>.
7516         The returned string
7517         contains exactly the debug extension information present in the
7518         class file of <code>klass</code>.
7519       </description>
7520       <origin>jvmdi</origin>
7521       <capabilities>
7522         <required id="can_get_source_debug_extension"></required>
7523       </capabilities>
7524       <parameters>
7525         <param id="klass">
7526           <jclass/>
7527             <description>
7528               The class to query.
7529             </description>
7530         </param>
7531         <param id="source_debug_extension_ptr">
7532           <allocbuf><char/></allocbuf>
7533           <description>
7534             On return, points to the class's debug extension, encoded as a
7535             <internallink id="mUTF">modified UTF-8</internallink> string.
7536           </description>
7537         </param>
7538       </parameters>
7539       <errors>
7540         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7541           Class information does not include a debug extension.
7542         </error>
7543       </errors>
7544     </function>
7545 
7546     <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
7547       <synopsis>Retransform Classes</synopsis>
7548       <description>
7549         This function facilitates the
7550         <internallink id="bci">bytecode instrumentation</internallink>
7551         of already loaded classes.
7552         To replace the class definition without reference to the existing
7553         bytecodes, as one might do when recompiling from source for
7554         fix-and-continue debugging, <functionlink id="RedefineClasses"/>
7555         function should be used instead.
7556         <p/>
7557         When classes are initially loaded or when they are
7558         <functionlink id="RedefineClasses">redefined</functionlink>,
7559         the initial class file bytes can be transformed with the
7560         <eventlink id="ClassFileLoadHook"/> event.
7561         This function reruns the transformation process
7562         (whether or not a transformation has previously occurred).
7563         This retransformation follows these steps:
7564         <ul>
7565           <li>starting from the initial class file bytes
7566           </li>
7567           <li>for each <fieldlink id="can_retransform_classes"
7568                      struct="jvmtiCapabilities">retransformation
7569                                                 incapable</fieldlink>
7570             agent which received a
7571             <code>ClassFileLoadHook</code> event during the previous
7572             load or redefine, the bytes it returned
7573             (via the <code>new_class_data</code> parameter)
7574             are reused as the output of the transformation;
7575             note that this is equivalent to reapplying
7576             the previous transformation, unaltered. except that
7577             the <code>ClassFileLoadHook</code> event
7578             is <b>not</b> sent to these agents
7579           </li>
7580           <li>for each <fieldlink id="can_retransform_classes"
7581                      struct="jvmtiCapabilities">retransformation
7582                                                 capable</fieldlink>
7583             agent, the <code>ClassFileLoadHook</code> event is sent,
7584             allowing a new transformation to be applied
7585           </li>
7586           <li>the transformed class file bytes are installed as the new
7587             definition of the class
7588           </li>
7589         </ul>
7590         See the <eventlink id="ClassFileLoadHook"/> event for more details.
7591         <p/>
7592         The initial class file bytes represent the bytes passed to
7593         <code>ClassLoader.defineClass</code>
7594         or <code>RedefineClasses</code> (before any transformations
7595         were applied), however they may not exactly match them.
7596         The constant pool may differ in ways described in
7597         <functionlink id="GetConstantPool"/>.
7598         Constant pool indices in the bytecodes of methods will correspond.
7599         Some attributes may not be present.
7600         Where order is not meaningful, for example the order of methods,
7601         order may not be preserved.
7602         <p/>
7603         Retransformation can cause new versions of methods to be installed.
7604         Old method versions may become
7605         <internallink id="obsoleteMethods">obsolete</internallink>
7606         The new method version will be used on new invokes.
7607         If a method has active stack frames, those active frames continue to
7608         run the bytecodes of the original method version.
7609         <p/>
7610         This function does not cause any initialization except that which
7611         would occur under the customary JVM semantics.
7612         In other words, retransforming a class does not cause its initializers to be
7613         run. The values of static fields will remain as they were
7614         prior to the call.
7615         <p/>
7616         Threads need not be suspended.
7617         <p/>
7618         All breakpoints in the class are cleared.
7619         <p/>
7620         All attributes are updated.
7621         <p/>
7622         Instances of the retransformed class are not affected -- fields retain their
7623         previous values.
7624         <functionlink id="GetTag">Tags</functionlink> on the instances are
7625         also unaffected.
7626         <p/>
7627         In response to this call, no events other than the
7628         <eventlink id="ClassFileLoadHook"/> event
7629         will be sent.
7630         <p/>
7631         The retransformation may change method bodies, the constant pool and attributes.
7632         The retransformation must not add, remove or rename fields or methods, change the
7633         signatures of methods, change modifiers, or change inheritance.
7634         These restrictions may be lifted in future versions.
7635         See the error return description below for information on error codes
7636         returned if an unsupported retransformation is attempted.
7637         The class file bytes are not verified or installed until they have passed
7638         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7639         returned error code reflects the result of the transformations.
7640         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7641         none of the classes to be retransformed will have a new definition installed.
7642         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7643         all of the classes to be retransformed will have their new definitions installed.
7644       </description>
7645       <origin>new</origin>
7646       <capabilities>
7647         <required id="can_retransform_classes"></required>
7648         <capability id="can_retransform_any_class"></capability>
7649       </capabilities>
7650       <parameters>
7651         <param id="class_count">
7652           <jint min="0"/>
7653           <description>
7654             The number of classes to be retransformed.
7655           </description>
7656         </param>
7657         <param id="classes">
7658           <inbuf incount="class_count"><jclass/></inbuf>
7659           <description>
7660             The array of classes to be retransformed.
7661           </description>
7662         </param>
7663       </parameters>
7664       <errors>
7665         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7666           One of the <paramlink id="classes"/> cannot be modified.
7667           See <functionlink id="IsModifiableClass"/>.
7668         </error>
7669         <error id="JVMTI_ERROR_INVALID_CLASS">
7670           One of the <paramlink id="classes"/> is not a valid class.
7671         </error>
7672         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7673           A retransformed class file has a version number not supported by this VM.
7674         </error>
7675         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7676           A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>).
7677         </error>
7678         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7679           The retransformed class file definitions would lead to a circular definition
7680           (the VM would return a <code>ClassCircularityError</code>).
7681         </error>
7682         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7683           The retransformed class file bytes fail verification.
7684         </error>
7685         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7686           The class name defined in a retransformed class file is
7687           different from the name in the old class object.
7688         </error>
7689         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7690           A retransformed class file would require adding a method.
7691         </error>
7692         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7693           A retransformed class file changes a field.
7694         </error>
7695         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7696           A direct superclass is different for a retransformed class file,
7697           or the set of directly implemented
7698           interfaces is different.
7699         </error>
7700         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7701           A retransformed class file does not declare a method
7702           declared in the old class version.
7703         </error>
7704         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7705           A retransformed class file has different class modifiers.
7706         </error>
7707         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7708           A method in the retransformed class file has different modifiers
7709           than its counterpart in the old class version.
7710         </error>
7711       </errors>
7712     </function>
7713 
7714     <function id="RedefineClasses" jkernel="yes" num="87">
7715       <synopsis>Redefine Classes</synopsis>
7716       <typedef id="jvmtiClassDefinition" label="Class redefinition description">
7717         <field id="klass">
7718           <jclass/>
7719             <description>
7720               Class object for this class
7721             </description>
7722         </field>
7723         <field id="class_byte_count">
7724           <jint/>
7725           <description>
7726             Number of bytes defining class (below)
7727           </description>
7728         </field>
7729         <field id="class_bytes">
7730           <inbuf incount="class_byte_count"><uchar/></inbuf>
7731           <description>
7732             Bytes defining class (in <vmspec chapter="4"/>)
7733           </description>
7734         </field>
7735       </typedef>
7736       <description>
7737         All classes given are redefined according to the definitions
7738         supplied.
7739         This function is used to replace the definition of a class
7740         with a new definition, as might be needed in fix-and-continue
7741         debugging.
7742         Where the existing class file bytes are to be transformed, for
7743         example in
7744         <internallink id="bci">bytecode instrumentation</internallink>,
7745         <functionlink id="RetransformClasses"/> should be used.
7746         <p/>
7747         Redefinition can cause new versions of methods to be installed.
7748         Old method versions may become
7749         <internallink id="obsoleteMethods">obsolete</internallink>
7750         The new method version will be used on new invokes.
7751         If a method has active stack frames, those active frames continue to
7752         run the bytecodes of the original method version.
7753         If resetting of stack frames is desired, use
7754         <functionlink id="PopFrame"></functionlink>
7755         to pop frames with obsolete method versions.
7756         <p/>
7757         This function does not cause any initialization except that which
7758         would occur under the customary JVM semantics.
7759         In other words, redefining a class does not cause its initializers to be
7760         run. The values of static fields will remain as they were
7761         prior to the call.
7762         <p/>
7763         Threads need not be suspended.
7764         <p/>
7765         All breakpoints in the class are cleared.
7766         <p/>
7767         All attributes are updated.
7768         <p/>
7769         Instances of the redefined class are not affected -- fields retain their
7770         previous values.
7771         <functionlink id="GetTag">Tags</functionlink> on the instances are
7772         also unaffected.
7773         <p/>
7774         In response to this call, the <jvmti/> event
7775         <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
7776         will be sent (if enabled), but no other <jvmti/> events will be sent.
7777         <p/>
7778         The redefinition may change method bodies, the constant pool and attributes.
7779         The redefinition must not add, remove or rename fields or methods, change the
7780         signatures of methods, change modifiers, or change inheritance.
7781         These restrictions may be lifted in future versions.
7782         See the error return description below for information on error codes
7783         returned if an unsupported redefinition is attempted.
7784         The class file bytes are not verified or installed until they have passed
7785         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7786         returned error code reflects the result of the transformations applied
7787         to the bytes passed into <paramlink id="class_definitions"/>.
7788         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7789         none of the classes to be redefined will have a new definition installed.
7790         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7791         all of the classes to be redefined will have their new definitions installed.
7792       </description>
7793       <origin>jvmdi</origin>
7794       <capabilities>
7795         <required id="can_redefine_classes"></required>
7796         <capability id="can_redefine_any_class"></capability>
7797       </capabilities>
7798       <parameters>
7799         <param id="class_count">
7800           <jint min="0"/>
7801           <description>
7802             The number of classes specified in <code>class_definitions</code>
7803           </description>
7804         </param>
7805         <param id="class_definitions">
7806           <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
7807           <description>
7808             The array of new class definitions
7809           </description>
7810         </param>
7811       </parameters>
7812       <errors>
7813         <error id="JVMTI_ERROR_NULL_POINTER">
7814           One of <code>class_bytes</code> is <code>NULL</code>.
7815         </error>
7816         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7817           An element of <code>class_definitions</code> cannot be modified.
7818           See <functionlink id="IsModifiableClass"/>.
7819         </error>
7820         <error id="JVMTI_ERROR_INVALID_CLASS">
7821           An element of <code>class_definitions</code> is not a valid class.
7822         </error>
7823         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7824           A new class file has a version number not supported by this VM.
7825         </error>
7826         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7827           A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
7828         </error>
7829         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7830           The new class file definitions would lead to a circular definition
7831           (the VM would return a <code>ClassCircularityError</code>).
7832         </error>
7833         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7834           The class bytes fail verification.
7835         </error>
7836         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7837           The class name defined in a new class file is
7838           different from the name in the old class object.
7839         </error>
7840         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7841           A new class file would require adding a method.
7842         </error>
7843         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7844           A new class version changes a field.
7845         </error>
7846         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7847           A direct superclass is different for a new class
7848           version, or the set of directly implemented
7849           interfaces is different.
7850         </error>
7851         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7852           A new class version does not declare a method
7853           declared in the old class version.
7854         </error>
7855         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7856           A new class version has different modifiers.
7857         </error>
7858         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7859           A method in the new class version has different modifiers
7860           than its counterpart in the old class version.
7861         </error>
7862         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
7863           A module cannot be modified.
7864           See <functionlink id="IsModifiableModule"/>.
7865         </error>
7866       </errors>
7867     </function>
7868 
7869   </category>
7870 
7871   <category id="object" label="Object">
7872 
7873     <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
7874       <synopsis>Get Object Size</synopsis>
7875       <description>
7876         For the object indicated by <code>object</code>,
7877         return via <code>size_ptr</code> the size of the object.
7878         This size is an implementation-specific approximation of
7879         the amount of storage consumed by this object.
7880         It may include some or all of the object's overhead, and thus
7881         is useful for comparison within an implementation but not
7882         between implementations.
7883         The estimate may change during a single invocation of the JVM.
7884       </description>
7885       <origin>new</origin>
7886       <capabilities>
7887       </capabilities>
7888       <parameters>
7889         <param id="object">
7890           <jobject/>
7891             <description>
7892               The object to query.
7893             </description>
7894         </param>
7895         <param id="size_ptr">
7896           <outptr><jlong/></outptr>
7897           <description>
7898             On return, points to the object's size in bytes.
7899           </description>
7900         </param>
7901       </parameters>
7902       <errors>
7903       </errors>
7904     </function>
7905 
7906     <function id="GetObjectHashCode" phase="start" num="58">
7907       <synopsis>Get Object Hash Code</synopsis>
7908       <description>
7909         For the object indicated by <code>object</code>,
7910         return via <code>hash_code_ptr</code> a hash code.
7911         This hash code could be used to maintain a hash table of object references,
7912         however, on some implementations this can cause significant performance
7913         impacts--in most cases
7914         <internallink id="Heap">tags</internallink>
7915         will be a more efficient means of associating information with objects.
7916         This function guarantees
7917         the same hash code value for a particular object throughout its life
7918       </description>
7919       <origin>jvmdi</origin>
7920       <capabilities>
7921       </capabilities>
7922       <parameters>
7923         <param id="object">
7924           <jobject/>
7925             <description>
7926               The object to query.
7927             </description>
7928         </param>
7929         <param id="hash_code_ptr">
7930           <outptr><jint/></outptr>
7931           <description>
7932             On return, points to the object's hash code.
7933           </description>
7934         </param>
7935       </parameters>
7936       <errors>
7937       </errors>
7938     </function>
7939 
7940     <function id="GetObjectMonitorUsage" num="59">
7941       <synopsis>Get Object Monitor Usage</synopsis>
7942       <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
7943         <field id="owner">
7944           <jthread/>
7945             <description>
7946               The thread owning this monitor, or <code>NULL</code> if unused
7947             </description>
7948         </field>
7949         <field id="entry_count">
7950           <jint/>
7951           <description>
7952             The number of times the owning thread has entered the monitor
7953           </description>
7954         </field>
7955         <field id="waiter_count">
7956           <jint/>
7957           <description>
7958             The number of threads waiting to own this monitor
7959           </description>
7960         </field>
7961         <field id="waiters">
7962           <allocfieldbuf><jthread/></allocfieldbuf>
7963             <description>
7964               The <code>waiter_count</code> waiting threads
7965             </description>
7966         </field>
7967         <field id="notify_waiter_count">
7968           <jint/>
7969           <description>
7970             The number of threads waiting to be notified by this monitor
7971           </description>
7972         </field>
7973         <field id="notify_waiters">
7974           <allocfieldbuf><jthread/></allocfieldbuf>
7975             <description>
7976               The <code>notify_waiter_count</code> threads waiting to be notified
7977             </description>
7978         </field>
7979       </typedef>
7980       <description>
7981         Get information about the object's monitor.
7982         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
7983         are filled in with information about usage of the monitor.
7984           <todo>
7985             Decide and then clarify suspend requirements.
7986           </todo>
7987       </description>
7988       <origin>jvmdi</origin>
7989       <capabilities>
7990         <required id="can_get_monitor_info"></required>
7991       </capabilities>
7992       <parameters>
7993         <param id="object">
7994           <jobject/>
7995             <description>
7996               The object to query.
7997             </description>
7998         </param>
7999         <param id="info_ptr">
8000           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
8001           <description>
8002             On return, filled with monitor information for the
8003             specified object.
8004           </description>
8005         </param>
8006       </parameters>
8007       <errors>
8008       </errors>
8009     </function>
8010 
8011     <elide>
8012     <function id="GetObjectMonitors" num="116">
8013       <synopsis>Get Object Monitors</synopsis>
8014       <description>
8015         Return the list of object monitors.
8016         <p/>
8017         Note: details about each monitor can be examined with
8018         <functionlink id="GetObjectMonitorUsage"></functionlink>.
8019       </description>
8020       <origin>new</origin>
8021       <capabilities>
8022         <required id="can_get_monitor_info"></required>
8023       </capabilities>
8024       <parameters>
8025         <param id="monitorCnt">
8026           <outptr><jint/></outptr>
8027           <description>
8028             On return, pointer to the number
8029             of monitors returned in <code>monitors_ptr</code>.
8030           </description>
8031         </param>
8032         <param id="monitors_ptr">
8033           <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
8034             <description>
8035               On return, pointer to the monitor list.
8036             </description>
8037         </param>
8038       </parameters>
8039       <errors>
8040       </errors>
8041     </function>
8042     </elide>
8043 
8044   </category>
8045 
8046   <category id="fieldCategory" label="Field">
8047 
8048     <intro>
8049     </intro>
8050 
8051     <function id="GetFieldName" phase="start" num="60">
8052       <synopsis>Get Field Name (and Signature)</synopsis>
8053       <description>
8054         For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
8055         return the field name via <paramlink id="name_ptr"/> and field signature via
8056         <paramlink id="signature_ptr"/>.
8057         <p/>
8058         Field signatures are defined in the
8059         <externallink id="jni/index.html">JNI Specification</externallink>
8060         and are referred to as <code>field descriptors</code> in
8061         <vmspec chapter="4.3.2"/>.
8062       </description>
8063       <origin>jvmdiClone</origin>
8064       <capabilities>
8065       </capabilities>
8066       <parameters>
8067         <param id="klass">
8068           <jclass field="field"/>
8069             <description>
8070               The class of the field to query.
8071             </description>
8072         </param>
8073         <param id="field">
8074           <jfieldID class="klass"/>
8075             <description>
8076               The field to query.
8077             </description>
8078         </param>
8079         <param id="name_ptr">
8080           <allocbuf>
8081             <char/>
8082             <nullok>the name is not returned</nullok>
8083           </allocbuf>
8084           <description>
8085             On return, points to the field name, encoded as a
8086             <internallink id="mUTF">modified UTF-8</internallink> string.
8087           </description>
8088         </param>
8089         <param id="signature_ptr">
8090           <allocbuf>
8091             <char/>
8092             <nullok>the signature is not returned</nullok>
8093           </allocbuf>
8094           <description>
8095             On return, points to the field signature, encoded as a
8096             <internallink id="mUTF">modified UTF-8</internallink> string.
8097           </description>
8098         </param>
8099         <param id="generic_ptr">
8100           <allocbuf>
8101             <char/>
8102             <nullok>the generic signature is not returned</nullok>
8103           </allocbuf>
8104           <description>
8105             On return, points to the generic signature of the field, encoded as a
8106             <internallink id="mUTF">modified UTF-8</internallink> string.
8107             If there is no generic signature attribute for the field, then,
8108             on return, points to <code>NULL</code>.
8109           </description>
8110         </param>
8111       </parameters>
8112       <errors>
8113       </errors>
8114     </function>
8115 
8116     <function id="GetFieldDeclaringClass" phase="start" num="61">
8117       <synopsis>Get Field Declaring Class</synopsis>
8118       <description>
8119         For the field indicated by <code>klass</code> and <code>field</code>
8120         return the class that defined it via <code>declaring_class_ptr</code>.
8121         The declaring class will either be <code>klass</code>, a superclass, or
8122         an implemented interface.
8123       </description>
8124       <origin>jvmdi</origin>
8125       <capabilities>
8126       </capabilities>
8127       <parameters>
8128         <param id="klass">
8129           <jclass field="field"/>
8130             <description>
8131               The class to query.
8132             </description>
8133         </param>
8134         <param id="field">
8135           <jfieldID class="klass"/>
8136             <description>
8137               The field to query.
8138             </description>
8139         </param>
8140         <param id="declaring_class_ptr">
8141           <outptr><jclass/></outptr>
8142             <description>
8143               On return, points to the declaring class
8144             </description>
8145         </param>
8146       </parameters>
8147       <errors>
8148       </errors>
8149     </function>
8150 
8151     <function id="GetFieldModifiers" phase="start" num="62">
8152       <synopsis>Get Field Modifiers</synopsis>
8153       <description>
8154         For the field indicated by <code>klass</code> and <code>field</code>
8155         return the access flags via <code>modifiers_ptr</code>.
8156         Access flags are defined in <vmspec chapter="4"/>.
8157       </description>
8158       <origin>jvmdi</origin>
8159       <capabilities>
8160       </capabilities>
8161       <parameters>
8162         <param id="klass">
8163           <jclass field="field"/>
8164             <description>
8165               The class to query.
8166             </description>
8167         </param>
8168         <param id="field">
8169           <jfieldID class="klass"/>
8170             <description>
8171               The field to query.
8172             </description>
8173         </param>
8174         <param id="modifiers_ptr">
8175           <outptr><jint/></outptr>
8176           <description>
8177             On return, points to the access flags.
8178           </description>
8179         </param>
8180       </parameters>
8181       <errors>
8182       </errors>
8183     </function>
8184 
8185     <function id="IsFieldSynthetic" phase="start" num="63">
8186       <synopsis>Is Field Synthetic</synopsis>
8187       <description>
8188         For the field indicated by <code>klass</code> and <code>field</code>, return a
8189         value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
8190         Synthetic fields are generated by the compiler but not present in the
8191         original source code.
8192       </description>
8193       <origin>jvmdi</origin>
8194       <capabilities>
8195         <required id="can_get_synthetic_attribute"></required>
8196       </capabilities>
8197       <parameters>
8198         <param id="klass">
8199           <jclass field="field"/>
8200             <description>
8201               The class of the field to query.
8202             </description>
8203         </param>
8204         <param id="field">
8205           <jfieldID class="klass"/>
8206             <description>
8207               The field to query.
8208             </description>
8209         </param>
8210         <param id="is_synthetic_ptr">
8211           <outptr><jboolean/></outptr>
8212           <description>
8213             On return, points to the boolean result of this function.
8214           </description>
8215         </param>
8216       </parameters>
8217       <errors>
8218       </errors>
8219     </function>
8220 
8221   </category>
8222 
8223   <category id="method" label="Method">
8224 
8225     <intro>
8226       These functions provide information about a method (represented as a
8227       <typelink id="jmethodID"/>) and set how methods are processed.
8228     </intro>
8229 
8230     <intro id="obsoleteMethods" label="Obsolete Methods">
8231       The functions <functionlink id="RetransformClasses"/> and
8232       <functionlink id="RedefineClasses"/> can cause new versions
8233       of methods to be installed.
8234       An original version of a method is considered equivalent
8235       to the new version if:
8236       <ul>
8237         <li>their bytecodes are the same except for indices into the
8238           constant pool and </li>
8239         <li>the referenced constants are equal.</li>
8240       </ul>
8241       An original method version which is not equivalent to the
8242       new method version is called obsolete and is assigned a new method ID;
8243       the original method ID now refers to the new method version.
8244       A method ID can be tested for obsolescence with
8245       <functionlink id="IsMethodObsolete"/>.
8246     </intro>
8247 
8248     <function id="GetMethodName" phase="start" num="64">
8249       <synopsis>Get Method Name (and Signature)</synopsis>
8250       <description>
8251         For the method indicated by <code>method</code>,
8252         return the method name via <code>name_ptr</code> and method signature via
8253         <code>signature_ptr</code>.
8254         <p/>
8255         Method signatures are defined in the
8256         <externallink id="jni/index.html">JNI Specification</externallink>
8257         and are referred to as <code>method descriptors</code> in
8258         <vmspec chapter="4.3.3"/>.
8259         Note this is different
8260         than method signatures as defined in the <i>Java Language Specification</i>.
8261       </description>
8262       <origin>jvmdiClone</origin>
8263       <capabilities>
8264       </capabilities>
8265       <parameters>
8266         <param id="method">
8267           <jmethodID/>
8268             <description>
8269               The method to query.
8270             </description>
8271         </param>
8272         <param id="name_ptr">
8273           <allocbuf>
8274             <char/>
8275             <nullok>the name is not returned</nullok>
8276           </allocbuf>
8277           <description>
8278             On return, points to the method name, encoded as a
8279             <internallink id="mUTF">modified UTF-8</internallink> string.
8280           </description>
8281         </param>
8282         <param id="signature_ptr">
8283           <allocbuf>
8284             <char/>
8285             <nullok>the signature is not returned</nullok>
8286           </allocbuf>
8287           <description>
8288             On return, points to the method signature, encoded as a
8289             <internallink id="mUTF">modified UTF-8</internallink> string.
8290           </description>
8291         </param>
8292         <param id="generic_ptr">
8293           <allocbuf>
8294             <char/>
8295             <nullok>the generic signature is not returned</nullok>
8296           </allocbuf>
8297           <description>
8298             On return, points to the generic signature of the method, encoded as a
8299             <internallink id="mUTF">modified UTF-8</internallink> string.
8300             If there is no generic signature attribute for the method, then,
8301             on return, points to <code>NULL</code>.
8302           </description>
8303         </param>
8304       </parameters>
8305       <errors>
8306       </errors>
8307     </function>
8308 
8309     <function id="GetMethodDeclaringClass" phase="start" num="65">
8310       <synopsis>Get Method Declaring Class</synopsis>
8311       <description>
8312         For the method indicated by <code>method</code>,
8313         return the class that defined it via <code>declaring_class_ptr</code>.
8314       </description>
8315       <origin>jvmdi</origin>
8316       <capabilities>
8317       </capabilities>
8318       <parameters>
8319         <param id="klass">
8320           <jclass method="method"/>
8321             <description>
8322               The class to query.
8323             </description>
8324         </param>
8325         <param id="method">
8326           <jmethodID class="klass"/>
8327             <description>
8328               The method to query.
8329             </description>
8330         </param>
8331         <param id="declaring_class_ptr">
8332           <outptr><jclass/></outptr>
8333             <description>
8334               On return, points to the declaring class
8335             </description>
8336         </param>
8337       </parameters>
8338       <errors>
8339       </errors>
8340     </function>
8341 
8342     <function id="GetMethodModifiers" phase="start" num="66">
8343       <synopsis>Get Method Modifiers</synopsis>
8344       <description>
8345         For the method indicated by <code>method</code>,
8346         return the access flags via <code>modifiers_ptr</code>.
8347         Access flags are defined in <vmspec chapter="4"/>.
8348       </description>
8349       <origin>jvmdi</origin>
8350       <capabilities>
8351       </capabilities>
8352       <parameters>
8353         <param id="klass">
8354           <jclass method="method"/>
8355             <description>
8356               The class to query.
8357             </description>
8358         </param>
8359         <param id="method">
8360           <jmethodID class="klass"/>
8361             <description>
8362               The method to query.
8363             </description>
8364         </param>
8365         <param id="modifiers_ptr">
8366           <outptr><jint/></outptr>
8367           <description>
8368             On return, points to the access flags.
8369           </description>
8370         </param>
8371       </parameters>
8372       <errors>
8373       </errors>
8374     </function>
8375 
8376     <function id="GetMaxLocals" phase="start" num="68">
8377       <synopsis>Get Max Locals</synopsis>
8378       <description>
8379           For the method indicated by <code>method</code>,
8380           return the number of local variable slots used by the method,
8381           including the local variables used to pass parameters to the
8382           method on its invocation.
8383           <p/>
8384           See <code>max_locals</code> in <vmspec chapter="4.7.3"/>.
8385       </description>
8386       <origin>jvmdi</origin>
8387       <capabilities>
8388       </capabilities>
8389       <parameters>
8390         <param id="klass">
8391           <jclass method="method"/>
8392             <description>
8393               The class to query.
8394             </description>
8395         </param>
8396         <param id="method">
8397           <jmethodID class="klass" native="error"/>
8398             <description>
8399               The method to query.
8400             </description>
8401         </param>
8402         <param id="max_ptr">
8403           <outptr><jint/></outptr>
8404           <description>
8405             On return, points to the maximum number of local slots
8406           </description>
8407         </param>
8408       </parameters>
8409       <errors>
8410       </errors>
8411     </function>
8412 
8413     <function id="GetArgumentsSize" phase="start" num="69">
8414       <synopsis>Get Arguments Size</synopsis>
8415       <description>
8416         For the method indicated by <code>method</code>,
8417         return via <code>max_ptr</code> the number of local variable slots used
8418         by the method's arguments.
8419         Note that two-word arguments use two slots.
8420       </description>
8421       <origin>jvmdi</origin>
8422       <capabilities>
8423       </capabilities>
8424       <parameters>
8425         <param id="klass">
8426           <jclass method="method"/>
8427             <description>
8428               The class to query.
8429             </description>
8430         </param>
8431         <param id="method">
8432           <jmethodID class="klass" native="error"/>
8433             <description>
8434               The method to query.
8435             </description>
8436         </param>
8437         <param id="size_ptr">
8438           <outptr><jint/></outptr>
8439           <description>
8440             On return, points to the number of argument slots
8441           </description>
8442         </param>
8443       </parameters>
8444       <errors>
8445       </errors>
8446     </function>
8447 
8448     <function id="GetLineNumberTable" phase="start" num="70">
8449       <synopsis>Get Line Number Table</synopsis>
8450       <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
8451         <field id="start_location">
8452           <jlocation/>
8453           <description>
8454             the <datalink id="jlocation"></datalink> where the line begins
8455           </description>
8456         </field>
8457         <field id="line_number">
8458           <jint/>
8459           <description>
8460             the line number
8461           </description>
8462         </field>
8463       </typedef>
8464       <description>
8465         For the method indicated by <code>method</code>,
8466         return a table of source line number entries. The size of the table is
8467         returned via <code>entry_count_ptr</code> and the table itself is
8468         returned via <code>table_ptr</code>.
8469       </description>
8470       <origin>jvmdi</origin>
8471       <capabilities>
8472         <required id="can_get_line_numbers"></required>
8473       </capabilities>
8474       <parameters>
8475         <param id="klass">
8476           <jclass method="method"/>
8477             <description>
8478               The class to query.
8479             </description>
8480         </param>
8481         <param id="method">
8482           <jmethodID class="klass" native="error"/>
8483             <description>
8484               The method to query.
8485             </description>
8486         </param>
8487         <param id="entry_count_ptr">
8488           <outptr><jint/></outptr>
8489           <description>
8490             On return, points to the number of entries in the table
8491           </description>
8492         </param>
8493         <param id="table_ptr">
8494           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
8495           <description>
8496             On return, points to the line number table pointer.
8497           </description>
8498         </param>
8499       </parameters>
8500       <errors>
8501         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8502           Class information does not include line numbers.
8503         </error>
8504       </errors>
8505     </function>
8506 
8507     <function id="GetMethodLocation" phase="start" num="71">
8508       <synopsis>Get Method Location</synopsis>
8509       <description>
8510         For the method indicated by <code>method</code>,
8511         return the beginning and ending addresses through
8512         <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
8513         conventional byte code indexing scheme,
8514         <code>start_location_ptr</code> will always point to zero
8515         and <code>end_location_ptr</code>
8516         will always point to the byte code count minus one.
8517       </description>
8518       <origin>jvmdi</origin>
8519       <capabilities>
8520       </capabilities>
8521       <parameters>
8522         <param id="klass">
8523           <jclass method="method"/>
8524             <description>
8525               The class to query.
8526             </description>
8527         </param>
8528         <param id="method">
8529           <jmethodID class="klass" native="error"/>
8530             <description>
8531               The method to query.
8532             </description>
8533         </param>
8534         <param id="start_location_ptr">
8535           <outptr><jlocation/></outptr>
8536           <description>
8537             On return, points to the first location, or
8538             <code>-1</code> if location information is not available.
8539             If the information is available and
8540             <functionlink id="GetJLocationFormat"></functionlink>
8541             returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
8542             then this will always be zero.
8543           </description>
8544         </param>
8545         <param id="end_location_ptr">
8546           <outptr><jlocation/></outptr>
8547           <description>
8548             On return, points to the last location,
8549             or <code>-1</code> if location information is not available.
8550           </description>
8551         </param>
8552       </parameters>
8553       <errors>
8554         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8555           Class information does not include method sizes.
8556         </error>
8557       </errors>
8558     </function>
8559 
8560     <function id="GetLocalVariableTable" num="72">
8561       <synopsis>Get Local Variable Table</synopsis>
8562       <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
8563         <field id="start_location">
8564           <jlocation/>
8565           <description>
8566             The code array index where the local variable is first valid
8567             (that is, where it must have a value).
8568           </description>
8569         </field>
8570         <field id="length">
8571           <jint/>
8572           <description>
8573             The length of the valid section for this local variable.
8574             The last code array index where the local variable is valid
8575             is <code>start_location + length</code>.
8576           </description>
8577         </field>
8578         <field id="name">
8579           <allocfieldbuf><char/></allocfieldbuf>
8580           <description>
8581             The local variable name, encoded as a
8582             <internallink id="mUTF">modified UTF-8</internallink> string.
8583           </description>
8584         </field>
8585         <field id="signature">
8586           <allocfieldbuf><char/></allocfieldbuf>
8587           <description>
8588             The local variable's type signature, encoded as a
8589             <internallink id="mUTF">modified UTF-8</internallink> string.
8590             The signature format is the same as that defined in
8591             <vmspec chapter="4.3.2"/>.
8592           </description>
8593         </field>
8594         <field id="generic_signature">
8595           <allocfieldbuf><char/></allocfieldbuf>
8596           <description>
8597             The local variable's generic signature, encoded as a
8598             <internallink id="mUTF">modified UTF-8</internallink> string.
8599             The value of this field will be <code>NULL</code> for any local
8600             variable which does not have a generic type.
8601           </description>
8602         </field>
8603         <field id="slot">
8604           <jint/>
8605           <description>
8606             The local variable's slot.  See <internallink id="local">Local Variables</internallink>.
8607           </description>
8608         </field>
8609       </typedef>
8610       <description>
8611         Return local variable information.
8612       </description>
8613       <origin>jvmdiClone</origin>
8614       <capabilities>
8615         <required id="can_access_local_variables"></required>
8616       </capabilities>
8617       <parameters>
8618         <param id="method">
8619           <jmethodID native="error"/>
8620             <description>
8621               The method to query.
8622             </description>
8623         </param>
8624         <param id="entry_count_ptr">
8625           <outptr><jint/></outptr>
8626           <description>
8627             On return, points to the number of entries in the table
8628           </description>
8629         </param>
8630         <param id="table_ptr">
8631           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
8632           <description>
8633             On return, points to an array of local variable table entries.
8634           </description>
8635         </param>
8636       </parameters>
8637       <errors>
8638         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8639           Class information does not include local variable
8640           information.
8641         </error>
8642       </errors>
8643     </function>
8644 
8645     <function id="GetBytecodes" phase="start" num="75">
8646       <synopsis>Get Bytecodes</synopsis>
8647       <description>
8648         For the method indicated by <code>method</code>,
8649         return the byte codes that implement the method. The number of
8650         bytecodes is returned via <code>bytecode_count_ptr</code>. The byte codes
8651         themselves are returned via <code>bytecodes_ptr</code>.
8652       </description>
8653       <origin>jvmdi</origin>
8654       <capabilities>
8655         <required id="can_get_bytecodes"></required>
8656       </capabilities>
8657       <parameters>
8658         <param id="klass">
8659           <jclass method="method"/>
8660             <description>
8661               The class to query.
8662             </description>
8663         </param>
8664         <param id="method">
8665           <jmethodID class="klass" native="error"/>
8666             <description>
8667               The method to query.
8668             </description>
8669         </param>
8670         <param id="bytecode_count_ptr">
8671           <outptr><jint/></outptr>
8672           <description>
8673             On return, points to the length of the byte code array
8674           </description>
8675         </param>
8676         <param id="bytecodes_ptr">
8677           <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
8678           <description>
8679             On return, points to the pointer to the byte code array
8680           </description>
8681         </param>
8682       </parameters>
8683       <errors>
8684       </errors>
8685     </function>
8686 
8687     <function id="IsMethodNative" phase="start" num="76">
8688       <synopsis>Is Method Native</synopsis>
8689       <description>
8690         For the method indicated by <code>method</code>, return a
8691         value indicating whether the method is native via <code>is_native_ptr</code>
8692       </description>
8693       <origin>jvmdi</origin>
8694       <capabilities>
8695       </capabilities>
8696       <parameters>
8697         <param id="klass">
8698           <jclass method="method"/>
8699             <description>
8700               The class to query.
8701             </description>
8702         </param>
8703         <param id="method">
8704           <jmethodID class="klass"/>
8705             <description>
8706               The method to query.
8707             </description>
8708         </param>
8709         <param id="is_native_ptr">
8710           <outptr><jboolean/></outptr>
8711           <description>
8712             On return, points to the boolean result of this function.
8713           </description>
8714         </param>
8715       </parameters>
8716       <errors>
8717       </errors>
8718     </function>
8719 
8720     <function id="IsMethodSynthetic" phase="start" num="77">
8721       <synopsis>Is Method Synthetic</synopsis>
8722       <description>
8723         For the method indicated by <code>method</code>, return a
8724         value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
8725         Synthetic methods are generated by the compiler but not present in the
8726         original source code.
8727       </description>
8728       <origin>jvmdi</origin>
8729       <capabilities>
8730         <required id="can_get_synthetic_attribute"></required>
8731       </capabilities>
8732       <parameters>
8733         <param id="klass">
8734           <jclass method="method"/>
8735             <description>
8736               The class to query.
8737             </description>
8738         </param>
8739         <param id="method">
8740           <jmethodID class="klass"/>
8741             <description>
8742               The method to query.
8743             </description>
8744         </param>
8745         <param id="is_synthetic_ptr">
8746           <outptr><jboolean/></outptr>
8747           <description>
8748             On return, points to the boolean result of this function.
8749           </description>
8750         </param>
8751       </parameters>
8752       <errors>
8753       </errors>
8754     </function>
8755 
8756     <function id="IsMethodObsolete" phase="start" num="91">
8757       <synopsis>Is Method Obsolete</synopsis>
8758       <description>
8759         Determine if a method ID refers to an
8760         <internallink id="obsoleteMethods">obsolete</internallink>
8761         method version.
8762       </description>
8763       <origin>jvmdi</origin>
8764       <capabilities>
8765       </capabilities>
8766       <parameters>
8767         <param id="klass">
8768           <jclass method="method"/>
8769             <description>
8770               The class to query.
8771             </description>
8772         </param>
8773         <param id="method">
8774           <jmethodID class="klass"/>
8775             <description>
8776               The method ID to query.
8777             </description>
8778         </param>
8779         <param id="is_obsolete_ptr">
8780           <outptr><jboolean/></outptr>
8781           <description>
8782             On return, points to the boolean result of this function.
8783           </description>
8784         </param>
8785       </parameters>
8786       <errors>
8787       </errors>
8788     </function>
8789 
8790     <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
8791       <synopsis>Set Native Method Prefix</synopsis>
8792       <description>
8793         This function modifies the failure handling of
8794         native method resolution by allowing retry
8795         with a prefix applied to the name.
8796         When used with the
8797         <eventlink id="ClassFileLoadHook">ClassFileLoadHook
8798         event</eventlink>, it enables native methods to be
8799         <internallink id="bci">instrumented</internallink>.
8800         <p/>
8801         Since native methods cannot be directly instrumented
8802         (they have no bytecodes), they must be wrapped with
8803         a non-native method which can be instrumented.
8804         For example, if we had:
8805         <example>
8806 native boolean foo(int x);</example>
8807         <p/>
8808         We could transform the class file (with the
8809         ClassFileLoadHook event) so that this becomes:
8810         <example>
8811 boolean foo(int x) {
8812   <i>... record entry to foo ...</i>
8813   return wrapped_foo(x);
8814 }
8815 
8816 native boolean wrapped_foo(int x);</example>
8817         <p/>
8818         Where foo becomes a wrapper for the actual native method
8819         with the appended prefix "wrapped_".  Note that
8820         "wrapped_" would be a poor choice of prefix since it
8821         might conceivably form the name of an existing method
8822         thus something like "$$$MyAgentWrapped$$$_" would be
8823         better but would make these examples less readable.
8824         <p/>
8825         The wrapper will allow data to be collected on the native
8826         method call, but now the problem becomes linking up the
8827         wrapped method with the native implementation.
8828         That is, the method <code>wrapped_foo</code> needs to be
8829         resolved to the native implementation of <code>foo</code>,
8830         which might be:
8831         <example>
8832 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
8833         <p/>
8834         This function allows the prefix to be specified and the
8835         proper resolution to occur.
8836         Specifically, when the standard resolution fails, the
8837         resolution is retried taking the prefix into consideration.
8838         There are two ways that resolution occurs, explicit
8839         resolution with the JNI function <code>RegisterNatives</code>
8840         and the normal automatic resolution.  For
8841         <code>RegisterNatives</code>, the VM will attempt this
8842         association:
8843         <example>
8844 method(foo) -> nativeImplementation(foo)</example>
8845         <p/>
8846         When this fails, the resolution will be retried with
8847         the specified prefix prepended to the method name,
8848         yielding the correct resolution:
8849         <example>
8850 method(wrapped_foo) -> nativeImplementation(foo)</example>
8851         <p/>
8852         For automatic resolution, the VM will attempt:
8853         <example>
8854 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
8855         <p/>
8856         When this fails, the resolution will be retried with
8857         the specified prefix deleted from the implementation name,
8858         yielding the correct resolution:
8859         <example>
8860 method(wrapped_foo) -> nativeImplementation(foo)</example>
8861         <p/>
8862         Note that since the prefix is only used when standard
8863         resolution fails, native methods can be wrapped selectively.
8864         <p/>
8865         Since each <jvmti/> environment is independent and
8866         can do its own transformation of the bytecodes, more
8867         than one layer of wrappers may be applied. Thus each
8868         environment needs its own prefix.  Since transformations
8869         are applied in order, the prefixes, if applied, will
8870         be applied in the same order.
8871         The order of transformation application is described in
8872         the <eventlink id="ClassFileLoadHook"/> event.
8873         Thus if three environments applied
8874         wrappers, <code>foo</code> might become
8875         <code>$env3_$env2_$env1_foo</code>.  But if, say,
8876         the second environment did not apply a wrapper to
8877         <code>foo</code> it would be just
8878         <code>$env3_$env1_foo</code>.  To be able to
8879         efficiently determine the sequence of prefixes,
8880         an intermediate prefix is only applied if its non-native
8881         wrapper exists.  Thus, in the last example, even though
8882         <code>$env1_foo</code> is not a native method, the
8883         <code>$env1_</code> prefix is applied since
8884         <code>$env1_foo</code> exists.
8885         <p/>
8886         Since the prefixes are used at resolution time
8887         and since resolution may be arbitrarily delayed, a
8888         native method prefix must remain set as long as there
8889         are corresponding prefixed native methods.
8890       </description>
8891       <origin>new</origin>
8892       <capabilities>
8893         <required id="can_set_native_method_prefix"></required>
8894       </capabilities>
8895       <parameters>
8896         <param id="prefix">
8897           <inbuf>
8898             <char/>
8899             <nullok>
8900               any existing prefix in this environment is cancelled
8901             </nullok>
8902           </inbuf>
8903           <description>
8904             The prefix to apply, encoded as a
8905             <internallink id="mUTF">modified UTF-8</internallink> string.
8906           </description>
8907         </param>
8908       </parameters>
8909       <errors>
8910       </errors>
8911     </function>
8912 
8913     <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
8914       <synopsis>Set Native Method Prefixes</synopsis>
8915       <description>
8916          For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
8917          will provide all needed native method prefixing.
8918          For a meta-agent that performs multiple independent class
8919          file transformations (for example as a proxy for another
8920          layer of agents) this function allows each transformation
8921          to have its own prefix.
8922          The prefixes are applied in the order supplied and are
8923          processed in the same manor as described for the
8924          application of prefixes from multiple <jvmti/> environments
8925          in <functionlink id="SetNativeMethodPrefix"/>.
8926          <p/>
8927          Any previous prefixes are replaced.  Thus, calling this
8928          function with a <paramlink id="prefix_count"/> of <code>0</code>
8929          disables prefixing in this environment.
8930          <p/>
8931          <functionlink id="SetNativeMethodPrefix"/> and this function
8932          are the two ways to set the prefixes.
8933          Calling <code>SetNativeMethodPrefix</code> with
8934          a prefix is the same as calling this function with
8935          <paramlink id="prefix_count"/> of <code>1</code>.
8936          Calling <code>SetNativeMethodPrefix</code> with
8937          <code>NULL</code> is the same as calling this function with
8938          <paramlink id="prefix_count"/> of <code>0</code>.
8939       </description>
8940       <origin>new</origin>
8941       <capabilities>
8942         <required id="can_set_native_method_prefix"></required>
8943       </capabilities>
8944       <parameters>
8945         <param id="prefix_count">
8946           <jint min="0"/>
8947             <description>
8948               The number of prefixes to apply.
8949             </description>
8950         </param>
8951         <param id="prefixes">
8952           <agentbuf>
8953             <char/>
8954           </agentbuf>
8955           <description>
8956             The prefixes to apply for this environment, each encoded as a
8957             <internallink id="mUTF">modified UTF-8</internallink> string.
8958           </description>
8959         </param>
8960       </parameters>
8961       <errors>
8962       </errors>
8963     </function>
8964 
8965   </category>
8966 
8967   <category id="RawMonitors" label="Raw Monitor">
8968 
8969     <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
8970       <synopsis>Create Raw Monitor</synopsis>
8971       <description>
8972         Create a raw monitor.
8973       </description>
8974       <origin>jvmdi</origin>
8975       <capabilities>
8976       </capabilities>
8977       <parameters>
8978         <param id="name">
8979           <inbuf><char/></inbuf>
8980           <description>
8981             A name to identify the monitor, encoded as a
8982             <internallink id="mUTF">modified UTF-8</internallink> string.
8983           </description>
8984         </param>
8985         <param id="monitor_ptr">
8986           <outptr><jrawMonitorID/></outptr>
8987           <description>
8988             On return, points to the created monitor.
8989           </description>
8990         </param>
8991       </parameters>
8992       <errors>
8993       </errors>
8994     </function>
8995 
8996     <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
8997       <synopsis>Destroy Raw Monitor</synopsis>
8998       <description>
8999         Destroy the raw monitor.
9000         If the monitor being destroyed has been entered by this thread, it will be
9001         exited before it is destroyed.
9002         If the monitor being destroyed has been entered by another thread,
9003         an error will be returned and the monitor will not be destroyed.
9004       </description>
9005       <origin>jvmdi</origin>
9006       <capabilities>
9007       </capabilities>
9008       <parameters>
9009         <param id="monitor">
9010           <jrawMonitorID/>
9011           <description>
9012             The monitor
9013           </description>
9014         </param>
9015       </parameters>
9016       <errors>
9017         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9018           Not monitor owner
9019         </error>
9020       </errors>
9021     </function>
9022 
9023     <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
9024       <synopsis>Raw Monitor Enter</synopsis>
9025       <description>
9026         Gain exclusive ownership of a raw monitor.
9027         The same thread may enter a monitor more then once.
9028         The thread must
9029         <functionlink id="RawMonitorExit">exit</functionlink>
9030         the monitor the same number of times as it is entered.
9031         If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
9032         and has not exited when attached threads come into existence, the enter
9033         is considered to have occurred on the main thread.
9034       </description>
9035       <origin>jvmdi</origin>
9036       <capabilities>
9037       </capabilities>
9038       <parameters>
9039         <param id="monitor">
9040           <jrawMonitorID/>
9041           <description>
9042             The monitor
9043           </description>
9044         </param>
9045       </parameters>
9046       <errors>
9047       </errors>
9048     </function>
9049 
9050     <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
9051       <synopsis>Raw Monitor Exit</synopsis>
9052       <description>
9053         Release exclusive ownership of a raw monitor.
9054       </description>
9055       <origin>jvmdi</origin>
9056       <capabilities>
9057       </capabilities>
9058       <parameters>
9059         <param id="monitor">
9060           <jrawMonitorID/>
9061           <description>
9062             The monitor
9063           </description>
9064         </param>
9065       </parameters>
9066       <errors>
9067         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9068           Not monitor owner
9069         </error>
9070       </errors>
9071     </function>
9072 
9073     <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
9074       <synopsis>Raw Monitor Wait</synopsis>
9075       <description>
9076         Wait for notification of the raw monitor.
9077         <p/>
9078         Causes the current thread to wait until either another thread calls
9079         <functionlink id="RawMonitorNotify"/> or
9080         <functionlink id="RawMonitorNotifyAll"/>
9081         for the specified raw monitor, or the specified
9082         <paramlink id="millis">timeout</paramlink>
9083         has elapsed.
9084       </description>
9085       <origin>jvmdi</origin>
9086       <capabilities>
9087       </capabilities>
9088       <parameters>
9089         <param id="monitor">
9090           <jrawMonitorID/>
9091           <description>
9092             The monitor
9093           </description>
9094         </param>
9095         <param id="millis">
9096           <jlong/>
9097           <description>
9098             The timeout, in milliseconds.  If the timeout is
9099             zero, then real time is not taken into consideration
9100             and the thread simply waits until notified.
9101           </description>
9102         </param>
9103       </parameters>
9104       <errors>
9105         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9106           Not monitor owner
9107         </error>
9108         <error id="JVMTI_ERROR_INTERRUPT">
9109           Wait was interrupted, try again
9110         </error>
9111       </errors>
9112     </function>
9113 
9114     <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
9115       <synopsis>Raw Monitor Notify</synopsis>
9116       <description>
9117         Notify a single thread waiting on the raw monitor.
9118       </description>
9119       <origin>jvmdi</origin>
9120       <capabilities>
9121       </capabilities>
9122       <parameters>
9123         <param id="monitor">
9124           <jrawMonitorID/>
9125           <description>
9126             The monitor
9127           </description>
9128         </param>
9129       </parameters>
9130       <errors>
9131         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9132           Not monitor owner
9133         </error>
9134       </errors>
9135     </function>
9136 
9137     <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
9138       <synopsis>Raw Monitor Notify All</synopsis>
9139       <description>
9140         Notify all threads waiting on the raw monitor.
9141       </description>
9142       <origin>jvmdi</origin>
9143       <capabilities>
9144       </capabilities>
9145       <parameters>
9146         <param id="monitor">
9147           <jrawMonitorID/>
9148           <description>
9149             The monitor
9150           </description>
9151         </param>
9152       </parameters>
9153       <errors>
9154         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9155           Not monitor owner
9156         </error>
9157       </errors>
9158     </function>
9159 
9160    <elide>
9161     <function id="GetRawMonitorUse" num="118">
9162       <synopsis>Get Raw Monitor Use</synopsis>
9163       <description>
9164         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
9165         are filled in with information about usage of the raw monitor.
9166       </description>
9167       <origin>new</origin>
9168       <capabilities>
9169         <required id="can_get_raw_monitor_usage"></required>
9170       </capabilities>
9171       <parameters>
9172         <param id="monitor">
9173           <jrawMonitorID/>
9174           <description>
9175             the raw monitor to query.
9176           </description>
9177         </param>
9178         <param id="info_ptr">
9179           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
9180           <description>
9181             On return, filled with monitor information for the
9182             specified raw monitor.
9183           </description>
9184         </param>
9185       </parameters>
9186       <errors>
9187       </errors>
9188     </function>
9189 
9190     <function id="GetRawMonitors" num="119">
9191       <synopsis>Get Raw Monitors</synopsis>
9192       <description>
9193         Return the list of raw monitors.
9194         <p/>
9195         Note: details about each monitor can be examined with
9196         <functionlink id="GetRawMonitorUse"></functionlink>.
9197       </description>
9198       <origin>new</origin>
9199       <capabilities>
9200         <required id="can_get_raw_monitor_usage"></required>
9201       </capabilities>
9202       <parameters>
9203         <param id="monitorCnt">
9204           <outptr><jint/></outptr>
9205           <description>
9206             On return, pointer to the number
9207             of monitors returned in <code>monitors_ptr</code>.
9208           </description>
9209         </param>
9210         <param id="monitors_ptr">
9211           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
9212           <description>
9213             On return, pointer to the monitor list.
9214           </description>
9215         </param>
9216       </parameters>
9217       <errors>
9218       </errors>
9219     </function>
9220     </elide>
9221   </category>
9222 
9223   <category id="jniIntercept" label="JNI Function Interception">
9224 
9225     <intro>
9226       Provides the ability to intercept and resend
9227       Java Native Interface (JNI) function calls
9228       by manipulating the JNI function table.
9229       See <externallink id="jni/functions.html">JNI
9230         Functions</externallink> in the <i>Java Native Interface Specification</i>.
9231       <p/>
9232       The following example illustrates intercepting the
9233       <code>NewGlobalRef</code> JNI call in order to count reference
9234       creation.
9235       <example>
9236 JNIEnv original_jni_Functions;
9237 JNIEnv redirected_jni_Functions;
9238 int my_global_ref_count = 0;
9239 
9240 jobject
9241 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
9242    ++my_global_ref_count;
9243    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
9244 }
9245 
9246 void
9247 myInit() {
9248    jvmtiError err;
9249 
9250    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;original_jni_Functions);
9251    if (err != JVMTI_ERROR_NONE) {
9252       die();
9253    }
9254    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;redirected_jni_Functions);
9255    if (err != JVMTI_ERROR_NONE) {
9256       die();
9257    }
9258    redirectedJNIFunctions-&gt;NewGlobalRef = MyNewGlobalRef;
9259       err = (*jvmti_env)-&gt;SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
9260    if (err != JVMTI_ERROR_NONE) {
9261       die();
9262    }
9263 }
9264       </example>
9265       Sometime after <code>myInit</code> is called the user's JNI
9266       code is executed which makes the call to create a new global
9267       reference.  Instead of going to the normal JNI implementation
9268       the call goes to <code>myNewGlobalRef</code>.  Note that a
9269       copy of the original function table is kept so that the normal
9270       JNI function can be called after the data is collected.
9271       Note also that any JNI functions which are not overwritten
9272       will behave normally.
9273       <todo>
9274         check that the example compiles and executes.
9275       </todo>
9276     </intro>
9277 
9278     <function id="SetJNIFunctionTable" phase="start" num="120">
9279       <synopsis>Set JNI Function Table</synopsis>
9280       <description>
9281         Set the JNI function table
9282         in all current and future JNI environments.
9283         As a result, all future JNI calls are directed to the specified functions.
9284         Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
9285         function table to pass to this function.
9286         For this function to take effect the the updated table entries must be
9287         used by the JNI clients.
9288         Since the table is defined <code>const</code> some compilers may optimize
9289         away the access to the table, thus preventing this function from taking
9290         effect.
9291         The table is copied--changes to the local copy of the
9292         table have no effect.
9293         This function affects only the function table, all other aspects of the environment are
9294         unaffected.
9295         See the examples <internallink id="jniIntercept">above</internallink>.
9296       </description>
9297       <origin>new</origin>
9298       <capabilities>
9299       </capabilities>
9300       <parameters>
9301         <param id="function_table">
9302           <inptr>
9303             <struct>jniNativeInterface</struct>
9304           </inptr>
9305           <description>
9306             Points to the new JNI function table.
9307           </description>
9308         </param>
9309       </parameters>
9310       <errors>
9311       </errors>
9312     </function>
9313 
9314     <function id="GetJNIFunctionTable" phase="start" num="121">
9315       <synopsis>Get JNI Function Table</synopsis>
9316       <description>
9317         Get the JNI function table.
9318         The JNI function table is copied into allocated memory.
9319         If <functionlink id="SetJNIFunctionTable"></functionlink>
9320         has been called, the modified (not the original) function
9321         table is returned.
9322         Only the function table is copied, no other aspects of the environment
9323         are copied.
9324         See the examples <internallink id="jniIntercept">above</internallink>.
9325       </description>
9326       <origin>new</origin>
9327       <capabilities>
9328       </capabilities>
9329       <parameters>
9330         <param id="function_table">
9331           <allocbuf>
9332             <struct>jniNativeInterface</struct>
9333           </allocbuf>
9334           <description>
9335             On return, <code>*function_table</code>
9336             points a newly allocated copy of the JNI function table.
9337           </description>
9338         </param>
9339       </parameters>
9340       <errors>
9341       </errors>
9342     </function>
9343 
9344   </category>
9345 
9346   <category id="eventManagement" label="Event Management">
9347 
9348     <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
9349       <synopsis>Set Event Callbacks</synopsis>
9350       <description>
9351         Set the functions to be called for each event.
9352         The callbacks are specified by supplying a replacement function table.
9353         The function table is copied--changes to the local copy of the
9354         table have no effect.
9355         This is an atomic action, all callbacks are set at once.
9356         No events are sent before this function is called.
9357         When an entry is <code>NULL</code> or when the event is beyond
9358         <paramlink id="size_of_callbacks"></paramlink> no event is sent.
9359         Details on events are
9360         described <internallink id="EventSection">later</internallink> in this document.
9361         An event must be enabled and have a callback in order to be
9362         sent--the order in which this function and
9363         <functionlink id="SetEventNotificationMode"></functionlink>
9364         are called does not affect the result.
9365       </description>
9366       <origin>new</origin>
9367       <capabilities>
9368       </capabilities>
9369       <parameters>
9370         <param id="callbacks">
9371           <inptr>
9372             <struct>jvmtiEventCallbacks</struct>
9373             <nullok>remove the existing callbacks</nullok>
9374           </inptr>
9375           <description>
9376             The new event callbacks.
9377           </description>
9378         </param>
9379         <param id="size_of_callbacks">
9380           <jint min="0"/>
9381           <description>
9382             <code>sizeof(jvmtiEventCallbacks)</code>--for version
9383             compatibility.
9384           </description>
9385         </param>
9386       </parameters>
9387       <errors>
9388       </errors>
9389     </function>
9390 
9391     <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
9392       <synopsis>Set Event Notification Mode</synopsis>
9393       <description>
9394         Control the generation of events.
9395         <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
9396           <constant id="JVMTI_ENABLE" num="1">
9397             If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>,
9398             the event <paramlink id="event_type"></paramlink> will be enabled
9399           </constant>
9400           <constant id="JVMTI_DISABLE" num="0">
9401             If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>,
9402             the event <paramlink id="event_type"></paramlink> will be disabled
9403           </constant>
9404         </constants>
9405         If <code>thread</code> is <code>NULL</code>,
9406         the event is enabled or disabled globally; otherwise, it is
9407         enabled or disabled for a particular thread.
9408         An event is generated for
9409         a particular thread if it is enabled either at the thread or global
9410         levels.
9411         <p/>
9412         See <internallink id="EventIndex">below</internallink> for information on specific events.
9413         <p/>
9414         The following events cannot be controlled at the thread
9415         level through this function.
9416         <ul>
9417           <li><eventlink id="VMInit"></eventlink></li>
9418           <li><eventlink id="VMStart"></eventlink></li>
9419           <li><eventlink id="VMDeath"></eventlink></li>
9420           <li><eventlink id="ThreadStart"></eventlink></li>
9421           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9422           <li><eventlink id="CompiledMethodUnload"></eventlink></li>
9423           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9424           <li><eventlink id="DataDumpRequest"></eventlink></li>
9425         </ul>
9426         <p/>
9427         Initially, no events are enabled at either the thread level
9428         or the global level.
9429         <p/>
9430         Any needed capabilities (see Event Enabling Capabilities below) must be possessed
9431         before calling this function.
9432         <p/>
9433         Details on events are
9434         described <internallink id="EventSection">below</internallink>.
9435       </description>
9436       <origin>jvmdiClone</origin>
9437       <eventcapabilities></eventcapabilities>
9438       <parameters>
9439         <param id="mode">
9440           <enum>jvmtiEventMode</enum>
9441           <description>
9442             <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
9443           </description>
9444         </param>
9445         <param id="event_type">
9446           <enum>jvmtiEvent</enum>
9447           <description>
9448             the event to control
9449           </description>
9450         </param>
9451         <param id="event_thread">
9452           <ptrtype>
9453             <jthread impl="noconvert"/>
9454             <nullok>event is controlled at the global level</nullok>
9455           </ptrtype>
9456             <description>
9457               The thread to control
9458             </description>
9459         </param>
9460         <param id="...">
9461           <varargs/>
9462             <description>
9463               for future expansion
9464             </description>
9465         </param>
9466       </parameters>
9467       <errors>
9468         <error id="JVMTI_ERROR_INVALID_THREAD">
9469           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
9470         </error>
9471         <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
9472           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead).
9473         </error>
9474         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9475           thread level control was attempted on events which do not
9476           permit thread level control.
9477         </error>
9478         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
9479           The Required Event Enabling Capability is not possessed.
9480         </error>
9481       </errors>
9482     </function>
9483 
9484     <function id="GenerateEvents" num="123">
9485       <synopsis>Generate Events</synopsis>
9486       <description>
9487         Generate events to represent the current state of the VM.
9488         For example, if <paramlink id="event_type"/> is
9489         <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
9490         a <eventlink id="CompiledMethodLoad"></eventlink> event will be
9491         sent for each currently compiled method.
9492         Methods that were loaded and now have been unloaded are not sent.
9493         The history of what events have previously been sent does not
9494         effect what events are sent by this function--for example,
9495         all currently compiled methods
9496         will be sent each time this function is called.
9497         <p/>
9498         This function is useful when
9499         events may have been missed due to the agent attaching after program
9500         execution begins; this function generates the missed events.
9501         <p/>
9502         Attempts to execute Java programming language code or
9503         JNI functions may be paused until this function returns -
9504         so neither should be called from the thread sending the event.
9505         This function returns only after the missed events have been
9506         sent, processed and have returned.
9507         The event may be sent on a different thread than the thread
9508         on which the event occurred.
9509         The callback for the event must be set with
9510         <functionlink id="SetEventCallbacks"></functionlink>
9511         and the event must be enabled with
9512         <functionlink id="SetEventNotificationMode"></functionlink>
9513         or the events will not occur.
9514         If the VM no longer has the information to generate some or
9515         all of the requested events, the events are simply not sent -
9516         no error is returned.
9517         <p/>
9518         Only the following events are supported:
9519         <ul>
9520           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9521           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9522         </ul>
9523       </description>
9524       <origin>new</origin>
9525       <capabilities>
9526         <capability id="can_generate_compiled_method_load_events"></capability>
9527       </capabilities>
9528       <parameters>
9529         <param id="event_type">
9530           <enum>jvmtiEvent</enum>
9531           <description>
9532             The type of event to generate.  Must be one of these:
9533             <ul>
9534               <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
9535               <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
9536             </ul>
9537           </description>
9538         </param>
9539       </parameters>
9540       <errors>
9541         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
9542           <paramlink id="event_type"/> is
9543           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9544           and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
9545           is <code>false</code>.
9546         </error>
9547         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9548           <paramlink id="event_type"/> is other than
9549           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9550           or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
9551         </error>
9552       </errors>
9553     </function>
9554 
9555   </category>
9556 
9557     <category id="extension" label="Extension Mechanism">
9558 
9559       <intro>
9560         These functions
9561         allow a <jvmti/> implementation to provide functions and events
9562         beyond those defined in this specification.
9563         <p/>
9564         Both extension functions and extension events have parameters
9565         each of which has a 'type' and 'kind' chosen from the following tables:
9566 
9567         <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
9568           <constant id="JVMTI_TYPE_JBYTE" num="101">
9569             Java programming language primitive type - <code>byte</code>.
9570             JNI type <code>jbyte</code>.
9571           </constant>
9572           <constant id="JVMTI_TYPE_JCHAR" num="102">
9573             Java programming language primitive type - <code>char</code>.
9574             JNI type <code>jchar</code>.
9575           </constant>
9576           <constant id="JVMTI_TYPE_JSHORT" num="103">
9577             Java programming language primitive type - <code>short</code>.
9578             JNI type <code>jshort</code>.
9579           </constant>
9580           <constant id="JVMTI_TYPE_JINT" num="104">
9581             Java programming language primitive type - <code>int</code>.
9582             JNI type <datalink id="jint"></datalink>.
9583           </constant>
9584           <constant id="JVMTI_TYPE_JLONG" num="105">
9585             Java programming language primitive type - <code>long</code>.
9586             JNI type <datalink id="jlong"></datalink>.
9587           </constant>
9588           <constant id="JVMTI_TYPE_JFLOAT" num="106">
9589             Java programming language primitive type - <code>float</code>.
9590             JNI type <datalink id="jfloat"></datalink>.
9591           </constant>
9592           <constant id="JVMTI_TYPE_JDOUBLE" num="107">
9593             Java programming language primitive type - <code>double</code>.
9594             JNI type <datalink id="jdouble"></datalink>.
9595           </constant>
9596           <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
9597             Java programming language primitive type - <code>boolean</code>.
9598             JNI type <datalink id="jboolean"></datalink>.
9599           </constant>
9600           <constant id="JVMTI_TYPE_JOBJECT" num="109">
9601             Java programming language object type - <code>java.lang.Object</code>.
9602             JNI type <datalink id="jobject"></datalink>.
9603             Returned values are JNI local references and must be managed.
9604           </constant>
9605           <constant id="JVMTI_TYPE_JTHREAD" num="110">
9606             Java programming language object type - <code>java.lang.Thread</code>.
9607             <jvmti/> type <datalink id="jthread"></datalink>.
9608             Returned values are JNI local references and must be managed.
9609           </constant>
9610           <constant id="JVMTI_TYPE_JCLASS" num="111">
9611             Java programming language object type - <code>java.lang.Class</code>.
9612             JNI type <datalink id="jclass"></datalink>.
9613             Returned values are JNI local references and must be managed.
9614           </constant>
9615           <constant id="JVMTI_TYPE_JVALUE" num="112">
9616             Union of all Java programming language primitive and object types -
9617             JNI type <datalink id="jvalue"></datalink>.
9618             Returned values which represent object types are JNI local references and must be managed.
9619           </constant>
9620           <constant id="JVMTI_TYPE_JFIELDID" num="113">
9621             Java programming language field identifier -
9622             JNI type <datalink id="jfieldID"></datalink>.
9623           </constant>
9624           <constant id="JVMTI_TYPE_JMETHODID" num="114">
9625             Java programming language method identifier -
9626             JNI type <datalink id="jmethodID"></datalink>.
9627           </constant>
9628           <constant id="JVMTI_TYPE_CCHAR" num="115">
9629             C programming language type - <code>char</code>.
9630           </constant>
9631           <constant id="JVMTI_TYPE_CVOID" num="116">
9632             C programming language type - <code>void</code>.
9633           </constant>
9634           <constant id="JVMTI_TYPE_JNIENV" num="117">
9635             JNI environment - <code>JNIEnv</code>.
9636             Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
9637           </constant>
9638         </constants>
9639 
9640         <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
9641           <constant id="JVMTI_KIND_IN" num="91">
9642             Ingoing argument - <code>foo</code>.
9643           </constant>
9644           <constant id="JVMTI_KIND_IN_PTR" num="92">
9645             Ingoing pointer argument - <code>const foo*</code>.
9646           </constant>
9647           <constant id="JVMTI_KIND_IN_BUF" num="93">
9648             Ingoing array argument - <code>const foo*</code>.
9649           </constant>
9650           <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
9651             Outgoing allocated array argument -  <code>foo**</code>.
9652             Free with <code>Deallocate</code>.
9653           </constant>
9654           <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
9655             Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
9656             Free with <code>Deallocate</code>.
9657           </constant>
9658           <constant id="JVMTI_KIND_OUT" num="96">
9659             Outgoing argument - <code>foo*</code>.
9660           </constant>
9661           <constant id="JVMTI_KIND_OUT_BUF" num="97">
9662             Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
9663             Do not <code>Deallocate</code>.
9664           </constant>
9665         </constants>
9666 
9667       </intro>
9668 
9669       <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
9670         <field id="name">
9671           <allocfieldbuf><char/></allocfieldbuf>
9672             <description>
9673               The parameter name, encoded as a
9674               <internallink id="mUTF">modified UTF-8</internallink> string
9675             </description>
9676         </field>
9677         <field id="kind">
9678           <enum>jvmtiParamKind</enum>
9679           <description>
9680             The kind of the parameter - type modifiers
9681           </description>
9682         </field>
9683         <field id="base_type">
9684           <enum>jvmtiParamTypes</enum>
9685           <description>
9686             The base type of the parameter -  modified by <code>kind</code>
9687           </description>
9688         </field>
9689         <field id="null_ok">
9690           <jboolean/>
9691             <description>
9692               Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
9693             </description>
9694         </field>
9695       </typedef>
9696 
9697       <callback id="jvmtiExtensionFunction">
9698         <enum>jvmtiError</enum>
9699           <synopsis>Extension Function</synopsis>
9700         <description>
9701           This is the implementation-specific extension function.
9702         </description>
9703         <parameters>
9704           <param id="jvmti_env">
9705             <outptr>
9706               <struct>jvmtiEnv</struct>
9707             </outptr>
9708             <description>
9709               The <jvmti/> environment is the only fixed parameter for extension functions.
9710             </description>
9711           </param>
9712           <param id="...">
9713             <varargs/>
9714               <description>
9715                 The extension function-specific parameters
9716               </description>
9717           </param>
9718         </parameters>
9719       </callback>
9720 
9721       <function id="GetExtensionFunctions" phase="onload" num="124">
9722         <synopsis>Get Extension Functions</synopsis>
9723 
9724         <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
9725           <field id="func">
9726             <ptrtype>
9727               <struct>jvmtiExtensionFunction</struct>
9728             </ptrtype>
9729             <description>
9730               The actual function to call
9731             </description>
9732           </field>
9733           <field id="id">
9734             <allocfieldbuf><char/></allocfieldbuf>
9735               <description>
9736                 The identifier for the extension function, encoded as a
9737                 <internallink id="mUTF">modified UTF-8</internallink> string.
9738                 Uses package name conventions.
9739                 For example, <code>com.sun.hotspot.bar</code>
9740               </description>
9741           </field>
9742           <field id="short_description">
9743             <allocfieldbuf><char/></allocfieldbuf>
9744               <description>
9745                 A one sentence description of the function, encoded as a
9746                 <internallink id="mUTF">modified UTF-8</internallink> string.
9747               </description>
9748           </field>
9749           <field id="param_count">
9750             <jint/>
9751               <description>
9752                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9753               </description>
9754           </field>
9755           <field id="params">
9756             <allocfieldbuf outcount="param_count">
9757               <struct>jvmtiParamInfo</struct>
9758             </allocfieldbuf>
9759             <description>
9760               Array of
9761               <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9762               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9763             </description>
9764           </field>
9765           <field id="error_count">
9766             <jint/>
9767               <description>
9768                 The number of possible error returns (excluding universal errors)
9769               </description>
9770           </field>
9771           <field id="errors">
9772             <allocfieldbuf outcount="error_count">
9773               <enum>jvmtiError</enum>
9774             </allocfieldbuf>
9775             <description>
9776               Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9777               possible errors
9778             </description>
9779           </field>
9780         </typedef>
9781 
9782         <description>
9783           Returns the set of extension functions.
9784         </description>
9785         <origin>new</origin>
9786         <capabilities>
9787         </capabilities>
9788         <parameters>
9789           <param id="extension_count_ptr">
9790             <outptr><jint/></outptr>
9791               <description>
9792                 On return, points to the number of extension functions
9793               </description>
9794           </param>
9795           <param id="extensions">
9796             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
9797             <description>
9798               Returns an array of extension function info, one per function
9799             </description>
9800           </param>
9801         </parameters>
9802         <errors>
9803         </errors>
9804       </function>
9805 
9806       <function id="GetExtensionEvents" phase="onload" num="125">
9807         <synopsis>Get Extension Events</synopsis>
9808 
9809         <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
9810           <field id="extension_event_index">
9811             <jint/>
9812             <description>
9813               The identifying index of the event
9814             </description>
9815           </field>
9816           <field id="id">
9817             <allocfieldbuf><char/></allocfieldbuf>
9818               <description>
9819                 The identifier for the extension event, encoded as a
9820                 <internallink id="mUTF">modified UTF-8</internallink> string.
9821                 Uses package name conventions.
9822                 For example, <code>com.sun.hotspot.bar</code>
9823               </description>
9824           </field>
9825           <field id="short_description">
9826             <allocfieldbuf><char/></allocfieldbuf>
9827               <description>
9828                 A one sentence description of the event, encoded as a
9829                 <internallink id="mUTF">modified UTF-8</internallink> string.
9830               </description>
9831           </field>
9832           <field id="param_count">
9833             <jint/>
9834               <description>
9835                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9836               </description>
9837           </field>
9838           <field id="params">
9839             <allocfieldbuf outcount="param_count">
9840               <struct>jvmtiParamInfo</struct>
9841             </allocfieldbuf>
9842             <description>
9843               Array of
9844               <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
9845               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9846             </description>
9847           </field>
9848         </typedef>
9849 
9850         <description>
9851           Returns the set of extension events.
9852         </description>
9853         <origin>new</origin>
9854         <capabilities>
9855         </capabilities>
9856         <parameters>
9857           <param id="extension_count_ptr">
9858             <outptr><jint/></outptr>
9859               <description>
9860                 On return, points to the number of extension events
9861               </description>
9862           </param>
9863           <param id="extensions">
9864             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
9865             <description>
9866               Returns an array of extension event info, one per event
9867             </description>
9868           </param>
9869         </parameters>
9870         <errors>
9871         </errors>
9872       </function>
9873 
9874       <callback id="jvmtiExtensionEvent">
9875         <void/>
9876           <synopsis>Extension Event</synopsis>
9877         <description>
9878           This is the implementation-specific event.
9879           The event handler is set with
9880           <functionlink id="SetExtensionEventCallback"/>.
9881           <p/>
9882           Event handlers for extension events must be declared varargs to match this definition.
9883           Failure to do so could result in calling convention mismatch and undefined behavior
9884           on some platforms.
9885           <p/>
9886           For example, if the <code>jvmtiParamInfo</code>
9887           returned by <functionlink id="GetExtensionEvents"/> indicates that
9888           there is a <code>jint</code> parameter, the event handler should be
9889           declared:
9890 <example>
9891     void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...)
9892 </example>
9893           Note the terminal "<code>...</code>" which indicates varargs.
9894         </description>
9895         <parameters>
9896           <param id="jvmti_env">
9897             <outptr>
9898               <struct>jvmtiEnv</struct>
9899             </outptr>
9900             <description>
9901               The <jvmti/> environment is the only fixed parameter for extension events.
9902             </description>
9903           </param>
9904           <param id="...">
9905             <varargs/>
9906               <description>
9907                 The extension event-specific parameters
9908               </description>
9909           </param>
9910         </parameters>
9911       </callback>
9912 
9913       <function id="SetExtensionEventCallback" phase="onload" num="126">
9914         <synopsis>Set Extension Event Callback</synopsis>
9915 
9916         <description>
9917           Sets the callback function for an extension event and
9918           enables the event. Or, if the callback is <code>NULL</code>, disables
9919           the event.  Note that unlike standard events, setting
9920           the callback and enabling the event are a single operation.
9921         </description>
9922         <origin>new</origin>
9923         <capabilities>
9924         </capabilities>
9925         <parameters>
9926           <param id="extension_event_index">
9927             <jint/>
9928               <description>
9929                 Identifies which callback to set.
9930                 This index is the
9931                 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
9932                 field of
9933                 <datalink id="jvmtiExtensionEventInfo"/>.
9934               </description>
9935           </param>
9936           <param id="callback">
9937             <ptrtype>
9938               <struct>jvmtiExtensionEvent</struct>
9939               <nullok>disable the event</nullok>
9940             </ptrtype>
9941             <description>
9942               If <code>callback</code> is non-<code>NULL</code>,
9943               set <code>callback</code> to be the event callback function
9944               and enable the event.
9945             </description>
9946           </param>
9947         </parameters>
9948         <errors>
9949         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9950             <paramlink id="extension_event_index"/> is not an
9951             <fieldlink id="extension_event_index"
9952                        struct="jvmtiExtensionEventInfo"/>
9953             returned by
9954             <functionlink id="GetExtensionEvents"/>
9955         </error>
9956         </errors>
9957       </function>
9958 
9959     </category>
9960 
9961   <category id="capability" label="Capability">
9962 
9963     <intro>
9964       The capabilities functions allow you to change the
9965       functionality available to <jvmti/>--that is,
9966       which <jvmti/>
9967       functions can be called, what events can be generated,
9968       and what functionality these events and functions can
9969       provide.
9970       <p/>
9971         The "Capabilities" section of each function and event describe which
9972         capabilities, if any, they are associated with. "Required Functionality"
9973         means it is available for use and no capabilities must be added to use it.
9974         "Optional Functionality" means the agent must possess the capability
9975         before it can be used.
9976         To possess a capability, the agent must
9977         <functionlink id="AddCapabilities">add the capability</functionlink>.
9978         "Optional Features" describe capabilities which,
9979         if added, extend the feature set.
9980         <p/>
9981         The potentially available capabilities of each <jvmti/> implementation are different.
9982         Depending on the implementation, a capability:
9983         <ul>
9984           <li>may never be added</li>
9985           <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
9986           <li>may be added only during the <code>OnLoad</code> phase</li>
9987           <li>may be possessed by only one environment at a time</li>
9988           <li>may be possessed by only one environment at a time,
9989               and only during the <code>OnLoad</code> phase</li>
9990           <li>and so on ...</li>
9991         </ul>
9992       Frequently, the addition of a capability may incur a cost in execution speed, start up
9993       time, and/or memory footprint.  Note that the overhead of using a capability
9994       is completely different than the overhead of possessing a capability.
9995       Take single stepping as an example. When single stepping is on (that
9996       is, when the event is enabled and thus actively sending events)
9997       the overhead of sending and processing an event
9998       on each instruction is huge in any implementation.
9999       However, the overhead of possessing the capability may be small or large,
10000       depending on the implementation.  Also, when and if a capability is potentially
10001       available depends on the implementation.  Some examples:
10002       <ul>
10003         <li>One VM might perform all execution by compiling bytecodes into
10004           native code and be unable to generate single step instructions.
10005           In this implementation the capability can not be added.</li>
10006         <li>Another VM may be able to switch execution to a single stepping
10007           interpreter at any time.  In this implementation, having the capability has no
10008           overhead and could be added at any time.</li>
10009         <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
10010           execution engine at start up, but be unable to switch between them.
10011           In this implementation the capability would need to be added
10012           during the <code>OnLoad</code> phase (before bytecode
10013           execution begins) and would have a large impact on execution speed
10014           even if single stepping was never used.</li>
10015         <li>Still another VM might be able to add an "is single stepping on" check
10016           into compiled bytecodes or a generated interpreter.  Again in this implementation
10017           the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
10018           and branch on each instruction) would be considerably less.</li>
10019       </ul>
10020       <p/>
10021       Each <jvmti/> <internallink id="environments">environment</internallink>
10022       has its own set of capabilities.
10023       Initially, that set is empty.
10024       Any desired capability must be added.
10025       If possible, capabilities should be added during the <code>OnLoad</code> phase.  For most
10026       virtual machines certain capabilities require special set up for
10027       the virtual machine and this set up must happen
10028       during the <code>OnLoad</code> phase, before the virtual machine begins execution.
10029       Once a capability is added, it can
10030       only be removed if explicitly relinquished by the environment.
10031       <p/>
10032       The agent can,
10033       <functionlink id="GetPotentialCapabilities">determine what
10034         capabilities this VM can potentially provide</functionlink>,
10035       <functionlink id="AddCapabilities">add the capabilities
10036         to be used</functionlink>,
10037       <functionlink id="RelinquishCapabilities">release capabilities
10038         which are no longer needed</functionlink>, and
10039       <functionlink id="GetCapabilities">examine the currently available
10040         capabilities</functionlink>.
10041     </intro>
10042 
10043     <intro id="capabilityExamples" label="Capability Examples">
10044       For example, a freshly started agent (in the <code>OnLoad</code> function)
10045       wants to enable all possible capabilities.
10046       Note that, in general, this is not advisable as the agent may suffer
10047       a performance penalty for functionality it is not using.
10048       The code might look like this in C:
10049       <example>
10050         jvmtiCapabilities capa;
10051         jvmtiError err;
10052 
10053         err = (*jvmti)-&gt;GetPotentialCapabilities(jvmti, &amp;capa);
10054         if (err == JVMTI_ERROR_NONE) {
10055            err = (*jvmti)-&gt;AddCapabilities(jvmti, &amp;capa);
10056       </example>
10057       For example, if an  agent wants to check if it can get
10058       the bytecodes of a method (that is, it wants to check
10059       if it previously added this capability and has not
10060       relinquished it), the code might
10061       look like this in C:
10062       <example>
10063         jvmtiCapabilities capa;
10064         jvmtiError err;
10065 
10066         err = (*jvmti)-&gt;GetCapabilities(jvmti, &amp;capa);
10067         if (err == JVMTI_ERROR_NONE) {
10068            if (capa.can_get_bytecodes) { ... } }
10069       </example>
10070     </intro>
10071 
10072     <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
10073       <description>
10074         The functions in this category use this capabilities structure
10075         which contains boolean flags corresponding to each capability:
10076       </description>
10077       <capabilityfield id="can_tag_objects">
10078         <description>
10079           Can set and get tags, as described in the
10080           <internallink id="Heap">Heap category</internallink>.
10081         </description>
10082       </capabilityfield>
10083       <capabilityfield id="can_generate_field_modification_events">
10084         <description>
10085           Can set watchpoints on field modification -
10086           <functionlink id="SetFieldModificationWatch"></functionlink>
10087         </description>
10088       </capabilityfield>
10089       <capabilityfield id="can_generate_field_access_events">
10090         <description>
10091           Can set watchpoints on field access -
10092           <functionlink id="SetFieldAccessWatch"></functionlink>
10093         </description>
10094       </capabilityfield>
10095       <capabilityfield id="can_get_bytecodes">
10096         <description>
10097           Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
10098         </description>
10099       </capabilityfield>
10100       <capabilityfield id="can_get_synthetic_attribute">
10101         <description>
10102           Can test if a field or method is synthetic -
10103           <functionlink id="IsFieldSynthetic"></functionlink> and
10104           <functionlink id="IsMethodSynthetic"></functionlink>
10105         </description>
10106       </capabilityfield>
10107       <capabilityfield id="can_get_owned_monitor_info">
10108         <description>
10109           Can get information about ownership of monitors -
10110           <functionlink id="GetOwnedMonitorInfo"></functionlink>
10111         </description>
10112       </capabilityfield>
10113       <capabilityfield id="can_get_current_contended_monitor">
10114         <description>
10115           Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
10116         </description>
10117       </capabilityfield>
10118       <capabilityfield id="can_get_monitor_info">
10119       <description>
10120         Can <functionlink id="GetObjectMonitorUsage"></functionlink>
10121       </description>
10122       </capabilityfield>
10123       <capabilityfield id="can_pop_frame">
10124         <description>
10125           Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
10126         </description>
10127       </capabilityfield>
10128       <capabilityfield id="can_redefine_classes">
10129         <description>
10130           Can redefine classes with <functionlink id="RedefineClasses"/>.
10131         </description>
10132       </capabilityfield>
10133       <capabilityfield id="can_signal_thread">
10134         <description>
10135           Can send stop or interrupt to threads
10136         </description>
10137       </capabilityfield>
10138       <capabilityfield id="can_get_source_file_name">
10139         <description>
10140           Can get the source file name of a class
10141         </description>
10142       </capabilityfield>
10143       <capabilityfield id="can_get_line_numbers">
10144         <description>
10145           Can get the line number table of a method
10146         </description>
10147       </capabilityfield>
10148       <capabilityfield id="can_get_source_debug_extension">
10149         <description>
10150           Can get the source debug extension of a class
10151         </description>
10152       </capabilityfield>
10153       <capabilityfield id="can_access_local_variables">
10154         <description>
10155           Can set and get local variables
10156         </description>
10157       </capabilityfield>
10158       <capabilityfield id="can_maintain_original_method_order">
10159         <description>
10160           Can return methods in the order they occur in the class file
10161         </description>
10162       </capabilityfield>
10163       <capabilityfield id="can_generate_single_step_events">
10164         <description>
10165           Can get <eventlink id="SingleStep">single step</eventlink> events
10166         </description>
10167       </capabilityfield>
10168       <capabilityfield id="can_generate_exception_events">
10169         <description>
10170           Can get <eventlink id="Exception">exception thrown</eventlink> and
10171             <eventlink id="ExceptionCatch">exception catch</eventlink> events
10172         </description>
10173       </capabilityfield>
10174       <capabilityfield id="can_generate_frame_pop_events">
10175         <description>
10176           Can <functionlink id="NotifyFramePop">set</functionlink> and thus get
10177             <eventlink id="FramePop"></eventlink> events
10178         </description>
10179       </capabilityfield>
10180       <capabilityfield id="can_generate_breakpoint_events">
10181         <description>
10182           Can <functionlink id="SetBreakpoint">set</functionlink> and thus get
10183             <eventlink id="Breakpoint"></eventlink> events
10184         </description>
10185       </capabilityfield>
10186       <capabilityfield id="can_suspend">
10187         <description>
10188           Can suspend and resume threads
10189         </description>
10190       </capabilityfield>
10191       <capabilityfield id="can_redefine_any_class">
10192         <description>
10193           Can modify (retransform or redefine) any modifiable class.
10194           See <functionlink id="IsModifiableClass"/>.
10195         </description>
10196       </capabilityfield>
10197       <capabilityfield id="can_get_current_thread_cpu_time">
10198         <description>
10199           Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
10200           current thread CPU time
10201         </description>
10202       </capabilityfield>
10203       <capabilityfield id="can_get_thread_cpu_time">
10204         <description>
10205           Can <functionlink id="GetThreadCpuTime">get</functionlink>
10206           thread CPU time
10207         </description>
10208       </capabilityfield>
10209       <capabilityfield id="can_generate_method_entry_events"
10210                        disp1="can_generate" disp2="_method_entry_events"
10211                        >
10212         <description>
10213           Can generate method entry events on entering a method
10214         </description>
10215       </capabilityfield>
10216       <capabilityfield id="can_generate_method_exit_events"
10217                        disp1="can_generate" disp2="_method_exit_events"
10218                        >
10219         <description>
10220           Can generate method exit events on leaving a method
10221         </description>
10222       </capabilityfield>
10223       <capabilityfield id="can_generate_all_class_hook_events"
10224                        disp1="can_generate" disp2="_all_class_hook_events"
10225                        >
10226         <description>
10227           Can generate ClassFileLoadHook events for every loaded class.
10228         </description>
10229       </capabilityfield>
10230       <capabilityfield id="can_generate_compiled_method_load_events"
10231                        disp1="can_generate" disp2="_compiled_method_load_events"
10232                        >
10233         <description>
10234           Can generate events when a method is compiled or unloaded
10235         </description>
10236       </capabilityfield>
10237       <capabilityfield id="can_generate_monitor_events"
10238                        disp1="can_generate" disp2="_monitor_events"
10239                        >
10240         <description>
10241           Can generate events on monitor activity
10242         </description>
10243       </capabilityfield>
10244       <capabilityfield id="can_generate_vm_object_alloc_events"
10245                        disp1="can_generate" disp2="_vm_object_alloc_events"
10246                        >
10247         <description>
10248           Can generate events on VM allocation of an object
10249         </description>
10250       </capabilityfield>
10251       <capabilityfield id="can_generate_native_method_bind_events"
10252                        disp1="can_generate" disp2="_native_method_bind_events"
10253                        >
10254         <description>
10255           Can generate events when a native method is bound to its
10256           implementation
10257         </description>
10258       </capabilityfield>
10259       <capabilityfield id="can_generate_garbage_collection_events"
10260                        disp1="can_generate" disp2="_garbage_collection_events"
10261                        >
10262         <description>
10263           Can generate events when garbage collection begins or ends
10264         </description>
10265       </capabilityfield>
10266       <capabilityfield id="can_generate_object_free_events"
10267                        disp1="can_generate" disp2="_object_free_events"
10268                        >
10269         <description>
10270           Can generate events when the garbage collector frees an object
10271         </description>
10272       </capabilityfield>
10273       <capabilityfield id="can_force_early_return" since="1.1">
10274         <description>
10275           Can return early from a method, as described in the
10276           <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
10277         </description>
10278       </capabilityfield>
10279       <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
10280         <description>
10281           Can get information about owned monitors with stack depth -
10282           <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
10283         </description>
10284       </capabilityfield>
10285       <capabilityfield id="can_get_constant_pool" since="1.1">
10286         <description>
10287           Can get the constant pool of a class -
10288           <functionlink id="GetConstantPool"></functionlink>
10289         </description>
10290       </capabilityfield>
10291       <capabilityfield id="can_set_native_method_prefix" since="1.1">
10292         <description>
10293           Can set prefix to be applied when native method cannot be resolved -
10294           <functionlink id="SetNativeMethodPrefix"/> and
10295           <functionlink id="SetNativeMethodPrefixes"/>
10296         </description>
10297       </capabilityfield>
10298       <capabilityfield id="can_retransform_classes" since="1.1">
10299         <description>
10300           Can retransform classes with <functionlink id="RetransformClasses"/>.
10301           In addition to the restrictions imposed by the specific
10302           implementation on this capability (see the
10303           <internallink id="capability">Capability</internallink> section),
10304           this capability must be set before the
10305           <eventlink id="ClassFileLoadHook"/> event is enabled for the
10306           first time in this environment.
10307           An environment that possesses this capability at the time that
10308           <code>ClassFileLoadHook</code> is enabled for the first time is
10309           said to be <i>retransformation capable</i>.
10310           An environment that does not possess this capability at the time that
10311           <code>ClassFileLoadHook</code> is enabled for the first time is
10312           said to be <i>retransformation incapable</i>.
10313         </description>
10314       </capabilityfield>
10315       <capabilityfield id="can_retransform_any_class" since="1.1">
10316         <description>
10317           <functionlink id="RetransformClasses"/> can be called on any modifiable class.
10318           See <functionlink id="IsModifiableClass"/>.
10319           (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
10320           must also be set)
10321         </description>
10322       </capabilityfield>
10323       <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
10324         <description>
10325           Can generate events when the VM is unable to allocate memory from
10326           the <tm>Java</tm> platform heap.
10327           See <eventlink id="ResourceExhausted"/>.
10328         </description>
10329       </capabilityfield>
10330       <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
10331         <description>
10332           Can generate events when the VM is unable to create a thread.
10333           See <eventlink id="ResourceExhausted"/>.
10334         </description>
10335       </capabilityfield>
10336       <capabilityfield id="can_generate_early_vmstart" since="9">
10337         <description>
10338           Can generate the <code>VMStart</code> event early.
10339           See <eventlink id="VMStart"/>.
10340         </description>
10341       </capabilityfield>
10342       <capabilityfield id="can_generate_early_class_hook_events" since="9">
10343         <description>
10344           Can generate the <eventlink id="ClassFileLoadHook"/> events
10345           in the primordial phase. If this capability and
10346           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10347           <code>can_generate_all_class_hook_events</code></internallink>
10348           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10349           can be posted for classes loaded in the primordial phase.
10350           See <eventlink id="ClassFileLoadHook"/>.
10351         </description>
10352       </capabilityfield>
10353     </capabilitiestypedef>
10354 
10355     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10356       <synopsis>Get Potential Capabilities</synopsis>
10357       <description>
10358         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10359         features that can potentially be possessed by this environment
10360         at this time.
10361         The returned capabilities differ from the complete set of capabilities
10362         implemented by the VM in two cases: another environment possesses
10363         capabilities that can only be possessed by one environment, or the
10364         current <functionlink id="GetPhase">phase</functionlink> is live,
10365         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10366         The <functionlink id="AddCapabilities"></functionlink> function
10367         may be used to set any or all or these capabilities.
10368         Currently possessed capabilities are included.
10369         <p/>
10370         Typically this function is used in the <code>OnLoad</code> function.
10371         Some virtual machines may allow a limited set of capabilities to be
10372         added in the live phase.
10373         In this case, the set of potentially available capabilities
10374         will likely differ from the <code>OnLoad</code> phase set.
10375         <p/>
10376         See the
10377         <internallink id="capabilityExamples">Capability Examples</internallink>.
10378       </description>
10379       <origin>new</origin>
10380       <capabilities>
10381       </capabilities>
10382       <parameters>
10383         <param id="capabilities_ptr">
10384           <outptr><struct>jvmtiCapabilities</struct></outptr>
10385           <description>
10386             On return, points to the <jvmti/> capabilities that may be added.
10387           </description>
10388         </param>
10389       </parameters>
10390       <errors>
10391       </errors>
10392     </function>
10393 
10394     <elide>
10395     <function id="EstimateCostOfCapabilities" phase="onload" num="141">
10396       <synopsis>Estimate Cost Of Capabilities</synopsis>
10397       <description>
10398         <issue>There is strong opposition to this function.  The concern is
10399           that it would be difficult or impossible to provide meaningful
10400           numbers, as the amount of impact is conditional on many factors
10401           that a single number could not represent.  There is doubt that
10402           conditional implementations would be used or are even a good idea.
10403           The thought is that release documentation for the implementation
10404           would be the best means of exposing this information.
10405           Unless new arguments are presented, I intend to remove this
10406           function in the next revision.
10407         </issue>
10408         <p/>
10409         Return via the <paramlink id="time_impact_ptr"></paramlink> and
10410         <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
10411         of adding the capabilities pointed to by
10412         <paramlink id="capabilities_ptr"></paramlink>.
10413         The returned estimates are in percentage of additional overhead, thus
10414         a time impact of 100 mean the application might run
10415         at half the speed.
10416         The estimates are very rough approximations and are not guaranteed.
10417         Note also, that the estimates are of the impact of having the
10418         capability available--when and if it is used the impact may be
10419         much greater.
10420         Estimates can be for a single capability or for a set of
10421         capabilities.  Note that the costs are not necessarily additive,
10422         adding support for one capability might make another available
10423         for free or conversely having two capabilities at once may
10424         have multiplicative impact.
10425         Estimates are relative to the current set of capabilities -
10426         that is, how much more impact given the currently possessed capabilities.
10427         <p/>
10428         Typically this function is used in the OnLoad function,
10429         some virtual machines may allow a limited set of capabilities to be
10430         added in the live phase.
10431         In this case, the set of potentially available capabilities
10432         will likely differ from the OnLoad phase set.
10433         <p/>
10434         See the
10435         <internallink id="capabilityExamples">Capability Examples</internallink>.
10436       </description>
10437       <origin>new</origin>
10438       <capabilities>
10439       </capabilities>
10440       <parameters>
10441         <param id="capabilities_ptr">
10442           <inptr><struct>jvmtiCapabilities</struct></inptr>
10443           <description>
10444             points to the <jvmti/> capabilities to evaluate.
10445           </description>
10446         </param>
10447         <param id="time_impact_ptr">
10448           <outptr><jint/></outptr>
10449           <description>
10450             On return, points to the estimated percentage increase in
10451             run time if this capability was added.
10452           </description>
10453         </param>
10454         <param id="space_impact_ptr">
10455           <outptr><jint/></outptr>
10456           <description>
10457             On return, points to the estimated percentage increase in
10458             memory space used if this capability was added.
10459           </description>
10460         </param>
10461       </parameters>
10462       <errors>
10463         <error id="JVMTI_ERROR_NOT_AVAILABLE">
10464           The desired capabilities are not even potentially available.
10465         </error>
10466       </errors>
10467     </function>
10468     </elide>
10469 
10470     <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
10471       <synopsis>Add Capabilities</synopsis>
10472       <description>
10473         Set new capabilities by adding the capabilities
10474         whose values are set to one (<code>1</code>) in
10475         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10476         All previous capabilities are retained.
10477         Typically this function is used in the <code>OnLoad</code> function.
10478         Some virtual machines may allow a limited set of capabilities to be
10479         added in the live phase.
10480         <p/>
10481         See the
10482         <internallink id="capabilityExamples">Capability Examples</internallink>.
10483       </description>
10484       <origin>new</origin>
10485       <capabilities>
10486       </capabilities>
10487       <parameters>
10488         <param id="capabilities_ptr">
10489           <inptr><struct>jvmtiCapabilities</struct></inptr>
10490           <description>
10491             Points to the <jvmti/> capabilities to add.
10492           </description>
10493         </param>
10494       </parameters>
10495       <errors>
10496         <error id="JVMTI_ERROR_NOT_AVAILABLE">
10497           The desired capabilities are not even potentially available.
10498         </error>
10499       </errors>
10500     </function>
10501 
10502 
10503     <function id="RelinquishCapabilities" phase="onload" num="143">
10504       <synopsis>Relinquish Capabilities</synopsis>
10505       <description>
10506         Relinquish the capabilities
10507         whose values are set to one (<code>1</code>) in
10508         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10509         Some implementations may allow only one environment to have a capability
10510         (see the <internallink id="capability">capability introduction</internallink>).
10511         This function releases capabilities
10512         so that they may be used by other agents.
10513         All other capabilities are retained.
10514         The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
10515         Attempting to relinquish a capability that the agent does not possess is not an error.
10516           <issue>
10517             It is possible for the agent to be actively using capabilities
10518             which are being relinquished.  For example, a thread is currently
10519             suspended and can_suspend is being relinquished or an event is currently
10520             enabled and can_generate_whatever is being relinquished.
10521             There are three possible ways we could spec this:
10522             <ul>
10523               <li>relinquish automatically releases them</li>
10524               <li>relinquish checks and returns some error code if held</li>
10525               <li>it is the agent's responsibility and it is not checked</li>
10526             </ul>
10527             One of these should be chosen.
10528           </issue>
10529       </description>
10530       <origin>new</origin>
10531       <capabilities>
10532       </capabilities>
10533       <parameters>
10534         <param id="capabilities_ptr">
10535           <inptr><struct>jvmtiCapabilities</struct></inptr>
10536           <description>
10537             Points to the <jvmti/> capabilities to relinquish.
10538           </description>
10539         </param>
10540       </parameters>
10541       <errors>
10542       </errors>
10543     </function>
10544 
10545 
10546 
10547     <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
10548       <synopsis>Get Capabilities</synopsis>
10549         <description>
10550           Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/>
10551           features which this environment currently possesses.
10552           Each possessed capability is indicated by a one (<code>1</code>) in the
10553           corresponding field of the <internallink id="jvmtiCapabilities">capabilities
10554           structure</internallink>.
10555           An environment does not possess a capability unless it has been successfully added with
10556           <functionlink id="AddCapabilities"/>.
10557           An environment only loses possession of a capability if it has been relinquished with
10558           <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
10559           of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
10560           have been made.
10561           <p/>
10562           See the
10563           <internallink id="capabilityExamples">Capability Examples</internallink>.
10564         </description>
10565       <origin>jvmdiClone</origin>
10566       <capabilities>
10567       </capabilities>
10568       <parameters>
10569         <param id="capabilities_ptr">
10570           <outptr><struct>jvmtiCapabilities</struct></outptr>
10571           <description>
10572             On return, points to the <jvmti/> capabilities.
10573           </description>
10574         </param>
10575       </parameters>
10576       <errors>
10577       </errors>
10578     </function>
10579 
10580   </category>
10581 
10582 
10583   <category id="timers" label="Timers">
10584 
10585       <intro>
10586         These functions provide timing information.
10587         The resolution at which the time is updated is not specified.
10588         They provides nanosecond precision, but not necessarily nanosecond accuracy.
10589         Details about the timers, such as their maximum values, can be accessed with
10590         the timer information functions.
10591       </intro>
10592 
10593       <typedef id="jvmtiTimerInfo" label="Timer Info">
10594         <description>
10595           The information function for each timer returns this data structure.
10596         </description>
10597         <field id="max_value">
10598           <jlong/>
10599             <description>
10600               The maximum value the timer can reach.
10601               After this value is reached the timer wraps back to zero.
10602               This is an unsigned value.  If tested or printed as a jlong (signed value)
10603               it may appear to be a negative number.
10604             </description>
10605         </field>
10606         <field id="may_skip_forward">
10607           <jboolean/>
10608           <description>
10609             If true, the timer can be externally adjusted and as a result skip forward.
10610             If false, the timer value will never increase faster than real time.
10611           </description>
10612         </field>
10613         <field id="may_skip_backward">
10614           <jboolean/>
10615           <description>
10616             If true, the timer can be externally adjusted and as a result skip backward.
10617             If false, the timer value will be monotonically increasing.
10618           </description>
10619         </field>
10620         <field id="kind">
10621           <enum>jvmtiTimerKind</enum>
10622           <description>
10623             The kind of timer.
10624             On a platform that does not distinguish between user and system time, <datalink
10625                  id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
10626             is returned.
10627           </description>
10628         </field>
10629         <field id="reserved1">
10630           <jlong/>
10631             <description>
10632               Reserved for future use.
10633             </description>
10634         </field>
10635         <field id="reserved2">
10636           <jlong/>
10637             <description>
10638               Reserved for future use.
10639             </description>
10640         </field>
10641       </typedef>
10642 
10643       <intro>
10644         Where the timer kind is --
10645 
10646         <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
10647           <constant id="JVMTI_TIMER_USER_CPU" num="30">
10648             CPU time that a thread is in user mode.
10649           </constant>
10650           <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
10651             CPU time that a thread is in user or system mode.
10652           </constant>
10653           <constant id="JVMTI_TIMER_ELAPSED" num="32">
10654             Elapsed time.
10655           </constant>
10656         </constants>
10657       </intro>
10658 
10659     <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe"  impl="innative notrace" phase="start" num="134">
10660       <synopsis>Get Current Thread CPU Timer Information</synopsis>
10661       <description>
10662         Get information about the
10663         <functionlink id="GetCurrentThreadCpuTime"/> timer.
10664         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10665         are filled in with details about the timer.
10666         This information is specific to the platform and the implementation of
10667         <functionlink id="GetCurrentThreadCpuTime"/> and thus
10668         does not vary by thread nor does it vary
10669         during a particular invocation of the VM.
10670         <p/>
10671         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10672         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10673         returned by <code>GetCurrentThreadCpuTimerInfo</code>
10674         and <functionlink id="GetThreadCpuTimerInfo"/>
10675         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10676       </description>
10677       <origin>new</origin>
10678       <capabilities>
10679         <required id="can_get_current_thread_cpu_time">
10680             Can get current thread CPU time.
10681         </required>
10682       </capabilities>
10683       <parameters>
10684         <param id="info_ptr">
10685           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10686           <description>
10687             On return, filled with information describing the time
10688             returned by <functionlink id="GetCurrentThreadCpuTime"/>.
10689           </description>
10690         </param>
10691       </parameters>
10692       <errors>
10693       </errors>
10694     </function>
10695 
10696     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10697       <synopsis>Get Current Thread CPU Time</synopsis>
10698       <description>
10699             Return the CPU time utilized by the current thread.
10700             <p/>
10701             Note that the <functionlink id="GetThreadCpuTime"/>
10702             function provides CPU time for any thread, including
10703             the current thread. <code>GetCurrentThreadCpuTime</code>
10704             exists to support platforms which cannot
10705             supply CPU time for threads other than the current
10706             thread or which have more accurate information for
10707             the current thread (see
10708             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10709             <functionlink id="GetThreadCpuTimerInfo"/>).
10710             On many platforms this call will be equivalent to:
10711 <example>
10712   GetThreadCpuTime(env, NULL, nanos_ptr)
10713 </example>
10714       </description>
10715       <origin>new</origin>
10716       <capabilities>
10717         <required id="can_get_current_thread_cpu_time">
10718             Can get current thread CPU time.
10719             <p/>
10720             If this capability is enabled after threads have started,
10721             the implementation may choose any time up
10722             to and including the time that the capability is enabled
10723             as the point where CPU time collection starts.
10724             <p/>
10725             This capability must be potentially available on any
10726             platform where
10727             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10728             is potentially available.
10729         </required>
10730       </capabilities>
10731       <parameters>
10732         <param id="nanos_ptr">
10733           <outptr><jlong/></outptr>
10734           <description>
10735             On return, points to the CPU time used by this thread
10736             in nanoseconds.
10737             This is an unsigned value.  If tested or printed as a jlong (signed value)
10738             it may appear to be a negative number.
10739           </description>
10740         </param>
10741       </parameters>
10742       <errors>
10743       </errors>
10744     </function>
10745 
10746     <function id="GetThreadCpuTimerInfo" num="136">
10747       <synopsis>Get Thread CPU Timer Information</synopsis>
10748       <description>
10749         Get information about the
10750         <functionlink id="GetThreadCpuTime"/> timer.
10751         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10752         are filled in with details about the timer.
10753         This information is specific to the platform and the implementation of
10754         <functionlink id="GetThreadCpuTime"/> and thus
10755         does not vary by thread nor does it vary
10756         during a particular invocation of the VM.
10757         <p/>
10758         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10759         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10760         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
10761         and <code>GetThreadCpuTimerInfo</code>
10762         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10763       </description>
10764       <origin>new</origin>
10765       <capabilities>
10766         <required id="can_get_thread_cpu_time">
10767             Can get thread CPU time.
10768         </required>
10769       </capabilities>
10770       <parameters>
10771         <param id="info_ptr">
10772           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10773           <description>
10774             On return, filled with information describing the time
10775             returned by <functionlink id="GetThreadCpuTime"/>.
10776           </description>
10777         </param>
10778       </parameters>
10779       <errors>
10780       </errors>
10781     </function>
10782 
10783     <function id="GetThreadCpuTime" num="137">
10784       <synopsis>Get Thread CPU Time</synopsis>
10785       <description>
10786           Return the CPU time utilized by the specified thread.
10787           <p/>
10788           Get information about this timer with
10789           <functionlink id="GetThreadCpuTimerInfo"/>.
10790       </description>
10791       <origin>new</origin>
10792       <capabilities>
10793         <required id="can_get_thread_cpu_time">
10794             Can get thread CPU time.
10795             <p/>
10796             If this capability is enabled after threads have started,
10797             the implementation may choose any time up
10798             to and including the time that the capability is enabled
10799             as the point where CPU time collection starts.
10800         </required>
10801       </capabilities>
10802       <parameters>
10803         <param id="thread">
10804           <jthread null="current"/>
10805             <description>
10806               The thread to query.
10807             </description>
10808         </param>
10809         <param id="nanos_ptr">
10810           <outptr><jlong/></outptr>
10811           <description>
10812             On return, points to the CPU time used by the specified thread
10813             in nanoseconds.
10814             This is an unsigned value.  If tested or printed as a jlong (signed value)
10815             it may appear to be a negative number.
10816           </description>
10817         </param>
10818       </parameters>
10819       <errors>
10820       </errors>
10821     </function>
10822 
10823     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
10824       <synopsis>Get Timer Information</synopsis>
10825       <description>
10826         Get information about the
10827         <functionlink id="GetTime"/> timer.
10828         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10829         are filled in with details about the timer.
10830         This information will not change during a particular invocation of the VM.
10831       </description>
10832       <origin>new</origin>
10833       <capabilities>
10834       </capabilities>
10835       <parameters>
10836         <param id="info_ptr">
10837           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10838           <description>
10839             On return, filled with information describing the time
10840             returned by <functionlink id="GetTime"/>.
10841           </description>
10842         </param>
10843       </parameters>
10844       <errors>
10845       </errors>
10846     </function>
10847 
10848     <function id="GetTime" phase="any" callbacksafe="safe" num="139">
10849       <synopsis>Get Time</synopsis>
10850       <description>
10851           Return the current value of the system timer, in nanoseconds.
10852           <p/>
10853           The value returned represents nanoseconds since some fixed but
10854           arbitrary time (perhaps in the future, so values may be
10855           negative).  This function provides nanosecond precision, but not
10856           necessarily nanosecond accuracy. No guarantees are made about
10857           how frequently values change.
10858           <p/>
10859           Get information about this timer with
10860           <functionlink id="GetTimerInfo"/>.
10861       </description>
10862       <origin>new</origin>
10863       <capabilities>
10864       </capabilities>
10865       <parameters>
10866         <param id="nanos_ptr">
10867           <outptr><jlong/></outptr>
10868           <description>
10869             On return, points to the time in nanoseconds.
10870             This is an unsigned value.  If tested or printed as a jlong (signed value)
10871             it may appear to be a negative number.
10872           </description>
10873         </param>
10874       </parameters>
10875       <errors>
10876       </errors>
10877     </function>
10878 
10879     <function id="GetAvailableProcessors" phase="any" num="144">
10880       <synopsis>Get Available Processors</synopsis>
10881       <description>
10882           Returns the number of processors available to the Java virtual machine.
10883           <p/>
10884           This value may change during a particular invocation of the virtual machine.
10885           Applications that are sensitive to the number of available processors should
10886           therefore occasionally poll this property.
10887       </description>
10888       <origin>new</origin>
10889       <capabilities>
10890       </capabilities>
10891       <parameters>
10892         <param id="processor_count_ptr">
10893           <outptr><jint/></outptr>
10894           <description>
10895             On return, points to the maximum number of processors available to the
10896             virtual machine; never smaller than one.
10897           </description>
10898         </param>
10899       </parameters>
10900       <errors>
10901       </errors>
10902     </function>
10903 
10904   </category>
10905 
10906 
10907   <category id="classLoaderSearch" label="Class Loader Search">
10908 
10909     <intro>
10910       These functions allow the agent to add to the locations that a class loader searches for a class.
10911       This is useful for installing instrumentation under the correct class loader.
10912     </intro>
10913 
10914     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
10915       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
10916       <description>
10917           This function can be used to cause instrumentation classes to be defined by the
10918           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
10919           After the bootstrap
10920           class loader unsuccessfully searches for a class, the specified platform-dependent
10921           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in
10922           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments,
10923           the segments will be searched in the order that this function was called.
10924           <p/>
10925           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
10926           search path segment to be searched after the bootstrap class loader unsuccessfully searches
10927           for a class. The segment is typically a directory or JAR file.
10928           <p/>
10929           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
10930           path to a <externallink id="docs/technotes/guides/jar/jar.html">
10931           JAR file</externallink>. The agent should take care that the JAR file does not
10932           contain any classes or resources other than those to be defined by the bootstrap
10933           class loader for the purposes of instrumentation.
10934           <p/>
10935           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10936           reference that the Java virtual machine has previously unsuccessfully attempted
10937           to resolve always fails with the same error that was thrown as a result of the
10938           initial resolution attempt. Consequently, if the JAR file contains an entry
10939           that corresponds to a class for which the Java virtual machine has
10940           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10941           resolve that reference will fail with the same error as the initial attempt.
10942       </description>
10943       <origin>new</origin>
10944       <capabilities>
10945       </capabilities>
10946       <parameters>
10947         <param id="segment">
10948           <inbuf><char/></inbuf>
10949           <description>
10950             The platform-dependent search path segment, encoded as a
10951             <internallink id="mUTF">modified UTF-8</internallink> string.
10952           </description>
10953         </param>
10954       </parameters>
10955       <errors>
10956         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
10957           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10958            existing JAR file is an invalid path.
10959         </error>
10960       </errors>
10961     </function>
10962 
10963     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
10964       <synopsis>Add To System Class Loader Search</synopsis>
10965       <description>
10966           This function can be used to cause instrumentation classes to be
10967           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
10968           After the class loader unsuccessfully searches for a class, the specified platform-dependent search
10969           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the
10970           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the
10971           segments will be searched in the order that this function was called.
10972           <p/>
10973           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
10974           search path segment to be searched after the system class loader unsuccessfully searches
10975           for a class. The segment is typically a directory or JAR file.
10976           <p/>
10977           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a
10978           <externallink id="docs/technotes/guides/jar/jar.html">JAR file</externallink> to be
10979           searched after the system class loader unsuccessfully searches for a class. The agent should
10980           take care that the JAR file does not contain any classes or resources other than those to be
10981           defined by the system class loader for the purposes of instrumentation.
10982           <p/>
10983           In the live phase the system class loader supports adding a JAR file to be searched if
10984           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code>
10985           which takes a single parameter of type <code>java.lang.String</code>. The method is not required
10986           to have <code>public</code> access.
10987           <p/>
10988           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10989           reference that the Java virtual machine has previously unsuccessfully attempted
10990           to resolve always fails with the same error that was thrown as a result of the
10991           initial resolution attempt. Consequently, if the JAR file contains an entry
10992           that corresponds to a class for which the Java virtual machine has
10993           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10994           resolve that reference will fail with the same error as the initial attempt.
10995       </description>
10996       <origin>new</origin>
10997       <capabilities>
10998       </capabilities>
10999       <parameters>
11000         <param id="segment">
11001           <inbuf><char/></inbuf>
11002           <description>
11003             The platform-dependent search path segment, encoded as a
11004             <internallink id="mUTF">modified UTF-8</internallink> string.
11005           </description>
11006         </param>
11007       </parameters>
11008       <errors>
11009         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11010           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
11011            existing JAR file is an invalid path.
11012         </error>
11013         <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
11014           Operation not supported by the system class loader.
11015         </error>
11016       </errors>
11017     </function>
11018 
11019   </category>
11020 
11021 
11022   <category id="props" label="System Properties">
11023 
11024     <intro>
11025       These functions get and set system properties.
11026     </intro>
11027 
11028     <function id="GetSystemProperties" phase="onload" num="130">
11029       <synopsis>Get System Properties</synopsis>
11030       <description>
11031         The list of VM system property keys which may be used with
11032         <functionlink id="GetSystemProperty"/> is returned.
11033         It is strongly recommended that virtual machines provide the
11034         following property keys:
11035         <ul>
11036           <li><code>java.vm.vendor</code></li>
11037           <li><code>java.vm.version</code></li>
11038           <li><code>java.vm.name</code></li>
11039           <li><code>java.vm.info</code></li>
11040           <li><code>java.library.path</code></li>
11041           <li><code>java.class.path</code></li>
11042         </ul>
11043         Provides access to system properties defined by and used
11044         by the VM.
11045         Properties set on the command-line are included.
11046         This allows getting and setting of these properties
11047         before the VM even begins executing bytecodes.
11048         Since this is a VM view of system properties, the set of available
11049         properties will usually be different than that
11050         in <code>java.lang.System.getProperties</code>.
11051         JNI method invocation may be used to access
11052         <code>java.lang.System.getProperties</code>.
11053         <p/>
11054         The set of properties may grow during execution.
11055       </description>
11056       <origin>new</origin>
11057       <capabilities>
11058       </capabilities>
11059       <parameters>
11060         <param id="count_ptr">
11061           <outptr><jint/></outptr>
11062           <description>
11063             On return, points to the number of property keys returned.
11064           </description>
11065         </param>
11066         <param id="property_ptr">
11067           <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
11068           <description>
11069             On return, points to an array of property keys, encoded as
11070             <internallink id="mUTF">modified UTF-8</internallink> strings.
11071           </description>
11072         </param>
11073       </parameters>
11074       <errors>
11075       </errors>
11076     </function>
11077 
11078     <function id="GetSystemProperty" phase="onload" num="131">
11079       <synopsis>Get System Property</synopsis>
11080       <description>
11081         Return a VM system property value given the property key.
11082         <p/>
11083         The function <functionlink id="GetSystemProperties"/>
11084         returns the set of property keys which may be used.
11085         The properties which can be retrieved may grow during
11086         execution.
11087         <p/>
11088         Since this is a VM view of system properties, the values
11089         of properties may differ from that returned by
11090         <code>java.lang.System.getProperty(String)</code>.
11091         A typical VM might copy the values of the VM system
11092         properties into the <code>Properties</code> held by
11093         <code>java.lang.System</code> during the initialization
11094         of that class. Thereafter any changes to the VM system
11095         properties (with <functionlink id="SetSystemProperty"/>)
11096         or the <code>java.lang.System</code> system properties
11097         (with <code>java.lang.System.setProperty(String,String)</code>)
11098         would cause the values to diverge.
11099         JNI method invocation may be used to access
11100         <code>java.lang.System.getProperty(String)</code>.
11101       </description>
11102       <origin>new</origin>
11103       <capabilities>
11104       </capabilities>
11105       <parameters>
11106         <param id="property">
11107           <inbuf><char/></inbuf>
11108           <description>
11109             The key of the property to retrieve, encoded as a
11110             <internallink id="mUTF">modified UTF-8</internallink> string.
11111           </description>
11112         </param>
11113         <param id="value_ptr">
11114           <allocbuf><char/></allocbuf>
11115           <description>
11116             On return, points to the property value, encoded as a
11117             <internallink id="mUTF">modified UTF-8</internallink> string.
11118           </description>
11119         </param>
11120       </parameters>
11121       <errors>
11122         <error id="JVMTI_ERROR_NOT_AVAILABLE">
11123           This property is not available.
11124           Use <functionlink id="GetSystemProperties"/> to find available properties.
11125         </error>
11126       </errors>
11127     </function>
11128 
11129     <function id="SetSystemProperty" phase="onloadOnly" num="132">
11130       <synopsis>Set System Property</synopsis>
11131       <description>
11132         Set a VM system property value.
11133         <p/>
11134         The function <functionlink id="GetSystemProperties"/>
11135         returns the set of property keys, some of these may be settable.
11136         See <functionlink id="GetSystemProperty"/>.
11137       </description>
11138       <origin>new</origin>
11139       <capabilities>
11140       </capabilities>
11141       <parameters>
11142         <param id="property">
11143           <inbuf><char/></inbuf>
11144           <description>
11145             The key of the property, encoded as a
11146             <internallink id="mUTF">modified UTF-8</internallink> string.
11147           </description>
11148         </param>
11149         <param id="value_ptr">
11150           <inbuf>
11151             <char/>
11152             <nullok>
11153               do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
11154               if the property is not writeable
11155             </nullok>
11156           </inbuf>
11157           <description>
11158             The property value to set, encoded as a
11159             <internallink id="mUTF">modified UTF-8</internallink> string.
11160           </description>
11161         </param>
11162       </parameters>
11163       <errors>
11164         <error id="JVMTI_ERROR_NOT_AVAILABLE">
11165           This property is not available or is not writeable.
11166         </error>
11167       </errors>
11168     </function>
11169 
11170   </category>
11171 
11172   <category id="general" label="General">
11173 
11174     <intro>
11175     </intro>
11176 
11177     <function id="GetPhase" jkernel="yes" phase="any" num="133">
11178       <synopsis>Get Phase</synopsis>
11179       <description>
11180           Return the current phase of VM execution.
11181           The phases proceed in sequence:
11182           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
11183             <constant id="JVMTI_PHASE_ONLOAD" num="1">
11184               <code>OnLoad</code> phase: while in the
11185               <internallink id="onload"><code>Agent_OnLoad</code></internallink>
11186               or, for statically linked agents, the <internallink id="onload">
11187               <code>Agent_OnLoad_&lt;agent-lib-name&gt;
11188               </code></internallink> function.
11189             </constant>
11190             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
11191               Primordial phase: between return from <code>Agent_OnLoad</code>
11192               or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> and the
11193               <code>VMStart</code> event.
11194             </constant>
11195             <constant id="JVMTI_PHASE_START" num="6">
11196               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event
11197               is sent and until the <code>VMInit</code> event is sent.
11198             </constant>
11199             <constant id="JVMTI_PHASE_LIVE" num="4">
11200               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
11201               and until the <eventlink id="VMDeath"></eventlink> event returns.
11202             </constant>
11203             <constant id="JVMTI_PHASE_DEAD" num="8">
11204               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
11205               start-up failure.
11206             </constant>
11207           </constants>
11208           In the case of start-up failure the VM will proceed directly to the dead
11209           phase skipping intermediate phases and neither a <code>VMInit</code> nor
11210           <code>VMDeath</code> event will be sent.
11211           <p/>
11212           Most <jvmti/> functions operate only in the live phase.
11213           The following functions operate in either the <code>OnLoad</code> or live phases:
11214           <functionphaselist phase="onload"/>
11215           The following functions operate in only the <code>OnLoad</code> phase:
11216           <functionphaselist phase="onloadOnly"/>
11217           The following functions operate in the start or live phases:
11218           <functionphaselist phase="start"/>
11219           The following functions operate in any phase:
11220           <functionphaselist phase="any"/>
11221           JNI functions (except the Invocation API) must only be used in the start or live phases.
11222           <p/>
11223           Most <jvmti/> events are sent only in the live phase.
11224           The following events operate in others phases:
11225           <eventphaselist phase="start"/>
11226           <eventphaselist phase="any"/>
11227       </description>
11228       <origin>new</origin>
11229       <capabilities>
11230       </capabilities>
11231       <parameters>
11232         <param id="phase_ptr">
11233           <outptr><enum>jvmtiPhase</enum></outptr>
11234           <description>
11235             On return, points to the phase.
11236           </description>
11237         </param>
11238       </parameters>
11239       <errors>
11240       </errors>
11241     </function>
11242 
11243     <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
11244       <synopsis>Dispose Environment</synopsis>
11245       <description>
11246         Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
11247         (see <internallink id="environments"><jvmti/> Environments</internallink>).
11248         Dispose of any resources held by the environment.
11249         <issue>
11250             What resources are reclaimed? What is undone?
11251             Breakpoints,watchpoints removed?
11252         </issue>
11253         Threads suspended by this environment are not resumed by this call,
11254         this must be done explicitly by the agent.
11255         Memory allocated by this environment via calls to <jvmti/> functions
11256         is not released, this can be done explicitly by the agent
11257         by calling <functionlink id="Deallocate"/>.
11258         Raw monitors created by this environment are not destroyed,
11259         this can be done explicitly by the agent
11260         by calling <functionlink id="DestroyRawMonitor"/>.
11261         The state of threads waiting on raw monitors created by this environment
11262         are not affected.
11263         <p/>
11264         Any <functionlink id="SetNativeMethodPrefix">native method
11265         prefixes</functionlink> for this environment will be unset;
11266         the agent must remove any prefixed native methods before
11267         dispose is called.
11268         <p/>
11269         Any <internallink id="capability">capabilities</internallink>
11270         held by this environment are relinquished.
11271         <p/>
11272         Events enabled by this environment will no longer be sent, however
11273         event handlers currently running will continue to run.  Caution must
11274         be exercised in the design of event handlers whose environment may
11275         be disposed and thus become invalid during their execution.
11276         <p/>
11277         This environment may not be used after this call.
11278         This call returns to the caller.
11279       </description>
11280       <origin>new</origin>
11281       <capabilities>
11282       </capabilities>
11283       <parameters>
11284       </parameters>
11285       <errors>
11286       </errors>
11287     </function>
11288 
11289     <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
11290       <synopsis>Set Environment Local Storage</synopsis>
11291       <description>
11292         The VM stores a pointer value associated with each environment.
11293         This pointer value is called <i>environment-local storage</i>.
11294         This value is <code>NULL</code> unless set with this function.
11295         Agents can allocate memory in which they store environment specific
11296         information. By setting environment-local storage it can then be
11297         accessed with
11298         <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
11299         <p/>
11300         Called by the agent to set the value of the <jvmti/>
11301         environment-local storage. <jvmti/> supplies to the agent a pointer-size
11302         environment-local storage that can be used to record per-environment
11303         information.
11304       </description>
11305       <origin>new</origin>
11306       <capabilities>
11307       </capabilities>
11308       <parameters>
11309         <param id="data">
11310           <inbuf>
11311             <void/>
11312             <nullok>value is set to <code>NULL</code></nullok>
11313           </inbuf>
11314           <description>
11315             The value to be entered into the environment-local storage.
11316           </description>
11317         </param>
11318       </parameters>
11319       <errors>
11320       </errors>
11321     </function>
11322 
11323     <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
11324       <synopsis>Get Environment Local Storage</synopsis>
11325       <description>
11326         Called by the agent to get the value of the <jvmti/> environment-local
11327         storage.
11328       </description>
11329       <origin>new</origin>
11330       <capabilities>
11331       </capabilities>
11332       <parameters>
11333         <param id="data_ptr">
11334           <agentbuf><void/></agentbuf>
11335           <description>
11336             Pointer through which the value of the environment local
11337             storage is returned.
11338             If environment-local storage has not been set with
11339             <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned
11340             pointer is <code>NULL</code>.
11341           </description>
11342         </param>
11343       </parameters>
11344       <errors>
11345       </errors>
11346     </function>
11347 
11348     <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
11349       <synopsis>Get Version Number</synopsis>
11350       <description>
11351         Return the <jvmti/> version via <code>version_ptr</code>.
11352         The return value is the version identifier.
11353         The version identifier includes major, minor and micro
11354         version as well as the interface type.
11355         <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
11356           <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
11357             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
11358           </constant>
11359           <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
11360             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
11361           </constant>
11362         </constants>
11363         <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
11364           <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
11365             Mask to extract interface type.
11366             The value of the version returned by this function masked with
11367             <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
11368             <code>JVMTI_VERSION_INTERFACE_JVMTI</code>
11369             since this is a <jvmti/> function.
11370           </constant>
11371           <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
11372             Mask to extract major version number.
11373           </constant>
11374           <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
11375             Mask to extract minor version number.
11376           </constant>
11377           <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
11378             Mask to extract micro version number.
11379           </constant>
11380         </constants>
11381         <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
11382           <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
11383             Shift to extract major version number.
11384           </constant>
11385           <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
11386             Shift to extract minor version number.
11387           </constant>
11388           <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
11389             Shift to extract micro version number.
11390           </constant>
11391         </constants>
11392       </description>
11393       <origin>jvmdi</origin>
11394       <capabilities>
11395       </capabilities>
11396       <parameters>
11397         <param id="version_ptr">
11398           <outptr><jint/></outptr>
11399           <description>
11400             On return, points to the <jvmti/> version.
11401           </description>
11402         </param>
11403       </parameters>
11404       <errors>
11405       </errors>
11406     </function>
11407 
11408 
11409     <function id="GetErrorName" phase="any" num="128">
11410       <synopsis>Get Error Name</synopsis>
11411       <description>
11412         Return the symbolic name for an
11413           <internallink id="ErrorSection">error code</internallink>.
11414         <p/>
11415         For example
11416         <code>GetErrorName(env, JVMTI_ERROR_NONE, &amp;err_name)</code>
11417         would return in <code>err_name</code> the string
11418         <code>"JVMTI_ERROR_NONE"</code>.
11419       </description>
11420       <origin>new</origin>
11421       <capabilities>
11422       </capabilities>
11423       <parameters>
11424         <param id="error">
11425           <enum>jvmtiError</enum>
11426           <description>
11427             The error code.
11428           </description>
11429         </param>
11430         <param id="name_ptr">
11431           <allocbuf><char/></allocbuf>
11432           <description>
11433             On return, points to the error name.
11434             The name is encoded as a
11435             <internallink id="mUTF">modified UTF-8</internallink> string,
11436             but is restricted to the ASCII subset.
11437           </description>
11438         </param>
11439       </parameters>
11440       <errors>
11441       </errors>
11442     </function>
11443 
11444     <function id="SetVerboseFlag" phase="any" num="150">
11445       <synopsis>Set Verbose Flag</synopsis>
11446       <description>
11447         <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
11448           <constant id="JVMTI_VERBOSE_OTHER" num="0">
11449             Verbose output other than the below.
11450           </constant>
11451           <constant id="JVMTI_VERBOSE_GC" num="1">
11452             Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
11453           </constant>
11454           <constant id="JVMTI_VERBOSE_CLASS" num="2">
11455             Verbose class loading output, like that specified with <code>-verbose:class</code>.
11456           </constant>
11457           <constant id="JVMTI_VERBOSE_JNI" num="4">
11458             Verbose JNI output, like that specified with <code>-verbose:jni</code>.
11459           </constant>
11460         </constants>
11461         Control verbose output.
11462         This is the output which typically is sent to <code>stderr</code>.
11463       </description>
11464       <origin>new</origin>
11465       <capabilities>
11466       </capabilities>
11467       <parameters>
11468         <param id="flag">
11469           <enum>jvmtiVerboseFlag</enum>
11470           <description>
11471             Which verbose flag to set.
11472           </description>
11473         </param>
11474         <param id="value">
11475           <jboolean/>
11476           <description>
11477             New value of the flag.
11478           </description>
11479         </param>
11480       </parameters>
11481       <errors>
11482       </errors>
11483     </function>
11484 
11485 
11486     <function id="GetJLocationFormat" phase="any" num="129">
11487       <synopsis>Get JLocation Format</synopsis>
11488       <description>
11489         Although the greatest functionality is achieved with location information
11490         referencing the virtual machine bytecode index, the definition of
11491         <code>jlocation</code> has intentionally been left unconstrained to allow VM
11492         implementations that do not have this information.
11493         <p/>
11494         This function describes the representation of <code>jlocation</code> used in this VM.
11495         If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>,
11496         <code>jlocation</code>s can
11497         be used as in indices into the array returned by
11498         <functionlink id="GetBytecodes"></functionlink>.
11499         <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
11500           <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
11501             <code>jlocation</code> values represent virtual machine
11502             bytecode indices--that is, offsets into the
11503             virtual machine code for a method.
11504           </constant>
11505           <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
11506             <code>jlocation</code> values represent native machine
11507             program counter values.
11508           </constant>
11509           <constant id="JVMTI_JLOCATION_OTHER" num="0">
11510             <code>jlocation</code> values have some other representation.
11511           </constant>
11512         </constants>
11513       </description>
11514       <origin>new</origin>
11515       <capabilities>
11516       </capabilities>
11517       <parameters>
11518         <param id="format_ptr">
11519           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11520           <description>
11521             On return, points to the format identifier for <code>jlocation</code> values.
11522           </description>
11523         </param>
11524       </parameters>
11525       <errors>
11526       </errors>
11527     </function>
11528 
11529   </category>
11530 
11531 </functionsection>
11532 
11533 <errorsection label="Error Reference">
11534   <intro>
11535     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11536     <p/>
11537     It is the responsibility of the agent to call <jvmti/> functions with
11538     valid parameters and in the proper context (calling thread is attached,
11539     phase is correct, etc.).
11540     Detecting some error conditions may be difficult, inefficient, or
11541     impossible for an implementation.
11542     The errors listed in
11543     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11544     must be detected by the implementation.
11545     All other errors represent the recommended response to the error
11546     condition.
11547   </intro>
11548 
11549   <errorcategory id="universal-error" label="Universal Errors">
11550     <intro>
11551       The following errors may be returned by any function
11552     </intro>
11553 
11554     <errorid id="JVMTI_ERROR_NONE" num="0">
11555       No error has occurred.  This is the error code that is returned
11556       on successful completion of the function.
11557     </errorid>
11558     <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
11559       Pointer is unexpectedly <code>NULL</code>.
11560     </errorid>
11561     <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
11562       The function attempted to allocate memory and no more memory was
11563       available for allocation.
11564     </errorid>
11565     <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
11566       The desired functionality has not been enabled in this virtual machine.
11567     </errorid>
11568     <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
11569       The thread being used to call this function is not attached
11570       to the virtual machine.  Calls must be made from attached threads.
11571       See <code>AttachCurrentThread</code> in the JNI invocation API.
11572     </errorid>
11573     <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
11574       The <jvmti/> environment provided is no longer connected or is
11575       not an environment.
11576     </errorid>
11577     <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
11578       The desired functionality is not available in the current
11579         <functionlink id="GetPhase">phase</functionlink>.
11580       Always returned if the virtual machine has completed running.
11581     </errorid>
11582     <errorid id="JVMTI_ERROR_INTERNAL" num="113">
11583       An unexpected internal error has occurred.
11584     </errorid>
11585   </errorcategory>
11586 
11587   <errorcategory id="reqerrors" label="Function Specific Required Errors">
11588     <intro>
11589       The following errors are returned by some <jvmti/> functions and must
11590       be returned by the implementation when the condition occurs.
11591     </intro>
11592 
11593     <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
11594       Invalid priority.
11595     </errorid>
11596     <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
11597       Thread was not suspended.
11598     </errorid>
11599     <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
11600       Thread already suspended.
11601     </errorid>
11602     <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
11603       This operation requires the thread to be alive--that is,
11604       it must be started and not yet have died.
11605     </errorid>
11606     <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
11607       The class has been loaded but not yet prepared.
11608     </errorid>
11609     <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
11610       There are no Java programming language or JNI stack frames at the specified depth.
11611     </errorid>
11612     <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
11613       Information about the frame is not available (e.g. for native frames).
11614     </errorid>
11615     <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
11616       Item already set.
11617     </errorid>
11618     <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
11619       Desired element (e.g. field or breakpoint) not found
11620     </errorid>
11621     <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
11622       This thread doesn't own the raw monitor.
11623     </errorid>
11624     <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
11625       The call has been interrupted before completion.
11626     </errorid>
11627     <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
11628       The class cannot be modified.
11629     </errorid>
11630     <errorid id="JVMTI_ERROR_UNMODIFIABLE_MODULE" num="80">
11631       The module cannot be modified.
11632     </errorid>
11633     <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
11634       The functionality is not available in this virtual machine.
11635     </errorid>
11636     <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
11637       The requested information is not available.
11638     </errorid>
11639     <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
11640       The specified event type ID is not recognized.
11641     </errorid>
11642     <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
11643       The requested information is not available for native method.
11644     </errorid>
11645     <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
11646       The class loader does not support this operation.
11647     </errorid>
11648   </errorcategory>
11649 
11650   <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
11651     <intro>
11652       The following errors are returned by some <jvmti/> functions.
11653       They are returned in the event of invalid parameters passed by the
11654       agent or usage in an invalid context.
11655       An implementation is not required to detect these errors.
11656     </intro>
11657 
11658     <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
11659       The passed thread is not a valid thread.
11660     </errorid>
11661     <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
11662       Invalid field.
11663     </errorid>
11664     <errorid id="JVMTI_ERROR_INVALID_MODULE" num="26">
11665       Invalid module.
11666     </errorid>
11667     <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
11668       Invalid method.
11669     </errorid>
11670     <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
11671       Invalid location.
11672     </errorid>
11673     <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
11674       Invalid object.
11675     </errorid>
11676     <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
11677       Invalid class.
11678     </errorid>
11679     <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
11680       The variable is not an appropriate type for the function used.
11681     </errorid>
11682     <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
11683       Invalid slot.
11684     </errorid>
11685     <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
11686       The capability being used is false in this environment.
11687     </errorid>
11688     <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
11689       Thread group invalid.
11690     </errorid>
11691     <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
11692       Invalid raw monitor.
11693     </errorid>
11694     <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
11695       Illegal argument.
11696     </errorid>
11697     <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
11698       The state of the thread has been modified, and is now inconsistent.
11699     </errorid>
11700     <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
11701       A new class file has a version number not supported by this VM.
11702     </errorid>
11703     <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
11704       A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
11705     </errorid>
11706     <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
11707       The new class file definitions would lead to a circular
11708       definition (the VM would return a <code>ClassCircularityError</code>).
11709     </errorid>
11710     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
11711       A new class file would require adding a method.
11712     </errorid>
11713     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
11714       A new class version changes a field.
11715     </errorid>
11716     <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
11717       The class bytes fail verification.
11718     </errorid>
11719     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
11720       A direct superclass is different for the new class
11721       version, or the set of directly implemented
11722       interfaces is different.
11723     </errorid>
11724     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
11725       A new class version does not declare a method
11726       declared in the old class version.
11727     </errorid>
11728     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
11729       The class name defined in the new class file is
11730       different from the name in the old class object.
11731     </errorid>
11732     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
11733       A new class version has different modifiers.
11734     </errorid>
11735     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
11736       A method in the new class version has different modifiers
11737       than its counterpart in the old class version.
11738     </errorid>
11739   </errorcategory>
11740 </errorsection>
11741 
11742 <eventsection label="Events">
11743   <intro label="Handling Events" id="eventIntro">
11744     Agents can be informed of many events that occur in application
11745     programs.
11746     <p/>
11747     To handle events, designate a set of callback functions with
11748     <functionlink id="SetEventCallbacks"></functionlink>.
11749     For each event the corresponding callback function will be
11750     called.
11751     Arguments to the callback function provide additional
11752     information about the event.
11753     <p/>
11754     The callback function is usually called from within an application
11755     thread. The <jvmti/> implementation does not
11756     queue events in any way. This means
11757     that event callback functions must be written
11758     carefully. Here are some general guidelines. See
11759     the individual event descriptions for further
11760     suggestions.
11761     <p/>
11762     <ul>
11763       <li>Any exception thrown during the execution of an event callback can
11764         overwrite any current pending exception in the current application thread.
11765         Care must be taken to preserve a pending exception
11766         when an event callback makes a JNI call that might generate an exception.
11767       </li>
11768       <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
11769         not queue events. If an agent needs to process events one at a time, it
11770         can use a raw monitor inside the
11771         event callback functions to serialize event processing.
11772       </li>
11773       <li>Event callback functions that execute JNI's FindClass function to load
11774         classes need to note that FindClass locates the class loader associated
11775         with the current native method. For the purposes of class loading, an
11776         event callback that includes a JNI environment as a parameter to the
11777         callback will treated as if it is a native call, where the native method
11778         is in the class of the event thread's current frame.
11779       </li>
11780     </ul>
11781     <p/>
11782     Some <jvmti/> events identify objects with JNI references.
11783     All references
11784     in <jvmti/> events are JNI local references and will become invalid
11785     after the event callback returns.
11786     Unless stated otherwise, memory referenced by pointers sent in event
11787     callbacks may not be referenced after the event callback returns.
11788     <p/>
11789     Except where stated otherwise, events are delivered on the thread
11790     that caused the event.
11791     Events are sent at the time they occur.
11792     The specification for each event includes the set of
11793     <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
11794     if an event triggering activity occurs during another phase, no event
11795     is sent.
11796     <p/>
11797     A thread that generates an event does not change its execution status
11798     (for example, the event does not cause the thread to be suspended).
11799     If an agent wishes the event to result in suspension, then the agent
11800     is responsible for explicitly suspending the thread with
11801     <functionlink id="SuspendThread"></functionlink>.
11802     <p/>
11803     If an event is enabled in multiple environments, the event will be sent
11804     to each agent in the order that the environments were created.
11805   </intro>
11806 
11807   <intro label="Enabling Events" id="enablingevents">
11808     All events are initially disabled.  In order to receive any
11809     event:
11810       <ul>
11811         <li>
11812           If the event requires a capability, that capability must
11813           be added with
11814           <functionlink id="AddCapabilities"></functionlink>.
11815         </li>
11816         <li>
11817           A callback for the event must be set with
11818           <functionlink id="SetEventCallbacks"></functionlink>.
11819         </li>
11820         <li>
11821           The event must be enabled with
11822           <functionlink id="SetEventNotificationMode"></functionlink>.
11823         </li>
11824       </ul>
11825   </intro>
11826 
11827   <intro label="Multiple Co-located Events" id="eventorder">
11828     In many situations it is possible for multiple events to occur
11829     at the same location in one thread. When this happens, all the events
11830     are reported through the event callbacks in the order specified in this section.
11831     <p/>
11832     If the current location is at the entry point of a method, the
11833     <eventlink id="MethodEntry"></eventlink> event is reported before
11834     any other event at the current location in the same thread.
11835     <p/>
11836     If an exception catch has been detected at the current location,
11837     either because it is the beginning of a catch clause or a native method
11838     that cleared a pending exception has returned, the
11839     <code>exceptionCatch</code> event is reported before
11840     any other event at the current location in the same thread.
11841     <p/>
11842     If a <code>singleStep</code> event or
11843     <code>breakpoint</code> event is triggered at the
11844     current location, the event is defined to occur
11845     immediately before the code at the current location is executed.
11846     These events are reported before any events which are triggered
11847     by the execution of code at the current location in the same
11848     thread (specifically:
11849     <code>exception</code>,
11850     <code>fieldAccess</code>, and
11851     <code>fieldModification</code>).
11852     If both a step and breakpoint event are triggered for the same thread and
11853     location, the step event is reported before the breakpoint event.
11854     <p/>
11855     If the current location is the exit point of a method (that is, the last
11856     location before returning to the caller), the
11857     <eventlink id="MethodExit"></eventlink> event and
11858     the <eventlink id="FramePop"></eventlink> event (if requested)
11859     are reported after all other events at the current location in the same
11860     thread. There is no specified ordering of these two events
11861     with respect to each other.
11862     <p/>
11863     Co-located events can be triggered during the processing of some other
11864     event by the agent at the same location in the same thread.
11865     If such an event, of type <i>y</i>, is triggered during the processing of
11866     an event of type <i>x</i>, and if <i>x</i>
11867     precedes <i>y</i> in the ordering specified above, the co-located event
11868     <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
11869     <i>y</i>, <i>y</i> is not reported for the current thread and location.
11870     For example, if a breakpoint is set at the current location
11871     during the processing of <eventlink id="SingleStep"></eventlink>,
11872     that breakpoint will be reported before the thread moves off the current
11873     location.
11874     <p/>The following events are never considered to be co-located with
11875     other events.
11876     <ul>
11877       <li><eventlink id="VMStart"></eventlink></li>
11878       <li><eventlink id="VMInit"></eventlink></li>
11879       <li><eventlink id="VMDeath"></eventlink></li>
11880       <li><eventlink id="ThreadStart"></eventlink></li>
11881       <li><eventlink id="ThreadEnd"></eventlink></li>
11882       <li><eventlink id="ClassLoad"></eventlink></li>
11883       <li><eventlink id="ClassPrepare"></eventlink></li>
11884     </ul>
11885   </intro>
11886 
11887   <intro label="Event Callbacks" id="jvmtiEventCallbacks">
11888       The event callback structure below is used to specify the handler function
11889       for events.  It is set with the
11890       <functionlink id="SetEventCallbacks"></functionlink> function.
11891   </intro>
11892 
11893   <event label="Single Step"
11894          id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
11895     <description>
11896       Single step events allow the agent to trace thread execution
11897       at the finest granularity allowed by the VM. A single step event is
11898       generated whenever a thread reaches a new location.
11899       Typically, single step events represent the completion of one VM
11900       instruction as defined in <vmspec/>. However, some implementations
11901       may define locations differently. In any case the
11902       <code>method</code> and <code>location</code>
11903       parameters  uniquely identify the current location and allow
11904       the mapping to source file and line number when that information is
11905       available.
11906       <p/>
11907       No single step events are generated from within native methods.
11908     </description>
11909     <origin>jvmdi</origin>
11910     <capabilities>
11911       <required id="can_generate_single_step_events"></required>
11912     </capabilities>
11913     <parameters>
11914       <param id="jni_env">
11915         <outptr>
11916           <struct>JNIEnv</struct>
11917         </outptr>
11918           <description>
11919             The JNI environment of the event (current) thread
11920           </description>
11921       </param>
11922       <param id="thread">
11923         <jthread/>
11924           <description>
11925             Thread about to execution a new instruction
11926           </description>
11927       </param>
11928       <param id="klass">
11929         <jclass method="method"/>
11930           <description>
11931             Class of the method about to execute a new instruction
11932           </description>
11933       </param>
11934       <param id="method">
11935         <jmethodID class="klass"/>
11936           <description>
11937             Method about to execute a new instruction
11938           </description>
11939       </param>
11940       <param id="location">
11941         <jlocation/>
11942         <description>
11943           Location of the new instruction
11944         </description>
11945       </param>
11946     </parameters>
11947   </event>
11948 
11949   <event label="Breakpoint"
11950          id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
11951     <description>
11952       Breakpoint events are generated whenever a thread reaches a location
11953       designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
11954       The <code>method</code> and <code>location</code>
11955       parameters uniquely identify the current location and allow
11956       the mapping to source file and line number when that information is
11957       available.
11958     </description>
11959     <origin>jvmdi</origin>
11960     <capabilities>
11961       <required id="can_generate_breakpoint_events"></required>
11962     </capabilities>
11963     <parameters>
11964       <param id="jni_env">
11965         <outptr>
11966           <struct>JNIEnv</struct>
11967         </outptr>
11968           <description>
11969             The JNI environment of the event (current) thread.
11970           </description>
11971       </param>
11972       <param id="thread">
11973         <jthread/>
11974           <description>
11975             Thread that hit the breakpoint
11976           </description>
11977       </param>
11978       <param id="klass">
11979         <jclass method="method"/>
11980           <description>
11981             Class of the method that hit the breakpoint
11982           </description>
11983       </param>
11984       <param id="method">
11985         <jmethodID class="klass"/>
11986           <description>
11987             Method that hit the breakpoint
11988           </description>
11989       </param>
11990       <param id="location">
11991         <jlocation/>
11992         <description>
11993           location of the breakpoint
11994         </description>
11995       </param>
11996     </parameters>
11997   </event>
11998 
11999   <event label="Field Access"
12000          id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
12001     <description>
12002       Field access events are generated whenever a thread accesses
12003       a field that was designated as a watchpoint
12004       with <functionlink id="SetFieldAccessWatch"></functionlink>.
12005       The <code>method</code> and <code>location</code>
12006       parameters uniquely identify the current location and allow
12007       the mapping to source file and line number when that information is
12008       available.
12009     </description>
12010     <origin>jvmdi</origin>
12011     <capabilities>
12012       <required id="can_generate_field_access_events"></required>
12013     </capabilities>
12014     <parameters>
12015       <param id="jni_env">
12016         <outptr>
12017           <struct>JNIEnv</struct>
12018         </outptr>
12019           <description>
12020             The JNI environment of the event (current) thread
12021           </description>
12022       </param>
12023       <param id="thread">
12024         <jthread/>
12025           <description>
12026             Thread accessing the field
12027           </description>
12028       </param>
12029       <param id="klass">
12030         <jclass method="method"/>
12031           <description>
12032             Class of the method where the access is occurring
12033           </description>
12034       </param>
12035       <param id="method">
12036         <jmethodID class="klass"/>
12037           <description>
12038             Method where the access is occurring
12039           </description>
12040       </param>
12041       <param id="location">
12042         <jlocation/>
12043         <description>
12044           Location where the access is occurring
12045         </description>
12046       </param>
12047       <param id="field_klass">
12048         <jclass field="field"/>
12049           <description>
12050             Class of the field being accessed
12051           </description>
12052       </param>
12053       <param id="object">
12054         <jobject/>
12055           <description>
12056             Object with the field being accessed if the field is an
12057             instance field; <code>NULL</code> otherwise
12058           </description>
12059       </param>
12060       <param id="field">
12061         <jfieldID class="field_klass"/>
12062           <description>
12063             Field being accessed
12064           </description>
12065       </param>
12066     </parameters>
12067   </event>
12068 
12069   <event label="Field Modification"
12070          id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
12071     <description>
12072       Field modification events are generated whenever a thread modifies
12073       a field that was designated as a watchpoint
12074       with <functionlink id="SetFieldModificationWatch"></functionlink>.
12075       The <code>method</code> and <code>location</code>
12076       parameters uniquely identify the current location and allow
12077       the mapping to source file and line number when that information is
12078       available.
12079     </description>
12080     <origin>jvmdi</origin>
12081     <capabilities>
12082       <required id="can_generate_field_modification_events"></required>
12083     </capabilities>
12084     <parameters>
12085       <param id="jni_env">
12086         <outptr>
12087           <struct>JNIEnv</struct>
12088         </outptr>
12089           <description>
12090             The JNI environment of the event (current) thread
12091           </description>
12092       </param>
12093       <param id="thread">
12094         <jthread/>
12095           <description>
12096             Thread modifying the field
12097           </description>
12098       </param>
12099       <param id="klass">
12100         <jclass method="method"/>
12101           <description>
12102             Class of the method where the modification is occurring
12103           </description>
12104       </param>
12105       <param id="method">
12106         <jmethodID class="klass"/>
12107           <description>
12108             Method where the modification is occurring
12109           </description>
12110       </param>
12111       <param id="location">
12112         <jlocation/>
12113         <description>
12114           Location where the modification is occurring
12115         </description>
12116       </param>
12117       <param id="field_klass">
12118         <jclass field="field"/>
12119           <description>
12120             Class of the field being modified
12121           </description>
12122       </param>
12123       <param id="object">
12124         <jobject/>
12125           <description>
12126             Object with the field being modified if the field is an
12127             instance field; <code>NULL</code> otherwise
12128           </description>
12129       </param>
12130       <param id="field">
12131         <jfieldID class="field_klass"/>
12132           <description>
12133             Field being modified
12134           </description>
12135       </param>
12136       <param id="signature_type">
12137         <char/>
12138         <description>
12139           Signature type of the new value
12140         </description>
12141       </param>
12142       <param id="new_value">
12143         <jvalue/>
12144         <description>
12145           The new value
12146         </description>
12147       </param>
12148     </parameters>
12149   </event>
12150 
12151   <event label="Frame Pop"
12152          id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
12153     <description>
12154       Frame pop events are generated upon exit from a single method
12155       in a single frame as specified
12156       in a call to <functionlink id="NotifyFramePop"></functionlink>.
12157       This is true whether termination is caused by
12158       executing its return instruction
12159       or by throwing an exception to its caller
12160       (see <paramlink id="was_popped_by_exception"></paramlink>).
12161       However, frame pops caused by the <functionlink id="PopFrame"/>
12162       function are not reported.
12163       <p/>
12164       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12165       identifies the executable location in the returning method,
12166       immediately prior to the return.
12167     </description>
12168     <origin>jvmdi</origin>
12169     <capabilities>
12170       <required id="can_generate_frame_pop_events"></required>
12171     </capabilities>
12172     <parameters>
12173       <param id="jni_env">
12174         <outptr>
12175           <struct>JNIEnv</struct>
12176         </outptr>
12177           <description>
12178             The JNI environment of the event (current) thread
12179           </description>
12180       </param>
12181       <param id="thread">
12182         <jthread/>
12183           <description>
12184             Thread that is popping the frame
12185           </description>
12186       </param>
12187       <param id="klass">
12188         <jclass method="method"/>
12189           <description>
12190             Class of the method being popped
12191           </description>
12192       </param>
12193       <param id="method">
12194         <jmethodID class="klass"/>
12195           <description>
12196             Method being popped
12197           </description>
12198       </param>
12199       <param id="was_popped_by_exception">
12200         <jboolean/>
12201         <description>
12202           True if frame was popped by a thrown exception.
12203           False if method exited through its return instruction.
12204         </description>
12205       </param>
12206     </parameters>
12207   </event>
12208 
12209   <event label="Method Entry"
12210          id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
12211     <description>
12212       Method entry events are generated upon entry of Java
12213       programming language methods (including native methods).
12214       <p/>
12215       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12216       identifies the initial executable location in
12217       the method.
12218       <p/>
12219       Enabling method
12220       entry or exit events will significantly degrade performance on many platforms and is thus
12221       not advised for performance critical usage (such as profiling).
12222       <internallink id="bci">Bytecode instrumentation</internallink> should be
12223       used in these cases.
12224     </description>
12225     <origin>jvmdi</origin>
12226     <capabilities>
12227       <required id="can_generate_method_entry_events"></required>
12228     </capabilities>
12229     <parameters>
12230       <param id="jni_env">
12231         <outptr>
12232           <struct>JNIEnv</struct>
12233         </outptr>
12234           <description>
12235             The JNI environment of the event (current) thread
12236           </description>
12237       </param>
12238       <param id="thread">
12239         <jthread/>
12240           <description>
12241             Thread entering the method
12242           </description>
12243       </param>
12244       <param id="klass">
12245         <jclass method="method"/>
12246           <description>
12247             Class of the method being entered
12248           </description>
12249       </param>
12250       <param id="method">
12251         <jmethodID class="klass"/>
12252           <description>
12253             Method being entered
12254           </description>
12255       </param>
12256     </parameters>
12257   </event>
12258 
12259   <event label="Method Exit"
12260          id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
12261     <description>
12262       Method exit events are generated upon exit from Java
12263       programming language methods (including native methods).
12264       This is true whether termination is caused by
12265       executing its return instruction
12266       or by throwing an exception to its caller
12267       (see <paramlink id="was_popped_by_exception"></paramlink>).
12268       <p/>
12269       The <code>method</code> field uniquely identifies the
12270       method being entered or exited. The <code>frame</code> field provides
12271       access to the stack frame for the method.
12272       <p/>
12273       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12274       identifies the executable location in the returning method
12275       immediately prior to the return.
12276       <p/>
12277         Enabling method
12278         entry or exit events will significantly degrade performance on many platforms and is thus
12279         not advised for performance critical usage (such as profiling).
12280         <internallink id="bci">Bytecode instrumentation</internallink> should be
12281         used in these cases.
12282     </description>
12283     <origin>jvmdi</origin>
12284     <capabilities>
12285       <required id="can_generate_method_exit_events"></required>
12286     </capabilities>
12287     <parameters>
12288       <param id="jni_env">
12289         <outptr>
12290           <struct>JNIEnv</struct>
12291         </outptr>
12292           <description>
12293             The JNI environment of the event (current) thread
12294           </description>
12295       </param>
12296       <param id="thread">
12297         <jthread/>
12298           <description>
12299             Thread exiting the method
12300           </description>
12301       </param>
12302       <param id="klass">
12303         <jclass method="method"/>
12304           <description>
12305             Class of the method being exited
12306           </description>
12307       </param>
12308       <param id="method">
12309         <jmethodID class="klass"/>
12310           <description>
12311             Method being exited
12312           </description>
12313       </param>
12314       <param id="was_popped_by_exception">
12315         <jboolean/>
12316         <description>
12317           True if frame was popped by a thrown exception.
12318           False if method exited through its return instruction.
12319         </description>
12320       </param>
12321       <param id="return_value">
12322         <jvalue/>
12323         <description>
12324           The return value of the method being exited.
12325           Undefined and should not be used if
12326           <paramlink id="was_popped_by_exception"></paramlink>
12327           is true.
12328         </description>
12329       </param>
12330     </parameters>
12331   </event>
12332 
12333   <event label="Native Method Bind" phase="any"
12334          id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
12335     <description>
12336       A Native Method Bind event is sent when a VM binds a
12337       Java programming language native method
12338       to the address of a function that implements the native method.
12339       This will occur when the native method is called for the first time
12340       and also occurs when the JNI function <code>RegisterNatives</code> is called.
12341       This event allows the bind to be redirected to an agent-specified
12342       proxy function.
12343       This event is not sent when the native method is unbound.
12344       Typically, this proxy function will need to be specific to a
12345       particular method or, to handle the general case, automatically
12346       generated assembly code, since after instrumentation code is
12347       executed the function at the original binding
12348       address will usually be invoked.
12349       The original binding can be restored or the redirection changed
12350       by use of the JNI function <code>RegisterNatives</code>.
12351       Some events may be sent during the primordial phase, JNI and
12352       most of <jvmti/> cannot be used at this time but the method and
12353       address can be saved for use later.
12354     </description>
12355     <origin>new</origin>
12356     <capabilities>
12357       <required id="can_generate_native_method_bind_events"></required>
12358     </capabilities>
12359     <parameters>
12360       <param id="jni_env">
12361         <outptr>
12362           <struct>JNIEnv</struct>
12363         </outptr>
12364           <description>
12365             The JNI environment of the event (current) thread
12366             Will be <code>NULL</code> if sent during the primordial
12367             <functionlink id="GetPhase">phase</functionlink>.
12368           </description>
12369       </param>
12370       <param id="thread">
12371         <jthread/>
12372           <description>
12373             Thread requesting the bind
12374           </description>
12375       </param>
12376       <param id="klass">
12377         <jclass method="method"/>
12378           <description>
12379             Class of the method being bound
12380           </description>
12381       </param>
12382       <param id="method">
12383         <jmethodID class="klass"/>
12384           <description>
12385             Native method being bound
12386           </description>
12387       </param>
12388       <param id="address">
12389         <outptr><void/></outptr>
12390         <description>
12391           The address the VM is about to bind to--that is, the
12392           address of the implementation of the native method
12393         </description>
12394       </param>
12395       <param id="new_address_ptr">
12396         <agentbuf><void/></agentbuf>
12397         <description>
12398           if the referenced address is changed (that is, if
12399           <code>*new_address_ptr</code> is set), the binding
12400           will instead be made to the supplied address.
12401         </description>
12402       </param>
12403     </parameters>
12404   </event>
12405 
12406   <event label="Exception"
12407          id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
12408     <description>
12409       Exception events are generated whenever an exception is first detected
12410       in a Java programming language method.
12411       Where "exception" means any <code>java.lang.Throwable</code>.
12412       The exception may have been thrown by a Java programming language or native
12413       method, but in the case of native methods, the event is not generated
12414       until the exception is first seen by a Java programming language method. If an exception is
12415       set and cleared in a native method (and thus is never visible to Java programming language code),
12416       no exception event is generated.
12417       <p/>
12418       The <code>method</code> and <code>location</code>
12419       parameters  uniquely identify the current location
12420       (where the exception was detected) and allow
12421       the mapping to source file and line number when that information is
12422       available. The <code>exception</code> field identifies the thrown
12423       exception object. The <code>catch_method</code>
12424       and <code>catch_location</code> identify the location of the catch clause,
12425       if any, that handles the thrown exception. If there is no such catch clause,
12426       each field is set to 0. There is no guarantee that the thread will ever
12427       reach this catch clause. If there are native methods on the call stack
12428       between the throw location and the catch clause, the exception may
12429       be reset by one of those native methods.
12430       Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
12431       et al. set to 0) may in fact be caught by native code.
12432       Agents can check for these occurrences by monitoring
12433       <eventlink id="ExceptionCatch"></eventlink> events.
12434       Note that finally clauses are implemented as catch and re-throw. Therefore they
12435       will be reported in the catch location.
12436     </description>
12437     <origin>jvmdi</origin>
12438     <capabilities>
12439       <required id="can_generate_exception_events"></required>
12440     </capabilities>
12441     <parameters>
12442       <param id="jni_env">
12443         <outptr>
12444           <struct>JNIEnv</struct>
12445         </outptr>
12446           <description>
12447             The JNI environment of the event (current) thread
12448           </description>
12449       </param>
12450       <param id="thread">
12451         <jthread/>
12452           <description>
12453             Thread generating the exception
12454           </description>
12455       </param>
12456       <param id="klass">
12457         <jclass method="method"/>
12458           <description>
12459             Class generating the exception
12460           </description>
12461       </param>
12462       <param id="method">
12463         <jmethodID class="klass"/>
12464           <description>
12465             Method generating the exception
12466           </description>
12467       </param>
12468       <param id="location">
12469         <jlocation/>
12470         <description>
12471           Location where exception occurred
12472         </description>
12473       </param>
12474       <param id="exception">
12475         <jobject/>
12476           <description>
12477             The exception being thrown
12478           </description>
12479       </param>
12480       <param id="catch_klass">
12481         <jclass method="catch_method"/>
12482           <description>
12483             Class that will catch the exception, or <code>NULL</code> if no known catch
12484           </description>
12485       </param>
12486       <param id="catch_method">
12487         <jmethodID class="catch_klass"/>
12488           <description>
12489             Method that will catch the exception, or <code>NULL</code> if no known catch
12490           </description>
12491       </param>
12492       <param id="catch_location">
12493         <jlocation/>
12494         <description>
12495           location which will catch the exception or zero if no known catch
12496         </description>
12497       </param>
12498     </parameters>
12499   </event>
12500 
12501   <event label="Exception Catch"
12502          id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
12503     <description>
12504       Exception catch events are generated whenever a thrown exception is caught.
12505       Where "exception" means any <code>java.lang.Throwable</code>.
12506       If the exception is caught in a Java programming language method, the event is generated
12507       when the catch clause is reached. If the exception is caught in a native
12508       method, the event is generated as soon as control is returned to a Java programming language
12509       method. Exception catch events are generated for any exception for which
12510       a throw was detected in a Java programming language method.
12511       Note that finally clauses are implemented as catch and re-throw. Therefore they
12512       will generate exception catch events.
12513       <p/>
12514       The <code>method</code> and <code>location</code>
12515       parameters uniquely identify the current location
12516       and allow the mapping to source file and line number when that information is
12517       available. For exceptions caught in a Java programming language method, the
12518       <code>exception</code> object identifies the exception object. Exceptions
12519       caught in native methods are not necessarily available by the time the
12520       exception catch is reported, so the <code>exception</code> field is set
12521       to <code>NULL</code>.
12522     </description>
12523     <origin>jvmdi</origin>
12524     <capabilities>
12525       <required id="can_generate_exception_events"></required>
12526     </capabilities>
12527     <parameters>
12528       <param id="jni_env">
12529         <outptr>
12530           <struct>JNIEnv</struct>
12531         </outptr>
12532           <description>
12533             The JNI environment of the event (current) thread
12534           </description>
12535       </param>
12536       <param id="thread">
12537         <jthread/>
12538           <description>
12539             Thread catching the exception
12540           </description>
12541       </param>
12542       <param id="klass">
12543         <jclass method="method"/>
12544           <description>
12545             Class catching the exception
12546           </description>
12547       </param>
12548       <param id="method">
12549         <jmethodID class="klass"/>
12550           <description>
12551             Method catching the exception
12552           </description>
12553       </param>
12554       <param id="location">
12555         <jlocation/>
12556         <description>
12557           Location where exception is being caught
12558         </description>
12559       </param>
12560       <param id="exception">
12561         <jobject/>
12562           <description>
12563             Exception being caught
12564           </description>
12565       </param>
12566     </parameters>
12567   </event>
12568 
12569   <event label="Thread Start"
12570          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12571     <description>
12572       Thread start events are generated by a new thread before its initial
12573       method executes.
12574       <p/>
12575       A thread may be listed in the array returned by
12576       <functionlink id="GetAllThreads"></functionlink>
12577       before its thread start event is generated.
12578       It is possible for other events to be generated
12579       on a thread before its thread start event.
12580       <p/>
12581       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12582     </description>
12583     <origin>jvmdi</origin>
12584     <capabilities>
12585     </capabilities>
12586     <parameters>
12587       <param id="jni_env">
12588         <outptr>
12589           <struct>JNIEnv</struct>
12590         </outptr>
12591           <description>
12592             The JNI environment of the event (current) thread.
12593           </description>
12594       </param>
12595       <param id="thread">
12596         <jthread/>
12597           <description>
12598             Thread starting
12599           </description>
12600       </param>
12601     </parameters>
12602   </event>
12603 
12604   <event label="Thread End"
12605          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start">
12606     <description>
12607       Thread end events are generated by a terminating thread
12608       after its initial method has finished execution.
12609       <p/>
12610       A thread may be listed in the array returned by
12611       <functionlink id="GetAllThreads"></functionlink>
12612       after its thread end event is generated.
12613       No events are generated on a thread
12614       after its thread end event.
12615       <p/>
12616       The event is sent on the dying <paramlink id="thread"></paramlink>.
12617     </description>
12618     <origin>jvmdi</origin>
12619     <capabilities>
12620     </capabilities>
12621     <parameters>
12622       <param id="jni_env">
12623         <outptr>
12624           <struct>JNIEnv</struct>
12625         </outptr>
12626           <description>
12627             The JNI environment of the event (current) thread.
12628           </description>
12629       </param>
12630       <param id="thread">
12631         <jthread/>
12632           <description>
12633             Thread ending
12634           </description>
12635       </param>
12636     </parameters>
12637   </event>
12638 
12639   <event label="Class Load"
12640          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
12641     <description>
12642       A class load event is generated when a class is first loaded. The order
12643       of class load events generated by a particular thread are guaranteed
12644       to match the order of class loading within that thread.
12645       Array class creation does not generate a class load event.
12646       The creation of a primitive class (for example, java.lang.Integer.TYPE)
12647       does not generate a class load event.
12648       <p/>
12649       This event is sent at an early stage in loading the class. As
12650       a result the class should be used carefully.  Note, for example,
12651       that methods and fields are not yet loaded, so queries for methods,
12652       fields, subclasses, and so on will not give correct results.
12653       See "Loading of Classes and Interfaces" in the <i>Java Language
12654       Specification</i>.  For most
12655       purposes the <eventlink id="ClassPrepare"></eventlink> event will
12656       be more useful.
12657     </description>
12658     <origin>jvmdi</origin>
12659     <capabilities>
12660     </capabilities>
12661     <parameters>
12662       <param id="jni_env">
12663         <outptr>
12664           <struct>JNIEnv</struct>
12665         </outptr>
12666           <description>
12667             The JNI environment of the event (current) thread
12668           </description>
12669       </param>
12670       <param id="thread">
12671         <jthread/>
12672           <description>
12673             Thread loading the class
12674           </description>
12675       </param>
12676       <param id="klass">
12677         <jclass/>
12678           <description>
12679             Class being loaded
12680           </description>
12681       </param>
12682     </parameters>
12683   </event>
12684 
12685   <elide>
12686   <event label="Class Unload"
12687          id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
12688     <description>
12689       A class unload event is generated when the class is about to be unloaded.
12690       Class unload events take place during garbage collection and must be
12691       handled extremely carefully. The garbage collector holds many locks
12692       and has suspended all other threads, so the event handler cannot depend
12693       on the ability to acquire any locks. The class unload event handler should
12694       do as little as possible, perhaps by queuing information to be processed
12695       later.  In particular, the <code>jclass</code> should be used only in
12696       the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
12697       <ul>
12698         <li><functionlink id="GetClassSignature"></functionlink></li>
12699         <li><functionlink id="GetSourceFileName"></functionlink></li>
12700         <li><functionlink id="IsInterface"></functionlink></li>
12701         <li><functionlink id="IsArrayClass"></functionlink></li>
12702       </ul>
12703     </description>
12704     <origin>jvmdi</origin>
12705     <capabilities>
12706     </capabilities>
12707     <parameters>
12708       <param id="jni_env">
12709         <outptr>
12710           <struct>JNIEnv</struct>
12711         </outptr>
12712           <description>
12713             The JNI environment of the event (current) thread
12714           </description>
12715       </param>
12716       <param id="thread">
12717         <jthread/>
12718           <description>
12719             Thread generating the class unload
12720           </description>
12721       </param>
12722       <param id="klass">
12723         <jclass/>
12724           <description>
12725             Class being unloaded
12726           </description>
12727       </param>
12728     </parameters>
12729   </event>
12730   </elide>
12731 
12732   <event label="Class Prepare"
12733          id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
12734     <description>
12735       A class prepare event is generated when class preparation is complete.
12736       At this point, class fields, methods, and implemented interfaces are
12737       available, and no code from the class has been executed. Since array
12738       classes never have fields or methods, class prepare events are not
12739       generated for them. Class prepare events are not generated for
12740       primitive classes (for example, <code>java.lang.Integer.TYPE</code>).
12741     </description>
12742     <origin>jvmdi</origin>
12743     <capabilities>
12744     </capabilities>
12745     <parameters>
12746       <param id="jni_env">
12747         <outptr>
12748           <struct>JNIEnv</struct>
12749         </outptr>
12750           <description>
12751             The JNI environment of the event (current) thread
12752           </description>
12753       </param>
12754       <param id="thread">
12755         <jthread/>
12756           <description>
12757             Thread generating the class prepare
12758           </description>
12759       </param>
12760       <param id="klass">
12761         <jclass/>
12762           <description>
12763             Class being prepared
12764           </description>
12765       </param>
12766     </parameters>
12767   </event>
12768 
12769   <event label="Class File Load Hook" phase="any"
12770          id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
12771     <description>
12772       This event is sent when the VM obtains class file data,
12773       but before it constructs
12774       the in-memory representation for that class.
12775       This event is also sent when the class is being modified by the
12776       <functionlink id="RetransformClasses"/> function or
12777       the <functionlink id="RedefineClasses"/> function,
12778       called in any <jvmti/> environment.
12779       The agent can instrument
12780       the existing class file data sent by the VM to include profiling/debugging hooks.
12781       See the description of
12782       <internallink id="bci">bytecode instrumentation</internallink>
12783       for usage information.
12784       <p/>
12785     When the capabilities
12786     <internallink id="jvmtiCapabilities.can_generate_early_class_hook_events">
12787     <code>can_generate_early_class_hook_events</code></internallink> and
12788     <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
12789     <code>can_generate_all_class_hook_events</code></internallink>
12790     are enabled then this event may be sent in the primordial phase.
12791     Otherwise, this event may be sent before the VM is initialized (the start
12792     <functionlink id="GetPhase">phase</functionlink>).
12793     Some classes might not be compatible
12794     with the function (eg. ROMized classes or implementation defined classes) and this event will
12795     not be generated for these classes.
12796     <p/>
12797     The agent must allocate the space for the modified
12798     class file data buffer
12799     using the memory allocation function
12800     <functionlink id="Allocate"></functionlink> because the
12801     VM is responsible for freeing the new class file data buffer
12802     using <functionlink id="Deallocate"></functionlink>.
12803     <p/>
12804     If the agent wishes to modify the class file, it must set
12805     <code>new_class_data</code> to point
12806     to the newly instrumented class file data buffer and set
12807     <code>new_class_data_len</code> to the length of that
12808     buffer before returning
12809     from this call.  If no modification is desired, the agent simply
12810     does not set <code>new_class_data</code>.  If multiple agents
12811     have enabled this event the results are chained. That is, if
12812     <code>new_class_data</code> has been set, it becomes the
12813     <code>class_data</code> for the next agent.
12814     <p/>
12815     When handling a class load in the live phase, then the
12816     <functionlink id="GetNamedModule"></functionlink>
12817     function can be used to map class loader and a package name to a module.
12818     When a class is being redefined or retransformed then
12819     <code>class_being_redefined</code> is non <code>NULL</code> and so
12820     the JNI <code>GetModule</code> function can also be used
12821     to obtain the Module.
12822     <p/>
12823     The order that this event is sent to each environment differs
12824     from other events.
12825     This event is sent to environments in the following order:
12826     <ul>
12827       <li><fieldlink id="can_retransform_classes"
12828                      struct="jvmtiCapabilities">retransformation
12829                                                 incapable</fieldlink>
12830           environments, in the
12831           order in which they were created
12832       </li>
12833       <li><fieldlink id="can_retransform_classes"
12834                      struct="jvmtiCapabilities">retransformation
12835                                                 capable</fieldlink>
12836           environments, in the
12837           order in which they were created
12838       </li>
12839     </ul>
12840     When triggered by <functionlink id="RetransformClasses"/>,
12841     this event is sent only to <fieldlink id="can_retransform_classes"
12842                      struct="jvmtiCapabilities">retransformation
12843                                                 capable</fieldlink>
12844     environments.
12845   </description>
12846   <origin>jvmpi</origin>
12847     <capabilities>
12848       <capability id="can_generate_all_class_hook_events"></capability>
12849       <capability id="can_generate_early_class_hook_events"></capability>
12850     </capabilities>
12851     <parameters>
12852       <param id="jni_env">
12853         <outptr>
12854           <struct>JNIEnv</struct>
12855         </outptr>
12856           <description>
12857             The JNI environment of the event (current) thread.
12858           </description>
12859       </param>
12860       <param id="class_being_redefined">
12861         <jclass/>
12862         <description>
12863           The class being
12864           <functionlink id="RedefineClasses">redefined</functionlink> or
12865           <functionlink id="RetransformClasses">retransformed</functionlink>.
12866           <code>NULL</code> if sent by class load.
12867         </description>
12868       </param>
12869       <param id="loader">
12870         <jobject/>
12871           <description>
12872             The class loader loading the class.
12873             <code>NULL</code> if the bootstrap class loader.
12874           </description>
12875       </param>
12876       <param id="name">
12877         <vmbuf><char/></vmbuf>
12878         <description>
12879             Name of class being loaded as a VM internal qualified name
12880             (for example, "java/util/List"), encoded as a
12881             <internallink id="mUTF">modified UTF-8</internallink> string.
12882             Note: if the class is defined with a <code>NULL</code> name or
12883             without a name specified, <code>name</code> will be <code>NULL</code>.
12884         </description>
12885       </param>
12886       <param id="protection_domain">
12887         <jobject/>
12888         <description>
12889           The <code>ProtectionDomain</code> of the class.
12890         </description>
12891       </param>
12892       <param id="class_data_len">
12893         <jint/>
12894         <description>
12895           Length of current class file data buffer.
12896         </description>
12897       </param>
12898       <param id="class_data">
12899         <vmbuf><uchar/></vmbuf>
12900         <description>
12901           Pointer to the current class file data buffer.
12902         </description>
12903       </param>
12904       <param id="new_class_data_len">
12905         <outptr><jint/></outptr>
12906         <description>
12907           Pointer to the length of the new class file data buffer.
12908         </description>
12909       </param>
12910       <param id="new_class_data">
12911         <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
12912         <description>
12913           Pointer to the pointer to the instrumented class file data buffer.
12914         </description>
12915       </param>
12916     </parameters>
12917   </event>
12918 
12919   <event label="VM Start Event"
12920          id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
12921     <description>
12922       The VM start event signals the start of the VM.
12923       At this time JNI is live but the VM is not yet fully initialized.
12924       Once this event is generated, the agent is free to call any JNI function.
12925       This event signals the beginning of the start phase,
12926       <jvmti/> functions permitted in the start phase may be called.
12927       <p/>
12928       The timing of this event may depend on whether the agent has added the
12929       <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
12930       <code>can_generate_early_vmstart</code></internallink> capability or not.
12931       If the capability has been added then the VM posts the event as early
12932       as possible. The VM is capable of executing bytecode but it may not have
12933       initialized to the point where it can load classes in modules other than
12934       <code>java.base</code>, or even arbitrary classes in <code>java.base</code>.
12935       Agents that do load-time instrumentation in this
12936       phase must take great care when instrumenting code that potentially
12937       executes in this phase. Extreme care should also be taken with JNI
12938       <code>FindClass</code> as it may not be possible to load classes and attempts
12939       to do so may result in unpredictable behavior, maybe even stability issues
12940       on some VM implementations.
12941       If the capability has not been added then the VM delays posting this
12942       event until it is capable of loading classes in modules other than
12943       <code>java.base</code> or the VM has completed its initialization.
12944       Agents that create more than one JVM TI environment, where the
12945       capability is added to some but not all environments, may observe the
12946       start phase beginning earlier in the JVM TI environments that possess
12947       the capabilty.
12948       <p/>
12949       In the case of VM start-up failure, this event will not be sent.
12950     </description>
12951     <origin>jvmdi</origin>
12952     <capabilities>
12953     </capabilities>
12954     <parameters>
12955       <param id="jni_env">
12956         <outptr>
12957           <struct>JNIEnv</struct>
12958         </outptr>
12959           <description>
12960             The JNI environment of the event (current) thread.
12961           </description>
12962       </param>
12963     </parameters>
12964   </event>
12965 
12966   <event label="VM Initialization Event"
12967          id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
12968     <description>
12969       The VM initialization event signals the completion of VM initialization. Once
12970       this event is generated, the agent is free to call any JNI or <jvmti/>
12971       function. The VM initialization event can be preceded by or can be concurrent
12972       with other events, but
12973       the preceding events should be handled carefully, if at all, because the
12974       VM has not completed its initialization. The thread start event for the
12975       main application thread is guaranteed not to occur until after the
12976       handler for the VM initialization event returns.
12977       <p/>
12978       In the case of VM start-up failure, this event will not be sent.
12979     </description>
12980     <origin>jvmdi</origin>
12981     <capabilities>
12982     </capabilities>
12983     <parameters>
12984       <param id="jni_env">
12985         <outptr>
12986           <struct>JNIEnv</struct>
12987         </outptr>
12988           <description>
12989             The JNI environment of the event (current) thread.
12990           </description>
12991       </param>
12992       <param id="thread">
12993         <jthread/>
12994           <description>
12995             The initial thread
12996           </description>
12997       </param>
12998     </parameters>
12999   </event>
13000 
13001   <event label="VM Death Event"
13002          id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
13003     <description>
13004       The VM death event notifies the agent of the termination of the VM.
13005       No events will occur after the VMDeath event.
13006       <p/>
13007       In the case of VM start-up failure, this event will not be sent.
13008       Note that <internallink id="onunload">Agent_OnUnload</internallink>
13009       will still be called in these cases.
13010     </description>
13011     <origin>jvmdi</origin>
13012     <capabilities>
13013     </capabilities>
13014     <parameters>
13015       <param id="jni_env">
13016         <outptr>
13017           <struct>JNIEnv</struct>
13018         </outptr>
13019           <description>
13020             The JNI environment of the event (current) thread
13021           </description>
13022       </param>
13023     </parameters>
13024   </event>
13025 
13026   <event label="Compiled Method Load" phase="start"
13027          id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
13028     <description>
13029       Sent when a method is compiled and loaded into memory by the VM.
13030       If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
13031       If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
13032       followed by a new <code>CompiledMethodLoad</code> event.
13033       Note that a single method may have multiple compiled forms, and that
13034       this event will be sent for each form.
13035       Note also that several methods may be inlined into a single
13036       address range, and that this event will be sent for each method.
13037       <p/>
13038       These events can be sent after their initial occurrence with
13039       <functionlink id="GenerateEvents"></functionlink>.
13040     </description>
13041     <origin>jvmpi</origin>
13042     <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
13043       <field id="start_address">
13044         <vmbuf><void/></vmbuf>
13045         <description>
13046           Starting native address of code corresponding to a location
13047         </description>
13048       </field>
13049       <field id="location">
13050         <jlocation/>
13051         <description>
13052           Corresponding location. See
13053           <functionlink id="GetJLocationFormat"></functionlink>
13054           for the meaning of location.
13055         </description>
13056       </field>
13057     </typedef>
13058     <capabilities>
13059       <required id="can_generate_compiled_method_load_events"></required>
13060     </capabilities>
13061     <parameters>
13062       <param id="klass">
13063         <jclass method="method"/>
13064           <description>
13065             Class of the method being compiled and loaded
13066           </description>
13067       </param>
13068       <param id="method">
13069         <jmethodID class="klass"/>
13070           <description>
13071             Method being compiled and loaded
13072           </description>
13073       </param>
13074       <param id="code_size">
13075         <jint/>
13076         <description>
13077           Size of compiled code
13078         </description>
13079       </param>
13080       <param id="code_addr">
13081         <vmbuf><void/></vmbuf>
13082         <description>
13083           Address where compiled method code is loaded
13084         </description>
13085       </param>
13086       <param id="map_length">
13087         <jint/>
13088         <description>
13089           Number of <typelink id="jvmtiAddrLocationMap"></typelink>
13090           entries in the address map.
13091           Zero if mapping information cannot be supplied.
13092         </description>
13093       </param>
13094       <param id="map">
13095         <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
13096         <description>
13097           Map from native addresses to location.
13098           The native address range of each entry is from
13099           <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
13100           to <code>start_address-1</code> of the next entry.
13101           <code>NULL</code> if mapping information cannot be supplied.
13102         </description>
13103       </param>
13104       <param id="compile_info">
13105         <vmbuf><void/></vmbuf>
13106         <description>
13107           VM-specific compilation information.
13108           The referenced compile information is managed by the VM
13109           and must not depend on the agent for collection.
13110           A VM implementation defines the content and lifetime
13111           of the information.
13112         </description>
13113       </param>
13114     </parameters>
13115   </event>
13116 
13117   <event label="Compiled Method Unload" phase="start"
13118          id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
13119     <description>
13120       Sent when a compiled method is unloaded from memory.
13121       This event might not be sent on the thread which performed the unload.
13122       This event may be sent sometime after the unload occurs, but
13123       will be sent before the memory is reused
13124       by a newly generated compiled method. This event may be sent after
13125       the class is unloaded.
13126     </description>
13127     <origin>jvmpi</origin>
13128     <capabilities>
13129       <required id="can_generate_compiled_method_load_events"></required>
13130     </capabilities>
13131     <parameters>
13132       <param id="klass">
13133         <jclass method="method"/>
13134           <description>
13135             Class of the compiled method being unloaded.
13136           </description>
13137       </param>
13138       <param id="method">
13139         <jmethodID class="klass"/>
13140           <description>
13141             Compiled method being unloaded.
13142             For identification of the compiled method only -- the class
13143             may be unloaded and therefore the method should not be used
13144             as an argument to further JNI or <jvmti/> functions.
13145           </description>
13146       </param>
13147       <param id="code_addr">
13148         <vmbuf><void/></vmbuf>
13149         <description>
13150           Address where compiled method code was loaded.
13151           For identification of the compiled method only --
13152           the space may have been reclaimed.
13153         </description>
13154       </param>
13155     </parameters>
13156   </event>
13157 
13158   <event label="Dynamic Code Generated" phase="any"
13159          id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
13160     <description>
13161       Sent when a component of the virtual machine is generated dynamically.
13162       This does not correspond to Java programming language code that is
13163       compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
13164       This is for native code--for example, an interpreter that is generated
13165       differently depending on command-line options.
13166       <p/>
13167       Note that this event has no controlling capability.
13168       If a VM cannot generate these events, it simply does not send any.
13169       <p/>
13170       These events can be sent after their initial occurrence with
13171       <functionlink id="GenerateEvents"></functionlink>.
13172     </description>
13173     <origin>jvmpi</origin>
13174     <capabilities>
13175     </capabilities>
13176     <parameters>
13177       <param id="name">
13178         <vmbuf><char/></vmbuf>
13179         <description>
13180           Name of the code, encoded as a
13181           <internallink id="mUTF">modified UTF-8</internallink> string.
13182           Intended for display to an end-user.
13183           The name might not be unique.
13184         </description>
13185       </param>
13186       <param id="address">
13187         <vmbuf><void/></vmbuf>
13188         <description>
13189           Native address of the code
13190         </description>
13191       </param>
13192       <param id="length">
13193         <jint/>
13194         <description>
13195           Length in bytes of the code
13196         </description>
13197       </param>
13198     </parameters>
13199   </event>
13200 
13201   <event label="Data Dump Request"
13202          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
13203     <description>
13204       Sent by the VM to request the agent to dump its data.  This
13205       is just a hint and the agent need not react to this event.
13206       This is useful for processing command-line signals from users.  For
13207       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris
13208       causes the VM to send this event to the agent.
13209     </description>
13210     <origin>jvmpi</origin>
13211     <capabilities>
13212     </capabilities>
13213     <parameters>
13214     </parameters>
13215   </event>
13216 
13217   <event label="Monitor Contended Enter"
13218          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
13219     <description>
13220       Sent when a thread is attempting to enter a Java programming language
13221       monitor already acquired by another thread.
13222     </description>
13223     <origin>jvmpi</origin>
13224     <capabilities>
13225       <required id="can_generate_monitor_events"></required>
13226     </capabilities>
13227     <parameters>
13228       <param id="jni_env">
13229         <outptr>
13230           <struct>JNIEnv</struct>
13231         </outptr>
13232           <description>
13233             The JNI environment of the event (current) thread
13234           </description>
13235       </param>
13236       <param id="thread">
13237         <jthread/>
13238           <description>
13239             JNI local reference to the thread
13240             attempting to enter the monitor
13241           </description>
13242       </param>
13243       <param id="object">
13244         <jobject/>
13245           <description>
13246             JNI local reference to the monitor
13247           </description>
13248       </param>
13249     </parameters>
13250   </event>
13251 
13252   <event label="Monitor Contended Entered"
13253          id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
13254     <description>
13255       Sent when a thread enters a Java programming language
13256       monitor after waiting for it to be released by another thread.
13257     </description>
13258     <origin>jvmpi</origin>
13259     <capabilities>
13260       <required id="can_generate_monitor_events"></required>
13261     </capabilities>
13262     <parameters>
13263       <param id="jni_env">
13264         <outptr>
13265           <struct>JNIEnv</struct>
13266         </outptr>
13267           <description>
13268             The JNI environment of the event (current) thread
13269           </description>
13270       </param>
13271       <param id="thread">
13272         <jthread/>
13273           <description>
13274             JNI local reference to the thread entering
13275             the monitor
13276           </description>
13277       </param>
13278       <param id="object">
13279         <jobject/>
13280           <description>
13281             JNI local reference to the monitor
13282           </description>
13283       </param>
13284     </parameters>
13285   </event>
13286 
13287   <event label="Monitor Wait"
13288          id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
13289     <description>
13290       Sent when a thread is about to wait on an object.
13291     </description>
13292     <origin>jvmpi</origin>
13293     <capabilities>
13294       <required id="can_generate_monitor_events"></required>
13295     </capabilities>
13296     <parameters>
13297       <param id="jni_env">
13298         <outptr>
13299           <struct>JNIEnv</struct>
13300         </outptr>
13301           <description>
13302             The JNI environment of the event (current) thread
13303           </description>
13304       </param>
13305       <param id="thread">
13306         <jthread/>
13307           <description>
13308             JNI local reference to the thread about to wait
13309           </description>
13310       </param>
13311       <param id="object">
13312         <jobject/>
13313           <description>
13314             JNI local reference to the monitor
13315           </description>
13316       </param>
13317       <param id="timeout">
13318         <jlong/>
13319         <description>
13320           The number of milliseconds the thread will wait
13321         </description>
13322       </param>
13323     </parameters>
13324   </event>
13325 
13326   <event label="Monitor Waited"
13327          id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
13328     <description>
13329       Sent when a thread finishes waiting on an object.
13330     </description>
13331     <origin>jvmpi</origin>
13332     <capabilities>
13333       <required id="can_generate_monitor_events"></required>
13334     </capabilities>
13335     <parameters>
13336       <param id="jni_env">
13337         <outptr>
13338           <struct>JNIEnv</struct>
13339         </outptr>
13340           <description>
13341             The JNI environment of the event (current) thread
13342           </description>
13343       </param>
13344       <param id="thread">
13345         <jthread/>
13346           <description>
13347             JNI local reference to the thread that was finished waiting
13348           </description>
13349       </param>
13350       <param id="object">
13351         <jobject/>
13352           <description>
13353             JNI local reference to the monitor.
13354           </description>
13355       </param>
13356       <param id="timed_out">
13357         <jboolean/>
13358         <description>
13359           True if the monitor timed out
13360         </description>
13361       </param>
13362     </parameters>
13363   </event>
13364 
13365   <event label="Resource Exhausted"
13366          id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
13367          since="1.1">
13368     <description>
13369       Sent when a VM resource needed by a running application has been exhausted.
13370       Except as required by the optional capabilities, the set of resources
13371       which report exhaustion is implementation dependent.
13372       <p/>
13373       The following bit flags define the properties of the resource exhaustion:
13374       <constants id="jvmtiResourceExhaustionFlags"
13375                  label="Resource Exhaustion Flags"
13376                  kind="bits"
13377                  since="1.1">
13378         <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
13379           After this event returns, the VM will throw a
13380           <code>java.lang.OutOfMemoryError</code>.
13381         </constant>
13382         <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
13383           The VM was unable to allocate memory from the <tm>Java</tm>
13384           platform <i>heap</i>.
13385           The <i>heap</i> is the runtime
13386           data area from which memory for all class instances and
13387           arrays are allocated.
13388         </constant>
13389         <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
13390           The VM was unable to create a thread.
13391         </constant>
13392       </constants>
13393     </description>
13394     <origin>new</origin>
13395     <capabilities>
13396       <capability id="can_generate_resource_exhaustion_heap_events">
13397         Can generate events when the VM is unable to allocate memory from the
13398         <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
13399       </capability>
13400       <capability id="can_generate_resource_exhaustion_threads_events">
13401         Can generate events when the VM is unable to
13402         <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
13403         a thread</internallink>.
13404       </capability>
13405     </capabilities>
13406     <parameters>
13407       <param id="jni_env">
13408         <outptr>
13409           <struct>JNIEnv</struct>
13410         </outptr>
13411           <description>
13412             The JNI environment of the event (current) thread
13413           </description>
13414       </param>
13415       <param id="flags">
13416         <jint/>
13417         <description>
13418           Flags defining the properties of the of resource exhaustion
13419           as specified by the
13420           <internallink id="jvmtiResourceExhaustionFlags">Resource
13421           Exhaustion Flags</internallink>.
13422           </description>
13423         </param>
13424       <param id="reserved">
13425         <vmbuf><void/></vmbuf>
13426         <description>
13427           Reserved.
13428         </description>
13429       </param>
13430       <param id="description">
13431         <vmbuf><char/></vmbuf>
13432         <description>
13433           Description of the resource exhaustion, encoded as a
13434           <internallink id="mUTF">modified UTF-8</internallink> string.
13435         </description>
13436       </param>
13437     </parameters>
13438   </event>
13439 
13440   <event label="VM Object Allocation"
13441          id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
13442     <description>
13443       Sent when a method causes the virtual machine to allocate an
13444       Object visible to Java programming language code and the
13445       allocation is not detectable by other intrumentation mechanisms.
13446       Generally object allocation should be detected by instrumenting
13447       the bytecodes of allocating methods.
13448       Object allocation generated in native code by JNI function
13449       calls should be detected using
13450       <internallink id="jniIntercept">JNI function interception</internallink>.
13451       Some methods might not have associated bytecodes and are not
13452       native methods, they instead are executed directly by the
13453       VM. These methods should send this event.
13454       Virtual machines which are incapable of bytecode instrumentation
13455       for some or all of their methods can send this event.
13456       <p/>
13457       Typical examples where this event might be sent:
13458       <ul>
13459         <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
13460         <li>Methods not represented by bytecodes -- for example, VM intrinsics and
13461             J2ME preloaded classes</li>
13462       </ul>
13463       Cases where this event would not be generated:
13464       <ul>
13465         <li>Allocation due to bytecodes -- for example, the <code>new</code>
13466             and <code>newarray</code> VM instructions</li>
13467         <li>Allocation due to JNI function calls -- for example,
13468             <code>AllocObject</code></li>
13469         <li>Allocations during VM initialization</li>
13470         <li>VM internal objects</li>
13471       </ul>
13472     </description>
13473     <origin>new</origin>
13474     <capabilities>
13475       <required id="can_generate_vm_object_alloc_events"></required>
13476     </capabilities>
13477     <parameters>
13478       <param id="jni_env">
13479         <outptr>
13480           <struct>JNIEnv</struct>
13481         </outptr>
13482           <description>
13483             The JNI environment of the event (current) thread
13484           </description>
13485       </param>
13486       <param id="thread">
13487         <jthread/>
13488           <description>
13489             Thread allocating the object.
13490           </description>
13491       </param>
13492       <param id="object">
13493         <jobject/>
13494           <description>
13495             JNI local reference to the object that was allocated
13496           </description>
13497       </param>
13498       <param id="object_klass">
13499         <jclass/>
13500           <description>
13501             JNI local reference to the class of the object
13502           </description>
13503       </param>
13504       <param id="size">
13505         <jlong/>
13506         <description>
13507             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13508         </description>
13509       </param>
13510     </parameters>
13511   </event>
13512 
13513   <event label="Object Free"
13514          id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13515     <description>
13516       An Object Free event is sent when the garbage collector frees an object.
13517       Events are only sent for tagged objects--see
13518       <internallink id="Heap">heap functions</internallink>.
13519       <p/>
13520       The event handler must not use JNI functions and
13521       must not use <jvmti/> functions except those which
13522       specifically allow such use (see the raw monitor, memory management,
13523       and environment local storage functions).
13524     </description>
13525     <origin>new</origin>
13526     <capabilities>
13527       <required id="can_generate_object_free_events"></required>
13528     </capabilities>
13529     <parameters>
13530       <param id="tag">
13531         <jlong/>
13532         <description>
13533           The freed object's tag
13534         </description>
13535       </param>
13536     </parameters>
13537   </event>
13538 
13539   <event label="Garbage Collection Start"
13540          id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
13541     <description>
13542       A Garbage Collection Start event is sent when a
13543       garbage collection pause begins.
13544       Only stop-the-world collections are reported--that is, collections during
13545       which all threads cease to modify the state of the Java virtual machine.
13546       This means that some collectors will never generate these events.
13547       This event is sent while the VM is still stopped, thus
13548       the event handler must not use JNI functions and
13549       must not use <jvmti/> functions except those which
13550       specifically allow such use (see the raw monitor, memory management,
13551       and environment local storage functions).
13552       <p/>
13553       This event is always sent as a matched pair with
13554       <eventlink id="GarbageCollectionFinish"/>
13555       (assuming both events are enabled) and no garbage collection
13556       events will occur between them.
13557     </description>
13558     <origin>new</origin>
13559     <capabilities>
13560       <required id="can_generate_garbage_collection_events"></required>
13561     </capabilities>
13562     <parameters>
13563     </parameters>
13564   </event>
13565 
13566   <event label="Garbage Collection Finish"
13567          id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
13568     <description>
13569       A Garbage Collection Finish event is sent when a
13570       garbage collection pause ends.
13571       This event is sent while the VM is still stopped, thus
13572       the event handler must not use JNI functions and
13573       must not use <jvmti/> functions except those which
13574       specifically allow such use (see the raw monitor, memory management,
13575       and environment local storage functions).
13576       <p/>
13577       Some agents may need to do post garbage collection operations that
13578       require the use of the disallowed <jvmti/> or JNI functions. For these
13579       cases an agent thread can be created which waits on a raw monitor,
13580       and the handler for the Garbage Collection Finish event simply
13581       notifies the raw monitor
13582       <p/>
13583       This event is always sent as a matched pair with
13584       <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
13585       <issue>
13586         The most important use of this event is to provide timing information,
13587         and thus additional information is not required.  However,
13588         information about the collection which is "free" should be included -
13589         what that information is needs to be determined.
13590       </issue>
13591     </description>
13592     <origin>new</origin>
13593     <capabilities>
13594       <required id="can_generate_garbage_collection_events"></required>
13595     </capabilities>
13596     <parameters>
13597     </parameters>
13598   </event>
13599 
13600   <elide>
13601   <event label="Verbose Output" phase="any"
13602          id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
13603     <description>
13604       Send verbose messages as strings.
13605         <issue>
13606           This format is extremely fragile, as it can change with each
13607           platform, collector and version.  Alternatives include:
13608           <ul>
13609             <li>building off Java programming language M and M APIs</li>
13610             <li>XML</li>
13611             <li>key/value pairs</li>
13612             <li>removing it</li>
13613           </ul>
13614         </issue>
13615         <issue>
13616           Though this seemed trivial to implement.
13617           In the RI it appears this will be quite complex.
13618         </issue>
13619     </description>
13620     <origin>new</origin>
13621     <capabilities>
13622     </capabilities>
13623     <parameters>
13624       <param id="flag">
13625         <enum>jvmtiVerboseFlag</enum>
13626         <description>
13627           Which verbose output is being sent.
13628         </description>
13629       </param>
13630       <param id="message">
13631         <vmbuf><char/></vmbuf>
13632         <description>
13633           Message text, encoded as a
13634           <internallink id="mUTF">modified UTF-8</internallink> string.
13635         </description>
13636       </param>
13637     </parameters>
13638   </event>
13639   </elide>
13640 
13641 </eventsection>
13642 
13643 <datasection>
13644   <intro>
13645     <jvmti/> extends the data types defined by JNI.
13646   </intro>
13647   <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
13648     <basetype id="jboolean">
13649       <description>
13650         Holds a Java programming language <code>boolean</code>.
13651         Unsigned 8 bits.
13652       </description>
13653     </basetype>
13654     <basetype id="jchar">
13655       <description>
13656         Holds a Java programming language <code>char</code>.
13657         Unsigned 16 bits.
13658       </description>
13659     </basetype>
13660     <basetype id="jint">
13661       <description>
13662         Holds a Java programming language <code>int</code>.
13663         Signed 32 bits.
13664       </description>
13665     </basetype>
13666     <basetype id="jlong">
13667       <description>
13668         Holds a Java programming language <code>long</code>.
13669         Signed 64 bits.
13670       </description>
13671     </basetype>
13672     <basetype id="jfloat">
13673       <description>
13674         Holds a Java programming language <code>float</code>.
13675         32 bits.
13676       </description>
13677     </basetype>
13678     <basetype id="jdouble">
13679       <description>
13680         Holds a Java programming language <code>double</code>.
13681         64 bits.
13682       </description>
13683     </basetype>
13684     <basetype id="jobject">
13685       <description>
13686         Holds a Java programming language object.
13687       </description>
13688     </basetype>
13689     <basetype id="jclass">
13690       <description>
13691         Holds a Java programming language class.
13692       </description>
13693     </basetype>
13694     <basetype id="jvalue">
13695       <description>
13696         Is a union of all primitive types and <code>jobject</code>.  Thus, holds any Java
13697         programming language value.
13698       </description>
13699     </basetype>
13700     <basetype id="jfieldID">
13701       <description>
13702         Identifies a Java programming language field.
13703         <code>jfieldID</code>s returned by <jvmti/> functions and events may be
13704         safely stored.
13705       </description>
13706     </basetype>
13707     <basetype id="jmethodID">
13708       <description>
13709         Identifies a Java programming language method, initializer, or constructor.
13710         <code>jmethodID</code>s returned by <jvmti/> functions and events may be
13711         safely stored.  However, if the class is unloaded, they become invalid
13712         and must not be used.
13713       </description>
13714     </basetype>
13715     <basetype id="JNIEnv">
13716       <description>
13717         Pointer to the JNI function table.  Pointer to this (<code>JNIEnv *</code>)
13718         is a JNI environment.
13719       </description>
13720     </basetype>
13721   </basetypes>
13722 
13723   <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
13724     <basetype id="jvmtiEnv">
13725       <description>
13726         The <jvmti/> <internallink id="environments">environment</internallink> pointer.
13727         See the <internallink id="FunctionSection">Function Section</internallink>.
13728         <code>jvmtiEnv</code> points to the
13729         <internallink id="FunctionTable">function table</internallink> pointer.
13730       </description>
13731     </basetype>
13732     <basetype id="jthread">
13733       <definition>typedef jobject jthread;</definition>
13734       <description>
13735         Subtype of <datalink id="jobject"></datalink> that holds a thread.
13736       </description>
13737     </basetype>
13738     <basetype id="jthreadGroup">
13739       <definition>typedef jobject jthreadGroup;</definition>
13740       <description>
13741         Subtype of <datalink id="jobject"></datalink> that holds a thread group.
13742       </description>
13743     </basetype>
13744     <basetype id="jlocation">
13745       <definition>typedef jlong jlocation;</definition>
13746       <description>
13747         A 64 bit value, representing a monotonically increasing
13748         executable position within a method.
13749         <code>-1</code> indicates a native method.
13750         See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
13751         given VM.
13752       </description>
13753     </basetype>
13754     <basetype id="jrawMonitorID">
13755       <definition>struct _jrawMonitorID;
13756 typedef struct _jrawMonitorID *jrawMonitorID;</definition>
13757       <description>
13758         A raw monitor.
13759       </description>
13760     </basetype>
13761     <basetype id="jvmtiError">
13762       <description>
13763         Holds an error return code.
13764         See the <internallink id="ErrorSection">Error section</internallink> for possible values.
13765         <example>
13766 typedef enum {
13767     JVMTI_ERROR_NONE = 0,
13768     JVMTI_ERROR_INVALID_THREAD = 10,
13769       ...
13770 } jvmtiError;
13771 </example>
13772       </description>
13773     </basetype>
13774     <basetype id="jvmtiEvent">
13775       <description>
13776         An identifier for an event type.
13777         See the <internallink id="EventSection">Event section</internallink> for possible values.
13778         It is guaranteed that future versions of this specification will
13779         never assign zero as an event type identifier.
13780 <example>
13781 typedef enum {
13782     JVMTI_EVENT_SINGLE_STEP = 1,
13783     JVMTI_EVENT_BREAKPOINT = 2,
13784       ...
13785 } jvmtiEvent;
13786 </example>
13787       </description>
13788     </basetype>
13789     <basetype id="jvmtiEventCallbacks">
13790       <description>
13791         The callbacks used for events.
13792 <example>
13793 typedef struct {
13794     jvmtiEventVMInit VMInit;
13795     jvmtiEventVMDeath VMDeath;
13796       ...
13797 } jvmtiEventCallbacks;
13798 </example>
13799         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink>
13800         for the complete structure.
13801         <p/>
13802         Where, for example, the VM initialization callback is defined:
13803 <example>
13804 typedef void (JNICALL *jvmtiEventVMInit)
13805     (jvmtiEnv *jvmti_env,
13806      JNIEnv* jni_env,
13807      jthread thread);
13808 </example>
13809         See the individual events for the callback function definition.
13810       </description>
13811     </basetype>
13812     <basetype id="jniNativeInterface">
13813       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
13814       <description>
13815         Typedef for the JNI function table <code>JNINativeInterface</code>
13816         defined in the
13817         <externallink id="jni/functions.html#interface-function-table">
13818           JNI Specification</externallink>.
13819         The JNI reference implementation defines this with an underscore.
13820       </description>
13821     </basetype>
13822   </basetypes>
13823 
13824 </datasection>
13825 
13826 <issuessection label="Issues">
13827   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
13828     JVMDI requires that the agent suspend threads before calling
13829     certain sensitive functions.  JVMPI requires garbage collection to be
13830     disabled before calling certain sensitive functions.
13831     It was suggested that rather than have this requirement, that
13832     VM place itself in a suitable state before performing an
13833     operation.  This makes considerable sense since each VM
13834     knows its requirements and can most easily arrange a
13835     safe state.
13836     <p/>
13837     The ability to externally suspend/resume threads will, of
13838     course, remain.  The ability to enable/disable garbage collection will not.
13839     <p/>
13840     This issue is resolved--suspend will not
13841     be required.  The spec has been updated to reflect this.
13842   </intro>
13843 
13844   <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
13845     There are a variety of approaches to sampling call stacks.
13846     The biggest bifurcation is between VM controlled and agent
13847     controlled.
13848     <p/>
13849     This issue is resolved--agent controlled
13850     sampling will be the approach.
13851   </intro>
13852 
13853   <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
13854     JVMDI represents threads as jthread.  JVMPI primarily
13855     uses JNIEnv* to represent threads.
13856     <p/>
13857     The Expert Group has chosen jthread as the representation
13858     for threads in <jvmti/>.
13859     JNIEnv* is sent by
13860     events since it is needed to JNI functions.  JNIEnv, per the
13861     JNI spec, are not supposed to be used outside their thread.
13862   </intro>
13863 
13864   <intro id="design" label="Resolved Issue: Method Representation">
13865     The JNI spec allows an implementation to depend on jclass/jmethodID
13866     pairs, rather than simply a jmethodID, to reference a method.
13867     JVMDI, for consistency, choose the same representation.
13868     JVMPI, however, specifies that a jmethodID alone maps to a
13869     method.  Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
13870     pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
13871     In fact, any JVM implementation that supports JVMPI must have
13872     such a representation.
13873     <jvmti/> will use jmethodID as a unique representation of a method
13874     (no jclass is used).
13875     There should be efficiency gains, particularly in
13876     functionality like stack dumping, to this representation.
13877     <p/>
13878     Note that fields were not used in JVMPI and that the access profile
13879     of fields differs from methods--for implementation efficiency
13880     reasons, a jclass/jfieldID pair will still be needed for field
13881     reference.
13882   </intro>
13883 
13884   <intro id="localReferenceIssue" label="Resolved Issue: Local References">
13885     Functions return local references.
13886   </intro>
13887 
13888   <intro id="frameRep" label="Resolved Issue: Representation of frames">
13889     In JVMDI, a frame ID is used to represent a frame.  Problem with this
13890     is that a VM must track when a frame becomes invalid, a far better
13891     approach, and the one used in <jvmti/>, is to reference frames by depth.
13892   </intro>
13893 
13894   <intro id="requiredCapabilities" label="Issue: Required Capabilities">
13895     Currently, having a required capabilities means that the functionality
13896     is optional.   Capabilities are useful even for required functionality
13897     since they can inform the VM is needed set-up.  Thus, there should be
13898     a set of capabilities that a conformant implementation must provide
13899     (if requested during Agent_OnLoad).
13900   </intro>
13901 
13902   <intro id="taghint" label="Proposal: add tag hint function">
13903     A hint of the percentage of objects that will be tagged would
13904     help the VM pick a good implementation.
13905   </intro>
13906 
13907   <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
13908   How difficult or easy would be to extend the monitor_info category to include
13909     <pre>
13910   - current number of monitors
13911   - enumeration of monitors
13912   - enumeration of threads waiting on a given monitor
13913     </pre>
13914   The reason for my question is the fact that current get_monitor_info support
13915   requires the agent to specify a given thread to get the info which is probably
13916   OK in the profiling/debugging space, while in the monitoring space the agent
13917   could be watching the monitor list and then decide which thread to ask for
13918   the info. You might ask why is this important for monitoring .... I think it
13919   can aid in the detection/prediction of application contention caused by hot-locks.
13920   </intro>
13921 </issuessection>
13922 
13923 <changehistory id="ChangeHistory" update="09/05/07">
13924   <intro>
13925     The <jvmti/> specification is an evolving document with major, minor,
13926     and micro version numbers.
13927     A released version of the specification is uniquely identified
13928     by its major and minor version.
13929     The functions, events, and capabilities in this specification
13930     indicate a "Since" value which is the major and minor version in
13931     which it was introduced.
13932     The version of the specification implemented by the VM can
13933     be retrieved at runtime with the <functionlink id="GetVersionNumber"/>
13934     function.
13935   </intro>
13936   <change date="14 Nov 2002">
13937     Converted to XML document.
13938   </change>
13939   <change date="14 Nov 2002">
13940     Elided heap dump functions (for now) since what was there
13941     was wrong.
13942   </change>
13943   <change date="18 Nov 2002">
13944     Added detail throughout.
13945   </change>
13946   <change date="18 Nov 2002">
13947     Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
13948   </change>
13949   <change date="19 Nov 2002">
13950     Added AsyncGetStackTrace.
13951   </change>
13952   <change date="19 Nov 2002">
13953     Added jframeID return to GetStackTrace.
13954   </change>
13955   <change date="19 Nov 2002">
13956     Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
13957     since they are redundant with GetStackTrace.
13958   </change>
13959   <change date="19 Nov 2002">
13960     Elided ClearAllBreakpoints since it has always been redundant.
13961   </change>
13962   <change date="19 Nov 2002">
13963     Added GetSystemProperties.
13964   </change>
13965   <change date="19 Nov 2002">
13966     Changed the thread local storage functions to use jthread.
13967   </change>
13968   <change date="20 Nov 2002">
13969     Added GetJLocationFormat.
13970   </change>
13971   <change date="22 Nov 2002">
13972     Added events and introductory text.
13973   </change>
13974   <change date="22 Nov 2002">
13975     Cross reference type and constant definitions.
13976   </change>
13977   <change date="24 Nov 2002">
13978     Added DTD.
13979   </change>
13980   <change date="24 Nov 2002">
13981     Added capabilities function section.
13982   </change>
13983   <change date="29 Nov 2002">
13984     Assign capabilities to each function and event.
13985   </change>
13986   <change date="29 Nov 2002">
13987     Add <internallink id="jniIntercept">JNI interception functions</internallink>.
13988   </change>
13989   <change date="30 Nov 2002">
13990     Auto generate SetEventNotificationMode capabilities.
13991   </change>
13992   <change date="30 Nov 2002">
13993     Add <eventlink id="VMObjectAlloc"></eventlink> event.
13994   </change>
13995   <change date="30 Nov 2002">
13996     Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
13997   </change>
13998   <change date="30 Nov 2002">
13999     Add const to declarations.
14000   </change>
14001   <change date="30 Nov 2002">
14002     Change method exit and frame pop to send on exception.
14003   </change>
14004   <change date="1 Dec 2002">
14005     Add ForceGarbageCollection.
14006   </change>
14007   <change date="2 Dec 2002">
14008     Redo Xrun section; clarify GetStackTrace and add example;
14009     Fix width problems; use "agent" consistently.
14010   </change>
14011   <change date="8 Dec 2002">
14012     Remove previous start-up intro.
14013     Add <internallink id="environments"><jvmti/> Environments</internallink>
14014     section.
14015   </change>
14016   <change date="8 Dec 2002">
14017     Add <functionlink id="DisposeEnvironment"></functionlink>.
14018   </change>
14019   <change date="9 Dec 2002">
14020     Numerous minor updates.
14021   </change>
14022   <change date="15 Dec 2002">
14023     Add heap profiling functions added:
14024     get/set annotation, iterate live objects/heap.
14025     Add heap profiling functions place holder added:
14026     heap roots.
14027     Heap profiling event added: object free.
14028     Heap profiling event redesigned: vm object allocation.
14029     Heap profiling event placeholders added: garbage collection start/finish.
14030     Native method bind event added.
14031   </change>
14032   <change date="19 Dec 2002">
14033     Revamp suspend/resume functions.
14034     Add origin information with jvmdi tag.
14035     Misc fixes.
14036   </change>
14037   <change date="24 Dec 2002">
14038     Add semantics to types.
14039   </change>
14040   <change date="27 Dec 2002">
14041     Add local reference section.
14042     Autogenerate parameter descriptions from types.
14043   </change>
14044   <change date="28 Dec 2002">
14045     Document that RunAgentThread sends threadStart.
14046   </change>
14047   <change date="29 Dec 2002">
14048     Remove redundant local ref and dealloc warning.
14049     Convert GetRawMonitorName to allocated buffer.
14050     Add GenerateEvents.
14051   </change>
14052   <change date="30 Dec 2002">
14053     Make raw monitors a type and rename to "jrawMonitorID".
14054   </change>
14055   <change date="1 Jan 2003">
14056     Include origin information.
14057     Clean-up JVMDI issue references.
14058     Remove Deallocate warnings which are now automatically generated.
14059   </change>
14060   <change date="2 Jan 2003">
14061     Fix representation issues for jthread.
14062   </change>
14063   <change date="3 Jan 2003">
14064     Make capabilities buffered out to 64 bits - and do it automatically.
14065   </change>
14066   <change date="4 Jan 2003">
14067     Make constants which are enumeration into enum types.
14068     Parameters now of enum type.
14069     Clean-up and index type section.
14070     Replace remaining datadef entities with callback.
14071   </change>
14072   <change date="7 Jan 2003">
14073     Correct GenerateEvents description.
14074     More internal semantics work.
14075   </change>
14076   <change date="9 Jan 2003">
14077     Replace previous GetSystemProperties with two functions
14078     which use allocated information instead fixed.
14079     Add SetSystemProperty.
14080     More internal semantics work.
14081   </change>
14082   <change date="12 Jan 2003">
14083     Add varargs to end of SetEventNotificationMode.
14084   </change>
14085   <change date="20 Jan 2003">
14086     Finish fixing spec to reflect that alloc sizes are jlong.
14087   </change>
14088   <change date="22 Jan 2003">
14089     Allow NULL as RunAgentThread arg.
14090   </change>
14091   <change date="22 Jan 2003">
14092     Fixed names to standardized naming convention
14093     Removed AsyncGetStackTrace.
14094   </change>
14095   <change date="29 Jan 2003">
14096     Since we are using jthread, removed GetThread.
14097   </change>
14098   <change date="31 Jan 2003">
14099     Change GetFieldName to allow NULLs like GetMethodName.
14100   </change>
14101   <change date="29 Feb 2003" version="v40">
14102       Rewrite the introductory text, adding sections on
14103       start-up, environments and bytecode instrumentation.
14104       Change the command line arguments per EG discussions.
14105       Add an introduction to the capabilities section.
14106       Add the extension mechanism category and functions.
14107       Mark for deletion, but clarified anyhow, SuspendAllThreads.
14108       Rename IterateOverLiveObjects to IterateOverReachableObjects and
14109       change the text accordingly.
14110       Clarify IterateOverHeap.
14111       Clarify CompiledMethodLoad.
14112       Discuss prerequisite state for Calling Functions.
14113       Clarify SetAllocationHooks.
14114       Added issues ("To be resolved:") through-out.
14115       And so on...
14116   </change>
14117   <change date="6 Mar 2003" version="v41">
14118       Remove struct from the call to GetOwnedMonitorInfo.
14119       Automatically generate most error documentation, remove
14120       (rather broken) hand written error doc.
14121       Better describe capability use (empty initial set).
14122       Add min value to jint params.
14123       Remove the capability can_access_thread_local_storage.
14124       Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
14125       same for *NOT_IMPLEMENTED.
14126       Description fixes.
14127   </change>
14128   <change date="8 Mar 2003" version="v42">
14129       Rename GetClassSignature to GetClassName.
14130       Rename IterateOverClassObjects to IterateOverInstancesOfClass.
14131       Remove GetMaxStack (operand stack isn't used in <jvmti/>).
14132       Description fixes: define launch-time, remove native frame pop
14133       from PopFrame, and assorted clarifications.
14134   </change>
14135   <change date="8 Mar 2003" version="v43">
14136       Fix minor editing problem.
14137   </change>
14138   <change date="10 Mar 2003" version="v44">
14139       Add phase information.
14140       Remap (compact) event numbers.
14141   </change>
14142   <change date="11 Mar 2003" version="v45">
14143       More phase information - allow "any".
14144       Elide raw monitor queries and events.
14145       Minor description fixes.
14146   </change>
14147   <change date="12 Mar 2003" version="v46">
14148       Add GetPhase.
14149       Use "phase" through document.
14150       Elide GetRawMonitorName.
14151       Elide GetObjectMonitors.
14152   </change>
14153   <change date="12 Mar 2003" version="v47">
14154       Fixes from link, XML, and spell checking.
14155       Auto-generate the callback structure.
14156   </change>
14157   <change date="13 Mar 2003" version="v48">
14158       One character XML fix.
14159   </change>
14160   <change date="13 Mar 2003" version="v49">
14161       Change function parameter names to be consistent with
14162       event parameters (fooBarBaz becomes foo_bar_baz).
14163   </change>
14164   <change date="14 Mar 2003" version="v50">
14165       Fix broken link.  Fix thread markers.
14166   </change>
14167   <change date="14 Mar 2003" version="v51">
14168       Change constants so they are under 128 to workaround
14169       compiler problems.
14170   </change>
14171   <change date="23 Mar 2003" version="v52">
14172       Overhaul capabilities.  Separate GetStackTrace into
14173       GetStackTrace and GetStackFrames.
14174   </change>
14175   <change date="8 Apr 2003" version="v54">
14176       Use depth instead of jframeID to reference frames.
14177       Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
14178       Remove frame arg from events.
14179   </change>
14180   <change date="9 Apr 2003" version="v55">
14181       Remove GetObjectWithAnnotation since tests show bufferred approach more efficient.
14182       Add missing annotation_count to GetObjectsWithAnnotations
14183   </change>
14184   <change date="10 Apr 2003" version="v56">
14185       Remove confusing parenthetical statement in GetObjectsWithAnnotations
14186   </change>
14187   <change date="13 Apr 2003" version="v58">
14188       Replace jclass/jmethodID representation of method with simply jmethodID;
14189       Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
14190       Replace can_access_frames with can_access_local_variables; remove from purely stack access.
14191       Use can_get_synthetic_attribute; fix description.
14192       Clarify that zero length arrays must be deallocated.
14193       Clarify RelinquishCapabilities.
14194       Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
14195   </change>
14196   <change date="27 Apr 2003" version="v59">
14197       Remove lingering indirect references to OBSOLETE_METHOD_ID.
14198   </change>
14199   <change date="4 May 2003" version="v60">
14200       Allow DestroyRawMonitor during OnLoad.
14201   </change>
14202   <change date="7 May 2003" version="v61">
14203       Added not monitor owner error return to DestroyRawMonitor.
14204   </change>
14205   <change date="13 May 2003" version="v62">
14206       Clarify semantics of raw monitors.
14207       Change flags on <code>GetThreadStatus</code>.
14208       <code>GetClassLoader</code> return NULL for the bootstrap class loader.
14209       Add <code>GetClassName</code> issue.
14210       Define local variable signature.
14211       Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
14212       Remove over specification in <code>GetObjectsWithAnnotations</code>.
14213       Elide <code>SetAllocationHooks</code>.
14214       Elide <code>SuspendAllThreads</code>.
14215   </change>
14216   <change date="14 May 2003" version="v63">
14217       Define the data type <code>jvmtiEventCallbacks</code>.
14218       Zero length allocations return NULL.
14219       Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.
14220       Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
14221   </change>
14222   <change date="15 May 2003" version="v64">
14223       Better wording, per review.
14224   </change>
14225   <change date="15 May 2003" version="v65">
14226       First Alpha.
14227       Make jmethodID and jfieldID unique, jclass not used.
14228   </change>
14229   <change date="27 May 2003" version="v66">
14230       Fix minor XSLT errors.
14231   </change>
14232   <change date="13 June 2003" version="v67">
14233       Undo making jfieldID unique (jmethodID still is).
14234   </change>
14235   <change date="17 June 2003" version="v68">
14236       Changes per June 11th Expert Group meeting --
14237       Overhaul Heap functionality: single callback,
14238       remove GetHeapRoots, add reachable iterators,
14239       and rename "annotation" to "tag".
14240       NULL thread parameter on most functions is current
14241       thread.
14242       Add timers.
14243       Remove ForceExit.
14244       Add GetEnvironmentLocalStorage.
14245       Add verbose flag and event.
14246       Add AddToBootstrapClassLoaderSearch.
14247       Update ClassFileLoadHook.
14248   </change>
14249   <change date="18 June 2003" version="v69">
14250       Clean up issues sections.
14251       Rename GetClassName back to GetClassSignature and
14252       fix description.
14253       Add generic signature to GetClassSignature,
14254       GetFieldSignature, GetMethodSignature, and
14255       GetLocalVariableTable.
14256       Elide EstimateCostOfCapabilities.
14257       Clarify that the system property functions operate
14258       on the VM view of system properties.
14259       Clarify Agent_OnLoad.
14260       Remove "const" from JNIEnv* in events.
14261       Add metadata accessors.
14262   </change>
14263   <change date="18 June 2003" version="v70">
14264       Add start_depth to GetStackTrace.
14265       Move system properties to a new category.
14266       Add GetObjectSize.
14267       Remove "X" from command line flags.
14268       XML, HTML, and spell check corrections.
14269   </change>
14270   <change date="19 June 2003" version="v71">
14271       Fix JVMTI_HEAP_ROOT_THREAD to be 6.
14272       Make each synopsis match the function name.
14273       Fix unclear wording.
14274   </change>
14275   <change date="26 June 2003" version="v72">
14276       SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
14277       to be set to NULL.
14278       NotifyFramePop, GetFrameLocationm and all the local variable operations
14279       needed to have their wording about frames fixed.
14280       Grammar and clarity need to be fixed throughout.
14281       Capitalization and puntuation need to be consistent.
14282       Need micro version number and masks for accessing major, minor, and micro.
14283       The error code lists should indicate which must be returned by
14284       an implementation.
14285       The command line properties should be visible in the properties functions.
14286       Disallow popping from the current thread.
14287       Allow implementations to return opaque frame error when they cannot pop.
14288       The NativeMethodBind event should be sent during any phase.
14289       The DynamicCodeGenerated event should be sent during any phase.
14290       The following functions should be allowed to operate before VMInit:
14291         Set/GetEnvironmentLocalStorage
14292         GetMethodDeclaringClass
14293         GetClassSignature
14294         GetClassModifiers
14295         IsInterface
14296         IsArrayClass
14297         GetMethodName
14298         GetMethodModifiers
14299         GetMaxLocals
14300         GetArgumentsSize
14301         GetLineNumberTable
14302         GetMethodLocation
14303         IsMethodNative
14304         IsMethodSynthetic.
14305       Other changes (to XSL):
14306       Argument description should show asterisk after not before pointers.
14307       NotifyFramePop, GetFrameLocationm and all the local variable operations
14308       should hsve the NO_MORE_FRAMES error added.
14309       Not alive threads should have a different error return than invalid thread.
14310   </change>
14311   <change date="7 July 2003" version="v73">
14312       VerboseOutput event was missing message parameter.
14313       Minor fix-ups.
14314   </change>
14315   <change date="14 July 2003" version="v74">
14316       Technical Publications Department corrections.
14317       Allow thread and environment local storage to be set to NULL.
14318   </change>
14319   <change date="23 July 2003" version="v75">
14320       Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
14321       Add JNICALL to callbacks (XSL).
14322       Document JNICALL requirement for both events and callbacks (XSL).
14323       Restrict RedefineClasses to methods and attributes.
14324       Elide the VerboseOutput event.
14325       VMObjectAlloc: restrict when event is sent and remove method parameter.
14326       Finish loose ends from Tech Pubs edit.
14327   </change>
14328   <change date="24 July 2003" version="v76">
14329       Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
14330   </change>
14331   <change date="24 July 2003" version="v77">
14332       XML fixes.
14333       Minor text clarifications and corrections.
14334   </change>
14335   <change date="24 July 2003" version="v78">
14336       Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
14337       Clarify that stack frames are JVM Spec frames.
14338       Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
14339       and can_get_source_debug_extension.
14340       PopFrame cannot have a native calling method.
14341       Removed incorrect statement in GetClassloaderClasses
14342       (see <vmspec chapter="4.4"/>).
14343   </change>
14344   <change date="24 July 2003" version="v79">
14345       XML and text fixes.
14346       Move stack frame description into Stack Frame category.
14347   </change>
14348   <change date="26 July 2003" version="v80">
14349       Allow NULL (means bootstrap loader) for GetClassloaderClasses.
14350       Add new heap reference kinds for references from classes.
14351       Add timer information struct and query functions.
14352       Add AvailableProcessors.
14353       Rename GetOtherThreadCpuTime to GetThreadCpuTime.
14354       Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
14355       to SetEventNotification mode.
14356       Add initial thread to the VM_INIT event.
14357       Remove platform assumptions from AddToBootstrapClassLoaderSearch.
14358   </change>
14359   <change date="26 July 2003" version="v81">
14360       Grammar and clarity changes per review.
14361   </change>
14362   <change date="27 July 2003" version="v82">
14363       More grammar and clarity changes per review.
14364       Add Agent_OnUnload.
14365   </change>
14366   <change date="28 July 2003" version="v83">
14367       Change return type of Agent_OnUnload to void.
14368   </change>
14369   <change date="28 July 2003" version="v84">
14370       Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
14371   </change>
14372   <change date="28 July 2003" version="v85">
14373       Steal java.lang.Runtime.availableProcessors() wording for
14374       AvailableProcessors().
14375       Guarantee that zero will never be an event ID.
14376       Remove some issues which are no longer issues.
14377       Per review, rename and more completely document the timer
14378       information functions.
14379   </change>
14380   <change date="29 July 2003" version="v86">
14381       Non-spec visible change to XML controlled implementation:
14382         SetThreadLocalStorage must run in VM mode.
14383   </change>
14384   <change date="5 August 2003" version="0.1.87">
14385       Add GetErrorName.
14386       Add varargs warning to jvmtiExtensionEvent.
14387       Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
14388       Remove unused can_get_exception_info capability.
14389       Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
14390       Fix jvmtiExtensionFunctionInfo.func declared type.
14391       Extension function returns error code.
14392       Use new version numbering.
14393   </change>
14394   <change date="5 August 2003" version="0.2.88">
14395       Remove the ClassUnload event.
14396   </change>
14397   <change date="8 August 2003" version="0.2.89">
14398       Heap reference iterator callbacks return an enum that
14399       allows outgoing object references to be ignored.
14400       Allow JNIEnv as a param type to extension events/functions.
14401   </change>
14402   <change date="15 August 2003" version="0.2.90">
14403       Fix a typo.
14404   </change>
14405   <change date="2 September 2003" version="0.2.91">
14406       Remove all metadata functions: GetClassMetadata,
14407       GetFieldMetadata, and GetMethodMetadata.
14408   </change>
14409   <change date="1 October 2003" version="0.2.92">
14410       Mark the functions Allocate. Deallocate, RawMonitor*,
14411       SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage
14412       as safe for use in heap callbacks and GC events.
14413   </change>
14414   <change date="24 November 2003" version="0.2.93">
14415       Add pass through opaque user data pointer to heap iterate
14416       functions and callbacks.
14417       In the CompiledMethodUnload event, send the code address.
14418       Add GarbageCollectionOccurred event.
14419       Add constant pool reference kind.
14420       Mark the functions CreateRawMonitor and DestroyRawMonitor
14421       as safe for use in heap callbacks and GC events.
14422       Clarify: VMDeath, GetCurrentThreadCpuTimerInfo,
14423       GetThreadCpuTimerInfo, IterateOverReachableObjects,
14424       IterateOverObjectsReachableFromObject, GetTime and
14425       JVMTI_ERROR_NULL_POINTER.
14426       Add missing errors to: GenerateEvents and
14427       AddToBootstrapClassLoaderSearch.
14428       Fix description of ClassFileLoadHook name parameter.
14429       In heap callbacks and GC/ObjectFree events, specify
14430       that only explicitly allowed functions can be called.
14431       Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
14432       GetTimerInfo, and GetTime during callback.
14433       Allow calling SetTag/GetTag during the onload phase.
14434       SetEventNotificationMode, add: error attempted inappropriate
14435       thread level control.
14436       Remove jvmtiExceptionHandlerEntry.
14437       Fix handling of native methods on the stack --
14438       location_ptr param of GetFrameLocation, remove
14439       JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
14440       jvmtiFrameInfo.location, and jlocation.
14441       Remove typo (from JVMPI) implying that the MonitorWaited
14442       event is sent on sleep.
14443   </change>
14444   <change date="25 November 2003" version="0.2.94">
14445       Clarifications and typos.
14446   </change>
14447   <change date="3 December 2003" version="0.2.95">
14448       Allow NULL user_data in heap iterators.
14449   </change>
14450   <change date="28 January 2004" version="0.2.97">
14451       Add GetThreadState, deprecate GetThreadStatus.
14452   </change>
14453   <change date="29 January 2004" version="0.2.98">
14454       INVALID_SLOT and TYPE_MISMATCH errors should be optional.
14455   </change>
14456   <change date="12 February 2004" version="0.2.102">
14457       Remove MonitorContendedExit.
14458       Added JNIEnv parameter to VMObjectAlloc.
14459       Clarified definition of class_tag and referrer_index
14460       parameters to heap callbacks.
14461   </change>
14462   <change date="16 Febuary 2004" version="0.2.103">
14463       Document JAVA_TOOL_OPTIONS.
14464   </change>
14465   <change date="17 Febuary 2004" version="0.2.105">
14466       Divide start phase into primordial and start.
14467       Add VMStart event
14468       Change phase associations of functions and events.
14469   </change>
14470   <change date="18 Febuary 2004" version="0.3.6">
14471       Elide deprecated GetThreadStatus.
14472       Bump minor version, subtract 100 from micro version
14473   </change>
14474   <change date="18 Febuary 2004" version="0.3.7">
14475       Document that timer nanosecond values are unsigned.
14476       Clarify text having to do with native methods.
14477   </change>
14478   <change date="19 Febuary 2004" version="0.3.8">
14479       Fix typos.
14480       Remove elided deprecated GetThreadStatus.
14481   </change>
14482   <change date="23 Febuary 2004" version="0.3.9">
14483       Require NotifyFramePop to act on suspended threads.
14484   </change>
14485   <change date="24 Febuary 2004" version="0.3.10">
14486       Add capabilities
14487         (<internallink id="jvmtiCapabilities.can_redefine_any_class"
14488          ><code>can_redefine_any_class</code></internallink>
14489       and
14490          <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
14491          ><code>can_generate_all_class_hook_events</code></internallink>)
14492       and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>)
14493       which allow some classes to be unmodifiable.
14494   </change>
14495   <change date="28 Febuary 2004" version="0.3.11">
14496       Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
14497   </change>
14498   <change date="8 March 2004" version="0.3.12">
14499       Clarified CompiledMethodUnload so that it is clear the event
14500       may be posted after the class has been unloaded.
14501   </change>
14502   <change date="5 March 2004" version="0.3.13">
14503       Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
14504   </change>
14505   <change date="13 March 2004" version="0.3.14">
14506       Added guideline for the use of the JNI FindClass function in event
14507       callback functions.
14508   </change>
14509   <change date="15 March 2004" version="0.3.15">
14510       Add GetAllStackTraces and GetThreadListStackTraces.
14511   </change>
14512   <change date="19 March 2004" version="0.3.16">
14513       ClassLoad and ClassPrepare events can be posted during start phase.
14514   </change>
14515   <change date="25 March 2004" version="0.3.17">
14516       Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
14517       GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
14518   </change>
14519   <change date="29 March 2004" version="0.3.18">
14520       Return the timer kind in the timer information structure.
14521   </change>
14522   <change date="31 March 2004" version="0.3.19">
14523       Spec clarifications:
14524       JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
14525       ForceGarbageCollection does not run finalizers.
14526       The context of the specification is the Java platform.
14527       Warn about early instrumentation.
14528   </change>
14529   <change date="1 April 2004" version="0.3.20">
14530       Refinements to the above clarifications and
14531       Clarify that an error returned by Agent_OnLoad terminates the VM.
14532   </change>
14533   <change date="1 April 2004" version="0.3.21">
14534       Array class creation does not generate a class load event.
14535   </change>
14536   <change date="7 April 2004" version="0.3.22">
14537       Align thread state hierarchy more closely with java.lang.Thread.State.
14538   </change>
14539   <change date="12 April 2004" version="0.3.23">
14540       Clarify the documentation of thread state.
14541   </change>
14542   <change date="19 April 2004" version="0.3.24">
14543       Remove GarbageCollectionOccurred event -- can be done by agent.
14544   </change>
14545   <change date="22 April 2004" version="0.3.25">
14546       Define "command-line option".
14547   </change>
14548   <change date="29 April 2004" version="0.3.26">
14549       Describe the intended use of bytecode instrumentation.
14550       Fix description of extension event first parameter.
14551   </change>
14552   <change date="30 April 2004" version="0.3.27">
14553       Clarification and typos.
14554   </change>
14555   <change date="18 May 2004" version="0.3.28">
14556       Remove DataDumpRequest event.
14557   </change>
14558   <change date="18 May 2004" version="0.3.29">
14559       Clarify RawMonitorWait with zero timeout.
14560       Clarify thread state after RunAgentThread.
14561   </change>
14562   <change date="24 May 2004" version="0.3.30">
14563       Clean-up: fix bad/old links, etc.
14564   </change>
14565   <change date="30 May 2004" version="0.3.31">
14566       Clarifications including:
14567       All character strings are modified UTF-8.
14568       Agent thread visibiity.
14569       Meaning of obsolete method version.
14570       Thread invoking heap callbacks,
14571   </change>
14572   <change date="1 June 2004" version="1.0.32">
14573       Bump major.minor version numbers to "1.0".
14574   </change>
14575   <change date="2 June 2004" version="1.0.33">
14576       Clarify interaction between ForceGarbageCollection
14577       and ObjectFree.
14578   </change>
14579   <change date="6 June 2004" version="1.0.34">
14580       Restrict AddToBootstrapClassLoaderSearch and
14581       SetSystemProperty to the OnLoad phase only.
14582   </change>
14583   <change date="11 June 2004" version="1.0.35">
14584       Fix typo in SetTag.
14585   </change>
14586   <change date="18 June 2004" version="1.0.36">
14587       Fix trademarks.
14588       Add missing parameter in example GetThreadState usage.
14589   </change>
14590   <change date="4 August 2004" version="1.0.37">
14591       Copyright updates.
14592   </change>
14593   <change date="5 November 2004" version="1.0.38">
14594       Add missing function table layout.
14595       Add missing description of C++ member function format of functions.
14596       Clarify that name in CFLH can be NULL.
14597       Released as part of <tm>J2SE</tm> 5.0.
14598   </change>
14599   <change date="24 April 2005" version="1.1.47">
14600       Bump major.minor version numbers to "1.1".
14601       Add ForceEarlyReturn* functions.
14602       Add GetOwnedMonitorStackDepthInfo function.
14603       Add GetCurrentThread function.
14604       Add "since" version marker.
14605       Add AddToSystemClassLoaderSearch.
14606       Allow AddToBootstrapClassLoaderSearch be used in live phase.
14607       Fix historic rubbish in the descriptions of the heap_object_callback
14608       parameter of IterateOverHeap and IterateOverInstancesOfClass functions;
14609       disallow NULL for this parameter.
14610       Clarify, correct and make consistent: wording about current thread,
14611       opaque frames and insufficient number of frames in PopFrame.
14612       Consistently use "current frame" rather than "topmost".
14613       Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
14614       by making them compatible with those in ForceEarlyReturn*.
14615       Many other clarifications and wording clean ups.
14616   </change>
14617   <change date="25 April 2005" version="1.1.48">
14618       Add GetConstantPool.
14619       Switch references to the first edition of the VM Spec, to the seconds edition.
14620   </change>
14621   <change date="26 April 2005" version="1.1.49">
14622       Clarify minor/major version order in GetConstantPool.
14623   </change>
14624   <change date="26 April 2005" version="1.1.50">
14625       Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
14626       Reassign GetOwnedMonitorStackDepthInfo to position 153.
14627       Break out Class Loader Search in its own documentation category.
14628       Deal with overly long lines in XML source.
14629   </change>
14630   <change date="29 April 2005" version="1.1.51">
14631       Allow agents be started in the live phase.
14632       Added paragraph about deploying agents.
14633   </change>
14634   <change date="30 April 2005" version="1.1.52">
14635       Add specification description to SetNativeMethodPrefix(es).
14636       Better define the conditions on GetConstantPool.
14637   </change>
14638   <change date="30 April 2005" version="1.1.53">
14639       Break out the GetClassVersionNumber function from GetConstantPool.
14640       Clean-up the references to the VM Spec.
14641   </change>
14642   <change date="1 May 2005" version="1.1.54">
14643       Allow SetNativeMethodPrefix(es) in any phase.
14644       Add clarifications about the impact of redefinition on GetConstantPool.
14645   </change>
14646   <change date="2 May 2005" version="1.1.56">
14647       Various clarifications to SetNativeMethodPrefix(es).
14648   </change>
14649   <change date="2 May 2005" version="1.1.57">
14650       Add missing performance warning to the method entry event.
14651   </change>
14652   <change date="5 May 2005" version="1.1.58">
14653       Remove internal JVMDI support.
14654   </change>
14655   <change date="8 May 2005" version="1.1.59">
14656       Add <functionlink id="RetransformClasses"/>.
14657       Revamp the bytecode instrumentation documentation.
14658       Change <functionlink id="IsMethodObsolete"/> to no longer
14659       require the can_redefine_classes capability.
14660   </change>
14661   <change date="11 May 2005" version="1.1.63">
14662       Clarifications for retransformation.
14663   </change>
14664   <change date="11 May 2005" version="1.1.64">
14665       Clarifications for retransformation, per review.
14666       Lock "retransformation (in)capable" at class load enable time.
14667   </change>
14668   <change date="4 June 2005" version="1.1.67">
14669       Add new heap functionity which supports reporting primitive values,
14670       allows setting the referrer tag, and has more powerful filtering:
14671       FollowReferences, IterateThroughHeap, and their associated
14672       callbacks, structs, enums, and constants.
14673   </change>
14674   <change date="4 June 2005" version="1.1.68">
14675       Clarification.
14676   </change>
14677   <change date="6 June 2005" version="1.1.69">
14678       FollowReferences, IterateThroughHeap: Put callbacks in a struct;
14679       Add missing error codes; reduce bits in the visit control flags.
14680   </change>
14681   <change date="14 June 2005" version="1.1.70">
14682       More on new heap functionity: spec clean-up per review.
14683   </change>
14684   <change date="15 June 2005" version="1.1.71">
14685       More on new heap functionity: Rename old heap section to Heap (1.0).
14686   </change>
14687   <change date="21 June 2005" version="1.1.72">
14688       Fix typos.
14689   </change>
14690   <change date="27 June 2005" version="1.1.73">
14691       Make referrer info structure a union.
14692   </change>
14693   <change date="9 September 2005" version="1.1.74">
14694       In new heap functions:
14695       Add missing superclass reference kind.
14696       Use a single scheme for computing field indexes.
14697       Remove outdated references to struct based referrer info.
14698   </change>
14699   <change date="12 September 2005" version="1.1.75">
14700       Don't callback during FollowReferences on frivolous java.lang.Object superclass.
14701   </change>
14702   <change date="13 September 2005" version="1.1.76">
14703       In string primitive callback, length now Unicode length.
14704       In array and string primitive callbacks, value now "const".
14705       Note possible compiler impacts on setting JNI function table.
14706   </change>
14707   <change date="13 September 2005" version="1.1.77">
14708       GetClassVersionNumbers() and GetConstantPool() should return
14709       error on array or primitive class.
14710   </change>
14711   <change date="14 September 2005" version="1.1.78">
14712       Grammar fixes.
14713   </change>
14714   <change date="26 September 2005" version="1.1.79">
14715       Add IsModifiableClass query.
14716   </change>
14717   <change date="9 February 2006" version="1.1.81">
14718       Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
14719   </change>
14720   <change date="13 February 2006" version="1.1.82">
14721       Doc fixes: update can_redefine_any_class to include retransform.
14722       Clarify that exception events cover all Throwables.
14723       In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
14724       Clarify fields reported in Primitive Field Callback -- static vs instance.
14725       Repair confusing names of heap types, including callback names.
14726       Require consistent usage of stack depth in the face of thread launch methods.
14727       Note incompatibility of <jvmti/> memory management with other systems.
14728   </change>
14729   <change date="14 February 2006" version="1.1.85">
14730       Fix typos and missing renames.
14731   </change>
14732   <change date="13 March 2006" version="1.1.86">
14733       Clarify that jmethodIDs and jfieldIDs can be saved.
14734       Clarify that Iterate Over Instances Of Class includes subclasses.
14735   </change>
14736   <change date="14 March 2006" version="1.1.87">
14737       Better phrasing.
14738   </change>
14739   <change date="16 March 2006" version="1.1.88">
14740       Match the referrer_index for static fields in Object Reference Callback
14741       with the Reference Implementation (and all other known implementations);
14742       that is, make it match the definition for instance fields.
14743       In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover
14744       an invalid thread in the list; and specify that not started threads
14745       return empty stacks.
14746   </change>
14747   <change date="17 March 2006" version="1.1.89">
14748       Typo.
14749   </change>
14750   <change date="25 March 2006" version="1.1.90">
14751       Typo.
14752   </change>
14753   <change date="6 April 2006" version="1.1.91">
14754       Remove restrictions on AddToBootstrapClassLoaderSearch and
14755       AddToSystemClassLoaderSearch.
14756   </change>
14757   <change date="1 May 2006" version="1.1.93">
14758       Changed spec to return -1 for monitor stack depth for the
14759       implementation which can not determine stack depth.
14760   </change>
14761   <change date="3 May 2006" version="1.1.94">
14762       Corrections for readability and accuracy courtesy of Alan Pratt of IBM.
14763       List the object relationships reported in FollowReferences.
14764   </change>
14765   <change date="5 May 2006" version="1.1.95">
14766       Clarify the object relationships reported in FollowReferences.
14767   </change>
14768   <change date="28 June 2006" version="1.1.98">
14769       Clarify DisposeEnvironment; add warning.
14770       Fix typos in SetLocalXXX "retrieve" => "set".
14771       Clarify that native method prefixes must remain set while used.
14772       Clarify that exactly one Agent_OnXXX is called per agent.
14773       Clarify that library loading is independent from start-up.
14774       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14775   </change>
14776   <change date="31 July 2006" version="1.1.99">
14777       Clarify the interaction between functions and exceptions.
14778       Clarify and give examples of field indices.
14779       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14780       Update links to point to Java 6.
14781   </change>
14782   <change date="6 August 2006" version="1.1.102">
14783       Add ResourceExhaustedEvent.
14784   </change>
14785   <change date="11 October 2012" version="1.2.2">
14786       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14787   </change>
14788   <change date="19 June 2013" version="1.2.3">
14789       Added support for statically linked agents.
14790   </change>
14791   <change date="13 October 2016" version="9.0.0">
14792       Support for modules:
14793        - The majorversion is 9 now
14794        - The ClassFileLoadHook events are not sent during the primordial phase anymore.
14795        - Allow CompiledMethodLoad events at start phase
14796        - Add new capabilities:
14797           - can_generate_early_vmstart
14798           - can_generate_early_class_hook_events
14799        - Add new functions:
14800           - GetAllModules
14801           - AddModuleReads, AddModuleExports, AddModuleOpens, AddModuleUses, AddModuleProvides
14802           - IsModifiableModule
14803       Clarified can_redefine_any_classes, can_retransform_any_classes and IsModifiableClass API to
14804       disallow some implementation defined classes.
14805   </change>
14806   <change date="12 February 2017" version="9.0.0">
14807       Minor update for GetCurrentThread function:
14808        - The function may return NULL in the start phase if the
14809          can_generate_early_vmstart capability is enabled.
14810   </change>
14811 </changehistory>
14812 
14813 </specification>
14814 <!-- Keep this comment at the end of the file
14815 Local variables:
14816 mode: sgml
14817 sgml-omittag:t
14818 sgml-shorttag:t
14819 sgml-namecase-general:t
14820 sgml-general-insert-case:lower
14821 sgml-minimize-attributes:nil
14822 sgml-always-quote-attributes:t
14823 sgml-indent-step:2
14824 sgml-indent-data:t
14825 sgml-parent-document:nil
14826 sgml-exposed-tags:nil
14827 sgml-local-catalogs:nil
14828 sgml-local-ecat-files:nil
14829 End:
14830 -->