1 <?xml version="1.0" encoding="ISO-8859-1"?>
    2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
    3 <!--
    4  Copyright (c) 2002, 2021, 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    <!ATTLIST jobject frame CDATA #IMPLIED>
  138 
  139    <!ELEMENT jvalue EMPTY>
  140    <!ELEMENT jchar EMPTY>
  141    <!ELEMENT jint EMPTY>
  142    <!ATTLIST jint min CDATA #IMPLIED>
  143    <!ELEMENT jlong EMPTY>
  144    <!ELEMENT jfloat EMPTY>
  145    <!ELEMENT jdouble EMPTY>
  146    <!ELEMENT jlocation EMPTY>
  147    <!ELEMENT jboolean EMPTY>
  148    <!ELEMENT char EMPTY>
  149    <!ELEMENT uchar EMPTY>
  150    <!ELEMENT size_t EMPTY>
  151    <!ELEMENT void EMPTY>
  152    <!ELEMENT enum (#PCDATA)*>
  153    <!ELEMENT struct (#PCDATA)*>
  154 
  155    <!ELEMENT nullok ANY>
  156 
  157    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  158                                    jthreadGroup|jobject|jvalue), nullok?)>
  159 
  160    <!ELEMENT outptr     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  161                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
  162                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
  163 
  164    <!ELEMENT allocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  165                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
  166                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
  167    <!ATTLIST allocbuf incount CDATA #IMPLIED
  168                       outcount CDATA #IMPLIED>
  169 
  170    <!ELEMENT allocallocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  171                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
  172                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
  173    <!ATTLIST allocallocbuf incount CDATA #IMPLIED
  174                       outcount CDATA #IMPLIED>
  175 
  176    <!ELEMENT inptr      (struct, nullok?)>
  177 
  178    <!ELEMENT inbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  179                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
  180                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
  181    <!ATTLIST inbuf    incount CDATA #IMPLIED>
  182 
  183    <!ELEMENT outbuf     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  184                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
  185                                    jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>
  186    <!ATTLIST outbuf   incount CDATA #IMPLIED
  187                       outcount CDATA #IMPLIED>
  188 
  189    <!ELEMENT vmbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  190                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|
  191                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
  192    <!ATTLIST vmbuf    incount CDATA #IMPLIED
  193                       outcount CDATA #IMPLIED>
  194 
  195    <!ELEMENT agentbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  196                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
  197                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>
  198    <!ATTLIST agentbuf incount CDATA #IMPLIED
  199                       outcount CDATA #IMPLIED>
  200 
  201    <!ELEMENT allocfieldbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|
  202                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|
  203                                    jlocation|jboolean|char|uchar|size_t|void))>
  204    <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>
  205 
  206    <!ELEMENT errors (error*)>
  207 
  208    <!ELEMENT error ANY>
  209    <!ATTLIST error id CDATA #REQUIRED>
  210 
  211    <!ELEMENT errorsection (intro*, errorcategory*)>
  212    <!ATTLIST errorsection label CDATA #REQUIRED>
  213 
  214    <!ELEMENT errorcategory (intro*, errorid*)>
  215    <!ATTLIST errorcategory id CDATA #REQUIRED
  216                            label CDATA #REQUIRED>
  217 
  218    <!ELEMENT errorid ANY>
  219    <!ATTLIST errorid id CDATA #REQUIRED
  220                      num CDATA #REQUIRED>
  221 
  222    <!ELEMENT datasection (intro*, basetypes*)>
  223 
  224    <!ELEMENT basetypes (intro*, basetype*)>
  225    <!ATTLIST basetypes id CDATA #REQUIRED
  226                        label CDATA #REQUIRED>
  227 
  228    <!ELEMENT basetype (definition?,description)>
  229    <!ATTLIST basetype id CDATA #REQUIRED
  230                       name CDATA #IMPLIED>
  231 
  232    <!ELEMENT definition (#PCDATA|jvmti)*>
  233 
  234    <!ELEMENT eventsection (intro*, (event|elide)*)>
  235    <!ATTLIST eventsection label CDATA #REQUIRED>
  236 
  237    <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>
  238    <!ATTLIST event id CDATA #REQUIRED
  239                    label CDATA #REQUIRED
  240                    const CDATA #REQUIRED
  241                    num CDATA #REQUIRED
  242                    phase (onload|start|live|any) #IMPLIED
  243                    filtered (thread|global) #IMPLIED
  244                    since CDATA "1.0">
  245 
  246    <!ELEMENT issuessection (intro*)>
  247    <!ATTLIST issuessection label CDATA #REQUIRED>
  248 
  249    <!ELEMENT changehistory (intro*, change*)>
  250    <!ATTLIST changehistory update CDATA #REQUIRED
  251                            id CDATA #REQUIRED>
  252 
  253    <!ELEMENT change ANY>
  254    <!ATTLIST change date CDATA #REQUIRED
  255                     version CDATA #IMPLIED>
  256 
  257    <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>
  258    <!ATTLIST functionlink id CDATA #REQUIRED>
  259 
  260    <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>
  261    <!ATTLIST datalink id CDATA #REQUIRED>
  262 
  263    <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>
  264    <!ATTLIST typelink id CDATA #REQUIRED>
  265 
  266    <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>
  267    <!ATTLIST fieldlink id CDATA #REQUIRED
  268                        struct CDATA #REQUIRED>
  269 
  270    <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>
  271    <!ATTLIST paramlink id CDATA #REQUIRED>
  272 
  273    <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>
  274    <!ATTLIST eventlink id CDATA #REQUIRED>
  275 
  276    <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>
  277    <!ATTLIST errorlink id CDATA #REQUIRED>
  278 
  279    <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>
  280    <!ATTLIST externallink id CDATA #REQUIRED>
  281 
  282    <!ELEMENT vmspec EMPTY>
  283    <!ATTLIST vmspec chapter CDATA #IMPLIED>
  284 
  285    <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>
  286    <!ATTLIST internallink id CDATA #REQUIRED>
  287 
  288    <!ELEMENT functionphaselist EMPTY>
  289    <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>
  290 
  291    <!ELEMENT eventphaselist EMPTY>
  292    <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>
  293 
  294    <!ELEMENT issue ANY>
  295 
  296    <!ELEMENT rationale ANY>
  297 
  298    <!ELEMENT todo ANY>
  299 
  300    <!ELEMENT origin (#PCDATA)*>
  301 
  302    <!ELEMENT elide (intro|function|callback|event)*>
  303    <!ATTLIST elide why CDATA #IMPLIED>
  304 
  305    <!ELEMENT constants (constant*)>
  306    <!ATTLIST constants id CDATA #REQUIRED
  307                        label CDATA #REQUIRED
  308                        kind (enum|bits|const) #REQUIRED
  309                        since CDATA "1.0">
  310 
  311    <!ELEMENT constant ANY>
  312    <!ATTLIST constant id CDATA #REQUIRED
  313                       num CDATA #REQUIRED>
  314 
  315    <!ELEMENT tm (#PCDATA)>
  316 
  317    <!ELEMENT i (#PCDATA|jvmti|tm)*>
  318 
  319    <!ELEMENT b (#PCDATA|jvmti|code)*>
  320 
  321    <!ELEMENT code (#PCDATA|space)*>
  322 
  323    <!ELEMENT pre ANY>
  324 
  325    <!ELEMENT space EMPTY>
  326 
  327    <!ELEMENT jvmti EMPTY>
  328 
  329    <!ELEMENT example (#PCDATA|i)*>
  330 
  331    <!ELEMENT br EMPTY>
  332 
  333    <!ELEMENT p EMPTY>
  334 
  335    <!ELEMENT blockquote ANY>
  336 
  337    <!ELEMENT dl  (dt|dd)+>
  338 
  339    <!ELEMENT dd  ANY>
  340 
  341    <!ELEMENT dt  (#PCDATA|jvmti|code|i|b)*>
  342 
  343    <!ELEMENT table  (tr)+>
  344 
  345    <!ELEMENT tr  (td|th)*>
  346    <!ATTLIST tr class CDATA #IMPLIED>
  347 
  348    <!ELEMENT td  ANY>
  349    <!ATTLIST td class CDATA #IMPLIED>
  350 
  351    <!ELEMENT th  ANY>
  352    <!ATTLIST th class CDATA #IMPLIED
  353                 scope (col|row) #IMPLIED>
  354 
  355    <!ELEMENT ul  (li)+>
  356    <!ATTLIST ul type (disc|circle|square) "disc">
  357 
  358    <!ELEMENT li  ANY>
  359  ]>
  360 
  361 <specification label="JVM(TM) Tool Interface">
  362   <title subtitle="Version">
  363     <tm>JVM</tm> Tool Interface
  364   </title>
  365 
  366   <intro id="whatIs" label="What is the JVM Tool Interface?">
  367     The <tm>JVM</tm> Tool Interface (<jvmti/>)
  368     is a programming interface used by development and monitoring tools.
  369     It provides both a way to inspect the state and
  370     to control the execution of applications running in the
  371     <tm>Java</tm> virtual machine (VM).
  372     <p/>
  373     <jvmti/> is intended to provide a VM interface for the full breadth of tools
  374     that need access to VM state, including but not limited to: profiling,
  375     debugging, monitoring, thread analysis, and coverage analysis tools.
  376     <p/>
  377     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
  378     machine.
  379     <p/>
  380     <jvmti/> is a two-way interface.
  381     A client of <jvmti/>, hereafter called an <i>agent</i>,
  382     can be notified of
  383     interesting occurrences through <internallink id="EventSection">events</internallink>.
  384     <jvmti/>
  385     can query and control the application through many
  386     <internallink id="FunctionSection">functions</internallink>,
  387     either in response to events or
  388     independent of them.
  389     <p/>
  390     Agents run in the same process with and communicate directly with
  391     the virtual machine executing
  392     the application being examined.  This communication is
  393     through a native interface (<jvmti/>). The native in-process interface allows
  394     maximal control with minimal intrusion on the part of a tool.
  395     Typically, agents are relatively compact. They can be controlled
  396     by a separate process which implements the bulk of a tool's
  397     function without interfering with the target application's normal execution.
  398   </intro>
  399 
  400   <intro id="architecture" label="Architecture">
  401     Tools can be written directly to <jvmti/> or indirectly
  402     through higher level interfaces.
  403     The Java Platform Debugger Architecture includes <jvmti/>, but also
  404     contains higher-level, out-of-process debugger interfaces. The higher-level
  405     interfaces are more appropriate than <jvmti/> for many tools.
  406     For more information on the Java Platform Debugger Architecture,
  407     see the
  408     <externallink id="jpda/architecture.html">Java
  409       Platform Debugger Architecture website</externallink>.
  410   </intro>
  411 
  412   <intro id="writingAgents" label="Writing Agents">
  413     Agents can be written in any native language that supports C
  414     language calling conventions and C or C++
  415     definitions.
  416     <p/>
  417     The function, event, data type, and constant definitions needed for
  418     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
  419     To use these definitions add the <tm>J2SE</tm> include directory
  420     to your include path and add
  421     <example>
  422 #include &lt;jvmti.h&gt;
  423     </example>
  424     to your source code.
  425   </intro>
  426 
  427   <intro id="deployingAgents" label="Deploying Agents">
  428     An agent is deployed in a platform specific manner but is typically the
  429     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating
  430     system, for example, an agent library is a "Dynamic Linked Library" (DLL).
  431     On <tm>Linux</tm> Operating Environment, an agent library is a shared object
  432     (<code>.so</code> file).
  433     <p/>
  434 
  435     An agent may be started at VM startup by specifying the agent library
  436     name using a <internallink id="starting">command line option</internallink>.
  437     Some implementations may support a mechanism to <internallink id="onattach">
  438     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
  439     The details of how this is initiated are implementation specific.
  440   </intro>
  441 
  442     <intro id="entryPoint" label="Statically Linked Agents (since version 1.2.3)">
  443 
  444       A native JVMTI Agent may be <i>statically linked</i> with the VM.
  445       The manner in which the library and VM image are combined is
  446       implementation-dependent.
  447       An agent L whose image has been combined with the VM is defined as
  448       <i>statically linked</i> if and only if the agent exports a function
  449       called Agent_OnLoad_L.
  450 <p/>
  451       If a <i>statically linked</i> agent L exports a function called
  452       Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
  453       function will be ignored.
  454       If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
  455       function will be invoked with the same arguments and expected return
  456       value as specified for the Agent_OnLoad function.
  457       An agent L that is <i>statically linked</i> will prohibit an agent of
  458       the same name from being loaded dynamically.
  459 <p/>
  460       The VM will invoke the Agent_OnUnload_L function of the agent, if such
  461       a function is exported, at the same point during VM execution as it would
  462       have called the dynamic entry point Agent_OnUnLoad. A statically loaded
  463       agent cannot be unloaded. The Agent_OnUnload_L function will still be
  464       called to do any other agent shutdown related tasks.
  465       If a <i>statically linked</i> agent L exports a function called
  466       Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
  467       function will be ignored.
  468 <p/>
  469       If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
  470       will be invoked with the same arguments and expected return value as
  471       specified for the Agent_OnAttach function.
  472       If a <i>statically linked</i> agent L exports a function called
  473       Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
  474       function will be ignored.
  475 </intro>
  476 
  477   <intro id="starting" label="Agent Command Line Options">
  478     The term "command-line option" is used below to
  479     mean options supplied in the <code>JavaVMInitArgs</code> argument
  480     to the <code>JNI_CreateJavaVM</code> function of the JNI
  481     Invocation API.
  482     <p/>
  483     One of the two following
  484     command-line options is used on VM startup to
  485     properly load and run agents.
  486     These arguments identify the library containing
  487     the agent as well as an options
  488     string to be passed in at startup.
  489     <dl>
  490       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
  491       <dd>
  492         The name following <code>-agentlib:</code> is the name of the
  493         library to load.  Lookup of the library, both its full name and location,
  494         proceeds in a platform-specific manner.
  495         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
  496         operating system specific file name.
  497         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
  498         For example, if the option
  499         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to
  500         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
  501         under <tm>Windows</tm> or <code>libfoo.so</code> from the
  502         <code>LD_LIBRARY_PATH</code> under <tm>Linux</tm>.
  503         If the agent library is statically linked into the executable
  504         then no actual loading takes place.
  505     <p/>
  506       </dd>
  507       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
  508       <dd>
  509         The path following <code>-agentpath:</code> is the absolute path from which
  510         to load the library.
  511         No library name expansion will occur.
  512         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
  513         For example, if the option
  514         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to
  515         load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
  516         library is statically linked into the executable
  517         then no actual loading takes place.
  518     <p/>
  519       </dd>
  520     </dl>
  521     For a dynamic shared library agent, the start-up routine
  522     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
  523     in the library will be invoked. If the agent library is statically linked
  524     into the executable then the system will attempt to invoke the
  525     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> entry point where
  526     &lt;agent-lib-name&gt; is the basename of the
  527     agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
  528     the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
  529     <p/>
  530     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
  531     will be searched for JNI native method implementations to facilitate the
  532     use of Java programming language code in tools, as is needed for
  533     <internallink id="bci">bytecode instrumentation</internallink>.
  534     <p/>
  535     The agent libraries will be searched after all other libraries have been
  536     searched (agents wishing to override or intercept the native method
  537     implementations of non-agent methods can use the
  538     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
  539     <p/>
  540     These switches do the above and nothing more - they do not change the
  541     state of the VM or <jvmti/>.  No command line options are needed
  542     to enable <jvmti/>
  543     or aspects of <jvmti/>, this is handled programmatically
  544     by the use of
  545     <internallink id="capability">capabilities</internallink>.
  546   </intro>
  547 
  548   <intro id="startup" label="Agent Start-Up">
  549     The VM starts each agent by invoking a start-up function.
  550     If the agent is started in the <code>OnLoad</code>
  551     <functionlink id="GetPhase">phase</functionlink> the function
  552     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
  553     or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
  554     for statically linked agents will be invoked.
  555     If the agent is started in the live
  556     <functionlink id="GetPhase">phase</functionlink> the function
  557     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
  558     or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
  559     for statically linked agents will be invoked.
  560     Exactly one call to a start-up function is made per agent.
  561   </intro>
  562 
  563   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
  564     If an agent is started during the <code>OnLoad</code> phase then its
  565     agent library must export a start-up function with the following prototype:
  566     <example>
  567 JNIEXPORT jint JNICALL
  568 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
  569     Or for a statically linked agent named 'L':
  570     <example>
  571 JNIEXPORT jint JNICALL
  572 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
  573 
  574     The VM will start the agent by calling this function.
  575     It will be called early enough in VM initialization that:
  576     <ul>
  577       <li><functionlink id="SetSystemProperty">system properties</functionlink>
  578         may be set before they have been used in the start-up of the VM</li>
  579       <li>the full set of
  580         <internallink id="capability">capabilities</internallink>
  581         is still available (note that capabilities that configure the VM
  582         may only be available at this time--see the
  583         <internallink id="capability">Capability function section</internallink>)</li>
  584       <li>no bytecodes have executed</li>
  585       <li>no classes have been loaded</li>
  586       <li>no objects have been created</li>
  587     </ul>
  588     <p/>
  589     The VM will call the <code>Agent_OnLoad</code> or
  590     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> function with
  591     <i>&lt;options&gt;</i> as the second argument -
  592     that is, using the command-line option examples,
  593     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
  594     argument of <code>Agent_OnLoad</code>.
  595     The <code>options</code> argument is encoded as a
  596     <internallink id="mUTF">modified UTF-8</internallink> string.
  597     If <i>=&lt;options&gt;</i> is not specified,
  598     a zero length string is passed to <code>options</code>.
  599     The lifespan of the <code>options</code> string is the
  600     <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code>
  601     call.  If needed beyond this time the string or parts of the string must
  602     be copied.
  603     The period between when <code>Agent_OnLoad</code> is called and when it
  604     returns is called the <i>OnLoad phase</i>.
  605     Since the VM is not initialized during the OnLoad
  606     <functionlink id="GetPhase">phase</functionlink>,
  607     the set of allowed operations
  608     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
  609     functionality available at this time).
  610     The agent can safely process the options and set
  611     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once
  612     the VM initialization event is received
  613     (that is, the <eventlink id="VMInit">VMInit</eventlink>
  614     callback is invoked), the agent
  615     can complete its initialization.
  616     <rationale>
  617       Early startup is required so that agents can set the desired capabilities,
  618       many of which must be set before the VM is initialized.
  619       In JVMDI, the -Xdebug command-line option provided
  620       very coarse-grain control of capabilities.
  621       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
  622       No reasonable command-line
  623       option could provide the fine-grain of control required to balance needed capabilities vs
  624       performance impact.
  625       Early startup is also needed so that agents can control the execution
  626       environment - modifying the file system and system properties to install
  627       their functionality.
  628     </rationale>
  629     <p/>
  630     The return value from <code>Agent_OnLoad</code> or
  631     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> is used to indicate an error.
  632     Any value other than zero indicates an error and causes termination of the VM.
  633   </intro>
  634 
  635   <intro id="onattach" label="Agent Start-Up (Live phase)">
  636     A VM may support a mechanism that allows agents to be started in the VM during the live
  637     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
  638     are implementation specific. For example, a tool may use some platform specific mechanism,
  639     or implementation specific API, to attach to the running VM, and request it start a given
  640     agent.
  641     <p/>
  642     If an agent is started during the live phase then its agent library
  643     must export a start-up function
  644     with the following prototype:
  645     <example>
  646 JNIEXPORT jint JNICALL
  647 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
  648 Or for a statically linked agent named 'L':
  649     <example>
  650 JNIEXPORT jint JNICALL
  651 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
  652 
  653     <p/>
  654     The VM will start the agent by calling this function.
  655     It will be called in the context of a thread
  656     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
  657     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
  658     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
  659     </internallink> string.
  660     If startup options were not provided, a zero length string is passed to
  661     <code>options</code>. The lifespan of the <code>options</code> string is the
  662     <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> call.
  663     If needed beyond this time the string or parts of the string must be copied.
  664     <p/>
  665     Note that some <internallink id="capability">capabilities</internallink>
  666     may not be available in the live phase.
  667     <p/>
  668     The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name
  669     &gt;</code> function initializes the agent and returns a value
  670     to the VM to indicate if an error occurred. Any value other than zero indicates an error.
  671     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes
  672     some implementation specific action -- for example it might print an error to standard error,
  673     or record the error in a system log.
  674   </intro>
  675 
  676   <intro id="onunload" label="Agent Shutdown">
  677     The library may optionally export a
  678     shutdown function with the following prototype:
  679     <example>
  680 JNIEXPORT void JNICALL
  681 Agent_OnUnload(JavaVM *vm)</example>
  682     Or for a statically linked agent named 'L':
  683     <example>
  684 JNIEXPORT void JNICALL
  685 Agent_OnUnload_L(JavaVM *vm)</example>
  686 
  687     This function will be called by the VM when the library is about to be unloaded.
  688     The library will be unloaded (unless it is statically linked into the
  689     executable) and this function will be called if some platform specific
  690     mechanism causes the unload (an unload mechanism is not specified in this document)
  691     or the library is (in effect) unloaded by the termination of the VM.
  692     VM termination includes normal termination and VM failure, including start-up failure,
  693     but not, of course, uncontrolled shutdown. An implementation may also
  694     choose to not call this function if the <code>Agent_OnAttach</code>/
  695     <code>Agent_OnAttach_L</code> function reported an error (returned a non-zero value).
  696     Note the distinction between this function and the
  697     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
  698     to be sent, the VM must have run at least to the point of initialization and a valid
  699     <jvmti/> environment must exist which has set a callback for VMDeath
  700     and enabled the event.
  701     None of these are required for <code>Agent_OnUnload</code> or
  702     <code>Agent_OnUnload_&lt;agent-lib-name&gt;</code> and this function
  703     is also called if the library is unloaded for other reasons.
  704     In the case that a VM Death event is sent, it will be sent before this
  705     function is called (assuming this function is called due to VM termination).
  706     This function can be used to clean-up resources allocated by the agent.
  707   </intro>
  708 
  709   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
  710     Since the command-line cannot always be accessed or modified, for example in embedded VMs
  711     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
  712     provided so that agents may be launched in these cases.
  713     <p/>
  714     Platforms which support environment variables or other named strings, may support the
  715     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space
  716     boundaries.  White-space characters include space, tab, carriage-return, new-line,
  717     vertical-tab, and form-feed.  Sequences of white-space characters are considered
  718     equivalent to a single white-space character.  No white-space is included in the options
  719     unless quoted.  Quoting is as follows:
  720     <ul>
  721         <li>All characters enclosed between a pair of single quote marks (''), except a single
  722         quote, are quoted.</li>
  723         <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>
  724         <li>All characters enclosed between a pair of double quote marks (""), except a double
  725         quote, are quoted.</li>
  726         <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>
  727         <li>A quoted part can start or end anywhere in the variable.</li>
  728         <li>White-space characters have no special meaning when quoted -- they are included in
  729         the option like any other character and do not mark white-space boundaries.</li>
  730         <li>The pair of quote marks is not included in the option.</li>
  731     </ul>
  732     <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied
  733     in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is
  734     a concern; for example, the Reference Implementation disables this feature on Unix systems when
  735     the effective user or group ID differs from the real ID.
  736     This feature is intended to support the initialization of tools -- specifically including the
  737     launching of native or Java programming language agents.  Multiple tools may wish to use this
  738     feature, so the variable should not be overwritten, instead,  options should be appended to
  739     the variable.  Note that since the variable is processed at the time of the JNI Invocation
  740     API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.
  741   </intro>
  742 
  743   <intro id="environments" label="Environments">
  744     The <jvmti/> specification supports the use of multiple simultaneous
  745     <jvmti/> agents.
  746     Each agent has its own <jvmti/> environment.
  747     That is, the <jvmti/> state is
  748     separate for each agent - changes to one environment do not affect the
  749     others.  The state of a <jvmti/>
  750     environment includes:
  751     <ul>
  752       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>
  753       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>
  754       <li><internallink id="capability">the capabilities</internallink></li>
  755       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>
  756     </ul>
  757     Although their <jvmti/> state
  758     is separate, agents inspect and modify the shared state
  759     of the VM, they also share the native environment in which they execute.
  760     As such, an agent can perturb the results of other agents or cause them
  761     to fail.  It is the responsibility of the agent writer to specify the level
  762     of compatibility with other agents.  <jvmti/> implementations are not capable
  763     of preventing destructive interactions between agents. Techniques to reduce
  764     the likelihood of these occurrences are beyond the scope of this document.
  765     <p/>
  766     An agent creates a <jvmti/> environment
  767     by passing a <jvmti/> version
  768     as the interface ID to the JNI Invocation API function
  769     <externallink id="jni/invocation.html#getenv">
  770       <code>GetEnv</code></externallink>.
  771     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>
  772     for more details on the creation and use of
  773     <jvmti/> environments.
  774     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from
  775     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.
  776   </intro>
  777 
  778   <intro id="bci" label="Bytecode Instrumentation">
  779     This interface does not include some events that one might expect in an interface with
  780     profiling support.  Some examples include full speed
  781     method enter and exit events.  The interface instead provides support for
  782     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine
  783     bytecode instructions which comprise the target program.  Typically, these alterations
  784     are to add "events" to the code of a method - for example, to add, at the beginning of a method,
  785     a call to <code>MyProfiler.methodEntered()</code>.
  786     Since the changes are purely additive, they do not modify application
  787     state or behavior.
  788     Because the inserted agent code is standard bytecodes, the VM can run at full speed,
  789     optimizing not only the target program but also the instrumentation.  If the
  790     instrumentation does not involve switching from bytecode execution, no expensive
  791     state transitions are needed.  The result is high performance events.
  792     This approach also provides complete control to the agent: instrumentation can be
  793     restricted to "interesting" portions of the code (e.g., the end user's code) and
  794     can be conditional.  Instrumentation can run entirely in Java programming language
  795     code or can call into the native agent.  Instrumentation can simply maintain
  796     counters or can statistically sample events.
  797     <p/>
  798     Instrumentation can be inserted in one of three ways:
  799     <ul>
  800       <li>
  801         Static Instrumentation: The class file is instrumented before it
  802         is loaded into the VM - for example, by creating a duplicate directory of
  803         <code>*.class</code> files which have been modified to add the instrumentation.
  804         This method is extremely awkward and, in general, an agent cannot know
  805         the origin of the class files which will be loaded.
  806       </li>
  807       <li>
  808         Load-Time Instrumentation: When a class file is loaded by the VM, the raw
  809         bytes of the class file are sent for instrumentation to the agent.
  810         The <eventlink id="ClassFileLoadHook"/>
  811         event, triggered by the class load,
  812         provides this functionality.  This mechanism provides efficient
  813         and complete access to one-time instrumentation.
  814       </li>
  815       <li>
  816         Dynamic Instrumentation: A class which is already loaded (and possibly
  817         even running) is modified.  This optional feature is provided by the
  818         <eventlink id="ClassFileLoadHook"/> event, triggered by calling the
  819         <functionlink id="RetransformClasses"/> function.
  820         Classes can be modified multiple times and can be returned to their
  821         original state.
  822         The mechanism allows instrumentation which changes during the
  823         course of execution.
  824       </li>
  825     </ul>
  826     <p/>
  827     The class modification functionality provided in this interface
  828     is intended to provide a mechanism for instrumentation
  829     (the <eventlink id="ClassFileLoadHook"/> event
  830     and the <functionlink id="RetransformClasses"/> function)
  831     and, during development, for fix-and-continue debugging
  832     (the <functionlink id="RedefineClasses"/> function).
  833     <p/>
  834     Care must be taken to avoid perturbing dependencies, especially when
  835     instrumenting core classes.  For example, an approach to getting notification
  836     of every object allocation is to instrument the constructor on
  837     <code>Object</code>.  Assuming that the constructor is initially
  838     empty, the constructor could be changed to:
  839     <example>
  840       public Object() {
  841         MyProfiler.allocationTracker(this);
  842       }
  843     </example>
  844     However, if this change was made using the
  845     <eventlink id="ClassFileLoadHook"/>
  846     event then this might impact a typical VM as follows:
  847     the first created object will call the constructor causing a class load of
  848     <code>MyProfiler</code>; which will then cause
  849     object creation, and since <code>MyProfiler</code> isn't loaded yet,
  850     infinite recursion; resulting in a stack overflow.  A refinement of this
  851     would be to delay invoking the tracking method until a safe time.  For
  852     example, <code>trackAllocations</code> could be set in the
  853     handler for the <code>VMInit</code> event.
  854     <example>
  855       static boolean trackAllocations = false;
  856 
  857       public Object() {
  858         if (trackAllocations) {
  859           MyProfiler.allocationTracker(this);
  860         }
  861       }
  862     </example>
  863     <p/>
  864     The <functionlink id="SetNativeMethodPrefix"/> allows native methods
  865     to be instrumented by the use of wrapper methods.
  866   </intro>
  867 
  868 <intro id="bcimodules" label="Bytecode Instrumentation of code in modules">
  869   Agents can use the functions <functionlink id="AddModuleReads"/>,
  870   <functionlink id="AddModuleExports"/>, <functionlink id="AddModuleOpens"/>,
  871   <functionlink id="AddModuleUses"/> and <functionlink id="AddModuleProvides"/>
  872   to update a module to expand the set of modules that it reads, the set of
  873   packages that it exports or opens to other modules, or the services that it
  874   uses and provides.
  875   <p/>
  876   As an aid to agents that deploy supporting classes on the search path of
  877   the bootstrap class loader, or the search path of the class loader that
  878   loads the main class, the Java virtual machine arranges for the module
  879   of classes transformed by the <eventlink id="ClassFileLoadHook"/> event to
  880   read the unnamed module of both class loaders.
  881 </intro>
  882 
  883   <intro id="mUTF" label="Modified UTF-8 String Encoding">
  884     <jvmti/> uses modified UTF-8 to encode character strings.
  885     This is the same encoding used by JNI.
  886     Modified UTF-8 differs
  887     from standard UTF-8 in the representation of supplementary characters
  888     and of the null character. See the
  889     <externallink id="jni/types.html#modified-utf-8-strings">
  890       Modified UTF-8 Strings</externallink>
  891     section of the JNI specification for details.
  892   </intro>
  893 
  894   <intro id="context" label="Specification Context">
  895     Since this interface provides access to the state of applications running in the
  896     Java virtual machine;
  897     terminology refers to the Java platform and not the native
  898     platform (unless stated otherwise).  For example:
  899     <ul>
  900       <li>"thread" means Java programming language thread.</li>
  901       <li>"stack frame" means Java virtual machine stack frame.</li>
  902       <li>"class" means Java programming language class.</li>
  903       <li>"heap" means Java virtual machine heap.</li>
  904       <li>"monitor" means Java programming language object monitor.</li>
  905     </ul>
  906     <p/>
  907     Sun, Sun Microsystems, the Sun logo, Java, and JVM
  908     are trademarks or registered trademarks of Oracle
  909     and/or its affiliates, in the U.S. and other countries.
  910   </intro>
  911 
  912 
  913 <functionsection label="Functions">
  914   <intro id="jvmtiEnvAccess" label="Accessing Functions">
  915     Native code accesses <jvmti/> features
  916     by calling <jvmti/> functions.
  917     Access to <jvmti/> functions is by use of an interface pointer
  918     in the same manner as
  919     <externallink id="jni/design.html">Java
  920       Native Interface (JNI) functions</externallink> are accessed.
  921     The <jvmti/> interface pointer is called the
  922     <i>environment pointer</i>.
  923     <p/>
  924     An environment pointer is a pointer to an environment and has
  925     the type <code>jvmtiEnv*</code>.
  926     An environment has information about its <jvmti/> connection.
  927     The first value in the environment is a pointer to the function table.
  928     The function table is an array of pointers to <jvmti/> functions.
  929     Every function pointer is at a predefined offset inside the
  930     array.
  931     <p/>
  932     When used from the C language:
  933     double indirection is used to access the functions;
  934     the environment pointer provides context and is the first
  935     parameter of each function call; for example:
  936     <example>
  937 jvmtiEnv *jvmti;
  938 ...
  939 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &amp;class_count, &amp;classes);
  940     </example>
  941     <p/>
  942     When used from the C++ language:
  943     functions are accessed as member functions of <code>jvmtiEnv</code>;
  944     the environment pointer is not passed to the function call; for example:
  945     <example>
  946 jvmtiEnv *jvmti;
  947 ...
  948 jvmtiError err = jvmti->GetLoadedClasses(&amp;class_count, &amp;classes);
  949     </example>
  950     Unless otherwise stated, all examples and declarations in this
  951     specification use the C language.
  952     <p/>
  953     A <jvmti/> environment can be obtained through the JNI Invocation API
  954     <code>GetEnv</code> function:
  955     <example>
  956 jvmtiEnv *jvmti;
  957 ...
  958 (*jvm)->GetEnv(jvm, &amp;jvmti, JVMTI_VERSION_1_0);
  959     </example>
  960     Each call to <code>GetEnv</code>
  961     creates a new <jvmti/> connection and thus
  962     a new <jvmti/> environment.
  963     The <code>version</code> argument of <code>GetEnv</code> must be
  964     a <jvmti/> version.
  965     The returned environment may have a different version than the
  966     requested version but the returned environment must be compatible.
  967     <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a
  968     compatible version is not available, if <jvmti/> is not supported or
  969     <jvmti/> is not supported in the current VM configuration.
  970     Other interfaces may be added for creating <jvmti/> environments
  971     in specific contexts.
  972     Each environment has its own state (for example,
  973     <functionlink id="SetEventNotificationMode">desired events</functionlink>,
  974     <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and
  975     <functionlink id="AddCapabilities">capabilities</functionlink>).
  976     An environment is released with
  977     <functionlink id="DisposeEnvironment"></functionlink>.
  978     Thus, unlike JNI which has one environment per thread, <jvmti/> environments work
  979     across threads and are created dynamically.
  980   </intro>
  981 
  982   <intro id="functionReturn" label="Function Return Values">
  983     <jvmti/> functions always return an
  984     <internallink id="ErrorSection">error code</internallink> via the
  985     <datalink id="jvmtiError"/> function return value.
  986     Some functions can return additional
  987     values through pointers provided by the calling function.
  988     In some cases, <jvmti/> functions allocate memory that your program must
  989     explicitly deallocate. This is indicated in the individual <jvmti/>
  990     function descriptions.  Empty lists, arrays, sequences, etc are
  991     returned as <code>NULL</code>.
  992     <p/>
  993     In the event that the <jvmti/> function encounters
  994     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values
  995     of memory referenced by argument pointers is undefined, but no memory
  996     will have been allocated and no global references will have been allocated.
  997     If the error occurs because of invalid input, no action will have occurred.
  998   </intro>
  999 
 1000 <intro id="refs" label="Managing JNI Object References">
 1001     <jvmti/> functions identify objects with JNI references
 1002     (<datalink id="jobject"/> and <datalink id="jclass"/>)
 1003     and their derivatives
 1004     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).
 1005     References passed to
 1006     <jvmti/> functions can be either global or local, but they must be
 1007     strong references. All references returned by <jvmti/> functions are
 1008     local references--these local references are created
 1009     during the <jvmti/> call.
 1010     Local references are a resource that must be managed (see the
 1011     <externallink id="jni/functions.html#local-references">
 1012       JNI Documentation</externallink>).
 1013     When threads return from native code all local references
 1014     are freed.  Note that some threads, including typical
 1015     agent threads, will never return from native code.
 1016     A thread is ensured the ability to create sixteen local
 1017     references without the need for any explicit management.
 1018     For threads executing a limited number of <jvmti/> calls before
 1019     returning from native code
 1020     (for example, threads processing events),
 1021     it may be determined that no explicit management
 1022     is needed.
 1023     However, long running agent threads will need explicit
 1024     local reference management--usually with the JNI functions
 1025     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.
 1026     Conversely, to preserve references beyond the
 1027     return from native code, they must be converted to global references.
 1028     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/>
 1029     as they are not <datalink id="jobject"/>s.
 1030 </intro>
 1031 
 1032     <intro id="prereqState" label="Prerequisite State for Calling Functions">
 1033       Unless the function explicitly states that the agent must bring
 1034       a thread or the VM to a particular state (for example, suspended),
 1035       the <jvmti/> implementation is responsible for bringing the VM to a
 1036       safe and consistent state for performing the function.
 1037     </intro>
 1038 
 1039     <intro id="functionsExceptions" label="Exceptions and Functions">
 1040       <jvmti/> functions never throw exceptions; error conditions are
 1041       communicated via the
 1042       <internallink id="functionReturn">function return value</internallink>.
 1043       Any existing exception state is preserved across a call to a
 1044       <jvmti/> function.
 1045       See the
 1046       <externallink
 1047         id="jni/design.html#java-exceptions"
 1048              >Java Exceptions</externallink>
 1049       section of the JNI specification for information on handling exceptions.
 1050     </intro>
 1051 
 1052   <category id="memory" label="Memory Management">
 1053     <intro>
 1054       These functions provide for the allocation and deallocation of
 1055       memory used by <jvmti/> functionality and can be used to provide
 1056       working memory for agents.
 1057       Memory managed by <jvmti/> is not compatible with other memory
 1058       allocation libraries and mechanisms.
 1059     </intro>
 1060 
 1061     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">
 1062       <synopsis>Allocate</synopsis>
 1063       <description>
 1064         Allocate an area of memory through the <jvmti/> allocator.
 1065         The allocated
 1066         memory should be freed with <functionlink id="Deallocate"></functionlink>.
 1067       </description>
 1068       <origin>jvmdi</origin>
 1069       <capabilities>
 1070       </capabilities>
 1071       <parameters>
 1072         <param id="size">
 1073           <jlong/>
 1074           <description>
 1075             The number of bytes to allocate.
 1076             <rationale>
 1077               <code>jlong</code> is used for compatibility with JVMDI.
 1078             </rationale>
 1079           </description>
 1080         </param>
 1081         <param id="mem_ptr">
 1082           <allocbuf incount="size"><uchar/></allocbuf>
 1083           <description>
 1084             On return, a pointer to the beginning of the allocated memory.
 1085             If <code>size</code> is zero, <code>NULL</code> is returned.
 1086           </description>
 1087         </param>
 1088       </parameters>
 1089       <errors>
 1090         <error id="JVMTI_ERROR_OUT_OF_MEMORY">
 1091           Memory request cannot be honored.
 1092         </error>
 1093         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 1094           <paramlink id="size"></paramlink> is less than zero.
 1095         </error>
 1096       </errors>
 1097     </function>
 1098 
 1099     <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">
 1100       <synopsis>Deallocate</synopsis>
 1101       <description>
 1102         Deallocate <code>mem</code>  using the <jvmti/> allocator.
 1103         This function should
 1104         be used to deallocate any memory allocated and returned
 1105         by a <jvmti/> function
 1106         (including memory allocated with <functionlink id="Allocate"></functionlink>).
 1107         All allocated memory must be deallocated
 1108         or the memory cannot be reclaimed.
 1109       </description>
 1110       <origin>jvmdi</origin>
 1111       <capabilities>
 1112       </capabilities>
 1113       <parameters>
 1114         <param id="mem">
 1115           <outbuf>
 1116             <uchar/>
 1117             <nullok>the call is ignored</nullok>
 1118           </outbuf>
 1119           <description>
 1120             A pointer to the beginning of the allocated memory.
 1121             Please ignore "On return, the elements are set."
 1122               <todo>keep it from generating "On return, the elements are set"</todo>
 1123           </description>
 1124         </param>
 1125       </parameters>
 1126       <errors>
 1127       </errors>
 1128     </function>
 1129   </category>
 1130 
 1131   <category id="threadCategory" label="Thread">
 1132     <intro>
 1133         These functions provide information about threads and allow an agent to
 1134         suspend and resume threads.
 1135         <p/>
 1136         The <code>jthread</code> specified to these functions can be a JNI
 1137         reference to a
 1138         <externallink id="../api/java.base/java/lang/Thread.html#platform-threads">platform thread</externallink>
 1139         or <externallink id="../api/java.base/java/lang/Thread.html#virtual-threads">virtual thread</externallink>.
 1140         Some functions are not supported on virtual threads and return
 1141         <code>JVMTI_ERROR_INVALID_THREAD</code> when called with a reference
 1142         to a virtual thread.
 1143     </intro>
 1144 
 1145     <function id="GetThreadState" num="17">
 1146       <synopsis>Get Thread State</synopsis>
 1147       <description>
 1148         Get the state of a thread.  The state of the thread is represented by the
 1149         answers to the hierarchical set of questions below:
 1150           <ul type="circle">
 1151             <li><i>Alive?</i>
 1152               <ul>
 1153                 <li>Not alive.
 1154                   <ul type="circle">
 1155                     <li><i>Why not alive?</i>
 1156                       <ul>
 1157                         <li>New.</li>
 1158                         <li>Terminated (<datalink
 1159                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>
 1160                       </ul>
 1161                     </li>
 1162                   </ul>
 1163                 </li>
 1164                 <li>Alive (<datalink
 1165                     id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)
 1166                   <ul type="circle">
 1167                     <li><i>Suspended?</i>
 1168                       <ul>
 1169                         <li>Suspended (<datalink
 1170                             id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>
 1171                         <li>Not suspended</li>
 1172                       </ul>
 1173                     </li>
 1174                     <li><i>Interrupted?</i>
 1175                       <ul>
 1176                         <li>Interrupted (<datalink
 1177                             id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>
 1178                         <li>Not interrupted.</li>
 1179                       </ul>
 1180                     </li>
 1181                     <li><i>In native?</i>
 1182                       <ul>
 1183                         <li>In native code (<datalink
 1184                             id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>
 1185                         <li>In Java programming language code</li>
 1186                       </ul>
 1187                     </li>
 1188                     <li><i>What alive state?</i>
 1189                       <ul>
 1190                         <li>Runnable (<datalink
 1191                             id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>
 1192                         <li>Blocked (<datalink
 1193                             id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>
 1194                         <li>Waiting (<datalink
 1195                             id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)
 1196                           <ul type="circle">
 1197                             <li><i>Timed wait?</i>
 1198                               <ul>
 1199                                 <li>Indefinite (<datalink
 1200                                     id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>
 1201                                 <li>Timed (<datalink
 1202                                     id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>
 1203                               </ul>
 1204                             </li>
 1205                             <li><i>Why waiting?</i>
 1206                               <ul>
 1207                                 <li>Object.wait (<datalink
 1208                                     id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>
 1209                                 <li>LockSupport.park (<datalink
 1210                                     id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>
 1211                                 <li>Sleeping (<datalink
 1212                                     id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>
 1213                               </ul>
 1214                             </li>
 1215                           </ul>
 1216                         </li>
 1217                       </ul>
 1218                     </li>
 1219                   </ul>
 1220                 </li>
 1221               </ul>
 1222             </li>
 1223           </ul>
 1224         <p/>
 1225         The answers are represented by the following bit vector.
 1226         <constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">
 1227           <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">
 1228             Thread is alive. Zero if thread is new (not started) or terminated.
 1229           </constant>
 1230           <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">
 1231             Thread has completed execution.
 1232           </constant>
 1233           <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">
 1234             Thread is runnable.
 1235           </constant>
 1236           <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">
 1237             Thread is waiting to enter a synchronized block/method or,
 1238             after an <code>Object.wait()</code>, waiting to re-enter a
 1239             synchronized block/method.
 1240           </constant>
 1241           <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">
 1242             Thread is waiting.
 1243           </constant>
 1244           <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">
 1245             Thread is waiting without a timeout.
 1246             For example, <code>Object.wait()</code>.
 1247           </constant>
 1248           <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">
 1249             Thread is waiting with a maximum time to wait specified.
 1250             For example, <code>Object.wait(long)</code>.
 1251           </constant>
 1252           <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">
 1253             Thread is sleeping -- <code>Thread.sleep</code>.
 1254           </constant>
 1255           <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">
 1256             Thread is waiting on an object monitor -- <code>Object.wait</code>.
 1257           </constant>
 1258           <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">
 1259             Thread is parked, for example: <code>LockSupport.park</code>,
 1260             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.
 1261             A virtual thread that is sleeping, in <code>Thread.sleep</code>, may
 1262             have this state flag set instead of <code>JVMTI_THREAD_STATE_SLEEPING</code>.
 1263           </constant>
 1264           <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">
 1265             Thread suspended.
 1266             <code>java.lang.Thread.suspend()</code>
 1267             or a <jvmti/> suspend function
 1268             (such as <functionlink id="SuspendThread"></functionlink>)
 1269             has been called on the thread. If this bit
 1270             is set, the other bits refer to the thread state before suspension.
 1271           </constant>
 1272           <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">
 1273             Thread has been interrupted.
 1274           </constant>
 1275           <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">
 1276             Thread is in native code--that is, a native method is running
 1277             which has not called back into the VM or Java programming
 1278             language code.
 1279             <p/>
 1280             This flag is not set when running VM compiled Java programming
 1281             language code nor is it set when running VM code or
 1282             VM support code. Native VM interface functions, such as JNI and
 1283             <jvmti/> functions, may be implemented as VM code.
 1284           </constant>
 1285           <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">
 1286             Defined by VM vendor.
 1287           </constant>
 1288           <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">
 1289             Defined by VM vendor.
 1290           </constant>
 1291           <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">
 1292             Defined by VM vendor.
 1293           </constant>
 1294         </constants>
 1295         The following definitions are used to convert <jvmti/> thread state
 1296         to <code>java.lang.Thread.State</code> style states.
 1297         <constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">
 1298           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"
 1299                      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">
 1300             Mask the state with this before comparison
 1301           </constant>
 1302           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"
 1303                      num="0">
 1304             <code>java.lang.Thread.State.NEW</code>
 1305           </constant>
 1306           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"
 1307                      num="JVMTI_THREAD_STATE_TERMINATED">
 1308             <code>java.lang.Thread.State.TERMINATED</code>
 1309           </constant>
 1310           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"
 1311                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">
 1312             <code>java.lang.Thread.State.RUNNABLE</code>
 1313           </constant>
 1314           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"
 1315                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">
 1316             <code>java.lang.Thread.State.BLOCKED</code>
 1317           </constant>
 1318           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"
 1319                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">
 1320             <code>java.lang.Thread.State.WAITING</code>
 1321           </constant>
 1322           <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"
 1323                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">
 1324             <code>java.lang.Thread.State.TIMED_WAITING</code>
 1325           </constant>
 1326         </constants>
 1327         <b>Rules</b>
 1328         <p/>
 1329         There can be no more than one answer to a question, although there can be no
 1330         answer (because the answer is unknown, does not apply, or none of the answers is
 1331         correct).  An answer is set only when the enclosing answers match.
 1332         That is, no more than one of
 1333           <ul type="circle">
 1334               <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>
 1335               <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>
 1336               <li><code>JVMTI_THREAD_STATE_WAITING</code></li>
 1337           </ul>
 1338         can be set (a <tm>J2SE</tm> compliant implementation will always set
 1339         one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set).
 1340         And if any of these are set, the enclosing answer
 1341         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
 1342         No more than one of
 1343           <ul type="circle">
 1344               <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>
 1345               <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>
 1346           </ul>
 1347         can be set (a <tm>J2SE</tm> compliant implementation will always set
 1348         one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set).
 1349         And if either is set, the enclosing answers
 1350         <code>JVMTI_THREAD_STATE_ALIVE</code> and
 1351         <code>JVMTI_THREAD_STATE_WAITING</code> are set.
 1352         No more than one of
 1353           <ul type="circle">
 1354               <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>
 1355               <li><code>JVMTI_THREAD_STATE_PARKED</code></li>
 1356               <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>
 1357           </ul>
 1358         can be set. And if any of these is set, the enclosing answers
 1359         <code>JVMTI_THREAD_STATE_ALIVE</code> and
 1360         <code>JVMTI_THREAD_STATE_WAITING</code> are set.
 1361         Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,
 1362         then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.
 1363         If a state <i>A</i> is implemented using the mechanism of
 1364         state <i>B</i> then it is state <i>A</i> which
 1365         is returned by this function.
 1366         For example, if <code>Thread.sleep(long)</code>
 1367         is implemented using <code>Object.wait(long)</code>
 1368         then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>
 1369         which is returned.
 1370         More than one of
 1371           <ul type="circle">
 1372               <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>
 1373               <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>
 1374               <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>
 1375           </ul>
 1376         can be set, but if any is set,
 1377         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.
 1378         <p/>
 1379         And finally,
 1380         <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless
 1381         <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.
 1382         <p/>
 1383         The thread state representation is designed for extension in future versions
 1384         of the specification; thread state values should be used accordingly, that is
 1385         they should not be used as ordinals.
 1386         Most queries can be made by testing a single bit, if use in a switch statement is desired,
 1387         the state bits should be masked with the interesting bits.
 1388         All bits not defined above are reserved for future use.
 1389         A VM, compliant to the current specification, must set reserved bits to zero.
 1390         An agent should ignore reserved bits --
 1391         they should not be assumed to be zero and thus should not be included in comparisons.
 1392         <p/>
 1393         <b>Examples</b>
 1394         <p/>
 1395         Note that the values below exclude reserved and vendor bits.
 1396         <p/>
 1397         The state of a thread blocked at a <code>synchronized</code>-statement would be:
 1398         <example>
 1399             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER
 1400         </example>
 1401         The state of a thread which hasn't started yet would be:
 1402         <example>
 1403             0
 1404         </example>
 1405         The state of a thread at a <code>Object.wait(3000)</code> would be:
 1406         <example>
 1407             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING +
 1408                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT +
 1409                 JVMTI_THREAD_STATE_MONITOR_WAITING
 1410         </example>
 1411         The state of a thread suspended while runnable would be:
 1412         <example>
 1413             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED
 1414         </example>
 1415         <p/>
 1416         <b>Testing the State</b>
 1417         <p/>
 1418         In most cases, the thread state can be determined by testing the one bit corresponding
 1419         to that question.  For example, the code to test if a thread is sleeping:
 1420         <example>
 1421         jint state;
 1422         jvmtiError err;
 1423 
 1424         err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
 1425         if (err == JVMTI_ERROR_NONE) {
 1426            if (state &amp; JVMTI_THREAD_STATE_SLEEPING) {  ...
 1427         </example>
 1428         <p/>
 1429         For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:
 1430         <example>
 1431            if (state &amp; JVMTI_THREAD_STATE_WAITING) {  ...
 1432         </example>
 1433         For some states, more than one bit will need to be tested as is the case
 1434         when testing if a thread has not yet been started:
 1435         <example>
 1436            if ((state &amp; (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...
 1437         </example>
 1438         To distinguish timed from untimed <code>Object.wait</code>:
 1439         <example>
 1440            if (state &amp; JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {
 1441              if (state &amp; JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {
 1442                printf("in Object.wait(long timeout)\n");
 1443              } else {
 1444                printf("in Object.wait()\n");
 1445              }
 1446            }
 1447         </example>
 1448         <p/>
 1449         <b>Relationship to <code>java.lang.Thread.State</code></b>
 1450         <p/>
 1451         The thread state represented by <code>java.lang.Thread.State</code>
 1452         returned from <code>java.lang.Thread.getState()</code> is a subset of the
 1453         information returned from this function.
 1454         The corresponding <code>java.lang.Thread.State</code> can be determined
 1455         by using the provided conversion masks.
 1456         For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:
 1457         <example>
 1458             err = (*jvmti)-&gt;GetThreadState(jvmti, thread, &amp;state);
 1459             abortOnError(err);
 1460             switch (state &amp; JVMTI_JAVA_LANG_THREAD_STATE_MASK) {
 1461             case JVMTI_JAVA_LANG_THREAD_STATE_NEW:
 1462               return "NEW";
 1463             case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:
 1464               return "TERMINATED";
 1465             case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:
 1466               return "RUNNABLE";
 1467             case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:
 1468               return "BLOCKED";
 1469             case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:
 1470               return "WAITING";
 1471             case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:
 1472               return "TIMED_WAITING";
 1473             }
 1474         </example>
 1475       </description>
 1476       <origin>new</origin>
 1477       <capabilities>
 1478       </capabilities>
 1479       <parameters>
 1480         <param id="thread">
 1481           <jthread null="current" started="maybe" impl="noconvert"/>
 1482             <description>
 1483               The thread to query.
 1484             </description>
 1485         </param>
 1486         <param id="thread_state_ptr">
 1487           <outptr><jint/></outptr>
 1488           <description>
 1489             On return, points to state flags,
 1490             as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.
 1491           </description>
 1492         </param>
 1493       </parameters>
 1494       <errors>
 1495       </errors>
 1496     </function>
 1497 
 1498     <function id="GetCurrentThread" phase="start" num="18" since="1.1">
 1499       <synopsis>Get Current Thread</synopsis>
 1500       <description>
 1501         Get the current thread.
 1502         The current thread is the Java programming language thread which has called the function.
 1503         The function may return <code>NULL</code> in the start phase if the
 1504         <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
 1505         <code>can_generate_early_vmstart</code></internallink> capability is enabled
 1506         and the <code>java.lang.Thread</code> class has not been initialized yet.
 1507         <p/>
 1508         Note that most <jvmti/> functions that take a thread
 1509         as an argument will accept <code>NULL</code> to mean
 1510         the current thread.
 1511       </description>
 1512       <origin>new</origin>
 1513       <capabilities>
 1514       </capabilities>
 1515       <parameters>
 1516         <param id="thread_ptr">
 1517           <outptr><jthread/></outptr>
 1518           <description>
 1519              On return, points to the current thread, or <code>NULL</code>.
 1520           </description>
 1521         </param>
 1522       </parameters>
 1523       <errors>
 1524       </errors>
 1525     </function>
 1526 
 1527     <function id="GetAllThreads" num="4">
 1528       <synopsis>Get All Threads</synopsis>
 1529       <description>
 1530         Get all live platform threads that are attached to the VM.
 1531         The list of threads includes
 1532         <internallink id="RunAgentThread">agent threads</internallink>.
 1533         It does not include virtual threads.
 1534         A thread is live if <code>java.lang.Thread.isAlive()</code>
 1535         would return <code>true</code>, that is, the thread has
 1536         been started and has not yet died.
 1537         The universe of threads is determined by the context of the <jvmti/>
 1538         environment, which typically is all threads attached to the VM.
 1539       </description>
 1540       <origin>jvmdi</origin>
 1541       <capabilities>
 1542       </capabilities>
 1543       <parameters>
 1544         <param id="threads_count_ptr">
 1545           <outptr><jint/></outptr>
 1546           <description>
 1547             On return, points to the number of threads.
 1548           </description>
 1549         </param>
 1550         <param id="threads_ptr">
 1551           <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>
 1552             <description>
 1553               On return, points to an array of references, one
 1554               for each thread.
 1555             </description>
 1556         </param>
 1557       </parameters>
 1558       <errors>
 1559       </errors>
 1560     </function>
 1561 
 1562     <function id="SuspendThread" num="5">
 1563       <synopsis>Suspend Thread</synopsis>
 1564       <description>
 1565         Suspend the specified thread. If the calling thread is specified,
 1566         this function will not return until some other thread calls
 1567         <functionlink id="ResumeThread"></functionlink>.
 1568         If the thread is currently suspended, this function
 1569         does nothing and returns an error.
 1570       </description>
 1571       <origin>jvmdi</origin>
 1572       <capabilities>
 1573         <required id="can_suspend"></required>
 1574       </capabilities>
 1575       <parameters>
 1576         <param id="thread">
 1577           <jthread null="current" impl="noconvert"/>
 1578             <description>
 1579               The thread to suspend.
 1580             </description>
 1581         </param>
 1582       </parameters>
 1583       <errors>
 1584         <error id="JVMTI_ERROR_THREAD_SUSPENDED">
 1585           Thread already suspended.
 1586         </error>
 1587       </errors>
 1588     </function>
 1589 
 1590     <elide>
 1591     <function id="SuspendAllThreads" num="101">
 1592       <synopsis>Suspend All Threads</synopsis>
 1593       <description>
 1594         <issue>
 1595             There has been no explicit call for this function, and it will
 1596             thus be removed if there is no interest.
 1597         </issue>
 1598         Suspend all live threads except:
 1599         <ul>
 1600           <li>already suspended threads</li>
 1601           <li>those listed in <paramlink id="except_list"></paramlink></li>
 1602           <li>certain system (non application) threads, as determined
 1603             by the VM implementation</li>
 1604         </ul>
 1605         The threads are Java programming language threads;
 1606         native threads which are not attached to the VM are not
 1607         Java programming language threads.
 1608         A thread is live if <code>java.lang.Thread.isAlive()</code>
 1609         would return <code>true</code>, that is, the thread has
 1610         been started and has not yet died.
 1611         The universe of threads is determined
 1612         by the context of the <jvmti/>
 1613         environment, which, typically, is all threads attached to the VM,
 1614         except critical VM internal threads and <jvmti/> agent threads
 1615         (see <functionlink id="RunAgentThread"/>).
 1616         <p/>
 1617         If the calling thread is specified,
 1618         all other threads are suspended first then the caller thread is suspended -
 1619         this function will not return until some other thread calls
 1620         <functionlink id="ResumeThread"></functionlink>.
 1621         <p/>
 1622         The list of actually
 1623         suspended threads is returned in
 1624         <paramlink id="suspended_list_ptr"></paramlink>.
 1625         Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.
 1626         <functionlink id="ResumeThreadList"></functionlink>
 1627         can be used to resume the suspended threads.
 1628       </description>
 1629       <origin>new</origin>
 1630       <capabilities>
 1631         <required id="can_suspend"></required>
 1632       </capabilities>
 1633       <parameters>
 1634         <param id="except_count">
 1635           <jint min="0"/>
 1636           <description>
 1637             The number of threads in the list of threads not to be suspended.
 1638           </description>
 1639         </param>
 1640         <param id="except_list">
 1641             <inbuf incount="except_count">
 1642               <jthread/>
 1643               <nullok>not an error if <code>except_count == 0</code></nullok>
 1644             </inbuf>
 1645             <description>
 1646               The list of threads not to be suspended.
 1647             </description>
 1648         </param>
 1649         <param id="suspended_count_ptr">
 1650           <outptr><jint/></outptr>
 1651           <description>
 1652             On return, points to the number of threads suspended by this call.
 1653           </description>
 1654         </param>
 1655         <param id="suspended_list_ptr">
 1656           <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>
 1657             <description>
 1658               On return, points to an array of references, one
 1659               for each thread suspended.
 1660             </description>
 1661         </param>
 1662       </parameters>
 1663       <errors>
 1664         <error id="JVMTI_ERROR_INVALID_THREAD">
 1665           A thread in <paramlink id="except_list"></paramlink> was invalid.
 1666         </error>
 1667         <error id="JVMTI_ERROR_NULL_POINTER">
 1668           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
 1669           and <paramlink id="except_count"></paramlink> was non-zero.
 1670         </error>
 1671       </errors>
 1672     </function>
 1673     </elide>
 1674 
 1675     <function id="SuspendThreadList" num="92">
 1676       <synopsis>Suspend Thread List</synopsis>
 1677       <description>
 1678         Suspend the <paramlink id="request_count"></paramlink>
 1679         threads specified in the
 1680         <paramlink id="request_list"></paramlink> array.
 1681         Threads may be resumed with
 1682         <functionlink id="ResumeThreadList"></functionlink> or
 1683         <functionlink id="ResumeThread"></functionlink>.
 1684         If the calling thread is specified in the
 1685         <paramlink id="request_list"></paramlink> array, this function will
 1686         not return until some other thread resumes it.
 1687         Errors encountered in the suspension of a thread
 1688         are returned in the <paramlink id="results"></paramlink>
 1689         array, <b>not</b> in the return value of this function.
 1690         Threads that are currently suspended do not change state.
 1691       </description>
 1692       <origin>jvmdi</origin>
 1693       <capabilities>
 1694         <required id="can_suspend"></required>
 1695       </capabilities>
 1696       <parameters>
 1697         <param id="request_count">
 1698           <jint min="0"/>
 1699           <description>
 1700             The number of threads to suspend.
 1701           </description>
 1702         </param>
 1703         <param id="request_list">
 1704           <inbuf incount="request_count"><jthread/></inbuf>
 1705             <description>
 1706               The list of threads to suspend.
 1707             </description>
 1708         </param>
 1709         <param id="results">
 1710           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
 1711           <description>
 1712             An agent supplied array of
 1713             <paramlink id="request_count"></paramlink> elements.
 1714             On return, filled with the error code for
 1715             the suspend of the corresponding thread.
 1716             The error code will be
 1717             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
 1718             if the thread was suspended by this call.
 1719             Possible error codes are those specified
 1720             for <functionlink id="SuspendThread"></functionlink>.
 1721           </description>
 1722         </param>
 1723       </parameters>
 1724       <errors>
 1725       </errors>
 1726     </function>
 1727 
 1728     <function id="SuspendAllVirtualThreads" num="118" since="16">
 1729       <synopsis>Suspend All Virtual Threads</synopsis>
 1730       <description>
 1731         <b> SuspendAllVirtualThreads is a preview API of the Java platform. </b>
 1732         <i>Preview features may be removed in a future release, or upgraded to
 1733         permanent features of the Java platform.</i>.
 1734         <p/>
 1735         Suspend all virtual threads except those already suspended.
 1736         Virtual threads may be resumed with
 1737         <functionlink id="ResumeAllVirtualThreads"></functionlink> or
 1738         <functionlink id="ResumeThreadList"></functionlink> or
 1739         <functionlink id="ResumeThread"></functionlink>.
 1740         Virtual threads that are currently suspended do not change state.
 1741       </description>
 1742       <origin>new</origin>
 1743       <capabilities>
 1744         <required id="can_suspend"></required>
 1745         <required id="can_support_virtual_threads"></required>
 1746       </capabilities>
 1747       <parameters>
 1748         <param id="except_count">
 1749           <jint min="0"/>
 1750           <description>
 1751             The number of threads in the list of threads not to be suspended.
 1752           </description>
 1753         </param>
 1754         <param id="except_list">
 1755             <inbuf incount="except_count">
 1756               <jthread/>
 1757               <nullok>not an error if <code>except_count == 0</code></nullok>
 1758             </inbuf>
 1759             <description>
 1760               The list of threads not to be suspended.
 1761             </description>
 1762         </param>
 1763       </parameters>
 1764       <errors>
 1765         <error id="JVMTI_ERROR_INVALID_THREAD">
 1766           A thread in <paramlink id="except_list"></paramlink> was invalid.
 1767         </error>
 1768         <error id="JVMTI_ERROR_NULL_POINTER">
 1769           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
 1770           and <paramlink id="except_count"></paramlink> was non-zero.
 1771         </error>
 1772       </errors>
 1773     </function>
 1774 
 1775     <function id="ResumeThread" num="6">
 1776       <synopsis>Resume Thread</synopsis>
 1777       <description>
 1778         Resume a suspended thread.
 1779         Any threads currently suspended through
 1780         a <jvmti/> suspend function (eg.
 1781         <functionlink id="SuspendThread"></functionlink>)
 1782         or <code>java.lang.Thread.suspend()</code>
 1783         will resume execution;
 1784         all other threads are unaffected.
 1785       </description>
 1786       <origin>jvmdi</origin>
 1787       <capabilities>
 1788         <required id="can_suspend"></required>
 1789       </capabilities>
 1790       <parameters>
 1791         <param id="thread">
 1792           <jthread impl="noconvert"/>
 1793             <description>
 1794               The thread to resume.
 1795             </description>
 1796         </param>
 1797       </parameters>
 1798       <errors>
 1799         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 1800           Thread was not suspended.
 1801         </error>
 1802         <error id="JVMTI_ERROR_INVALID_TYPESTATE">
 1803           The state of the thread has been modified, and is now inconsistent.
 1804         </error>
 1805       </errors>
 1806     </function>
 1807 
 1808     <function id="ResumeThreadList" num="93">
 1809       <synopsis>Resume Thread List</synopsis>
 1810       <description>
 1811         Resume the <paramlink id="request_count"></paramlink>
 1812         threads specified in the
 1813         <paramlink id="request_list"></paramlink> array.
 1814         Any thread suspended through
 1815         a <jvmti/> suspend function (eg.
 1816         <functionlink id="SuspendThreadList"></functionlink>)
 1817         or <code>java.lang.Thread.suspend()</code>
 1818         will resume execution.
 1819       </description>
 1820       <origin>jvmdi</origin>
 1821       <capabilities>
 1822         <required id="can_suspend"></required>
 1823       </capabilities>
 1824       <parameters>
 1825         <param id="request_count">
 1826           <jint min="0"/>
 1827           <description>
 1828             The number of threads to resume.
 1829           </description>
 1830         </param>
 1831         <param id="request_list">
 1832           <inbuf incount="request_count"><jthread/></inbuf>
 1833             <description>
 1834               The threads to resume.
 1835             </description>
 1836         </param>
 1837         <param id="results">
 1838           <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>
 1839           <description>
 1840             An agent supplied array of
 1841             <paramlink id="request_count"></paramlink> elements.
 1842             On return, filled with the error code for
 1843             the resume of the corresponding thread.
 1844             The error code will be
 1845             <errorlink id="JVMTI_ERROR_NONE"></errorlink>
 1846             if the thread was suspended by this call.
 1847             Possible error codes are those specified
 1848             for <functionlink id="ResumeThread"></functionlink>.
 1849           </description>
 1850         </param>
 1851       </parameters>
 1852       <errors>
 1853       </errors>
 1854     </function>
 1855 
 1856    <function id="ResumeAllVirtualThreads" num="119" since="16">
 1857       <synopsis>Resume All Virtual Threads</synopsis>
 1858       <description>
 1859         <b> SuspendAllVirtualThreads is a preview API of the Java platform. </b>
 1860         <i>Preview features may be removed in a future release, or upgraded to
 1861         permanent features of the Java platform.</i>.
 1862         <p/>
 1863         Resume all virtual threads except those already resumed.
 1864         Virtual threads may be suspended with
 1865         <functionlink id="SuspendAllVirtualThreads"></functionlink> or
 1866         <functionlink id="SuspendThreadList"></functionlink> or
 1867         <functionlink id="SuspendThread"></functionlink>.
 1868         Virtual threads that are currently resumed do not change state.
 1869       </description>
 1870       <origin>new</origin>
 1871       <capabilities>
 1872         <required id="can_suspend"></required>
 1873         <required id="can_support_virtual_threads"></required>
 1874       </capabilities>
 1875       <parameters>
 1876         <param id="except_count">
 1877           <jint min="0"/>
 1878           <description>
 1879             The number of threads in the list of threads not to be resumed.
 1880           </description>
 1881         </param>
 1882         <param id="except_list">
 1883             <inbuf incount="except_count">
 1884               <jthread/>
 1885               <nullok>not an error if <code>except_count == 0</code></nullok>
 1886             </inbuf>
 1887             <description>
 1888               The list of threads not to be resumed.
 1889             </description>
 1890         </param>
 1891       </parameters>
 1892       <errors>
 1893         <error id="JVMTI_ERROR_INVALID_THREAD">
 1894           A thread in <paramlink id="except_list"></paramlink> was invalid.
 1895         </error>
 1896         <error id="JVMTI_ERROR_NULL_POINTER">
 1897           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>
 1898           and <paramlink id="except_count"></paramlink> was non-zero.
 1899         </error>
 1900       </errors>
 1901     </function>
 1902 
 1903     <function id="StopThread" num="7">
 1904       <synopsis>Stop Thread</synopsis>
 1905       <description>
 1906         Send the specified asynchronous exception to the specified platform thread.
 1907         Normally, this function is used to kill the specified thread with an
 1908         instance of the exception <code>ThreadDeath</code>, similar to
 1909         <code>java.lang.Thread.stop</code>.
 1910       </description>
 1911       <origin>jvmdi</origin>
 1912       <capabilities>
 1913         <required id="can_signal_thread"></required>
 1914       </capabilities>
 1915       <parameters>
 1916         <param id="thread">
 1917           <jthread/>
 1918             <description>
 1919               The thread to stop.
 1920               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
 1921               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
 1922              </description>
 1923         </param>
 1924         <param id="exception">
 1925           <jobject/>
 1926             <description>
 1927               The asynchronous exception object.
 1928             </description>
 1929         </param>
 1930       </parameters>
 1931       <errors>
 1932         <error id="JVMTI_ERROR_INVALID_THREAD">
 1933           <paramlink id="thread"/> is a virtual thread.
 1934         </error>
 1935       </errors>
 1936     </function>
 1937 
 1938     <function id="InterruptThread" num="8">
 1939       <synopsis>Interrupt Thread</synopsis>
 1940       <description>
 1941         Interrupt the specified thread
 1942         (similar to <code>java.lang.Thread.interrupt</code>).
 1943       </description>
 1944       <origin>jvmdi</origin>
 1945       <capabilities>
 1946         <required id="can_signal_thread"></required>
 1947       </capabilities>
 1948       <parameters>
 1949         <param id="thread">
 1950           <jthread impl="noconvert"/>
 1951             <description>
 1952               The thread to interrupt.
 1953             </description>
 1954         </param>
 1955       </parameters>
 1956       <errors>
 1957       </errors>
 1958     </function>
 1959 
 1960     <function id="GetThreadInfo" num="9">
 1961       <synopsis>Get Thread Info</synopsis>
 1962       <typedef id="jvmtiThreadInfo" label="Thread information structure">
 1963         <field id="name">
 1964           <allocfieldbuf><char/></allocfieldbuf>
 1965           <description>
 1966             The thread name, encoded as a
 1967             <internallink id="mUTF">modified UTF-8</internallink> string.
 1968           </description>
 1969         </field>
 1970         <field id="priority">
 1971           <jint/>
 1972           <description>
 1973             The thread priority.  See the thread priority constants:
 1974             <datalink id="jvmtiThreadPriority"></datalink>. The priority of a
 1975             virtual thread is always <code>JVMTI_THREAD_NORM_PRIORITY</code>.
 1976           </description>
 1977         </field>
 1978         <field id="is_daemon">
 1979           <jboolean/>
 1980           <description>
 1981             Is this a daemon thread? The daemon status of a virtual thread is
 1982             always <code>JNI_TRUE</code>.
 1983           </description>
 1984         </field>
 1985         <field id="thread_group">
 1986           <jthreadGroup/>
 1987           <description>
 1988             The thread group to which this thread belongs.
 1989             <code>NULL</code> if the thread has died.
 1990           </description>
 1991         </field>
 1992         <field id="context_class_loader">
 1993           <jobject/>
 1994             <description>
 1995               The context class loader associated with this thread.
 1996             </description>
 1997         </field>
 1998       </typedef>
 1999       <description>
 2000         Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure
 2001         are filled in with details of the specified thread.
 2002       </description>
 2003       <origin>jvmdi</origin>
 2004       <capabilities>
 2005       </capabilities>
 2006       <parameters>
 2007         <param id="thread">
 2008           <jthread null="current" impl="noconvert" started="maybe"/>
 2009             <description>
 2010               The thread to query.
 2011             </description>
 2012         </param>
 2013         <param id="info_ptr">
 2014           <outptr><struct>jvmtiThreadInfo</struct></outptr>
 2015           <description>
 2016             On return, filled with information describing the specified thread.
 2017           </description>
 2018         </param>
 2019       </parameters>
 2020       <errors>
 2021       </errors>
 2022     </function>
 2023 
 2024     <function id="GetOwnedMonitorInfo" num="10">
 2025       <synopsis>Get Owned Monitor Info</synopsis>
 2026       <description>
 2027         Get information about the monitors owned by the
 2028         specified thread.
 2029       </description>
 2030       <origin>jvmdiClone</origin>
 2031       <capabilities>
 2032         <required id="can_get_owned_monitor_info"></required>
 2033       </capabilities>
 2034       <parameters>
 2035         <param id="thread">
 2036           <jthread null="current" impl="noconvert"/>
 2037             <description>
 2038               The thread to query.
 2039             </description>
 2040         </param>
 2041         <param id="owned_monitor_count_ptr">
 2042           <outptr><jint/></outptr>
 2043           <description>
 2044             The number of monitors returned.
 2045           </description>
 2046         </param>
 2047         <param id="owned_monitors_ptr">
 2048           <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>
 2049             <description>
 2050               The array of owned monitors.
 2051             </description>
 2052         </param>
 2053       </parameters>
 2054       <errors>
 2055       </errors>
 2056     </function>
 2057 
 2058     <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">
 2059       <synopsis>Get Owned Monitor Stack Depth Info</synopsis>
 2060       <typedef id="jvmtiMonitorStackDepthInfo"
 2061                label="Monitor stack depth information structure">
 2062         <field id="monitor">
 2063           <jobject/>
 2064             <description>
 2065               The owned monitor.
 2066             </description>
 2067         </field>
 2068         <field id="stack_depth">
 2069           <jint/>
 2070           <description>
 2071             The stack depth.  Corresponds to the stack depth used in the
 2072             <internallink id="stack">Stack Frame functions</internallink>.
 2073             That is, zero is the current frame, one is the frame which
 2074             called the current frame. And it is negative one if the
 2075             implementation cannot determine the stack depth (e.g., for
 2076             monitors acquired by JNI <code>MonitorEnter</code>).
 2077           </description>
 2078         </field>
 2079       </typedef>
 2080       <description>
 2081         Get information about the monitors owned by the
 2082         specified thread and the depth of the stack frame which locked them.
 2083       </description>
 2084       <origin>new</origin>
 2085       <capabilities>
 2086         <required id="can_get_owned_monitor_stack_depth_info"></required>
 2087       </capabilities>
 2088       <parameters>
 2089         <param id="thread">
 2090           <jthread null="current" impl="noconvert"/>
 2091             <description>
 2092               The thread to query.
 2093             </description>
 2094         </param>
 2095         <param id="monitor_info_count_ptr">
 2096           <outptr><jint/></outptr>
 2097           <description>
 2098             The number of monitors returned.
 2099           </description>
 2100         </param>
 2101         <param id="monitor_info_ptr">
 2102           <allocbuf outcount="monitor_info_count_ptr">
 2103             <struct>jvmtiMonitorStackDepthInfo</struct>
 2104           </allocbuf>
 2105           <description>
 2106             The array of owned monitor depth information.
 2107           </description>
 2108         </param>
 2109       </parameters>
 2110       <errors>
 2111       </errors>
 2112     </function>
 2113 
 2114     <function id="GetCurrentContendedMonitor" num="11">
 2115       <synopsis>Get Current Contended Monitor</synopsis>
 2116       <description>
 2117         Get the object, if any, whose monitor the specified thread is waiting to
 2118         enter or waiting to regain through <code>java.lang.Object.wait</code>.
 2119       </description>
 2120       <origin>jvmdi</origin>
 2121       <capabilities>
 2122         <required id="can_get_current_contended_monitor"></required>
 2123       </capabilities>
 2124       <parameters>
 2125         <param id="thread">
 2126           <jthread null="current" impl="noconvert"/>
 2127             <description>
 2128               The thread to query.
 2129             </description>
 2130         </param>
 2131         <param id="monitor_ptr">
 2132           <outptr><jobject/></outptr>
 2133             <description>
 2134               On return, filled with the current contended monitor, or
 2135               NULL if there is none.
 2136             </description>
 2137         </param>
 2138       </parameters>
 2139       <errors>
 2140       </errors>
 2141     </function>
 2142 
 2143     <callback id="jvmtiStartFunction">
 2144       <void/>
 2145       <synopsis>Agent Start Function</synopsis>
 2146       <description>
 2147         Agent supplied callback function.
 2148         This function is the entry point for an agent thread
 2149         started with
 2150         <functionlink id="RunAgentThread"></functionlink>.
 2151       </description>
 2152       <parameters>
 2153           <param id="jvmti_env">
 2154             <outptr>
 2155               <struct>jvmtiEnv</struct>
 2156             </outptr>
 2157             <description>
 2158               The <jvmti/> environment.
 2159             </description>
 2160           </param>
 2161           <param id="jni_env">
 2162             <outptr>
 2163               <struct>JNIEnv</struct>
 2164             </outptr>
 2165             <description>
 2166               The JNI environment.
 2167             </description>
 2168           </param>
 2169           <param id="arg">
 2170             <outptr>
 2171               <void/>
 2172             </outptr>
 2173               <description>
 2174                 The <code>arg</code> parameter passed to
 2175                 <functionlink id="RunAgentThread"></functionlink>.
 2176               </description>
 2177           </param>
 2178       </parameters>
 2179     </callback>
 2180 
 2181     <function id="RunAgentThread" num="12">
 2182       <synopsis>Run Agent Thread</synopsis>
 2183       <description>
 2184         Starts the execution of an agent thread. with the specified native function.
 2185         The parameter <paramlink id="arg"></paramlink> is forwarded on to the
 2186         <functionlink id="jvmtiStartFunction">start function</functionlink>
 2187         (specified with <paramlink id="proc"></paramlink>) as its single argument.
 2188         This function allows the creation of agent threads
 2189         for handling communication with another process or for handling events
 2190         without the need to load a special subclass of <code>java.lang.Thread</code> or
 2191         implementer of <code>java.lang.Runnable</code>.
 2192         Instead, the created thread can run entirely in native code.
 2193         However, the created thread does require a newly created instance
 2194         of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to
 2195         which it will be associated.
 2196         The thread object can be created with JNI calls.
 2197         <p/>
 2198         The following common thread priorities are provided for your convenience:
 2199         <constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">
 2200           <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">
 2201             Minimum possible thread priority
 2202           </constant>
 2203           <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">
 2204             Normal thread priority
 2205           </constant>
 2206           <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">
 2207             Maximum possible thread priority
 2208           </constant>
 2209         </constants>
 2210         <p/>
 2211         The new thread is started as a daemon thread with the specified
 2212         <paramlink id="priority"></paramlink>.
 2213         If enabled, a <eventlink id="ThreadStart"/> event will be sent.
 2214         <p/>
 2215         Since the thread has been started, the thread will be live when this function
 2216         returns, unless the thread has died immediately.
 2217         <p/>
 2218         The thread group of the thread is ignored -- specifically, the thread is not
 2219         added to the thread group and the thread is not seen on queries of the thread
 2220         group at either the Java programming language or <jvmti/> levels.
 2221         <p/>
 2222         The thread is not visible to Java programming language queries but is
 2223         included in <jvmti/> queries (for example,
 2224         <functionlink id="GetAllThreads"/> and
 2225         <functionlink id="GetAllStackTraces"/>).
 2226         <p/>
 2227         Upon execution of <code>proc</code>, the new thread will be attached to the
 2228         VM -- see the JNI documentation on
 2229         <externallink id="jni/invocation.html#attaching-to-the-vm"
 2230                       >Attaching to the VM</externallink>.
 2231       </description>
 2232       <origin>jvmdiClone</origin>
 2233       <capabilities>
 2234       </capabilities>
 2235       <parameters>
 2236         <param id="thread">
 2237           <jthread impl="noconvert" started="no"/>
 2238             <description>
 2239               The thread to run.
 2240               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
 2241               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
 2242              </description>
 2243         </param>
 2244         <param id="proc">
 2245           <ptrtype>
 2246             <struct>jvmtiStartFunction</struct>
 2247           </ptrtype>
 2248           <description>
 2249             The start function.
 2250           </description>
 2251         </param>
 2252         <param id="arg">
 2253           <inbuf>
 2254             <void/>
 2255             <nullok><code>NULL</code> is passed to the start function</nullok>
 2256           </inbuf>
 2257           <description>
 2258             The argument to the start function.
 2259           </description>
 2260         </param>
 2261         <param id="priority">
 2262           <jint/>
 2263           <description>
 2264             The priority of the started thread. Any thread
 2265             priority allowed by <code>java.lang.Thread.setPriority</code> can be used including
 2266             those in <datalink id="jvmtiThreadPriority"></datalink>.
 2267           </description>
 2268         </param>
 2269       </parameters>
 2270       <errors>
 2271         <error id="JVMTI_ERROR_INVALID_PRIORITY">
 2272             <paramlink id="priority"/> is less than
 2273             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>
 2274               or greater than
 2275             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>
 2276         </error>
 2277         <error id="JVMTI_ERROR_INVALID_THREAD">
 2278           <paramlink id="thread"/> is a virtual thread.
 2279         </error>
 2280       </errors>
 2281     </function>
 2282 
 2283     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">
 2284       <synopsis>Set Thread Local Storage</synopsis>
 2285       <description>
 2286         The VM stores a pointer value associated with each environment-thread
 2287         pair. This pointer value is called <i>thread-local storage</i>.
 2288         This value is <code>NULL</code> unless set with this function.
 2289         Agents can allocate memory in which they store thread specific
 2290         information. By setting thread-local storage it can then be
 2291         accessed with
 2292         <functionlink id="GetThreadLocalStorage"></functionlink>.
 2293         <p/>
 2294         This function is called by the agent to set the value of the <jvmti/>
 2295         thread-local storage. <jvmti/> supplies to the agent a pointer-size
 2296         thread-local storage that can be used to record per-thread
 2297         information.
 2298       </description>
 2299       <origin>jvmpi</origin>
 2300       <capabilities>
 2301       </capabilities>
 2302       <parameters>
 2303         <param id="thread">
 2304           <jthread null="current" impl="noconvert"/>
 2305             <description>
 2306               Store to this thread.
 2307             </description>
 2308         </param>
 2309         <param id="data">
 2310           <inbuf>
 2311             <void/>
 2312             <nullok>value is set to <code>NULL</code></nullok>
 2313           </inbuf>
 2314           <description>
 2315             The value to be entered into the thread-local storage.
 2316           </description>
 2317         </param>
 2318       </parameters>
 2319       <errors>
 2320       </errors>
 2321     </function>
 2322 
 2323     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">
 2324       <synopsis>Get Thread Local Storage</synopsis>
 2325       <description>
 2326         Called by the agent to get the value of the <jvmti/> thread-local
 2327         storage.
 2328       </description>
 2329       <origin>jvmpi</origin>
 2330       <capabilities>
 2331       </capabilities>
 2332       <parameters>
 2333         <param id="thread">
 2334           <jthread null="current" impl="noconvert"/>
 2335             <description>
 2336               Retrieve from this thread.
 2337             </description>
 2338         </param>
 2339         <param id="data_ptr">
 2340           <agentbuf><void/></agentbuf>
 2341           <description>
 2342             Pointer through which the value of the thread local
 2343             storage is returned.
 2344             If thread-local storage has not been set with
 2345             <functionlink id="SetThreadLocalStorage"></functionlink> the returned
 2346             pointer is <code>NULL</code>.
 2347           </description>
 2348         </param>
 2349       </parameters>
 2350       <errors>
 2351       </errors>
 2352     </function>
 2353 
 2354   </category>
 2355 
 2356   <category id="thread_groups" label="Thread Group">
 2357     <intro>
 2358     </intro>
 2359 
 2360     <function id="GetTopThreadGroups" num="13">
 2361       <synopsis>Get Top Thread Groups</synopsis>
 2362       <description>
 2363         Return all top-level (parentless) thread groups in the VM.
 2364       </description>
 2365       <origin>jvmdi</origin>
 2366       <capabilities>
 2367       </capabilities>
 2368       <parameters>
 2369         <param id="group_count_ptr">
 2370           <outptr><jint/></outptr>
 2371           <description>
 2372             On return, points to the number of top-level thread groups.
 2373           </description>
 2374         </param>
 2375         <param id="groups_ptr">
 2376           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
 2377             <description>
 2378               On return, refers to a pointer to the top-level thread group array.
 2379             </description>
 2380         </param>
 2381       </parameters>
 2382       <errors>
 2383       </errors>
 2384     </function>
 2385 
 2386     <function id="GetThreadGroupInfo" num="14">
 2387       <synopsis>Get Thread Group Info</synopsis>
 2388       <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">
 2389         <field id="parent">
 2390           <jthreadGroup/>
 2391           <description>
 2392             The parent thread group.
 2393           </description>
 2394         </field>
 2395         <field id="name">
 2396           <allocfieldbuf><char/></allocfieldbuf>
 2397           <description>
 2398             The thread group's name, encoded as a
 2399             <internallink id="mUTF">modified UTF-8</internallink> string.
 2400           </description>
 2401         </field>
 2402         <field id="max_priority">
 2403           <jint/>
 2404           <description>
 2405             The maximum priority for this thread group.
 2406           </description>
 2407         </field>
 2408         <field id="is_daemon">
 2409           <jboolean/>
 2410           <description>
 2411             <code>JNI_FALSE</code>.
 2412             The concept of daemon thread group no longer exists.
 2413           </description>
 2414         </field>
 2415       </typedef>
 2416       <description>
 2417         Get information about the thread group. The fields of the
 2418         <functionlink id="jvmtiThreadGroupInfo"></functionlink> structure
 2419         are filled in with details of the specified thread group.
 2420       </description>
 2421       <origin>jvmdi</origin>
 2422       <capabilities>
 2423       </capabilities>
 2424       <parameters>
 2425         <param id="group">
 2426           <jthreadGroup/>
 2427           <description>
 2428             The thread group to query.
 2429           </description>
 2430         </param>
 2431         <param id="info_ptr">
 2432           <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>
 2433           <description>
 2434             On return, filled with information describing the specified
 2435             thread group.
 2436           </description>
 2437         </param>
 2438       </parameters>
 2439       <errors>
 2440       </errors>
 2441     </function>
 2442 
 2443     <function id="GetThreadGroupChildren" num="15">
 2444       <synopsis>Get Thread Group Children</synopsis>
 2445       <description>
 2446         Get the live platform threads and the child thread groups in this
 2447         thread group.  Virtual threads are not considered live threads in
 2448         a thread group and not returned by this function.
 2449       </description>
 2450       <origin>jvmdi</origin>
 2451       <capabilities>
 2452       </capabilities>
 2453       <parameters>
 2454         <param id="group">
 2455           <jthreadGroup/>
 2456           <description>
 2457             The group to query.
 2458           </description>
 2459         </param>
 2460         <param id="thread_count_ptr">
 2461           <outptr><jint/></outptr>
 2462           <description>
 2463             On return, points to the number of live threads in this thread group.
 2464           </description>
 2465         </param>
 2466         <param id="threads_ptr">
 2467           <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>
 2468             <description>
 2469               On return, points to an array of the live threads in this thread group.
 2470             </description>
 2471         </param>
 2472         <param id="group_count_ptr">
 2473           <outptr><jint/></outptr>
 2474           <description>
 2475             On return, points to the number of child thread groups
 2476           </description>
 2477         </param>
 2478         <param id="groups_ptr">
 2479           <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>
 2480             <description>
 2481               On return, points to an array of the child thread groups.
 2482             </description>
 2483         </param>
 2484       </parameters>
 2485       <errors>
 2486       </errors>
 2487     </function>
 2488   </category>
 2489 
 2490   <category id="stack" label="Stack Frame">
 2491     <intro>
 2492         These functions provide information about the stack of a thread.
 2493         Stack frames are referenced by depth.
 2494         The frame at depth zero is the current frame.
 2495         <p/>
 2496         Stack frames are as described in
 2497         <vmspec chapter="3.6"/>,
 2498         That is, they correspond to method
 2499         invocations (including native methods) but do not correspond to platform native or
 2500         VM internal frames.
 2501         <p/>
 2502         A <jvmti/> implementation may use method invocations to launch a thread and
 2503         the corresponding frames may be included in the stack as presented by these functions --
 2504         that is, there may be frames shown
 2505         deeper than <code>main()</code> and <code>run()</code>.
 2506         However this presentation must be consistent across all <jvmti/> functionality which
 2507         uses stack frames or stack depth.
 2508     </intro>
 2509 
 2510       <typedef id="jvmtiFrameInfo" label="Stack frame information structure">
 2511         <description>
 2512           Information about a stack frame is returned in this structure.
 2513         </description>
 2514         <field id="method">
 2515           <jmethodID/>
 2516             <description>
 2517               The method executing in this frame.
 2518             </description>
 2519         </field>
 2520         <field id="location">
 2521           <jlocation/>
 2522           <description>
 2523             The index of the instruction executing in this frame.
 2524             <code>-1</code> if the frame is executing a native method.
 2525           </description>
 2526         </field>
 2527       </typedef>
 2528 
 2529       <typedef id="jvmtiStackInfo" label="Stack information structure">
 2530         <description>
 2531           Information about a set of stack frames is returned in this structure.
 2532         </description>
 2533         <field id="thread">
 2534           <jthread/>
 2535           <description>
 2536             On return, the thread traced.
 2537           </description>
 2538         </field>
 2539         <field id="state">
 2540           <jint/>
 2541           <description>
 2542             On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.
 2543           </description>
 2544         </field>
 2545         <field id="frame_buffer">
 2546           <outbuf incount="max_frame_count">
 2547             <struct>jvmtiFrameInfo</struct>
 2548           </outbuf>
 2549             <description>
 2550               On return, this agent allocated buffer is filled
 2551               with stack frame information.
 2552             </description>
 2553         </field>
 2554         <field id="frame_count">
 2555           <jint/>
 2556           <description>
 2557             On return, the number of records filled into
 2558             <code>frame_buffer</code>.
 2559             This will be
 2560             min(<code>max_frame_count</code>, <i>stackDepth</i>).
 2561           </description>
 2562         </field>
 2563       </typedef>
 2564 
 2565     <function id="GetStackTrace" num="104">
 2566       <synopsis>Get Stack Trace</synopsis>
 2567       <description>
 2568         Get information about the stack of a thread.
 2569         If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,
 2570         the <paramlink id="max_frame_count"></paramlink> topmost frames are returned,
 2571         otherwise the entire stack is returned.
 2572         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
 2573         <p/>
 2574         The following example causes up to five of the topmost frames
 2575         to be returned and (if there are any frames) the currently
 2576         executing method name to be printed.
 2577         <example>
 2578 jvmtiFrameInfo frames[5];
 2579 jint count;
 2580 jvmtiError err;
 2581 
 2582 err = (*jvmti)-&gt;GetStackTrace(jvmti, aThread, 0, 5,
 2583                                frames, &amp;count);
 2584 if (err == JVMTI_ERROR_NONE &amp;&amp; count &gt;= 1) {
 2585    char *methodName;
 2586    err = (*jvmti)-&gt;GetMethodName(jvmti, frames[0].method,
 2587                        &amp;methodName, NULL, NULL);
 2588    if (err == JVMTI_ERROR_NONE) {
 2589       printf("Executing method: %s", methodName);
 2590    }
 2591 }
 2592         </example>
 2593         <todo>
 2594           check example code.
 2595         </todo>
 2596         <p/>
 2597         The <paramlink id="thread"></paramlink> need not be suspended
 2598         to call this function.
 2599         <p/>
 2600         The <functionlink id="GetLineNumberTable"></functionlink>
 2601         function can be used to map locations to line numbers. Note that
 2602         this mapping can be done lazily.
 2603       </description>
 2604       <origin>jvmpi</origin>
 2605       <capabilities>
 2606       </capabilities>
 2607       <parameters>
 2608         <param id="thread">
 2609           <jthread null="current" impl="noconvert"/>
 2610             <description>
 2611               Fetch the stack trace of this thread.
 2612             </description>
 2613         </param>
 2614         <param id="start_depth">
 2615           <jint/>
 2616           <description>
 2617             Begin retrieving frames at this depth.
 2618             If non-negative, count from the current frame,
 2619             the first frame retrieved is at depth <code>start_depth</code>.
 2620             For example, if zero, start from the current frame; if one, start from the
 2621             caller of the current frame; if two, start from the caller of the
 2622             caller of the current frame; and so on.
 2623             If negative, count from below the oldest frame,
 2624             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,
 2625             where <i>stackDepth</i> is the count of frames on the stack.
 2626             For example, if negative one, only the oldest frame is retrieved;
 2627             if negative two, start from the frame called by the oldest frame.
 2628           </description>
 2629         </param>
 2630         <param id="max_frame_count">
 2631           <jint min="0"/>
 2632           <description>
 2633             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
 2634           </description>
 2635         </param>
 2636         <param id="frame_buffer">
 2637           <outbuf incount="max_frame_count" outcount="count_ptr">
 2638             <struct>jvmtiFrameInfo</struct>
 2639           </outbuf>
 2640             <description>
 2641               On return, this agent allocated buffer is filled
 2642               with stack frame information.
 2643             </description>
 2644         </param>
 2645         <param id="count_ptr">
 2646           <outptr><jint/></outptr>
 2647           <description>
 2648             On return, points to the number of records filled in.
 2649             For non-negative <code>start_depth</code>, this will be
 2650             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).
 2651             For negative <code>start_depth</code>, this will be
 2652             min(<code>max_frame_count</code>, <code>-start_depth</code>).
 2653           </description>
 2654         </param>
 2655       </parameters>
 2656       <errors>
 2657         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 2658           <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.
 2659           Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.
 2660         </error>
 2661       </errors>
 2662     </function>
 2663 
 2664 
 2665     <function id="GetAllStackTraces" num="100">
 2666       <synopsis>Get All Stack Traces</synopsis>
 2667       <description>
 2668         Get the stack traces of all live platform threads attached to the VM.
 2669         The list includes the stack traces of
 2670         <internallink id="RunAgentThread">agent threads</internallink>.
 2671         It does not include the stack traces of virtual threads.
 2672         <p/>
 2673         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
 2674         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
 2675         otherwise the entire stack is returned.
 2676         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
 2677         <p/>
 2678         All stacks are collected simultaneously, that is, no changes will occur to the
 2679         thread state or stacks between the sampling of one thread and the next.
 2680         The threads need not be suspended.
 2681 
 2682         <example>
 2683 jvmtiStackInfo *stack_info;
 2684 jint thread_count;
 2685 int ti;
 2686 jvmtiError err;
 2687 
 2688 err = (*jvmti)-&gt;GetAllStackTraces(jvmti, MAX_FRAMES, &amp;stack_info, &amp;thread_count);
 2689 if (err != JVMTI_ERROR_NONE) {
 2690    ...
 2691 }
 2692 for (ti = 0; ti &lt; thread_count; ++ti) {
 2693    jvmtiStackInfo *infop = &amp;stack_info[ti];
 2694    jthread thread = infop-&gt;thread;
 2695    jint state = infop-&gt;state;
 2696    jvmtiFrameInfo *frames = infop-&gt;frame_buffer;
 2697    int fi;
 2698 
 2699    myThreadAndStatePrinter(thread, state);
 2700    for (fi = 0; fi &lt; infop-&gt;frame_count; fi++) {
 2701       myFramePrinter(frames[fi].method, frames[fi].location);
 2702    }
 2703 }
 2704 /* this one Deallocate call frees all data allocated by GetAllStackTraces */
 2705 err = (*jvmti)-&gt;Deallocate(jvmti, stack_info);
 2706         </example>
 2707         <todo>
 2708           check example code.
 2709         </todo>
 2710 
 2711       </description>
 2712       <origin>new</origin>
 2713       <capabilities>
 2714       </capabilities>
 2715       <parameters>
 2716         <param id="max_frame_count">
 2717           <jint min="0"/>
 2718           <description>
 2719             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
 2720           </description>
 2721         </param>
 2722         <param id="stack_info_ptr">
 2723           <allocbuf>
 2724             <struct>jvmtiStackInfo</struct>
 2725           </allocbuf>
 2726             <description>
 2727               On return, this buffer is filled
 2728               with stack information for each thread.
 2729               The number of <datalink id="jvmtiStackInfo"/> records is determined
 2730               by <paramlink id="thread_count_ptr"/>.
 2731               <p/>
 2732               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
 2733               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
 2734               These buffers must not be separately deallocated.
 2735             </description>
 2736         </param>
 2737         <param id="thread_count_ptr">
 2738           <outptr><jint/></outptr>
 2739           <description>
 2740             The number of threads traced.
 2741           </description>
 2742         </param>
 2743       </parameters>
 2744       <errors>
 2745       </errors>
 2746     </function>
 2747 
 2748     <function id="GetThreadListStackTraces" num="101">
 2749       <synopsis>Get Thread List Stack Traces</synopsis>
 2750       <description>
 2751         Get information about the stacks of the supplied threads.
 2752         If <paramlink id="max_frame_count"/> is less than the depth of a stack,
 2753         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread,
 2754         otherwise the entire stack is returned.
 2755         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.
 2756         <p/>
 2757         All stacks are collected simultaneously, that is, no changes will occur to the
 2758         thread state or stacks between the sampling one thread and the next.
 2759         The threads need not be suspended.
 2760         <p/>
 2761         If a thread has not yet started or terminates before the stack information is collected,
 2762         a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)
 2763         will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.
 2764         <p/>
 2765         See the example for the similar function
 2766         <functionlink id="GetAllStackTraces"/>.
 2767       </description>
 2768       <origin>new</origin>
 2769       <capabilities>
 2770       </capabilities>
 2771       <parameters>
 2772         <param id="thread_count">
 2773           <jint min="0"/>
 2774           <description>
 2775             The number of threads to trace.
 2776           </description>
 2777         </param>
 2778         <param id="thread_list">
 2779           <inbuf incount="thread_count"><jthread/></inbuf>
 2780             <description>
 2781               The list of threads to trace.
 2782             </description>
 2783         </param>
 2784         <param id="max_frame_count">
 2785           <jint min="0"/>
 2786           <description>
 2787             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.
 2788           </description>
 2789         </param>
 2790         <param id="stack_info_ptr">
 2791           <allocbuf outcount="thread_count">
 2792             <struct>jvmtiStackInfo</struct>
 2793           </allocbuf>
 2794             <description>
 2795               On return, this buffer is filled
 2796               with stack information for each thread.
 2797               The number of <datalink id="jvmtiStackInfo"/> records is determined
 2798               by <paramlink id="thread_count"/>.
 2799               <p/>
 2800               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/>
 2801               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.
 2802               These buffers must not be separately deallocated.
 2803             </description>
 2804         </param>
 2805       </parameters>
 2806       <errors>
 2807         <error id="JVMTI_ERROR_INVALID_THREAD">
 2808           An element in <paramlink id="thread_list"/> is not a thread object.
 2809         </error>
 2810       </errors>
 2811     </function>
 2812 
 2813     <elide>
 2814     <function id="AsyncGetStackTrace" num="1000">
 2815       <synopsis>Get Stack Trace--Asynchronous</synopsis>
 2816       <description>
 2817         Get information about the entire stack of a thread (or a sub-section of it).
 2818         This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>
 2819         and is reentrant and safe to call
 2820         from asynchronous signal handlers.
 2821         The stack trace is returned only for the calling thread.
 2822         <p/>
 2823         The <functionlink id="GetLineNumberTable"></functionlink>
 2824         function can be used to map locations to line numbers. Note that
 2825         this mapping can be done lazily.
 2826       </description>
 2827       <origin>jvmpi</origin>
 2828       <capabilities>
 2829         <required id="can_get_async_stack_trace"></required>
 2830         <capability id="can_show_JVM_spec_async_frames">
 2831           If <code>false</code>,
 2832           <paramlink id="use_java_stack"></paramlink>
 2833           must be <code>false</code>.
 2834         </capability>
 2835       </capabilities>
 2836       <parameters>
 2837         <param id="use_java_stack">
 2838           <jboolean/>
 2839           <description>
 2840             Return the stack showing <vmspec/>
 2841             model of the stack;
 2842             otherwise, show the internal representation of the stack with
 2843             inlined and optimized methods missing.  If the virtual machine
 2844             is using the <i>Java Virtual Machine Specification</i> stack model
 2845             internally, this flag is ignored.
 2846           </description>
 2847         </param>
 2848         <param id="max_count">
 2849           <jint min="0"/>
 2850           <description>
 2851             The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.
 2852             Retrieve this many unless the stack depth is less than <code>max_count</code>.
 2853           </description>
 2854         </param>
 2855         <param id="frame_buffer">
 2856           <outbuf incount="max_count" outcount="count_ptr">
 2857             <struct>jvmtiFrameInfo</struct>
 2858             <nullok>this information is not returned</nullok>
 2859           </outbuf>
 2860             <description>
 2861               The agent passes in a buffer
 2862               large enough to hold <code>max_count</code> records of
 2863               <datalink id="jvmtiFrameInfo"></datalink>.  This buffer must be
 2864               pre-allocated by the agent.
 2865             </description>
 2866         </param>
 2867         <param id="count_ptr">
 2868           <outptr><jint/></outptr>
 2869           <description>
 2870             On return, points to the number of records filled in..
 2871           </description>
 2872         </param>
 2873       </parameters>
 2874       <errors>
 2875         <error id="JVMTI_ERROR_UNATTACHED_THREAD">
 2876           The thread being used to call this function is not attached
 2877           to the virtual machine.  Calls must be made from attached threads.
 2878         </error>
 2879       </errors>
 2880     </function>
 2881     </elide>
 2882 
 2883     <function id="GetFrameCount" num="16">
 2884       <synopsis>Get Frame Count</synopsis>
 2885       <description>
 2886         Get the number of frames currently in the specified thread's call stack.
 2887         <p/>
 2888         If this function is called for a thread actively executing bytecodes (for example,
 2889         not the current thread and not suspended), the information returned is transient.
 2890       </description>
 2891       <origin>jvmdi</origin>
 2892       <capabilities>
 2893       </capabilities>
 2894       <parameters>
 2895         <param id="thread">
 2896           <jthread null="current" impl="noconvert"/>
 2897             <description>
 2898               The thread to query.
 2899             </description>
 2900         </param>
 2901         <param id="count_ptr">
 2902           <outptr><jint/></outptr>
 2903           <description>
 2904             On return, points to the number of frames in the call stack.
 2905           </description>
 2906         </param>
 2907       </parameters>
 2908       <errors>
 2909       </errors>
 2910     </function>
 2911 
 2912     <function id="PopFrame" num="80">
 2913       <synopsis>Pop Frame</synopsis>
 2914       <description>
 2915         Pop the current frame of <code>thread</code>'s stack.
 2916         Popping a frame takes you to the previous frame.
 2917         When the thread is resumed, the execution
 2918         state of the thread is reset to the state
 2919         immediately before the called method was invoked.
 2920         That is (using <vmspec/> terminology):
 2921           <ul>
 2922             <li>the current frame is discarded as the previous frame becomes the current one</li>
 2923             <li>the operand stack is restored--the argument values are added back
 2924               and if the invoke was not <code>invokestatic</code>,
 2925               <code>objectref</code> is added back as well</li>
 2926             <li>the Java virtual machine PC is restored to the opcode
 2927               of the invoke instruction</li>
 2928           </ul>
 2929         Note however, that any changes to the arguments, which
 2930         occurred in the called method, remain;
 2931         when execution continues, the first instruction to
 2932         execute will be the invoke.
 2933         <p/>
 2934         Between calling <code>PopFrame</code> and resuming the
 2935         thread the state of the stack is undefined.
 2936         To pop frames beyond the first,
 2937         these three steps must be repeated:
 2938         <ul>
 2939           <li>suspend the thread via an event (step, breakpoint, ...)</li>
 2940           <li>call <code>PopFrame</code></li>
 2941           <li>resume the thread</li>
 2942         </ul>
 2943         <p/>
 2944         A lock acquired by calling the called method
 2945         (if it is a <code>synchronized</code>  method)
 2946         and locks acquired by entering <code>synchronized</code>
 2947         blocks within the called method are released.
 2948         Note: this does not apply to native locks or
 2949         <code>java.util.concurrent.locks</code> locks.
 2950         <p/>
 2951         Finally blocks are not executed.
 2952         <p/>
 2953         Changes to global state are not addressed and thus remain changed.
 2954         <p/>
 2955         The specified thread must be suspended or must be the current thread.
 2956         <p/>
 2957         Both the called method and calling method must be non-native Java programming
 2958         language methods.
 2959         <p/>
 2960         No <jvmti/> events are generated by this function.
 2961       </description>
 2962       <origin>jvmdi</origin>
 2963       <capabilities>
 2964         <required id="can_pop_frame"></required>
 2965       </capabilities>
 2966       <parameters>
 2967         <param id="thread">
 2968           <jthread/>
 2969             <description>
 2970               The thread whose current frame is to be popped.
 2971               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
 2972               <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
 2973             </description>
 2974         </param>
 2975       </parameters>
 2976       <errors>
 2977         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 2978           Called or calling method is a native method.
 2979           The implementation is unable to pop this frame.
 2980         </error>
 2981         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 2982           Thread was not suspended and was not the current thread.
 2983         </error>
 2984         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 2985           There are less than two stack frames on the call stack.
 2986         </error>
 2987         <error id="JVMTI_ERROR_INVALID_THREAD">
 2988           <paramlink id="thread"/> is a virtual thread.
 2989         </error>
 2990       </errors>
 2991     </function>
 2992 
 2993     <function id="GetFrameLocation" num="19">
 2994       <synopsis>Get Frame Location</synopsis>
 2995       <description>
 2996         <p/>
 2997         For a Java programming language frame, return the location of the instruction
 2998         currently executing.
 2999       </description>
 3000       <origin>jvmdiClone</origin>
 3001       <capabilities>
 3002       </capabilities>
 3003       <parameters>
 3004         <param id="thread">
 3005           <jthread null="current" frame="frame" impl="noconvert"/>
 3006           <description>
 3007             The thread of the frame to query.
 3008           </description>
 3009         </param>
 3010         <param id="depth">
 3011           <jframeID thread="thread"/>
 3012           <description>
 3013             The depth of the frame to query.
 3014           </description>
 3015         </param>
 3016         <param id="method_ptr">
 3017           <outptr><jmethodID/></outptr>
 3018             <description>
 3019               On return, points to the method for the current location.
 3020             </description>
 3021         </param>
 3022         <param id="location_ptr">
 3023           <outptr><jlocation/></outptr>
 3024           <description>
 3025             On return, points to the index of the currently
 3026             executing instruction.
 3027             Is set to <code>-1</code> if the frame is executing
 3028             a native method.
 3029           </description>
 3030         </param>
 3031       </parameters>
 3032       <errors>
 3033       </errors>
 3034     </function>
 3035 
 3036     <function id="NotifyFramePop" num="20">
 3037       <synopsis>Notify Frame Pop</synopsis>
 3038       <description>
 3039         When the frame that is currently at <paramlink id="depth"></paramlink>
 3040         is popped from the stack, generate a
 3041         <eventlink id="FramePop"></eventlink> event.  See the
 3042         <eventlink id="FramePop"></eventlink> event for details.
 3043         Only frames corresponding to non-native Java programming language
 3044         methods can receive notification.
 3045         <p/>
 3046         The specified thread must be suspended or must be the current thread.
 3047       </description>
 3048       <origin>jvmdi</origin>
 3049       <capabilities>
 3050         <required id="can_generate_frame_pop_events"></required>
 3051       </capabilities>
 3052       <parameters>
 3053         <param id="thread">
 3054           <jthread null="current" frame="depth" impl="noconvert"/>
 3055           <description>
 3056             The thread of the frame for which the frame pop event will be generated.
 3057           </description>
 3058         </param>
 3059         <param id="depth">
 3060           <jframeID thread="thread"/>
 3061           <description>
 3062             The depth of the frame for which the frame pop event will be generated.
 3063           </description>
 3064         </param>
 3065       </parameters>
 3066       <errors>
 3067         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3068           The frame at <code>depth</code> is executing a
 3069           native method.
 3070         </error>
 3071         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3072           Thread was not suspended and was not the current thread.
 3073         </error>
 3074       </errors>
 3075     </function>
 3076 
 3077   </category>
 3078 
 3079   <category id="ForceEarlyReturn" label="Force Early Return">
 3080     <intro>
 3081       These functions allow an agent to force a method
 3082       to return at any point during its execution.
 3083       The method which will return early is referred to as the <i>called method</i>.
 3084       The called method is the current method
 3085       (as defined by
 3086       <vmspec chapter="3.6"/>)
 3087       for the specified thread at
 3088       the time the function is called.
 3089       <p/>
 3090       The <code>thread</code> may not be a virtual thread. Otherwise, the error code
 3091       <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
 3092       The specified thread must be suspended or must be the current thread.
 3093       The return occurs when execution of Java programming
 3094       language code is resumed on this thread.
 3095       Between calling one of these functions and resumption
 3096       of thread execution, the state of the stack is undefined.
 3097       <p/>
 3098       No further instructions are executed in the called method.
 3099       Specifically, finally blocks are not executed.
 3100       Note: this can cause inconsistent states in the application.
 3101       <p/>
 3102       A lock acquired by calling the called method
 3103       (if it is a <code>synchronized</code>  method)
 3104       and locks acquired by entering <code>synchronized</code>
 3105       blocks within the called method are released.
 3106       Note: this does not apply to native locks or
 3107       <code>java.util.concurrent.locks</code> locks.
 3108       <p/>
 3109       Events, such as <eventlink id="MethodExit"></eventlink>,
 3110       are generated as they would be in a normal return.
 3111       <p/>
 3112       The called method must be a non-native Java programming
 3113       language method.
 3114       Forcing return on a thread with only one frame on the
 3115       stack causes the thread to exit when resumed.
 3116     </intro>
 3117 
 3118     <function id="ForceEarlyReturnObject" num="81" since="1.1">
 3119       <synopsis>Force Early Return - Object</synopsis>
 3120       <description>
 3121         This function can be used to return from a method whose
 3122         result type is <code>Object</code>
 3123         or a subclass of <code>Object</code>.
 3124       </description>
 3125       <origin>new</origin>
 3126       <capabilities>
 3127         <required id="can_force_early_return"></required>
 3128       </capabilities>
 3129       <parameters>
 3130         <param id="thread">
 3131           <jthread null="current"/>
 3132           <description>
 3133             The thread whose current frame is to return early.
 3134           </description>
 3135         </param>
 3136         <param id="value">
 3137           <jobject/>
 3138           <description>
 3139             The return value for the called frame.
 3140             An object or <code>NULL</code>.
 3141           </description>
 3142         </param>
 3143       </parameters>
 3144       <errors>
 3145         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3146           Attempted to return early from a frame
 3147           corresponding to a native method.
 3148           Or the implementation is unable to provide
 3149           this functionality on this frame.
 3150         </error>
 3151         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3152           The result type of the called method is not
 3153           <code>Object</code> or a subclass of <code>Object</code>.
 3154         </error>
 3155         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3156           The supplied <paramlink id="value"/> is not compatible with the
 3157           result type of the called method.
 3158         </error>
 3159         <error id="JVMTI_ERROR_INVALID_THREAD">
 3160           <paramlink id="thread"/> is a virtual thread.
 3161         </error>
 3162         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3163           Thread was not suspended and was not the current thread.
 3164         </error>
 3165         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3166           There are no more frames on the call stack.
 3167         </error>
 3168       </errors>
 3169     </function>
 3170 
 3171     <function id="ForceEarlyReturnInt" num="82" since="1.1">
 3172       <synopsis>Force Early Return - Int</synopsis>
 3173       <description>
 3174         This function can be used to return from a method whose
 3175         result type is <code>int</code>, <code>short</code>,
 3176         <code>char</code>, <code>byte</code>, or
 3177         <code>boolean</code>.
 3178       </description>
 3179       <origin>new</origin>
 3180       <capabilities>
 3181         <required id="can_force_early_return"></required>
 3182       </capabilities>
 3183       <parameters>
 3184         <param id="thread">
 3185           <jthread null="current"/>
 3186           <description>
 3187             The thread whose current frame is to return early.
 3188           </description>
 3189         </param>
 3190         <param id="value">
 3191           <jint/>
 3192           <description>
 3193             The return value for the called frame.
 3194           </description>
 3195         </param>
 3196       </parameters>
 3197       <errors>
 3198         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3199           Attempted to return early from a frame
 3200           corresponding to a native method.
 3201           Or the implementation is unable to provide
 3202           this functionality on this frame.
 3203         </error>
 3204         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3205           The result type of the called method is not
 3206           <code>int</code>, <code>short</code>,
 3207           <code>char</code>, <code>byte</code>, or
 3208           <code>boolean</code>.
 3209         </error>
 3210         <error id="JVMTI_ERROR_INVALID_THREAD">
 3211           <paramlink id="thread"/> is a virtual thread.
 3212         </error>
 3213         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3214           Thread was not suspended and was not the current thread.
 3215         </error>
 3216         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3217           There are no frames on the call stack.
 3218         </error>
 3219       </errors>
 3220     </function>
 3221 
 3222     <function id="ForceEarlyReturnLong" num="83" since="1.1">
 3223       <synopsis>Force Early Return - Long</synopsis>
 3224       <description>
 3225         This function can be used to return from a method whose
 3226         result type is <code>long</code>.
 3227       </description>
 3228       <origin>new</origin>
 3229       <capabilities>
 3230         <required id="can_force_early_return"></required>
 3231       </capabilities>
 3232       <parameters>
 3233         <param id="thread">
 3234           <jthread null="current"/>
 3235           <description>
 3236             The thread whose current frame is to return early.
 3237           </description>
 3238         </param>
 3239         <param id="value">
 3240           <jlong/>
 3241           <description>
 3242             The return value for the called frame.
 3243           </description>
 3244         </param>
 3245       </parameters>
 3246       <errors>
 3247         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3248           Attempted to return early from a frame
 3249           corresponding to a native method.
 3250           Or the implementation is unable to provide
 3251           this functionality on this frame.
 3252         </error>
 3253         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3254           The result type of the called method is not <code>long</code>.
 3255         </error>
 3256         <error id="JVMTI_ERROR_INVALID_THREAD">
 3257           <paramlink id="thread"/> is a virtual thread.
 3258         </error>
 3259         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3260           Thread was not suspended and was not the current thread.
 3261         </error>
 3262         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3263           There are no frames on the call stack.
 3264         </error>
 3265       </errors>
 3266     </function>
 3267 
 3268     <function id="ForceEarlyReturnFloat" num="84" since="1.1">
 3269       <synopsis>Force Early Return - Float</synopsis>
 3270       <description>
 3271         This function can be used to return from a method whose
 3272         result type is <code>float</code>.
 3273       </description>
 3274       <origin>new</origin>
 3275       <capabilities>
 3276         <required id="can_force_early_return"></required>
 3277       </capabilities>
 3278       <parameters>
 3279         <param id="thread">
 3280           <jthread null="current"/>
 3281           <description>
 3282             The thread whose current frame is to return early.
 3283           </description>
 3284         </param>
 3285         <param id="value">
 3286           <jfloat/>
 3287           <description>
 3288             The return value for the called frame.
 3289           </description>
 3290         </param>
 3291       </parameters>
 3292       <errors>
 3293         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3294           Attempted to return early from a frame
 3295           corresponding to a native method.
 3296           Or the implementation is unable to provide
 3297           this functionality on this frame.
 3298         </error>
 3299         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3300           The result type of the called method is not <code>float</code>.
 3301         </error>
 3302         <error id="JVMTI_ERROR_INVALID_THREAD">
 3303           <paramlink id="thread"/> is a virtual thread.
 3304         </error>
 3305         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3306           Thread was not suspended and was not the current thread.
 3307         </error>
 3308         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3309           There are no frames on the call stack.
 3310         </error>
 3311       </errors>
 3312     </function>
 3313 
 3314     <function id="ForceEarlyReturnDouble" num="85" since="1.1">
 3315       <synopsis>Force Early Return - Double</synopsis>
 3316       <description>
 3317         This function can be used to return from a method whose
 3318         result type is <code>double</code>.
 3319       </description>
 3320       <origin>new</origin>
 3321       <capabilities>
 3322         <required id="can_force_early_return"></required>
 3323       </capabilities>
 3324       <parameters>
 3325         <param id="thread">
 3326           <jthread null="current"/>
 3327           <description>
 3328             The thread whose current frame is to return early.
 3329           </description>
 3330         </param>
 3331         <param id="value">
 3332           <jdouble/>
 3333           <description>
 3334             The return value for the called frame.
 3335           </description>
 3336         </param>
 3337       </parameters>
 3338       <errors>
 3339         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3340           Attempted to return early from a frame corresponding to a native method.
 3341           Or the implementation is unable to provide this functionality on this frame.
 3342         </error>
 3343         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3344           The result type of the called method is not <code>double</code>.
 3345         </error>
 3346         <error id="JVMTI_ERROR_INVALID_THREAD">
 3347           <paramlink id="thread"/> is a virtual thread.
 3348         </error>
 3349         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3350           Thread was not suspended and was not the current thread.
 3351         </error>
 3352         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3353           There are no frames on the call stack.
 3354         </error>
 3355       </errors>
 3356     </function>
 3357 
 3358     <function id="ForceEarlyReturnVoid" num="86" since="1.1">
 3359       <synopsis>Force Early Return - Void</synopsis>
 3360       <description>
 3361         This function can be used to return from a method with no result type.
 3362         That is, the called method must be declared <code>void</code>.
 3363       </description>
 3364       <origin>new</origin>
 3365       <capabilities>
 3366         <required id="can_force_early_return"></required>
 3367       </capabilities>
 3368       <parameters>
 3369         <param id="thread">
 3370           <jthread null="current"/>
 3371           <description>
 3372             The thread whose current frame is to return early.
 3373           </description>
 3374         </param>
 3375       </parameters>
 3376       <errors>
 3377         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 3378           Attempted to return early from a frame
 3379           corresponding to a native method.
 3380           Or the implementation is unable to provide
 3381           this functionality on this frame.
 3382         </error>
 3383         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 3384           The called method has a result type.
 3385         </error>
 3386         <error id="JVMTI_ERROR_INVALID_THREAD">
 3387           <paramlink id="thread"/> is a virtual thread.
 3388         </error>
 3389         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">
 3390           Thread was not suspended and was not the current thread.
 3391         </error>
 3392         <error id="JVMTI_ERROR_NO_MORE_FRAMES">
 3393           There are no frames on the call stack.
 3394         </error>
 3395       </errors>
 3396     </function>
 3397 
 3398   </category>
 3399 
 3400   <category id="Heap" label="Heap">
 3401     <intro>
 3402       These functions are used to analyze the heap.
 3403       Functionality includes the ability to view the objects in the
 3404       heap and to tag these objects.
 3405     </intro>
 3406 
 3407     <intro id="objectTags" label="Object Tags">
 3408       A <i>tag</i> is a value associated with an object.
 3409       Tags are explicitly set by the agent using the
 3410       <functionlink id="SetTag"></functionlink> function or by
 3411       callback functions such as <functionlink id="jvmtiHeapIterationCallback"/>.
 3412       <p/>
 3413       Tags are local to the environment; that is, the tags of one
 3414       environment are not visible in another.
 3415       <p/>
 3416       Tags are <code>jlong</code> values which can be used
 3417       simply to mark an object or to store a pointer to more detailed
 3418       information.  Objects which have not been tagged have a
 3419       tag of zero.
 3420       Setting a tag to zero makes the object untagged.
 3421     </intro>
 3422 
 3423     <intro id="heapCallbacks" label="Heap Callback Functions">
 3424         Heap functions which iterate through the heap and recursively
 3425         follow object references use agent supplied callback functions
 3426         to deliver the information.
 3427         <p/>
 3428         These heap callback functions must adhere to the following restrictions --
 3429         These callbacks must not use JNI functions.
 3430         These callbacks must not use <jvmti/> functions except
 3431         <i>callback safe</i> functions which
 3432         specifically allow such use (see the raw monitor, memory management,
 3433         and environment local storage functions).
 3434         <p/>
 3435         An implementation may invoke a callback on an internal thread or
 3436         the thread which called the iteration function.
 3437         Heap callbacks are single threaded -- no more than one callback will
 3438         be invoked at a time.
 3439         <p/>
 3440         The Heap Filter Flags can be used to prevent reporting
 3441         based on the tag status of an object or its class.
 3442         If no flags are set (the <code>jint</code> is zero), objects
 3443         will not be filtered out.
 3444 
 3445         <constants id="jvmtiHeapFilter" label="Heap Filter Flags" kind="bits">
 3446           <constant id="JVMTI_HEAP_FILTER_TAGGED" num="0x4">
 3447             Filter out tagged objects. Objects which are tagged are not included.
 3448           </constant>
 3449           <constant id="JVMTI_HEAP_FILTER_UNTAGGED" num="0x8">
 3450             Filter out untagged objects. Objects which are not tagged are not included.
 3451           </constant>
 3452           <constant id="JVMTI_HEAP_FILTER_CLASS_TAGGED" num="0x10">
 3453             Filter out objects with tagged classes. Objects whose class is tagged are not included.
 3454           </constant>
 3455           <constant id="JVMTI_HEAP_FILTER_CLASS_UNTAGGED" num="0x20">
 3456             Filter out objects with untagged classes. Objects whose class is not tagged are not included.
 3457           </constant>
 3458         </constants>
 3459 
 3460         <p/>
 3461         The Heap Visit Control Flags are returned by the heap callbacks
 3462         and can be used to abort the iteration.  For the
 3463         <functionlink id="jvmtiHeapReferenceCallback">Heap
 3464         Reference Callback</functionlink>, it can also be used
 3465         to prune the graph of traversed references
 3466         (<code>JVMTI_VISIT_OBJECTS</code> is not set).
 3467 
 3468         <constants id="jvmtiHeapVisitControl"
 3469                    label="Heap Visit Control Flags"
 3470                    kind="bits"
 3471                    since="1.1">
 3472           <constant id="JVMTI_VISIT_OBJECTS" num="0x100">
 3473             If we are visiting an object and if this callback
 3474             was initiated by <functionlink id="FollowReferences"/>,
 3475             traverse the references of this object.
 3476             Otherwise ignored.
 3477           </constant>
 3478           <constant id="JVMTI_VISIT_ABORT" num="0x8000">
 3479             Abort the iteration.  Ignore all other bits.
 3480           </constant>
 3481         </constants>
 3482 
 3483         <p/>
 3484         The Heap Reference Enumeration is provided by the
 3485         <functionlink id="jvmtiHeapReferenceCallback">Heap
 3486         Reference Callback</functionlink> and
 3487         <functionlink id="jvmtiPrimitiveFieldCallback">Primitive Field
 3488         Callback</functionlink> to
 3489         describe the kind of reference
 3490         being reported.
 3491 
 3492         <constants id="jvmtiHeapReferenceKind"
 3493                    label="Heap Reference Enumeration"
 3494                    kind="enum"
 3495                    since="1.1">
 3496           <constant id="JVMTI_HEAP_REFERENCE_CLASS" num="1">
 3497             Reference from an object to its class.
 3498           </constant>
 3499           <constant id="JVMTI_HEAP_REFERENCE_FIELD" num="2">
 3500             Reference from an object to the value of one of its instance fields.
 3501           </constant>
 3502           <constant id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT" num="3">
 3503             Reference from an array to one of its elements.
 3504           </constant>
 3505           <constant id="JVMTI_HEAP_REFERENCE_CLASS_LOADER" num="4">
 3506             Reference from a class to its class loader.
 3507           </constant>
 3508           <constant id="JVMTI_HEAP_REFERENCE_SIGNERS" num="5">
 3509             Reference from a class to its signers array.
 3510           </constant>
 3511           <constant id="JVMTI_HEAP_REFERENCE_PROTECTION_DOMAIN" num="6">
 3512             Reference from a class to its protection domain.
 3513           </constant>
 3514           <constant id="JVMTI_HEAP_REFERENCE_INTERFACE" num="7">
 3515             Reference from a class to one of its interfaces.
 3516             Note: interfaces are defined via a constant pool reference,
 3517             so the referenced interfaces may also be reported with a
 3518             <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
 3519           </constant>
 3520           <constant id="JVMTI_HEAP_REFERENCE_STATIC_FIELD" num="8">
 3521             Reference from a class to the value of one of its static fields.
 3522           </constant>
 3523           <constant id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL" num="9">
 3524             Reference from a class to a resolved entry in the constant pool.
 3525           </constant>
 3526           <constant id="JVMTI_HEAP_REFERENCE_SUPERCLASS" num="10">
 3527             Reference from a class to its superclass.
 3528             A callback is not sent if the superclass is <code>java.lang.Object</code>.
 3529             Note: loaded classes define superclasses via a constant pool
 3530             reference, so the referenced superclass may also be reported with
 3531             a <code>JVMTI_HEAP_REFERENCE_CONSTANT_POOL</code> reference kind.
 3532           </constant>
 3533           <constant id="JVMTI_HEAP_REFERENCE_JNI_GLOBAL" num="21">
 3534             Heap root reference: JNI global reference.
 3535           </constant>
 3536           <constant id="JVMTI_HEAP_REFERENCE_SYSTEM_CLASS" num="22">
 3537             Heap root reference: System class.
 3538           </constant>
 3539           <constant id="JVMTI_HEAP_REFERENCE_MONITOR" num="23">
 3540             Heap root reference: monitor.
 3541           </constant>
 3542           <constant id="JVMTI_HEAP_REFERENCE_STACK_LOCAL" num="24">
 3543             Heap root reference: local variable on the stack.
 3544           </constant>
 3545           <constant id="JVMTI_HEAP_REFERENCE_JNI_LOCAL" num="25">
 3546             Heap root reference: JNI local reference.
 3547           </constant>
 3548           <constant id="JVMTI_HEAP_REFERENCE_THREAD" num="26">
 3549             Heap root reference: Thread.
 3550           </constant>
 3551           <constant id="JVMTI_HEAP_REFERENCE_OTHER" num="27">
 3552             Heap root reference: other heap root reference.
 3553           </constant>
 3554         </constants>
 3555 
 3556         <p/>
 3557         Definitions for the single character type descriptors of
 3558         primitive types.
 3559 
 3560         <constants id="jvmtiPrimitiveType"
 3561                    label="Primitive Type Enumeration"
 3562                    kind="enum"
 3563                    since="1.1">
 3564           <constant id="JVMTI_PRIMITIVE_TYPE_BOOLEAN" num="90">
 3565             'Z' - Java programming language <code>boolean</code> - JNI <code>jboolean</code>
 3566           </constant>
 3567           <constant id="JVMTI_PRIMITIVE_TYPE_BYTE" num="66">
 3568             'B' - Java programming language <code>byte</code> - JNI <code>jbyte</code>
 3569           </constant>
 3570           <constant id="JVMTI_PRIMITIVE_TYPE_CHAR" num="67">
 3571             'C' - Java programming language <code>char</code> - JNI <code>jchar</code>
 3572           </constant>
 3573           <constant id="JVMTI_PRIMITIVE_TYPE_SHORT" num="83">
 3574             'S' - Java programming language <code>short</code> - JNI <code>jshort</code>
 3575           </constant>
 3576           <constant id="JVMTI_PRIMITIVE_TYPE_INT" num="73">
 3577             'I' - Java programming language <code>int</code> - JNI <code>jint</code>
 3578           </constant>
 3579           <constant id="JVMTI_PRIMITIVE_TYPE_LONG" num="74">
 3580             'J' - Java programming language <code>long</code> - JNI <code>jlong</code>
 3581           </constant>
 3582           <constant id="JVMTI_PRIMITIVE_TYPE_FLOAT" num="70">
 3583             'F' - Java programming language <code>float</code> - JNI <code>jfloat</code>
 3584           </constant>
 3585           <constant id="JVMTI_PRIMITIVE_TYPE_DOUBLE" num="68">
 3586             'D' - Java programming language <code>double</code> - JNI <code>jdouble</code>
 3587           </constant>
 3588         </constants>
 3589     </intro>
 3590 
 3591       <typedef id="jvmtiHeapReferenceInfoField"
 3592                label="Reference information structure for Field references"
 3593                since="1.1">
 3594         <description>
 3595           Reference information returned for
 3596           <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> and
 3597           <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
 3598         </description>
 3599         <field id="index">
 3600           <jint/>
 3601           <description>
 3602             For <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>, the
 3603             referrer object is not a class or an interface.
 3604             In this case, <code>index</code> is the index of the field
 3605             in the class of the referrer object.
 3606             This class is referred to below as <i>C</i>.
 3607             <p/>
 3608             For <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
 3609             the referrer object is a class (referred to below as <i>C</i>)
 3610             or an interface (referred to below as <i>I</i>).
 3611             In this case, <code>index</code> is the index of the field in
 3612             that class or interface.
 3613             <p/>
 3614             If the referrer object is not an interface, then the field
 3615             indices are determined as follows:
 3616             <ul>
 3617               <li>make a list of all the fields in <i>C</i> and its
 3618                   superclasses, starting with all the fields in
 3619                   <code>java.lang.Object</code> and ending with all the
 3620                   fields in <i>C</i>.</li>
 3621               <li>Within this list, put
 3622                   the fields for a given class in the order returned by
 3623                   <functionlink id="GetClassFields"/>.</li>
 3624               <li>Assign the fields in this list indices
 3625                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
 3626                   is the count of the fields in all the interfaces
 3627                   implemented by <i>C</i>.
 3628                   Note that <i>C</i> implements all interfaces
 3629                   directly implemented by its superclasses; as well
 3630                   as all superinterfaces of these interfaces.</li>
 3631             </ul>
 3632             If the referrer object is an interface, then the field
 3633             indices are determined as follows:
 3634             <ul>
 3635               <li>make a list of the fields directly declared in
 3636                   <i>I</i>.</li>
 3637               <li>Within this list, put
 3638                   the fields in the order returned by
 3639                   <functionlink id="GetClassFields"/>.</li>
 3640               <li>Assign the fields in this list indices
 3641                   <i>n</i>, <i>n</i>+1, ..., in order, where <i>n</i>
 3642                   is the count of the fields in all the superinterfaces
 3643                   of <i>I</i>.</li>
 3644             </ul>
 3645             All fields are included in this computation, regardless of
 3646             field modifier (static, public, private, etc).
 3647             <p/>
 3648             For example, given the following classes and interfaces:
 3649             <example>
 3650 interface I0 {
 3651     int p = 0;
 3652 }
 3653 
 3654 interface I1 extends I0 {
 3655     int x = 1;
 3656 }
 3657 
 3658 interface I2 extends I0 {
 3659     int y = 2;
 3660 }
 3661 
 3662 class C1 implements I1 {
 3663     public static int a = 3;
 3664     private int b = 4;
 3665 }
 3666 
 3667 class C2 extends C1 implements I2 {
 3668     static int q = 5;
 3669     final int r = 6;
 3670 }
 3671             </example>
 3672             Assume that <functionlink id="GetClassFields"/> called on
 3673             <code>C1</code> returns the fields of <code>C1</code> in the
 3674             order: a, b; and that the fields of <code>C2</code> are
 3675             returned in the order: q, r.
 3676             An instance of class <code>C1</code> will have the
 3677             following field indices:
 3678             <blockquote><table>
 3679               <tr class="bgLight">
 3680                 <th class="centered" scope="col">Field</th>
 3681                 <th class="centered" scope="col">Index</th>
 3682                 <th scope="col">Description</th>
 3683               </tr>
 3684               <tr>
 3685                 <th class="centered" scope="row">
 3686                   a
 3687                 </th>
 3688                 <td class="centered">
 3689                   2
 3690                 </td>
 3691                 <td>
 3692                   The count of the fields in the interfaces
 3693                   implemented by <code>C1</code> is two (<i>n</i>=2):
 3694                   <code>p</code> of <code>I0</code>
 3695                   and <code>x</code> of <code>I1</code>.
 3696                 </td>
 3697               </tr>
 3698               <tr>
 3699                 <th class="centered" scope="row">
 3700                   b
 3701                 </th>
 3702                 <td class="centered">
 3703                   3
 3704                 </td>
 3705                 <td>
 3706                   the subsequent index.
 3707                 </td>
 3708               </tr>
 3709             </table></blockquote>
 3710             The class <code>C1</code> will have the same field indices.
 3711             <p/>
 3712             An instance of class <code>C2</code> will have the
 3713             following field indices:
 3714             <blockquote><table>
 3715               <tr class="bgLight">
 3716                 <th class="centered" scope="col">Field</th>
 3717                 <th class="centered" scope="col">Index</th>
 3718                 <th scope="col">Description</th>
 3719               </tr>
 3720               <tr>
 3721                 <th class="centered" scope="row">
 3722                   a
 3723                 </th>
 3724                 <td class="centered">
 3725                   3
 3726                 </td>
 3727                 <td>
 3728                   The count of the fields in the interfaces
 3729                   implemented by <code>C2</code> is three (<i>n</i>=3):
 3730                   <code>p</code> of <code>I0</code>,
 3731                   <code>x</code> of <code>I1</code> and <code>y</code> of <code>I2</code>
 3732                   (an interface of <code>C2</code>).  Note that the field <code>p</code>
 3733                   of <code>I0</code> is only included once.
 3734                 </td>
 3735               </tr>
 3736               <tr>
 3737                 <th class="centered" scope="row">
 3738                   b
 3739                 </th>
 3740                 <td class="centered">
 3741                   4
 3742                 </td>
 3743                 <td>
 3744                   the subsequent index to "a".
 3745                 </td>
 3746               </tr>
 3747               <tr>
 3748                 <th class="centered" scope="row">
 3749                   q
 3750                 </th>
 3751                 <td class="centered">
 3752                   5
 3753                 </td>
 3754                 <td>
 3755                   the subsequent index to "b".
 3756                 </td>
 3757               </tr>
 3758               <tr>
 3759                 <th class="centered" scope="row">
 3760                   r
 3761                 </th>
 3762                 <td class="centered">
 3763                   6
 3764                 </td>
 3765                 <td>
 3766                   the subsequent index to "q".
 3767                 </td>
 3768               </tr>
 3769             </table></blockquote>
 3770             The class <code>C2</code> will have the same field indices.
 3771             Note that a field may have a different index depending on the
 3772             object that is viewing it -- for example field "a" above.
 3773             Note also: not all field indices may be visible from the
 3774             callbacks, but all indices are shown for illustrative purposes.
 3775             <p/>
 3776             The interface <code>I1</code> will have the
 3777             following field indices:
 3778             <blockquote><table>
 3779               <tr class="bgLight">
 3780                 <th class="centered" scope="col">Field</th>
 3781                 <th class="centered" scope="col">Index</th>
 3782                 <th scope="col">Description</th>
 3783               </tr>
 3784               <tr>
 3785                 <th class="centered" scope="row">
 3786                   x
 3787                 </th>
 3788                 <td class="centered">
 3789                   1
 3790                 </td>
 3791                 <td>
 3792                   The count of the fields in the superinterfaces
 3793                   of <code>I1</code> is one (<i>n</i>=1):
 3794                   <code>p</code> of <code>I0</code>.
 3795                 </td>
 3796               </tr>
 3797             </table></blockquote>
 3798           </description>
 3799         </field>
 3800       </typedef>
 3801 
 3802       <typedef id="jvmtiHeapReferenceInfoArray"
 3803                label="Reference information structure for Array references"
 3804                since="1.1">
 3805         <description>
 3806           Reference information returned for
 3807          <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
 3808         </description>
 3809         <field id="index">
 3810           <jint/>
 3811           <description>
 3812             The array index.
 3813           </description>
 3814         </field>
 3815       </typedef>
 3816 
 3817       <typedef id="jvmtiHeapReferenceInfoConstantPool"
 3818                label="Reference information structure for Constant Pool references"
 3819                since="1.1">
 3820         <description>
 3821           Reference information returned for
 3822           <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
 3823         </description>
 3824         <field id="index">
 3825           <jint/>
 3826           <description>
 3827             The index into the constant pool of the class. See the description in
 3828       <vmspec chapter="4.4"/>.
 3829           </description>
 3830         </field>
 3831       </typedef>
 3832 
 3833       <typedef id="jvmtiHeapReferenceInfoStackLocal"
 3834                label="Reference information structure for Local Variable references"
 3835                since="1.1">
 3836         <description>
 3837           Reference information returned for
 3838           <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
 3839         </description>
 3840         <field id="thread_tag">
 3841           <jlong/>
 3842           <description>
 3843             The tag of the thread corresponding to this stack, zero if not tagged.
 3844           </description>
 3845         </field>
 3846         <field id="thread_id">
 3847           <jlong/>
 3848           <description>
 3849             The unique thread ID of the thread corresponding to this stack.
 3850           </description>
 3851         </field>
 3852         <field id="depth">
 3853           <jint/>
 3854           <description>
 3855             The depth of the frame.
 3856           </description>
 3857         </field>
 3858         <field id="method">
 3859           <jmethodID/>
 3860           <description>
 3861             The method executing in this frame.
 3862           </description>
 3863         </field>
 3864         <field id="location">
 3865           <jlocation/>
 3866           <description>
 3867             The currently executing location in this frame.
 3868           </description>
 3869         </field>
 3870         <field id="slot">
 3871           <jint/>
 3872           <description>
 3873             The slot number of the local variable.
 3874           </description>
 3875         </field>
 3876       </typedef>
 3877 
 3878       <typedef id="jvmtiHeapReferenceInfoJniLocal"
 3879                label="Reference information structure for JNI local references"
 3880                since="1.1">
 3881         <description>
 3882           Reference information returned for
 3883           <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
 3884         </description>
 3885         <field id="thread_tag">
 3886           <jlong/>
 3887           <description>
 3888             The tag of the thread corresponding to this stack, zero if not tagged.
 3889           </description>
 3890         </field>
 3891         <field id="thread_id">
 3892           <jlong/>
 3893           <description>
 3894             The unique thread ID of the thread corresponding to this stack.
 3895           </description>
 3896         </field>
 3897         <field id="depth">
 3898           <jint/>
 3899           <description>
 3900             The depth of the frame.
 3901           </description>
 3902         </field>
 3903         <field id="method">
 3904           <jmethodID/>
 3905           <description>
 3906             The method executing in this frame.
 3907           </description>
 3908         </field>
 3909       </typedef>
 3910 
 3911       <typedef id="jvmtiHeapReferenceInfoReserved"
 3912                label="Reference information structure for Other references"
 3913                since="1.1">
 3914         <description>
 3915           Reference information returned for other references.
 3916         </description>
 3917         <field id="reserved1">
 3918           <jlong/>
 3919           <description>
 3920             reserved for future use.
 3921           </description>
 3922         </field>
 3923         <field id="reserved2">
 3924           <jlong/>
 3925           <description>
 3926             reserved for future use.
 3927           </description>
 3928         </field>
 3929         <field id="reserved3">
 3930           <jlong/>
 3931           <description>
 3932             reserved for future use.
 3933           </description>
 3934         </field>
 3935         <field id="reserved4">
 3936           <jlong/>
 3937           <description>
 3938             reserved for future use.
 3939           </description>
 3940         </field>
 3941         <field id="reserved5">
 3942           <jlong/>
 3943           <description>
 3944             reserved for future use.
 3945           </description>
 3946         </field>
 3947         <field id="reserved6">
 3948           <jlong/>
 3949           <description>
 3950             reserved for future use.
 3951           </description>
 3952         </field>
 3953         <field id="reserved7">
 3954           <jlong/>
 3955           <description>
 3956             reserved for future use.
 3957           </description>
 3958         </field>
 3959         <field id="reserved8">
 3960           <jlong/>
 3961           <description>
 3962             reserved for future use.
 3963           </description>
 3964         </field>
 3965       </typedef>
 3966 
 3967       <uniontypedef id="jvmtiHeapReferenceInfo"
 3968                label="Reference information structure"
 3969                since="1.1">
 3970         <description>
 3971           The information returned about referrers.
 3972           Represented as a union of the various kinds of reference information.
 3973         </description>
 3974         <field id="field">
 3975           <struct>jvmtiHeapReferenceInfoField</struct>
 3976           <description>
 3977             The referrer information for
 3978             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>
 3979             and <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/> references.
 3980           </description>
 3981         </field>
 3982         <field id="array">
 3983           <struct>jvmtiHeapReferenceInfoArray</struct>
 3984           <description>
 3985             The referrer information for
 3986             For <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/> references.
 3987           </description>
 3988         </field>
 3989         <field id="constant_pool">
 3990           <struct>jvmtiHeapReferenceInfoConstantPool</struct>
 3991           <description>
 3992             The referrer information for
 3993             For <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/> references.
 3994           </description>
 3995         </field>
 3996         <field id="stack_local">
 3997           <struct>jvmtiHeapReferenceInfoStackLocal</struct>
 3998           <description>
 3999             The referrer information for
 4000             For <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/> references.
 4001           </description>
 4002         </field>
 4003         <field id="jni_local">
 4004           <struct>jvmtiHeapReferenceInfoJniLocal</struct>
 4005           <description>
 4006             The referrer information for
 4007             For <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/> references.
 4008           </description>
 4009         </field>
 4010         <field id="other">
 4011           <struct>jvmtiHeapReferenceInfoReserved</struct>
 4012           <description>
 4013             reserved for future use.
 4014           </description>
 4015         </field>
 4016       </uniontypedef>
 4017 
 4018       <typedef id="jvmtiHeapCallbacks"
 4019                label="Heap callback function structure"
 4020                since="1.1">
 4021         <field id="heap_iteration_callback">
 4022           <ptrtype>
 4023             <struct>jvmtiHeapIterationCallback</struct>
 4024           </ptrtype>
 4025           <description>
 4026             The callback to be called to describe an
 4027             object in the heap. Used by the
 4028             <functionlink id="IterateThroughHeap"/> function, ignored by the
 4029             <functionlink id="FollowReferences"/> function.
 4030           </description>
 4031         </field>
 4032         <field id="heap_reference_callback">
 4033           <ptrtype>
 4034             <struct>jvmtiHeapReferenceCallback</struct>
 4035           </ptrtype>
 4036           <description>
 4037             The callback to be called to describe an
 4038             object reference.  Used by the
 4039             <functionlink id="FollowReferences"/> function, ignored by the
 4040             <functionlink id="IterateThroughHeap"/> function.
 4041           </description>
 4042         </field>
 4043         <field id="primitive_field_callback">
 4044           <ptrtype>
 4045             <struct>jvmtiPrimitiveFieldCallback</struct>
 4046           </ptrtype>
 4047           <description>
 4048             The callback to be called to describe a
 4049             primitive field.
 4050           </description>
 4051         </field>
 4052         <field id="array_primitive_value_callback">
 4053           <ptrtype>
 4054             <struct>jvmtiArrayPrimitiveValueCallback</struct>
 4055           </ptrtype>
 4056           <description>
 4057             The callback to be called to describe an
 4058             array of primitive values.
 4059           </description>
 4060         </field>
 4061         <field id="string_primitive_value_callback">
 4062           <ptrtype>
 4063             <struct>jvmtiStringPrimitiveValueCallback</struct>
 4064           </ptrtype>
 4065           <description>
 4066             The callback to be called to describe a String value.
 4067           </description>
 4068         </field>
 4069         <field id="reserved5">
 4070           <ptrtype>
 4071             <struct>jvmtiReservedCallback</struct>
 4072           </ptrtype>
 4073           <description>
 4074             Reserved for future use..
 4075           </description>
 4076         </field>
 4077         <field id="reserved6">
 4078           <ptrtype>
 4079             <struct>jvmtiReservedCallback</struct>
 4080           </ptrtype>
 4081           <description>
 4082             Reserved for future use..
 4083           </description>
 4084         </field>
 4085         <field id="reserved7">
 4086           <ptrtype>
 4087             <struct>jvmtiReservedCallback</struct>
 4088           </ptrtype>
 4089           <description>
 4090             Reserved for future use..
 4091           </description>
 4092         </field>
 4093         <field id="reserved8">
 4094           <ptrtype>
 4095             <struct>jvmtiReservedCallback</struct>
 4096           </ptrtype>
 4097           <description>
 4098             Reserved for future use..
 4099           </description>
 4100         </field>
 4101         <field id="reserved9">
 4102           <ptrtype>
 4103             <struct>jvmtiReservedCallback</struct>
 4104           </ptrtype>
 4105           <description>
 4106             Reserved for future use..
 4107           </description>
 4108         </field>
 4109         <field id="reserved10">
 4110           <ptrtype>
 4111             <struct>jvmtiReservedCallback</struct>
 4112           </ptrtype>
 4113           <description>
 4114             Reserved for future use..
 4115           </description>
 4116         </field>
 4117         <field id="reserved11">
 4118           <ptrtype>
 4119             <struct>jvmtiReservedCallback</struct>
 4120           </ptrtype>
 4121           <description>
 4122             Reserved for future use..
 4123           </description>
 4124         </field>
 4125         <field id="reserved12">
 4126           <ptrtype>
 4127             <struct>jvmtiReservedCallback</struct>
 4128           </ptrtype>
 4129           <description>
 4130             Reserved for future use..
 4131           </description>
 4132         </field>
 4133         <field id="reserved13">
 4134           <ptrtype>
 4135             <struct>jvmtiReservedCallback</struct>
 4136           </ptrtype>
 4137           <description>
 4138             Reserved for future use..
 4139           </description>
 4140         </field>
 4141         <field id="reserved14">
 4142           <ptrtype>
 4143             <struct>jvmtiReservedCallback</struct>
 4144           </ptrtype>
 4145           <description>
 4146             Reserved for future use..
 4147           </description>
 4148         </field>
 4149         <field id="reserved15">
 4150           <ptrtype>
 4151             <struct>jvmtiReservedCallback</struct>
 4152           </ptrtype>
 4153           <description>
 4154             Reserved for future use..
 4155           </description>
 4156         </field>
 4157       </typedef>
 4158 
 4159 
 4160     <intro>
 4161       <rationale>
 4162         The heap dumping functionality (below) uses a callback
 4163         for each object.  While it would seem that a buffered approach
 4164         would provide better throughput, tests do
 4165         not show this to be the case--possibly due to locality of
 4166         memory reference or array access overhead.
 4167       </rationale>
 4168 
 4169       <issue>
 4170         Still under investigation as to if java.lang.ref references
 4171         are reported as a different type of reference.
 4172       </issue>
 4173 
 4174       <issue>
 4175         Should or can an indication of the cost or relative cost of
 4176         these operations be included?
 4177       </issue>
 4178 
 4179     </intro>
 4180 
 4181     <callback id="jvmtiHeapIterationCallback" since="1.1">
 4182       <jint/>
 4183       <synopsis>Heap Iteration Callback</synopsis>
 4184       <description>
 4185         Agent supplied callback function.
 4186         Describes (but does not pass in) an object in the heap.
 4187         <p/>
 4188         This function should return a bit vector of the desired
 4189         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
 4190         This will determine if the entire iteration should be aborted
 4191         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
 4192         <p/>
 4193         See the <internallink id="heapCallbacks">heap callback
 4194         function restrictions</internallink>.
 4195       </description>
 4196       <parameters>
 4197         <param id="class_tag">
 4198           <jlong/>
 4199           <description>
 4200             The tag of the class of object (zero if the class is not tagged).
 4201             If the object represents a runtime class,
 4202             the <code>class_tag</code> is the tag
 4203             associated with <code>java.lang.Class</code>
 4204             (zero if <code>java.lang.Class</code> is not tagged).
 4205           </description>
 4206         </param>
 4207         <param id="size">
 4208           <jlong/>
 4209           <description>
 4210             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
 4211           </description>
 4212         </param>
 4213         <param id="tag_ptr">
 4214           <outptr><jlong/></outptr>
 4215           <description>
 4216             The object tag value, or zero if the object is not tagged.
 4217             To set the tag value to be associated with the object
 4218             the agent sets the <code>jlong</code> pointed to by the parameter.
 4219           </description>
 4220         </param>
 4221         <param id="length">
 4222           <jint/>
 4223           <description>
 4224             If this object is an array, the length of the array. Otherwise negative one (-1).
 4225           </description>
 4226         </param>
 4227         <param id="user_data">
 4228           <outptr><void/></outptr>
 4229           <description>
 4230             The user supplied data that was passed into the iteration function.
 4231           </description>
 4232         </param>
 4233       </parameters>
 4234     </callback>
 4235 
 4236     <callback id="jvmtiHeapReferenceCallback" since="1.1">
 4237       <jint/>
 4238       <synopsis>Heap Reference Callback</synopsis>
 4239       <description>
 4240         Agent supplied callback function.
 4241         Describes a reference from an object or the VM (the referrer) to another object
 4242         (the referree) or a heap root to a referree.
 4243         <p/>
 4244         This function should return a bit vector of the desired
 4245         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
 4246         This will determine if the objects referenced by the referree
 4247         should be visited or if the entire iteration should be aborted.
 4248         <p/>
 4249         See the <internallink id="heapCallbacks">heap callback
 4250         function restrictions</internallink>.
 4251       </description>
 4252       <parameters>
 4253         <param id="reference_kind">
 4254           <enum>jvmtiHeapReferenceKind</enum>
 4255           <description>
 4256             The kind of reference.
 4257           </description>
 4258         </param>
 4259         <param id="reference_info">
 4260           <inptr>
 4261             <struct>jvmtiHeapReferenceInfo</struct>
 4262           </inptr>
 4263           <description>
 4264             Details about the reference.
 4265             Set when the <datalink id="jvmtiHeapReferenceCallback.reference_kind">reference_kind</datalink> is
 4266             <datalink id="JVMTI_HEAP_REFERENCE_FIELD"/>,
 4267             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>,
 4268             <datalink id="JVMTI_HEAP_REFERENCE_ARRAY_ELEMENT"/>,
 4269             <datalink id="JVMTI_HEAP_REFERENCE_CONSTANT_POOL"/>,
 4270             <datalink id="JVMTI_HEAP_REFERENCE_STACK_LOCAL"/>,
 4271             or <datalink id="JVMTI_HEAP_REFERENCE_JNI_LOCAL"/>.
 4272             Otherwise <code>NULL</code>.
 4273           </description>
 4274         </param>
 4275         <param id="class_tag">
 4276           <jlong/>
 4277           <description>
 4278             The tag of the class of referree object (zero if the class is not tagged).
 4279             If the referree object represents a runtime class,
 4280             the <code>class_tag</code> is the tag
 4281             associated with <code>java.lang.Class</code>
 4282             (zero if <code>java.lang.Class</code> is not tagged).
 4283           </description>
 4284         </param>
 4285         <param id="referrer_class_tag">
 4286           <jlong/>
 4287           <description>
 4288             The tag of the class of the referrer object (zero if the class is not tagged
 4289             or the referree is a heap root). If the referrer object represents a runtime
 4290             class, the <code>referrer_class_tag</code> is the tag associated with
 4291             the <code>java.lang.Class</code>
 4292             (zero if <code>java.lang.Class</code> is not tagged).
 4293           </description>
 4294         </param>
 4295         <param id="size">
 4296           <jlong/>
 4297           <description>
 4298             Size of the referree object (in bytes).
 4299             See <functionlink id="GetObjectSize"/>.
 4300           </description>
 4301         </param>
 4302         <param id="tag_ptr">
 4303           <outptr><jlong/></outptr>
 4304           <description>
 4305             Points to the referree object tag value, or zero if the object is not
 4306             tagged.
 4307             To set the tag value to be associated with the object
 4308             the agent sets the <code>jlong</code> pointed to by the parameter.
 4309           </description>
 4310         </param>
 4311         <param id="referrer_tag_ptr">
 4312           <outptr><jlong/></outptr>
 4313           <description>
 4314             Points to the tag of the referrer object, or
 4315             points to the zero if the referrer
 4316             object is not tagged.
 4317             <code>NULL</code> if the referrer in not an object (that is,
 4318             this callback is reporting a heap root).
 4319             To set the tag value to be associated with the referrer object
 4320             the agent sets the <code>jlong</code> pointed to by the parameter.
 4321             If this callback is reporting a reference from an object to itself,
 4322             <code>referrer_tag_ptr == tag_ptr</code>.
 4323           </description>
 4324         </param>
 4325         <param id="length">
 4326           <jint/>
 4327           <description>
 4328             If this object is an array, the length of the array. Otherwise negative one (-1).
 4329           </description>
 4330         </param>
 4331         <param id="user_data">
 4332           <outptr><void/></outptr>
 4333           <description>
 4334             The user supplied data that was passed into the iteration function.
 4335           </description>
 4336         </param>
 4337       </parameters>
 4338     </callback>
 4339 
 4340     <callback id="jvmtiPrimitiveFieldCallback" since="1.1">
 4341       <jint/>
 4342       <synopsis>Primitive Field Callback</synopsis>
 4343       <description>
 4344         Agent supplied callback function which
 4345         describes a primitive field of an object (<i>the object</i>).
 4346         A primitive field is a field whose type is a primitive type.
 4347         This callback will describe a static field if the object is a class,
 4348         and otherwise will describe an instance field.
 4349         <p/>
 4350         This function should return a bit vector of the desired
 4351         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
 4352         This will determine if the entire iteration should be aborted
 4353         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
 4354         <p/>
 4355         See the <internallink id="heapCallbacks">heap callback
 4356         function restrictions</internallink>.
 4357       </description>
 4358       <parameters>
 4359         <param id="kind">
 4360           <enum>jvmtiHeapReferenceKind</enum>
 4361           <description>
 4362             The kind of field -- instance or static (<datalink id="JVMTI_HEAP_REFERENCE_FIELD"/> or
 4363             <datalink id="JVMTI_HEAP_REFERENCE_STATIC_FIELD"/>).
 4364           </description>
 4365         </param>
 4366         <param id="info">
 4367           <inptr>
 4368             <struct>jvmtiHeapReferenceInfo</struct>
 4369           </inptr>
 4370           <description>
 4371             Which field (the field index).
 4372           </description>
 4373         </param>
 4374         <param id="object_class_tag">
 4375           <jlong/>
 4376           <description>
 4377             The tag of the class of the object (zero if the class is not tagged).
 4378             If the object represents a runtime class, the
 4379             <code>object_class_tag</code> is the tag
 4380             associated with <code>java.lang.Class</code>
 4381             (zero if <code>java.lang.Class</code> is not tagged).
 4382           </description>
 4383         </param>
 4384         <param id="object_tag_ptr">
 4385           <outptr><jlong/></outptr>
 4386           <description>
 4387             Points to the tag of the object, or zero if the object is not
 4388             tagged.
 4389             To set the tag value to be associated with the object
 4390             the agent sets the <code>jlong</code> pointed to by the parameter.
 4391           </description>
 4392         </param>
 4393         <param id="value">
 4394           <jvalue/>
 4395           <description>
 4396             The value of the field.
 4397           </description>
 4398         </param>
 4399         <param id="value_type">
 4400           <enum>jvmtiPrimitiveType</enum>
 4401           <description>
 4402             The type of the field.
 4403           </description>
 4404         </param>
 4405         <param id="user_data">
 4406           <outptr><void/></outptr>
 4407           <description>
 4408             The user supplied data that was passed into the iteration function.
 4409           </description>
 4410         </param>
 4411       </parameters>
 4412     </callback>
 4413 
 4414     <callback id="jvmtiArrayPrimitiveValueCallback" since="1.1">
 4415       <jint/>
 4416       <synopsis>Array Primitive Value Callback</synopsis>
 4417       <description>
 4418         Agent supplied callback function.
 4419         Describes the values in an array of a primitive type.
 4420         <p/>
 4421         This function should return a bit vector of the desired
 4422         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
 4423         This will determine if the entire iteration should be aborted
 4424         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
 4425         <p/>
 4426         See the <internallink id="heapCallbacks">heap callback
 4427         function restrictions</internallink>.
 4428       </description>
 4429       <parameters>
 4430         <param id="class_tag">
 4431           <jlong/>
 4432           <description>
 4433             The tag of the class of the array object (zero if the class is not tagged).
 4434           </description>
 4435         </param>
 4436         <param id="size">
 4437           <jlong/>
 4438           <description>
 4439             Size of the array (in bytes).
 4440             See <functionlink id="GetObjectSize"/>.
 4441           </description>
 4442         </param>
 4443         <param id="tag_ptr">
 4444           <outptr><jlong/></outptr>
 4445           <description>
 4446             Points to the tag of the array object, or zero if the object is not
 4447             tagged.
 4448             To set the tag value to be associated with the object
 4449             the agent sets the <code>jlong</code> pointed to by the parameter.
 4450           </description>
 4451         </param>
 4452         <param id="element_count">
 4453           <jint/>
 4454           <description>
 4455             The length of the primitive array.
 4456           </description>
 4457         </param>
 4458         <param id="element_type">
 4459           <enum>jvmtiPrimitiveType</enum>
 4460           <description>
 4461             The type of the elements of the array.
 4462           </description>
 4463         </param>
 4464         <param id="elements">
 4465           <vmbuf><void/></vmbuf>
 4466           <description>
 4467             The elements of the array in a packed array of <code>element_count</code>
 4468             items of <code>element_type</code> size each.
 4469           </description>
 4470         </param>
 4471         <param id="user_data">
 4472           <outptr><void/></outptr>
 4473           <description>
 4474             The user supplied data that was passed into the iteration function.
 4475           </description>
 4476         </param>
 4477       </parameters>
 4478     </callback>
 4479 
 4480     <callback id="jvmtiStringPrimitiveValueCallback" since="1.1">
 4481       <jint/>
 4482       <synopsis>String Primitive Value Callback</synopsis>
 4483       <description>
 4484         Agent supplied callback function.
 4485         Describes the value of a java.lang.String.
 4486         <p/>
 4487         This function should return a bit vector of the desired
 4488         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>.
 4489         This will determine if the entire iteration should be aborted
 4490         (the <code>JVMTI_VISIT_OBJECTS</code> flag is ignored).
 4491         <p/>
 4492         See the <internallink id="heapCallbacks">heap callback
 4493         function restrictions</internallink>.
 4494       </description>
 4495       <parameters>
 4496         <param id="class_tag">
 4497           <jlong/>
 4498           <description>
 4499             The tag of the class of the String class (zero if the class is not tagged).
 4500             <issue>Is this needed?</issue>
 4501           </description>
 4502         </param>
 4503         <param id="size">
 4504           <jlong/>
 4505           <description>
 4506             Size of the string (in bytes).
 4507             See <functionlink id="GetObjectSize"/>.
 4508           </description>
 4509         </param>
 4510         <param id="tag_ptr">
 4511           <outptr><jlong/></outptr>
 4512           <description>
 4513             Points to the tag of the String object, or zero if the object is not
 4514             tagged.
 4515             To set the tag value to be associated with the object
 4516             the agent sets the <code>jlong</code> pointed to by the parameter.
 4517           </description>
 4518         </param>
 4519         <param id="value">
 4520           <vmbuf><jchar/></vmbuf>
 4521           <description>
 4522             The value of the String, encoded as a Unicode string.
 4523           </description>
 4524         </param>
 4525         <param id="value_length">
 4526           <jint/>
 4527           <description>
 4528             The length of the string.
 4529             The length is equal to the number of 16-bit Unicode
 4530             characters in the string.
 4531           </description>
 4532         </param>
 4533         <param id="user_data">
 4534           <outptr><void/></outptr>
 4535           <description>
 4536             The user supplied data that was passed into the iteration function.
 4537           </description>
 4538         </param>
 4539       </parameters>
 4540     </callback>
 4541 
 4542 
 4543     <callback id="jvmtiReservedCallback" since="1.1">
 4544       <jint/>
 4545       <synopsis>reserved for future use Callback</synopsis>
 4546       <description>
 4547         Placeholder -- reserved for future use.
 4548       </description>
 4549       <parameters>
 4550       </parameters>
 4551     </callback>
 4552 
 4553     <function id="FollowReferences" num="115" since="1.1">
 4554       <synopsis>Follow References</synopsis>
 4555       <description>
 4556         This function initiates a traversal over the objects that are
 4557         directly and indirectly reachable from the specified object or,
 4558         if <code>initial_object</code> is not specified, all objects
 4559         reachable from the heap roots.
 4560         The heap root are the set of system classes,
 4561         JNI globals, references from thread stacks, and other objects used as roots
 4562         for the purposes of garbage collection.
 4563         <p/>
 4564         This function operates by traversing the reference graph.
 4565         Let <i>A</i>, <i>B</i>, ... represent objects.
 4566         When a reference from <i>A</i> to <i>B</i> is traversed,
 4567         when a reference from a heap root to <i>B</i> is traversed,
 4568         or when <i>B</i> is specified as the <paramlink id="initial_object"/>,
 4569         then <i>B</i> is said to be <i>visited</i>.
 4570         A reference from <i>A</i> to <i>B</i> is not traversed until <i>A</i>
 4571         is visited.
 4572         References are reported in the same order that the references are traversed.
 4573         Object references are reported by invoking the agent supplied
 4574         callback function <functionlink id="jvmtiHeapReferenceCallback"/>.
 4575         In a reference from <i>A</i> to <i>B</i>, <i>A</i> is known
 4576         as the <i>referrer</i> and <i>B</i> as the <i>referree</i>.
 4577         The callback is invoked exactly once for each reference from a referrer;
 4578         this is true even if there are reference cycles or multiple paths to
 4579         the referrer.
 4580         There may be more than one reference between a referrer and a referree,
 4581         each reference is reported.
 4582         These references may be distinguished by examining the
 4583         <datalink
 4584          id="jvmtiHeapReferenceCallback.reference_kind"><code>reference_kind</code></datalink>
 4585          and
 4586         <datalink
 4587          id="jvmtiHeapReferenceCallback.reference_info"><code>reference_info</code></datalink>
 4588         parameters of the <functionlink id="jvmtiHeapReferenceCallback"/> callback.
 4589         <p/>
 4590         This function reports a Java programming language view of object references,
 4591         not a virtual machine implementation view. The following object references
 4592         are reported when they are non-null:
 4593         <ul>
 4594           <li>Instance objects report references to each non-primitive instance fields
 4595               (including inherited fields).</li>
 4596           <li>Instance objects report a reference to the object type (class).</li>
 4597           <li>Classes report a reference to the superclass and directly
 4598               implemented/extended interfaces.</li>
 4599           <li>Classes report a reference to the class loader, protection domain,
 4600               signers, and resolved entries in the constant pool.</li>
 4601           <li>Classes report a reference to each directly declared non-primitive
 4602               static field.</li>
 4603           <li>Arrays report a reference to the array type (class) and each
 4604               array element.</li>
 4605           <li>Primitive arrays report a reference to the array type.</li>
 4606         </ul>
 4607         <p/>
 4608         This function can also be used to examine primitive (non-object) values.
 4609         The primitive value of an array or String
 4610         is reported after the object has been visited;
 4611         it is reported by invoking the agent supplied callback function
 4612         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
 4613         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
 4614         A primitive field
 4615         is reported after the object with that field is visited;
 4616         it is reported by invoking the agent supplied callback function
 4617         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
 4618         <p/>
 4619         Whether a callback is provided or is <code>NULL</code> only determines
 4620         whether the callback will be invoked, it does not influence
 4621         which objects are visited nor does it influence whether other callbacks
 4622         will be invoked.
 4623         However, the
 4624         <datalink id="jvmtiHeapVisitControl">visit control flags</datalink>
 4625         returned by <functionlink id="jvmtiHeapReferenceCallback"/>
 4626         do determine if the objects referenced by the
 4627         current object as visited.
 4628         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
 4629         and <paramlink id="klass"/> provided as parameters to this function
 4630         do not control which objects are visited but they do control which
 4631         objects and primitive values are reported by the callbacks.
 4632         For example, if the only callback that was set is
 4633         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
 4634         is set to the array of bytes class, then only arrays of byte will be
 4635         reported.
 4636         The table below summarizes this:
 4637         <p/>
 4638         <table>
 4639           <tr class="bgLight">
 4640             <th/>
 4641             <th class="centered" scope="col">Controls objects visited</th>
 4642             <th class="centered" scope="col">Controls objects reported</th>
 4643             <th class="centered" scope="col">Controls primitives reported</th>
 4644           </tr>
 4645           <tr>
 4646             <th scope="row">
 4647               the
 4648               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
 4649               returned by <functionlink id="jvmtiHeapReferenceCallback"/>
 4650             </th>
 4651             <td class="centered">
 4652               <b>Yes</b>
 4653             </td>
 4654             <td class="centered">
 4655               <b>Yes</b>, since visits are controlled
 4656             </td>
 4657             <td class="centered">
 4658               <b>Yes</b>, since visits are controlled
 4659             </td>
 4660           </tr>
 4661           <tr>
 4662             <th scope="row">
 4663               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
 4664               in <paramlink id="callbacks"/> set
 4665             </th>
 4666             <td class="centered">
 4667               No
 4668             </td>
 4669             <td class="centered">
 4670               <b>Yes</b>
 4671             </td>
 4672             <td class="centered">
 4673               No
 4674             </td>
 4675           </tr>
 4676           <tr>
 4677             <th scope="row">
 4678               <paramlink id="heap_filter"/>
 4679             </th>
 4680             <td class="centered">
 4681               No
 4682             </td>
 4683             <td class="centered">
 4684               <b>Yes</b>
 4685             </td>
 4686             <td class="centered">
 4687               <b>Yes</b>
 4688             </td>
 4689           </tr>
 4690           <tr>
 4691             <th scope="row">
 4692               <paramlink id="klass"/>
 4693             </th>
 4694             <td class="centered">
 4695               No
 4696             </td>
 4697             <td class="centered">
 4698               <b>Yes</b>
 4699             </td>
 4700             <td class="centered">
 4701               <b>Yes</b>
 4702             </td>
 4703           </tr>
 4704         </table>
 4705         <p/>
 4706         During the execution of this function the state of the heap
 4707         does not change: no objects are allocated, no objects are
 4708         garbage collected, and the state of objects (including
 4709         held values) does not change.
 4710         As a result, threads executing Java
 4711         programming language code, threads attempting to resume the
 4712         execution of Java programming language code, and threads
 4713         attempting to execute JNI functions are typically stalled.
 4714       </description>
 4715       <origin>new</origin>
 4716       <capabilities>
 4717         <required id="can_tag_objects"></required>
 4718       </capabilities>
 4719       <parameters>
 4720         <param id="heap_filter">
 4721           <jint/>
 4722           <description>
 4723             This bit vector of
 4724             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
 4725             restricts the objects for which the callback function is called.
 4726             This applies to both the object and primitive callbacks.
 4727           </description>
 4728         </param>
 4729         <param id="klass">
 4730           <ptrtype>
 4731             <jclass/>
 4732             <nullok>callbacks are not limited to instances of a particular
 4733                     class</nullok>
 4734           </ptrtype>
 4735           <description>
 4736             Callbacks are only reported when the object is an instance of
 4737             this class.
 4738             Objects which are instances of a subclass of <code>klass</code>
 4739             are not reported.
 4740             If <code>klass</code> is an interface, no objects are reported.
 4741             This applies to both the object and primitive callbacks.
 4742           </description>
 4743         </param>
 4744         <param id="initial_object">
 4745           <ptrtype>
 4746             <jobject/>
 4747             <nullok>references are followed from the heap roots</nullok>
 4748           </ptrtype>
 4749           <description>
 4750             The object to follow
 4751           </description>
 4752         </param>
 4753         <param id="callbacks">
 4754           <inptr>
 4755             <struct>jvmtiHeapCallbacks</struct>
 4756           </inptr>
 4757           <description>
 4758             Structure defining the set of callback functions.
 4759           </description>
 4760         </param>
 4761         <param id="user_data">
 4762           <inbuf>
 4763             <void/>
 4764             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
 4765           </inbuf>
 4766           <description>
 4767             User supplied data to be passed to the callback.
 4768           </description>
 4769         </param>
 4770       </parameters>
 4771       <errors>
 4772         <error id="JVMTI_ERROR_INVALID_CLASS">
 4773           <paramlink id="klass"/> is not a valid class.
 4774         </error>
 4775         <error id="JVMTI_ERROR_INVALID_OBJECT">
 4776           <paramlink id="initial_object"/> is not a valid object.
 4777         </error>
 4778       </errors>
 4779     </function>
 4780 
 4781 
 4782     <function id="IterateThroughHeap" num="116" since="1.1">
 4783       <synopsis>Iterate Through Heap</synopsis>
 4784       <description>
 4785         Initiate an iteration over all objects in the heap.
 4786         This includes both reachable and
 4787         unreachable objects. Objects are visited in no particular order.
 4788         <p/>
 4789         Heap objects are reported by invoking the agent supplied
 4790         callback function <functionlink id="jvmtiHeapIterationCallback"/>.
 4791         References between objects are not reported.
 4792         If only reachable objects are desired, or if object reference information
 4793         is needed, use <functionlink id="FollowReferences"/>.
 4794         <p/>
 4795         This function can also be used to examine primitive (non-object) values.
 4796         The primitive value of an array or String
 4797         is reported after the object has been visited;
 4798         it is reported by invoking the agent supplied callback function
 4799         <functionlink id="jvmtiArrayPrimitiveValueCallback"/> or
 4800         <functionlink id="jvmtiStringPrimitiveValueCallback"/>.
 4801         A primitive field
 4802         is reported after the object with that field is visited;
 4803         it is reported by invoking the agent supplied
 4804         callback function
 4805         <functionlink id="jvmtiPrimitiveFieldCallback"/>.
 4806         <p/>
 4807         Unless the iteration is aborted by the
 4808         <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
 4809         returned by a callback, all objects in the heap are visited.
 4810         Whether a callback is provided or is <code>NULL</code> only determines
 4811         whether the callback will be invoked, it does not influence
 4812         which objects are visited nor does it influence whether other callbacks
 4813         will be invoked.
 4814         The <datalink id="jvmtiHeapFilter">heap filter flags</datalink>
 4815         and <paramlink id="klass"/> provided as parameters to this function
 4816         do not control which objects are visited but they do control which
 4817         objects and primitive values are reported by the callbacks.
 4818         For example, if the only callback that was set is
 4819         <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/> and <code>klass</code>
 4820         is set to the array of bytes class, then only arrays of byte will be
 4821         reported. The table below summarizes this (contrast this with
 4822         <functionlink id="FollowReferences"/>):
 4823         <p/>
 4824         <table>
 4825           <tr class="bgLight">
 4826             <th/>
 4827             <th class="centered" scope="col">Controls objects visited</th>
 4828             <th class="centered" scope="col">Controls objects reported</th>
 4829             <th class="centered" scope="col">Controls primitives reported</th>
 4830           </tr>
 4831           <tr>
 4832             <th scope="row">
 4833               the
 4834               <datalink id="jvmtiHeapVisitControl">Heap Visit Control Flags</datalink>
 4835               returned by <functionlink id="jvmtiHeapIterationCallback"/>
 4836             </th>
 4837             <td class="centered">
 4838               No<br/>(unless they abort the iteration)
 4839             </td>
 4840             <td class="centered">
 4841               No<br/>(unless they abort the iteration)
 4842             </td>
 4843             <td class="centered">
 4844               No<br/>(unless they abort the iteration)
 4845             </td>
 4846           </tr>
 4847           <tr>
 4848             <th scope="row">
 4849               <fieldlink id="array_primitive_value_callback" struct="jvmtiHeapCallbacks"/>
 4850               in <paramlink id="callbacks"/> set
 4851             </th>
 4852             <td class="centered">
 4853               No
 4854             </td>
 4855             <td class="centered">
 4856               <b>Yes</b>
 4857             </td>
 4858             <td class="centered">
 4859               No
 4860             </td>
 4861           </tr>
 4862           <tr>
 4863             <th scope="row">
 4864               <paramlink id="heap_filter"/>
 4865             </th>
 4866             <td class="centered">
 4867               No
 4868             </td>
 4869             <td class="centered">
 4870               <b>Yes</b>
 4871             </td>
 4872             <td class="centered">
 4873               <b>Yes</b>
 4874             </td>
 4875           </tr>
 4876           <tr>
 4877             <th scope="row">
 4878               <paramlink id="klass"/>
 4879             </th>
 4880             <td class="centered">
 4881               No
 4882             </td>
 4883             <td class="centered">
 4884               <b>Yes</b>
 4885             </td>
 4886             <td class="centered">
 4887               <b>Yes</b>
 4888             </td>
 4889           </tr>
 4890         </table>
 4891         <p/>
 4892         During the execution of this function the state of the heap
 4893         does not change: no objects are allocated, no objects are
 4894         garbage collected, and the state of objects (including
 4895         held values) does not change.
 4896         As a result, threads executing Java
 4897         programming language code, threads attempting to resume the
 4898         execution of Java programming language code, and threads
 4899         attempting to execute JNI functions are typically stalled.
 4900       </description>
 4901       <origin>new</origin>
 4902       <capabilities>
 4903         <required id="can_tag_objects"></required>
 4904       </capabilities>
 4905       <parameters>
 4906         <param id="heap_filter">
 4907           <jint/>
 4908           <description>
 4909             This bit vector of
 4910             <datalink id="jvmtiHeapFilter">heap filter flags</datalink>.
 4911             restricts the objects for which the callback function is called.
 4912             This applies to both the object and primitive callbacks.
 4913           </description>
 4914         </param>
 4915         <param id="klass">
 4916           <ptrtype>
 4917             <jclass/>
 4918             <nullok>callbacks are not limited to instances of a particular class</nullok>
 4919           </ptrtype>
 4920           <description>
 4921             Callbacks are only reported when the object is an instance of
 4922             this class.
 4923             Objects which are instances of a subclass of <code>klass</code>
 4924             are not reported.
 4925             If <code>klass</code> is an interface, no objects are reported.
 4926             This applies to both the object and primitive callbacks.
 4927           </description>
 4928         </param>
 4929         <param id="callbacks">
 4930           <inptr>
 4931             <struct>jvmtiHeapCallbacks</struct>
 4932           </inptr>
 4933           <description>
 4934             Structure defining the set callback functions.
 4935           </description>
 4936         </param>
 4937         <param id="user_data">
 4938           <inbuf>
 4939             <void/>
 4940             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
 4941           </inbuf>
 4942           <description>
 4943             User supplied data to be passed to the callback.
 4944           </description>
 4945         </param>
 4946       </parameters>
 4947       <errors>
 4948         <error id="JVMTI_ERROR_INVALID_CLASS">
 4949           <paramlink id="klass"/> is not a valid class.
 4950         </error>
 4951       </errors>
 4952     </function>
 4953 
 4954     <function id="GetTag" phase="start" num="106">
 4955       <synopsis>Get Tag</synopsis>
 4956       <description>
 4957         Retrieve the tag associated with an object.
 4958         The tag is a long value typically used to store a
 4959         unique identifier or pointer to object information.
 4960         The tag is set with
 4961         <functionlink id="SetTag"></functionlink>.
 4962         Objects for which no tags have been set return a
 4963         tag value of zero.
 4964       </description>
 4965       <origin>new</origin>
 4966       <capabilities>
 4967         <required id="can_tag_objects"></required>
 4968       </capabilities>
 4969       <parameters>
 4970         <param id="object">
 4971           <jobject/>
 4972             <description>
 4973               The object whose tag is to be retrieved.
 4974             </description>
 4975         </param>
 4976         <param id="tag_ptr">
 4977           <outptr><jlong/></outptr>
 4978           <description>
 4979             On return, the referenced long is set to the value
 4980             of the tag.
 4981           </description>
 4982         </param>
 4983       </parameters>
 4984       <errors>
 4985       </errors>
 4986     </function>
 4987 
 4988     <function id="SetTag" phase="start" num="107">
 4989       <synopsis>Set Tag</synopsis>
 4990       <description>
 4991         Set the tag associated with an object.
 4992         The tag is a long value typically used to store a
 4993         unique identifier or pointer to object information.
 4994         The tag is visible with
 4995         <functionlink id="GetTag"></functionlink>.
 4996       </description>
 4997       <origin>new</origin>
 4998       <capabilities>
 4999         <required id="can_tag_objects"></required>
 5000       </capabilities>
 5001       <parameters>
 5002         <param id="object">
 5003           <jobject/>
 5004             <description>
 5005               The object whose tag is to be set.
 5006             </description>
 5007         </param>
 5008         <param id="tag">
 5009           <jlong/>
 5010           <description>
 5011             The new value of the tag.
 5012           </description>
 5013         </param>
 5014       </parameters>
 5015       <errors>
 5016       </errors>
 5017     </function>
 5018 
 5019     <function id="GetObjectsWithTags" num="114">
 5020       <synopsis>Get Objects With Tags</synopsis>
 5021       <description>
 5022         Return objects in the heap with the specified tags.
 5023         The format is parallel arrays of objects and tags.
 5024       </description>
 5025       <origin>new</origin>
 5026       <capabilities>
 5027         <required id="can_tag_objects"></required>
 5028       </capabilities>
 5029       <parameters>
 5030         <param id="tag_count">
 5031           <jint min="0"/>
 5032             <description>
 5033               Number of tags to scan for.
 5034             </description>
 5035         </param>
 5036         <param id="tags">
 5037           <inbuf incount="tag_count">
 5038             <jlong/>
 5039           </inbuf>
 5040             <description>
 5041               Scan for objects with these tags.
 5042               Zero is not permitted in this array.
 5043             </description>
 5044         </param>
 5045         <param id="count_ptr">
 5046           <outptr>
 5047             <jint/>
 5048           </outptr>
 5049             <description>
 5050               Return the number of objects with any of the tags
 5051               in <paramlink id="tags"/>.
 5052             </description>
 5053         </param>
 5054         <param id="object_result_ptr">
 5055           <allocbuf outcount="count_ptr">
 5056             <jobject/>
 5057             <nullok>this information is not returned</nullok>
 5058           </allocbuf>
 5059             <description>
 5060               Returns the array of objects with any of the tags
 5061               in <paramlink id="tags"/>.
 5062             </description>
 5063         </param>
 5064         <param id="tag_result_ptr">
 5065           <allocbuf outcount="count_ptr">
 5066             <jlong/>
 5067             <nullok>this information is not returned</nullok>
 5068           </allocbuf>
 5069             <description>
 5070               For each object in <paramlink id="object_result_ptr"/>,
 5071               return the tag at the corresponding index.
 5072             </description>
 5073         </param>
 5074       </parameters>
 5075       <errors>
 5076         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 5077           Zero is present in <paramlink id="tags"></paramlink>.
 5078         </error>
 5079       </errors>
 5080     </function>
 5081 
 5082     <function id="ForceGarbageCollection" num="108">
 5083       <synopsis>Force Garbage Collection</synopsis>
 5084       <description>
 5085         Force the VM to perform a garbage collection.
 5086         The garbage collection is as complete as possible.
 5087         This function does not cause finalizers to be run.
 5088         This function does not return until the garbage collection
 5089         is finished.
 5090         <p/>
 5091         Although garbage collection is as complete
 5092         as possible there is no guarantee that all
 5093         <eventlink id="ObjectFree"/>
 5094         events will have been
 5095         sent by the time that this function
 5096         returns. In particular, an object may be
 5097         prevented from being freed because it
 5098         is awaiting finalization.
 5099       </description>
 5100       <origin>new</origin>
 5101       <capabilities>
 5102       </capabilities>
 5103       <parameters>
 5104       </parameters>
 5105       <errors>
 5106       </errors>
 5107     </function>
 5108 
 5109 
 5110   </category>
 5111 
 5112   <category id="Heap_1_0" label="Heap (1.0)">
 5113     <intro>
 5114       <b>
 5115         These functions and data types were introduced in the original
 5116         <jvmti/> version 1.0. They are deprecated and will be changed 
 5117         to return an error in a future release. They were superseded in
 5118         <jvmti/> version 1.2 (Java SE 6) by more 
 5119       </b>
 5120       <internallink id="Heap"><b>powerful and flexible versions</b></internallink>
 5121       <b>
 5122         which:
 5123       </b>
 5124       <ul>
 5125         <li>
 5126           <b>
 5127             Allow access to primitive values (the value of Strings, arrays,
 5128             and primitive fields)
 5129           </b>
 5130         </li>
 5131         <li>
 5132           <b>
 5133             Allow the tag of the referrer to be set, thus enabling more
 5134             efficient localized reference graph building
 5135           </b>
 5136         </li>
 5137         <li>
 5138           <b>
 5139             Provide more extensive filtering abilities
 5140           </b>
 5141         </li>
 5142         <li>
 5143           <b>
 5144             Are extensible, allowing their abilities to grow in future versions of <jvmti/>
 5145           </b>
 5146         </li>
 5147       </ul>
 5148       <p/>
 5149       <b>Please use the </b>
 5150       <internallink id="Heap"><b>current Heap functions</b></internallink>.
 5151         <p/>
 5152         <constants id="jvmtiHeapObjectFilter" label="Heap Object Filter Enumeration" kind="enum">
 5153           <constant id="JVMTI_HEAP_OBJECT_TAGGED" num="1">
 5154             Tagged objects only.
 5155           </constant>
 5156           <constant id="JVMTI_HEAP_OBJECT_UNTAGGED" num="2">
 5157             Untagged objects only.
 5158           </constant>
 5159           <constant id="JVMTI_HEAP_OBJECT_EITHER" num="3">
 5160             Either tagged or untagged objects.
 5161           </constant>
 5162         </constants>
 5163 
 5164         <constants id="jvmtiHeapRootKind" label="Heap Root Kind Enumeration" kind="enum">
 5165           <constant id="JVMTI_HEAP_ROOT_JNI_GLOBAL" num="1">
 5166             JNI global reference.
 5167           </constant>
 5168           <constant id="JVMTI_HEAP_ROOT_SYSTEM_CLASS" num="2">
 5169             System class.
 5170           </constant>
 5171           <constant id="JVMTI_HEAP_ROOT_MONITOR" num="3">
 5172             Monitor.
 5173           </constant>
 5174           <constant id="JVMTI_HEAP_ROOT_STACK_LOCAL" num="4">
 5175             Stack local.
 5176           </constant>
 5177           <constant id="JVMTI_HEAP_ROOT_JNI_LOCAL" num="5">
 5178             JNI local reference.
 5179           </constant>
 5180           <constant id="JVMTI_HEAP_ROOT_THREAD" num="6">
 5181             Thread.
 5182           </constant>
 5183           <constant id="JVMTI_HEAP_ROOT_OTHER" num="7">
 5184             Other.
 5185           </constant>
 5186         </constants>
 5187 
 5188         <constants id="jvmtiObjectReferenceKind" label="Object Reference Enumeration" kind="enum">
 5189           <constant id="JVMTI_REFERENCE_CLASS" num="1">
 5190             Reference from an object to its class.
 5191           </constant>
 5192           <constant id="JVMTI_REFERENCE_FIELD" num="2">
 5193             Reference from an object to the value of one of its instance fields.
 5194             For references of this kind the <code>referrer_index</code>
 5195             parameter to the <internallink id="jvmtiObjectReferenceCallback">
 5196             jvmtiObjectReferenceCallback</internallink> is the index of the
 5197             the instance field. The index is based on the order of all the
 5198             object's fields. This includes all fields of the directly declared
 5199             static and instance fields in the class, and includes all fields (both
 5200             public and private) fields declared in superclasses and superinterfaces.
 5201             The index is thus calculated by summing the index of the field in the directly
 5202             declared class (see <functionlink id="GetClassFields"/>), with the total
 5203             number of fields (both public and private) declared in all superclasses
 5204             and superinterfaces. The index starts at zero.
 5205           </constant>
 5206           <constant id="JVMTI_REFERENCE_ARRAY_ELEMENT" num="3">
 5207             Reference from an array to one of its elements.
 5208             For references of this kind the <code>referrer_index</code>
 5209             parameter to the <internallink id="jvmtiObjectReferenceCallback">
 5210             jvmtiObjectReferenceCallback</internallink> is the array index.
 5211           </constant>
 5212           <constant id="JVMTI_REFERENCE_CLASS_LOADER" num="4">
 5213             Reference from a class to its class loader.
 5214           </constant>
 5215           <constant id="JVMTI_REFERENCE_SIGNERS" num="5">
 5216             Reference from a class to its signers array.
 5217           </constant>
 5218           <constant id="JVMTI_REFERENCE_PROTECTION_DOMAIN" num="6">
 5219             Reference from a class to its protection domain.
 5220           </constant>
 5221           <constant id="JVMTI_REFERENCE_INTERFACE" num="7">
 5222             Reference from a class to one of its interfaces.
 5223           </constant>
 5224           <constant id="JVMTI_REFERENCE_STATIC_FIELD" num="8">
 5225             Reference from a class to the value of one of its static fields.
 5226             For references of this kind the <code>referrer_index</code>
 5227             parameter to the <internallink id="jvmtiObjectReferenceCallback">
 5228             jvmtiObjectReferenceCallback</internallink> is the index of the
 5229             the static field. The index is based on the order of all the
 5230             object's fields. This includes all fields of the directly declared
 5231             static and instance fields in the class, and includes all fields (both
 5232             public and private) fields declared in superclasses and superinterfaces.
 5233             The index is thus calculated by summing the index of the field in the directly
 5234             declared class (see <functionlink id="GetClassFields"/>), with the total
 5235             number of fields (both public and private) declared in all superclasses
 5236             and superinterfaces. The index starts at zero.
 5237             Note: this definition differs from that in the <jvmti/> 1.0 Specification.
 5238             <rationale>No known implementations used the 1.0 definition.</rationale>
 5239           </constant>
 5240           <constant id="JVMTI_REFERENCE_CONSTANT_POOL" num="9">
 5241             Reference from a class to a resolved entry in the constant pool.
 5242             For references of this kind the <code>referrer_index</code>
 5243             parameter to the <internallink id="jvmtiObjectReferenceCallback">
 5244             jvmtiObjectReferenceCallback</internallink> is the index into
 5245             constant pool table of the class, starting at 1. See
 5246             <vmspec chapter="4.4"/>.
 5247           </constant>
 5248         </constants>
 5249 
 5250         <constants id="jvmtiIterationControl" label="Iteration Control Enumeration" kind="enum">
 5251           <constant id="JVMTI_ITERATION_CONTINUE" num="1">
 5252             Continue the iteration.
 5253             If this is a reference iteration, follow the references of this object.
 5254           </constant>
 5255           <constant id="JVMTI_ITERATION_IGNORE" num="2">
 5256             Continue the iteration.
 5257             If this is a reference iteration, ignore the references of this object.
 5258           </constant>
 5259           <constant id="JVMTI_ITERATION_ABORT" num="0">
 5260             Abort the iteration.
 5261           </constant>
 5262         </constants>
 5263     </intro>
 5264 
 5265     <callback id="jvmtiHeapObjectCallback">
 5266       <enum>jvmtiIterationControl</enum>
 5267       <synopsis>Heap Object Callback</synopsis>
 5268       <description>
 5269         Agent supplied callback function.
 5270         Describes (but does not pass in) an object in the heap.
 5271         <p/>
 5272         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
 5273         or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
 5274         <p/>
 5275         See the <internallink id="heapCallbacks">heap callback
 5276         function restrictions</internallink>.
 5277       </description>
 5278       <parameters>
 5279         <param id="class_tag">
 5280           <jlong/>
 5281           <description>
 5282             The tag of the class of object (zero if the class is not tagged).
 5283             If the object represents a runtime class,
 5284             the <code>class_tag</code> is the tag
 5285             associated with <code>java.lang.Class</code>
 5286             (zero if <code>java.lang.Class</code> is not tagged).
 5287           </description>
 5288         </param>
 5289         <param id="size">
 5290           <jlong/>
 5291           <description>
 5292             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
 5293           </description>
 5294         </param>
 5295         <param id="tag_ptr">
 5296           <outptr><jlong/></outptr>
 5297           <description>
 5298             The object tag value, or zero if the object is not tagged.
 5299             To set the tag value to be associated with the object
 5300             the agent sets the <code>jlong</code> pointed to by the parameter.
 5301           </description>
 5302         </param>
 5303         <param id="user_data">
 5304           <outptr><void/></outptr>
 5305           <description>
 5306             The user supplied data that was passed into the iteration function.
 5307           </description>
 5308         </param>
 5309       </parameters>
 5310     </callback>
 5311 
 5312     <callback id="jvmtiHeapRootCallback">
 5313       <enum>jvmtiIterationControl</enum>
 5314       <synopsis>Heap Root Object Callback</synopsis>
 5315       <description>
 5316         Agent supplied callback function.
 5317         Describes (but does not pass in) an object that is a root for the purposes
 5318         of garbage collection.
 5319         <p/>
 5320         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
 5321         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
 5322         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
 5323         <p/>
 5324         See the <internallink id="heapCallbacks">heap callback
 5325         function restrictions</internallink>.
 5326       </description>
 5327       <parameters>
 5328         <param id="root_kind">
 5329           <enum>jvmtiHeapRootKind</enum>
 5330           <description>
 5331             The kind of heap root.
 5332           </description>
 5333         </param>
 5334         <param id="class_tag">
 5335           <jlong/>
 5336           <description>
 5337             The tag of the class of object (zero if the class is not tagged).
 5338             If the object represents a runtime class, the <code>class_tag</code> is the tag
 5339             associated with <code>java.lang.Class</code>
 5340             (zero if <code>java.lang.Class</code> is not tagged).
 5341           </description>
 5342         </param>
 5343         <param id="size">
 5344           <jlong/>
 5345           <description>
 5346             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
 5347           </description>
 5348         </param>
 5349         <param id="tag_ptr">
 5350           <outptr><jlong/></outptr>
 5351           <description>
 5352             The object tag value, or zero if the object is not tagged.
 5353             To set the tag value to be associated with the object
 5354             the agent sets the <code>jlong</code> pointed to by the parameter.
 5355           </description>
 5356         </param>
 5357         <param id="user_data">
 5358           <outptr><void/></outptr>
 5359           <description>
 5360             The user supplied data that was passed into the iteration function.
 5361           </description>
 5362         </param>
 5363       </parameters>
 5364     </callback>
 5365 
 5366     <callback id="jvmtiStackReferenceCallback">
 5367       <enum>jvmtiIterationControl</enum>
 5368       <synopsis>Stack Reference Object Callback</synopsis>
 5369       <description>
 5370         Agent supplied callback function.
 5371         Describes (but does not pass in) an object on the stack that is a root for
 5372         the purposes of garbage collection.
 5373         <p/>
 5374         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
 5375         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
 5376         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
 5377         <p/>
 5378         See the <internallink id="heapCallbacks">heap callback
 5379         function restrictions</internallink>.
 5380       </description>
 5381       <parameters>
 5382         <param id="root_kind">
 5383           <enum>jvmtiHeapRootKind</enum>
 5384           <description>
 5385             The kind of root (either <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
 5386             <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>).
 5387           </description>
 5388         </param>
 5389         <param id="class_tag">
 5390           <jlong/>
 5391           <description>
 5392            The tag of the class of object (zero if the class is not tagged).
 5393            If the object represents a runtime class, the  <code>class_tag</code> is the tag
 5394            associated with <code>java.lang.Class</code>
 5395            (zero if <code>java.lang.Class</code> is not tagged).
 5396           </description>
 5397         </param>
 5398         <param id="size">
 5399           <jlong/>
 5400           <description>
 5401             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
 5402           </description>
 5403         </param>
 5404         <param id="tag_ptr">
 5405           <outptr><jlong/></outptr>
 5406           <description>
 5407             The object tag value, or zero if the object is not tagged.
 5408             To set the tag value to be associated with the object
 5409             the agent sets the <code>jlong</code> pointed to by the parameter.
 5410           </description>
 5411         </param>
 5412         <param id="thread_tag">
 5413           <jlong/>
 5414           <description>
 5415             The tag of the thread corresponding to this stack, zero if not tagged.
 5416           </description>
 5417         </param>
 5418         <param id="depth">
 5419           <jint/>
 5420           <description>
 5421             The depth of the frame.
 5422           </description>
 5423         </param>
 5424         <param id="method">
 5425           <jmethodID/>
 5426           <description>
 5427             The method executing in this frame.
 5428           </description>
 5429         </param>
 5430         <param id="slot">
 5431           <jint/>
 5432           <description>
 5433             The slot number.
 5434           </description>
 5435         </param>
 5436         <param id="user_data">
 5437           <outptr><void/></outptr>
 5438           <description>
 5439             The user supplied data that was passed into the iteration function.
 5440           </description>
 5441         </param>
 5442       </parameters>
 5443     </callback>
 5444 
 5445     <callback id="jvmtiObjectReferenceCallback">
 5446       <enum>jvmtiIterationControl</enum>
 5447       <synopsis>Object Reference Callback</synopsis>
 5448       <description>
 5449         Agent supplied callback function.
 5450         Describes a reference from an object (the referrer) to another object
 5451         (the referree).
 5452         <p/>
 5453         Return value should be <code>JVMTI_ITERATION_CONTINUE</code> to continue iteration,
 5454         <code>JVMTI_ITERATION_IGNORE</code> to continue iteration without pursuing
 5455         references from referree object or <code>JVMTI_ITERATION_ABORT</code> to stop iteration.
 5456         <p/>
 5457         See the <internallink id="heapCallbacks">heap callback
 5458         function restrictions</internallink>.
 5459       </description>
 5460       <parameters>
 5461         <param id="reference_kind">
 5462           <enum>jvmtiObjectReferenceKind</enum>
 5463           <description>
 5464             The type of reference.
 5465           </description>
 5466         </param>
 5467         <param id="class_tag">
 5468           <jlong/>
 5469           <description>
 5470             The tag of the class of referree object (zero if the class is not tagged).
 5471             If the referree object represents a runtime class,
 5472             the  <code>class_tag</code> is the tag
 5473             associated with <code>java.lang.Class</code>
 5474             (zero if <code>java.lang.Class</code> is not tagged).
 5475           </description>
 5476         </param>
 5477         <param id="size">
 5478           <jlong/>
 5479           <description>
 5480             Size of the referree object (in bytes).
 5481             See <functionlink id="GetObjectSize"/>.
 5482           </description>
 5483         </param>
 5484         <param id="tag_ptr">
 5485           <outptr><jlong/></outptr>
 5486           <description>
 5487             The referree object tag value, or zero if the object is not
 5488             tagged.
 5489             To set the tag value to be associated with the object
 5490             the agent sets the <code>jlong</code> pointed to by the parameter.
 5491           </description>
 5492         </param>
 5493         <param id="referrer_tag">
 5494           <jlong/>
 5495           <description>
 5496             The tag of the referrer object, or zero if the referrer
 5497             object is not tagged.
 5498           </description>
 5499         </param>
 5500         <param id="referrer_index">
 5501           <jint/>
 5502           <description>
 5503             For references of type <code>JVMTI_REFERENCE_FIELD</code> or
 5504             <code>JVMTI_REFERENCE_STATIC_FIELD</code> the index
 5505             of the field in the referrer object. The index is based on the
 5506             order of all the object's fields - see <internallink
 5507             id="JVMTI_REFERENCE_FIELD">JVMTI_REFERENCE_FIELD</internallink>
 5508             or <internallink
 5509             id="JVMTI_REFERENCE_STATIC_FIELD">JVMTI_REFERENCE_STATIC_FIELD
 5510             </internallink> for further description.
 5511             <p/>
 5512             For references of type <code>JVMTI_REFERENCE_ARRAY_ELEMENT</code>
 5513             the array index - see <internallink id="JVMTI_REFERENCE_ARRAY_ELEMENT">
 5514             JVMTI_REFERENCE_ARRAY_ELEMENT</internallink> for further description.
 5515             <p/>
 5516             For references of type <code>JVMTI_REFERENCE_CONSTANT_POOL</code>
 5517             the index into the constant pool of the class - see
 5518             <internallink id="JVMTI_REFERENCE_CONSTANT_POOL">
 5519             JVMTI_REFERENCE_CONSTANT_POOL</internallink> for further
 5520             description.
 5521             <p/>
 5522             For references of other kinds the <code>referrer_index</code> is
 5523             <code>-1</code>.
 5524           </description>
 5525         </param>
 5526         <param id="user_data">
 5527           <outptr><void/></outptr>
 5528           <description>
 5529             The user supplied data that was passed into the iteration function.
 5530           </description>
 5531         </param>
 5532       </parameters>
 5533     </callback>
 5534 
 5535     <function id="IterateOverObjectsReachableFromObject" num="109">
 5536       <synopsis>Iterate Over Objects Reachable From Object</synopsis>
 5537       <description>
 5538         This function iterates over all objects that are directly
 5539         and indirectly reachable from the specified object.
 5540         For each object <i>A</i> (known
 5541         as the referrer) with a reference to object <i>B</i> the specified
 5542         callback function is called to describe the object reference.
 5543         The callback is called exactly once for each reference from a referrer;
 5544         this is true even if there are reference cycles or multiple paths to
 5545         the referrer.
 5546         There may be more than one reference between a referrer and a referree,
 5547         These may be distinguished by the
 5548         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
 5549         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
 5550         The callback for an object will always occur after the callback for
 5551         its referrer.
 5552         <p/>
 5553         See <functionlink id="FollowReferences"/> for the object
 5554         references which are reported.
 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">
 5571           <jobject/>
 5572             <description>
 5573               The object
 5574             </description>
 5575         </param>
 5576         <param id="object_reference_callback">
 5577           <ptrtype>
 5578             <struct>jvmtiObjectReferenceCallback</struct>
 5579           </ptrtype>
 5580             <description>
 5581               The callback to be called to describe each
 5582               object reference.
 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="IterateOverReachableObjects" num="110">
 5600       <synopsis>Iterate Over Reachable Objects</synopsis>
 5601       <description>
 5602         This function iterates over the root objects and all objects that
 5603         are directly and indirectly reachable from the root objects.
 5604         The root objects comprise the set of system classes,
 5605         JNI globals, references from thread stacks, and other objects used as roots
 5606         for the purposes of garbage collection.
 5607         <p/>
 5608         For each root the <paramlink id="heap_root_callback"></paramlink>
 5609         or <paramlink id="stack_ref_callback"></paramlink> callback is called.
 5610         An object can be a root object for more than one reason and in that case
 5611         the appropriate callback is called for each reason.
 5612         <p/>
 5613         For each object reference the <paramlink id="object_ref_callback"></paramlink>
 5614         callback function is called to describe the object reference.
 5615         The callback is called exactly once for each reference from a referrer;
 5616         this is true even if there are reference cycles or multiple paths to
 5617         the referrer.
 5618         There may be more than one reference between a referrer and a referree,
 5619         These may be distinguished by the
 5620         <datalink id="jvmtiObjectReferenceCallback.reference_kind"></datalink> and
 5621         <datalink id="jvmtiObjectReferenceCallback.referrer_index"></datalink>.
 5622         The callback for an object will always occur after the callback for
 5623         its referrer.
 5624         <p/>
 5625         See <functionlink id="FollowReferences"/> for the object
 5626         references which are reported.
 5627         <p/>
 5628         Roots are always reported to the profiler before any object references
 5629         are reported. In other words, the <paramlink id="object_ref_callback"></paramlink>
 5630         callback will not be called until the appropriate callback has been called
 5631         for all roots. If the <paramlink id="object_ref_callback"></paramlink> callback is
 5632         specified as <code>NULL</code> then this function returns after
 5633         reporting the root objects to the profiler.
 5634         <p/>
 5635         During the execution of this function the state of the heap
 5636         does not change: no objects are allocated, no objects are
 5637         garbage collected, and the state of objects (including
 5638         held values) does not change.
 5639         As a result, threads executing Java
 5640         programming language code, threads attempting to resume the
 5641         execution of Java programming language code, and threads
 5642         attempting to execute JNI functions are typically stalled.
 5643       </description>
 5644       <origin>new</origin>
 5645       <capabilities>
 5646         <required id="can_tag_objects"></required>
 5647       </capabilities>
 5648       <parameters>
 5649         <param id="heap_root_callback">
 5650           <ptrtype>
 5651             <struct>jvmtiHeapRootCallback</struct>
 5652             <nullok>do not report heap roots</nullok>
 5653           </ptrtype>
 5654             <description>
 5655               The callback function to be called for each heap root of type
 5656               <code>JVMTI_HEAP_ROOT_JNI_GLOBAL</code>,
 5657               <code>JVMTI_HEAP_ROOT_SYSTEM_CLASS</code>,
 5658               <code>JVMTI_HEAP_ROOT_MONITOR</code>,
 5659               <code>JVMTI_HEAP_ROOT_THREAD</code>, or
 5660               <code>JVMTI_HEAP_ROOT_OTHER</code>.
 5661             </description>
 5662         </param>
 5663         <param id="stack_ref_callback">
 5664           <ptrtype>
 5665             <struct>jvmtiStackReferenceCallback</struct>
 5666             <nullok>do not report stack references</nullok>
 5667           </ptrtype>
 5668             <description>
 5669               The callback function to be called for each heap root of
 5670               <code>JVMTI_HEAP_ROOT_STACK_LOCAL</code> or
 5671               <code>JVMTI_HEAP_ROOT_JNI_LOCAL</code>.
 5672             </description>
 5673         </param>
 5674         <param id="object_ref_callback">
 5675           <ptrtype>
 5676             <struct>jvmtiObjectReferenceCallback</struct>
 5677             <nullok>do not follow references from the root objects</nullok>
 5678           </ptrtype>
 5679             <description>
 5680               The callback function to be called for each object reference.
 5681             </description>
 5682         </param>
 5683         <param id="user_data">
 5684           <inbuf>
 5685             <void/>
 5686             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
 5687           </inbuf>
 5688           <description>
 5689             User supplied data to be passed to the callback.
 5690           </description>
 5691         </param>
 5692       </parameters>
 5693       <errors>
 5694       </errors>
 5695     </function>
 5696 
 5697     <function id="IterateOverHeap" num="111">
 5698       <synopsis>Iterate Over Heap</synopsis>
 5699       <description>
 5700         Iterate over all objects in the heap. This includes both reachable and
 5701         unreachable objects.
 5702         <p/>
 5703         The <paramlink id="object_filter"></paramlink> parameter indicates the
 5704         objects for which the callback function is called. If this parameter
 5705         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
 5706         called for every object that is tagged. If the parameter is
 5707         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
 5708         for objects that are not tagged. If the parameter
 5709         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
 5710         called for every object in the heap, irrespective of whether it is
 5711         tagged or not.
 5712         <p/>
 5713         During the execution of this function the state of the heap
 5714         does not change: no objects are allocated, no objects are
 5715         garbage collected, and the state of objects (including
 5716         held values) does not change.
 5717         As a result, threads executing Java
 5718         programming language code, threads attempting to resume the
 5719         execution of Java programming language code, and threads
 5720         attempting to execute JNI functions are typically stalled.
 5721       </description>
 5722       <origin>new</origin>
 5723       <capabilities>
 5724         <required id="can_tag_objects"></required>
 5725       </capabilities>
 5726       <parameters>
 5727         <param id="object_filter">
 5728           <enum>jvmtiHeapObjectFilter</enum>
 5729           <description>
 5730             Indicates the objects for which the callback function is called.
 5731           </description>
 5732         </param>
 5733         <param id="heap_object_callback">
 5734           <ptrtype>
 5735             <struct>jvmtiHeapObjectCallback</struct>
 5736           </ptrtype>
 5737             <description>
 5738               The iterator function to be called for each
 5739               object matching the <paramlink id="object_filter"/>.
 5740             </description>
 5741         </param>
 5742         <param id="user_data">
 5743           <inbuf>
 5744             <void/>
 5745             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
 5746           </inbuf>
 5747           <description>
 5748             User supplied data to be passed to the callback.
 5749           </description>
 5750         </param>
 5751       </parameters>
 5752       <errors>
 5753       </errors>
 5754     </function>
 5755 
 5756     <function id="IterateOverInstancesOfClass" num="112">
 5757       <synopsis>Iterate Over Instances Of Class</synopsis>
 5758       <description>
 5759         Iterate over all objects in the heap that are instances of the specified class.
 5760         This includes direct instances of the specified class and
 5761         instances of all subclasses of the specified class.
 5762         This includes both reachable and unreachable objects.
 5763         <p/>
 5764         The <paramlink id="object_filter"></paramlink> parameter indicates the
 5765         objects for which the callback function is called. If this parameter
 5766         is <code>JVMTI_HEAP_OBJECT_TAGGED</code> then the callback will only be
 5767         called for every object that is tagged. If the parameter is
 5768         <code>JVMTI_HEAP_OBJECT_UNTAGGED</code> then the callback will only be
 5769         called for objects that are not tagged. If the parameter
 5770         is <code>JVMTI_HEAP_OBJECT_EITHER</code> then the callback will be
 5771         called for every object in the heap, irrespective of whether it is
 5772         tagged or not.
 5773         <p/>
 5774         During the execution of this function the state of the heap
 5775         does not change: no objects are allocated, no objects are
 5776         garbage collected, and the state of objects (including
 5777         held values) does not change.
 5778         As a result, threads executing Java
 5779         programming language code, threads attempting to resume the
 5780         execution of Java programming language code, and threads
 5781         attempting to execute JNI functions are typically stalled.
 5782       </description>
 5783       <origin>new</origin>
 5784       <capabilities>
 5785         <required id="can_tag_objects"></required>
 5786       </capabilities>
 5787       <parameters>
 5788         <param id="klass">
 5789           <jclass/>
 5790             <description>
 5791               Iterate over objects of this class only.
 5792             </description>
 5793         </param>
 5794         <param id="object_filter">
 5795           <enum>jvmtiHeapObjectFilter</enum>
 5796           <description>
 5797             Indicates the objects for which the callback function is called.
 5798           </description>
 5799         </param>
 5800         <param id="heap_object_callback">
 5801           <ptrtype>
 5802             <struct>jvmtiHeapObjectCallback</struct>
 5803           </ptrtype>
 5804             <description>
 5805               The iterator function to be called for each
 5806               <paramlink id="klass"/> instance matching
 5807               the <paramlink id="object_filter"/>.
 5808             </description>
 5809         </param>
 5810         <param id="user_data">
 5811           <inbuf>
 5812             <void/>
 5813             <nullok><code>NULL</code> is passed as the user supplied data</nullok>
 5814           </inbuf>
 5815           <description>
 5816             User supplied data to be passed to the callback.
 5817           </description>
 5818         </param>
 5819       </parameters>
 5820       <errors>
 5821       </errors>
 5822     </function>
 5823 
 5824   </category>
 5825 
 5826   <category id="local" label="Local Variable">
 5827 
 5828     <intro>
 5829       These functions are used to retrieve or set the value of a local variable.
 5830       The variable is identified by the depth of the frame containing its
 5831       value and the variable's slot number within that frame.
 5832       The mapping of variables to
 5833       slot numbers can be obtained with the function
 5834       <functionlink id="GetLocalVariableTable"></functionlink>.
 5835     </intro>
 5836 
 5837     <function id="GetLocalObject" num="21">
 5838       <synopsis>Get Local Variable - Object</synopsis>
 5839       <description>
 5840         This function can be used to retrieve the value of a local
 5841         variable whose type is <code>Object</code> or a subclass of <code>Object</code>.
 5842       </description>
 5843       <origin>jvmdi</origin>
 5844       <capabilities>
 5845         <required id="can_access_local_variables"></required>
 5846       </capabilities>
 5847       <parameters>
 5848         <param id="thread">
 5849           <jthread null="current" frame="frame" impl="noconvert"/>
 5850           <description>
 5851             The thread of the frame containing the variable's value.
 5852           </description>
 5853         </param>
 5854         <param id="depth">
 5855           <jframeID thread="thread"/>
 5856           <description>
 5857             The depth of the frame containing the variable's value.
 5858           </description>
 5859         </param>
 5860         <param id="slot">
 5861           <jint/>
 5862           <description>
 5863             The variable's slot number.
 5864           </description>
 5865         </param>
 5866         <param id="value_ptr">
 5867           <outptr><jobject/></outptr>
 5868             <description>
 5869               On return, points to the variable's value.
 5870             </description>
 5871         </param>
 5872       </parameters>
 5873       <errors>
 5874         <error id="JVMTI_ERROR_INVALID_SLOT">
 5875           Invalid <code>slot</code>.
 5876         </error>
 5877         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 5878           The variable type is not
 5879           <code>Object</code> or a subclass of <code>Object</code>.
 5880         </error>
 5881         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 5882           Not a visible frame
 5883         </error>
 5884       </errors>
 5885     </function>
 5886 
 5887     <function id="GetLocalInstance" num="155" since="1.2">
 5888       <synopsis>Get Local Instance</synopsis>
 5889       <description>
 5890         This function can be used to retrieve the value of the local object
 5891         variable at slot 0 (the "<code>this</code>" object) from non-static
 5892         frames.  This function can retrieve the "<code>this</code>" object from
 5893         native method frames, whereas <code>GetLocalObject()</code> would
 5894         return <code>JVMTI_ERROR_OPAQUE_FRAME</code> in those cases.
 5895       </description>
 5896       <origin>new</origin>
 5897       <capabilities>
 5898         <required id="can_access_local_variables"></required>
 5899       </capabilities>
 5900       <parameters>
 5901         <param id="thread">
 5902           <jthread null="current" frame="frame" impl="noconvert"/>
 5903           <description>
 5904             The thread of the frame containing the variable's value.
 5905           </description>
 5906         </param>
 5907         <param id="depth">
 5908           <jframeID thread="thread"/>
 5909           <description>
 5910             The depth of the frame containing the variable's value.
 5911           </description>
 5912         </param>
 5913         <param id="value_ptr">
 5914           <outptr><jobject/></outptr>
 5915             <description>
 5916               On return, points to the variable's value.
 5917             </description>
 5918         </param>
 5919       </parameters>
 5920       <errors>
 5921         <error id="JVMTI_ERROR_INVALID_SLOT">
 5922           If the specified frame is a static method frame.
 5923         </error>
 5924       </errors>
 5925     </function>
 5926     <function id="GetLocalInt" num="22">
 5927       <synopsis>Get Local Variable - Int</synopsis>
 5928       <description>
 5929         This function can be used to retrieve the value of a local
 5930         variable whose type is <code>int</code>,
 5931         <code>short</code>, <code>char</code>, <code>byte</code>, or
 5932         <code>boolean</code>.
 5933       </description>
 5934       <origin>jvmdi</origin>
 5935       <capabilities>
 5936         <required id="can_access_local_variables"></required>
 5937       </capabilities>
 5938       <parameters>
 5939         <param id="thread">
 5940           <jthread null="current" frame="frame" impl="noconvert"/>
 5941           <description>
 5942             The thread of the frame containing the variable's value.
 5943           </description>
 5944         </param>
 5945         <param id="depth">
 5946           <jframeID thread="thread"/>
 5947           <description>
 5948             The depth of the frame containing the variable's value.
 5949           </description>
 5950         </param>
 5951         <param id="slot">
 5952           <jint/>
 5953           <description>
 5954             The variable's slot number.
 5955           </description>
 5956         </param>
 5957         <param id="value_ptr">
 5958           <outptr><jint/></outptr>
 5959           <description>
 5960             On return, points to the variable's value.
 5961           </description>
 5962         </param>
 5963       </parameters>
 5964       <errors>
 5965         <error id="JVMTI_ERROR_INVALID_SLOT">
 5966           Invalid <code>slot</code>.
 5967         </error>
 5968         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 5969           The variable type is not
 5970           <code>int</code>, <code>short</code>,
 5971           <code>char</code>, <code>byte</code>, or
 5972           <code>boolean</code>.
 5973         </error>
 5974         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 5975           Not a visible frame
 5976         </error>
 5977       </errors>
 5978     </function>
 5979 
 5980     <function id="GetLocalLong" num="23">
 5981       <synopsis>Get Local Variable - Long</synopsis>
 5982       <description>
 5983         This function can be used to retrieve the value of a local
 5984         variable whose type is <code>long</code>.
 5985       </description>
 5986       <origin>jvmdi</origin>
 5987       <capabilities>
 5988         <required id="can_access_local_variables"></required>
 5989       </capabilities>
 5990       <parameters>
 5991         <param id="thread">
 5992           <jthread null="current" frame="frame" impl="noconvert"/>
 5993           <description>
 5994             The thread of the frame containing the variable's value.
 5995           </description>
 5996         </param>
 5997         <param id="depth">
 5998           <jframeID thread="thread"/>
 5999           <description>
 6000             The depth of the frame containing the variable's value.
 6001           </description>
 6002         </param>
 6003         <param id="slot">
 6004           <jint/>
 6005           <description>
 6006             The variable's slot number.
 6007           </description>
 6008         </param>
 6009         <param id="value_ptr">
 6010           <outptr><jlong/></outptr>
 6011           <description>
 6012             On return, points to the variable's value.
 6013           </description>
 6014         </param>
 6015       </parameters>
 6016       <errors>
 6017         <error id="JVMTI_ERROR_INVALID_SLOT">
 6018           Invalid <code>slot</code>.
 6019         </error>
 6020         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 6021           The variable type is not <code>long</code>.
 6022         </error>
 6023         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 6024           Not a visible frame
 6025         </error>
 6026       </errors>
 6027     </function>
 6028 
 6029     <function id="GetLocalFloat" num="24">
 6030       <synopsis>Get Local Variable - Float</synopsis>
 6031       <description>
 6032         This function can be used to retrieve the value of a local
 6033         variable whose type is <code>float</code>.
 6034       </description>
 6035       <origin>jvmdi</origin>
 6036       <capabilities>
 6037         <required id="can_access_local_variables"></required>
 6038       </capabilities>
 6039       <parameters>
 6040         <param id="thread">
 6041           <jthread null="current" frame="frame" impl="noconvert"/>
 6042           <description>
 6043             The thread of the frame containing the variable's value.
 6044           </description>
 6045         </param>
 6046         <param id="depth">
 6047           <jframeID thread="thread"/>
 6048           <description>
 6049             The depth of the frame containing the variable's value.
 6050           </description>
 6051         </param>
 6052         <param id="slot">
 6053           <jint/>
 6054           <description>
 6055             The variable's slot number.
 6056           </description>
 6057         </param>
 6058         <param id="value_ptr">
 6059           <outptr><jfloat/></outptr>
 6060           <description>
 6061             On return, points to the variable's value.
 6062           </description>
 6063         </param>
 6064       </parameters>
 6065       <errors>
 6066         <error id="JVMTI_ERROR_INVALID_SLOT">
 6067           Invalid <code>slot</code>.
 6068         </error>
 6069         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 6070           The variable type is not <code>float</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="GetLocalDouble" num="25">
 6079       <synopsis>Get Local Variable - Double</synopsis>
 6080       <description>
 6081         This function can be used to retrieve 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" impl="noconvert"/>
 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_ptr">
 6108           <outptr><jdouble/></outptr>
 6109           <description>
 6110             On return, points to the variable's value.
 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>double</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="SetLocalObject" num="26">
 6128       <synopsis>Set Local Variable - Object</synopsis>
 6129       <description>
 6130         This function can be used to set the value of a local
 6131         variable whose type is <code>Object</code> or a subclass of <code>Object</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           <jobject/>
 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
 6169           <code>Object</code> or a subclass of <code>Object</code>.
 6170         </error>
 6171         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 6172           The supplied <paramlink id="value"/> is not compatible
 6173           with the variable type.
 6174         </error>
 6175         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 6176           Not a visible frame
 6177         </error>
 6178       </errors>
 6179     </function>
 6180 
 6181     <function id="SetLocalInt" num="27">
 6182       <synopsis>Set Local Variable - Int</synopsis>
 6183       <description>
 6184         This function can be used to set the value of a local
 6185         variable whose type is <code>int</code>,
 6186         <code>short</code>, <code>char</code>, <code>byte</code>, or
 6187         <code>boolean</code>.
 6188       </description>
 6189       <origin>jvmdi</origin>
 6190       <capabilities>
 6191         <required id="can_access_local_variables"></required>
 6192       </capabilities>
 6193       <parameters>
 6194         <param id="thread">
 6195           <jthread null="current" frame="frame"/>
 6196           <description>
 6197             The thread of the frame containing the variable's value.
 6198           </description>
 6199         </param>
 6200         <param id="depth">
 6201           <jframeID thread="thread"/>
 6202           <description>
 6203             The depth of the frame containing the variable's value.
 6204           </description>
 6205         </param>
 6206         <param id="slot">
 6207           <jint/>
 6208           <description>
 6209             The variable's slot number.
 6210           </description>
 6211         </param>
 6212         <param id="value">
 6213           <jint/>
 6214           <description>
 6215             The new value for the variable.
 6216           </description>
 6217         </param>
 6218       </parameters>
 6219       <errors>
 6220         <error id="JVMTI_ERROR_INVALID_SLOT">
 6221           Invalid <code>slot</code>.
 6222         </error>
 6223         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 6224           The variable type is not
 6225           <code>int</code>, <code>short</code>,
 6226           <code>char</code>, <code>byte</code>, or
 6227           <code>boolean</code>.
 6228         </error>
 6229         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 6230           Not a visible frame
 6231         </error>
 6232       </errors>
 6233     </function>
 6234 
 6235     <function id="SetLocalLong" num="28">
 6236       <synopsis>Set Local Variable - Long</synopsis>
 6237       <description>
 6238         This function can be used to set the value of a local
 6239         variable whose type is <code>long</code>.
 6240       </description>
 6241       <origin>jvmdi</origin>
 6242       <capabilities>
 6243         <required id="can_access_local_variables"></required>
 6244       </capabilities>
 6245       <parameters>
 6246         <param id="thread">
 6247           <jthread null="current" frame="frame"/>
 6248           <description>
 6249             The thread of the frame containing the variable's value.
 6250           </description>
 6251         </param>
 6252         <param id="depth">
 6253           <jframeID thread="thread"/>
 6254           <description>
 6255             The depth of the frame containing the variable's value.
 6256           </description>
 6257         </param>
 6258         <param id="slot">
 6259           <jint/>
 6260           <description>
 6261             The variable's slot number.
 6262           </description>
 6263         </param>
 6264         <param id="value">
 6265           <jlong/>
 6266           <description>
 6267             The new value for the variable.
 6268           </description>
 6269         </param>
 6270       </parameters>
 6271       <errors>
 6272         <error id="JVMTI_ERROR_INVALID_SLOT">
 6273           Invalid <code>slot</code>.
 6274         </error>
 6275         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 6276           The variable type is not <code>long</code>.
 6277         </error>
 6278         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 6279           Not a visible frame
 6280         </error>
 6281       </errors>
 6282     </function>
 6283 
 6284     <function id="SetLocalFloat" num="29">
 6285       <synopsis>Set Local Variable - Float</synopsis>
 6286       <description>
 6287         This function can be used to set the value of a local
 6288         variable whose type is <code>float</code>.
 6289       </description>
 6290       <origin>jvmdi</origin>
 6291       <capabilities>
 6292         <required id="can_access_local_variables"></required>
 6293       </capabilities>
 6294       <parameters>
 6295         <param id="thread">
 6296           <jthread null="current" frame="frame"/>
 6297           <description>
 6298             The thread of the frame containing the variable's value.
 6299           </description>
 6300         </param>
 6301         <param id="depth">
 6302           <jframeID thread="thread"/>
 6303           <description>
 6304             The depth of the frame containing the variable's value.
 6305           </description>
 6306         </param>
 6307         <param id="slot">
 6308           <jint/>
 6309           <description>
 6310             The variable's slot number.
 6311           </description>
 6312         </param>
 6313         <param id="value">
 6314           <jfloat/>
 6315           <description>
 6316             The new value for the variable.
 6317           </description>
 6318         </param>
 6319       </parameters>
 6320       <errors>
 6321         <error id="JVMTI_ERROR_INVALID_SLOT">
 6322           Invalid <code>slot</code>.
 6323         </error>
 6324         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 6325           The variable type is not <code>float</code>.
 6326         </error>
 6327         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 6328           Not a visible frame
 6329         </error>
 6330       </errors>
 6331     </function>
 6332 
 6333     <function id="SetLocalDouble" num="30">
 6334       <synopsis>Set Local Variable - Double</synopsis>
 6335       <description>
 6336         This function can be used to set the value of a local
 6337         variable whose type is <code>double</code>.
 6338       </description>
 6339       <origin>jvmdi</origin>
 6340       <capabilities>
 6341         <required id="can_access_local_variables"></required>
 6342       </capabilities>
 6343       <parameters>
 6344         <param id="thread">
 6345           <jthread null="current" frame="frame"/>
 6346           <description>
 6347             The thread of the frame containing the variable's value.
 6348           </description>
 6349         </param>
 6350         <param id="depth">
 6351           <jframeID thread="thread"/>
 6352           <description>
 6353             The depth of the frame containing the variable's value.
 6354           </description>
 6355         </param>
 6356         <param id="slot">
 6357           <jint/>
 6358           <description>
 6359             The variable's slot number.
 6360           </description>
 6361         </param>
 6362         <param id="value">
 6363           <jdouble/>
 6364           <description>
 6365             The new value for the variable.
 6366           </description>
 6367         </param>
 6368       </parameters>
 6369       <errors>
 6370         <error id="JVMTI_ERROR_INVALID_SLOT">
 6371           Invalid <code>slot</code>.
 6372         </error>
 6373         <error id="JVMTI_ERROR_TYPE_MISMATCH">
 6374           The variable type is not <code>double</code>.
 6375         </error>
 6376         <error id="JVMTI_ERROR_OPAQUE_FRAME">
 6377           Not a visible frame
 6378         </error>
 6379       </errors>
 6380     </function>
 6381   </category>
 6382 
 6383   <category id="breakpointCategory" label="Breakpoint">
 6384 
 6385     <intro>
 6386     </intro>
 6387 
 6388     <function id="SetBreakpoint" num="38">
 6389       <synopsis>Set Breakpoint</synopsis>
 6390       <description>
 6391         Set a breakpoint at the instruction indicated by
 6392         <code>method</code> and <code>location</code>.
 6393         An instruction can only have one breakpoint.
 6394         <p/>
 6395         Whenever the designated instruction is about to be executed, a
 6396         <eventlink id="Breakpoint"></eventlink> event is generated.
 6397       </description>
 6398       <origin>jvmdi</origin>
 6399       <capabilities>
 6400         <required id="can_generate_breakpoint_events"></required>
 6401       </capabilities>
 6402       <parameters>
 6403         <param id="klass">
 6404           <jclass method="method"/>
 6405             <description>
 6406               The class in which to set the breakpoint
 6407             </description>
 6408         </param>
 6409         <param id="method">
 6410           <jmethodID class="klass"/>
 6411             <description>
 6412               The method in which to set the breakpoint
 6413             </description>
 6414         </param>
 6415         <param id="location">
 6416           <jlocation/>
 6417           <description>
 6418             the index of the instruction at which to set the breakpoint
 6419 
 6420           </description>
 6421         </param>
 6422       </parameters>
 6423       <errors>
 6424         <error id="JVMTI_ERROR_DUPLICATE">
 6425           The designated bytecode already has a breakpoint.
 6426         </error>
 6427       </errors>
 6428     </function>
 6429 
 6430     <function id="ClearBreakpoint" num="39">
 6431       <synopsis>Clear Breakpoint</synopsis>
 6432       <description>
 6433         Clear the breakpoint at the bytecode indicated by
 6434         <code>method</code> and <code>location</code>.
 6435       </description>
 6436       <origin>jvmdi</origin>
 6437       <capabilities>
 6438         <required id="can_generate_breakpoint_events"></required>
 6439       </capabilities>
 6440       <parameters>
 6441         <param id="klass">
 6442           <jclass method="method"/>
 6443             <description>
 6444               The class in which to clear the breakpoint
 6445             </description>
 6446         </param>
 6447         <param id="method">
 6448           <jmethodID class="klass"/>
 6449             <description>
 6450               The method in which to clear the breakpoint
 6451             </description>
 6452         </param>
 6453         <param id="location">
 6454           <jlocation/>
 6455           <description>
 6456             the index of the instruction at which to clear the breakpoint
 6457           </description>
 6458         </param>
 6459       </parameters>
 6460       <errors>
 6461         <error id="JVMTI_ERROR_NOT_FOUND">
 6462           There's no breakpoint at the designated bytecode.
 6463         </error>
 6464       </errors>
 6465     </function>
 6466 
 6467   </category>
 6468 
 6469   <category id="fieldWatch" label="Watched Field">
 6470 
 6471     <intro>
 6472     </intro>
 6473 
 6474     <function id="SetFieldAccessWatch" num="41">
 6475       <synopsis>Set Field Access Watch</synopsis>
 6476       <description>
 6477         Generate a <eventlink id="FieldAccess"></eventlink> event
 6478         when the field specified
 6479         by <code>klass</code> and
 6480         <code>field</code> is about to be accessed.
 6481         An event will be generated for each access of the field
 6482         until it is canceled with
 6483         <functionlink id="ClearFieldAccessWatch"></functionlink>.
 6484         Field accesses from Java programming language code or from JNI code are watched,
 6485         fields modified by other means are not watched.
 6486         Note that <jvmti/> users should be aware that their own field accesses
 6487         will trigger the watch.
 6488         A field can only have one field access watch set.
 6489         Modification of a field is not considered an access--use
 6490         <functionlink id="SetFieldModificationWatch"></functionlink>
 6491         to monitor modifications.
 6492       </description>
 6493       <origin>jvmdi</origin>
 6494       <capabilities>
 6495         <required id="can_generate_field_access_events"></required>
 6496       </capabilities>
 6497       <parameters>
 6498         <param id="klass">
 6499           <jclass field="field"/>
 6500             <description>
 6501               The class containing the field to watch
 6502             </description>
 6503         </param>
 6504         <param id="field">
 6505           <jfieldID class="klass"/>
 6506             <description>
 6507               The field to watch
 6508 
 6509             </description>
 6510         </param>
 6511       </parameters>
 6512       <errors>
 6513         <error id="JVMTI_ERROR_DUPLICATE">
 6514           The designated field is already being watched for accesses.
 6515         </error>
 6516       </errors>
 6517     </function>
 6518 
 6519     <function id="ClearFieldAccessWatch" num="42">
 6520       <synopsis>Clear Field Access Watch</synopsis>
 6521       <description>
 6522         Cancel a field access watch previously set by
 6523         <functionlink id="SetFieldAccessWatch"></functionlink>, on the
 6524         field specified
 6525         by <code>klass</code> and
 6526         <code>field</code>.
 6527       </description>
 6528       <origin>jvmdi</origin>
 6529       <capabilities>
 6530         <required id="can_generate_field_access_events"></required>
 6531       </capabilities>
 6532       <parameters>
 6533         <param id="klass">
 6534           <jclass field="field"/>
 6535             <description>
 6536               The class containing the field to watch
 6537             </description>
 6538         </param>
 6539         <param id="field">
 6540           <jfieldID class="klass"/>
 6541             <description>
 6542               The field to watch
 6543 
 6544             </description>
 6545         </param>
 6546       </parameters>
 6547       <errors>
 6548         <error id="JVMTI_ERROR_NOT_FOUND">
 6549           The designated field is not being watched for accesses.
 6550         </error>
 6551       </errors>
 6552     </function>
 6553 
 6554     <function id="SetFieldModificationWatch" num="43">
 6555       <synopsis>Set Field Modification Watch</synopsis>
 6556       <description>
 6557         Generate a <eventlink id="FieldModification"></eventlink> event
 6558         when the field specified
 6559         by <code>klass</code> and
 6560         <code>field</code> is about to be modified.
 6561         An event will be generated for each modification of the field
 6562         until it is canceled with
 6563         <functionlink id="ClearFieldModificationWatch"></functionlink>.
 6564         Field modifications from Java programming language code or from JNI code are watched,
 6565         fields modified by other means are not watched.
 6566         Note that <jvmti/> users should be aware that their own field modifications
 6567         will trigger the watch.
 6568         A field can only have one field modification watch set.
 6569       </description>
 6570       <origin>jvmdi</origin>
 6571       <capabilities>
 6572         <required id="can_generate_field_modification_events"></required>
 6573       </capabilities>
 6574       <parameters>
 6575         <param id="klass">
 6576           <jclass field="field"/>
 6577             <description>
 6578               The class containing the field to watch
 6579             </description>
 6580         </param>
 6581         <param id="field">
 6582           <jfieldID class="klass"/>
 6583             <description>
 6584               The field to watch
 6585 
 6586             </description>
 6587         </param>
 6588       </parameters>
 6589       <errors>
 6590         <error id="JVMTI_ERROR_DUPLICATE">
 6591           The designated field is already being watched for modifications.
 6592         </error>
 6593       </errors>
 6594     </function>
 6595 
 6596     <function id="ClearFieldModificationWatch" num="44">
 6597       <synopsis>Clear Field Modification Watch</synopsis>
 6598       <description>
 6599 
 6600         Cancel a field modification watch previously set by
 6601         <functionlink id="SetFieldModificationWatch"></functionlink>, on the
 6602         field specified
 6603         by <code>klass</code> and
 6604         <code>field</code>.
 6605       </description>
 6606       <origin>jvmdi</origin>
 6607       <capabilities>
 6608         <required id="can_generate_field_modification_events"></required>
 6609       </capabilities>
 6610       <parameters>
 6611         <param id="klass">
 6612           <jclass field="field"/>
 6613             <description>
 6614               The class containing the field to watch
 6615             </description>
 6616         </param>
 6617         <param id="field">
 6618           <jfieldID class="klass"/>
 6619             <description>
 6620               The field to watch
 6621 
 6622             </description>
 6623         </param>
 6624       </parameters>
 6625       <errors>
 6626         <error id="JVMTI_ERROR_NOT_FOUND">
 6627           The designated field is not being watched for modifications.
 6628         </error>
 6629       </errors>
 6630     </function>
 6631   </category>
 6632 
 6633   <category id="module" label="Module">
 6634 
 6635     <intro>
 6636     </intro>
 6637 
 6638     <function id="GetAllModules" num="3" since="9">
 6639       <synopsis>Get All Modules</synopsis>
 6640       <description>
 6641         Return an array of all modules loaded in the virtual machine.
 6642         The array includes the unnamed module for each class loader.
 6643         The number of modules in the array is returned via
 6644         <code>module_count_ptr</code>, and the array itself via
 6645         <code>modules_ptr</code>.
 6646         <p/>
 6647       </description>
 6648       <origin>new</origin>
 6649       <capabilities>
 6650       </capabilities>
 6651       <parameters>
 6652         <param id="module_count_ptr">
 6653           <outptr><jint/></outptr>
 6654           <description>
 6655             On return, points to the number of returned modules.
 6656           </description>
 6657         </param>
 6658         <param id="modules_ptr">
 6659           <allocbuf outcount="module_count_ptr"><jobject/></allocbuf>
 6660             <description>
 6661               On return, points to an array of references, one
 6662               for each module.
 6663             </description>
 6664         </param>
 6665       </parameters>
 6666       <errors>
 6667       </errors>
 6668     </function>
 6669 
 6670     <function id="GetNamedModule" num="40" since="9">
 6671       <synopsis>Get Named Module</synopsis>
 6672       <description>
 6673         Return the <code>java.lang.Module</code> object for a named
 6674         module defined to a class loader that contains a given package.
 6675         The module is returned via <code>module_ptr</code>.
 6676         <p/>
 6677         If a named module is defined to the class loader and it
 6678         contains the package then that named module is returned,
 6679         otherwise <code>NULL</code> is returned.
 6680         <p/>
 6681       </description>
 6682       <origin>new</origin>
 6683       <capabilities>
 6684       </capabilities>
 6685       <parameters>
 6686         <param id="class_loader">
 6687           <ptrtype>
 6688             <jobject/>
 6689             <nullok>the bootstrap loader is assumed</nullok>
 6690           </ptrtype>
 6691           <description>
 6692             A class loader.
 6693             If the <code>class_loader</code> is not <code>NULL</code>
 6694             or a subclass of <code>java.lang.ClassLoader</code>
 6695             this function returns
 6696             <errorlink id="JVMTI_ERROR_ILLEGAL_ARGUMENT"></errorlink>.
 6697           </description>
 6698         </param>
 6699         <param id="package_name">
 6700           <inbuf><char/></inbuf>
 6701           <description>
 6702             The name of the package, encoded as a
 6703             <internallink id="mUTF">modified UTF-8</internallink> string.
 6704             The package name is in internal form (JVMS 4.2.1);
 6705             identifiers are separated by forward slashes rather than periods.
 6706           </description>
 6707         </param>
 6708         <param id="module_ptr">
 6709           <outptr><jobject/></outptr>
 6710           <description>
 6711             On return, points to a <code>java.lang.Module</code> object
 6712             or points to <code>NULL</code>.
 6713           </description>
 6714         </param>
 6715       </parameters>
 6716       <errors>
 6717         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 6718           If class loader is not <code>NULL</code> and is not a class loader object.
 6719         </error>
 6720       </errors>
 6721     </function>
 6722 
 6723     <function id="AddModuleReads" num="94" since="9">
 6724       <synopsis>Add Module Reads</synopsis>
 6725       <description>
 6726          Update a module to read another module. This function is a no-op
 6727          when <paramlink id="module"></paramlink> is an unnamed module.
 6728          This function facilitates the instrumentation of code
 6729          in named modules where that instrumentation requires
 6730          expanding the set of modules that a module reads.
 6731       </description>
 6732       <origin>new</origin>
 6733       <capabilities>
 6734       </capabilities>
 6735       <parameters>
 6736         <param id="module">
 6737           <ptrtype><jobject/></ptrtype>
 6738           <description>
 6739             The module to update.
 6740           </description>
 6741         </param>
 6742         <param id="to_module">
 6743           <ptrtype><jobject/></ptrtype>
 6744           <description>
 6745             The additional module to read.
 6746           </description>
 6747         </param>
 6748       </parameters>
 6749       <errors>
 6750         <error id="JVMTI_ERROR_INVALID_MODULE">
 6751           If <paramlink id="module"></paramlink> is not a module object.
 6752         </error>
 6753         <error id="JVMTI_ERROR_INVALID_MODULE">
 6754           If <paramlink id="to_module"></paramlink> is not a module object.
 6755         </error>
 6756         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
 6757           if the module cannot be modified.
 6758           See <functionlink id="IsModifiableModule"/>.
 6759         </error>
 6760       </errors>
 6761     </function>
 6762 
 6763     <function id="AddModuleExports" num="95" since="9">
 6764       <synopsis>Add Module Exports</synopsis>
 6765       <description>
 6766          Update a module to export a package to another module.
 6767          This function is a no-op when <paramlink id="module"></paramlink>
 6768          is an unnamed module or an open module.
 6769          This function facilitates the instrumentation of code
 6770          in named modules where that instrumentation requires
 6771          expanding the set of packages that a module exports.
 6772       </description>
 6773       <origin>new</origin>
 6774       <capabilities>
 6775       </capabilities>
 6776       <parameters>
 6777         <param id="module">
 6778           <ptrtype><jobject/></ptrtype>
 6779           <description>
 6780             The module to update.
 6781           </description>
 6782         </param>
 6783         <param id="pkg_name">
 6784           <inbuf><char/></inbuf>
 6785           <description>
 6786             The exported package name.
 6787           </description>
 6788         </param>
 6789         <param id="to_module">
 6790           <ptrtype><jobject/></ptrtype>
 6791           <description>
 6792             The module the package is exported to.
 6793             If the <code>to_module</code> is not a subclass of
 6794             <code>java.lang.Module</code> this function returns
 6795             <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
 6796           </description>
 6797         </param>
 6798       </parameters>
 6799       <errors>
 6800         <error id="JVMTI_ERROR_INVALID_MODULE">
 6801           If <paramlink id="module"></paramlink> is not a module object.
 6802         </error>
 6803         <error id="JVMTI_ERROR_INVALID_MODULE">
 6804           If <paramlink id="to_module"></paramlink> is not a module object.
 6805         </error>
 6806         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 6807           If the package <paramlink id="pkg_name"></paramlink>
 6808           does not belong to the module.
 6809         </error>
 6810         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
 6811           if the module cannot be modified.
 6812           See <functionlink id="IsModifiableModule"/>.
 6813         </error>
 6814       </errors>
 6815     </function>
 6816 
 6817     <function id="AddModuleOpens" num="96" since="9">
 6818       <synopsis>Add Module Opens</synopsis>
 6819       <description>
 6820          Update a module to open a package to another module.
 6821          This function is a no-op when <paramlink id="module"></paramlink>
 6822          is an unnamed module or an open module.
 6823          This function facilitates the instrumentation of code
 6824          in modules where that instrumentation requires
 6825          expanding the set of packages that a module opens to
 6826          other modules.
 6827       </description>
 6828       <origin>new</origin>
 6829       <capabilities>
 6830       </capabilities>
 6831       <parameters>
 6832         <param id="module">
 6833           <ptrtype><jobject/></ptrtype>
 6834           <description>
 6835             The module to update.
 6836           </description>
 6837         </param>
 6838         <param id="pkg_name">
 6839           <inbuf><char/></inbuf>
 6840           <description>
 6841             The package name of the package to open.
 6842           </description>
 6843         </param>
 6844         <param id="to_module">
 6845           <ptrtype><jobject/></ptrtype>
 6846           <description>
 6847             The module with the package to open.
 6848             If the <code>to_module</code> is not a subclass of
 6849             <code>java.lang.Module</code> this function returns
 6850             <errorlink id="JVMTI_ERROR_INVALID_MODULE"></errorlink>.
 6851           </description>
 6852         </param>
 6853       </parameters>
 6854       <errors>
 6855         <error id="JVMTI_ERROR_INVALID_MODULE">
 6856           If <paramlink id="module"></paramlink> is not a module object.
 6857         </error>
 6858         <error id="JVMTI_ERROR_INVALID_MODULE">
 6859           If <paramlink id="to_module"></paramlink> is not a module object.
 6860         </error>
 6861         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 6862           If the package <paramlink id="pkg_name"></paramlink>
 6863           does not belong to the module.
 6864         </error>
 6865         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
 6866           if the module cannot be modified.
 6867           See <functionlink id="IsModifiableModule"/>.
 6868         </error>
 6869       </errors>
 6870     </function>
 6871 
 6872     <function id="AddModuleUses" num="97" since="9">
 6873       <synopsis>Add Module Uses</synopsis>
 6874       <description>
 6875          Updates a module to add a service to the set of services that
 6876          a module uses. This function is a no-op when the module
 6877          is an unnamed module.
 6878          This function facilitates the instrumentation of code
 6879          in named modules where that instrumentation requires
 6880          expanding the set of services that a module is using.
 6881       </description>
 6882       <origin>new</origin>
 6883       <capabilities>
 6884       </capabilities>
 6885       <parameters>
 6886         <param id="module">
 6887           <ptrtype><jobject/></ptrtype>
 6888           <description>
 6889             The module to update.
 6890           </description>
 6891         </param>
 6892         <param id="service">
 6893           <ptrtype><jclass/></ptrtype>
 6894           <description>
 6895             The service to use.
 6896           </description>
 6897         </param>
 6898       </parameters>
 6899       <errors>
 6900         <error id="JVMTI_ERROR_INVALID_MODULE">
 6901           If <paramlink id="module"></paramlink> is not a module object.
 6902         </error>
 6903         <error id="JVMTI_ERROR_INVALID_CLASS">
 6904           If <paramlink id="service"></paramlink> is not a class object.
 6905         </error>
 6906         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
 6907           if the module cannot be modified.
 6908           See <functionlink id="IsModifiableModule"/>.
 6909         </error>
 6910       </errors>
 6911     </function>
 6912 
 6913     <function id="AddModuleProvides" num="98" since="9">
 6914       <synopsis>Add Module Provides</synopsis>
 6915       <description>
 6916          Updates a module to add a service to the set of services that
 6917          a module provides. This function is a no-op when the module
 6918          is an unnamed module.
 6919          This function facilitates the instrumentation of code
 6920          in named modules where that instrumentation requires
 6921          changes to the services that are provided.
 6922       </description>
 6923       <origin>new</origin>
 6924       <capabilities>
 6925       </capabilities>
 6926       <parameters>
 6927         <param id="module">
 6928           <ptrtype><jobject/></ptrtype>
 6929           <description>
 6930             The module to update.
 6931           </description>
 6932         </param>
 6933         <param id="service">
 6934           <ptrtype><jclass/></ptrtype>
 6935           <description>
 6936             The service to provide.
 6937           </description>
 6938         </param>
 6939         <param id="impl_class">
 6940           <ptrtype><jclass/></ptrtype>
 6941           <description>
 6942             The implementation class for the provided service.
 6943           </description>
 6944         </param>
 6945       </parameters>
 6946       <errors>
 6947         <error id="JVMTI_ERROR_INVALID_MODULE">
 6948           If <paramlink id="module"></paramlink> is not a module object.
 6949         </error>
 6950         <error id="JVMTI_ERROR_INVALID_CLASS">
 6951           If <paramlink id="service"></paramlink> is not a class object.
 6952         </error>
 6953         <error id="JVMTI_ERROR_INVALID_CLASS">
 6954           If <paramlink id="impl_class"></paramlink> is not a class object.
 6955         </error>
 6956         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
 6957           if the module cannot be modified.
 6958           See <functionlink id="IsModifiableModule"/>.
 6959         </error>
 6960       </errors>
 6961     </function>
 6962 
 6963     <function id="IsModifiableModule" num="99" since="9">
 6964       <synopsis>Is Modifiable Module</synopsis>
 6965       <description>
 6966         Determines whether a module is modifiable.
 6967         If a module is modifiable then this module can be updated with
 6968         <functionlink id="AddModuleReads"/>, <functionlink id="AddModuleExports"/>,
 6969         <functionlink id="AddModuleOpens"/>, <functionlink id="AddModuleUses"/>,
 6970         and <functionlink id="AddModuleProvides"/>. If a module is not modifiable
 6971         then the module can not be updated with these functions. The result of
 6972         this function is always <code>JNI_TRUE</code> when called to determine
 6973         if an unnamed module is modifiable.
 6974       </description>
 6975       <origin>new</origin>
 6976       <capabilities>
 6977       </capabilities>
 6978       <parameters>
 6979         <param id="module">
 6980           <ptrtype><jobject/></ptrtype>
 6981           <description>
 6982             The module to query.
 6983           </description>
 6984         </param>
 6985         <param id="is_modifiable_module_ptr">
 6986           <outptr><jboolean/></outptr>
 6987           <description>
 6988             On return, points to the boolean result of this function.
 6989           </description>
 6990         </param>
 6991       </parameters>
 6992       <errors>
 6993         <error id="JVMTI_ERROR_INVALID_MODULE">
 6994           If <paramlink id="module"></paramlink> is not a module object.
 6995         </error>
 6996       </errors>
 6997     </function>
 6998 
 6999   </category>
 7000 
 7001   <category id="class" label="Class">
 7002     <function id="GetLoadedClasses" jkernel="yes" num="78">
 7003       <synopsis>Get Loaded Classes</synopsis>
 7004       <description>
 7005         Return an array of all classes loaded in the virtual machine.
 7006         The number of classes in the array is returned via
 7007         <code>class_count_ptr</code>, and the array itself via
 7008         <code>classes_ptr</code>.
 7009         <p/>
 7010         A class or interface creation can be triggered by one of the following:
 7011         <ul>
 7012         <li>By loading and deriving a class from a <code>class</code> file representation
 7013             using a class loader (see <vmspec chapter="5.3"/>).</li>
 7014         <li>By invoking <externallink id="../api/java.base/java/lang/invoke/MethodHandles.Lookup.html#defineHiddenClass(byte[],boolean,java.lang.invoke.MethodHandles.Lookup.ClassOption...)">Lookup::defineHiddenClass</externallink>
 7015             that creates a hidden class or interface from a <code>class</code> file representation.</li>
 7016         <li>By invoking methods in certain Java SE Platform APIs such as reflection.</li>
 7017          </ul>
 7018         <p/>
 7019         An array class is created directly by the Java virtual machine.  The creation
 7020         can be triggered by using class loaders or by invoking methods in certain
 7021         Java SE Platform APIs such as reflection.
 7022         <p/>
 7023         The returned list includes all classes and interfaces, including
 7024         <externallink id="../api/java.base/java/lang/Class.html#isHidden()">
 7025         hidden classes or interfaces</externallink>,
 7026         and also array classes of all types
 7027         (including arrays of primitive types).
 7028         Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) are
 7029         <i>not</i> included in the returned list.
 7030       </description>
 7031       <origin>jvmdi</origin>
 7032       <capabilities>
 7033       </capabilities>
 7034       <parameters>
 7035         <param id="class_count_ptr">
 7036           <outptr><jint/></outptr>
 7037           <description>
 7038             On return, points to the number of classes.
 7039           </description>
 7040         </param>
 7041         <param id="classes_ptr">
 7042           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
 7043             <description>
 7044               On return, points to an array of references, one
 7045               for each class.
 7046             </description>
 7047         </param>
 7048       </parameters>
 7049       <errors>
 7050       </errors>
 7051     </function>
 7052 
 7053     <function id="GetClassLoaderClasses" jkernel="yes" num="79">
 7054       <synopsis>Get Classloader Classes</synopsis>
 7055       <description>
 7056         Returns an array of all classes which this class loader
 7057         can find by name via
 7058         <externallink id="../api/java.base/java/lang/ClassLoader.html#loadClass(java.lang.String,boolean)">ClassLoader::loadClass</externallink>,
 7059         <externallink id="../api/java.base/java/lang/Class.html#forName(java.lang.String,boolean,java.lang.ClassLoader)">Class::forName</externallink> and bytecode linkage.
 7060         That is, all classes for which <code>initiating_loader</code>
 7061         has been recorded as an initiating loader.
 7062         Each class in the returned array was created by this class loader,
 7063         either by defining it directly or by delegation to another class loader.
 7064         See <vmspec chapter="5.3"/>.
 7065         <p/>
 7066         The returned list does not include
 7067         <externallink id="../api/java.base/java/lang/Class.html#isHidden()">hidden
 7068         classes or interfaces</externallink> or array classes whose
 7069         element type is a hidden class or interface as they cannot be discovered
 7070         by any class loader.
 7071         <p/>
 7072         The number of classes in the array is returned via
 7073         <code>class_count_ptr</code>, and the array itself via
 7074         <code>classes_ptr</code>.
 7075         <p/>
 7076         See <externallink id="../api/java.base/java/lang/invoke/MethodHandles.Lookup.html#defineHiddenClass(byte[],boolean,java.lang.invoke.MethodHandles.Lookup.ClassOption...)">Lookup::defineHiddenClass</externallink>.
 7077       </description>
 7078       <origin>jvmdi</origin>
 7079       <capabilities>
 7080       </capabilities>
 7081       <parameters>
 7082         <param id="initiating_loader">
 7083           <ptrtype>
 7084             <jobject/>
 7085             <nullok>the classes initiated by the bootstrap loader will be returned</nullok>
 7086           </ptrtype>
 7087             <description>
 7088               An initiating class loader.
 7089             </description>
 7090         </param>
 7091         <param id="class_count_ptr">
 7092           <outptr><jint/></outptr>
 7093           <description>
 7094             On return, points to the number of classes.
 7095           </description>
 7096         </param>
 7097         <param id="classes_ptr">
 7098           <allocbuf outcount="class_count_ptr"><jclass/></allocbuf>
 7099             <description>
 7100               On return, points to an array of references, one
 7101               for each class.
 7102             </description>
 7103         </param>
 7104       </parameters>
 7105       <errors>
 7106       </errors>
 7107     </function>
 7108 
 7109     <function id="GetClassSignature" phase="start" num="48">
 7110       <synopsis>Get Class Signature</synopsis>
 7111       <description>
 7112         Return the name and the generic signature of the class indicated by <code>klass</code>.
 7113         <p/>
 7114         If the class is a class or interface, then:
 7115         <ul>
 7116         <li>If the class or interface is not <externallink id="../api/java.base/java/lang/Class.html#isHidden()">hidden</externallink>,
 7117           then the returned name is the <externallink id="jni/types.html#type-signatures">
 7118           JNI type signature</externallink>.
 7119           For example, java.util.List is "Ljava/util/List;"
 7120         </li>
 7121         <li>If the class or interface is <externallink id="../api/java.base/java/lang/Class.html#isHidden()">hidden</externallink>,
 7122           then the returned name is a string of the form:
 7123           <code>"L" + N + "." +  S + ";"</code>
 7124           where <code>N</code> is the binary name encoded in internal form (JVMS 4.2.1)
 7125           indicated by the <code>class</code> file passed to
 7126           <externallink id="../api/java.base/java/lang/invoke/MethodHandles.Lookup.html#defineHiddenClass(byte[],boolean,java.lang.invoke.MethodHandles.Lookup.ClassOption...)">Lookup::defineHiddenClass</externallink>,
 7127           and <code>S</code> is an unqualified name.
 7128           The returned name is not a type descriptor and does not conform to JVMS 4.3.2.
 7129           For example, com.foo.Foo/AnySuffix is "Lcom/foo/Foo.AnySuffix;"
 7130         </li>
 7131         </ul>
 7132         <p/>
 7133         If the class indicated by <code>klass</code> represents an array class, then
 7134         the returned name is a string consisting of one or more "<code>[</code>" characters
 7135         representing the depth of the array nesting, followed by the class signature
 7136         of the element type.  For example the class signature of java.lang.String[] is
 7137         "[Ljava/lang/String;" and that of int[] is "[I".
 7138         <p/>
 7139         If the class indicated by <code>klass</code> represents primitive type or <code>void</code>,
 7140         then the returned name is the <externallink id="jni/types.html#type-signatures">
 7141         type signature character of the corresponding primitive type</externallink>.
 7142         For example, java.lang.Integer.TYPE is "I".
 7143       </description>
 7144       <origin>jvmdiClone</origin>
 7145       <capabilities>
 7146       </capabilities>
 7147       <parameters>
 7148         <param id="klass">
 7149           <jclass/>
 7150             <description>
 7151               The class to query.
 7152             </description>
 7153         </param>
 7154         <param id="signature_ptr">
 7155           <allocbuf>
 7156             <char/>
 7157             <nullok>the signature is not returned</nullok>
 7158           </allocbuf>
 7159           <description>
 7160             On return, points to the JNI type signature of the class, encoded as a
 7161             <internallink id="mUTF">modified UTF-8</internallink> string.
 7162           </description>
 7163         </param>
 7164         <param id="generic_ptr">
 7165           <allocbuf>
 7166             <char/>
 7167             <nullok>the generic signature is not returned</nullok>
 7168           </allocbuf>
 7169           <description>
 7170             On return, points to the generic signature of the class, encoded as a
 7171             <internallink id="mUTF">modified UTF-8</internallink> string.
 7172             If there is no generic signature attribute for the class, then,
 7173             on return, points to <code>NULL</code>.
 7174           </description>
 7175         </param>
 7176       </parameters>
 7177       <errors>
 7178       </errors>
 7179     </function>
 7180 
 7181     <function id="GetClassStatus" phase="start" num="49">
 7182       <synopsis>Get Class Status</synopsis>
 7183       <description>
 7184         Get the status of the class. Zero or more of the following bits can be
 7185         set.
 7186         <constants id="jvmtiClassStatus" label="Class Status Flags" kind="bits">
 7187           <constant id="JVMTI_CLASS_STATUS_VERIFIED" num="1">
 7188             Class bytecodes have been verified
 7189           </constant>
 7190           <constant id="JVMTI_CLASS_STATUS_PREPARED" num="2">
 7191             Class preparation is complete
 7192           </constant>
 7193           <constant id="JVMTI_CLASS_STATUS_INITIALIZED" num="4">
 7194             Class initialization is complete. Static initializer has been run.
 7195           </constant>
 7196           <constant id="JVMTI_CLASS_STATUS_ERROR" num="8">
 7197             Error during initialization makes class unusable
 7198           </constant>
 7199           <constant id="JVMTI_CLASS_STATUS_ARRAY" num="16">
 7200             Class is an array.  If set, all other bits are zero.
 7201           </constant>
 7202           <constant id="JVMTI_CLASS_STATUS_PRIMITIVE" num="32">
 7203             Class is a primitive class (for example, <code>java.lang.Integer.TYPE</code>).
 7204             If set, all other bits are zero.
 7205           </constant>
 7206         </constants>
 7207       </description>
 7208       <origin>jvmdi</origin>
 7209       <capabilities>
 7210       </capabilities>
 7211       <parameters>
 7212         <param id="klass">
 7213           <jclass/>
 7214             <description>
 7215               The class to query.
 7216             </description>
 7217         </param>
 7218         <param id="status_ptr">
 7219           <outptr><jint/></outptr>
 7220           <description>
 7221             On return, points to the current state of this class as one or
 7222             more of the <internallink id="jvmtiClassStatus">class status flags</internallink>.
 7223           </description>
 7224         </param>
 7225       </parameters>
 7226       <errors>
 7227       </errors>
 7228     </function>
 7229 
 7230     <function id="GetSourceFileName" phase="start" num="50">
 7231       <synopsis>Get Source File Name</synopsis>
 7232       <description>
 7233         For the class indicated by <code>klass</code>, return the source file
 7234         name via <code>source_name_ptr</code>. The returned string
 7235         is a file name only and never contains a directory name.
 7236         <p/>
 7237         For primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
 7238         and for arrays this function returns
 7239         <errorlink id="JVMTI_ERROR_ABSENT_INFORMATION"></errorlink>.
 7240       </description>
 7241       <origin>jvmdi</origin>
 7242       <capabilities>
 7243         <required id="can_get_source_file_name"></required>
 7244       </capabilities>
 7245       <parameters>
 7246         <param id="klass">
 7247           <jclass/>
 7248             <description>
 7249               The class to query.
 7250             </description>
 7251         </param>
 7252         <param id="source_name_ptr">
 7253           <allocbuf><char/></allocbuf>
 7254           <description>
 7255             On return, points to the class's source file name, encoded as a
 7256             <internallink id="mUTF">modified UTF-8</internallink> string.
 7257           </description>
 7258         </param>
 7259       </parameters>
 7260       <errors>
 7261         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
 7262           Class information does not include a source file name. This includes
 7263           cases where the class is an array class or primitive class.
 7264         </error>
 7265       </errors>
 7266     </function>
 7267 
 7268     <function id="GetClassModifiers" phase="start" num="51">
 7269       <synopsis>Get Class Modifiers</synopsis>
 7270       <description>
 7271         For the class indicated by <code>klass</code>, return the access
 7272         flags
 7273         via <code>modifiers_ptr</code>.
 7274         Access flags are defined in <vmspec chapter="4"/>.
 7275         <p/>
 7276         If the class is an array class, then its public, private, and protected
 7277         modifiers are the same as those of its component type. For arrays of
 7278         primitives, this component type is represented by one of the primitive
 7279         classes (for example, <code>java.lang.Integer.TYPE</code>).
 7280         <p/>
 7281         If the class is a primitive class, its public modifier is always true,
 7282         and its protected and private modifiers are always false.
 7283         <p/>
 7284         If the class is an array class or a primitive class then its final
 7285         modifier is always true and its interface modifier is always false.
 7286         The values of its other modifiers are not determined by this specification.
 7287 
 7288       </description>
 7289       <origin>jvmdi</origin>
 7290       <capabilities>
 7291       </capabilities>
 7292       <parameters>
 7293         <param id="klass">
 7294           <jclass/>
 7295             <description>
 7296               The class to query.
 7297             </description>
 7298         </param>
 7299         <param id="modifiers_ptr">
 7300           <outptr><jint/></outptr>
 7301           <description>
 7302             On return, points to the current access flags of this class.
 7303 
 7304           </description>
 7305         </param>
 7306       </parameters>
 7307       <errors>
 7308       </errors>
 7309     </function>
 7310 
 7311     <function id="GetClassMethods" phase="start" num="52">
 7312       <synopsis>Get Class Methods</synopsis>
 7313       <description>
 7314         For the class indicated by <code>klass</code>, return a count of
 7315         methods via <code>method_count_ptr</code> and a list of
 7316         method IDs via <code>methods_ptr</code>. The method list contains
 7317         constructors and static initializers as well as true methods.
 7318         Only directly declared methods are returned (not inherited methods).
 7319         An empty method list is returned for array classes and primitive classes
 7320         (for example, <code>java.lang.Integer.TYPE</code>).
 7321       </description>
 7322       <origin>jvmdi</origin>
 7323       <capabilities>
 7324         <capability id="can_maintain_original_method_order"/>
 7325       </capabilities>
 7326       <parameters>
 7327         <param id="klass">
 7328           <jclass/>
 7329             <description>
 7330               The class to query.
 7331             </description>
 7332         </param>
 7333         <param id="method_count_ptr">
 7334           <outptr><jint/></outptr>
 7335           <description>
 7336             On return, points to the number of methods declared in this class.
 7337           </description>
 7338         </param>
 7339         <param id="methods_ptr">
 7340           <allocbuf outcount="method_count_ptr"><jmethodID class="klass"/></allocbuf>
 7341             <description>
 7342               On return, points to the method ID array.
 7343             </description>
 7344         </param>
 7345       </parameters>
 7346       <errors>
 7347         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
 7348           <paramlink id="klass"></paramlink> is not prepared.
 7349         </error>
 7350       </errors>
 7351     </function>
 7352 
 7353     <function id="GetClassFields" phase="start" num="53">
 7354       <synopsis>Get Class Fields</synopsis>
 7355       <description>
 7356         For the class indicated by <code>klass</code>, return a count of fields
 7357         via <code>field_count_ptr</code> and a list of field IDs via
 7358         <code>fields_ptr</code>.
 7359         Only directly declared fields are returned (not inherited fields).
 7360         Fields are returned in the order they occur in the class file.
 7361         An empty field list is returned for array classes and primitive classes
 7362         (for example, <code>java.lang.Integer.TYPE</code>).
 7363         Use JNI to determine the length of an array.
 7364       </description>
 7365       <origin>jvmdi</origin>
 7366       <capabilities>
 7367       </capabilities>
 7368       <parameters>
 7369         <param id="klass">
 7370           <jclass/>
 7371             <description>
 7372               The class to query.
 7373             </description>
 7374         </param>
 7375         <param id="field_count_ptr">
 7376           <outptr><jint/></outptr>
 7377           <description>
 7378             On return, points to the number of fields declared in this class.
 7379           </description>
 7380         </param>
 7381         <param id="fields_ptr">
 7382           <allocbuf outcount="field_count_ptr"><jfieldID/></allocbuf>
 7383             <description>
 7384               On return, points to the field ID array.
 7385             </description>
 7386         </param>
 7387       </parameters>
 7388       <errors>
 7389         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
 7390           <paramlink id="klass"></paramlink> is not prepared.
 7391         </error>
 7392       </errors>
 7393     </function>
 7394 
 7395     <function id="GetImplementedInterfaces" phase="start" num="54">
 7396       <synopsis>Get Implemented Interfaces</synopsis>
 7397       <description>
 7398         Return the direct super-interfaces of this class. For a class, this
 7399         function returns the interfaces declared in its <code>implements</code>
 7400         clause. For an interface, this function returns the interfaces declared in
 7401         its <code>extends</code> clause.
 7402         An empty interface list is returned for array classes and primitive classes
 7403         (for example, <code>java.lang.Integer.TYPE</code>).
 7404       </description>
 7405       <origin>jvmdi</origin>
 7406       <capabilities>
 7407       </capabilities>
 7408       <parameters>
 7409         <param id="klass">
 7410           <jclass/>
 7411             <description>
 7412               The class to query.
 7413             </description>
 7414         </param>
 7415         <param id="interface_count_ptr">
 7416           <outptr><jint/></outptr>
 7417           <description>
 7418             On return, points to the number of interfaces.
 7419           </description>
 7420         </param>
 7421         <param id="interfaces_ptr">
 7422           <allocbuf outcount="interface_count_ptr"><jclass/></allocbuf>
 7423             <description>
 7424               On return, points to the interface array.
 7425             </description>
 7426         </param>
 7427       </parameters>
 7428       <errors>
 7429         <error id="JVMTI_ERROR_CLASS_NOT_PREPARED">
 7430           <paramlink id="klass"></paramlink> is not prepared.
 7431         </error>
 7432       </errors>
 7433     </function>
 7434 
 7435     <function id="GetClassVersionNumbers" phase="start" num="145" since="1.1">
 7436       <synopsis>Get Class Version Numbers</synopsis>
 7437       <description>
 7438         For the class indicated by <code>klass</code>,
 7439         return the minor and major version numbers,
 7440         as defined in
 7441         <vmspec chapter="4"/>.
 7442       </description>
 7443       <origin>new</origin>
 7444       <capabilities>
 7445       </capabilities>
 7446       <parameters>
 7447         <param id="klass">
 7448           <jclass/>
 7449             <description>
 7450               The class to query.
 7451             </description>
 7452         </param>
 7453         <param id="minor_version_ptr">
 7454           <outptr><jint/></outptr>
 7455           <description>
 7456             On return, points to the value of the
 7457             <code>minor_version</code> item of the
 7458             Class File Format.
 7459             Note: to be consistent with the Class File Format,
 7460             the minor version number is the first parameter.
 7461           </description>
 7462         </param>
 7463         <param id="major_version_ptr">
 7464           <outptr><jint/></outptr>
 7465           <description>
 7466             On return, points to the value of the
 7467             <code>major_version</code> item of the
 7468             Class File Format.
 7469           </description>
 7470         </param>
 7471       </parameters>
 7472       <errors>
 7473         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
 7474           The class is a primitive or array class.
 7475         </error>
 7476       </errors>
 7477     </function>
 7478 
 7479     <function id="GetConstantPool" phase="start" num="146" since="1.1">
 7480       <synopsis>Get Constant Pool</synopsis>
 7481       <description>
 7482         For the class indicated by <code>klass</code>,
 7483         return the raw bytes of the constant pool in the format of the
 7484         <code>constant_pool</code> item of
 7485         <vmspec chapter="4"/>.
 7486         The format of the constant pool may differ between versions
 7487         of the Class File Format, so, the
 7488         <functionlink id="GetClassVersionNumbers">minor and major
 7489         class version numbers</functionlink> should be checked for
 7490         compatibility.
 7491         <p/>
 7492         The returned constant pool might not have the same layout or
 7493         contents as the constant pool in the defining class file.
 7494         The constant pool returned by GetConstantPool() may have
 7495         more or fewer entries than the defining constant pool.
 7496         Entries may be in a different order.
 7497         The constant pool returned by GetConstantPool() will match the
 7498         constant pool used by
 7499         <functionlink id="GetBytecodes">GetBytecodes()</functionlink>.
 7500         That is, the bytecodes returned by GetBytecodes() will have
 7501         constant pool indices which refer to constant pool entries returned
 7502         by GetConstantPool().
 7503         Note that since <functionlink id="RetransformClasses"/>
 7504         and <functionlink id="RedefineClasses"/> can change
 7505         the constant pool, the constant pool returned by this function
 7506         can change accordingly.  Thus, the correspondence between
 7507         GetConstantPool() and GetBytecodes() does not hold if there
 7508         is an intervening class retransformation or redefinition.
 7509         The value of a constant pool entry used by a given bytecode will
 7510         match that of the defining class file (even if the indices don't match).
 7511         Constant pool entries which are not used directly or indirectly by
 7512         bytecodes (for example,  UTF-8 strings associated with annotations) are
 7513         not  required to exist in the returned constant pool.
 7514       </description>
 7515       <origin>new</origin>
 7516       <capabilities>
 7517         <required id="can_get_constant_pool"></required>
 7518       </capabilities>
 7519       <parameters>
 7520         <param id="klass">
 7521           <jclass/>
 7522             <description>
 7523               The class to query.
 7524             </description>
 7525         </param>
 7526         <param id="constant_pool_count_ptr">
 7527           <outptr><jint/></outptr>
 7528           <description>
 7529             On return, points to the number of entries
 7530             in the constant pool table plus one.
 7531             This corresponds to the <code>constant_pool_count</code>
 7532             item of the Class File Format.
 7533           </description>
 7534         </param>
 7535         <param id="constant_pool_byte_count_ptr">
 7536           <outptr><jint/></outptr>
 7537           <description>
 7538             On return, points to the number of bytes
 7539             in the returned raw constant pool.
 7540           </description>
 7541         </param>
 7542         <param id="constant_pool_bytes_ptr">
 7543           <allocbuf outcount="constant_pool_byte_count_ptr"><uchar/></allocbuf>
 7544             <description>
 7545               On return, points to the raw constant pool, that is the bytes
 7546               defined by the <code>constant_pool</code> item of the
 7547               Class File Format
 7548             </description>
 7549         </param>
 7550       </parameters>
 7551       <errors>
 7552         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
 7553           The class is a primitive or array class.
 7554         </error>
 7555       </errors>
 7556     </function>
 7557 
 7558     <function id="IsInterface" phase="start" num="55">
 7559       <synopsis>Is Interface</synopsis>
 7560       <description>
 7561         Determines whether a class object reference represents an interface.
 7562         The <code>jboolean</code> result is
 7563         <code>JNI_TRUE</code> if the "class" is actually an interface,
 7564         <code>JNI_FALSE</code> otherwise.
 7565       </description>
 7566       <origin>jvmdi</origin>
 7567       <capabilities>
 7568       </capabilities>
 7569       <parameters>
 7570         <param id="klass">
 7571           <jclass/>
 7572             <description>
 7573               The class to query.
 7574             </description>
 7575         </param>
 7576         <param id="is_interface_ptr">
 7577           <outptr><jboolean/></outptr>
 7578           <description>
 7579             On return, points to the boolean result of this function.
 7580 
 7581           </description>
 7582         </param>
 7583       </parameters>
 7584       <errors>
 7585       </errors>
 7586     </function>
 7587 
 7588     <function id="IsArrayClass" phase="start" num="56">
 7589       <synopsis>Is Array Class</synopsis>
 7590       <description>
 7591         Determines whether a class object reference represents an array.
 7592         The <code>jboolean</code> result is
 7593         <code>JNI_TRUE</code> if the class is an array,
 7594         <code>JNI_FALSE</code> otherwise.
 7595       </description>
 7596       <origin>jvmdi</origin>
 7597       <capabilities>
 7598       </capabilities>
 7599       <parameters>
 7600         <param id="klass">
 7601           <jclass/>
 7602             <description>
 7603               The class to query.
 7604             </description>
 7605         </param>
 7606         <param id="is_array_class_ptr">
 7607           <outptr><jboolean/></outptr>
 7608           <description>
 7609             On return, points to the boolean result of this function.
 7610 
 7611           </description>
 7612         </param>
 7613       </parameters>
 7614       <errors>
 7615       </errors>
 7616     </function>
 7617 
 7618     <function id="IsModifiableClass" jkernel="yes" phase="start" num="45" since="1.1">
 7619       <synopsis>Is Modifiable Class</synopsis>
 7620       <description>
 7621         Determines whether a class is modifiable.
 7622         If a class is modifiable (<paramlink id="is_modifiable_class_ptr"/>
 7623         returns <code>JNI_TRUE</code>) the class can be
 7624         redefined with <functionlink id="RedefineClasses"/> (assuming
 7625         the agent possesses the
 7626         <fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
 7627         capability) or
 7628         retransformed with <functionlink id="RetransformClasses"/> (assuming
 7629         the agent possesses the
 7630         <fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
 7631         capability).
 7632         If a class is not modifiable (<paramlink id="is_modifiable_class_ptr"/>
 7633         returns <code>JNI_FALSE</code>) the class can be neither
 7634         redefined nor retransformed.
 7635         <p/>
 7636         Primitive classes (for example, <code>java.lang.Integer.TYPE</code>),
 7637         array classes, and some implementation defined classes are never modifiable.
 7638         <p/>
 7639       </description>
 7640       <origin>new</origin>
 7641       <capabilities>
 7642         <capability id="can_redefine_any_class">
 7643           If possessed then all classes (except primitive, array, and some implementation defined
 7644           classes) are modifiable with <functionlink id="RedefineClasses"/>.
 7645         </capability>
 7646         <capability id="can_retransform_any_class">
 7647           If possessed then all classes (except primitive, array, and some implementation defined
 7648           classes) are modifiable with <functionlink id="RetransformClasses"/>.
 7649         </capability>
 7650         <capability id="can_redefine_classes">
 7651           No effect on the result of the function.
 7652           But must additionally be possessed to modify the class with
 7653           <functionlink id="RedefineClasses"/>.
 7654         </capability>
 7655         <capability id="can_retransform_classes">
 7656           No effect on the result of the function.
 7657           But must additionally be possessed to modify the class with
 7658           <functionlink id="RetransformClasses"/>.
 7659         </capability>
 7660       </capabilities>
 7661       <parameters>
 7662         <param id="klass">
 7663           <jclass/>
 7664             <description>
 7665               The class to query.
 7666             </description>
 7667         </param>
 7668         <param id="is_modifiable_class_ptr">
 7669           <outptr><jboolean/></outptr>
 7670           <description>
 7671             On return, points to the boolean result of this function.
 7672           </description>
 7673         </param>
 7674       </parameters>
 7675       <errors>
 7676       </errors>
 7677     </function>
 7678 
 7679     <function id="GetClassLoader" phase="start" num="57">
 7680       <synopsis>Get Class Loader</synopsis>
 7681       <description>
 7682         For the class indicated by <code>klass</code>, return via
 7683         <code>classloader_ptr</code> a reference to the class loader for the
 7684         class.
 7685       </description>
 7686       <origin>jvmdi</origin>
 7687       <capabilities>
 7688       </capabilities>
 7689       <parameters>
 7690         <param id="klass">
 7691           <jclass/>
 7692             <description>
 7693               The class to query.
 7694             </description>
 7695         </param>
 7696         <param id="classloader_ptr">
 7697           <outptr><jobject/></outptr>
 7698             <description>
 7699               On return, points to the class loader that loaded
 7700               this class.
 7701               If the class was not created by a class loader
 7702               or if the class loader is the bootstrap class loader,
 7703               points to <code>NULL</code>.
 7704             </description>
 7705         </param>
 7706       </parameters>
 7707       <errors>
 7708       </errors>
 7709 
 7710     </function>
 7711 
 7712     <function id="GetSourceDebugExtension" phase="start" num="90">
 7713       <synopsis>Get Source Debug Extension</synopsis>
 7714       <description>
 7715         For the class indicated by <code>klass</code>, return the debug
 7716         extension via <code>source_debug_extension_ptr</code>.
 7717         The returned string
 7718         contains exactly the debug extension information present in the
 7719         class file of <code>klass</code>.
 7720       </description>
 7721       <origin>jvmdi</origin>
 7722       <capabilities>
 7723         <required id="can_get_source_debug_extension"></required>
 7724       </capabilities>
 7725       <parameters>
 7726         <param id="klass">
 7727           <jclass/>
 7728             <description>
 7729               The class to query.
 7730             </description>
 7731         </param>
 7732         <param id="source_debug_extension_ptr">
 7733           <allocbuf><char/></allocbuf>
 7734           <description>
 7735             On return, points to the class's debug extension, encoded as a
 7736             <internallink id="mUTF">modified UTF-8</internallink> string.
 7737           </description>
 7738         </param>
 7739       </parameters>
 7740       <errors>
 7741         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
 7742           Class information does not include a debug extension.
 7743         </error>
 7744       </errors>
 7745     </function>
 7746 
 7747     <function id="RetransformClasses" jkernel="yes" num="152" since="1.1">
 7748       <synopsis>Retransform Classes</synopsis>
 7749       <description>
 7750         This function facilitates the
 7751         <internallink id="bci">bytecode instrumentation</internallink>
 7752         of already loaded classes.
 7753         To replace the class definition without reference to the existing
 7754         bytecodes, as one might do when recompiling from source for
 7755         fix-and-continue debugging, <functionlink id="RedefineClasses"/>
 7756         function should be used instead.
 7757         <p/>
 7758         When classes are initially loaded or when they are
 7759         <functionlink id="RedefineClasses">redefined</functionlink>,
 7760         the initial class file bytes can be transformed with the
 7761         <eventlink id="ClassFileLoadHook"/> event.
 7762         This function reruns the transformation process
 7763         (whether or not a transformation has previously occurred).
 7764         This retransformation follows these steps:
 7765         <ul>
 7766           <li>starting from the initial class file bytes
 7767           </li>
 7768           <li>for each <fieldlink id="can_retransform_classes"
 7769                      struct="jvmtiCapabilities">retransformation
 7770                                                 incapable</fieldlink>
 7771             agent which received a
 7772             <code>ClassFileLoadHook</code> event during the previous
 7773             load or redefine, the bytes it returned
 7774             (via the <code>new_class_data</code> parameter)
 7775             are reused as the output of the transformation;
 7776             note that this is equivalent to reapplying
 7777             the previous transformation, unaltered. except that
 7778             the <code>ClassFileLoadHook</code> event
 7779             is <b>not</b> sent to these agents
 7780           </li>
 7781           <li>for each <fieldlink id="can_retransform_classes"
 7782                      struct="jvmtiCapabilities">retransformation
 7783                                                 capable</fieldlink>
 7784             agent, the <code>ClassFileLoadHook</code> event is sent,
 7785             allowing a new transformation to be applied
 7786           </li>
 7787           <li>the transformed class file bytes are installed as the new
 7788             definition of the class
 7789           </li>
 7790         </ul>
 7791         See the <eventlink id="ClassFileLoadHook"/> event for more details.
 7792         <p/>
 7793         The initial class file bytes represent the bytes passed to
 7794         <code>ClassLoader.defineClass</code>
 7795         or <code>RedefineClasses</code> (before any transformations
 7796         were applied), however they may not exactly match them.
 7797         The constant pool may differ in ways described in
 7798         <functionlink id="GetConstantPool"/>.
 7799         Constant pool indices in the bytecodes of methods will correspond.
 7800         Some attributes may not be present.
 7801         Where order is not meaningful, for example the order of methods,
 7802         order may not be preserved.
 7803         <p/>
 7804         Retransformation can cause new versions of methods to be installed.
 7805         Old method versions may become
 7806         <internallink id="obsoleteMethods">obsolete</internallink>
 7807         The new method version will be used on new invokes.
 7808         If a method has active stack frames, those active frames continue to
 7809         run the bytecodes of the original method version.
 7810         <p/>
 7811         This function does not cause any initialization except that which
 7812         would occur under the customary JVM semantics.
 7813         In other words, retransforming a class does not cause its initializers to be
 7814         run. The values of static fields will remain as they were
 7815         prior to the call.
 7816         <p/>
 7817         Threads need not be suspended.
 7818         <p/>
 7819         All breakpoints in the class are cleared.
 7820         <p/>
 7821         All attributes are updated.
 7822         <p/>
 7823         Instances of the retransformed class are not affected -- fields retain their
 7824         previous values.
 7825         <functionlink id="GetTag">Tags</functionlink> on the instances are
 7826         also unaffected.
 7827         <p/>
 7828         In response to this call, no events other than the
 7829         <eventlink id="ClassFileLoadHook"/> event
 7830         will be sent.
 7831         <p/>
 7832         The retransformation may change method bodies, the constant pool and attributes
 7833         (unless explicitly prohibited).
 7834         The retransformation must not add, remove or rename fields or methods, change the
 7835         signatures of methods, change modifiers, or change inheritance.
 7836         The retransformation must not change the <code>NestHost</code>,
 7837         <code>NestMembers</code>, <code>Record</code>, or <code>PermittedSubclasses</code>
 7838         attributes.
 7839         These restrictions may be lifted in future versions.
 7840         See the error return description below for information on error codes
 7841         returned if an unsupported retransformation is attempted.
 7842         The class file bytes are not verified or installed until they have passed
 7843         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
 7844         returned error code reflects the result of the transformations.
 7845         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
 7846         none of the classes to be retransformed will have a new definition installed.
 7847         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
 7848         all of the classes to be retransformed will have their new definitions installed.
 7849       </description>
 7850       <origin>new</origin>
 7851       <capabilities>
 7852         <required id="can_retransform_classes"></required>
 7853         <capability id="can_retransform_any_class"></capability>
 7854       </capabilities>
 7855       <parameters>
 7856         <param id="class_count">
 7857           <jint min="0"/>
 7858           <description>
 7859             The number of classes to be retransformed.
 7860           </description>
 7861         </param>
 7862         <param id="classes">
 7863           <inbuf incount="class_count"><jclass/></inbuf>
 7864           <description>
 7865             The array of classes to be retransformed.
 7866           </description>
 7867         </param>
 7868       </parameters>
 7869       <errors>
 7870         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
 7871           One of the <paramlink id="classes"/> cannot be modified.
 7872           See <functionlink id="IsModifiableClass"/>.
 7873         </error>
 7874         <error id="JVMTI_ERROR_INVALID_CLASS">
 7875           One of the <paramlink id="classes"/> is not a valid class.
 7876         </error>
 7877         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
 7878           A retransformed class file has a version number not supported by this VM.
 7879         </error>
 7880         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
 7881           A retransformed class file is malformed (The VM would return a <code>ClassFormatError</code>).
 7882         </error>
 7883         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
 7884           The retransformed class file definitions would lead to a circular definition
 7885           (the VM would return a <code>ClassCircularityError</code>).
 7886         </error>
 7887         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
 7888           The retransformed class file bytes fail verification.
 7889         </error>
 7890         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
 7891           The class name defined in a retransformed class file is
 7892           different from the name in the old class object.
 7893         </error>
 7894         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
 7895           A retransformed class file would require adding a method.
 7896         </error>
 7897         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
 7898           A retransformed class file changes a field.
 7899         </error>
 7900         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
 7901           A direct superclass is different for a retransformed class file,
 7902           or the set of directly implemented
 7903           interfaces is different.
 7904         </error>
 7905         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
 7906           A retransformed class file does not declare a method
 7907           declared in the old class version.
 7908         </error>
 7909         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED">
 7910           A retransformed class file has unsupported differences in class attributes.
 7911         </error>
 7912         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
 7913           A retransformed class file has different class modifiers.
 7914         </error>
 7915         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
 7916           A method in the retransformed class file has different modifiers
 7917           than its counterpart in the old class version.
 7918         </error>
 7919       </errors>
 7920     </function>
 7921 
 7922     <function id="RedefineClasses" jkernel="yes" num="87">
 7923       <synopsis>Redefine Classes</synopsis>
 7924       <typedef id="jvmtiClassDefinition" label="Class redefinition description">
 7925         <field id="klass">
 7926           <jclass/>
 7927             <description>
 7928               Class object for this class
 7929             </description>
 7930         </field>
 7931         <field id="class_byte_count">
 7932           <jint/>
 7933           <description>
 7934             Number of bytes defining class (below)
 7935           </description>
 7936         </field>
 7937         <field id="class_bytes">
 7938           <inbuf incount="class_byte_count"><uchar/></inbuf>
 7939           <description>
 7940             Bytes defining class (in <vmspec chapter="4"/>)
 7941           </description>
 7942         </field>
 7943       </typedef>
 7944       <description>
 7945         All classes given are redefined according to the definitions
 7946         supplied.
 7947         This function is used to replace the definition of a class
 7948         with a new definition, as might be needed in fix-and-continue
 7949         debugging.
 7950         Where the existing class file bytes are to be transformed, for
 7951         example in
 7952         <internallink id="bci">bytecode instrumentation</internallink>,
 7953         <functionlink id="RetransformClasses"/> should be used.
 7954         <p/>
 7955         Redefinition can cause new versions of methods to be installed.
 7956         Old method versions may become
 7957         <internallink id="obsoleteMethods">obsolete</internallink>
 7958         The new method version will be used on new invokes.
 7959         If a method has active stack frames, those active frames continue to
 7960         run the bytecodes of the original method version.
 7961         If resetting of stack frames is desired, use
 7962         <functionlink id="PopFrame"></functionlink>
 7963         to pop frames with obsolete method versions.
 7964         <p/>
 7965         This function does not cause any initialization except that which
 7966         would occur under the customary JVM semantics.
 7967         In other words, redefining a class does not cause its initializers to be
 7968         run. The values of static fields will remain as they were
 7969         prior to the call.
 7970         <p/>
 7971         Threads need not be suspended.
 7972         <p/>
 7973         All breakpoints in the class are cleared.
 7974         <p/>
 7975         All attributes are updated.
 7976         <p/>
 7977         Instances of the redefined class are not affected -- fields retain their
 7978         previous values.
 7979         <functionlink id="GetTag">Tags</functionlink> on the instances are
 7980         also unaffected.
 7981         <p/>
 7982         In response to this call, the <jvmti/> event
 7983         <eventlink id="ClassFileLoadHook">Class File Load Hook</eventlink>
 7984         will be sent (if enabled), but no other <jvmti/> events will be sent.
 7985         <p/>
 7986         The redefinition may change method bodies, the constant pool and attributes
 7987         (unless explicitly prohibited).
 7988         The redefinition must not add, remove or rename fields or methods, change the
 7989         signatures of methods, change modifiers, or change inheritance.
 7990         The redefinition must not change the <code>NestHost</code>,
 7991         <code>NestMembers</code>, <code>Record</code>, or <code>PermittedSubclasses</code>
 7992         attributes.
 7993         These restrictions may be lifted in future versions.
 7994         See the error return description below for information on error codes
 7995         returned if an unsupported redefinition is attempted.
 7996         The class file bytes are not verified or installed until they have passed
 7997         through the chain of <eventlink id="ClassFileLoadHook"/> events, thus the
 7998         returned error code reflects the result of the transformations applied
 7999         to the bytes passed into <paramlink id="class_definitions"/>.
 8000         If any error code is returned other than <code>JVMTI_ERROR_NONE</code>,
 8001         none of the classes to be redefined will have a new definition installed.
 8002         When this function returns (with the error code of <code>JVMTI_ERROR_NONE</code>)
 8003         all of the classes to be redefined will have their new definitions installed.
 8004       </description>
 8005       <origin>jvmdi</origin>
 8006       <capabilities>
 8007         <required id="can_redefine_classes"></required>
 8008         <capability id="can_redefine_any_class"></capability>
 8009       </capabilities>
 8010       <parameters>
 8011         <param id="class_count">
 8012           <jint min="0"/>
 8013           <description>
 8014             The number of classes specified in <code>class_definitions</code>
 8015           </description>
 8016         </param>
 8017         <param id="class_definitions">
 8018           <inbuf incount="class_count"><struct>jvmtiClassDefinition</struct></inbuf>
 8019           <description>
 8020             The array of new class definitions
 8021           </description>
 8022         </param>
 8023       </parameters>
 8024       <errors>
 8025         <error id="JVMTI_ERROR_NULL_POINTER">
 8026           One of <code>class_bytes</code> is <code>NULL</code>.
 8027         </error>
 8028         <error id="JVMTI_ERROR_UNMODIFIABLE_CLASS">
 8029           An element of <code>class_definitions</code> cannot be modified.
 8030           See <functionlink id="IsModifiableClass"/>.
 8031         </error>
 8032         <error id="JVMTI_ERROR_INVALID_CLASS">
 8033           An element of <code>class_definitions</code> is not a valid class.
 8034         </error>
 8035         <error id="JVMTI_ERROR_UNSUPPORTED_VERSION">
 8036           A new class file has a version number not supported by this VM.
 8037         </error>
 8038         <error id="JVMTI_ERROR_INVALID_CLASS_FORMAT">
 8039           A new class file is malformed (The VM would return a <code>ClassFormatError</code>).
 8040         </error>
 8041         <error id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION">
 8042           The new class file definitions would lead to a circular definition
 8043           (the VM would return a <code>ClassCircularityError</code>).
 8044         </error>
 8045         <error id="JVMTI_ERROR_FAILS_VERIFICATION">
 8046           The class bytes fail verification.
 8047         </error>
 8048         <error id="JVMTI_ERROR_NAMES_DONT_MATCH">
 8049           The class name defined in a new class file is
 8050           different from the name in the old class object.
 8051         </error>
 8052         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED">
 8053           A new class file would require adding a method.
 8054         </error>
 8055         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED">
 8056           A new class version changes a field.
 8057         </error>
 8058         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED">
 8059           A direct superclass is different for a new class
 8060           version, or the set of directly implemented
 8061           interfaces is different.
 8062         </error>
 8063         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED">
 8064           A new class version does not declare a method
 8065           declared in the old class version.
 8066         </error>
 8067         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED">
 8068           A new class version has unsupported differences in class attributes.
 8069         </error>
 8070         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED">
 8071           A new class version has different modifiers.
 8072         </error>
 8073         <error id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED">
 8074           A method in the new class version has different modifiers
 8075           than its counterpart in the old class version.
 8076         </error>
 8077         <error id="JVMTI_ERROR_UNMODIFIABLE_MODULE">
 8078           A module cannot be modified.
 8079           See <functionlink id="IsModifiableModule"/>.
 8080         </error>
 8081       </errors>
 8082     </function>
 8083 
 8084   </category>
 8085 
 8086   <category id="object" label="Object">
 8087 
 8088     <function id="GetObjectSize" jkernel="yes" phase="start" num="154">
 8089       <synopsis>Get Object Size</synopsis>
 8090       <description>
 8091         For the object indicated by <code>object</code>,
 8092         return via <code>size_ptr</code> the size of the object.
 8093         This size is an implementation-specific approximation of
 8094         the amount of storage consumed by this object.
 8095         It may include some or all of the object's overhead, and thus
 8096         is useful for comparison within an implementation but not
 8097         between implementations.
 8098         The estimate may change during a single invocation of the JVM.
 8099       </description>
 8100       <origin>new</origin>
 8101       <capabilities>
 8102       </capabilities>
 8103       <parameters>
 8104         <param id="object">
 8105           <jobject/>
 8106             <description>
 8107               The object to query.
 8108             </description>
 8109         </param>
 8110         <param id="size_ptr">
 8111           <outptr><jlong/></outptr>
 8112           <description>
 8113             On return, points to the object's size in bytes.
 8114           </description>
 8115         </param>
 8116       </parameters>
 8117       <errors>
 8118       </errors>
 8119     </function>
 8120 
 8121     <function id="GetObjectHashCode" phase="start" num="58">
 8122       <synopsis>Get Object Hash Code</synopsis>
 8123       <description>
 8124         For the object indicated by <code>object</code>,
 8125         return via <code>hash_code_ptr</code> a hash code.
 8126         This hash code could be used to maintain a hash table of object references,
 8127         however, on some implementations this can cause significant performance
 8128         impacts--in most cases
 8129         <internallink id="Heap">tags</internallink>
 8130         will be a more efficient means of associating information with objects.
 8131         This function guarantees
 8132         the same hash code value for a particular object throughout its life
 8133       </description>
 8134       <origin>jvmdi</origin>
 8135       <capabilities>
 8136       </capabilities>
 8137       <parameters>
 8138         <param id="object">
 8139           <jobject/>
 8140             <description>
 8141               The object to query.
 8142             </description>
 8143         </param>
 8144         <param id="hash_code_ptr">
 8145           <outptr><jint/></outptr>
 8146           <description>
 8147             On return, points to the object's hash code.
 8148           </description>
 8149         </param>
 8150       </parameters>
 8151       <errors>
 8152       </errors>
 8153     </function>
 8154 
 8155     <function id="GetObjectMonitorUsage" num="59">
 8156       <synopsis>Get Object Monitor Usage</synopsis>
 8157       <typedef id="jvmtiMonitorUsage" label="Object monitor usage information">
 8158         <field id="owner">
 8159           <jthread/>
 8160             <description>
 8161               The thread owning this monitor, or <code>NULL</code> if unused
 8162             </description>
 8163         </field>
 8164         <field id="entry_count">
 8165           <jint/>
 8166           <description>
 8167             The number of times the owning thread has entered the monitor
 8168           </description>
 8169         </field>
 8170         <field id="waiter_count">
 8171           <jint/>
 8172           <description>
 8173             The number of threads waiting to own this monitor
 8174           </description>
 8175         </field>
 8176         <field id="waiters">
 8177           <allocfieldbuf><jthread/></allocfieldbuf>
 8178             <description>
 8179               The <code>waiter_count</code> waiting threads
 8180             </description>
 8181         </field>
 8182         <field id="notify_waiter_count">
 8183           <jint/>
 8184           <description>
 8185             The number of threads waiting to be notified by this monitor
 8186           </description>
 8187         </field>
 8188         <field id="notify_waiters">
 8189           <allocfieldbuf><jthread/></allocfieldbuf>
 8190             <description>
 8191               The <code>notify_waiter_count</code> threads waiting to be notified
 8192             </description>
 8193         </field>
 8194       </typedef>
 8195       <description>
 8196         Get information about the object's monitor.
 8197         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
 8198         are filled in with information about usage of the monitor.
 8199           <todo>
 8200             Decide and then clarify suspend requirements.
 8201           </todo>
 8202       </description>
 8203       <origin>jvmdi</origin>
 8204       <capabilities>
 8205         <required id="can_get_monitor_info"></required>
 8206       </capabilities>
 8207       <parameters>
 8208         <param id="object">
 8209           <jobject/>
 8210             <description>
 8211               The object to query.
 8212             </description>
 8213         </param>
 8214         <param id="info_ptr">
 8215           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
 8216           <description>
 8217             On return, filled with monitor information for the
 8218             specified object.
 8219           </description>
 8220         </param>
 8221       </parameters>
 8222       <errors>
 8223       </errors>
 8224     </function>
 8225 
 8226     <elide>
 8227     <function id="GetObjectMonitors" num="116">
 8228       <synopsis>Get Object Monitors</synopsis>
 8229       <description>
 8230         Return the list of object monitors.
 8231         <p/>
 8232         Note: details about each monitor can be examined with
 8233         <functionlink id="GetObjectMonitorUsage"></functionlink>.
 8234       </description>
 8235       <origin>new</origin>
 8236       <capabilities>
 8237         <required id="can_get_monitor_info"></required>
 8238       </capabilities>
 8239       <parameters>
 8240         <param id="monitorCnt">
 8241           <outptr><jint/></outptr>
 8242           <description>
 8243             On return, pointer to the number
 8244             of monitors returned in <code>monitors_ptr</code>.
 8245           </description>
 8246         </param>
 8247         <param id="monitors_ptr">
 8248           <allocbuf outcount="monitorCnt"><jobject/></allocbuf>
 8249             <description>
 8250               On return, pointer to the monitor list.
 8251             </description>
 8252         </param>
 8253       </parameters>
 8254       <errors>
 8255       </errors>
 8256     </function>
 8257     </elide>
 8258 
 8259   </category>
 8260 
 8261   <category id="fieldCategory" label="Field">
 8262 
 8263     <intro>
 8264     </intro>
 8265 
 8266     <function id="GetFieldName" phase="start" num="60">
 8267       <synopsis>Get Field Name (and Signature)</synopsis>
 8268       <description>
 8269         For the field indicated by <paramlink id="klass"/> and <paramlink id="field"/>,
 8270         return the field name via <paramlink id="name_ptr"/> and field signature via
 8271         <paramlink id="signature_ptr"/>.
 8272         <p/>
 8273         Field signatures are defined in the
 8274         <externallink id="jni/index.html">JNI Specification</externallink>
 8275         and are referred to as <code>field descriptors</code> in
 8276         <vmspec chapter="4.3.2"/>.
 8277       </description>
 8278       <origin>jvmdiClone</origin>
 8279       <capabilities>
 8280       </capabilities>
 8281       <parameters>
 8282         <param id="klass">
 8283           <jclass field="field"/>
 8284             <description>
 8285               The class of the field to query.
 8286             </description>
 8287         </param>
 8288         <param id="field">
 8289           <jfieldID class="klass"/>
 8290             <description>
 8291               The field to query.
 8292             </description>
 8293         </param>
 8294         <param id="name_ptr">
 8295           <allocbuf>
 8296             <char/>
 8297             <nullok>the name is not returned</nullok>
 8298           </allocbuf>
 8299           <description>
 8300             On return, points to the field name, encoded as a
 8301             <internallink id="mUTF">modified UTF-8</internallink> string.
 8302           </description>
 8303         </param>
 8304         <param id="signature_ptr">
 8305           <allocbuf>
 8306             <char/>
 8307             <nullok>the signature is not returned</nullok>
 8308           </allocbuf>
 8309           <description>
 8310             On return, points to the field signature, encoded as a
 8311             <internallink id="mUTF">modified UTF-8</internallink> string.
 8312           </description>
 8313         </param>
 8314         <param id="generic_ptr">
 8315           <allocbuf>
 8316             <char/>
 8317             <nullok>the generic signature is not returned</nullok>
 8318           </allocbuf>
 8319           <description>
 8320             On return, points to the generic signature of the field, encoded as a
 8321             <internallink id="mUTF">modified UTF-8</internallink> string.
 8322             If there is no generic signature attribute for the field, then,
 8323             on return, points to <code>NULL</code>.
 8324           </description>
 8325         </param>
 8326       </parameters>
 8327       <errors>
 8328       </errors>
 8329     </function>
 8330 
 8331     <function id="GetFieldDeclaringClass" phase="start" num="61">
 8332       <synopsis>Get Field Declaring Class</synopsis>
 8333       <description>
 8334         For the field indicated by <code>klass</code> and <code>field</code>
 8335         return the class that defined it via <code>declaring_class_ptr</code>.
 8336         The declaring class will either be <code>klass</code>, a superclass, or
 8337         an implemented interface.
 8338       </description>
 8339       <origin>jvmdi</origin>
 8340       <capabilities>
 8341       </capabilities>
 8342       <parameters>
 8343         <param id="klass">
 8344           <jclass field="field"/>
 8345             <description>
 8346               The class to query.
 8347             </description>
 8348         </param>
 8349         <param id="field">
 8350           <jfieldID class="klass"/>
 8351             <description>
 8352               The field to query.
 8353             </description>
 8354         </param>
 8355         <param id="declaring_class_ptr">
 8356           <outptr><jclass/></outptr>
 8357             <description>
 8358               On return, points to the declaring class
 8359             </description>
 8360         </param>
 8361       </parameters>
 8362       <errors>
 8363       </errors>
 8364     </function>
 8365 
 8366     <function id="GetFieldModifiers" phase="start" num="62">
 8367       <synopsis>Get Field Modifiers</synopsis>
 8368       <description>
 8369         For the field indicated by <code>klass</code> and <code>field</code>
 8370         return the access flags via <code>modifiers_ptr</code>.
 8371         Access flags are defined in <vmspec chapter="4"/>.
 8372       </description>
 8373       <origin>jvmdi</origin>
 8374       <capabilities>
 8375       </capabilities>
 8376       <parameters>
 8377         <param id="klass">
 8378           <jclass field="field"/>
 8379             <description>
 8380               The class to query.
 8381             </description>
 8382         </param>
 8383         <param id="field">
 8384           <jfieldID class="klass"/>
 8385             <description>
 8386               The field to query.
 8387             </description>
 8388         </param>
 8389         <param id="modifiers_ptr">
 8390           <outptr><jint/></outptr>
 8391           <description>
 8392             On return, points to the access flags.
 8393           </description>
 8394         </param>
 8395       </parameters>
 8396       <errors>
 8397       </errors>
 8398     </function>
 8399 
 8400     <function id="IsFieldSynthetic" phase="start" num="63">
 8401       <synopsis>Is Field Synthetic</synopsis>
 8402       <description>
 8403         For the field indicated by <code>klass</code> and <code>field</code>, return a
 8404         value indicating whether the field is synthetic via <code>is_synthetic_ptr</code>.
 8405         Synthetic fields are generated by the compiler but not present in the
 8406         original source code.
 8407       </description>
 8408       <origin>jvmdi</origin>
 8409       <capabilities>
 8410         <required id="can_get_synthetic_attribute"></required>
 8411       </capabilities>
 8412       <parameters>
 8413         <param id="klass">
 8414           <jclass field="field"/>
 8415             <description>
 8416               The class of the field to query.
 8417             </description>
 8418         </param>
 8419         <param id="field">
 8420           <jfieldID class="klass"/>
 8421             <description>
 8422               The field to query.
 8423             </description>
 8424         </param>
 8425         <param id="is_synthetic_ptr">
 8426           <outptr><jboolean/></outptr>
 8427           <description>
 8428             On return, points to the boolean result of this function.
 8429           </description>
 8430         </param>
 8431       </parameters>
 8432       <errors>
 8433       </errors>
 8434     </function>
 8435 
 8436   </category>
 8437 
 8438   <category id="method" label="Method">
 8439 
 8440     <intro>
 8441       These functions provide information about a method (represented as a
 8442       <typelink id="jmethodID"/>) and set how methods are processed.
 8443     </intro>
 8444 
 8445     <intro id="obsoleteMethods" label="Obsolete Methods">
 8446       The functions <functionlink id="RetransformClasses"/> and
 8447       <functionlink id="RedefineClasses"/> can cause new versions
 8448       of methods to be installed.
 8449       An original version of a method is considered equivalent
 8450       to the new version if:
 8451       <ul>
 8452         <li>their bytecodes are the same except for indices into the
 8453           constant pool and </li>
 8454         <li>the referenced constants are equal.</li>
 8455       </ul>
 8456       An original method version which is not equivalent to the
 8457       new method version is called obsolete and is assigned a new method ID;
 8458       the original method ID now refers to the new method version.
 8459       A method ID can be tested for obsolescence with
 8460       <functionlink id="IsMethodObsolete"/>.
 8461     </intro>
 8462 
 8463     <function id="GetMethodName" phase="start" num="64">
 8464       <synopsis>Get Method Name (and Signature)</synopsis>
 8465       <description>
 8466         For the method indicated by <code>method</code>,
 8467         return the method name via <code>name_ptr</code> and method signature via
 8468         <code>signature_ptr</code>.
 8469         <p/>
 8470         Method signatures are defined in the
 8471         <externallink id="jni/index.html">JNI Specification</externallink>
 8472         and are referred to as <code>method descriptors</code> in
 8473         <vmspec chapter="4.3.3"/>.
 8474         Note this is different
 8475         than method signatures as defined in the <i>Java Language Specification</i>.
 8476       </description>
 8477       <origin>jvmdiClone</origin>
 8478       <capabilities>
 8479       </capabilities>
 8480       <parameters>
 8481         <param id="method">
 8482           <jmethodID/>
 8483             <description>
 8484               The method to query.
 8485             </description>
 8486         </param>
 8487         <param id="name_ptr">
 8488           <allocbuf>
 8489             <char/>
 8490             <nullok>the name is not returned</nullok>
 8491           </allocbuf>
 8492           <description>
 8493             On return, points to the method name, encoded as a
 8494             <internallink id="mUTF">modified UTF-8</internallink> string.
 8495           </description>
 8496         </param>
 8497         <param id="signature_ptr">
 8498           <allocbuf>
 8499             <char/>
 8500             <nullok>the signature is not returned</nullok>
 8501           </allocbuf>
 8502           <description>
 8503             On return, points to the method signature, encoded as a
 8504             <internallink id="mUTF">modified UTF-8</internallink> string.
 8505           </description>
 8506         </param>
 8507         <param id="generic_ptr">
 8508           <allocbuf>
 8509             <char/>
 8510             <nullok>the generic signature is not returned</nullok>
 8511           </allocbuf>
 8512           <description>
 8513             On return, points to the generic signature of the method, encoded as a
 8514             <internallink id="mUTF">modified UTF-8</internallink> string.
 8515             If there is no generic signature attribute for the method, then,
 8516             on return, points to <code>NULL</code>.
 8517           </description>
 8518         </param>
 8519       </parameters>
 8520       <errors>
 8521       </errors>
 8522     </function>
 8523 
 8524     <function id="GetMethodDeclaringClass" phase="start" num="65">
 8525       <synopsis>Get Method Declaring Class</synopsis>
 8526       <description>
 8527         For the method indicated by <code>method</code>,
 8528         return the class that defined it via <code>declaring_class_ptr</code>.
 8529       </description>
 8530       <origin>jvmdi</origin>
 8531       <capabilities>
 8532       </capabilities>
 8533       <parameters>
 8534         <param id="klass">
 8535           <jclass method="method"/>
 8536             <description>
 8537               The class to query.
 8538             </description>
 8539         </param>
 8540         <param id="method">
 8541           <jmethodID class="klass"/>
 8542             <description>
 8543               The method to query.
 8544             </description>
 8545         </param>
 8546         <param id="declaring_class_ptr">
 8547           <outptr><jclass/></outptr>
 8548             <description>
 8549               On return, points to the declaring class
 8550             </description>
 8551         </param>
 8552       </parameters>
 8553       <errors>
 8554       </errors>
 8555     </function>
 8556 
 8557     <function id="GetMethodModifiers" phase="start" num="66">
 8558       <synopsis>Get Method Modifiers</synopsis>
 8559       <description>
 8560         For the method indicated by <code>method</code>,
 8561         return the access flags via <code>modifiers_ptr</code>.
 8562         Access flags are defined in <vmspec chapter="4"/>.
 8563       </description>
 8564       <origin>jvmdi</origin>
 8565       <capabilities>
 8566       </capabilities>
 8567       <parameters>
 8568         <param id="klass">
 8569           <jclass method="method"/>
 8570             <description>
 8571               The class to query.
 8572             </description>
 8573         </param>
 8574         <param id="method">
 8575           <jmethodID class="klass"/>
 8576             <description>
 8577               The method to query.
 8578             </description>
 8579         </param>
 8580         <param id="modifiers_ptr">
 8581           <outptr><jint/></outptr>
 8582           <description>
 8583             On return, points to the access flags.
 8584           </description>
 8585         </param>
 8586       </parameters>
 8587       <errors>
 8588       </errors>
 8589     </function>
 8590 
 8591     <function id="GetMaxLocals" phase="start" num="68">
 8592       <synopsis>Get Max Locals</synopsis>
 8593       <description>
 8594           For the method indicated by <code>method</code>,
 8595           return the number of local variable slots used by the method,
 8596           including the local variables used to pass parameters to the
 8597           method on its invocation.
 8598           <p/>
 8599           See <code>max_locals</code> in <vmspec chapter="4.7.3"/>.
 8600       </description>
 8601       <origin>jvmdi</origin>
 8602       <capabilities>
 8603       </capabilities>
 8604       <parameters>
 8605         <param id="klass">
 8606           <jclass method="method"/>
 8607             <description>
 8608               The class to query.
 8609             </description>
 8610         </param>
 8611         <param id="method">
 8612           <jmethodID class="klass" native="error"/>
 8613             <description>
 8614               The method to query.
 8615             </description>
 8616         </param>
 8617         <param id="max_ptr">
 8618           <outptr><jint/></outptr>
 8619           <description>
 8620             On return, points to the maximum number of local slots
 8621           </description>
 8622         </param>
 8623       </parameters>
 8624       <errors>
 8625       </errors>
 8626     </function>
 8627 
 8628     <function id="GetArgumentsSize" phase="start" num="69">
 8629       <synopsis>Get Arguments Size</synopsis>
 8630       <description>
 8631         For the method indicated by <code>method</code>,
 8632         return via <code>max_ptr</code> the number of local variable slots used
 8633         by the method's arguments.
 8634         Note that two-word arguments use two slots.
 8635       </description>
 8636       <origin>jvmdi</origin>
 8637       <capabilities>
 8638       </capabilities>
 8639       <parameters>
 8640         <param id="klass">
 8641           <jclass method="method"/>
 8642             <description>
 8643               The class to query.
 8644             </description>
 8645         </param>
 8646         <param id="method">
 8647           <jmethodID class="klass" native="error"/>
 8648             <description>
 8649               The method to query.
 8650             </description>
 8651         </param>
 8652         <param id="size_ptr">
 8653           <outptr><jint/></outptr>
 8654           <description>
 8655             On return, points to the number of argument slots
 8656           </description>
 8657         </param>
 8658       </parameters>
 8659       <errors>
 8660       </errors>
 8661     </function>
 8662 
 8663     <function id="GetLineNumberTable" phase="start" num="70">
 8664       <synopsis>Get Line Number Table</synopsis>
 8665       <typedef id="jvmtiLineNumberEntry" label="Line number table entry">
 8666         <field id="start_location">
 8667           <jlocation/>
 8668           <description>
 8669             the <datalink id="jlocation"></datalink> where the line begins
 8670           </description>
 8671         </field>
 8672         <field id="line_number">
 8673           <jint/>
 8674           <description>
 8675             the line number
 8676           </description>
 8677         </field>
 8678       </typedef>
 8679       <description>
 8680         For the method indicated by <code>method</code>,
 8681         return a table of source line number entries. The size of the table is
 8682         returned via <code>entry_count_ptr</code> and the table itself is
 8683         returned via <code>table_ptr</code>.
 8684       </description>
 8685       <origin>jvmdi</origin>
 8686       <capabilities>
 8687         <required id="can_get_line_numbers"></required>
 8688       </capabilities>
 8689       <parameters>
 8690         <param id="klass">
 8691           <jclass method="method"/>
 8692             <description>
 8693               The class to query.
 8694             </description>
 8695         </param>
 8696         <param id="method">
 8697           <jmethodID class="klass" native="error"/>
 8698             <description>
 8699               The method to query.
 8700             </description>
 8701         </param>
 8702         <param id="entry_count_ptr">
 8703           <outptr><jint/></outptr>
 8704           <description>
 8705             On return, points to the number of entries in the table
 8706           </description>
 8707         </param>
 8708         <param id="table_ptr">
 8709           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLineNumberEntry</struct></allocbuf>
 8710           <description>
 8711             On return, points to the line number table pointer.
 8712           </description>
 8713         </param>
 8714       </parameters>
 8715       <errors>
 8716         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
 8717           Class information does not include line numbers.
 8718         </error>
 8719       </errors>
 8720     </function>
 8721 
 8722     <function id="GetMethodLocation" phase="start" num="71">
 8723       <synopsis>Get Method Location</synopsis>
 8724       <description>
 8725         For the method indicated by <code>method</code>,
 8726         return the beginning and ending addresses through
 8727         <code>start_location_ptr</code> and <code>end_location_ptr</code>. In a
 8728         conventional bytecode indexing scheme,
 8729         <code>start_location_ptr</code> will always point to zero
 8730         and <code>end_location_ptr</code>
 8731         will always point to the bytecode count minus one.
 8732       </description>
 8733       <origin>jvmdi</origin>
 8734       <capabilities>
 8735       </capabilities>
 8736       <parameters>
 8737         <param id="klass">
 8738           <jclass method="method"/>
 8739             <description>
 8740               The class to query.
 8741             </description>
 8742         </param>
 8743         <param id="method">
 8744           <jmethodID class="klass" native="error"/>
 8745             <description>
 8746               The method to query.
 8747             </description>
 8748         </param>
 8749         <param id="start_location_ptr">
 8750           <outptr><jlocation/></outptr>
 8751           <description>
 8752             On return, points to the first location, or
 8753             <code>-1</code> if location information is not available.
 8754             If the information is available and
 8755             <functionlink id="GetJLocationFormat"></functionlink>
 8756             returns <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>
 8757             then this will always be zero.
 8758           </description>
 8759         </param>
 8760         <param id="end_location_ptr">
 8761           <outptr><jlocation/></outptr>
 8762           <description>
 8763             On return, points to the last location,
 8764             or <code>-1</code> if location information is not available.
 8765           </description>
 8766         </param>
 8767       </parameters>
 8768       <errors>
 8769         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
 8770           Class information does not include method sizes.
 8771         </error>
 8772       </errors>
 8773     </function>
 8774 
 8775     <function id="GetLocalVariableTable" num="72">
 8776       <synopsis>Get Local Variable Table</synopsis>
 8777       <typedef id="jvmtiLocalVariableEntry" label="Local variable table entry">
 8778         <field id="start_location">
 8779           <jlocation/>
 8780           <description>
 8781             The code array index where the local variable is first valid
 8782             (that is, where it must have a value).
 8783           </description>
 8784         </field>
 8785         <field id="length">
 8786           <jint/>
 8787           <description>
 8788             The length of the valid section for this local variable.
 8789             The last code array index where the local variable is valid
 8790             is <code>start_location + length</code>.
 8791           </description>
 8792         </field>
 8793         <field id="name">
 8794           <allocfieldbuf><char/></allocfieldbuf>
 8795           <description>
 8796             The local variable name, encoded as a
 8797             <internallink id="mUTF">modified UTF-8</internallink> string.
 8798           </description>
 8799         </field>
 8800         <field id="signature">
 8801           <allocfieldbuf><char/></allocfieldbuf>
 8802           <description>
 8803             The local variable's type signature, encoded as a
 8804             <internallink id="mUTF">modified UTF-8</internallink> string.
 8805             The signature format is the same as that defined in
 8806             <vmspec chapter="4.3.2"/>.
 8807           </description>
 8808         </field>
 8809         <field id="generic_signature">
 8810           <allocfieldbuf><char/></allocfieldbuf>
 8811           <description>
 8812             The local variable's generic signature, encoded as a
 8813             <internallink id="mUTF">modified UTF-8</internallink> string.
 8814             The value of this field will be <code>NULL</code> for any local
 8815             variable which does not have a generic type.
 8816           </description>
 8817         </field>
 8818         <field id="slot">
 8819           <jint/>
 8820           <description>
 8821             The local variable's slot.  See <internallink id="local">Local Variables</internallink>.
 8822           </description>
 8823         </field>
 8824       </typedef>
 8825       <description>
 8826         Return local variable information.
 8827       </description>
 8828       <origin>jvmdiClone</origin>
 8829       <capabilities>
 8830         <required id="can_access_local_variables"></required>
 8831       </capabilities>
 8832       <parameters>
 8833         <param id="method">
 8834           <jmethodID native="error"/>
 8835             <description>
 8836               The method to query.
 8837             </description>
 8838         </param>
 8839         <param id="entry_count_ptr">
 8840           <outptr><jint/></outptr>
 8841           <description>
 8842             On return, points to the number of entries in the table
 8843           </description>
 8844         </param>
 8845         <param id="table_ptr">
 8846           <allocbuf outcount="entry_count_ptr"><struct>jvmtiLocalVariableEntry</struct></allocbuf>
 8847           <description>
 8848             On return, points to an array of local variable table entries.
 8849           </description>
 8850         </param>
 8851       </parameters>
 8852       <errors>
 8853         <error id="JVMTI_ERROR_ABSENT_INFORMATION">
 8854           Class information does not include local variable
 8855           information.
 8856         </error>
 8857       </errors>
 8858     </function>
 8859 
 8860     <function id="GetBytecodes" phase="start" num="75">
 8861       <synopsis>Get Bytecodes</synopsis>
 8862       <description>
 8863         For the method indicated by <code>method</code>,
 8864         return the bytecodes that implement the method. The number of
 8865         bytecodes is returned via <code>bytecode_count_ptr</code>. The bytecodes
 8866         themselves are returned via <code>bytecodes_ptr</code>.
 8867       </description>
 8868       <origin>jvmdi</origin>
 8869       <capabilities>
 8870         <required id="can_get_bytecodes"></required>
 8871       </capabilities>
 8872       <parameters>
 8873         <param id="klass">
 8874           <jclass method="method"/>
 8875             <description>
 8876               The class to query.
 8877             </description>
 8878         </param>
 8879         <param id="method">
 8880           <jmethodID class="klass" native="error"/>
 8881             <description>
 8882               The method to query.
 8883             </description>
 8884         </param>
 8885         <param id="bytecode_count_ptr">
 8886           <outptr><jint/></outptr>
 8887           <description>
 8888             On return, points to the length of the bytecode array
 8889           </description>
 8890         </param>
 8891         <param id="bytecodes_ptr">
 8892           <allocbuf outcount="bytecode_count_ptr"><uchar/></allocbuf>
 8893           <description>
 8894             On return, points to the pointer to the bytecode array
 8895           </description>
 8896         </param>
 8897       </parameters>
 8898       <errors>
 8899       </errors>
 8900     </function>
 8901 
 8902     <function id="IsMethodNative" phase="start" num="76">
 8903       <synopsis>Is Method Native</synopsis>
 8904       <description>
 8905         For the method indicated by <code>method</code>, return a
 8906         value indicating whether the method is native via <code>is_native_ptr</code>
 8907       </description>
 8908       <origin>jvmdi</origin>
 8909       <capabilities>
 8910       </capabilities>
 8911       <parameters>
 8912         <param id="klass">
 8913           <jclass method="method"/>
 8914             <description>
 8915               The class to query.
 8916             </description>
 8917         </param>
 8918         <param id="method">
 8919           <jmethodID class="klass"/>
 8920             <description>
 8921               The method to query.
 8922             </description>
 8923         </param>
 8924         <param id="is_native_ptr">
 8925           <outptr><jboolean/></outptr>
 8926           <description>
 8927             On return, points to the boolean result of this function.
 8928           </description>
 8929         </param>
 8930       </parameters>
 8931       <errors>
 8932       </errors>
 8933     </function>
 8934 
 8935     <function id="IsMethodSynthetic" phase="start" num="77">
 8936       <synopsis>Is Method Synthetic</synopsis>
 8937       <description>
 8938         For the method indicated by <code>method</code>, return a
 8939         value indicating whether the method is synthetic via <code>is_synthetic_ptr</code>.
 8940         Synthetic methods are generated by the compiler but not present in the
 8941         original source code.
 8942       </description>
 8943       <origin>jvmdi</origin>
 8944       <capabilities>
 8945         <required id="can_get_synthetic_attribute"></required>
 8946       </capabilities>
 8947       <parameters>
 8948         <param id="klass">
 8949           <jclass method="method"/>
 8950             <description>
 8951               The class to query.
 8952             </description>
 8953         </param>
 8954         <param id="method">
 8955           <jmethodID class="klass"/>
 8956             <description>
 8957               The method to query.
 8958             </description>
 8959         </param>
 8960         <param id="is_synthetic_ptr">
 8961           <outptr><jboolean/></outptr>
 8962           <description>
 8963             On return, points to the boolean result of this function.
 8964           </description>
 8965         </param>
 8966       </parameters>
 8967       <errors>
 8968       </errors>
 8969     </function>
 8970 
 8971     <function id="IsMethodObsolete" phase="start" num="91">
 8972       <synopsis>Is Method Obsolete</synopsis>
 8973       <description>
 8974         Determine if a method ID refers to an
 8975         <internallink id="obsoleteMethods">obsolete</internallink>
 8976         method version.
 8977       </description>
 8978       <origin>jvmdi</origin>
 8979       <capabilities>
 8980       </capabilities>
 8981       <parameters>
 8982         <param id="klass">
 8983           <jclass method="method"/>
 8984             <description>
 8985               The class to query.
 8986             </description>
 8987         </param>
 8988         <param id="method">
 8989           <jmethodID class="klass"/>
 8990             <description>
 8991               The method ID to query.
 8992             </description>
 8993         </param>
 8994         <param id="is_obsolete_ptr">
 8995           <outptr><jboolean/></outptr>
 8996           <description>
 8997             On return, points to the boolean result of this function.
 8998           </description>
 8999         </param>
 9000       </parameters>
 9001       <errors>
 9002       </errors>
 9003     </function>
 9004 
 9005     <function id="SetNativeMethodPrefix" jkernel="yes" phase="any" num="73" since="1.1">
 9006       <synopsis>Set Native Method Prefix</synopsis>
 9007       <description>
 9008         This function modifies the failure handling of
 9009         native method resolution by allowing retry
 9010         with a prefix applied to the name.
 9011         When used with the
 9012         <eventlink id="ClassFileLoadHook">ClassFileLoadHook
 9013         event</eventlink>, it enables native methods to be
 9014         <internallink id="bci">instrumented</internallink>.
 9015         <p/>
 9016         Since native methods cannot be directly instrumented
 9017         (they have no bytecodes), they must be wrapped with
 9018         a non-native method which can be instrumented.
 9019         For example, if we had:
 9020         <example>
 9021 native boolean foo(int x);</example>
 9022         <p/>
 9023         We could transform the class file (with the
 9024         ClassFileLoadHook event) so that this becomes:
 9025         <example>
 9026 boolean foo(int x) {
 9027   <i>... record entry to foo ...</i>
 9028   return wrapped_foo(x);
 9029 }
 9030 
 9031 native boolean wrapped_foo(int x);</example>
 9032         <p/>
 9033         Where foo becomes a wrapper for the actual native method
 9034         with the appended prefix "wrapped_".  Note that
 9035         "wrapped_" would be a poor choice of prefix since it
 9036         might conceivably form the name of an existing method
 9037         thus something like "$$$MyAgentWrapped$$$_" would be
 9038         better but would make these examples less readable.
 9039         <p/>
 9040         The wrapper will allow data to be collected on the native
 9041         method call, but now the problem becomes linking up the
 9042         wrapped method with the native implementation.
 9043         That is, the method <code>wrapped_foo</code> needs to be
 9044         resolved to the native implementation of <code>foo</code>,
 9045         which might be:
 9046         <example>
 9047 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</example>
 9048         <p/>
 9049         This function allows the prefix to be specified and the
 9050         proper resolution to occur.
 9051         Specifically, when the standard resolution fails, the
 9052         resolution is retried taking the prefix into consideration.
 9053         There are two ways that resolution occurs, explicit
 9054         resolution with the JNI function <code>RegisterNatives</code>
 9055         and the normal automatic resolution.  For
 9056         <code>RegisterNatives</code>, the VM will attempt this
 9057         association:
 9058         <example>
 9059 method(foo) -> nativeImplementation(foo)</example>
 9060         <p/>
 9061         When this fails, the resolution will be retried with
 9062         the specified prefix prepended to the method name,
 9063         yielding the correct resolution:
 9064         <example>
 9065 method(wrapped_foo) -> nativeImplementation(foo)</example>
 9066         <p/>
 9067         For automatic resolution, the VM will attempt:
 9068         <example>
 9069 method(wrapped_foo) -> nativeImplementation(wrapped_foo)</example>
 9070         <p/>
 9071         When this fails, the resolution will be retried with
 9072         the specified prefix deleted from the implementation name,
 9073         yielding the correct resolution:
 9074         <example>
 9075 method(wrapped_foo) -> nativeImplementation(foo)</example>
 9076         <p/>
 9077         Note that since the prefix is only used when standard
 9078         resolution fails, native methods can be wrapped selectively.
 9079         <p/>
 9080         Since each <jvmti/> environment is independent and
 9081         can do its own transformation of the bytecodes, more
 9082         than one layer of wrappers may be applied. Thus each
 9083         environment needs its own prefix.  Since transformations
 9084         are applied in order, the prefixes, if applied, will
 9085         be applied in the same order.
 9086         The order of transformation application is described in
 9087         the <eventlink id="ClassFileLoadHook"/> event.
 9088         Thus if three environments applied
 9089         wrappers, <code>foo</code> might become
 9090         <code>$env3_$env2_$env1_foo</code>.  But if, say,
 9091         the second environment did not apply a wrapper to
 9092         <code>foo</code> it would be just
 9093         <code>$env3_$env1_foo</code>.  To be able to
 9094         efficiently determine the sequence of prefixes,
 9095         an intermediate prefix is only applied if its non-native
 9096         wrapper exists.  Thus, in the last example, even though
 9097         <code>$env1_foo</code> is not a native method, the
 9098         <code>$env1_</code> prefix is applied since
 9099         <code>$env1_foo</code> exists.
 9100         <p/>
 9101         Since the prefixes are used at resolution time
 9102         and since resolution may be arbitrarily delayed, a
 9103         native method prefix must remain set as long as there
 9104         are corresponding prefixed native methods.
 9105       </description>
 9106       <origin>new</origin>
 9107       <capabilities>
 9108         <required id="can_set_native_method_prefix"></required>
 9109       </capabilities>
 9110       <parameters>
 9111         <param id="prefix">
 9112           <inbuf>
 9113             <char/>
 9114             <nullok>
 9115               any existing prefix in this environment is cancelled
 9116             </nullok>
 9117           </inbuf>
 9118           <description>
 9119             The prefix to apply, encoded as a
 9120             <internallink id="mUTF">modified UTF-8</internallink> string.
 9121           </description>
 9122         </param>
 9123       </parameters>
 9124       <errors>
 9125       </errors>
 9126     </function>
 9127 
 9128     <function id="SetNativeMethodPrefixes" jkernel="yes" phase="any" num="74" since="1.1">
 9129       <synopsis>Set Native Method Prefixes</synopsis>
 9130       <description>
 9131          For a normal agent, <functionlink id="SetNativeMethodPrefix"/>
 9132          will provide all needed native method prefixing.
 9133          For a meta-agent that performs multiple independent class
 9134          file transformations (for example as a proxy for another
 9135          layer of agents) this function allows each transformation
 9136          to have its own prefix.
 9137          The prefixes are applied in the order supplied and are
 9138          processed in the same manner as described for the
 9139          application of prefixes from multiple <jvmti/> environments
 9140          in <functionlink id="SetNativeMethodPrefix"/>.
 9141          <p/>
 9142          Any previous prefixes are replaced.  Thus, calling this
 9143          function with a <paramlink id="prefix_count"/> of <code>0</code>
 9144          disables prefixing in this environment.
 9145          <p/>
 9146          <functionlink id="SetNativeMethodPrefix"/> and this function
 9147          are the two ways to set the prefixes.
 9148          Calling <code>SetNativeMethodPrefix</code> with
 9149          a prefix is the same as calling this function with
 9150          <paramlink id="prefix_count"/> of <code>1</code>.
 9151          Calling <code>SetNativeMethodPrefix</code> with
 9152          <code>NULL</code> is the same as calling this function with
 9153          <paramlink id="prefix_count"/> of <code>0</code>.
 9154       </description>
 9155       <origin>new</origin>
 9156       <capabilities>
 9157         <required id="can_set_native_method_prefix"></required>
 9158       </capabilities>
 9159       <parameters>
 9160         <param id="prefix_count">
 9161           <jint min="0"/>
 9162             <description>
 9163               The number of prefixes to apply.
 9164             </description>
 9165         </param>
 9166         <param id="prefixes">
 9167           <agentbuf>
 9168             <char/>
 9169           </agentbuf>
 9170           <description>
 9171             The prefixes to apply for this environment, each encoded as a
 9172             <internallink id="mUTF">modified UTF-8</internallink> string.
 9173           </description>
 9174         </param>
 9175       </parameters>
 9176       <errors>
 9177       </errors>
 9178     </function>
 9179 
 9180   </category>
 9181 
 9182   <category id="RawMonitors" label="Raw Monitor">
 9183 
 9184     <function id="CreateRawMonitor" phase="onload" callbacksafe="safe" num="31">
 9185       <synopsis>Create Raw Monitor</synopsis>
 9186       <description>
 9187         Create a raw monitor.
 9188       </description>
 9189       <origin>jvmdi</origin>
 9190       <capabilities>
 9191       </capabilities>
 9192       <parameters>
 9193         <param id="name">
 9194           <inbuf><char/></inbuf>
 9195           <description>
 9196             A name to identify the monitor, encoded as a
 9197             <internallink id="mUTF">modified UTF-8</internallink> string.
 9198           </description>
 9199         </param>
 9200         <param id="monitor_ptr">
 9201           <outptr><jrawMonitorID/></outptr>
 9202           <description>
 9203             On return, points to the created monitor.
 9204           </description>
 9205         </param>
 9206       </parameters>
 9207       <errors>
 9208       </errors>
 9209     </function>
 9210 
 9211     <function id="DestroyRawMonitor" phase="onload" callbacksafe="safe" num="32">
 9212       <synopsis>Destroy Raw Monitor</synopsis>
 9213       <description>
 9214         Destroy the raw monitor.
 9215         If the monitor being destroyed has been entered by this thread, it will be
 9216         exited before it is destroyed.
 9217         If the monitor being destroyed has been entered by another thread,
 9218         an error will be returned and the monitor will not be destroyed.
 9219       </description>
 9220       <origin>jvmdi</origin>
 9221       <capabilities>
 9222       </capabilities>
 9223       <parameters>
 9224         <param id="monitor">
 9225           <jrawMonitorID/>
 9226           <description>
 9227             The monitor
 9228           </description>
 9229         </param>
 9230       </parameters>
 9231       <errors>
 9232         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
 9233           Not monitor owner
 9234         </error>
 9235       </errors>
 9236     </function>
 9237 
 9238     <function id="RawMonitorEnter" phase="any" callbacksafe="safe" impl="innative notrace" num="33">
 9239       <synopsis>Raw Monitor Enter</synopsis>
 9240       <description>
 9241         Gain exclusive ownership of a raw monitor.
 9242         The same thread may enter a monitor more then once.
 9243         The thread must
 9244         <functionlink id="RawMonitorExit">exit</functionlink>
 9245         the monitor the same number of times as it is entered.
 9246         If a monitor is entered during <code>OnLoad</code> (before attached threads exist)
 9247         and has not exited when attached threads come into existence, the enter
 9248         is considered to have occurred on the main thread.
 9249       </description>
 9250       <origin>jvmdi</origin>
 9251       <capabilities>
 9252       </capabilities>
 9253       <parameters>
 9254         <param id="monitor">
 9255           <jrawMonitorID/>
 9256           <description>
 9257             The monitor
 9258           </description>
 9259         </param>
 9260       </parameters>
 9261       <errors>
 9262       </errors>
 9263     </function>
 9264 
 9265     <function id="RawMonitorExit" phase="any" callbacksafe="safe" impl="innative notrace" num="34">
 9266       <synopsis>Raw Monitor Exit</synopsis>
 9267       <description>
 9268         Release exclusive ownership of a raw monitor.
 9269       </description>
 9270       <origin>jvmdi</origin>
 9271       <capabilities>
 9272       </capabilities>
 9273       <parameters>
 9274         <param id="monitor">
 9275           <jrawMonitorID/>
 9276           <description>
 9277             The monitor
 9278           </description>
 9279         </param>
 9280       </parameters>
 9281       <errors>
 9282         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
 9283           Not monitor owner
 9284         </error>
 9285       </errors>
 9286     </function>
 9287 
 9288     <function id="RawMonitorWait" phase="any" callbacksafe="safe" impl="innative notrace" num="35">
 9289       <synopsis>Raw Monitor Wait</synopsis>
 9290       <description>
 9291         Wait for notification of the raw monitor.
 9292         <p/>
 9293         Causes the current thread to wait until either another thread calls
 9294         <functionlink id="RawMonitorNotify"/> or
 9295         <functionlink id="RawMonitorNotifyAll"/>
 9296         for the specified raw monitor, or the specified
 9297         <paramlink id="millis">timeout</paramlink>
 9298         has elapsed.
 9299       </description>
 9300       <origin>jvmdi</origin>
 9301       <capabilities>
 9302       </capabilities>
 9303       <parameters>
 9304         <param id="monitor">
 9305           <jrawMonitorID/>
 9306           <description>
 9307             The monitor
 9308           </description>
 9309         </param>
 9310         <param id="millis">
 9311           <jlong/>
 9312           <description>
 9313             The timeout, in milliseconds.  If the timeout is
 9314             zero, then real time is not taken into consideration
 9315             and the thread simply waits until notified.
 9316           </description>
 9317         </param>
 9318       </parameters>
 9319       <errors>
 9320         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
 9321           Not monitor owner
 9322         </error>
 9323         <error id="JVMTI_ERROR_INTERRUPT">
 9324           Wait was interrupted, try again
 9325         </error>
 9326       </errors>
 9327     </function>
 9328 
 9329     <function id="RawMonitorNotify" phase="any" callbacksafe="safe" impl="notrace" num="36">
 9330       <synopsis>Raw Monitor Notify</synopsis>
 9331       <description>
 9332         Notify a single thread waiting on the raw monitor.
 9333       </description>
 9334       <origin>jvmdi</origin>
 9335       <capabilities>
 9336       </capabilities>
 9337       <parameters>
 9338         <param id="monitor">
 9339           <jrawMonitorID/>
 9340           <description>
 9341             The monitor
 9342           </description>
 9343         </param>
 9344       </parameters>
 9345       <errors>
 9346         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
 9347           Not monitor owner
 9348         </error>
 9349       </errors>
 9350     </function>
 9351 
 9352     <function id="RawMonitorNotifyAll" phase="any" callbacksafe="safe" impl="notrace" num="37">
 9353       <synopsis>Raw Monitor Notify All</synopsis>
 9354       <description>
 9355         Notify all threads waiting on the raw monitor.
 9356       </description>
 9357       <origin>jvmdi</origin>
 9358       <capabilities>
 9359       </capabilities>
 9360       <parameters>
 9361         <param id="monitor">
 9362           <jrawMonitorID/>
 9363           <description>
 9364             The monitor
 9365           </description>
 9366         </param>
 9367       </parameters>
 9368       <errors>
 9369         <error id="JVMTI_ERROR_NOT_MONITOR_OWNER">
 9370           Not monitor owner
 9371         </error>
 9372       </errors>
 9373     </function>
 9374 
 9375    <elide>
 9376     <function id="GetRawMonitorUse" num="118">
 9377       <synopsis>Get Raw Monitor Use</synopsis>
 9378       <description>
 9379         The fields of the <functionlink id="jvmtiMonitorUsage"></functionlink> structure
 9380         are filled in with information about usage of the raw monitor.
 9381       </description>
 9382       <origin>new</origin>
 9383       <capabilities>
 9384         <required id="can_get_raw_monitor_usage"></required>
 9385       </capabilities>
 9386       <parameters>
 9387         <param id="monitor">
 9388           <jrawMonitorID/>
 9389           <description>
 9390             the raw monitor to query.
 9391           </description>
 9392         </param>
 9393         <param id="info_ptr">
 9394           <outptr><struct>jvmtiMonitorUsage</struct></outptr>
 9395           <description>
 9396             On return, filled with monitor information for the
 9397             specified raw monitor.
 9398           </description>
 9399         </param>
 9400       </parameters>
 9401       <errors>
 9402       </errors>
 9403     </function>
 9404 
 9405     <function id="GetRawMonitors" num="119">
 9406       <synopsis>Get Raw Monitors</synopsis>
 9407       <description>
 9408         Return the list of raw monitors.
 9409         <p/>
 9410         Note: details about each monitor can be examined with
 9411         <functionlink id="GetRawMonitorUse"></functionlink>.
 9412       </description>
 9413       <origin>new</origin>
 9414       <capabilities>
 9415         <required id="can_get_raw_monitor_usage"></required>
 9416       </capabilities>
 9417       <parameters>
 9418         <param id="monitorCnt">
 9419           <outptr><jint/></outptr>
 9420           <description>
 9421             On return, pointer to the number
 9422             of monitors returned in <code>monitors_ptr</code>.
 9423           </description>
 9424         </param>
 9425         <param id="monitors_ptr">
 9426           <allocbuf outcount="monitorCnt"><jrawMonitorID/></allocbuf>
 9427           <description>
 9428             On return, pointer to the monitor list.
 9429           </description>
 9430         </param>
 9431       </parameters>
 9432       <errors>
 9433       </errors>
 9434     </function>
 9435     </elide>
 9436   </category>
 9437 
 9438   <category id="jniIntercept" label="JNI Function Interception">
 9439 
 9440     <intro>
 9441       Provides the ability to intercept and resend
 9442       Java Native Interface (JNI) function calls
 9443       by manipulating the JNI function table.
 9444       See <externallink id="jni/functions.html">JNI
 9445         Functions</externallink> in the <i>Java Native Interface Specification</i>.
 9446       <p/>
 9447       The following example illustrates intercepting the
 9448       <code>NewGlobalRef</code> JNI call in order to count reference
 9449       creation.
 9450       <example>
 9451 JNIEnv original_jni_Functions;
 9452 JNIEnv redirected_jni_Functions;
 9453 int my_global_ref_count = 0;
 9454 
 9455 jobject
 9456 MyNewGlobalRef(JNIEnv *jni_env, jobject lobj) {
 9457    ++my_global_ref_count;
 9458    return originalJNIFunctions-&gt;NewGlobalRef(env, lobj);
 9459 }
 9460 
 9461 void
 9462 myInit() {
 9463    jvmtiError err;
 9464 
 9465    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;original_jni_Functions);
 9466    if (err != JVMTI_ERROR_NONE) {
 9467       die();
 9468    }
 9469    err = (*jvmti_env)-&gt;GetJNIFunctionTable(jvmti_env, &amp;redirected_jni_Functions);
 9470    if (err != JVMTI_ERROR_NONE) {
 9471       die();
 9472    }
 9473    redirectedJNIFunctions-&gt;NewGlobalRef = MyNewGlobalRef;
 9474       err = (*jvmti_env)-&gt;SetJNIFunctionTable(jvmti_env, redirected_jni_Functions);
 9475    if (err != JVMTI_ERROR_NONE) {
 9476       die();
 9477    }
 9478 }
 9479       </example>
 9480       Sometime after <code>myInit</code> is called the user's JNI
 9481       code is executed which makes the call to create a new global
 9482       reference.  Instead of going to the normal JNI implementation
 9483       the call goes to <code>myNewGlobalRef</code>.  Note that a
 9484       copy of the original function table is kept so that the normal
 9485       JNI function can be called after the data is collected.
 9486       Note also that any JNI functions which are not overwritten
 9487       will behave normally.
 9488       <todo>
 9489         check that the example compiles and executes.
 9490       </todo>
 9491     </intro>
 9492 
 9493     <function id="SetJNIFunctionTable" phase="start" num="120">
 9494       <synopsis>Set JNI Function Table</synopsis>
 9495       <description>
 9496         Set the JNI function table
 9497         in all current and future JNI environments.
 9498         As a result, all future JNI calls are directed to the specified functions.
 9499         Use <functionlink id="GetJNIFunctionTable"></functionlink> to get the
 9500         function table to pass to this function.
 9501         For this function to take effect the the updated table entries must be
 9502         used by the JNI clients.
 9503         Since the table is defined <code>const</code> some compilers may optimize
 9504         away the access to the table, thus preventing this function from taking
 9505         effect.
 9506         The table is copied--changes to the local copy of the
 9507         table have no effect.
 9508         This function affects only the function table, all other aspects of the environment are
 9509         unaffected.
 9510         See the examples <internallink id="jniIntercept">above</internallink>.
 9511       </description>
 9512       <origin>new</origin>
 9513       <capabilities>
 9514       </capabilities>
 9515       <parameters>
 9516         <param id="function_table">
 9517           <inptr>
 9518             <struct>jniNativeInterface</struct>
 9519           </inptr>
 9520           <description>
 9521             Points to the new JNI function table.
 9522           </description>
 9523         </param>
 9524       </parameters>
 9525       <errors>
 9526       </errors>
 9527     </function>
 9528 
 9529     <function id="GetJNIFunctionTable" phase="start" num="121">
 9530       <synopsis>Get JNI Function Table</synopsis>
 9531       <description>
 9532         Get the JNI function table.
 9533         The JNI function table is copied into allocated memory.
 9534         If <functionlink id="SetJNIFunctionTable"></functionlink>
 9535         has been called, the modified (not the original) function
 9536         table is returned.
 9537         Only the function table is copied, no other aspects of the environment
 9538         are copied.
 9539         See the examples <internallink id="jniIntercept">above</internallink>.
 9540       </description>
 9541       <origin>new</origin>
 9542       <capabilities>
 9543       </capabilities>
 9544       <parameters>
 9545         <param id="function_table">
 9546           <allocbuf>
 9547             <struct>jniNativeInterface</struct>
 9548           </allocbuf>
 9549           <description>
 9550             On return, <code>*function_table</code>
 9551             points a newly allocated copy of the JNI function table.
 9552           </description>
 9553         </param>
 9554       </parameters>
 9555       <errors>
 9556       </errors>
 9557     </function>
 9558 
 9559   </category>
 9560 
 9561   <category id="eventManagement" label="Event Management">
 9562 
 9563     <function id="SetEventCallbacks" jkernel="yes" phase="onload" num="122">
 9564       <synopsis>Set Event Callbacks</synopsis>
 9565       <description>
 9566         Set the functions to be called for each event.
 9567         The callbacks are specified by supplying a replacement function table.
 9568         The function table is copied--changes to the local copy of the
 9569         table have no effect.
 9570         This is an atomic action, all callbacks are set at once.
 9571         No events are sent before this function is called.
 9572         When an entry is <code>NULL</code> or when the event is beyond
 9573         <paramlink id="size_of_callbacks"></paramlink> no event is sent.
 9574         Details on events are
 9575         described <internallink id="EventSection">later</internallink> in this document.
 9576         An event must be enabled and have a callback in order to be
 9577         sent--the order in which this function and
 9578         <functionlink id="SetEventNotificationMode"></functionlink>
 9579         are called does not affect the result.
 9580       </description>
 9581       <origin>new</origin>
 9582       <capabilities>
 9583       </capabilities>
 9584       <parameters>
 9585         <param id="callbacks">
 9586           <inptr>
 9587             <struct>jvmtiEventCallbacks</struct>
 9588             <nullok>remove the existing callbacks</nullok>
 9589           </inptr>
 9590           <description>
 9591             The new event callbacks.
 9592           </description>
 9593         </param>
 9594         <param id="size_of_callbacks">
 9595           <jint min="0"/>
 9596           <description>
 9597             <code>sizeof(jvmtiEventCallbacks)</code>--for version
 9598             compatibility.
 9599           </description>
 9600         </param>
 9601       </parameters>
 9602       <errors>
 9603       </errors>
 9604     </function>
 9605 
 9606     <function id="SetEventNotificationMode" jkernel="yes" phase="onload" num="2">
 9607       <synopsis>Set Event Notification Mode</synopsis>
 9608       <description>
 9609         Control the generation of events.
 9610         <constants id="jvmtiEventMode" label="Event Enable/Disable" kind="enum">
 9611           <constant id="JVMTI_ENABLE" num="1">
 9612             If <paramlink id="mode"></paramlink> is <code>JVMTI_ENABLE</code>,
 9613             the event <paramlink id="event_type"></paramlink> will be enabled
 9614           </constant>
 9615           <constant id="JVMTI_DISABLE" num="0">
 9616             If <paramlink id="mode"></paramlink> is <code>JVMTI_DISABLE</code>,
 9617             the event <paramlink id="event_type"></paramlink> will be disabled
 9618           </constant>
 9619         </constants>
 9620         If <code>event_thread</code> is <code>NULL</code>,
 9621         the event is enabled or disabled globally; otherwise, it is
 9622         enabled or disabled for a particular thread.
 9623         An event is generated for
 9624         a particular thread if it is enabled either at the thread or global
 9625         levels.
 9626         <p/>
 9627         See <internallink id="EventIndex">below</internallink> for information on specific events.
 9628         <p/>
 9629         The following events cannot be controlled at the thread
 9630         level through this function.
 9631         <ul>
 9632           <li><eventlink id="VMInit"></eventlink></li>
 9633           <li><eventlink id="VMStart"></eventlink></li>
 9634           <li><eventlink id="VMDeath"></eventlink></li>
 9635           <li><eventlink id="ThreadStart"></eventlink></li>
 9636           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
 9637           <li><eventlink id="CompiledMethodUnload"></eventlink></li>
 9638           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
 9639           <li><eventlink id="DataDumpRequest"></eventlink></li>
 9640         </ul>
 9641         <p/>
 9642         Initially, no events are enabled at either the thread level
 9643         or the global level.
 9644         <p/>
 9645         Any needed capabilities (see Event Enabling Capabilities below) must be possessed
 9646         before calling this function.
 9647         <p/>
 9648         Details on events are
 9649         described <internallink id="EventSection">below</internallink>.
 9650       </description>
 9651       <origin>jvmdiClone</origin>
 9652       <eventcapabilities></eventcapabilities>
 9653       <parameters>
 9654         <param id="mode">
 9655           <enum>jvmtiEventMode</enum>
 9656           <description>
 9657             <code>JVMTI_ENABLE</code> or <code>JVMTI_DISABLE</code>
 9658           </description>
 9659         </param>
 9660         <param id="event_type">
 9661           <enum>jvmtiEvent</enum>
 9662           <description>
 9663             the event to control
 9664           </description>
 9665         </param>
 9666         <param id="event_thread">
 9667           <ptrtype>
 9668             <jthread impl="noconvert"/>
 9669             <nullok>event is controlled at the global level</nullok>
 9670           </ptrtype>
 9671             <description>
 9672               The thread to control
 9673             </description>
 9674         </param>
 9675         <param id="...">
 9676           <varargs/>
 9677             <description>
 9678               for future expansion
 9679             </description>
 9680         </param>
 9681       </parameters>
 9682       <errors>
 9683         <error id="JVMTI_ERROR_INVALID_THREAD">
 9684           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not a valid thread.
 9685         </error>
 9686         <error id="JVMTI_ERROR_THREAD_NOT_ALIVE">
 9687           <paramlink id="event_thread"/> is non-<code>NULL</code> and is not live (has not been started or is now dead).
 9688         </error>
 9689         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 9690           thread level control was attempted on events which do not
 9691           permit thread level control.
 9692         </error>
 9693         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
 9694           The Required Event Enabling Capability is not possessed.
 9695         </error>
 9696       </errors>
 9697     </function>
 9698 
 9699     <function id="GenerateEvents" num="123">
 9700       <synopsis>Generate Events</synopsis>
 9701       <description>
 9702         Generate events to represent the current state of the VM.
 9703         For example, if <paramlink id="event_type"/> is
 9704         <code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code>,
 9705         a <eventlink id="CompiledMethodLoad"></eventlink> event will be
 9706         sent for each currently compiled method.
 9707         Methods that were loaded and now have been unloaded are not sent.
 9708         The history of what events have previously been sent does not
 9709         effect what events are sent by this function--for example,
 9710         all currently compiled methods
 9711         will be sent each time this function is called.
 9712         <p/>
 9713         This function is useful when
 9714         events may have been missed due to the agent attaching after program
 9715         execution begins; this function generates the missed events.
 9716         <p/>
 9717         Attempts to execute Java programming language code or
 9718         JNI functions may be paused until this function returns -
 9719         so neither should be called from the thread sending the event.
 9720         This function returns only after the missed events have been
 9721         sent, processed and have returned.
 9722         The event may be sent on a different thread than the thread
 9723         on which the event occurred.
 9724         The callback for the event must be set with
 9725         <functionlink id="SetEventCallbacks"></functionlink>
 9726         and the event must be enabled with
 9727         <functionlink id="SetEventNotificationMode"></functionlink>
 9728         or the events will not occur.
 9729         If the VM no longer has the information to generate some or
 9730         all of the requested events, the events are simply not sent -
 9731         no error is returned.
 9732         <p/>
 9733         Only the following events are supported:
 9734         <ul>
 9735           <li><eventlink id="CompiledMethodLoad"></eventlink></li>
 9736           <li><eventlink id="DynamicCodeGenerated"></eventlink></li>
 9737         </ul>
 9738       </description>
 9739       <origin>new</origin>
 9740       <capabilities>
 9741         <capability id="can_generate_compiled_method_load_events"></capability>
 9742       </capabilities>
 9743       <parameters>
 9744         <param id="event_type">
 9745           <enum>jvmtiEvent</enum>
 9746           <description>
 9747             The type of event to generate.  Must be one of these:
 9748             <ul>
 9749               <li><eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink></li>
 9750               <li><eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink></li>
 9751             </ul>
 9752           </description>
 9753         </param>
 9754       </parameters>
 9755       <errors>
 9756         <error id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY">
 9757           <paramlink id="event_type"/> is
 9758           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
 9759           and <fieldlink id="can_generate_compiled_method_load_events" struct="jvmtiCapabilities"></fieldlink>
 9760           is <code>false</code>.
 9761         </error>
 9762         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
 9763           <paramlink id="event_type"/> is other than
 9764           <eventlink id="CompiledMethodLoad"><code>JVMTI_EVENT_COMPILED_METHOD_LOAD</code></eventlink>
 9765           or <eventlink id="DynamicCodeGenerated"><code>JVMTI_EVENT_DYNAMIC_CODE_GENERATED</code></eventlink>.
 9766         </error>
 9767       </errors>
 9768     </function>
 9769 
 9770   </category>
 9771 
 9772     <category id="extension" label="Extension Mechanism">
 9773 
 9774       <intro>
 9775         These functions
 9776         allow a <jvmti/> implementation to provide functions and events
 9777         beyond those defined in this specification.
 9778         <p/>
 9779         Both extension functions and extension events have parameters
 9780         each of which has a 'type' and 'kind' chosen from the following tables:
 9781 
 9782         <constants id="jvmtiParamTypes" label="Extension Function/Event Parameter Types" kind="enum">
 9783           <constant id="JVMTI_TYPE_JBYTE" num="101">
 9784             Java programming language primitive type - <code>byte</code>.
 9785             JNI type <code>jbyte</code>.
 9786           </constant>
 9787           <constant id="JVMTI_TYPE_JCHAR" num="102">
 9788             Java programming language primitive type - <code>char</code>.
 9789             JNI type <code>jchar</code>.
 9790           </constant>
 9791           <constant id="JVMTI_TYPE_JSHORT" num="103">
 9792             Java programming language primitive type - <code>short</code>.
 9793             JNI type <code>jshort</code>.
 9794           </constant>
 9795           <constant id="JVMTI_TYPE_JINT" num="104">
 9796             Java programming language primitive type - <code>int</code>.
 9797             JNI type <datalink id="jint"></datalink>.
 9798           </constant>
 9799           <constant id="JVMTI_TYPE_JLONG" num="105">
 9800             Java programming language primitive type - <code>long</code>.
 9801             JNI type <datalink id="jlong"></datalink>.
 9802           </constant>
 9803           <constant id="JVMTI_TYPE_JFLOAT" num="106">
 9804             Java programming language primitive type - <code>float</code>.
 9805             JNI type <datalink id="jfloat"></datalink>.
 9806           </constant>
 9807           <constant id="JVMTI_TYPE_JDOUBLE" num="107">
 9808             Java programming language primitive type - <code>double</code>.
 9809             JNI type <datalink id="jdouble"></datalink>.
 9810           </constant>
 9811           <constant id="JVMTI_TYPE_JBOOLEAN" num="108">
 9812             Java programming language primitive type - <code>boolean</code>.
 9813             JNI type <datalink id="jboolean"></datalink>.
 9814           </constant>
 9815           <constant id="JVMTI_TYPE_JOBJECT" num="109">
 9816             Java programming language object type - <code>java.lang.Object</code>.
 9817             JNI type <datalink id="jobject"></datalink>.
 9818             Returned values are JNI local references and must be managed.
 9819           </constant>
 9820           <constant id="JVMTI_TYPE_JTHREAD" num="110">
 9821             Java programming language object type - <code>java.lang.Thread</code>.
 9822             <jvmti/> type <datalink id="jthread"></datalink>.
 9823             Returned values are JNI local references and must be managed.
 9824           </constant>
 9825           <constant id="JVMTI_TYPE_JCLASS" num="111">
 9826             Java programming language object type - <code>java.lang.Class</code>.
 9827             JNI type <datalink id="jclass"></datalink>.
 9828             Returned values are JNI local references and must be managed.
 9829           </constant>
 9830           <constant id="JVMTI_TYPE_JVALUE" num="112">
 9831             Union of all Java programming language primitive and object types -
 9832             JNI type <datalink id="jvalue"></datalink>.
 9833             Returned values which represent object types are JNI local references and must be managed.
 9834           </constant>
 9835           <constant id="JVMTI_TYPE_JFIELDID" num="113">
 9836             Java programming language field identifier -
 9837             JNI type <datalink id="jfieldID"></datalink>.
 9838           </constant>
 9839           <constant id="JVMTI_TYPE_JMETHODID" num="114">
 9840             Java programming language method identifier -
 9841             JNI type <datalink id="jmethodID"></datalink>.
 9842           </constant>
 9843           <constant id="JVMTI_TYPE_CCHAR" num="115">
 9844             C programming language type - <code>char</code>.
 9845           </constant>
 9846           <constant id="JVMTI_TYPE_CVOID" num="116">
 9847             C programming language type - <code>void</code>.
 9848           </constant>
 9849           <constant id="JVMTI_TYPE_JNIENV" num="117">
 9850             JNI environment - <code>JNIEnv</code>.
 9851             Should be used with the correct <datalink id="jvmtiParamKind"/> to make it a pointer type.
 9852           </constant>
 9853         </constants>
 9854 
 9855         <constants id="jvmtiParamKind" label="Extension Function/Event Parameter Kinds" kind="enum">
 9856           <constant id="JVMTI_KIND_IN" num="91">
 9857             Ingoing argument - <code>foo</code>.
 9858           </constant>
 9859           <constant id="JVMTI_KIND_IN_PTR" num="92">
 9860             Ingoing pointer argument - <code>const foo*</code>.
 9861           </constant>
 9862           <constant id="JVMTI_KIND_IN_BUF" num="93">
 9863             Ingoing array argument - <code>const foo*</code>.
 9864           </constant>
 9865           <constant id="JVMTI_KIND_ALLOC_BUF" num="94">
 9866             Outgoing allocated array argument -  <code>foo**</code>.
 9867             Free with <code>Deallocate</code>.
 9868           </constant>
 9869           <constant id="JVMTI_KIND_ALLOC_ALLOC_BUF" num="95">
 9870             Outgoing allocated array of allocated arrays argument - <code>foo***</code>.
 9871             Free with <code>Deallocate</code>.
 9872           </constant>
 9873           <constant id="JVMTI_KIND_OUT" num="96">
 9874             Outgoing argument - <code>foo*</code>.
 9875           </constant>
 9876           <constant id="JVMTI_KIND_OUT_BUF" num="97">
 9877             Outgoing array argument (pre-allocated by agent) - <code>foo*</code>.
 9878             Do not <code>Deallocate</code>.
 9879           </constant>
 9880         </constants>
 9881 
 9882       </intro>
 9883 
 9884       <typedef id="jvmtiParamInfo" label="Extension Function/Event Parameter Info">
 9885         <field id="name">
 9886           <allocfieldbuf><char/></allocfieldbuf>
 9887             <description>
 9888               The parameter name, encoded as a
 9889               <internallink id="mUTF">modified UTF-8</internallink> string
 9890             </description>
 9891         </field>
 9892         <field id="kind">
 9893           <enum>jvmtiParamKind</enum>
 9894           <description>
 9895             The kind of the parameter - type modifiers
 9896           </description>
 9897         </field>
 9898         <field id="base_type">
 9899           <enum>jvmtiParamTypes</enum>
 9900           <description>
 9901             The base type of the parameter -  modified by <code>kind</code>
 9902           </description>
 9903         </field>
 9904         <field id="null_ok">
 9905           <jboolean/>
 9906             <description>
 9907               Is a <code>NULL</code> argument permitted? Applies only to pointer and object types.
 9908             </description>
 9909         </field>
 9910       </typedef>
 9911 
 9912       <callback id="jvmtiExtensionFunction">
 9913         <enum>jvmtiError</enum>
 9914           <synopsis>Extension Function</synopsis>
 9915         <description>
 9916           This is the implementation-specific extension function.
 9917         </description>
 9918         <parameters>
 9919           <param id="jvmti_env">
 9920             <outptr>
 9921               <struct>jvmtiEnv</struct>
 9922             </outptr>
 9923             <description>
 9924               The <jvmti/> environment is the only fixed parameter for extension functions.
 9925             </description>
 9926           </param>
 9927           <param id="...">
 9928             <varargs/>
 9929               <description>
 9930                 The extension function-specific parameters
 9931               </description>
 9932           </param>
 9933         </parameters>
 9934       </callback>
 9935 
 9936       <function id="GetExtensionFunctions" phase="onload" num="124">
 9937         <synopsis>Get Extension Functions</synopsis>
 9938 
 9939         <typedef id="jvmtiExtensionFunctionInfo" label="Extension Function Info">
 9940           <field id="func">
 9941             <ptrtype>
 9942               <struct>jvmtiExtensionFunction</struct>
 9943             </ptrtype>
 9944             <description>
 9945               The actual function to call
 9946             </description>
 9947           </field>
 9948           <field id="id">
 9949             <allocfieldbuf><char/></allocfieldbuf>
 9950               <description>
 9951                 The identifier for the extension function, encoded as a
 9952                 <internallink id="mUTF">modified UTF-8</internallink> string.
 9953                 Uses package name conventions.
 9954                 For example, <code>com.sun.hotspot.bar</code>
 9955               </description>
 9956           </field>
 9957           <field id="short_description">
 9958             <allocfieldbuf><char/></allocfieldbuf>
 9959               <description>
 9960                 A one sentence description of the function, encoded as a
 9961                 <internallink id="mUTF">modified UTF-8</internallink> string.
 9962               </description>
 9963           </field>
 9964           <field id="param_count">
 9965             <jint/>
 9966               <description>
 9967                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
 9968               </description>
 9969           </field>
 9970           <field id="params">
 9971             <allocfieldbuf outcount="param_count">
 9972               <struct>jvmtiParamInfo</struct>
 9973             </allocfieldbuf>
 9974             <description>
 9975               Array of
 9976               <fieldlink id="param_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
 9977               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
 9978             </description>
 9979           </field>
 9980           <field id="error_count">
 9981             <jint/>
 9982               <description>
 9983                 The number of possible error returns (excluding universal errors)
 9984               </description>
 9985           </field>
 9986           <field id="errors">
 9987             <allocfieldbuf outcount="error_count">
 9988               <enum>jvmtiError</enum>
 9989             </allocfieldbuf>
 9990             <description>
 9991               Array of <fieldlink id="error_count" struct="jvmtiExtensionFunctionInfo"></fieldlink>
 9992               possible errors
 9993             </description>
 9994           </field>
 9995         </typedef>
 9996 
 9997         <description>
 9998           Returns the set of extension functions.
 9999         </description>
10000         <origin>new</origin>
10001         <capabilities>
10002         </capabilities>
10003         <parameters>
10004           <param id="extension_count_ptr">
10005             <outptr><jint/></outptr>
10006               <description>
10007                 On return, points to the number of extension functions
10008               </description>
10009           </param>
10010           <param id="extensions">
10011             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionFunctionInfo</struct></allocbuf>
10012             <description>
10013               Returns an array of extension function info, one per function
10014             </description>
10015           </param>
10016         </parameters>
10017         <errors>
10018         </errors>
10019       </function>
10020 
10021       <function id="GetExtensionEvents" phase="onload" num="125">
10022         <synopsis>Get Extension Events</synopsis>
10023 
10024         <typedef id="jvmtiExtensionEventInfo" label="Extension Event Info">
10025           <field id="extension_event_index">
10026             <jint/>
10027             <description>
10028               The identifying index of the event
10029             </description>
10030           </field>
10031           <field id="id">
10032             <allocfieldbuf><char/></allocfieldbuf>
10033               <description>
10034                 The identifier for the extension event, encoded as a
10035                 <internallink id="mUTF">modified UTF-8</internallink> string.
10036                 Uses package name conventions.
10037                 For example, <code>com.sun.hotspot.bar</code>
10038               </description>
10039           </field>
10040           <field id="short_description">
10041             <allocfieldbuf><char/></allocfieldbuf>
10042               <description>
10043                 A one sentence description of the event, encoded as a
10044                 <internallink id="mUTF">modified UTF-8</internallink> string.
10045               </description>
10046           </field>
10047           <field id="param_count">
10048             <jint/>
10049               <description>
10050                 The number of parameters excluding <code>jvmtiEnv *jvmti_env</code>
10051               </description>
10052           </field>
10053           <field id="params">
10054             <allocfieldbuf outcount="param_count">
10055               <struct>jvmtiParamInfo</struct>
10056             </allocfieldbuf>
10057             <description>
10058               Array of
10059               <fieldlink id="param_count" struct="jvmtiExtensionEventInfo"></fieldlink>
10060               parameters (<code>jvmtiEnv *jvmti_env</code> excluded)
10061             </description>
10062           </field>
10063         </typedef>
10064 
10065         <description>
10066           Returns the set of extension events.
10067         </description>
10068         <origin>new</origin>
10069         <capabilities>
10070         </capabilities>
10071         <parameters>
10072           <param id="extension_count_ptr">
10073             <outptr><jint/></outptr>
10074               <description>
10075                 On return, points to the number of extension events
10076               </description>
10077           </param>
10078           <param id="extensions">
10079             <allocbuf outcount="extension_count_ptr"><struct>jvmtiExtensionEventInfo</struct></allocbuf>
10080             <description>
10081               Returns an array of extension event info, one per event
10082             </description>
10083           </param>
10084         </parameters>
10085         <errors>
10086         </errors>
10087       </function>
10088 
10089       <callback id="jvmtiExtensionEvent">
10090         <void/>
10091           <synopsis>Extension Event</synopsis>
10092         <description>
10093           This is the implementation-specific event.
10094           The event handler is set with
10095           <functionlink id="SetExtensionEventCallback"/>.
10096           <p/>
10097           Event handlers for extension events must be declared varargs to match this definition.
10098           Failure to do so could result in calling convention mismatch and undefined behavior
10099           on some platforms.
10100           <p/>
10101           For example, if the <code>jvmtiParamInfo</code>
10102           returned by <functionlink id="GetExtensionEvents"/> indicates that
10103           there is a <code>jint</code> parameter, the event handler should be
10104           declared:
10105 <example>
10106     void JNICALL myHandler(jvmtiEnv* jvmti_env, ...)
10107 </example>
10108           Note the terminal "<code>...</code>" which indicates varargs.
10109           The <code>jint</code> argument inside <code>myHandler</code> needs to be extracted using
10110           the <code>va_*</code> syntax of the C programming language.
10111         </description>
10112         <parameters>
10113           <param id="jvmti_env">
10114             <outptr>
10115               <struct>jvmtiEnv</struct>
10116             </outptr>
10117             <description>
10118               The <jvmti/> environment is the only fixed parameter for extension events.
10119             </description>
10120           </param>
10121           <param id="...">
10122             <varargs/>
10123               <description>
10124                 The extension event-specific parameters
10125               </description>
10126           </param>
10127         </parameters>
10128       </callback>
10129 
10130       <function id="SetExtensionEventCallback" phase="onload" num="126">
10131         <synopsis>Set Extension Event Callback</synopsis>
10132 
10133         <description>
10134           Sets the callback function for an extension event and
10135           enables the event. Or, if the callback is <code>NULL</code>, disables
10136           the event.  Note that unlike standard events, setting
10137           the callback and enabling the event are a single operation.
10138         </description>
10139         <origin>new</origin>
10140         <capabilities>
10141         </capabilities>
10142         <parameters>
10143           <param id="extension_event_index">
10144             <jint/>
10145               <description>
10146                 Identifies which callback to set.
10147                 This index is the
10148                 <fieldlink id="extension_event_index" struct="jvmtiExtensionEventInfo"></fieldlink>
10149                 field of
10150                 <datalink id="jvmtiExtensionEventInfo"/>.
10151               </description>
10152           </param>
10153           <param id="callback">
10154             <ptrtype>
10155               <struct>jvmtiExtensionEvent</struct>
10156               <nullok>disable the event</nullok>
10157             </ptrtype>
10158             <description>
10159               If <code>callback</code> is non-<code>NULL</code>,
10160               set <code>callback</code> to be the event callback function
10161               and enable the event.
10162             </description>
10163           </param>
10164         </parameters>
10165         <errors>
10166         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
10167             <paramlink id="extension_event_index"/> is not an
10168             <fieldlink id="extension_event_index"
10169                        struct="jvmtiExtensionEventInfo"/>
10170             returned by
10171             <functionlink id="GetExtensionEvents"/>
10172         </error>
10173         </errors>
10174       </function>
10175 
10176     </category>
10177 
10178   <category id="capability" label="Capability">
10179 
10180     <intro>
10181       The capabilities functions allow you to change the
10182       functionality available to <jvmti/>--that is,
10183       which <jvmti/>
10184       functions can be called, what events can be generated,
10185       and what functionality these events and functions can
10186       provide.
10187       <p/>
10188         The "Capabilities" section of each function and event describe which
10189         capabilities, if any, they are associated with. "Required Functionality"
10190         means it is available for use and no capabilities must be added to use it.
10191         "Optional Functionality" means the agent must possess the capability
10192         before it can be used.
10193         To possess a capability, the agent must
10194         <functionlink id="AddCapabilities">add the capability</functionlink>.
10195         "Optional Features" describe capabilities which,
10196         if added, extend the feature set.
10197         <p/>
10198         The potentially available capabilities of each <jvmti/> implementation are different.
10199         Depending on the implementation, a capability:
10200         <ul>
10201           <li>may never be added</li>
10202           <li>may be added in either the <code>OnLoad</code> or live phase in any environment</li>
10203           <li>may be added only during the <code>OnLoad</code> phase</li>
10204           <li>may be possessed by only one environment at a time</li>
10205           <li>may be possessed by only one environment at a time,
10206               and only during the <code>OnLoad</code> phase</li>
10207           <li>and so on ...</li>
10208         </ul>
10209       Frequently, the addition of a capability may incur a cost in execution speed, start up
10210       time, and/or memory footprint.  Note that the overhead of using a capability
10211       is completely different than the overhead of possessing a capability.
10212       Take single stepping as an example. When single stepping is on (that
10213       is, when the event is enabled and thus actively sending events)
10214       the overhead of sending and processing an event
10215       on each instruction is huge in any implementation.
10216       However, the overhead of possessing the capability may be small or large,
10217       depending on the implementation.  Also, when and if a capability is potentially
10218       available depends on the implementation.  Some examples:
10219       <ul>
10220         <li>One VM might perform all execution by compiling bytecodes into
10221           native code and be unable to generate single step instructions.
10222           In this implementation the capability can not be added.</li>
10223         <li>Another VM may be able to switch execution to a single stepping
10224           interpreter at any time.  In this implementation, having the capability has no
10225           overhead and could be added at any time.</li>
10226         <li>Yet another VM might be able to choose a bytecode compiling or single stepping capable interpreted
10227           execution engine at start up, but be unable to switch between them.
10228           In this implementation the capability would need to be added
10229           during the <code>OnLoad</code> phase (before bytecode
10230           execution begins) and would have a large impact on execution speed
10231           even if single stepping was never used.</li>
10232         <li>Still another VM might be able to add an "is single stepping on" check
10233           into compiled bytecodes or a generated interpreter.  Again in this implementation
10234           the capability would need to be added during the <code>OnLoad</code> phase but the overhead (a test
10235           and branch on each instruction) would be considerably less.</li>
10236       </ul>
10237       <p/>
10238       Each <jvmti/> <internallink id="environments">environment</internallink>
10239       has its own set of capabilities.
10240       Initially, that set is empty.
10241       Any desired capability must be added.
10242       If possible, capabilities should be added during the <code>OnLoad</code> phase.  For most
10243       virtual machines certain capabilities require special set up for
10244       the virtual machine and this set up must happen
10245       during the <code>OnLoad</code> phase, before the virtual machine begins execution.
10246       Once a capability is added, it can
10247       only be removed if explicitly relinquished by the environment.
10248       <p/>
10249       The agent can,
10250       <functionlink id="GetPotentialCapabilities">determine what
10251         capabilities this VM can potentially provide</functionlink>,
10252       <functionlink id="AddCapabilities">add the capabilities
10253         to be used</functionlink>,
10254       <functionlink id="RelinquishCapabilities">release capabilities
10255         which are no longer needed</functionlink>, and
10256       <functionlink id="GetCapabilities">examine the currently available
10257         capabilities</functionlink>.
10258     </intro>
10259 
10260     <intro id="capabilityExamples" label="Capability Examples">
10261       For example, a freshly started agent (in the <code>OnLoad</code> function)
10262       wants to enable all possible capabilities.
10263       Note that, in general, this is not advisable as the agent may suffer
10264       a performance penalty for functionality it is not using.
10265       The code might look like this in C:
10266       <example>
10267         jvmtiCapabilities capa;
10268         jvmtiError err;
10269 
10270         err = (*jvmti)-&gt;GetPotentialCapabilities(jvmti, &amp;capa);
10271         if (err == JVMTI_ERROR_NONE) {
10272            err = (*jvmti)-&gt;AddCapabilities(jvmti, &amp;capa);
10273       </example>
10274       For example, if an  agent wants to check if it can get
10275       the bytecodes of a method (that is, it wants to check
10276       if it previously added this capability and has not
10277       relinquished it), the code might
10278       look like this in C:
10279       <example>
10280         jvmtiCapabilities capa;
10281         jvmtiError err;
10282 
10283         err = (*jvmti)-&gt;GetCapabilities(jvmti, &amp;capa);
10284         if (err == JVMTI_ERROR_NONE) {
10285            if (capa.can_get_bytecodes) { ... } }
10286       </example>
10287     </intro>
10288 
10289     <capabilitiestypedef id="jvmtiCapabilities" label="The Capabilities Structure">
10290       <description>
10291         The functions in this category use this capabilities structure
10292         which contains boolean flags corresponding to each capability:
10293       </description>
10294       <capabilityfield id="can_tag_objects">
10295         <description>
10296           Can set and get tags, as described in the
10297           <internallink id="Heap">Heap category</internallink>.
10298         </description>
10299       </capabilityfield>
10300       <capabilityfield id="can_generate_field_modification_events">
10301         <description>
10302           Can set watchpoints on field modification -
10303           <functionlink id="SetFieldModificationWatch"></functionlink>
10304         </description>
10305       </capabilityfield>
10306       <capabilityfield id="can_generate_field_access_events">
10307         <description>
10308           Can set watchpoints on field access -
10309           <functionlink id="SetFieldAccessWatch"></functionlink>
10310         </description>
10311       </capabilityfield>
10312       <capabilityfield id="can_get_bytecodes">
10313         <description>
10314           Can get bytecodes of a method <functionlink id="GetBytecodes"></functionlink>
10315         </description>
10316       </capabilityfield>
10317       <capabilityfield id="can_get_synthetic_attribute">
10318         <description>
10319           Can test if a field or method is synthetic -
10320           <functionlink id="IsFieldSynthetic"></functionlink> and
10321           <functionlink id="IsMethodSynthetic"></functionlink>
10322         </description>
10323       </capabilityfield>
10324       <capabilityfield id="can_get_owned_monitor_info">
10325         <description>
10326           Can get information about ownership of monitors -
10327           <functionlink id="GetOwnedMonitorInfo"></functionlink>
10328         </description>
10329       </capabilityfield>
10330       <capabilityfield id="can_get_current_contended_monitor">
10331         <description>
10332           Can <functionlink id="GetCurrentContendedMonitor"></functionlink>
10333         </description>
10334       </capabilityfield>
10335       <capabilityfield id="can_get_monitor_info">
10336       <description>
10337         Can <functionlink id="GetObjectMonitorUsage"></functionlink>
10338       </description>
10339       </capabilityfield>
10340       <capabilityfield id="can_pop_frame">
10341         <description>
10342           Can pop frames off the stack - <functionlink id="PopFrame"></functionlink>
10343         </description>
10344       </capabilityfield>
10345       <capabilityfield id="can_redefine_classes">
10346         <description>
10347           Can redefine classes with <functionlink id="RedefineClasses"/>.
10348         </description>
10349       </capabilityfield>
10350       <capabilityfield id="can_signal_thread">
10351         <description>
10352           Can send stop or interrupt to threads
10353         </description>
10354       </capabilityfield>
10355       <capabilityfield id="can_get_source_file_name">
10356         <description>
10357           Can get the source file name of a class
10358         </description>
10359       </capabilityfield>
10360       <capabilityfield id="can_get_line_numbers">
10361         <description>
10362           Can get the line number table of a method
10363         </description>
10364       </capabilityfield>
10365       <capabilityfield id="can_get_source_debug_extension">
10366         <description>
10367           Can get the source debug extension of a class
10368         </description>
10369       </capabilityfield>
10370       <capabilityfield id="can_access_local_variables">
10371         <description>
10372           Can set and get local variables
10373         </description>
10374       </capabilityfield>
10375       <capabilityfield id="can_maintain_original_method_order">
10376         <description>
10377           Can return methods in the order they occur in the class file
10378         </description>
10379       </capabilityfield>
10380       <capabilityfield id="can_generate_single_step_events">
10381         <description>
10382           Can get <eventlink id="SingleStep">single step</eventlink> events
10383         </description>
10384       </capabilityfield>
10385       <capabilityfield id="can_generate_exception_events">
10386         <description>
10387           Can get <eventlink id="Exception">exception thrown</eventlink> and
10388             <eventlink id="ExceptionCatch">exception catch</eventlink> events
10389         </description>
10390       </capabilityfield>
10391       <capabilityfield id="can_generate_frame_pop_events">
10392         <description>
10393           Can <functionlink id="NotifyFramePop">set</functionlink> and thus get
10394             <eventlink id="FramePop"></eventlink> events
10395         </description>
10396       </capabilityfield>
10397       <capabilityfield id="can_generate_breakpoint_events">
10398         <description>
10399           Can <functionlink id="SetBreakpoint">set</functionlink> and thus get
10400             <eventlink id="Breakpoint"></eventlink> events
10401         </description>
10402       </capabilityfield>
10403       <capabilityfield id="can_suspend">
10404         <description>
10405           Can suspend and resume threads
10406         </description>
10407       </capabilityfield>
10408       <capabilityfield id="can_redefine_any_class">
10409         <description>
10410           <functionlink id="RedefineClasses"/> can be called on any modifiable class.
10411           See <functionlink id="IsModifiableClass"/>.
10412           (<fieldlink id="can_redefine_classes" struct="jvmtiCapabilities"/>
10413           must also be set)
10414         </description>
10415       </capabilityfield>
10416       <capabilityfield id="can_get_current_thread_cpu_time">
10417         <description>
10418           Can <functionlink id="GetCurrentThreadCpuTime">get</functionlink>
10419           current thread CPU time
10420         </description>
10421       </capabilityfield>
10422       <capabilityfield id="can_get_thread_cpu_time">
10423         <description>
10424           Can <functionlink id="GetThreadCpuTime">get</functionlink>
10425           thread CPU time
10426         </description>
10427       </capabilityfield>
10428       <capabilityfield id="can_generate_method_entry_events"
10429                        disp1="can_generate" disp2="_method_entry_events"
10430                        >
10431         <description>
10432           Can generate method entry events on entering a method
10433         </description>
10434       </capabilityfield>
10435       <capabilityfield id="can_generate_method_exit_events"
10436                        disp1="can_generate" disp2="_method_exit_events"
10437                        >
10438         <description>
10439           Can generate method exit events on leaving a method
10440         </description>
10441       </capabilityfield>
10442       <capabilityfield id="can_generate_all_class_hook_events"
10443                        disp1="can_generate" disp2="_all_class_hook_events"
10444                        >
10445         <description>
10446           Can generate ClassFileLoadHook events for every loaded class.
10447         </description>
10448       </capabilityfield>
10449       <capabilityfield id="can_generate_compiled_method_load_events"
10450                        disp1="can_generate" disp2="_compiled_method_load_events"
10451                        >
10452         <description>
10453           Can generate events when a method is compiled or unloaded
10454         </description>
10455       </capabilityfield>
10456       <capabilityfield id="can_generate_monitor_events"
10457                        disp1="can_generate" disp2="_monitor_events"
10458                        >
10459         <description>
10460           Can generate events on monitor activity
10461         </description>
10462       </capabilityfield>
10463       <capabilityfield id="can_generate_vm_object_alloc_events"
10464                        disp1="can_generate" disp2="_vm_object_alloc_events"
10465                        >
10466         <description>
10467           Can generate events on VM allocation of an object
10468         </description>
10469       </capabilityfield>
10470       <capabilityfield id="can_generate_native_method_bind_events"
10471                        disp1="can_generate" disp2="_native_method_bind_events"
10472                        >
10473         <description>
10474           Can generate events when a native method is bound to its
10475           implementation
10476         </description>
10477       </capabilityfield>
10478       <capabilityfield id="can_generate_garbage_collection_events"
10479                        disp1="can_generate" disp2="_garbage_collection_events"
10480                        >
10481         <description>
10482           Can generate events when garbage collection begins or ends
10483         </description>
10484       </capabilityfield>
10485       <capabilityfield id="can_generate_object_free_events"
10486                        disp1="can_generate" disp2="_object_free_events"
10487                        >
10488         <description>
10489           Can generate events when the garbage collector frees an object
10490         </description>
10491       </capabilityfield>
10492       <capabilityfield id="can_force_early_return" since="1.1">
10493         <description>
10494           Can return early from a method, as described in the
10495           <internallink id="ForceEarlyReturn">Force Early Return category</internallink>.
10496         </description>
10497       </capabilityfield>
10498       <capabilityfield id="can_get_owned_monitor_stack_depth_info" since="1.1">
10499         <description>
10500           Can get information about owned monitors with stack depth -
10501           <functionlink id="GetOwnedMonitorStackDepthInfo"></functionlink>
10502         </description>
10503       </capabilityfield>
10504       <capabilityfield id="can_get_constant_pool" since="1.1">
10505         <description>
10506           Can get the constant pool of a class -
10507           <functionlink id="GetConstantPool"></functionlink>
10508         </description>
10509       </capabilityfield>
10510       <capabilityfield id="can_set_native_method_prefix" since="1.1">
10511         <description>
10512           Can set prefix to be applied when native method cannot be resolved -
10513           <functionlink id="SetNativeMethodPrefix"/> and
10514           <functionlink id="SetNativeMethodPrefixes"/>
10515         </description>
10516       </capabilityfield>
10517       <capabilityfield id="can_retransform_classes" since="1.1">
10518         <description>
10519           Can retransform classes with <functionlink id="RetransformClasses"/>.
10520           In addition to the restrictions imposed by the specific
10521           implementation on this capability (see the
10522           <internallink id="capability">Capability</internallink> section),
10523           this capability must be set before the
10524           <eventlink id="ClassFileLoadHook"/> event is enabled for the
10525           first time in this environment.
10526           An environment that possesses this capability at the time that
10527           <code>ClassFileLoadHook</code> is enabled for the first time is
10528           said to be <i>retransformation capable</i>.
10529           An environment that does not possess this capability at the time that
10530           <code>ClassFileLoadHook</code> is enabled for the first time is
10531           said to be <i>retransformation incapable</i>.
10532         </description>
10533       </capabilityfield>
10534       <capabilityfield id="can_retransform_any_class" since="1.1">
10535         <description>
10536           <functionlink id="RetransformClasses"/> can be called on any modifiable class.
10537           See <functionlink id="IsModifiableClass"/>.
10538           (<fieldlink id="can_retransform_classes" struct="jvmtiCapabilities"/>
10539           must also be set)
10540         </description>
10541       </capabilityfield>
10542       <capabilityfield id="can_generate_resource_exhaustion_heap_events" since="1.1">
10543         <description>
10544           Can generate events when the VM is unable to allocate memory from
10545           the <tm>Java</tm> platform heap.
10546           See <eventlink id="ResourceExhausted"/>.
10547         </description>
10548       </capabilityfield>
10549       <capabilityfield id="can_generate_resource_exhaustion_threads_events" since="1.1">
10550         <description>
10551           Can generate events when the VM is unable to create a thread.
10552           See <eventlink id="ResourceExhausted"/>.
10553         </description>
10554       </capabilityfield>
10555       <capabilityfield id="can_generate_early_vmstart" since="9">
10556         <description>
10557           Can generate the <code>VMStart</code> event early.
10558           See <eventlink id="VMStart"/>.
10559         </description>
10560       </capabilityfield>
10561       <capabilityfield id="can_generate_early_class_hook_events" since="9">
10562         <description>
10563           Can generate the <eventlink id="ClassFileLoadHook"/> events
10564           in the primordial phase. If this capability and
10565           <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
10566           <code>can_generate_all_class_hook_events</code></internallink>
10567           are enabled then the <eventlink id="ClassFileLoadHook"/> events
10568           can be posted for classes loaded in the primordial phase.
10569           See <eventlink id="ClassFileLoadHook"/>.
10570         </description>
10571       </capabilityfield>
10572       <capabilityfield id="can_generate_sampled_object_alloc_events" since="11">
10573         <description>
10574           Can generate sampled allocation events.
10575           If this capability is enabled then the heap sampling method
10576           <functionlink id="SetHeapSamplingInterval"></functionlink> can be
10577           called and <eventlink id="SampledObjectAlloc"></eventlink> events can be generated.
10578         </description>
10579       </capabilityfield>
10580       <capabilityfield id="can_support_virtual_threads" since="14">
10581         <description>
10582           <b> can_support_virtual_threads is a preview API of the Java platform. </b>
10583           <i>Preview features may be removed in a future release, or upgraded to
10584           permanent features of the Java platform.</i>.
10585           <p/>
10586           Can support virtual threads.
10587           If this capability is enabled then the following functions can be called:
10588           <functionlink id="SuspendAllVirtualThreads"></functionlink>, 
10589           <functionlink id="ResumeAllVirtualThreads"></functionlink>,
10590           and the following events can be enabled:
10591           <eventlink id="VirtualThreadStart"></eventlink>,
10592           <eventlink id="VirtualThreadEnd"></eventlink>,
10593         </description>
10594       </capabilityfield>
10595     </capabilitiestypedef>
10596 
10597     <function id="GetPotentialCapabilities" jkernel="yes" phase="onload" num="140">
10598       <synopsis>Get Potential Capabilities</synopsis>
10599       <description>
10600         Returns via <paramlink id="capabilities_ptr"></paramlink> the <jvmti/>
10601         features that can potentially be possessed by this environment
10602         at this time.
10603         The returned capabilities differ from the complete set of capabilities
10604         implemented by the VM in two cases: another environment possesses
10605         capabilities that can only be possessed by one environment, or the
10606         current <functionlink id="GetPhase">phase</functionlink> is live,
10607         and certain capabilities can only be added during the <code>OnLoad</code> phase.
10608         The <functionlink id="AddCapabilities"></functionlink> function
10609         may be used to set any or all or these capabilities.
10610         Currently possessed capabilities are included.
10611         <p/>
10612         Typically this function is used in the <code>OnLoad</code> function.
10613         Some virtual machines may allow a limited set of capabilities to be
10614         added in the live phase.
10615         In this case, the set of potentially available capabilities
10616         will likely differ from the <code>OnLoad</code> phase set.
10617         <p/>
10618         See the
10619         <internallink id="capabilityExamples">Capability Examples</internallink>.
10620       </description>
10621       <origin>new</origin>
10622       <capabilities>
10623       </capabilities>
10624       <parameters>
10625         <param id="capabilities_ptr">
10626           <outptr><struct>jvmtiCapabilities</struct></outptr>
10627           <description>
10628             On return, points to the <jvmti/> capabilities that may be added.
10629           </description>
10630         </param>
10631       </parameters>
10632       <errors>
10633       </errors>
10634     </function>
10635 
10636     <elide>
10637     <function id="EstimateCostOfCapabilities" phase="onload" num="141">
10638       <synopsis>Estimate Cost Of Capabilities</synopsis>
10639       <description>
10640         <issue>There is strong opposition to this function.  The concern is
10641           that it would be difficult or impossible to provide meaningful
10642           numbers, as the amount of impact is conditional on many factors
10643           that a single number could not represent.  There is doubt that
10644           conditional implementations would be used or are even a good idea.
10645           The thought is that release documentation for the implementation
10646           would be the best means of exposing this information.
10647           Unless new arguments are presented, I intend to remove this
10648           function in the next revision.
10649         </issue>
10650         <p/>
10651         Return via the <paramlink id="time_impact_ptr"></paramlink> and
10652         <paramlink id="space_impact_ptr"></paramlink> an estimate of the impact
10653         of adding the capabilities pointed to by
10654         <paramlink id="capabilities_ptr"></paramlink>.
10655         The returned estimates are in percentage of additional overhead, thus
10656         a time impact of 100 mean the application might run
10657         at half the speed.
10658         The estimates are very rough approximations and are not guaranteed.
10659         Note also, that the estimates are of the impact of having the
10660         capability available--when and if it is used the impact may be
10661         much greater.
10662         Estimates can be for a single capability or for a set of
10663         capabilities.  Note that the costs are not necessarily additive,
10664         adding support for one capability might make another available
10665         for free or conversely having two capabilities at once may
10666         have multiplicative impact.
10667         Estimates are relative to the current set of capabilities -
10668         that is, how much more impact given the currently possessed capabilities.
10669         <p/>
10670         Typically this function is used in the OnLoad function,
10671         some virtual machines may allow a limited set of capabilities to be
10672         added in the live phase.
10673         In this case, the set of potentially available capabilities
10674         will likely differ from the OnLoad phase set.
10675         <p/>
10676         See the
10677         <internallink id="capabilityExamples">Capability Examples</internallink>.
10678       </description>
10679       <origin>new</origin>
10680       <capabilities>
10681       </capabilities>
10682       <parameters>
10683         <param id="capabilities_ptr">
10684           <inptr><struct>jvmtiCapabilities</struct></inptr>
10685           <description>
10686             points to the <jvmti/> capabilities to evaluate.
10687           </description>
10688         </param>
10689         <param id="time_impact_ptr">
10690           <outptr><jint/></outptr>
10691           <description>
10692             On return, points to the estimated percentage increase in
10693             run time if this capability was added.
10694           </description>
10695         </param>
10696         <param id="space_impact_ptr">
10697           <outptr><jint/></outptr>
10698           <description>
10699             On return, points to the estimated percentage increase in
10700             memory space used if this capability was added.
10701           </description>
10702         </param>
10703       </parameters>
10704       <errors>
10705         <error id="JVMTI_ERROR_NOT_AVAILABLE">
10706           The desired capabilities are not even potentially available.
10707         </error>
10708       </errors>
10709     </function>
10710     </elide>
10711 
10712     <function id="AddCapabilities" jkernel="yes" phase="onload" num="142">
10713       <synopsis>Add Capabilities</synopsis>
10714       <description>
10715         Set new capabilities by adding the capabilities
10716         whose values are set to one (<code>1</code>) in
10717         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10718         All previous capabilities are retained.
10719         Typically this function is used in the <code>OnLoad</code> function.
10720         Some virtual machines may allow a limited set of capabilities to be
10721         added in the live phase.
10722         <p/>
10723         See the
10724         <internallink id="capabilityExamples">Capability Examples</internallink>.
10725       </description>
10726       <origin>new</origin>
10727       <capabilities>
10728       </capabilities>
10729       <parameters>
10730         <param id="capabilities_ptr">
10731           <inptr><struct>jvmtiCapabilities</struct></inptr>
10732           <description>
10733             Points to the <jvmti/> capabilities to add.
10734           </description>
10735         </param>
10736       </parameters>
10737       <errors>
10738         <error id="JVMTI_ERROR_NOT_AVAILABLE">
10739           The desired capabilities are not even potentially available.
10740         </error>
10741       </errors>
10742     </function>
10743 
10744 
10745     <function id="RelinquishCapabilities" phase="onload" num="143">
10746       <synopsis>Relinquish Capabilities</synopsis>
10747       <description>
10748         Relinquish the capabilities
10749         whose values are set to one (<code>1</code>) in
10750         <code>*</code><paramlink id="capabilities_ptr"></paramlink>.
10751         Some implementations may allow only one environment to have a capability
10752         (see the <internallink id="capability">capability introduction</internallink>).
10753         This function releases capabilities
10754         so that they may be used by other agents.
10755         All other capabilities are retained.
10756         The capability will no longer be present in <functionlink id="GetCapabilities"></functionlink>.
10757         Attempting to relinquish a capability that the agent does not possess is not an error.
10758           <issue>
10759             It is possible for the agent to be actively using capabilities
10760             which are being relinquished.  For example, a thread is currently
10761             suspended and can_suspend is being relinquished or an event is currently
10762             enabled and can_generate_whatever is being relinquished.
10763             There are three possible ways we could spec this:
10764             <ul>
10765               <li>relinquish automatically releases them</li>
10766               <li>relinquish checks and returns some error code if held</li>
10767               <li>it is the agent's responsibility and it is not checked</li>
10768             </ul>
10769             One of these should be chosen.
10770           </issue>
10771       </description>
10772       <origin>new</origin>
10773       <capabilities>
10774       </capabilities>
10775       <parameters>
10776         <param id="capabilities_ptr">
10777           <inptr><struct>jvmtiCapabilities</struct></inptr>
10778           <description>
10779             Points to the <jvmti/> capabilities to relinquish.
10780           </description>
10781         </param>
10782       </parameters>
10783       <errors>
10784       </errors>
10785     </function>
10786 
10787 
10788 
10789     <function id="GetCapabilities" jkernel="yes" phase="any" num="89">
10790       <synopsis>Get Capabilities</synopsis>
10791         <description>
10792           Returns via <paramlink id="capabilities_ptr"></paramlink> the optional <jvmti/>
10793           features which this environment currently possesses.
10794           Each possessed capability is indicated by a one (<code>1</code>) in the
10795           corresponding field of the <internallink id="jvmtiCapabilities">capabilities
10796           structure</internallink>.
10797           An environment does not possess a capability unless it has been successfully added with
10798           <functionlink id="AddCapabilities"/>.
10799           An environment only loses possession of a capability if it has been relinquished with
10800           <functionlink id="RelinquishCapabilities"/>. Thus, this function returns the net result
10801           of the <code>AddCapabilities</code> and <code>RelinquishCapabilities</code> calls which
10802           have been made.
10803           <p/>
10804           See the
10805           <internallink id="capabilityExamples">Capability Examples</internallink>.
10806         </description>
10807       <origin>jvmdiClone</origin>
10808       <capabilities>
10809       </capabilities>
10810       <parameters>
10811         <param id="capabilities_ptr">
10812           <outptr><struct>jvmtiCapabilities</struct></outptr>
10813           <description>
10814             On return, points to the <jvmti/> capabilities.
10815           </description>
10816         </param>
10817       </parameters>
10818       <errors>
10819       </errors>
10820     </function>
10821 
10822   </category>
10823 
10824 
10825   <category id="timers" label="Timers">
10826 
10827       <intro>
10828         These functions provide timing information.
10829         The resolution at which the time is updated is not specified.
10830         They provides nanosecond precision, but not necessarily nanosecond accuracy.
10831         Details about the timers, such as their maximum values, can be accessed with
10832         the timer information functions.
10833       </intro>
10834 
10835       <typedef id="jvmtiTimerInfo" label="Timer Info">
10836         <description>
10837           The information function for each timer returns this data structure.
10838         </description>
10839         <field id="max_value">
10840           <jlong/>
10841             <description>
10842               The maximum value the timer can reach.
10843               After this value is reached the timer wraps back to zero.
10844               This is an unsigned value.  If tested or printed as a jlong (signed value)
10845               it may appear to be a negative number.
10846             </description>
10847         </field>
10848         <field id="may_skip_forward">
10849           <jboolean/>
10850           <description>
10851             If true, the timer can be externally adjusted and as a result skip forward.
10852             If false, the timer value will never increase faster than real time.
10853           </description>
10854         </field>
10855         <field id="may_skip_backward">
10856           <jboolean/>
10857           <description>
10858             If true, the timer can be externally adjusted and as a result skip backward.
10859             If false, the timer value will be monotonically increasing.
10860           </description>
10861         </field>
10862         <field id="kind">
10863           <enum>jvmtiTimerKind</enum>
10864           <description>
10865             The kind of timer.
10866             On a platform that does not distinguish between user and system time, <datalink
10867                  id="JVMTI_TIMER_TOTAL_CPU"><code>JVMTI_TIMER_TOTAL_CPU</code></datalink>
10868             is returned.
10869           </description>
10870         </field>
10871         <field id="reserved1">
10872           <jlong/>
10873             <description>
10874               Reserved for future use.
10875             </description>
10876         </field>
10877         <field id="reserved2">
10878           <jlong/>
10879             <description>
10880               Reserved for future use.
10881             </description>
10882         </field>
10883       </typedef>
10884 
10885       <intro>
10886         Where the timer kind is --
10887 
10888         <constants id="jvmtiTimerKind" label="Timer Kinds" kind="enum">
10889           <constant id="JVMTI_TIMER_USER_CPU" num="30">
10890             CPU time that a thread is in user mode.
10891           </constant>
10892           <constant id="JVMTI_TIMER_TOTAL_CPU" num="31">
10893             CPU time that a thread is in user or system mode.
10894           </constant>
10895           <constant id="JVMTI_TIMER_ELAPSED" num="32">
10896             Elapsed time.
10897           </constant>
10898         </constants>
10899       </intro>
10900 
10901     <function id="GetCurrentThreadCpuTimerInfo" callbacksafe="safe"  impl="innative notrace" phase="start" num="134">
10902       <synopsis>Get Current Thread CPU Timer Information</synopsis>
10903       <description>
10904         Get information about the
10905         <functionlink id="GetCurrentThreadCpuTime"/> timer.
10906         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10907         are filled in with details about the timer.
10908         This information is specific to the platform and the implementation of
10909         <functionlink id="GetCurrentThreadCpuTime"/> and thus
10910         does not vary by thread nor does it vary
10911         during a particular invocation of the VM.
10912         <p/>
10913         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
10914         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
10915         returned by <code>GetCurrentThreadCpuTimerInfo</code>
10916         and <functionlink id="GetThreadCpuTimerInfo"/>
10917         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
10918       </description>
10919       <origin>new</origin>
10920       <capabilities>
10921         <required id="can_get_current_thread_cpu_time">
10922             Can get current thread CPU time.
10923         </required>
10924       </capabilities>
10925       <parameters>
10926         <param id="info_ptr">
10927           <outptr><struct>jvmtiTimerInfo</struct></outptr>
10928           <description>
10929             On return, filled with information describing the time
10930             returned by <functionlink id="GetCurrentThreadCpuTime"/>.
10931           </description>
10932         </param>
10933       </parameters>
10934       <errors>
10935       </errors>
10936     </function>
10937 
10938     <function id="GetCurrentThreadCpuTime" callbacksafe="safe" impl="innative notrace" phase="start" num="135">
10939       <synopsis>Get Current Thread CPU Time</synopsis>
10940       <description>
10941             Return the CPU time utilized by the current thread.
10942             <p/>
10943             Note that the <functionlink id="GetThreadCpuTime"/>
10944             function provides CPU time for any thread, including
10945             the current thread. <code>GetCurrentThreadCpuTime</code>
10946             exists to support platforms which cannot
10947             supply CPU time for threads other than the current
10948             thread or which have more accurate information for
10949             the current thread (see
10950             <functionlink id="GetCurrentThreadCpuTimerInfo"/> vs
10951             <functionlink id="GetThreadCpuTimerInfo"/>).
10952             The current thread may not be a virtual thread. Otherwise, the error code
10953             <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
10954             On many platforms this call will be equivalent to:
10955 <example>
10956   GetThreadCpuTime(env, NULL, nanos_ptr)
10957 </example>
10958       </description>
10959       <origin>new</origin>
10960       <capabilities>
10961         <required id="can_get_current_thread_cpu_time">
10962             Can get current thread CPU time.
10963             <p/>
10964             If this capability is enabled after threads have started,
10965             the implementation may choose any time up
10966             to and including the time that the capability is enabled
10967             as the point where CPU time collection starts.
10968             <p/>
10969             This capability must be potentially available on any
10970             platform where
10971             <internallink id="jvmtiCapabilities.can_get_thread_cpu_time"><code>can_get_thread_cpu_time</code></internallink>
10972             is potentially available.
10973         </required>
10974       </capabilities>
10975       <parameters>
10976         <param id="nanos_ptr">
10977           <outptr><jlong/></outptr>
10978           <description>
10979             On return, points to the CPU time used by this thread
10980             in nanoseconds.
10981             This is an unsigned value.  If tested or printed as a jlong (signed value)
10982             it may appear to be a negative number.
10983           </description>
10984         </param>
10985       </parameters>
10986       <errors>
10987         <error id="JVMTI_ERROR_INVALID_THREAD">
10988           Current thread is a virtual thread.
10989         </error>
10990       </errors>
10991     </function>
10992 
10993     <function id="GetThreadCpuTimerInfo" num="136">
10994       <synopsis>Get Thread CPU Timer Information</synopsis>
10995       <description>
10996         Get information about the
10997         <functionlink id="GetThreadCpuTime"/> timer.
10998         The fields of the <datalink id="jvmtiTimerInfo"/> structure
10999         are filled in with details about the timer.
11000         This information is specific to the platform and the implementation of
11001         <functionlink id="GetThreadCpuTime"/> and thus
11002         does not vary by thread nor does it vary
11003         during a particular invocation of the VM.
11004         <p/>
11005         Note that the implementations of <functionlink id="GetCurrentThreadCpuTime"/>
11006         and <functionlink id="GetThreadCpuTime"/> may differ, and thus the values
11007         returned by <functionlink id="GetCurrentThreadCpuTimerInfo"/>
11008         and <code>GetThreadCpuTimerInfo</code>
11009         may differ -- see <functionlink id="GetCurrentThreadCpuTime"/> for more information.
11010       </description>
11011       <origin>new</origin>
11012       <capabilities>
11013         <required id="can_get_thread_cpu_time">
11014             Can get thread CPU time.
11015         </required>
11016       </capabilities>
11017       <parameters>
11018         <param id="info_ptr">
11019           <outptr><struct>jvmtiTimerInfo</struct></outptr>
11020           <description>
11021             On return, filled with information describing the time
11022             returned by <functionlink id="GetThreadCpuTime"/>.
11023           </description>
11024         </param>
11025       </parameters>
11026       <errors>
11027       </errors>
11028     </function>
11029 
11030     <function id="GetThreadCpuTime" num="137">
11031       <synopsis>Get Thread CPU Time</synopsis>
11032       <description>
11033           Return the CPU time utilized by the specified thread.
11034           <p/>
11035           Get information about this timer with
11036           <functionlink id="GetThreadCpuTimerInfo"/>.
11037       </description>
11038       <origin>new</origin>
11039       <capabilities>
11040         <required id="can_get_thread_cpu_time">
11041             Can get thread CPU time.
11042             <p/>
11043             If this capability is enabled after threads have started,
11044             the implementation may choose any time up
11045             to and including the time that the capability is enabled
11046             as the point where CPU time collection starts.
11047         </required>
11048       </capabilities>
11049       <parameters>
11050         <param id="thread">
11051           <jthread null="current"/>
11052             <description>
11053               The thread to query.
11054               The <code>thread</code> may not be a virtual thread. Otherwise, the error code
11055                <errorlink id="JVMTI_ERROR_INVALID_THREAD"></errorlink> will be returned.
11056              </description>
11057         </param>
11058         <param id="nanos_ptr">
11059           <outptr><jlong/></outptr>
11060           <description>
11061             On return, points to the CPU time used by the specified thread
11062             in nanoseconds.
11063             This is an unsigned value.  If tested or printed as a jlong (signed value)
11064             it may appear to be a negative number.
11065           </description>
11066         </param>
11067       </parameters>
11068       <errors>
11069         <error id="JVMTI_ERROR_INVALID_THREAD">
11070           <paramlink id="thread"/> is a virtual thread.
11071         </error>
11072       </errors>
11073     </function>
11074 
11075     <function id="GetTimerInfo" phase="any" callbacksafe="safe" num="138">
11076       <synopsis>Get Timer Information</synopsis>
11077       <description>
11078         Get information about the
11079         <functionlink id="GetTime"/> timer.
11080         The fields of the <datalink id="jvmtiTimerInfo"/> structure
11081         are filled in with details about the timer.
11082         This information will not change during a particular invocation of the VM.
11083       </description>
11084       <origin>new</origin>
11085       <capabilities>
11086       </capabilities>
11087       <parameters>
11088         <param id="info_ptr">
11089           <outptr><struct>jvmtiTimerInfo</struct></outptr>
11090           <description>
11091             On return, filled with information describing the time
11092             returned by <functionlink id="GetTime"/>.
11093           </description>
11094         </param>
11095       </parameters>
11096       <errors>
11097       </errors>
11098     </function>
11099 
11100     <function id="GetTime" phase="any" callbacksafe="safe" num="139">
11101       <synopsis>Get Time</synopsis>
11102       <description>
11103           Return the current value of the system timer, in nanoseconds.
11104           <p/>
11105           The value returned represents nanoseconds since some fixed but
11106           arbitrary time (perhaps in the future, so values may be
11107           negative).  This function provides nanosecond precision, but not
11108           necessarily nanosecond accuracy. No guarantees are made about
11109           how frequently values change.
11110           <p/>
11111           Get information about this timer with
11112           <functionlink id="GetTimerInfo"/>.
11113       </description>
11114       <origin>new</origin>
11115       <capabilities>
11116       </capabilities>
11117       <parameters>
11118         <param id="nanos_ptr">
11119           <outptr><jlong/></outptr>
11120           <description>
11121             On return, points to the time in nanoseconds.
11122             This is an unsigned value.  If tested or printed as a jlong (signed value)
11123             it may appear to be a negative number.
11124           </description>
11125         </param>
11126       </parameters>
11127       <errors>
11128       </errors>
11129     </function>
11130 
11131     <function id="GetAvailableProcessors" phase="any" num="144">
11132       <synopsis>Get Available Processors</synopsis>
11133       <description>
11134           Returns the number of processors available to the Java virtual machine.
11135           <p/>
11136           This value may change during a particular invocation of the virtual machine.
11137           Applications that are sensitive to the number of available processors should
11138           therefore occasionally poll this property.
11139       </description>
11140       <origin>new</origin>
11141       <capabilities>
11142       </capabilities>
11143       <parameters>
11144         <param id="processor_count_ptr">
11145           <outptr><jint/></outptr>
11146           <description>
11147             On return, points to the maximum number of processors available to the
11148             virtual machine; never smaller than one.
11149           </description>
11150         </param>
11151       </parameters>
11152       <errors>
11153       </errors>
11154     </function>
11155 
11156   </category>
11157 
11158 
11159   <category id="classLoaderSearch" label="Class Loader Search">
11160 
11161     <intro>
11162       These functions allow the agent to add to the locations that a class loader searches for a class.
11163       This is useful for installing instrumentation under the correct class loader.
11164     </intro>
11165 
11166     <function id="AddToBootstrapClassLoaderSearch" jkernel="yes" phase="onload" num="149">
11167       <synopsis>Add To Bootstrap Class Loader Search</synopsis>
11168       <description>
11169           This function can be used to cause instrumentation classes to be defined by the
11170           bootstrap class loader. See <vmspec chapter="5.3.1"/>.
11171           After the bootstrap
11172           class loader unsuccessfully searches for a class, the specified platform-dependent
11173           search path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in
11174           the <paramlink id="segment"/>. This function may be called multiple times to add multiple segments,
11175           the segments will be searched in the order that this function was called.
11176           <p/>
11177           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
11178           search path segment to be searched after the bootstrap class loader unsuccessfully searches
11179           for a class. The segment is typically a directory or JAR file.
11180           <p/>
11181           In the live phase the <paramlink id="segment"/> may be used to specify any platform-dependent
11182           path to a <externallink id="jar/jar.html">
11183           JAR file</externallink>. The agent should take care that the JAR file does not
11184           contain any classes or resources other than those to be defined by the bootstrap
11185           class loader for the purposes of instrumentation.
11186           <p/>
11187           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
11188           reference that the Java virtual machine has previously unsuccessfully attempted
11189           to resolve always fails with the same error that was thrown as a result of the
11190           initial resolution attempt. Consequently, if the JAR file contains an entry
11191           that corresponds to a class for which the Java virtual machine has
11192           unsuccessfully attempted to resolve a reference, then subsequent attempts to
11193           resolve that reference will fail with the same error as the initial attempt.
11194       </description>
11195       <origin>new</origin>
11196       <capabilities>
11197       </capabilities>
11198       <parameters>
11199         <param id="segment">
11200           <inbuf><char/></inbuf>
11201           <description>
11202             The platform-dependent search path segment, encoded as a
11203             <internallink id="mUTF">modified UTF-8</internallink> string.
11204           </description>
11205         </param>
11206       </parameters>
11207       <errors>
11208         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11209           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
11210            existing JAR file is an invalid path.
11211         </error>
11212       </errors>
11213     </function>
11214 
11215     <function id="AddToSystemClassLoaderSearch" jkernel="yes" phase="onload" num="151" since="1.1">
11216       <synopsis>Add To System Class Loader Search</synopsis>
11217       <description>
11218           This function can be used to cause instrumentation classes to be
11219           defined by the system class loader. See <vmspec chapter="5.3.2"/>.
11220           After the class loader unsuccessfully searches for a class, the specified platform-dependent search
11221           path <paramlink id="segment"/> will be searched as well. Only one segment may be specified in the
11222           <paramlink id="segment"/>. This function may be called multiple times to add multiple segments, the
11223           segments will be searched in the order that this function was called.
11224           <p/>
11225           In the <code>OnLoad</code> phase the function may be used to specify any platform-dependent
11226           search path segment to be searched after the system class loader unsuccessfully searches
11227           for a class. The segment is typically a directory or JAR file.
11228           <p/>
11229           In the live phase the <paramlink id="segment"/> is a platform-dependent path to a
11230           <externallink id="jar/jar.html">JAR file</externallink> to be
11231           searched after the system class loader unsuccessfully searches for a class. The agent should
11232           take care that the JAR file does not contain any classes or resources other than those to be
11233           defined by the system class loader for the purposes of instrumentation.
11234           <p/>
11235           In the live phase the system class loader supports adding a JAR file to be searched if
11236           the system class loader implements a method name <code>appendToClassPathForInstrumentation</code>
11237           which takes a single parameter of type <code>java.lang.String</code>. The method is not required
11238           to have <code>public</code> access.
11239           <p/>
11240           <vmspec/> specifies that a subsequent attempt to resolve a symbolic
11241           reference that the Java virtual machine has previously unsuccessfully attempted
11242           to resolve always fails with the same error that was thrown as a result of the
11243           initial resolution attempt. Consequently, if the JAR file contains an entry
11244           that corresponds to a class for which the Java virtual machine has
11245           unsuccessfully attempted to resolve a reference, then subsequent attempts to
11246           resolve that reference will fail with the same error as the initial attempt.
11247       </description>
11248       <origin>new</origin>
11249       <capabilities>
11250       </capabilities>
11251       <parameters>
11252         <param id="segment">
11253           <inbuf><char/></inbuf>
11254           <description>
11255             The platform-dependent search path segment, encoded as a
11256             <internallink id="mUTF">modified UTF-8</internallink> string.
11257           </description>
11258         </param>
11259       </parameters>
11260       <errors>
11261         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11262           <paramlink id="segment"/> is an invalid path. In the live phase, anything other than an
11263            existing JAR file is an invalid path.
11264         </error>
11265         <error id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED">
11266           Operation not supported by the system class loader.
11267         </error>
11268       </errors>
11269     </function>
11270 
11271   </category>
11272 
11273 
11274   <category id="props" label="System Properties">
11275 
11276     <intro>
11277       These functions get and set system properties.
11278     </intro>
11279 
11280     <function id="GetSystemProperties" phase="onload" num="130">
11281       <synopsis>Get System Properties</synopsis>
11282       <description>
11283         The list of VM system property keys which may be used with
11284         <functionlink id="GetSystemProperty"/> is returned.
11285         It is strongly recommended that virtual machines provide the
11286         following property keys:
11287         <ul>
11288           <li><code>java.vm.vendor</code></li>
11289           <li><code>java.vm.version</code></li>
11290           <li><code>java.vm.name</code></li>
11291           <li><code>java.vm.info</code></li>
11292           <li><code>java.library.path</code></li>
11293           <li><code>java.class.path</code></li>
11294         </ul>
11295         Provides access to system properties defined by and used
11296         by the VM.
11297         Properties set on the command-line are included.
11298         This allows getting and setting of these properties
11299         before the VM even begins executing bytecodes.
11300         Since this is a VM view of system properties, the set of available
11301         properties will usually be different than that
11302         in <code>java.lang.System.getProperties</code>.
11303         JNI method invocation may be used to access
11304         <code>java.lang.System.getProperties</code>.
11305         <p/>
11306         The set of properties may grow during execution.
11307       </description>
11308       <origin>new</origin>
11309       <capabilities>
11310       </capabilities>
11311       <parameters>
11312         <param id="count_ptr">
11313           <outptr><jint/></outptr>
11314           <description>
11315             On return, points to the number of property keys returned.
11316           </description>
11317         </param>
11318         <param id="property_ptr">
11319           <allocallocbuf outcount="count_ptr"><char/></allocallocbuf>
11320           <description>
11321             On return, points to an array of property keys, encoded as
11322             <internallink id="mUTF">modified UTF-8</internallink> strings.
11323           </description>
11324         </param>
11325       </parameters>
11326       <errors>
11327       </errors>
11328     </function>
11329 
11330     <function id="GetSystemProperty" phase="onload" num="131">
11331       <synopsis>Get System Property</synopsis>
11332       <description>
11333         Return a VM system property value given the property key.
11334         <p/>
11335         The function <functionlink id="GetSystemProperties"/>
11336         returns the set of property keys which may be used.
11337         The properties which can be retrieved may grow during
11338         execution.
11339         <p/>
11340         Since this is a VM view of system properties, the values
11341         of properties may differ from that returned by
11342         <code>java.lang.System.getProperty(String)</code>.
11343         A typical VM might copy the values of the VM system
11344         properties into the <code>Properties</code> held by
11345         <code>java.lang.System</code> during the initialization
11346         of that class. Thereafter any changes to the VM system
11347         properties (with <functionlink id="SetSystemProperty"/>)
11348         or the <code>java.lang.System</code> system properties
11349         (with <code>java.lang.System.setProperty(String,String)</code>)
11350         would cause the values to diverge.
11351         JNI method invocation may be used to access
11352         <code>java.lang.System.getProperty(String)</code>.
11353       </description>
11354       <origin>new</origin>
11355       <capabilities>
11356       </capabilities>
11357       <parameters>
11358         <param id="property">
11359           <inbuf><char/></inbuf>
11360           <description>
11361             The key of the property to retrieve, encoded as a
11362             <internallink id="mUTF">modified UTF-8</internallink> string.
11363           </description>
11364         </param>
11365         <param id="value_ptr">
11366           <allocbuf><char/></allocbuf>
11367           <description>
11368             On return, points to the property value, encoded as a
11369             <internallink id="mUTF">modified UTF-8</internallink> string.
11370           </description>
11371         </param>
11372       </parameters>
11373       <errors>
11374         <error id="JVMTI_ERROR_NOT_AVAILABLE">
11375           This property is not available.
11376           Use <functionlink id="GetSystemProperties"/> to find available properties.
11377         </error>
11378       </errors>
11379     </function>
11380 
11381     <function id="SetSystemProperty" phase="onloadOnly" num="132">
11382       <synopsis>Set System Property</synopsis>
11383       <description>
11384         Set a VM system property value.
11385         <p/>
11386         The function <functionlink id="GetSystemProperties"/>
11387         returns the set of property keys, some of these may be settable.
11388         See <functionlink id="GetSystemProperty"/>.
11389       </description>
11390       <origin>new</origin>
11391       <capabilities>
11392       </capabilities>
11393       <parameters>
11394         <param id="property">
11395           <inbuf><char/></inbuf>
11396           <description>
11397             The key of the property, encoded as a
11398             <internallink id="mUTF">modified UTF-8</internallink> string.
11399           </description>
11400         </param>
11401         <param id="value_ptr">
11402           <inbuf>
11403             <char/>
11404             <nullok>
11405               do not set the value, but return <errorlink id="JVMTI_ERROR_NOT_AVAILABLE"/>
11406               if the property is not writeable
11407             </nullok>
11408           </inbuf>
11409           <description>
11410             The property value to set, encoded as a
11411             <internallink id="mUTF">modified UTF-8</internallink> string.
11412           </description>
11413         </param>
11414       </parameters>
11415       <errors>
11416         <error id="JVMTI_ERROR_NOT_AVAILABLE">
11417           This property is not available or is not writeable.
11418         </error>
11419       </errors>
11420     </function>
11421 
11422   </category>
11423 
11424   <category id="general" label="General">
11425 
11426     <intro>
11427     </intro>
11428 
11429     <function id="GetPhase" jkernel="yes" phase="any" num="133">
11430       <synopsis>Get Phase</synopsis>
11431       <description>
11432           Return the current phase of VM execution.
11433           The phases proceed in sequence:
11434           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
11435             <constant id="JVMTI_PHASE_ONLOAD" num="1">
11436               <code>OnLoad</code> phase: while in the
11437               <internallink id="onload"><code>Agent_OnLoad</code></internallink>
11438               or, for statically linked agents, the <internallink id="onload">
11439               <code>Agent_OnLoad_&lt;agent-lib-name&gt;
11440               </code></internallink> function.
11441             </constant>
11442             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
11443               Primordial phase: between return from <code>Agent_OnLoad</code>
11444               or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> and the
11445               <code>VMStart</code> event.
11446             </constant>
11447             <constant id="JVMTI_PHASE_START" num="6">
11448               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event
11449               is sent and until the <code>VMInit</code> event is sent.
11450             </constant>
11451             <constant id="JVMTI_PHASE_LIVE" num="4">
11452               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
11453               and until the <eventlink id="VMDeath"></eventlink> event returns.
11454             </constant>
11455             <constant id="JVMTI_PHASE_DEAD" num="8">
11456               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
11457               start-up failure.
11458             </constant>
11459           </constants>
11460           In the case of start-up failure the VM will proceed directly to the dead
11461           phase skipping intermediate phases and neither a <code>VMInit</code> nor
11462           <code>VMDeath</code> event will be sent.
11463           <p/>
11464           Most <jvmti/> functions operate only in the live phase.
11465           The following functions operate in either the <code>OnLoad</code> or live phases:
11466           <functionphaselist phase="onload"/>
11467           The following functions operate in only the <code>OnLoad</code> phase:
11468           <functionphaselist phase="onloadOnly"/>
11469           The following functions operate in the start or live phases:
11470           <functionphaselist phase="start"/>
11471           The following functions operate in any phase:
11472           <functionphaselist phase="any"/>
11473           JNI functions (except the Invocation API) must only be used in the start or live phases.
11474           <p/>
11475           Most <jvmti/> events are sent only in the live phase.
11476           The following events operate in others phases:
11477           <eventphaselist phase="start"/>
11478           <eventphaselist phase="any"/>
11479       </description>
11480       <origin>new</origin>
11481       <capabilities>
11482       </capabilities>
11483       <parameters>
11484         <param id="phase_ptr">
11485           <outptr><enum>jvmtiPhase</enum></outptr>
11486           <description>
11487             On return, points to the phase.
11488           </description>
11489         </param>
11490       </parameters>
11491       <errors>
11492       </errors>
11493     </function>
11494 
11495     <function id="DisposeEnvironment" jkernel="yes" phase="any" num="127">
11496       <synopsis>Dispose Environment</synopsis>
11497       <description>
11498         Shutdown a <jvmti/> connection created with JNI <code>GetEnv</code>
11499         (see <internallink id="environments"><jvmti/> Environments</internallink>).
11500         Dispose of any resources held by the environment.
11501         <issue>
11502             What resources are reclaimed? What is undone?
11503             Breakpoints,watchpoints removed?
11504         </issue>
11505         Threads suspended by this environment are not resumed by this call,
11506         this must be done explicitly by the agent.
11507         Memory allocated by this environment via calls to <jvmti/> functions
11508         is not released, this can be done explicitly by the agent
11509         by calling <functionlink id="Deallocate"/>.
11510         Raw monitors created by this environment are not destroyed,
11511         this can be done explicitly by the agent
11512         by calling <functionlink id="DestroyRawMonitor"/>.
11513         The state of threads waiting on raw monitors created by this environment
11514         are not affected.
11515         <p/>
11516         Any <functionlink id="SetNativeMethodPrefix">native method
11517         prefixes</functionlink> for this environment will be unset;
11518         the agent must remove any prefixed native methods before
11519         dispose is called.
11520         <p/>
11521         Any <internallink id="capability">capabilities</internallink>
11522         held by this environment are relinquished.
11523         <p/>
11524         Events enabled by this environment will no longer be sent, however
11525         event handlers currently running will continue to run.  Caution must
11526         be exercised in the design of event handlers whose environment may
11527         be disposed and thus become invalid during their execution.
11528         <p/>
11529         This environment may not be used after this call.
11530         This call returns to the caller.
11531       </description>
11532       <origin>new</origin>
11533       <capabilities>
11534       </capabilities>
11535       <parameters>
11536       </parameters>
11537       <errors>
11538       </errors>
11539     </function>
11540 
11541     <function id="SetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="148">
11542       <synopsis>Set Environment Local Storage</synopsis>
11543       <description>
11544         The VM stores a pointer value associated with each environment.
11545         This pointer value is called <i>environment-local storage</i>.
11546         This value is <code>NULL</code> unless set with this function.
11547         Agents can allocate memory in which they store environment specific
11548         information. By setting environment-local storage it can then be
11549         accessed with
11550         <functionlink id="GetEnvironmentLocalStorage"></functionlink>.
11551         <p/>
11552         Called by the agent to set the value of the <jvmti/>
11553         environment-local storage. <jvmti/> supplies to the agent a pointer-size
11554         environment-local storage that can be used to record per-environment
11555         information.
11556       </description>
11557       <origin>new</origin>
11558       <capabilities>
11559       </capabilities>
11560       <parameters>
11561         <param id="data">
11562           <inbuf>
11563             <void/>
11564             <nullok>value is set to <code>NULL</code></nullok>
11565           </inbuf>
11566           <description>
11567             The value to be entered into the environment-local storage.
11568           </description>
11569         </param>
11570       </parameters>
11571       <errors>
11572       </errors>
11573     </function>
11574 
11575     <function id="GetEnvironmentLocalStorage" jkernel="yes" phase="any" callbacksafe="safe" impl="innative notrace" num="147">
11576       <synopsis>Get Environment Local Storage</synopsis>
11577       <description>
11578         Called by the agent to get the value of the <jvmti/> environment-local
11579         storage.
11580       </description>
11581       <origin>new</origin>
11582       <capabilities>
11583       </capabilities>
11584       <parameters>
11585         <param id="data_ptr">
11586           <agentbuf><void/></agentbuf>
11587           <description>
11588             Pointer through which the value of the environment local
11589             storage is returned.
11590             If environment-local storage has not been set with
11591             <functionlink id="SetEnvironmentLocalStorage"></functionlink> returned
11592             pointer is <code>NULL</code>.
11593           </description>
11594         </param>
11595       </parameters>
11596       <errors>
11597       </errors>
11598     </function>
11599 
11600     <function id="GetVersionNumber" jkernel="yes" phase="any" num="88">
11601       <synopsis>Get Version Number</synopsis>
11602       <description>
11603         Return the <jvmti/> version via <code>version_ptr</code>.
11604         The return value is the version identifier.
11605         The version identifier includes major, minor and micro
11606         version as well as the interface type.
11607         <constants id="jvmtiVersionInterfaceTypes" label="Version Interface Types" kind="bits">
11608           <constant id="JVMTI_VERSION_INTERFACE_JNI" num="0x00000000">
11609             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for JNI.
11610           </constant>
11611           <constant id="JVMTI_VERSION_INTERFACE_JVMTI" num="0x30000000">
11612             Value of <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> for <jvmti/>.
11613           </constant>
11614         </constants>
11615         <constants id="jvmtiVersionMasks" label="Version Masks" kind="bits">
11616           <constant id="JVMTI_VERSION_MASK_INTERFACE_TYPE" num="0x70000000">
11617             Mask to extract interface type.
11618             The value of the version returned by this function masked with
11619             <code>JVMTI_VERSION_MASK_INTERFACE_TYPE</code> is always
11620             <code>JVMTI_VERSION_INTERFACE_JVMTI</code>
11621             since this is a <jvmti/> function.
11622           </constant>
11623           <constant id="JVMTI_VERSION_MASK_MAJOR" num="0x0FFF0000">
11624             Mask to extract major version number.
11625           </constant>
11626           <constant id="JVMTI_VERSION_MASK_MINOR" num="0x0000FF00">
11627             Mask to extract minor version number.
11628           </constant>
11629           <constant id="JVMTI_VERSION_MASK_MICRO" num="0x000000FF">
11630             Mask to extract micro version number.
11631           </constant>
11632         </constants>
11633         <constants id="jvmtiVersionShifts" label="Version Shifts" kind="bits">
11634           <constant id="JVMTI_VERSION_SHIFT_MAJOR" num="16">
11635             Shift to extract major version number.
11636           </constant>
11637           <constant id="JVMTI_VERSION_SHIFT_MINOR" num="8">
11638             Shift to extract minor version number.
11639           </constant>
11640           <constant id="JVMTI_VERSION_SHIFT_MICRO" num="0">
11641             Shift to extract micro version number.
11642           </constant>
11643         </constants>
11644       </description>
11645       <origin>jvmdi</origin>
11646       <capabilities>
11647       </capabilities>
11648       <parameters>
11649         <param id="version_ptr">
11650           <outptr><jint/></outptr>
11651           <description>
11652             On return, points to the <jvmti/> version.
11653           </description>
11654         </param>
11655       </parameters>
11656       <errors>
11657       </errors>
11658     </function>
11659 
11660 
11661     <function id="GetErrorName" phase="any" num="128">
11662       <synopsis>Get Error Name</synopsis>
11663       <description>
11664         Return the symbolic name for an
11665           <internallink id="ErrorSection">error code</internallink>.
11666         <p/>
11667         For example
11668         <code>GetErrorName(env, JVMTI_ERROR_NONE, &amp;err_name)</code>
11669         would return in <code>err_name</code> the string
11670         <code>"JVMTI_ERROR_NONE"</code>.
11671       </description>
11672       <origin>new</origin>
11673       <capabilities>
11674       </capabilities>
11675       <parameters>
11676         <param id="error">
11677           <enum>jvmtiError</enum>
11678           <description>
11679             The error code.
11680           </description>
11681         </param>
11682         <param id="name_ptr">
11683           <allocbuf><char/></allocbuf>
11684           <description>
11685             On return, points to the error name.
11686             The name is encoded as a
11687             <internallink id="mUTF">modified UTF-8</internallink> string,
11688             but is restricted to the ASCII subset.
11689           </description>
11690         </param>
11691       </parameters>
11692       <errors>
11693       </errors>
11694     </function>
11695 
11696     <function id="SetVerboseFlag" phase="any" num="150">
11697       <synopsis>Set Verbose Flag</synopsis>
11698       <description>
11699         <constants id="jvmtiVerboseFlag" label="Verbose Flag Enumeration" kind="enum">
11700           <constant id="JVMTI_VERBOSE_OTHER" num="0">
11701             Verbose output other than the below.
11702           </constant>
11703           <constant id="JVMTI_VERBOSE_GC" num="1">
11704             Verbose garbage collector output, like that specified with <code>-verbose:gc</code>.
11705           </constant>
11706           <constant id="JVMTI_VERBOSE_CLASS" num="2">
11707             Verbose class loading output, like that specified with <code>-verbose:class</code>.
11708           </constant>
11709           <constant id="JVMTI_VERBOSE_JNI" num="4">
11710             Verbose JNI output, like that specified with <code>-verbose:jni</code>.
11711           </constant>
11712         </constants>
11713         Control verbose output.
11714         This is the output which typically is sent to <code>stderr</code>.
11715       </description>
11716       <origin>new</origin>
11717       <capabilities>
11718       </capabilities>
11719       <parameters>
11720         <param id="flag">
11721           <enum>jvmtiVerboseFlag</enum>
11722           <description>
11723             Which verbose flag to set.
11724           </description>
11725         </param>
11726         <param id="value">
11727           <jboolean/>
11728           <description>
11729             New value of the flag.
11730           </description>
11731         </param>
11732       </parameters>
11733       <errors>
11734       </errors>
11735     </function>
11736 
11737 
11738     <function id="GetJLocationFormat" phase="any" num="129">
11739       <synopsis>Get JLocation Format</synopsis>
11740       <description>
11741         Although the greatest functionality is achieved with location information
11742         referencing the virtual machine bytecode index, the definition of
11743         <code>jlocation</code> has intentionally been left unconstrained to allow VM
11744         implementations that do not have this information.
11745         <p/>
11746         This function describes the representation of <code>jlocation</code> used in this VM.
11747         If the returned format is <datalink id="JVMTI_JLOCATION_JVMBCI"></datalink>,
11748         <code>jlocation</code>s can
11749         be used as in indices into the array returned by
11750         <functionlink id="GetBytecodes"></functionlink>.
11751         <constants id="jvmtiJlocationFormat" label="JLocation Format Enumeration" kind="enum">
11752           <constant id="JVMTI_JLOCATION_JVMBCI" num="1">
11753             <code>jlocation</code> values represent virtual machine
11754             bytecode indices--that is, offsets into the
11755             virtual machine code for a method.
11756           </constant>
11757           <constant id="JVMTI_JLOCATION_MACHINEPC" num="2">
11758             <code>jlocation</code> values represent native machine
11759             program counter values.
11760           </constant>
11761           <constant id="JVMTI_JLOCATION_OTHER" num="0">
11762             <code>jlocation</code> values have some other representation.
11763           </constant>
11764         </constants>
11765       </description>
11766       <origin>new</origin>
11767       <capabilities>
11768       </capabilities>
11769       <parameters>
11770         <param id="format_ptr">
11771           <outptr><enum>jvmtiJlocationFormat</enum></outptr>
11772           <description>
11773             On return, points to the format identifier for <code>jlocation</code> values.
11774           </description>
11775         </param>
11776       </parameters>
11777       <errors>
11778       </errors>
11779     </function>
11780 
11781   </category>
11782 
11783   <category id="heap_monitoring" label="Heap Monitoring">
11784     <function id="SetHeapSamplingInterval" phase="onload" num="156" since="11">
11785       <synopsis>Set Heap Sampling Interval</synopsis>
11786       <description>
11787         Generate a <eventlink id="SampledObjectAlloc"/> event when objects are allocated.
11788         Each thread keeps a counter of bytes allocated. The event will only be generated
11789         when that counter exceeds an average of <paramlink id="sampling_interval"></paramlink>
11790         since the last sample.
11791         <p/>
11792         Setting <paramlink id="sampling_interval"></paramlink> to 0 will cause an event to be
11793         generated by each allocation supported by the system once the new interval is taken into account.
11794         <p/>
11795         Note that updating the new sampling interval might take various number of allocations
11796         to provoke internal data structure updates.  Therefore it is important to
11797         consider the sampling interval as an average. This includes the interval 0, where events
11798         might not be generated straight away for each allocation.
11799       </description>
11800       <origin>new</origin>
11801       <capabilities>
11802         <required id="can_generate_sampled_object_alloc_events"></required>
11803       </capabilities>
11804       <parameters>
11805         <param id="sampling_interval">
11806           <jint/>
11807           <description>
11808             The sampling interval in bytes. The sampler uses a statistical approach to
11809             generate an event, on average, once for every <paramlink id="sampling_interval"/> bytes of
11810             memory allocated by a given thread.
11811             <p/>
11812             Once the new sampling interval is taken into account, 0 as a sampling interval will generate
11813             a sample for every allocation.
11814             <p/>
11815             Note: The overhead of this feature is directly correlated with the sampling interval.
11816             A high sampling interval, such as 1024 bytes, will incur a high overhead.
11817             A lower interval, such as 1024KB, will have a much lower overhead.  Sampling should only
11818             be used with an understanding that it may impact performance.
11819           </description>
11820         </param>
11821       </parameters>
11822       <errors>
11823         <error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">
11824           <paramlink id="sampling_interval"></paramlink> is less than zero.
11825         </error>
11826       </errors>
11827     </function>
11828   </category>
11829 
11830 </functionsection>
11831 
11832 <errorsection label="Error Reference">
11833   <intro>
11834     Every <jvmti/> function returns a <b><code>jvmtiError</code></b> error code.
11835     <p/>
11836     It is the responsibility of the agent to call <jvmti/> functions with
11837     valid parameters and in the proper context (calling thread is attached,
11838     phase is correct, etc.).
11839     Detecting some error conditions may be difficult, inefficient, or
11840     impossible for an implementation.
11841     The errors listed in
11842     <internallink id="reqerrors">Function Specific Required Errors</internallink>
11843     must be detected by the implementation.
11844     All other errors represent the recommended response to the error
11845     condition.
11846   </intro>
11847 
11848   <errorcategory id="universal-error" label="Universal Errors">
11849     <intro>
11850       The following errors may be returned by any function
11851     </intro>
11852 
11853     <errorid id="JVMTI_ERROR_NONE" num="0">
11854       No error has occurred.  This is the error code that is returned
11855       on successful completion of the function.
11856     </errorid>
11857     <errorid id="JVMTI_ERROR_NULL_POINTER" num="100">
11858       Pointer is unexpectedly <code>NULL</code>.
11859     </errorid>
11860     <errorid id="JVMTI_ERROR_OUT_OF_MEMORY" num="110">
11861       The function attempted to allocate memory and no more memory was
11862       available for allocation.
11863     </errorid>
11864     <errorid id="JVMTI_ERROR_ACCESS_DENIED" num="111">
11865       The desired functionality has not been enabled in this virtual machine.
11866     </errorid>
11867     <errorid id="JVMTI_ERROR_UNATTACHED_THREAD" num="115">
11868       The thread being used to call this function is not attached
11869       to the virtual machine.  Calls must be made from attached threads.
11870       See <code>AttachCurrentThread</code> in the JNI invocation API.
11871     </errorid>
11872     <errorid id="JVMTI_ERROR_INVALID_ENVIRONMENT" num="116">
11873       The <jvmti/> environment provided is no longer connected or is
11874       not an environment.
11875     </errorid>
11876     <errorid id="JVMTI_ERROR_WRONG_PHASE" num="112">
11877       The desired functionality is not available in the current
11878         <functionlink id="GetPhase">phase</functionlink>.
11879       Always returned if the virtual machine has completed running.
11880     </errorid>
11881     <errorid id="JVMTI_ERROR_INTERNAL" num="113">
11882       An unexpected internal error has occurred.
11883     </errorid>
11884   </errorcategory>
11885 
11886   <errorcategory id="reqerrors" label="Function Specific Required Errors">
11887     <intro>
11888       The following errors are returned by some <jvmti/> functions and must
11889       be returned by the implementation when the condition occurs.
11890     </intro>
11891 
11892     <errorid id="JVMTI_ERROR_INVALID_PRIORITY" num="12">
11893       Invalid priority.
11894     </errorid>
11895     <errorid id="JVMTI_ERROR_THREAD_NOT_SUSPENDED" num="13">
11896       Thread was not suspended.
11897     </errorid>
11898     <errorid id="JVMTI_ERROR_THREAD_SUSPENDED" num="14">
11899       Thread already suspended.
11900     </errorid>
11901     <errorid id="JVMTI_ERROR_THREAD_NOT_ALIVE" num="15">
11902       This operation requires the thread to be alive--that is,
11903       it must be started and not yet have died.
11904     </errorid>
11905     <errorid id="JVMTI_ERROR_CLASS_NOT_PREPARED" num="22">
11906       The class has been loaded but not yet prepared.
11907     </errorid>
11908     <errorid id="JVMTI_ERROR_NO_MORE_FRAMES" num="31">
11909       There are no Java programming language or JNI stack frames at the specified depth.
11910     </errorid>
11911     <errorid id="JVMTI_ERROR_OPAQUE_FRAME" num="32">
11912       Information about the frame is not available (e.g. for native frames).
11913     </errorid>
11914     <errorid id="JVMTI_ERROR_DUPLICATE" num="40">
11915       Item already set.
11916     </errorid>
11917     <errorid id="JVMTI_ERROR_NOT_FOUND" num="41">
11918       Desired element (e.g. field or breakpoint) not found
11919     </errorid>
11920     <errorid id="JVMTI_ERROR_NOT_MONITOR_OWNER" num="51">
11921       This thread doesn't own the raw monitor.
11922     </errorid>
11923     <errorid id="JVMTI_ERROR_INTERRUPT" num="52">
11924       The call has been interrupted before completion.
11925     </errorid>
11926     <errorid id="JVMTI_ERROR_UNMODIFIABLE_CLASS" num="79">
11927       The class cannot be modified.
11928     </errorid>
11929     <errorid id="JVMTI_ERROR_UNMODIFIABLE_MODULE" num="80">
11930       The module cannot be modified.
11931     </errorid>
11932     <errorid id="JVMTI_ERROR_NOT_AVAILABLE" num="98">
11933       The functionality is not available in this virtual machine.
11934     </errorid>
11935     <errorid id="JVMTI_ERROR_ABSENT_INFORMATION" num="101">
11936       The requested information is not available.
11937     </errorid>
11938     <errorid id="JVMTI_ERROR_INVALID_EVENT_TYPE" num="102">
11939       The specified event type ID is not recognized.
11940     </errorid>
11941     <errorid id="JVMTI_ERROR_NATIVE_METHOD" num="104">
11942       The requested information is not available for native method.
11943     </errorid>
11944     <errorid id="JVMTI_ERROR_CLASS_LOADER_UNSUPPORTED" num="106">
11945       The class loader does not support this operation.
11946     </errorid>
11947   </errorcategory>
11948 
11949   <errorcategory id="function-specific-errors" label="Function Specific Agent Errors">
11950     <intro>
11951       The following errors are returned by some <jvmti/> functions.
11952       They are returned in the event of invalid parameters passed by the
11953       agent or usage in an invalid context.
11954       An implementation is not required to detect these errors.
11955     </intro>
11956 
11957     <errorid id="JVMTI_ERROR_INVALID_THREAD" num="10">
11958       The passed thread is not a valid thread.
11959     </errorid>
11960     <errorid id="JVMTI_ERROR_INVALID_FIELDID" num="25">
11961       Invalid field.
11962     </errorid>
11963     <errorid id="JVMTI_ERROR_INVALID_MODULE" num="26">
11964       Invalid module.
11965     </errorid>
11966     <errorid id="JVMTI_ERROR_INVALID_METHODID" num="23">
11967       Invalid method.
11968     </errorid>
11969     <errorid id="JVMTI_ERROR_INVALID_LOCATION" num="24">
11970       Invalid location.
11971     </errorid>
11972     <errorid id="JVMTI_ERROR_INVALID_OBJECT" num="20">
11973       Invalid object.
11974     </errorid>
11975     <errorid id="JVMTI_ERROR_INVALID_CLASS" num="21">
11976       Invalid class.
11977     </errorid>
11978     <errorid id="JVMTI_ERROR_TYPE_MISMATCH" num="34">
11979       The variable is not an appropriate type for the function used.
11980     </errorid>
11981     <errorid id="JVMTI_ERROR_INVALID_SLOT" num="35">
11982       Invalid slot.
11983     </errorid>
11984     <errorid id="JVMTI_ERROR_MUST_POSSESS_CAPABILITY" num="99">
11985       The capability being used is false in this environment.
11986     </errorid>
11987     <errorid id="JVMTI_ERROR_INVALID_THREAD_GROUP" num="11">
11988       Thread group invalid.
11989     </errorid>
11990     <errorid id="JVMTI_ERROR_INVALID_MONITOR" num="50">
11991       Invalid raw monitor.
11992     </errorid>
11993     <errorid id="JVMTI_ERROR_ILLEGAL_ARGUMENT" num="103">
11994       Illegal argument.
11995     </errorid>
11996     <errorid id="JVMTI_ERROR_INVALID_TYPESTATE" num="65">
11997       The state of the thread has been modified, and is now inconsistent.
11998     </errorid>
11999     <errorid id="JVMTI_ERROR_UNSUPPORTED_VERSION" num="68">
12000       A new class file has a version number not supported by this VM.
12001     </errorid>
12002     <errorid id="JVMTI_ERROR_INVALID_CLASS_FORMAT" num="60">
12003       A new class file is malformed (the VM would return a <code>ClassFormatError</code>).
12004     </errorid>
12005     <errorid id="JVMTI_ERROR_CIRCULAR_CLASS_DEFINITION" num="61">
12006       The new class file definitions would lead to a circular
12007       definition (the VM would return a <code>ClassCircularityError</code>).
12008     </errorid>
12009     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_ADDED" num="63">
12010       A new class file would require adding a method.
12011     </errorid>
12012     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_SCHEMA_CHANGED" num="64">
12013       A new class version changes a field.
12014     </errorid>
12015     <errorid id="JVMTI_ERROR_FAILS_VERIFICATION" num="62">
12016       The class bytes fail verification.
12017     </errorid>
12018     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_HIERARCHY_CHANGED" num="66">
12019       A direct superclass is different for the new class
12020       version, or the set of directly implemented
12021       interfaces is different.
12022     </errorid>
12023     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_DELETED" num="67">
12024       A new class version does not declare a method
12025       declared in the old class version.
12026     </errorid>
12027     <errorid id="JVMTI_ERROR_NAMES_DONT_MATCH" num="69">
12028       The class name defined in the new class file is
12029       different from the name in the old class object.
12030     </errorid>
12031     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_MODIFIERS_CHANGED" num="70">
12032       A new class version has different modifiers.
12033     </errorid>
12034     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_METHOD_MODIFIERS_CHANGED" num="71">
12035       A method in the new class version has different modifiers
12036       than its counterpart in the old class version.
12037     </errorid>
12038     <errorid id="JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED" num="72">
12039       A new class version has unsupported differences in class attributes.
12040     </errorid>
12041   </errorcategory>
12042 </errorsection>
12043 
12044 <eventsection label="Events">
12045   <intro label="Handling Events" id="eventIntro">
12046     Agents can be informed of many events that occur in application
12047     programs.
12048     <p/>
12049     To handle events, designate a set of callback functions with
12050     <functionlink id="SetEventCallbacks"></functionlink>.
12051     For each event the corresponding callback function will be
12052     called.
12053     Arguments to the callback function provide additional
12054     information about the event.
12055     <p/>
12056     The callback function is usually called from within an application
12057     thread. The <jvmti/> implementation does not
12058     queue events in any way. This means
12059     that event callback functions must be written
12060     carefully. Here are some general guidelines. See
12061     the individual event descriptions for further
12062     suggestions.
12063     <p/>
12064     <ul>
12065       <li>Any exception thrown during the execution of an event callback can
12066         overwrite any current pending exception in the current application thread.
12067         Care must be taken to preserve a pending exception
12068         when an event callback makes a JNI call that might generate an exception.
12069       </li>
12070       <li>Event callback functions must be re-entrant. The <jvmti/> implementation does
12071         not queue events. If an agent needs to process events one at a time, it
12072         can use a raw monitor inside the
12073         event callback functions to serialize event processing.
12074       </li>
12075       <li>Event callback functions that execute JNI's FindClass function to load
12076         classes need to note that FindClass locates the class loader associated
12077         with the current native method. For the purposes of class loading, an
12078         event callback that includes a JNI environment as a parameter to the
12079         callback will treated as if it is a native call, where the native method
12080         is in the class of the event thread's current frame.
12081       </li>
12082     </ul>
12083     <p/>
12084     Some <jvmti/> events identify objects with JNI references.
12085     All references
12086     in <jvmti/> events are JNI local references and will become invalid
12087     after the event callback returns.
12088     Unless stated otherwise, memory referenced by pointers sent in event
12089     callbacks may not be referenced after the event callback returns.
12090     <p/>
12091     Except where stated otherwise, events are delivered on the thread
12092     that caused the event.
12093     Events are sent at the time they occur.
12094     The specification for each event includes the set of
12095     <functionlink id="GetPhase">phases</functionlink> in which it can be sent;
12096     if an event triggering activity occurs during another phase, no event
12097     is sent.
12098     <p/>
12099     A thread that generates an event does not change its execution status
12100     (for example, the event does not cause the thread to be suspended).
12101     If an agent wishes the event to result in suspension, then the agent
12102     is responsible for explicitly suspending the thread with
12103     <functionlink id="SuspendThread"></functionlink>.
12104     <p/>
12105     If an event is enabled in multiple environments, the event will be sent
12106     to each agent in the order that the environments were created.
12107   </intro>
12108 
12109   <intro label="Enabling Events" id="enablingevents">
12110     All events are initially disabled.  In order to receive any
12111     event:
12112       <ul>
12113         <li>
12114           If the event requires a capability, that capability must
12115           be added with
12116           <functionlink id="AddCapabilities"></functionlink>.
12117         </li>
12118         <li>
12119           A callback for the event must be set with
12120           <functionlink id="SetEventCallbacks"></functionlink>.
12121         </li>
12122         <li>
12123           The event must be enabled with
12124           <functionlink id="SetEventNotificationMode"></functionlink>.
12125         </li>
12126       </ul>
12127   </intro>
12128 
12129   <intro label="Multiple Co-located Events" id="eventorder">
12130     In many situations it is possible for multiple events to occur
12131     at the same location in one thread. When this happens, all the events
12132     are reported through the event callbacks in the order specified in this section.
12133     <p/>
12134     If the current location is at the entry point of a method, the
12135     <eventlink id="MethodEntry"></eventlink> event is reported before
12136     any other event at the current location in the same thread.
12137     <p/>
12138     If an exception catch has been detected at the current location,
12139     either because it is the beginning of a catch clause or a native method
12140     that cleared a pending exception has returned, the
12141     <code>exceptionCatch</code> event is reported before
12142     any other event at the current location in the same thread.
12143     <p/>
12144     If a <code>singleStep</code> event or
12145     <code>breakpoint</code> event is triggered at the
12146     current location, the event is defined to occur
12147     immediately before the code at the current location is executed.
12148     These events are reported before any events which are triggered
12149     by the execution of code at the current location in the same
12150     thread (specifically:
12151     <code>exception</code>,
12152     <code>fieldAccess</code>, and
12153     <code>fieldModification</code>).
12154     If both a step and breakpoint event are triggered for the same thread and
12155     location, the step event is reported before the breakpoint event.
12156     <p/>
12157     If the current location is the exit point of a method (that is, the last
12158     location before returning to the caller), the
12159     <eventlink id="MethodExit"></eventlink> event and
12160     the <eventlink id="FramePop"></eventlink> event (if requested)
12161     are reported after all other events at the current location in the same
12162     thread. There is no specified ordering of these two events
12163     with respect to each other.
12164     <p/>
12165     Co-located events can be triggered during the processing of some other
12166     event by the agent at the same location in the same thread.
12167     If such an event, of type <i>y</i>, is triggered during the processing of
12168     an event of type <i>x</i>, and if <i>x</i>
12169     precedes <i>y</i> in the ordering specified above, the co-located event
12170     <i>y</i> is reported for the current thread and location. If <i>x</i> does not precede
12171     <i>y</i>, <i>y</i> is not reported for the current thread and location.
12172     For example, if a breakpoint is set at the current location
12173     during the processing of <eventlink id="SingleStep"></eventlink>,
12174     that breakpoint will be reported before the thread moves off the current
12175     location.
12176     <p/>The following events are never considered to be co-located with
12177     other events.
12178     <ul>
12179       <li><eventlink id="VMStart"></eventlink></li>
12180       <li><eventlink id="VMInit"></eventlink></li>
12181       <li><eventlink id="VMDeath"></eventlink></li>
12182       <li><eventlink id="ThreadStart"></eventlink></li>
12183       <li><eventlink id="ThreadEnd"></eventlink></li>
12184       <li><eventlink id="ClassLoad"></eventlink></li>
12185       <li><eventlink id="ClassPrepare"></eventlink></li>
12186     </ul>
12187   </intro>
12188 
12189   <intro label="Event Callbacks" id="jvmtiEventCallbacks">
12190       The event callback structure below is used to specify the handler function
12191       for events.  It is set with the
12192       <functionlink id="SetEventCallbacks"></functionlink> function.
12193   </intro>
12194 
12195   <event label="Single Step"
12196          id="SingleStep" const="JVMTI_EVENT_SINGLE_STEP" filtered="thread" num="60">
12197     <description>
12198       Single step events allow the agent to trace thread execution
12199       at the finest granularity allowed by the VM. A single step event is
12200       generated whenever a thread reaches a new location.
12201       Typically, single step events represent the completion of one VM
12202       instruction as defined in <vmspec/>. However, some implementations
12203       may define locations differently. In any case the
12204       <code>method</code> and <code>location</code>
12205       parameters  uniquely identify the current location and allow
12206       the mapping to source file and line number when that information is
12207       available.
12208       <p/>
12209       No single step events are generated from within native methods.
12210     </description>
12211     <origin>jvmdi</origin>
12212     <capabilities>
12213       <required id="can_generate_single_step_events"></required>
12214     </capabilities>
12215     <parameters>
12216       <param id="jni_env">
12217         <outptr>
12218           <struct>JNIEnv</struct>
12219         </outptr>
12220           <description>
12221             The JNI environment of the event (current) thread
12222           </description>
12223       </param>
12224       <param id="thread">
12225         <jthread/>
12226           <description>
12227             Thread about to execution a new instruction
12228           </description>
12229       </param>
12230       <param id="klass">
12231         <jclass method="method"/>
12232           <description>
12233             Class of the method about to execute a new instruction
12234           </description>
12235       </param>
12236       <param id="method">
12237         <jmethodID class="klass"/>
12238           <description>
12239             Method about to execute a new instruction
12240           </description>
12241       </param>
12242       <param id="location">
12243         <jlocation/>
12244         <description>
12245           Location of the new instruction
12246         </description>
12247       </param>
12248     </parameters>
12249   </event>
12250 
12251   <event label="Breakpoint"
12252          id="Breakpoint" const="JVMTI_EVENT_BREAKPOINT" filtered="thread" num="62">
12253     <description>
12254       Breakpoint events are generated whenever a thread reaches a location
12255       designated as a breakpoint with <functionlink id="SetBreakpoint"></functionlink>.
12256       The <code>method</code> and <code>location</code>
12257       parameters uniquely identify the current location and allow
12258       the mapping to source file and line number when that information is
12259       available.
12260     </description>
12261     <origin>jvmdi</origin>
12262     <capabilities>
12263       <required id="can_generate_breakpoint_events"></required>
12264     </capabilities>
12265     <parameters>
12266       <param id="jni_env">
12267         <outptr>
12268           <struct>JNIEnv</struct>
12269         </outptr>
12270           <description>
12271             The JNI environment of the event (current) thread.
12272           </description>
12273       </param>
12274       <param id="thread">
12275         <jthread/>
12276           <description>
12277             Thread that hit the breakpoint
12278           </description>
12279       </param>
12280       <param id="klass">
12281         <jclass method="method"/>
12282           <description>
12283             Class of the method that hit the breakpoint
12284           </description>
12285       </param>
12286       <param id="method">
12287         <jmethodID class="klass"/>
12288           <description>
12289             Method that hit the breakpoint
12290           </description>
12291       </param>
12292       <param id="location">
12293         <jlocation/>
12294         <description>
12295           location of the breakpoint
12296         </description>
12297       </param>
12298     </parameters>
12299   </event>
12300 
12301   <event label="Field Access"
12302          id="FieldAccess" const="JVMTI_EVENT_FIELD_ACCESS" filtered="thread" num="63">
12303     <description>
12304       Field access events are generated whenever a thread accesses
12305       a field that was designated as a watchpoint
12306       with <functionlink id="SetFieldAccessWatch"></functionlink>.
12307       The <code>method</code> and <code>location</code>
12308       parameters uniquely identify the current location and allow
12309       the mapping to source file and line number when that information is
12310       available.
12311     </description>
12312     <origin>jvmdi</origin>
12313     <capabilities>
12314       <required id="can_generate_field_access_events"></required>
12315     </capabilities>
12316     <parameters>
12317       <param id="jni_env">
12318         <outptr>
12319           <struct>JNIEnv</struct>
12320         </outptr>
12321           <description>
12322             The JNI environment of the event (current) thread
12323           </description>
12324       </param>
12325       <param id="thread">
12326         <jthread/>
12327           <description>
12328             Thread accessing the field
12329           </description>
12330       </param>
12331       <param id="klass">
12332         <jclass method="method"/>
12333           <description>
12334             Class of the method where the access is occurring
12335           </description>
12336       </param>
12337       <param id="method">
12338         <jmethodID class="klass"/>
12339           <description>
12340             Method where the access is occurring
12341           </description>
12342       </param>
12343       <param id="location">
12344         <jlocation/>
12345         <description>
12346           Location where the access is occurring
12347         </description>
12348       </param>
12349       <param id="field_klass">
12350         <jclass field="field"/>
12351           <description>
12352             Class of the field being accessed
12353           </description>
12354       </param>
12355       <param id="object">
12356         <jobject/>
12357           <description>
12358             Object with the field being accessed if the field is an
12359             instance field; <code>NULL</code> otherwise
12360           </description>
12361       </param>
12362       <param id="field">
12363         <jfieldID class="field_klass"/>
12364           <description>
12365             Field being accessed
12366           </description>
12367       </param>
12368     </parameters>
12369   </event>
12370 
12371   <event label="Field Modification"
12372          id="FieldModification" const="JVMTI_EVENT_FIELD_MODIFICATION" filtered="thread" num="64">
12373     <description>
12374       Field modification events are generated whenever a thread modifies
12375       a field that was designated as a watchpoint
12376       with <functionlink id="SetFieldModificationWatch"></functionlink>.
12377       The <code>method</code> and <code>location</code>
12378       parameters uniquely identify the current location and allow
12379       the mapping to source file and line number when that information is
12380       available.
12381     </description>
12382     <origin>jvmdi</origin>
12383     <capabilities>
12384       <required id="can_generate_field_modification_events"></required>
12385     </capabilities>
12386     <parameters>
12387       <param id="jni_env">
12388         <outptr>
12389           <struct>JNIEnv</struct>
12390         </outptr>
12391           <description>
12392             The JNI environment of the event (current) thread
12393           </description>
12394       </param>
12395       <param id="thread">
12396         <jthread/>
12397           <description>
12398             Thread modifying the field
12399           </description>
12400       </param>
12401       <param id="klass">
12402         <jclass method="method"/>
12403           <description>
12404             Class of the method where the modification is occurring
12405           </description>
12406       </param>
12407       <param id="method">
12408         <jmethodID class="klass"/>
12409           <description>
12410             Method where the modification is occurring
12411           </description>
12412       </param>
12413       <param id="location">
12414         <jlocation/>
12415         <description>
12416           Location where the modification is occurring
12417         </description>
12418       </param>
12419       <param id="field_klass">
12420         <jclass field="field"/>
12421           <description>
12422             Class of the field being modified
12423           </description>
12424       </param>
12425       <param id="object">
12426         <jobject/>
12427           <description>
12428             Object with the field being modified if the field is an
12429             instance field; <code>NULL</code> otherwise
12430           </description>
12431       </param>
12432       <param id="field">
12433         <jfieldID class="field_klass"/>
12434           <description>
12435             Field being modified
12436           </description>
12437       </param>
12438       <param id="signature_type">
12439         <char/>
12440         <description>
12441           Signature type of the new value
12442         </description>
12443       </param>
12444       <param id="new_value">
12445         <jvalue/>
12446         <description>
12447           The new value
12448         </description>
12449       </param>
12450     </parameters>
12451   </event>
12452 
12453   <event label="Frame Pop"
12454          id="FramePop" const="JVMTI_EVENT_FRAME_POP" filtered="thread" num="61">
12455     <description>
12456       Frame pop events are generated upon exit from a single method
12457       in a single frame as specified
12458       in a call to <functionlink id="NotifyFramePop"></functionlink>.
12459       This is true whether termination is caused by
12460       executing its return instruction
12461       or by throwing an exception to its caller
12462       (see <paramlink id="was_popped_by_exception"></paramlink>).
12463       However, frame pops caused by the <functionlink id="PopFrame"/>
12464       function are not reported.
12465       <p/>
12466       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12467       for the depth 0 identifies the executable location in the returning method,
12468       immediately prior to the return.
12469     </description>
12470     <origin>jvmdi</origin>
12471     <capabilities>
12472       <required id="can_generate_frame_pop_events"></required>
12473     </capabilities>
12474     <parameters>
12475       <param id="jni_env">
12476         <outptr>
12477           <struct>JNIEnv</struct>
12478         </outptr>
12479           <description>
12480             The JNI environment of the event (current) thread
12481           </description>
12482       </param>
12483       <param id="thread">
12484         <jthread/>
12485           <description>
12486             Thread that is popping the frame
12487           </description>
12488       </param>
12489       <param id="klass">
12490         <jclass method="method"/>
12491           <description>
12492             Class of the method being popped
12493           </description>
12494       </param>
12495       <param id="method">
12496         <jmethodID class="klass"/>
12497           <description>
12498             Method being popped
12499           </description>
12500       </param>
12501       <param id="was_popped_by_exception">
12502         <jboolean/>
12503         <description>
12504           True if frame was popped by a thrown exception.
12505           False if method exited through its return instruction.
12506         </description>
12507       </param>
12508     </parameters>
12509   </event>
12510 
12511   <event label="Method Entry"
12512          id="MethodEntry" const="JVMTI_EVENT_METHOD_ENTRY" filtered="thread" num="65">
12513     <description>
12514       Method entry events are generated upon entry of Java
12515       programming language methods (including native methods).
12516       <p/>
12517       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12518       for the depth 0 identifies the initial executable location in the method.
12519       <p/>
12520       Enabling method
12521       entry or exit events will significantly degrade performance on many platforms and is thus
12522       not advised for performance critical usage (such as profiling).
12523       <internallink id="bci">Bytecode instrumentation</internallink> should be
12524       used in these cases.
12525     </description>
12526     <origin>jvmdi</origin>
12527     <capabilities>
12528       <required id="can_generate_method_entry_events"></required>
12529     </capabilities>
12530     <parameters>
12531       <param id="jni_env">
12532         <outptr>
12533           <struct>JNIEnv</struct>
12534         </outptr>
12535           <description>
12536             The JNI environment of the event (current) thread
12537           </description>
12538       </param>
12539       <param id="thread">
12540         <jthread/>
12541           <description>
12542             Thread entering the method
12543           </description>
12544       </param>
12545       <param id="klass">
12546         <jclass method="method"/>
12547           <description>
12548             Class of the method being entered
12549           </description>
12550       </param>
12551       <param id="method">
12552         <jmethodID class="klass"/>
12553           <description>
12554             Method being entered
12555           </description>
12556       </param>
12557     </parameters>
12558   </event>
12559 
12560   <event label="Method Exit"
12561          id="MethodExit" const="JVMTI_EVENT_METHOD_EXIT" filtered="thread" num="66">
12562     <description>
12563       Method exit events are generated upon exit from Java
12564       programming language methods (including native methods).
12565       This is true whether termination is caused by
12566       executing its return instruction
12567       or by throwing an exception to its caller
12568       (see <paramlink id="was_popped_by_exception"></paramlink>).
12569       <p/>
12570       The location reported by <functionlink id="GetFrameLocation"></functionlink>
12571       for the depth 0 identifies the executable location in the returning method
12572       immediately prior to the return.
12573       <p/>
12574         Enabling method
12575         entry or exit events will significantly degrade performance on many platforms and is thus
12576         not advised for performance critical usage (such as profiling).
12577         <internallink id="bci">Bytecode instrumentation</internallink> should be
12578         used in these cases.
12579     </description>
12580     <origin>jvmdi</origin>
12581     <capabilities>
12582       <required id="can_generate_method_exit_events"></required>
12583     </capabilities>
12584     <parameters>
12585       <param id="jni_env">
12586         <outptr>
12587           <struct>JNIEnv</struct>
12588         </outptr>
12589           <description>
12590             The JNI environment of the event (current) thread
12591           </description>
12592       </param>
12593       <param id="thread">
12594         <jthread/>
12595           <description>
12596             Thread exiting the method
12597           </description>
12598       </param>
12599       <param id="klass">
12600         <jclass method="method"/>
12601           <description>
12602             Class of the method being exited
12603           </description>
12604       </param>
12605       <param id="method">
12606         <jmethodID class="klass"/>
12607           <description>
12608             Method being exited
12609           </description>
12610       </param>
12611       <param id="was_popped_by_exception">
12612         <jboolean/>
12613         <description>
12614           True if frame was popped by a thrown exception.
12615           False if method exited through its return instruction.
12616         </description>
12617       </param>
12618       <param id="return_value">
12619         <jvalue/>
12620         <description>
12621           The return value of the method being exited.
12622           Undefined and should not be used if
12623           <paramlink id="was_popped_by_exception"></paramlink>
12624           is true.
12625         </description>
12626       </param>
12627     </parameters>
12628   </event>
12629 
12630   <event label="Native Method Bind" phase="any"
12631          id="NativeMethodBind" const="JVMTI_EVENT_NATIVE_METHOD_BIND" num="67">
12632     <description>
12633       A Native Method Bind event is sent when a VM binds a
12634       Java programming language native method
12635       to the address of a function that implements the native method.
12636       This will occur when the native method is called for the first time
12637       and also occurs when the JNI function <code>RegisterNatives</code> is called.
12638       This event allows the bind to be redirected to an agent-specified
12639       proxy function.
12640       This event is not sent when the native method is unbound.
12641       Typically, this proxy function will need to be specific to a
12642       particular method or, to handle the general case, automatically
12643       generated assembly code, since after instrumentation code is
12644       executed the function at the original binding
12645       address will usually be invoked.
12646       The original binding can be restored or the redirection changed
12647       by use of the JNI function <code>RegisterNatives</code>.
12648       Some events may be sent during the primordial phase, JNI and
12649       most of <jvmti/> cannot be used at this time but the method and
12650       address can be saved for use later.
12651     </description>
12652     <origin>new</origin>
12653     <capabilities>
12654       <required id="can_generate_native_method_bind_events"></required>
12655     </capabilities>
12656     <parameters>
12657       <param id="jni_env">
12658         <outptr>
12659           <struct>JNIEnv</struct>
12660         </outptr>
12661           <description>
12662             The JNI environment of the event (current) thread
12663             Will be <code>NULL</code> if sent during the primordial
12664             <functionlink id="GetPhase">phase</functionlink>.
12665           </description>
12666       </param>
12667       <param id="thread">
12668         <jthread/>
12669           <description>
12670             Thread requesting the bind
12671           </description>
12672       </param>
12673       <param id="klass">
12674         <jclass method="method"/>
12675           <description>
12676             Class of the method being bound
12677           </description>
12678       </param>
12679       <param id="method">
12680         <jmethodID class="klass"/>
12681           <description>
12682             Native method being bound
12683           </description>
12684       </param>
12685       <param id="address">
12686         <outptr><void/></outptr>
12687         <description>
12688           The address the VM is about to bind to--that is, the
12689           address of the implementation of the native method
12690         </description>
12691       </param>
12692       <param id="new_address_ptr">
12693         <agentbuf><void/></agentbuf>
12694         <description>
12695           if the referenced address is changed (that is, if
12696           <code>*new_address_ptr</code> is set), the binding
12697           will instead be made to the supplied address.
12698         </description>
12699       </param>
12700     </parameters>
12701   </event>
12702 
12703   <event label="Exception"
12704          id="Exception" const="JVMTI_EVENT_EXCEPTION" filtered="thread" num="58">
12705     <description>
12706       Exception events are generated whenever an exception is first detected
12707       in a Java programming language method.
12708       Where "exception" means any <code>java.lang.Throwable</code>.
12709       The exception may have been thrown by a Java programming language or native
12710       method, but in the case of native methods, the event is not generated
12711       until the exception is first seen by a Java programming language method. If an exception is
12712       set and cleared in a native method (and thus is never visible to Java programming language code),
12713       no exception event is generated.
12714       <p/>
12715       The <code>method</code> and <code>location</code>
12716       parameters  uniquely identify the current location
12717       (where the exception was detected) and allow
12718       the mapping to source file and line number when that information is
12719       available. The <code>exception</code> field identifies the thrown
12720       exception object. The <code>catch_method</code>
12721       and <code>catch_location</code> identify the location of the catch clause,
12722       if any, that handles the thrown exception. If there is no such catch clause,
12723       each field is set to 0. There is no guarantee that the thread will ever
12724       reach this catch clause. If there are native methods on the call stack
12725       between the throw location and the catch clause, the exception may
12726       be reset by one of those native methods.
12727       Similarly, exceptions that are reported as uncaught (<code>catch_klass</code>
12728       et al. set to 0) may in fact be caught by native code.
12729       Agents can check for these occurrences by monitoring
12730       <eventlink id="ExceptionCatch"></eventlink> events.
12731       Note that finally clauses are implemented as catch and re-throw. Therefore they
12732       will be reported in the catch location.
12733     </description>
12734     <origin>jvmdi</origin>
12735     <capabilities>
12736       <required id="can_generate_exception_events"></required>
12737     </capabilities>
12738     <parameters>
12739       <param id="jni_env">
12740         <outptr>
12741           <struct>JNIEnv</struct>
12742         </outptr>
12743           <description>
12744             The JNI environment of the event (current) thread
12745           </description>
12746       </param>
12747       <param id="thread">
12748         <jthread/>
12749           <description>
12750             Thread generating the exception
12751           </description>
12752       </param>
12753       <param id="klass">
12754         <jclass method="method"/>
12755           <description>
12756             Class generating the exception
12757           </description>
12758       </param>
12759       <param id="method">
12760         <jmethodID class="klass"/>
12761           <description>
12762             Method generating the exception
12763           </description>
12764       </param>
12765       <param id="location">
12766         <jlocation/>
12767         <description>
12768           Location where exception occurred
12769         </description>
12770       </param>
12771       <param id="exception">
12772         <jobject/>
12773           <description>
12774             The exception being thrown
12775           </description>
12776       </param>
12777       <param id="catch_klass">
12778         <jclass method="catch_method"/>
12779           <description>
12780             Class that will catch the exception, or <code>NULL</code> if no known catch
12781           </description>
12782       </param>
12783       <param id="catch_method">
12784         <jmethodID class="catch_klass"/>
12785           <description>
12786             Method that will catch the exception, or <code>NULL</code> if no known catch
12787           </description>
12788       </param>
12789       <param id="catch_location">
12790         <jlocation/>
12791         <description>
12792           location which will catch the exception or zero if no known catch
12793         </description>
12794       </param>
12795     </parameters>
12796   </event>
12797 
12798   <event label="Exception Catch"
12799          id="ExceptionCatch" const="JVMTI_EVENT_EXCEPTION_CATCH" filtered="thread" num="59">
12800     <description>
12801       Exception catch events are generated whenever a thrown exception is caught.
12802       Where "exception" means any <code>java.lang.Throwable</code>.
12803       If the exception is caught in a Java programming language method, the event is generated
12804       when the catch clause is reached. If the exception is caught in a native
12805       method, the event is generated as soon as control is returned to a Java programming language
12806       method. Exception catch events are generated for any exception for which
12807       a throw was detected in a Java programming language method.
12808       Note that finally clauses are implemented as catch and re-throw. Therefore they
12809       will generate exception catch events.
12810       <p/>
12811       The <code>method</code> and <code>location</code>
12812       parameters uniquely identify the current location
12813       and allow the mapping to source file and line number when that information is
12814       available. For exceptions caught in a Java programming language method, the
12815       <code>exception</code> object identifies the exception object. Exceptions
12816       caught in native methods are not necessarily available by the time the
12817       exception catch is reported, so the <code>exception</code> field is set
12818       to <code>NULL</code>.
12819     </description>
12820     <origin>jvmdi</origin>
12821     <capabilities>
12822       <required id="can_generate_exception_events"></required>
12823     </capabilities>
12824     <parameters>
12825       <param id="jni_env">
12826         <outptr>
12827           <struct>JNIEnv</struct>
12828         </outptr>
12829           <description>
12830             The JNI environment of the event (current) thread
12831           </description>
12832       </param>
12833       <param id="thread">
12834         <jthread/>
12835           <description>
12836             Thread catching the exception
12837           </description>
12838       </param>
12839       <param id="klass">
12840         <jclass method="method"/>
12841           <description>
12842             Class catching the exception
12843           </description>
12844       </param>
12845       <param id="method">
12846         <jmethodID class="klass"/>
12847           <description>
12848             Method catching the exception
12849           </description>
12850       </param>
12851       <param id="location">
12852         <jlocation/>
12853         <description>
12854           Location where exception is being caught
12855         </description>
12856       </param>
12857       <param id="exception">
12858         <jobject/>
12859           <description>
12860             Exception being caught
12861           </description>
12862       </param>
12863     </parameters>
12864   </event>
12865 
12866   <event label="Thread Start"
12867          id="ThreadStart" const="JVMTI_EVENT_THREAD_START" num="52" phase="start">
12868     <description>
12869       A thread start event is generated by a new thread before its initial
12870       method executes. Thread start events are generated by platform threads.
12871       The capability
12872       <internallink id="jvmtiCapabilities.can_support_virtual_threads">
12873       <code>can_support_virtual_threads</code></internallink> determines
12874       if a new virtual thread generates a <code>ThreadStart</code> event or
12875       a <eventlink id="VirtualThreadStart"/> event. If disabled, a virtual
12876       thread generates a <code>ThreadStart</code> event. If enabled, a virtual
12877       thread generates a <code>VirtualThreadStart</code> event.
12878       <p/>
12879       A thread may be listed in the array returned by
12880       <functionlink id="GetAllThreads"></functionlink>
12881       before its thread start event is generated.
12882       It is possible for other events to be generated
12883       on a thread before its thread start event.
12884       <p/>
12885       The event is sent on the newly started <paramlink id="thread"></paramlink>.
12886     </description>
12887     <origin>jvmdi</origin>
12888     <capabilities>
12889     </capabilities>
12890     <parameters>
12891       <param id="jni_env">
12892         <outptr>
12893           <struct>JNIEnv</struct>
12894         </outptr>
12895           <description>
12896             The JNI environment of the event (current) thread.
12897           </description>
12898       </param>
12899       <param id="thread">
12900         <jthread/>
12901           <description>
12902             Thread starting
12903           </description>
12904       </param>
12905     </parameters>
12906   </event>
12907 
12908   <event label="Thread End"
12909          id="ThreadEnd" const="JVMTI_EVENT_THREAD_END" filtered="thread" num="53" phase="start">
12910     <description>
12911       A thread end event is generated by a terminating thread after its
12912       initial method has finished execution.
12913       Thread end events are generated by platform threads.
12914       The capability
12915       <internallink id="jvmtiCapabilities.can_support_virtual_threads">
12916       <code>can_support_virtual_threads</code></internallink> determines
12917       if a terminating virtual thread generates a <code>ThreadEnd</code>
12918       event or a <eventlink id="VirtualThreadEnd"/> event. If disabled, a
12919       virtual thread generates a <code>ThreadEnd</code> event. If enabled,
12920       a virtual thread generates a <code>VirtualThreadEnd</code> event.
12921       <p/>
12922       A thread may be listed in the array returned by
12923       <functionlink id="GetAllThreads"></functionlink>
12924       after its thread end event is generated.
12925       No events are generated on a thread
12926       after its thread end event.
12927       <p/>
12928       The event is sent on the dying <paramlink id="thread"></paramlink>.
12929     </description>
12930     <origin>jvmdi</origin>
12931     <capabilities>
12932     </capabilities>
12933     <parameters>
12934       <param id="jni_env">
12935         <outptr>
12936           <struct>JNIEnv</struct>
12937         </outptr>
12938           <description>
12939             The JNI environment of the event (current) thread.
12940           </description>
12941       </param>
12942       <param id="thread">
12943         <jthread/>
12944           <description>
12945             Thread ending
12946           </description>
12947       </param>
12948     </parameters>
12949   </event>
12950 
12951  <event label="Virtual Thread Start"
12952          id="VirtualThreadStart" const="JVMTI_EVENT_VIRTUAL_THREAD_START" filtered="thread" num="87" phase="start" since="14">
12953     <description>
12954       <b> VirtualThreadStart is a preview API of the Java platform. </b>
12955       <i>Preview features may be removed in a future release, or upgraded to
12956       permanent features of the Java platform.</i>.
12957       <p/>
12958       Virtual thread started events are generated before its initial method executes.
12959       <p/>
12960       The event is sent on the <paramlink id="thread"></paramlink>.
12961     </description>
12962     <origin>new</origin>
12963     <capabilities>
12964       <required id="can_support_virtual_threads">Can support virtual threads</required>
12965     </capabilities>
12966     <parameters>
12967       <param id="jni_env">
12968         <outptr>
12969           <struct>JNIEnv</struct>
12970         </outptr>
12971           <description>
12972             The JNI environment of the event (current) thread.
12973           </description>
12974       </param>
12975       <param id="virtual_thread">
12976         <jthread/>
12977           <description>
12978             Virtual thread started for execution.
12979           </description>
12980       </param>
12981     </parameters>
12982   </event>
12983 
12984   <event label="Virtual Thread End"
12985          id="VirtualThreadEnd" const="JVMTI_EVENT_VIRTUAL_THREAD_END" filtered="thread" num="88" phase="start" since="14">
12986     <description>
12987       <b> VirtualThreadEnd is a preview API of the Java platform. </b>
12988       <i>Preview features may be removed in a future release, or upgraded to
12989       permanent features of the Java platform.</i>.
12990       <p/>
12991       Virtual thread end events are generated after its initial method has finished execution.
12992       <p/>
12993       The event is sent on the <paramlink id="thread"></paramlink>.
12994     </description>
12995     <origin>new</origin>
12996     <capabilities>
12997       <required id="can_support_virtual_threads">Can support virtual threads</required>
12998     </capabilities>
12999     <parameters>
13000       <param id="jni_env">
13001         <outptr>
13002           <struct>JNIEnv</struct>
13003         </outptr>
13004           <description>
13005             The JNI environment of the event (current) thread.
13006           </description>
13007       </param>
13008       <param id="virtual_thread">
13009         <jthread/>
13010           <description>
13011             Virtual thread being ended.
13012           </description>
13013       </param>
13014     </parameters>
13015   </event>
13016 
13017   <elide>
13018   <event label="Virtual Thread Mount"
13019          id="VirtualThreadMount" const="JVMTI_EVENT_VIRTUAL_THREAD_MOUNT" filtered="thread" num="89" phase="start" since="14">
13020     <description>
13021       Virtual thread mount events are generated before its method continue to execute on the mounted thread.
13022       <p/>
13023       The event is sent on the <paramlink id="thread"></paramlink> the virtual thread is mounted to.
13024     </description>
13025     <origin>new</origin>
13026     <capabilities>
13027       <required id="can_support_virtual_threads">Can support virtual threads</required>
13028     </capabilities>
13029     <parameters>
13030       <param id="jni_env">
13031         <outptr>
13032           <struct>JNIEnv</struct>
13033         </outptr>
13034           <description>
13035             The JNI environment of the event (current) thread.
13036           </description>
13037       </param>
13038       <param id="virtual_thread">
13039         <jthread/>
13040           <description>
13041             Virtual thread that is mounted.
13042           </description>
13043       </param>
13044     </parameters>
13045   </event>
13046   </elide>
13047 
13048   <elide>
13049   <event label="Virtual Thread Unmount"
13050          id="VirtualThreadUnmount" const="JVMTI_EVENT_VIRTUAL_THREAD_UNMOUNT" filtered="thread" num="90" phase="start" since="14">
13051     <description>
13052       Virtual thread unmount events are generated when the virtual thread is about to be unmounted from the carrier thread.
13053       <p/>
13054       The event is sent on the <paramlink id="thread"></paramlink> the virtual thread is unmounted from.
13055     </description>
13056     <origin>new</origin>
13057     <capabilities>
13058       <required id="can_support_virtual_threads">Can support virtual threads</required>
13059     </capabilities>
13060     <parameters>
13061       <param id="jni_env">
13062         <outptr>
13063           <struct>JNIEnv</struct>
13064         </outptr>
13065           <description>
13066             The JNI environment of the event (current) thread.
13067           </description>
13068       </param>
13069       <param id="virtual_thread">
13070         <jthread/>
13071           <description>
13072             Virtual thread that is unmounted.
13073           </description>
13074       </param>
13075     </parameters>
13076   </event>
13077   </elide>
13078 
13079   <event label="Class Load"
13080          id="ClassLoad" const="JVMTI_EVENT_CLASS_LOAD" filtered="thread" phase="start" num="55">
13081     <description>
13082       A class load event is generated
13083       <functionlink id="GetLoadedClasses">when a class or interface is created.</functionlink>.
13084       <p/>
13085       Array class creation does not generate a class load event.
13086       The creation of a primitive class (for example, java.lang.Integer.TYPE)
13087       does not generate a class load event.
13088       <p/>
13089       The order of class load events generated by a particular thread is guaranteed
13090       to match the order of class loading within that thread.
13091       <p/>
13092       This event is sent at an early stage in loading the class. As
13093       a result the class should be used carefully.  Note, for example,
13094       that methods and fields are not yet loaded, so queries for methods,
13095       fields, subclasses, and so on will not give correct results.
13096       See "Loading of Classes and Interfaces" in the <i>Java Language
13097       Specification</i>.  For most
13098       purposes the <eventlink id="ClassPrepare"></eventlink> event will
13099       be more useful.
13100     </description>
13101     <origin>jvmdi</origin>
13102     <capabilities>
13103     </capabilities>
13104     <parameters>
13105       <param id="jni_env">
13106         <outptr>
13107           <struct>JNIEnv</struct>
13108         </outptr>
13109           <description>
13110             The JNI environment of the event (current) thread
13111           </description>
13112       </param>
13113       <param id="thread">
13114         <jthread/>
13115           <description>
13116             Thread loading the class
13117           </description>
13118       </param>
13119       <param id="klass">
13120         <jclass/>
13121           <description>
13122             Class being loaded
13123           </description>
13124       </param>
13125     </parameters>
13126   </event>
13127 
13128   <elide>
13129   <event label="Class Unload"
13130          id="ClassUnload" const="JVMTI_EVENT_CLASS_UNLOAD" num="57">
13131     <description>
13132       A class unload event is generated when the class is about to be unloaded.
13133       Class unload events take place during garbage collection and must be
13134       handled extremely carefully. The garbage collector holds many locks
13135       and has suspended all other threads, so the event handler cannot depend
13136       on the ability to acquire any locks. The class unload event handler should
13137       do as little as possible, perhaps by queuing information to be processed
13138       later.  In particular, the <code>jclass</code> should be used only in
13139       the JNI function <code>isSameObject</code> or in the following <jvmti/> functions:
13140       <ul>
13141         <li><functionlink id="GetClassSignature"></functionlink></li>
13142         <li><functionlink id="GetSourceFileName"></functionlink></li>
13143         <li><functionlink id="IsInterface"></functionlink></li>
13144         <li><functionlink id="IsArrayClass"></functionlink></li>
13145       </ul>
13146     </description>
13147     <origin>jvmdi</origin>
13148     <capabilities>
13149     </capabilities>
13150     <parameters>
13151       <param id="jni_env">
13152         <outptr>
13153           <struct>JNIEnv</struct>
13154         </outptr>
13155           <description>
13156             The JNI environment of the event (current) thread
13157           </description>
13158       </param>
13159       <param id="thread">
13160         <jthread/>
13161           <description>
13162             Thread generating the class unload
13163           </description>
13164       </param>
13165       <param id="klass">
13166         <jclass/>
13167           <description>
13168             Class being unloaded
13169           </description>
13170       </param>
13171     </parameters>
13172   </event>
13173   </elide>
13174 
13175   <event label="Class Prepare"
13176          id="ClassPrepare" const="JVMTI_EVENT_CLASS_PREPARE" filtered="thread" phase="start" num="56">
13177     <description>
13178       A class prepare event is generated when class preparation is complete.
13179       At this point, class fields, methods, and implemented interfaces are
13180       available, and no code from the class has been executed. Since array
13181       classes never have fields or methods, class prepare events are not
13182       generated for them. Class prepare events are not generated for
13183       primitive classes (for example, <code>java.lang.Integer.TYPE</code>).
13184     </description>
13185     <origin>jvmdi</origin>
13186     <capabilities>
13187     </capabilities>
13188     <parameters>
13189       <param id="jni_env">
13190         <outptr>
13191           <struct>JNIEnv</struct>
13192         </outptr>
13193           <description>
13194             The JNI environment of the event (current) thread
13195           </description>
13196       </param>
13197       <param id="thread">
13198         <jthread/>
13199           <description>
13200             Thread generating the class prepare
13201           </description>
13202       </param>
13203       <param id="klass">
13204         <jclass/>
13205           <description>
13206             Class being prepared
13207           </description>
13208       </param>
13209     </parameters>
13210   </event>
13211 
13212   <event label="Class File Load Hook" phase="any"
13213          id="ClassFileLoadHook" const="JVMTI_EVENT_CLASS_FILE_LOAD_HOOK" num="54">
13214     <description>
13215       This event is sent when the VM obtains class file data,
13216       but before it constructs
13217       the in-memory representation for that class.
13218       This event is also sent when the class is being modified by the
13219       <functionlink id="RetransformClasses"/> function or
13220       the <functionlink id="RedefineClasses"/> function,
13221       called in any <jvmti/> environment.
13222       The agent can instrument
13223       the existing class file data sent by the VM to include profiling/debugging hooks.
13224       See the description of
13225       <internallink id="bci">bytecode instrumentation</internallink>
13226       for usage information.
13227       <p/>
13228     When the capabilities
13229     <internallink id="jvmtiCapabilities.can_generate_early_class_hook_events">
13230     <code>can_generate_early_class_hook_events</code></internallink> and
13231     <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events">
13232     <code>can_generate_all_class_hook_events</code></internallink>
13233     are enabled then this event may be sent in the primordial phase.
13234     Otherwise, this event may be sent before the VM is initialized (the start
13235     <functionlink id="GetPhase">phase</functionlink>).
13236     Some classes might not be compatible
13237     with the function (eg. ROMized classes or implementation defined classes) and this event will
13238     not be generated for these classes.
13239     <p/>
13240     The agent must allocate the space for the modified
13241     class file data buffer
13242     using the memory allocation function
13243     <functionlink id="Allocate"></functionlink> because the
13244     VM is responsible for freeing the new class file data buffer
13245     using <functionlink id="Deallocate"></functionlink>.
13246     <p/>
13247     If the agent wishes to modify the class file, it must set
13248     <code>new_class_data</code> to point
13249     to the newly instrumented class file data buffer and set
13250     <code>new_class_data_len</code> to the length of that
13251     buffer before returning
13252     from this call.  If no modification is desired, the agent simply
13253     does not set <code>new_class_data</code>.  If multiple agents
13254     have enabled this event the results are chained. That is, if
13255     <code>new_class_data</code> has been set, it becomes the
13256     <code>class_data</code> for the next agent.
13257     <p/>
13258     When handling a class load in the live phase, then the
13259     <functionlink id="GetNamedModule"></functionlink>
13260     function can be used to map class loader and a package name to a module.
13261     When a class is being redefined or retransformed then
13262     <code>class_being_redefined</code> is non <code>NULL</code> and so
13263     the JNI <code>GetModule</code> function can also be used
13264     to obtain the Module.
13265     <p/>
13266     The order that this event is sent to each environment differs
13267     from other events.
13268     This event is sent to environments in the following order:
13269     <ul>
13270       <li><fieldlink id="can_retransform_classes"
13271                      struct="jvmtiCapabilities">retransformation
13272                                                 incapable</fieldlink>
13273           environments, in the
13274           order in which they were created
13275       </li>
13276       <li><fieldlink id="can_retransform_classes"
13277                      struct="jvmtiCapabilities">retransformation
13278                                                 capable</fieldlink>
13279           environments, in the
13280           order in which they were created
13281       </li>
13282     </ul>
13283     When triggered by <functionlink id="RetransformClasses"/>,
13284     this event is sent only to <fieldlink id="can_retransform_classes"
13285                      struct="jvmtiCapabilities">retransformation
13286                                                 capable</fieldlink>
13287     environments.
13288   </description>
13289   <origin>jvmpi</origin>
13290     <capabilities>
13291       <capability id="can_generate_all_class_hook_events"></capability>
13292       <capability id="can_generate_early_class_hook_events"></capability>
13293     </capabilities>
13294     <parameters>
13295       <param id="jni_env">
13296         <outptr>
13297           <struct>JNIEnv</struct>
13298         </outptr>
13299           <description>
13300             The JNI environment of the event (current) thread.
13301           </description>
13302       </param>
13303       <param id="class_being_redefined">
13304         <jclass/>
13305         <description>
13306           The class being
13307           <functionlink id="RedefineClasses">redefined</functionlink> or
13308           <functionlink id="RetransformClasses">retransformed</functionlink>.
13309           <code>NULL</code> if sent by class load.
13310         </description>
13311       </param>
13312       <param id="loader">
13313         <jobject/>
13314           <description>
13315             The class loader loading the class.
13316             <code>NULL</code> if the bootstrap class loader.
13317           </description>
13318       </param>
13319       <param id="name">
13320         <vmbuf><char/></vmbuf>
13321         <description>
13322             Name of class being loaded as a VM internal qualified name
13323             (for example, "java/util/List"), encoded as a
13324             <internallink id="mUTF">modified UTF-8</internallink> string.
13325             Note: if the class is defined with a <code>NULL</code> name or
13326             without a name specified, <code>name</code> will be <code>NULL</code>.
13327         </description>
13328       </param>
13329       <param id="protection_domain">
13330         <jobject/>
13331         <description>
13332           The <code>ProtectionDomain</code> of the class.
13333         </description>
13334       </param>
13335       <param id="class_data_len">
13336         <jint/>
13337         <description>
13338           Length of current class file data buffer.
13339         </description>
13340       </param>
13341       <param id="class_data">
13342         <vmbuf><uchar/></vmbuf>
13343         <description>
13344           Pointer to the current class file data buffer.
13345         </description>
13346       </param>
13347       <param id="new_class_data_len">
13348         <outptr><jint/></outptr>
13349         <description>
13350           Pointer to the length of the new class file data buffer.
13351         </description>
13352       </param>
13353       <param id="new_class_data">
13354         <agentbuf incount="new_class_data_len"><uchar/></agentbuf>
13355         <description>
13356           Pointer to the pointer to the instrumented class file data buffer.
13357         </description>
13358       </param>
13359     </parameters>
13360   </event>
13361 
13362   <event label="VM Start Event"
13363          id="VMStart" const="JVMTI_EVENT_VM_START" num="57" phase="start">
13364     <description>
13365       The VM start event signals the start of the VM.
13366       At this time JNI is live but the VM is not yet fully initialized.
13367       Once this event is generated, the agent is free to call any JNI function.
13368       This event signals the beginning of the start phase,
13369       <jvmti/> functions permitted in the start phase may be called.
13370       <p/>
13371       The timing of this event may depend on whether the agent has added the
13372       <internallink id="jvmtiCapabilities.can_generate_early_vmstart">
13373       <code>can_generate_early_vmstart</code></internallink> capability or not.
13374       If the capability has been added then the VM posts the event as early
13375       as possible. The VM is capable of executing bytecode but it may not have
13376       initialized to the point where it can load classes in modules other than
13377       <code>java.base</code>, or even arbitrary classes in <code>java.base</code>.
13378       Agents that do load-time instrumentation in this
13379       phase must take great care when instrumenting code that potentially
13380       executes in this phase. Extreme care should also be taken with JNI
13381       <code>FindClass</code> as it may not be possible to load classes and attempts
13382       to do so may result in unpredictable behavior, maybe even stability issues
13383       on some VM implementations.
13384       If the capability has not been added then the VM delays posting this
13385       event until it is capable of loading classes in modules other than
13386       <code>java.base</code> or the VM has completed its initialization.
13387       Agents that create more than one JVM TI environment, where the
13388       capability is added to some but not all environments, may observe the
13389       start phase beginning earlier in the JVM TI environments that possess
13390       the capability.
13391       <p/>
13392       In the case of VM start-up failure, this event will not be sent.
13393     </description>
13394     <origin>jvmdi</origin>
13395     <capabilities>
13396     </capabilities>
13397     <parameters>
13398       <param id="jni_env">
13399         <outptr>
13400           <struct>JNIEnv</struct>
13401         </outptr>
13402           <description>
13403             The JNI environment of the event (current) thread.
13404           </description>
13405       </param>
13406     </parameters>
13407   </event>
13408 
13409   <event label="VM Initialization Event"
13410          id="VMInit" const="JVMTI_EVENT_VM_INIT" num="50">
13411     <description>
13412       The VM initialization event signals the completion of VM initialization. Once
13413       this event is generated, the agent is free to call any JNI or <jvmti/>
13414       function. The VM initialization event can be preceded by or can be concurrent
13415       with other events, but
13416       the preceding events should be handled carefully, if at all, because the
13417       VM has not completed its initialization. The thread start event for the
13418       main application thread is guaranteed not to occur until after the
13419       handler for the VM initialization event returns.
13420       <p/>
13421       In the case of VM start-up failure, this event will not be sent.
13422     </description>
13423     <origin>jvmdi</origin>
13424     <capabilities>
13425     </capabilities>
13426     <parameters>
13427       <param id="jni_env">
13428         <outptr>
13429           <struct>JNIEnv</struct>
13430         </outptr>
13431           <description>
13432             The JNI environment of the event (current) thread.
13433           </description>
13434       </param>
13435       <param id="thread">
13436         <jthread/>
13437           <description>
13438             The initial thread
13439           </description>
13440       </param>
13441     </parameters>
13442   </event>
13443 
13444   <event label="VM Death Event"
13445          id="VMDeath" const="JVMTI_EVENT_VM_DEATH" num="51">
13446     <description>
13447       The VM death event notifies the agent of the termination of the VM.
13448       No events will occur after the VMDeath event.
13449       <p/>
13450       In the case of VM start-up failure, this event will not be sent.
13451       Note that <internallink id="onunload">Agent_OnUnload</internallink>
13452       will still be called in these cases.
13453     </description>
13454     <origin>jvmdi</origin>
13455     <capabilities>
13456     </capabilities>
13457     <parameters>
13458       <param id="jni_env">
13459         <outptr>
13460           <struct>JNIEnv</struct>
13461         </outptr>
13462           <description>
13463             The JNI environment of the event (current) thread
13464           </description>
13465       </param>
13466     </parameters>
13467   </event>
13468 
13469   <event label="Compiled Method Load" phase="start"
13470          id="CompiledMethodLoad" const="JVMTI_EVENT_COMPILED_METHOD_LOAD" num="68">
13471     <description>
13472       Sent when a method is compiled and loaded into memory by the VM.
13473       If it is unloaded, the <eventlink id="CompiledMethodUnload"/> event is sent.
13474       If it is moved, the <eventlink id="CompiledMethodUnload"/> event is sent,
13475       followed by a new <code>CompiledMethodLoad</code> event.
13476       Note that a single method may have multiple compiled forms, and that
13477       this event will be sent for each form.
13478       Note also that several methods may be inlined into a single
13479       address range, and that this event will be sent for each method.
13480       <p/>
13481       These events can be sent after their initial occurrence with
13482       <functionlink id="GenerateEvents"></functionlink>.
13483     </description>
13484     <origin>jvmpi</origin>
13485     <typedef id="jvmtiAddrLocationMap" label="Native address to location entry">
13486       <field id="start_address">
13487         <vmbuf><void/></vmbuf>
13488         <description>
13489           Starting native address of code corresponding to a location
13490         </description>
13491       </field>
13492       <field id="location">
13493         <jlocation/>
13494         <description>
13495           Corresponding location. See
13496           <functionlink id="GetJLocationFormat"></functionlink>
13497           for the meaning of location.
13498         </description>
13499       </field>
13500     </typedef>
13501     <capabilities>
13502       <required id="can_generate_compiled_method_load_events"></required>
13503     </capabilities>
13504     <parameters>
13505       <param id="klass">
13506         <jclass method="method"/>
13507           <description>
13508             Class of the method being compiled and loaded
13509           </description>
13510       </param>
13511       <param id="method">
13512         <jmethodID class="klass"/>
13513           <description>
13514             Method being compiled and loaded
13515           </description>
13516       </param>
13517       <param id="code_size">
13518         <jint/>
13519         <description>
13520           Size of compiled code
13521         </description>
13522       </param>
13523       <param id="code_addr">
13524         <vmbuf><void/></vmbuf>
13525         <description>
13526           Address where compiled method code is loaded
13527         </description>
13528       </param>
13529       <param id="map_length">
13530         <jint/>
13531         <description>
13532           Number of <typelink id="jvmtiAddrLocationMap"></typelink>
13533           entries in the address map.
13534           Zero if mapping information cannot be supplied.
13535         </description>
13536       </param>
13537       <param id="map">
13538         <vmbuf><struct>jvmtiAddrLocationMap</struct></vmbuf>
13539         <description>
13540           Map from native addresses to location.
13541           The native address range of each entry is from
13542           <fieldlink id="start_address" struct="jvmtiAddrLocationMap"></fieldlink>
13543           to <code>start_address-1</code> of the next entry.
13544           <code>NULL</code> if mapping information cannot be supplied.
13545         </description>
13546       </param>
13547       <param id="compile_info">
13548         <vmbuf><void/></vmbuf>
13549         <description>
13550           VM-specific compilation information.
13551           The referenced compile information is managed by the VM
13552           and must not depend on the agent for collection.
13553           A VM implementation defines the content and lifetime
13554           of the information.
13555         </description>
13556       </param>
13557     </parameters>
13558   </event>
13559 
13560   <event label="Compiled Method Unload" phase="start"
13561          id="CompiledMethodUnload" const="JVMTI_EVENT_COMPILED_METHOD_UNLOAD" num="69">
13562     <description>
13563       Sent when a compiled method is unloaded from memory.
13564       This event might not be sent on the thread which performed the unload.
13565       This event may be sent sometime after the unload occurs, but
13566       will be sent before the memory is reused
13567       by a newly generated compiled method. This event may be sent after
13568       the class is unloaded.
13569     </description>
13570     <origin>jvmpi</origin>
13571     <capabilities>
13572       <required id="can_generate_compiled_method_load_events"></required>
13573     </capabilities>
13574     <parameters>
13575       <param id="klass">
13576         <jclass method="method"/>
13577           <description>
13578             Class of the compiled method being unloaded.
13579           </description>
13580       </param>
13581       <param id="method">
13582         <jmethodID class="klass"/>
13583           <description>
13584             Compiled method being unloaded.
13585             For identification of the compiled method only -- the class
13586             may be unloaded and therefore the method should not be used
13587             as an argument to further JNI or <jvmti/> functions.
13588           </description>
13589       </param>
13590       <param id="code_addr">
13591         <vmbuf><void/></vmbuf>
13592         <description>
13593           Address where compiled method code was loaded.
13594           For identification of the compiled method only --
13595           the space may have been reclaimed.
13596         </description>
13597       </param>
13598     </parameters>
13599   </event>
13600 
13601   <event label="Dynamic Code Generated" phase="any"
13602          id="DynamicCodeGenerated" const="JVMTI_EVENT_DYNAMIC_CODE_GENERATED" num="70">
13603     <description>
13604       Sent when a component of the virtual machine is generated dynamically.
13605       This does not correspond to Java programming language code that is
13606       compiled--see <eventlink id="CompiledMethodLoad"></eventlink>.
13607       This is for native code--for example, an interpreter that is generated
13608       differently depending on command-line options.
13609       <p/>
13610       Note that this event has no controlling capability.
13611       If a VM cannot generate these events, it simply does not send any.
13612       <p/>
13613       These events can be sent after their initial occurrence with
13614       <functionlink id="GenerateEvents"></functionlink>.
13615     </description>
13616     <origin>jvmpi</origin>
13617     <capabilities>
13618     </capabilities>
13619     <parameters>
13620       <param id="name">
13621         <vmbuf><char/></vmbuf>
13622         <description>
13623           Name of the code, encoded as a
13624           <internallink id="mUTF">modified UTF-8</internallink> string.
13625           Intended for display to an end-user.
13626           The name might not be unique.
13627         </description>
13628       </param>
13629       <param id="address">
13630         <vmbuf><void/></vmbuf>
13631         <description>
13632           Native address of the code
13633         </description>
13634       </param>
13635       <param id="length">
13636         <jint/>
13637         <description>
13638           Length in bytes of the code
13639         </description>
13640       </param>
13641     </parameters>
13642   </event>
13643 
13644   <event label="Data Dump Request"
13645          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
13646     <description>
13647       Sent by the VM to request the agent to dump its data.  This
13648       is just a hint and the agent need not react to this event.
13649       This is useful for processing command-line signals from users.  For
13650       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Linux
13651       causes the VM to send this event to the agent.
13652     </description>
13653     <origin>jvmpi</origin>
13654     <capabilities>
13655     </capabilities>
13656     <parameters>
13657     </parameters>
13658   </event>
13659 
13660   <event label="Monitor Contended Enter"
13661          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
13662     <description>
13663       Sent when a thread is attempting to enter a Java programming language
13664       monitor already acquired by another thread.
13665     </description>
13666     <origin>jvmpi</origin>
13667     <capabilities>
13668       <required id="can_generate_monitor_events"></required>
13669     </capabilities>
13670     <parameters>
13671       <param id="jni_env">
13672         <outptr>
13673           <struct>JNIEnv</struct>
13674         </outptr>
13675           <description>
13676             The JNI environment of the event (current) thread
13677           </description>
13678       </param>
13679       <param id="thread">
13680         <jthread/>
13681           <description>
13682             JNI local reference to the thread
13683             attempting to enter the monitor
13684           </description>
13685       </param>
13686       <param id="object">
13687         <jobject/>
13688           <description>
13689             JNI local reference to the monitor
13690           </description>
13691       </param>
13692     </parameters>
13693   </event>
13694 
13695   <event label="Monitor Contended Entered"
13696          id="MonitorContendedEntered" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTERED" filtered="thread" num="76">
13697     <description>
13698       Sent when a thread enters a Java programming language
13699       monitor after waiting for it to be released by another thread.
13700     </description>
13701     <origin>jvmpi</origin>
13702     <capabilities>
13703       <required id="can_generate_monitor_events"></required>
13704     </capabilities>
13705     <parameters>
13706       <param id="jni_env">
13707         <outptr>
13708           <struct>JNIEnv</struct>
13709         </outptr>
13710           <description>
13711             The JNI environment of the event (current) thread
13712           </description>
13713       </param>
13714       <param id="thread">
13715         <jthread/>
13716           <description>
13717             JNI local reference to the thread entering
13718             the monitor
13719           </description>
13720       </param>
13721       <param id="object">
13722         <jobject/>
13723           <description>
13724             JNI local reference to the monitor
13725           </description>
13726       </param>
13727     </parameters>
13728   </event>
13729 
13730   <event label="Monitor Wait"
13731          id="MonitorWait" const="JVMTI_EVENT_MONITOR_WAIT" filtered="thread" num="73">
13732     <description>
13733       Sent when a thread is about to wait on an object.
13734     </description>
13735     <origin>jvmpi</origin>
13736     <capabilities>
13737       <required id="can_generate_monitor_events"></required>
13738     </capabilities>
13739     <parameters>
13740       <param id="jni_env">
13741         <outptr>
13742           <struct>JNIEnv</struct>
13743         </outptr>
13744           <description>
13745             The JNI environment of the event (current) thread
13746           </description>
13747       </param>
13748       <param id="thread">
13749         <jthread/>
13750           <description>
13751             JNI local reference to the thread about to wait
13752           </description>
13753       </param>
13754       <param id="object">
13755         <jobject/>
13756           <description>
13757             JNI local reference to the monitor
13758           </description>
13759       </param>
13760       <param id="timeout">
13761         <jlong/>
13762         <description>
13763           The number of milliseconds the thread will wait
13764         </description>
13765       </param>
13766     </parameters>
13767   </event>
13768 
13769   <event label="Monitor Waited"
13770          id="MonitorWaited" const="JVMTI_EVENT_MONITOR_WAITED" filtered="thread" num="74">
13771     <description>
13772       Sent when a thread finishes waiting on an object.
13773     </description>
13774     <origin>jvmpi</origin>
13775     <capabilities>
13776       <required id="can_generate_monitor_events"></required>
13777     </capabilities>
13778     <parameters>
13779       <param id="jni_env">
13780         <outptr>
13781           <struct>JNIEnv</struct>
13782         </outptr>
13783           <description>
13784             The JNI environment of the event (current) thread
13785           </description>
13786       </param>
13787       <param id="thread">
13788         <jthread/>
13789           <description>
13790             JNI local reference to the thread that was finished waiting
13791           </description>
13792       </param>
13793       <param id="object">
13794         <jobject/>
13795           <description>
13796             JNI local reference to the monitor.
13797           </description>
13798       </param>
13799       <param id="timed_out">
13800         <jboolean/>
13801         <description>
13802           True if the monitor timed out
13803         </description>
13804       </param>
13805     </parameters>
13806   </event>
13807 
13808   <event label="Resource Exhausted"
13809          id="ResourceExhausted" const="JVMTI_EVENT_RESOURCE_EXHAUSTED" num="80"
13810          since="1.1">
13811     <description>
13812       Sent when a VM resource needed by a running application has been exhausted.
13813       Except as required by the optional capabilities, the set of resources
13814       which report exhaustion is implementation dependent.
13815       <p/>
13816       The following bit flags define the properties of the resource exhaustion:
13817       <constants id="jvmtiResourceExhaustionFlags"
13818                  label="Resource Exhaustion Flags"
13819                  kind="bits"
13820                  since="1.1">
13821         <constant id="JVMTI_RESOURCE_EXHAUSTED_OOM_ERROR" num="0x0001">
13822           After this event returns, the VM will throw a
13823           <code>java.lang.OutOfMemoryError</code>.
13824         </constant>
13825         <constant id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP" num="0x0002">
13826           The VM was unable to allocate memory from the <tm>Java</tm>
13827           platform <i>heap</i>.
13828           The <i>heap</i> is the runtime
13829           data area from which memory for all class instances and
13830           arrays are allocated.
13831         </constant>
13832         <constant id="JVMTI_RESOURCE_EXHAUSTED_THREADS" num="0x0004">
13833           The VM was unable to create a thread.
13834         </constant>
13835       </constants>
13836     </description>
13837     <origin>new</origin>
13838     <capabilities>
13839       <capability id="can_generate_resource_exhaustion_heap_events">
13840         Can generate events when the VM is unable to allocate memory from the
13841         <internallink id="JVMTI_RESOURCE_EXHAUSTED_JAVA_HEAP">heap</internallink>.
13842       </capability>
13843       <capability id="can_generate_resource_exhaustion_threads_events">
13844         Can generate events when the VM is unable to
13845         <internallink id="JVMTI_RESOURCE_EXHAUSTED_THREADS">create
13846         a thread</internallink>.
13847       </capability>
13848     </capabilities>
13849     <parameters>
13850       <param id="jni_env">
13851         <outptr>
13852           <struct>JNIEnv</struct>
13853         </outptr>
13854           <description>
13855             The JNI environment of the event (current) thread
13856           </description>
13857       </param>
13858       <param id="flags">
13859         <jint/>
13860         <description>
13861           Flags defining the properties of the of resource exhaustion
13862           as specified by the
13863           <internallink id="jvmtiResourceExhaustionFlags">Resource
13864           Exhaustion Flags</internallink>.
13865           </description>
13866         </param>
13867       <param id="reserved">
13868         <vmbuf><void/></vmbuf>
13869         <description>
13870           Reserved.
13871         </description>
13872       </param>
13873       <param id="description">
13874         <vmbuf><char/></vmbuf>
13875         <description>
13876           Description of the resource exhaustion, encoded as a
13877           <internallink id="mUTF">modified UTF-8</internallink> string.
13878         </description>
13879       </param>
13880     </parameters>
13881   </event>
13882 
13883   <event label="VM Object Allocation"
13884          id="VMObjectAlloc" const="JVMTI_EVENT_VM_OBJECT_ALLOC" num="84">
13885     <description>
13886       Sent when a method causes the virtual machine to directly allocate an
13887       Object visible to Java programming language code.
13888       Generally object allocation should be detected by instrumenting
13889       the bytecodes of allocating methods.
13890       Object allocation generated in native code by JNI function
13891       calls should be detected using
13892       <internallink id="jniIntercept">JNI function interception</internallink>.
13893       Some methods might not have associated bytecodes and are not
13894       native methods, they instead are executed directly by the
13895       VM. These methods should send this event.
13896       Virtual machines which are incapable of bytecode instrumentation
13897       for some or all of their methods can send this event.
13898 
13899       Note that the <internallink
13900       id="SampledObjectAlloc">SampledObjectAlloc</internallink>
13901       event is triggered on all Java object allocations, including those
13902       caused by bytecode method execution, JNI method execution, and
13903       directly by VM methods.
13904       <p/>
13905       Typical examples where this event might be sent:
13906       <ul>
13907         <li>Reflection -- for example, <code>java.lang.Class.newInstance()</code></li>
13908         <li>Methods not represented by bytecodes -- for example, VM intrinsics and
13909             J2ME preloaded classes</li>
13910       </ul>
13911       Cases where this event would not be generated:
13912       <ul>
13913         <li>Allocation due to bytecodes -- for example, the <code>new</code>
13914             and <code>newarray</code> VM instructions</li>
13915         <li>Allocation due to JNI function calls -- for example,
13916             <code>AllocObject</code></li>
13917         <li>Allocations during VM initialization</li>
13918         <li>VM internal objects</li>
13919       </ul>
13920     </description>
13921     <origin>new</origin>
13922     <capabilities>
13923       <required id="can_generate_vm_object_alloc_events"></required>
13924     </capabilities>
13925     <parameters>
13926       <param id="jni_env">
13927         <outptr>
13928           <struct>JNIEnv</struct>
13929         </outptr>
13930           <description>
13931             The JNI environment of the event (current) thread
13932           </description>
13933       </param>
13934       <param id="thread">
13935         <jthread/>
13936           <description>
13937             Thread allocating the object.
13938           </description>
13939       </param>
13940       <param id="object">
13941         <jobject/>
13942           <description>
13943             JNI local reference to the object that was allocated.
13944           </description>
13945       </param>
13946       <param id="object_klass">
13947         <jclass/>
13948           <description>
13949             JNI local reference to the class of the object.
13950           </description>
13951       </param>
13952       <param id="size">
13953         <jlong/>
13954         <description>
13955             Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
13956         </description>
13957       </param>
13958     </parameters>
13959   </event>
13960 
13961   <event label="Sampled Object Allocation"
13962     id="SampledObjectAlloc" const="JVMTI_EVENT_SAMPLED_OBJECT_ALLOC" filtered="thread" num="86" since="11">
13963     <description>
13964       Sent when an allocated object is sampled.
13965       By default, the sampling interval is set to 512KB. The sampling is semi-random to avoid
13966       pattern-based bias and provides an approximate overall average interval over long periods of
13967       sampling.
13968       <p/>
13969       Each thread tracks how many bytes it has allocated since it sent the last event.
13970       When the number of bytes exceeds the sampling interval, it will send another event.
13971       This implies that, on average, one object will be sampled every time a thread has
13972       allocated 512KB bytes since the last sample.
13973       <p/>
13974       Note that the sampler is pseudo-random: it will not sample every 512KB precisely.
13975       The goal of this is to ensure high quality sampling even if allocation is
13976       happening in a fixed pattern (i.e., the same set of objects are being allocated
13977       every 512KB).
13978       <p/>
13979       If another sampling interval is required, the user can call
13980       <functionlink id="SetHeapSamplingInterval"></functionlink> with a strictly positive integer value,
13981       representing the new sampling interval.
13982       <p/>
13983       This event is sent once the sampled allocation has been performed.  It provides the object, stack trace
13984       of the allocation, the thread allocating, the size of allocation, and the object's class.
13985       <p/>
13986       A typical use case of this system is to determine where heap allocations originate.
13987       In conjunction with weak references and the function
13988       <functionlink id="GetStackTrace"></functionlink>, a user can track which objects were allocated from which
13989       stack trace, and which are still live during the execution of the program.
13990     </description>
13991     <origin>new</origin>
13992     <capabilities>
13993       <required id="can_generate_sampled_object_alloc_events"></required>
13994     </capabilities>
13995     <parameters>
13996       <param id="jni_env">
13997         <outptr>
13998           <struct>JNIEnv</struct>
13999         </outptr>
14000         <description>
14001           The JNI environment of the event (current) thread.
14002         </description>
14003       </param>
14004       <param id="thread">
14005         <jthread/>
14006         <description>
14007           Thread allocating the object.
14008         </description>
14009       </param>
14010       <param id="object">
14011         <jobject/>
14012         <description>
14013           JNI local reference to the object that was allocated.
14014         </description>
14015       </param>
14016       <param id="object_klass">
14017         <jclass/>
14018         <description>
14019           JNI local reference to the class of the object
14020         </description>
14021       </param>
14022       <param id="size">
14023         <jlong/>
14024         <description>
14025           Size of the object (in bytes). See <functionlink id="GetObjectSize"/>.
14026         </description>
14027       </param>
14028     </parameters>
14029   </event>
14030 
14031   <event label="Object Free"
14032         id="ObjectFree" const="JVMTI_EVENT_OBJECT_FREE" num="83">
14033     <description>
14034       An Object Free event is sent when the garbage collector frees an object.
14035       Events are only sent for tagged objects--see
14036       <internallink id="Heap">heap functions</internallink>.
14037       <p/>
14038       The event handler must not use JNI functions and
14039       must not use <jvmti/> functions except those which
14040       specifically allow such use (see the raw monitor, memory management,
14041       and environment local storage functions).
14042     </description>
14043     <origin>new</origin>
14044     <capabilities>
14045       <required id="can_generate_object_free_events"></required>
14046     </capabilities>
14047     <parameters>
14048       <param id="tag">
14049         <jlong/>
14050         <description>
14051           The freed object's tag
14052         </description>
14053       </param>
14054     </parameters>
14055   </event>
14056 
14057   <event label="Garbage Collection Start"
14058          id="GarbageCollectionStart" const="JVMTI_EVENT_GARBAGE_COLLECTION_START" num="81">
14059     <description>
14060       A Garbage Collection Start event is sent when a
14061       garbage collection pause begins.
14062       Only stop-the-world collections are reported--that is, collections during
14063       which all threads cease to modify the state of the Java virtual machine.
14064       This means that some collectors will never generate these events.
14065       This event is sent while the VM is still stopped, thus
14066       the event handler must not use JNI functions and
14067       must not use <jvmti/> functions except those which
14068       specifically allow such use (see the raw monitor, memory management,
14069       and environment local storage functions).
14070       <p/>
14071       This event is always sent as a matched pair with
14072       <eventlink id="GarbageCollectionFinish"/>
14073       (assuming both events are enabled) and no garbage collection
14074       events will occur between them.
14075     </description>
14076     <origin>new</origin>
14077     <capabilities>
14078       <required id="can_generate_garbage_collection_events"></required>
14079     </capabilities>
14080     <parameters>
14081     </parameters>
14082   </event>
14083 
14084   <event label="Garbage Collection Finish"
14085          id="GarbageCollectionFinish" const="JVMTI_EVENT_GARBAGE_COLLECTION_FINISH" num="82">
14086     <description>
14087       A Garbage Collection Finish event is sent when a
14088       garbage collection pause ends.
14089       This event is sent while the VM is still stopped, thus
14090       the event handler must not use JNI functions and
14091       must not use <jvmti/> functions except those which
14092       specifically allow such use (see the raw monitor, memory management,
14093       and environment local storage functions).
14094       <p/>
14095       Some agents may need to do post garbage collection operations that
14096       require the use of the disallowed <jvmti/> or JNI functions. For these
14097       cases an agent thread can be created which waits on a raw monitor,
14098       and the handler for the Garbage Collection Finish event simply
14099       notifies the raw monitor
14100       <p/>
14101       This event is always sent as a matched pair with
14102       <eventlink id="GarbageCollectionStart"/> (assuming both events are enabled).
14103       <issue>
14104         The most important use of this event is to provide timing information,
14105         and thus additional information is not required.  However,
14106         information about the collection which is "free" should be included -
14107         what that information is needs to be determined.
14108       </issue>
14109     </description>
14110     <origin>new</origin>
14111     <capabilities>
14112       <required id="can_generate_garbage_collection_events"></required>
14113     </capabilities>
14114     <parameters>
14115     </parameters>
14116   </event>
14117 
14118   <elide>
14119   <event label="Verbose Output" phase="any"
14120          id="VerboseOutput" const="JVMTI_EVENT_VERBOSE_OUTPUT" num="85">
14121     <description>
14122       Send verbose messages as strings.
14123         <issue>
14124           This format is extremely fragile, as it can change with each
14125           platform, collector and version.  Alternatives include:
14126           <ul>
14127             <li>building off Java programming language M and M APIs</li>
14128             <li>XML</li>
14129             <li>key/value pairs</li>
14130             <li>removing it</li>
14131           </ul>
14132         </issue>
14133         <issue>
14134           Though this seemed trivial to implement.
14135           In the RI it appears this will be quite complex.
14136         </issue>
14137     </description>
14138     <origin>new</origin>
14139     <capabilities>
14140     </capabilities>
14141     <parameters>
14142       <param id="flag">
14143         <enum>jvmtiVerboseFlag</enum>
14144         <description>
14145           Which verbose output is being sent.
14146         </description>
14147       </param>
14148       <param id="message">
14149         <vmbuf><char/></vmbuf>
14150         <description>
14151           Message text, encoded as a
14152           <internallink id="mUTF">modified UTF-8</internallink> string.
14153         </description>
14154       </param>
14155     </parameters>
14156   </event>
14157   </elide>
14158 
14159 </eventsection>
14160 
14161 <datasection>
14162   <intro>
14163     <jvmti/> extends the data types defined by JNI.
14164   </intro>
14165   <basetypes id="jniTypes" label="JNI Types Used in the JVM Tool Interface">
14166     <basetype id="jboolean">
14167       <description>
14168         Holds a Java programming language <code>boolean</code>.
14169         Unsigned 8 bits.
14170       </description>
14171     </basetype>
14172     <basetype id="jchar">
14173       <description>
14174         Holds a Java programming language <code>char</code>.
14175         Unsigned 16 bits.
14176       </description>
14177     </basetype>
14178     <basetype id="jint">
14179       <description>
14180         Holds a Java programming language <code>int</code>.
14181         Signed 32 bits.
14182       </description>
14183     </basetype>
14184     <basetype id="jlong">
14185       <description>
14186         Holds a Java programming language <code>long</code>.
14187         Signed 64 bits.
14188       </description>
14189     </basetype>
14190     <basetype id="jfloat">
14191       <description>
14192         Holds a Java programming language <code>float</code>.
14193         32 bits.
14194       </description>
14195     </basetype>
14196     <basetype id="jdouble">
14197       <description>
14198         Holds a Java programming language <code>double</code>.
14199         64 bits.
14200       </description>
14201     </basetype>
14202     <basetype id="jobject">
14203       <description>
14204         Holds a Java programming language object.
14205       </description>
14206     </basetype>
14207     <basetype id="jclass">
14208       <description>
14209         Holds a Java programming language class.
14210       </description>
14211     </basetype>
14212     <basetype id="jvalue">
14213       <description>
14214         Is a union of all primitive types and <code>jobject</code>.  Thus, holds any Java
14215         programming language value.
14216       </description>
14217     </basetype>
14218     <basetype id="jfieldID">
14219       <description>
14220         Identifies a Java programming language field.
14221         <code>jfieldID</code>s returned by <jvmti/> functions and events may be
14222         safely stored.
14223       </description>
14224     </basetype>
14225     <basetype id="jmethodID">
14226       <description>
14227         Identifies a Java programming language method, initializer, or constructor.
14228         <code>jmethodID</code>s returned by <jvmti/> functions and events may be
14229         safely stored.  However, if the class is unloaded, they become invalid
14230         and must not be used.
14231       </description>
14232     </basetype>
14233     <basetype id="JNIEnv">
14234       <description>
14235         Pointer to the JNI function table.  Pointer to this (<code>JNIEnv *</code>)
14236         is a JNI environment.
14237       </description>
14238     </basetype>
14239   </basetypes>
14240 
14241   <basetypes id="jvmtiTypes" label="JVM Tool Interface Base Types">
14242     <basetype id="jvmtiEnv">
14243       <description>
14244         The <jvmti/> <internallink id="environments">environment</internallink> pointer.
14245         See the <internallink id="FunctionSection">Function Section</internallink>.
14246         <code>jvmtiEnv</code> points to the
14247         <internallink id="FunctionTable">function table</internallink> pointer.
14248       </description>
14249     </basetype>
14250     <basetype id="jthread">
14251       <definition>typedef jobject jthread;</definition>
14252       <description>
14253         Subtype of <datalink id="jobject"></datalink> that holds a thread.
14254       </description>
14255     </basetype>
14256     <basetype id="jthreadGroup">
14257       <definition>typedef jobject jthreadGroup;</definition>
14258       <description>
14259         Subtype of <datalink id="jobject"></datalink> that holds a thread group.
14260       </description>
14261     </basetype>
14262     <basetype id="jlocation">
14263       <definition>typedef jlong jlocation;</definition>
14264       <description>
14265         A 64 bit value, representing a monotonically increasing
14266         executable position within a method.
14267         <code>-1</code> indicates a native method.
14268         See <functionlink id="GetJLocationFormat"></functionlink> for the format on a
14269         given VM.
14270       </description>
14271     </basetype>
14272     <basetype id="jrawMonitorID">
14273       <definition>struct _jrawMonitorID;
14274 typedef struct _jrawMonitorID *jrawMonitorID;</definition>
14275       <description>
14276         A raw monitor.
14277       </description>
14278     </basetype>
14279     <basetype id="jvmtiError">
14280       <description>
14281         Holds an error return code.
14282         See the <internallink id="ErrorSection">Error section</internallink> for possible values.
14283         <example>
14284 typedef enum {
14285     JVMTI_ERROR_NONE = 0,
14286     JVMTI_ERROR_INVALID_THREAD = 10,
14287       ...
14288 } jvmtiError;
14289 </example>
14290       </description>
14291     </basetype>
14292     <basetype id="jvmtiEvent">
14293       <description>
14294         An identifier for an event type.
14295         See the <internallink id="EventSection">Event section</internallink> for possible values.
14296         It is guaranteed that future versions of this specification will
14297         never assign zero as an event type identifier.
14298 <example>
14299 typedef enum {
14300     JVMTI_EVENT_SINGLE_STEP = 1,
14301     JVMTI_EVENT_BREAKPOINT = 2,
14302       ...
14303 } jvmtiEvent;
14304 </example>
14305       </description>
14306     </basetype>
14307     <basetype id="jvmtiEventCallbacks" name="eventCallbacks">
14308       <description>
14309         The callbacks used for events.
14310 <example>
14311 typedef struct {
14312     jvmtiEventVMInit VMInit;
14313     jvmtiEventVMDeath VMDeath;
14314       ...
14315 } jvmtiEventCallbacks;
14316 </example>
14317         See <internallink id="jvmtiEventCallbacks">event callbacks</internallink>
14318         for the complete structure.
14319         <p/>
14320         Where, for example, the VM initialization callback is defined:
14321 <example>
14322 typedef void (JNICALL *jvmtiEventVMInit)
14323     (jvmtiEnv *jvmti_env,
14324      JNIEnv* jni_env,
14325      jthread thread);
14326 </example>
14327         See the individual events for the callback function definition.
14328       </description>
14329     </basetype>
14330     <basetype id="jniNativeInterface">
14331       <definition>typedef struct JNINativeInterface_ jniNativeInterface;</definition>
14332       <description>
14333         Typedef for the JNI function table <code>JNINativeInterface</code>
14334         defined in the
14335         <externallink id="jni/functions.html#interface-function-table">
14336           JNI Specification</externallink>.
14337         The JNI reference implementation defines this with an underscore.
14338       </description>
14339     </basetype>
14340   </basetypes>
14341 
14342 </datasection>
14343 
14344 <issuessection label="Issues">
14345   <intro id="suspendRequired" label="Resolved Issue: Suspend - Required or Automatic">
14346     JVMDI requires that the agent suspend threads before calling
14347     certain sensitive functions.  JVMPI requires garbage collection to be
14348     disabled before calling certain sensitive functions.
14349     It was suggested that rather than have this requirement, that
14350     VM place itself in a suitable state before performing an
14351     operation.  This makes considerable sense since each VM
14352     knows its requirements and can most easily arrange a
14353     safe state.
14354     <p/>
14355     The ability to externally suspend/resume threads will, of
14356     course, remain.  The ability to enable/disable garbage collection will not.
14357     <p/>
14358     This issue is resolved--suspend will not
14359     be required.  The spec has been updated to reflect this.
14360   </intro>
14361 
14362   <intro id="stackSampling" label="Resolved Issue: Call Stack Sampling">
14363     There are a variety of approaches to sampling call stacks.
14364     The biggest bifurcation is between VM controlled and agent
14365     controlled.
14366     <p/>
14367     This issue is resolved--agent controlled
14368     sampling will be the approach.
14369   </intro>
14370 
14371   <intro id="threadRepresentation" label="Resolved Issue: Thread Representation">
14372     JVMDI represents threads as jthread.  JVMPI primarily
14373     uses JNIEnv* to represent threads.
14374     <p/>
14375     The Expert Group has chosen jthread as the representation
14376     for threads in <jvmti/>.
14377     JNIEnv* is sent by
14378     events since it is needed to JNI functions.  JNIEnv, per the
14379     JNI spec, are not supposed to be used outside their thread.
14380   </intro>
14381 
14382   <intro id="design" label="Resolved Issue: Method Representation">
14383     The JNI spec allows an implementation to depend on jclass/jmethodID
14384     pairs, rather than simply a jmethodID, to reference a method.
14385     JVMDI, for consistency, choose the same representation.
14386     JVMPI, however, specifies that a jmethodID alone maps to a
14387     method.  Both of the Sun <tm>J2SE</tm> virtual machines (Classic and <tm>HotSpot</tm>) store
14388     pointers in jmethodIDs, and as a result, a jmethodID is sufficient.
14389     In fact, any JVM implementation that supports JVMPI must have
14390     such a representation.
14391     <jvmti/> will use jmethodID as a unique representation of a method
14392     (no jclass is used).
14393     There should be efficiency gains, particularly in
14394     functionality like stack dumping, to this representation.
14395     <p/>
14396     Note that fields were not used in JVMPI and that the access profile
14397     of fields differs from methods--for implementation efficiency
14398     reasons, a jclass/jfieldID pair will still be needed for field
14399     reference.
14400   </intro>
14401 
14402   <intro id="localReferenceIssue" label="Resolved Issue: Local References">
14403     Functions return local references.
14404   </intro>
14405 
14406   <intro id="frameRep" label="Resolved Issue: Representation of frames">
14407     In JVMDI, a frame ID is used to represent a frame.  Problem with this
14408     is that a VM must track when a frame becomes invalid, a far better
14409     approach, and the one used in <jvmti/>, is to reference frames by depth.
14410   </intro>
14411 
14412   <intro id="requiredCapabilities" label="Issue: Required Capabilities">
14413     Currently, having a required capabilities means that the functionality
14414     is optional.   Capabilities are useful even for required functionality
14415     since they can inform the VM is needed set-up.  Thus, there should be
14416     a set of capabilities that a conformant implementation must provide
14417     (if requested during Agent_OnLoad).
14418   </intro>
14419 
14420   <intro id="taghint" label="Proposal: add tag hint function">
14421     A hint of the percentage of objects that will be tagged would
14422     help the VM pick a good implementation.
14423   </intro>
14424 
14425   <intro id="moreMonitorQueries" label="Request: More Monitor Quires">
14426   How difficult or easy would be to extend the monitor_info category to include
14427     <pre>
14428   - current number of monitors
14429   - enumeration of monitors
14430   - enumeration of threads waiting on a given monitor
14431     </pre>
14432   The reason for my question is the fact that current get_monitor_info support
14433   requires the agent to specify a given thread to get the info which is probably
14434   OK in the profiling/debugging space, while in the monitoring space the agent
14435   could be watching the monitor list and then decide which thread to ask for
14436   the info. You might ask why is this important for monitoring .... I think it
14437   can aid in the detection/prediction of application contention caused by hot-locks.
14438   </intro>
14439 </issuessection>
14440 
14441 <changehistory id="ChangeHistory" update="09/05/07">
14442   <intro>
14443     The <jvmti/> specification is an evolving document with major, minor,
14444     and micro version numbers.
14445     A released version of the specification is uniquely identified
14446     by its major and minor version.
14447     The functions, events, and capabilities in this specification
14448     indicate a "Since" value which is the major and minor version in
14449     which it was introduced.
14450     The version of the specification implemented by the VM can
14451     be retrieved at runtime with the <functionlink id="GetVersionNumber"/>
14452     function.
14453   </intro>
14454   <change date="14 Nov 2002">
14455     Converted to XML document.
14456   </change>
14457   <change date="14 Nov 2002">
14458     Elided heap dump functions (for now) since what was there
14459     was wrong.
14460   </change>
14461   <change date="18 Nov 2002">
14462     Added detail throughout.
14463   </change>
14464   <change date="18 Nov 2002">
14465     Changed JVMTI_THREAD_STATUS_RUNNING to JVMTI_THREAD_STATUS_RUNNABLE.
14466   </change>
14467   <change date="19 Nov 2002">
14468     Added AsyncGetStackTrace.
14469   </change>
14470   <change date="19 Nov 2002">
14471     Added jframeID return to GetStackTrace.
14472   </change>
14473   <change date="19 Nov 2002">
14474     Elided GetCurrentFrame and GetCallingFrame functions (for now) since what was there
14475     since they are redundant with GetStackTrace.
14476   </change>
14477   <change date="19 Nov 2002">
14478     Elided ClearAllBreakpoints since it has always been redundant.
14479   </change>
14480   <change date="19 Nov 2002">
14481     Added GetSystemProperties.
14482   </change>
14483   <change date="19 Nov 2002">
14484     Changed the thread local storage functions to use jthread.
14485   </change>
14486   <change date="20 Nov 2002">
14487     Added GetJLocationFormat.
14488   </change>
14489   <change date="22 Nov 2002">
14490     Added events and introductory text.
14491   </change>
14492   <change date="22 Nov 2002">
14493     Cross reference type and constant definitions.
14494   </change>
14495   <change date="24 Nov 2002">
14496     Added DTD.
14497   </change>
14498   <change date="24 Nov 2002">
14499     Added capabilities function section.
14500   </change>
14501   <change date="29 Nov 2002">
14502     Assign capabilities to each function and event.
14503   </change>
14504   <change date="29 Nov 2002">
14505     Add <internallink id="jniIntercept">JNI interception functions</internallink>.
14506   </change>
14507   <change date="30 Nov 2002">
14508     Auto generate SetEventNotificationMode capabilities.
14509   </change>
14510   <change date="30 Nov 2002">
14511     Add <eventlink id="VMObjectAlloc"></eventlink> event.
14512   </change>
14513   <change date="30 Nov 2002">
14514     Add <eventlink id="DynamicCodeGenerated"></eventlink> event.
14515   </change>
14516   <change date="30 Nov 2002">
14517     Add const to declarations.
14518   </change>
14519   <change date="30 Nov 2002">
14520     Change method exit and frame pop to send on exception.
14521   </change>
14522   <change date="1 Dec 2002">
14523     Add ForceGarbageCollection.
14524   </change>
14525   <change date="2 Dec 2002">
14526     Redo Xrun section; clarify GetStackTrace and add example;
14527     Fix width problems; use "agent" consistently.
14528   </change>
14529   <change date="8 Dec 2002">
14530     Remove previous start-up intro.
14531     Add <internallink id="environments"><jvmti/> Environments</internallink>
14532     section.
14533   </change>
14534   <change date="8 Dec 2002">
14535     Add <functionlink id="DisposeEnvironment"></functionlink>.
14536   </change>
14537   <change date="9 Dec 2002">
14538     Numerous minor updates.
14539   </change>
14540   <change date="15 Dec 2002">
14541     Add heap profiling functions added:
14542     get/set annotation, iterate live objects/heap.
14543     Add heap profiling functions place holder added:
14544     heap roots.
14545     Heap profiling event added: object free.
14546     Heap profiling event redesigned: vm object allocation.
14547     Heap profiling event placeholders added: garbage collection start/finish.
14548     Native method bind event added.
14549   </change>
14550   <change date="19 Dec 2002">
14551     Revamp suspend/resume functions.
14552     Add origin information with jvmdi tag.
14553     Misc fixes.
14554   </change>
14555   <change date="24 Dec 2002">
14556     Add semantics to types.
14557   </change>
14558   <change date="27 Dec 2002">
14559     Add local reference section.
14560     Autogenerate parameter descriptions from types.
14561   </change>
14562   <change date="28 Dec 2002">
14563     Document that RunAgentThread sends threadStart.
14564   </change>
14565   <change date="29 Dec 2002">
14566     Remove redundant local ref and dealloc warning.
14567     Convert GetRawMonitorName to allocated buffer.
14568     Add GenerateEvents.
14569   </change>
14570   <change date="30 Dec 2002">
14571     Make raw monitors a type and rename to "jrawMonitorID".
14572   </change>
14573   <change date="1 Jan 2003">
14574     Include origin information.
14575     Clean-up JVMDI issue references.
14576     Remove Deallocate warnings which are now automatically generated.
14577   </change>
14578   <change date="2 Jan 2003">
14579     Fix representation issues for jthread.
14580   </change>
14581   <change date="3 Jan 2003">
14582     Make capabilities buffered out to 64 bits - and do it automatically.
14583   </change>
14584   <change date="4 Jan 2003">
14585     Make constants which are enumeration into enum types.
14586     Parameters now of enum type.
14587     Clean-up and index type section.
14588     Replace remaining datadef entities with callback.
14589   </change>
14590   <change date="7 Jan 2003">
14591     Correct GenerateEvents description.
14592     More internal semantics work.
14593   </change>
14594   <change date="9 Jan 2003">
14595     Replace previous GetSystemProperties with two functions
14596     which use allocated information instead fixed.
14597     Add SetSystemProperty.
14598     More internal semantics work.
14599   </change>
14600   <change date="12 Jan 2003">
14601     Add varargs to end of SetEventNotificationMode.
14602   </change>
14603   <change date="20 Jan 2003">
14604     Finish fixing spec to reflect that alloc sizes are jlong.
14605   </change>
14606   <change date="22 Jan 2003">
14607     Allow NULL as RunAgentThread arg.
14608   </change>
14609   <change date="22 Jan 2003">
14610     Fixed names to standardized naming convention
14611     Removed AsyncGetStackTrace.
14612   </change>
14613   <change date="29 Jan 2003">
14614     Since we are using jthread, removed GetThread.
14615   </change>
14616   <change date="31 Jan 2003">
14617     Change GetFieldName to allow NULLs like GetMethodName.
14618   </change>
14619   <change date="29 Feb 2003" version="v40">
14620       Rewrite the introductory text, adding sections on
14621       start-up, environments and bytecode instrumentation.
14622       Change the command line arguments per EG discussions.
14623       Add an introduction to the capabilities section.
14624       Add the extension mechanism category and functions.
14625       Mark for deletion, but clarified anyhow, SuspendAllThreads.
14626       Rename IterateOverLiveObjects to IterateOverReachableObjects and
14627       change the text accordingly.
14628       Clarify IterateOverHeap.
14629       Clarify CompiledMethodLoad.
14630       Discuss prerequisite state for Calling Functions.
14631       Clarify SetAllocationHooks.
14632       Added issues ("To be resolved:") through-out.
14633       And so on...
14634   </change>
14635   <change date="6 Mar 2003" version="v41">
14636       Remove struct from the call to GetOwnedMonitorInfo.
14637       Automatically generate most error documentation, remove
14638       (rather broken) hand written error doc.
14639       Better describe capability use (empty initial set).
14640       Add min value to jint params.
14641       Remove the capability can_access_thread_local_storage.
14642       Rename error JVMTI_ERROR_NOT_IMPLEMENTED to JVMTI_ERROR_MUST_POSSESS_CAPABILITY;
14643       same for *NOT_IMPLEMENTED.
14644       Description fixes.
14645   </change>
14646   <change date="8 Mar 2003" version="v42">
14647       Rename GetClassSignature to GetClassName.
14648       Rename IterateOverClassObjects to IterateOverInstancesOfClass.
14649       Remove GetMaxStack (operand stack isn't used in <jvmti/>).
14650       Description fixes: define launch-time, remove native frame pop
14651       from PopFrame, and assorted clarifications.
14652   </change>
14653   <change date="8 Mar 2003" version="v43">
14654       Fix minor editing problem.
14655   </change>
14656   <change date="10 Mar 2003" version="v44">
14657       Add phase information.
14658       Remap (compact) event numbers.
14659   </change>
14660   <change date="11 Mar 2003" version="v45">
14661       More phase information - allow "any".
14662       Elide raw monitor queries and events.
14663       Minor description fixes.
14664   </change>
14665   <change date="12 Mar 2003" version="v46">
14666       Add GetPhase.
14667       Use "phase" through document.
14668       Elide GetRawMonitorName.
14669       Elide GetObjectMonitors.
14670   </change>
14671   <change date="12 Mar 2003" version="v47">
14672       Fixes from link, XML, and spell checking.
14673       Auto-generate the callback structure.
14674   </change>
14675   <change date="13 Mar 2003" version="v48">
14676       One character XML fix.
14677   </change>
14678   <change date="13 Mar 2003" version="v49">
14679       Change function parameter names to be consistent with
14680       event parameters (fooBarBaz becomes foo_bar_baz).
14681   </change>
14682   <change date="14 Mar 2003" version="v50">
14683       Fix broken link.  Fix thread markers.
14684   </change>
14685   <change date="14 Mar 2003" version="v51">
14686       Change constants so they are under 128 to workaround
14687       compiler problems.
14688   </change>
14689   <change date="23 Mar 2003" version="v52">
14690       Overhaul capabilities.  Separate GetStackTrace into
14691       GetStackTrace and GetStackFrames.
14692   </change>
14693   <change date="8 Apr 2003" version="v54">
14694       Use depth instead of jframeID to reference frames.
14695       Remove the now irrelevant GetCurrentFrame, GetCallerFrame and GetStackFrames.
14696       Remove frame arg from events.
14697   </change>
14698   <change date="9 Apr 2003" version="v55">
14699       Remove GetObjectWithAnnotation since tests show bufferred approach more efficient.
14700       Add missing annotation_count to GetObjectsWithAnnotations
14701   </change>
14702   <change date="10 Apr 2003" version="v56">
14703       Remove confusing parenthetical statement in GetObjectsWithAnnotations
14704   </change>
14705   <change date="13 Apr 2003" version="v58">
14706       Replace jclass/jmethodID representation of method with simply jmethodID;
14707       Pass JvmtiEnv* as first arg of every event; remove JNIEnv* where inappropriate.
14708       Replace can_access_frames with can_access_local_variables; remove from purely stack access.
14709       Use can_get_synthetic_attribute; fix description.
14710       Clarify that zero length arrays must be deallocated.
14711       Clarify RelinquishCapabilities.
14712       Generalize JVMTI_ERROR_VM_DEAD to JVMTI_ERROR_WRONG_PHASE.
14713   </change>
14714   <change date="27 Apr 2003" version="v59">
14715       Remove lingering indirect references to OBSOLETE_METHOD_ID.
14716   </change>
14717   <change date="4 May 2003" version="v60">
14718       Allow DestroyRawMonitor during OnLoad.
14719   </change>
14720   <change date="7 May 2003" version="v61">
14721       Added not monitor owner error return to DestroyRawMonitor.
14722   </change>
14723   <change date="13 May 2003" version="v62">
14724       Clarify semantics of raw monitors.
14725       Change flags on <code>GetThreadStatus</code>.
14726       <code>GetClassLoader</code> return NULL for the bootstrap class loader.
14727       Add <code>GetClassName</code> issue.
14728       Define local variable signature.
14729       Disallow zero in annotations array of <code>GetObjectsWithAnnotations</code>.
14730       Remove over specification in <code>GetObjectsWithAnnotations</code>.
14731       Elide <code>SetAllocationHooks</code>.
14732       Elide <code>SuspendAllThreads</code>.
14733   </change>
14734   <change date="14 May 2003" version="v63">
14735       Define the data type <code>jvmtiEventCallbacks</code>.
14736       Zero length allocations return NULL.
14737       Keep SetAllocationHooks in JVMDI, but remove from <jvmti/>.
14738       Add JVMTI_THREAD_STATUS_FLAG_INTERRUPTED.
14739   </change>
14740   <change date="15 May 2003" version="v64">
14741       Better wording, per review.
14742   </change>
14743   <change date="15 May 2003" version="v65">
14744       First Alpha.
14745       Make jmethodID and jfieldID unique, jclass not used.
14746   </change>
14747   <change date="27 May 2003" version="v66">
14748       Fix minor XSLT errors.
14749   </change>
14750   <change date="13 June 2003" version="v67">
14751       Undo making jfieldID unique (jmethodID still is).
14752   </change>
14753   <change date="17 June 2003" version="v68">
14754       Changes per June 11th Expert Group meeting --
14755       Overhaul Heap functionality: single callback,
14756       remove GetHeapRoots, add reachable iterators,
14757       and rename "annotation" to "tag".
14758       NULL thread parameter on most functions is current
14759       thread.
14760       Add timers.
14761       Remove ForceExit.
14762       Add GetEnvironmentLocalStorage.
14763       Add verbose flag and event.
14764       Add AddToBootstrapClassLoaderSearch.
14765       Update ClassFileLoadHook.
14766   </change>
14767   <change date="18 June 2003" version="v69">
14768       Clean up issues sections.
14769       Rename GetClassName back to GetClassSignature and
14770       fix description.
14771       Add generic signature to GetClassSignature,
14772       GetFieldSignature, GetMethodSignature, and
14773       GetLocalVariableTable.
14774       Elide EstimateCostOfCapabilities.
14775       Clarify that the system property functions operate
14776       on the VM view of system properties.
14777       Clarify Agent_OnLoad.
14778       Remove "const" from JNIEnv* in events.
14779       Add metadata accessors.
14780   </change>
14781   <change date="18 June 2003" version="v70">
14782       Add start_depth to GetStackTrace.
14783       Move system properties to a new category.
14784       Add GetObjectSize.
14785       Remove "X" from command line flags.
14786       XML, HTML, and spell check corrections.
14787   </change>
14788   <change date="19 June 2003" version="v71">
14789       Fix JVMTI_HEAP_ROOT_THREAD to be 6.
14790       Make each synopsis match the function name.
14791       Fix unclear wording.
14792   </change>
14793   <change date="26 June 2003" version="v72">
14794       SetThreadLocalStorage and SetEnvironmentLocalStorage should allow value
14795       to be set to NULL.
14796       NotifyFramePop, GetFrameLocationm and all the local variable operations
14797       needed to have their wording about frames fixed.
14798       Grammar and clarity need to be fixed throughout.
14799       Capitalization and puntuation need to be consistent.
14800       Need micro version number and masks for accessing major, minor, and micro.
14801       The error code lists should indicate which must be returned by
14802       an implementation.
14803       The command line properties should be visible in the properties functions.
14804       Disallow popping from the current thread.
14805       Allow implementations to return opaque frame error when they cannot pop.
14806       The NativeMethodBind event should be sent during any phase.
14807       The DynamicCodeGenerated event should be sent during any phase.
14808       The following functions should be allowed to operate before VMInit:
14809         Set/GetEnvironmentLocalStorage
14810         GetMethodDeclaringClass
14811         GetClassSignature
14812         GetClassModifiers
14813         IsInterface
14814         IsArrayClass
14815         GetMethodName
14816         GetMethodModifiers
14817         GetMaxLocals
14818         GetArgumentsSize
14819         GetLineNumberTable
14820         GetMethodLocation
14821         IsMethodNative
14822         IsMethodSynthetic.
14823       Other changes (to XSL):
14824       Argument description should show asterisk after not before pointers.
14825       NotifyFramePop, GetFrameLocationm and all the local variable operations
14826       should hsve the NO_MORE_FRAMES error added.
14827       Not alive threads should have a different error return than invalid thread.
14828   </change>
14829   <change date="7 July 2003" version="v73">
14830       VerboseOutput event was missing message parameter.
14831       Minor fix-ups.
14832   </change>
14833   <change date="14 July 2003" version="v74">
14834       Technical Publications Department corrections.
14835       Allow thread and environment local storage to be set to NULL.
14836   </change>
14837   <change date="23 July 2003" version="v75">
14838       Use new Agent_OnLoad rather than overloaded JVM_OnLoad.
14839       Add JNICALL to callbacks (XSL).
14840       Document JNICALL requirement for both events and callbacks (XSL).
14841       Restrict RedefineClasses to methods and attributes.
14842       Elide the VerboseOutput event.
14843       VMObjectAlloc: restrict when event is sent and remove method parameter.
14844       Finish loose ends from Tech Pubs edit.
14845   </change>
14846   <change date="24 July 2003" version="v76">
14847       Change ClassFileLoadHook event to send the class instead of a boolean of redefine.
14848   </change>
14849   <change date="24 July 2003" version="v77">
14850       XML fixes.
14851       Minor text clarifications and corrections.
14852   </change>
14853   <change date="24 July 2003" version="v78">
14854       Remove GetExceptionHandlerTable and GetThrownExceptions from <jvmti/>.
14855       Clarify that stack frames are JVM Spec frames.
14856       Split can_get_source_info into can_get_source_file_name, can_get_line_numbers,
14857       and can_get_source_debug_extension.
14858       PopFrame cannot have a native calling method.
14859       Removed incorrect statement in GetClassloaderClasses
14860       (see <vmspec chapter="4.4"/>).
14861   </change>
14862   <change date="24 July 2003" version="v79">
14863       XML and text fixes.
14864       Move stack frame description into Stack Frame category.
14865   </change>
14866   <change date="26 July 2003" version="v80">
14867       Allow NULL (means bootstrap loader) for GetClassloaderClasses.
14868       Add new heap reference kinds for references from classes.
14869       Add timer information struct and query functions.
14870       Add AvailableProcessors.
14871       Rename GetOtherThreadCpuTime to GetThreadCpuTime.
14872       Explicitly add JVMTI_ERROR_INVALID_THREAD and JVMTI_ERROR_THREAD_NOT_ALIVE
14873       to SetEventNotification mode.
14874       Add initial thread to the VM_INIT event.
14875       Remove platform assumptions from AddToBootstrapClassLoaderSearch.
14876   </change>
14877   <change date="26 July 2003" version="v81">
14878       Grammar and clarity changes per review.
14879   </change>
14880   <change date="27 July 2003" version="v82">
14881       More grammar and clarity changes per review.
14882       Add Agent_OnUnload.
14883   </change>
14884   <change date="28 July 2003" version="v83">
14885       Change return type of Agent_OnUnload to void.
14886   </change>
14887   <change date="28 July 2003" version="v84">
14888       Rename JVMTI_REFERENCE_ARRAY to JVMTI_REFERENCE_ARRAY_ELEMENT.
14889   </change>
14890   <change date="28 July 2003" version="v85">
14891       Steal java.lang.Runtime.availableProcessors() wording for
14892       AvailableProcessors().
14893       Guarantee that zero will never be an event ID.
14894       Remove some issues which are no longer issues.
14895       Per review, rename and more completely document the timer
14896       information functions.
14897   </change>
14898   <change date="29 July 2003" version="v86">
14899       Non-spec visible change to XML controlled implementation:
14900         SetThreadLocalStorage must run in VM mode.
14901   </change>
14902   <change date="5 August 2003" version="0.1.87">
14903       Add GetErrorName.
14904       Add varargs warning to jvmtiExtensionEvent.
14905       Remove "const" on the jvmtiEnv* of jvmtiExtensionEvent.
14906       Remove unused can_get_exception_info capability.
14907       Pass jvmtiEnv* and JNIEnv* to the jvmtiStartFunction.
14908       Fix jvmtiExtensionFunctionInfo.func declared type.
14909       Extension function returns error code.
14910       Use new version numbering.
14911   </change>
14912   <change date="5 August 2003" version="0.2.88">
14913       Remove the ClassUnload event.
14914   </change>
14915   <change date="8 August 2003" version="0.2.89">
14916       Heap reference iterator callbacks return an enum that
14917       allows outgoing object references to be ignored.
14918       Allow JNIEnv as a param type to extension events/functions.
14919   </change>
14920   <change date="15 August 2003" version="0.2.90">
14921       Fix a typo.
14922   </change>
14923   <change date="2 September 2003" version="0.2.91">
14924       Remove all metadata functions: GetClassMetadata,
14925       GetFieldMetadata, and GetMethodMetadata.
14926   </change>
14927   <change date="1 October 2003" version="0.2.92">
14928       Mark the functions Allocate. Deallocate, RawMonitor*,
14929       SetEnvironmentLocalStorage, and GetEnvironmentLocalStorage
14930       as safe for use in heap callbacks and GC events.
14931   </change>
14932   <change date="24 November 2003" version="0.2.93">
14933       Add pass through opaque user data pointer to heap iterate
14934       functions and callbacks.
14935       In the CompiledMethodUnload event, send the code address.
14936       Add GarbageCollectionOccurred event.
14937       Add constant pool reference kind.
14938       Mark the functions CreateRawMonitor and DestroyRawMonitor
14939       as safe for use in heap callbacks and GC events.
14940       Clarify: VMDeath, GetCurrentThreadCpuTimerInfo,
14941       GetThreadCpuTimerInfo, IterateOverReachableObjects,
14942       IterateOverObjectsReachableFromObject, GetTime and
14943       JVMTI_ERROR_NULL_POINTER.
14944       Add missing errors to: GenerateEvents and
14945       AddToBootstrapClassLoaderSearch.
14946       Fix description of ClassFileLoadHook name parameter.
14947       In heap callbacks and GC/ObjectFree events, specify
14948       that only explicitly allowed functions can be called.
14949       Allow GetCurrentThreadCpuTimerInfo, GetCurrentThreadCpuTime,
14950       GetTimerInfo, and GetTime during callback.
14951       Allow calling SetTag/GetTag during the onload phase.
14952       SetEventNotificationMode, add: error attempted inappropriate
14953       thread level control.
14954       Remove jvmtiExceptionHandlerEntry.
14955       Fix handling of native methods on the stack --
14956       location_ptr param of GetFrameLocation, remove
14957       JVMTI_ERROR_OPAQUE_FRAME from GetFrameLocation,
14958       jvmtiFrameInfo.location, and jlocation.
14959       Remove typo (from JVMPI) implying that the MonitorWaited
14960       event is sent on sleep.
14961   </change>
14962   <change date="25 November 2003" version="0.2.94">
14963       Clarifications and typos.
14964   </change>
14965   <change date="3 December 2003" version="0.2.95">
14966       Allow NULL user_data in heap iterators.
14967   </change>
14968   <change date="28 January 2004" version="0.2.97">
14969       Add GetThreadState, deprecate GetThreadStatus.
14970   </change>
14971   <change date="29 January 2004" version="0.2.98">
14972       INVALID_SLOT and TYPE_MISMATCH errors should be optional.
14973   </change>
14974   <change date="12 February 2004" version="0.2.102">
14975       Remove MonitorContendedExit.
14976       Added JNIEnv parameter to VMObjectAlloc.
14977       Clarified definition of class_tag and referrer_index
14978       parameters to heap callbacks.
14979   </change>
14980   <change date="16 Febuary 2004" version="0.2.103">
14981       Document JAVA_TOOL_OPTIONS.
14982   </change>
14983   <change date="17 Febuary 2004" version="0.2.105">
14984       Divide start phase into primordial and start.
14985       Add VMStart event
14986       Change phase associations of functions and events.
14987   </change>
14988   <change date="18 Febuary 2004" version="0.3.6">
14989       Elide deprecated GetThreadStatus.
14990       Bump minor version, subtract 100 from micro version
14991   </change>
14992   <change date="18 Febuary 2004" version="0.3.7">
14993       Document that timer nanosecond values are unsigned.
14994       Clarify text having to do with native methods.
14995   </change>
14996   <change date="19 Febuary 2004" version="0.3.8">
14997       Fix typos.
14998       Remove elided deprecated GetThreadStatus.
14999   </change>
15000   <change date="23 Febuary 2004" version="0.3.9">
15001       Require NotifyFramePop to act on suspended threads.
15002   </change>
15003   <change date="24 Febuary 2004" version="0.3.10">
15004       Add capabilities
15005         (<internallink id="jvmtiCapabilities.can_redefine_any_class"
15006          ><code>can_redefine_any_class</code></internallink>
15007       and
15008          <internallink id="jvmtiCapabilities.can_generate_all_class_hook_events"
15009          ><code>can_generate_all_class_hook_events</code></internallink>)
15010       and an error (<errorlink id="JVMTI_ERROR_UNMODIFIABLE_CLASS"></errorlink>)
15011       which allow some classes to be unmodifiable.
15012   </change>
15013   <change date="28 Febuary 2004" version="0.3.11">
15014       Add JVMTI_ERROR_MUST_POSSESS_CAPABILITY to SetEventNotificationMode.
15015   </change>
15016   <change date="8 March 2004" version="0.3.12">
15017       Clarified CompiledMethodUnload so that it is clear the event
15018       may be posted after the class has been unloaded.
15019   </change>
15020   <change date="5 March 2004" version="0.3.13">
15021       Change the size parameter of VMObjectAlloc to jlong to match GetObjectSize.
15022   </change>
15023   <change date="13 March 2004" version="0.3.14">
15024       Added guideline for the use of the JNI FindClass function in event
15025       callback functions.
15026   </change>
15027   <change date="15 March 2004" version="0.3.15">
15028       Add GetAllStackTraces and GetThreadListStackTraces.
15029   </change>
15030   <change date="19 March 2004" version="0.3.16">
15031       ClassLoad and ClassPrepare events can be posted during start phase.
15032   </change>
15033   <change date="25 March 2004" version="0.3.17">
15034       Add JVMTI_ERROR_NATIVE_METHOD to GetLineNumberTable, GetLocalVariableTable,
15035       GetMaxLocals, GetArgumentsSize, GetMethodLocation, GetBytecodes.
15036   </change>
15037   <change date="29 March 2004" version="0.3.18">
15038       Return the timer kind in the timer information structure.
15039   </change>
15040   <change date="31 March 2004" version="0.3.19">
15041       Spec clarifications:
15042       JVMTI_THREAD_STATE_IN_NATIVE might not include JNI or <jvmti/>.
15043       ForceGarbageCollection does not run finalizers.
15044       The context of the specification is the Java platform.
15045       Warn about early instrumentation.
15046   </change>
15047   <change date="1 April 2004" version="0.3.20">
15048       Refinements to the above clarifications and
15049       Clarify that an error returned by Agent_OnLoad terminates the VM.
15050   </change>
15051   <change date="1 April 2004" version="0.3.21">
15052       Array class creation does not generate a class load event.
15053   </change>
15054   <change date="7 April 2004" version="0.3.22">
15055       Align thread state hierarchy more closely with java.lang.Thread.State.
15056   </change>
15057   <change date="12 April 2004" version="0.3.23">
15058       Clarify the documentation of thread state.
15059   </change>
15060   <change date="19 April 2004" version="0.3.24">
15061       Remove GarbageCollectionOccurred event -- can be done by agent.
15062   </change>
15063   <change date="22 April 2004" version="0.3.25">
15064       Define "command-line option".
15065   </change>
15066   <change date="29 April 2004" version="0.3.26">
15067       Describe the intended use of bytecode instrumentation.
15068       Fix description of extension event first parameter.
15069   </change>
15070   <change date="30 April 2004" version="0.3.27">
15071       Clarification and typos.
15072   </change>
15073   <change date="18 May 2004" version="0.3.28">
15074       Remove DataDumpRequest event.
15075   </change>
15076   <change date="18 May 2004" version="0.3.29">
15077       Clarify RawMonitorWait with zero timeout.
15078       Clarify thread state after RunAgentThread.
15079   </change>
15080   <change date="24 May 2004" version="0.3.30">
15081       Clean-up: fix bad/old links, etc.
15082   </change>
15083   <change date="30 May 2004" version="0.3.31">
15084       Clarifications including:
15085       All character strings are modified UTF-8.
15086       Agent thread visibiity.
15087       Meaning of obsolete method version.
15088       Thread invoking heap callbacks,
15089   </change>
15090   <change date="1 June 2004" version="1.0.32">
15091       Bump major.minor version numbers to "1.0".
15092   </change>
15093   <change date="2 June 2004" version="1.0.33">
15094       Clarify interaction between ForceGarbageCollection
15095       and ObjectFree.
15096   </change>
15097   <change date="6 June 2004" version="1.0.34">
15098       Restrict AddToBootstrapClassLoaderSearch and
15099       SetSystemProperty to the OnLoad phase only.
15100   </change>
15101   <change date="11 June 2004" version="1.0.35">
15102       Fix typo in SetTag.
15103   </change>
15104   <change date="18 June 2004" version="1.0.36">
15105       Fix trademarks.
15106       Add missing parameter in example GetThreadState usage.
15107   </change>
15108   <change date="4 August 2004" version="1.0.37">
15109       Copyright updates.
15110   </change>
15111   <change date="5 November 2004" version="1.0.38">
15112       Add missing function table layout.
15113       Add missing description of C++ member function format of functions.
15114       Clarify that name in CFLH can be NULL.
15115       Released as part of <tm>J2SE</tm> 5.0.
15116   </change>
15117   <change date="24 April 2005" version="1.1.47">
15118       Bump major.minor version numbers to "1.1".
15119       Add ForceEarlyReturn* functions.
15120       Add GetOwnedMonitorStackDepthInfo function.
15121       Add GetCurrentThread function.
15122       Add "since" version marker.
15123       Add AddToSystemClassLoaderSearch.
15124       Allow AddToBootstrapClassLoaderSearch be used in live phase.
15125       Fix historic rubbish in the descriptions of the heap_object_callback
15126       parameter of IterateOverHeap and IterateOverInstancesOfClass functions;
15127       disallow NULL for this parameter.
15128       Clarify, correct and make consistent: wording about current thread,
15129       opaque frames and insufficient number of frames in PopFrame.
15130       Consistently use "current frame" rather than "topmost".
15131       Clarify the JVMTI_ERROR_TYPE_MISMATCH errors in GetLocal* and SetLocal*
15132       by making them compatible with those in ForceEarlyReturn*.
15133       Many other clarifications and wording clean ups.
15134   </change>
15135   <change date="25 April 2005" version="1.1.48">
15136       Add GetConstantPool.
15137       Switch references to the first edition of the VM Spec, to the seconds edition.
15138   </change>
15139   <change date="26 April 2005" version="1.1.49">
15140       Clarify minor/major version order in GetConstantPool.
15141   </change>
15142   <change date="26 April 2005" version="1.1.50">
15143       Add SetNativeMethodPrefix and SetNativeMethodPrefixes.
15144       Reassign GetOwnedMonitorStackDepthInfo to position 153.
15145       Break out Class Loader Search in its own documentation category.
15146       Deal with overly long lines in XML source.
15147   </change>
15148   <change date="29 April 2005" version="1.1.51">
15149       Allow agents be started in the live phase.
15150       Added paragraph about deploying agents.
15151   </change>
15152   <change date="30 April 2005" version="1.1.52">
15153       Add specification description to SetNativeMethodPrefix(es).
15154       Better define the conditions on GetConstantPool.
15155   </change>
15156   <change date="30 April 2005" version="1.1.53">
15157       Break out the GetClassVersionNumber function from GetConstantPool.
15158       Clean-up the references to the VM Spec.
15159   </change>
15160   <change date="1 May 2005" version="1.1.54">
15161       Allow SetNativeMethodPrefix(es) in any phase.
15162       Add clarifications about the impact of redefinition on GetConstantPool.
15163   </change>
15164   <change date="2 May 2005" version="1.1.56">
15165       Various clarifications to SetNativeMethodPrefix(es).
15166   </change>
15167   <change date="2 May 2005" version="1.1.57">
15168       Add missing performance warning to the method entry event.
15169   </change>
15170   <change date="5 May 2005" version="1.1.58">
15171       Remove internal JVMDI support.
15172   </change>
15173   <change date="8 May 2005" version="1.1.59">
15174       Add <functionlink id="RetransformClasses"/>.
15175       Revamp the bytecode instrumentation documentation.
15176       Change <functionlink id="IsMethodObsolete"/> to no longer
15177       require the can_redefine_classes capability.
15178   </change>
15179   <change date="11 May 2005" version="1.1.63">
15180       Clarifications for retransformation.
15181   </change>
15182   <change date="11 May 2005" version="1.1.64">
15183       Clarifications for retransformation, per review.
15184       Lock "retransformation (in)capable" at class load enable time.
15185   </change>
15186   <change date="4 June 2005" version="1.1.67">
15187       Add new heap functionity which supports reporting primitive values,
15188       allows setting the referrer tag, and has more powerful filtering:
15189       FollowReferences, IterateThroughHeap, and their associated
15190       callbacks, structs, enums, and constants.
15191   </change>
15192   <change date="4 June 2005" version="1.1.68">
15193       Clarification.
15194   </change>
15195   <change date="6 June 2005" version="1.1.69">
15196       FollowReferences, IterateThroughHeap: Put callbacks in a struct;
15197       Add missing error codes; reduce bits in the visit control flags.
15198   </change>
15199   <change date="14 June 2005" version="1.1.70">
15200       More on new heap functionity: spec clean-up per review.
15201   </change>
15202   <change date="15 June 2005" version="1.1.71">
15203       More on new heap functionity: Rename old heap section to Heap (1.0).
15204   </change>
15205   <change date="21 June 2005" version="1.1.72">
15206       Fix typos.
15207   </change>
15208   <change date="27 June 2005" version="1.1.73">
15209       Make referrer info structure a union.
15210   </change>
15211   <change date="9 September 2005" version="1.1.74">
15212       In new heap functions:
15213       Add missing superclass reference kind.
15214       Use a single scheme for computing field indexes.
15215       Remove outdated references to struct based referrer info.
15216   </change>
15217   <change date="12 September 2005" version="1.1.75">
15218       Don't callback during FollowReferences on frivolous java.lang.Object superclass.
15219   </change>
15220   <change date="13 September 2005" version="1.1.76">
15221       In string primitive callback, length now Unicode length.
15222       In array and string primitive callbacks, value now "const".
15223       Note possible compiler impacts on setting JNI function table.
15224   </change>
15225   <change date="13 September 2005" version="1.1.77">
15226       GetClassVersionNumbers() and GetConstantPool() should return
15227       error on array or primitive class.
15228   </change>
15229   <change date="14 September 2005" version="1.1.78">
15230       Grammar fixes.
15231   </change>
15232   <change date="26 September 2005" version="1.1.79">
15233       Add IsModifiableClass query.
15234   </change>
15235   <change date="9 February 2006" version="1.1.81">
15236       Add referrer_class_tag parameter to jvmtiHeapReferenceCallback.
15237   </change>
15238   <change date="13 February 2006" version="1.1.82">
15239       Doc fixes: update can_redefine_any_class to include retransform.
15240       Clarify that exception events cover all Throwables.
15241       In GetStackTrace, no test is done for start_depth too big if start_depth is zero,
15242       Clarify fields reported in Primitive Field Callback -- static vs instance.
15243       Repair confusing names of heap types, including callback names.
15244       Require consistent usage of stack depth in the face of thread launch methods.
15245       Note incompatibility of <jvmti/> memory management with other systems.
15246   </change>
15247   <change date="14 February 2006" version="1.1.85">
15248       Fix typos and missing renames.
15249   </change>
15250   <change date="13 March 2006" version="1.1.86">
15251       Clarify that jmethodIDs and jfieldIDs can be saved.
15252       Clarify that Iterate Over Instances Of Class includes subclasses.
15253   </change>
15254   <change date="14 March 2006" version="1.1.87">
15255       Better phrasing.
15256   </change>
15257   <change date="16 March 2006" version="1.1.88">
15258       Match the referrer_index for static fields in Object Reference Callback
15259       with the Reference Implementation (and all other known implementations);
15260       that is, make it match the definition for instance fields.
15261       In GetThreadListStackTraces, add JVMTI_ERROR_INVALID_THREAD to cover
15262       an invalid thread in the list; and specify that not started threads
15263       return empty stacks.
15264   </change>
15265   <change date="17 March 2006" version="1.1.89">
15266       Typo.
15267   </change>
15268   <change date="25 March 2006" version="1.1.90">
15269       Typo.
15270   </change>
15271   <change date="6 April 2006" version="1.1.91">
15272       Remove restrictions on AddToBootstrapClassLoaderSearch and
15273       AddToSystemClassLoaderSearch.
15274   </change>
15275   <change date="1 May 2006" version="1.1.93">
15276       Changed spec to return -1 for monitor stack depth for the
15277       implementation which can not determine stack depth.
15278   </change>
15279   <change date="3 May 2006" version="1.1.94">
15280       Corrections for readability and accuracy courtesy of Alan Pratt of IBM.
15281       List the object relationships reported in FollowReferences.
15282   </change>
15283   <change date="5 May 2006" version="1.1.95">
15284       Clarify the object relationships reported in FollowReferences.
15285   </change>
15286   <change date="28 June 2006" version="1.1.98">
15287       Clarify DisposeEnvironment; add warning.
15288       Fix typos in SetLocalXXX "retrieve" => "set".
15289       Clarify that native method prefixes must remain set while used.
15290       Clarify that exactly one Agent_OnXXX is called per agent.
15291       Clarify that library loading is independent from start-up.
15292       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
15293   </change>
15294   <change date="31 July 2006" version="1.1.99">
15295       Clarify the interaction between functions and exceptions.
15296       Clarify and give examples of field indices.
15297       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
15298       Update links to point to Java 6.
15299   </change>
15300   <change date="6 August 2006" version="1.1.102">
15301       Add ResourceExhaustedEvent.
15302   </change>
15303   <change date="11 October 2012" version="1.2.2">
15304       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
15305   </change>
15306   <change date="19 June 2013" version="1.2.3">
15307       Added support for statically linked agents.
15308   </change>
15309   <change date="13 October 2016" version="9.0.0">
15310       Support for modules:
15311        - The majorversion is 9 now
15312        - The ClassFileLoadHook events are not sent during the primordial phase anymore.
15313        - Allow CompiledMethodLoad events at start phase
15314        - Add new capabilities:
15315           - can_generate_early_vmstart
15316           - can_generate_early_class_hook_events
15317        - Add new functions:
15318           - GetAllModules
15319           - AddModuleReads, AddModuleExports, AddModuleOpens, AddModuleUses, AddModuleProvides
15320           - IsModifiableModule
15321       Clarified can_redefine_any_classes, can_retransform_any_classes and IsModifiableClass API to
15322       disallow some implementation defined classes.
15323   </change>
15324   <change date="12 February 2017" version="9.0.0">
15325       Minor update for GetCurrentThread function:
15326        - The function may return NULL in the start phase if the
15327          can_generate_early_vmstart capability is enabled.
15328   </change>
15329   <change date="7 February 2018" version="11.0.0">
15330       Minor update for new class file NestHost and NestMembers attributes:
15331         - Specify that RedefineClasses and RetransformClasses are not allowed
15332           to change the class file NestHost and NestMembers attributes.
15333         - Add new error JVMTI_ERROR_UNSUPPORTED_REDEFINITION_CLASS_ATTRIBUTE_CHANGED
15334           that can be returned by RedefineClasses and RetransformClasses.
15335   </change>
15336   <change date="20 May 2019" version="13.0.0">
15337       Minor spec update for the capability "can_redefine_any_class".
15338       It now says:
15339        "RedefineClasses can be called on any modifiable class. See IsModifiableClass.
15340        (can_redefine_classes must also be set)"
15341   </change>
15342   <change date="5 June 2019" version="13.0.0">
15343       Minor PopFrame spec update:
15344         - The specified thread must be suspended or must be the current thread.
15345           (It was not allowed to be the current thread before.)
15346   </change>
15347   <change date="10 October 2019" version="14.0.0">
15348       Minor update for new class file Record attribute:
15349         - Specify that RedefineClasses and RetransformClasses are not allowed
15350           to change the class file Record attribute.
15351   </change>
15352   <change date="13 May 2020" version="15.0.0">
15353       Minor update for new class file PermittedSubclasses attribute:
15354         - Specify that RedefineClasses and RetransformClasses are not allowed
15355           to change the class file PermittedSubclasses attribute.
15356   </change>
15357   <change date="15 January 2021" version="17.0.0">
15358       Minor clarification in the section "Agent Shutdown" that says the
15359       implementation may choose to not call the Agent_OnUnload function
15360       if the Agent_OnAttach/Agent_OnAttach_L function reported an error. 
15361   </change>
15362   <change date="8 June 2021" version="17.0.0">
15363       Minor update to deprecate Heap functions 1.0.
15364   </change>
15365 </changehistory>
15366 
15367 </specification>
15368 <!-- Keep this comment at the end of the file
15369 Local variables:
15370 mode: sgml
15371 sgml-omittag:t
15372 sgml-shorttag:t
15373 sgml-namecase-general:t
15374 sgml-general-insert-case:lower
15375 sgml-minimize-attributes:nil
15376 sgml-always-quote-attributes:t
15377 sgml-indent-step:2
15378 sgml-indent-data:t
15379 sgml-parent-document:nil
15380 sgml-exposed-tags:nil
15381 sgml-local-catalogs:nil
15382 sgml-local-ecat-files:nil
15383 End:
15384 -->