1.1 --- a/src/share/vm/prims/jvmti.xml Fri Aug 23 03:14:54 2013 -0700
1.2 +++ b/src/share/vm/prims/jvmti.xml Fri Aug 23 20:33:02 2013 -0400
1.3 @@ -1,7 +1,7 @@
1.4 <?xml version="1.0" encoding="ISO-8859-1"?>
1.5 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
1.6 <!--
1.7 - Copyright (c) 2002, 2012, Oracle and/or its affiliates. All rights reserved.
1.8 + Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved.
1.9 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.10
1.11 This code is free software; you can redistribute it and/or modify it
1.12 @@ -358,7 +358,7 @@
1.13 <specification label="JVM(TM) Tool Interface"
1.14 majorversion="1"
1.15 minorversion="2"
1.16 - microversion="2">
1.17 + microversion="3">
1.18 <title subtitle="Version">
1.19 <tm>JVM</tm> Tool Interface
1.20 </title>
1.21 @@ -431,12 +431,46 @@
1.22 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared
1.23 object (<code>.so</code> file).
1.24 <p/>
1.25 +
1.26 An agent may be started at VM startup by specifying the agent library
1.27 name using a <internallink id="starting">command line option</internallink>.
1.28 Some implementations may support a mechanism to <internallink id="onattach">
1.29 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>.
1.30 The details of how this is initiated are implementation specific.
1.31 </intro>
1.32 +
1.33 + <intro id="entry point" label="Statically Linked Agents (since version 1.2.3)">
1.34 +
1.35 + A native JVMTI Agent may be <i>statically linked</i> with the VM.
1.36 + The manner in which the library and VM image are combined is
1.37 + implementation-dependent.
1.38 + An agent L whose image has been combined with the VM is defined as
1.39 + <i>statically linked</i> if and only if the agent exports a function
1.40 + called Agent_OnLoad_L.
1.41 +<p/>
1.42 + If a <i>statically linked</i> agent L exports a function called
1.43 + Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad
1.44 + function will be ignored.
1.45 + If an agent L is <i>statically linked</i>, an Agent_OnLoad_L
1.46 + function will be invoked with the same arguments and expected return
1.47 + value as specified for the Agent_OnLoad function.
1.48 + An agent L that is <i>statically linked</i> will prohibit an agent of
1.49 + the same name from being loaded dynamically.
1.50 +<p/>
1.51 + The VM will invoke the Agent_OnUnload_L function of the agent, if such
1.52 + a function is exported, at the same point during startup as it would
1.53 + have called the dynamic entry point Agent_OnUnLoad.
1.54 + If a <i>statically linked</i> agent L exports a function called
1.55 + Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad
1.56 + function will be ignored.
1.57 +<p/>
1.58 + If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function
1.59 + will be invoked with the same arguments and expected return value as
1.60 + specified for the Agent_OnAttach function.
1.61 + If a <i>statically linked</i> agent L exports a function called
1.62 + Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach
1.63 + function will be ignored.
1.64 +</intro>
1.65
1.66 <intro id="starting" label="Agent Command Line Options">
1.67 The term "command-line option" is used below to
1.68 @@ -455,7 +489,7 @@
1.69 <dd>
1.70 The name following <code>-agentlib:</code> is the name of the
1.71 library to load. Lookup of the library, both its full name and location,
1.72 - proceeds in a platform-specific manner.
1.73 + proceeds in a platform-specific manner.
1.74 Typically, the <i><agent-lib-name></i> is expanded to an
1.75 operating system specific file name.
1.76 The <i><options></i> will be passed to the agent on start-up.
1.77 @@ -463,7 +497,11 @@
1.78 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to
1.79 load the shared library <code>foo.dll</code> from the system <code>PATH</code>
1.80 under <tm>Windows</tm> or <code>libfoo.so</code> from the
1.81 - <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment.
1.82 + <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating
1.83 + environment.
1.84 + If the agent library is statically linked into the executable
1.85 + then no actual loading takes place.
1.86 + <p/>
1.87 </dd>
1.88 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt>
1.89 <dd>
1.90 @@ -473,11 +511,20 @@
1.91 The <i><options></i> will be passed to the agent on start-up.
1.92 For example, if the option
1.93 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to
1.94 - load the shared library <code>c:\myLibs\foo.dll</code>.
1.95 + load the shared library <code>c:\myLibs\foo.dll</code>. If the agent
1.96 + library is statically linked into the executable
1.97 + then no actual loading takes place.
1.98 + <p/>
1.99 </dd>
1.100 </dl>
1.101 - The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink>
1.102 - in the library will be invoked.
1.103 + For a dynamic shared library agent, the start-up routine
1.104 + <internallink id="onload"><code>Agent_OnLoad</code></internallink>
1.105 + in the library will be invoked. If the agent library is statically linked
1.106 + into the executable then the system will attempt to invoke the
1.107 + <code>Agent_OnLoad_<agent-lib-name></code> entry point where
1.108 + <agent-lib-name> is the basename of the
1.109 + agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>,
1.110 + the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
1.111 <p/>
1.112 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
1.113 will be searched for JNI native method implementations to facilitate the
1.114 @@ -502,11 +549,13 @@
1.115 If the agent is started in the <code>OnLoad</code>
1.116 <functionlink id="GetPhase">phase</functionlink> the function
1.117 <internallink id="onload"><code>Agent_OnLoad</code></internallink>
1.118 - will be invoked.
1.119 + or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
1.120 + for statically linked agents will be invoked.
1.121 If the agent is started in the live
1.122 <functionlink id="GetPhase">phase</functionlink> the function
1.123 <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
1.124 - will be invoked.
1.125 + or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
1.126 + for statically linked agents will be invoked.
1.127 Exactly one call to a start-up function is made per agent.
1.128 </intro>
1.129
1.130 @@ -516,6 +565,11 @@
1.131 <example>
1.132 JNIEXPORT jint JNICALL
1.133 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
1.134 + Or for a statically linked agent named 'L':
1.135 + <example>
1.136 +JNIEXPORT jint JNICALL
1.137 +Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
1.138 +
1.139 The VM will start the agent by calling this function.
1.140 It will be called early enough in VM initialization that:
1.141 <ul>
1.142 @@ -531,7 +585,8 @@
1.143 <li>no objects have been created</li>
1.144 </ul>
1.145 <p/>
1.146 - The VM will call the <code>Agent_OnLoad</code> function with
1.147 + The VM will call the <code>Agent_OnLoad</code> or
1.148 + <code>Agent_OnLoad_<agent-lib-name></code> function with
1.149 <i><options></i> as the second argument -
1.150 that is, using the command-line option examples,
1.151 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
1.152 @@ -540,7 +595,8 @@
1.153 <internallink id="mUTF">modified UTF-8</internallink> string.
1.154 If <i>=<options></i> is not specified,
1.155 a zero length string is passed to <code>options</code>.
1.156 - The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code>
1.157 + The lifespan of the <code>options</code> string is the
1.158 + <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code>
1.159 call. If needed beyond this time the string or parts of the string must
1.160 be copied.
1.161 The period between when <code>Agent_OnLoad</code> is called and when it
1.162 @@ -570,7 +626,8 @@
1.163 their functionality.
1.164 </rationale>
1.165 <p/>
1.166 - The return value from <code>Agent_OnLoad</code> is used to indicate an error.
1.167 + The return value from <code>Agent_OnLoad</code> or
1.168 + <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error.
1.169 Any value other than zero indicates an error and causes termination of the VM.
1.170 </intro>
1.171
1.172 @@ -587,6 +644,11 @@
1.173 <example>
1.174 JNIEXPORT jint JNICALL
1.175 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
1.176 +Or for a statically linked agent named 'L':
1.177 + <example>
1.178 +JNIEXPORT jint JNICALL
1.179 +Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
1.180 +
1.181 <p/>
1.182 The VM will start the agent by calling this function.
1.183 It will be called in the context of a thread
1.184 @@ -596,13 +658,14 @@
1.185 </internallink> string.
1.186 If startup options were not provided, a zero length string is passed to
1.187 <code>options</code>. The lifespan of the <code>options</code> string is the
1.188 - <code>Agent_OnAttach</code> call. If needed beyond this time the string or parts of
1.189 - the string must be copied.
1.190 + <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call.
1.191 + If needed beyond this time the string or parts of the string must be copied.
1.192 <p/>
1.193 Note that some <internallink id="capability">capabilities</internallink>
1.194 may not be available in the live phase.
1.195 <p/>
1.196 - The <code>Agent_OnAttach</code> function initializes the agent and returns a value
1.197 + The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name
1.198 + ></code> function initializes the agent and returns a value
1.199 to the VM to indicate if an error occurred. Any value other than zero indicates an error.
1.200 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes
1.201 some implementation specific action -- for example it might print an error to standard error,
1.202 @@ -615,8 +678,14 @@
1.203 <example>
1.204 JNIEXPORT void JNICALL
1.205 Agent_OnUnload(JavaVM *vm)</example>
1.206 + Or for a statically linked agent named 'L':
1.207 + <example>
1.208 +JNIEXPORT void JNICALL
1.209 +Agent_OnUnload_L(JavaVM *vm)</example>
1.210 +
1.211 This function will be called by the VM when the library is about to be unloaded.
1.212 - The library will be unloaded and this function will be called if some platform specific
1.213 + The library will be unloaded (unless it is statically linked into the
1.214 + executable) and this function will be called if some platform specific
1.215 mechanism causes the unload (an unload mechanism is not specified in this document)
1.216 or the library is (in effect) unloaded by the termination of the VM whether through
1.217 normal termination or VM failure, including start-up failure.
1.218 @@ -625,8 +694,9 @@
1.219 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
1.220 to be sent, the VM must have run at least to the point of initialization and a valid
1.221 <jvmti/> environment must exist which has set a callback for VMDeath
1.222 - and enabled the event
1.223 - None of these are required for <code>Agent_OnUnload</code> and this function
1.224 + and enabled the event.
1.225 + None of these are required for <code>Agent_OnUnload</code> or
1.226 + <code>Agent_OnUnload_<agent-lib-name></code> and this function
1.227 is also called if the library is unloaded for other reasons.
1.228 In the case that a VM Death event is sent, it will be sent before this
1.229 function is called (assuming this function is called due to VM termination).
1.230 @@ -10701,10 +10771,14 @@
1.231 <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
1.232 <constant id="JVMTI_PHASE_ONLOAD" num="1">
1.233 <code>OnLoad</code> phase: while in the
1.234 - <internallink id="onload"><code>Agent_OnLoad</code></internallink> function.
1.235 + <internallink id="onload"><code>Agent_OnLoad</code></internallink>
1.236 + or, for statically linked agents, the <internallink id="onload">
1.237 + <code>Agent_OnLoad_<agent-lib-name>
1.238 + </code></internallink> function.
1.239 </constant>
1.240 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
1.241 - Primordial phase: between return from <code>Agent_OnLoad</code> and the
1.242 + Primordial phase: between return from <code>Agent_OnLoad</code>
1.243 + or <code>Agent_OnLoad_<agent-lib-name></code> and the
1.244 <code>VMStart</code> event.
1.245 </constant>
1.246 <constant id="JVMTI_PHASE_START" num="6">
1.247 @@ -14261,6 +14335,9 @@
1.248 <change date="11 October 2012" version="1.2.2">
1.249 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
1.250 </change>
1.251 + <change date="19 June 2013" version="1.2.3">
1.252 + Added support for statically linked agents.
1.253 + </change>
1.254 </changehistory>
1.255
1.256 </specification>
