src/share/vm/prims/jvmti.xml

Print this page


   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
   3 <!--
   4  Copyright (c) 2002, 2012, Oracle and/or its affiliates. All rights reserved.
   5  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6 
   7  This code is free software; you can redistribute it and/or modify it
   8  under the terms of the GNU General Public License version 2 only, as
   9  published by the Free Software Foundation.
  10 
  11  This code is distributed in the hope that it will be useful, but WITHOUT
  12  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  version 2 for more details (a copy is included in the LICENSE file that
  15  accompanied this code).
  16 
  17  You should have received a copy of the GNU General Public License version
  18  2 along with this work; if not, write to the Free Software Foundation,
  19  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20 
  21  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  or visit www.oracle.com if you need additional information or have any
  23  questions.
  24   


 341 
 342    <!ELEMENT table  (tr)+>
 343 
 344    <!ELEMENT tr  (td|th)*>
 345 
 346    <!ELEMENT td  ANY>
 347    <!ATTLIST td align (left|right|center) "center">
 348 
 349    <!ELEMENT th  ANY>
 350    <!ATTLIST th align (left|right|center) "center">
 351 
 352    <!ELEMENT ul  (li)+>
 353    <!ATTLIST ul type (disc|circle|square) "disc">
 354 
 355    <!ELEMENT li  ANY>
 356  ]>
 357 
 358 <specification label="JVM(TM) Tool Interface"
 359         majorversion="1"
 360         minorversion="2"
 361         microversion="2">
 362   <title subtitle="Version">
 363     <tm>JVM</tm> Tool Interface
 364   </title>
 365   
 366   <intro id="whatIs" label="What is the JVM Tool Interface?">
 367     The <tm>JVM</tm> Tool Interface (<jvmti/>) 
 368     is a programming interface used by development and monitoring tools. 
 369     It provides both a way to inspect the state and 
 370     to control the execution of applications running in the
 371     <tm>Java</tm> virtual machine (VM).
 372     <p/>
 373     <jvmti/> is intended to provide a VM interface for the full breadth of tools
 374     that need access to VM state, including but not limited to: profiling,
 375     debugging, monitoring, thread analysis, and coverage analysis tools.
 376     <p/>
 377     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
 378     machine.
 379     <p/>
 380     <jvmti/> is a two-way interface. 
 381     A client of <jvmti/>, hereafter called an <i>agent</i>,


 414     language calling conventions and C or C++
 415     definitions.
 416     <p/>
 417     The function, event, data type, and constant definitions needed for
 418     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 419     To use these definitions add the <tm>J2SE</tm> include directory
 420     to your include path and add
 421     <example>
 422 #include &lt;jvmti.h&gt;
 423     </example>
 424     to your source code.
 425   </intro>
 426 
 427   <intro id="deployingAgents" label="Deploying Agents">
 428     An agent is deployed in a platform specific manner but is typically the 
 429     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating 
 430     system, for example, an agent library is a "Dynamic Linked Library" (DLL). 
 431     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
 432     object (<code>.so</code> file).
 433     <p/>

 434     An agent may be started at VM startup by specifying the agent library
 435     name using a <internallink id="starting">command line option</internallink>.
 436     Some implementations may support a mechanism to <internallink id="onattach"> 
 437     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
 438     The details of how this is initiated are implementation specific.
 439   </intro>
 440   

































 441   <intro id="starting" label="Agent Command Line Options">
 442     The term "command-line option" is used below to
 443     mean options supplied in the <code>JavaVMInitArgs</code> argument
 444     to the <code>JNI_CreateJavaVM</code> function of the JNI
 445     Invocation API.
 446     <p/>
 447     One of the two following 
 448     command-line options is used on VM startup to 
 449     properly load and run agents.
 450     These arguments identify the library containing 
 451     the agent as well as an options
 452     string to be passed in at startup. 
 453     <dl>
 454       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 455       <dd>
 456         The name following <code>-agentlib:</code> is the name of the
 457         library to load.  Lookup of the library, both its full name and location,
 458         proceeds in a platform-specific manner. 
 459         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
 460         operating system specific file name.
 461         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 462         For example, if the option 
 463         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to 
 464         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
 465         under <tm>Windows</tm> or <code>libfoo.so</code> from the 
 466         <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment.




 467       </dd>
 468       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 469       <dd>
 470         The path following <code>-agentpath:</code> is the absolute path from which
 471         to load the library.
 472         No library name expansion will occur.
 473         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 474         For example, if the option 
 475         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to 
 476         load the shared library <code>c:\myLibs\foo.dll</code>.



 477       </dd>
 478     </dl>
 479     The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 480     in the library will be invoked.






 481     <p/>
 482     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
 483     will be searched for JNI native method implementations to facilitate the
 484     use of Java programming language code in tools, as is needed for 
 485     <internallink id="bci">bytecode instrumentation</internallink>.
 486     <p/>
 487     The agent libraries will be searched after all other libraries have been
 488     searched (agents wishing to override or intercept the native method
 489     implementations of non-agent methods can use the
 490     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
 491     <p/>
 492     These switches do the above and nothing more - they do not change the 
 493     state of the VM or <jvmti/>.  No command line options are needed 
 494     to enable <jvmti/> 
 495     or aspects of <jvmti/>, this is handled programmatically
 496     by the use of 
 497     <internallink id="capability">capabilities</internallink>.
 498   </intro>
 499 
 500   <intro id="startup" label="Agent Start-Up">
 501     The VM starts each agent by invoking a start-up function.
 502     If the agent is started in the <code>OnLoad</code>
 503     <functionlink id="GetPhase">phase</functionlink> the function
 504     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 505     will be invoked.

 506     If the agent is started in the live
 507     <functionlink id="GetPhase">phase</functionlink> the function
 508     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
 509     will be invoked.

 510     Exactly one call to a start-up function is made per agent.  
 511   </intro>
 512 
 513   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
 514     If an agent is started during the <code>OnLoad</code> phase then its
 515     agent library must export a start-up function with the following prototype:
 516     <example>
 517 JNIEXPORT jint JNICALL 
 518 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>





 519     The VM will start the agent by calling this function.  
 520     It will be called early enough in VM initialization that:
 521     <ul>
 522       <li><functionlink id="SetSystemProperty">system properties</functionlink>
 523         may be set before they have been used in the start-up of the VM</li>
 524       <li>the full set of 
 525         <internallink id="capability">capabilities</internallink>
 526         is still available (note that capabilities that configure the VM
 527         may only be available at this time--see the 
 528         <internallink id="capability">Capability function section</internallink>)</li>
 529       <li>no bytecodes have executed</li>
 530       <li>no classes have been loaded</li>
 531       <li>no objects have been created</li>
 532     </ul>
 533     <p/>
 534     The VM will call the <code>Agent_OnLoad</code> function with

 535     <i>&lt;options&gt;</i> as the second argument - 
 536     that is, using the command-line option examples,
 537     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> 
 538     argument of <code>Agent_OnLoad</code>.
 539     The <code>options</code> argument is encoded as a
 540     <internallink id="mUTF">modified UTF-8</internallink> string.
 541     If <i>=&lt;options&gt;</i> is not specified, 
 542     a zero length string is passed to <code>options</code>.
 543     The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code>

 544     call.  If needed beyond this time the string or parts of the string must
 545     be copied.
 546     The period between when <code>Agent_OnLoad</code> is called and when it
 547     returns is called the <i>OnLoad phase</i>.
 548     Since the VM is not initialized during the OnLoad 
 549     <functionlink id="GetPhase">phase</functionlink>,
 550     the set of allowed operations 
 551     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
 552     functionality available at this time). 
 553     The agent can safely process the options and set 
 554     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once  
 555     the VM initialization event is received 
 556     (that is, the <eventlink id="VMInit">VMInit</eventlink> 
 557     callback is invoked), the agent
 558     can complete its initialization.
 559     <rationale>
 560       Early startup is required so that agents can set the desired capabilities,
 561       many of which must be set before the VM is initialized.
 562       In JVMDI, the -Xdebug command-line option provided 
 563       very coarse-grain control of capabilities. 
 564       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
 565       No reasonable command-line 
 566       option could provide the fine-grain of control required to balance needed capabilities vs
 567       performance impact.  
 568       Early startup is also needed so that agents can control the execution
 569       environment - modifying the file system and system properties to install
 570       their functionality.
 571     </rationale>
 572     <p/>
 573     The return value from <code>Agent_OnLoad</code> is used to indicate an error.

 574     Any value other than zero indicates an error and causes termination of the VM.
 575   </intro>
 576   
 577   <intro id="onattach" label="Agent Start-Up (Live phase)">
 578     A VM may support a mechanism that allows agents to be started in the VM during the live 
 579     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
 580     are implementation specific. For example, a tool may use some platform specific mechanism, 
 581     or implementation specific API, to attach to the running VM, and request it start a given
 582     agent.
 583     <p/>
 584     If an agent is started during the live phase then its agent library
 585     must export a start-up function 
 586     with the following prototype:
 587     <example>
 588 JNIEXPORT jint JNICALL 
 589 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>





 590     <p/>         
 591     The VM will start the agent by calling this function.  
 592     It will be called in the context of a thread
 593     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
 594     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
 595     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
 596     </internallink> string.
 597     If startup options were not provided, a zero length string is passed to 
 598     <code>options</code>. The lifespan of the <code>options</code> string is the 
 599     <code>Agent_OnAttach</code> call.  If needed beyond this time the string or parts of 
 600     the string must be copied.
 601     <p/>
 602     Note that some <internallink id="capability">capabilities</internallink> 
 603     may not be available in the live phase.
 604     <p/>
 605     The <code>Agent_OnAttach</code> function initializes the agent and returns a value
 606     to the VM to indicate if an error occurred. Any value other than zero indicates an error. 
 607     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes 
 608     some implementation specific action -- for example it might print an error to standard error, 
 609     or record the error in a system log.
 610   </intro>
 611 
 612   <intro id="onunload" label="Agent Shutdown">
 613     The library may optionally export a 
 614     shutdown function with the following prototype:
 615     <example>
 616 JNIEXPORT void JNICALL 
 617 Agent_OnUnload(JavaVM *vm)</example>





 618     This function will be called by the VM when the library is about to be unloaded.
 619     The library will be unloaded and this function will be called if some platform specific 

 620     mechanism causes the unload (an unload mechanism is not specified in this document)
 621     or the library is (in effect) unloaded by the termination of the VM whether through 
 622     normal termination or VM failure, including start-up failure.
 623     Uncontrolled shutdown is, of couse, an exception to this rule.
 624     Note the distinction between this function and the 
 625     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
 626     to be sent, the VM must have run at least to the point of initialization and a valid 
 627     <jvmti/> environment must exist which has set a callback for VMDeath
 628     and enabled the event
 629     None of these are required for <code>Agent_OnUnload</code> and this function

 630     is also called if the library is unloaded for other reasons.
 631     In the case that a VM Death event is sent, it will be sent before this 
 632     function is called (assuming this function is called due to VM termination).
 633     This function can be used to clean-up resources allocated by the agent.
 634   </intro>
 635 
 636   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
 637     Since the command-line cannot always be accessed or modified, for example in embedded VMs
 638     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
 639     provided so that agents may be launched in these cases.
 640     <p/>
 641     Platforms which support environment variables or other named strings, may support the 
 642     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space 
 643     boundaries.  White-space characters include space, tab, carriage-return, new-line, 
 644     vertical-tab, and form-feed.  Sequences of white-space characters are considered 
 645     equivalent to a single white-space character.  No white-space is included in the options 
 646     unless quoted.  Quoting is as follows:
 647     <ul>
 648         <li>All characters enclosed between a pair of single quote marks (''), except a single 
 649         quote, are quoted.</li>


10684           This property is not available or is not writeable.
10685         </error>
10686       </errors>
10687     </function>
10688 
10689   </category>
10690 
10691   <category id="general" label="General">
10692 
10693     <intro>
10694     </intro>
10695 
10696     <function id="GetPhase" jkernel="yes" phase="any" num="133">
10697       <synopsis>Get Phase</synopsis>
10698       <description>
10699           Return the current phase of VM execution.  
10700           The phases proceed in sequence:
10701           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
10702             <constant id="JVMTI_PHASE_ONLOAD" num="1">
10703               <code>OnLoad</code> phase: while in the
10704               <internallink id="onload"><code>Agent_OnLoad</code></internallink> function.
10705             </constant>
10706             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
10707               Primordial phase: between return from <code>Agent_OnLoad</code> and the
10708               <code>VMStart</code> event.
10709             </constant>
10710             <constant id="JVMTI_PHASE_START" num="6">
10711               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event 
10712               is sent and until the <code>VMInit</code> event is sent.
10713             </constant>
10714             <constant id="JVMTI_PHASE_LIVE" num="4">
10715               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
10716               and until the <eventlink id="VMDeath"></eventlink> event returns.
10717             </constant>
10718             <constant id="JVMTI_PHASE_DEAD" num="8">
10719               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
10720               start-up failure.
10721             </constant>
10722           </constants>
10723           In the case of start-up failure the VM will proceed directly to the dead
10724           phase skipping intermediate phases and neither a <code>VMInit</code> nor
10725           <code>VMDeath</code> event will be sent.
10726           <p/>
10727           Most <jvmti/> functions operate only in the live phase.


14243   </change>
14244   <change date="28 June 2006" version="1.1.98">
14245       Clarify DisposeEnvironment; add warning.
14246       Fix typos in SetLocalXXX "retrieve" => "set".
14247       Clarify that native method prefixes must remain set while used.
14248       Clarify that exactly one Agent_OnXXX is called per agent.
14249       Clarify that library loading is independent from start-up.
14250       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14251   </change>
14252   <change date="31 July 2006" version="1.1.99">
14253       Clarify the interaction between functions and exceptions.
14254       Clarify and give examples of field indices.
14255       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14256       Update links to point to Java 6.
14257   </change>
14258   <change date="6 August 2006" version="1.1.102">
14259       Add ResourceExhaustedEvent.
14260   </change>
14261   <change date="11 October 2012" version="1.2.2">
14262       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.



14263   </change>
14264 </changehistory>
14265 
14266 </specification>
14267 <!-- Keep this comment at the end of the file
14268 Local variables:
14269 mode: sgml
14270 sgml-omittag:t
14271 sgml-shorttag:t
14272 sgml-namecase-general:t
14273 sgml-general-insert-case:lower
14274 sgml-minimize-attributes:nil
14275 sgml-always-quote-attributes:t
14276 sgml-indent-step:2
14277 sgml-indent-data:t
14278 sgml-parent-document:nil
14279 sgml-exposed-tags:nil
14280 sgml-local-catalogs:nil
14281 sgml-local-ecat-files:nil
14282 End:
   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
   3 <!--
   4  Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved.
   5  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6 
   7  This code is free software; you can redistribute it and/or modify it
   8  under the terms of the GNU General Public License version 2 only, as
   9  published by the Free Software Foundation.
  10 
  11  This code is distributed in the hope that it will be useful, but WITHOUT
  12  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  version 2 for more details (a copy is included in the LICENSE file that
  15  accompanied this code).
  16 
  17  You should have received a copy of the GNU General Public License version
  18  2 along with this work; if not, write to the Free Software Foundation,
  19  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20 
  21  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  or visit www.oracle.com if you need additional information or have any
  23  questions.
  24   


 341 
 342    <!ELEMENT table  (tr)+>
 343 
 344    <!ELEMENT tr  (td|th)*>
 345 
 346    <!ELEMENT td  ANY>
 347    <!ATTLIST td align (left|right|center) "center">
 348 
 349    <!ELEMENT th  ANY>
 350    <!ATTLIST th align (left|right|center) "center">
 351 
 352    <!ELEMENT ul  (li)+>
 353    <!ATTLIST ul type (disc|circle|square) "disc">
 354 
 355    <!ELEMENT li  ANY>
 356  ]>
 357 
 358 <specification label="JVM(TM) Tool Interface"
 359         majorversion="1"
 360         minorversion="2"
 361         microversion="3">
 362   <title subtitle="Version">
 363     <tm>JVM</tm> Tool Interface
 364   </title>
 365   
 366   <intro id="whatIs" label="What is the JVM Tool Interface?">
 367     The <tm>JVM</tm> Tool Interface (<jvmti/>) 
 368     is a programming interface used by development and monitoring tools. 
 369     It provides both a way to inspect the state and 
 370     to control the execution of applications running in the
 371     <tm>Java</tm> virtual machine (VM).
 372     <p/>
 373     <jvmti/> is intended to provide a VM interface for the full breadth of tools
 374     that need access to VM state, including but not limited to: profiling,
 375     debugging, monitoring, thread analysis, and coverage analysis tools.
 376     <p/>
 377     <jvmti/> may not be available in all implementations of the <tm>Java</tm> virtual
 378     machine.
 379     <p/>
 380     <jvmti/> is a two-way interface. 
 381     A client of <jvmti/>, hereafter called an <i>agent</i>,


 414     language calling conventions and C or C++
 415     definitions.
 416     <p/>
 417     The function, event, data type, and constant definitions needed for
 418     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 419     To use these definitions add the <tm>J2SE</tm> include directory
 420     to your include path and add
 421     <example>
 422 #include &lt;jvmti.h&gt;
 423     </example>
 424     to your source code.
 425   </intro>
 426 
 427   <intro id="deployingAgents" label="Deploying Agents">
 428     An agent is deployed in a platform specific manner but is typically the 
 429     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating 
 430     system, for example, an agent library is a "Dynamic Linked Library" (DLL). 
 431     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
 432     object (<code>.so</code> file).
 433     <p/>
 434 
 435     An agent may be started at VM startup by specifying the agent library
 436     name using a <internallink id="starting">command line option</internallink>.
 437     Some implementations may support a mechanism to <internallink id="onattach"> 
 438     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
 439     The details of how this is initiated are implementation specific.
 440   </intro>
 441 
 442     <intro id="entry point" label="Statically Linked Agents (since version 1.2.3)">
 443 
 444       A native JVMTI Agent may be <i>statically linked</i> with the VM.
 445       The manner in which the library and VM image are combined is
 446       implementation-dependent.
 447       An agent L whose image has been combined with the VM is defined as
 448       <i>statically linked</i> if and only if the agent exports a function
 449       called Agent_OnLoad_L.
 450 <p/>
 451       If a <i>statically linked</i> agent L exports a function called
 452       Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
 453       function will be ignored.
 454       If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
 455       function will be invoked with the same arguments and expected return
 456       value as specified for the Agent_OnLoad function.
 457       An agent L that is <i>statically linked</i> will prohibit an agent of
 458       the same name from being loaded dynamically.
 459 <p/>
 460       The VM will invoke the Agent_OnUnload_L function of the agent, if such
 461       a function is exported, at the same point during startup as it would
 462       have called the dynamic entry point Agent_OnUnLoad.
 463       If a <i>statically linked</i> agent L exports a function called
 464       Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
 465       function will be ignored.
 466 <p/>
 467       If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
 468       will be invoked with the same arguments and expected return value as
 469       specified for the Agent_OnAttach function.
 470       If a <i>statically linked</i> agent L exports a function called
 471       Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
 472       function will be ignored.
 473 </intro>
 474   
 475   <intro id="starting" label="Agent Command Line Options">
 476     The term "command-line option" is used below to
 477     mean options supplied in the <code>JavaVMInitArgs</code> argument
 478     to the <code>JNI_CreateJavaVM</code> function of the JNI
 479     Invocation API.
 480     <p/>
 481     One of the two following 
 482     command-line options is used on VM startup to 
 483     properly load and run agents.
 484     These arguments identify the library containing 
 485     the agent as well as an options
 486     string to be passed in at startup. 
 487     <dl>
 488       <dt><code>-agentlib:</code><i>&lt;agent-lib-name&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 489       <dd>
 490         The name following <code>-agentlib:</code> is the name of the
 491         library to load.  Lookup of the library, both its full name and location,
 492         proceeds in a platform-specific manner.
 493         Typically, the <i>&lt;agent-lib-name&gt;</i> is expanded to an
 494         operating system specific file name.
 495         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 496         For example, if the option 
 497         <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to 
 498         load the shared library <code>foo.dll</code> from the system <code>PATH</code>
 499         under <tm>Windows</tm> or <code>libfoo.so</code> from the 
 500         <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating
 501         environment.
 502         If the agent library is statically linked into the executable
 503         then no actual loading takes place.
 504     <p/>
 505       </dd>
 506       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 507       <dd>
 508         The path following <code>-agentpath:</code> is the absolute path from which
 509         to load the library.
 510         No library name expansion will occur.
 511         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 512         For example, if the option 
 513         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to 
 514         load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
 515         library is statically linked into the executable
 516         then no actual loading takes place.
 517     <p/>
 518       </dd>
 519     </dl>
 520     For a dynamic shared library agent, the start-up routine
 521     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 522     in the library will be invoked. If the agent library is statically linked
 523     into the executable then the system will attempt to invoke the
 524     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> entry point where
 525     &lt;agent-lib-name&gt; is the basename of the 
 526     agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
 527     the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
 528     <p/>
 529     Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
 530     will be searched for JNI native method implementations to facilitate the
 531     use of Java programming language code in tools, as is needed for 
 532     <internallink id="bci">bytecode instrumentation</internallink>.
 533     <p/>
 534     The agent libraries will be searched after all other libraries have been
 535     searched (agents wishing to override or intercept the native method
 536     implementations of non-agent methods can use the
 537     <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
 538     <p/>
 539     These switches do the above and nothing more - they do not change the 
 540     state of the VM or <jvmti/>.  No command line options are needed 
 541     to enable <jvmti/> 
 542     or aspects of <jvmti/>, this is handled programmatically
 543     by the use of 
 544     <internallink id="capability">capabilities</internallink>.
 545   </intro>
 546 
 547   <intro id="startup" label="Agent Start-Up">
 548     The VM starts each agent by invoking a start-up function.
 549     If the agent is started in the <code>OnLoad</code>
 550     <functionlink id="GetPhase">phase</functionlink> the function
 551     <internallink id="onload"><code>Agent_OnLoad</code></internallink>
 552     or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
 553     for statically linked agents will be invoked.
 554     If the agent is started in the live
 555     <functionlink id="GetPhase">phase</functionlink> the function
 556     <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
 557     or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
 558     for statically linked agents will be invoked.
 559     Exactly one call to a start-up function is made per agent.  
 560   </intro>
 561 
 562   <intro id="onload" label="Agent Start-Up (OnLoad phase)">
 563     If an agent is started during the <code>OnLoad</code> phase then its
 564     agent library must export a start-up function with the following prototype:
 565     <example>
 566 JNIEXPORT jint JNICALL 
 567 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
 568     Or for a statically linked agent named 'L':
 569     <example>
 570 JNIEXPORT jint JNICALL 
 571 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
 572 
 573     The VM will start the agent by calling this function.  
 574     It will be called early enough in VM initialization that:
 575     <ul>
 576       <li><functionlink id="SetSystemProperty">system properties</functionlink>
 577         may be set before they have been used in the start-up of the VM</li>
 578       <li>the full set of 
 579         <internallink id="capability">capabilities</internallink>
 580         is still available (note that capabilities that configure the VM
 581         may only be available at this time--see the 
 582         <internallink id="capability">Capability function section</internallink>)</li>
 583       <li>no bytecodes have executed</li>
 584       <li>no classes have been loaded</li>
 585       <li>no objects have been created</li>
 586     </ul>
 587     <p/>
 588     The VM will call the <code>Agent_OnLoad</code> or
 589     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> function with
 590     <i>&lt;options&gt;</i> as the second argument - 
 591     that is, using the command-line option examples,
 592     <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> 
 593     argument of <code>Agent_OnLoad</code>.
 594     The <code>options</code> argument is encoded as a
 595     <internallink id="mUTF">modified UTF-8</internallink> string.
 596     If <i>=&lt;options&gt;</i> is not specified, 
 597     a zero length string is passed to <code>options</code>.
 598     The lifespan of the <code>options</code> string is the
 599     <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code>
 600     call.  If needed beyond this time the string or parts of the string must
 601     be copied.
 602     The period between when <code>Agent_OnLoad</code> is called and when it
 603     returns is called the <i>OnLoad phase</i>.
 604     Since the VM is not initialized during the OnLoad 
 605     <functionlink id="GetPhase">phase</functionlink>,
 606     the set of allowed operations 
 607     inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
 608     functionality available at this time). 
 609     The agent can safely process the options and set 
 610     event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once  
 611     the VM initialization event is received 
 612     (that is, the <eventlink id="VMInit">VMInit</eventlink> 
 613     callback is invoked), the agent
 614     can complete its initialization.
 615     <rationale>
 616       Early startup is required so that agents can set the desired capabilities,
 617       many of which must be set before the VM is initialized.
 618       In JVMDI, the -Xdebug command-line option provided 
 619       very coarse-grain control of capabilities. 
 620       JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
 621       No reasonable command-line 
 622       option could provide the fine-grain of control required to balance needed capabilities vs
 623       performance impact.  
 624       Early startup is also needed so that agents can control the execution
 625       environment - modifying the file system and system properties to install
 626       their functionality.
 627     </rationale>
 628     <p/>
 629     The return value from <code>Agent_OnLoad</code> or
 630     <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> is used to indicate an error.
 631     Any value other than zero indicates an error and causes termination of the VM.
 632   </intro>
 633   
 634   <intro id="onattach" label="Agent Start-Up (Live phase)">
 635     A VM may support a mechanism that allows agents to be started in the VM during the live 
 636     <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
 637     are implementation specific. For example, a tool may use some platform specific mechanism, 
 638     or implementation specific API, to attach to the running VM, and request it start a given
 639     agent.
 640     <p/>
 641     If an agent is started during the live phase then its agent library
 642     must export a start-up function 
 643     with the following prototype:
 644     <example>
 645 JNIEXPORT jint JNICALL 
 646 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
 647 Or for a statically linked agent named 'L':
 648     <example>
 649 JNIEXPORT jint JNICALL 
 650 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
 651 
 652     <p/>         
 653     The VM will start the agent by calling this function.  
 654     It will be called in the context of a thread
 655     that is attached to the VM. The first argument <i>&lt;vm&gt;</i> is the Java VM.
 656     The <i>&lt;options&gt;</i> argument is the startup options provided to the agent.
 657     <i>&lt;options&gt;</i> is encoded as a <internallink id="mUTF">modified UTF-8
 658     </internallink> string.
 659     If startup options were not provided, a zero length string is passed to 
 660     <code>options</code>. The lifespan of the <code>options</code> string is the 
 661     <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> call.
 662     If needed beyond this time the string or parts of the string must be copied.
 663     <p/>
 664     Note that some <internallink id="capability">capabilities</internallink> 
 665     may not be available in the live phase.
 666     <p/>
 667     The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_&lt;agent-lib-name&gt;</code> function initializes the agent and returns a value
 668     to the VM to indicate if an error occurred. Any value other than zero indicates an error. 
 669     An error does not cause the VM to terminate. Instead the VM ignores the error, or takes 
 670     some implementation specific action -- for example it might print an error to standard error, 
 671     or record the error in a system log.
 672   </intro>
 673 
 674   <intro id="onunload" label="Agent Shutdown">
 675     The library may optionally export a 
 676     shutdown function with the following prototype:
 677     <example>
 678 JNIEXPORT void JNICALL 
 679 Agent_OnUnload(JavaVM *vm)</example>
 680     Or for a statically linked agent named 'L':
 681     <example>
 682 JNIEXPORT void JNICALL 
 683 Agent_OnUnload_L(JavaVM *vm)</example>
 684 
 685     This function will be called by the VM when the library is about to be unloaded.
 686     The library will be unloaded (unless it is statically linked into the
 687     executable) and this function will be called if some platform specific 
 688     mechanism causes the unload (an unload mechanism is not specified in this document)
 689     or the library is (in effect) unloaded by the termination of the VM whether through 
 690     normal termination or VM failure, including start-up failure.
 691     Uncontrolled shutdown is, of couse, an exception to this rule.
 692     Note the distinction between this function and the 
 693     <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
 694     to be sent, the VM must have run at least to the point of initialization and a valid 
 695     <jvmti/> environment must exist which has set a callback for VMDeath
 696     and enabled the event.
 697     None of these are required for <code>Agent_OnUnload</code> or
 698     <code>Agent_OnUnload_&lt;agent-lib-name&gt;</code> and this function
 699     is also called if the library is unloaded for other reasons.
 700     In the case that a VM Death event is sent, it will be sent before this 
 701     function is called (assuming this function is called due to VM termination).
 702     This function can be used to clean-up resources allocated by the agent.
 703   </intro>
 704 
 705   <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
 706     Since the command-line cannot always be accessed or modified, for example in embedded VMs
 707     or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
 708     provided so that agents may be launched in these cases.
 709     <p/>
 710     Platforms which support environment variables or other named strings, may support the 
 711     <code>JAVA_TOOL_OPTIONS</code> variable.  This variable will be broken into options at white-space 
 712     boundaries.  White-space characters include space, tab, carriage-return, new-line, 
 713     vertical-tab, and form-feed.  Sequences of white-space characters are considered 
 714     equivalent to a single white-space character.  No white-space is included in the options 
 715     unless quoted.  Quoting is as follows:
 716     <ul>
 717         <li>All characters enclosed between a pair of single quote marks (''), except a single 
 718         quote, are quoted.</li>


10753           This property is not available or is not writeable.
10754         </error>
10755       </errors>
10756     </function>
10757 
10758   </category>
10759 
10760   <category id="general" label="General">
10761 
10762     <intro>
10763     </intro>
10764 
10765     <function id="GetPhase" jkernel="yes" phase="any" num="133">
10766       <synopsis>Get Phase</synopsis>
10767       <description>
10768           Return the current phase of VM execution.  
10769           The phases proceed in sequence:
10770           <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
10771             <constant id="JVMTI_PHASE_ONLOAD" num="1">
10772               <code>OnLoad</code> phase: while in the
10773               <internallink id="onload"><code>Agent_OnLoad</code></internallink> or, for statically linked agents, the <internallink id="onload"><code>Agent_OnLoad_&lt;agent-lib-name&gt;</code></internallink> function.
10774             </constant>
10775             <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
10776               Primordial phase: between return from <code>Agent_OnLoad</code> or <code>Agent_OnLoad_&lt;agent-lib-name&gt;</code> and the
10777               <code>VMStart</code> event.
10778             </constant>
10779             <constant id="JVMTI_PHASE_START" num="6">
10780               Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event 
10781               is sent and until the <code>VMInit</code> event is sent.
10782             </constant>
10783             <constant id="JVMTI_PHASE_LIVE" num="4">
10784               Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
10785               and until the <eventlink id="VMDeath"></eventlink> event returns.
10786             </constant>
10787             <constant id="JVMTI_PHASE_DEAD" num="8">
10788               Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
10789               start-up failure.
10790             </constant>
10791           </constants>
10792           In the case of start-up failure the VM will proceed directly to the dead
10793           phase skipping intermediate phases and neither a <code>VMInit</code> nor
10794           <code>VMDeath</code> event will be sent.
10795           <p/>
10796           Most <jvmti/> functions operate only in the live phase.


14312   </change>
14313   <change date="28 June 2006" version="1.1.98">
14314       Clarify DisposeEnvironment; add warning.
14315       Fix typos in SetLocalXXX "retrieve" => "set".
14316       Clarify that native method prefixes must remain set while used.
14317       Clarify that exactly one Agent_OnXXX is called per agent.
14318       Clarify that library loading is independent from start-up.
14319       Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14320   </change>
14321   <change date="31 July 2006" version="1.1.99">
14322       Clarify the interaction between functions and exceptions.
14323       Clarify and give examples of field indices.
14324       Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14325       Update links to point to Java 6.
14326   </change>
14327   <change date="6 August 2006" version="1.1.102">
14328       Add ResourceExhaustedEvent.
14329   </change>
14330   <change date="11 October 2012" version="1.2.2">
14331       Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14332   </change>
14333   <change date="19 June 2013" version="1.2.3">
14334       Added support for statically linked agents.
14335   </change>
14336 </changehistory>
14337 
14338 </specification>
14339 <!-- Keep this comment at the end of the file
14340 Local variables:
14341 mode: sgml
14342 sgml-omittag:t
14343 sgml-shorttag:t
14344 sgml-namecase-general:t
14345 sgml-general-insert-case:lower
14346 sgml-minimize-attributes:nil
14347 sgml-always-quote-attributes:t
14348 sgml-indent-step:2
14349 sgml-indent-data:t
14350 sgml-parent-document:nil
14351 sgml-exposed-tags:nil
14352 sgml-local-catalogs:nil
14353 sgml-local-ecat-files:nil
14354 End: