409 
 410   <intro id="writingAgents" label="Writing Agents">
 411     Agents can be written in any native language that supports C
 412     language calling conventions and C or C++
 413     definitions.
 414     <p/>
 415     The function, event, data type, and constant definitions needed for
 416     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 417     To use these definitions add the <tm>J2SE</tm> include directory
 418     to your include path and add
 419     <example>
 420 #include &lt;jvmti.h&gt;
 421     </example>
 422     to your source code.
 423   </intro>
 424 
 425   <intro id="deployingAgents" label="Deploying Agents">
 426     An agent is deployed in a platform specific manner but is typically the
 427     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating
 428     system, for example, an agent library is a "Dynamic Linked Library" (DLL).
 429     On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
 430     object (<code>.so</code> file).
 431     <p/>
 432 
 433     An agent may be started at VM startup by specifying the agent library
 434     name using a <internallink id="starting">command line option</internallink>.
 435     Some implementations may support a mechanism to <internallink id="onattach">
 436     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
 437     The details of how this is initiated are implementation specific.
 438   </intro>
 439 
 440     <intro id="entryPoint" label="Statically Linked Agents (since version 1.2.3)">
 441 
 442       A native JVMTI Agent may be <i>statically linked</i> with the VM.
 443       The manner in which the library and VM image are combined is
 444       implementation-dependent.
 445       An agent L whose image has been combined with the VM is defined as
 446       <i>statically linked</i> if and only if the agent exports a function
 447       called Agent_OnLoad_L.
 448 <p/>
 449       If a <i>statically linked</i> agent L exports a function called
 450       Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad

 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>

13310         <vmbuf><void/></vmbuf>
13311         <description>
13312           Native address of the code
13313         </description>
13314       </param>
13315       <param id="length">
13316         <jint/>
13317         <description>
13318           Length in bytes of the code
13319         </description>
13320       </param>
13321     </parameters>
13322   </event>
13323 
13324   <event label="Data Dump Request"
13325          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
13326     <description>
13327       Sent by the VM to request the agent to dump its data.  This
13328       is just a hint and the agent need not react to this event.
13329       This is useful for processing command-line signals from users.  For
13330       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Solaris
13331       causes the VM to send this event to the agent.
13332     </description>
13333     <origin>jvmpi</origin>
13334     <capabilities>
13335     </capabilities>
13336     <parameters>
13337     </parameters>
13338   </event>
13339 
13340   <event label="Monitor Contended Enter"
13341          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
13342     <description>
13343       Sent when a thread is attempting to enter a Java programming language
13344       monitor already acquired by another thread.
13345     </description>
13346     <origin>jvmpi</origin>
13347     <capabilities>
13348       <required id="can_generate_monitor_events"></required>
13349     </capabilities>
13350     <parameters>

 409 
 410   <intro id="writingAgents" label="Writing Agents">
 411     Agents can be written in any native language that supports C
 412     language calling conventions and C or C++
 413     definitions.
 414     <p/>
 415     The function, event, data type, and constant definitions needed for
 416     using <jvmti/> are defined in the include file <code>jvmti.h</code>.
 417     To use these definitions add the <tm>J2SE</tm> include directory
 418     to your include path and add
 419     <example>
 420 #include &lt;jvmti.h&gt;
 421     </example>
 422     to your source code.
 423   </intro>
 424 
 425   <intro id="deployingAgents" label="Deploying Agents">
 426     An agent is deployed in a platform specific manner but is typically the
 427     platform equivalent of a dynamic library. On the <tm>Windows</tm> operating
 428     system, for example, an agent library is a "Dynamic Linked Library" (DLL).
 429     On <tm>Linux</tm> Operating Environment, an agent library is a shared object
 430     (<code>.so</code> file).
 431     <p/>
 432 
 433     An agent may be started at VM startup by specifying the agent library
 434     name using a <internallink id="starting">command line option</internallink>.
 435     Some implementations may support a mechanism to <internallink id="onattach">
 436     start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
 437     The details of how this is initiated are implementation specific.
 438   </intro>
 439 
 440     <intro id="entryPoint" label="Statically Linked Agents (since version 1.2.3)">
 441 
 442       A native JVMTI Agent may be <i>statically linked</i> with the VM.
 443       The manner in which the library and VM image are combined is
 444       implementation-dependent.
 445       An agent L whose image has been combined with the VM is defined as
 446       <i>statically linked</i> if and only if the agent exports a function
 447       called Agent_OnLoad_L.
 448 <p/>
 449       If a <i>statically linked</i> agent L exports a function called
 450       Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad

 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 <tm>Linux</tm>.

 501         If the agent library is statically linked into the executable
 502         then no actual loading takes place.
 503     <p/>
 504       </dd>
 505       <dt><code>-agentpath:</code><i>&lt;path-to-agent&gt;</i><code>=</code><i>&lt;options&gt;</i></dt>
 506       <dd>
 507         The path following <code>-agentpath:</code> is the absolute path from which
 508         to load the library.
 509         No library name expansion will occur.
 510         The <i>&lt;options&gt;</i> will be passed to the agent on start-up.
 511         For example, if the option
 512         <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to
 513         load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
 514         library is statically linked into the executable
 515         then no actual loading takes place.
 516     <p/>
 517       </dd>
 518     </dl>
 519     For a dynamic shared library agent, the start-up routine
 520     <internallink id="onload"><code>Agent_OnLoad</code></internallink>

13309         <vmbuf><void/></vmbuf>
13310         <description>
13311           Native address of the code
13312         </description>
13313       </param>
13314       <param id="length">
13315         <jint/>
13316         <description>
13317           Length in bytes of the code
13318         </description>
13319       </param>
13320     </parameters>
13321   </event>
13322 
13323   <event label="Data Dump Request"
13324          id="DataDumpRequest" const="JVMTI_EVENT_DATA_DUMP_REQUEST" num="71">
13325     <description>
13326       Sent by the VM to request the agent to dump its data.  This
13327       is just a hint and the agent need not react to this event.
13328       This is useful for processing command-line signals from users.  For
13329       example, in the Java 2 SDK a CTRL-Break on Win32 and a CTRL-\ on Linux
13330       causes the VM to send this event to the agent.
13331     </description>
13332     <origin>jvmpi</origin>
13333     <capabilities>
13334     </capabilities>
13335     <parameters>
13336     </parameters>
13337   </event>
13338 
13339   <event label="Monitor Contended Enter"
13340          id="MonitorContendedEnter" const="JVMTI_EVENT_MONITOR_CONTENDED_ENTER" filtered="thread" num="75">
13341     <description>
13342       Sent when a thread is attempting to enter a Java programming language
13343       monitor already acquired by another thread.
13344     </description>
13345     <origin>jvmpi</origin>
13346     <capabilities>
13347       <required id="can_generate_monitor_events"></required>
13348     </capabilities>
13349     <parameters>