1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
   3 <!--
   4  Copyright (c) 2002, 2019, 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 
  31    <!ELEMENT title (#PCDATA|jvmti|tm)*>
  32    <!ATTLIST title subtitle CDATA #REQUIRED>
  33 
  34    <!ELEMENT intro ANY>
  35    <!ATTLIST intro id CDATA #IMPLIED
  36                    label CDATA "">
  37 
  38    <!ELEMENT functionsection (intro*, category*)>
  39    <!ATTLIST functionsection label CDATA #REQUIRED>
  40 
  41    <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*,
  42                           (function|callback|elide)*)>
  43    <!ATTLIST category id CDATA #REQUIRED
  44                       label CDATA #REQUIRED>
  45 
  46    <!ELEMENT function (synopsis, typedef*, description?, origin,
  47                          (capabilities|eventcapabilities),
  48                          parameters, errors)>
  49    <!ATTLIST function id CDATA #REQUIRED
  50                       num CDATA #REQUIRED
  51                       phase (onload|onloadOnly|start|live|any) #IMPLIED
  52                       callbacksafe (safe|unsafe) #IMPLIED
  53                       impl CDATA #IMPLIED
  54                       hide CDATA #IMPLIED
  55                       jkernel (yes|no) #IMPLIED
  56                       since CDATA "1.0">
  57 
  58    <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  59                         jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),
  60                         synopsis, description?, parameters)>
  61    <!ATTLIST callback id CDATA #REQUIRED
  62                       since CDATA "1.0">
  63 
  64    <!ELEMENT synopsis (#PCDATA|jvmti)*>
  65 
  66    <!ELEMENT typedef (description?, field*)>
  67    <!ATTLIST typedef id CDATA #REQUIRED
  68                      label CDATA #REQUIRED
  69                      since CDATA "1.0">
  70 
  71    <!ELEMENT uniontypedef (description?, field*)>
  72    <!ATTLIST uniontypedef id CDATA #REQUIRED
  73                      label CDATA #REQUIRED
  74                      since CDATA "1.0">
  75 
  76    <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
  77                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct),
  78                     description)>
  79    <!ATTLIST field id CDATA #REQUIRED>
  80 
  81    <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>
  82    <!ATTLIST capabilitiestypedef id CDATA #REQUIRED
  83                      label CDATA #REQUIRED>
  84 
  85    <!ELEMENT capabilityfield (description)>
  86    <!ATTLIST capabilityfield id CDATA #REQUIRED
  87                    disp1 CDATA ""
  88                    disp2 CDATA ""
  89                    since CDATA "1.0">
  90 
  91    <!ELEMENT description ANY>
  92 
  93    <!ELEMENT capabilities (required*, capability*)>
  94 
  95    <!ELEMENT eventcapabilities EMPTY>
  96 
  97    <!ELEMENT required ANY>
  98    <!ATTLIST required id CDATA #REQUIRED>
  99 
 100    <!ELEMENT capability ANY>
 101    <!ATTLIST capability id CDATA #REQUIRED>
 102 
 103    <!ELEMENT parameters (param*)>
 104 
 105    <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|
 106                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|
 107                      outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf),
 108                     description)>
 109    <!ATTLIST param id CDATA #REQUIRED>
 110 
 111    <!ELEMENT jmethodID EMPTY>
 112    <!ATTLIST jmethodID class  CDATA #IMPLIED
 113                        native CDATA #IMPLIED>
 114 
 115    <!ELEMENT jfieldID EMPTY>
 116    <!ATTLIST jfieldID class CDATA #IMPLIED>
 117 
 118    <!ELEMENT jclass EMPTY>
 119    <!ATTLIST jclass method CDATA #IMPLIED
 120                     field  CDATA #IMPLIED>
 121 
 122    <!ELEMENT jframeID EMPTY>
 123    <!ATTLIST jframeID thread CDATA #IMPLIED>
 124 
 125    <!ELEMENT jrawMonitorID EMPTY>
 126 
 127    <!ELEMENT jthread EMPTY>
 128    <!ATTLIST jthread started CDATA #IMPLIED
 129                      null CDATA #IMPLIED
 130                      frame CDATA #IMPLIED
 131                      impl CDATA #IMPLIED>
 132 
 133    <!ELEMENT varargs EMPTY>
 134 
 135    <!ELEMENT jthreadGroup EMPTY>
 136    <!ELEMENT jobject EMPTY>
 137    <!ELEMENT jvalue EMPTY>
 138    <!ELEMENT jchar EMPTY>
 139    <!ELEMENT jint EMPTY>
 140    <!ATTLIST jint min CDATA #IMPLIED>
 141    <!ELEMENT jlong EMPTY>
 142    <!ELEMENT jfloat EMPTY>
 143    <!ELEMENT jdouble EMPTY>
 144    <!ELEMENT jlocation EMPTY>
 145    <!ELEMENT jboolean EMPTY>
 146    <!ELEMENT char EMPTY>
 147    <!ELEMENT uchar EMPTY>
 148    <!ELEMENT size_t EMPTY>
 149    <!ELEMENT void EMPTY>
 150    <!ELEMENT enum (#PCDATA)*>
 151    <!ELEMENT struct (#PCDATA)*>
 152 
 153    <!ELEMENT nullok ANY>
 154 
 155    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 156                                    jthreadGroup|jobject|jvalue), nullok?)>
 157 
 158    <!ELEMENT outptr     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 159                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 160                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 161 
 162    <!ELEMENT allocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 163                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 164                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 165    <!ATTLIST allocbuf incount CDATA #IMPLIED
 166                       outcount CDATA #IMPLIED>
 167 
 168    <!ELEMENT allocallocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 169                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 170                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 171    <!ATTLIST allocallocbuf incount CDATA #IMPLIED
 172                       outcount CDATA #IMPLIED>
 173 
 174    <!ELEMENT inptr      (struct, nullok?)>
 175 
 176    <!ELEMENT inbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 177                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 178                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 179    <!ATTLIST inbuf    incount CDATA #IMPLIED>
 180 
 181    <!ELEMENT outbuf     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 182                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 183                                    jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
 184    <!ATTLIST outbuf   incount CDATA #IMPLIED
 185                       outcount CDATA #IMPLIED>
 186 
 187    <!ELEMENT vmbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 188                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
 189                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 190    <!ATTLIST vmbuf    incount CDATA #IMPLIED
 191                       outcount CDATA #IMPLIED>
 192 
 193    <!ELEMENT agentbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 194                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 195                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
 196    <!ATTLIST agentbuf incount CDATA #IMPLIED
 197                       outcount CDATA #IMPLIED>
 198 
 199    <!ELEMENT allocfieldbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
 200                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
 201                                    jlocation|jboolean|char|uchar|size_t|void))>
 202    <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
 203 
 204    <!ELEMENT errors (error*)>
 205 
 206    <!ELEMENT error ANY>
 207    <!ATTLIST error id CDATA #REQUIRED>
 208 
 209    <!ELEMENT errorsection (intro*, errorcategory*)>
 210    <!ATTLIST errorsection label CDATA #REQUIRED>
 211 
 212    <!ELEMENT errorcategory (intro*, errorid*)>
 213    <!ATTLIST errorcategory id CDATA #REQUIRED
 214                            label CDATA #REQUIRED>
 215 
 216    <!ELEMENT errorid ANY>
 217    <!ATTLIST errorid id CDATA #REQUIRED
 218                      num CDATA #REQUIRED>
 219 
 220    <!ELEMENT datasection (intro*, basetypes*)>
 221 
 222    <!ELEMENT basetypes (intro*, basetype*)>
 223    <!ATTLIST basetypes id CDATA #REQUIRED
 224                        label CDATA #REQUIRED>
 225 
 226    <!ELEMENT basetype (definition?,description)>
 227    <!ATTLIST basetype id CDATA #REQUIRED
 228                       name CDATA #IMPLIED>
 229 
 230    <!ELEMENT definition (#PCDATA|jvmti)*>
 231 
 232    <!ELEMENT eventsection (intro*, (event|elide)*)>
 233    <!ATTLIST eventsection label CDATA #REQUIRED>
 234 
 235    <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
 236    <!ATTLIST event id CDATA #REQUIRED
 237                    label CDATA #REQUIRED
 238                    const CDATA #REQUIRED
 239                    num CDATA #REQUIRED
 240                    phase (onload|start|live|any) #IMPLIED
 241                    filtered (thread|global) #IMPLIED
 242                    since CDATA "1.0">
 243 
 244    <!ELEMENT issuessection (intro*)>
 245    <!ATTLIST issuessection label CDATA #REQUIRED>
 246 
 247    <!ELEMENT changehistory (intro*, change*)>
 248    <!ATTLIST changehistory update CDATA #REQUIRED
 249                            id CDATA #REQUIRED>
 250 
 251    <!ELEMENT change ANY>
 252    <!ATTLIST change date CDATA #REQUIRED
 253                     version CDATA #IMPLIED>
 254 
 255    <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
 256    <!ATTLIST functionlink id CDATA #REQUIRED>
 257 
 258    <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
 259    <!ATTLIST datalink id CDATA #REQUIRED>
 260 
 261    <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
 262    <!ATTLIST typelink id CDATA #REQUIRED>
 263 
 264    <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
 265    <!ATTLIST fieldlink id CDATA #REQUIRED
 266                        struct CDATA #REQUIRED>
 267 
 268    <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
 269    <!ATTLIST paramlink id CDATA #REQUIRED>
 270 
 271    <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
 272    <!ATTLIST eventlink id CDATA #REQUIRED>
 273 
 274    <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
 275    <!ATTLIST errorlink id CDATA #REQUIRED>
 276 
 277    <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
 278    <!ATTLIST externallink id CDATA #REQUIRED>
 279 
 280    <!ELEMENT vmspec EMPTY>
 281    <!ATTLIST vmspec chapter CDATA #IMPLIED>
 282 
 283    <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
 284    <!ATTLIST internallink id CDATA #REQUIRED>
 285 
 286    <!ELEMENT functionphaselist EMPTY>
 287    <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
 288 
 289    <!ELEMENT eventphaselist EMPTY>
 290    <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
 291 
 292    <!ELEMENT issue ANY>
 293 
 294    <!ELEMENT rationale ANY>
 295 
 296    <!ELEMENT todo ANY>
 297 
 298    <!ELEMENT origin (#PCDATA)*>
 299 
 300    <!ELEMENT elide (intro|function|callback|event)*>
 301    <!ATTLIST elide why CDATA #IMPLIED>
 302 
 303    <!ELEMENT constants (constant*)>
 304    <!ATTLIST constants id CDATA #REQUIRED
 305                        label CDATA #REQUIRED
 306                        kind (enum|bits|const) #REQUIRED
 307                        since CDATA "1.0">
 308 
 309    <!ELEMENT constant ANY>
 310    <!ATTLIST constant id CDATA #REQUIRED
 311                       num CDATA #REQUIRED>
 312 
 313    <!ELEMENT tm (#PCDATA)>
 314 
 315    <!ELEMENT i (#PCDATA|jvmti|tm)*>
 316 
 317    <!ELEMENT b (#PCDATA|jvmti|code)*>
 318 
 319    <!ELEMENT code (#PCDATA|space)*>
 320 
 321    <!ELEMENT pre ANY>
 322 
 323    <!ELEMENT space EMPTY>
 324 
 325    <!ELEMENT jvmti EMPTY>
 326 
 327    <!ELEMENT example (#PCDATA|i)*>
 328 
 329    <!ELEMENT br EMPTY>
 330 
 331    <!ELEMENT p EMPTY>
 332 
 333    <!ELEMENT blockquote ANY>
 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 class CDATA #IMPLIED>
 347 
 348    <!ELEMENT th  ANY>
 349    <!ATTLIST th class CDATA #IMPLIED>
 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   <title subtitle="Version">
 359     <tm>JVM</tm> Tool Interface
 360   </title>
 361 
 362   <intro id="whatIs" label="What is the JVM Tool Interface?">
 363     The <tm>JVM</tm> Tool Interface (<jvmti/>)
 364     is a programming interface used by development and monitoring tools.
 365     It provides both a way to inspect the state and
 366     to control the execution of applications running in the
 367     <tm>Java</tm> virtual machine (VM).
 368     <p/>
 369     <jvmti/> is intended to provide a VM interface for the full breadth of tools
 370     that need access to VM state, including but not limited to: profiling,
 371     debugging, monitoring, thread analysis, and coverage analysis tools.
 372     <p/>
 373     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
 374     machine.
 375     <p/>
 376     <jvmti/> is a two-way interface.
 377     A client of <jvmti/>, hereafter called an <i>agent</i>,
 378     can be notified of
 379     interesting occurrences through <internallink id="EventSection">events</internallink>.
 380     <jvmti/>
 381     can query and control the application through many
 382     <internallink id="FunctionSection">functions</internallink>,
 383     either in response to events or
 384     independent of them.
 385     <p/>
 386     Agents run in the same process with and communicate directly with
 387     the virtual machine executing
 388     the application being examined.  This communication is
 389     through a native interface (<jvmti/>). The native in-process interface allows
 390     maximal control with minimal intrusion on the part of a tool.
 391     Typically, agents are relatively compact. They can be controlled
 392     by a separate process which implements the bulk of a tool's
 393     function without interfering with the target application's normal execution.
 394   </intro>
 395 
 396   <intro id="architecture" label="Architecture">
 397     Tools can be written directly to <jvmti/> or indirectly
 398     through higher level interfaces.
 399     The Java Platform Debugger Architecture includes <jvmti/>, but also
 400     contains higher-level, out-of-process debugger interfaces. The higher-level
 401     interfaces are more appropriate than <jvmti/> for many tools.
 402     For more information on the Java Platform Debugger Architecture,
 403     see the
 404     <externallink id="jpda/architecture.html">Java
 405       Platform Debugger Architecture website</externallink>.
 406   </intro>
 407 
 408   <intro id="writingAgents" label="Writing Agents">
 409     Agents can be written in any native language that supports C
 410     language calling conventions and C or C++
 411     definitions.
 412     <p/>
 413     The function, event, data type, and constant definitions needed for
 414     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 415     To use these definitions add the <tm>J2SE</tm> include directory
 416     to your include path and add
 417     <example>
 418 #include &lt;jvmti.h&gt;
 419     </example>
 420     to your source code.
 421   </intro>
 422 
 423   <intro id="deployingAgents" label="Deploying Agents">
 424     An agent is deployed in a platform specific manner but is typically the
 425     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating
 426     system, for example, an agent library is a "Dynamic Linked Library" (DLL).
 427     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
 428     object (<code>.so</code> file).
 429     <p/>
 430 
 431     An agent may be started at VM startup by specifying the agent library
 432     name using a <internallink id="starting">command line option</internallink>.
 433     Some implementations may support a mechanism to <internallink id="onattach">
 434     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
 435     The details of how this is initiated are implementation specific.
 436   </intro>
 437 
 438     <intro id="entryPoint" label="Statically Linked Agents (since version 1.2.3)">
 439 
 440       A native JVMTI Agent may be <i>statically linked</i> with the VM.
 441       The manner in which the library and VM image are combined is
 442       implementation-dependent.
 443       An agent L whose image has been combined with the VM is defined as
 444       <i>statically linked</i> if and only if the agent exports a function
 445       called Agent_OnLoad_L.
 446 <p/>
 447       If a <i>statically linked</i> agent L exports a function called
 448       Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
 449       function will be ignored.
 450       If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
 451       function will be invoked with the same arguments and expected return
 452       value as specified for the Agent_OnLoad function.
 453       An agent L that is <i>statically linked</i> will prohibit an agent of
 454       the same name from being loaded dynamically.
 455 <p/>
 456       The VM will invoke the Agent_OnUnload_L function of the agent, if such
 457       a function is exported, at the same point during VM execution as it would
 458       have called the dynamic entry point Agent_OnUnLoad. A statically loaded
 459       agent cannot be unloaded. The Agent_OnUnload_L function will still be
 460       called to do any other agent shutdown related tasks.
 461       If a <i>statically linked</i> agent L exports a function called
 462       Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
 463       function will be ignored.
 464 <p/>
 465       If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
 466       will be invoked with the same arguments and expected return value as
 467       specified for the Agent_OnAttach function.
 468       If a <i>statically linked</i> agent L exports a function called
 469       Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
 470       function will be ignored.
 471 </intro>
 472 
 473   <intro id="starting" label="Agent Command Line Options">
 474     The term "command-line option" is used below to
 475     mean options supplied in the <code>JavaVMInitArgs</code> argument
 476     to the <code>JNI_CreateJavaVM</code> function of the JNI
 477     Invocation API.
 478     <p/>
 479     One of the two following
 480     command-line options is used on VM startup to
 481     properly load and run agents.
 482     These arguments identify the library containing
 483     the agent as well as an options
 484     string to be passed in at startup.
 485     <dl>
 486       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 487       <dd>
 488         The name following <code>-agentlib:</code> is the name of the
 489         library to load.  Lookup of the library, both its full name and location,
 490         proceeds in a platform-specific manner.
 491         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
 492         operating system specific file name.
 493         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 494         For example, if the option
 495         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to
 496         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
 497         under <tm>Windows</tm> or <code>libfoo.so</code> from the
 498         <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating
 499         environment.
 500         If the agent library is statically linked into the executable
 501         then no actual loading takes place.
 502     <p/>
 503       </dd>
 504       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 505       <dd>
 506         The path following <code>-agentpath:</code> is the absolute path from which
 507         to load the library.
 508         No library name expansion will occur.
 509         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 510         For example, if the option
 511         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to
 512         load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
 513         library is statically linked into the executable
 514         then no actual loading takes place.
 515     <p/>
 516       </dd>
 517     </dl>
 518     For a dynamic shared library agent, the start-up routine
 519     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 520     in the library will be invoked. If the agent library is statically linked
 521     into the executable then the system will attempt to invoke the
 522     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> entry point where
 523     &lt;agent-lib-name&gt; is the basename of the
 524     agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
 525     the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
 526     <p/>
 527     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
 528     will be searched for JNI native method implementations to facilitate the
 529     use of Java programming language code in tools, as is needed for
 530     <internallink id="bci">bytecode instrumentation</internallink>.
 531     <p/>
 532     The agent libraries will be searched after all other libraries have been
 533     searched (agents wishing to override or intercept the native method
 534     implementations of non-agent methods can use the
 535     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
 536     <p/>
 537     These switches do the above and nothing more - they do not change the
 538     state of the VM or <jvmti/>.  No command line options are needed
 539     to enable <jvmti/>
 540     or aspects of <jvmti/>, this is handled programmatically
 541     by the use of
 542     <internallink id="capability">capabilities</internallink>.
 543   </intro>
 544 
 545   <intro id="startup" label="Agent Start-Up">
 546     The VM starts each agent by invoking a start-up function.
 547     If the agent is started in the <code>OnLoad</code>
 548     <functionlink id="GetPhase">phase</functionlink> the function
 549     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 550     or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
 551     for statically linked agents will be invoked.
 552     If the agent is started in the live
 553     <functionlink id="GetPhase">phase</functionlink> the function
 554     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
 555     or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
 556     for statically linked agents will be invoked.
 557     Exactly one call to a start-up function is made per agent.
 558   </intro>
 559 
 560   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
 561     If an agent is started during the <code>OnLoad</code> phase then its
 562     agent library must export a start-up function with the following prototype:
 563     <example>
 564 JNIEXPORT jint JNICALL
 565 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
 566     Or for a statically linked agent named 'L':
 567     <example>
 568 JNIEXPORT jint JNICALL
 569 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
 570 
 571     The VM will start the agent by calling this function.
 572     It will be called early enough in VM initialization that:
 573     <ul>
 574       <li><functionlink id="SetSystemProperty">system properties</functionlink>
 575         may be set before they have been used in the start-up of the VM</li>
 576       <li>the full set of
 577         <internallink id="capability">capabilities</internallink>
 578         is still available (note that capabilities that configure the VM
 579         may only be available at this time--see the
 580         <internallink id="capability">Capability function section</internallink>)</li>
 581       <li>no bytecodes have executed</li>
 582       <li>no classes have been loaded</li>
 583       <li>no objects have been created</li>
 584     </ul>
 585     <p/>
 586     The VM will call the <code>Agent_OnLoad</code> or
 587     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> function with
 588     <i>&lt;options&gt;</i> as the second argument -
 589     that is, using the command-line option examples,
 590     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
 591     argument of <code>Agent_OnLoad</code>.
 592     The <code>options</code> argument is encoded as a
 593     <internallink id="mUTF">modified UTF-8</internallink> string.
 594     If <i>=&lt;options&gt;</i> is not specified,
 595     a zero length string is passed to <code>options</code>.
 596     The lifespan of the <code>options</code> string is the
 597     <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code>
 598     call.  If needed beyond this time the string or parts of the string must
 599     be copied.
 600     The period between when <code>Agent_OnLoad</code> is called and when it
 601     returns is called the <i>OnLoad phase</i>.
 602     Since the VM is not initialized during the OnLoad
 603     <functionlink id="GetPhase">phase</functionlink>,
 604     the set of allowed operations
 605     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
 606     functionality available at this time).
 607     The agent can safely process the options and set
 608     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once
 609     the VM initialization event is received
 610     (that is, the <eventlink id="VMInit">VMInit</eventlink>
 611     callback is invoked), the agent
 612     can complete its initialization.
 613     <rationale>
 614       Early startup is required so that agents can set the desired capabilities,
 615       many of which must be set before the VM is initialized.
 616       In JVMDI, the -Xdebug command-line option provided
 617       very coarse-grain control of capabilities.
 618       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
 619       No reasonable command-line
 620       option could provide the fine-grain of control required to balance needed capabilities vs
 621       performance impact.
 622       Early startup is also needed so that agents can control the execution
 623       environment - modifying the file system and system properties to install
 624       their functionality.
 625     </rationale>
 626     <p/>
 627     The return value from <code>Agent_OnLoad</code> or
 628     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> is used to indicate an error.
 629     Any value other than zero indicates an error and causes termination of the VM.
 630   </intro>
 631 
 632   <intro id="onattach" label="Agent Start-Up (Live phase)">
 633     A VM may support a mechanism that allows agents to be started in the VM during the live
 634     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
 635     are implementation specific. For example, a tool may use some platform specific mechanism,
 636     or implementation specific API, to attach to the running VM, and request it start a given
 637     agent.
 638     <p/>
 639     If an agent is started during the live phase then its agent library
 640     must export a start-up function
 641     with the following prototype:
 642     <example>
 643 JNIEXPORT jint JNICALL
 644 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
 645 Or for a statically linked agent named 'L':
 646     <example>
 647 JNIEXPORT jint JNICALL
 648 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
 649 
 650     <p/>
 651     The VM will start the agent by calling this function.
 652     It will be called in the context of a thread
 653     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
 654     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
 655     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
 656     </internallink> string.
 657     If startup options were not provided, a zero length string is passed to
 658     <code>options</code>. The lifespan of the <code>options</code> string is the
 659     <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> call.
 660     If needed beyond this time the string or parts of the string must be copied.
 661     <p/>
 662     Note that some <internallink id="capability">capabilities</internallink>
 663     may not be available in the live phase.
 664     <p/>
 665     The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name
 666     &gt;</code> function initializes the agent and returns a value
 667     to the VM to indicate if an error occurred. Any value other than zero indicates an error.
 668     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes
 669     some implementation specific action -- for example it might print an error to standard error,
 670     or record the error in a system log.
 671   </intro>
 672 
 673   <intro id="onunload" label="Agent Shutdown">
 674     The library may optionally export a
 675     shutdown function with the following prototype:
 676     <example>
 677 JNIEXPORT void JNICALL
 678 Agent_OnUnload(JavaVM *vm)</example>
 679     Or for a statically linked agent named 'L':
 680     <example>
 681 JNIEXPORT void JNICALL
 682 Agent_OnUnload_L(JavaVM *vm)</example>
 683 
 684     This function will be called by the VM when the library is about to be unloaded.
 685     The library will be unloaded (unless it is statically linked into the
 686     executable) and this function will be called if some platform specific
 687     mechanism causes the unload (an unload mechanism is not specified in this document)
 688     or the library is (in effect) unloaded by the termination of the VM whether through
 689     normal termination or VM failure, including start-up failure.
 690     Uncontrolled shutdown is, of course, an exception to this rule.
 691     Note the distinction between this function and the
 692     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
 693     to be sent, the VM must have run at least to the point of initialization and a valid
 694     <jvmti/> environment must exist which has set a callback for VMDeath
 695     and enabled the event.
 696     None of these are required for <code>Agent_OnUnload</code> or
 697     <code>Agent_OnUnload_&lt;agent-lib-name&gt;</code> and this function
 698     is also called if the library is unloaded for other reasons.
 699     In the case that a VM Death event is sent, it will be sent before this
 700     function is called (assuming this function is called due to VM termination).
 701     This function can be used to clean-up resources allocated by the agent.
 702   </intro>
 703 
 704   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
 705     Since the command-line cannot always be accessed or modified, for example in embedded VMs
 706     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
 707     provided so that agents may be launched in these cases.
 708     <p/>
 709     Platforms which support environment variables or other named strings, may support the
 710     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space
 711     boundaries.  White-space characters include space, tab, carriage-return, new-line,
 712     vertical-tab, and form-feed.  Sequences of white-space characters are considered
 713     equivalent to a single white-space character.  No white-space is included in the options
 714     unless quoted.  Quoting is as follows:
 715     <ul>
 716         <li>All characters enclosed between a pair of single quote marks (''), except a single
 717         quote, are quoted.</li>
 718         <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
 719         <li>All characters enclosed between a pair of double quote marks (""), except a double
 720         quote, are quoted.</li>
 721         <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
 722         <li>A quoted part can start or end anywhere in the variable.</li>
 723         <li>White-space characters have no special meaning when quoted -- they are included in
 724         the option like any other character and do not mark white-space boundaries.</li>
 725         <li>The pair of quote marks is not included in the option.</li>
 726     </ul>
 727     <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied
 728     in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is
 729     a concern; for example, the Reference Implementation disables this feature on Unix systems when
 730     the effective user or group ID differs from the real ID.
 731     This feature is intended to support the initialization of tools -- specifically including the
 732     launching of native or Java programming language agents.  Multiple tools may wish to use this
 733     feature, so the variable should not be overwritten, instead,  options should be appended to
 734     the variable.  Note that since the variable is processed at the time of the JNI Invocation
 735     API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
 736   </intro>
 737 
 738   <intro id="environments" label="Environments">
 739     The <jvmti/> specification supports the use of multiple simultaneous
 740     <jvmti/> agents.
 741     Each agent has its own <jvmti/> environment.
 742     That is, the <jvmti/> state is
 743     separate for each agent - changes to one environment do not affect the
 744     others.  The state of a <jvmti/>
 745     environment includes:
 746     <ul>
 747       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
 748       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
 749       <li><internallink id="capability">the capabilities</internallink></li>
 750       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
 751     </ul>
 752     Although their <jvmti/> state
 753     is separate, agents inspect and modify the shared state
 754     of the VM, they also share the native environment in which they execute.
 755     As such, an agent can perturb the results of other agents or cause them
 756     to fail.  It is the responsibility of the agent writer to specify the level
 757     of compatibility with other agents.  <jvmti/> implementations are not capable
 758     of preventing destructive interactions between agents. Techniques to reduce
 759     the likelihood of these occurrences are beyond the scope of this document.
 760     <p/>
 761     An agent creates a <jvmti/> environment
 762     by passing a <jvmti/> version
 763     as the interface ID to the JNI Invocation API function
 764     <externallink id="jni/invocation.html#getenv">
 765       <code>GetEnv</code></externallink>.
 766     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
 767     for more details on the creation and use of
 768     <jvmti/> environments.
 769     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from
 770     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
 771   </intro>
 772 
 773   <intro id="bci" label="Bytecode Instrumentation">
 774     This interface does not include some events that one might expect in an interface with
 775     profiling support.  Some examples include full speed
 776     method enter and exit events.  The interface instead provides support for
 777     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
 778     bytecode instructions which comprise the target program.  Typically, these alterations
 779     are to add "events" to the code of a method - for example, to add, at the beginning of a method,
 780     a call to <code>MyProfiler.methodEntered()</code>.
 781     Since the changes are purely additive, they do not modify application
 782     state or behavior.
 783     Because the inserted agent code is standard bytecodes, the VM can run at full speed,
 784     optimizing not only the target program but also the instrumentation.  If the
 785     instrumentation does not involve switching from bytecode execution, no expensive
 786     state transitions are needed.  The result is high performance events.
 787     This approach also provides complete control to the agent: instrumentation can be
 788     restricted to "interesting" portions of the code (e.g., the end user's code) and
 789     can be conditional.  Instrumentation can run entirely in Java programming language
 790     code or can call into the native agent.  Instrumentation can simply maintain
 791     counters or can statistically sample events.
 792     <p/>
 793     Instrumentation can be inserted in one of three ways:
 794     <ul>
 795       <li>
 796         Static Instrumentation: The class file is instrumented before it
 797         is loaded into the VM - for example, by creating a duplicate directory of
 798         <code>*.class</code> files which have been modified to add the instrumentation.
 799         This method is extremely awkward and, in general, an agent cannot know
 800         the origin of the class files which will be loaded.
 801       </li>
 802       <li>
 803         Load-Time Instrumentation: When a class file is loaded by the VM, the raw
 804         bytes of the class file are sent for instrumentation to the agent.
 805         The <eventlink id="ClassFileLoadHook"/>
 806         event, triggered by the class load,
 807         provides this functionality.  This mechanism provides efficient
 808         and complete access to one-time instrumentation.
 809       </li>
 810       <li>
 811         Dynamic Instrumentation: A class which is already loaded (and possibly
 812         even running) is modified.  This optional feature is provided by the
 813         <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
 814         <functionlink id="RetransformClasses"/> function.
 815         Classes can be modified multiple times and can be returned to their
 816         original state.
 817         The mechanism allows instrumentation which changes during the
 818         course of execution.
 819       </li>
 820     </ul>
 821     <p/>
 822     The class modification functionality provided in this interface
 823     is intended to provide a mechanism for instrumentation
 824     (the <eventlink id="ClassFileLoadHook"/> event
 825     and the <functionlink id="RetransformClasses"/> function)
 826     and, during development, for fix-and-continue debugging
 827     (the <functionlink id="RedefineClasses"/> function).
 828     <p/>
 829     Care must be taken to avoid perturbing dependencies, especially when
 830     instrumenting core classes.  For example, an approach to getting notification
 831     of every object allocation is to instrument the constructor on
 832     <code>Object</code>.  Assuming that the constructor is initially
 833     empty, the constructor could be changed to:
 834     <example>
 835       public Object() {
 836         MyProfiler.allocationTracker(this);
 837       }
 838     </example>
 839     However, if this change was made using the
 840     <eventlink id="ClassFileLoadHook"/>
 841     event then this might impact a typical VM as follows:
 842     the first created object will call the constructor causing a class load of
 843     <code>MyProfiler</code>; which will then cause
 844     object creation, and since <code>MyProfiler</code> isn't loaded yet,
 845     infinite recursion; resulting in a stack overflow.  A refinement of this
 846     would be to delay invoking the tracking method until a safe time.  For
 847     example, <code>trackAllocations</code> could be set in the
 848     handler for the <code>VMInit</code> event.
 849     <example>
 850       static boolean trackAllocations = false;
 851 
 852       public Object() {
 853         if (trackAllocations) {
 854           MyProfiler.allocationTracker(this);
 855         }
 856       }
 857     </example>
 858     <p/>
 859     The <functionlink id="SetNativeMethodPrefix"/> allows native methods
 860     to be instrumented by the use of wrapper methods.
 861   </intro>
 862 
 863 <intro id="bcimodules" label="Bytecode Instrumentation of code in modules">
 864   Agents can use the functions <functionlink id="AddModuleReads"/>,
 865   <functionlink id="AddModuleExports"/>, <functionlink id="AddModuleOpens"/>,
 866   <functionlink id="AddModuleUses"/> and <functionlink id="AddModuleProvides"/>
 867   to update a module to expand the set of modules that it reads, the set of
 868   packages that it exports or opens to other modules, or the services that it
 869   uses and provides.
 870   <p/>
 871   As an aid to agents that deploy supporting classes on the search path of
 872   the bootstrap class loader, or the search path of the class loader that
 873   loads the main class, the Java virtual machine arranges for the module
 874   of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
 875   read the unnamed module of both class loaders.
 876 </intro>
 877 
 878   <intro id="mUTF" label="Modified UTF-8 String Encoding">
 879     <jvmti/> uses modified UTF-8 to encode character strings.
 880     This is the same encoding used by JNI.
 881     Modified UTF-8 differs
 882     from standard UTF-8 in the representation of supplementary characters
 883     and of the null character. See the
 884     <externallink id="jni/types.html#modified-utf-8-strings">
 885       Modified UTF-8 Strings</externallink>
 886     section of the JNI specification for details.
 887   </intro>
 888 
 889   <intro id="context" label="Specification Context">
 890     Since this interface provides access to the state of applications running in the
 891     Java virtual machine;
 892     terminology refers to the Java platform and not the native
 893     platform (unless stated otherwise).  For example:
 894     <ul>
 895       <li>"thread" means Java programming language thread.</li>
 896       <li>"stack frame" means Java virtual machine stack frame.</li>
 897       <li>"class" means Java programming language class.</li>
 898       <li>"heap" means Java virtual machine heap.</li>
 899       <li>"monitor" means Java programming language object monitor.</li>
 900     </ul>
 901     <p/>
 902     Sun, Sun Microsystems, the Sun logo, Java, and JVM
 903     are trademarks or registered trademarks of Oracle
 904     and/or its affiliates, in the U.S. and other countries.
 905   </intro>
 906 
 907 
 908 <functionsection label="Functions">
 909   <intro id="jvmtiEnvAccess" label="Accessing Functions">
 910     Native code accesses <jvmti/> features
 911     by calling <jvmti/> functions.
 912     Access to <jvmti/> functions is by use of an interface pointer
 913     in the same manner as
 914     <externallink id="jni/design.html">Java
 915       Native Interface (JNI) functions</externallink> are accessed.
 916     The <jvmti/> interface pointer is called the
 917     <i>environment pointer</i>.
 918     <p/>
 919     An environment pointer is a pointer to an environment and has
 920     the type <code>jvmtiEnv*</code>.
 921     An environment has information about its <jvmti/> connection.
 922     The first value in the environment is a pointer to the function table.
 923     The function table is an array of pointers to <jvmti/> functions.
 924     Every function pointer is at a predefined offset inside the
 925     array.
 926     <p/>
 927     When used from the C language:
 928     double indirection is used to access the functions;
 929     the environment pointer provides context and is the first
 930     parameter of each function call; for example:
 931     <example>
 932 jvmtiEnv *jvmti;
 933 ...
 934 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);
 935     </example>
 936     <p/>
 937     When used from the C++ language:
 938     functions are accessed as member functions of <code>jvmtiEnv</code>;
 939     the environment pointer is not passed to the function call; for example:
 940     <example>
 941 jvmtiEnv *jvmti;
 942 ...
 943 jvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);
 944     </example>
 945     Unless otherwise stated, all examples and declarations in this
 946     specification use the C language.
 947     <p/>
 948     A <jvmti/> environment can be obtained through the JNI Invocation API
 949     <code>GetEnv</code> function:
 950     <example>
 951 jvmtiEnv *jvmti;
 952 ...
 953 (*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);
 954     </example>
 955     Each call to <code>GetEnv</code>
 956     creates a new <jvmti/> connection and thus
 957     a new <jvmti/> environment.
 958     The <code>version</code> argument of <code>GetEnv</code> must be
 959     a <jvmti/> version.
 960     The returned environment may have a different version than the
 961     requested version but the returned environment must be compatible.
 962     <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a
 963     compatible version is not available, if <jvmti/> is not supported or
 964     <jvmti/> is not supported in the current VM configuration.
 965     Other interfaces may be added for creating <jvmti/> environments
 966     in specific contexts.
 967     Each environment has its own state (for example,
 968     <functionlink id="SetEventNotificationMode">desired events</functionlink>,
 969     <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and
 970     <functionlink id="AddCapabilities">capabilities</functionlink>).
 971     An environment is released with
 972     <functionlink id="DisposeEnvironment"></functionlink>.
 973     Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
 974     across threads and are created dynamically.
 975   </intro>
 976 
 977   <intro id="functionReturn" label="Function Return Values">
 978     <jvmti/> functions always return an
 979     <internallink id="ErrorSection">error code</internallink> via the
 980     <datalink id="jvmtiError"/> function return value.
 981     Some functions can return additional
 982     values through pointers provided by the calling function.
 983     In some cases, <jvmti/> functions allocate memory that your program must
 984     explicitly deallocate. This is indicated in the individual <jvmti/>
 985     function descriptions.  Empty lists, arrays, sequences, etc are
 986     returned as <code>NULL</code>.
 987     <p/>
 988     In the event that the <jvmti/> function encounters
 989     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
 990     of memory referenced by argument pointers is undefined, but no memory
 991     will have been allocated and no global references will have been allocated.
 992     If the error occurs because of invalid input, no action will have occurred.
 993   </intro>
 994 
 995 <intro id="refs" label="Managing JNI Object References">
 996     <jvmti/> functions identify objects with JNI references
 997     (<datalink id="jobject"/> and <datalink id="jclass"/>)
 998     and their derivatives
 999     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
1000     References passed to
1001     <jvmti/> functions can be either global or local, but they must be
1002     strong references. All references returned by <jvmti/> functions are
1003     local references--these local references are created
1004     during the <jvmti/> call.
1005     Local references are a resource that must be managed (see the
1006     <externallink id="jni/functions.html#local-references">
1007       JNI Documentation</externallink>).
1008     When threads return from native code all local references
1009     are freed.  Note that some threads, including typical
1010     agent threads, will never return from native code.
1011     A thread is ensured the ability to create sixteen local
1012     references without the need for any explicit management.
1013     For threads executing a limited number of <jvmti/> calls before
1014     returning from native code
1015     (for example, threads processing events),
1016     it may be determined that no explicit management
1017     is needed.
1018     However, long running agent threads will need explicit
1019     local reference management--usually with the JNI functions
1020     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
1021     Conversely, to preserve references beyond the
1022     return from native code, they must be converted to global references.
1023     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/>
1024     as they are not <datalink id="jobject"/>s.
1025 </intro>
1026 
1027     <intro id="prereqState" label="Prerequisite State for Calling Functions">
1028       Unless the function explicitly states that the agent must bring
1029       a thread or the VM to a particular state (for example, suspended),
1030       the <jvmti/> implementation is responsible for bringing the VM to a
1031       safe and consistent state for performing the function.
1032     </intro>
1033 
1034     <intro id="functionsExceptions" label="Exceptions and Functions">
1035       <jvmti/> functions never throw exceptions; error conditions are
1036       communicated via the
1037       <internallink id="functionReturn">function return value</internallink>.
1038       Any existing exception state is preserved across a call to a
1039       <jvmti/> function.
1040       See the
1041       <externallink
1042         id="jni/design.html#java-exceptions"
1043              >Java Exceptions</externallink>
1044       section of the JNI specification for information on handling exceptions.
1045     </intro>
1046 
1047   <category id="memory" label="Memory Management">
1048     <intro>
1049       These functions provide for the allocation and deallocation of
1050       memory used by <jvmti/> functionality and can be used to provide
1051       working memory for agents.
1052       Memory managed by <jvmti/> is not compatible with other memory
1053       allocation libraries and mechanisms.
1054     </intro>
1055 
1056     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
1057       <synopsis>Allocate</synopsis>
1058       <description>
1059         Allocate an area of memory through the <jvmti/> allocator.
1060         The allocated
1061         memory should be freed with <functionlink id="Deallocate"></functionlink>.
1062       </description>
1063       <origin>jvmdi</origin>
1064       <capabilities>
1065       </capabilities>
1066       <parameters>
1067         <param id="size">
1068           <jlong/>
1069           <description>
1070             The number of bytes to allocate.
1071             <rationale>
1072               <code>jlong</code> is used for compatibility with JVMDI.
1073             </rationale>
1074           </description>
1075         </param>
1076         <param id="mem_ptr">
1077           <allocbuf incount="size"><uchar/></allocbuf>
1078           <description>
1079             On return, a pointer to the beginning of the allocated memory.
1080             If <code>size</code> is zero, <code>NULL</code> is returned.
1081           </description>
1082         </param>
1083       </parameters>
1084       <errors>
1085         <error id="JVMTI_ERROR_OUT_OF_MEMORY">
1086           Memory request cannot be honored.
1087         </error>
1088         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
1089           <paramlink id="size"></paramlink> is less than zero.
1090         </error>
1091       </errors>
1092     </function>
1093 
1094     <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
1095       <synopsis>Deallocate</synopsis>
1096       <description>
1097         Deallocate <code>mem</code>  using the <jvmti/> allocator.
1098         This function should
1099         be used to deallocate any memory allocated and returned
1100         by a <jvmti/> function
1101         (including memory allocated with <functionlink id="Allocate"></functionlink>).
1102         All allocated memory must be deallocated
1103         or the memory cannot be reclaimed.
1104       </description>
1105       <origin>jvmdi</origin>
1106       <capabilities>
1107       </capabilities>
1108       <parameters>
1109         <param id="mem">
1110           <outbuf>
1111             <uchar/>
1112             <nullok>the call is ignored</nullok>
1113           </outbuf>
1114           <description>
1115             A pointer to the beginning of the allocated memory.
1116             Please ignore "On return, the elements are set."
1117               <todo>keep it from generating "On return, the elements are set"</todo>
1118           </description>
1119         </param>
1120       </parameters>
1121       <errors>
1122       </errors>
1123     </function>
1124   </category>
1125 
1126   <category id="threadCategory" label="Thread">
1127     <intro>
1128     </intro>
1129 
1130     <function id="GetThreadState" num="17">
1131       <synopsis>Get Thread State</synopsis>
1132       <description>
1133         Get the state of a thread.  The state of the thread is represented by the
1134         answers to the hierarchical set of questions below:
1135           <ul type="circle">
1136             <li><i>Alive?</i>
1137               <ul>
1138                 <li>Not alive.
1139                   <ul type="circle">
1140                     <li><i>Why not alive?</i>
1141                       <ul>
1142                         <li>New.</li>
1143                         <li>Terminated (<datalink
1144                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
1145                       </ul>
1146                     </li>
1147                   </ul>
1148                 </li>
1149                 <li>Alive (<datalink
1150                     id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
1151                   <ul type="circle">
1152                     <li><i>Suspended?</i>
1153                       <ul>
1154                         <li>Suspended (<datalink
1155                             id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
1156                         <li>Not suspended</li>
1157                       </ul>
1158                     </li>
1159                     <li><i>Interrupted?</i>
1160                       <ul>
1161                         <li>Interrupted (<datalink
1162                             id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
1163                         <li>Not interrupted.</li>
1164                       </ul>
1165                     </li>
1166                     <li><i>In native?</i>
1167                       <ul>
1168                         <li>In native code (<datalink
1169                             id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
1170                         <li>In Java programming language code</li>
1171                       </ul>
1172                     </li>
1173                     <li><i>What alive state?</i>
1174                       <ul>
1175                         <li>Runnable (<datalink
1176                             id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
1177                         <li>Blocked (<datalink
1178                             id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
1179                         <li>Waiting (<datalink
1180                             id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
1181                           <ul type="circle">
1182                             <li><i>Timed wait?</i>
1183                               <ul>
1184                                 <li>Indefinite (<datalink
1185                                     id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
1186                                 <li>Timed (<datalink
1187                                     id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
1188                               </ul>
1189                             </li>
1190                             <li><i>Why waiting?</i>
1191                               <ul>
1192                                 <li>Object.wait (<datalink
1193                                     id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
1194                                 <li>LockSupport.park (<datalink
1195                                     id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
1196                                 <li>Sleeping (<datalink
1197                                     id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
1198                               </ul>
1199                             </li>
1200                           </ul>
1201                         </li>
1202                       </ul>
1203                     </li>
1204                   </ul>
1205                 </li>
1206               </ul>
1207             </li>
1208           </ul>
1209         <p/>
1210         The answers are represented by the following bit vector.
1211         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
1212           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
1213             Thread is alive. Zero if thread is new (not started) or terminated.
1214           </constant>
1215           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
1216             Thread has completed execution.
1217           </constant>
1218           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
1219             Thread is runnable.
1220           </constant>
1221           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
1222             Thread is waiting to enter a synchronization block/method or,
1223             after an <code>Object.wait()</code>, waiting to re-enter a
1224             synchronization block/method.
1225           </constant>
1226           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
1227             Thread is waiting.
1228           </constant>
1229           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
1230             Thread is waiting without a timeout.
1231             For example, <code>Object.wait()</code>.
1232           </constant>
1233           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
1234             Thread is waiting with a maximum time to wait specified.
1235             For example, <code>Object.wait(long)</code>.
1236           </constant>
1237           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
1238             Thread is sleeping -- <code>Thread.sleep(long)</code>.
1239           </constant>
1240           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
1241             Thread is waiting on an object monitor -- <code>Object.wait</code>.
1242           </constant>
1243           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
1244             Thread is parked, for example: <code>LockSupport.park</code>,
1245             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
1246           </constant>
1247           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
1248             Thread suspended.
1249             <code>java.lang.Thread.suspend()</code>
1250             or a <jvmti/> suspend function
1251             (such as <functionlink id="SuspendThread"></functionlink>)
1252             has been called on the thread. If this bit
1253             is set, the other bits refer to the thread state before suspension.
1254           </constant>
1255           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
1256             Thread has been interrupted.
1257           </constant>
1258           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
1259             Thread is in native code--that is, a native method is running
1260             which has not called back into the VM or Java programming
1261             language code.
1262             <p/>
1263             This flag is not set when running VM compiled Java programming
1264             language code nor is it set when running VM code or
1265             VM support code. Native VM interface functions, such as JNI and
1266             <jvmti/> functions, may be implemented as VM code.
1267           </constant>
1268           <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
1269             Defined by VM vendor.
1270           </constant>
1271           <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
1272             Defined by VM vendor.
1273           </constant>
1274           <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
1275             Defined by VM vendor.
1276           </constant>
1277         </constants>
1278         The following definitions are used to convert <jvmti/> thread state
1279         to <code>java.lang.Thread.State</code> style states.
1280         <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
1281           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
1282                      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">
1283             Mask the state with this before comparison
1284           </constant>
1285           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
1286                      num="0">
1287             <code>java.lang.Thread.State.NEW</code>
1288           </constant>
1289           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
1290                      num="JVMTI_THREAD_STATE_TERMINATED">
1291             <code>java.lang.Thread.State.TERMINATED</code>
1292           </constant>
1293           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
1294                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
1295             <code>java.lang.Thread.State.RUNNABLE</code>
1296           </constant>
1297           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
1298                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
1299             <code>java.lang.Thread.State.BLOCKED</code>
1300           </constant>
1301           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
1302                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
1303             <code>java.lang.Thread.State.WAITING</code>
1304           </constant>
1305           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
1306                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
1307             <code>java.lang.Thread.State.TIMED_WAITING</code>
1308           </constant>
1309         </constants>
1310         <b>Rules</b>
1311         <p/>
1312         There can be no more than one answer to a question, although there can be no
1313         answer (because the answer is unknown, does not apply, or none of the answers is
1314         correct).  An answer is set only when the enclosing answers match.
1315         That is, no more than one of
1316           <ul type="circle">
1317               <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
1318               <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
1319               <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
1320           </ul>
1321         can be set (a <tm>J2SE</tm> compliant implementation will always set
1322         one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set).
1323         And if any of these are set, the enclosing answer
1324         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1325         No more than one of
1326           <ul type="circle">
1327               <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
1328               <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
1329           </ul>
1330         can be set (a <tm>J2SE</tm> compliant implementation will always set
1331         one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set).
1332         And if either is set, the enclosing answers
1333         <code>JVMTI_THREAD_STATE_ALIVE</code> and
1334         <code>JVMTI_THREAD_STATE_WAITING</code> are set.
1335         No more than one of
1336           <ul type="circle">
1337               <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
1338               <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
1339               <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
1340           </ul>
1341         can be set. And if any of these is set, the enclosing answers
1342         <code>JVMTI_THREAD_STATE_ALIVE</code> and
1343         <code>JVMTI_THREAD_STATE_WAITING</code> are set.
1344         Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
1345         then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
1346         If a state <i>A</i> is implemented using the mechanism of
1347         state <i>B</i> then it is state <i>A</i> which
1348         is returned by this function.
1349         For example, if <code>Thread.sleep(long)</code>
1350         is implemented using <code>Object.wait(long)</code>
1351         then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
1352         which is returned.
1353         More than one of
1354           <ul type="circle">
1355               <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
1356               <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
1357               <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
1358           </ul>
1359         can be set, but if any is set,
1360         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
1361         <p/>
1362         And finally,
1363         <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
1364         <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.
1365         <p/>
1366         The thread state representation is designed for extension in future versions
1367         of the specification; thread state values should be used accordingly, that is
1368         they should not be used as ordinals.
1369         Most queries can be made by testing a single bit, if use in a switch statement is desired,
1370         the state bits should be masked with the interesting bits.
1371         All bits not defined above are reserved for future use.
1372         A VM, compliant to the current specification, must set reserved bits to zero.
1373         An agent should ignore reserved bits --
1374         they should not be assumed to be zero and thus should not be included in comparisons.
1375         <p/>
1376         <b>Examples</b>
1377         <p/>
1378         Note that the values below exclude reserved and vendor bits.
1379         <p/>
1380         The state of a thread blocked at a <code>synchronized</code>-statement would be:
1381         <example>
1382             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
1383         </example>
1384         The state of a thread which hasn't started yet would be:
1385         <example>
1386             0
1387         </example>
1388         The state of a thread at a <code>Object.wait(3000)</code> would be:
1389         <example>
1390             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING +
1391                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT +
1392                 JVMTI_THREAD_STATE_MONITOR_WAITING
1393         </example>
1394         The state of a thread suspended while runnable would be:
1395         <example>
1396             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
1397         </example>
1398         <p/>
1399         <b>Testing the State</b>
1400         <p/>
1401         In most cases, the thread state can be determined by testing the one bit corresponding
1402         to that question.  For example, the code to test if a thread is sleeping:
1403         <example>
1404         jint state;
1405         jvmtiError err;
1406 
1407         err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1408         if (err == JVMTI_ERROR_NONE) {
1409            if (state &amp; JVMTI_THREAD_STATE_SLEEPING) {  ...
1410         </example>
1411         <p/>
1412         For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
1413         <example>
1414            if (state &amp; JVMTI_THREAD_STATE_WAITING) {  ...
1415         </example>
1416         For some states, more than one bit will need to be tested as is the case
1417         when testing if a thread has not yet been started:
1418         <example>
1419            if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
1420         </example>
1421         To distinguish timed from untimed <code>Object.wait</code>:
1422         <example>
1423            if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {
1424              if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
1425                printf("in Object.wait(long timeout)\n");
1426              } else {
1427                printf("in Object.wait()\n");
1428              }
1429            }
1430         </example>
1431         <p/>
1432         <b>Relationship to <code>java.lang.Thread.State</code></b>
1433         <p/>
1434         The thread state represented by <code>java.lang.Thread.State</code>
1435         returned from <code>java.lang.Thread.getState()</code> is a subset of the
1436         information returned from this function.
1437         The corresponding <code>java.lang.Thread.State</code> can be determined
1438         by using the provided conversion masks.
1439         For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
1440         <example>
1441             err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
1442             abortOnError(err);
1443             switch (state &amp; JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
1444             case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
1445               return "NEW";
1446             case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
1447               return "TERMINATED";
1448             case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
1449               return "RUNNABLE";
1450             case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
1451               return "BLOCKED";
1452             case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
1453               return "WAITING";
1454             case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
1455               return "TIMED_WAITING";
1456             }
1457         </example>
1458       </description>
1459       <origin>new</origin>
1460       <capabilities>
1461       </capabilities>
1462       <parameters>
1463         <param id="thread">
1464           <jthread null="current" started="maybe" impl="noconvert"/>
1465             <description>
1466               The thread to query.
1467             </description>
1468         </param>
1469         <param id="thread_state_ptr">
1470           <outptr><jint/></outptr>
1471           <description>
1472             On return, points to state flags,
1473             as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
1474           </description>
1475         </param>
1476       </parameters>
1477       <errors>
1478       </errors>
1479     </function>
1480 
1481     <function id="GetCurrentThread" phase="start" num="18" since="1.1">
1482       <synopsis>Get Current Thread</synopsis>
1483       <description>
1484         Get the current thread.
1485         The current thread is the Java programming language thread which has called the function.
1486         The function may return <code>NULL</code> in the start phase if the
1487         <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
1488         <code>can_generate_early_vmstart</code></internallink> capability is enabled
1489         and the <code>java.lang.Thread</code> class has not been initialized yet.
1490         <p/>
1491         Note that most <jvmti/> functions that take a thread
1492         as an argument will accept <code>NULL</code> to mean
1493         the current thread.
1494       </description>
1495       <origin>new</origin>
1496       <capabilities>
1497       </capabilities>
1498       <parameters>
1499         <param id="thread_ptr">
1500           <outptr><jthread/></outptr>
1501           <description>
1502              On return, points to the current thread, or <code>NULL</code>.
1503           </description>
1504         </param>
1505       </parameters>
1506       <errors>
1507       </errors>
1508     </function>
1509 
1510     <function id="GetAllThreads" num="4">
1511       <synopsis>Get All Threads</synopsis>
1512       <description>
1513         Get all live threads.
1514         The threads are Java programming language threads;
1515         that is, threads that are attached to the VM.
1516         A thread is live if <code>java.lang.Thread.isAlive()</code>
1517         would return <code>true</code>, that is, the thread has
1518         been started and has not yet died.
1519         The universe of threads is determined by the context of the <jvmti/>
1520         environment, which typically is all threads attached to the VM.
1521         Note that this includes <jvmti/> agent threads
1522         (see <functionlink id="RunAgentThread"/>).
1523       </description>
1524       <origin>jvmdi</origin>
1525       <capabilities>
1526       </capabilities>
1527       <parameters>
1528         <param id="threads_count_ptr">
1529           <outptr><jint/></outptr>
1530           <description>
1531             On return, points to the number of running threads.
1532           </description>
1533         </param>
1534         <param id="threads_ptr">
1535           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
1536             <description>
1537               On return, points to an array of references, one
1538               for each running thread.
1539             </description>
1540         </param>
1541       </parameters>
1542       <errors>
1543       </errors>
1544     </function>
1545 
1546     <function id="SuspendThread" num="5">
1547       <synopsis>Suspend Thread</synopsis>
1548       <description>
1549         Suspend the specified thread. If the calling thread is specified,
1550         this function will not return until some other thread calls
1551         <functionlink id="ResumeThread"></functionlink>.
1552         If the thread is currently suspended, this function
1553         does nothing and returns an error.
1554       </description>
1555       <origin>jvmdi</origin>
1556       <capabilities>
1557         <required id="can_suspend"></required>
1558       </capabilities>
1559       <parameters>
1560         <param id="thread">
1561           <jthread null="current"/>
1562             <description>
1563               The thread to suspend.
1564             </description>
1565         </param>
1566       </parameters>
1567       <errors>
1568         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
1569           Thread already suspended.
1570         </error>
1571       </errors>
1572     </function>
1573 
1574     <elide>
1575     <function id="SuspendAllThreads" num="101">
1576       <synopsis>Suspend All Threads</synopsis>
1577       <description>
1578         <issue>
1579             There has been no explicit call for this function, and it will
1580             thus be removed if there is no interest.
1581         </issue>
1582         Suspend all live threads except:
1583         <ul>
1584           <li>already suspended threads</li>
1585           <li>those listed in <paramlink id="except_list"></paramlink></li>
1586           <li>certain system (non application) threads, as determined
1587             by the VM implementation</li>
1588         </ul>
1589         The threads are Java programming language threads;
1590         native threads which are not attached to the VM are not
1591         Java programming language threads.
1592         A thread is live if <code>java.lang.Thread.isAlive()</code>
1593         would return <code>true</code>, that is, the thread has
1594         been started and has not yet died.
1595         The universe of threads is determined
1596         by the context of the <jvmti/>
1597         environment, which, typically, is all threads attached to the VM,
1598         except critical VM internal threads and <jvmti/> agent threads
1599         (see <functionlink id="RunAgentThread"/>).
1600         <p/>
1601         If the calling thread is specified,
1602         all other threads are suspended first then the caller thread is suspended -
1603         this function will not return until some other thread calls
1604         <functionlink id="ResumeThread"></functionlink>.
1605         <p/>
1606         The list of actually
1607         suspended threads is returned in
1608         <paramlink id="suspended_list_ptr"></paramlink>.
1609         Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
1610         <functionlink id="ResumeThreadList"></functionlink>
1611         can be used to resume the suspended threads.
1612       </description>
1613       <origin>new</origin>
1614       <capabilities>
1615         <required id="can_suspend"></required>
1616       </capabilities>
1617       <parameters>
1618         <param id="except_count">
1619           <jint min="0"/>
1620           <description>
1621             The number of threads in the list of threads not to be suspended.
1622           </description>
1623         </param>
1624         <param id="except_list">
1625             <inbuf incount="except_count">
1626               <jthread/>
1627               <nullok>not an error if <code>except_count == 0</code></nullok>
1628             </inbuf>
1629             <description>
1630               The list of threads not to be suspended.
1631             </description>
1632         </param>
1633         <param id="suspended_count_ptr">
1634           <outptr><jint/></outptr>
1635           <description>
1636             On return, points to the number of threads suspended by this call.
1637           </description>
1638         </param>
1639         <param id="suspended_list_ptr">
1640           <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
1641             <description>
1642               On return, points to an array of references, one
1643               for each thread suspended.
1644             </description>
1645         </param>
1646       </parameters>
1647       <errors>
1648         <error id="JVMTI_ERROR_INVALID_THREAD">
1649           A thread in <paramlink id="except_list"></paramlink> was invalid.
1650         </error>
1651         <error id="JVMTI_ERROR_NULL_POINTER">
1652           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
1653           and <paramlink id="except_count"></paramlink> was non-zero.
1654         </error>
1655       </errors>
1656     </function>
1657     </elide>
1658 
1659     <function id="SuspendThreadList" num="92">
1660       <synopsis>Suspend Thread List</synopsis>
1661       <description>
1662         Suspend the <paramlink id="request_count"></paramlink>
1663         threads specified in the
1664         <paramlink id="request_list"></paramlink> array.
1665         Threads may be resumed with
1666         <functionlink id="ResumeThreadList"></functionlink> or
1667         <functionlink id="ResumeThread"></functionlink>.
1668         If the calling thread is specified in the
1669         <paramlink id="request_list"></paramlink> array, this function will
1670         not return until some other thread resumes it.
1671         Errors encountered in the suspension of a thread
1672         are returned in the <paramlink id="results"></paramlink>
1673         array, <b>not</b> in the return value of this function.
1674         Threads that are currently suspended do not change state.
1675       </description>
1676       <origin>jvmdi</origin>
1677       <capabilities>
1678         <required id="can_suspend"></required>
1679       </capabilities>
1680       <parameters>
1681         <param id="request_count">
1682           <jint min="0"/>
1683           <description>
1684             The number of threads to suspend.
1685           </description>
1686         </param>
1687         <param id="request_list">
1688           <inbuf incount="request_count"><jthread/></inbuf>
1689             <description>
1690               The list of threads to suspend.
1691             </description>
1692         </param>
1693         <param id="results">
1694           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1695           <description>
1696             An agent supplied array of
1697             <paramlink id="request_count"></paramlink> elements.
1698             On return, filled with the error code for
1699             the suspend of the corresponding thread.
1700             The error code will be
1701             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1702             if the thread was suspended by this call.
1703             Possible error codes are those specified
1704             for <functionlink id="SuspendThread"></functionlink>.
1705           </description>
1706         </param>
1707       </parameters>
1708       <errors>
1709       </errors>
1710     </function>
1711 
1712     <function id="ResumeThread" num="6">
1713       <synopsis>Resume Thread</synopsis>
1714       <description>
1715         Resume a suspended thread.
1716         Any threads currently suspended through
1717         a <jvmti/> suspend function (eg.
1718         <functionlink id="SuspendThread"></functionlink>)
1719         or <code>java.lang.Thread.suspend()</code>
1720         will resume execution;
1721         all other threads are unaffected.
1722       </description>
1723       <origin>jvmdi</origin>
1724       <capabilities>
1725         <required id="can_suspend"></required>
1726       </capabilities>
1727       <parameters>
1728         <param id="thread">
1729           <jthread/>
1730             <description>
1731               The thread to resume.
1732             </description>
1733         </param>
1734       </parameters>
1735       <errors>
1736         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
1737           Thread was not suspended.
1738         </error>
1739         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
1740           The state of the thread has been modified, and is now inconsistent.
1741         </error>
1742       </errors>
1743     </function>
1744 
1745     <function id="ResumeThreadList" num="93">
1746       <synopsis>Resume Thread List</synopsis>
1747       <description>
1748         Resume the <paramlink id="request_count"></paramlink>
1749         threads specified in the
1750         <paramlink id="request_list"></paramlink> array.
1751         Any thread suspended through
1752         a <jvmti/> suspend function (eg.
1753         <functionlink id="SuspendThreadList"></functionlink>)
1754         or <code>java.lang.Thread.suspend()</code>
1755         will resume execution.
1756       </description>
1757       <origin>jvmdi</origin>
1758       <capabilities>
1759         <required id="can_suspend"></required>
1760       </capabilities>
1761       <parameters>
1762         <param id="request_count">
1763           <jint min="0"/>
1764           <description>
1765             The number of threads to resume.
1766           </description>
1767         </param>
1768         <param id="request_list">
1769           <inbuf incount="request_count"><jthread/></inbuf>
1770             <description>
1771               The threads to resume.
1772             </description>
1773         </param>
1774         <param id="results">
1775           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
1776           <description>
1777             An agent supplied array of
1778             <paramlink id="request_count"></paramlink> elements.
1779             On return, filled with the error code for
1780             the resume of the corresponding thread.
1781             The error code will be
1782             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
1783             if the thread was suspended by this call.
1784             Possible error codes are those specified
1785             for <functionlink id="ResumeThread"></functionlink>.
1786           </description>
1787         </param>
1788       </parameters>
1789       <errors>
1790       </errors>
1791     </function>
1792 
1793     <function id="StopThread" num="7">
1794       <synopsis>Stop Thread</synopsis>
1795       <description>
1796         Send the specified asynchronous exception to the specified thread.
1797         Normally, this function is used to kill the specified thread with an
1798         instance of the exception <code>ThreadDeath</code>, similar to
1799         <code>java.lang.Thread.stop</code>.
1800       </description>
1801       <origin>jvmdi</origin>
1802       <capabilities>
1803         <required id="can_signal_thread"></required>
1804       </capabilities>
1805       <parameters>
1806         <param id="thread">
1807           <jthread/>
1808             <description>
1809               The thread to stop.
1810             </description>
1811         </param>
1812         <param id="exception">
1813           <jobject/>
1814             <description>
1815               The asynchronous exception object.
1816             </description>
1817         </param>
1818       </parameters>
1819       <errors>
1820       </errors>
1821     </function>
1822 
1823     <function id="InterruptThread" num="8">
1824       <synopsis>Interrupt Thread</synopsis>
1825       <description>
1826         Interrupt the specified thread
1827         (similar to <code>java.lang.Thread.interrupt</code>).
1828       </description>
1829       <origin>jvmdi</origin>
1830       <capabilities>
1831         <required id="can_signal_thread"></required>
1832       </capabilities>
1833       <parameters>
1834         <param id="thread">
1835           <jthread impl="noconvert"/>
1836             <description>
1837               The thread to interrupt.
1838             </description>
1839         </param>
1840       </parameters>
1841       <errors>
1842       </errors>
1843     </function>
1844 
1845     <function id="GetThreadInfo" num="9">
1846       <synopsis>Get Thread Info</synopsis>
1847       <typedef id="jvmtiThreadInfo" label="Thread information structure">
1848         <field id="name">
1849           <allocfieldbuf><char/></allocfieldbuf>
1850           <description>
1851             The thread name, encoded as a
1852             <internallink id="mUTF">modified UTF-8</internallink> string.
1853           </description>
1854         </field>
1855         <field id="priority">
1856           <jint/>
1857           <description>
1858             The thread priority.  See the thread priority constants:
1859             <datalink id="jvmtiThreadPriority"></datalink>.
1860           </description>
1861         </field>
1862         <field id="is_daemon">
1863           <jboolean/>
1864           <description>
1865             Is this a daemon thread?
1866           </description>
1867         </field>
1868         <field id="thread_group">
1869           <jthreadGroup/>
1870           <description>
1871             The thread group to which this thread belongs.
1872             <code>NULL</code> if the thread has died.
1873           </description>
1874         </field>
1875         <field id="context_class_loader">
1876           <jobject/>
1877             <description>
1878               The context class loader associated with this thread.
1879             </description>
1880         </field>
1881       </typedef>
1882       <description>
1883         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure
1884         are filled in with details of the specified thread.
1885       </description>
1886       <origin>jvmdi</origin>
1887       <capabilities>
1888       </capabilities>
1889       <parameters>
1890         <param id="thread">
1891           <jthread null="current" impl="noconvert" started="maybe"/>
1892             <description>
1893               The thread to query.
1894             </description>
1895         </param>
1896         <param id="info_ptr">
1897           <outptr><struct>jvmtiThreadInfo</struct></outptr>
1898           <description>
1899             On return, filled with information describing the specified thread.
1900           </description>
1901         </param>
1902       </parameters>
1903       <errors>
1904       </errors>
1905     </function>
1906 
1907     <function id="GetOwnedMonitorInfo" num="10">
1908       <synopsis>Get Owned Monitor Info</synopsis>
1909       <description>
1910         Get information about the monitors owned by the
1911         specified thread.
1912       </description>
1913       <origin>jvmdiClone</origin>
1914       <capabilities>
1915         <required id="can_get_owned_monitor_info"></required>
1916       </capabilities>
1917       <parameters>
1918         <param id="thread">
1919           <jthread null="current"/>
1920             <description>
1921               The thread to query.
1922             </description>
1923         </param>
1924         <param id="owned_monitor_count_ptr">
1925           <outptr><jint/></outptr>
1926           <description>
1927             The number of monitors returned.
1928           </description>
1929         </param>
1930         <param id="owned_monitors_ptr">
1931           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
1932             <description>
1933               The array of owned monitors.
1934             </description>
1935         </param>
1936       </parameters>
1937       <errors>
1938       </errors>
1939     </function>
1940 
1941     <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
1942       <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
1943       <typedef id="jvmtiMonitorStackDepthInfo"
1944                label="Monitor stack depth information structure">
1945         <field id="monitor">
1946           <jobject/>
1947             <description>
1948               The owned monitor.
1949             </description>
1950         </field>
1951         <field id="stack_depth">
1952           <jint/>
1953           <description>
1954             The stack depth.  Corresponds to the stack depth used in the
1955             <internallink id="stack">Stack Frame functions</internallink>.
1956             That is, zero is the current frame, one is the frame which
1957             called the current frame. And it is negative one if the
1958             implementation cannot determine the stack depth (e.g., for
1959             monitors acquired by JNI <code>MonitorEnter</code>).
1960           </description>
1961         </field>
1962       </typedef>
1963       <description>
1964         Get information about the monitors owned by the
1965         specified thread and the depth of the stack frame which locked them.
1966       </description>
1967       <origin>new</origin>
1968       <capabilities>
1969         <required id="can_get_owned_monitor_stack_depth_info"></required>
1970       </capabilities>
1971       <parameters>
1972         <param id="thread">
1973           <jthread null="current"/>
1974             <description>
1975               The thread to query.
1976             </description>
1977         </param>
1978         <param id="monitor_info_count_ptr">
1979           <outptr><jint/></outptr>
1980           <description>
1981             The number of monitors returned.
1982           </description>
1983         </param>
1984         <param id="monitor_info_ptr">
1985           <allocbuf outcount="monitor_info_count_ptr">
1986             <struct>jvmtiMonitorStackDepthInfo</struct>
1987           </allocbuf>
1988           <description>
1989             The array of owned monitor depth information.
1990           </description>
1991         </param>
1992       </parameters>
1993       <errors>
1994       </errors>
1995     </function>
1996 
1997     <function id="GetCurrentContendedMonitor" num="11">
1998       <synopsis>Get Current Contended Monitor</synopsis>
1999       <description>
2000         Get the object, if any, whose monitor the specified thread is waiting to
2001         enter or waiting to regain through <code>java.lang.Object.wait</code>.
2002       </description>
2003       <origin>jvmdi</origin>
2004       <capabilities>
2005         <required id="can_get_current_contended_monitor"></required>
2006       </capabilities>
2007       <parameters>
2008         <param id="thread">
2009           <jthread null="current"/>
2010             <description>
2011               The thread to query.
2012             </description>
2013         </param>
2014         <param id="monitor_ptr">
2015           <outptr><jobject/></outptr>
2016             <description>
2017               On return, filled with the current contended monitor, or
2018               NULL if there is none.
2019             </description>
2020         </param>
2021       </parameters>
2022       <errors>
2023       </errors>
2024     </function>
2025 
2026     <callback id="jvmtiStartFunction">
2027       <void/>
2028       <synopsis>Agent Start Function</synopsis>
2029       <description>
2030         Agent supplied callback function.
2031         This function is the entry point for an agent thread
2032         started with
2033         <functionlink id="RunAgentThread"></functionlink>.
2034       </description>
2035       <parameters>
2036           <param id="jvmti_env">
2037             <outptr>
2038               <struct>jvmtiEnv</struct>
2039             </outptr>
2040             <description>
2041               The <jvmti/> environment.
2042             </description>
2043           </param>
2044           <param id="jni_env">
2045             <outptr>
2046               <struct>JNIEnv</struct>
2047             </outptr>
2048             <description>
2049               The JNI environment.
2050             </description>
2051           </param>
2052           <param id="arg">
2053             <outptr>
2054               <void/>
2055             </outptr>
2056               <description>
2057                 The <code>arg</code> parameter passed to
2058                 <functionlink id="RunAgentThread"></functionlink>.
2059               </description>
2060           </param>
2061       </parameters>
2062     </callback>
2063 
2064     <function id="RunAgentThread" num="12">
2065       <synopsis>Run Agent Thread</synopsis>
2066       <description>
2067         Starts the execution of an agent thread. with the specified native function.
2068         The parameter <paramlink id="arg"></paramlink> is forwarded on to the
2069         <functionlink id="jvmtiStartFunction">start function</functionlink>
2070         (specified with <paramlink id="proc"></paramlink>) as its single argument.
2071         This function allows the creation of agent threads
2072         for handling communication with another process or for handling events
2073         without the need to load a special subclass of <code>java.lang.Thread</code> or
2074         implementer of <code>java.lang.Runnable</code>.
2075         Instead, the created thread can run entirely in native code.
2076         However, the created thread does require a newly created instance
2077         of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to
2078         which it will be associated.
2079         The thread object can be created with JNI calls.
2080         <p/>
2081         The following common thread priorities are provided for your convenience:
2082         <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
2083           <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
2084             Minimum possible thread priority
2085           </constant>
2086           <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
2087             Normal thread priority
2088           </constant>
2089           <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
2090             Maximum possible thread priority
2091           </constant>
2092         </constants>
2093         <p/>
2094         The new thread is started as a daemon thread with the specified
2095         <paramlink id="priority"></paramlink>.
2096         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
2097         <p/>
2098         Since the thread has been started, the thread will be live when this function
2099         returns, unless the thread has died immediately.
2100         <p/>
2101         The thread group of the thread is ignored -- specifically, the thread is not
2102         added to the thread group and the thread is not seen on queries of the thread
2103         group at either the Java programming language or <jvmti/> levels.
2104         <p/>
2105         The thread is not visible to Java programming language queries but is
2106         included in <jvmti/> queries (for example,
2107         <functionlink id="GetAllThreads"/> and
2108         <functionlink id="GetAllStackTraces"/>).
2109         <p/>
2110         Upon execution of <code>proc</code>, the new thread will be attached to the
2111         VM -- see the JNI documentation on
2112         <externallink id="jni/invocation.html#attaching-to-the-vm"
2113                       >Attaching to the VM</externallink>.
2114       </description>
2115       <origin>jvmdiClone</origin>
2116       <capabilities>
2117       </capabilities>
2118       <parameters>
2119         <param id="thread">
2120           <jthread impl="noconvert" started="no"/>
2121             <description>
2122               The thread to run.
2123             </description>
2124         </param>
2125         <param id="proc">
2126           <ptrtype>
2127             <struct>jvmtiStartFunction</struct>
2128           </ptrtype>
2129           <description>
2130             The start function.
2131           </description>
2132         </param>
2133         <param id="arg">
2134           <inbuf>
2135             <void/>
2136             <nullok><code>NULL</code> is passed to the start function</nullok>
2137           </inbuf>
2138           <description>
2139             The argument to the start function.
2140           </description>
2141         </param>
2142         <param id="priority">
2143           <jint/>
2144           <description>
2145             The priority of the started thread. Any thread
2146             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
2147             those in <datalink id="jvmtiThreadPriority"></datalink>.
2148           </description>
2149         </param>
2150       </parameters>
2151       <errors>
2152         <error id="JVMTI_ERROR_INVALID_PRIORITY">
2153             <paramlink id="priority"/> is less than
2154             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
2155               or greater than
2156             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
2157         </error>
2158       </errors>
2159     </function>
2160 
2161     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
2162       <synopsis>Set Thread Local Storage</synopsis>
2163       <description>
2164         The VM stores a pointer value associated with each environment-thread
2165         pair. This pointer value is called <i>thread-local storage</i>.
2166         This value is <code>NULL</code> unless set with this function.
2167         Agents can allocate memory in which they store thread specific
2168         information. By setting thread-local storage it can then be
2169         accessed with
2170         <functionlink id="GetThreadLocalStorage"></functionlink>.
2171         <p/>
2172         This function is called by the agent to set the value of the <jvmti/>
2173         thread-local storage. <jvmti/> supplies to the agent a pointer-size
2174         thread-local storage that can be used to record per-thread
2175         information.
2176       </description>
2177       <origin>jvmpi</origin>
2178       <capabilities>
2179       </capabilities>
2180       <parameters>
2181         <param id="thread">
2182           <jthread null="current"/>
2183             <description>
2184               Store to this thread.
2185             </description>
2186         </param>
2187         <param id="data">
2188           <inbuf>
2189             <void/>
2190             <nullok>value is set to <code>NULL</code></nullok>
2191           </inbuf>
2192           <description>
2193             The value to be entered into the thread-local storage.
2194           </description>
2195         </param>
2196       </parameters>
2197       <errors>
2198       </errors>
2199     </function>
2200 
2201     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
2202       <synopsis>Get Thread Local Storage</synopsis>
2203       <description>
2204         Called by the agent to get the value of the <jvmti/> thread-local
2205         storage.
2206       </description>
2207       <origin>jvmpi</origin>
2208       <capabilities>
2209       </capabilities>
2210       <parameters>
2211         <param id="thread">
2212           <jthread null="current" impl="noconvert"/>
2213             <description>
2214               Retrieve from this thread.
2215             </description>
2216         </param>
2217         <param id="data_ptr">
2218           <agentbuf><void/></agentbuf>
2219           <description>
2220             Pointer through which the value of the thread local
2221             storage is returned.
2222             If thread-local storage has not been set with
2223             <functionlink id="SetThreadLocalStorage"></functionlink> the returned
2224             pointer is <code>NULL</code>.
2225           </description>
2226         </param>
2227       </parameters>
2228       <errors>
2229       </errors>
2230     </function>
2231 
2232   </category>
2233 
2234   <category id="thread_groups" label="Thread Group">
2235     <intro>
2236     </intro>
2237 
2238     <function id="GetTopThreadGroups" num="13">
2239       <synopsis>Get Top Thread Groups</synopsis>
2240       <description>
2241         Return all top-level (parentless) thread groups in the VM.
2242       </description>
2243       <origin>jvmdi</origin>
2244       <capabilities>
2245       </capabilities>
2246       <parameters>
2247         <param id="group_count_ptr">
2248           <outptr><jint/></outptr>
2249           <description>
2250             On return, points to the number of top-level thread groups.
2251           </description>
2252         </param>
2253         <param id="groups_ptr">
2254           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2255             <description>
2256               On return, refers to a pointer to the top-level thread group array.
2257             </description>
2258         </param>
2259       </parameters>
2260       <errors>
2261       </errors>
2262     </function>
2263 
2264     <function id="GetThreadGroupInfo" num="14">
2265       <synopsis>Get Thread Group Info</synopsis>
2266       <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
2267         <field id="parent">
2268           <jthreadGroup/>
2269           <description>
2270             The parent thread group.
2271           </description>
2272         </field>
2273         <field id="name">
2274           <allocfieldbuf><char/></allocfieldbuf>
2275           <description>
2276             The thread group's name, encoded as a
2277             <internallink id="mUTF">modified UTF-8</internallink> string.
2278           </description>
2279         </field>
2280         <field id="max_priority">
2281           <jint/>
2282           <description>
2283             The maximum priority for this thread group.
2284           </description>
2285         </field>
2286         <field id="is_daemon">
2287           <jboolean/>
2288           <description>
2289             Is this a daemon thread group?
2290           </description>
2291         </field>
2292       </typedef>
2293       <description>
2294         Get information about the thread group. The fields of the
2295         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure
2296         are filled in with details of the specified thread group.
2297       </description>
2298       <origin>jvmdi</origin>
2299       <capabilities>
2300       </capabilities>
2301       <parameters>
2302         <param id="group">
2303           <jthreadGroup/>
2304           <description>
2305             The thread group to query.
2306           </description>
2307         </param>
2308         <param id="info_ptr">
2309           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
2310           <description>
2311             On return, filled with information describing the specified
2312             thread group.
2313           </description>
2314         </param>
2315       </parameters>
2316       <errors>
2317       </errors>
2318     </function>
2319 
2320     <function id="GetThreadGroupChildren" num="15">
2321       <synopsis>Get Thread Group Children</synopsis>
2322       <description>
2323         Get the live threads and active subgroups in this thread group.
2324       </description>
2325       <origin>jvmdi</origin>
2326       <capabilities>
2327       </capabilities>
2328       <parameters>
2329         <param id="group">
2330           <jthreadGroup/>
2331           <description>
2332             The group to query.
2333           </description>
2334         </param>
2335         <param id="thread_count_ptr">
2336           <outptr><jint/></outptr>
2337           <description>
2338             On return, points to the number of live threads in this thread group.
2339           </description>
2340         </param>
2341         <param id="threads_ptr">
2342           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
2343             <description>
2344               On return, points to an array of the live threads in this thread group.
2345             </description>
2346         </param>
2347         <param id="group_count_ptr">
2348           <outptr><jint/></outptr>
2349           <description>
2350             On return, points to the number of active child thread groups
2351           </description>
2352         </param>
2353         <param id="groups_ptr">
2354           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
2355             <description>
2356               On return, points to an array of the active child thread groups.
2357             </description>
2358         </param>
2359       </parameters>
2360       <errors>
2361       </errors>
2362     </function>
2363   </category>
2364 
2365   <category id="stack" label="Stack Frame">
2366     <intro>
2367         These functions provide information about the stack of a thread.
2368         Stack frames are referenced by depth.
2369         The frame at depth zero is the current frame.
2370         <p/>
2371         Stack frames are as described in
2372         <vmspec chapter="3.6"/>,
2373         That is, they correspond to method
2374         invocations (including native methods) but do not correspond to platform native or
2375         VM internal frames.
2376         <p/>
2377         A <jvmti/> implementation may use method invocations to launch a thread and
2378         the corresponding frames may be included in the stack as presented by these functions --
2379         that is, there may be frames shown
2380         deeper than <code>main()</code> and <code>run()</code>.
2381         However this presentation must be consistent across all <jvmti/> functionality which
2382         uses stack frames or stack depth.
2383     </intro>
2384 
2385       <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
2386         <description>
2387           Information about a stack frame is returned in this structure.
2388         </description>
2389         <field id="method">
2390           <jmethodID/>
2391             <description>
2392               The method executing in this frame.
2393             </description>
2394         </field>
2395         <field id="location">
2396           <jlocation/>
2397           <description>
2398             The index of the instruction executing in this frame.
2399             <code>-1</code> if the frame is executing a native method.
2400           </description>
2401         </field>
2402       </typedef>
2403 
2404       <typedef id="jvmtiStackInfo" label="Stack information structure">
2405         <description>
2406           Information about a set of stack frames is returned in this structure.
2407         </description>
2408         <field id="thread">
2409           <jthread/>
2410           <description>
2411             On return, the thread traced.
2412           </description>
2413         </field>
2414         <field id="state">
2415           <jint/>
2416           <description>
2417             On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
2418           </description>
2419         </field>
2420         <field id="frame_buffer">
2421           <outbuf incount="max_frame_count">
2422             <struct>jvmtiFrameInfo</struct>
2423           </outbuf>
2424             <description>
2425               On return, this agent allocated buffer is filled
2426               with stack frame information.
2427             </description>
2428         </field>
2429         <field id="frame_count">
2430           <jint/>
2431           <description>
2432             On return, the number of records filled into
2433             <code>frame_buffer</code>.
2434             This will be
2435             min(<code>max_frame_count</code>, <i>stackDepth</i>).
2436           </description>
2437         </field>
2438       </typedef>
2439 
2440     <function id="GetStackTrace" num="104">
2441       <synopsis>Get Stack Trace</synopsis>
2442       <description>
2443         Get information about the stack of a thread.
2444         If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
2445         the <paramlink id="max_frame_count"></paramlink> topmost frames are returned,
2446         otherwise the entire stack is returned.
2447         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2448         <p/>
2449         The following example causes up to five of the topmost frames
2450         to be returned and (if there are any frames) the currently
2451         executing method name to be printed.
2452         <example>
2453 jvmtiFrameInfo frames[5];
2454 jint count;
2455 jvmtiError err;
2456 
2457 err = (*jvmti)-&gt;GetStackTrace(jvmti, aThread, 0, 5,
2458                                frames, &amp;count);
2459 if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
2460    char *methodName;
2461    err = (*jvmti)-&gt;GetMethodName(jvmti, frames[0].method,
2462                        &amp;methodName, NULL, NULL);
2463    if (err == JVMTI_ERROR_NONE) {
2464       printf("Executing method: %s", methodName);
2465    }
2466 }
2467         </example>
2468         <todo>
2469           check example code.
2470         </todo>
2471         <p/>
2472         The <paramlink id="thread"></paramlink> need not be suspended
2473         to call this function.
2474         <p/>
2475         The <functionlink id="GetLineNumberTable"></functionlink>
2476         function can be used to map locations to line numbers. Note that
2477         this mapping can be done lazily.
2478       </description>
2479       <origin>jvmpi</origin>
2480       <capabilities>
2481       </capabilities>
2482       <parameters>
2483         <param id="thread">
2484           <jthread null="current"/>
2485             <description>
2486               Fetch the stack trace of this thread.
2487             </description>
2488         </param>
2489         <param id="start_depth">
2490           <jint/>
2491           <description>
2492             Begin retrieving frames at this depth.
2493             If non-negative, count from the current frame,
2494             the first frame retrieved is at depth <code>start_depth</code>.
2495             For example, if zero, start from the current frame; if one, start from the
2496             caller of the current frame; if two, start from the caller of the
2497             caller of the current frame; and so on.
2498             If negative, count from below the oldest frame,
2499             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,
2500             where <i>stackDepth</i> is the count of frames on the stack.
2501             For example, if negative one, only the oldest frame is retrieved;
2502             if negative two, start from the frame called by the oldest frame.
2503           </description>
2504         </param>
2505         <param id="max_frame_count">
2506           <jint min="0"/>
2507           <description>
2508             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2509           </description>
2510         </param>
2511         <param id="frame_buffer">
2512           <outbuf incount="max_frame_count" outcount="count_ptr">
2513             <struct>jvmtiFrameInfo</struct>
2514           </outbuf>
2515             <description>
2516               On return, this agent allocated buffer is filled
2517               with stack frame information.
2518             </description>
2519         </param>
2520         <param id="count_ptr">
2521           <outptr><jint/></outptr>
2522           <description>
2523             On return, points to the number of records filled in.
2524             For non-negative <code>start_depth</code>, this will be
2525             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
2526             For negative <code>start_depth</code>, this will be
2527             min(<code>max_frame_count</code>, <code>-start_depth</code>).
2528           </description>
2529         </param>
2530       </parameters>
2531       <errors>
2532         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
2533           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
2534           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
2535         </error>
2536       </errors>
2537     </function>
2538 
2539 
2540     <function id="GetAllStackTraces" num="100">
2541       <synopsis>Get All Stack Traces</synopsis>
2542       <description>
2543         Get information about the stacks of all live threads
2544         (including <internallink id="RunAgentThread">agent threads</internallink>).
2545         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2546         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
2547         otherwise the entire stack is returned.
2548         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2549         <p/>
2550         All stacks are collected simultaneously, that is, no changes will occur to the
2551         thread state or stacks between the sampling of one thread and the next.
2552         The threads need not be suspended.
2553 
2554         <example>
2555 jvmtiStackInfo *stack_info;
2556 jint thread_count;
2557 int ti;
2558 jvmtiError err;
2559 
2560 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count);
2561 if (err != JVMTI_ERROR_NONE) {
2562    ...
2563 }
2564 for (ti = 0; ti &lt; thread_count; ++ti) {
2565    jvmtiStackInfo *infop = &amp;stack_info[ti];
2566    jthread thread = infop-&gt;thread;
2567    jint state = infop-&gt;state;
2568    jvmtiFrameInfo *frames = infop-&gt;frame_buffer;
2569    int fi;
2570 
2571    myThreadAndStatePrinter(thread, state);
2572    for (fi = 0; fi &lt; infop-&gt;frame_count; fi++) {
2573       myFramePrinter(frames[fi].method, frames[fi].location);
2574    }
2575 }
2576 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
2577 err = (*jvmti)-&gt;Deallocate(jvmti, stack_info);
2578         </example>
2579         <todo>
2580           check example code.
2581         </todo>
2582 
2583       </description>
2584       <origin>new</origin>
2585       <capabilities>
2586       </capabilities>
2587       <parameters>
2588         <param id="max_frame_count">
2589           <jint min="0"/>
2590           <description>
2591             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2592           </description>
2593         </param>
2594         <param id="stack_info_ptr">
2595           <allocbuf>
2596             <struct>jvmtiStackInfo</struct>
2597           </allocbuf>
2598             <description>
2599               On return, this buffer is filled
2600               with stack information for each thread.
2601               The number of <datalink id="jvmtiStackInfo"/> records is determined
2602               by <paramlink id="thread_count_ptr"/>.
2603               <p/>
2604               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
2605               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2606               These buffers must not be separately deallocated.
2607             </description>
2608         </param>
2609         <param id="thread_count_ptr">
2610           <outptr><jint/></outptr>
2611           <description>
2612             The number of threads traced.
2613           </description>
2614         </param>
2615       </parameters>
2616       <errors>
2617       </errors>
2618     </function>
2619 
2620     <function id="GetThreadListStackTraces" num="101">
2621       <synopsis>Get Thread List Stack Traces</synopsis>
2622       <description>
2623         Get information about the stacks of the supplied threads.
2624         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
2625         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
2626         otherwise the entire stack is returned.
2627         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
2628         <p/>
2629         All stacks are collected simultaneously, that is, no changes will occur to the
2630         thread state or stacks between the sampling one thread and the next.
2631         The threads need not be suspended.
2632         <p/>
2633         If a thread has not yet started or terminates before the stack information is collected,
2634         a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
2635         will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
2636         <p/>
2637         See the example for the similar function
2638         <functionlink id="GetAllStackTraces"/>.
2639       </description>
2640       <origin>new</origin>
2641       <capabilities>
2642       </capabilities>
2643       <parameters>
2644         <param id="thread_count">
2645           <jint min="0"/>
2646           <description>
2647             The number of threads to trace.
2648           </description>
2649         </param>
2650         <param id="thread_list">
2651           <inbuf incount="thread_count"><jthread/></inbuf>
2652             <description>
2653               The list of threads to trace.
2654             </description>
2655         </param>
2656         <param id="max_frame_count">
2657           <jint min="0"/>
2658           <description>
2659             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
2660           </description>
2661         </param>
2662         <param id="stack_info_ptr">
2663           <allocbuf outcount="thread_count">
2664             <struct>jvmtiStackInfo</struct>
2665           </allocbuf>
2666             <description>
2667               On return, this buffer is filled
2668               with stack information for each thread.
2669               The number of <datalink id="jvmtiStackInfo"/> records is determined
2670               by <paramlink id="thread_count"/>.
2671               <p/>
2672               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
2673               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
2674               These buffers must not be separately deallocated.
2675             </description>
2676         </param>
2677       </parameters>
2678       <errors>
2679         <error id="JVMTI_ERROR_INVALID_THREAD">
2680           An element in <paramlink id="thread_list"/> is not a thread object.
2681         </error>
2682       </errors>
2683     </function>
2684 
2685     <elide>
2686     <function id="AsyncGetStackTrace" num="1000">
2687       <synopsis>Get Stack Trace--Asynchronous</synopsis>
2688       <description>
2689         Get information about the entire stack of a thread (or a sub-section of it).
2690         This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
2691         and is reentrant and safe to call
2692         from asynchronous signal handlers.
2693         The stack trace is returned only for the calling thread.
2694         <p/>
2695         The <functionlink id="GetLineNumberTable"></functionlink>
2696         function can be used to map locations to line numbers. Note that
2697         this mapping can be done lazily.
2698       </description>
2699       <origin>jvmpi</origin>
2700       <capabilities>
2701         <required id="can_get_async_stack_trace"></required>
2702         <capability id="can_show_JVM_spec_async_frames">
2703           If <code>false</code>,
2704           <paramlink id="use_java_stack"></paramlink>
2705           must be <code>false</code>.
2706         </capability>
2707       </capabilities>
2708       <parameters>
2709         <param id="use_java_stack">
2710           <jboolean/>
2711           <description>
2712             Return the stack showing <vmspec/>
2713             model of the stack;
2714             otherwise, show the internal representation of the stack with
2715             inlined and optimized methods missing.  If the virtual machine
2716             is using the <i>Java Virtual Machine Specification</i> stack model
2717             internally, this flag is ignored.
2718           </description>
2719         </param>
2720         <param id="max_count">
2721           <jint min="0"/>
2722           <description>
2723             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
2724             Retrieve this many unless the stack depth is less than <code>max_count</code>.
2725           </description>
2726         </param>
2727         <param id="frame_buffer">
2728           <outbuf incount="max_count" outcount="count_ptr">
2729             <struct>jvmtiFrameInfo</struct>
2730             <nullok>this information is not returned</nullok>
2731           </outbuf>
2732             <description>
2733               The agent passes in a buffer
2734               large enough to hold <code>max_count</code> records of
2735               <datalink id="jvmtiFrameInfo"></datalink>.  This buffer must be
2736               pre-allocated by the agent.
2737             </description>
2738         </param>
2739         <param id="count_ptr">
2740           <outptr><jint/></outptr>
2741           <description>
2742             On return, points to the number of records filled in..
2743           </description>
2744         </param>
2745       </parameters>
2746       <errors>
2747         <error id="JVMTI_ERROR_UNATTACHED_THREAD">
2748           The thread being used to call this function is not attached
2749           to the virtual machine.  Calls must be made from attached threads.
2750         </error>
2751       </errors>
2752     </function>
2753     </elide>
2754 
2755     <function id="GetFrameCount" num="16">
2756       <synopsis>Get Frame Count</synopsis>
2757       <description>
2758         Get the number of frames currently in the specified thread's call stack.
2759         <p/>
2760         If this function is called for a thread actively executing bytecodes (for example,
2761         not the current thread and not suspended), the information returned is transient.
2762       </description>
2763       <origin>jvmdi</origin>
2764       <capabilities>
2765       </capabilities>
2766       <parameters>
2767         <param id="thread">
2768           <jthread null="current"/>
2769             <description>
2770               The thread to query.
2771             </description>
2772         </param>
2773         <param id="count_ptr">
2774           <outptr><jint/></outptr>
2775           <description>
2776             On return, points to the number of frames in the call stack.
2777           </description>
2778         </param>
2779       </parameters>
2780       <errors>
2781       </errors>
2782     </function>
2783 
2784     <function id="PopFrame" num="80">
2785       <synopsis>Pop Frame</synopsis>
2786       <description>
2787         Pop the current frame of <code>thread</code>'s stack.
2788         Popping a frame takes you to the previous frame.
2789         When the thread is resumed, the execution
2790         state of the thread is reset to the state
2791         immediately before the called method was invoked.
2792         That is (using <vmspec/> terminology):
2793           <ul>
2794             <li>the current frame is discarded as the previous frame becomes the current one</li>
2795             <li>the operand stack is restored--the argument values are added back
2796               and if the invoke was not <code>invokestatic</code>,
2797               <code>objectref</code> is added back as well</li>
2798             <li>the Java virtual machine PC is restored to the opcode
2799               of the invoke instruction</li>
2800           </ul>
2801         Note however, that any changes to the arguments, which
2802         occurred in the called method, remain;
2803         when execution continues, the first instruction to
2804         execute will be the invoke.
2805         <p/>
2806         Between calling <code>PopFrame</code> and resuming the
2807         thread the state of the stack is undefined.
2808         To pop frames beyond the first,
2809         these three steps must be repeated:
2810         <ul>
2811           <li>suspend the thread via an event (step, breakpoint, ...)</li>
2812           <li>call <code>PopFrame</code></li>
2813           <li>resume the thread</li>
2814         </ul>
2815         <p/>
2816         A lock acquired by calling the called method
2817         (if it is a <code>synchronized</code>  method)
2818         and locks acquired by entering <code>synchronized</code>
2819         blocks within the called method are released.
2820         Note: this does not apply to native locks or
2821         <code>java.util.concurrent.locks</code> locks.
2822         <p/>
2823         Finally blocks are not executed.
2824         <p/>
2825         Changes to global state are not addressed and thus remain changed.
2826         <p/>
2827         The specified thread must be suspended (which implies it cannot be the current thread).
2828         <p/>
2829         Both the called method and calling method must be non-native Java programming
2830         language methods.
2831         <p/>
2832         No <jvmti/> events are generated by this function.
2833       </description>
2834       <origin>jvmdi</origin>
2835       <capabilities>
2836         <required id="can_pop_frame"></required>
2837       </capabilities>
2838       <parameters>
2839         <param id="thread">
2840           <jthread/>
2841             <description>
2842               The thread whose current frame is to be popped.
2843             </description>
2844         </param>
2845       </parameters>
2846       <errors>
2847         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2848           Called or calling method is a native method.
2849           The implementation is unable to pop this frame.
2850         </error>
2851         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2852           Thread was not suspended.
2853         </error>
2854         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
2855           There are less than two stack frames on the call stack.
2856         </error>
2857       </errors>
2858     </function>
2859 
2860     <function id="GetFrameLocation" num="19">
2861       <synopsis>Get Frame Location</synopsis>
2862       <description>
2863         <p/>
2864         For a Java programming language frame, return the location of the instruction
2865         currently executing.
2866       </description>
2867       <origin>jvmdiClone</origin>
2868       <capabilities>
2869       </capabilities>
2870       <parameters>
2871         <param id="thread">
2872           <jthread null="current" frame="frame"/>
2873           <description>
2874             The thread of the frame to query.
2875           </description>
2876         </param>
2877         <param id="depth">
2878           <jframeID thread="thread"/>
2879           <description>
2880             The depth of the frame to query.
2881           </description>
2882         </param>
2883         <param id="method_ptr">
2884           <outptr><jmethodID/></outptr>
2885             <description>
2886               On return, points to the method for the current location.
2887             </description>
2888         </param>
2889         <param id="location_ptr">
2890           <outptr><jlocation/></outptr>
2891           <description>
2892             On return, points to the index of the currently
2893             executing instruction.
2894             Is set to <code>-1</code> if the frame is executing
2895             a native method.
2896           </description>
2897         </param>
2898       </parameters>
2899       <errors>
2900       </errors>
2901     </function>
2902 
2903     <function id="NotifyFramePop" num="20">
2904       <synopsis>Notify Frame Pop</synopsis>
2905       <description>
2906         When the frame that is currently at <paramlink id="depth"></paramlink>
2907         is popped from the stack, generate a
2908         <eventlink id="FramePop"></eventlink> event.  See the
2909         <eventlink id="FramePop"></eventlink> event for details.
2910         Only frames corresponding to non-native Java programming language
2911         methods can receive notification.
2912         <p/>
2913         The specified thread must either be the current thread
2914         or the thread must be suspended.
2915       </description>
2916       <origin>jvmdi</origin>
2917       <capabilities>
2918         <required id="can_generate_frame_pop_events"></required>
2919       </capabilities>
2920       <parameters>
2921         <param id="thread">
2922           <jthread null="current" frame="depth"/>
2923           <description>
2924             The thread of the frame for which the frame pop event will be generated.
2925           </description>
2926         </param>
2927         <param id="depth">
2928           <jframeID thread="thread"/>
2929           <description>
2930             The depth of the frame for which the frame pop event will be generated.
2931           </description>
2932         </param>
2933       </parameters>
2934       <errors>
2935         <error id="JVMTI_ERROR_OPAQUE_FRAME">
2936           The frame at <code>depth</code> is executing a
2937           native method.
2938         </error>
2939         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
2940           Thread was not suspended and was not the current thread.
2941         </error>
2942       </errors>
2943     </function>
2944 
2945   </category>
2946 
2947   <category id="ForceEarlyReturn" label="Force Early Return">
2948     <intro>
2949       These functions allow an agent to force a method
2950       to return at any point during its execution.
2951       The method which will return early is referred to as the <i>called method</i>.
2952       The called method is the current method
2953       (as defined by
2954       <vmspec chapter="3.6"/>)
2955       for the specified thread at
2956       the time the function is called.
2957       <p/>
2958       The specified thread must be suspended or must be the current thread.
2959       The return occurs when execution of Java programming
2960       language code is resumed on this thread.
2961       Between calling one of these functions and resumption
2962       of thread execution, the state of the stack is undefined.
2963       <p/>
2964       No further instructions are executed in the called method.
2965       Specifically, finally blocks are not executed.
2966       Note: this can cause inconsistent states in the application.
2967       <p/>
2968       A lock acquired by calling the called method
2969       (if it is a <code>synchronized</code>  method)
2970       and locks acquired by entering <code>synchronized</code>
2971       blocks within the called method are released.
2972       Note: this does not apply to native locks or
2973       <code>java.util.concurrent.locks</code> locks.
2974       <p/>
2975       Events, such as <eventlink id="MethodExit"></eventlink>,
2976       are generated as they would be in a normal return.
2977       <p/>
2978       The called method must be a non-native Java programming
2979       language method.
2980       Forcing return on a thread with only one frame on the
2981       stack causes the thread to exit when resumed.
2982     </intro>
2983 
2984     <function id="ForceEarlyReturnObject" num="81" since="1.1">
2985       <synopsis>Force Early Return - Object</synopsis>
2986       <description>
2987         This function can be used to return from a method whose
2988         result type is <code>Object</code>
2989         or a subclass of <code>Object</code>.
2990       </description>
2991       <origin>new</origin>
2992       <capabilities>
2993         <required id="can_force_early_return"></required>
2994       </capabilities>
2995       <parameters>
2996         <param id="thread">
2997           <jthread null="current"/>
2998           <description>
2999             The thread whose current frame is to return early.
3000           </description>
3001         </param>
3002         <param id="value">
3003           <jobject/>
3004           <description>
3005             The return value for the called frame.
3006             An object or <code>NULL</code>.
3007           </description>
3008         </param>
3009       </parameters>
3010       <errors>
3011         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3012           Attempted to return early from a frame
3013           corresponding to a native method.
3014           Or the implementation is unable to provide
3015           this functionality on this frame.
3016         </error>
3017         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3018           The result type of the called method is not
3019           <code>Object</code> or a subclass of <code>Object</code>.
3020         </error>
3021         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3022           The supplied <paramlink id="value"/> is not compatible with the
3023           result type of the called method.
3024         </error>
3025         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3026           Thread was not the current thread and was not suspended.
3027         </error>
3028         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3029           There are no more frames on the call stack.
3030         </error>
3031       </errors>
3032     </function>
3033 
3034     <function id="ForceEarlyReturnInt" num="82" since="1.1">
3035       <synopsis>Force Early Return - Int</synopsis>
3036       <description>
3037         This function can be used to return from a method whose
3038         result type is <code>int</code>, <code>short</code>,
3039         <code>char</code>, <code>byte</code>, or
3040         <code>boolean</code>.
3041       </description>
3042       <origin>new</origin>
3043       <capabilities>
3044         <required id="can_force_early_return"></required>
3045       </capabilities>
3046       <parameters>
3047         <param id="thread">
3048           <jthread null="current"/>
3049           <description>
3050             The thread whose current frame is to return early.
3051           </description>
3052         </param>
3053         <param id="value">
3054           <jint/>
3055           <description>
3056             The return value for the called frame.
3057           </description>
3058         </param>
3059       </parameters>
3060       <errors>
3061         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3062           Attempted to return early from a frame
3063           corresponding to a native method.
3064           Or the implementation is unable to provide
3065           this functionality on this frame.
3066         </error>
3067         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3068           The result type of the called method is not
3069           <code>int</code>, <code>short</code>,
3070           <code>char</code>, <code>byte</code>, or
3071           <code>boolean</code>.
3072         </error>
3073         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3074           Thread was not the current thread and was not suspended.
3075         </error>
3076         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3077           There are no frames on the call stack.
3078         </error>
3079       </errors>
3080     </function>
3081 
3082     <function id="ForceEarlyReturnLong" num="83" since="1.1">
3083       <synopsis>Force Early Return - Long</synopsis>
3084       <description>
3085         This function can be used to return from a method whose
3086         result type is <code>long</code>.
3087       </description>
3088       <origin>new</origin>
3089       <capabilities>
3090         <required id="can_force_early_return"></required>
3091       </capabilities>
3092       <parameters>
3093         <param id="thread">
3094           <jthread null="current"/>
3095           <description>
3096             The thread whose current frame is to return early.
3097           </description>
3098         </param>
3099         <param id="value">
3100           <jlong/>
3101           <description>
3102             The return value for the called frame.
3103           </description>
3104         </param>
3105       </parameters>
3106       <errors>
3107         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3108           Attempted to return early from a frame
3109           corresponding to a native method.
3110           Or the implementation is unable to provide
3111           this functionality on this frame.
3112         </error>
3113         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3114           The result type of the called method is not <code>long</code>.
3115         </error>
3116         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3117           Thread was not the current thread and was not suspended.
3118         </error>
3119         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3120           There are no frames on the call stack.
3121         </error>
3122       </errors>
3123     </function>
3124 
3125     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
3126       <synopsis>Force Early Return - Float</synopsis>
3127       <description>
3128         This function can be used to return from a method whose
3129         result type is <code>float</code>.
3130       </description>
3131       <origin>new</origin>
3132       <capabilities>
3133         <required id="can_force_early_return"></required>
3134       </capabilities>
3135       <parameters>
3136         <param id="thread">
3137           <jthread null="current"/>
3138           <description>
3139             The thread whose current frame is to return early.
3140           </description>
3141         </param>
3142         <param id="value">
3143           <jfloat/>
3144           <description>
3145             The return value for the called frame.
3146           </description>
3147         </param>
3148       </parameters>
3149       <errors>
3150         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3151           Attempted to return early from a frame
3152           corresponding to a native method.
3153           Or the implementation is unable to provide
3154           this functionality on this frame.
3155         </error>
3156         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3157           The result type of the called method is not <code>float</code>.
3158         </error>
3159         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3160           Thread was not the current thread and was not suspended.
3161         </error>
3162         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3163           There are no frames on the call stack.
3164         </error>
3165       </errors>
3166     </function>
3167 
3168     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
3169       <synopsis>Force Early Return - Double</synopsis>
3170       <description>
3171         This function can be used to return from a method whose
3172         result type is <code>double</code>.
3173       </description>
3174       <origin>new</origin>
3175       <capabilities>
3176         <required id="can_force_early_return"></required>
3177       </capabilities>
3178       <parameters>
3179         <param id="thread">
3180           <jthread null="current"/>
3181           <description>
3182             The thread whose current frame is to return early.
3183           </description>
3184         </param>
3185         <param id="value">
3186           <jdouble/>
3187           <description>
3188             The return value for the called frame.
3189           </description>
3190         </param>
3191       </parameters>
3192       <errors>
3193         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3194           Attempted to return early from a frame corresponding to a native method.
3195           Or the implementation is unable to provide this functionality on this frame.
3196         </error>
3197         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3198           The result type of the called method is not <code>double</code>.
3199         </error>
3200         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3201           Thread was not the current thread and was not suspended.
3202         </error>
3203         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3204           There are no frames on the call stack.
3205         </error>
3206       </errors>
3207     </function>
3208 
3209     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
3210       <synopsis>Force Early Return - Void</synopsis>
3211       <description>
3212         This function can be used to return from a method with no result type.
3213         That is, the called method must be declared <code>void</code>.
3214       </description>
3215       <origin>new</origin>
3216       <capabilities>
3217         <required id="can_force_early_return"></required>
3218       </capabilities>
3219       <parameters>
3220         <param id="thread">
3221           <jthread null="current"/>
3222           <description>
3223             The thread whose current frame is to return early.
3224           </description>
3225         </param>
3226       </parameters>
3227       <errors>
3228         <error id="JVMTI_ERROR_OPAQUE_FRAME">
3229           Attempted to return early from a frame
3230           corresponding to a native method.
3231           Or the implementation is unable to provide
3232           this functionality on this frame.
3233         </error>
3234         <error id="JVMTI_ERROR_TYPE_MISMATCH">
3235           The called method has a result type.
3236         </error>
3237         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
3238           Thread was not the current thread and was not suspended.
3239         </error>
3240         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
3241           There are no frames on the call stack.
3242         </error>
3243       </errors>
3244     </function>
3245 
3246   </category>
3247 
3248   <category id="Heap" label="Heap">
3249     <intro>
3250       These functions are used to analyze the heap.
3251       Functionality includes the ability to view the objects in the
3252       heap and to tag these objects.
3253     </intro>
3254 
3255     <intro id="objectTags" label="Object Tags">
3256       A <i>tag</i> is a value associated with an object.
3257       Tags are explicitly set by the agent using the
3258       <functionlink id="SetTag"></functionlink> function or by
3259       callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.
3260       <p/>
3261       Tags are local to the environment; that is, the tags of one
3262       environment are not visible in another.
3263       <p/>
3264       Tags are <code>jlong</code> values which can be used
3265       simply to mark an object or to store a pointer to more detailed
3266       information.  Objects which have not been tagged have a
3267       tag of zero.
3268       Setting a tag to zero makes the object untagged.
3269     </intro>
3270 
3271     <intro id="heapCallbacks" label="Heap Callback Functions">
3272         Heap functions which iterate through the heap and recursively
3273         follow object references use agent supplied callback functions
3274         to deliver the information.
3275         <p/>
3276         These heap callback functions must adhere to the following restrictions --
3277         These callbacks must not use JNI functions.
3278         These callbacks must not use <jvmti/> functions except
3279         <i>callback safe</i> functions which
3280         specifically allow such use (see the raw monitor, memory management,
3281         and environment local storage functions).
3282         <p/>
3283         An implementation may invoke a callback on an internal thread or
3284         the thread which called the iteration function.
3285         Heap callbacks are single threaded -- no more than one callback will
3286         be invoked at a time.
3287         <p/>
3288         The Heap Filter Flags can be used to prevent reporting
3289         based on the tag status of an object or its class.
3290         If no flags are set (the <code>jint</code> is zero), objects
3291         will not be filtered out.
3292 
3293         <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
3294           <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
3295             Filter out tagged objects. Objects which are tagged are not included.
3296           </constant>
3297           <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
3298             Filter out untagged objects. Objects which are not tagged are not included.
3299           </constant>
3300           <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
3301             Filter out objects with tagged classes. Objects whose class is tagged are not included.
3302           </constant>
3303           <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
3304             Filter out objects with untagged classes. Objects whose class is not tagged are not included.
3305           </constant>
3306         </constants>
3307 
3308         <p/>
3309         The Heap Visit Control Flags are returned by the heap callbacks
3310         and can be used to abort the iteration.  For the
3311         <functionlink id="jvmtiHeapReferenceCallback">Heap
3312         Reference Callback</functionlink>, it can also be used
3313         to prune the graph of traversed references
3314         (<code>JVMTI_VISIT_OBJECTS</code> is not set).
3315 
3316         <constants id="jvmtiHeapVisitControl"
3317                    label="Heap Visit Control Flags"
3318                    kind="bits"
3319                    since="1.1">
3320           <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
3321             If we are visiting an object and if this callback
3322             was initiated by <functionlink id="FollowReferences"/>,
3323             traverse the references of this object.
3324             Otherwise ignored.
3325           </constant>
3326           <constant id="JVMTI_VISIT_ABORT" num="0x8000">
3327             Abort the iteration.  Ignore all other bits.
3328           </constant>
3329         </constants>
3330 
3331         <p/>
3332         The Heap Reference Enumeration is provided by the
3333         <functionlink id="jvmtiHeapReferenceCallback">Heap
3334         Reference Callback</functionlink> and
3335         <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field
3336         Callback</functionlink> to
3337         describe the kind of reference
3338         being reported.
3339 
3340         <constants id="jvmtiHeapReferenceKind"
3341                    label="Heap Reference Enumeration"
3342                    kind="enum"
3343                    since="1.1">
3344           <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
3345             Reference from an object to its class.
3346           </constant>
3347           <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
3348             Reference from an object to the value of one of its instance fields.
3349           </constant>
3350           <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
3351             Reference from an array to one of its elements.
3352           </constant>
3353           <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
3354             Reference from a class to its class loader.
3355           </constant>
3356           <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
3357             Reference from a class to its signers array.
3358           </constant>
3359           <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
3360             Reference from a class to its protection domain.
3361           </constant>
3362           <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
3363             Reference from a class to one of its interfaces.
3364             Note: interfaces are defined via a constant pool reference,
3365             so the referenced interfaces may also be reported with a
3366             <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3367           </constant>
3368           <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
3369             Reference from a class to the value of one of its static fields.
3370           </constant>
3371           <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
3372             Reference from a class to a resolved entry in the constant pool.
3373           </constant>
3374           <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
3375             Reference from a class to its superclass.
3376             A callback is not sent if the superclass is <code>java.lang.Object</code>.
3377             Note: loaded classes define superclasses via a constant pool
3378             reference, so the referenced superclass may also be reported with
3379             a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
3380           </constant>
3381           <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
3382             Heap root reference: JNI global reference.
3383           </constant>
3384           <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
3385             Heap root reference: System class.
3386           </constant>
3387           <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
3388             Heap root reference: monitor.
3389           </constant>
3390           <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
3391             Heap root reference: local variable on the stack.
3392           </constant>
3393           <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
3394             Heap root reference: JNI local reference.
3395           </constant>
3396           <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
3397             Heap root reference: Thread.
3398           </constant>
3399           <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
3400             Heap root reference: other heap root reference.
3401           </constant>
3402         </constants>
3403 
3404         <p/>
3405         Definitions for the single character type descriptors of
3406         primitive types.
3407 
3408         <constants id="jvmtiPrimitiveType"
3409                    label="Primitive Type Enumeration"
3410                    kind="enum"
3411                    since="1.1">
3412           <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
3413             'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
3414           </constant>
3415           <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
3416             'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
3417           </constant>
3418           <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
3419             'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
3420           </constant>
3421           <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
3422             'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
3423           </constant>
3424           <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
3425             'I' - Java programming language <code>int</code> - JNI <code>jint</code>
3426           </constant>
3427           <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
3428             'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
3429           </constant>
3430           <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
3431             'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
3432           </constant>
3433           <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
3434             'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
3435           </constant>
3436         </constants>
3437     </intro>
3438 
3439       <typedef id="jvmtiHeapReferenceInfoField"
3440                label="Reference information structure for Field references"
3441                since="1.1">
3442         <description>
3443           Reference information returned for
3444           <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and
3445           <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3446         </description>
3447         <field id="index">
3448           <jint/>
3449           <description>
3450             For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the
3451             referrer object is not a class or an interface.
3452             In this case, <code>index</code> is the index of the field
3453             in the class of the referrer object.
3454             This class is referred to below as <i>C</i>.
3455             <p/>
3456             For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
3457             the referrer object is a class (referred to below as <i>C</i>)
3458             or an interface (referred to below as <i>I</i>).
3459             In this case, <code>index</code> is the index of the field in
3460             that class or interface.
3461             <p/>
3462             If the referrer object is not an interface, then the field
3463             indices are determined as follows:
3464             <ul>
3465               <li>make a list of all the fields in <i>C</i> and its
3466                   superclasses, starting with all the fields in
3467                   <code>java.lang.Object</code> and ending with all the
3468                   fields in <i>C</i>.</li>
3469               <li>Within this list, put
3470                   the fields for a given class in the order returned by
3471                   <functionlink id="GetClassFields"/>.</li>
3472               <li>Assign the fields in this list indices
3473                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
3474                   is the count of the fields in all the interfaces
3475                   implemented by <i>C</i>.
3476                   Note that <i>C</i> implements all interfaces
3477                   directly implemented by its superclasses; as well
3478                   as all superinterfaces of these interfaces.</li>
3479             </ul>
3480             If the referrer object is an interface, then the field
3481             indices are determined as follows:
3482             <ul>
3483               <li>make a list of the fields directly declared in
3484                   <i>I</i>.</li>
3485               <li>Within this list, put
3486                   the fields in the order returned by
3487                   <functionlink id="GetClassFields"/>.</li>
3488               <li>Assign the fields in this list indices
3489                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
3490                   is the count of the fields in all the superinterfaces
3491                   of <i>I</i>.</li>
3492             </ul>
3493             All fields are included in this computation, regardless of
3494             field modifier (static, public, private, etc).
3495             <p/>
3496             For example, given the following classes and interfaces:
3497             <example>
3498 interface I0 {
3499     int p = 0;
3500 }
3501 
3502 interface I1 extends I0 {
3503     int x = 1;
3504 }
3505 
3506 interface I2 extends I0 {
3507     int y = 2;
3508 }
3509 
3510 class C1 implements I1 {
3511     public static int a = 3;
3512     private int b = 4;
3513 }
3514 
3515 class C2 extends C1 implements I2 {
3516     static int q = 5;
3517     final int r = 6;
3518 }
3519             </example>
3520             Assume that <functionlink id="GetClassFields"/> called on
3521             <code>C1</code> returns the fields of <code>C1</code> in the
3522             order: a, b; and that the fields of <code>C2</code> are
3523             returned in the order: q, r.
3524             An instance of class <code>C1</code> will have the
3525             following field indices:
3526             <blockquote><table>
3527               <tr>
3528                 <td class="centered">
3529                   a
3530                 </td>
3531                 <td class="centered">
3532                   2
3533                 </td>
3534                 <td>
3535                   The count of the fields in the interfaces
3536                   implemented by <code>C1</code> is two (<i>n</i>=2):
3537                   <code>p</code> of <code>I0</code>
3538                   and <code>x</code> of <code>I1</code>.
3539                 </td>
3540               </tr>
3541               <tr>
3542                 <td class="centered">
3543                   b
3544                 </td>
3545                 <td class="centered">
3546                   3
3547                 </td>
3548                 <td>
3549                   the subsequent index.
3550                 </td>
3551               </tr>
3552             </table></blockquote>
3553             The class <code>C1</code> will have the same field indices.
3554             <p/>
3555             An instance of class <code>C2</code> will have the
3556             following field indices:
3557             <blockquote><table>
3558               <tr>
3559                 <td class="centered">
3560                   a
3561                 </td>
3562                 <td class="centered">
3563                   3
3564                 </td>
3565                 <td>
3566                   The count of the fields in the interfaces
3567                   implemented by <code>C2</code> is three (<i>n</i>=3):
3568                   <code>p</code> of <code>I0</code>,
3569                   <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code>
3570                   (an interface of <code>C2</code>).  Note that the field <code>p</code>
3571                   of <code>I0</code> is only included once.
3572                 </td>
3573               </tr>
3574               <tr>
3575                 <td class="centered">
3576                   b
3577                 </td>
3578                 <td class="centered">
3579                   4
3580                 </td>
3581                 <td>
3582                   the subsequent index to "a".
3583                 </td>
3584               </tr>
3585               <tr>
3586                 <td class="centered">
3587                   q
3588                 </td>
3589                 <td class="centered">
3590                   5
3591                 </td>
3592                 <td>
3593                   the subsequent index to "b".
3594                 </td>
3595               </tr>
3596               <tr>
3597                 <td class="centered">
3598                   r
3599                 </td>
3600                 <td class="centered">
3601                   6
3602                 </td>
3603                 <td>
3604                   the subsequent index to "q".
3605                 </td>
3606               </tr>
3607             </table></blockquote>
3608             The class <code>C2</code> will have the same field indices.
3609             Note that a field may have a different index depending on the
3610             object that is viewing it -- for example field "a" above.
3611             Note also: not all field indices may be visible from the
3612             callbacks, but all indices are shown for illustrative purposes.
3613             <p/>
3614             The interface <code>I1</code> will have the
3615             following field indices:
3616             <blockquote><table>
3617               <tr>
3618                 <td class="centered">
3619                   x
3620                 </td>
3621                 <td class="centered">
3622                   1
3623                 </td>
3624                 <td>
3625                   The count of the fields in the superinterfaces
3626                   of <code>I1</code> is one (<i>n</i>=1):
3627                   <code>p</code> of <code>I0</code>.
3628                 </td>
3629               </tr>
3630             </table></blockquote>
3631           </description>
3632         </field>
3633       </typedef>
3634 
3635       <typedef id="jvmtiHeapReferenceInfoArray"
3636                label="Reference information structure for Array references"
3637                since="1.1">
3638         <description>
3639           Reference information returned for
3640          <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3641         </description>
3642         <field id="index">
3643           <jint/>
3644           <description>
3645             The array index.
3646           </description>
3647         </field>
3648       </typedef>
3649 
3650       <typedef id="jvmtiHeapReferenceInfoConstantPool"
3651                label="Reference information structure for Constant Pool references"
3652                since="1.1">
3653         <description>
3654           Reference information returned for
3655           <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3656         </description>
3657         <field id="index">
3658           <jint/>
3659           <description>
3660             The index into the constant pool of the class. See the description in
3661       <vmspec chapter="4.4"/>.
3662           </description>
3663         </field>
3664       </typedef>
3665 
3666       <typedef id="jvmtiHeapReferenceInfoStackLocal"
3667                label="Reference information structure for Local Variable references"
3668                since="1.1">
3669         <description>
3670           Reference information returned for
3671           <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3672         </description>
3673         <field id="thread_tag">
3674           <jlong/>
3675           <description>
3676             The tag of the thread corresponding to this stack, zero if not tagged.
3677           </description>
3678         </field>
3679         <field id="thread_id">
3680           <jlong/>
3681           <description>
3682             The unique thread ID of the thread corresponding to this stack.
3683           </description>
3684         </field>
3685         <field id="depth">
3686           <jint/>
3687           <description>
3688             The depth of the frame.
3689           </description>
3690         </field>
3691         <field id="method">
3692           <jmethodID/>
3693           <description>
3694             The method executing in this frame.
3695           </description>
3696         </field>
3697         <field id="location">
3698           <jlocation/>
3699           <description>
3700             The currently executing location in this frame.
3701           </description>
3702         </field>
3703         <field id="slot">
3704           <jint/>
3705           <description>
3706             The slot number of the local variable.
3707           </description>
3708         </field>
3709       </typedef>
3710 
3711       <typedef id="jvmtiHeapReferenceInfoJniLocal"
3712                label="Reference information structure for JNI local references"
3713                since="1.1">
3714         <description>
3715           Reference information returned for
3716           <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3717         </description>
3718         <field id="thread_tag">
3719           <jlong/>
3720           <description>
3721             The tag of the thread corresponding to this stack, zero if not tagged.
3722           </description>
3723         </field>
3724         <field id="thread_id">
3725           <jlong/>
3726           <description>
3727             The unique thread ID of the thread corresponding to this stack.
3728           </description>
3729         </field>
3730         <field id="depth">
3731           <jint/>
3732           <description>
3733             The depth of the frame.
3734           </description>
3735         </field>
3736         <field id="method">
3737           <jmethodID/>
3738           <description>
3739             The method executing in this frame.
3740           </description>
3741         </field>
3742       </typedef>
3743 
3744       <typedef id="jvmtiHeapReferenceInfoReserved"
3745                label="Reference information structure for Other references"
3746                since="1.1">
3747         <description>
3748           Reference information returned for other references.
3749         </description>
3750         <field id="reserved1">
3751           <jlong/>
3752           <description>
3753             reserved for future use.
3754           </description>
3755         </field>
3756         <field id="reserved2">
3757           <jlong/>
3758           <description>
3759             reserved for future use.
3760           </description>
3761         </field>
3762         <field id="reserved3">
3763           <jlong/>
3764           <description>
3765             reserved for future use.
3766           </description>
3767         </field>
3768         <field id="reserved4">
3769           <jlong/>
3770           <description>
3771             reserved for future use.
3772           </description>
3773         </field>
3774         <field id="reserved5">
3775           <jlong/>
3776           <description>
3777             reserved for future use.
3778           </description>
3779         </field>
3780         <field id="reserved6">
3781           <jlong/>
3782           <description>
3783             reserved for future use.
3784           </description>
3785         </field>
3786         <field id="reserved7">
3787           <jlong/>
3788           <description>
3789             reserved for future use.
3790           </description>
3791         </field>
3792         <field id="reserved8">
3793           <jlong/>
3794           <description>
3795             reserved for future use.
3796           </description>
3797         </field>
3798       </typedef>
3799 
3800       <uniontypedef id="jvmtiHeapReferenceInfo"
3801                label="Reference information structure"
3802                since="1.1">
3803         <description>
3804           The information returned about referrers.
3805           Represented as a union of the various kinds of reference information.
3806         </description>
3807         <field id="field">
3808           <struct>jvmtiHeapReferenceInfoField</struct>
3809           <description>
3810             The referrer information for
3811             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>
3812             and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
3813           </description>
3814         </field>
3815         <field id="array">
3816           <struct>jvmtiHeapReferenceInfoArray</struct>
3817           <description>
3818             The referrer information for
3819             For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
3820           </description>
3821         </field>
3822         <field id="constant_pool">
3823           <struct>jvmtiHeapReferenceInfoConstantPool</struct>
3824           <description>
3825             The referrer information for
3826             For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
3827           </description>
3828         </field>
3829         <field id="stack_local">
3830           <struct>jvmtiHeapReferenceInfoStackLocal</struct>
3831           <description>
3832             The referrer information for
3833             For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
3834           </description>
3835         </field>
3836         <field id="jni_local">
3837           <struct>jvmtiHeapReferenceInfoJniLocal</struct>
3838           <description>
3839             The referrer information for
3840             For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
3841           </description>
3842         </field>
3843         <field id="other">
3844           <struct>jvmtiHeapReferenceInfoReserved</struct>
3845           <description>
3846             reserved for future use.
3847           </description>
3848         </field>
3849       </uniontypedef>
3850 
3851       <typedef id="jvmtiHeapCallbacks"
3852                label="Heap callback function structure"
3853                since="1.1">
3854         <field id="heap_iteration_callback">
3855           <ptrtype>
3856             <struct>jvmtiHeapIterationCallback</struct>
3857           </ptrtype>
3858           <description>
3859             The callback to be called to describe an
3860             object in the heap. Used by the
3861             <functionlink id="IterateThroughHeap"/> function, ignored by the
3862             <functionlink id="FollowReferences"/> function.
3863           </description>
3864         </field>
3865         <field id="heap_reference_callback">
3866           <ptrtype>
3867             <struct>jvmtiHeapReferenceCallback</struct>
3868           </ptrtype>
3869           <description>
3870             The callback to be called to describe an
3871             object reference.  Used by the
3872             <functionlink id="FollowReferences"/> function, ignored by the
3873             <functionlink id="IterateThroughHeap"/> function.
3874           </description>
3875         </field>
3876         <field id="primitive_field_callback">
3877           <ptrtype>
3878             <struct>jvmtiPrimitiveFieldCallback</struct>
3879           </ptrtype>
3880           <description>
3881             The callback to be called to describe a
3882             primitive field.
3883           </description>
3884         </field>
3885         <field id="array_primitive_value_callback">
3886           <ptrtype>
3887             <struct>jvmtiArrayPrimitiveValueCallback</struct>
3888           </ptrtype>
3889           <description>
3890             The callback to be called to describe an
3891             array of primitive values.
3892           </description>
3893         </field>
3894         <field id="string_primitive_value_callback">
3895           <ptrtype>
3896             <struct>jvmtiStringPrimitiveValueCallback</struct>
3897           </ptrtype>
3898           <description>
3899             The callback to be called to describe a String value.
3900           </description>
3901         </field>
3902         <field id="reserved5">
3903           <ptrtype>
3904             <struct>jvmtiReservedCallback</struct>
3905           </ptrtype>
3906           <description>
3907             Reserved for future use..
3908           </description>
3909         </field>
3910         <field id="reserved6">
3911           <ptrtype>
3912             <struct>jvmtiReservedCallback</struct>
3913           </ptrtype>
3914           <description>
3915             Reserved for future use..
3916           </description>
3917         </field>
3918         <field id="reserved7">
3919           <ptrtype>
3920             <struct>jvmtiReservedCallback</struct>
3921           </ptrtype>
3922           <description>
3923             Reserved for future use..
3924           </description>
3925         </field>
3926         <field id="reserved8">
3927           <ptrtype>
3928             <struct>jvmtiReservedCallback</struct>
3929           </ptrtype>
3930           <description>
3931             Reserved for future use..
3932           </description>
3933         </field>
3934         <field id="reserved9">
3935           <ptrtype>
3936             <struct>jvmtiReservedCallback</struct>
3937           </ptrtype>
3938           <description>
3939             Reserved for future use..
3940           </description>
3941         </field>
3942         <field id="reserved10">
3943           <ptrtype>
3944             <struct>jvmtiReservedCallback</struct>
3945           </ptrtype>
3946           <description>
3947             Reserved for future use..
3948           </description>
3949         </field>
3950         <field id="reserved11">
3951           <ptrtype>
3952             <struct>jvmtiReservedCallback</struct>
3953           </ptrtype>
3954           <description>
3955             Reserved for future use..
3956           </description>
3957         </field>
3958         <field id="reserved12">
3959           <ptrtype>
3960             <struct>jvmtiReservedCallback</struct>
3961           </ptrtype>
3962           <description>
3963             Reserved for future use..
3964           </description>
3965         </field>
3966         <field id="reserved13">
3967           <ptrtype>
3968             <struct>jvmtiReservedCallback</struct>
3969           </ptrtype>
3970           <description>
3971             Reserved for future use..
3972           </description>
3973         </field>
3974         <field id="reserved14">
3975           <ptrtype>
3976             <struct>jvmtiReservedCallback</struct>
3977           </ptrtype>
3978           <description>
3979             Reserved for future use..
3980           </description>
3981         </field>
3982         <field id="reserved15">
3983           <ptrtype>
3984             <struct>jvmtiReservedCallback</struct>
3985           </ptrtype>
3986           <description>
3987             Reserved for future use..
3988           </description>
3989         </field>
3990       </typedef>
3991 
3992 
3993     <intro>
3994       <rationale>
3995         The heap dumping functionality (below) uses a callback
3996         for each object.  While it would seem that a buffered approach
3997         would provide better throughput, tests do
3998         not show this to be the case--possibly due to locality of
3999         memory reference or array access overhead.
4000       </rationale>
4001 
4002       <issue>
4003         Still under investigation as to if java.lang.ref references
4004         are reported as a different type of reference.
4005       </issue>
4006 
4007       <issue>
4008         Should or can an indication of the cost or relative cost of
4009         these operations be included?
4010       </issue>
4011 
4012     </intro>
4013 
4014     <callback id="jvmtiHeapIterationCallback" since="1.1">
4015       <jint/>
4016       <synopsis>Heap Iteration Callback</synopsis>
4017       <description>
4018         Agent supplied callback function.
4019         Describes (but does not pass in) an object in the heap.
4020         <p/>
4021         This function should return a bit vector of the desired
4022         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4023         This will determine if the entire iteration should be aborted
4024         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4025         <p/>
4026         See the <internallink id="heapCallbacks">heap callback
4027         function restrictions</internallink>.
4028       </description>
4029       <parameters>
4030         <param id="class_tag">
4031           <jlong/>
4032           <description>
4033             The tag of the class of object (zero if the class is not tagged).
4034             If the object represents a runtime class,
4035             the <code>class_tag</code> is the tag
4036             associated with <code>java.lang.Class</code>
4037             (zero if <code>java.lang.Class</code> is not tagged).
4038           </description>
4039         </param>
4040         <param id="size">
4041           <jlong/>
4042           <description>
4043             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
4044           </description>
4045         </param>
4046         <param id="tag_ptr">
4047           <outptr><jlong/></outptr>
4048           <description>
4049             The object tag value, or zero if the object is not tagged.
4050             To set the tag value to be associated with the object
4051             the agent sets the <code>jlong</code> pointed to by the parameter.
4052           </description>
4053         </param>
4054         <param id="length">
4055           <jint/>
4056           <description>
4057             If this object is an array, the length of the array. Otherwise negative one (-1).
4058           </description>
4059         </param>
4060         <param id="user_data">
4061           <outptr><void/></outptr>
4062           <description>
4063             The user supplied data that was passed into the iteration function.
4064           </description>
4065         </param>
4066       </parameters>
4067     </callback>
4068 
4069     <callback id="jvmtiHeapReferenceCallback" since="1.1">
4070       <jint/>
4071       <synopsis>Heap Reference Callback</synopsis>
4072       <description>
4073         Agent supplied callback function.
4074         Describes a reference from an object or the VM (the referrer) to another object
4075         (the referree) or a heap root to a referree.
4076         <p/>
4077         This function should return a bit vector of the desired
4078         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4079         This will determine if the objects referenced by the referree
4080         should be visited or if the entire iteration should be aborted.
4081         <p/>
4082         See the <internallink id="heapCallbacks">heap callback
4083         function restrictions</internallink>.
4084       </description>
4085       <parameters>
4086         <param id="reference_kind">
4087           <enum>jvmtiHeapReferenceKind</enum>
4088           <description>
4089             The kind of reference.
4090           </description>
4091         </param>
4092         <param id="reference_info">
4093           <inptr>
4094             <struct>jvmtiHeapReferenceInfo</struct>
4095           </inptr>
4096           <description>
4097             Details about the reference.
4098             Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is
4099             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
4100             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
4101             <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
4102             <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>,
4103             <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
4104             or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
4105             Otherwise <code>NULL</code>.
4106           </description>
4107         </param>
4108         <param id="class_tag">
4109           <jlong/>
4110           <description>
4111             The tag of the class of referree object (zero if the class is not tagged).
4112             If the referree object represents a runtime class,
4113             the <code>class_tag</code> is the tag
4114             associated with <code>java.lang.Class</code>
4115             (zero if <code>java.lang.Class</code> is not tagged).
4116           </description>
4117         </param>
4118         <param id="referrer_class_tag">
4119           <jlong/>
4120           <description>
4121             The tag of the class of the referrer object (zero if the class is not tagged
4122             or the referree is a heap root). If the referrer object represents a runtime
4123             class, the <code>referrer_class_tag</code> is the tag associated with
4124             the <code>java.lang.Class</code>
4125             (zero if <code>java.lang.Class</code> is not tagged).
4126           </description>
4127         </param>
4128         <param id="size">
4129           <jlong/>
4130           <description>
4131             Size of the referree object (in bytes).
4132             See <functionlink id="GetObjectSize"/>.
4133           </description>
4134         </param>
4135         <param id="tag_ptr">
4136           <outptr><jlong/></outptr>
4137           <description>
4138             Points to the referree object tag value, or zero if the object is not
4139             tagged.
4140             To set the tag value to be associated with the object
4141             the agent sets the <code>jlong</code> pointed to by the parameter.
4142           </description>
4143         </param>
4144         <param id="referrer_tag_ptr">
4145           <outptr><jlong/></outptr>
4146           <description>
4147             Points to the tag of the referrer object, or
4148             points to the zero if the referrer
4149             object is not tagged.
4150             <code>NULL</code> if the referrer in not an object (that is,
4151             this callback is reporting a heap root).
4152             To set the tag value to be associated with the referrer object
4153             the agent sets the <code>jlong</code> pointed to by the parameter.
4154             If this callback is reporting a reference from an object to itself,
4155             <code>referrer_tag_ptr == tag_ptr</code>.
4156           </description>
4157         </param>
4158         <param id="length">
4159           <jint/>
4160           <description>
4161             If this object is an array, the length of the array. Otherwise negative one (-1).
4162           </description>
4163         </param>
4164         <param id="user_data">
4165           <outptr><void/></outptr>
4166           <description>
4167             The user supplied data that was passed into the iteration function.
4168           </description>
4169         </param>
4170       </parameters>
4171     </callback>
4172 
4173     <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
4174       <jint/>
4175       <synopsis>Primitive Field Callback</synopsis>
4176       <description>
4177         Agent supplied callback function which
4178         describes a primitive field of an object (<i>the object</i>).
4179         A primitive field is a field whose type is a primitive type.
4180         This callback will describe a static field if the object is a class,
4181         and otherwise will describe an instance field.
4182         <p/>
4183         This function should return a bit vector of the desired
4184         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4185         This will determine if the entire iteration should be aborted
4186         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4187         <p/>
4188         See the <internallink id="heapCallbacks">heap callback
4189         function restrictions</internallink>.
4190       </description>
4191       <parameters>
4192         <param id="kind">
4193           <enum>jvmtiHeapReferenceKind</enum>
4194           <description>
4195             The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or
4196             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
4197           </description>
4198         </param>
4199         <param id="info">
4200           <inptr>
4201             <struct>jvmtiHeapReferenceInfo</struct>
4202           </inptr>
4203           <description>
4204             Which field (the field index).
4205           </description>
4206         </param>
4207         <param id="object_class_tag">
4208           <jlong/>
4209           <description>
4210             The tag of the class of the object (zero if the class is not tagged).
4211             If the object represents a runtime class, the
4212             <code>object_class_tag</code> is the tag
4213             associated with <code>java.lang.Class</code>
4214             (zero if <code>java.lang.Class</code> is not tagged).
4215           </description>
4216         </param>
4217         <param id="object_tag_ptr">
4218           <outptr><jlong/></outptr>
4219           <description>
4220             Points to the tag of the object, or zero if the object is not
4221             tagged.
4222             To set the tag value to be associated with the object
4223             the agent sets the <code>jlong</code> pointed to by the parameter.
4224           </description>
4225         </param>
4226         <param id="value">
4227           <jvalue/>
4228           <description>
4229             The value of the field.
4230           </description>
4231         </param>
4232         <param id="value_type">
4233           <enum>jvmtiPrimitiveType</enum>
4234           <description>
4235             The type of the field.
4236           </description>
4237         </param>
4238         <param id="user_data">
4239           <outptr><void/></outptr>
4240           <description>
4241             The user supplied data that was passed into the iteration function.
4242           </description>
4243         </param>
4244       </parameters>
4245     </callback>
4246 
4247     <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
4248       <jint/>
4249       <synopsis>Array Primitive Value Callback</synopsis>
4250       <description>
4251         Agent supplied callback function.
4252         Describes the values in an array of a primitive type.
4253         <p/>
4254         This function should return a bit vector of the desired
4255         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4256         This will determine if the entire iteration should be aborted
4257         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4258         <p/>
4259         See the <internallink id="heapCallbacks">heap callback
4260         function restrictions</internallink>.
4261       </description>
4262       <parameters>
4263         <param id="class_tag">
4264           <jlong/>
4265           <description>
4266             The tag of the class of the array object (zero if the class is not tagged).
4267           </description>
4268         </param>
4269         <param id="size">
4270           <jlong/>
4271           <description>
4272             Size of the array (in bytes).
4273             See <functionlink id="GetObjectSize"/>.
4274           </description>
4275         </param>
4276         <param id="tag_ptr">
4277           <outptr><jlong/></outptr>
4278           <description>
4279             Points to the tag of the array object, or zero if the object is not
4280             tagged.
4281             To set the tag value to be associated with the object
4282             the agent sets the <code>jlong</code> pointed to by the parameter.
4283           </description>
4284         </param>
4285         <param id="element_count">
4286           <jint/>
4287           <description>
4288             The length of the primitive array.
4289           </description>
4290         </param>
4291         <param id="element_type">
4292           <enum>jvmtiPrimitiveType</enum>
4293           <description>
4294             The type of the elements of the array.
4295           </description>
4296         </param>
4297         <param id="elements">
4298           <vmbuf><void/></vmbuf>
4299           <description>
4300             The elements of the array in a packed array of <code>element_count</code>
4301             items of <code>element_type</code> size each.
4302           </description>
4303         </param>
4304         <param id="user_data">
4305           <outptr><void/></outptr>
4306           <description>
4307             The user supplied data that was passed into the iteration function.
4308           </description>
4309         </param>
4310       </parameters>
4311     </callback>
4312 
4313     <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
4314       <jint/>
4315       <synopsis>String Primitive Value Callback</synopsis>
4316       <description>
4317         Agent supplied callback function.
4318         Describes the value of a java.lang.String.
4319         <p/>
4320         This function should return a bit vector of the desired
4321         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
4322         This will determine if the entire iteration should be aborted
4323         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
4324         <p/>
4325         See the <internallink id="heapCallbacks">heap callback
4326         function restrictions</internallink>.
4327       </description>
4328       <parameters>
4329         <param id="class_tag">
4330           <jlong/>
4331           <description>
4332             The tag of the class of the String class (zero if the class is not tagged).
4333             <issue>Is this needed?</issue>
4334           </description>
4335         </param>
4336         <param id="size">
4337           <jlong/>
4338           <description>
4339             Size of the string (in bytes).
4340             See <functionlink id="GetObjectSize"/>.
4341           </description>
4342         </param>
4343         <param id="tag_ptr">
4344           <outptr><jlong/></outptr>
4345           <description>
4346             Points to the tag of the String object, or zero if the object is not
4347             tagged.
4348             To set the tag value to be associated with the object
4349             the agent sets the <code>jlong</code> pointed to by the parameter.
4350           </description>
4351         </param>
4352         <param id="value">
4353           <vmbuf><jchar/></vmbuf>
4354           <description>
4355             The value of the String, encoded as a Unicode string.
4356           </description>
4357         </param>
4358         <param id="value_length">
4359           <jint/>
4360           <description>
4361             The length of the string.
4362             The length is equal to the number of 16-bit Unicode
4363             characters in the string.
4364           </description>
4365         </param>
4366         <param id="user_data">
4367           <outptr><void/></outptr>
4368           <description>
4369             The user supplied data that was passed into the iteration function.
4370           </description>
4371         </param>
4372       </parameters>
4373     </callback>
4374 
4375 
4376     <callback id="jvmtiReservedCallback" since="1.1">
4377       <jint/>
4378       <synopsis>reserved for future use Callback</synopsis>
4379       <description>
4380         Placeholder -- reserved for future use.
4381       </description>
4382       <parameters>
4383       </parameters>
4384     </callback>
4385 
4386     <function id="FollowReferences" num="115" since="1.1">
4387       <synopsis>Follow References</synopsis>
4388       <description>
4389         This function initiates a traversal over the objects that are
4390         directly and indirectly reachable from the specified object or,
4391         if <code>initial_object</code> is not specified, all objects
4392         reachable from the heap roots.
4393         The heap root are the set of system classes,
4394         JNI globals, references from thread stacks, and other objects used as roots
4395         for the purposes of garbage collection.
4396         <p/>
4397         This function operates by traversing the reference graph.
4398         Let <i>A</i>, <i>B</i>, ... represent objects.
4399         When a reference from <i>A</i> to <i>B</i> is traversed,
4400         when a reference from a heap root to <i>B</i> is traversed,
4401         or when <i>B</i> is specified as the <paramlink id="initial_object"/>,
4402         then <i>B</i> is said to be <i>visited</i>.
4403         A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i>
4404         is visited.
4405         References are reported in the same order that the references are traversed.
4406         Object references are reported by invoking the agent supplied
4407         callback function <functionlink id="jvmtiHeapReferenceCallback"/>.
4408         In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known
4409         as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
4410         The callback is invoked exactly once for each reference from a referrer;
4411         this is true even if there are reference cycles or multiple paths to
4412         the referrer.
4413         There may be more than one reference between a referrer and a referree,
4414         each reference is reported.
4415         These references may be distinguished by examining the
4416         <datalink
4417          id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
4418          and
4419         <datalink
4420          id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
4421         parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
4422         <p/>
4423         This function reports a Java programming language view of object references,
4424         not a virtual machine implementation view. The following object references
4425         are reported when they are non-null:
4426         <ul>
4427           <li>Instance objects report references to each non-primitive instance fields
4428               (including inherited fields).</li>
4429           <li>Instance objects report a reference to the object type (class).</li>
4430           <li>Classes report a reference to the superclass and directly
4431               implemented/extended interfaces.</li>
4432           <li>Classes report a reference to the class loader, protection domain,
4433               signers, and resolved entries in the constant pool.</li>
4434           <li>Classes report a reference to each directly declared non-primitive
4435               static field.</li>
4436           <li>Arrays report a reference to the array type (class) and each
4437               array element.</li>
4438           <li>Primitive arrays report a reference to the array type.</li>
4439         </ul>
4440         <p/>
4441         This function can also be used to examine primitive (non-object) values.
4442         The primitive value of an array or String
4443         is reported after the object has been visited;
4444         it is reported by invoking the agent supplied callback function
4445         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4446         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4447         A primitive field
4448         is reported after the object with that field is visited;
4449         it is reported by invoking the agent supplied callback function
4450         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4451         <p/>
4452         Whether a callback is provided or is <code>NULL</code> only determines
4453         whether the callback will be invoked, it does not influence
4454         which objects are visited nor does it influence whether other callbacks
4455         will be invoked.
4456         However, the
4457         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
4458         returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4459         do determine if the objects referenced by the
4460         current object as visited.
4461         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4462         and <paramlink id="klass"/> provided as parameters to this function
4463         do not control which objects are visited but they do control which
4464         objects and primitive values are reported by the callbacks.
4465         For example, if the only callback that was set is
4466         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4467         is set to the array of bytes class, then only arrays of byte will be
4468         reported.
4469         The table below summarizes this:
4470         <p/>
4471         <table>
4472           <tr>
4473             <th/>
4474             <th>
4475               Controls objects visited
4476             </th>
4477             <th>
4478               Controls objects reported
4479             </th>
4480             <th>
4481               Controls primitives reported
4482             </th>
4483           </tr>
4484           <tr>
4485             <th class="leftAligned">
4486               the
4487               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4488               returned by <functionlink id="jvmtiHeapReferenceCallback"/>
4489             </th>
4490             <td class="centered">
4491               <b>Yes</b>
4492             </td>
4493             <td class="centered">
4494               <b>Yes</b>, since visits are controlled
4495             </td>
4496             <td class="centered">
4497               <b>Yes</b>, since visits are controlled
4498             </td>
4499           </tr>
4500           <tr>
4501             <th class="leftAligned">
4502               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4503               in <paramlink id="callbacks"/> set
4504             </th>
4505             <td class="centered">
4506               No
4507             </td>
4508             <td class="centered">
4509               <b>Yes</b>
4510             </td>
4511             <td class="centered">
4512               No
4513             </td>
4514           </tr>
4515           <tr>
4516             <th class="leftAligned">
4517               <paramlink id="heap_filter"/>
4518             </th>
4519             <td class="centered">
4520               No
4521             </td>
4522             <td class="centered">
4523               <b>Yes</b>
4524             </td>
4525             <td class="centered">
4526               <b>Yes</b>
4527             </td>
4528           </tr>
4529           <tr>
4530             <th class="leftAligned">
4531               <paramlink id="klass"/>
4532             </th>
4533             <td class="centered">
4534               No
4535             </td>
4536             <td class="centered">
4537               <b>Yes</b>
4538             </td>
4539             <td class="centered">
4540               <b>Yes</b>
4541             </td>
4542           </tr>
4543         </table>
4544         <p/>
4545         During the execution of this function the state of the heap
4546         does not change: no objects are allocated, no objects are
4547         garbage collected, and the state of objects (including
4548         held values) does not change.
4549         As a result, threads executing Java
4550         programming language code, threads attempting to resume the
4551         execution of Java programming language code, and threads
4552         attempting to execute JNI functions are typically stalled.
4553       </description>
4554       <origin>new</origin>
4555       <capabilities>
4556         <required id="can_tag_objects"></required>
4557       </capabilities>
4558       <parameters>
4559         <param id="heap_filter">
4560           <jint/>
4561           <description>
4562             This bit vector of
4563             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4564             restricts the objects for which the callback function is called.
4565             This applies to both the object and primitive callbacks.
4566           </description>
4567         </param>
4568         <param id="klass">
4569           <ptrtype>
4570             <jclass/>
4571             <nullok>callbacks are not limited to instances of a particular
4572                     class</nullok>
4573           </ptrtype>
4574           <description>
4575             Callbacks are only reported when the object is an instance of
4576             this class.
4577             Objects which are instances of a subclass of <code>klass</code>
4578             are not reported.
4579             If <code>klass</code> is an interface, no objects are reported.
4580             This applies to both the object and primitive callbacks.
4581           </description>
4582         </param>
4583         <param id="initial_object">
4584           <ptrtype>
4585             <jobject/>
4586             <nullok>references are followed from the heap roots</nullok>
4587           </ptrtype>
4588           <description>
4589             The object to follow
4590           </description>
4591         </param>
4592         <param id="callbacks">
4593           <inptr>
4594             <struct>jvmtiHeapCallbacks</struct>
4595           </inptr>
4596           <description>
4597             Structure defining the set of callback functions.
4598           </description>
4599         </param>
4600         <param id="user_data">
4601           <inbuf>
4602             <void/>
4603             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4604           </inbuf>
4605           <description>
4606             User supplied data to be passed to the callback.
4607           </description>
4608         </param>
4609       </parameters>
4610       <errors>
4611         <error id="JVMTI_ERROR_INVALID_CLASS">
4612           <paramlink id="klass"/> is not a valid class.
4613         </error>
4614         <error id="JVMTI_ERROR_INVALID_OBJECT">
4615           <paramlink id="initial_object"/> is not a valid object.
4616         </error>
4617       </errors>
4618     </function>
4619 
4620 
4621     <function id="IterateThroughHeap" num="116" since="1.1">
4622       <synopsis>Iterate Through Heap</synopsis>
4623       <description>
4624         Initiate an iteration over all objects in the heap.
4625         This includes both reachable and
4626         unreachable objects. Objects are visited in no particular order.
4627         <p/>
4628         Heap objects are reported by invoking the agent supplied
4629         callback function <functionlink id="jvmtiHeapIterationCallback"/>.
4630         References between objects are not reported.
4631         If only reachable objects are desired, or if object reference information
4632         is needed, use <functionlink id="FollowReferences"/>.
4633         <p/>
4634         This function can also be used to examine primitive (non-object) values.
4635         The primitive value of an array or String
4636         is reported after the object has been visited;
4637         it is reported by invoking the agent supplied callback function
4638         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
4639         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
4640         A primitive field
4641         is reported after the object with that field is visited;
4642         it is reported by invoking the agent supplied
4643         callback function
4644         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
4645         <p/>
4646         Unless the iteration is aborted by the
4647         <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4648         returned by a callback, all objects in the heap are visited.
4649         Whether a callback is provided or is <code>NULL</code> only determines
4650         whether the callback will be invoked, it does not influence
4651         which objects are visited nor does it influence whether other callbacks
4652         will be invoked.
4653         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
4654         and <paramlink id="klass"/> provided as parameters to this function
4655         do not control which objects are visited but they do control which
4656         objects and primitive values are reported by the callbacks.
4657         For example, if the only callback that was set is
4658         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
4659         is set to the array of bytes class, then only arrays of byte will be
4660         reported. The table below summarizes this (contrast this with
4661         <functionlink id="FollowReferences"/>):
4662         <p/>
4663         <table>
4664           <tr>
4665             <th/>
4666             <th>
4667               Controls objects visited
4668             </th>
4669             <th>
4670               Controls objects reported
4671             </th>
4672             <th>
4673               Controls primitives reported
4674             </th>
4675           </tr>
4676           <tr>
4677             <th class="leftAligned">
4678               the
4679               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
4680               returned by <functionlink id="jvmtiHeapIterationCallback"/>
4681             </th>
4682             <td class="centered">
4683               No<br/>(unless they abort the iteration)
4684             </td>
4685             <td class="centered">
4686               No<br/>(unless they abort the iteration)
4687             </td>
4688             <td class="centered">
4689               No<br/>(unless they abort the iteration)
4690             </td>
4691           </tr>
4692           <tr>
4693             <th class="leftAligned">
4694               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
4695               in <paramlink id="callbacks"/> set
4696             </th>
4697             <td class="centered">
4698               No
4699             </td>
4700             <td class="centered">
4701               <b>Yes</b>
4702             </td>
4703             <td class="centered">
4704               No
4705             </td>
4706           </tr>
4707           <tr>
4708             <th class="leftAligned">
4709               <paramlink id="heap_filter"/>
4710             </th>
4711             <td class="centered">
4712               No
4713             </td>
4714             <td class="centered">
4715               <b>Yes</b>
4716             </td>
4717             <td class="centered">
4718               <b>Yes</b>
4719             </td>
4720           </tr>
4721           <tr>
4722             <th class="leftAligned">
4723               <paramlink id="klass"/>
4724             </th>
4725             <td class="centered">
4726               No
4727             </td>
4728             <td class="centered">
4729               <b>Yes</b>
4730             </td>
4731             <td class="centered">
4732               <b>Yes</b>
4733             </td>
4734           </tr>
4735         </table>
4736         <p/>
4737         During the execution of this function the state of the heap
4738         does not change: no objects are allocated, no objects are
4739         garbage collected, and the state of objects (including
4740         held values) does not change.
4741         As a result, threads executing Java
4742         programming language code, threads attempting to resume the
4743         execution of Java programming language code, and threads
4744         attempting to execute JNI functions are typically stalled.
4745       </description>
4746       <origin>new</origin>
4747       <capabilities>
4748         <required id="can_tag_objects"></required>
4749       </capabilities>
4750       <parameters>
4751         <param id="heap_filter">
4752           <jint/>
4753           <description>
4754             This bit vector of
4755             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
4756             restricts the objects for which the callback function is called.
4757             This applies to both the object and primitive callbacks.
4758           </description>
4759         </param>
4760         <param id="klass">
4761           <ptrtype>
4762             <jclass/>
4763             <nullok>callbacks are not limited to instances of a particular class</nullok>
4764           </ptrtype>
4765           <description>
4766             Callbacks are only reported when the object is an instance of
4767             this class.
4768             Objects which are instances of a subclass of <code>klass</code>
4769             are not reported.
4770             If <code>klass</code> is an interface, no objects are reported.
4771             This applies to both the object and primitive callbacks.
4772           </description>
4773         </param>
4774         <param id="callbacks">
4775           <inptr>
4776             <struct>jvmtiHeapCallbacks</struct>
4777           </inptr>
4778           <description>
4779             Structure defining the set callback functions.
4780           </description>
4781         </param>
4782         <param id="user_data">
4783           <inbuf>
4784             <void/>
4785             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
4786           </inbuf>
4787           <description>
4788             User supplied data to be passed to the callback.
4789           </description>
4790         </param>
4791       </parameters>
4792       <errors>
4793         <error id="JVMTI_ERROR_INVALID_CLASS">
4794           <paramlink id="klass"/> is not a valid class.
4795         </error>
4796       </errors>
4797     </function>
4798 
4799     <function id="GetTag" phase="start" num="106">
4800       <synopsis>Get Tag</synopsis>
4801       <description>
4802         Retrieve the tag associated with an object.
4803         The tag is a long value typically used to store a
4804         unique identifier or pointer to object information.
4805         The tag is set with
4806         <functionlink id="SetTag"></functionlink>.
4807         Objects for which no tags have been set return a
4808         tag value of zero.
4809       </description>
4810       <origin>new</origin>
4811       <capabilities>
4812         <required id="can_tag_objects"></required>
4813       </capabilities>
4814       <parameters>
4815         <param id="object">
4816           <jobject/>
4817             <description>
4818               The object whose tag is to be retrieved.
4819             </description>
4820         </param>
4821         <param id="tag_ptr">
4822           <outptr><jlong/></outptr>
4823           <description>
4824             On return, the referenced long is set to the value
4825             of the tag.
4826           </description>
4827         </param>
4828       </parameters>
4829       <errors>
4830       </errors>
4831     </function>
4832 
4833     <function id="SetTag" phase="start" num="107">
4834       <synopsis>Set Tag</synopsis>
4835       <description>
4836         Set the tag associated with an object.
4837         The tag is a long value typically used to store a
4838         unique identifier or pointer to object information.
4839         The tag is visible with
4840         <functionlink id="GetTag"></functionlink>.
4841       </description>
4842       <origin>new</origin>
4843       <capabilities>
4844         <required id="can_tag_objects"></required>
4845       </capabilities>
4846       <parameters>
4847         <param id="object">
4848           <jobject/>
4849             <description>
4850               The object whose tag is to be set.
4851             </description>
4852         </param>
4853         <param id="tag">
4854           <jlong/>
4855           <description>
4856             The new value of the tag.
4857           </description>
4858         </param>
4859       </parameters>
4860       <errors>
4861       </errors>
4862     </function>
4863 
4864     <function id="GetObjectsWithTags" num="114">
4865       <synopsis>Get Objects With Tags</synopsis>
4866       <description>
4867         Return objects in the heap with the specified tags.
4868         The format is parallel arrays of objects and tags.
4869       </description>
4870       <origin>new</origin>
4871       <capabilities>
4872         <required id="can_tag_objects"></required>
4873       </capabilities>
4874       <parameters>
4875         <param id="tag_count">
4876           <jint min="0"/>
4877             <description>
4878               Number of tags to scan for.
4879             </description>
4880         </param>
4881         <param id="tags">
4882           <inbuf incount="tag_count">
4883             <jlong/>
4884           </inbuf>
4885             <description>
4886               Scan for objects with these tags.
4887               Zero is not permitted in this array.
4888             </description>
4889         </param>
4890         <param id="count_ptr">
4891           <outptr>
4892             <jint/>
4893           </outptr>
4894             <description>
4895               Return the number of objects with any of the tags
4896               in <paramlink id="tags"/>.
4897             </description>
4898         </param>
4899         <param id="object_result_ptr">
4900           <allocbuf outcount="count_ptr">
4901             <jobject/>
4902             <nullok>this information is not returned</nullok>
4903           </allocbuf>
4904             <description>
4905               Returns the array of objects with any of the tags
4906               in <paramlink id="tags"/>.
4907             </description>
4908         </param>
4909         <param id="tag_result_ptr">
4910           <allocbuf outcount="count_ptr">
4911             <jlong/>
4912             <nullok>this information is not returned</nullok>
4913           </allocbuf>
4914             <description>
4915               For each object in <paramlink id="object_result_ptr"/>,
4916               return the tag at the corresponding index.
4917             </description>
4918         </param>
4919       </parameters>
4920       <errors>
4921         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
4922           Zero is present in <paramlink id="tags"></paramlink>.
4923         </error>
4924       </errors>
4925     </function>
4926 
4927     <function id="ForceGarbageCollection" num="108">
4928       <synopsis>Force Garbage Collection</synopsis>
4929       <description>
4930         Force the VM to perform a garbage collection.
4931         The garbage collection is as complete as possible.
4932         This function does not cause finalizers to be run.
4933         This function does not return until the garbage collection
4934         is finished.
4935         <p/>
4936         Although garbage collection is as complete
4937         as possible there is no guarantee that all
4938         <eventlink id="ObjectFree"/>
4939         events will have been
4940         sent by the time that this function
4941         returns. In particular, an object may be
4942         prevented from being freed because it
4943         is awaiting finalization.
4944       </description>
4945       <origin>new</origin>
4946       <capabilities>
4947       </capabilities>
4948       <parameters>
4949       </parameters>
4950       <errors>
4951       </errors>
4952     </function>
4953 
4954 
4955   </category>
4956 
4957   <category id="Heap_1_0" label="Heap (1.0)">
4958     <intro>
4959       <b>
4960         These functions and data types were introduced in the original
4961         <jvmti/> version 1.0 and have been superseded by more
4962       </b>
4963       <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
4964       <b>
4965         which:
4966       </b>
4967       <ul>
4968         <li>
4969           <b>
4970             Allow access to primitive values (the value of Strings, arrays,
4971             and primitive fields)
4972           </b>
4973         </li>
4974         <li>
4975           <b>
4976             Allow the tag of the referrer to be set, thus enabling more
4977             efficient localized reference graph building
4978           </b>
4979         </li>
4980         <li>
4981           <b>
4982             Provide more extensive filtering abilities
4983           </b>
4984         </li>
4985         <li>
4986           <b>
4987             Are extensible, allowing their abilities to grow in future versions of <jvmti/>
4988           </b>
4989         </li>
4990       </ul>
4991       <p/>
4992       <b>Please use the </b>
4993       <internallink id="Heap"><b>current Heap functions</b></internallink>.
4994         <p/>
4995         <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
4996           <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
4997             Tagged objects only.
4998           </constant>
4999           <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
5000             Untagged objects only.
5001           </constant>
5002           <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
5003             Either tagged or untagged objects.
5004           </constant>
5005         </constants>
5006 
5007         <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
5008           <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
5009             JNI global reference.
5010           </constant>
5011           <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
5012             System class.
5013           </constant>
5014           <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
5015             Monitor.
5016           </constant>
5017           <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
5018             Stack local.
5019           </constant>
5020           <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
5021             JNI local reference.
5022           </constant>
5023           <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
5024             Thread.
5025           </constant>
5026           <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
5027             Other.
5028           </constant>
5029         </constants>
5030 
5031         <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
5032           <constant id="JVMTI_REFERENCE_CLASS" num="1">
5033             Reference from an object to its class.
5034           </constant>
5035           <constant id="JVMTI_REFERENCE_FIELD" num="2">
5036             Reference from an object to the value of one of its instance fields.
5037             For references of this kind the <code>referrer_index</code>
5038             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5039             jvmtiObjectReferenceCallback</internallink> is the index of the
5040             the instance field. The index is based on the order of all the
5041             object's fields. This includes all fields of the directly declared
5042             static and instance fields in the class, and includes all fields (both
5043             public and private) fields declared in superclasses and superinterfaces.
5044             The index is thus calculated by summing the index of the field in the directly
5045             declared class (see <functionlink id="GetClassFields"/>), with the total
5046             number of fields (both public and private) declared in all superclasses
5047             and superinterfaces. The index starts at zero.
5048           </constant>
5049           <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
5050             Reference from an array to one of its elements.
5051             For references of this kind the <code>referrer_index</code>
5052             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5053             jvmtiObjectReferenceCallback</internallink> is the array index.
5054           </constant>
5055           <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
5056             Reference from a class to its class loader.
5057           </constant>
5058           <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
5059             Reference from a class to its signers array.
5060           </constant>
5061           <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
5062             Reference from a class to its protection domain.
5063           </constant>
5064           <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
5065             Reference from a class to one of its interfaces.
5066           </constant>
5067           <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
5068             Reference from a class to the value of one of its static fields.
5069             For references of this kind the <code>referrer_index</code>
5070             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5071             jvmtiObjectReferenceCallback</internallink> is the index of the
5072             the static field. The index is based on the order of all the
5073             object's fields. This includes all fields of the directly declared
5074             static and instance fields in the class, and includes all fields (both
5075             public and private) fields declared in superclasses and superinterfaces.
5076             The index is thus calculated by summing the index of the field in the directly
5077             declared class (see <functionlink id="GetClassFields"/>), with the total
5078             number of fields (both public and private) declared in all superclasses
5079             and superinterfaces. The index starts at zero.
5080             Note: this definition differs from that in the <jvmti/> 1.0 Specification.
5081             <rationale>No known implementations used the 1.0 definition.</rationale>
5082           </constant>
5083           <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
5084             Reference from a class to a resolved entry in the constant pool.
5085             For references of this kind the <code>referrer_index</code>
5086             parameter to the <internallink id="jvmtiObjectReferenceCallback">
5087             jvmtiObjectReferenceCallback</internallink> is the index into
5088             constant pool table of the class, starting at 1. See
5089             <vmspec chapter="4.4"/>.
5090           </constant>
5091         </constants>
5092 
5093         <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
5094           <constant id="JVMTI_ITERATION_CONTINUE" num="1">
5095             Continue the iteration.
5096             If this is a reference iteration, follow the references of this object.
5097           </constant>
5098           <constant id="JVMTI_ITERATION_IGNORE" num="2">
5099             Continue the iteration.
5100             If this is a reference iteration, ignore the references of this object.
5101           </constant>
5102           <constant id="JVMTI_ITERATION_ABORT" num="0">
5103             Abort the iteration.
5104           </constant>
5105         </constants>
5106     </intro>
5107 
5108     <callback id="jvmtiHeapObjectCallback">
5109       <enum>jvmtiIterationControl</enum>
5110       <synopsis>Heap Object Callback</synopsis>
5111       <description>
5112         Agent supplied callback function.
5113         Describes (but does not pass in) an object in the heap.
5114         <p/>
5115         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5116         or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5117         <p/>
5118         See the <internallink id="heapCallbacks">heap callback
5119         function restrictions</internallink>.
5120       </description>
5121       <parameters>
5122         <param id="class_tag">
5123           <jlong/>
5124           <description>
5125             The tag of the class of object (zero if the class is not tagged).
5126             If the object represents a runtime class,
5127             the <code>class_tag</code> is the tag
5128             associated with <code>java.lang.Class</code>
5129             (zero if <code>java.lang.Class</code> is not tagged).
5130           </description>
5131         </param>
5132         <param id="size">
5133           <jlong/>
5134           <description>
5135             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5136           </description>
5137         </param>
5138         <param id="tag_ptr">
5139           <outptr><jlong/></outptr>
5140           <description>
5141             The object tag value, or zero if the object is not tagged.
5142             To set the tag value to be associated with the object
5143             the agent sets the <code>jlong</code> pointed to by the parameter.
5144           </description>
5145         </param>
5146         <param id="user_data">
5147           <outptr><void/></outptr>
5148           <description>
5149             The user supplied data that was passed into the iteration function.
5150           </description>
5151         </param>
5152       </parameters>
5153     </callback>
5154 
5155     <callback id="jvmtiHeapRootCallback">
5156       <enum>jvmtiIterationControl</enum>
5157       <synopsis>Heap Root Object Callback</synopsis>
5158       <description>
5159         Agent supplied callback function.
5160         Describes (but does not pass in) an object that is a root for the purposes
5161         of garbage collection.
5162         <p/>
5163         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5164         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5165         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5166         <p/>
5167         See the <internallink id="heapCallbacks">heap callback
5168         function restrictions</internallink>.
5169       </description>
5170       <parameters>
5171         <param id="root_kind">
5172           <enum>jvmtiHeapRootKind</enum>
5173           <description>
5174             The kind of heap root.
5175           </description>
5176         </param>
5177         <param id="class_tag">
5178           <jlong/>
5179           <description>
5180             The tag of the class of object (zero if the class is not tagged).
5181             If the object represents a runtime class, the <code>class_tag</code> is the tag
5182             associated with <code>java.lang.Class</code>
5183             (zero if <code>java.lang.Class</code> is not tagged).
5184           </description>
5185         </param>
5186         <param id="size">
5187           <jlong/>
5188           <description>
5189             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5190           </description>
5191         </param>
5192         <param id="tag_ptr">
5193           <outptr><jlong/></outptr>
5194           <description>
5195             The object tag value, or zero if the object is not tagged.
5196             To set the tag value to be associated with the object
5197             the agent sets the <code>jlong</code> pointed to by the parameter.
5198           </description>
5199         </param>
5200         <param id="user_data">
5201           <outptr><void/></outptr>
5202           <description>
5203             The user supplied data that was passed into the iteration function.
5204           </description>
5205         </param>
5206       </parameters>
5207     </callback>
5208 
5209     <callback id="jvmtiStackReferenceCallback">
5210       <enum>jvmtiIterationControl</enum>
5211       <synopsis>Stack Reference Object Callback</synopsis>
5212       <description>
5213         Agent supplied callback function.
5214         Describes (but does not pass in) an object on the stack that is a root for
5215         the purposes of garbage collection.
5216         <p/>
5217         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5218         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5219         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5220         <p/>
5221         See the <internallink id="heapCallbacks">heap callback
5222         function restrictions</internallink>.
5223       </description>
5224       <parameters>
5225         <param id="root_kind">
5226           <enum>jvmtiHeapRootKind</enum>
5227           <description>
5228             The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5229             <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
5230           </description>
5231         </param>
5232         <param id="class_tag">
5233           <jlong/>
5234           <description>
5235            The tag of the class of object (zero if the class is not tagged).
5236            If the object represents a runtime class, the  <code>class_tag</code> is the tag
5237            associated with <code>java.lang.Class</code>
5238            (zero if <code>java.lang.Class</code> is not tagged).
5239           </description>
5240         </param>
5241         <param id="size">
5242           <jlong/>
5243           <description>
5244             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
5245           </description>
5246         </param>
5247         <param id="tag_ptr">
5248           <outptr><jlong/></outptr>
5249           <description>
5250             The object tag value, or zero if the object is not tagged.
5251             To set the tag value to be associated with the object
5252             the agent sets the <code>jlong</code> pointed to by the parameter.
5253           </description>
5254         </param>
5255         <param id="thread_tag">
5256           <jlong/>
5257           <description>
5258             The tag of the thread corresponding to this stack, zero if not tagged.
5259           </description>
5260         </param>
5261         <param id="depth">
5262           <jint/>
5263           <description>
5264             The depth of the frame.
5265           </description>
5266         </param>
5267         <param id="method">
5268           <jmethodID/>
5269           <description>
5270             The method executing in this frame.
5271           </description>
5272         </param>
5273         <param id="slot">
5274           <jint/>
5275           <description>
5276             The slot number.
5277           </description>
5278         </param>
5279         <param id="user_data">
5280           <outptr><void/></outptr>
5281           <description>
5282             The user supplied data that was passed into the iteration function.
5283           </description>
5284         </param>
5285       </parameters>
5286     </callback>
5287 
5288     <callback id="jvmtiObjectReferenceCallback">
5289       <enum>jvmtiIterationControl</enum>
5290       <synopsis>Object Reference Callback</synopsis>
5291       <description>
5292         Agent supplied callback function.
5293         Describes a reference from an object (the referrer) to another object
5294         (the referree).
5295         <p/>
5296         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
5297         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
5298         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
5299         <p/>
5300         See the <internallink id="heapCallbacks">heap callback
5301         function restrictions</internallink>.
5302       </description>
5303       <parameters>
5304         <param id="reference_kind">
5305           <enum>jvmtiObjectReferenceKind</enum>
5306           <description>
5307             The type of reference.
5308           </description>
5309         </param>
5310         <param id="class_tag">
5311           <jlong/>
5312           <description>
5313             The tag of the class of referree object (zero if the class is not tagged).
5314             If the referree object represents a runtime class,
5315             the  <code>class_tag</code> is the tag
5316             associated with <code>java.lang.Class</code>
5317             (zero if <code>java.lang.Class</code> is not tagged).
5318           </description>
5319         </param>
5320         <param id="size">
5321           <jlong/>
5322           <description>
5323             Size of the referree object (in bytes).
5324             See <functionlink id="GetObjectSize"/>.
5325           </description>
5326         </param>
5327         <param id="tag_ptr">
5328           <outptr><jlong/></outptr>
5329           <description>
5330             The referree object tag value, or zero if the object is not
5331             tagged.
5332             To set the tag value to be associated with the object
5333             the agent sets the <code>jlong</code> pointed to by the parameter.
5334           </description>
5335         </param>
5336         <param id="referrer_tag">
5337           <jlong/>
5338           <description>
5339             The tag of the referrer object, or zero if the referrer
5340             object is not tagged.
5341           </description>
5342         </param>
5343         <param id="referrer_index">
5344           <jint/>
5345           <description>
5346             For references of type <code>JVMTI_REFERENCE_FIELD</code> or
5347             <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
5348             of the field in the referrer object. The index is based on the
5349             order of all the object's fields - see <internallink
5350             id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
5351             or <internallink
5352             id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
5353             </internallink> for further description.
5354             <p/>
5355             For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
5356             the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
5357             JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
5358             <p/>
5359             For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
5360             the index into the constant pool of the class - see
5361             <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
5362             JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further
5363             description.
5364             <p/>
5365             For references of other kinds the <code>referrer_index</code> is
5366             <code>-1</code>.
5367           </description>
5368         </param>
5369         <param id="user_data">
5370           <outptr><void/></outptr>
5371           <description>
5372             The user supplied data that was passed into the iteration function.
5373           </description>
5374         </param>
5375       </parameters>
5376     </callback>
5377 
5378     <function id="IterateOverObjectsReachableFromObject" num="109">
5379       <synopsis>Iterate Over Objects Reachable From Object</synopsis>
5380       <description>
5381         This function iterates over all objects that are directly
5382         and indirectly reachable from the specified object.
5383         For each object <i>A</i> (known
5384         as the referrer) with a reference to object <i>B</i> the specified
5385         callback function is called to describe the object reference.
5386         The callback is called exactly once for each reference from a referrer;
5387         this is true even if there are reference cycles or multiple paths to
5388         the referrer.
5389         There may be more than one reference between a referrer and a referree,
5390         These may be distinguished by the
5391         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5392         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5393         The callback for an object will always occur after the callback for
5394         its referrer.
5395         <p/>
5396         See <functionlink id="FollowReferences"/> for the object
5397         references which are reported.
5398         <p/>
5399         During the execution of this function the state of the heap
5400         does not change: no objects are allocated, no objects are
5401         garbage collected, and the state of objects (including
5402         held values) does not change.
5403         As a result, threads executing Java
5404         programming language code, threads attempting to resume the
5405         execution of Java programming language code, and threads
5406         attempting to execute JNI functions are typically stalled.
5407       </description>
5408       <origin>new</origin>
5409       <capabilities>
5410         <required id="can_tag_objects"></required>
5411       </capabilities>
5412       <parameters>
5413         <param id="object">
5414           <jobject/>
5415             <description>
5416               The object
5417             </description>
5418         </param>
5419         <param id="object_reference_callback">
5420           <ptrtype>
5421             <struct>jvmtiObjectReferenceCallback</struct>
5422           </ptrtype>
5423             <description>
5424               The callback to be called to describe each
5425               object reference.
5426             </description>
5427         </param>
5428         <param id="user_data">
5429           <inbuf>
5430             <void/>
5431             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5432           </inbuf>
5433           <description>
5434             User supplied data to be passed to the callback.
5435           </description>
5436         </param>
5437       </parameters>
5438       <errors>
5439       </errors>
5440     </function>
5441 
5442     <function id="IterateOverReachableObjects" num="110">
5443       <synopsis>Iterate Over Reachable Objects</synopsis>
5444       <description>
5445         This function iterates over the root objects and all objects that
5446         are directly and indirectly reachable from the root objects.
5447         The root objects comprise the set of system classes,
5448         JNI globals, references from thread stacks, and other objects used as roots
5449         for the purposes of garbage collection.
5450         <p/>
5451         For each root the <paramlink id="heap_root_callback"></paramlink>
5452         or <paramlink id="stack_ref_callback"></paramlink> callback is called.
5453         An object can be a root object for more than one reason and in that case
5454         the appropriate callback is called for each reason.
5455         <p/>
5456         For each object reference the <paramlink id="object_ref_callback"></paramlink>
5457         callback function is called to describe the object reference.
5458         The callback is called exactly once for each reference from a referrer;
5459         this is true even if there are reference cycles or multiple paths to
5460         the referrer.
5461         There may be more than one reference between a referrer and a referree,
5462         These may be distinguished by the
5463         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
5464         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
5465         The callback for an object will always occur after the callback for
5466         its referrer.
5467         <p/>
5468         See <functionlink id="FollowReferences"/> for the object
5469         references which are reported.
5470         <p/>
5471         Roots are always reported to the profiler before any object references
5472         are reported. In other words, the <paramlink id="object_ref_callback"></paramlink>
5473         callback will not be called until the appropriate callback has been called
5474         for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is
5475         specified as <code>NULL</code> then this function returns after
5476         reporting the root objects to the profiler.
5477         <p/>
5478         During the execution of this function the state of the heap
5479         does not change: no objects are allocated, no objects are
5480         garbage collected, and the state of objects (including
5481         held values) does not change.
5482         As a result, threads executing Java
5483         programming language code, threads attempting to resume the
5484         execution of Java programming language code, and threads
5485         attempting to execute JNI functions are typically stalled.
5486       </description>
5487       <origin>new</origin>
5488       <capabilities>
5489         <required id="can_tag_objects"></required>
5490       </capabilities>
5491       <parameters>
5492         <param id="heap_root_callback">
5493           <ptrtype>
5494             <struct>jvmtiHeapRootCallback</struct>
5495             <nullok>do not report heap roots</nullok>
5496           </ptrtype>
5497             <description>
5498               The callback function to be called for each heap root of type
5499               <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
5500               <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
5501               <code>JVMTI_HEAP_ROOT_MONITOR</code>,
5502               <code>JVMTI_HEAP_ROOT_THREAD</code>, or
5503               <code>JVMTI_HEAP_ROOT_OTHER</code>.
5504             </description>
5505         </param>
5506         <param id="stack_ref_callback">
5507           <ptrtype>
5508             <struct>jvmtiStackReferenceCallback</struct>
5509             <nullok>do not report stack references</nullok>
5510           </ptrtype>
5511             <description>
5512               The callback function to be called for each heap root of
5513               <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
5514               <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
5515             </description>
5516         </param>
5517         <param id="object_ref_callback">
5518           <ptrtype>
5519             <struct>jvmtiObjectReferenceCallback</struct>
5520             <nullok>do not follow references from the root objects</nullok>
5521           </ptrtype>
5522             <description>
5523               The callback function to be called for each object reference.
5524             </description>
5525         </param>
5526         <param id="user_data">
5527           <inbuf>
5528             <void/>
5529             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5530           </inbuf>
5531           <description>
5532             User supplied data to be passed to the callback.
5533           </description>
5534         </param>
5535       </parameters>
5536       <errors>
5537       </errors>
5538     </function>
5539 
5540     <function id="IterateOverHeap" num="111">
5541       <synopsis>Iterate Over Heap</synopsis>
5542       <description>
5543         Iterate over all objects in the heap. This includes both reachable and
5544         unreachable objects.
5545         <p/>
5546         The <paramlink id="object_filter"></paramlink> parameter indicates the
5547         objects for which the callback function is called. If this parameter
5548         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
5549         called for every object that is tagged. If the parameter is
5550         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5551         for objects that are not tagged. If the parameter
5552         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5553         called for every object in the heap, irrespective of whether it is
5554         tagged or not.
5555         <p/>
5556         During the execution of this function the state of the heap
5557         does not change: no objects are allocated, no objects are
5558         garbage collected, and the state of objects (including
5559         held values) does not change.
5560         As a result, threads executing Java
5561         programming language code, threads attempting to resume the
5562         execution of Java programming language code, and threads
5563         attempting to execute JNI functions are typically stalled.
5564       </description>
5565       <origin>new</origin>
5566       <capabilities>
5567         <required id="can_tag_objects"></required>
5568       </capabilities>
5569       <parameters>
5570         <param id="object_filter">
5571           <enum>jvmtiHeapObjectFilter</enum>
5572           <description>
5573             Indicates the objects for which the callback function is called.
5574           </description>
5575         </param>
5576         <param id="heap_object_callback">
5577           <ptrtype>
5578             <struct>jvmtiHeapObjectCallback</struct>
5579           </ptrtype>
5580             <description>
5581               The iterator function to be called for each
5582               object matching the <paramlink id="object_filter"/>.
5583             </description>
5584         </param>
5585         <param id="user_data">
5586           <inbuf>
5587             <void/>
5588             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5589           </inbuf>
5590           <description>
5591             User supplied data to be passed to the callback.
5592           </description>
5593         </param>
5594       </parameters>
5595       <errors>
5596       </errors>
5597     </function>
5598 
5599     <function id="IterateOverInstancesOfClass" num="112">
5600       <synopsis>Iterate Over Instances Of Class</synopsis>
5601       <description>
5602         Iterate over all objects in the heap that are instances of the specified class.
5603         This includes direct instances of the specified class and
5604         instances of all subclasses of the specified class.
5605         This includes both reachable and unreachable objects.
5606         <p/>
5607         The <paramlink id="object_filter"></paramlink> parameter indicates the
5608         objects for which the callback function is called. If this parameter
5609         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
5610         called for every object that is tagged. If the parameter is
5611         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
5612         called for objects that are not tagged. If the parameter
5613         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
5614         called for every object in the heap, irrespective of whether it is
5615         tagged or not.
5616         <p/>
5617         During the execution of this function the state of the heap
5618         does not change: no objects are allocated, no objects are
5619         garbage collected, and the state of objects (including
5620         held values) does not change.
5621         As a result, threads executing Java
5622         programming language code, threads attempting to resume the
5623         execution of Java programming language code, and threads
5624         attempting to execute JNI functions are typically stalled.
5625       </description>
5626       <origin>new</origin>
5627       <capabilities>
5628         <required id="can_tag_objects"></required>
5629       </capabilities>
5630       <parameters>
5631         <param id="klass">
5632           <jclass/>
5633             <description>
5634               Iterate over objects of this class only.
5635             </description>
5636         </param>
5637         <param id="object_filter">
5638           <enum>jvmtiHeapObjectFilter</enum>
5639           <description>
5640             Indicates the objects for which the callback function is called.
5641           </description>
5642         </param>
5643         <param id="heap_object_callback">
5644           <ptrtype>
5645             <struct>jvmtiHeapObjectCallback</struct>
5646           </ptrtype>
5647             <description>
5648               The iterator function to be called for each
5649               <paramlink id="klass"/> instance matching
5650               the <paramlink id="object_filter"/>.
5651             </description>
5652         </param>
5653         <param id="user_data">
5654           <inbuf>
5655             <void/>
5656             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
5657           </inbuf>
5658           <description>
5659             User supplied data to be passed to the callback.
5660           </description>
5661         </param>
5662       </parameters>
5663       <errors>
5664       </errors>
5665     </function>
5666 
5667   </category>
5668 
5669   <category id="local" label="Local Variable">
5670 
5671     <intro>
5672       These functions are used to retrieve or set the value of a local variable.
5673       The variable is identified by the depth of the frame containing its
5674       value and the variable's slot number within that frame.
5675       The mapping of variables to
5676       slot numbers can be obtained with the function
5677       <functionlink id="GetLocalVariableTable"></functionlink>.
5678     </intro>
5679 
5680     <function id="GetLocalObject" num="21">
5681       <synopsis>Get Local Variable - Object</synopsis>
5682       <description>
5683         This function can be used to retrieve the value of a local
5684         variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
5685       </description>
5686       <origin>jvmdi</origin>
5687       <capabilities>
5688         <required id="can_access_local_variables"></required>
5689       </capabilities>
5690       <parameters>
5691         <param id="thread">
5692           <jthread null="current" frame="frame"/>
5693           <description>
5694             The thread of the frame containing the variable's value.
5695           </description>
5696         </param>
5697         <param id="depth">
5698           <jframeID thread="thread"/>
5699           <description>
5700             The depth of the frame containing the variable's value.
5701           </description>
5702         </param>
5703         <param id="slot">
5704           <jint/>
5705           <description>
5706             The variable's slot number.
5707           </description>
5708         </param>
5709         <param id="value_ptr">
5710           <outptr><jobject/></outptr>
5711             <description>
5712               On return, points to the variable's value.
5713             </description>
5714         </param>
5715       </parameters>
5716       <errors>
5717         <error id="JVMTI_ERROR_INVALID_SLOT">
5718           Invalid <code>slot</code>.
5719         </error>
5720         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5721           The variable type is not
5722           <code>Object</code> or a subclass of <code>Object</code>.
5723         </error>
5724         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5725           Not a visible frame
5726         </error>
5727       </errors>
5728     </function>
5729 
5730     <function id="GetLocalInstance" num="155" since="1.2">
5731       <synopsis>Get Local Instance</synopsis>
5732       <description>
5733         This function can be used to retrieve the value of the local object
5734         variable at slot 0 (the "<code>this</code>" object) from non-static
5735         frames.  This function can retrieve the "<code>this</code>" object from
5736         native method frames, whereas <code>GetLocalObject()</code> would
5737         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
5738       </description>
5739       <origin>new</origin>
5740       <capabilities>
5741         <required id="can_access_local_variables"></required>
5742       </capabilities>
5743       <parameters>
5744         <param id="thread">
5745           <jthread null="current" frame="frame"/>
5746           <description>
5747             The thread of the frame containing the variable's value.
5748           </description>
5749         </param>
5750         <param id="depth">
5751           <jframeID thread="thread"/>
5752           <description>
5753             The depth of the frame containing the variable's value.
5754           </description>
5755         </param>
5756         <param id="value_ptr">
5757           <outptr><jobject/></outptr>
5758             <description>
5759               On return, points to the variable's value.
5760             </description>
5761         </param>
5762       </parameters>
5763       <errors>
5764         <error id="JVMTI_ERROR_INVALID_SLOT">
5765           If the specified frame is a static method frame.
5766         </error>
5767       </errors>
5768     </function>
5769     <function id="GetLocalInt" num="22">
5770       <synopsis>Get Local Variable - Int</synopsis>
5771       <description>
5772         This function can be used to retrieve the value of a local
5773         variable whose type is <code>int</code>,
5774         <code>short</code>, <code>char</code>, <code>byte</code>, or
5775         <code>boolean</code>.
5776       </description>
5777       <origin>jvmdi</origin>
5778       <capabilities>
5779         <required id="can_access_local_variables"></required>
5780       </capabilities>
5781       <parameters>
5782         <param id="thread">
5783           <jthread null="current" frame="frame"/>
5784           <description>
5785             The thread of the frame containing the variable's value.
5786           </description>
5787         </param>
5788         <param id="depth">
5789           <jframeID thread="thread"/>
5790           <description>
5791             The depth of the frame containing the variable's value.
5792           </description>
5793         </param>
5794         <param id="slot">
5795           <jint/>
5796           <description>
5797             The variable's slot number.
5798           </description>
5799         </param>
5800         <param id="value_ptr">
5801           <outptr><jint/></outptr>
5802           <description>
5803             On return, points to the variable's value.
5804           </description>
5805         </param>
5806       </parameters>
5807       <errors>
5808         <error id="JVMTI_ERROR_INVALID_SLOT">
5809           Invalid <code>slot</code>.
5810         </error>
5811         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5812           The variable type is not
5813           <code>int</code>, <code>short</code>,
5814           <code>char</code>, <code>byte</code>, or
5815           <code>boolean</code>.
5816         </error>
5817         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5818           Not a visible frame
5819         </error>
5820       </errors>
5821     </function>
5822 
5823     <function id="GetLocalLong" num="23">
5824       <synopsis>Get Local Variable - Long</synopsis>
5825       <description>
5826         This function can be used to retrieve the value of a local
5827         variable whose type is <code>long</code>.
5828       </description>
5829       <origin>jvmdi</origin>
5830       <capabilities>
5831         <required id="can_access_local_variables"></required>
5832       </capabilities>
5833       <parameters>
5834         <param id="thread">
5835           <jthread null="current" frame="frame"/>
5836           <description>
5837             The thread of the frame containing the variable's value.
5838           </description>
5839         </param>
5840         <param id="depth">
5841           <jframeID thread="thread"/>
5842           <description>
5843             The depth of the frame containing the variable's value.
5844           </description>
5845         </param>
5846         <param id="slot">
5847           <jint/>
5848           <description>
5849             The variable's slot number.
5850           </description>
5851         </param>
5852         <param id="value_ptr">
5853           <outptr><jlong/></outptr>
5854           <description>
5855             On return, points to the variable's value.
5856           </description>
5857         </param>
5858       </parameters>
5859       <errors>
5860         <error id="JVMTI_ERROR_INVALID_SLOT">
5861           Invalid <code>slot</code>.
5862         </error>
5863         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5864           The variable type is not <code>long</code>.
5865         </error>
5866         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5867           Not a visible frame
5868         </error>
5869       </errors>
5870     </function>
5871 
5872     <function id="GetLocalFloat" num="24">
5873       <synopsis>Get Local Variable - Float</synopsis>
5874       <description>
5875         This function can be used to retrieve the value of a local
5876         variable whose type is <code>float</code>.
5877       </description>
5878       <origin>jvmdi</origin>
5879       <capabilities>
5880         <required id="can_access_local_variables"></required>
5881       </capabilities>
5882       <parameters>
5883         <param id="thread">
5884           <jthread null="current" frame="frame"/>
5885           <description>
5886             The thread of the frame containing the variable's value.
5887           </description>
5888         </param>
5889         <param id="depth">
5890           <jframeID thread="thread"/>
5891           <description>
5892             The depth of the frame containing the variable's value.
5893           </description>
5894         </param>
5895         <param id="slot">
5896           <jint/>
5897           <description>
5898             The variable's slot number.
5899           </description>
5900         </param>
5901         <param id="value_ptr">
5902           <outptr><jfloat/></outptr>
5903           <description>
5904             On return, points to the variable's value.
5905           </description>
5906         </param>
5907       </parameters>
5908       <errors>
5909         <error id="JVMTI_ERROR_INVALID_SLOT">
5910           Invalid <code>slot</code>.
5911         </error>
5912         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5913           The variable type is not <code>float</code>.
5914         </error>
5915         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5916           Not a visible frame
5917         </error>
5918       </errors>
5919     </function>
5920 
5921     <function id="GetLocalDouble" num="25">
5922       <synopsis>Get Local Variable - Double</synopsis>
5923       <description>
5924         This function can be used to retrieve the value of a local
5925         variable whose type is <code>long</code>.
5926       </description>
5927       <origin>jvmdi</origin>
5928       <capabilities>
5929         <required id="can_access_local_variables"></required>
5930       </capabilities>
5931       <parameters>
5932         <param id="thread">
5933           <jthread null="current" frame="frame"/>
5934           <description>
5935             The thread of the frame containing the variable's value.
5936           </description>
5937         </param>
5938         <param id="depth">
5939           <jframeID thread="thread"/>
5940           <description>
5941             The depth of the frame containing the variable's value.
5942           </description>
5943         </param>
5944         <param id="slot">
5945           <jint/>
5946           <description>
5947             The variable's slot number.
5948           </description>
5949         </param>
5950         <param id="value_ptr">
5951           <outptr><jdouble/></outptr>
5952           <description>
5953             On return, points to the variable's value.
5954           </description>
5955         </param>
5956       </parameters>
5957       <errors>
5958         <error id="JVMTI_ERROR_INVALID_SLOT">
5959           Invalid <code>slot</code>.
5960         </error>
5961         <error id="JVMTI_ERROR_TYPE_MISMATCH">
5962           The variable type is not <code>double</code>.
5963         </error>
5964         <error id="JVMTI_ERROR_OPAQUE_FRAME">
5965           Not a visible frame
5966         </error>
5967       </errors>
5968     </function>
5969 
5970     <function id="SetLocalObject" num="26">
5971       <synopsis>Set Local Variable - Object</synopsis>
5972       <description>
5973         This function can be used to set the value of a local
5974         variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
5975       </description>
5976       <origin>jvmdi</origin>
5977       <capabilities>
5978         <required id="can_access_local_variables"></required>
5979       </capabilities>
5980       <parameters>
5981         <param id="thread">
5982           <jthread null="current" frame="frame"/>
5983           <description>
5984             The thread of the frame containing the variable's value.
5985           </description>
5986         </param>
5987         <param id="depth">
5988           <jframeID thread="thread"/>
5989           <description>
5990             The depth of the frame containing the variable's value.
5991           </description>
5992         </param>
5993         <param id="slot">
5994           <jint/>
5995           <description>
5996             The variable's slot number.
5997           </description>
5998         </param>
5999         <param id="value">
6000           <jobject/>
6001             <description>
6002               The new value for the variable.
6003             </description>
6004         </param>
6005       </parameters>
6006       <errors>
6007         <error id="JVMTI_ERROR_INVALID_SLOT">
6008           Invalid <code>slot</code>.
6009         </error>
6010         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6011           The variable type is not
6012           <code>Object</code> or a subclass of <code>Object</code>.
6013         </error>
6014         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6015           The supplied <paramlink id="value"/> is not compatible
6016           with the variable type.
6017         </error>
6018         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6019           Not a visible frame
6020         </error>
6021       </errors>
6022     </function>
6023 
6024     <function id="SetLocalInt" num="27">
6025       <synopsis>Set Local Variable - Int</synopsis>
6026       <description>
6027         This function can be used to set the value of a local
6028         variable whose type is <code>int</code>,
6029         <code>short</code>, <code>char</code>, <code>byte</code>, or
6030         <code>boolean</code>.
6031       </description>
6032       <origin>jvmdi</origin>
6033       <capabilities>
6034         <required id="can_access_local_variables"></required>
6035       </capabilities>
6036       <parameters>
6037         <param id="thread">
6038           <jthread null="current" frame="frame"/>
6039           <description>
6040             The thread of the frame containing the variable's value.
6041           </description>
6042         </param>
6043         <param id="depth">
6044           <jframeID thread="thread"/>
6045           <description>
6046             The depth of the frame containing the variable's value.
6047           </description>
6048         </param>
6049         <param id="slot">
6050           <jint/>
6051           <description>
6052             The variable's slot number.
6053           </description>
6054         </param>
6055         <param id="value">
6056           <jint/>
6057           <description>
6058             The new value for the variable.
6059           </description>
6060         </param>
6061       </parameters>
6062       <errors>
6063         <error id="JVMTI_ERROR_INVALID_SLOT">
6064           Invalid <code>slot</code>.
6065         </error>
6066         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6067           The variable type is not
6068           <code>int</code>, <code>short</code>,
6069           <code>char</code>, <code>byte</code>, or
6070           <code>boolean</code>.
6071         </error>
6072         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6073           Not a visible frame
6074         </error>
6075       </errors>
6076     </function>
6077 
6078     <function id="SetLocalLong" num="28">
6079       <synopsis>Set Local Variable - Long</synopsis>
6080       <description>
6081         This function can be used to set the value of a local
6082         variable whose type is <code>long</code>.
6083       </description>
6084       <origin>jvmdi</origin>
6085       <capabilities>
6086         <required id="can_access_local_variables"></required>
6087       </capabilities>
6088       <parameters>
6089         <param id="thread">
6090           <jthread null="current" frame="frame"/>
6091           <description>
6092             The thread of the frame containing the variable's value.
6093           </description>
6094         </param>
6095         <param id="depth">
6096           <jframeID thread="thread"/>
6097           <description>
6098             The depth of the frame containing the variable's value.
6099           </description>
6100         </param>
6101         <param id="slot">
6102           <jint/>
6103           <description>
6104             The variable's slot number.
6105           </description>
6106         </param>
6107         <param id="value">
6108           <jlong/>
6109           <description>
6110             The new value for the variable.
6111           </description>
6112         </param>
6113       </parameters>
6114       <errors>
6115         <error id="JVMTI_ERROR_INVALID_SLOT">
6116           Invalid <code>slot</code>.
6117         </error>
6118         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6119           The variable type is not <code>long</code>.
6120         </error>
6121         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6122           Not a visible frame
6123         </error>
6124       </errors>
6125     </function>
6126 
6127     <function id="SetLocalFloat" num="29">
6128       <synopsis>Set Local Variable - Float</synopsis>
6129       <description>
6130         This function can be used to set the value of a local
6131         variable whose type is <code>float</code>.
6132       </description>
6133       <origin>jvmdi</origin>
6134       <capabilities>
6135         <required id="can_access_local_variables"></required>
6136       </capabilities>
6137       <parameters>
6138         <param id="thread">
6139           <jthread null="current" frame="frame"/>
6140           <description>
6141             The thread of the frame containing the variable's value.
6142           </description>
6143         </param>
6144         <param id="depth">
6145           <jframeID thread="thread"/>
6146           <description>
6147             The depth of the frame containing the variable's value.
6148           </description>
6149         </param>
6150         <param id="slot">
6151           <jint/>
6152           <description>
6153             The variable's slot number.
6154           </description>
6155         </param>
6156         <param id="value">
6157           <jfloat/>
6158           <description>
6159             The new value for the variable.
6160           </description>
6161         </param>
6162       </parameters>
6163       <errors>
6164         <error id="JVMTI_ERROR_INVALID_SLOT">
6165           Invalid <code>slot</code>.
6166         </error>
6167         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6168           The variable type is not <code>float</code>.
6169         </error>
6170         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6171           Not a visible frame
6172         </error>
6173       </errors>
6174     </function>
6175 
6176     <function id="SetLocalDouble" num="30">
6177       <synopsis>Set Local Variable - Double</synopsis>
6178       <description>
6179         This function can be used to set the value of a local
6180         variable whose type is <code>double</code>.
6181       </description>
6182       <origin>jvmdi</origin>
6183       <capabilities>
6184         <required id="can_access_local_variables"></required>
6185       </capabilities>
6186       <parameters>
6187         <param id="thread">
6188           <jthread null="current" frame="frame"/>
6189           <description>
6190             The thread of the frame containing the variable's value.
6191           </description>
6192         </param>
6193         <param id="depth">
6194           <jframeID thread="thread"/>
6195           <description>
6196             The depth of the frame containing the variable's value.
6197           </description>
6198         </param>
6199         <param id="slot">
6200           <jint/>
6201           <description>
6202             The variable's slot number.
6203           </description>
6204         </param>
6205         <param id="value">
6206           <jdouble/>
6207           <description>
6208             The new value for the variable.
6209           </description>
6210         </param>
6211       </parameters>
6212       <errors>
6213         <error id="JVMTI_ERROR_INVALID_SLOT">
6214           Invalid <code>slot</code>.
6215         </error>
6216         <error id="JVMTI_ERROR_TYPE_MISMATCH">
6217           The variable type is not <code>double</code>.
6218         </error>
6219         <error id="JVMTI_ERROR_OPAQUE_FRAME">
6220           Not a visible frame
6221         </error>
6222       </errors>
6223     </function>
6224   </category>
6225 
6226   <category id="breakpointCategory" label="Breakpoint">
6227 
6228     <intro>
6229     </intro>
6230 
6231     <function id="SetBreakpoint" num="38">
6232       <synopsis>Set Breakpoint</synopsis>
6233       <description>
6234         Set a breakpoint at the instruction indicated by
6235         <code>method</code> and <code>location</code>.
6236         An instruction can only have one breakpoint.
6237         <p/>
6238         Whenever the designated instruction is about to be executed, a
6239         <eventlink id="Breakpoint"></eventlink> event is generated.
6240       </description>
6241       <origin>jvmdi</origin>
6242       <capabilities>
6243         <required id="can_generate_breakpoint_events"></required>
6244       </capabilities>
6245       <parameters>
6246         <param id="klass">
6247           <jclass method="method"/>
6248             <description>
6249               The class in which to set the breakpoint
6250             </description>
6251         </param>
6252         <param id="method">
6253           <jmethodID class="klass"/>
6254             <description>
6255               The method in which to set the breakpoint
6256             </description>
6257         </param>
6258         <param id="location">
6259           <jlocation/>
6260           <description>
6261             the index of the instruction at which to set the breakpoint
6262 
6263           </description>
6264         </param>
6265       </parameters>
6266       <errors>
6267         <error id="JVMTI_ERROR_DUPLICATE">
6268           The designated bytecode already has a breakpoint.
6269         </error>
6270       </errors>
6271     </function>
6272 
6273     <function id="ClearBreakpoint" num="39">
6274       <synopsis>Clear Breakpoint</synopsis>
6275       <description>
6276         Clear the breakpoint at the bytecode indicated by
6277         <code>method</code> and <code>location</code>.
6278       </description>
6279       <origin>jvmdi</origin>
6280       <capabilities>
6281         <required id="can_generate_breakpoint_events"></required>
6282       </capabilities>
6283       <parameters>
6284         <param id="klass">
6285           <jclass method="method"/>
6286             <description>
6287               The class in which to clear the breakpoint
6288             </description>
6289         </param>
6290         <param id="method">
6291           <jmethodID class="klass"/>
6292             <description>
6293               The method in which to clear the breakpoint
6294             </description>
6295         </param>
6296         <param id="location">
6297           <jlocation/>
6298           <description>
6299             the index of the instruction at which to clear the breakpoint
6300           </description>
6301         </param>
6302       </parameters>
6303       <errors>
6304         <error id="JVMTI_ERROR_NOT_FOUND">
6305           There's no breakpoint at the designated bytecode.
6306         </error>
6307       </errors>
6308     </function>
6309 
6310   </category>
6311 
6312   <category id="fieldWatch" label="Watched Field">
6313 
6314     <intro>
6315     </intro>
6316 
6317     <function id="SetFieldAccessWatch" num="41">
6318       <synopsis>Set Field Access Watch</synopsis>
6319       <description>
6320         Generate a <eventlink id="FieldAccess"></eventlink> event
6321         when the field specified
6322         by <code>klass</code> and
6323         <code>field</code> is about to be accessed.
6324         An event will be generated for each access of the field
6325         until it is canceled with
6326         <functionlink id="ClearFieldAccessWatch"></functionlink>.
6327         Field accesses from Java programming language code or from JNI code are watched,
6328         fields modified by other means are not watched.
6329         Note that <jvmti/> users should be aware that their own field accesses
6330         will trigger the watch.
6331         A field can only have one field access watch set.
6332         Modification of a field is not considered an access--use
6333         <functionlink id="SetFieldModificationWatch"></functionlink>
6334         to monitor modifications.
6335       </description>
6336       <origin>jvmdi</origin>
6337       <capabilities>
6338         <required id="can_generate_field_access_events"></required>
6339       </capabilities>
6340       <parameters>
6341         <param id="klass">
6342           <jclass field="field"/>
6343             <description>
6344               The class containing the field to watch
6345             </description>
6346         </param>
6347         <param id="field">
6348           <jfieldID class="klass"/>
6349             <description>
6350               The field to watch
6351 
6352             </description>
6353         </param>
6354       </parameters>
6355       <errors>
6356         <error id="JVMTI_ERROR_DUPLICATE">
6357           The designated field is already being watched for accesses.
6358         </error>
6359       </errors>
6360     </function>
6361 
6362     <function id="ClearFieldAccessWatch" num="42">
6363       <synopsis>Clear Field Access Watch</synopsis>
6364       <description>
6365         Cancel a field access watch previously set by
6366         <functionlink id="SetFieldAccessWatch"></functionlink>, on the
6367         field specified
6368         by <code>klass</code> and
6369         <code>field</code>.
6370       </description>
6371       <origin>jvmdi</origin>
6372       <capabilities>
6373         <required id="can_generate_field_access_events"></required>
6374       </capabilities>
6375       <parameters>
6376         <param id="klass">
6377           <jclass field="field"/>
6378             <description>
6379               The class containing the field to watch
6380             </description>
6381         </param>
6382         <param id="field">
6383           <jfieldID class="klass"/>
6384             <description>
6385               The field to watch
6386 
6387             </description>
6388         </param>
6389       </parameters>
6390       <errors>
6391         <error id="JVMTI_ERROR_NOT_FOUND">
6392           The designated field is not being watched for accesses.
6393         </error>
6394       </errors>
6395     </function>
6396 
6397     <function id="SetFieldModificationWatch" num="43">
6398       <synopsis>Set Field Modification Watch</synopsis>
6399       <description>
6400         Generate a <eventlink id="FieldModification"></eventlink> event
6401         when the field specified
6402         by <code>klass</code> and
6403         <code>field</code> is about to be modified.
6404         An event will be generated for each modification of the field
6405         until it is canceled with
6406         <functionlink id="ClearFieldModificationWatch"></functionlink>.
6407         Field modifications from Java programming language code or from JNI code are watched,
6408         fields modified by other means are not watched.
6409         Note that <jvmti/> users should be aware that their own field modifications
6410         will trigger the watch.
6411         A field can only have one field modification watch set.
6412       </description>
6413       <origin>jvmdi</origin>
6414       <capabilities>
6415         <required id="can_generate_field_modification_events"></required>
6416       </capabilities>
6417       <parameters>
6418         <param id="klass">
6419           <jclass field="field"/>
6420             <description>
6421               The class containing the field to watch
6422             </description>
6423         </param>
6424         <param id="field">
6425           <jfieldID class="klass"/>
6426             <description>
6427               The field to watch
6428 
6429             </description>
6430         </param>
6431       </parameters>
6432       <errors>
6433         <error id="JVMTI_ERROR_DUPLICATE">
6434           The designated field is already being watched for modifications.
6435         </error>
6436       </errors>
6437     </function>
6438 
6439     <function id="ClearFieldModificationWatch" num="44">
6440       <synopsis>Clear Field Modification Watch</synopsis>
6441       <description>
6442 
6443         Cancel a field modification watch previously set by
6444         <functionlink id="SetFieldModificationWatch"></functionlink>, on the
6445         field specified
6446         by <code>klass</code> and
6447         <code>field</code>.
6448       </description>
6449       <origin>jvmdi</origin>
6450       <capabilities>
6451         <required id="can_generate_field_modification_events"></required>
6452       </capabilities>
6453       <parameters>
6454         <param id="klass">
6455           <jclass field="field"/>
6456             <description>
6457               The class containing the field to watch
6458             </description>
6459         </param>
6460         <param id="field">
6461           <jfieldID class="klass"/>
6462             <description>
6463               The field to watch
6464 
6465             </description>
6466         </param>
6467       </parameters>
6468       <errors>
6469         <error id="JVMTI_ERROR_NOT_FOUND">
6470           The designated field is not being watched for modifications.
6471         </error>
6472       </errors>
6473     </function>
6474   </category>
6475 
6476   <category id="module" label="Module">
6477 
6478     <intro>
6479     </intro>
6480 
6481     <function id="GetAllModules" num="3" since="9">
6482       <synopsis>Get All Modules</synopsis>
6483       <description>
6484         Return an array of all modules loaded in the virtual machine.
6485         The array includes the unnamed module for each class loader.
6486         The number of modules in the array is returned via
6487         <code>module_count_ptr</code>, and the array itself via
6488         <code>modules_ptr</code>.
6489         <p/>
6490       </description>
6491       <origin>new</origin>
6492       <capabilities>
6493       </capabilities>
6494       <parameters>
6495         <param id="module_count_ptr">
6496           <outptr><jint/></outptr>
6497           <description>
6498             On return, points to the number of returned modules.
6499           </description>
6500         </param>
6501         <param id="modules_ptr">
6502           <allocbuf outcount="module_count_ptr"><jobject/></allocbuf>
6503             <description>
6504               On return, points to an array of references, one
6505               for each module.
6506             </description>
6507         </param>
6508       </parameters>
6509       <errors>
6510       </errors>
6511     </function>
6512 
6513     <function id="GetNamedModule" num="40" since="9">
6514       <synopsis>Get Named Module</synopsis>
6515       <description>
6516         Return the <code>java.lang.Module</code> object for a named
6517         module defined to a class loader that contains a given package.
6518         The module is returned via <code>module_ptr</code>.
6519         <p/>
6520         If a named module is defined to the class loader and it
6521         contains the package then that named module is returned,
6522         otherwise <code>NULL</code> is returned.
6523         <p/>
6524       </description>
6525       <origin>new</origin>
6526       <capabilities>
6527       </capabilities>
6528       <parameters>
6529         <param id="class_loader">
6530           <ptrtype>
6531             <jobject/>
6532             <nullok>the bootstrap loader is assumed</nullok>
6533           </ptrtype>
6534           <description>
6535             A class loader.
6536             If the <code>class_loader</code> is not <code>NULL</code>
6537             or a subclass of <code>java.lang.ClassLoader</code>
6538             this function returns
6539             <errorlink id="JVMTI_ERROR_ILLEGAL_ARGUMENT"></errorlink>.
6540           </description>
6541         </param>
6542         <param id="package_name">
6543           <inbuf><char/></inbuf>
6544           <description>
6545             The name of the package, encoded as a
6546             <internallink id="mUTF">modified UTF-8</internallink> string.
6547             The package name is in internal form (JVMS 4.2.1);
6548             identifiers are separated by forward slashes rather than periods.
6549           </description>
6550         </param>
6551         <param id="module_ptr">
6552           <outptr><jobject/></outptr>
6553           <description>
6554             On return, points to a <code>java.lang.Module</code> object
6555             or points to <code>NULL</code>.
6556           </description>
6557         </param>
6558       </parameters>
6559       <errors>
6560         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6561           If class loader is not <code>NULL</code> and is not a class loader object.
6562         </error>
6563       </errors>
6564     </function>
6565 
6566     <function id="AddModuleReads" num="94" since="9">
6567       <synopsis>Add Module Reads</synopsis>
6568       <description>
6569          Update a module to read another module. This function is a no-op
6570          when <paramlink id="module"></paramlink> is an unnamed module.
6571          This function facilitates the instrumentation of code
6572          in named modules where that instrumentation requires
6573          expanding the set of modules that a module reads.
6574       </description>
6575       <origin>new</origin>
6576       <capabilities>
6577       </capabilities>
6578       <parameters>
6579         <param id="module">
6580           <ptrtype><jobject/></ptrtype>
6581           <description>
6582             The module to update.
6583           </description>
6584         </param>
6585         <param id="to_module">
6586           <ptrtype><jobject/></ptrtype>
6587           <description>
6588             The additional module to read.
6589           </description>
6590         </param>
6591       </parameters>
6592       <errors>
6593         <error id="JVMTI_ERROR_INVALID_MODULE">
6594           If <paramlink id="module"></paramlink> is not a module object.
6595         </error>
6596         <error id="JVMTI_ERROR_INVALID_MODULE">
6597           If <paramlink id="to_module"></paramlink> is not a module object.
6598         </error>
6599         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6600           if the module cannot be modified.
6601           See <functionlink id="IsModifiableModule"/>.
6602         </error>
6603       </errors>
6604     </function>
6605 
6606     <function id="AddModuleExports" num="95" since="9">
6607       <synopsis>Add Module Exports</synopsis>
6608       <description>
6609          Update a module to export a package to another module.
6610          This function is a no-op when <paramlink id="module"></paramlink>
6611          is an unnamed module or an open module.
6612          This function facilitates the instrumentation of code
6613          in named modules where that instrumentation requires
6614          expanding the set of packages that a module exports.
6615       </description>
6616       <origin>new</origin>
6617       <capabilities>
6618       </capabilities>
6619       <parameters>
6620         <param id="module">
6621           <ptrtype><jobject/></ptrtype>
6622           <description>
6623             The module to update.
6624           </description>
6625         </param>
6626         <param id="pkg_name">
6627           <inbuf><char/></inbuf>
6628           <description>
6629             The exported package name.
6630           </description>
6631         </param>
6632         <param id="to_module">
6633           <ptrtype><jobject/></ptrtype>
6634           <description>
6635             The module the package is exported to.
6636             If the <code>to_module</code> is not a subclass of
6637             <code>java.lang.Module</code> this function returns
6638             <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
6639           </description>
6640         </param>
6641       </parameters>
6642       <errors>
6643         <error id="JVMTI_ERROR_INVALID_MODULE">
6644           If <paramlink id="module"></paramlink> is not a module object.
6645         </error>
6646         <error id="JVMTI_ERROR_INVALID_MODULE">
6647           If <paramlink id="to_module"></paramlink> is not a module object.
6648         </error>
6649         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6650           If the package <paramlink id="pkg_name"></paramlink>
6651           does not belong to the module.
6652         </error>
6653         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6654           if the module cannot be modified.
6655           See <functionlink id="IsModifiableModule"/>.
6656         </error>
6657       </errors>
6658     </function>
6659 
6660     <function id="AddModuleOpens" num="96" since="9">
6661       <synopsis>Add Module Opens</synopsis>
6662       <description>
6663          Update a module to open a package to another module.
6664          This function is a no-op when <paramlink id="module"></paramlink>
6665          is an unnamed module or an open module.
6666          This function facilitates the instrumentation of code
6667          in modules where that instrumentation requires
6668          expanding the set of packages that a module opens to
6669          other modules.
6670       </description>
6671       <origin>new</origin>
6672       <capabilities>
6673       </capabilities>
6674       <parameters>
6675         <param id="module">
6676           <ptrtype><jobject/></ptrtype>
6677           <description>
6678             The module to update.
6679           </description>
6680         </param>
6681         <param id="pkg_name">
6682           <inbuf><char/></inbuf>
6683           <description>
6684             The package name of the package to open.
6685           </description>
6686         </param>
6687         <param id="to_module">
6688           <ptrtype><jobject/></ptrtype>
6689           <description>
6690             The module with the package to open.
6691             If the <code>to_module</code> is not a subclass of
6692             <code>java.lang.Module</code> this function returns
6693             <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
6694           </description>
6695         </param>
6696       </parameters>
6697       <errors>
6698         <error id="JVMTI_ERROR_INVALID_MODULE">
6699           If <paramlink id="module"></paramlink> is not a module object.
6700         </error>
6701         <error id="JVMTI_ERROR_INVALID_MODULE">
6702           If <paramlink id="to_module"></paramlink> is not a module object.
6703         </error>
6704         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
6705           If the package <paramlink id="pkg_name"></paramlink>
6706           does not belong to the module.
6707         </error>
6708         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6709           if the module cannot be modified.
6710           See <functionlink id="IsModifiableModule"/>.
6711         </error>
6712       </errors>
6713     </function>
6714 
6715     <function id="AddModuleUses" num="97" since="9">
6716       <synopsis>Add Module Uses</synopsis>
6717       <description>
6718          Updates a module to add a service to the set of services that
6719          a module uses. This function is a no-op when the module
6720          is an unnamed module.
6721          This function facilitates the instrumentation of code
6722          in named modules where that instrumentation requires
6723          expanding the set of services that a module is using.
6724       </description>
6725       <origin>new</origin>
6726       <capabilities>
6727       </capabilities>
6728       <parameters>
6729         <param id="module">
6730           <ptrtype><jobject/></ptrtype>
6731           <description>
6732             The module to update.
6733           </description>
6734         </param>
6735         <param id="service">
6736           <ptrtype><jclass/></ptrtype>
6737           <description>
6738             The service to use.
6739           </description>
6740         </param>
6741       </parameters>
6742       <errors>
6743         <error id="JVMTI_ERROR_INVALID_MODULE">
6744           If <paramlink id="module"></paramlink> is not a module object.
6745         </error>
6746         <error id="JVMTI_ERROR_INVALID_CLASS">
6747           If <paramlink id="service"></paramlink> is not a class object.
6748         </error>
6749         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6750           if the module cannot be modified.
6751           See <functionlink id="IsModifiableModule"/>.
6752         </error>
6753       </errors>
6754     </function>
6755 
6756     <function id="AddModuleProvides" num="98" since="9">
6757       <synopsis>Add Module Provides</synopsis>
6758       <description>
6759          Updates a module to add a service to the set of services that
6760          a module provides. This function is a no-op when the module
6761          is an unnamed module.
6762          This function facilitates the instrumentation of code
6763          in named modules where that instrumentation requires
6764          changes to the services that are provided.
6765       </description>
6766       <origin>new</origin>
6767       <capabilities>
6768       </capabilities>
6769       <parameters>
6770         <param id="module">
6771           <ptrtype><jobject/></ptrtype>
6772           <description>
6773             The module to update.
6774           </description>
6775         </param>
6776         <param id="service">
6777           <ptrtype><jclass/></ptrtype>
6778           <description>
6779             The service to provide.
6780           </description>
6781         </param>
6782         <param id="impl_class">
6783           <ptrtype><jclass/></ptrtype>
6784           <description>
6785             The implementation class for the provided service.
6786           </description>
6787         </param>
6788       </parameters>
6789       <errors>
6790         <error id="JVMTI_ERROR_INVALID_MODULE">
6791           If <paramlink id="module"></paramlink> is not a module object.
6792         </error>
6793         <error id="JVMTI_ERROR_INVALID_CLASS">
6794           If <paramlink id="service"></paramlink> is not a class object.
6795         </error>
6796         <error id="JVMTI_ERROR_INVALID_CLASS">
6797           If <paramlink id="impl_class"></paramlink> is not a class object.
6798         </error>
6799         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
6800           if the module cannot be modified.
6801           See <functionlink id="IsModifiableModule"/>.
6802         </error>
6803       </errors>
6804     </function>
6805 
6806     <function id="IsModifiableModule" num="99" since="9">
6807       <synopsis>Is Modifiable Module</synopsis>
6808       <description>
6809         Determines whether a module is modifiable.
6810         If a module is modifiable then this module can be updated with
6811         <functionlink id="AddModuleReads"/>, <functionlink id="AddModuleExports"/>,
6812         <functionlink id="AddModuleOpens"/>, <functionlink id="AddModuleUses"/>,
6813         and <functionlink id="AddModuleProvides"/>. If a module is not modifiable
6814         then the module can not be updated with these functions. The result of
6815         this function is always <code>JNI_TRUE</code> when called to determine
6816         if an unnamed module is modifiable.
6817       </description>
6818       <origin>new</origin>
6819       <capabilities>
6820       </capabilities>
6821       <parameters>
6822         <param id="module">
6823           <ptrtype><jobject/></ptrtype>
6824           <description>
6825             The module to query.
6826           </description>
6827         </param>
6828         <param id="is_modifiable_module_ptr">
6829           <outptr><jboolean/></outptr>
6830           <description>
6831             On return, points to the boolean result of this function.
6832           </description>
6833         </param>
6834       </parameters>
6835       <errors>
6836         <error id="JVMTI_ERROR_INVALID_MODULE">
6837           If <paramlink id="module"></paramlink> is not a module object.
6838         </error>
6839       </errors>
6840     </function>
6841 
6842   </category>
6843 
6844   <category id="class" label="Class">
6845 
6846     <intro>
6847     </intro>
6848 
6849     <function id="GetLoadedClasses" jkernel="yes" num="78">
6850       <synopsis>Get Loaded Classes</synopsis>
6851       <description>
6852         Return an array of all classes loaded in the virtual machine.
6853         The number of classes in the array is returned via
6854         <code>class_count_ptr</code>, and the array itself via
6855         <code>classes_ptr</code>.
6856         <p/>
6857         Array classes of all types (including arrays of primitive types) are
6858         included in the returned list. Primitive classes (for example,
6859         <code>java.lang.Integer.TYPE</code>) are <i>not</i> included in this list.
6860       </description>
6861       <origin>jvmdi</origin>
6862       <capabilities>
6863       </capabilities>
6864       <parameters>
6865         <param id="class_count_ptr">
6866           <outptr><jint/></outptr>
6867           <description>
6868             On return, points to the number of classes.
6869           </description>
6870         </param>
6871         <param id="classes_ptr">
6872           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6873             <description>
6874               On return, points to an array of references, one
6875               for each class.
6876             </description>
6877         </param>
6878       </parameters>
6879       <errors>
6880       </errors>
6881     </function>
6882 
6883     <function id="GetClassLoaderClasses" jkernel="yes" num="79">
6884       <synopsis>Get Classloader Classes</synopsis>
6885       <description>
6886         Returns an array of those classes for which this class loader has
6887         been recorded as an initiating loader. Each
6888         class in the returned array was created by this class loader,
6889         either by defining it directly or by delegation to another class loader.
6890         See <vmspec chapter="5.3"/>.
6891         <p/>
6892         The number of classes in the array is returned via
6893         <code>class_count_ptr</code>, and the array itself via
6894         <code>classes_ptr</code>.
6895       </description>
6896       <origin>jvmdi</origin>
6897       <capabilities>
6898       </capabilities>
6899       <parameters>
6900         <param id="initiating_loader">
6901           <ptrtype>
6902             <jobject/>
6903             <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
6904           </ptrtype>
6905             <description>
6906               An initiating class loader.
6907             </description>
6908         </param>
6909         <param id="class_count_ptr">
6910           <outptr><jint/></outptr>
6911           <description>
6912             On return, points to the number of classes.
6913           </description>
6914         </param>
6915         <param id="classes_ptr">
6916           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
6917             <description>
6918               On return, points to an array of references, one
6919               for each class.
6920             </description>
6921         </param>
6922       </parameters>
6923       <errors>
6924       </errors>
6925     </function>
6926 
6927     <function id="GetClassSignature" phase="start" num="48">
6928       <synopsis>Get Class Signature</synopsis>
6929       <description>
6930         For the class indicated by <code>klass</code>, return the
6931         <externallink id="jni/types.html#type-signatures">JNI
6932             type signature</externallink>
6933         and the generic signature of the class.
6934         For example, <code>java.util.List</code> is <code>"Ljava/util/List;"</code>
6935         and <code>int[]</code> is <code>"[I"</code>
6936         The returned name for primitive classes
6937         is the type signature character of the corresponding primitive type.
6938         For example, <code>java.lang.Integer.TYPE</code> is <code>"I"</code>.
6939       </description>
6940       <origin>jvmdiClone</origin>
6941       <capabilities>
6942       </capabilities>
6943       <parameters>
6944         <param id="klass">
6945           <jclass/>
6946             <description>
6947               The class to query.
6948             </description>
6949         </param>
6950         <param id="signature_ptr">
6951           <allocbuf>
6952             <char/>
6953             <nullok>the signature is not returned</nullok>
6954           </allocbuf>
6955           <description>
6956             On return, points to the JNI type signature of the class, encoded as a
6957             <internallink id="mUTF">modified UTF-8</internallink> string.
6958           </description>
6959         </param>
6960         <param id="generic_ptr">
6961           <allocbuf>
6962             <char/>
6963             <nullok>the generic signature is not returned</nullok>
6964           </allocbuf>
6965           <description>
6966             On return, points to the generic signature of the class, encoded as a
6967             <internallink id="mUTF">modified UTF-8</internallink> string.
6968             If there is no generic signature attribute for the class, then,
6969             on return, points to <code>NULL</code>.
6970           </description>
6971         </param>
6972       </parameters>
6973       <errors>
6974       </errors>
6975     </function>
6976 
6977     <function id="GetClassStatus" phase="start" num="49">
6978       <synopsis>Get Class Status</synopsis>
6979       <description>
6980         Get the status of the class. Zero or more of the following bits can be
6981         set.
6982         <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
6983           <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
6984             Class bytecodes have been verified
6985           </constant>
6986           <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
6987             Class preparation is complete
6988           </constant>
6989           <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
6990             Class initialization is complete. Static initializer has been run.
6991           </constant>
6992           <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
6993             Error during initialization makes class unusable
6994           </constant>
6995           <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
6996             Class is an array.  If set, all other bits are zero.
6997           </constant>
6998           <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
6999             Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).
7000             If set, all other bits are zero.
7001           </constant>
7002         </constants>
7003       </description>
7004       <origin>jvmdi</origin>
7005       <capabilities>
7006       </capabilities>
7007       <parameters>
7008         <param id="klass">
7009           <jclass/>
7010             <description>
7011               The class to query.
7012             </description>
7013         </param>
7014         <param id="status_ptr">
7015           <outptr><jint/></outptr>
7016           <description>
7017             On return, points to the current state of this class as one or
7018             more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
7019           </description>
7020         </param>
7021       </parameters>
7022       <errors>
7023       </errors>
7024     </function>
7025 
7026     <function id="GetSourceFileName" phase="start" num="50">
7027       <synopsis>Get Source File Name</synopsis>
7028       <description>
7029         For the class indicated by <code>klass</code>, return the source file
7030         name via <code>source_name_ptr</code>. The returned string
7031         is a file name only and never contains a directory name.
7032         <p/>
7033         For primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
7034         and for arrays this function returns
7035         <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
7036       </description>
7037       <origin>jvmdi</origin>
7038       <capabilities>
7039         <required id="can_get_source_file_name"></required>
7040       </capabilities>
7041       <parameters>
7042         <param id="klass">
7043           <jclass/>
7044             <description>
7045               The class to query.
7046             </description>
7047         </param>
7048         <param id="source_name_ptr">
7049           <allocbuf><char/></allocbuf>
7050           <description>
7051             On return, points to the class's source file name, encoded as a
7052             <internallink id="mUTF">modified UTF-8</internallink> string.
7053           </description>
7054         </param>
7055       </parameters>
7056       <errors>
7057         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7058           Class information does not include a source file name. This includes
7059           cases where the class is an array class or primitive class.
7060         </error>
7061       </errors>
7062     </function>
7063 
7064     <function id="GetClassModifiers" phase="start" num="51">
7065       <synopsis>Get Class Modifiers</synopsis>
7066       <description>
7067         For the class indicated by <code>klass</code>, return the access
7068         flags
7069         via <code>modifiers_ptr</code>.
7070         Access flags are defined in <vmspec chapter="4"/>.
7071         <p/>
7072         If the class is an array class, then its public, private, and protected
7073         modifiers are the same as those of its component type. For arrays of
7074         primitives, this component type is represented by one of the primitive
7075         classes (for example, <code>java.lang.Integer.TYPE</code>).
7076         <p/>
7077         If the class is a primitive class, its public modifier is always true,
7078         and its protected and private modifiers are always false.
7079         <p/>
7080         If the class is an array class or a primitive class then its final
7081         modifier is always true and its interface modifier is always false.
7082         The values of its other modifiers are not determined by this specification.
7083 
7084       </description>
7085       <origin>jvmdi</origin>
7086       <capabilities>
7087       </capabilities>
7088       <parameters>
7089         <param id="klass">
7090           <jclass/>
7091             <description>
7092               The class to query.
7093             </description>
7094         </param>
7095         <param id="modifiers_ptr">
7096           <outptr><jint/></outptr>
7097           <description>
7098             On return, points to the current access flags of this class.
7099 
7100           </description>
7101         </param>
7102       </parameters>
7103       <errors>
7104       </errors>
7105     </function>
7106 
7107     <function id="GetClassMethods" phase="start" num="52">
7108       <synopsis>Get Class Methods</synopsis>
7109       <description>
7110         For the class indicated by <code>klass</code>, return a count of
7111         methods via <code>method_count_ptr</code> and a list of
7112         method IDs via <code>methods_ptr</code>. The method list contains
7113         constructors and static initializers as well as true methods.
7114         Only directly declared methods are returned (not inherited methods).
7115         An empty method list is returned for array classes and primitive classes
7116         (for example, <code>java.lang.Integer.TYPE</code>).
7117       </description>
7118       <origin>jvmdi</origin>
7119       <capabilities>
7120         <capability id="can_maintain_original_method_order"/>
7121       </capabilities>
7122       <parameters>
7123         <param id="klass">
7124           <jclass/>
7125             <description>
7126               The class to query.
7127             </description>
7128         </param>
7129         <param id="method_count_ptr">
7130           <outptr><jint/></outptr>
7131           <description>
7132             On return, points to the number of methods declared in this class.
7133           </description>
7134         </param>
7135         <param id="methods_ptr">
7136           <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
7137             <description>
7138               On return, points to the method ID array.
7139             </description>
7140         </param>
7141       </parameters>
7142       <errors>
7143         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7144           <paramlink id="klass"></paramlink> is not prepared.
7145         </error>
7146       </errors>
7147     </function>
7148 
7149     <function id="GetClassFields" phase="start" num="53">
7150       <synopsis>Get Class Fields</synopsis>
7151       <description>
7152         For the class indicated by <code>klass</code>, return a count of fields
7153         via <code>field_count_ptr</code> and a list of field IDs via
7154         <code>fields_ptr</code>.
7155         Only directly declared fields are returned (not inherited fields).
7156         Fields are returned in the order they occur in the class file.
7157         An empty field list is returned for array classes and primitive classes
7158         (for example, <code>java.lang.Integer.TYPE</code>).
7159         Use JNI to determine the length of an array.
7160       </description>
7161       <origin>jvmdi</origin>
7162       <capabilities>
7163       </capabilities>
7164       <parameters>
7165         <param id="klass">
7166           <jclass/>
7167             <description>
7168               The class to query.
7169             </description>
7170         </param>
7171         <param id="field_count_ptr">
7172           <outptr><jint/></outptr>
7173           <description>
7174             On return, points to the number of fields declared in this class.
7175           </description>
7176         </param>
7177         <param id="fields_ptr">
7178           <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
7179             <description>
7180               On return, points to the field ID array.
7181             </description>
7182         </param>
7183       </parameters>
7184       <errors>
7185         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7186           <paramlink id="klass"></paramlink> is not prepared.
7187         </error>
7188       </errors>
7189     </function>
7190 
7191     <function id="GetImplementedInterfaces" phase="start" num="54">
7192       <synopsis>Get Implemented Interfaces</synopsis>
7193       <description>
7194         Return the direct super-interfaces of this class. For a class, this
7195         function returns the interfaces declared in its <code>implements</code>
7196         clause. For an interface, this function returns the interfaces declared in
7197         its <code>extends</code> clause.
7198         An empty interface list is returned for array classes and primitive classes
7199         (for example, <code>java.lang.Integer.TYPE</code>).
7200       </description>
7201       <origin>jvmdi</origin>
7202       <capabilities>
7203       </capabilities>
7204       <parameters>
7205         <param id="klass">
7206           <jclass/>
7207             <description>
7208               The class to query.
7209             </description>
7210         </param>
7211         <param id="interface_count_ptr">
7212           <outptr><jint/></outptr>
7213           <description>
7214             On return, points to the number of interfaces.
7215           </description>
7216         </param>
7217         <param id="interfaces_ptr">
7218           <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
7219             <description>
7220               On return, points to the interface array.
7221             </description>
7222         </param>
7223       </parameters>
7224       <errors>
7225         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
7226           <paramlink id="klass"></paramlink> is not prepared.
7227         </error>
7228       </errors>
7229     </function>
7230 
7231     <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
7232       <synopsis>Get Class Version Numbers</synopsis>
7233       <description>
7234         For the class indicated by <code>klass</code>,
7235         return the minor and major version numbers,
7236         as defined in
7237         <vmspec chapter="4"/>.
7238       </description>
7239       <origin>new</origin>
7240       <capabilities>
7241       </capabilities>
7242       <parameters>
7243         <param id="klass">
7244           <jclass/>
7245             <description>
7246               The class to query.
7247             </description>
7248         </param>
7249         <param id="minor_version_ptr">
7250           <outptr><jint/></outptr>
7251           <description>
7252             On return, points to the value of the
7253             <code>minor_version</code> item of the
7254             Class File Format.
7255             Note: to be consistent with the Class File Format,
7256             the minor version number is the first parameter.
7257           </description>
7258         </param>
7259         <param id="major_version_ptr">
7260           <outptr><jint/></outptr>
7261           <description>
7262             On return, points to the value of the
7263             <code>major_version</code> item of the
7264             Class File Format.
7265           </description>
7266         </param>
7267       </parameters>
7268       <errors>
7269         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7270           The class is a primitive or array class.
7271         </error>
7272       </errors>
7273     </function>
7274 
7275     <function id="GetConstantPool" phase="start" num="146" since="1.1">
7276       <synopsis>Get Constant Pool</synopsis>
7277       <description>
7278         For the class indicated by <code>klass</code>,
7279         return the raw bytes of the constant pool in the format of the
7280         <code>constant_pool</code> item of
7281         <vmspec chapter="4"/>.
7282         The format of the constant pool may differ between versions
7283         of the Class File Format, so, the
7284         <functionlink id="GetClassVersionNumbers">minor and major
7285         class version numbers</functionlink> should be checked for
7286         compatibility.
7287         <p/>
7288         The returned constant pool might not have the same layout or
7289         contents as the constant pool in the defining class file.
7290         The constant pool returned by GetConstantPool() may have
7291         more or fewer entries than the defining constant pool.
7292         Entries may be in a different order.
7293         The constant pool returned by GetConstantPool() will match the
7294         constant pool used by
7295         <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
7296         That is, the bytecodes returned by GetBytecodes() will have
7297         constant pool indices which refer to constant pool entries returned
7298         by GetConstantPool().
7299         Note that since <functionlink id="RetransformClasses"/>
7300         and <functionlink id="RedefineClasses"/> can change
7301         the constant pool, the constant pool returned by this function
7302         can change accordingly.  Thus, the correspondence between
7303         GetConstantPool() and GetBytecodes() does not hold if there
7304         is an intervening class retransformation or redefinition.
7305         The value of a constant pool entry used by a given bytecode will
7306         match that of the defining class file (even if the indices don't match).
7307         Constant pool entries which are not used directly or indirectly by
7308         bytecodes (for example,  UTF-8 strings associated with annotations) are
7309         not  required to exist in the returned constant pool.
7310       </description>
7311       <origin>new</origin>
7312       <capabilities>
7313         <required id="can_get_constant_pool"></required>
7314       </capabilities>
7315       <parameters>
7316         <param id="klass">
7317           <jclass/>
7318             <description>
7319               The class to query.
7320             </description>
7321         </param>
7322         <param id="constant_pool_count_ptr">
7323           <outptr><jint/></outptr>
7324           <description>
7325             On return, points to the number of entries
7326             in the constant pool table plus one.
7327             This corresponds to the <code>constant_pool_count</code>
7328             item of the Class File Format.
7329           </description>
7330         </param>
7331         <param id="constant_pool_byte_count_ptr">
7332           <outptr><jint/></outptr>
7333           <description>
7334             On return, points to the number of bytes
7335             in the returned raw constant pool.
7336           </description>
7337         </param>
7338         <param id="constant_pool_bytes_ptr">
7339           <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
7340             <description>
7341               On return, points to the raw constant pool, that is the bytes
7342               defined by the <code>constant_pool</code> item of the
7343               Class File Format
7344             </description>
7345         </param>
7346       </parameters>
7347       <errors>
7348         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7349           The class is a primitive or array class.
7350         </error>
7351       </errors>
7352     </function>
7353 
7354     <function id="IsInterface" phase="start" num="55">
7355       <synopsis>Is Interface</synopsis>
7356       <description>
7357         Determines whether a class object reference represents an interface.
7358         The <code>jboolean</code> result is
7359         <code>JNI_TRUE</code> if the "class" is actually an interface,
7360         <code>JNI_FALSE</code> otherwise.
7361       </description>
7362       <origin>jvmdi</origin>
7363       <capabilities>
7364       </capabilities>
7365       <parameters>
7366         <param id="klass">
7367           <jclass/>
7368             <description>
7369               The class to query.
7370             </description>
7371         </param>
7372         <param id="is_interface_ptr">
7373           <outptr><jboolean/></outptr>
7374           <description>
7375             On return, points to the boolean result of this function.
7376 
7377           </description>
7378         </param>
7379       </parameters>
7380       <errors>
7381       </errors>
7382     </function>
7383 
7384     <function id="IsArrayClass" phase="start" num="56">
7385       <synopsis>Is Array Class</synopsis>
7386       <description>
7387         Determines whether a class object reference represents an array.
7388         The <code>jboolean</code> result is
7389         <code>JNI_TRUE</code> if the class is an array,
7390         <code>JNI_FALSE</code> otherwise.
7391       </description>
7392       <origin>jvmdi</origin>
7393       <capabilities>
7394       </capabilities>
7395       <parameters>
7396         <param id="klass">
7397           <jclass/>
7398             <description>
7399               The class to query.
7400             </description>
7401         </param>
7402         <param id="is_array_class_ptr">
7403           <outptr><jboolean/></outptr>
7404           <description>
7405             On return, points to the boolean result of this function.
7406 
7407           </description>
7408         </param>
7409       </parameters>
7410       <errors>
7411       </errors>
7412     </function>
7413 
7414     <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
7415       <synopsis>Is Modifiable Class</synopsis>
7416       <description>
7417         Determines whether a class is modifiable.
7418         If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
7419         returns <code>JNI_TRUE</code>) the class can be
7420         redefined with <functionlink id="RedefineClasses"/> (assuming
7421         the agent possesses the
7422         <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
7423         capability) or
7424         retransformed with <functionlink id="RetransformClasses"/> (assuming
7425         the agent possesses the
7426         <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
7427         capability).
7428         If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
7429         returns <code>JNI_FALSE</code>) the class can be neither
7430         redefined nor retransformed.
7431         <p/>
7432         Primitive classes (for example, <code>java.lang.Integer.TYPE</code>),
7433         array classes, and some implementation defined classes are never modifiable.
7434         <p/>
7435       </description>
7436       <origin>new</origin>
7437       <capabilities>
7438         <capability id="can_redefine_any_class">
7439           If possessed then all classes (except primitive, array, and some implementation defined
7440           classes) are modifiable with <functionlink id="RedefineClasses"/>.
7441         </capability>
7442         <capability id="can_retransform_any_class">
7443           If possessed then all classes (except primitive, array, and some implementation defined
7444           classes) are modifiable with <functionlink id="RetransformClasses"/>.
7445         </capability>
7446         <capability id="can_redefine_classes">
7447           No effect on the result of the function.
7448           But must additionally be possessed to modify the class with
7449           <functionlink id="RedefineClasses"/>.
7450         </capability>
7451         <capability id="can_retransform_classes">
7452           No effect on the result of the function.
7453           But must additionally be possessed to modify the class with
7454           <functionlink id="RetransformClasses"/>.
7455         </capability>
7456       </capabilities>
7457       <parameters>
7458         <param id="klass">
7459           <jclass/>
7460             <description>
7461               The class to query.
7462             </description>
7463         </param>
7464         <param id="is_modifiable_class_ptr">
7465           <outptr><jboolean/></outptr>
7466           <description>
7467             On return, points to the boolean result of this function.
7468           </description>
7469         </param>
7470       </parameters>
7471       <errors>
7472       </errors>
7473     </function>
7474 
7475     <function id="GetClassLoader" phase="start" num="57">
7476       <synopsis>Get Class Loader</synopsis>
7477       <description>
7478         For the class indicated by <code>klass</code>, return via
7479         <code>classloader_ptr</code> a reference to the class loader for the
7480         class.
7481       </description>
7482       <origin>jvmdi</origin>
7483       <capabilities>
7484       </capabilities>
7485       <parameters>
7486         <param id="klass">
7487           <jclass/>
7488             <description>
7489               The class to query.
7490             </description>
7491         </param>
7492         <param id="classloader_ptr">
7493           <outptr><jobject/></outptr>
7494             <description>
7495               On return, points to the class loader that loaded
7496               this class.
7497               If the class was not created by a class loader
7498               or if the class loader is the bootstrap class loader,
7499               points to <code>NULL</code>.
7500             </description>
7501         </param>
7502       </parameters>
7503       <errors>
7504       </errors>
7505 
7506     </function>
7507 
7508     <function id="GetSourceDebugExtension" phase="start" num="90">
7509       <synopsis>Get Source Debug Extension</synopsis>
7510       <description>
7511         For the class indicated by <code>klass</code>, return the debug
7512         extension via <code>source_debug_extension_ptr</code>.
7513         The returned string
7514         contains exactly the debug extension information present in the
7515         class file of <code>klass</code>.
7516       </description>
7517       <origin>jvmdi</origin>
7518       <capabilities>
7519         <required id="can_get_source_debug_extension"></required>
7520       </capabilities>
7521       <parameters>
7522         <param id="klass">
7523           <jclass/>
7524             <description>
7525               The class to query.
7526             </description>
7527         </param>
7528         <param id="source_debug_extension_ptr">
7529           <allocbuf><char/></allocbuf>
7530           <description>
7531             On return, points to the class's debug extension, encoded as a
7532             <internallink id="mUTF">modified UTF-8</internallink> string.
7533           </description>
7534         </param>
7535       </parameters>
7536       <errors>
7537         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
7538           Class information does not include a debug extension.
7539         </error>
7540       </errors>
7541     </function>
7542 
7543     <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
7544       <synopsis>Retransform Classes</synopsis>
7545       <description>
7546         This function facilitates the
7547         <internallink id="bci">bytecode instrumentation</internallink>
7548         of already loaded classes.
7549         To replace the class definition without reference to the existing
7550         bytecodes, as one might do when recompiling from source for
7551         fix-and-continue debugging, <functionlink id="RedefineClasses"/>
7552         function should be used instead.
7553         <p/>
7554         When classes are initially loaded or when they are
7555         <functionlink id="RedefineClasses">redefined</functionlink>,
7556         the initial class file bytes can be transformed with the
7557         <eventlink id="ClassFileLoadHook"/> event.
7558         This function reruns the transformation process
7559         (whether or not a transformation has previously occurred).
7560         This retransformation follows these steps:
7561         <ul>
7562           <li>starting from the initial class file bytes
7563           </li>
7564           <li>for each <fieldlink id="can_retransform_classes"
7565                      struct="jvmtiCapabilities">retransformation
7566                                                 incapable</fieldlink>
7567             agent which received a
7568             <code>ClassFileLoadHook</code> event during the previous
7569             load or redefine, the bytes it returned
7570             (via the <code>new_class_data</code> parameter)
7571             are reused as the output of the transformation;
7572             note that this is equivalent to reapplying
7573             the previous transformation, unaltered. except that
7574             the <code>ClassFileLoadHook</code> event
7575             is <b>not</b> sent to these agents
7576           </li>
7577           <li>for each <fieldlink id="can_retransform_classes"
7578                      struct="jvmtiCapabilities">retransformation
7579                                                 capable</fieldlink>
7580             agent, the <code>ClassFileLoadHook</code> event is sent,
7581             allowing a new transformation to be applied
7582           </li>
7583           <li>the transformed class file bytes are installed as the new
7584             definition of the class
7585           </li>
7586         </ul>
7587         See the <eventlink id="ClassFileLoadHook"/> event for more details.
7588         <p/>
7589         The initial class file bytes represent the bytes passed to
7590         <code>ClassLoader.defineClass</code>
7591         or <code>RedefineClasses</code> (before any transformations
7592         were applied), however they may not exactly match them.
7593         The constant pool may differ in ways described in
7594         <functionlink id="GetConstantPool"/>.
7595         Constant pool indices in the bytecodes of methods will correspond.
7596         Some attributes may not be present.
7597         Where order is not meaningful, for example the order of methods,
7598         order may not be preserved.
7599         <p/>
7600         Retransformation can cause new versions of methods to be installed.
7601         Old method versions may become
7602         <internallink id="obsoleteMethods">obsolete</internallink>
7603         The new method version will be used on new invokes.
7604         If a method has active stack frames, those active frames continue to
7605         run the bytecodes of the original method version.
7606         <p/>
7607         This function does not cause any initialization except that which
7608         would occur under the customary JVM semantics.
7609         In other words, retransforming a class does not cause its initializers to be
7610         run. The values of static fields will remain as they were
7611         prior to the call.
7612         <p/>
7613         Threads need not be suspended.
7614         <p/>
7615         All breakpoints in the class are cleared.
7616         <p/>
7617         All attributes are updated.
7618         <p/>
7619         Instances of the retransformed class are not affected -- fields retain their
7620         previous values.
7621         <functionlink id="GetTag">Tags</functionlink> on the instances are
7622         also unaffected.
7623         <p/>
7624         In response to this call, no events other than the
7625         <eventlink id="ClassFileLoadHook"/> event
7626         will be sent.
7627         <p/>
7628         The retransformation may change method bodies, the constant pool and attributes
7629         (unless explicitly prohibited).
7630         The retransformation must not add, remove or rename fields or methods, change the
7631         signatures of methods, change modifiers, or change inheritance.
7632         The retransformation must not change the <code>NestHost</code> or
7633         <code>NestMembers</code> attributes.
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_ATTRIBUTE_CHANGED">
7705           A retransformed class file has unsupported differences in class attributes.
7706         </error>
7707         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7708           A retransformed class file has different class modifiers.
7709         </error>
7710         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7711           A method in the retransformed class file has different modifiers
7712           than its counterpart in the old class version.
7713         </error>
7714       </errors>
7715     </function>
7716 
7717     <function id="RedefineClasses" jkernel="yes" num="87">
7718       <synopsis>Redefine Classes</synopsis>
7719       <typedef id="jvmtiClassDefinition" label="Class redefinition description">
7720         <field id="klass">
7721           <jclass/>
7722             <description>
7723               Class object for this class
7724             </description>
7725         </field>
7726         <field id="class_byte_count">
7727           <jint/>
7728           <description>
7729             Number of bytes defining class (below)
7730           </description>
7731         </field>
7732         <field id="class_bytes">
7733           <inbuf incount="class_byte_count"><uchar/></inbuf>
7734           <description>
7735             Bytes defining class (in <vmspec chapter="4"/>)
7736           </description>
7737         </field>
7738       </typedef>
7739       <description>
7740         All classes given are redefined according to the definitions
7741         supplied.
7742         This function is used to replace the definition of a class
7743         with a new definition, as might be needed in fix-and-continue
7744         debugging.
7745         Where the existing class file bytes are to be transformed, for
7746         example in
7747         <internallink id="bci">bytecode instrumentation</internallink>,
7748         <functionlink id="RetransformClasses"/> should be used.
7749         <p/>
7750         Redefinition can cause new versions of methods to be installed.
7751         Old method versions may become
7752         <internallink id="obsoleteMethods">obsolete</internallink>
7753         The new method version will be used on new invokes.
7754         If a method has active stack frames, those active frames continue to
7755         run the bytecodes of the original method version.
7756         If resetting of stack frames is desired, use
7757         <functionlink id="PopFrame"></functionlink>
7758         to pop frames with obsolete method versions.
7759         <p/>
7760         This function does not cause any initialization except that which
7761         would occur under the customary JVM semantics.
7762         In other words, redefining a class does not cause its initializers to be
7763         run. The values of static fields will remain as they were
7764         prior to the call.
7765         <p/>
7766         Threads need not be suspended.
7767         <p/>
7768         All breakpoints in the class are cleared.
7769         <p/>
7770         All attributes are updated.
7771         <p/>
7772         Instances of the redefined class are not affected -- fields retain their
7773         previous values.
7774         <functionlink id="GetTag">Tags</functionlink> on the instances are
7775         also unaffected.
7776         <p/>
7777         In response to this call, the <jvmti/> event
7778         <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
7779         will be sent (if enabled), but no other <jvmti/> events will be sent.
7780         <p/>
7781         The redefinition may change method bodies, the constant pool and attributes
7782         (unless explicitly prohibited).
7783         The redefinition must not add, remove or rename fields or methods, change the
7784         signatures of methods, change modifiers, or change inheritance.
7785         The retransformation must not change the <code>NestHost</code> or
7786         <code>NestMembers</code> attributes.
7787         These restrictions may be lifted in future versions.
7788         See the error return description below for information on error codes
7789         returned if an unsupported redefinition is attempted.
7790         The class file bytes are not verified or installed until they have passed
7791         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
7792         returned error code reflects the result of the transformations applied
7793         to the bytes passed into <paramlink id="class_definitions"/>.
7794         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
7795         none of the classes to be redefined will have a new definition installed.
7796         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
7797         all of the classes to be redefined will have their new definitions installed.
7798       </description>
7799       <origin>jvmdi</origin>
7800       <capabilities>
7801         <required id="can_redefine_classes"></required>
7802         <capability id="can_redefine_any_class"></capability>
7803       </capabilities>
7804       <parameters>
7805         <param id="class_count">
7806           <jint min="0"/>
7807           <description>
7808             The number of classes specified in <code>class_definitions</code>
7809           </description>
7810         </param>
7811         <param id="class_definitions">
7812           <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
7813           <description>
7814             The array of new class definitions
7815           </description>
7816         </param>
7817       </parameters>
7818       <errors>
7819         <error id="JVMTI_ERROR_NULL_POINTER">
7820           One of <code>class_bytes</code> is <code>NULL</code>.
7821         </error>
7822         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
7823           An element of <code>class_definitions</code> cannot be modified.
7824           See <functionlink id="IsModifiableClass"/>.
7825         </error>
7826         <error id="JVMTI_ERROR_INVALID_CLASS">
7827           An element of <code>class_definitions</code> is not a valid class.
7828         </error>
7829         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
7830           A new class file has a version number not supported by this VM.
7831         </error>
7832         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
7833           A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
7834         </error>
7835         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
7836           The new class file definitions would lead to a circular definition
7837           (the VM would return a <code>ClassCircularityError</code>).
7838         </error>
7839         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
7840           The class bytes fail verification.
7841         </error>
7842         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
7843           The class name defined in a new class file is
7844           different from the name in the old class object.
7845         </error>
7846         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
7847           A new class file would require adding a method.
7848         </error>
7849         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
7850           A new class version changes a field.
7851         </error>
7852         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
7853           A direct superclass is different for a new class
7854           version, or the set of directly implemented
7855           interfaces is different.
7856         </error>
7857         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
7858           A new class version does not declare a method
7859           declared in the old class version.
7860         </error>
7861         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED">
7862           A new class version has unsupported differences in class attributes.
7863         </error>
7864         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
7865           A new class version has different modifiers.
7866         </error>
7867         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
7868           A method in the new class version has different modifiers
7869           than its counterpart in the old class version.
7870         </error>
7871         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
7872           A module cannot be modified.
7873           See <functionlink id="IsModifiableModule"/>.
7874         </error>
7875       </errors>
7876     </function>
7877 
7878   </category>
7879 
7880   <category id="object" label="Object">
7881 
7882     <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
7883       <synopsis>Get Object Size</synopsis>
7884       <description>
7885         For the object indicated by <code>object</code>,
7886         return via <code>size_ptr</code> the size of the object.
7887         This size is an implementation-specific approximation of
7888         the amount of storage consumed by this object.
7889         It may include some or all of the object's overhead, and thus
7890         is useful for comparison within an implementation but not
7891         between implementations.
7892         The estimate may change during a single invocation of the JVM.
7893       </description>
7894       <origin>new</origin>
7895       <capabilities>
7896       </capabilities>
7897       <parameters>
7898         <param id="object">
7899           <jobject/>
7900             <description>
7901               The object to query.
7902             </description>
7903         </param>
7904         <param id="size_ptr">
7905           <outptr><jlong/></outptr>
7906           <description>
7907             On return, points to the object's size in bytes.
7908           </description>
7909         </param>
7910       </parameters>
7911       <errors>
7912       </errors>
7913     </function>
7914 
7915     <function id="GetObjectHashCode" phase="start" num="58">
7916       <synopsis>Get Object Hash Code</synopsis>
7917       <description>
7918         For the object indicated by <code>object</code>,
7919         return via <code>hash_code_ptr</code> a hash code.
7920         This hash code could be used to maintain a hash table of object references,
7921         however, on some implementations this can cause significant performance
7922         impacts--in most cases
7923         <internallink id="Heap">tags</internallink>
7924         will be a more efficient means of associating information with objects.
7925         This function guarantees
7926         the same hash code value for a particular object throughout its life
7927       </description>
7928       <origin>jvmdi</origin>
7929       <capabilities>
7930       </capabilities>
7931       <parameters>
7932         <param id="object">
7933           <jobject/>
7934             <description>
7935               The object to query.
7936             </description>
7937         </param>
7938         <param id="hash_code_ptr">
7939           <outptr><jint/></outptr>
7940           <description>
7941             On return, points to the object's hash code.
7942           </description>
7943         </param>
7944       </parameters>
7945       <errors>
7946       </errors>
7947     </function>
7948 
7949     <function id="GetObjectMonitorUsage" num="59">
7950       <synopsis>Get Object Monitor Usage</synopsis>
7951       <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
7952         <field id="owner">
7953           <jthread/>
7954             <description>
7955               The thread owning this monitor, or <code>NULL</code> if unused
7956             </description>
7957         </field>
7958         <field id="entry_count">
7959           <jint/>
7960           <description>
7961             The number of times the owning thread has entered the monitor
7962           </description>
7963         </field>
7964         <field id="waiter_count">
7965           <jint/>
7966           <description>
7967             The number of threads waiting to own this monitor
7968           </description>
7969         </field>
7970         <field id="waiters">
7971           <allocfieldbuf><jthread/></allocfieldbuf>
7972             <description>
7973               The <code>waiter_count</code> waiting threads
7974             </description>
7975         </field>
7976         <field id="notify_waiter_count">
7977           <jint/>
7978           <description>
7979             The number of threads waiting to be notified by this monitor
7980           </description>
7981         </field>
7982         <field id="notify_waiters">
7983           <allocfieldbuf><jthread/></allocfieldbuf>
7984             <description>
7985               The <code>notify_waiter_count</code> threads waiting to be notified
7986             </description>
7987         </field>
7988       </typedef>
7989       <description>
7990         Get information about the object's monitor.
7991         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
7992         are filled in with information about usage of the monitor.
7993           <todo>
7994             Decide and then clarify suspend requirements.
7995           </todo>
7996       </description>
7997       <origin>jvmdi</origin>
7998       <capabilities>
7999         <required id="can_get_monitor_info"></required>
8000       </capabilities>
8001       <parameters>
8002         <param id="object">
8003           <jobject/>
8004             <description>
8005               The object to query.
8006             </description>
8007         </param>
8008         <param id="info_ptr">
8009           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
8010           <description>
8011             On return, filled with monitor information for the
8012             specified object.
8013           </description>
8014         </param>
8015       </parameters>
8016       <errors>
8017       </errors>
8018     </function>
8019 
8020     <elide>
8021     <function id="GetObjectMonitors" num="116">
8022       <synopsis>Get Object Monitors</synopsis>
8023       <description>
8024         Return the list of object monitors.
8025         <p/>
8026         Note: details about each monitor can be examined with
8027         <functionlink id="GetObjectMonitorUsage"></functionlink>.
8028       </description>
8029       <origin>new</origin>
8030       <capabilities>
8031         <required id="can_get_monitor_info"></required>
8032       </capabilities>
8033       <parameters>
8034         <param id="monitorCnt">
8035           <outptr><jint/></outptr>
8036           <description>
8037             On return, pointer to the number
8038             of monitors returned in <code>monitors_ptr</code>.
8039           </description>
8040         </param>
8041         <param id="monitors_ptr">
8042           <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
8043             <description>
8044               On return, pointer to the monitor list.
8045             </description>
8046         </param>
8047       </parameters>
8048       <errors>
8049       </errors>
8050     </function>
8051     </elide>
8052 
8053   </category>
8054 
8055   <category id="fieldCategory" label="Field">
8056 
8057     <intro>
8058     </intro>
8059 
8060     <function id="GetFieldName" phase="start" num="60">
8061       <synopsis>Get Field Name (and Signature)</synopsis>
8062       <description>
8063         For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
8064         return the field name via <paramlink id="name_ptr"/> and field signature via
8065         <paramlink id="signature_ptr"/>.
8066         <p/>
8067         Field signatures are defined in the
8068         <externallink id="jni/index.html">JNI Specification</externallink>
8069         and are referred to as <code>field descriptors</code> in
8070         <vmspec chapter="4.3.2"/>.
8071       </description>
8072       <origin>jvmdiClone</origin>
8073       <capabilities>
8074       </capabilities>
8075       <parameters>
8076         <param id="klass">
8077           <jclass field="field"/>
8078             <description>
8079               The class of the field to query.
8080             </description>
8081         </param>
8082         <param id="field">
8083           <jfieldID class="klass"/>
8084             <description>
8085               The field to query.
8086             </description>
8087         </param>
8088         <param id="name_ptr">
8089           <allocbuf>
8090             <char/>
8091             <nullok>the name is not returned</nullok>
8092           </allocbuf>
8093           <description>
8094             On return, points to the field name, encoded as a
8095             <internallink id="mUTF">modified UTF-8</internallink> string.
8096           </description>
8097         </param>
8098         <param id="signature_ptr">
8099           <allocbuf>
8100             <char/>
8101             <nullok>the signature is not returned</nullok>
8102           </allocbuf>
8103           <description>
8104             On return, points to the field signature, encoded as a
8105             <internallink id="mUTF">modified UTF-8</internallink> string.
8106           </description>
8107         </param>
8108         <param id="generic_ptr">
8109           <allocbuf>
8110             <char/>
8111             <nullok>the generic signature is not returned</nullok>
8112           </allocbuf>
8113           <description>
8114             On return, points to the generic signature of the field, encoded as a
8115             <internallink id="mUTF">modified UTF-8</internallink> string.
8116             If there is no generic signature attribute for the field, then,
8117             on return, points to <code>NULL</code>.
8118           </description>
8119         </param>
8120       </parameters>
8121       <errors>
8122       </errors>
8123     </function>
8124 
8125     <function id="GetFieldDeclaringClass" phase="start" num="61">
8126       <synopsis>Get Field Declaring Class</synopsis>
8127       <description>
8128         For the field indicated by <code>klass</code> and <code>field</code>
8129         return the class that defined it via <code>declaring_class_ptr</code>.
8130         The declaring class will either be <code>klass</code>, a superclass, or
8131         an implemented interface.
8132       </description>
8133       <origin>jvmdi</origin>
8134       <capabilities>
8135       </capabilities>
8136       <parameters>
8137         <param id="klass">
8138           <jclass field="field"/>
8139             <description>
8140               The class to query.
8141             </description>
8142         </param>
8143         <param id="field">
8144           <jfieldID class="klass"/>
8145             <description>
8146               The field to query.
8147             </description>
8148         </param>
8149         <param id="declaring_class_ptr">
8150           <outptr><jclass/></outptr>
8151             <description>
8152               On return, points to the declaring class
8153             </description>
8154         </param>
8155       </parameters>
8156       <errors>
8157       </errors>
8158     </function>
8159 
8160     <function id="GetFieldModifiers" phase="start" num="62">
8161       <synopsis>Get Field Modifiers</synopsis>
8162       <description>
8163         For the field indicated by <code>klass</code> and <code>field</code>
8164         return the access flags via <code>modifiers_ptr</code>.
8165         Access flags are defined in <vmspec chapter="4"/>.
8166       </description>
8167       <origin>jvmdi</origin>
8168       <capabilities>
8169       </capabilities>
8170       <parameters>
8171         <param id="klass">
8172           <jclass field="field"/>
8173             <description>
8174               The class to query.
8175             </description>
8176         </param>
8177         <param id="field">
8178           <jfieldID class="klass"/>
8179             <description>
8180               The field to query.
8181             </description>
8182         </param>
8183         <param id="modifiers_ptr">
8184           <outptr><jint/></outptr>
8185           <description>
8186             On return, points to the access flags.
8187           </description>
8188         </param>
8189       </parameters>
8190       <errors>
8191       </errors>
8192     </function>
8193 
8194     <function id="IsFieldSynthetic" phase="start" num="63">
8195       <synopsis>Is Field Synthetic</synopsis>
8196       <description>
8197         For the field indicated by <code>klass</code> and <code>field</code>, return a
8198         value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
8199         Synthetic fields are generated by the compiler but not present in the
8200         original source code.
8201       </description>
8202       <origin>jvmdi</origin>
8203       <capabilities>
8204         <required id="can_get_synthetic_attribute"></required>
8205       </capabilities>
8206       <parameters>
8207         <param id="klass">
8208           <jclass field="field"/>
8209             <description>
8210               The class of the field to query.
8211             </description>
8212         </param>
8213         <param id="field">
8214           <jfieldID class="klass"/>
8215             <description>
8216               The field to query.
8217             </description>
8218         </param>
8219         <param id="is_synthetic_ptr">
8220           <outptr><jboolean/></outptr>
8221           <description>
8222             On return, points to the boolean result of this function.
8223           </description>
8224         </param>
8225       </parameters>
8226       <errors>
8227       </errors>
8228     </function>
8229 
8230   </category>
8231 
8232   <category id="method" label="Method">
8233 
8234     <intro>
8235       These functions provide information about a method (represented as a
8236       <typelink id="jmethodID"/>) and set how methods are processed.
8237     </intro>
8238 
8239     <intro id="obsoleteMethods" label="Obsolete Methods">
8240       The functions <functionlink id="RetransformClasses"/> and
8241       <functionlink id="RedefineClasses"/> can cause new versions
8242       of methods to be installed.
8243       An original version of a method is considered equivalent
8244       to the new version if:
8245       <ul>
8246         <li>their bytecodes are the same except for indices into the
8247           constant pool and </li>
8248         <li>the referenced constants are equal.</li>
8249       </ul>
8250       An original method version which is not equivalent to the
8251       new method version is called obsolete and is assigned a new method ID;
8252       the original method ID now refers to the new method version.
8253       A method ID can be tested for obsolescence with
8254       <functionlink id="IsMethodObsolete"/>.
8255     </intro>
8256 
8257     <function id="GetMethodName" phase="start" num="64">
8258       <synopsis>Get Method Name (and Signature)</synopsis>
8259       <description>
8260         For the method indicated by <code>method</code>,
8261         return the method name via <code>name_ptr</code> and method signature via
8262         <code>signature_ptr</code>.
8263         <p/>
8264         Method signatures are defined in the
8265         <externallink id="jni/index.html">JNI Specification</externallink>
8266         and are referred to as <code>method descriptors</code> in
8267         <vmspec chapter="4.3.3"/>.
8268         Note this is different
8269         than method signatures as defined in the <i>Java Language Specification</i>.
8270       </description>
8271       <origin>jvmdiClone</origin>
8272       <capabilities>
8273       </capabilities>
8274       <parameters>
8275         <param id="method">
8276           <jmethodID/>
8277             <description>
8278               The method to query.
8279             </description>
8280         </param>
8281         <param id="name_ptr">
8282           <allocbuf>
8283             <char/>
8284             <nullok>the name is not returned</nullok>
8285           </allocbuf>
8286           <description>
8287             On return, points to the method name, encoded as a
8288             <internallink id="mUTF">modified UTF-8</internallink> string.
8289           </description>
8290         </param>
8291         <param id="signature_ptr">
8292           <allocbuf>
8293             <char/>
8294             <nullok>the signature is not returned</nullok>
8295           </allocbuf>
8296           <description>
8297             On return, points to the method signature, encoded as a
8298             <internallink id="mUTF">modified UTF-8</internallink> string.
8299           </description>
8300         </param>
8301         <param id="generic_ptr">
8302           <allocbuf>
8303             <char/>
8304             <nullok>the generic signature is not returned</nullok>
8305           </allocbuf>
8306           <description>
8307             On return, points to the generic signature of the method, encoded as a
8308             <internallink id="mUTF">modified UTF-8</internallink> string.
8309             If there is no generic signature attribute for the method, then,
8310             on return, points to <code>NULL</code>.
8311           </description>
8312         </param>
8313       </parameters>
8314       <errors>
8315       </errors>
8316     </function>
8317 
8318     <function id="GetMethodDeclaringClass" phase="start" num="65">
8319       <synopsis>Get Method Declaring Class</synopsis>
8320       <description>
8321         For the method indicated by <code>method</code>,
8322         return the class that defined it via <code>declaring_class_ptr</code>.
8323       </description>
8324       <origin>jvmdi</origin>
8325       <capabilities>
8326       </capabilities>
8327       <parameters>
8328         <param id="klass">
8329           <jclass method="method"/>
8330             <description>
8331               The class to query.
8332             </description>
8333         </param>
8334         <param id="method">
8335           <jmethodID class="klass"/>
8336             <description>
8337               The method to query.
8338             </description>
8339         </param>
8340         <param id="declaring_class_ptr">
8341           <outptr><jclass/></outptr>
8342             <description>
8343               On return, points to the declaring class
8344             </description>
8345         </param>
8346       </parameters>
8347       <errors>
8348       </errors>
8349     </function>
8350 
8351     <function id="GetMethodModifiers" phase="start" num="66">
8352       <synopsis>Get Method Modifiers</synopsis>
8353       <description>
8354         For the method indicated by <code>method</code>,
8355         return the access flags via <code>modifiers_ptr</code>.
8356         Access flags are defined in <vmspec chapter="4"/>.
8357       </description>
8358       <origin>jvmdi</origin>
8359       <capabilities>
8360       </capabilities>
8361       <parameters>
8362         <param id="klass">
8363           <jclass method="method"/>
8364             <description>
8365               The class to query.
8366             </description>
8367         </param>
8368         <param id="method">
8369           <jmethodID class="klass"/>
8370             <description>
8371               The method to query.
8372             </description>
8373         </param>
8374         <param id="modifiers_ptr">
8375           <outptr><jint/></outptr>
8376           <description>
8377             On return, points to the access flags.
8378           </description>
8379         </param>
8380       </parameters>
8381       <errors>
8382       </errors>
8383     </function>
8384 
8385     <function id="GetMaxLocals" phase="start" num="68">
8386       <synopsis>Get Max Locals</synopsis>
8387       <description>
8388           For the method indicated by <code>method</code>,
8389           return the number of local variable slots used by the method,
8390           including the local variables used to pass parameters to the
8391           method on its invocation.
8392           <p/>
8393           See <code>max_locals</code> in <vmspec chapter="4.7.3"/>.
8394       </description>
8395       <origin>jvmdi</origin>
8396       <capabilities>
8397       </capabilities>
8398       <parameters>
8399         <param id="klass">
8400           <jclass method="method"/>
8401             <description>
8402               The class to query.
8403             </description>
8404         </param>
8405         <param id="method">
8406           <jmethodID class="klass" native="error"/>
8407             <description>
8408               The method to query.
8409             </description>
8410         </param>
8411         <param id="max_ptr">
8412           <outptr><jint/></outptr>
8413           <description>
8414             On return, points to the maximum number of local slots
8415           </description>
8416         </param>
8417       </parameters>
8418       <errors>
8419       </errors>
8420     </function>
8421 
8422     <function id="GetArgumentsSize" phase="start" num="69">
8423       <synopsis>Get Arguments Size</synopsis>
8424       <description>
8425         For the method indicated by <code>method</code>,
8426         return via <code>max_ptr</code> the number of local variable slots used
8427         by the method's arguments.
8428         Note that two-word arguments use two slots.
8429       </description>
8430       <origin>jvmdi</origin>
8431       <capabilities>
8432       </capabilities>
8433       <parameters>
8434         <param id="klass">
8435           <jclass method="method"/>
8436             <description>
8437               The class to query.
8438             </description>
8439         </param>
8440         <param id="method">
8441           <jmethodID class="klass" native="error"/>
8442             <description>
8443               The method to query.
8444             </description>
8445         </param>
8446         <param id="size_ptr">
8447           <outptr><jint/></outptr>
8448           <description>
8449             On return, points to the number of argument slots
8450           </description>
8451         </param>
8452       </parameters>
8453       <errors>
8454       </errors>
8455     </function>
8456 
8457     <function id="GetLineNumberTable" phase="start" num="70">
8458       <synopsis>Get Line Number Table</synopsis>
8459       <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
8460         <field id="start_location">
8461           <jlocation/>
8462           <description>
8463             the <datalink id="jlocation"></datalink> where the line begins
8464           </description>
8465         </field>
8466         <field id="line_number">
8467           <jint/>
8468           <description>
8469             the line number
8470           </description>
8471         </field>
8472       </typedef>
8473       <description>
8474         For the method indicated by <code>method</code>,
8475         return a table of source line number entries. The size of the table is
8476         returned via <code>entry_count_ptr</code> and the table itself is
8477         returned via <code>table_ptr</code>.
8478       </description>
8479       <origin>jvmdi</origin>
8480       <capabilities>
8481         <required id="can_get_line_numbers"></required>
8482       </capabilities>
8483       <parameters>
8484         <param id="klass">
8485           <jclass method="method"/>
8486             <description>
8487               The class to query.
8488             </description>
8489         </param>
8490         <param id="method">
8491           <jmethodID class="klass" native="error"/>
8492             <description>
8493               The method to query.
8494             </description>
8495         </param>
8496         <param id="entry_count_ptr">
8497           <outptr><jint/></outptr>
8498           <description>
8499             On return, points to the number of entries in the table
8500           </description>
8501         </param>
8502         <param id="table_ptr">
8503           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
8504           <description>
8505             On return, points to the line number table pointer.
8506           </description>
8507         </param>
8508       </parameters>
8509       <errors>
8510         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8511           Class information does not include line numbers.
8512         </error>
8513       </errors>
8514     </function>
8515 
8516     <function id="GetMethodLocation" phase="start" num="71">
8517       <synopsis>Get Method Location</synopsis>
8518       <description>
8519         For the method indicated by <code>method</code>,
8520         return the beginning and ending addresses through
8521         <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
8522         conventional bytecode indexing scheme,
8523         <code>start_location_ptr</code> will always point to zero
8524         and <code>end_location_ptr</code>
8525         will always point to the bytecode count minus one.
8526       </description>
8527       <origin>jvmdi</origin>
8528       <capabilities>
8529       </capabilities>
8530       <parameters>
8531         <param id="klass">
8532           <jclass method="method"/>
8533             <description>
8534               The class to query.
8535             </description>
8536         </param>
8537         <param id="method">
8538           <jmethodID class="klass" native="error"/>
8539             <description>
8540               The method to query.
8541             </description>
8542         </param>
8543         <param id="start_location_ptr">
8544           <outptr><jlocation/></outptr>
8545           <description>
8546             On return, points to the first location, or
8547             <code>-1</code> if location information is not available.
8548             If the information is available and
8549             <functionlink id="GetJLocationFormat"></functionlink>
8550             returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
8551             then this will always be zero.
8552           </description>
8553         </param>
8554         <param id="end_location_ptr">
8555           <outptr><jlocation/></outptr>
8556           <description>
8557             On return, points to the last location,
8558             or <code>-1</code> if location information is not available.
8559           </description>
8560         </param>
8561       </parameters>
8562       <errors>
8563         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8564           Class information does not include method sizes.
8565         </error>
8566       </errors>
8567     </function>
8568 
8569     <function id="GetLocalVariableTable" num="72">
8570       <synopsis>Get Local Variable Table</synopsis>
8571       <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
8572         <field id="start_location">
8573           <jlocation/>
8574           <description>
8575             The code array index where the local variable is first valid
8576             (that is, where it must have a value).
8577           </description>
8578         </field>
8579         <field id="length">
8580           <jint/>
8581           <description>
8582             The length of the valid section for this local variable.
8583             The last code array index where the local variable is valid
8584             is <code>start_location + length</code>.
8585           </description>
8586         </field>
8587         <field id="name">
8588           <allocfieldbuf><char/></allocfieldbuf>
8589           <description>
8590             The local variable name, encoded as a
8591             <internallink id="mUTF">modified UTF-8</internallink> string.
8592           </description>
8593         </field>
8594         <field id="signature">
8595           <allocfieldbuf><char/></allocfieldbuf>
8596           <description>
8597             The local variable's type signature, encoded as a
8598             <internallink id="mUTF">modified UTF-8</internallink> string.
8599             The signature format is the same as that defined in
8600             <vmspec chapter="4.3.2"/>.
8601           </description>
8602         </field>
8603         <field id="generic_signature">
8604           <allocfieldbuf><char/></allocfieldbuf>
8605           <description>
8606             The local variable's generic signature, encoded as a
8607             <internallink id="mUTF">modified UTF-8</internallink> string.
8608             The value of this field will be <code>NULL</code> for any local
8609             variable which does not have a generic type.
8610           </description>
8611         </field>
8612         <field id="slot">
8613           <jint/>
8614           <description>
8615             The local variable's slot.  See <internallink id="local">Local Variables</internallink>.
8616           </description>
8617         </field>
8618       </typedef>
8619       <description>
8620         Return local variable information.
8621       </description>
8622       <origin>jvmdiClone</origin>
8623       <capabilities>
8624         <required id="can_access_local_variables"></required>
8625       </capabilities>
8626       <parameters>
8627         <param id="method">
8628           <jmethodID native="error"/>
8629             <description>
8630               The method to query.
8631             </description>
8632         </param>
8633         <param id="entry_count_ptr">
8634           <outptr><jint/></outptr>
8635           <description>
8636             On return, points to the number of entries in the table
8637           </description>
8638         </param>
8639         <param id="table_ptr">
8640           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
8641           <description>
8642             On return, points to an array of local variable table entries.
8643           </description>
8644         </param>
8645       </parameters>
8646       <errors>
8647         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
8648           Class information does not include local variable
8649           information.
8650         </error>
8651       </errors>
8652     </function>
8653 
8654     <function id="GetBytecodes" phase="start" num="75">
8655       <synopsis>Get Bytecodes</synopsis>
8656       <description>
8657         For the method indicated by <code>method</code>,
8658         return the bytecodes that implement the method. The number of
8659         bytecodes is returned via <code>bytecode_count_ptr</code>. The bytecodes
8660         themselves are returned via <code>bytecodes_ptr</code>.
8661       </description>
8662       <origin>jvmdi</origin>
8663       <capabilities>
8664         <required id="can_get_bytecodes"></required>
8665       </capabilities>
8666       <parameters>
8667         <param id="klass">
8668           <jclass method="method"/>
8669             <description>
8670               The class to query.
8671             </description>
8672         </param>
8673         <param id="method">
8674           <jmethodID class="klass" native="error"/>
8675             <description>
8676               The method to query.
8677             </description>
8678         </param>
8679         <param id="bytecode_count_ptr">
8680           <outptr><jint/></outptr>
8681           <description>
8682             On return, points to the length of the bytecode array
8683           </description>
8684         </param>
8685         <param id="bytecodes_ptr">
8686           <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
8687           <description>
8688             On return, points to the pointer to the bytecode array
8689           </description>
8690         </param>
8691       </parameters>
8692       <errors>
8693       </errors>
8694     </function>
8695 
8696     <function id="IsMethodNative" phase="start" num="76">
8697       <synopsis>Is Method Native</synopsis>
8698       <description>
8699         For the method indicated by <code>method</code>, return a
8700         value indicating whether the method is native via <code>is_native_ptr</code>
8701       </description>
8702       <origin>jvmdi</origin>
8703       <capabilities>
8704       </capabilities>
8705       <parameters>
8706         <param id="klass">
8707           <jclass method="method"/>
8708             <description>
8709               The class to query.
8710             </description>
8711         </param>
8712         <param id="method">
8713           <jmethodID class="klass"/>
8714             <description>
8715               The method to query.
8716             </description>
8717         </param>
8718         <param id="is_native_ptr">
8719           <outptr><jboolean/></outptr>
8720           <description>
8721             On return, points to the boolean result of this function.
8722           </description>
8723         </param>
8724       </parameters>
8725       <errors>
8726       </errors>
8727     </function>
8728 
8729     <function id="IsMethodSynthetic" phase="start" num="77">
8730       <synopsis>Is Method Synthetic</synopsis>
8731       <description>
8732         For the method indicated by <code>method</code>, return a
8733         value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
8734         Synthetic methods are generated by the compiler but not present in the
8735         original source code.
8736       </description>
8737       <origin>jvmdi</origin>
8738       <capabilities>
8739         <required id="can_get_synthetic_attribute"></required>
8740       </capabilities>
8741       <parameters>
8742         <param id="klass">
8743           <jclass method="method"/>
8744             <description>
8745               The class to query.
8746             </description>
8747         </param>
8748         <param id="method">
8749           <jmethodID class="klass"/>
8750             <description>
8751               The method to query.
8752             </description>
8753         </param>
8754         <param id="is_synthetic_ptr">
8755           <outptr><jboolean/></outptr>
8756           <description>
8757             On return, points to the boolean result of this function.
8758           </description>
8759         </param>
8760       </parameters>
8761       <errors>
8762       </errors>
8763     </function>
8764 
8765     <function id="IsMethodObsolete" phase="start" num="91">
8766       <synopsis>Is Method Obsolete</synopsis>
8767       <description>
8768         Determine if a method ID refers to an
8769         <internallink id="obsoleteMethods">obsolete</internallink>
8770         method version.
8771       </description>
8772       <origin>jvmdi</origin>
8773       <capabilities>
8774       </capabilities>
8775       <parameters>
8776         <param id="klass">
8777           <jclass method="method"/>
8778             <description>
8779               The class to query.
8780             </description>
8781         </param>
8782         <param id="method">
8783           <jmethodID class="klass"/>
8784             <description>
8785               The method ID to query.
8786             </description>
8787         </param>
8788         <param id="is_obsolete_ptr">
8789           <outptr><jboolean/></outptr>
8790           <description>
8791             On return, points to the boolean result of this function.
8792           </description>
8793         </param>
8794       </parameters>
8795       <errors>
8796       </errors>
8797     </function>
8798 
8799     <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
8800       <synopsis>Set Native Method Prefix</synopsis>
8801       <description>
8802         This function modifies the failure handling of
8803         native method resolution by allowing retry
8804         with a prefix applied to the name.
8805         When used with the
8806         <eventlink id="ClassFileLoadHook">ClassFileLoadHook
8807         event</eventlink>, it enables native methods to be
8808         <internallink id="bci">instrumented</internallink>.
8809         <p/>
8810         Since native methods cannot be directly instrumented
8811         (they have no bytecodes), they must be wrapped with
8812         a non-native method which can be instrumented.
8813         For example, if we had:
8814         <example>
8815 native boolean foo(int x);</example>
8816         <p/>
8817         We could transform the class file (with the
8818         ClassFileLoadHook event) so that this becomes:
8819         <example>
8820 boolean foo(int x) {
8821   <i>... record entry to foo ...</i>
8822   return wrapped_foo(x);
8823 }
8824 
8825 native boolean wrapped_foo(int x);</example>
8826         <p/>
8827         Where foo becomes a wrapper for the actual native method
8828         with the appended prefix "wrapped_".  Note that
8829         "wrapped_" would be a poor choice of prefix since it
8830         might conceivably form the name of an existing method
8831         thus something like "$$$MyAgentWrapped$$$_" would be
8832         better but would make these examples less readable.
8833         <p/>
8834         The wrapper will allow data to be collected on the native
8835         method call, but now the problem becomes linking up the
8836         wrapped method with the native implementation.
8837         That is, the method <code>wrapped_foo</code> needs to be
8838         resolved to the native implementation of <code>foo</code>,
8839         which might be:
8840         <example>
8841 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
8842         <p/>
8843         This function allows the prefix to be specified and the
8844         proper resolution to occur.
8845         Specifically, when the standard resolution fails, the
8846         resolution is retried taking the prefix into consideration.
8847         There are two ways that resolution occurs, explicit
8848         resolution with the JNI function <code>RegisterNatives</code>
8849         and the normal automatic resolution.  For
8850         <code>RegisterNatives</code>, the VM will attempt this
8851         association:
8852         <example>
8853 method(foo) -> nativeImplementation(foo)</example>
8854         <p/>
8855         When this fails, the resolution will be retried with
8856         the specified prefix prepended to the method name,
8857         yielding the correct resolution:
8858         <example>
8859 method(wrapped_foo) -> nativeImplementation(foo)</example>
8860         <p/>
8861         For automatic resolution, the VM will attempt:
8862         <example>
8863 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
8864         <p/>
8865         When this fails, the resolution will be retried with
8866         the specified prefix deleted from the implementation name,
8867         yielding the correct resolution:
8868         <example>
8869 method(wrapped_foo) -> nativeImplementation(foo)</example>
8870         <p/>
8871         Note that since the prefix is only used when standard
8872         resolution fails, native methods can be wrapped selectively.
8873         <p/>
8874         Since each <jvmti/> environment is independent and
8875         can do its own transformation of the bytecodes, more
8876         than one layer of wrappers may be applied. Thus each
8877         environment needs its own prefix.  Since transformations
8878         are applied in order, the prefixes, if applied, will
8879         be applied in the same order.
8880         The order of transformation application is described in
8881         the <eventlink id="ClassFileLoadHook"/> event.
8882         Thus if three environments applied
8883         wrappers, <code>foo</code> might become
8884         <code>$env3_$env2_$env1_foo</code>.  But if, say,
8885         the second environment did not apply a wrapper to
8886         <code>foo</code> it would be just
8887         <code>$env3_$env1_foo</code>.  To be able to
8888         efficiently determine the sequence of prefixes,
8889         an intermediate prefix is only applied if its non-native
8890         wrapper exists.  Thus, in the last example, even though
8891         <code>$env1_foo</code> is not a native method, the
8892         <code>$env1_</code> prefix is applied since
8893         <code>$env1_foo</code> exists.
8894         <p/>
8895         Since the prefixes are used at resolution time
8896         and since resolution may be arbitrarily delayed, a
8897         native method prefix must remain set as long as there
8898         are corresponding prefixed native methods.
8899       </description>
8900       <origin>new</origin>
8901       <capabilities>
8902         <required id="can_set_native_method_prefix"></required>
8903       </capabilities>
8904       <parameters>
8905         <param id="prefix">
8906           <inbuf>
8907             <char/>
8908             <nullok>
8909               any existing prefix in this environment is cancelled
8910             </nullok>
8911           </inbuf>
8912           <description>
8913             The prefix to apply, encoded as a
8914             <internallink id="mUTF">modified UTF-8</internallink> string.
8915           </description>
8916         </param>
8917       </parameters>
8918       <errors>
8919       </errors>
8920     </function>
8921 
8922     <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
8923       <synopsis>Set Native Method Prefixes</synopsis>
8924       <description>
8925          For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
8926          will provide all needed native method prefixing.
8927          For a meta-agent that performs multiple independent class
8928          file transformations (for example as a proxy for another
8929          layer of agents) this function allows each transformation
8930          to have its own prefix.
8931          The prefixes are applied in the order supplied and are
8932          processed in the same manner as described for the
8933          application of prefixes from multiple <jvmti/> environments
8934          in <functionlink id="SetNativeMethodPrefix"/>.
8935          <p/>
8936          Any previous prefixes are replaced.  Thus, calling this
8937          function with a <paramlink id="prefix_count"/> of <code>0</code>
8938          disables prefixing in this environment.
8939          <p/>
8940          <functionlink id="SetNativeMethodPrefix"/> and this function
8941          are the two ways to set the prefixes.
8942          Calling <code>SetNativeMethodPrefix</code> with
8943          a prefix is the same as calling this function with
8944          <paramlink id="prefix_count"/> of <code>1</code>.
8945          Calling <code>SetNativeMethodPrefix</code> with
8946          <code>NULL</code> is the same as calling this function with
8947          <paramlink id="prefix_count"/> of <code>0</code>.
8948       </description>
8949       <origin>new</origin>
8950       <capabilities>
8951         <required id="can_set_native_method_prefix"></required>
8952       </capabilities>
8953       <parameters>
8954         <param id="prefix_count">
8955           <jint min="0"/>
8956             <description>
8957               The number of prefixes to apply.
8958             </description>
8959         </param>
8960         <param id="prefixes">
8961           <agentbuf>
8962             <char/>
8963           </agentbuf>
8964           <description>
8965             The prefixes to apply for this environment, each encoded as a
8966             <internallink id="mUTF">modified UTF-8</internallink> string.
8967           </description>
8968         </param>
8969       </parameters>
8970       <errors>
8971       </errors>
8972     </function>
8973 
8974   </category>
8975 
8976   <category id="RawMonitors" label="Raw Monitor">
8977 
8978     <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
8979       <synopsis>Create Raw Monitor</synopsis>
8980       <description>
8981         Create a raw monitor.
8982       </description>
8983       <origin>jvmdi</origin>
8984       <capabilities>
8985       </capabilities>
8986       <parameters>
8987         <param id="name">
8988           <inbuf><char/></inbuf>
8989           <description>
8990             A name to identify the monitor, encoded as a
8991             <internallink id="mUTF">modified UTF-8</internallink> string.
8992           </description>
8993         </param>
8994         <param id="monitor_ptr">
8995           <outptr><jrawMonitorID/></outptr>
8996           <description>
8997             On return, points to the created monitor.
8998           </description>
8999         </param>
9000       </parameters>
9001       <errors>
9002       </errors>
9003     </function>
9004 
9005     <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
9006       <synopsis>Destroy Raw Monitor</synopsis>
9007       <description>
9008         Destroy the raw monitor.
9009         If the monitor being destroyed has been entered by this thread, it will be
9010         exited before it is destroyed.
9011         If the monitor being destroyed has been entered by another thread,
9012         an error will be returned and the monitor will not be destroyed.
9013       </description>
9014       <origin>jvmdi</origin>
9015       <capabilities>
9016       </capabilities>
9017       <parameters>
9018         <param id="monitor">
9019           <jrawMonitorID/>
9020           <description>
9021             The monitor
9022           </description>
9023         </param>
9024       </parameters>
9025       <errors>
9026         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9027           Not monitor owner
9028         </error>
9029       </errors>
9030     </function>
9031 
9032     <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
9033       <synopsis>Raw Monitor Enter</synopsis>
9034       <description>
9035         Gain exclusive ownership of a raw monitor.
9036         The same thread may enter a monitor more then once.
9037         The thread must
9038         <functionlink id="RawMonitorExit">exit</functionlink>
9039         the monitor the same number of times as it is entered.
9040         If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
9041         and has not exited when attached threads come into existence, the enter
9042         is considered to have occurred on the main thread.
9043       </description>
9044       <origin>jvmdi</origin>
9045       <capabilities>
9046       </capabilities>
9047       <parameters>
9048         <param id="monitor">
9049           <jrawMonitorID/>
9050           <description>
9051             The monitor
9052           </description>
9053         </param>
9054       </parameters>
9055       <errors>
9056       </errors>
9057     </function>
9058 
9059     <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
9060       <synopsis>Raw Monitor Exit</synopsis>
9061       <description>
9062         Release exclusive ownership of a raw monitor.
9063       </description>
9064       <origin>jvmdi</origin>
9065       <capabilities>
9066       </capabilities>
9067       <parameters>
9068         <param id="monitor">
9069           <jrawMonitorID/>
9070           <description>
9071             The monitor
9072           </description>
9073         </param>
9074       </parameters>
9075       <errors>
9076         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9077           Not monitor owner
9078         </error>
9079       </errors>
9080     </function>
9081 
9082     <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
9083       <synopsis>Raw Monitor Wait</synopsis>
9084       <description>
9085         Wait for notification of the raw monitor.
9086         <p/>
9087         Causes the current thread to wait until either another thread calls
9088         <functionlink id="RawMonitorNotify"/> or
9089         <functionlink id="RawMonitorNotifyAll"/>
9090         for the specified raw monitor, or the specified
9091         <paramlink id="millis">timeout</paramlink>
9092         has elapsed.
9093       </description>
9094       <origin>jvmdi</origin>
9095       <capabilities>
9096       </capabilities>
9097       <parameters>
9098         <param id="monitor">
9099           <jrawMonitorID/>
9100           <description>
9101             The monitor
9102           </description>
9103         </param>
9104         <param id="millis">
9105           <jlong/>
9106           <description>
9107             The timeout, in milliseconds.  If the timeout is
9108             zero, then real time is not taken into consideration
9109             and the thread simply waits until notified.
9110           </description>
9111         </param>
9112       </parameters>
9113       <errors>
9114         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9115           Not monitor owner
9116         </error>
9117         <error id="JVMTI_ERROR_INTERRUPT">
9118           Wait was interrupted, try again
9119         </error>
9120       </errors>
9121     </function>
9122 
9123     <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
9124       <synopsis>Raw Monitor Notify</synopsis>
9125       <description>
9126         Notify a single thread waiting on the raw monitor.
9127       </description>
9128       <origin>jvmdi</origin>
9129       <capabilities>
9130       </capabilities>
9131       <parameters>
9132         <param id="monitor">
9133           <jrawMonitorID/>
9134           <description>
9135             The monitor
9136           </description>
9137         </param>
9138       </parameters>
9139       <errors>
9140         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9141           Not monitor owner
9142         </error>
9143       </errors>
9144     </function>
9145 
9146     <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
9147       <synopsis>Raw Monitor Notify All</synopsis>
9148       <description>
9149         Notify all threads waiting on the raw monitor.
9150       </description>
9151       <origin>jvmdi</origin>
9152       <capabilities>
9153       </capabilities>
9154       <parameters>
9155         <param id="monitor">
9156           <jrawMonitorID/>
9157           <description>
9158             The monitor
9159           </description>
9160         </param>
9161       </parameters>
9162       <errors>
9163         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
9164           Not monitor owner
9165         </error>
9166       </errors>
9167     </function>
9168 
9169    <elide>
9170     <function id="GetRawMonitorUse" num="118">
9171       <synopsis>Get Raw Monitor Use</synopsis>
9172       <description>
9173         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
9174         are filled in with information about usage of the raw monitor.
9175       </description>
9176       <origin>new</origin>
9177       <capabilities>
9178         <required id="can_get_raw_monitor_usage"></required>
9179       </capabilities>
9180       <parameters>
9181         <param id="monitor">
9182           <jrawMonitorID/>
9183           <description>
9184             the raw monitor to query.
9185           </description>
9186         </param>
9187         <param id="info_ptr">
9188           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
9189           <description>
9190             On return, filled with monitor information for the
9191             specified raw monitor.
9192           </description>
9193         </param>
9194       </parameters>
9195       <errors>
9196       </errors>
9197     </function>
9198 
9199     <function id="GetRawMonitors" num="119">
9200       <synopsis>Get Raw Monitors</synopsis>
9201       <description>
9202         Return the list of raw monitors.
9203         <p/>
9204         Note: details about each monitor can be examined with
9205         <functionlink id="GetRawMonitorUse"></functionlink>.
9206       </description>
9207       <origin>new</origin>
9208       <capabilities>
9209         <required id="can_get_raw_monitor_usage"></required>
9210       </capabilities>
9211       <parameters>
9212         <param id="monitorCnt">
9213           <outptr><jint/></outptr>
9214           <description>
9215             On return, pointer to the number
9216             of monitors returned in <code>monitors_ptr</code>.
9217           </description>
9218         </param>
9219         <param id="monitors_ptr">
9220           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
9221           <description>
9222             On return, pointer to the monitor list.
9223           </description>
9224         </param>
9225       </parameters>
9226       <errors>
9227       </errors>
9228     </function>
9229     </elide>
9230   </category>
9231 
9232   <category id="jniIntercept" label="JNI Function Interception">
9233 
9234     <intro>
9235       Provides the ability to intercept and resend
9236       Java Native Interface (JNI) function calls
9237       by manipulating the JNI function table.
9238       See <externallink id="jni/functions.html">JNI
9239         Functions</externallink> in the <i>Java Native Interface Specification</i>.
9240       <p/>
9241       The following example illustrates intercepting the
9242       <code>NewGlobalRef</code> JNI call in order to count reference
9243       creation.
9244       <example>
9245 JNIEnv original_jni_Functions;
9246 JNIEnv redirected_jni_Functions;
9247 int my_global_ref_count = 0;
9248 
9249 jobject
9250 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
9251    ++my_global_ref_count;
9252    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
9253 }
9254 
9255 void
9256 myInit() {
9257    jvmtiError err;
9258 
9259    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;original_jni_Functions);
9260    if (err != JVMTI_ERROR_NONE) {
9261       die();
9262    }
9263    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;redirected_jni_Functions);
9264    if (err != JVMTI_ERROR_NONE) {
9265       die();
9266    }
9267    redirectedJNIFunctions-&gt;NewGlobalRef = MyNewGlobalRef;
9268       err = (*jvmti_env)-&gt;SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
9269    if (err != JVMTI_ERROR_NONE) {
9270       die();
9271    }
9272 }
9273       </example>
9274       Sometime after <code>myInit</code> is called the user's JNI
9275       code is executed which makes the call to create a new global
9276       reference.  Instead of going to the normal JNI implementation
9277       the call goes to <code>myNewGlobalRef</code>.  Note that a
9278       copy of the original function table is kept so that the normal
9279       JNI function can be called after the data is collected.
9280       Note also that any JNI functions which are not overwritten
9281       will behave normally.
9282       <todo>
9283         check that the example compiles and executes.
9284       </todo>
9285     </intro>
9286 
9287     <function id="SetJNIFunctionTable" phase="start" num="120">
9288       <synopsis>Set JNI Function Table</synopsis>
9289       <description>
9290         Set the JNI function table
9291         in all current and future JNI environments.
9292         As a result, all future JNI calls are directed to the specified functions.
9293         Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
9294         function table to pass to this function.
9295         For this function to take effect the the updated table entries must be
9296         used by the JNI clients.
9297         Since the table is defined <code>const</code> some compilers may optimize
9298         away the access to the table, thus preventing this function from taking
9299         effect.
9300         The table is copied--changes to the local copy of the
9301         table have no effect.
9302         This function affects only the function table, all other aspects of the environment are
9303         unaffected.
9304         See the examples <internallink id="jniIntercept">above</internallink>.
9305       </description>
9306       <origin>new</origin>
9307       <capabilities>
9308       </capabilities>
9309       <parameters>
9310         <param id="function_table">
9311           <inptr>
9312             <struct>jniNativeInterface</struct>
9313           </inptr>
9314           <description>
9315             Points to the new JNI function table.
9316           </description>
9317         </param>
9318       </parameters>
9319       <errors>
9320       </errors>
9321     </function>
9322 
9323     <function id="GetJNIFunctionTable" phase="start" num="121">
9324       <synopsis>Get JNI Function Table</synopsis>
9325       <description>
9326         Get the JNI function table.
9327         The JNI function table is copied into allocated memory.
9328         If <functionlink id="SetJNIFunctionTable"></functionlink>
9329         has been called, the modified (not the original) function
9330         table is returned.
9331         Only the function table is copied, no other aspects of the environment
9332         are copied.
9333         See the examples <internallink id="jniIntercept">above</internallink>.
9334       </description>
9335       <origin>new</origin>
9336       <capabilities>
9337       </capabilities>
9338       <parameters>
9339         <param id="function_table">
9340           <allocbuf>
9341             <struct>jniNativeInterface</struct>
9342           </allocbuf>
9343           <description>
9344             On return, <code>*function_table</code>
9345             points a newly allocated copy of the JNI function table.
9346           </description>
9347         </param>
9348       </parameters>
9349       <errors>
9350       </errors>
9351     </function>
9352 
9353   </category>
9354 
9355   <category id="eventManagement" label="Event Management">
9356 
9357     <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
9358       <synopsis>Set Event Callbacks</synopsis>
9359       <description>
9360         Set the functions to be called for each event.
9361         The callbacks are specified by supplying a replacement function table.
9362         The function table is copied--changes to the local copy of the
9363         table have no effect.
9364         This is an atomic action, all callbacks are set at once.
9365         No events are sent before this function is called.
9366         When an entry is <code>NULL</code> or when the event is beyond
9367         <paramlink id="size_of_callbacks"></paramlink> no event is sent.
9368         Details on events are
9369         described <internallink id="EventSection">later</internallink> in this document.
9370         An event must be enabled and have a callback in order to be
9371         sent--the order in which this function and
9372         <functionlink id="SetEventNotificationMode"></functionlink>
9373         are called does not affect the result.
9374       </description>
9375       <origin>new</origin>
9376       <capabilities>
9377       </capabilities>
9378       <parameters>
9379         <param id="callbacks">
9380           <inptr>
9381             <struct>jvmtiEventCallbacks</struct>
9382             <nullok>remove the existing callbacks</nullok>
9383           </inptr>
9384           <description>
9385             The new event callbacks.
9386           </description>
9387         </param>
9388         <param id="size_of_callbacks">
9389           <jint min="0"/>
9390           <description>
9391             <code>sizeof(jvmtiEventCallbacks)</code>--for version
9392             compatibility.
9393           </description>
9394         </param>
9395       </parameters>
9396       <errors>
9397       </errors>
9398     </function>
9399 
9400     <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
9401       <synopsis>Set Event Notification Mode</synopsis>
9402       <description>
9403         Control the generation of events.
9404         <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
9405           <constant id="JVMTI_ENABLE" num="1">
9406             If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>,
9407             the event <paramlink id="event_type"></paramlink> will be enabled
9408           </constant>
9409           <constant id="JVMTI_DISABLE" num="0">
9410             If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>,
9411             the event <paramlink id="event_type"></paramlink> will be disabled
9412           </constant>
9413         </constants>
9414         If <code>event_thread</code> is <code>NULL</code>,
9415         the event is enabled or disabled globally; otherwise, it is
9416         enabled or disabled for a particular thread.
9417         An event is generated for
9418         a particular thread if it is enabled either at the thread or global
9419         levels.
9420         <p/>
9421         See <internallink id="EventIndex">below</internallink> for information on specific events.
9422         <p/>
9423         The following events cannot be controlled at the thread
9424         level through this function.
9425         <ul>
9426           <li><eventlink id="VMInit"></eventlink></li>
9427           <li><eventlink id="VMStart"></eventlink></li>
9428           <li><eventlink id="VMDeath"></eventlink></li>
9429           <li><eventlink id="ThreadStart"></eventlink></li>
9430           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9431           <li><eventlink id="CompiledMethodUnload"></eventlink></li>
9432           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9433           <li><eventlink id="DataDumpRequest"></eventlink></li>
9434         </ul>
9435         <p/>
9436         Initially, no events are enabled at either the thread level
9437         or the global level.
9438         <p/>
9439         Any needed capabilities (see Event Enabling Capabilities below) must be possessed
9440         before calling this function.
9441         <p/>
9442         Details on events are
9443         described <internallink id="EventSection">below</internallink>.
9444       </description>
9445       <origin>jvmdiClone</origin>
9446       <eventcapabilities></eventcapabilities>
9447       <parameters>
9448         <param id="mode">
9449           <enum>jvmtiEventMode</enum>
9450           <description>
9451             <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
9452           </description>
9453         </param>
9454         <param id="event_type">
9455           <enum>jvmtiEvent</enum>
9456           <description>
9457             the event to control
9458           </description>
9459         </param>
9460         <param id="event_thread">
9461           <ptrtype>
9462             <jthread impl="noconvert"/>
9463             <nullok>event is controlled at the global level</nullok>
9464           </ptrtype>
9465             <description>
9466               The thread to control
9467             </description>
9468         </param>
9469         <param id="...">
9470           <varargs/>
9471             <description>
9472               for future expansion
9473             </description>
9474         </param>
9475       </parameters>
9476       <errors>
9477         <error id="JVMTI_ERROR_INVALID_THREAD">
9478           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
9479         </error>
9480         <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
9481           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead).
9482         </error>
9483         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9484           thread level control was attempted on events which do not
9485           permit thread level control.
9486         </error>
9487         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
9488           The Required Event Enabling Capability is not possessed.
9489         </error>
9490       </errors>
9491     </function>
9492 
9493     <function id="GenerateEvents" num="123">
9494       <synopsis>Generate Events</synopsis>
9495       <description>
9496         Generate events to represent the current state of the VM.
9497         For example, if <paramlink id="event_type"/> is
9498         <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
9499         a <eventlink id="CompiledMethodLoad"></eventlink> event will be
9500         sent for each currently compiled method.
9501         Methods that were loaded and now have been unloaded are not sent.
9502         The history of what events have previously been sent does not
9503         effect what events are sent by this function--for example,
9504         all currently compiled methods
9505         will be sent each time this function is called.
9506         <p/>
9507         This function is useful when
9508         events may have been missed due to the agent attaching after program
9509         execution begins; this function generates the missed events.
9510         <p/>
9511         Attempts to execute Java programming language code or
9512         JNI functions may be paused until this function returns -
9513         so neither should be called from the thread sending the event.
9514         This function returns only after the missed events have been
9515         sent, processed and have returned.
9516         The event may be sent on a different thread than the thread
9517         on which the event occurred.
9518         The callback for the event must be set with
9519         <functionlink id="SetEventCallbacks"></functionlink>
9520         and the event must be enabled with
9521         <functionlink id="SetEventNotificationMode"></functionlink>
9522         or the events will not occur.
9523         If the VM no longer has the information to generate some or
9524         all of the requested events, the events are simply not sent -
9525         no error is returned.
9526         <p/>
9527         Only the following events are supported:
9528         <ul>
9529           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
9530           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
9531         </ul>
9532       </description>
9533       <origin>new</origin>
9534       <capabilities>
9535         <capability id="can_generate_compiled_method_load_events"></capability>
9536       </capabilities>
9537       <parameters>
9538         <param id="event_type">
9539           <enum>jvmtiEvent</enum>
9540           <description>
9541             The type of event to generate.  Must be one of these:
9542             <ul>
9543               <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
9544               <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
9545             </ul>
9546           </description>
9547         </param>
9548       </parameters>
9549       <errors>
9550         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
9551           <paramlink id="event_type"/> is
9552           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9553           and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
9554           is <code>false</code>.
9555         </error>
9556         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9557           <paramlink id="event_type"/> is other than
9558           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
9559           or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
9560         </error>
9561       </errors>
9562     </function>
9563 
9564   </category>
9565 
9566     <category id="extension" label="Extension Mechanism">
9567 
9568       <intro>
9569         These functions
9570         allow a <jvmti/> implementation to provide functions and events
9571         beyond those defined in this specification.
9572         <p/>
9573         Both extension functions and extension events have parameters
9574         each of which has a 'type' and 'kind' chosen from the following tables:
9575 
9576         <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
9577           <constant id="JVMTI_TYPE_JBYTE" num="101">
9578             Java programming language primitive type - <code>byte</code>.
9579             JNI type <code>jbyte</code>.
9580           </constant>
9581           <constant id="JVMTI_TYPE_JCHAR" num="102">
9582             Java programming language primitive type - <code>char</code>.
9583             JNI type <code>jchar</code>.
9584           </constant>
9585           <constant id="JVMTI_TYPE_JSHORT" num="103">
9586             Java programming language primitive type - <code>short</code>.
9587             JNI type <code>jshort</code>.
9588           </constant>
9589           <constant id="JVMTI_TYPE_JINT" num="104">
9590             Java programming language primitive type - <code>int</code>.
9591             JNI type <datalink id="jint"></datalink>.
9592           </constant>
9593           <constant id="JVMTI_TYPE_JLONG" num="105">
9594             Java programming language primitive type - <code>long</code>.
9595             JNI type <datalink id="jlong"></datalink>.
9596           </constant>
9597           <constant id="JVMTI_TYPE_JFLOAT" num="106">
9598             Java programming language primitive type - <code>float</code>.
9599             JNI type <datalink id="jfloat"></datalink>.
9600           </constant>
9601           <constant id="JVMTI_TYPE_JDOUBLE" num="107">
9602             Java programming language primitive type - <code>double</code>.
9603             JNI type <datalink id="jdouble"></datalink>.
9604           </constant>
9605           <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
9606             Java programming language primitive type - <code>boolean</code>.
9607             JNI type <datalink id="jboolean"></datalink>.
9608           </constant>
9609           <constant id="JVMTI_TYPE_JOBJECT" num="109">
9610             Java programming language object type - <code>java.lang.Object</code>.
9611             JNI type <datalink id="jobject"></datalink>.
9612             Returned values are JNI local references and must be managed.
9613           </constant>
9614           <constant id="JVMTI_TYPE_JTHREAD" num="110">
9615             Java programming language object type - <code>java.lang.Thread</code>.
9616             <jvmti/> type <datalink id="jthread"></datalink>.
9617             Returned values are JNI local references and must be managed.
9618           </constant>
9619           <constant id="JVMTI_TYPE_JCLASS" num="111">
9620             Java programming language object type - <code>java.lang.Class</code>.
9621             JNI type <datalink id="jclass"></datalink>.
9622             Returned values are JNI local references and must be managed.
9623           </constant>
9624           <constant id="JVMTI_TYPE_JVALUE" num="112">
9625             Union of all Java programming language primitive and object types -
9626             JNI type <datalink id="jvalue"></datalink>.
9627             Returned values which represent object types are JNI local references and must be managed.
9628           </constant>
9629           <constant id="JVMTI_TYPE_JFIELDID" num="113">
9630             Java programming language field identifier -
9631             JNI type <datalink id="jfieldID"></datalink>.
9632           </constant>
9633           <constant id="JVMTI_TYPE_JMETHODID" num="114">
9634             Java programming language method identifier -
9635             JNI type <datalink id="jmethodID"></datalink>.
9636           </constant>
9637           <constant id="JVMTI_TYPE_CCHAR" num="115">
9638             C programming language type - <code>char</code>.
9639           </constant>
9640           <constant id="JVMTI_TYPE_CVOID" num="116">
9641             C programming language type - <code>void</code>.
9642           </constant>
9643           <constant id="JVMTI_TYPE_JNIENV" num="117">
9644             JNI environment - <code>JNIEnv</code>.
9645             Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
9646           </constant>
9647         </constants>
9648 
9649         <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
9650           <constant id="JVMTI_KIND_IN" num="91">
9651             Ingoing argument - <code>foo</code>.
9652           </constant>
9653           <constant id="JVMTI_KIND_IN_PTR" num="92">
9654             Ingoing pointer argument - <code>const foo*</code>.
9655           </constant>
9656           <constant id="JVMTI_KIND_IN_BUF" num="93">
9657             Ingoing array argument - <code>const foo*</code>.
9658           </constant>
9659           <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
9660             Outgoing allocated array argument -  <code>foo**</code>.
9661             Free with <code>Deallocate</code>.
9662           </constant>
9663           <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
9664             Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
9665             Free with <code>Deallocate</code>.
9666           </constant>
9667           <constant id="JVMTI_KIND_OUT" num="96">
9668             Outgoing argument - <code>foo*</code>.
9669           </constant>
9670           <constant id="JVMTI_KIND_OUT_BUF" num="97">
9671             Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
9672             Do not <code>Deallocate</code>.
9673           </constant>
9674         </constants>
9675 
9676       </intro>
9677 
9678       <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
9679         <field id="name">
9680           <allocfieldbuf><char/></allocfieldbuf>
9681             <description>
9682               The parameter name, encoded as a
9683               <internallink id="mUTF">modified UTF-8</internallink> string
9684             </description>
9685         </field>
9686         <field id="kind">
9687           <enum>jvmtiParamKind</enum>
9688           <description>
9689             The kind of the parameter - type modifiers
9690           </description>
9691         </field>
9692         <field id="base_type">
9693           <enum>jvmtiParamTypes</enum>
9694           <description>
9695             The base type of the parameter -  modified by <code>kind</code>
9696           </description>
9697         </field>
9698         <field id="null_ok">
9699           <jboolean/>
9700             <description>
9701               Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
9702             </description>
9703         </field>
9704       </typedef>
9705 
9706       <callback id="jvmtiExtensionFunction">
9707         <enum>jvmtiError</enum>
9708           <synopsis>Extension Function</synopsis>
9709         <description>
9710           This is the implementation-specific extension function.
9711         </description>
9712         <parameters>
9713           <param id="jvmti_env">
9714             <outptr>
9715               <struct>jvmtiEnv</struct>
9716             </outptr>
9717             <description>
9718               The <jvmti/> environment is the only fixed parameter for extension functions.
9719             </description>
9720           </param>
9721           <param id="...">
9722             <varargs/>
9723               <description>
9724                 The extension function-specific parameters
9725               </description>
9726           </param>
9727         </parameters>
9728       </callback>
9729 
9730       <function id="GetExtensionFunctions" phase="onload" num="124">
9731         <synopsis>Get Extension Functions</synopsis>
9732 
9733         <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
9734           <field id="func">
9735             <ptrtype>
9736               <struct>jvmtiExtensionFunction</struct>
9737             </ptrtype>
9738             <description>
9739               The actual function to call
9740             </description>
9741           </field>
9742           <field id="id">
9743             <allocfieldbuf><char/></allocfieldbuf>
9744               <description>
9745                 The identifier for the extension function, encoded as a
9746                 <internallink id="mUTF">modified UTF-8</internallink> string.
9747                 Uses package name conventions.
9748                 For example, <code>com.sun.hotspot.bar</code>
9749               </description>
9750           </field>
9751           <field id="short_description">
9752             <allocfieldbuf><char/></allocfieldbuf>
9753               <description>
9754                 A one sentence description of the function, encoded as a
9755                 <internallink id="mUTF">modified UTF-8</internallink> string.
9756               </description>
9757           </field>
9758           <field id="param_count">
9759             <jint/>
9760               <description>
9761                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9762               </description>
9763           </field>
9764           <field id="params">
9765             <allocfieldbuf outcount="param_count">
9766               <struct>jvmtiParamInfo</struct>
9767             </allocfieldbuf>
9768             <description>
9769               Array of
9770               <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9771               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9772             </description>
9773           </field>
9774           <field id="error_count">
9775             <jint/>
9776               <description>
9777                 The number of possible error returns (excluding universal errors)
9778               </description>
9779           </field>
9780           <field id="errors">
9781             <allocfieldbuf outcount="error_count">
9782               <enum>jvmtiError</enum>
9783             </allocfieldbuf>
9784             <description>
9785               Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
9786               possible errors
9787             </description>
9788           </field>
9789         </typedef>
9790 
9791         <description>
9792           Returns the set of extension functions.
9793         </description>
9794         <origin>new</origin>
9795         <capabilities>
9796         </capabilities>
9797         <parameters>
9798           <param id="extension_count_ptr">
9799             <outptr><jint/></outptr>
9800               <description>
9801                 On return, points to the number of extension functions
9802               </description>
9803           </param>
9804           <param id="extensions">
9805             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
9806             <description>
9807               Returns an array of extension function info, one per function
9808             </description>
9809           </param>
9810         </parameters>
9811         <errors>
9812         </errors>
9813       </function>
9814 
9815       <function id="GetExtensionEvents" phase="onload" num="125">
9816         <synopsis>Get Extension Events</synopsis>
9817 
9818         <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
9819           <field id="extension_event_index">
9820             <jint/>
9821             <description>
9822               The identifying index of the event
9823             </description>
9824           </field>
9825           <field id="id">
9826             <allocfieldbuf><char/></allocfieldbuf>
9827               <description>
9828                 The identifier for the extension event, encoded as a
9829                 <internallink id="mUTF">modified UTF-8</internallink> string.
9830                 Uses package name conventions.
9831                 For example, <code>com.sun.hotspot.bar</code>
9832               </description>
9833           </field>
9834           <field id="short_description">
9835             <allocfieldbuf><char/></allocfieldbuf>
9836               <description>
9837                 A one sentence description of the event, encoded as a
9838                 <internallink id="mUTF">modified UTF-8</internallink> string.
9839               </description>
9840           </field>
9841           <field id="param_count">
9842             <jint/>
9843               <description>
9844                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
9845               </description>
9846           </field>
9847           <field id="params">
9848             <allocfieldbuf outcount="param_count">
9849               <struct>jvmtiParamInfo</struct>
9850             </allocfieldbuf>
9851             <description>
9852               Array of
9853               <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
9854               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
9855             </description>
9856           </field>
9857         </typedef>
9858 
9859         <description>
9860           Returns the set of extension events.
9861         </description>
9862         <origin>new</origin>
9863         <capabilities>
9864         </capabilities>
9865         <parameters>
9866           <param id="extension_count_ptr">
9867             <outptr><jint/></outptr>
9868               <description>
9869                 On return, points to the number of extension events
9870               </description>
9871           </param>
9872           <param id="extensions">
9873             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
9874             <description>
9875               Returns an array of extension event info, one per event
9876             </description>
9877           </param>
9878         </parameters>
9879         <errors>
9880         </errors>
9881       </function>
9882 
9883       <callback id="jvmtiExtensionEvent">
9884         <void/>
9885           <synopsis>Extension Event</synopsis>
9886         <description>
9887           This is the implementation-specific event.
9888           The event handler is set with
9889           <functionlink id="SetExtensionEventCallback"/>.
9890           <p/>
9891           Event handlers for extension events must be declared varargs to match this definition.
9892           Failure to do so could result in calling convention mismatch and undefined behavior
9893           on some platforms.
9894           <p/>
9895           For example, if the <code>jvmtiParamInfo</code>
9896           returned by <functionlink id="GetExtensionEvents"/> indicates that
9897           there is a <code>jint</code> parameter, the event handler should be
9898           declared:
9899 <example>
9900     void JNICALL myHandler(jvmtiEnv* jvmti_env, jint myInt, ...)
9901 </example>
9902           Note the terminal "<code>...</code>" which indicates varargs.
9903         </description>
9904         <parameters>
9905           <param id="jvmti_env">
9906             <outptr>
9907               <struct>jvmtiEnv</struct>
9908             </outptr>
9909             <description>
9910               The <jvmti/> environment is the only fixed parameter for extension events.
9911             </description>
9912           </param>
9913           <param id="...">
9914             <varargs/>
9915               <description>
9916                 The extension event-specific parameters
9917               </description>
9918           </param>
9919         </parameters>
9920       </callback>
9921 
9922       <function id="SetExtensionEventCallback" phase="onload" num="126">
9923         <synopsis>Set Extension Event Callback</synopsis>
9924 
9925         <description>
9926           Sets the callback function for an extension event and
9927           enables the event. Or, if the callback is <code>NULL</code>, disables
9928           the event.  Note that unlike standard events, setting
9929           the callback and enabling the event are a single operation.
9930         </description>
9931         <origin>new</origin>
9932         <capabilities>
9933         </capabilities>
9934         <parameters>
9935           <param id="extension_event_index">
9936             <jint/>
9937               <description>
9938                 Identifies which callback to set.
9939                 This index is the
9940                 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
9941                 field of
9942                 <datalink id="jvmtiExtensionEventInfo"/>.
9943               </description>
9944           </param>
9945           <param id="callback">
9946             <ptrtype>
9947               <struct>jvmtiExtensionEvent</struct>
9948               <nullok>disable the event</nullok>
9949             </ptrtype>
9950             <description>
9951               If <code>callback</code> is non-<code>NULL</code>,
9952               set <code>callback</code> to be the event callback function
9953               and enable the event.
9954             </description>
9955           </param>
9956         </parameters>
9957         <errors>
9958         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
9959             <paramlink id="extension_event_index"/> is not an
9960             <fieldlink id="extension_event_index"
9961                        struct="jvmtiExtensionEventInfo"/>
9962             returned by
9963             <functionlink id="GetExtensionEvents"/>
9964         </error>
9965         </errors>
9966       </function>
9967 
9968     </category>
9969 
9970   <category id="capability" label="Capability">
9971 
9972     <intro>
9973       The capabilities functions allow you to change the
9974       functionality available to <jvmti/>--that is,
9975       which <jvmti/>
9976       functions can be called, what events can be generated,
9977       and what functionality these events and functions can
9978       provide.
9979       <p/>
9980         The "Capabilities" section of each function and event describe which
9981         capabilities, if any, they are associated with. "Required Functionality"
9982         means it is available for use and no capabilities must be added to use it.
9983         "Optional Functionality" means the agent must possess the capability
9984         before it can be used.
9985         To possess a capability, the agent must
9986         <functionlink id="AddCapabilities">add the capability</functionlink>.
9987         "Optional Features" describe capabilities which,
9988         if added, extend the feature set.
9989         <p/>
9990         The potentially available capabilities of each <jvmti/> implementation are different.
9991         Depending on the implementation, a capability:
9992         <ul>
9993           <li>may never be added</li>
9994           <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
9995           <li>may be added only during the <code>OnLoad</code> phase</li>
9996           <li>may be possessed by only one environment at a time</li>
9997           <li>may be possessed by only one environment at a time,
9998               and only during the <code>OnLoad</code> phase</li>
9999           <li>and so on ...</li>
10000         </ul>
10001       Frequently, the addition of a capability may incur a cost in execution speed, start up
10002       time, and/or memory footprint.  Note that the overhead of using a capability
10003       is completely different than the overhead of possessing a capability.
10004       Take single stepping as an example. When single stepping is on (that
10005       is, when the event is enabled and thus actively sending events)
10006       the overhead of sending and processing an event
10007       on each instruction is huge in any implementation.
10008       However, the overhead of possessing the capability may be small or large,
10009       depending on the implementation.  Also, when and if a capability is potentially
10010       available depends on the implementation.  Some examples:
10011       <ul>
10012         <li>One VM might perform all execution by compiling bytecodes into
10013           native code and be unable to generate single step instructions.
10014           In this implementation the capability can not be added.</li>
10015         <li>Another VM may be able to switch execution to a single stepping
10016           interpreter at any time.  In this implementation, having the capability has no
10017           overhead and could be added at any time.</li>
10018         <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
10019           execution engine at start up, but be unable to switch between them.
10020           In this implementation the capability would need to be added
10021           during the <code>OnLoad</code> phase (before bytecode
10022           execution begins) and would have a large impact on execution speed
10023           even if single stepping was never used.</li>
10024         <li>Still another VM might be able to add an "is single stepping on" check
10025           into compiled bytecodes or a generated interpreter.  Again in this implementation
10026           the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
10027           and branch on each instruction) would be considerably less.</li>
10028       </ul>
10029       <p/>
10030       Each <jvmti/> <internallink id="environments">environment</internallink>
10031       has its own set of capabilities.
10032       Initially, that set is empty.
10033       Any desired capability must be added.
10034       If possible, capabilities should be added during the <code>OnLoad</code> phase.  For most
10035       virtual machines certain capabilities require special set up for
10036       the virtual machine and this set up must happen
10037       during the <code>OnLoad</code> phase, before the virtual machine begins execution.
10038       Once a capability is added, it can
10039       only be removed if explicitly relinquished by the environment.
10040       <p/>
10041       The agent can,
10042       <functionlink id="GetPotentialCapabilities">determine what
10043         capabilities this VM can potentially provide</functionlink>,
10044       <functionlink id="AddCapabilities">add the capabilities
10045         to be used</functionlink>,
10046       <functionlink id="RelinquishCapabilities">release capabilities
10047         which are no longer needed</functionlink>, and
10048       <functionlink id="GetCapabilities">examine the currently available
10049         capabilities</functionlink>.
10050     </intro>
10051 
10052     <intro id="capabilityExamples" label="Capability Examples">
10053       For example, a freshly started agent (in the <code>OnLoad</code> function)
10054       wants to enable all possible capabilities.
10055       Note that, in general, this is not advisable as the agent may suffer
10056       a performance penalty for functionality it is not using.
10057       The code might look like this in C:
10058       <example>
10059         jvmtiCapabilities capa;
10060         jvmtiError err;
10061 
10062         err = (*jvmti)-&gt;GetPotentialCapabilities(jvmti, &amp;capa);
10063         if (err == JVMTI_ERROR_NONE) {
10064            err = (*jvmti)-&gt;AddCapabilities(jvmti, &amp;capa);
10065       </example>
10066       For example, if an  agent wants to check if it can get
10067       the bytecodes of a method (that is, it wants to check
10068       if it previously added this capability and has not
10069       relinquished it), the code might
10070       look like this in C:
10071       <example>
10072         jvmtiCapabilities capa;
10073         jvmtiError err;
10074 
10075         err = (*jvmti)-&gt;GetCapabilities(jvmti, &amp;capa);
10076         if (err == JVMTI_ERROR_NONE) {
10077            if (capa.can_get_bytecodes) { ... } }
10078       </example>
10079     </intro>
10080 
10081     <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
10082       <description>
10083         The functions in this category use this capabilities structure
10084         which contains boolean flags corresponding to each capability:
10085       </description>
10086       <capabilityfield id="can_tag_objects">
10087         <description>
10088           Can set and get tags, as described in the
10089           <internallink id="Heap">Heap category</internallink>.
10090         </description>
10091       </capabilityfield>
10092       <capabilityfield id="can_generate_field_modification_events">
10093         <description>
10094           Can set watchpoints on field modification -
10095           <functionlink id="SetFieldModificationWatch"></functionlink>
10096         </description>
10097       </capabilityfield>
10098       <capabilityfield id="can_generate_field_access_events">
10099         <description>
10100           Can set watchpoints on field access -
10101           <functionlink id="SetFieldAccessWatch"></functionlink>
10102         </description>
10103       </capabilityfield>
10104       <capabilityfield id="can_get_bytecodes">
10105         <description>
10106           Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
10107         </description>
10108       </capabilityfield>
10109       <capabilityfield id="can_get_synthetic_attribute">
10110         <description>
10111           Can test if a field or method is synthetic -
10112           <functionlink id="IsFieldSynthetic"></functionlink> and
10113           <functionlink id="IsMethodSynthetic"></functionlink>
10114         </description>
10115       </capabilityfield>
10116       <capabilityfield id="can_get_owned_monitor_info">
10117         <description>
10118           Can get information about ownership of monitors -
10119           <functionlink id="GetOwnedMonitorInfo"></functionlink>
10120         </description>
10121       </capabilityfield>
10122       <capabilityfield id="can_get_current_contended_monitor">
10123         <description>
10124           Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
10125         </description>
10126       </capabilityfield>
10127       <capabilityfield id="can_get_monitor_info">
10128       <description>
10129         Can <functionlink id="GetObjectMonitorUsage"></functionlink>
10130       </description>
10131       </capabilityfield>
10132       <capabilityfield id="can_pop_frame">
10133         <description>
10134           Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
10135         </description>
10136       </capabilityfield>
10137       <capabilityfield id="can_redefine_classes">
10138         <description>
10139           Can redefine classes with <functionlink id="RedefineClasses"/>.
10140         </description>
10141       </capabilityfield>
10142       <capabilityfield id="can_signal_thread">
10143         <description>
10144           Can send stop or interrupt to threads
10145         </description>
10146       </capabilityfield>
10147       <capabilityfield id="can_get_source_file_name">
10148         <description>
10149           Can get the source file name of a class
10150         </description>
10151       </capabilityfield>
10152       <capabilityfield id="can_get_line_numbers">
10153         <description>
10154           Can get the line number table of a method
10155         </description>
10156       </capabilityfield>
10157       <capabilityfield id="can_get_source_debug_extension">
10158         <description>
10159           Can get the source debug extension of a class
10160         </description>
10161       </capabilityfield>
10162       <capabilityfield id="can_access_local_variables">
10163         <description>
10164           Can set and get local variables
10165         </description>
10166       </capabilityfield>
10167       <capabilityfield id="can_maintain_original_method_order">
10168         <description>
10169           Can return methods in the order they occur in the class file
10170         </description>
10171       </capabilityfield>
10172       <capabilityfield id="can_generate_single_step_events">
10173         <description>
10174           Can get <eventlink id="SingleStep">single step</eventlink> events
10175         </description>
10176       </capabilityfield>
10177       <capabilityfield id="can_generate_exception_events">
10178         <description>
10179           Can get <eventlink id="Exception">exception thrown</eventlink> and
10180             <eventlink id="ExceptionCatch">exception catch</eventlink> events
10181         </description>
10182       </capabilityfield>
10183       <capabilityfield id="can_generate_frame_pop_events">
10184         <description>
10185           Can <functionlink id="NotifyFramePop">set</functionlink> and thus get
10186             <eventlink id="FramePop"></eventlink> events
10187         </description>
10188       </capabilityfield>
10189       <capabilityfield id="can_generate_breakpoint_events">
10190         <description>
10191           Can <functionlink id="SetBreakpoint">set</functionlink> and thus get
10192             <eventlink id="Breakpoint"></eventlink> events
10193         </description>
10194       </capabilityfield>
10195       <capabilityfield id="can_suspend">
10196         <description>
10197           Can suspend and resume threads
10198         </description>
10199       </capabilityfield>
10200       <capabilityfield id="can_redefine_any_class">
10201         <description>
10202           <functionlink id="RedefineClasses"/> can be called on any modifiable class.
10203           See <functionlink id="IsModifiableClass"/>.
10204           (<fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
10205           must also be set)
10206         </description>
10207       </capabilityfield>
10208       <capabilityfield id="can_get_current_thread_cpu_time">
10209         <description>
10210           Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
10211           current thread CPU time
10212         </description>
10213       </capabilityfield>
10214       <capabilityfield id="can_get_thread_cpu_time">
10215         <description>
10216           Can <functionlink id="GetThreadCpuTime">get</functionlink>
10217           thread CPU time
10218         </description>
10219       </capabilityfield>
10220       <capabilityfield id="can_generate_method_entry_events"
10221                        disp1="can_generate" disp2="_method_entry_events"
10222                        >
10223         <description>
10224           Can generate method entry events on entering a method
10225         </description>
10226       </capabilityfield>
10227       <capabilityfield id="can_generate_method_exit_events"
10228                        disp1="can_generate" disp2="_method_exit_events"
10229                        >
10230         <description>
10231           Can generate method exit events on leaving a method
10232         </description>
10233       </capabilityfield>
10234       <capabilityfield id="can_generate_all_class_hook_events"
10235                        disp1="can_generate" disp2="_all_class_hook_events"
10236                        >
10237         <description>
10238           Can generate ClassFileLoadHook events for every loaded class.
10239         </description>
10240       </capabilityfield>
10241       <capabilityfield id="can_generate_compiled_method_load_events"
10242                        disp1="can_generate" disp2="_compiled_method_load_events"
10243                        >
10244         <description>
10245           Can generate events when a method is compiled or unloaded
10246         </description>
10247       </capabilityfield>
10248       <capabilityfield id="can_generate_monitor_events"
10249                        disp1="can_generate" disp2="_monitor_events"
10250                        >
10251         <description>
10252           Can generate events on monitor activity
10253         </description>
10254       </capabilityfield>
10255       <capabilityfield id="can_generate_vm_object_alloc_events"
10256                        disp1="can_generate" disp2="_vm_object_alloc_events"
10257                        >
10258         <description>
10259           Can generate events on VM allocation of an object
10260         </description>
10261       </capabilityfield>
10262       <capabilityfield id="can_generate_native_method_bind_events"
10263                        disp1="can_generate" disp2="_native_method_bind_events"
10264                        >
10265         <description>
10266           Can generate events when a native method is bound to its
10267           implementation
10268         </description>
10269       </capabilityfield>
10270       <capabilityfield id="can_generate_garbage_collection_events"
10271                        disp1="can_generate" disp2="_garbage_collection_events"
10272                        >
10273         <description>
10274           Can generate events when garbage collection begins or ends
10275         </description>
10276       </capabilityfield>
10277       <capabilityfield id="can_generate_object_free_events"
10278                        disp1="can_generate" disp2="_object_free_events"
10279                        >
10280         <description>
10281           Can generate events when the garbage collector frees an object
10282         </description>
10283       </capabilityfield>
10284       <capabilityfield id="can_force_early_return" since="1.1">
10285         <description>
10286           Can return early from a method, as described in the
10287           <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
10288         </description>
10289       </capabilityfield>
10290       <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
10291         <description>
10292           Can get information about owned monitors with stack depth -
10293           <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
10294         </description>
10295       </capabilityfield>
10296       <capabilityfield id="can_get_constant_pool" since="1.1">
10297         <description>
10298           Can get the constant pool of a class -
10299           <functionlink id="GetConstantPool"></functionlink>
10300         </description>
10301       </capabilityfield>
10302       <capabilityfield id="can_set_native_method_prefix" since="1.1">
10303         <description>
10304           Can set prefix to be applied when native method cannot be resolved -
10305           <functionlink id="SetNativeMethodPrefix"/> and
10306           <functionlink id="SetNativeMethodPrefixes"/>
10307         </description>
10308       </capabilityfield>
10309       <capabilityfield id="can_retransform_classes" since="1.1">
10310         <description>
10311           Can retransform classes with <functionlink id="RetransformClasses"/>.
10312           In addition to the restrictions imposed by the specific
10313           implementation on this capability (see the
10314           <internallink id="capability">Capability</internallink> section),
10315           this capability must be set before the
10316           <eventlink id="ClassFileLoadHook"/> event is enabled for the
10317           first time in this environment.
10318           An environment that possesses this capability at the time that
10319           <code>ClassFileLoadHook</code> is enabled for the first time is
10320           said to be <i>retransformation capable</i>.
10321           An environment that does not possess this capability at the time that
10322           <code>ClassFileLoadHook</code> is enabled for the first time is
10323           said to be <i>retransformation incapable</i>.
10324         </description>
10325       </capabilityfield>
10326       <capabilityfield id="can_retransform_any_class" since="1.1">
10327         <description>
10328           <functionlink id="RetransformClasses"/> can be called on any modifiable class.
10329           See <functionlink id="IsModifiableClass"/>.
10330           (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
10331           must also be set)
10332         </description>
10333       </capabilityfield>
10334       <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
10335         <description>
10336           Can generate events when the VM is unable to allocate memory from
10337           the <tm>Java</tm> platform heap.
10338           See <eventlink id="ResourceExhausted"/>.
10339         </description>
10340       </capabilityfield>
10341       <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
10342         <description>
10343           Can generate events when the VM is unable to create a thread.
10344           See <eventlink id="ResourceExhausted"/>.
10345         </description>
10346       </capabilityfield>
10347       <capabilityfield id="can_generate_early_vmstart" since="9">
10348         <description>
10349           Can generate the <code>VMStart</code> event early.
10350           See <eventlink id="VMStart"/>.
10351         </description>
10352       </capabilityfield>
10353       <capabilityfield id="can_generate_early_class_hook_events" since="9">
10354         <description>
10355           Can generate the <eventlink id="ClassFileLoadHook"/> events
10356           in the primordial phase. If this capability and
10357           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10358           <code>can_generate_all_class_hook_events</code></internallink>
10359           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10360           can be posted for classes loaded in the primordial phase.
10361           See <eventlink id="ClassFileLoadHook"/>.
10362         </description>
10363       </capabilityfield>
10364       <capabilityfield id="can_generate_sampled_object_alloc_events" since="11">
10365         <description>
10366           Can generate sampled allocation events.
10367           If this capability is enabled then the heap sampling method
10368           <functionlink id="SetHeapSamplingInterval"></functionlink> can be
10369           called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
10370         </description>
10371       </capabilityfield>
10372     </capabilitiestypedef>
10373 
10374     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10375       <synopsis>Get Potential Capabilities</synopsis>
10376       <description>
10377         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10378         features that can potentially be possessed by this environment
10379         at this time.
10380         The returned capabilities differ from the complete set of capabilities
10381         implemented by the VM in two cases: another environment possesses
10382         capabilities that can only be possessed by one environment, or the
10383         current <functionlink id="GetPhase">phase</functionlink> is live,
10384         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10385         The <functionlink id="AddCapabilities"></functionlink> function
10386         may be used to set any or all or these capabilities.
10387         Currently possessed capabilities are included.
10388         <p/>
10389         Typically this function is used in the <code>OnLoad</code> function.
10390         Some virtual machines may allow a limited set of capabilities to be
10391         added in the live phase.
10392         In this case, the set of potentially available capabilities
10393         will likely differ from the <code>OnLoad</code> phase set.
10394         <p/>
10395         See the
10396         <internallink id="capabilityExamples">Capability Examples</internallink>.
10397       </description>
10398       <origin>new</origin>
10399       <capabilities>
10400       </capabilities>
10401       <parameters>
10402         <param id="capabilities_ptr">
10403           <outptr><struct>jvmtiCapabilities</struct></outptr>
10404           <description>
10405             On return, points to the <jvmti/> capabilities that may be added.
10406           </description>
10407         </param>
10408       </parameters>
10409       <errors>
10410       </errors>
10411     </function>
10412 
10413     <elide>
10414     <function id="EstimateCostOfCapabilities" phase="onload" num="141">
10415       <synopsis>Estimate Cost Of Capabilities</synopsis>
10416       <description>
10417         <issue>There is strong opposition to this function.  The concern is
10418           that it would be difficult or impossible to provide meaningful
10419           numbers, as the amount of impact is conditional on many factors
10420           that a single number could not represent.  There is doubt that
10421           conditional implementations would be used or are even a good idea.
10422           The thought is that release documentation for the implementation
10423           would be the best means of exposing this information.
10424           Unless new arguments are presented, I intend to remove this
10425           function in the next revision.
10426         </issue>
10427         <p/>
10428         Return via the <paramlink id="time_impact_ptr"></paramlink> and
10429         <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
10430         of adding the capabilities pointed to by
10431         <paramlink id="capabilities_ptr"></paramlink>.
10432         The returned estimates are in percentage of additional overhead, thus
10433         a time impact of 100 mean the application might run
10434         at half the speed.
10435         The estimates are very rough approximations and are not guaranteed.
10436         Note also, that the estimates are of the impact of having the
10437         capability available--when and if it is used the impact may be
10438         much greater.
10439         Estimates can be for a single capability or for a set of
10440         capabilities.  Note that the costs are not necessarily additive,
10441         adding support for one capability might make another available
10442         for free or conversely having two capabilities at once may
10443         have multiplicative impact.
10444         Estimates are relative to the current set of capabilities -
10445         that is, how much more impact given the currently possessed capabilities.
10446         <p/>
10447         Typically this function is used in the OnLoad function,
10448         some virtual machines may allow a limited set of capabilities to be
10449         added in the live phase.
10450         In this case, the set of potentially available capabilities
10451         will likely differ from the OnLoad phase set.
10452         <p/>
10453         See the
10454         <internallink id="capabilityExamples">Capability Examples</internallink>.
10455       </description>
10456       <origin>new</origin>
10457       <capabilities>
10458       </capabilities>
10459       <parameters>
10460         <param id="capabilities_ptr">
10461           <inptr><struct>jvmtiCapabilities</struct></inptr>
10462           <description>
10463             points to the <jvmti/> capabilities to evaluate.
10464           </description>
10465         </param>
10466         <param id="time_impact_ptr">
10467           <outptr><jint/></outptr>
10468           <description>
10469             On return, points to the estimated percentage increase in
10470             run time if this capability was added.
10471           </description>
10472         </param>
10473         <param id="space_impact_ptr">
10474           <outptr><jint/></outptr>
10475           <description>
10476             On return, points to the estimated percentage increase in
10477             memory space used if this capability was added.
10478           </description>
10479         </param>
10480       </parameters>
10481       <errors>
10482         <error id="JVMTI_ERROR_NOT_AVAILABLE">
10483           The desired capabilities are not even potentially available.
10484         </error>
10485       </errors>
10486     </function>
10487     </elide>
10488 
10489     <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
10490       <synopsis>Add Capabilities</synopsis>
10491       <description>
10492         Set new capabilities by adding the capabilities
10493         whose values are set to one (<code>1</code>) in
10494         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10495         All previous capabilities are retained.
10496         Typically this function is used in the <code>OnLoad</code> function.
10497         Some virtual machines may allow a limited set of capabilities to be
10498         added in the live phase.
10499         <p/>
10500         See the
10501         <internallink id="capabilityExamples">Capability Examples</internallink>.
10502       </description>
10503       <origin>new</origin>
10504       <capabilities>
10505       </capabilities>
10506       <parameters>
10507         <param id="capabilities_ptr">
10508           <inptr><struct>jvmtiCapabilities</struct></inptr>
10509           <description>
10510             Points to the <jvmti/> capabilities to add.
10511           </description>
10512         </param>
10513       </parameters>
10514       <errors>
10515         <error id="JVMTI_ERROR_NOT_AVAILABLE">
10516           The desired capabilities are not even potentially available.
10517         </error>
10518       </errors>
10519     </function>
10520 
10521 
10522     <function id="RelinquishCapabilities" phase="onload" num="143">
10523       <synopsis>Relinquish Capabilities</synopsis>
10524       <description>
10525         Relinquish the capabilities
10526         whose values are set to one (<code>1</code>) in
10527         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10528         Some implementations may allow only one environment to have a capability
10529         (see the <internallink id="capability">capability introduction</internallink>).
10530         This function releases capabilities
10531         so that they may be used by other agents.
10532         All other capabilities are retained.
10533         The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
10534         Attempting to relinquish a capability that the agent does not possess is not an error.
10535           <issue>
10536             It is possible for the agent to be actively using capabilities
10537             which are being relinquished.  For example, a thread is currently
10538             suspended and can_suspend is being relinquished or an event is currently
10539             enabled and can_generate_whatever is being relinquished.
10540             There are three possible ways we could spec this:
10541             <ul>
10542               <li>relinquish automatically releases them</li>
10543               <li>relinquish checks and returns some error code if held</li>
10544               <li>it is the agent's responsibility and it is not checked</li>
10545             </ul>
10546             One of these should be chosen.
10547           </issue>
10548       </description>
10549       <origin>new</origin>
10550       <capabilities>
10551       </capabilities>
10552       <parameters>
10553         <param id="capabilities_ptr">
10554           <inptr><struct>jvmtiCapabilities</struct></inptr>
10555           <description>
10556             Points to the <jvmti/> capabilities to relinquish.
10557           </description>
10558         </param>
10559       </parameters>
10560       <errors>
10561       </errors>
10562     </function>
10563 
10564 
10565 
10566     <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
10567       <synopsis>Get Capabilities</synopsis>
10568         <description>
10569           Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/>
10570           features which this environment currently possesses.
10571           Each possessed capability is indicated by a one (<code>1</code>) in the
10572           corresponding field of the <internallink id="jvmtiCapabilities">capabilities
10573           structure</internallink>.
10574           An environment does not possess a capability unless it has been successfully added with
10575           <functionlink id="AddCapabilities"/>.
10576           An environment only loses possession of a capability if it has been relinquished with
10577           <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
10578           of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
10579           have been made.
10580           <p/>
10581           See the
10582           <internallink id="capabilityExamples">Capability Examples</internallink>.
10583         </description>
10584       <origin>jvmdiClone</origin>
10585       <capabilities>
10586       </capabilities>
10587       <parameters>
10588         <param id="capabilities_ptr">
10589           <outptr><struct>jvmtiCapabilities</struct></outptr>
10590           <description>
10591             On return, points to the <jvmti/> capabilities.
10592           </description>
10593         </param>
10594       </parameters>
10595       <errors>
10596       </errors>
10597     </function>
10598 
10599   </category>
10600 
10601 
10602   <category id="timers" label="Timers">
10603 
10604       <intro>
10605         These functions provide timing information.
10606         The resolution at which the time is updated is not specified.
10607         They provides nanosecond precision, but not necessarily nanosecond accuracy.
10608         Details about the timers, such as their maximum values, can be accessed with
10609         the timer information functions.
10610       </intro>
10611 
10612       <typedef id="jvmtiTimerInfo" label="Timer Info">
10613         <description>
10614           The information function for each timer returns this data structure.
10615         </description>
10616         <field id="max_value">
10617           <jlong/>
10618             <description>
10619               The maximum value the timer can reach.
10620               After this value is reached the timer wraps back to zero.
10621               This is an unsigned value.  If tested or printed as a jlong (signed value)
10622               it may appear to be a negative number.
10623             </description>
10624         </field>
10625         <field id="may_skip_forward">
10626           <jboolean/>
10627           <description>
10628             If true, the timer can be externally adjusted and as a result skip forward.
10629             If false, the timer value will never increase faster than real time.
10630           </description>
10631         </field>
10632         <field id="may_skip_backward">
10633           <jboolean/>
10634           <description>
10635             If true, the timer can be externally adjusted and as a result skip backward.
10636             If false, the timer value will be monotonically increasing.
10637           </description>
10638         </field>
10639         <field id="kind">
10640           <enum>jvmtiTimerKind</enum>
10641           <description>
10642             The kind of timer.
10643             On a platform that does not distinguish between user and system time, <datalink
10644                  id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
10645             is returned.
10646           </description>
10647         </field>
10648         <field id="reserved1">
10649           <jlong/>
10650             <description>
10651               Reserved for future use.
10652             </description>
10653         </field>
10654         <field id="reserved2">
10655           <jlong/>
10656             <description>
10657               Reserved for future use.
10658             </description>
10659         </field>
10660       </typedef>
10661 
10662       <intro>
10663         Where the timer kind is --
10664 
10665         <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
10666           <constant id="JVMTI_TIMER_USER_CPU" num="30">
10667             CPU time that a thread is in user mode.
10668           </constant>
10669           <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
10670             CPU time that a thread is in user or system mode.
10671           </constant>
10672           <constant id="JVMTI_TIMER_ELAPSED" num="32">
10673             Elapsed time.
10674           </constant>
10675         </constants>
10676       </intro>
10677 
10678     <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe"  impl="innative notrace" phase="start" num="134">
10679       <synopsis>Get Current Thread CPU Timer Information</synopsis>
10680       <description>
10681         Get information about the
10682         <functionlink id="GetCurrentThreadCpuTime"/> timer.
10683         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10684         are filled in with details about the timer.
10685         This information is specific to the platform and the implementation of
10686         <functionlink id="GetCurrentThreadCpuTime"/> and thus
10687         does not vary by thread nor does it vary
10688         during a particular invocation of the VM.
10689         <p/>
10690         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10691         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10692         returned by <code>GetCurrentThreadCpuTimerInfo</code>
10693         and <functionlink id="GetThreadCpuTimerInfo"/>
10694         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10695       </description>
10696       <origin>new</origin>
10697       <capabilities>
10698         <required id="can_get_current_thread_cpu_time">
10699             Can get current thread CPU time.
10700         </required>
10701       </capabilities>
10702       <parameters>
10703         <param id="info_ptr">
10704           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10705           <description>
10706             On return, filled with information describing the time
10707             returned by <functionlink id="GetCurrentThreadCpuTime"/>.
10708           </description>
10709         </param>
10710       </parameters>
10711       <errors>
10712       </errors>
10713     </function>
10714 
10715     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10716       <synopsis>Get Current Thread CPU Time</synopsis>
10717       <description>
10718             Return the CPU time utilized by the current thread.
10719             <p/>
10720             Note that the <functionlink id="GetThreadCpuTime"/>
10721             function provides CPU time for any thread, including
10722             the current thread. <code>GetCurrentThreadCpuTime</code>
10723             exists to support platforms which cannot
10724             supply CPU time for threads other than the current
10725             thread or which have more accurate information for
10726             the current thread (see
10727             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10728             <functionlink id="GetThreadCpuTimerInfo"/>).
10729             On many platforms this call will be equivalent to:
10730 <example>
10731   GetThreadCpuTime(env, NULL, nanos_ptr)
10732 </example>
10733       </description>
10734       <origin>new</origin>
10735       <capabilities>
10736         <required id="can_get_current_thread_cpu_time">
10737             Can get current thread CPU time.
10738             <p/>
10739             If this capability is enabled after threads have started,
10740             the implementation may choose any time up
10741             to and including the time that the capability is enabled
10742             as the point where CPU time collection starts.
10743             <p/>
10744             This capability must be potentially available on any
10745             platform where
10746             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10747             is potentially available.
10748         </required>
10749       </capabilities>
10750       <parameters>
10751         <param id="nanos_ptr">
10752           <outptr><jlong/></outptr>
10753           <description>
10754             On return, points to the CPU time used by this thread
10755             in nanoseconds.
10756             This is an unsigned value.  If tested or printed as a jlong (signed value)
10757             it may appear to be a negative number.
10758           </description>
10759         </param>
10760       </parameters>
10761       <errors>
10762       </errors>
10763     </function>
10764 
10765     <function id="GetThreadCpuTimerInfo" num="136">
10766       <synopsis>Get Thread CPU Timer Information</synopsis>
10767       <description>
10768         Get information about the
10769         <functionlink id="GetThreadCpuTime"/> timer.
10770         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10771         are filled in with details about the timer.
10772         This information is specific to the platform and the implementation of
10773         <functionlink id="GetThreadCpuTime"/> and thus
10774         does not vary by thread nor does it vary
10775         during a particular invocation of the VM.
10776         <p/>
10777         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10778         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10779         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
10780         and <code>GetThreadCpuTimerInfo</code>
10781         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10782       </description>
10783       <origin>new</origin>
10784       <capabilities>
10785         <required id="can_get_thread_cpu_time">
10786             Can get thread CPU time.
10787         </required>
10788       </capabilities>
10789       <parameters>
10790         <param id="info_ptr">
10791           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10792           <description>
10793             On return, filled with information describing the time
10794             returned by <functionlink id="GetThreadCpuTime"/>.
10795           </description>
10796         </param>
10797       </parameters>
10798       <errors>
10799       </errors>
10800     </function>
10801 
10802     <function id="GetThreadCpuTime" num="137">
10803       <synopsis>Get Thread CPU Time</synopsis>
10804       <description>
10805           Return the CPU time utilized by the specified thread.
10806           <p/>
10807           Get information about this timer with
10808           <functionlink id="GetThreadCpuTimerInfo"/>.
10809       </description>
10810       <origin>new</origin>
10811       <capabilities>
10812         <required id="can_get_thread_cpu_time">
10813             Can get thread CPU time.
10814             <p/>
10815             If this capability is enabled after threads have started,
10816             the implementation may choose any time up
10817             to and including the time that the capability is enabled
10818             as the point where CPU time collection starts.
10819         </required>
10820       </capabilities>
10821       <parameters>
10822         <param id="thread">
10823           <jthread null="current"/>
10824             <description>
10825               The thread to query.
10826             </description>
10827         </param>
10828         <param id="nanos_ptr">
10829           <outptr><jlong/></outptr>
10830           <description>
10831             On return, points to the CPU time used by the specified thread
10832             in nanoseconds.
10833             This is an unsigned value.  If tested or printed as a jlong (signed value)
10834             it may appear to be a negative number.
10835           </description>
10836         </param>
10837       </parameters>
10838       <errors>
10839       </errors>
10840     </function>
10841 
10842     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
10843       <synopsis>Get Timer Information</synopsis>
10844       <description>
10845         Get information about the
10846         <functionlink id="GetTime"/> timer.
10847         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10848         are filled in with details about the timer.
10849         This information will not change during a particular invocation of the VM.
10850       </description>
10851       <origin>new</origin>
10852       <capabilities>
10853       </capabilities>
10854       <parameters>
10855         <param id="info_ptr">
10856           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10857           <description>
10858             On return, filled with information describing the time
10859             returned by <functionlink id="GetTime"/>.
10860           </description>
10861         </param>
10862       </parameters>
10863       <errors>
10864       </errors>
10865     </function>
10866 
10867     <function id="GetTime" phase="any" callbacksafe="safe" num="139">
10868       <synopsis>Get Time</synopsis>
10869       <description>
10870           Return the current value of the system timer, in nanoseconds.
10871           <p/>
10872           The value returned represents nanoseconds since some fixed but
10873           arbitrary time (perhaps in the future, so values may be
10874           negative).  This function provides nanosecond precision, but not
10875           necessarily nanosecond accuracy. No guarantees are made about
10876           how frequently values change.
10877           <p/>
10878           Get information about this timer with
10879           <functionlink id="GetTimerInfo"/>.
10880       </description>
10881       <origin>new</origin>
10882       <capabilities>
10883       </capabilities>
10884       <parameters>
10885         <param id="nanos_ptr">
10886           <outptr><jlong/></outptr>
10887           <description>
10888             On return, points to the time in nanoseconds.
10889             This is an unsigned value.  If tested or printed as a jlong (signed value)
10890             it may appear to be a negative number.
10891           </description>
10892         </param>
10893       </parameters>
10894       <errors>
10895       </errors>
10896     </function>
10897 
10898     <function id="GetAvailableProcessors" phase="any" num="144">
10899       <synopsis>Get Available Processors</synopsis>
10900       <description>
10901           Returns the number of processors available to the Java virtual machine.
10902           <p/>
10903           This value may change during a particular invocation of the virtual machine.
10904           Applications that are sensitive to the number of available processors should
10905           therefore occasionally poll this property.
10906       </description>
10907       <origin>new</origin>
10908       <capabilities>
10909       </capabilities>
10910       <parameters>
10911         <param id="processor_count_ptr">
10912           <outptr><jint/></outptr>
10913           <description>
10914             On return, points to the maximum number of processors available to the
10915             virtual machine; never smaller than one.
10916           </description>
10917         </param>
10918       </parameters>
10919       <errors>
10920       </errors>
10921     </function>
10922 
10923   </category>
10924 
10925 
10926   <category id="classLoaderSearch" label="Class Loader Search">
10927 
10928     <intro>
10929       These functions allow the agent to add to the locations that a class loader searches for a class.
10930       This is useful for installing instrumentation under the correct class loader.
10931     </intro>
10932 
10933     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
10934       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
10935       <description>
10936           This function can be used to cause instrumentation classes to be defined by the
10937           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
10938           After the bootstrap
10939           class loader unsuccessfully searches for a class, the specified platform-dependent
10940           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in
10941           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments,
10942           the segments will be searched in the order that this function was called.
10943           <p/>
10944           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
10945           search path segment to be searched after the bootstrap class loader unsuccessfully searches
10946           for a class. The segment is typically a directory or JAR file.
10947           <p/>
10948           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
10949           path to a <externallink id="jar/jar.html">
10950           JAR file</externallink>. The agent should take care that the JAR file does not
10951           contain any classes or resources other than those to be defined by the bootstrap
10952           class loader for the purposes of instrumentation.
10953           <p/>
10954           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
10955           reference that the Java virtual machine has previously unsuccessfully attempted
10956           to resolve always fails with the same error that was thrown as a result of the
10957           initial resolution attempt. Consequently, if the JAR file contains an entry
10958           that corresponds to a class for which the Java virtual machine has
10959           unsuccessfully attempted to resolve a reference, then subsequent attempts to
10960           resolve that reference will fail with the same error as the initial attempt.
10961       </description>
10962       <origin>new</origin>
10963       <capabilities>
10964       </capabilities>
10965       <parameters>
10966         <param id="segment">
10967           <inbuf><char/></inbuf>
10968           <description>
10969             The platform-dependent search path segment, encoded as a
10970             <internallink id="mUTF">modified UTF-8</internallink> string.
10971           </description>
10972         </param>
10973       </parameters>
10974       <errors>
10975         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
10976           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
10977            existing JAR file is an invalid path.
10978         </error>
10979       </errors>
10980     </function>
10981 
10982     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
10983       <synopsis>Add To System Class Loader Search</synopsis>
10984       <description>
10985           This function can be used to cause instrumentation classes to be
10986           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
10987           After the class loader unsuccessfully searches for a class, the specified platform-dependent search
10988           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the
10989           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the
10990           segments will be searched in the order that this function was called.
10991           <p/>
10992           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
10993           search path segment to be searched after the system class loader unsuccessfully searches
10994           for a class. The segment is typically a directory or JAR file.
10995           <p/>
10996           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a
10997           <externallink id="jar/jar.html">JAR file</externallink> to be
10998           searched after the system class loader unsuccessfully searches for a class. The agent should
10999           take care that the JAR file does not contain any classes or resources other than those to be
11000           defined by the system class loader for the purposes of instrumentation.
11001           <p/>
11002           In the live phase the system class loader supports adding a JAR file to be searched if
11003           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code>
11004           which takes a single parameter of type <code>java.lang.String</code>. The method is not required
11005           to have <code>public</code> access.
11006           <p/>
11007           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
11008           reference that the Java virtual machine has previously unsuccessfully attempted
11009           to resolve always fails with the same error that was thrown as a result of the
11010           initial resolution attempt. Consequently, if the JAR file contains an entry
11011           that corresponds to a class for which the Java virtual machine has
11012           unsuccessfully attempted to resolve a reference, then subsequent attempts to
11013           resolve that reference will fail with the same error as the initial attempt.
11014       </description>
11015       <origin>new</origin>
11016       <capabilities>
11017       </capabilities>
11018       <parameters>
11019         <param id="segment">
11020           <inbuf><char/></inbuf>
11021           <description>
11022             The platform-dependent search path segment, encoded as a
11023             <internallink id="mUTF">modified UTF-8</internallink> string.
11024           </description>
11025         </param>
11026       </parameters>
11027       <errors>
11028         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11029           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
11030            existing JAR file is an invalid path.
11031         </error>
11032         <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
11033           Operation not supported by the system class loader.
11034         </error>
11035       </errors>
11036     </function>
11037 
11038   </category>
11039 
11040 
11041   <category id="props" label="System Properties">
11042 
11043     <intro>
11044       These functions get and set system properties.
11045     </intro>
11046 
11047     <function id="GetSystemProperties" phase="onload" num="130">
11048       <synopsis>Get System Properties</synopsis>
11049       <description>
11050         The list of VM system property keys which may be used with
11051         <functionlink id="GetSystemProperty"/> is returned.
11052         It is strongly recommended that virtual machines provide the
11053         following property keys:
11054         <ul>
11055           <li><code>java.vm.vendor</code></li>
11056           <li><code>java.vm.version</code></li>
11057           <li><code>java.vm.name</code></li>
11058           <li><code>java.vm.info</code></li>
11059           <li><code>java.library.path</code></li>
11060           <li><code>java.class.path</code></li>
11061         </ul>
11062         Provides access to system properties defined by and used
11063         by the VM.
11064         Properties set on the command-line are included.
11065         This allows getting and setting of these properties
11066         before the VM even begins executing bytecodes.
11067         Since this is a VM view of system properties, the set of available
11068         properties will usually be different than that
11069         in <code>java.lang.System.getProperties</code>.
11070         JNI method invocation may be used to access
11071         <code>java.lang.System.getProperties</code>.
11072         <p/>
11073         The set of properties may grow during execution.
11074       </description>
11075       <origin>new</origin>
11076       <capabilities>
11077       </capabilities>
11078       <parameters>
11079         <param id="count_ptr">
11080           <outptr><jint/></outptr>
11081           <description>
11082             On return, points to the number of property keys returned.
11083           </description>
11084         </param>
11085         <param id="property_ptr">
11086           <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
11087           <description>
11088             On return, points to an array of property keys, encoded as
11089             <internallink id="mUTF">modified UTF-8</internallink> strings.
11090           </description>
11091         </param>
11092       </parameters>
11093       <errors>
11094       </errors>
11095     </function>
11096 
11097     <function id="GetSystemProperty" phase="onload" num="131">
11098       <synopsis>Get System Property</synopsis>
11099       <description>
11100         Return a VM system property value given the property key.
11101         <p/>
11102         The function <functionlink id="GetSystemProperties"/>
11103         returns the set of property keys which may be used.
11104         The properties which can be retrieved may grow during
11105         execution.
11106         <p/>
11107         Since this is a VM view of system properties, the values
11108         of properties may differ from that returned by
11109         <code>java.lang.System.getProperty(String)</code>.
11110         A typical VM might copy the values of the VM system
11111         properties into the <code>Properties</code> held by
11112         <code>java.lang.System</code> during the initialization
11113         of that class. Thereafter any changes to the VM system
11114         properties (with <functionlink id="SetSystemProperty"/>)
11115         or the <code>java.lang.System</code> system properties
11116         (with <code>java.lang.System.setProperty(String,String)</code>)
11117         would cause the values to diverge.
11118         JNI method invocation may be used to access
11119         <code>java.lang.System.getProperty(String)</code>.
11120       </description>
11121       <origin>new</origin>
11122       <capabilities>
11123       </capabilities>
11124       <parameters>
11125         <param id="property">
11126           <inbuf><char/></inbuf>
11127           <description>
11128             The key of the property to retrieve, encoded as a
11129             <internallink id="mUTF">modified UTF-8</internallink> string.
11130           </description>
11131         </param>
11132         <param id="value_ptr">
11133           <allocbuf><char/></allocbuf>
11134           <description>
11135             On return, points to the property value, encoded as a
11136             <internallink id="mUTF">modified UTF-8</internallink> string.
11137           </description>
11138         </param>
11139       </parameters>
11140       <errors>
11141         <error id="JVMTI_ERROR_NOT_AVAILABLE">
11142           This property is not available.
11143           Use <functionlink id="GetSystemProperties"/> to find available properties.
11144         </error>
11145       </errors>
11146     </function>
11147 
11148     <function id="SetSystemProperty" phase="onloadOnly" num="132">
11149       <synopsis>Set System Property</synopsis>
11150       <description>
11151         Set a VM system property value.
11152         <p/>
11153         The function <functionlink id="GetSystemProperties"/>
11154         returns the set of property keys, some of these may be settable.
11155         See <functionlink id="GetSystemProperty"/>.
11156       </description>
11157       <origin>new</origin>
11158       <capabilities>
11159       </capabilities>
11160       <parameters>
11161         <param id="property">
11162           <inbuf><char/></inbuf>
11163           <description>
11164             The key of the property, encoded as a
11165             <internallink id="mUTF">modified UTF-8</internallink> string.
11166           </description>
11167         </param>
11168         <param id="value_ptr">
11169           <inbuf>
11170             <char/>
11171             <nullok>
11172               do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
11173               if the property is not writeable
11174             </nullok>
11175           </inbuf>
11176           <description>
11177             The property value to set, encoded as a
11178             <internallink id="mUTF">modified UTF-8</internallink> string.
11179           </description>
11180         </param>
11181       </parameters>
11182       <errors>
11183         <error id="JVMTI_ERROR_NOT_AVAILABLE">
11184           This property is not available or is not writeable.
11185         </error>
11186       </errors>
11187     </function>
11188 
11189   </category>
11190 
11191   <category id="general" label="General">
11192 
11193     <intro>
11194     </intro>
11195 
11196     <function id="GetPhase" jkernel="yes" phase="any" num="133">
11197       <synopsis>Get Phase</synopsis>
11198       <description>
11199           Return the current phase of VM execution.
11200           The phases proceed in sequence:
11201           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
11202             <constant id="JVMTI_PHASE_ONLOAD" num="1">
11203               <code>OnLoad</code> phase: while in the
11204               <internallink id="onload"><code>Agent_OnLoad</code></internallink>
11205               or, for statically linked agents, the <internallink id="onload">
11206               <code>Agent_OnLoad_&lt;agent-lib-name&gt;
11207               </code></internallink> function.
11208             </constant>
11209             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
11210               Primordial phase: between return from <code>Agent_OnLoad</code>
11211               or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> and the
11212               <code>VMStart</code> event.
11213             </constant>
11214             <constant id="JVMTI_PHASE_START" num="6">
11215               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event
11216               is sent and until the <code>VMInit</code> event is sent.
11217             </constant>
11218             <constant id="JVMTI_PHASE_LIVE" num="4">
11219               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
11220               and until the <eventlink id="VMDeath"></eventlink> event returns.
11221             </constant>
11222             <constant id="JVMTI_PHASE_DEAD" num="8">
11223               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
11224               start-up failure.
11225             </constant>
11226           </constants>
11227           In the case of start-up failure the VM will proceed directly to the dead
11228           phase skipping intermediate phases and neither a <code>VMInit</code> nor
11229           <code>VMDeath</code> event will be sent.
11230           <p/>
11231           Most <jvmti/> functions operate only in the live phase.
11232           The following functions operate in either the <code>OnLoad</code> or live phases:
11233           <functionphaselist phase="onload"/>
11234           The following functions operate in only the <code>OnLoad</code> phase:
11235           <functionphaselist phase="onloadOnly"/>
11236           The following functions operate in the start or live phases:
11237           <functionphaselist phase="start"/>
11238           The following functions operate in any phase:
11239           <functionphaselist phase="any"/>
11240           JNI functions (except the Invocation API) must only be used in the start or live phases.
11241           <p/>
11242           Most <jvmti/> events are sent only in the live phase.
11243           The following events operate in others phases:
11244           <eventphaselist phase="start"/>
11245           <eventphaselist phase="any"/>
11246       </description>
11247       <origin>new</origin>
11248       <capabilities>
11249       </capabilities>
11250       <parameters>
11251         <param id="phase_ptr">
11252           <outptr><enum>jvmtiPhase</enum></outptr>
11253           <description>
11254             On return, points to the phase.
11255           </description>
11256         </param>
11257       </parameters>
11258       <errors>
11259       </errors>
11260     </function>
11261 
11262     <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
11263       <synopsis>Dispose Environment</synopsis>
11264       <description>
11265         Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
11266         (see <internallink id="environments"><jvmti/> Environments</internallink>).
11267         Dispose of any resources held by the environment.
11268         <issue>
11269             What resources are reclaimed? What is undone?
11270             Breakpoints,watchpoints removed?
11271         </issue>
11272         Threads suspended by this environment are not resumed by this call,
11273         this must be done explicitly by the agent.
11274         Memory allocated by this environment via calls to <jvmti/> functions
11275         is not released, this can be done explicitly by the agent
11276         by calling <functionlink id="Deallocate"/>.
11277         Raw monitors created by this environment are not destroyed,
11278         this can be done explicitly by the agent
11279         by calling <functionlink id="DestroyRawMonitor"/>.
11280         The state of threads waiting on raw monitors created by this environment
11281         are not affected.
11282         <p/>
11283         Any <functionlink id="SetNativeMethodPrefix">native method
11284         prefixes</functionlink> for this environment will be unset;
11285         the agent must remove any prefixed native methods before
11286         dispose is called.
11287         <p/>
11288         Any <internallink id="capability">capabilities</internallink>
11289         held by this environment are relinquished.
11290         <p/>
11291         Events enabled by this environment will no longer be sent, however
11292         event handlers currently running will continue to run.  Caution must
11293         be exercised in the design of event handlers whose environment may
11294         be disposed and thus become invalid during their execution.
11295         <p/>
11296         This environment may not be used after this call.
11297         This call returns to the caller.
11298       </description>
11299       <origin>new</origin>
11300       <capabilities>
11301       </capabilities>
11302       <parameters>
11303       </parameters>
11304       <errors>
11305       </errors>
11306     </function>
11307 
11308     <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
11309       <synopsis>Set Environment Local Storage</synopsis>
11310       <description>
11311         The VM stores a pointer value associated with each environment.
11312         This pointer value is called <i>environment-local storage</i>.
11313         This value is <code>NULL</code> unless set with this function.
11314         Agents can allocate memory in which they store environment specific
11315         information. By setting environment-local storage it can then be
11316         accessed with
11317         <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
11318         <p/>
11319         Called by the agent to set the value of the <jvmti/>
11320         environment-local storage. <jvmti/> supplies to the agent a pointer-size
11321         environment-local storage that can be used to record per-environment
11322         information.
11323       </description>
11324       <origin>new</origin>
11325       <capabilities>
11326       </capabilities>
11327       <parameters>
11328         <param id="data">
11329           <inbuf>
11330             <void/>
11331             <nullok>value is set to <code>NULL</code></nullok>
11332           </inbuf>
11333           <description>
11334             The value to be entered into the environment-local storage.
11335           </description>
11336         </param>
11337       </parameters>
11338       <errors>
11339       </errors>
11340     </function>
11341 
11342     <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
11343       <synopsis>Get Environment Local Storage</synopsis>
11344       <description>
11345         Called by the agent to get the value of the <jvmti/> environment-local
11346         storage.
11347       </description>
11348       <origin>new</origin>
11349       <capabilities>
11350       </capabilities>
11351       <parameters>
11352         <param id="data_ptr">
11353           <agentbuf><void/></agentbuf>
11354           <description>
11355             Pointer through which the value of the environment local
11356             storage is returned.
11357             If environment-local storage has not been set with
11358             <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned
11359             pointer is <code>NULL</code>.
11360           </description>
11361         </param>
11362       </parameters>
11363       <errors>
11364       </errors>
11365     </function>
11366 
11367     <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
11368       <synopsis>Get Version Number</synopsis>
11369       <description>
11370         Return the <jvmti/> version via <code>version_ptr</code>.
11371         The return value is the version identifier.
11372         The version identifier includes major, minor and micro
11373         version as well as the interface type.
11374         <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
11375           <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
11376             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
11377           </constant>
11378           <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
11379             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
11380           </constant>
11381         </constants>
11382         <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
11383           <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
11384             Mask to extract interface type.
11385             The value of the version returned by this function masked with
11386             <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
11387             <code>JVMTI_VERSION_INTERFACE_JVMTI</code>
11388             since this is a <jvmti/> function.
11389           </constant>
11390           <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
11391             Mask to extract major version number.
11392           </constant>
11393           <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
11394             Mask to extract minor version number.
11395           </constant>
11396           <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
11397             Mask to extract micro version number.
11398           </constant>
11399         </constants>
11400         <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
11401           <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
11402             Shift to extract major version number.
11403           </constant>
11404           <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
11405             Shift to extract minor version number.
11406           </constant>
11407           <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
11408             Shift to extract micro version number.
11409           </constant>
11410         </constants>
11411       </description>
11412       <origin>jvmdi</origin>
11413       <capabilities>
11414       </capabilities>
11415       <parameters>
11416         <param id="version_ptr">
11417           <outptr><jint/></outptr>
11418           <description>
11419             On return, points to the <jvmti/> version.
11420           </description>
11421         </param>
11422       </parameters>
11423       <errors>
11424       </errors>
11425     </function>
11426 
11427 
11428     <function id="GetErrorName" phase="any" num="128">
11429       <synopsis>Get Error Name</synopsis>
11430       <description>
11431         Return the symbolic name for an
11432           <internallink id="ErrorSection">error code</internallink>.
11433         <p/>
11434         For example
11435         <code>GetErrorName(env, JVMTI_ERROR_NONE, &amp;err_name)</code>
11436         would return in <code>err_name</code> the string
11437         <code>"JVMTI_ERROR_NONE"</code>.
11438       </description>
11439       <origin>new</origin>
11440       <capabilities>
11441       </capabilities>
11442       <parameters>
11443         <param id="error">
11444           <enum>jvmtiError</enum>
11445           <description>
11446             The error code.
11447           </description>
11448         </param>
11449         <param id="name_ptr">
11450           <allocbuf><char/></allocbuf>
11451           <description>
11452             On return, points to the error name.
11453             The name is encoded as a
11454             <internallink id="mUTF">modified UTF-8</internallink> string,
11455             but is restricted to the ASCII subset.
11456           </description>
11457         </param>
11458       </parameters>
11459       <errors>
11460       </errors>
11461     </function>
11462 
11463     <function id="SetVerboseFlag" phase="any" num="150">
11464       <synopsis>Set Verbose Flag</synopsis>
11465       <description>
11466         <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
11467           <constant id="JVMTI_VERBOSE_OTHER" num="0">
11468             Verbose output other than the below.
11469           </constant>
11470           <constant id="JVMTI_VERBOSE_GC" num="1">
11471             Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
11472           </constant>
11473           <constant id="JVMTI_VERBOSE_CLASS" num="2">
11474             Verbose class loading output, like that specified with <code>-verbose:class</code>.
11475           </constant>
11476           <constant id="JVMTI_VERBOSE_JNI" num="4">
11477             Verbose JNI output, like that specified with <code>-verbose:jni</code>.
11478           </constant>
11479         </constants>
11480         Control verbose output.
11481         This is the output which typically is sent to <code>stderr</code>.
11482       </description>
11483       <origin>new</origin>
11484       <capabilities>
11485       </capabilities>
11486       <parameters>
11487         <param id="flag">
11488           <enum>jvmtiVerboseFlag</enum>
11489           <description>
11490             Which verbose flag to set.
11491           </description>
11492         </param>
11493         <param id="value">
11494           <jboolean/>
11495           <description>
11496             New value of the flag.
11497           </description>
11498         </param>
11499       </parameters>
11500       <errors>
11501       </errors>
11502     </function>
11503 
11504 
11505     <function id="GetJLocationFormat" phase="any" num="129">
11506       <synopsis>Get JLocation Format</synopsis>
11507       <description>
11508         Although the greatest functionality is achieved with location information
11509         referencing the virtual machine bytecode index, the definition of
11510         <code>jlocation</code> has intentionally been left unconstrained to allow VM
11511         implementations that do not have this information.
11512         <p/>
11513         This function describes the representation of <code>jlocation</code> used in this VM.
11514         If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>,
11515         <code>jlocation</code>s can
11516         be used as in indices into the array returned by
11517         <functionlink id="GetBytecodes"></functionlink>.
11518         <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
11519           <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
11520             <code>jlocation</code> values represent virtual machine
11521             bytecode indices--that is, offsets into the
11522             virtual machine code for a method.
11523           </constant>
11524           <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
11525             <code>jlocation</code> values represent native machine
11526             program counter values.
11527           </constant>
11528           <constant id="JVMTI_JLOCATION_OTHER" num="0">
11529             <code>jlocation</code> values have some other representation.
11530           </constant>
11531         </constants>
11532       </description>
11533       <origin>new</origin>
11534       <capabilities>
11535       </capabilities>
11536       <parameters>
11537         <param id="format_ptr">
11538           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11539           <description>
11540             On return, points to the format identifier for <code>jlocation</code> values.
11541           </description>
11542         </param>
11543       </parameters>
11544       <errors>
11545       </errors>
11546     </function>
11547 
11548   </category>
11549 
11550   <category id="heap_monitoring" label="Heap Monitoring">
11551     <function id="SetHeapSamplingInterval" phase="onload" num="156" since="11">
11552       <synopsis>Set Heap Sampling Interval</synopsis>
11553       <description>
11554         Generate a <eventlink id="SampledObjectAlloc"/> event when objects are allocated.
11555         Each thread keeps a counter of bytes allocated. The event will only be generated
11556         when that counter exceeds an average of <paramlink id="sampling_interval"></paramlink>
11557         since the last sample.
11558         <p/>
11559         Setting <paramlink id="sampling_interval"></paramlink> to 0 will cause an event to be
11560         generated by each allocation supported by the system once the new interval is taken into account.
11561         <p/>
11562         Note that updating the new sampling interval might take various number of allocations
11563         to provoke internal data structure updates.  Therefore it is important to
11564         consider the sampling interval as an average. This includes the interval 0, where events
11565         might not be generated straight away for each allocation.
11566       </description>
11567       <origin>new</origin>
11568       <capabilities>
11569         <required id="can_generate_sampled_object_alloc_events"></required>
11570       </capabilities>
11571       <parameters>
11572         <param id="sampling_interval">
11573           <jint/>
11574           <description>
11575             The sampling interval in bytes. The sampler uses a statistical approach to
11576             generate an event, on average, once for every <paramlink id="sampling_interval"/> bytes of
11577             memory allocated by a given thread.
11578             <p/>
11579             Once the new sampling interval is taken into account, 0 as a sampling interval will generate
11580             a sample for every allocation.
11581             <p/>
11582             Note: The overhead of this feature is directly correlated with the sampling interval.
11583             A high sampling interval, such as 1024 bytes, will incur a high overhead.
11584             A lower interval, such as 1024KB, will have a much lower overhead.  Sampling should only
11585             be used with an understanding that it may impact performance.
11586           </description>
11587         </param>
11588       </parameters>
11589       <errors>
11590         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11591           <paramlink id="sampling_interval"></paramlink> is less than zero.
11592         </error>
11593       </errors>
11594     </function>
11595   </category>
11596 
11597 </functionsection>
11598 
11599 <errorsection label="Error Reference">
11600   <intro>
11601     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11602     <p/>
11603     It is the responsibility of the agent to call <jvmti/> functions with
11604     valid parameters and in the proper context (calling thread is attached,
11605     phase is correct, etc.).
11606     Detecting some error conditions may be difficult, inefficient, or
11607     impossible for an implementation.
11608     The errors listed in
11609     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11610     must be detected by the implementation.
11611     All other errors represent the recommended response to the error
11612     condition.
11613   </intro>
11614 
11615   <errorcategory id="universal-error" label="Universal Errors">
11616     <intro>
11617       The following errors may be returned by any function
11618     </intro>
11619 
11620     <errorid id="JVMTI_ERROR_NONE" num="0">
11621       No error has occurred.  This is the error code that is returned
11622       on successful completion of the function.
11623     </errorid>
11624     <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
11625       Pointer is unexpectedly <code>NULL</code>.
11626     </errorid>
11627     <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
11628       The function attempted to allocate memory and no more memory was
11629       available for allocation.
11630     </errorid>
11631     <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
11632       The desired functionality has not been enabled in this virtual machine.
11633     </errorid>
11634     <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
11635       The thread being used to call this function is not attached
11636       to the virtual machine.  Calls must be made from attached threads.
11637       See <code>AttachCurrentThread</code> in the JNI invocation API.
11638     </errorid>
11639     <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
11640       The <jvmti/> environment provided is no longer connected or is
11641       not an environment.
11642     </errorid>
11643     <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
11644       The desired functionality is not available in the current
11645         <functionlink id="GetPhase">phase</functionlink>.
11646       Always returned if the virtual machine has completed running.
11647     </errorid>
11648     <errorid id="JVMTI_ERROR_INTERNAL" num="113">
11649       An unexpected internal error has occurred.
11650     </errorid>
11651   </errorcategory>
11652 
11653   <errorcategory id="reqerrors" label="Function Specific Required Errors">
11654     <intro>
11655       The following errors are returned by some <jvmti/> functions and must
11656       be returned by the implementation when the condition occurs.
11657     </intro>
11658 
11659     <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
11660       Invalid priority.
11661     </errorid>
11662     <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
11663       Thread was not suspended.
11664     </errorid>
11665     <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
11666       Thread already suspended.
11667     </errorid>
11668     <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
11669       This operation requires the thread to be alive--that is,
11670       it must be started and not yet have died.
11671     </errorid>
11672     <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
11673       The class has been loaded but not yet prepared.
11674     </errorid>
11675     <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
11676       There are no Java programming language or JNI stack frames at the specified depth.
11677     </errorid>
11678     <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
11679       Information about the frame is not available (e.g. for native frames).
11680     </errorid>
11681     <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
11682       Item already set.
11683     </errorid>
11684     <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
11685       Desired element (e.g. field or breakpoint) not found
11686     </errorid>
11687     <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
11688       This thread doesn't own the raw monitor.
11689     </errorid>
11690     <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
11691       The call has been interrupted before completion.
11692     </errorid>
11693     <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
11694       The class cannot be modified.
11695     </errorid>
11696     <errorid id="JVMTI_ERROR_UNMODIFIABLE_MODULE" num="80">
11697       The module cannot be modified.
11698     </errorid>
11699     <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
11700       The functionality is not available in this virtual machine.
11701     </errorid>
11702     <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
11703       The requested information is not available.
11704     </errorid>
11705     <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
11706       The specified event type ID is not recognized.
11707     </errorid>
11708     <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
11709       The requested information is not available for native method.
11710     </errorid>
11711     <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
11712       The class loader does not support this operation.
11713     </errorid>
11714   </errorcategory>
11715 
11716   <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
11717     <intro>
11718       The following errors are returned by some <jvmti/> functions.
11719       They are returned in the event of invalid parameters passed by the
11720       agent or usage in an invalid context.
11721       An implementation is not required to detect these errors.
11722     </intro>
11723 
11724     <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
11725       The passed thread is not a valid thread.
11726     </errorid>
11727     <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
11728       Invalid field.
11729     </errorid>
11730     <errorid id="JVMTI_ERROR_INVALID_MODULE" num="26">
11731       Invalid module.
11732     </errorid>
11733     <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
11734       Invalid method.
11735     </errorid>
11736     <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
11737       Invalid location.
11738     </errorid>
11739     <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
11740       Invalid object.
11741     </errorid>
11742     <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
11743       Invalid class.
11744     </errorid>
11745     <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
11746       The variable is not an appropriate type for the function used.
11747     </errorid>
11748     <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
11749       Invalid slot.
11750     </errorid>
11751     <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
11752       The capability being used is false in this environment.
11753     </errorid>
11754     <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
11755       Thread group invalid.
11756     </errorid>
11757     <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
11758       Invalid raw monitor.
11759     </errorid>
11760     <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
11761       Illegal argument.
11762     </errorid>
11763     <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
11764       The state of the thread has been modified, and is now inconsistent.
11765     </errorid>
11766     <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
11767       A new class file has a version number not supported by this VM.
11768     </errorid>
11769     <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
11770       A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
11771     </errorid>
11772     <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
11773       The new class file definitions would lead to a circular
11774       definition (the VM would return a <code>ClassCircularityError</code>).
11775     </errorid>
11776     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
11777       A new class file would require adding a method.
11778     </errorid>
11779     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
11780       A new class version changes a field.
11781     </errorid>
11782     <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
11783       The class bytes fail verification.
11784     </errorid>
11785     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
11786       A direct superclass is different for the new class
11787       version, or the set of directly implemented
11788       interfaces is different.
11789     </errorid>
11790     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
11791       A new class version does not declare a method
11792       declared in the old class version.
11793     </errorid>
11794     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
11795       The class name defined in the new class file is
11796       different from the name in the old class object.
11797     </errorid>
11798     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
11799       A new class version has different modifiers.
11800     </errorid>
11801     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
11802       A method in the new class version has different modifiers
11803       than its counterpart in the old class version.
11804     </errorid>
11805     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED" num="72">
11806       A new class version has unsupported differences in class attributes.
11807     </errorid>
11808   </errorcategory>
11809 </errorsection>
11810 
11811 <eventsection label="Events">
11812   <intro label="Handling Events" id="eventIntro">
11813     Agents can be informed of many events that occur in application
11814     programs.
11815     <p/>
11816     To handle events, designate a set of callback functions with
11817     <functionlink id="SetEventCallbacks"></functionlink>.
11818     For each event the corresponding callback function will be
11819     called.
11820     Arguments to the callback function provide additional
11821     information about the event.
11822     <p/>
11823     The callback function is usually called from within an application
11824     thread. The <jvmti/> implementation does not
11825     queue events in any way. This means
11826     that event callback functions must be written
11827     carefully. Here are some general guidelines. See
11828     the individual event descriptions for further
11829     suggestions.
11830     <p/>
11831     <ul>
11832       <li>Any exception thrown during the execution of an event callback can
11833         overwrite any current pending exception in the current application thread.
11834         Care must be taken to preserve a pending exception
11835         when an event callback makes a JNI call that might generate an exception.
11836       </li>
11837       <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
11838         not queue events. If an agent needs to process events one at a time, it
11839         can use a raw monitor inside the
11840         event callback functions to serialize event processing.
11841       </li>
11842       <li>Event callback functions that execute JNI's FindClass function to load
11843         classes need to note that FindClass locates the class loader associated
11844         with the current native method. For the purposes of class loading, an
11845         event callback that includes a JNI environment as a parameter to the
11846         callback will treated as if it is a native call, where the native method
11847         is in the class of the event thread's current frame.
11848       </li>
11849     </ul>
11850     <p/>
11851     Some <jvmti/> events identify objects with JNI references.
11852     All references
11853     in <jvmti/> events are JNI local references and will become invalid
11854     after the event callback returns.
11855     Unless stated otherwise, memory referenced by pointers sent in event
11856     callbacks may not be referenced after the event callback returns.
11857     <p/>
11858     Except where stated otherwise, events are delivered on the thread
11859     that caused the event.
11860     Events are sent at the time they occur.
11861     The specification for each event includes the set of
11862     <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
11863     if an event triggering activity occurs during another phase, no event
11864     is sent.
11865     <p/>
11866     A thread that generates an event does not change its execution status
11867     (for example, the event does not cause the thread to be suspended).
11868     If an agent wishes the event to result in suspension, then the agent
11869     is responsible for explicitly suspending the thread with
11870     <functionlink id="SuspendThread"></functionlink>.
11871     <p/>
11872     If an event is enabled in multiple environments, the event will be sent
11873     to each agent in the order that the environments were created.
11874   </intro>
11875 
11876   <intro label="Enabling Events" id="enablingevents">
11877     All events are initially disabled.  In order to receive any
11878     event:
11879       <ul>
11880         <li>
11881           If the event requires a capability, that capability must
11882           be added with
11883           <functionlink id="AddCapabilities"></functionlink>.
11884         </li>
11885         <li>
11886           A callback for the event must be set with
11887           <functionlink id="SetEventCallbacks"></functionlink>.
11888         </li>
11889         <li>
11890           The event must be enabled with
11891           <functionlink id="SetEventNotificationMode"></functionlink>.
11892         </li>
11893       </ul>
11894   </intro>
11895 
11896   <intro label="Multiple Co-located Events" id="eventorder">
11897     In many situations it is possible for multiple events to occur
11898     at the same location in one thread. When this happens, all the events
11899     are reported through the event callbacks in the order specified in this section.
11900     <p/>
11901     If the current location is at the entry point of a method, the
11902     <eventlink id="MethodEntry"></eventlink> event is reported before
11903     any other event at the current location in the same thread.
11904     <p/>
11905     If an exception catch has been detected at the current location,
11906     either because it is the beginning of a catch clause or a native method
11907     that cleared a pending exception has returned, the
11908     <code>exceptionCatch</code> event is reported before
11909     any other event at the current location in the same thread.
11910     <p/>
11911     If a <code>singleStep</code> event or
11912     <code>breakpoint</code> event is triggered at the
11913     current location, the event is defined to occur
11914     immediately before the code at the current location is executed.
11915     These events are reported before any events which are triggered
11916     by the execution of code at the current location in the same
11917     thread (specifically:
11918     <code>exception</code>,
11919     <code>fieldAccess</code>, and
11920     <code>fieldModification</code>).
11921     If both a step and breakpoint event are triggered for the same thread and
11922     location, the step event is reported before the breakpoint event.
11923     <p/>
11924     If the current location is the exit point of a method (that is, the last
11925     location before returning to the caller), the
11926     <eventlink id="MethodExit"></eventlink> event and
11927     the <eventlink id="FramePop"></eventlink> event (if requested)
11928     are reported after all other events at the current location in the same
11929     thread. There is no specified ordering of these two events
11930     with respect to each other.
11931     <p/>
11932     Co-located events can be triggered during the processing of some other
11933     event by the agent at the same location in the same thread.
11934     If such an event, of type <i>y</i>, is triggered during the processing of
11935     an event of type <i>x</i>, and if <i>x</i>
11936     precedes <i>y</i> in the ordering specified above, the co-located event
11937     <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
11938     <i>y</i>, <i>y</i> is not reported for the current thread and location.
11939     For example, if a breakpoint is set at the current location
11940     during the processing of <eventlink id="SingleStep"></eventlink>,
11941     that breakpoint will be reported before the thread moves off the current
11942     location.
11943     <p/>The following events are never considered to be co-located with
11944     other events.
11945     <ul>
11946       <li><eventlink id="VMStart"></eventlink></li>
11947       <li><eventlink id="VMInit"></eventlink></li>
11948       <li><eventlink id="VMDeath"></eventlink></li>
11949       <li><eventlink id="ThreadStart"></eventlink></li>
11950       <li><eventlink id="ThreadEnd"></eventlink></li>
11951       <li><eventlink id="ClassLoad"></eventlink></li>
11952       <li><eventlink id="ClassPrepare"></eventlink></li>
11953     </ul>
11954   </intro>
11955 
11956   <intro label="Event Callbacks" id="jvmtiEventCallbacks">
11957       The event callback structure below is used to specify the handler function
11958       for events.  It is set with the
11959       <functionlink id="SetEventCallbacks"></functionlink> function.
11960   </intro>
11961 
11962   <event label="Single Step"
11963          id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
11964     <description>
11965       Single step events allow the agent to trace thread execution
11966       at the finest granularity allowed by the VM. A single step event is
11967       generated whenever a thread reaches a new location.
11968       Typically, single step events represent the completion of one VM
11969       instruction as defined in <vmspec/>. However, some implementations
11970       may define locations differently. In any case the
11971       <code>method</code> and <code>location</code>
11972       parameters  uniquely identify the current location and allow
11973       the mapping to source file and line number when that information is
11974       available.
11975       <p/>
11976       No single step events are generated from within native methods.
11977     </description>
11978     <origin>jvmdi</origin>
11979     <capabilities>
11980       <required id="can_generate_single_step_events"></required>
11981     </capabilities>
11982     <parameters>
11983       <param id="jni_env">
11984         <outptr>
11985           <struct>JNIEnv</struct>
11986         </outptr>
11987           <description>
11988             The JNI environment of the event (current) thread
11989           </description>
11990       </param>
11991       <param id="thread">
11992         <jthread/>
11993           <description>
11994             Thread about to execution a new instruction
11995           </description>
11996       </param>
11997       <param id="klass">
11998         <jclass method="method"/>
11999           <description>
12000             Class of the method about to execute a new instruction
12001           </description>
12002       </param>
12003       <param id="method">
12004         <jmethodID class="klass"/>
12005           <description>
12006             Method about to execute a new instruction
12007           </description>
12008       </param>
12009       <param id="location">
12010         <jlocation/>
12011         <description>
12012           Location of the new instruction
12013         </description>
12014       </param>
12015     </parameters>
12016   </event>
12017 
12018   <event label="Breakpoint"
12019          id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
12020     <description>
12021       Breakpoint events are generated whenever a thread reaches a location
12022       designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
12023       The <code>method</code> and <code>location</code>
12024       parameters uniquely identify the current location and allow
12025       the mapping to source file and line number when that information is
12026       available.
12027     </description>
12028     <origin>jvmdi</origin>
12029     <capabilities>
12030       <required id="can_generate_breakpoint_events"></required>
12031     </capabilities>
12032     <parameters>
12033       <param id="jni_env">
12034         <outptr>
12035           <struct>JNIEnv</struct>
12036         </outptr>
12037           <description>
12038             The JNI environment of the event (current) thread.
12039           </description>
12040       </param>
12041       <param id="thread">
12042         <jthread/>
12043           <description>
12044             Thread that hit the breakpoint
12045           </description>
12046       </param>
12047       <param id="klass">
12048         <jclass method="method"/>
12049           <description>
12050             Class of the method that hit the breakpoint
12051           </description>
12052       </param>
12053       <param id="method">
12054         <jmethodID class="klass"/>
12055           <description>
12056             Method that hit the breakpoint
12057           </description>
12058       </param>
12059       <param id="location">
12060         <jlocation/>
12061         <description>
12062           location of the breakpoint
12063         </description>
12064       </param>
12065     </parameters>
12066   </event>
12067 
12068   <event label="Field Access"
12069          id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
12070     <description>
12071       Field access events are generated whenever a thread accesses
12072       a field that was designated as a watchpoint
12073       with <functionlink id="SetFieldAccessWatch"></functionlink>.
12074       The <code>method</code> and <code>location</code>
12075       parameters uniquely identify the current location and allow
12076       the mapping to source file and line number when that information is
12077       available.
12078     </description>
12079     <origin>jvmdi</origin>
12080     <capabilities>
12081       <required id="can_generate_field_access_events"></required>
12082     </capabilities>
12083     <parameters>
12084       <param id="jni_env">
12085         <outptr>
12086           <struct>JNIEnv</struct>
12087         </outptr>
12088           <description>
12089             The JNI environment of the event (current) thread
12090           </description>
12091       </param>
12092       <param id="thread">
12093         <jthread/>
12094           <description>
12095             Thread accessing the field
12096           </description>
12097       </param>
12098       <param id="klass">
12099         <jclass method="method"/>
12100           <description>
12101             Class of the method where the access is occurring
12102           </description>
12103       </param>
12104       <param id="method">
12105         <jmethodID class="klass"/>
12106           <description>
12107             Method where the access is occurring
12108           </description>
12109       </param>
12110       <param id="location">
12111         <jlocation/>
12112         <description>
12113           Location where the access is occurring
12114         </description>
12115       </param>
12116       <param id="field_klass">
12117         <jclass field="field"/>
12118           <description>
12119             Class of the field being accessed
12120           </description>
12121       </param>
12122       <param id="object">
12123         <jobject/>
12124           <description>
12125             Object with the field being accessed if the field is an
12126             instance field; <code>NULL</code> otherwise
12127           </description>
12128       </param>
12129       <param id="field">
12130         <jfieldID class="field_klass"/>
12131           <description>
12132             Field being accessed
12133           </description>
12134       </param>
12135     </parameters>
12136   </event>
12137 
12138   <event label="Field Modification"
12139          id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
12140     <description>
12141       Field modification events are generated whenever a thread modifies
12142       a field that was designated as a watchpoint
12143       with <functionlink id="SetFieldModificationWatch"></functionlink>.
12144       The <code>method</code> and <code>location</code>
12145       parameters uniquely identify the current location and allow
12146       the mapping to source file and line number when that information is
12147       available.
12148     </description>
12149     <origin>jvmdi</origin>
12150     <capabilities>
12151       <required id="can_generate_field_modification_events"></required>
12152     </capabilities>
12153     <parameters>
12154       <param id="jni_env">
12155         <outptr>
12156           <struct>JNIEnv</struct>
12157         </outptr>
12158           <description>
12159             The JNI environment of the event (current) thread
12160           </description>
12161       </param>
12162       <param id="thread">
12163         <jthread/>
12164           <description>
12165             Thread modifying the field
12166           </description>
12167       </param>
12168       <param id="klass">
12169         <jclass method="method"/>
12170           <description>
12171             Class of the method where the modification is occurring
12172           </description>
12173       </param>
12174       <param id="method">
12175         <jmethodID class="klass"/>
12176           <description>
12177             Method where the modification is occurring
12178           </description>
12179       </param>
12180       <param id="location">
12181         <jlocation/>
12182         <description>
12183           Location where the modification is occurring
12184         </description>
12185       </param>
12186       <param id="field_klass">
12187         <jclass field="field"/>
12188           <description>
12189             Class of the field being modified
12190           </description>
12191       </param>
12192       <param id="object">
12193         <jobject/>
12194           <description>
12195             Object with the field being modified if the field is an
12196             instance field; <code>NULL</code> otherwise
12197           </description>
12198       </param>
12199       <param id="field">
12200         <jfieldID class="field_klass"/>
12201           <description>
12202             Field being modified
12203           </description>
12204       </param>
12205       <param id="signature_type">
12206         <char/>
12207         <description>
12208           Signature type of the new value
12209         </description>
12210       </param>
12211       <param id="new_value">
12212         <jvalue/>
12213         <description>
12214           The new value
12215         </description>
12216       </param>
12217     </parameters>
12218   </event>
12219 
12220   <event label="Frame Pop"
12221          id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
12222     <description>
12223       Frame pop events are generated upon exit from a single method
12224       in a single frame as specified
12225       in a call to <functionlink id="NotifyFramePop"></functionlink>.
12226       This is true whether termination is caused by
12227       executing its return instruction
12228       or by throwing an exception to its caller
12229       (see <paramlink id="was_popped_by_exception"></paramlink>).
12230       However, frame pops caused by the <functionlink id="PopFrame"/>
12231       function are not reported.
12232       <p/>
12233       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12234       identifies the executable location in the returning method,
12235       immediately prior to the return.
12236     </description>
12237     <origin>jvmdi</origin>
12238     <capabilities>
12239       <required id="can_generate_frame_pop_events"></required>
12240     </capabilities>
12241     <parameters>
12242       <param id="jni_env">
12243         <outptr>
12244           <struct>JNIEnv</struct>
12245         </outptr>
12246           <description>
12247             The JNI environment of the event (current) thread
12248           </description>
12249       </param>
12250       <param id="thread">
12251         <jthread/>
12252           <description>
12253             Thread that is popping the frame
12254           </description>
12255       </param>
12256       <param id="klass">
12257         <jclass method="method"/>
12258           <description>
12259             Class of the method being popped
12260           </description>
12261       </param>
12262       <param id="method">
12263         <jmethodID class="klass"/>
12264           <description>
12265             Method being popped
12266           </description>
12267       </param>
12268       <param id="was_popped_by_exception">
12269         <jboolean/>
12270         <description>
12271           True if frame was popped by a thrown exception.
12272           False if method exited through its return instruction.
12273         </description>
12274       </param>
12275     </parameters>
12276   </event>
12277 
12278   <event label="Method Entry"
12279          id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
12280     <description>
12281       Method entry events are generated upon entry of Java
12282       programming language methods (including native methods).
12283       <p/>
12284       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12285       identifies the initial executable location in
12286       the method.
12287       <p/>
12288       Enabling method
12289       entry or exit events will significantly degrade performance on many platforms and is thus
12290       not advised for performance critical usage (such as profiling).
12291       <internallink id="bci">Bytecode instrumentation</internallink> should be
12292       used in these cases.
12293     </description>
12294     <origin>jvmdi</origin>
12295     <capabilities>
12296       <required id="can_generate_method_entry_events"></required>
12297     </capabilities>
12298     <parameters>
12299       <param id="jni_env">
12300         <outptr>
12301           <struct>JNIEnv</struct>
12302         </outptr>
12303           <description>
12304             The JNI environment of the event (current) thread
12305           </description>
12306       </param>
12307       <param id="thread">
12308         <jthread/>
12309           <description>
12310             Thread entering the method
12311           </description>
12312       </param>
12313       <param id="klass">
12314         <jclass method="method"/>
12315           <description>
12316             Class of the method being entered
12317           </description>
12318       </param>
12319       <param id="method">
12320         <jmethodID class="klass"/>
12321           <description>
12322             Method being entered
12323           </description>
12324       </param>
12325     </parameters>
12326   </event>
12327 
12328   <event label="Method Exit"
12329          id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
12330     <description>
12331       Method exit events are generated upon exit from Java
12332       programming language methods (including native methods).
12333       This is true whether termination is caused by
12334       executing its return instruction
12335       or by throwing an exception to its caller
12336       (see <paramlink id="was_popped_by_exception"></paramlink>).
12337       <p/>
12338       The <code>method</code> field uniquely identifies the
12339       method being entered or exited. The <code>frame</code> field provides
12340       access to the stack frame for the method.
12341       <p/>
12342       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12343       identifies the executable location in the returning method
12344       immediately prior to the return.
12345       <p/>
12346         Enabling method
12347         entry or exit events will significantly degrade performance on many platforms and is thus
12348         not advised for performance critical usage (such as profiling).
12349         <internallink id="bci">Bytecode instrumentation</internallink> should be
12350         used in these cases.
12351     </description>
12352     <origin>jvmdi</origin>
12353     <capabilities>
12354       <required id="can_generate_method_exit_events"></required>
12355     </capabilities>
12356     <parameters>
12357       <param id="jni_env">
12358         <outptr>
12359           <struct>JNIEnv</struct>
12360         </outptr>
12361           <description>
12362             The JNI environment of the event (current) thread
12363           </description>
12364       </param>
12365       <param id="thread">
12366         <jthread/>
12367           <description>
12368             Thread exiting the method
12369           </description>
12370       </param>
12371       <param id="klass">
12372         <jclass method="method"/>
12373           <description>
12374             Class of the method being exited
12375           </description>
12376       </param>
12377       <param id="method">
12378         <jmethodID class="klass"/>
12379           <description>
12380             Method being exited
12381           </description>
12382       </param>
12383       <param id="was_popped_by_exception">
12384         <jboolean/>
12385         <description>
12386           True if frame was popped by a thrown exception.
12387           False if method exited through its return instruction.
12388         </description>
12389       </param>
12390       <param id="return_value">
12391         <jvalue/>
12392         <description>
12393           The return value of the method being exited.
12394           Undefined and should not be used if
12395           <paramlink id="was_popped_by_exception"></paramlink>
12396           is true.
12397         </description>
12398       </param>
12399     </parameters>
12400   </event>
12401 
12402   <event label="Native Method Bind" phase="any"
12403          id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
12404     <description>
12405       A Native Method Bind event is sent when a VM binds a
12406       Java programming language native method
12407       to the address of a function that implements the native method.
12408       This will occur when the native method is called for the first time
12409       and also occurs when the JNI function <code>RegisterNatives</code> is called.
12410       This event allows the bind to be redirected to an agent-specified
12411       proxy function.
12412       This event is not sent when the native method is unbound.
12413       Typically, this proxy function will need to be specific to a
12414       particular method or, to handle the general case, automatically
12415       generated assembly code, since after instrumentation code is
12416       executed the function at the original binding
12417       address will usually be invoked.
12418       The original binding can be restored or the redirection changed
12419       by use of the JNI function <code>RegisterNatives</code>.
12420       Some events may be sent during the primordial phase, JNI and
12421       most of <jvmti/> cannot be used at this time but the method and
12422       address can be saved for use later.
12423     </description>
12424     <origin>new</origin>
12425     <capabilities>
12426       <required id="can_generate_native_method_bind_events"></required>
12427     </capabilities>
12428     <parameters>
12429       <param id="jni_env">
12430         <outptr>
12431           <struct>JNIEnv</struct>
12432         </outptr>
12433           <description>
12434             The JNI environment of the event (current) thread
12435             Will be <code>NULL</code> if sent during the primordial
12436             <functionlink id="GetPhase">phase</functionlink>.
12437           </description>
12438       </param>
12439       <param id="thread">
12440         <jthread/>
12441           <description>
12442             Thread requesting the bind
12443           </description>
12444       </param>
12445       <param id="klass">
12446         <jclass method="method"/>
12447           <description>
12448             Class of the method being bound
12449           </description>
12450       </param>
12451       <param id="method">
12452         <jmethodID class="klass"/>
12453           <description>
12454             Native method being bound
12455           </description>
12456       </param>
12457       <param id="address">
12458         <outptr><void/></outptr>
12459         <description>
12460           The address the VM is about to bind to--that is, the
12461           address of the implementation of the native method
12462         </description>
12463       </param>
12464       <param id="new_address_ptr">
12465         <agentbuf><void/></agentbuf>
12466         <description>
12467           if the referenced address is changed (that is, if
12468           <code>*new_address_ptr</code> is set), the binding
12469           will instead be made to the supplied address.
12470         </description>
12471       </param>
12472     </parameters>
12473   </event>
12474 
12475   <event label="Exception"
12476          id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
12477     <description>
12478       Exception events are generated whenever an exception is first detected
12479       in a Java programming language method.
12480       Where "exception" means any <code>java.lang.Throwable</code>.
12481       The exception may have been thrown by a Java programming language or native
12482       method, but in the case of native methods, the event is not generated
12483       until the exception is first seen by a Java programming language method. If an exception is
12484       set and cleared in a native method (and thus is never visible to Java programming language code),
12485       no exception event is generated.
12486       <p/>
12487       The <code>method</code> and <code>location</code>
12488       parameters  uniquely identify the current location
12489       (where the exception was detected) and allow
12490       the mapping to source file and line number when that information is
12491       available. The <code>exception</code> field identifies the thrown
12492       exception object. The <code>catch_method</code>
12493       and <code>catch_location</code> identify the location of the catch clause,
12494       if any, that handles the thrown exception. If there is no such catch clause,
12495       each field is set to 0. There is no guarantee that the thread will ever
12496       reach this catch clause. If there are native methods on the call stack
12497       between the throw location and the catch clause, the exception may
12498       be reset by one of those native methods.
12499       Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
12500       et al. set to 0) may in fact be caught by native code.
12501       Agents can check for these occurrences by monitoring
12502       <eventlink id="ExceptionCatch"></eventlink> events.
12503       Note that finally clauses are implemented as catch and re-throw. Therefore they
12504       will be reported in the catch location.
12505     </description>
12506     <origin>jvmdi</origin>
12507     <capabilities>
12508       <required id="can_generate_exception_events"></required>
12509     </capabilities>
12510     <parameters>
12511       <param id="jni_env">
12512         <outptr>
12513           <struct>JNIEnv</struct>
12514         </outptr>
12515           <description>
12516             The JNI environment of the event (current) thread
12517           </description>
12518       </param>
12519       <param id="thread">
12520         <jthread/>
12521           <description>
12522             Thread generating the exception
12523           </description>
12524       </param>
12525       <param id="klass">
12526         <jclass method="method"/>
12527           <description>
12528             Class generating the exception
12529           </description>
12530       </param>
12531       <param id="method">
12532         <jmethodID class="klass"/>
12533           <description>
12534             Method generating the exception
12535           </description>
12536       </param>
12537       <param id="location">
12538         <jlocation/>
12539         <description>
12540           Location where exception occurred
12541         </description>
12542       </param>
12543       <param id="exception">
12544         <jobject/>
12545           <description>
12546             The exception being thrown
12547           </description>
12548       </param>
12549       <param id="catch_klass">
12550         <jclass method="catch_method"/>
12551           <description>
12552             Class that will catch the exception, or <code>NULL</code> if no known catch
12553           </description>
12554       </param>
12555       <param id="catch_method">
12556         <jmethodID class="catch_klass"/>
12557           <description>
12558             Method that will catch the exception, or <code>NULL</code> if no known catch
12559           </description>
12560       </param>
12561       <param id="catch_location">
12562         <jlocation/>
12563         <description>
12564           location which will catch the exception or zero if no known catch
12565         </description>
12566       </param>
12567     </parameters>
12568   </event>
12569 
12570   <event label="Exception Catch"
12571          id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
12572     <description>
12573       Exception catch events are generated whenever a thrown exception is caught.
12574       Where "exception" means any <code>java.lang.Throwable</code>.
12575       If the exception is caught in a Java programming language method, the event is generated
12576       when the catch clause is reached. If the exception is caught in a native
12577       method, the event is generated as soon as control is returned to a Java programming language
12578       method. Exception catch events are generated for any exception for which
12579       a throw was detected in a Java programming language method.
12580       Note that finally clauses are implemented as catch and re-throw. Therefore they
12581       will generate exception catch events.
12582       <p/>
12583       The <code>method</code> and <code>location</code>
12584       parameters uniquely identify the current location
12585       and allow the mapping to source file and line number when that information is
12586       available. For exceptions caught in a Java programming language method, the
12587       <code>exception</code> object identifies the exception object. Exceptions
12588       caught in native methods are not necessarily available by the time the
12589       exception catch is reported, so the <code>exception</code> field is set
12590       to <code>NULL</code>.
12591     </description>
12592     <origin>jvmdi</origin>
12593     <capabilities>
12594       <required id="can_generate_exception_events"></required>
12595     </capabilities>
12596     <parameters>
12597       <param id="jni_env">
12598         <outptr>
12599           <struct>JNIEnv</struct>
12600         </outptr>
12601           <description>
12602             The JNI environment of the event (current) thread
12603           </description>
12604       </param>
12605       <param id="thread">
12606         <jthread/>
12607           <description>
12608             Thread catching the exception
12609           </description>
12610       </param>
12611       <param id="klass">
12612         <jclass method="method"/>
12613           <description>
12614             Class catching the exception
12615           </description>
12616       </param>
12617       <param id="method">
12618         <jmethodID class="klass"/>
12619           <description>
12620             Method catching the exception
12621           </description>
12622       </param>
12623       <param id="location">
12624         <jlocation/>
12625         <description>
12626           Location where exception is being caught
12627         </description>
12628       </param>
12629       <param id="exception">
12630         <jobject/>
12631           <description>
12632             Exception being caught
12633           </description>
12634       </param>
12635     </parameters>
12636   </event>
12637 
12638   <event label="Thread Start"
12639          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12640     <description>
12641       Thread start events are generated by a new thread before its initial
12642       method executes.
12643       <p/>
12644       A thread may be listed in the array returned by
12645       <functionlink id="GetAllThreads"></functionlink>
12646       before its thread start event is generated.
12647       It is possible for other events to be generated
12648       on a thread before its thread start event.
12649       <p/>
12650       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12651     </description>
12652     <origin>jvmdi</origin>
12653     <capabilities>
12654     </capabilities>
12655     <parameters>
12656       <param id="jni_env">
12657         <outptr>
12658           <struct>JNIEnv</struct>
12659         </outptr>
12660           <description>
12661             The JNI environment of the event (current) thread.
12662           </description>
12663       </param>
12664       <param id="thread">
12665         <jthread/>
12666           <description>
12667             Thread starting
12668           </description>
12669       </param>
12670     </parameters>
12671   </event>
12672 
12673   <event label="Thread End"
12674          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start">
12675     <description>
12676       Thread end events are generated by a terminating thread
12677       after its initial method has finished execution.
12678       <p/>
12679       A thread may be listed in the array returned by
12680       <functionlink id="GetAllThreads"></functionlink>
12681       after its thread end event is generated.
12682       No events are generated on a thread
12683       after its thread end event.
12684       <p/>
12685       The event is sent on the dying <paramlink id="thread"></paramlink>.
12686     </description>
12687     <origin>jvmdi</origin>
12688     <capabilities>
12689     </capabilities>
12690     <parameters>
12691       <param id="jni_env">
12692         <outptr>
12693           <struct>JNIEnv</struct>
12694         </outptr>
12695           <description>
12696             The JNI environment of the event (current) thread.
12697           </description>
12698       </param>
12699       <param id="thread">
12700         <jthread/>
12701           <description>
12702             Thread ending
12703           </description>
12704       </param>
12705     </parameters>
12706   </event>
12707 
12708   <event label="Class Load"
12709          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
12710     <description>
12711       A class load event is generated when a class is first loaded. The order
12712       of class load events generated by a particular thread are guaranteed
12713       to match the order of class loading within that thread.
12714       Array class creation does not generate a class load event.
12715       The creation of a primitive class (for example, java.lang.Integer.TYPE)
12716       does not generate a class load event.
12717       <p/>
12718       This event is sent at an early stage in loading the class. As
12719       a result the class should be used carefully.  Note, for example,
12720       that methods and fields are not yet loaded, so queries for methods,
12721       fields, subclasses, and so on will not give correct results.
12722       See "Loading of Classes and Interfaces" in the <i>Java Language
12723       Specification</i>.  For most
12724       purposes the <eventlink id="ClassPrepare"></eventlink> event will
12725       be more useful.
12726     </description>
12727     <origin>jvmdi</origin>
12728     <capabilities>
12729     </capabilities>
12730     <parameters>
12731       <param id="jni_env">
12732         <outptr>
12733           <struct>JNIEnv</struct>
12734         </outptr>
12735           <description>
12736             The JNI environment of the event (current) thread
12737           </description>
12738       </param>
12739       <param id="thread">
12740         <jthread/>
12741           <description>
12742             Thread loading the class
12743           </description>
12744       </param>
12745       <param id="klass">
12746         <jclass/>
12747           <description>
12748             Class being loaded
12749           </description>
12750       </param>
12751     </parameters>
12752   </event>
12753 
12754   <elide>
12755   <event label="Class Unload"
12756          id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
12757     <description>
12758       A class unload event is generated when the class is about to be unloaded.
12759       Class unload events take place during garbage collection and must be
12760       handled extremely carefully. The garbage collector holds many locks
12761       and has suspended all other threads, so the event handler cannot depend
12762       on the ability to acquire any locks. The class unload event handler should
12763       do as little as possible, perhaps by queuing information to be processed
12764       later.  In particular, the <code>jclass</code> should be used only in
12765       the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
12766       <ul>
12767         <li><functionlink id="GetClassSignature"></functionlink></li>
12768         <li><functionlink id="GetSourceFileName"></functionlink></li>
12769         <li><functionlink id="IsInterface"></functionlink></li>
12770         <li><functionlink id="IsArrayClass"></functionlink></li>
12771       </ul>
12772     </description>
12773     <origin>jvmdi</origin>
12774     <capabilities>
12775     </capabilities>
12776     <parameters>
12777       <param id="jni_env">
12778         <outptr>
12779           <struct>JNIEnv</struct>
12780         </outptr>
12781           <description>
12782             The JNI environment of the event (current) thread
12783           </description>
12784       </param>
12785       <param id="thread">
12786         <jthread/>
12787           <description>
12788             Thread generating the class unload
12789           </description>
12790       </param>
12791       <param id="klass">
12792         <jclass/>
12793           <description>
12794             Class being unloaded
12795           </description>
12796       </param>
12797     </parameters>
12798   </event>
12799   </elide>
12800 
12801   <event label="Class Prepare"
12802          id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
12803     <description>
12804       A class prepare event is generated when class preparation is complete.
12805       At this point, class fields, methods, and implemented interfaces are
12806       available, and no code from the class has been executed. Since array
12807       classes never have fields or methods, class prepare events are not
12808       generated for them. Class prepare events are not generated for
12809       primitive classes (for example, <code>java.lang.Integer.TYPE</code>).
12810     </description>
12811     <origin>jvmdi</origin>
12812     <capabilities>
12813     </capabilities>
12814     <parameters>
12815       <param id="jni_env">
12816         <outptr>
12817           <struct>JNIEnv</struct>
12818         </outptr>
12819           <description>
12820             The JNI environment of the event (current) thread
12821           </description>
12822       </param>
12823       <param id="thread">
12824         <jthread/>
12825           <description>
12826             Thread generating the class prepare
12827           </description>
12828       </param>
12829       <param id="klass">
12830         <jclass/>
12831           <description>
12832             Class being prepared
12833           </description>
12834       </param>
12835     </parameters>
12836   </event>
12837 
12838   <event label="Class File Load Hook" phase="any"
12839          id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
12840     <description>
12841       This event is sent when the VM obtains class file data,
12842       but before it constructs
12843       the in-memory representation for that class.
12844       This event is also sent when the class is being modified by the
12845       <functionlink id="RetransformClasses"/> function or
12846       the <functionlink id="RedefineClasses"/> function,
12847       called in any <jvmti/> environment.
12848       The agent can instrument
12849       the existing class file data sent by the VM to include profiling/debugging hooks.
12850       See the description of
12851       <internallink id="bci">bytecode instrumentation</internallink>
12852       for usage information.
12853       <p/>
12854     When the capabilities
12855     <internallink id="jvmtiCapabilities.can_generate_early_class_hook_events">
12856     <code>can_generate_early_class_hook_events</code></internallink> and
12857     <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
12858     <code>can_generate_all_class_hook_events</code></internallink>
12859     are enabled then this event may be sent in the primordial phase.
12860     Otherwise, this event may be sent before the VM is initialized (the start
12861     <functionlink id="GetPhase">phase</functionlink>).
12862     Some classes might not be compatible
12863     with the function (eg. ROMized classes or implementation defined classes) and this event will
12864     not be generated for these classes.
12865     <p/>
12866     The agent must allocate the space for the modified
12867     class file data buffer
12868     using the memory allocation function
12869     <functionlink id="Allocate"></functionlink> because the
12870     VM is responsible for freeing the new class file data buffer
12871     using <functionlink id="Deallocate"></functionlink>.
12872     <p/>
12873     If the agent wishes to modify the class file, it must set
12874     <code>new_class_data</code> to point
12875     to the newly instrumented class file data buffer and set
12876     <code>new_class_data_len</code> to the length of that
12877     buffer before returning
12878     from this call.  If no modification is desired, the agent simply
12879     does not set <code>new_class_data</code>.  If multiple agents
12880     have enabled this event the results are chained. That is, if
12881     <code>new_class_data</code> has been set, it becomes the
12882     <code>class_data</code> for the next agent.
12883     <p/>
12884     When handling a class load in the live phase, then the
12885     <functionlink id="GetNamedModule"></functionlink>
12886     function can be used to map class loader and a package name to a module.
12887     When a class is being redefined or retransformed then
12888     <code>class_being_redefined</code> is non <code>NULL</code> and so
12889     the JNI <code>GetModule</code> function can also be used
12890     to obtain the Module.
12891     <p/>
12892     The order that this event is sent to each environment differs
12893     from other events.
12894     This event is sent to environments in the following order:
12895     <ul>
12896       <li><fieldlink id="can_retransform_classes"
12897                      struct="jvmtiCapabilities">retransformation
12898                                                 incapable</fieldlink>
12899           environments, in the
12900           order in which they were created
12901       </li>
12902       <li><fieldlink id="can_retransform_classes"
12903                      struct="jvmtiCapabilities">retransformation
12904                                                 capable</fieldlink>
12905           environments, in the
12906           order in which they were created
12907       </li>
12908     </ul>
12909     When triggered by <functionlink id="RetransformClasses"/>,
12910     this event is sent only to <fieldlink id="can_retransform_classes"
12911                      struct="jvmtiCapabilities">retransformation
12912                                                 capable</fieldlink>
12913     environments.
12914   </description>
12915   <origin>jvmpi</origin>
12916     <capabilities>
12917       <capability id="can_generate_all_class_hook_events"></capability>
12918       <capability id="can_generate_early_class_hook_events"></capability>
12919     </capabilities>
12920     <parameters>
12921       <param id="jni_env">
12922         <outptr>
12923           <struct>JNIEnv</struct>
12924         </outptr>
12925           <description>
12926             The JNI environment of the event (current) thread.
12927           </description>
12928       </param>
12929       <param id="class_being_redefined">
12930         <jclass/>
12931         <description>
12932           The class being
12933           <functionlink id="RedefineClasses">redefined</functionlink> or
12934           <functionlink id="RetransformClasses">retransformed</functionlink>.
12935           <code>NULL</code> if sent by class load.
12936         </description>
12937       </param>
12938       <param id="loader">
12939         <jobject/>
12940           <description>
12941             The class loader loading the class.
12942             <code>NULL</code> if the bootstrap class loader.
12943           </description>
12944       </param>
12945       <param id="name">
12946         <vmbuf><char/></vmbuf>
12947         <description>
12948             Name of class being loaded as a VM internal qualified name
12949             (for example, "java/util/List"), encoded as a
12950             <internallink id="mUTF">modified UTF-8</internallink> string.
12951             Note: if the class is defined with a <code>NULL</code> name or
12952             without a name specified, <code>name</code> will be <code>NULL</code>.
12953         </description>
12954       </param>
12955       <param id="protection_domain">
12956         <jobject/>
12957         <description>
12958           The <code>ProtectionDomain</code> of the class.
12959         </description>
12960       </param>
12961       <param id="class_data_len">
12962         <jint/>
12963         <description>
12964           Length of current class file data buffer.
12965         </description>
12966       </param>
12967       <param id="class_data">
12968         <vmbuf><uchar/></vmbuf>
12969         <description>
12970           Pointer to the current class file data buffer.
12971         </description>
12972       </param>
12973       <param id="new_class_data_len">
12974         <outptr><jint/></outptr>
12975         <description>
12976           Pointer to the length of the new class file data buffer.
12977         </description>
12978       </param>
12979       <param id="new_class_data">
12980         <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
12981         <description>
12982           Pointer to the pointer to the instrumented class file data buffer.
12983         </description>
12984       </param>
12985     </parameters>
12986   </event>
12987 
12988   <event label="VM Start Event"
12989          id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
12990     <description>
12991       The VM start event signals the start of the VM.
12992       At this time JNI is live but the VM is not yet fully initialized.
12993       Once this event is generated, the agent is free to call any JNI function.
12994       This event signals the beginning of the start phase,
12995       <jvmti/> functions permitted in the start phase may be called.
12996       <p/>
12997       The timing of this event may depend on whether the agent has added the
12998       <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
12999       <code>can_generate_early_vmstart</code></internallink> capability or not.
13000       If the capability has been added then the VM posts the event as early
13001       as possible. The VM is capable of executing bytecode but it may not have
13002       initialized to the point where it can load classes in modules other than
13003       <code>java.base</code>, or even arbitrary classes in <code>java.base</code>.
13004       Agents that do load-time instrumentation in this
13005       phase must take great care when instrumenting code that potentially
13006       executes in this phase. Extreme care should also be taken with JNI
13007       <code>FindClass</code> as it may not be possible to load classes and attempts
13008       to do so may result in unpredictable behavior, maybe even stability issues
13009       on some VM implementations.
13010       If the capability has not been added then the VM delays posting this
13011       event until it is capable of loading classes in modules other than
13012       <code>java.base</code> or the VM has completed its initialization.
13013       Agents that create more than one JVM TI environment, where the
13014       capability is added to some but not all environments, may observe the
13015       start phase beginning earlier in the JVM TI environments that possess
13016       the capability.
13017       <p/>
13018       In the case of VM start-up failure, this event will not be sent.
13019     </description>
13020     <origin>jvmdi</origin>
13021     <capabilities>
13022     </capabilities>
13023     <parameters>
13024       <param id="jni_env">
13025         <outptr>
13026           <struct>JNIEnv</struct>
13027         </outptr>
13028           <description>
13029             The JNI environment of the event (current) thread.
13030           </description>
13031       </param>
13032     </parameters>
13033   </event>
13034 
13035   <event label="VM Initialization Event"
13036          id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
13037     <description>
13038       The VM initialization event signals the completion of VM initialization. Once
13039       this event is generated, the agent is free to call any JNI or <jvmti/>
13040       function. The VM initialization event can be preceded by or can be concurrent
13041       with other events, but
13042       the preceding events should be handled carefully, if at all, because the
13043       VM has not completed its initialization. The thread start event for the
13044       main application thread is guaranteed not to occur until after the
13045       handler for the VM initialization event returns.
13046       <p/>
13047       In the case of VM start-up failure, this event will not be sent.
13048     </description>
13049     <origin>jvmdi</origin>
13050     <capabilities>
13051     </capabilities>
13052     <parameters>
13053       <param id="jni_env">
13054         <outptr>
13055           <struct>JNIEnv</struct>
13056         </outptr>
13057           <description>
13058             The JNI environment of the event (current) thread.
13059           </description>
13060       </param>
13061       <param id="thread">
13062         <jthread/>
13063           <description>
13064             The initial thread
13065           </description>
13066       </param>
13067     </parameters>
13068   </event>
13069 
13070   <event label="VM Death Event"
13071          id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
13072     <description>
13073       The VM death event notifies the agent of the termination of the VM.
13074       No events will occur after the VMDeath event.
13075       <p/>
13076       In the case of VM start-up failure, this event will not be sent.
13077       Note that <internallink id="onunload">Agent_OnUnload</internallink>
13078       will still be called in these cases.
13079     </description>
13080     <origin>jvmdi</origin>
13081     <capabilities>
13082     </capabilities>
13083     <parameters>
13084       <param id="jni_env">
13085         <outptr>
13086           <struct>JNIEnv</struct>
13087         </outptr>
13088           <description>
13089             The JNI environment of the event (current) thread
13090           </description>
13091       </param>
13092     </parameters>
13093   </event>
13094 
13095   <event label="Compiled Method Load" phase="start"
13096          id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
13097     <description>
13098       Sent when a method is compiled and loaded into memory by the VM.
13099       If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
13100       If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
13101       followed by a new <code>CompiledMethodLoad</code> event.
13102       Note that a single method may have multiple compiled forms, and that
13103       this event will be sent for each form.
13104       Note also that several methods may be inlined into a single
13105       address range, and that this event will be sent for each method.
13106       <p/>
13107       These events can be sent after their initial occurrence with
13108       <functionlink id="GenerateEvents"></functionlink>.
13109     </description>
13110     <origin>jvmpi</origin>
13111     <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
13112       <field id="start_address">
13113         <vmbuf><void/></vmbuf>
13114         <description>
13115           Starting native address of code corresponding to a location
13116         </description>
13117       </field>
13118       <field id="location">
13119         <jlocation/>
13120         <description>
13121           Corresponding location. See
13122           <functionlink id="GetJLocationFormat"></functionlink>
13123           for the meaning of location.
13124         </description>
13125       </field>
13126     </typedef>
13127     <capabilities>
13128       <required id="can_generate_compiled_method_load_events"></required>
13129     </capabilities>
13130     <parameters>
13131       <param id="klass">
13132         <jclass method="method"/>
13133           <description>
13134             Class of the method being compiled and loaded
13135           </description>
13136       </param>
13137       <param id="method">
13138         <jmethodID class="klass"/>
13139           <description>
13140             Method being compiled and loaded
13141           </description>
13142       </param>
13143       <param id="code_size">
13144         <jint/>
13145         <description>
13146           Size of compiled code
13147         </description>
13148       </param>
13149       <param id="code_addr">
13150         <vmbuf><void/></vmbuf>
13151         <description>
13152           Address where compiled method code is loaded
13153         </description>
13154       </param>
13155       <param id="map_length">
13156         <jint/>
13157         <description>
13158           Number of <typelink id="jvmtiAddrLocationMap"></typelink>
13159           entries in the address map.
13160           Zero if mapping information cannot be supplied.
13161         </description>
13162       </param>
13163       <param id="map">
13164         <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
13165         <description>
13166           Map from native addresses to location.
13167           The native address range of each entry is from
13168           <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
13169           to <code>start_address-1</code> of the next entry.
13170           <code>NULL</code> if mapping information cannot be supplied.
13171         </description>
13172       </param>
13173       <param id="compile_info">
13174         <vmbuf><void/></vmbuf>
13175         <description>
13176           VM-specific compilation information.
13177           The referenced compile information is managed by the VM
13178           and must not depend on the agent for collection.
13179           A VM implementation defines the content and lifetime
13180           of the information.
13181         </description>
13182       </param>
13183     </parameters>
13184   </event>
13185 
13186   <event label="Compiled Method Unload" phase="start"
13187          id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
13188     <description>
13189       Sent when a compiled method is unloaded from memory.
13190       This event might not be sent on the thread which performed the unload.
13191       This event may be sent sometime after the unload occurs, but
13192       will be sent before the memory is reused
13193       by a newly generated compiled method. This event may be sent after
13194       the class is unloaded.
13195     </description>
13196     <origin>jvmpi</origin>
13197     <capabilities>
13198       <required id="can_generate_compiled_method_load_events"></required>
13199     </capabilities>
13200     <parameters>
13201       <param id="klass">
13202         <jclass method="method"/>
13203           <description>
13204             Class of the compiled method being unloaded.
13205           </description>
13206       </param>
13207       <param id="method">
13208         <jmethodID class="klass"/>
13209           <description>
13210             Compiled method being unloaded.
13211             For identification of the compiled method only -- the class
13212             may be unloaded and therefore the method should not be used
13213             as an argument to further JNI or <jvmti/> functions.
13214           </description>
13215       </param>
13216       <param id="code_addr">
13217         <vmbuf><void/></vmbuf>
13218         <description>
13219           Address where compiled method code was loaded.
13220           For identification of the compiled method only --
13221           the space may have been reclaimed.
13222         </description>
13223       </param>
13224     </parameters>
13225   </event>
13226 
13227   <event label="Dynamic Code Generated" phase="any"
13228          id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
13229     <description>
13230       Sent when a component of the virtual machine is generated dynamically.
13231       This does not correspond to Java programming language code that is
13232       compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
13233       This is for native code--for example, an interpreter that is generated
13234       differently depending on command-line options.
13235       <p/>
13236       Note that this event has no controlling capability.
13237       If a VM cannot generate these events, it simply does not send any.
13238       <p/>
13239       These events can be sent after their initial occurrence with
13240       <functionlink id="GenerateEvents"></functionlink>.
13241     </description>
13242     <origin>jvmpi</origin>
13243     <capabilities>
13244     </capabilities>
13245     <parameters>
13246       <param id="name">
13247         <vmbuf><char/></vmbuf>
13248         <description>
13249           Name of the code, encoded as a
13250           <internallink id="mUTF">modified UTF-8</internallink> string.
13251           Intended for display to an end-user.
13252           The name might not be unique.
13253         </description>
13254       </param>
13255       <param id="address">
13256         <vmbuf><void/></vmbuf>
13257         <description>
13258           Native address of the code
13259         </description>
13260       </param>
13261       <param id="length">
13262         <jint/>
13263         <description>
13264           Length in bytes of the code
13265         </description>
13266       </param>
13267     </parameters>
13268   </event>
13269 
13270   <event label="Data Dump Request"
13271          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
13272     <description>
13273       Sent by the VM to request the agent to dump its data.  This
13274       is just a hint and the agent need not react to this event.
13275       This is useful for processing command-line signals from users.  For
13276       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris
13277       causes the VM to send this event to the agent.
13278     </description>
13279     <origin>jvmpi</origin>
13280     <capabilities>
13281     </capabilities>
13282     <parameters>
13283     </parameters>
13284   </event>
13285 
13286   <event label="Monitor Contended Enter"
13287          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
13288     <description>
13289       Sent when a thread is attempting to enter a Java programming language
13290       monitor already acquired by another thread.
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
13309             attempting to enter the monitor
13310           </description>
13311       </param>
13312       <param id="object">
13313         <jobject/>
13314           <description>
13315             JNI local reference to the monitor
13316           </description>
13317       </param>
13318     </parameters>
13319   </event>
13320 
13321   <event label="Monitor Contended Entered"
13322          id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
13323     <description>
13324       Sent when a thread enters a Java programming language
13325       monitor after waiting for it to be released by another thread.
13326     </description>
13327     <origin>jvmpi</origin>
13328     <capabilities>
13329       <required id="can_generate_monitor_events"></required>
13330     </capabilities>
13331     <parameters>
13332       <param id="jni_env">
13333         <outptr>
13334           <struct>JNIEnv</struct>
13335         </outptr>
13336           <description>
13337             The JNI environment of the event (current) thread
13338           </description>
13339       </param>
13340       <param id="thread">
13341         <jthread/>
13342           <description>
13343             JNI local reference to the thread entering
13344             the monitor
13345           </description>
13346       </param>
13347       <param id="object">
13348         <jobject/>
13349           <description>
13350             JNI local reference to the monitor
13351           </description>
13352       </param>
13353     </parameters>
13354   </event>
13355 
13356   <event label="Monitor Wait"
13357          id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
13358     <description>
13359       Sent when a thread is about to wait on an object.
13360     </description>
13361     <origin>jvmpi</origin>
13362     <capabilities>
13363       <required id="can_generate_monitor_events"></required>
13364     </capabilities>
13365     <parameters>
13366       <param id="jni_env">
13367         <outptr>
13368           <struct>JNIEnv</struct>
13369         </outptr>
13370           <description>
13371             The JNI environment of the event (current) thread
13372           </description>
13373       </param>
13374       <param id="thread">
13375         <jthread/>
13376           <description>
13377             JNI local reference to the thread about to wait
13378           </description>
13379       </param>
13380       <param id="object">
13381         <jobject/>
13382           <description>
13383             JNI local reference to the monitor
13384           </description>
13385       </param>
13386       <param id="timeout">
13387         <jlong/>
13388         <description>
13389           The number of milliseconds the thread will wait
13390         </description>
13391       </param>
13392     </parameters>
13393   </event>
13394 
13395   <event label="Monitor Waited"
13396          id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
13397     <description>
13398       Sent when a thread finishes waiting on an object.
13399     </description>
13400     <origin>jvmpi</origin>
13401     <capabilities>
13402       <required id="can_generate_monitor_events"></required>
13403     </capabilities>
13404     <parameters>
13405       <param id="jni_env">
13406         <outptr>
13407           <struct>JNIEnv</struct>
13408         </outptr>
13409           <description>
13410             The JNI environment of the event (current) thread
13411           </description>
13412       </param>
13413       <param id="thread">
13414         <jthread/>
13415           <description>
13416             JNI local reference to the thread that was finished waiting
13417           </description>
13418       </param>
13419       <param id="object">
13420         <jobject/>
13421           <description>
13422             JNI local reference to the monitor.
13423           </description>
13424       </param>
13425       <param id="timed_out">
13426         <jboolean/>
13427         <description>
13428           True if the monitor timed out
13429         </description>
13430       </param>
13431     </parameters>
13432   </event>
13433 
13434   <event label="Resource Exhausted"
13435          id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
13436          since="1.1">
13437     <description>
13438       Sent when a VM resource needed by a running application has been exhausted.
13439       Except as required by the optional capabilities, the set of resources
13440       which report exhaustion is implementation dependent.
13441       <p/>
13442       The following bit flags define the properties of the resource exhaustion:
13443       <constants id="jvmtiResourceExhaustionFlags"
13444                  label="Resource Exhaustion Flags"
13445                  kind="bits"
13446                  since="1.1">
13447         <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
13448           After this event returns, the VM will throw a
13449           <code>java.lang.OutOfMemoryError</code>.
13450         </constant>
13451         <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
13452           The VM was unable to allocate memory from the <tm>Java</tm>
13453           platform <i>heap</i>.
13454           The <i>heap</i> is the runtime
13455           data area from which memory for all class instances and
13456           arrays are allocated.
13457         </constant>
13458         <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
13459           The VM was unable to create a thread.
13460         </constant>
13461       </constants>
13462     </description>
13463     <origin>new</origin>
13464     <capabilities>
13465       <capability id="can_generate_resource_exhaustion_heap_events">
13466         Can generate events when the VM is unable to allocate memory from the
13467         <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
13468       </capability>
13469       <capability id="can_generate_resource_exhaustion_threads_events">
13470         Can generate events when the VM is unable to
13471         <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
13472         a thread</internallink>.
13473       </capability>
13474     </capabilities>
13475     <parameters>
13476       <param id="jni_env">
13477         <outptr>
13478           <struct>JNIEnv</struct>
13479         </outptr>
13480           <description>
13481             The JNI environment of the event (current) thread
13482           </description>
13483       </param>
13484       <param id="flags">
13485         <jint/>
13486         <description>
13487           Flags defining the properties of the of resource exhaustion
13488           as specified by the
13489           <internallink id="jvmtiResourceExhaustionFlags">Resource
13490           Exhaustion Flags</internallink>.
13491           </description>
13492         </param>
13493       <param id="reserved">
13494         <vmbuf><void/></vmbuf>
13495         <description>
13496           Reserved.
13497         </description>
13498       </param>
13499       <param id="description">
13500         <vmbuf><char/></vmbuf>
13501         <description>
13502           Description of the resource exhaustion, encoded as a
13503           <internallink id="mUTF">modified UTF-8</internallink> string.
13504         </description>
13505       </param>
13506     </parameters>
13507   </event>
13508 
13509   <event label="VM Object Allocation"
13510          id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
13511     <description>
13512       Sent when a method causes the virtual machine to directly allocate an
13513       Object visible to Java programming language code.
13514       Generally object allocation should be detected by instrumenting
13515       the bytecodes of allocating methods.
13516       Object allocation generated in native code by JNI function
13517       calls should be detected using
13518       <internallink id="jniIntercept">JNI function interception</internallink>.
13519       Some methods might not have associated bytecodes and are not
13520       native methods, they instead are executed directly by the
13521       VM. These methods should send this event.
13522       Virtual machines which are incapable of bytecode instrumentation
13523       for some or all of their methods can send this event.
13524 
13525       Note that the <internallink
13526       id="SampledObjectAlloc">SampledObjectAlloc</internallink>
13527       event is triggered on all Java object allocations, including those
13528       caused by bytecode method execution, JNI method execution, and
13529       directly by VM methods.
13530       <p/>
13531       Typical examples where this event might be sent:
13532       <ul>
13533         <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
13534         <li>Methods not represented by bytecodes -- for example, VM intrinsics and
13535             J2ME preloaded classes</li>
13536       </ul>
13537       Cases where this event would not be generated:
13538       <ul>
13539         <li>Allocation due to bytecodes -- for example, the <code>new</code>
13540             and <code>newarray</code> VM instructions</li>
13541         <li>Allocation due to JNI function calls -- for example,
13542             <code>AllocObject</code></li>
13543         <li>Allocations during VM initialization</li>
13544         <li>VM internal objects</li>
13545       </ul>
13546     </description>
13547     <origin>new</origin>
13548     <capabilities>
13549       <required id="can_generate_vm_object_alloc_events"></required>
13550     </capabilities>
13551     <parameters>
13552       <param id="jni_env">
13553         <outptr>
13554           <struct>JNIEnv</struct>
13555         </outptr>
13556           <description>
13557             The JNI environment of the event (current) thread
13558           </description>
13559       </param>
13560       <param id="thread">
13561         <jthread/>
13562           <description>
13563             Thread allocating the object.
13564           </description>
13565       </param>
13566       <param id="object">
13567         <jobject/>
13568           <description>
13569             JNI local reference to the object that was allocated.
13570           </description>
13571       </param>
13572       <param id="object_klass">
13573         <jclass/>
13574           <description>
13575             JNI local reference to the class of the object.
13576           </description>
13577       </param>
13578       <param id="size">
13579         <jlong/>
13580         <description>
13581             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13582         </description>
13583       </param>
13584     </parameters>
13585   </event>
13586 
13587   <event label="Sampled Object Allocation"
13588     id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" filtered="thread" num="86" since="11">
13589     <description>
13590       Sent when an allocated object is sampled.
13591       By default, the sampling interval is set to 512KB. The sampling is semi-random to avoid
13592       pattern-based bias and provides an approximate overall average interval over long periods of
13593       sampling.
13594       <p/>
13595       Each thread tracks how many bytes it has allocated since it sent the last event.
13596       When the number of bytes exceeds the sampling interval, it will send another event.
13597       This implies that, on average, one object will be sampled every time a thread has
13598       allocated 512KB bytes since the last sample.
13599       <p/>
13600       Note that the sampler is pseudo-random: it will not sample every 512KB precisely.
13601       The goal of this is to ensure high quality sampling even if allocation is
13602       happening in a fixed pattern (i.e., the same set of objects are being allocated
13603       every 512KB).
13604       <p/>
13605       If another sampling interval is required, the user can call
13606       <functionlink id="SetHeapSamplingInterval"></functionlink> with a strictly positive integer value,
13607       representing the new sampling interval.
13608       <p/>
13609       This event is sent once the sampled allocation has been performed.  It provides the object, stack trace
13610       of the allocation, the thread allocating, the size of allocation, and the object's class.
13611       <p/>
13612       A typical use case of this system is to determine where heap allocations originate.
13613       In conjunction with weak references and the function
13614       <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
13615       stack trace, and which are still live during the execution of the program.
13616     </description>
13617     <origin>new</origin>
13618     <capabilities>
13619       <required id="can_generate_sampled_object_alloc_events"></required>
13620     </capabilities>
13621     <parameters>
13622       <param id="jni_env">
13623         <outptr>
13624           <struct>JNIEnv</struct>
13625         </outptr>
13626         <description>
13627           The JNI environment of the event (current) thread.
13628         </description>
13629       </param>
13630       <param id="thread">
13631         <jthread/>
13632         <description>
13633           Thread allocating the object.
13634         </description>
13635       </param>
13636       <param id="object">
13637         <jobject/>
13638         <description>
13639           JNI local reference to the object that was allocated.
13640         </description>
13641       </param>
13642       <param id="object_klass">
13643         <jclass/>
13644         <description>
13645           JNI local reference to the class of the object
13646         </description>
13647       </param>
13648       <param id="size">
13649         <jlong/>
13650         <description>
13651           Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13652         </description>
13653       </param>
13654     </parameters>
13655   </event>
13656 
13657   <event label="Object Free"
13658         id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
13659     <description>
13660       An Object Free event is sent when the garbage collector frees an object.
13661       Events are only sent for tagged objects--see
13662       <internallink id="Heap">heap functions</internallink>.
13663       <p/>
13664       The event handler must not use JNI functions and
13665       must not use <jvmti/> functions except those which
13666       specifically allow such use (see the raw monitor, memory management,
13667       and environment local storage functions).
13668     </description>
13669     <origin>new</origin>
13670     <capabilities>
13671       <required id="can_generate_object_free_events"></required>
13672     </capabilities>
13673     <parameters>
13674       <param id="tag">
13675         <jlong/>
13676         <description>
13677           The freed object's tag
13678         </description>        
13679       </param>
13680     </parameters>
13681   </event>
13682 
13683   <event label="Garbage Collection Start"
13684          id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
13685     <description>
13686       A Garbage Collection Start event is sent when a
13687       garbage collection pause begins.
13688       Only stop-the-world collections are reported--that is, collections during
13689       which all threads cease to modify the state of the Java virtual machine.
13690       This means that some collectors will never generate these events.
13691       This event is sent while the VM is still stopped, thus
13692       the event handler must not use JNI functions and
13693       must not use <jvmti/> functions except those which
13694       specifically allow such use (see the raw monitor, memory management,
13695       and environment local storage functions).
13696       <p/>
13697       This event is always sent as a matched pair with
13698       <eventlink id="GarbageCollectionFinish"/>
13699       (assuming both events are enabled) and no garbage collection
13700       events will occur between them.
13701     </description>
13702     <origin>new</origin>
13703     <capabilities>
13704       <required id="can_generate_garbage_collection_events"></required>
13705     </capabilities>
13706     <parameters>
13707     </parameters>
13708   </event>
13709 
13710   <event label="Garbage Collection Finish"
13711          id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
13712     <description>
13713       A Garbage Collection Finish event is sent when a
13714       garbage collection pause ends.
13715       This event is sent while the VM is still stopped, thus
13716       the event handler must not use JNI functions and
13717       must not use <jvmti/> functions except those which
13718       specifically allow such use (see the raw monitor, memory management,
13719       and environment local storage functions).
13720       <p/>
13721       Some agents may need to do post garbage collection operations that
13722       require the use of the disallowed <jvmti/> or JNI functions. For these
13723       cases an agent thread can be created which waits on a raw monitor,
13724       and the handler for the Garbage Collection Finish event simply
13725       notifies the raw monitor
13726       <p/>
13727       This event is always sent as a matched pair with
13728       <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
13729       <issue>
13730         The most important use of this event is to provide timing information,
13731         and thus additional information is not required.  However,
13732         information about the collection which is "free" should be included -
13733         what that information is needs to be determined.
13734       </issue>
13735     </description>
13736     <origin>new</origin>
13737     <capabilities>
13738       <required id="can_generate_garbage_collection_events"></required>
13739     </capabilities>
13740     <parameters>
13741     </parameters>
13742   </event>
13743 
13744   <elide>
13745   <event label="Verbose Output" phase="any"
13746          id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
13747     <description>
13748       Send verbose messages as strings.
13749         <issue>
13750           This format is extremely fragile, as it can change with each
13751           platform, collector and version.  Alternatives include:
13752           <ul>
13753             <li>building off Java programming language M and M APIs</li>
13754             <li>XML</li>
13755             <li>key/value pairs</li>
13756             <li>removing it</li>
13757           </ul>
13758         </issue>
13759         <issue>
13760           Though this seemed trivial to implement.
13761           In the RI it appears this will be quite complex.
13762         </issue>
13763     </description>
13764     <origin>new</origin>
13765     <capabilities>
13766     </capabilities>
13767     <parameters>
13768       <param id="flag">
13769         <enum>jvmtiVerboseFlag</enum>
13770         <description>
13771           Which verbose output is being sent.
13772         </description>
13773       </param>
13774       <param id="message">
13775         <vmbuf><char/></vmbuf>
13776         <description>
13777           Message text, encoded as a
13778           <internallink id="mUTF">modified UTF-8</internallink> string.
13779         </description>
13780       </param>
13781     </parameters>
13782   </event>
13783   </elide>
13784 
13785 </eventsection>
13786 
13787 <datasection>
13788   <intro>
13789     <jvmti/> extends the data types defined by JNI.
13790   </intro>
13791   <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
13792     <basetype id="jboolean">
13793       <description>
13794         Holds a Java programming language <code>boolean</code>.
13795         Unsigned 8 bits.
13796       </description>
13797     </basetype>
13798     <basetype id="jchar">
13799       <description>
13800         Holds a Java programming language <code>char</code>.
13801         Unsigned 16 bits.
13802       </description>
13803     </basetype>
13804     <basetype id="jint">
13805       <description>
13806         Holds a Java programming language <code>int</code>.
13807         Signed 32 bits.
13808       </description>
13809     </basetype>
13810     <basetype id="jlong">
13811       <description>
13812         Holds a Java programming language <code>long</code>.
13813         Signed 64 bits.
13814       </description>
13815     </basetype>
13816     <basetype id="jfloat">
13817       <description>
13818         Holds a Java programming language <code>float</code>.
13819         32 bits.
13820       </description>
13821     </basetype>
13822     <basetype id="jdouble">
13823       <description>
13824         Holds a Java programming language <code>double</code>.
13825         64 bits.
13826       </description>
13827     </basetype>
13828     <basetype id="jobject">
13829       <description>
13830         Holds a Java programming language object.
13831       </description>
13832     </basetype>
13833     <basetype id="jclass">
13834       <description>
13835         Holds a Java programming language class.
13836       </description>
13837     </basetype>
13838     <basetype id="jvalue">
13839       <description>
13840         Is a union of all primitive types and <code>jobject</code>.  Thus, holds any Java
13841         programming language value.
13842       </description>
13843     </basetype>
13844     <basetype id="jfieldID">
13845       <description>
13846         Identifies a Java programming language field.
13847         <code>jfieldID</code>s returned by <jvmti/> functions and events may be
13848         safely stored.
13849       </description>
13850     </basetype>
13851     <basetype id="jmethodID">
13852       <description>
13853         Identifies a Java programming language method, initializer, or constructor.
13854         <code>jmethodID</code>s returned by <jvmti/> functions and events may be
13855         safely stored.  However, if the class is unloaded, they become invalid
13856         and must not be used.
13857       </description>
13858     </basetype>
13859     <basetype id="JNIEnv">
13860       <description>
13861         Pointer to the JNI function table.  Pointer to this (<code>JNIEnv *</code>)
13862         is a JNI environment.
13863       </description>
13864     </basetype>
13865   </basetypes>
13866 
13867   <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
13868     <basetype id="jvmtiEnv">
13869       <description>
13870         The <jvmti/> <internallink id="environments">environment</internallink> pointer.
13871         See the <internallink id="FunctionSection">Function Section</internallink>.
13872         <code>jvmtiEnv</code> points to the
13873         <internallink id="FunctionTable">function table</internallink> pointer.
13874       </description>
13875     </basetype>
13876     <basetype id="jthread">
13877       <definition>typedef jobject jthread;</definition>
13878       <description>
13879         Subtype of <datalink id="jobject"></datalink> that holds a thread.
13880       </description>
13881     </basetype>
13882     <basetype id="jthreadGroup">
13883       <definition>typedef jobject jthreadGroup;</definition>
13884       <description>
13885         Subtype of <datalink id="jobject"></datalink> that holds a thread group.
13886       </description>
13887     </basetype>
13888     <basetype id="jlocation">
13889       <definition>typedef jlong jlocation;</definition>
13890       <description>
13891         A 64 bit value, representing a monotonically increasing
13892         executable position within a method.
13893         <code>-1</code> indicates a native method.
13894         See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
13895         given VM.
13896       </description>
13897     </basetype>
13898     <basetype id="jrawMonitorID">
13899       <definition>struct _jrawMonitorID;
13900 typedef struct _jrawMonitorID *jrawMonitorID;</definition>
13901       <description>
13902         A raw monitor.
13903       </description>
13904     </basetype>
13905     <basetype id="jvmtiError">
13906       <description>
13907         Holds an error return code.
13908         See the <internallink id="ErrorSection">Error section</internallink> for possible values.
13909         <example>
13910 typedef enum {
13911     JVMTI_ERROR_NONE = 0,
13912     JVMTI_ERROR_INVALID_THREAD = 10,
13913       ...
13914 } jvmtiError;
13915 </example>
13916       </description>
13917     </basetype>
13918     <basetype id="jvmtiEvent">
13919       <description>
13920         An identifier for an event type.
13921         See the <internallink id="EventSection">Event section</internallink> for possible values.
13922         It is guaranteed that future versions of this specification will
13923         never assign zero as an event type identifier.
13924 <example>
13925 typedef enum {
13926     JVMTI_EVENT_SINGLE_STEP = 1,
13927     JVMTI_EVENT_BREAKPOINT = 2,
13928       ...
13929 } jvmtiEvent;
13930 </example>
13931       </description>
13932     </basetype>
13933     <basetype id="jvmtiEventCallbacks" name="eventCallbacks">
13934       <description>
13935         The callbacks used for events.
13936 <example>
13937 typedef struct {
13938     jvmtiEventVMInit VMInit;
13939     jvmtiEventVMDeath VMDeath;
13940       ...
13941 } jvmtiEventCallbacks;
13942 </example>
13943         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink>
13944         for the complete structure.
13945         <p/>
13946         Where, for example, the VM initialization callback is defined:
13947 <example>
13948 typedef void (JNICALL *jvmtiEventVMInit)
13949     (jvmtiEnv *jvmti_env,
13950      JNIEnv* jni_env,
13951      jthread thread);
13952 </example>
13953         See the individual events for the callback function definition.
13954       </description>
13955     </basetype>
13956     <basetype id="jniNativeInterface">
13957       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
13958       <description>
13959         Typedef for the JNI function table <code>JNINativeInterface</code>
13960         defined in the
13961         <externallink id="jni/functions.html#interface-function-table">
13962           JNI Specification</externallink>.
13963         The JNI reference implementation defines this with an underscore.
13964       </description>
13965     </basetype>
13966   </basetypes>
13967 
13968 </datasection>
13969 
13970 <issuessection label="Issues">
13971   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
13972     JVMDI requires that the agent suspend threads before calling
13973     certain sensitive functions.  JVMPI requires garbage collection to be
13974     disabled before calling certain sensitive functions.
13975     It was suggested that rather than have this requirement, that
13976     VM place itself in a suitable state before performing an
13977     operation.  This makes considerable sense since each VM
13978     knows its requirements and can most easily arrange a
13979     safe state.
13980     <p/>
13981     The ability to externally suspend/resume threads will, of
13982     course, remain.  The ability to enable/disable garbage collection will not.
13983     <p/>
13984     This issue is resolved--suspend will not
13985     be required.  The spec has been updated to reflect this.
13986   </intro>
13987 
13988   <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
13989     There are a variety of approaches to sampling call stacks.
13990     The biggest bifurcation is between VM controlled and agent
13991     controlled.
13992     <p/>
13993     This issue is resolved--agent controlled
13994     sampling will be the approach.
13995   </intro>
13996 
13997   <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
13998     JVMDI represents threads as jthread.  JVMPI primarily
13999     uses JNIEnv* to represent threads.
14000     <p/>
14001     The Expert Group has chosen jthread as the representation
14002     for threads in <jvmti/>.
14003     JNIEnv* is sent by
14004     events since it is needed to JNI functions.  JNIEnv, per the
14005     JNI spec, are not supposed to be used outside their thread.
14006   </intro>
14007 
14008   <intro id="design" label="Resolved Issue: Method Representation">
14009     The JNI spec allows an implementation to depend on jclass/jmethodID
14010     pairs, rather than simply a jmethodID, to reference a method.
14011     JVMDI, for consistency, choose the same representation.
14012     JVMPI, however, specifies that a jmethodID alone maps to a
14013     method.  Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
14014     pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
14015     In fact, any JVM implementation that supports JVMPI must have
14016     such a representation.
14017     <jvmti/> will use jmethodID as a unique representation of a method
14018     (no jclass is used).
14019     There should be efficiency gains, particularly in
14020     functionality like stack dumping, to this representation.
14021     <p/>
14022     Note that fields were not used in JVMPI and that the access profile
14023     of fields differs from methods--for implementation efficiency
14024     reasons, a jclass/jfieldID pair will still be needed for field
14025     reference.
14026   </intro>
14027 
14028   <intro id="localReferenceIssue" label="Resolved Issue: Local References">
14029     Functions return local references.
14030   </intro>
14031 
14032   <intro id="frameRep" label="Resolved Issue: Representation of frames">
14033     In JVMDI, a frame ID is used to represent a frame.  Problem with this
14034     is that a VM must track when a frame becomes invalid, a far better
14035     approach, and the one used in <jvmti/>, is to reference frames by depth.
14036   </intro>
14037 
14038   <intro id="requiredCapabilities" label="Issue: Required Capabilities">
14039     Currently, having a required capabilities means that the functionality
14040     is optional.   Capabilities are useful even for required functionality
14041     since they can inform the VM is needed set-up.  Thus, there should be
14042     a set of capabilities that a conformant implementation must provide
14043     (if requested during Agent_OnLoad).
14044   </intro>
14045 
14046   <intro id="taghint" label="Proposal: add tag hint function">
14047     A hint of the percentage of objects that will be tagged would
14048     help the VM pick a good implementation.
14049   </intro>
14050 
14051   <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
14052   How difficult or easy would be to extend the monitor_info category to include
14053     <pre>
14054   - current number of monitors
14055   - enumeration of monitors
14056   - enumeration of threads waiting on a given monitor
14057     </pre>
14058   The reason for my question is the fact that current get_monitor_info support
14059   requires the agent to specify a given thread to get the info which is probably
14060   OK in the profiling/debugging space, while in the monitoring space the agent
14061   could be watching the monitor list and then decide which thread to ask for
14062   the info. You might ask why is this important for monitoring .... I think it
14063   can aid in the detection/prediction of application contention caused by hot-locks.
14064   </intro>
14065 </issuessection>
14066 
14067 <changehistory id="ChangeHistory" update="09/05/07">
14068   <intro>
14069     The <jvmti/> specification is an evolving document with major, minor,
14070     and micro version numbers.
14071     A released version of the specification is uniquely identified
14072     by its major and minor version.
14073     The functions, events, and capabilities in this specification
14074     indicate a "Since" value which is the major and minor version in
14075     which it was introduced.
14076     The version of the specification implemented by the VM can
14077     be retrieved at runtime with the <functionlink id="GetVersionNumber"/>
14078     function.
14079   </intro>
14080   <change date="14 Nov 2002">
14081     Converted to XML document.
14082   </change>
14083   <change date="14 Nov 2002">
14084     Elided heap dump functions (for now) since what was there
14085     was wrong.
14086   </change>
14087   <change date="18 Nov 2002">
14088     Added detail throughout.
14089   </change>
14090   <change date="18 Nov 2002">
14091     Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
14092   </change>
14093   <change date="19 Nov 2002">
14094     Added AsyncGetStackTrace.
14095   </change>
14096   <change date="19 Nov 2002">
14097     Added jframeID return to GetStackTrace.
14098   </change>
14099   <change date="19 Nov 2002">
14100     Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
14101     since they are redundant with GetStackTrace.
14102   </change>
14103   <change date="19 Nov 2002">
14104     Elided ClearAllBreakpoints since it has always been redundant.
14105   </change>
14106   <change date="19 Nov 2002">
14107     Added GetSystemProperties.
14108   </change>
14109   <change date="19 Nov 2002">
14110     Changed the thread local storage functions to use jthread.
14111   </change>
14112   <change date="20 Nov 2002">
14113     Added GetJLocationFormat.
14114   </change>
14115   <change date="22 Nov 2002">
14116     Added events and introductory text.
14117   </change>
14118   <change date="22 Nov 2002">
14119     Cross reference type and constant definitions.
14120   </change>
14121   <change date="24 Nov 2002">
14122     Added DTD.
14123   </change>
14124   <change date="24 Nov 2002">
14125     Added capabilities function section.
14126   </change>
14127   <change date="29 Nov 2002">
14128     Assign capabilities to each function and event.
14129   </change>
14130   <change date="29 Nov 2002">
14131     Add <internallink id="jniIntercept">JNI interception functions</internallink>.
14132   </change>
14133   <change date="30 Nov 2002">
14134     Auto generate SetEventNotificationMode capabilities.
14135   </change>
14136   <change date="30 Nov 2002">
14137     Add <eventlink id="VMObjectAlloc"></eventlink> event.
14138   </change>
14139   <change date="30 Nov 2002">
14140     Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
14141   </change>
14142   <change date="30 Nov 2002">
14143     Add const to declarations.
14144   </change>
14145   <change date="30 Nov 2002">
14146     Change method exit and frame pop to send on exception.
14147   </change>
14148   <change date="1 Dec 2002">
14149     Add ForceGarbageCollection.
14150   </change>
14151   <change date="2 Dec 2002">
14152     Redo Xrun section; clarify GetStackTrace and add example;
14153     Fix width problems; use "agent" consistently.
14154   </change>
14155   <change date="8 Dec 2002">
14156     Remove previous start-up intro.
14157     Add <internallink id="environments"><jvmti/> Environments</internallink>
14158     section.
14159   </change>
14160   <change date="8 Dec 2002">
14161     Add <functionlink id="DisposeEnvironment"></functionlink>.
14162   </change>
14163   <change date="9 Dec 2002">
14164     Numerous minor updates.
14165   </change>
14166   <change date="15 Dec 2002">
14167     Add heap profiling functions added:
14168     get/set annotation, iterate live objects/heap.
14169     Add heap profiling functions place holder added:
14170     heap roots.
14171     Heap profiling event added: object free.
14172     Heap profiling event redesigned: vm object allocation.
14173     Heap profiling event placeholders added: garbage collection start/finish.
14174     Native method bind event added.
14175   </change>
14176   <change date="19 Dec 2002">
14177     Revamp suspend/resume functions.
14178     Add origin information with jvmdi tag.
14179     Misc fixes.
14180   </change>
14181   <change date="24 Dec 2002">
14182     Add semantics to types.
14183   </change>
14184   <change date="27 Dec 2002">
14185     Add local reference section.
14186     Autogenerate parameter descriptions from types.
14187   </change>
14188   <change date="28 Dec 2002">
14189     Document that RunAgentThread sends threadStart.
14190   </change>
14191   <change date="29 Dec 2002">
14192     Remove redundant local ref and dealloc warning.
14193     Convert GetRawMonitorName to allocated buffer.
14194     Add GenerateEvents.
14195   </change>
14196   <change date="30 Dec 2002">
14197     Make raw monitors a type and rename to "jrawMonitorID".
14198   </change>
14199   <change date="1 Jan 2003">
14200     Include origin information.
14201     Clean-up JVMDI issue references.
14202     Remove Deallocate warnings which are now automatically generated.
14203   </change>
14204   <change date="2 Jan 2003">
14205     Fix representation issues for jthread.
14206   </change>
14207   <change date="3 Jan 2003">
14208     Make capabilities buffered out to 64 bits - and do it automatically.
14209   </change>
14210   <change date="4 Jan 2003">
14211     Make constants which are enumeration into enum types.
14212     Parameters now of enum type.
14213     Clean-up and index type section.
14214     Replace remaining datadef entities with callback.
14215   </change>
14216   <change date="7 Jan 2003">
14217     Correct GenerateEvents description.
14218     More internal semantics work.
14219   </change>
14220   <change date="9 Jan 2003">
14221     Replace previous GetSystemProperties with two functions
14222     which use allocated information instead fixed.
14223     Add SetSystemProperty.
14224     More internal semantics work.
14225   </change>
14226   <change date="12 Jan 2003">
14227     Add varargs to end of SetEventNotificationMode.
14228   </change>
14229   <change date="20 Jan 2003">
14230     Finish fixing spec to reflect that alloc sizes are jlong.
14231   </change>
14232   <change date="22 Jan 2003">
14233     Allow NULL as RunAgentThread arg.
14234   </change>
14235   <change date="22 Jan 2003">
14236     Fixed names to standardized naming convention
14237     Removed AsyncGetStackTrace.
14238   </change>
14239   <change date="29 Jan 2003">
14240     Since we are using jthread, removed GetThread.
14241   </change>
14242   <change date="31 Jan 2003">
14243     Change GetFieldName to allow NULLs like GetMethodName.
14244   </change>
14245   <change date="29 Feb 2003" version="v40">
14246       Rewrite the introductory text, adding sections on
14247       start-up, environments and bytecode instrumentation.
14248       Change the command line arguments per EG discussions.
14249       Add an introduction to the capabilities section.
14250       Add the extension mechanism category and functions.
14251       Mark for deletion, but clarified anyhow, SuspendAllThreads.
14252       Rename IterateOverLiveObjects to IterateOverReachableObjects and
14253       change the text accordingly.
14254       Clarify IterateOverHeap.
14255       Clarify CompiledMethodLoad.
14256       Discuss prerequisite state for Calling Functions.
14257       Clarify SetAllocationHooks.
14258       Added issues ("To be resolved:") through-out.
14259       And so on...
14260   </change>
14261   <change date="6 Mar 2003" version="v41">
14262       Remove struct from the call to GetOwnedMonitorInfo.
14263       Automatically generate most error documentation, remove
14264       (rather broken) hand written error doc.
14265       Better describe capability use (empty initial set).
14266       Add min value to jint params.
14267       Remove the capability can_access_thread_local_storage.
14268       Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
14269       same for *NOT_IMPLEMENTED.
14270       Description fixes.
14271   </change>
14272   <change date="8 Mar 2003" version="v42">
14273       Rename GetClassSignature to GetClassName.
14274       Rename IterateOverClassObjects to IterateOverInstancesOfClass.
14275       Remove GetMaxStack (operand stack isn't used in <jvmti/>).
14276       Description fixes: define launch-time, remove native frame pop
14277       from PopFrame, and assorted clarifications.
14278   </change>
14279   <change date="8 Mar 2003" version="v43">
14280       Fix minor editing problem.
14281   </change>
14282   <change date="10 Mar 2003" version="v44">
14283       Add phase information.
14284       Remap (compact) event numbers.
14285   </change>
14286   <change date="11 Mar 2003" version="v45">
14287       More phase information - allow "any".
14288       Elide raw monitor queries and events.
14289       Minor description fixes.
14290   </change>
14291   <change date="12 Mar 2003" version="v46">
14292       Add GetPhase.
14293       Use "phase" through document.
14294       Elide GetRawMonitorName.
14295       Elide GetObjectMonitors.
14296   </change>
14297   <change date="12 Mar 2003" version="v47">
14298       Fixes from link, XML, and spell checking.
14299       Auto-generate the callback structure.
14300   </change>
14301   <change date="13 Mar 2003" version="v48">
14302       One character XML fix.
14303   </change>
14304   <change date="13 Mar 2003" version="v49">
14305       Change function parameter names to be consistent with
14306       event parameters (fooBarBaz becomes foo_bar_baz).
14307   </change>
14308   <change date="14 Mar 2003" version="v50">
14309       Fix broken link.  Fix thread markers.
14310   </change>
14311   <change date="14 Mar 2003" version="v51">
14312       Change constants so they are under 128 to workaround
14313       compiler problems.
14314   </change>
14315   <change date="23 Mar 2003" version="v52">
14316       Overhaul capabilities.  Separate GetStackTrace into
14317       GetStackTrace and GetStackFrames.
14318   </change>
14319   <change date="8 Apr 2003" version="v54">
14320       Use depth instead of jframeID to reference frames.
14321       Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
14322       Remove frame arg from events.
14323   </change>
14324   <change date="9 Apr 2003" version="v55">
14325       Remove GetObjectWithAnnotation since tests show bufferred approach more efficient.
14326       Add missing annotation_count to GetObjectsWithAnnotations
14327   </change>
14328   <change date="10 Apr 2003" version="v56">
14329       Remove confusing parenthetical statement in GetObjectsWithAnnotations
14330   </change>
14331   <change date="13 Apr 2003" version="v58">
14332       Replace jclass/jmethodID representation of method with simply jmethodID;
14333       Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
14334       Replace can_access_frames with can_access_local_variables; remove from purely stack access.
14335       Use can_get_synthetic_attribute; fix description.
14336       Clarify that zero length arrays must be deallocated.
14337       Clarify RelinquishCapabilities.
14338       Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
14339   </change>
14340   <change date="27 Apr 2003" version="v59">
14341       Remove lingering indirect references to OBSOLETE_METHOD_ID.
14342   </change>
14343   <change date="4 May 2003" version="v60">
14344       Allow DestroyRawMonitor during OnLoad.
14345   </change>
14346   <change date="7 May 2003" version="v61">
14347       Added not monitor owner error return to DestroyRawMonitor.
14348   </change>
14349   <change date="13 May 2003" version="v62">
14350       Clarify semantics of raw monitors.
14351       Change flags on <code>GetThreadStatus</code>.
14352       <code>GetClassLoader</code> return NULL for the bootstrap class loader.
14353       Add <code>GetClassName</code> issue.
14354       Define local variable signature.
14355       Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
14356       Remove over specification in <code>GetObjectsWithAnnotations</code>.
14357       Elide <code>SetAllocationHooks</code>.
14358       Elide <code>SuspendAllThreads</code>.
14359   </change>
14360   <change date="14 May 2003" version="v63">
14361       Define the data type <code>jvmtiEventCallbacks</code>.
14362       Zero length allocations return NULL.
14363       Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.
14364       Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
14365   </change>
14366   <change date="15 May 2003" version="v64">
14367       Better wording, per review.
14368   </change>
14369   <change date="15 May 2003" version="v65">
14370       First Alpha.
14371       Make jmethodID and jfieldID unique, jclass not used.
14372   </change>
14373   <change date="27 May 2003" version="v66">
14374       Fix minor XSLT errors.
14375   </change>
14376   <change date="13 June 2003" version="v67">
14377       Undo making jfieldID unique (jmethodID still is).
14378   </change>
14379   <change date="17 June 2003" version="v68">
14380       Changes per June 11th Expert Group meeting --
14381       Overhaul Heap functionality: single callback,
14382       remove GetHeapRoots, add reachable iterators,
14383       and rename "annotation" to "tag".
14384       NULL thread parameter on most functions is current
14385       thread.
14386       Add timers.
14387       Remove ForceExit.
14388       Add GetEnvironmentLocalStorage.
14389       Add verbose flag and event.
14390       Add AddToBootstrapClassLoaderSearch.
14391       Update ClassFileLoadHook.
14392   </change>
14393   <change date="18 June 2003" version="v69">
14394       Clean up issues sections.
14395       Rename GetClassName back to GetClassSignature and
14396       fix description.
14397       Add generic signature to GetClassSignature,
14398       GetFieldSignature, GetMethodSignature, and
14399       GetLocalVariableTable.
14400       Elide EstimateCostOfCapabilities.
14401       Clarify that the system property functions operate
14402       on the VM view of system properties.
14403       Clarify Agent_OnLoad.
14404       Remove "const" from JNIEnv* in events.
14405       Add metadata accessors.
14406   </change>
14407   <change date="18 June 2003" version="v70">
14408       Add start_depth to GetStackTrace.
14409       Move system properties to a new category.
14410       Add GetObjectSize.
14411       Remove "X" from command line flags.
14412       XML, HTML, and spell check corrections.
14413   </change>
14414   <change date="19 June 2003" version="v71">
14415       Fix JVMTI_HEAP_ROOT_THREAD to be 6.
14416       Make each synopsis match the function name.
14417       Fix unclear wording.
14418   </change>
14419   <change date="26 June 2003" version="v72">
14420       SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
14421       to be set to NULL.
14422       NotifyFramePop, GetFrameLocationm and all the local variable operations
14423       needed to have their wording about frames fixed.
14424       Grammar and clarity need to be fixed throughout.
14425       Capitalization and puntuation need to be consistent.
14426       Need micro version number and masks for accessing major, minor, and micro.
14427       The error code lists should indicate which must be returned by
14428       an implementation.
14429       The command line properties should be visible in the properties functions.
14430       Disallow popping from the current thread.
14431       Allow implementations to return opaque frame error when they cannot pop.
14432       The NativeMethodBind event should be sent during any phase.
14433       The DynamicCodeGenerated event should be sent during any phase.
14434       The following functions should be allowed to operate before VMInit:
14435         Set/GetEnvironmentLocalStorage
14436         GetMethodDeclaringClass
14437         GetClassSignature
14438         GetClassModifiers
14439         IsInterface
14440         IsArrayClass
14441         GetMethodName
14442         GetMethodModifiers
14443         GetMaxLocals
14444         GetArgumentsSize
14445         GetLineNumberTable
14446         GetMethodLocation
14447         IsMethodNative
14448         IsMethodSynthetic.
14449       Other changes (to XSL):
14450       Argument description should show asterisk after not before pointers.
14451       NotifyFramePop, GetFrameLocationm and all the local variable operations
14452       should hsve the NO_MORE_FRAMES error added.
14453       Not alive threads should have a different error return than invalid thread.
14454   </change>
14455   <change date="7 July 2003" version="v73">
14456       VerboseOutput event was missing message parameter.
14457       Minor fix-ups.
14458   </change>
14459   <change date="14 July 2003" version="v74">
14460       Technical Publications Department corrections.
14461       Allow thread and environment local storage to be set to NULL.
14462   </change>
14463   <change date="23 July 2003" version="v75">
14464       Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
14465       Add JNICALL to callbacks (XSL).
14466       Document JNICALL requirement for both events and callbacks (XSL).
14467       Restrict RedefineClasses to methods and attributes.
14468       Elide the VerboseOutput event.
14469       VMObjectAlloc: restrict when event is sent and remove method parameter.
14470       Finish loose ends from Tech Pubs edit.
14471   </change>
14472   <change date="24 July 2003" version="v76">
14473       Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
14474   </change>
14475   <change date="24 July 2003" version="v77">
14476       XML fixes.
14477       Minor text clarifications and corrections.
14478   </change>
14479   <change date="24 July 2003" version="v78">
14480       Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
14481       Clarify that stack frames are JVM Spec frames.
14482       Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
14483       and can_get_source_debug_extension.
14484       PopFrame cannot have a native calling method.
14485       Removed incorrect statement in GetClassloaderClasses
14486       (see <vmspec chapter="4.4"/>).
14487   </change>
14488   <change date="24 July 2003" version="v79">
14489       XML and text fixes.
14490       Move stack frame description into Stack Frame category.
14491   </change>
14492   <change date="26 July 2003" version="v80">
14493       Allow NULL (means bootstrap loader) for GetClassloaderClasses.
14494       Add new heap reference kinds for references from classes.
14495       Add timer information struct and query functions.
14496       Add AvailableProcessors.
14497       Rename GetOtherThreadCpuTime to GetThreadCpuTime.
14498       Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
14499       to SetEventNotification mode.
14500       Add initial thread to the VM_INIT event.
14501       Remove platform assumptions from AddToBootstrapClassLoaderSearch.
14502   </change>
14503   <change date="26 July 2003" version="v81">
14504       Grammar and clarity changes per review.
14505   </change>
14506   <change date="27 July 2003" version="v82">
14507       More grammar and clarity changes per review.
14508       Add Agent_OnUnload.
14509   </change>
14510   <change date="28 July 2003" version="v83">
14511       Change return type of Agent_OnUnload to void.
14512   </change>
14513   <change date="28 July 2003" version="v84">
14514       Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
14515   </change>
14516   <change date="28 July 2003" version="v85">
14517       Steal java.lang.Runtime.availableProcessors() wording for
14518       AvailableProcessors().
14519       Guarantee that zero will never be an event ID.
14520       Remove some issues which are no longer issues.
14521       Per review, rename and more completely document the timer
14522       information functions.
14523   </change>
14524   <change date="29 July 2003" version="v86">
14525       Non-spec visible change to XML controlled implementation:
14526         SetThreadLocalStorage must run in VM mode.
14527   </change>
14528   <change date="5 August 2003" version="0.1.87">
14529       Add GetErrorName.
14530       Add varargs warning to jvmtiExtensionEvent.
14531       Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
14532       Remove unused can_get_exception_info capability.
14533       Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
14534       Fix jvmtiExtensionFunctionInfo.func declared type.
14535       Extension function returns error code.
14536       Use new version numbering.
14537   </change>
14538   <change date="5 August 2003" version="0.2.88">
14539       Remove the ClassUnload event.
14540   </change>
14541   <change date="8 August 2003" version="0.2.89">
14542       Heap reference iterator callbacks return an enum that
14543       allows outgoing object references to be ignored.
14544       Allow JNIEnv as a param type to extension events/functions.
14545   </change>
14546   <change date="15 August 2003" version="0.2.90">
14547       Fix a typo.
14548   </change>
14549   <change date="2 September 2003" version="0.2.91">
14550       Remove all metadata functions: GetClassMetadata,
14551       GetFieldMetadata, and GetMethodMetadata.
14552   </change>
14553   <change date="1 October 2003" version="0.2.92">
14554       Mark the functions Allocate. Deallocate, RawMonitor*,
14555       SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage
14556       as safe for use in heap callbacks and GC events.
14557   </change>
14558   <change date="24 November 2003" version="0.2.93">
14559       Add pass through opaque user data pointer to heap iterate
14560       functions and callbacks.
14561       In the CompiledMethodUnload event, send the code address.
14562       Add GarbageCollectionOccurred event.
14563       Add constant pool reference kind.
14564       Mark the functions CreateRawMonitor and DestroyRawMonitor
14565       as safe for use in heap callbacks and GC events.
14566       Clarify: VMDeath, GetCurrentThreadCpuTimerInfo,
14567       GetThreadCpuTimerInfo, IterateOverReachableObjects,
14568       IterateOverObjectsReachableFromObject, GetTime and
14569       JVMTI_ERROR_NULL_POINTER.
14570       Add missing errors to: GenerateEvents and
14571       AddToBootstrapClassLoaderSearch.
14572       Fix description of ClassFileLoadHook name parameter.
14573       In heap callbacks and GC/ObjectFree events, specify
14574       that only explicitly allowed functions can be called.
14575       Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
14576       GetTimerInfo, and GetTime during callback.
14577       Allow calling SetTag/GetTag during the onload phase.
14578       SetEventNotificationMode, add: error attempted inappropriate
14579       thread level control.
14580       Remove jvmtiExceptionHandlerEntry.
14581       Fix handling of native methods on the stack --
14582       location_ptr param of GetFrameLocation, remove
14583       JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
14584       jvmtiFrameInfo.location, and jlocation.
14585       Remove typo (from JVMPI) implying that the MonitorWaited
14586       event is sent on sleep.
14587   </change>
14588   <change date="25 November 2003" version="0.2.94">
14589       Clarifications and typos.
14590   </change>
14591   <change date="3 December 2003" version="0.2.95">
14592       Allow NULL user_data in heap iterators.
14593   </change>
14594   <change date="28 January 2004" version="0.2.97">
14595       Add GetThreadState, deprecate GetThreadStatus.
14596   </change>
14597   <change date="29 January 2004" version="0.2.98">
14598       INVALID_SLOT and TYPE_MISMATCH errors should be optional.
14599   </change>
14600   <change date="12 February 2004" version="0.2.102">
14601       Remove MonitorContendedExit.
14602       Added JNIEnv parameter to VMObjectAlloc.
14603       Clarified definition of class_tag and referrer_index
14604       parameters to heap callbacks.
14605   </change>
14606   <change date="16 Febuary 2004" version="0.2.103">
14607       Document JAVA_TOOL_OPTIONS.
14608   </change>
14609   <change date="17 Febuary 2004" version="0.2.105">
14610       Divide start phase into primordial and start.
14611       Add VMStart event
14612       Change phase associations of functions and events.
14613   </change>
14614   <change date="18 Febuary 2004" version="0.3.6">
14615       Elide deprecated GetThreadStatus.
14616       Bump minor version, subtract 100 from micro version
14617   </change>
14618   <change date="18 Febuary 2004" version="0.3.7">
14619       Document that timer nanosecond values are unsigned.
14620       Clarify text having to do with native methods.
14621   </change>
14622   <change date="19 Febuary 2004" version="0.3.8">
14623       Fix typos.
14624       Remove elided deprecated GetThreadStatus.
14625   </change>
14626   <change date="23 Febuary 2004" version="0.3.9">
14627       Require NotifyFramePop to act on suspended threads.
14628   </change>
14629   <change date="24 Febuary 2004" version="0.3.10">
14630       Add capabilities
14631         (<internallink id="jvmtiCapabilities.can_redefine_any_class"
14632          ><code>can_redefine_any_class</code></internallink>
14633       and
14634          <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
14635          ><code>can_generate_all_class_hook_events</code></internallink>)
14636       and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>)
14637       which allow some classes to be unmodifiable.
14638   </change>
14639   <change date="28 Febuary 2004" version="0.3.11">
14640       Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
14641   </change>
14642   <change date="8 March 2004" version="0.3.12">
14643       Clarified CompiledMethodUnload so that it is clear the event
14644       may be posted after the class has been unloaded.
14645   </change>
14646   <change date="5 March 2004" version="0.3.13">
14647       Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
14648   </change>
14649   <change date="13 March 2004" version="0.3.14">
14650       Added guideline for the use of the JNI FindClass function in event
14651       callback functions.
14652   </change>
14653   <change date="15 March 2004" version="0.3.15">
14654       Add GetAllStackTraces and GetThreadListStackTraces.
14655   </change>
14656   <change date="19 March 2004" version="0.3.16">
14657       ClassLoad and ClassPrepare events can be posted during start phase.
14658   </change>
14659   <change date="25 March 2004" version="0.3.17">
14660       Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
14661       GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
14662   </change>
14663   <change date="29 March 2004" version="0.3.18">
14664       Return the timer kind in the timer information structure.
14665   </change>
14666   <change date="31 March 2004" version="0.3.19">
14667       Spec clarifications:
14668       JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
14669       ForceGarbageCollection does not run finalizers.
14670       The context of the specification is the Java platform.
14671       Warn about early instrumentation.
14672   </change>
14673   <change date="1 April 2004" version="0.3.20">
14674       Refinements to the above clarifications and
14675       Clarify that an error returned by Agent_OnLoad terminates the VM.
14676   </change>
14677   <change date="1 April 2004" version="0.3.21">
14678       Array class creation does not generate a class load event.
14679   </change>
14680   <change date="7 April 2004" version="0.3.22">
14681       Align thread state hierarchy more closely with java.lang.Thread.State.
14682   </change>
14683   <change date="12 April 2004" version="0.3.23">
14684       Clarify the documentation of thread state.
14685   </change>
14686   <change date="19 April 2004" version="0.3.24">
14687       Remove GarbageCollectionOccurred event -- can be done by agent.
14688   </change>
14689   <change date="22 April 2004" version="0.3.25">
14690       Define "command-line option".
14691   </change>
14692   <change date="29 April 2004" version="0.3.26">
14693       Describe the intended use of bytecode instrumentation.
14694       Fix description of extension event first parameter.
14695   </change>
14696   <change date="30 April 2004" version="0.3.27">
14697       Clarification and typos.
14698   </change>
14699   <change date="18 May 2004" version="0.3.28">
14700       Remove DataDumpRequest event.
14701   </change>
14702   <change date="18 May 2004" version="0.3.29">
14703       Clarify RawMonitorWait with zero timeout.
14704       Clarify thread state after RunAgentThread.
14705   </change>
14706   <change date="24 May 2004" version="0.3.30">
14707       Clean-up: fix bad/old links, etc.
14708   </change>
14709   <change date="30 May 2004" version="0.3.31">
14710       Clarifications including:
14711       All character strings are modified UTF-8.
14712       Agent thread visibiity.
14713       Meaning of obsolete method version.
14714       Thread invoking heap callbacks,
14715   </change>
14716   <change date="1 June 2004" version="1.0.32">
14717       Bump major.minor version numbers to "1.0".
14718   </change>
14719   <change date="2 June 2004" version="1.0.33">
14720       Clarify interaction between ForceGarbageCollection
14721       and ObjectFree.
14722   </change>
14723   <change date="6 June 2004" version="1.0.34">
14724       Restrict AddToBootstrapClassLoaderSearch and
14725       SetSystemProperty to the OnLoad phase only.
14726   </change>
14727   <change date="11 June 2004" version="1.0.35">
14728       Fix typo in SetTag.
14729   </change>
14730   <change date="18 June 2004" version="1.0.36">
14731       Fix trademarks.
14732       Add missing parameter in example GetThreadState usage.
14733   </change>
14734   <change date="4 August 2004" version="1.0.37">
14735       Copyright updates.
14736   </change>
14737   <change date="5 November 2004" version="1.0.38">
14738       Add missing function table layout.
14739       Add missing description of C++ member function format of functions.
14740       Clarify that name in CFLH can be NULL.
14741       Released as part of <tm>J2SE</tm> 5.0.
14742   </change>
14743   <change date="24 April 2005" version="1.1.47">
14744       Bump major.minor version numbers to "1.1".
14745       Add ForceEarlyReturn* functions.
14746       Add GetOwnedMonitorStackDepthInfo function.
14747       Add GetCurrentThread function.
14748       Add "since" version marker.
14749       Add AddToSystemClassLoaderSearch.
14750       Allow AddToBootstrapClassLoaderSearch be used in live phase.
14751       Fix historic rubbish in the descriptions of the heap_object_callback
14752       parameter of IterateOverHeap and IterateOverInstancesOfClass functions;
14753       disallow NULL for this parameter.
14754       Clarify, correct and make consistent: wording about current thread,
14755       opaque frames and insufficient number of frames in PopFrame.
14756       Consistently use "current frame" rather than "topmost".
14757       Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
14758       by making them compatible with those in ForceEarlyReturn*.
14759       Many other clarifications and wording clean ups.
14760   </change>
14761   <change date="25 April 2005" version="1.1.48">
14762       Add GetConstantPool.
14763       Switch references to the first edition of the VM Spec, to the seconds edition.
14764   </change>
14765   <change date="26 April 2005" version="1.1.49">
14766       Clarify minor/major version order in GetConstantPool.
14767   </change>
14768   <change date="26 April 2005" version="1.1.50">
14769       Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
14770       Reassign GetOwnedMonitorStackDepthInfo to position 153.
14771       Break out Class Loader Search in its own documentation category.
14772       Deal with overly long lines in XML source.
14773   </change>
14774   <change date="29 April 2005" version="1.1.51">
14775       Allow agents be started in the live phase.
14776       Added paragraph about deploying agents.
14777   </change>
14778   <change date="30 April 2005" version="1.1.52">
14779       Add specification description to SetNativeMethodPrefix(es).
14780       Better define the conditions on GetConstantPool.
14781   </change>
14782   <change date="30 April 2005" version="1.1.53">
14783       Break out the GetClassVersionNumber function from GetConstantPool.
14784       Clean-up the references to the VM Spec.
14785   </change>
14786   <change date="1 May 2005" version="1.1.54">
14787       Allow SetNativeMethodPrefix(es) in any phase.
14788       Add clarifications about the impact of redefinition on GetConstantPool.
14789   </change>
14790   <change date="2 May 2005" version="1.1.56">
14791       Various clarifications to SetNativeMethodPrefix(es).
14792   </change>
14793   <change date="2 May 2005" version="1.1.57">
14794       Add missing performance warning to the method entry event.
14795   </change>
14796   <change date="5 May 2005" version="1.1.58">
14797       Remove internal JVMDI support.
14798   </change>
14799   <change date="8 May 2005" version="1.1.59">
14800       Add <functionlink id="RetransformClasses"/>.
14801       Revamp the bytecode instrumentation documentation.
14802       Change <functionlink id="IsMethodObsolete"/> to no longer
14803       require the can_redefine_classes capability.
14804   </change>
14805   <change date="11 May 2005" version="1.1.63">
14806       Clarifications for retransformation.
14807   </change>
14808   <change date="11 May 2005" version="1.1.64">
14809       Clarifications for retransformation, per review.
14810       Lock "retransformation (in)capable" at class load enable time.
14811   </change>
14812   <change date="4 June 2005" version="1.1.67">
14813       Add new heap functionity which supports reporting primitive values,
14814       allows setting the referrer tag, and has more powerful filtering:
14815       FollowReferences, IterateThroughHeap, and their associated
14816       callbacks, structs, enums, and constants.
14817   </change>
14818   <change date="4 June 2005" version="1.1.68">
14819       Clarification.
14820   </change>
14821   <change date="6 June 2005" version="1.1.69">
14822       FollowReferences, IterateThroughHeap: Put callbacks in a struct;
14823       Add missing error codes; reduce bits in the visit control flags.
14824   </change>
14825   <change date="14 June 2005" version="1.1.70">
14826       More on new heap functionity: spec clean-up per review.
14827   </change>
14828   <change date="15 June 2005" version="1.1.71">
14829       More on new heap functionity: Rename old heap section to Heap (1.0).
14830   </change>
14831   <change date="21 June 2005" version="1.1.72">
14832       Fix typos.
14833   </change>
14834   <change date="27 June 2005" version="1.1.73">
14835       Make referrer info structure a union.
14836   </change>
14837   <change date="9 September 2005" version="1.1.74">
14838       In new heap functions:
14839       Add missing superclass reference kind.
14840       Use a single scheme for computing field indexes.
14841       Remove outdated references to struct based referrer info.
14842   </change>
14843   <change date="12 September 2005" version="1.1.75">
14844       Don't callback during FollowReferences on frivolous java.lang.Object superclass.
14845   </change>
14846   <change date="13 September 2005" version="1.1.76">
14847       In string primitive callback, length now Unicode length.
14848       In array and string primitive callbacks, value now "const".
14849       Note possible compiler impacts on setting JNI function table.
14850   </change>
14851   <change date="13 September 2005" version="1.1.77">
14852       GetClassVersionNumbers() and GetConstantPool() should return
14853       error on array or primitive class.
14854   </change>
14855   <change date="14 September 2005" version="1.1.78">
14856       Grammar fixes.
14857   </change>
14858   <change date="26 September 2005" version="1.1.79">
14859       Add IsModifiableClass query.
14860   </change>
14861   <change date="9 February 2006" version="1.1.81">
14862       Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
14863   </change>
14864   <change date="13 February 2006" version="1.1.82">
14865       Doc fixes: update can_redefine_any_class to include retransform.
14866       Clarify that exception events cover all Throwables.
14867       In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
14868       Clarify fields reported in Primitive Field Callback -- static vs instance.
14869       Repair confusing names of heap types, including callback names.
14870       Require consistent usage of stack depth in the face of thread launch methods.
14871       Note incompatibility of <jvmti/> memory management with other systems.
14872   </change>
14873   <change date="14 February 2006" version="1.1.85">
14874       Fix typos and missing renames.
14875   </change>
14876   <change date="13 March 2006" version="1.1.86">
14877       Clarify that jmethodIDs and jfieldIDs can be saved.
14878       Clarify that Iterate Over Instances Of Class includes subclasses.
14879   </change>
14880   <change date="14 March 2006" version="1.1.87">
14881       Better phrasing.
14882   </change>
14883   <change date="16 March 2006" version="1.1.88">
14884       Match the referrer_index for static fields in Object Reference Callback
14885       with the Reference Implementation (and all other known implementations);
14886       that is, make it match the definition for instance fields.
14887       In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover
14888       an invalid thread in the list; and specify that not started threads
14889       return empty stacks.
14890   </change>
14891   <change date="17 March 2006" version="1.1.89">
14892       Typo.
14893   </change>
14894   <change date="25 March 2006" version="1.1.90">
14895       Typo.
14896   </change>
14897   <change date="6 April 2006" version="1.1.91">
14898       Remove restrictions on AddToBootstrapClassLoaderSearch and
14899       AddToSystemClassLoaderSearch.
14900   </change>
14901   <change date="1 May 2006" version="1.1.93">
14902       Changed spec to return -1 for monitor stack depth for the
14903       implementation which can not determine stack depth.
14904   </change>
14905   <change date="3 May 2006" version="1.1.94">
14906       Corrections for readability and accuracy courtesy of Alan Pratt of IBM.
14907       List the object relationships reported in FollowReferences.
14908   </change>
14909   <change date="5 May 2006" version="1.1.95">
14910       Clarify the object relationships reported in FollowReferences.
14911   </change>
14912   <change date="28 June 2006" version="1.1.98">
14913       Clarify DisposeEnvironment; add warning.
14914       Fix typos in SetLocalXXX "retrieve" => "set".
14915       Clarify that native method prefixes must remain set while used.
14916       Clarify that exactly one Agent_OnXXX is called per agent.
14917       Clarify that library loading is independent from start-up.
14918       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14919   </change>
14920   <change date="31 July 2006" version="1.1.99">
14921       Clarify the interaction between functions and exceptions.
14922       Clarify and give examples of field indices.
14923       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14924       Update links to point to Java 6.
14925   </change>
14926   <change date="6 August 2006" version="1.1.102">
14927       Add ResourceExhaustedEvent.
14928   </change>
14929   <change date="11 October 2012" version="1.2.2">
14930       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14931   </change>
14932   <change date="19 June 2013" version="1.2.3">
14933       Added support for statically linked agents.
14934   </change>
14935   <change date="13 October 2016" version="9.0.0">
14936       Support for modules:
14937        - The majorversion is 9 now
14938        - The ClassFileLoadHook events are not sent during the primordial phase anymore.
14939        - Allow CompiledMethodLoad events at start phase
14940        - Add new capabilities:
14941           - can_generate_early_vmstart
14942           - can_generate_early_class_hook_events
14943        - Add new functions:
14944           - GetAllModules
14945           - AddModuleReads, AddModuleExports, AddModuleOpens, AddModuleUses, AddModuleProvides
14946           - IsModifiableModule
14947       Clarified can_redefine_any_classes, can_retransform_any_classes and IsModifiableClass API to
14948       disallow some implementation defined classes.
14949   </change>
14950   <change date="12 February 2017" version="9.0.0">
14951       Minor update for GetCurrentThread function:
14952        - The function may return NULL in the start phase if the
14953          can_generate_early_vmstart capability is enabled.
14954   </change>
14955   <change date="7 February 2018" version="11.0.0">
14956       Minor update for new class file NestHost and NestMembers attributes:
14957         - Specify that RedefineClasses and RetransformClasses are not allowed
14958           to change the class file NestHost and NestMembers attributes.
14959         - Add new error JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED
14960           that can be returned by RedefineClasses and RetransformClasses.
14961   </change>
14962   <change date="20 May 2019" version="13.0.0">
14963       Minor spec update for the capability "can_redefine_any_class".
14964       It now says:
14965        "RedefineClasses can be called on any modifiable class. See IsModifiableClass.
14966        (can_redefine_classes must also be set)"
14967   </change>
14968 </changehistory>
14969 
14970 </specification>
14971 <!-- Keep this comment at the end of the file
14972 Local variables:
14973 mode: sgml
14974 sgml-omittag:t
14975 sgml-shorttag:t
14976 sgml-namecase-general:t
14977 sgml-general-insert-case:lower
14978 sgml-minimize-attributes:nil
14979 sgml-always-quote-attributes:t
14980 sgml-indent-step:2
14981 sgml-indent-data:t
14982 sgml-parent-document:nil
14983 sgml-exposed-tags:nil
14984 sgml-local-catalogs:nil
14985 sgml-local-ecat-files:nil
14986 End:
14987 -->