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

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

<!--

 Copyright (c) 2002, 2012, Oracle and/or its affiliates. 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 or visit www.oracle.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 vmspec EMPTY>

   <!ATTLIST vmspec chapter 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="2"

        microversion="2">

  <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://docs.oracle.com/javase/7/docs/technotes/guides/jpda/architecture.html">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