Mercurial > jdk8-mips64-public > hotspot / file revision

 <?xml version="1.0" encoding="ISO-8859-1"?>

 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>

 <!--

  Copyright 2002-2006 Sun Microsystems, Inc.  All Rights Reserved.

  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

  This code is free software; you can redistribute it and/or modify it

  under the terms of the GNU General Public License version 2 only, as

  published by the Free Software Foundation.

  This code is distributed in the hope that it will be useful, but WITHOUT

  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or

  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

  version 2 for more details (a copy is included in the LICENSE file that

  accompanied this code).

  You should have received a copy of the GNU General Public License version

  2 along with this work; if not, write to the Free Software Foundation,

  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

  Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,

  CA 95054 USA or visit www.sun.com if you need additional information or

  have any questions.

 -->

 <!DOCTYPE specification [

    <!ELEMENT specification (title, intro*, functionsection, errorsection, 

                             eventsection, datasection, issuessection, changehistory)>

    <!ATTLIST specification label CDATA #REQUIRED 

                            majorversion CDATA #REQUIRED 

                            minorversion CDATA #REQUIRED 

                            microversion CDATA #REQUIRED>

    <!ELEMENT title (#PCDATA|jvmti|tm)*>

    <!ATTLIST title subtitle CDATA #REQUIRED>

    <!ELEMENT intro ANY>

    <!ATTLIST intro id CDATA #IMPLIED

                    label CDATA "">

    <!ELEMENT functionsection (intro*, category*)>

    <!ATTLIST functionsection label CDATA #REQUIRED>

    <!ELEMENT category ((intro|typedef|uniontypedef|capabilitiestypedef)*, 

                           (function|callback|elide)*)>

    <!ATTLIST category id CDATA #REQUIRED

                       label CDATA #REQUIRED>

    <!ELEMENT function (synopsis, typedef*, description?, origin,

                          (capabilities|eventcapabilities), 

                          parameters, errors)>

    <!ATTLIST function id CDATA #REQUIRED

                       num CDATA #REQUIRED

                       phase (onload|onloadOnly|start|live|any) #IMPLIED

 		      callbacksafe (safe|unsafe) #IMPLIED

                       impl CDATA #IMPLIED

                       hide CDATA #IMPLIED

                       jkernel (yes|no) #IMPLIED

                       since CDATA "1.0">

    <!ELEMENT callback ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|

                         jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void),

                         synopsis, description?, parameters)>

    <!ATTLIST callback id CDATA #REQUIRED

                       since CDATA "1.0">

    <!ELEMENT synopsis (#PCDATA|jvmti)*>

    <!ELEMENT typedef (description?, field*)>

    <!ATTLIST typedef id CDATA #REQUIRED

                      label CDATA #REQUIRED

                      since CDATA "1.0">

    <!ELEMENT uniontypedef (description?, field*)>

    <!ATTLIST uniontypedef id CDATA #REQUIRED

                      label CDATA #REQUIRED

                      since CDATA "1.0">

    <!ELEMENT field ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|

                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|allocfieldbuf|inptr|inbuf|outbuf|vmbuf|ptrtype|struct), 

                     description)>

    <!ATTLIST field id CDATA #REQUIRED>

    <!ELEMENT capabilitiestypedef (description?, capabilityfield*)>

    <!ATTLIST capabilitiestypedef id CDATA #REQUIRED

                      label CDATA #REQUIRED>

    <!ELEMENT capabilityfield (description)>

    <!ATTLIST capabilityfield id CDATA #REQUIRED

                    disp1 CDATA ""

                    disp2 CDATA ""

                    since CDATA "1.0">

    <!ELEMENT description ANY>

    <!ELEMENT capabilities (required*, capability*)>

    <!ELEMENT eventcapabilities EMPTY>

    <!ELEMENT required ANY>

    <!ATTLIST required id CDATA #REQUIRED>

    <!ELEMENT capability ANY>

    <!ATTLIST capability id CDATA #REQUIRED>

    <!ELEMENT parameters (param*)>

    <!ELEMENT param ((jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|jthreadGroup|jobject|

                      jvalue|enum|jint|jlong|jfloat|jdouble|jlocation|jboolean|char|uchar|size_t|void|varargs|struct|ptrtype|

                      outptr|allocbuf|allocallocbuf|inptr|inbuf|outbuf|vmbuf|agentbuf), 

                     description)>

    <!ATTLIST param id CDATA #REQUIRED>

    <!ELEMENT jmethodID EMPTY>

    <!ATTLIST jmethodID class  CDATA #IMPLIED

                        native CDATA #IMPLIED>

    <!ELEMENT jfieldID EMPTY>

    <!ATTLIST jfieldID class CDATA #IMPLIED>

    <!ELEMENT jclass EMPTY>

    <!ATTLIST jclass method CDATA #IMPLIED

                     field  CDATA #IMPLIED>

    <!ELEMENT jframeID EMPTY>

    <!ATTLIST jframeID thread CDATA #IMPLIED>

    <!ELEMENT jrawMonitorID EMPTY>

    <!ELEMENT jthread EMPTY>

    <!ATTLIST jthread started CDATA #IMPLIED

                      null CDATA #IMPLIED

                      frame CDATA #IMPLIED

                      impl CDATA #IMPLIED>

    <!ELEMENT varargs EMPTY>

    <!ELEMENT jthreadGroup EMPTY>

    <!ELEMENT jobject EMPTY>

    <!ELEMENT jvalue EMPTY>

    <!ELEMENT jchar EMPTY>

    <!ELEMENT jint EMPTY>

    <!ATTLIST jint min CDATA #IMPLIED>

    <!ELEMENT jlong EMPTY>

    <!ELEMENT jfloat EMPTY>

    <!ELEMENT jdouble EMPTY>

    <!ELEMENT jlocation EMPTY>

    <!ELEMENT jboolean EMPTY>

    <!ELEMENT char EMPTY>

    <!ELEMENT uchar EMPTY>

    <!ELEMENT size_t EMPTY>

    <!ELEMENT void EMPTY>

    <!ELEMENT enum (#PCDATA)*>

    <!ELEMENT struct (#PCDATA)*>

    <!ELEMENT nullok ANY>

    <!ELEMENT ptrtype     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue), nullok?)>

    <!ELEMENT outptr     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|

                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>

    <!ELEMENT allocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>

    <!ATTLIST allocbuf incount CDATA #IMPLIED

                       outcount CDATA #IMPLIED>

    <!ELEMENT allocallocbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>

    <!ATTLIST allocallocbuf incount CDATA #IMPLIED

                       outcount CDATA #IMPLIED>

    <!ELEMENT inptr      (struct, nullok?)>

    <!ELEMENT inbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>

    <!ATTLIST inbuf    incount CDATA #IMPLIED>

    <!ELEMENT outbuf     ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

                                    jlocation|jboolean|char|uchar|size_t|void|outbuf), nullok?)>

    <!ATTLIST outbuf   incount CDATA #IMPLIED

                       outcount CDATA #IMPLIED>

    <!ELEMENT vmbuf      ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue|enum|jchar|jint|jlong|jfloat|jdouble|

                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>

    <!ATTLIST vmbuf    incount CDATA #IMPLIED

                       outcount CDATA #IMPLIED>

    <!ELEMENT agentbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

                                    jlocation|jboolean|char|uchar|size_t|void), nullok?)>

    <!ATTLIST agentbuf incount CDATA #IMPLIED

                       outcount CDATA #IMPLIED>

    <!ELEMENT allocfieldbuf   ((struct|jmethodID|jfieldID|jframeID|jrawMonitorID|jclass|jthread|

                                    jthreadGroup|jobject|jvalue|enum|jint|jlong|jfloat|jdouble|

                                    jlocation|jboolean|char|uchar|size_t|void))>

    <!ATTLIST allocfieldbuf outcount CDATA #IMPLIED>

    <!ELEMENT errors (error*)>

    <!ELEMENT error ANY>

    <!ATTLIST error id CDATA #REQUIRED>

    <!ELEMENT errorsection (intro*, errorcategory*)>

    <!ATTLIST errorsection label CDATA #REQUIRED>

    <!ELEMENT errorcategory (intro*, errorid*)>

    <!ATTLIST errorcategory id CDATA #REQUIRED

                            label CDATA #REQUIRED>

    <!ELEMENT errorid ANY>

    <!ATTLIST errorid id CDATA #REQUIRED

                      num CDATA #REQUIRED>

    <!ELEMENT datasection (intro*, basetypes*)>

    <!ELEMENT basetypes (intro*, basetype*)>

    <!ATTLIST basetypes id CDATA #REQUIRED

                        label CDATA #REQUIRED>

    <!ELEMENT basetype (definition?,description)>

    <!ATTLIST basetype id CDATA #REQUIRED>

    <!ELEMENT definition (#PCDATA|jvmti)*>

    <!ELEMENT eventsection (intro*, (event|elide)*)>

    <!ATTLIST eventsection label CDATA #REQUIRED>

    <!ELEMENT event (description, origin, typedef*, capabilities, parameters)>

    <!ATTLIST event id CDATA #REQUIRED

                    label CDATA #REQUIRED

                    const CDATA #REQUIRED

                    num CDATA #REQUIRED

                    phase (onload|start|live|any) #IMPLIED

                    filtered (thread|global) #IMPLIED

                    since CDATA "1.0">

    <!ELEMENT issuessection (intro*)>

    <!ATTLIST issuessection label CDATA #REQUIRED>

    <!ELEMENT changehistory (intro*, change*)>

    <!ATTLIST changehistory update CDATA #REQUIRED

                            id CDATA #REQUIRED>

    <!ELEMENT change ANY>

    <!ATTLIST change date CDATA #REQUIRED

                     version CDATA #IMPLIED>

    <!ELEMENT functionlink (#PCDATA|jvmti|code|i|b)*>

    <!ATTLIST functionlink id CDATA #REQUIRED>

    <!ELEMENT datalink (#PCDATA|jvmti|code|i|b)*>

    <!ATTLIST datalink id CDATA #REQUIRED>

    <!ELEMENT typelink (#PCDATA|jvmti|code|i|b)*>

    <!ATTLIST typelink id CDATA #REQUIRED>

    <!ELEMENT fieldlink (#PCDATA|jvmti|code|i|b)*>

    <!ATTLIST fieldlink id CDATA #REQUIRED

                        struct CDATA #REQUIRED>

    <!ELEMENT paramlink (#PCDATA|jvmti|code|i|b)*>

    <!ATTLIST paramlink id CDATA #REQUIRED>

    <!ELEMENT eventlink (#PCDATA|jvmti|code|i|b)*>

    <!ATTLIST eventlink id CDATA #REQUIRED>

    <!ELEMENT errorlink (#PCDATA|jvmti|code|i|b|tm)*>

    <!ATTLIST errorlink id CDATA #REQUIRED>

    <!ELEMENT externallink (#PCDATA|jvmti|code|i|b|tm)*>

    <!ATTLIST externallink id CDATA #REQUIRED>

    <!ELEMENT vmspeclink EMPTY>

    <!ATTLIST vmspeclink id CDATA #IMPLIED>

    <!ATTLIST vmspeclink name CDATA #IMPLIED>

    <!ATTLIST vmspeclink preposition CDATA #IMPLIED>

    <!ELEMENT internallink (#PCDATA|jvmti|code|i|b)*>

    <!ATTLIST internallink id CDATA #REQUIRED>

    <!ELEMENT functionphaselist EMPTY>

    <!ATTLIST functionphaselist phase (onload|onloadOnly|start|live|any) #REQUIRED>

    <!ELEMENT eventphaselist EMPTY>

    <!ATTLIST eventphaselist phase (onload|start|live|any) #REQUIRED>

    <!ELEMENT issue ANY>

    <!ELEMENT rationale ANY>

    <!ELEMENT todo ANY>

    <!ELEMENT origin (#PCDATA)*>

    <!ELEMENT elide (intro|function|callback|event)*>

    <!ATTLIST elide why CDATA #IMPLIED>

    <!ELEMENT constants (constant*)>

    <!ATTLIST constants id CDATA #REQUIRED

                        label CDATA #REQUIRED

                        kind (enum|bits|const) #REQUIRED

                        since CDATA "1.0">

    <!ELEMENT constant ANY>

    <!ATTLIST constant id CDATA #REQUIRED

                       num CDATA #REQUIRED>

    <!ELEMENT tm (#PCDATA)>

    <!ELEMENT i (#PCDATA|jvmti|tm)*>

    <!ELEMENT b (#PCDATA|jvmti|code)*>

    <!ELEMENT code (#PCDATA|space)*>

    <!ELEMENT pre ANY>

    <!ELEMENT space EMPTY>

    <!ELEMENT jvmti EMPTY>

    <!ELEMENT example (#PCDATA|i)*>

    <!ELEMENT br EMPTY>

    <!ELEMENT p EMPTY>

    <!ELEMENT dl  (dt|dd)+>

    <!ELEMENT dd  ANY>

    <!ELEMENT dt  (#PCDATA|jvmti|code|i|b)*>

    <!ELEMENT table  (tr)+>

    <!ELEMENT tr  (td|th)*>

    <!ELEMENT td  ANY>

    <!ATTLIST td align (left|right|center) "center">

    <!ELEMENT th  ANY>

    <!ATTLIST th align (left|right|center) "center">

    <!ELEMENT ul  (li)+>

    <!ATTLIST ul type (disc|circle|square) "disc">

    <!ELEMENT li  ANY>

  ]>

 <specification label="JVM(TM) Tool Interface"

         majorversion="1"

         minorversion="1"

         microversion="109">

   <title subtitle="Version">

     <tm>JVM</tm> Tool Interface

   </title>

   <intro id="whatIs" label="What is the JVM Tool Interface?">

     The <tm>JVM</tm> Tool Interface (<jvmti/>) 

     is a programming interface used by development and monitoring tools. 

     It provides both a way to inspect the state and 

     to control the execution of applications running in the

     <tm>Java</tm> virtual machine (VM).

     <p/>

     <jvmti/> is intended to provide a VM interface for the full breadth of tools

     that need access to VM state, including but not limited to: profiling,

     debugging, monitoring, thread analysis, and coverage analysis tools.

     <p/>

     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual

     machine.

     <p/>

     <jvmti/> is a two-way interface. 

     A client of <jvmti/>, hereafter called an <i>agent</i>,

     can be notified of

     interesting occurrences through <internallink id="EventSection">events</internallink>. 

     <jvmti/>

     can query and control the application through many 

     <internallink id="FunctionSection">functions</internallink>, 

     either in response to events or 

     independent of them.

     <p/>

     Agents run in the same process with and communicate directly with 

     the virtual machine executing

     the application being examined.  This communication is

     through a native interface (<jvmti/>). The native in-process interface allows

     maximal control with minimal intrusion on the part of a tool. 

     Typically, agents are relatively compact. They can be controlled

     by a separate process which implements the bulk of a tool's

     function without interfering with the target application's normal execution.

   </intro>

   <intro id="architecture" label="Architecture">

     Tools can be written directly to <jvmti/> or indirectly

     through higher level interfaces.

     The Java Platform Debugger Architecture includes <jvmti/>, but also

     contains higher-level, out-of-process debugger interfaces. The higher-level 

     interfaces are more appropriate than <jvmti/> for many tools. 

     For more information on the Java Platform Debugger Architecture, 

     see the 

     <externallink id="http://java.sun.com/products/jpda/">Java 

       Platform Debugger Architecture website</externallink>. 

   </intro>

   <intro id="writingAgents" label="Writing Agents">

     Agents can be written in any native language that supports C

     language calling conventions and C or C++

     definitions.

     <p/>

     The function, event, data type, and constant definitions needed for

     using <jvmti/> are defined in the include file <code>jvmti.h</code>.

     To use these definitions add the <tm>J2SE</tm> include directory

     to your include path and add

     <example>

 #include <jvmti.h>

     </example>

     to your source code.

   </intro>

   <intro id="deployingAgents" label="Deploying Agents">

     An agent is deployed in a platform specific manner but is typically the 

     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating 

     system, for example, an agent library is a "Dynamic Linked Library" (DLL). 

     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared

     object (<code>.so</code> file).

     <p/>

     An agent may be started at VM startup by specifying the agent library

     name using a <internallink id="starting">command line option</internallink>.

     Some implementations may support a mechanism to <internallink id="onattach"> 

     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.

     The details of how this is initiated are implementation specific.

   </intro>

   <intro id="starting" label="Agent Command Line Options">

     The term "command-line option" is used below to

     mean options supplied in the <code>JavaVMInitArgs</code> argument

     to the <code>JNI_CreateJavaVM</code> function of the JNI

     Invocation API.

     <p/>

     One of the two following 

     command-line options is used on VM startup to 

     properly load and run agents.

     These arguments identify the library containing 

     the agent as well as an options

     string to be passed in at startup. 

     <dl>

       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>

       <dd>

 	The name following <code>-agentlib:</code> is the name of the

 	library to load.  Lookup of the library, both its full name and location,

 	proceeds in a platform-specific manner. 

 	Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an

 	operating system specific file name.

 	The <i>&lt;options&gt;</i> will be passed to the agent on start-up.

 	For example, if the option 

 	<code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to 

 	load the shared library <code>foo.dll</code> from the system <code>PATH</code>

         under <tm>Windows</tm> or <code>libfoo.so</code> from the 

 	<code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment.

       </dd>

       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>

       <dd>

 	The path following <code>-agentpath:</code> is the absolute path from which

 	to load the library.

 	No library name expansion will occur.

 	The <i>&lt;options&gt;</i> will be passed to the agent on start-up.

 	For example, if the option 

 	<code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to 

 	load the shared library <code>c:\myLibs\foo.dll</code>.

       </dd>

     </dl>

     The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink>

     in the library will be invoked.

     <p/>

     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>

     will be searched for JNI native method implementations to facilitate the

     use of Java programming language code in tools, as is needed for 

     <internallink id="bci">bytecode instrumentation</internallink>.

     <p/>

     The agent libraries will be searched after all other libraries have been

     searched (agents wishing to override or intercept the native method

     implementations of non-agent methods can use the

     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).

     <p/>

     These switches do the above and nothing more - they do not change the 

     state of the VM or <jvmti/>.  No command line options are needed 

     to enable <jvmti/> 

     or aspects of <jvmti/>, this is handled programmatically

     by the use of 

     <internallink id="capability">capabilities</internallink>.

   </intro>

   <intro id="startup" label="Agent Start-Up">

     The VM starts each agent by invoking a start-up function.

     If the agent is started in the <code>OnLoad</code>

     <functionlink id="GetPhase">phase</functionlink> the function

     <internallink id="onload"><code>Agent_OnLoad</code></internallink>

     will be invoked.

     If the agent is started in the live

     <functionlink id="GetPhase">phase</functionlink> the function

     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>

     will be invoked.

     Exactly one call to a start-up function is made per agent.  

   </intro>

   <intro id="onload" label="Agent Start-Up (OnLoad phase)">

     If an agent is started during the <code>OnLoad</code> phase then its

     agent library must export a start-up function with the following prototype:

     <example>

 JNIEXPORT jint JNICALL 

 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>

     The VM will start the agent by calling this function.  

     It will be called early enough in VM initialization that:

     <ul>

       <li><functionlink id="SetSystemProperty">system properties</functionlink>

 	may be set before they have been used in the start-up of the VM</li>

       <li>the full set of 

 	<internallink id="capability">capabilities</internallink>

 	is still available (note that capabilities that configure the VM

 	may only be available at this time--see the 

 	<internallink id="capability">Capability function section</internallink>)</li>

       <li>no bytecodes have executed</li>

       <li>no classes have been loaded</li>

       <li>no objects have been created</li>

     </ul>

     <p/>

     The VM will call the <code>Agent_OnLoad</code> function with

     <i>&lt;options&gt;</i> as the second argument - 

     that is, using the command-line option examples,

     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> 

     argument of <code>Agent_OnLoad</code>.

     The <code>options</code> argument is encoded as a

     <internallink id="mUTF">modified UTF-8</internallink> string.

     If <i>=&lt;options&gt;</i> is not specified, 

     a zero length string is passed to <code>options</code>.

     The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code>

     call.  If needed beyond this time the string or parts of the string must

     be copied.

     The period between when <code>Agent_OnLoad</code> is called and when it

     returns is called the <i>OnLoad phase</i>.

     Since the VM is not initialized during the OnLoad 

     <functionlink id="GetPhase">phase</functionlink>,

     the set of allowed operations 

     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the

     functionality available at this time). 

     The agent can safely process the options and set 

     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once  

     the VM initialization event is received 

     (that is, the <eventlink id="VMInit">VMInit</eventlink> 

     callback is invoked), the agent

     can complete its initialization.

     <rationale>

       Early startup is required so that agents can set the desired capabilities,

       many of which must be set before the VM is initialized.

       In JVMDI, the -Xdebug command-line option provided 

       very coarse-grain control of capabilities. 

       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.

       No reasonable command-line 

       option could provide the fine-grain of control required to balance needed capabilities vs

       performance impact.  

       Early startup is also needed so that agents can control the execution

       environment - modifying the file system and system properties to install

       their functionality.

     </rationale>

     <p/>

     The return value from <code>Agent_OnLoad</code> is used to indicate an error.

     Any value other than zero indicates an error and causes termination of the VM.

   </intro>

   <intro id="onattach" label="Agent Start-Up (Live phase)">

     A VM may support a mechanism that allows agents to be started in the VM during the live 

     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,

     are implementation specific. For example, a tool may use some platform specific mechanism, 

     or implementation specific API, to attach to the running VM, and request it start a given

     agent.

     <p/>

     If an agent is started during the live phase then its agent library

     must export a start-up function 

     with the following prototype:

     <example>

 JNIEXPORT jint JNICALL 

 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>

     <p/>         

     The VM will start the agent by calling this function.  

     It will be called in the context of a thread

     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.

     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.

     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8

     </internallink> string.

     If startup options were not provided, a zero length string is passed to 

     <code>options</code>. The lifespan of the <code>options</code> string is the 

     <code>Agent_OnAttach</code> call.  If needed beyond this time the string or parts of 

     the string must be copied.

     <p/>

     Note that some <internallink id="capability">capabilities</internallink> 

     may not be available in the live phase.

     <p/>

     The <code>Agent_OnAttach</code> function initializes the agent and returns a value

     to the VM to indicate if an error occurred. Any value other than zero indicates an error. 

     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes 

     some implementation specific action -- for example it might print an error to standard error, 

     or record the error in a system log.

   </intro>

   <intro id="onunload" label="Agent Shutdown">

     The library may optionally export a 

     shutdown function with the following prototype:

     <example>

 JNIEXPORT void JNICALL 

 Agent_OnUnload(JavaVM *vm)</example>

     This function will be called by the VM when the library is about to be unloaded.

     The library will be unloaded and this function will be called if some platform specific 

     mechanism causes the unload (an unload mechanism is not specified in this document)

     or the library is (in effect) unloaded by the termination of the VM whether through 

     normal termination or VM failure, including start-up failure.

     Uncontrolled shutdown is, of couse, an exception to this rule.

     Note the distinction between this function and the 

     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event

     to be sent, the VM must have run at least to the point of initialization and a valid 

     <jvmti/> environment must exist which has set a callback for VMDeath

     and enabled the event

     None of these are required for <code>Agent_OnUnload</code> and this function

     is also called if the library is unloaded for other reasons.

     In the case that a VM Death event is sent, it will be sent before this 

     function is called (assuming this function is called due to VM termination).

     This function can be used to clean-up resources allocated by the agent.

   </intro>

   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">

     Since the command-line cannot always be accessed or modified, for example in embedded VMs

     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is

     provided so that agents may be launched in these cases.

     <p/>

     Platforms which support environment variables or other named strings, may support the 

     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space 

     boundaries.  White-space characters include space, tab, carriage-return, new-line, 

     vertical-tab, and form-feed.  Sequences of white-space characters are considered 

     equivalent to a single white-space character.  No white-space is included in the options 

     unless quoted.  Quoting is as follows:

     <ul>

         <li>All characters enclosed between a pair of single quote marks (''), except a single 

         quote, are quoted.</li>

         <li>Double quote characters have no special meaning inside a pair of single quote marks.</li>

         <li>All characters enclosed between a pair of double quote marks (""), except a double 

         quote, are quoted.</li>

         <li>Single quote characters have no special meaning inside a pair of double quote marks.</li>

         <li>A quoted part can start or end anywhere in the variable.</li>

         <li>White-space characters have no special meaning when quoted -- they are included in

         the option like any other character and do not mark white-space boundaries.</li>

         <li>The pair of quote marks is not included in the option.</li>

     </ul>

     <code>JNI_CreateJavaVM</code> (in the JNI Invocation API) will prepend these options to the options supplied 

     in its <code>JavaVMInitArgs</code> argument. Platforms may disable this feature in cases where security is 

     a concern; for example, the Reference Implementation disables this feature on Unix systems when 

     the effective user or group ID differs from the real ID.  

     This feature is intended to support the initialization of tools -- specifically including the 

     launching of native or Java programming language agents.  Multiple tools may wish to use this 

     feature, so the variable should not be overwritten, instead,  options should be appended to 

     the variable.  Note that since the variable is processed at the time of the JNI Invocation 

     API create VM call, options processed by a launcher (e.g., VM selection options) will not be handled.

   </intro>

   <intro id="environments" label="Environments">

     The <jvmti/> specification supports the use of multiple simultaneous

     <jvmti/> agents.

     Each agent has its own <jvmti/> environment.  

     That is, the <jvmti/> state is

     separate for each agent - changes to one environment do not affect the

     others.  The state of a <jvmti/> 

     environment includes:

     <ul>

       <li><functionlink id="SetEventCallbacks">the event callbacks</functionlink></li>

       <li><functionlink id="SetEventNotificationMode">the set of events which are enabled</functionlink></li>

       <li><internallink id="capability">the capabilities</internallink></li>

       <li><internallink id="memory">the memory allocation/deallocation hooks</internallink></li>

     </ul>

     Although their <jvmti/> state 

     is separate, agents inspect and modify the shared state

     of the VM, they also share the native environment in which they execute.

     As such, an agent can perturb the results of other agents or cause them

     to fail.  It is the responsibility of the agent writer to specify the level

     of compatibility with other agents.  <jvmti/> implementations are not capable

     of preventing destructive interactions between agents. Techniques to reduce

     the likelihood of these occurrences are beyond the scope of this document.

     <p/>

     An agent creates a <jvmti/> environment 

     by passing a <jvmti/> version 

     as the interface ID to the JNI Invocation API function 

     <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#GetEnv"><code>GetEnv</code></externallink>.

     See <internallink id="jvmtiEnvAccess">Accessing <jvmti/> Functions</internallink>

     for more details on the creation and use of 

     <jvmti/> environments.

     Typically, <jvmti/> environments are created by calling <code>GetEnv</code> from 

     <internallink id="onload"><code>Agent_OnLoad</code></internallink>.

   </intro>

   <intro id="bci" label="Bytecode Instrumentation">

     This interface does not include some events that one might expect in an interface with

     profiling support.  Some examples include object allocation events and full speed

     method enter and exit events.  The interface instead provides support for 

     <i>bytecode instrumentation</i>, the ability to alter the Java virtual machine

     bytecode instructions which comprise the target program.  Typically, these alterations

     are to add "events" to the code of a method - for example, to add, at the beginning of a method,

     a call to <code>MyProfiler.methodEntered()</code>.  

     Since the changes are purely additive, they do not modify application

     state or behavior.

     Because the inserted agent code is standard bytecodes, the VM can run at full speed,

     optimizing not only the target program but also the instrumentation.  If the 

     instrumentation does not involve switching from bytecode execution, no expensive

     state transitions are needed.  The result is high performance events.

     This approach also provides complete control to the agent: instrumentation can be

     restricted to "interesting" portions of the code (e.g., the end user's code) and

     can be conditional.  Instrumentation can run entirely in Java programming language

     code or can call into the native agent.  Instrumentation can simply maintain

     counters or can statistically sample events.

     <p/>  

     Instrumentation can be inserted in one of three ways:

     <ul>

       <li>

 	Static Instrumentation: The class file is instrumented before it

 	is loaded into the VM - for example, by creating a duplicate directory of

 	<code>*.class</code> files which have been modified to add the instrumentation.

 	This method is extremely awkward and, in general, an agent cannot know 

 	the origin of the class files which will be loaded.

       </li>

       <li>

 	Load-Time Instrumentation: When a class file is loaded by the VM, the raw

 	bytes of the class file are sent for instrumentation to the agent.

 	The <eventlink id="ClassFileLoadHook"/>

 	event, triggered by the class load,

 	provides this functionality.  This mechanism provides efficient

 	and complete access to one-time instrumentation.

       </li>

       <li>

 	Dynamic Instrumentation: A class which is already loaded (and possibly

 	even running) is modified.  This optional feature is provided by the

 	<eventlink id="ClassFileLoadHook"/> event, triggered by calling the

 	<functionlink id="RetransformClasses"/> function.

 	Classes can be modified multiple times and can be returned to their

 	original state.

 	The mechanism allows instrumentation which changes during the 

 	course of execution.

       </li>

     </ul>

     <p/>  

     The class modification functionality provided in this interface

     is intended to provide a mechanism for instrumentation

     (the <eventlink id="ClassFileLoadHook"/> event

     and the <functionlink id="RetransformClasses"/> function)

     and, during development, for fix-and-continue debugging

     (the <functionlink id="RedefineClasses"/> function).

     <p/>  

     Care must be taken to avoid perturbing dependencies, especially when 

     instrumenting core classes.  For example, an approach to getting notification

     of every object allocation is to instrument the constructor on 

     <code>Object</code>.  Assuming that the constructor is initially

     empty, the constructor could be changed to:

     <example>

       public Object() {

         MyProfiler.allocationTracker(this);

       }

     </example>

     However, if this change was made using the 

     <eventlink id="ClassFileLoadHook"/>

     event then this might impact a typical VM as follows: 

     the first created object will call the constructor causing a class load of

     <code>MyProfiler</code>; which will then cause

     object creation, and since <code>MyProfiler</code> isn't loaded yet,

     infinite recursion; resulting in a stack overflow.  A refinement of this

     would be to delay invoking the tracking method until a safe time.  For

     example, <code>trackAllocations</code> could be set in the 

     handler for the <code>VMInit</code> event.

     <example>

       static boolean trackAllocations = false;

       public Object() {

         if (trackAllocations) {

           MyProfiler.allocationTracker(this);

         }

       }

     </example>

     <p/>

     The <functionlink id="SetNativeMethodPrefix"/> allows native methods

     to be instrumented by the use of wrapper methods.

   </intro>

   <intro id="mUTF" label="Modified UTF-8 String Encoding">

     <jvmti/> uses modified UTF-8 to encode character strings.

     This is the same encoding used by JNI.

     Modified UTF-8 differs 

     from standard UTF-8 in the representation of supplementary characters 

     and of the null character. See the

     <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/types.html#wp16542">

       Modified UTF-8 Strings</externallink>

     section of the JNI specification for details.

   </intro>

   <intro id="context" label="Specification Context">

     Since this interface provides access to the state of applications running in the

     Java virtual machine; 

     terminology refers to the Java platform and not the native

     platform (unless stated otherwise).  For example:

     <ul>

       <li>"thread" means Java programming language thread.</li>

       <li>"stack frame" means Java virtual machine stack frame.</li>

       <li>"class" means Java programming language class.</li>

       <li>"heap" means Java virtual machine heap.</li>

       <li>"monitor" means Java programming language object monitor.</li>

     </ul>

     <p/>

     Sun, Sun Microsystems, the Sun logo, Java, and JVM

     are trademarks or registered trademarks of Sun

     Microsystems, Inc. in the U.S. and other countries.

   </intro>

 <functionsection label="Functions">

   <intro id="jvmtiEnvAccess" label="Accessing Functions">

     Native code accesses <jvmti/> features 

     by calling <jvmti/> functions. 

     Access to <jvmti/> functions is by use of an interface pointer

     in the same manner as 

     <externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html">Java 

       Native Interface (JNI) functions</externallink> are accessed.

     The <jvmti/> interface pointer is called the 

     <i>environment pointer</i>.

     <p/>

     An environment pointer is a pointer to an environment and has

     the type <code>jvmtiEnv*</code>.

     An environment has information about its <jvmti/> connection.

     The first value in the environment is a pointer to the function table.

     The function table is an array of pointers to <jvmti/> functions.

     Every function pointer is at a predefined offset inside the 

     array. 

     <p/>

     When used from the C language:

     double indirection is used to access the functions;

     the environment pointer provides context and is the first

     parameter of each function call; for example:

     <example>

 jvmtiEnv *jvmti;

 ...

 jvmtiError err = (*jvmti)->GetLoadedClasses(jvmti, &class_count, &classes);

     </example>

     <p/>

     When used from the C++ language:

     functions are accessed as member functions of <code>jvmtiEnv</code>;

     the environment pointer is not passed to the function call; for example:

     <example>

 jvmtiEnv *jvmti;

 ...

 jvmtiError err = jvmti->GetLoadedClasses(&class_count, &classes);

     </example>

     Unless otherwise stated, all examples and declarations in this 

     specification use the C language.

     <p/>

     A <jvmti/> environment can be obtained through the JNI Invocation API

     <code>GetEnv</code> function:

     <example>

 jvmtiEnv *jvmti;

 ...

 (*jvm)->GetEnv(jvm, &jvmti, JVMTI_VERSION_1_0);

     </example>

     Each call to <code>GetEnv</code> 

     creates a new <jvmti/> connection and thus

     a new <jvmti/> environment. 

     The <code>version</code> argument of <code>GetEnv</code> must be

     a <jvmti/> version.

     The returned environment may have a different version than the

     requested version but the returned environment must be compatible.

     <code>GetEnv</code> will return <code>JNI_EVERSION</code> if a 

     compatible version is not available, if <jvmti/> is not supported or

     <jvmti/> is not supported in the current VM configuration.

     Other interfaces may be added for creating <jvmti/> environments

     in specific contexts.

     Each environment has its own state (for example,

     <functionlink id="SetEventNotificationMode">desired events</functionlink>, 

     <functionlink id="SetEventCallbacks">event handling functions</functionlink>, and 

     <functionlink id="AddCapabilities">capabilities</functionlink>). 

     An environment is released with 

     <functionlink id="DisposeEnvironment"></functionlink>. 

     Thus, unlike JNI which has one environment per thread, <jvmti/> environments work

     across threads and are created dynamically.

   </intro>

   <intro id="functionReturn" label="Function Return Values">

     <jvmti/> functions always return an

     <internallink id="ErrorSection">error code</internallink> via the

     <datalink id="jvmtiError"/> function return value. 

     Some functions can return additional

     values through pointers provided by the calling function. 

     In some cases, <jvmti/> functions allocate memory that your program must

     explicitly deallocate. This is indicated in the individual <jvmti/>

     function descriptions.  Empty lists, arrays, sequences, etc are 

     returned as <code>NULL</code>.

     <p/>

     In the event that the <jvmti/> function encounters

     an error (any return value other than <code>JVMTI_ERROR_NONE</code>) the values

     of memory referenced by argument pointers is undefined, but no memory

     will have been allocated and no global references will have been allocated.

     If the error occurs because of invalid input, no action will have occurred.

   </intro>

 <intro id="refs" label="Managing JNI Object References">

     <jvmti/> functions identify objects with JNI references 

     (<datalink id="jobject"/> and <datalink id="jclass"/>)

     and their derivatives

     (<datalink id="jthread"/> and <datalink id="jthreadGroup"/>).

     References passed to 

     <jvmti/> functions can be either global or local, but they must be 

     strong references. All references returned by <jvmti/> functions are 

     local references--these local references are created 

     during the <jvmti/> call.

     Local references are a resource that must be managed (see the 

     <externallink id="http://java.sun.com/javase/6/docs/guide/jni/spec/functions.html#wp18654">JNI Documentation</externallink>).  

     When threads return from native code all local references

     are freed.  Note that some threads, including typical

     agent threads, will never return from native code.

     A thread is ensured the ability to create sixteen local 

     references without the need for any explicit management.

     For threads executing a limited number of <jvmti/> calls before

     returning from native code

     (for example, threads processing events), 

     it may be determined that no explicit management

     is needed.

     However, long running agent threads will need explicit

     local reference management--usually with the JNI functions

     <code>PushLocalFrame</code> and <code>PopLocalFrame</code>.

     Conversely, to preserve references beyond the

     return from native code, they must be converted to global references.

     These rules do not apply to <datalink id="jmethodID"/> and <datalink id="jfieldID"/> 

     as they are not <datalink id="jobject"/>s.

 </intro>

     <intro id="prereqState" label="Prerequisite State for Calling Functions">

       Unless the function explicitly states that the agent must bring

       a thread or the VM to a particular state (for example, suspended),

       the <jvmti/> implementation is responsible for bringing the VM to a

       safe and consistent state for performing the function.

     </intro>

     <intro id="functionsExceptions" label="Exceptions and Functions">

       <jvmti/> functions never throw exceptions; error conditions are 

       communicated via the 

       <internallink id="functionReturn">function return value</internallink>.

       Any existing exception state is preserved across a call to a 

       <jvmti/> function.

       See the

       <externallink 

         id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/design.html#wp770"

              >Java Exceptions</externallink>

       section of the JNI specification for information on handling exceptions.

     </intro>

   <category id="memory" label="Memory Management">

     <intro>

       These functions provide for the allocation and deallocation of 

       memory used by <jvmti/> functionality and can be used to provide

       working memory for agents.

       Memory managed by <jvmti/> is not compatible with other memory

       allocation libraries and mechanisms.

     </intro>

     <function id="Allocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="46">

       <synopsis>Allocate</synopsis>

       <description>

 	Allocate an area of memory through the <jvmti/> allocator. 

         The allocated

 	memory should be freed with <functionlink id="Deallocate"></functionlink>.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

       </capabilities>

       <parameters>

 	<param id="size">

 	  <jlong/>

 	  <description>

 	    The number of bytes to allocate.

 	    <rationale>

 	      <code>jlong</code> is used for compatibility with JVMDI.

 	    </rationale>

 	  </description>

 	</param>

 	<param id="mem_ptr">

 	  <allocbuf incount="size"><uchar/></allocbuf>

 	  <description>

 	    On return, a pointer to the beginning of the allocated memory.

             If <code>size</code> is zero, <code>NULL</code> is returned.

 	  </description>

 	</param>

       </parameters>

       <errors>

 	<error id="JVMTI_ERROR_OUT_OF_MEMORY">

 	  Memory request cannot be honored.

 	</error>

 	<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">

 	  <paramlink id="size"></paramlink> is less than zero.

 	</error>

       </errors>

     </function>

     <function id="Deallocate" jkernel="yes" phase="any" callbacksafe="safe" impl="notrace" num="47">

       <synopsis>Deallocate</synopsis>

       <description>

 	Deallocate <code>mem</code>  using the <jvmti/> allocator. 

         This function should

 	be used to deallocate any memory allocated and returned 

         by a <jvmti/> function

 	(including memory allocated with <functionlink id="Allocate"></functionlink>).

         All allocated memory must be deallocated

         or the memory cannot be reclaimed.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

       </capabilities>

       <parameters>

 	<param id="mem">

 	  <outbuf>

             <uchar/>

 	    <nullok>the call is ignored</nullok>

           </outbuf>

 	  <description>

 	    A pointer to the beginning of the allocated memory.

             Please ignore "On return, the elements are set."

               <todo>keep it from generating "On return, the elements are set"</todo>

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

   </category>

   <category id="threadCategory" label="Thread">

     <intro>

     </intro>

     <function id="GetThreadState" num="17">

       <synopsis>Get Thread State</synopsis>

       <description>

         Get the state of a thread.  The state of the thread is represented by the

         answers to the hierarchical set of questions below:

           <ul type="circle">

             <li><i>Alive?</i>

               <ul>

                 <li>Not alive.

                   <ul type="circle">

                     <li><i>Why not alive?</i>

                       <ul>

                         <li>New.</li>

                         <li>Terminated (<datalink 

                             id="JVMTI_THREAD_STATE_TERMINATED"><code>JVMTI_THREAD_STATE_TERMINATED</code></datalink>)</li>

                       </ul>

                     </li>

                   </ul>

                 </li>

                 <li>Alive (<datalink 

                     id="JVMTI_THREAD_STATE_ALIVE"><code>JVMTI_THREAD_STATE_ALIVE</code></datalink>)

                   <ul type="circle">

                     <li><i>Suspended?</i>

                       <ul>

                         <li>Suspended (<datalink 

                             id="JVMTI_THREAD_STATE_SUSPENDED"><code>JVMTI_THREAD_STATE_SUSPENDED</code></datalink>)</li>

                         <li>Not suspended</li>

                       </ul>

                     </li>

                     <li><i>Interrupted?</i>

                       <ul>

                         <li>Interrupted (<datalink 

                             id="JVMTI_THREAD_STATE_INTERRUPTED"><code>JVMTI_THREAD_STATE_INTERRUPTED</code></datalink>)</li>

                         <li>Not interrupted.</li>

                       </ul>

                     </li>

                     <li><i>In native?</i>

                       <ul>

                         <li>In native code (<datalink 

                             id="JVMTI_THREAD_STATE_IN_NATIVE"><code>JVMTI_THREAD_STATE_IN_NATIVE</code></datalink>)</li>

                         <li>In Java programming language code</li>

                       </ul>

                     </li>

                     <li><i>What alive state?</i>

                       <ul>

                         <li>Runnable (<datalink 

                             id="JVMTI_THREAD_STATE_RUNNABLE"><code>JVMTI_THREAD_STATE_RUNNABLE</code></datalink>)</li>

                         <li>Blocked (<datalink 

                             id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER"><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></datalink>)</li>

                         <li>Waiting (<datalink 

                             id="JVMTI_THREAD_STATE_WAITING"><code>JVMTI_THREAD_STATE_WAITING</code></datalink>)

                           <ul type="circle">

                             <li><i>Timed wait?</i>

                               <ul>

                                 <li>Indefinite (<datalink 

                                     id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY"><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></datalink></li>

                                 <li>Timed (<datalink 

                                     id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT"><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></datalink>)</li>

                               </ul>

                             </li>

                             <li><i>Why waiting?</i>

                               <ul>

                                 <li>Object.wait (<datalink 

                                     id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT"><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></datalink>)</li>

                                 <li>LockSupport.park (<datalink 

                                     id="JVMTI_THREAD_STATE_PARKED"><code>JVMTI_THREAD_STATE_PARKED</code></datalink>)</li>

                                 <li>Sleeping (<datalink 

                                     id="JVMTI_THREAD_STATE_SLEEPING"><code>JVMTI_THREAD_STATE_SLEEPING</code></datalink>)</li>

                               </ul>

                             </li>

                           </ul>

                         </li>

                       </ul>

                     </li>

                   </ul>

                 </li>

               </ul>

             </li>

           </ul>

         <p/>

 	The answers are represented by the following bit vector. 

 	<constants id="jvmtiThreadState" label="Thread State Flags" kind="bits">

 	  <constant id="JVMTI_THREAD_STATE_ALIVE" num="0x0001">

 	    Thread is alive. Zero if thread is new (not started) or terminated.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_TERMINATED" num="0x0002">

 	    Thread has completed execution.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_RUNNABLE" num="0x0004">

 	    Thread is runnable.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER" num="0x0400">

 	    Thread is waiting to enter a synchronization block/method or,

             after an <code>Object.wait()</code>, waiting to re-enter a 

             synchronization block/method.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_WAITING" num="0x0080">

 	    Thread is waiting.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_WAITING_INDEFINITELY" num="0x0010">

 	    Thread is waiting without a timeout.

             For example, <code>Object.wait()</code>.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT" num="0x0020">

 	    Thread is waiting with a maximum time to wait specified.

             For example, <code>Object.wait(long)</code>.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_SLEEPING" num="0x0040">

 	    Thread is sleeping -- <code>Thread.sleep(long)</code>.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_IN_OBJECT_WAIT" num="0x0100">

 	    Thread is waiting on an object monitor -- <code>Object.wait</code>.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_PARKED" num="0x0200">

 	    Thread is parked, for example: <code>LockSupport.park</code>,

             <code>LockSupport.parkUtil</code> and <code>LockSupport.parkNanos</code>.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_SUSPENDED" num="0x100000">

 	    Thread suspended.

 	    <code>java.lang.Thread.suspend()</code>

 	    or a <jvmti/> suspend function 

             (such as <functionlink id="SuspendThread"></functionlink>) 

             has been called on the thread. If this bit

 	    is set, the other bits refer to the thread state before suspension.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_INTERRUPTED" num="0x200000">

 	    Thread has been interrupted.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_IN_NATIVE" num="0x400000">

             Thread is in native code--that is, a native method is running

             which has not called back into the VM or Java programming

             language code.

             <p/>

             This flag is not set when running VM compiled Java programming

             language code nor is it set when running VM code or

             VM support code. Native VM interface functions, such as JNI and

             <jvmti/> functions, may be implemented as VM code.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_VENDOR_1" num="0x10000000">

             Defined by VM vendor.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_VENDOR_2" num="0x20000000">

             Defined by VM vendor.

 	  </constant>

 	  <constant id="JVMTI_THREAD_STATE_VENDOR_3" num="0x40000000">

             Defined by VM vendor.

 	  </constant>

 	</constants>

         The following definitions are used to convert <jvmti/> thread state

         to <code>java.lang.Thread.State</code> style states.

 	<constants id="jvmtiJavaLangThreadState" label="java.lang.Thread.State Conversion Masks" kind="bits">

 	  <constant id="JVMTI_JAVA_LANG_THREAD_STATE_MASK"

                      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">

 	    Mask the state with this before comparison

 	  </constant>

 	  <constant id="JVMTI_JAVA_LANG_THREAD_STATE_NEW"

                      num="0">

 	    <code>java.lang.Thread.State.NEW</code>

 	  </constant>

 	  <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED"

                      num="JVMTI_THREAD_STATE_TERMINATED">

 	    <code>java.lang.Thread.State.TERMINATED</code>

 	  </constant>

 	  <constant id="JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE"

                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_RUNNABLE">

 	    <code>java.lang.Thread.State.RUNNABLE</code>

 	  </constant>

 	  <constant id="JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED"

                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER">

 	    <code>java.lang.Thread.State.BLOCKED</code>

 	  </constant>

 	  <constant id="JVMTI_JAVA_LANG_THREAD_STATE_WAITING"

                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_INDEFINITELY">

 	    <code>java.lang.Thread.State.WAITING</code>

 	  </constant>

 	  <constant id="JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING"

                      num="JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_WAITING | JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT">

 	    <code>java.lang.Thread.State.TIMED_WAITING</code>

 	  </constant>

 	</constants>

         <b>Rules</b>

         <p/>

         There can be no more than one answer to a question, although there can be no

         answer (because the answer is unknown, does not apply, or none of the answers is 

         correct).  An answer is set only when the enclosing answers match.

         That is, no more than one of

           <ul type="circle">

               <li><code>JVMTI_THREAD_STATE_RUNNABLE</code></li>

               <li><code>JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER</code></li>

               <li><code>JVMTI_THREAD_STATE_WAITING</code></li>

           </ul>

         can be set (a <tm>J2SE</tm> compliant implementation will always set

         one of these if <code>JVMTI_THREAD_STATE_ALIVE</code> is set). 

         And if any of these are set, the enclosing answer 

         <code>JVMTI_THREAD_STATE_ALIVE</code> is set. 

         No more than one of

           <ul type="circle">

               <li><code>JVMTI_THREAD_STATE_WAITING_INDEFINITELY</code></li>

               <li><code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code></li>

           </ul>

         can be set (a <tm>J2SE</tm> compliant implementation will always set

         one of these if <code>JVMTI_THREAD_STATE_WAITING</code> is set). 

         And if either is set, the enclosing answers 

         <code>JVMTI_THREAD_STATE_ALIVE</code> and 

         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 

         No more than one of

           <ul type="circle">

               <li><code>JVMTI_THREAD_STATE_IN_OBJECT_WAIT</code></li>

               <li><code>JVMTI_THREAD_STATE_PARKED</code></li>

               <li><code>JVMTI_THREAD_STATE_SLEEPING</code></li>

           </ul>

         can be set. And if any of these is set, the enclosing answers 

         <code>JVMTI_THREAD_STATE_ALIVE</code> and 

         <code>JVMTI_THREAD_STATE_WAITING</code> are set. 

         Also, if <code>JVMTI_THREAD_STATE_SLEEPING</code> is set,

         then <code>JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT</code> is set.

         If a state <i>A</i> is implemented using the mechanism of 

         state <i>B</i> then it is state <i>A</i> which 

         is returned by this function.

         For example, if <code>Thread.sleep(long)</code>

         is implemented using <code>Object.wait(long)</code>

         then it is still <code>JVMTI_THREAD_STATE_SLEEPING</code>

         which is returned.

         More than one of

           <ul type="circle">

               <li><code>JVMTI_THREAD_STATE_SUSPENDED</code></li>

               <li><code>JVMTI_THREAD_STATE_INTERRUPTED</code></li>

               <li><code>JVMTI_THREAD_STATE_IN_NATIVE</code></li>

           </ul>

         can be set, but if any is set,

         <code>JVMTI_THREAD_STATE_ALIVE</code> is set.

         <p/>

         And finally,

         <code>JVMTI_THREAD_STATE_TERMINATED</code> cannot be set unless

         <code>JVMTI_THREAD_STATE_ALIVE</code> is not set.  

         <p/>

         The thread state representation is designed for extension in future versions

         of the specification; thread state values should be used accordingly, that is

         they should not be used as ordinals.  

         Most queries can be made by testing a single bit, if use in a switch statement is desired,

         the state bits should be masked with the interesting bits.

         All bits not defined above are reserved for future use.  

         A VM, compliant to the current specification, must set reserved bits to zero.

         An agent should ignore reserved bits -- 

         they should not be assumed to be zero and thus should not be included in comparisons.

         <p/>

         <b>Examples</b>

         <p/>

         Note that the values below exclude reserved and vendor bits.

         <p/>

         The state of a thread blocked at a <code>synchronized</code>-statement would be:

         <example>

             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_BLOCKED_ON_MONITOR_ENTER

         </example>

         The state of a thread which hasn't started yet would be:

         <example>

             0

         </example>

         The state of a thread at a <code>Object.wait(3000)</code> would be:

         <example>

             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_WAITING + 

                 JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT + 

                 JVMTI_THREAD_STATE_MONITOR_WAITING

         </example>

         The state of a thread suspended while runnable would be:

         <example>

             JVMTI_THREAD_STATE_ALIVE + JVMTI_THREAD_STATE_RUNNABLE + JVMTI_THREAD_STATE_SUSPENDED

         </example>

         <p/>

         <b>Testing the State</b>

         <p/>

         In most cases, the thread state can be determined by testing the one bit corresponding

         to that question.  For example, the code to test if a thread is sleeping:

         <example>

 	jint state;

 	jvmtiError err;

 	err = (*jvmti)->GetThreadState(jvmti, thread, &state);

 	if (err == JVMTI_ERROR_NONE) {

 	   if (state & JVMTI_THREAD_STATE_SLEEPING) {  ...

         </example>

         <p/>

         For waiting (that is, in <code>Object.wait</code>, parked, or sleeping) it would be:

         <example>

 	   if (state & JVMTI_THREAD_STATE_WAITING) {  ...

         </example>

         For some states, more than one bit will need to be tested as is the case

         when testing if a thread has not yet been started:

         <example>

 	   if ((state & (JVMTI_THREAD_STATE_ALIVE | JVMTI_THREAD_STATE_TERMINATED)) == 0)  {  ...

         </example>

         To distinguish timed from untimed <code>Object.wait</code>:

         <example>

 	   if (state & JVMTI_THREAD_STATE_IN_OBJECT_WAIT)  {  

              if (state & JVMTI_THREAD_STATE_WAITING_WITH_TIMEOUT)  {

                printf("in Object.wait(long timeout)\n");

              } else {

                printf("in Object.wait()\n");

              }

            }

         </example>

         <p/>

         <b>Relationship to <code>java.lang.Thread.State</code></b>

         <p/>

         The thread state represented by <code>java.lang.Thread.State</code>

         returned from <code>java.lang.Thread.getState()</code> is a subset of the

         information returned from this function.  

         The corresponding <code>java.lang.Thread.State</code> can be determined

         by using the provided conversion masks.

         For example, this returns the name of the <code>java.lang.Thread.State</code> thread state:

         <example>

 	    err = (*jvmti)->GetThreadState(jvmti, thread, &state);

 	    abortOnError(err);

             switch (state & JVMTI_JAVA_LANG_THREAD_STATE_MASK) {

             case JVMTI_JAVA_LANG_THREAD_STATE_NEW:

               return "NEW";

             case JVMTI_JAVA_LANG_THREAD_STATE_TERMINATED:

               return "TERMINATED";

             case JVMTI_JAVA_LANG_THREAD_STATE_RUNNABLE:

               return "RUNNABLE";

             case JVMTI_JAVA_LANG_THREAD_STATE_BLOCKED:

               return "BLOCKED";

             case JVMTI_JAVA_LANG_THREAD_STATE_WAITING:

               return "WAITING";

             case JVMTI_JAVA_LANG_THREAD_STATE_TIMED_WAITING:

               return "TIMED_WAITING";

             }

         </example>

       </description>

       <origin>new</origin>

       <capabilities>

       </capabilities>

       <parameters>

 	<param id="thread">

 	  <jthread null="current" started="maybe" impl="noconvert"/>

 	    <description>

 	      The thread to query. 

 	    </description>

 	</param>

 	<param id="thread_state_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    On return, points to state flags,

 	    as defined by the <internallink id="jvmtiThreadState">Thread State Flags</internallink>.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetCurrentThread" phase="start" num="18" since="1.1">

       <synopsis>Get Current Thread</synopsis>

       <description>

         Get the current thread.  

         The current thread is the Java programming language thread which has called the function.

         <p/>

         Note that most <jvmti/> functions that take a thread 

         as an argument will accept <code>NULL</code> to mean 

         the current thread.

       </description>

       <origin>new</origin>

       <capabilities>

       </capabilities>

       <parameters>

         <param id="thread_ptr">

 	  <outptr><jthread/></outptr>

 	  <description>

 	     On return, points to the current thread.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetAllThreads" num="4">

       <synopsis>Get All Threads</synopsis>

       <description>

         Get all live threads.

         The threads are Java programming language threads;

         that is, threads that are attached to the VM.

         A thread is live if <code>java.lang.Thread.isAlive()</code> 

         would return <code>true</code>, that is, the thread has

         been started and has not yet died.

         The universe of threads is determined by the context of the <jvmti/>

         environment, which typically is all threads attached to the VM.

         Note that this includes <jvmti/> agent threads 

         (see <functionlink id="RunAgentThread"/>).

       </description>

       <origin>jvmdi</origin>

       <capabilities>

       </capabilities>

       <parameters>

         <param id="threads_count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    On return, points to the number of running threads.

 	  </description>

 	</param>

         <param id="threads_ptr">

 	  <allocbuf outcount="threads_count_ptr"><jthread/></allocbuf>

 	    <description>

 	      On return, points to an array of references, one

 	      for each running thread.

 	    </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="SuspendThread" num="5">

       <synopsis>Suspend Thread</synopsis>

       <description>

         Suspend the specified thread. If the calling thread is specified, 

         this function will not return until some other thread calls 

         <functionlink id="ResumeThread"></functionlink>.

         If the thread is currently suspended, this function

         does nothing and returns an error.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

         <required id="can_suspend"></required>

       </capabilities>

       <parameters>

         <param id="thread">

 	  <jthread null="current"/>

 	    <description>

 	      The thread to suspend. 

 	    </description>

 	</param>

       </parameters>

       <errors>

         <error id="JVMTI_ERROR_THREAD_SUSPENDED">

           Thread already suspended.

         </error>

       </errors>

     </function>

     <elide>

     <function id="SuspendAllThreads" num="101">

       <synopsis>Suspend All Threads</synopsis>

       <description>

 	<issue>

 	    There has been no explicit call for this function, and it will

 	    thus be removed if there is no interest.

         </issue>

         Suspend all live threads except:

         <ul>

           <li>already suspended threads</li>

           <li>those listed in <paramlink id="except_list"></paramlink></li>

           <li>certain system (non application) threads, as determined

             by the VM implementation</li>

         </ul>

         The threads are Java programming language threads;

         native threads which are not attached to the VM are not

         Java programming language threads.

         A thread is live if <code>java.lang.Thread.isAlive()</code> 

         would return <code>true</code>, that is, the thread has

         been started and has not yet died.

         The universe of threads is determined 

         by the context of the <jvmti/>

         environment, which, typically, is all threads attached to the VM,

         except critical VM internal threads and <jvmti/> agent threads 

 	(see <functionlink id="RunAgentThread"/>).

         <p/>

         If the calling thread is specified, 

         all other threads are suspended first then the caller thread is suspended -

         this function will not return until some other thread calls 

         <functionlink id="ResumeThread"></functionlink>.

         <p/>

         The list of actually

         suspended threads is returned in 

         <paramlink id="suspended_list_ptr"></paramlink>.

         Suspension is as defined in <functionlink id="SuspendThread"></functionlink>.

         <functionlink id="ResumeThreadList"></functionlink>

         can be used to resume the suspended threads.

       </description>

       <origin>new</origin>

       <capabilities>

         <required id="can_suspend"></required>

       </capabilities>

       <parameters>

         <param id="except_count">

 	  <jint min="0"/>

 	  <description>

 	    The number of threads in the list of threads not to be suspended.

 	  </description>

 	</param>

         <param id="except_list">

             <inbuf incount="except_count">

               <jthread/>

               <nullok>not an error if <code>except_count == 0</code></nullok>

             </inbuf>

 	    <description>

 	      The list of threads not to be suspended.

 	    </description>

 	</param>

         <param id="suspended_count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    On return, points to the number of threads suspended by this call.

 	  </description>

 	</param>

         <param id="suspended_list_ptr">

 	  <allocbuf outcount="suspended_count_ptr"><jthread/></allocbuf>

 	    <description>

 	      On return, points to an array of references, one

 	      for each thread suspended.

 	    </description>

 	</param>

       </parameters>

       <errors>

         <error id="JVMTI_ERROR_INVALID_THREAD">

           A thread in <paramlink id="except_list"></paramlink> was invalid.

         </error>

         <error id="JVMTI_ERROR_NULL_POINTER">

           Both <paramlink id="except_list"></paramlink> was <code>NULL</code>

           and <paramlink id="except_count"></paramlink> was non-zero.

         </error>

       </errors>

     </function>

     </elide>

     <function id="SuspendThreadList" num="92">

       <synopsis>Suspend Thread List</synopsis>

       <description>

         Suspend the <paramlink id="request_count"></paramlink> 

         threads specified in the 

         <paramlink id="request_list"></paramlink> array. 

         Threads may be resumed with

         <functionlink id="ResumeThreadList"></functionlink> or

         <functionlink id="ResumeThread"></functionlink>.

         If the calling thread is specified in the 

         <paramlink id="request_list"></paramlink> array, this function will

         not return until some other thread resumes it.

         Errors encountered in the suspension of a thread

         are returned in the <paramlink id="results"></paramlink>

         array, <b>not</b> in the return value of this function.

         Threads that are currently suspended do not change state.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

         <required id="can_suspend"></required>

       </capabilities>

       <parameters>

         <param id="request_count">

 	  <jint min="0"/>

 	  <description>

 	    The number of threads to suspend.

 	  </description>

 	</param>

         <param id="request_list">

 	  <inbuf incount="request_count"><jthread/></inbuf>

 	    <description>

 	      The list of threads to suspend.

 	    </description>

 	</param>

         <param id="results">

 	  <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>

 	  <description>

 	    An agent supplied array of 

 	    <paramlink id="request_count"></paramlink> elements.

 	    On return, filled with the error code for

 	    the suspend of the corresponding thread.

 	    The error code will be 

 	    <errorlink id="JVMTI_ERROR_NONE"></errorlink>

 	    if the thread was suspended by this call.

 	    Possible error codes are those specified

 	    for <functionlink id="SuspendThread"></functionlink>.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="ResumeThread" num="6">

       <synopsis>Resume Thread</synopsis>

       <description>

         Resume a suspended thread. 

         Any threads currently suspended through

         a <jvmti/> suspend function (eg.

         <functionlink id="SuspendThread"></functionlink>) 

         or <code>java.lang.Thread.suspend()</code>

         will resume execution;  

 	all other threads are unaffected.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

         <required id="can_suspend"></required>

       </capabilities>

       <parameters>

         <param id="thread">

 	  <jthread/>

 	    <description>

 	      The thread to resume.

 	    </description>

 	</param>

       </parameters>

       <errors>

         <error id="JVMTI_ERROR_THREAD_NOT_SUSPENDED">

           Thread was not suspended.

         </error>

         <error id="JVMTI_ERROR_INVALID_TYPESTATE">

           The state of the thread has been modified, and is now inconsistent. 

         </error>

       </errors>

     </function>

     <function id="ResumeThreadList" num="93">

       <synopsis>Resume Thread List</synopsis>

       <description>

         Resume the <paramlink id="request_count"></paramlink> 

         threads specified in the 

         <paramlink id="request_list"></paramlink> array. 

         Any thread suspended through

         a <jvmti/> suspend function (eg.

         <functionlink id="SuspendThreadList"></functionlink>) 

         or <code>java.lang.Thread.suspend()</code>

         will resume execution.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

         <required id="can_suspend"></required>

       </capabilities>

       <parameters>

         <param id="request_count">

 	  <jint min="0"/>

 	  <description>

 	    The number of threads to resume.

 	  </description>

 	</param>

         <param id="request_list">

 	  <inbuf incount="request_count"><jthread/></inbuf>

 	    <description>

 	      The threads to resume.

 	    </description>

 	</param>

         <param id="results">

 	  <outbuf incount="request_count"><enum>jvmtiError</enum></outbuf>

 	  <description>

 	    An agent supplied array of 

 	    <paramlink id="request_count"></paramlink> elements.

 	    On return, filled with the error code for

 	    the resume of the corresponding thread.

 	    The error code will be 

 	    <errorlink id="JVMTI_ERROR_NONE"></errorlink>

 	    if the thread was suspended by this call.

 	    Possible error codes are those specified

 	    for <functionlink id="ResumeThread"></functionlink>.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="StopThread" num="7">

       <synopsis>Stop Thread</synopsis>

       <description>

 	Send the specified asynchronous exception to the specified thread 

 	(similar to <code>java.lang.Thread.stop</code>).

 	Normally, this function is used to kill the specified thread with an 

 	instance of the exception <code>ThreadDeath</code>.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

 	<required id="can_signal_thread"></required>

       </capabilities>

       <parameters>

 	<param id="thread">

 	  <jthread/>

 	    <description>

 	      The thread to stop.

 	    </description>

 	</param>

 	<param id="exception">

 	  <jobject/>

 	    <description>

 	      The asynchronous exception object.

 	    </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="InterruptThread" num="8">

       <synopsis>Interrupt Thread</synopsis>

       <description>

 	Interrupt the specified thread

 	(similar to <code>java.lang.Thread.interrupt</code>).

       </description>

       <origin>jvmdi</origin>

       <capabilities>

 	<required id="can_signal_thread"></required>

       </capabilities>

       <parameters>

 	<param id="thread">

 	  <jthread impl="noconvert"/>

 	    <description>

 	      The thread to interrupt.

 	    </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetThreadInfo" num="9">

       <synopsis>Get Thread Info</synopsis>

       <typedef id="jvmtiThreadInfo" label="Thread information structure">

 	<field id="name">

 	  <allocfieldbuf><char/></allocfieldbuf>

 	  <description>

 	    The thread name, encoded as a

 	    <internallink id="mUTF">modified UTF-8</internallink> string.

 	  </description>

 	</field>

 	<field id="priority">

 	  <jint/>

 	  <description>

 	    The thread priority.  See the thread priority constants:

 	    <datalink id="jvmtiThreadPriority"></datalink>.

 	  </description>

 	</field>

 	<field id="is_daemon">

 	  <jboolean/>

 	  <description>

 	    Is this a daemon thread?

 	  </description>

 	</field>

 	<field id="thread_group">

 	  <jthreadGroup/>

 	  <description>

 	    The thread group to which this thread belongs.

             <code>NULL</code> if the thread has died.

 	  </description>

 	</field>

 	<field id="context_class_loader">

 	  <jobject/>

 	    <description>

 	      The context class loader associated with this thread.

 	    </description>

 	</field>

       </typedef>

       <description>

 	Get thread information. The fields of the <datalink id="jvmtiThreadInfo"/> structure 

 	are filled in with details of the specified thread.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

       </capabilities>

       <parameters>

 	<param id="thread">

 	  <jthread null="current" impl="noconvert" started="maybe"/>

 	    <description>

 	      The thread to query.

 	    </description>

 	</param>

 	<param id="info_ptr">

 	  <outptr><struct>jvmtiThreadInfo</struct></outptr>

 	  <description>

 	    On return, filled with information describing the specified thread.

 	    <p/>

 	    For JDK 1.1 implementations that don't

 	    recognize context class loaders, 

 	    the <code>context_class_loader</code> field will be NULL.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetOwnedMonitorInfo" num="10">

       <synopsis>Get Owned Monitor Info</synopsis>

       <description>

 	Get information about the monitors owned by the 

 	specified thread. 

       </description>

       <origin>jvmdiClone</origin>

       <capabilities>

 	<required id="can_get_owned_monitor_info"></required>

       </capabilities>

       <parameters>

 	<param id="thread">

 	  <jthread null="current"/>

 	    <description>

 	      The thread to query.

 	    </description>

 	</param>

 	<param id="owned_monitor_count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    The number of monitors returned.

 	  </description>

 	</param>

 	<param id="owned_monitors_ptr">

 	  <allocbuf outcount="owned_monitor_count_ptr"><jobject/></allocbuf>

 	    <description>

 	      The array of owned monitors.

 	    </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetOwnedMonitorStackDepthInfo" num="153" since="1.1">

       <synopsis>Get Owned Monitor Stack Depth Info</synopsis>

       <typedef id="jvmtiMonitorStackDepthInfo" 

                label="Monitor stack depth information structure">

         <field id="monitor">

 	  <jobject/>

 	    <description>

 	      The owned monitor.

 	    </description>

 	</field>

         <field id="stack_depth">

 	  <jint/>

 	  <description>

 	    The stack depth.  Corresponds to the stack depth used in the 

             <internallink id="stack">Stack Frame functions</internallink>.

             That is, zero is the current frame, one is the frame which

             called the current frame. And it is negative one if the 

 	    implementation cannot determine the stack depth (e.g., for 

 	    monitors acquired by JNI <code>MonitorEnter</code>).

 	  </description>

 	</field>

       </typedef>

       <description>

 	Get information about the monitors owned by the 

 	specified thread and the depth of the stack frame which locked them. 

       </description>

       <origin>new</origin>

       <capabilities>

 	<required id="can_get_owned_monitor_stack_depth_info"></required>

       </capabilities>

       <parameters>

 	<param id="thread">

 	  <jthread null="current"/>

 	    <description>

 	      The thread to query.

 	    </description>

 	</param>

 	<param id="monitor_info_count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    The number of monitors returned.

 	  </description>

 	</param>

 	<param id="monitor_info_ptr">

 	  <allocbuf outcount="owned_monitor_depth_count_ptr">

             <struct>jvmtiMonitorStackDepthInfo</struct>

           </allocbuf>

 	  <description>

 	    The array of owned monitor depth information.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetCurrentContendedMonitor" num="11">

       <synopsis>Get Current Contended Monitor</synopsis>

       <description>

 	Get the object, if any, whose monitor the specified thread is waiting to 

 	enter or waiting to regain through <code>java.lang.Object.wait</code>.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

 	<required id="can_get_current_contended_monitor"></required>

       </capabilities>

       <parameters>

 	<param id="thread">

 	  <jthread null="current"/>

 	    <description>

 	      The thread to query.

 	    </description>

 	</param>

 	<param id="monitor_ptr">

 	  <outptr><jobject/></outptr>

 	    <description>

 	      On return, filled with the current contended monitor, or

 	      NULL if there is none.

 	    </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <callback id="jvmtiStartFunction">

       <void/>

       <synopsis>Agent Start Function</synopsis>

       <description>

         Agent supplied callback function.

         This function is the entry point for an agent thread

 	started with

 	<functionlink id="RunAgentThread"></functionlink>.

       </description>

       <parameters>

 	  <param id="jvmti_env">

 	    <outptr>

 	      <struct>jvmtiEnv</struct>

 	    </outptr>

 	    <description>

 	      The <jvmti/> environment.

 	    </description>

 	  </param>

           <param id="jni_env">

             <outptr>

               <struct>JNIEnv</struct>

             </outptr>

             <description>

               The JNI environment.

             </description>

           </param>

           <param id="arg">

             <outptr>

               <void/>

             </outptr>

               <description>

                 The <code>arg</code> parameter passed to 

                 <functionlink id="RunAgentThread"></functionlink>.

               </description>

           </param>

       </parameters>

     </callback>

     <function id="RunAgentThread" num="12">

       <synopsis>Run Agent Thread</synopsis>

       <description>

 	Starts the execution of an agent thread. with the specified native function.

 	The parameter <paramlink id="arg"></paramlink> is forwarded on to the

 	<functionlink id="jvmtiStartFunction">start function</functionlink>

 	(specified with <paramlink id="proc"></paramlink>) as its single argument.

 	This function allows the creation of agent threads 

 	for handling communication with another process or for handling events 

 	without the need to load a special subclass of <code>java.lang.Thread</code> or 

 	implementer of <code>java.lang.Runnable</code>. 

 	Instead, the created thread can run entirely in native code.

 	However, the created thread does require a newly created instance

 	of <code>java.lang.Thread</code> (referenced by the argument <code>thread</code>) to 

 	which it will be associated.

 	The thread object can be created with JNI calls.

 	<p/>

 	The following common thread priorities are provided for your convenience:

 	<constants id="jvmtiThreadPriority" label="Thread Priority Constants" kind="const">

 	  <constant id="JVMTI_THREAD_MIN_PRIORITY" num="1">

 	    Minimum possible thread priority

 	  </constant>

 	  <constant id="JVMTI_THREAD_NORM_PRIORITY" num="5">

 	    Normal thread priority

 	  </constant>

 	  <constant id="JVMTI_THREAD_MAX_PRIORITY" num="10">

 	    Maximum possible thread priority

 	  </constant>

 	</constants>

 	<p/>

 	The new thread is started as a daemon thread with the specified

 	<paramlink id="priority"></paramlink>.

         If enabled, a <eventlink id="ThreadStart"/> event will be sent.

 	<p/>

         Since the thread has been started, the thread will be live when this function

         returns, unless the thread has died immediately.

 	<p/>

         The thread group of the thread is ignored -- specifically, the thread is not

         added to the thread group and the thread is not seen on queries of the thread

         group at either the Java programming language or <jvmti/> levels.

 	<p/>

         The thread is not visible to Java programming language queries but is 

         included in <jvmti/> queries (for example, 

         <functionlink id="GetAllThreads"/> and

         <functionlink id="GetAllStackTraces"/>).

 	<p/>

 	Upon execution of <code>proc</code>, the new thread will be attached to the

 	VM--see the JNI documentation on 

 	<externallink id="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#wp1060"

 		      >Attaching to the VM</externallink>.

       </description>

       <origin>jvmdiClone</origin>

       <capabilities>

       </capabilities>

       <parameters>

 	<param id="thread">

 	  <jthread impl="noconvert" started="no"/>

 	    <description>

 	      The thread to run.

 	    </description>

 	</param>

 	<param id="proc">

 	  <ptrtype>

 	    <struct>jvmtiStartFunction</struct>

 	  </ptrtype>

 	  <description>

 	    The start function.

 	  </description>

 	</param>

 	<param id="arg">

 	  <inbuf>

             <void/>

             <nullok><code>NULL</code> is passed to the start function</nullok>

           </inbuf>

 	  <description>

 	    The argument to the start function.

 	  </description>

 	</param>

 	<param id="priority">

 	  <jint/>

 	  <description>

 	    The priority of the started thread. Any thread

 	    priority allowed by <code>java.lang.Thread.setPriority</code> can be used including

 	    those in <datalink id="jvmtiThreadPriority"></datalink>.

 	  </description>

 	</param>

       </parameters>

       <errors>

 	<error id="JVMTI_ERROR_INVALID_PRIORITY"> 

             <paramlink id="priority"/> is less than 

             <datalink id="JVMTI_THREAD_MIN_PRIORITY"/>

               or greater than

             <datalink id="JVMTI_THREAD_MAX_PRIORITY"/>

 	</error>

       </errors>

     </function>

     <function id="SetThreadLocalStorage" jkernel="yes" impl="notrace" phase="start" num="103">

       <synopsis>Set Thread Local Storage</synopsis>

       <description>

 	The VM stores a pointer value associated with each environment-thread

 	pair. This pointer value is called <i>thread-local storage</i>.

         This value is <code>NULL</code> unless set with this function.

 	Agents can allocate memory in which they store thread specific

         information. By setting thread-local storage it can then be

 	accessed with 

 	<functionlink id="GetThreadLocalStorage"></functionlink>.

 	<p/>

         This function is called by the agent to set the value of the <jvmti/>

         thread-local storage. <jvmti/> supplies to the agent a pointer-size

         thread-local storage that can be used to record per-thread

         information.

       </description>

       <origin>jvmpi</origin>

       <capabilities>

       </capabilities>

       <parameters>

         <param id="thread">

 	  <jthread null="current"/>

 	    <description>

 	      Store to this thread.

 	    </description>

 	</param>

         <param id="data">

 	  <inbuf> 

 	    <void/> 

 	    <nullok>value is set to <code>NULL</code></nullok> 

 	  </inbuf> 

 	  <description>

 	    The value to be entered into the thread-local storage.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetThreadLocalStorage" jkernel="yes" impl="innative notrace" phase="start" num="102">

       <synopsis>Get Thread Local Storage</synopsis>

       <description>

         Called by the agent to get the value of the <jvmti/> thread-local

         storage. 

       </description>

       <origin>jvmpi</origin>

       <capabilities>

       </capabilities>

       <parameters>

         <param id="thread">

 	  <jthread null="current" impl="noconvert"/>

 	    <description>

 	      Retrieve from this thread.

 	    </description>

 	</param>

         <param id="data_ptr">

 	  <agentbuf><void/></agentbuf>

 	  <description>

 	    Pointer through which the value of the thread local 

 	    storage is returned.

 	    If thread-local storage has not been set with

 	    <functionlink id="SetThreadLocalStorage"></functionlink> the returned 

 	    pointer is <code>NULL</code>.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

   </category>

   <category id="thread_groups" label="Thread Group">

     <intro>

     </intro>

     <function id="GetTopThreadGroups" num="13">

       <synopsis>Get Top Thread Groups</synopsis>

       <description>

 	Return all top-level (parentless) thread groups in the VM.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

       </capabilities>

       <parameters>

 	<param id="group_count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    On return, points to the number of top-level thread groups.

 	  </description>

 	</param>

 	<param id="groups_ptr">

 	  <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>

 	    <description>

 	      On return, refers to a pointer to the top-level thread group array.

 	    </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetThreadGroupInfo" num="14">

       <synopsis>Get Thread Group Info</synopsis>

       <typedef id="jvmtiThreadGroupInfo" label="Thread group information structure">

 	<field id="parent">

 	  <jthreadGroup/>

 	  <description>

 	    The parent thread group.

 	  </description>

 	</field>

 	<field id="name">

 	  <allocfieldbuf><char/></allocfieldbuf>

 	  <description>

 	    The thread group's name, encoded as a

 	    <internallink id="mUTF">modified UTF-8</internallink> string.

 	  </description>

 	</field>

 	<field id="max_priority">

 	  <jint/>

 	  <description>

 	    The maximum priority for this thread group.

 	  </description>

 	</field>

 	<field id="is_daemon">

 	  <jboolean/>

 	  <description>

 	    Is this a daemon thread group?

 	  </description>

 	</field>

       </typedef>

       <description>

 	Get information about the thread group. The fields of the 

 	<functionlink id="jvmtiThreadGroupInfo"></functionlink> structure 

 	are filled in with details of the specified thread group.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

       </capabilities>

       <parameters>

 	<param id="group">

 	  <jthreadGroup/>

 	  <description>

 	    The thread group to query.

 	  </description>

 	</param>

 	<param id="info_ptr">

 	  <outptr><struct>jvmtiThreadGroupInfo</struct></outptr>

 	  <description>

 	    On return, filled with information describing the specified

 	    thread group. 

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetThreadGroupChildren" num="15">

       <synopsis>Get Thread Group Children</synopsis>

       <description>

 	Get the live threads and active subgroups in this thread group.

       </description>

       <origin>jvmdi</origin>

       <capabilities>

       </capabilities>

       <parameters>

 	<param id="group">

 	  <jthreadGroup/>

 	  <description>

 	    The group to query.

 	  </description>

 	</param>

 	<param id="thread_count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    On return, points to the number of live threads in this thread group.

 	  </description>

 	</param>

 	<param id="threads_ptr">

 	  <allocbuf outcount="thread_count_ptr"><jthread/></allocbuf>

 	    <description>

 	      On return, points to an array of the live threads in this thread group.

 	    </description>

 	</param>

 	<param id="group_count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    On return, points to the number of active child thread groups

 	  </description>

 	</param>

 	<param id="groups_ptr">

 	  <allocbuf outcount="group_count_ptr"><jthreadGroup/></allocbuf>

 	    <description>

 	      On return, points to an array of the active child thread groups.

 	    </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

   </category>

   <category id="stack" label="Stack Frame">

     <intro>

         These functions provide information about the stack of a thread.

         Stack frames are referenced by depth.

         The frame at depth zero is the current frame.

         <p/>

         Stack frames are as described in the 

         <vmspeclink id="Overview.doc.html#17257"

                     name="Frames section"/>.  

         That is, they correspond to method 

         invocations (including native methods) but do not correspond to platform native or 

         VM internal frames.

         <p/>

         A <jvmti/> implementation may use method invocations to launch a thread and

         the corresponding frames may be included in the stack as presented by these functions --

         that is, there may be frames shown

         deeper than <code>main()</code> and <code>run()</code>.

         However this presentation must be consistent across all <jvmti/> functionality which 

         uses stack frames or stack depth.

     </intro>

       <typedef id="jvmtiFrameInfo" label="Stack frame information structure">

         <description>

           Information about a stack frame is returned in this structure.

         </description>

         <field id="method">

 	  <jmethodID/>

 	    <description>

 	      The method executing in this frame.

 	    </description>

 	</field>

         <field id="location">

 	  <jlocation/>

 	  <description>

 	    The index of the instruction executing in this frame.

             <code>-1</code> if the frame is executing a native method.

 	  </description>

 	</field>

       </typedef>

       <typedef id="jvmtiStackInfo" label="Stack information structure">

         <description>

           Information about a set of stack frames is returned in this structure.

         </description>

         <field id="thread">

 	  <jthread/>

 	  <description>

 	    On return, the thread traced.

 	  </description>

 	</field>

         <field id="state">

 	  <jint/>

 	  <description>

 	    On return, the thread state. See <functionlink id="GetThreadState"></functionlink>.

 	  </description>

 	</field>

         <field id="frame_buffer">

 	  <outbuf incount="max_frame_count">

 	    <struct>jvmtiFrameInfo</struct>

 	  </outbuf>

 	    <description>

 	      On return, this agent allocated buffer is filled 

 	      with stack frame information.  

 	    </description>

 	</field>

         <field id="frame_count">

 	  <jint/>

 	  <description>

 	    On return, the number of records filled into 

             <code>frame_buffer</code>.

             This will be 

             min(<code>max_frame_count</code>, <i>stackDepth</i>).

 	  </description>

 	</field>

       </typedef>

     <function id="GetStackTrace" num="104">

       <synopsis>Get Stack Trace</synopsis>

       <description>

         Get information about the stack of a thread.

         If <paramlink id="max_frame_count"></paramlink> is less than the depth of the stack,

         the <paramlink id="max_frame_count"></paramlink> topmost frames are returned, 

         otherwise the entire stack is returned.

         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.

         <p/>

         The following example causes up to five of the topmost frames

         to be returned and (if there are any frames) the currently

         executing method name to be printed.

         <example>

 jvmtiFrameInfo frames[5];

 jint count;

 jvmtiError err;

 err = (*jvmti)->GetStackTrace(jvmti, aThread, 0, 5, 

                                &frames, &count);

 if (err == JVMTI_ERROR_NONE && count >= 1) {

    char *methodName;

    err = (*jvmti)->GetMethodName(jvmti, frames[0].method, 

                        &methodName, NULL);

    if (err == JVMTI_ERROR_NONE) {

       printf("Executing method: %s", methodName);

    }

 }

         </example>

         <todo> 

           check example code.

         </todo>

         <p/>

         The <paramlink id="thread"></paramlink> need not be suspended

         to call this function.  

         <p/>

         The <functionlink id="GetLineNumberTable"></functionlink>

         function can be used to map locations to line numbers. Note that

         this mapping can be done lazily.

       </description>

       <origin>jvmpi</origin>

       <capabilities>

       </capabilities>

       <parameters>

         <param id="thread">

 	  <jthread null="current"/>

 	    <description>

 	      Fetch the stack trace of this thread.

 	    </description>

 	</param>

         <param id="start_depth">

 	  <jint/>

 	  <description>

 	    Begin retrieving frames at this depth.  

             If non-negative, count from the current frame, 

             the first frame retrieved is at depth <code>start_depth</code>.  

             For example, if zero, start from the current frame; if one, start from the

             caller of the current frame; if two, start from the caller of the

             caller of the current frame; and so on.

             If negative, count from below the oldest frame,

             the first frame retrieved is at depth <i>stackDepth</i><code> + start_depth</code>,  

             where <i>stackDepth</i> is the count of frames on the stack.  

             For example, if negative one, only the oldest frame is retrieved;

             if negative two, start from the frame called by the oldest frame.

 	  </description>

 	</param>

         <param id="max_frame_count">

 	  <jint min="0"/>

 	  <description>

 	    The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.

 	  </description>

 	</param>

         <param id="frame_buffer">

 	  <outbuf incount="max_frame_count" outcount="count_ptr">

 	    <struct>jvmtiFrameInfo</struct>

 	  </outbuf>

 	    <description>

 	      On return, this agent allocated buffer is filled 

 	      with stack frame information.  

 	    </description>

 	</param>

         <param id="count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    On return, points to the number of records filled in.

             For non-negative <code>start_depth</code>, this will be 

             min(<code>max_frame_count</code>, <i>stackDepth</i><code> - start_depth</code>).

             For negative <code>start_depth</code>, this will be 

             min(<code>max_frame_count</code>, <code>-start_depth</code>).

 	  </description>

 	</param>

       </parameters>

       <errors>

 	<error id="JVMTI_ERROR_ILLEGAL_ARGUMENT">

 	  <paramlink id="start_depth"/> is positive and greater than or equal to <i>stackDepth</i>.

 	  Or <paramlink id="start_depth"/> is negative and less than <i>-stackDepth</i>.

 	</error>

       </errors>

     </function>

     <function id="GetAllStackTraces" num="100">

       <synopsis>Get All Stack Traces</synopsis>

       <description>

         Get information about the stacks of all live threads

         (including <internallink id="RunAgentThread">agent threads</internallink>).

         If <paramlink id="max_frame_count"/> is less than the depth of a stack,

         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 

         otherwise the entire stack is returned.

         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.

         <p/>

         All stacks are collected simultaneously, that is, no changes will occur to the 

         thread state or stacks between the sampling of one thread and the next.

         The threads need not be suspended.

         <example>

 jvmtiStackInfo *stack_info;

 jint thread_count;

 int ti;

 jvmtiError err;

 err = (*jvmti)->GetAllStackTraces(jvmti, MAX_FRAMES, &stack_info, &thread_count); 

 if (err != JVMTI_ERROR_NONE) {

    ...   

 }

 for (ti = 0; ti < thread_count; ++ti) {

    jvmtiStackInfo *infop = &stack_info[ti];

    jthread thread = infop->thread;

    jint state = infop->state;

    jvmtiFrameInfo *frames = infop->frame_buffer;

    int fi;

    myThreadAndStatePrinter(thread, state);

    for (fi = 0; fi < infop->frame_count; fi++) {

       myFramePrinter(frames[fi].method, frames[fi].location);

    }

 }

 /* this one Deallocate call frees all data allocated by GetAllStackTraces */

 err = (*jvmti)->Deallocate(jvmti, stack_info); 

         </example>

         <todo> 

           check example code.

         </todo>

       </description>

       <origin>new</origin>

       <capabilities>

       </capabilities>

       <parameters>

         <param id="max_frame_count">

 	  <jint min="0"/>

 	  <description>

 	    The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.

 	  </description>

 	</param>

         <param id="stack_info_ptr">

 	  <allocbuf>

 	    <struct>jvmtiStackInfo</struct>

 	  </allocbuf>

 	    <description>

 	      On return, this buffer is filled 

 	      with stack information for each thread.  

               The number of <datalink id="jvmtiStackInfo"/> records is determined 

               by <paramlink id="thread_count_ptr"/>.

               <p/>

               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 

               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.

               These buffers must not be separately deallocated.

 	    </description>

 	</param>

         <param id="thread_count_ptr">

 	  <outptr><jint/></outptr>

 	  <description>

 	    The number of threads traced.

 	  </description>

 	</param>

       </parameters>

       <errors>

       </errors>

     </function>

     <function id="GetThreadListStackTraces" num="101">

       <synopsis>Get Thread List Stack Traces</synopsis>

       <description>

         Get information about the stacks of the supplied threads.

         If <paramlink id="max_frame_count"/> is less than the depth of a stack,

         the <paramlink id="max_frame_count"/> topmost frames are returned for that thread, 

         otherwise the entire stack is returned.

         The topmost frames, those most recently invoked, are at the beginning of the returned buffer.

         <p/>

         All stacks are collected simultaneously, that is, no changes will occur to the 

         thread state or stacks between the sampling one thread and the next.

         The threads need not be suspended.

         <p/>

         If a thread has not yet started or terminates before the stack information is collected,

         a zero length stack (<datalink id="jvmtiStackInfo.frame_count"/> will be zero)

         will be returned and the thread <datalink id="jvmtiStackInfo.state"/> can be checked.

         <p/>

         See the example for the similar function

         <functionlink id="GetAllStackTraces"/>.

       </description>

       <origin>new</origin>

       <capabilities>

       </capabilities>

       <parameters>

         <param id="thread_count">

 	  <jint min="0"/>

 	  <description>

 	    The number of threads to trace.

 	  </description>

 	</param>

         <param id="thread_list">

 	  <inbuf incount="thread_count"><jthread/></inbuf>

 	    <description>

 	      The list of threads to trace.

 	    </description>

 	</param>

         <param id="max_frame_count">

 	  <jint min="0"/>

 	  <description>

 	    The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve per thread.

 	  </description>

 	</param>

         <param id="stack_info_ptr">

 	  <allocbuf outcount="thread_count">

 	    <struct>jvmtiStackInfo</struct>

 	  </allocbuf>

 	    <description>

 	      On return, this buffer is filled 

 	      with stack information for each thread.  

               The number of <datalink id="jvmtiStackInfo"/> records is determined 

               by <paramlink id="thread_count"/>.

               <p/>

               Note that this buffer is allocated to include the <datalink id="jvmtiFrameInfo"/> 

               buffers pointed to by <datalink id="jvmtiStackInfo.frame_buffer"/>.

               These buffers must not be separately deallocated.

 	    </description>

 	</param>

       </parameters>

       <errors>

 	<error id="JVMTI_ERROR_INVALID_THREAD">

 	  An element in <paramlink id="thread_list"/> is not a thread object.

 	</error>

       </errors>

     </function>

     <elide>

     <function id="AsyncGetStackTrace" num="1000">

       <synopsis>Get Stack Trace--Asynchronous</synopsis>

       <description>

         Get information about the entire stack of a thread (or a sub-section of it).

         This is the asynchronous version of <functionlink id="GetStackTrace"></functionlink>

         and is reentrant and safe to call

         from asynchronous signal handlers.

         The stack trace is returned only for the calling thread.

         <p/>

         The <functionlink id="GetLineNumberTable"></functionlink>

         function can be used to map locations to line numbers. Note that

         this mapping can be done lazily.

       </description>

       <origin>jvmpi</origin>

       <capabilities>

         <required id="can_get_async_stack_trace"></required>

         <capability id="can_show_JVM_spec_async_frames">

           If <code>false</code>, 

           <paramlink id="use_java_stack"></paramlink> 

           must be <code>false</code>.

         </capability>

       </capabilities>

       <parameters>

         <param id="use_java_stack">

 	  <jboolean/>

 	  <description>

 	    Return the stack showing the <vmspeclink/>

 	    model of the stack; 

 	    otherwise, show the internal representation of the stack with

 	    inlined and optimized methods missing.  If the virtual machine

 	    is using the <i>Java Virtual Machine Specification</i> stack model

 	    internally, this flag is ignored.

 	  </description>

 	</param>

         <param id="max_count">

 	  <jint min="0"/>

 	  <description>

 	    The maximum number of <datalink id="jvmtiFrameInfo"/> records to retrieve.

 	    Retrieve this many unless the stack depth is less than <code>max_count</code>.

 	  </description>

 	</param>

         <param id="frame_buffer">

 	  <outbuf incount="max_count" outcount="count_ptr">