--- old/src/share/vm/prims/jvmti.xml 2013-08-20 12:12:05.786693875 -0400 +++ new/src/share/vm/prims/jvmti.xml 2013-08-20 12:12:04.798638438 -0400 @@ -358,7 +358,7 @@ + microversion="3"> <tm>JVM</tm> Tool Interface @@ -431,12 +431,46 @@ On the Solaris Operating Environment, an agent library is a shared object (.so file).

+ An agent may be started at VM startup by specifying the agent library name using a command line option. Some implementations may support a mechanism to start agents in the live phase. The details of how this is initiated are implementation specific. + + + + A native JVMTI Agent may be statically linked with the VM. + The manner in which the library and VM image are combined is + implementation-dependent. + An agent L whose image has been combined with the VM is defined as + statically linked if and only if the agent exports a function + called Agent_OnLoad_L. +

+ If a statically linked agent L exports a function called + Agent_OnLoad_L and a function called Agent_OnLoad, the Agent_OnLoad + function will be ignored. + If an agent L is statically linked, an Agent_OnLoad_L + function will be invoked with the same arguments and expected return + value as specified for the Agent_OnLoad function. + An agent L that is statically linked will prohibit an agent of + the same name from being loaded dynamically. +

+ The VM will invoke the Agent_OnUnload_L function of the agent, if such + a function is exported, at the same point during startup as it would + have called the dynamic entry point Agent_OnUnLoad. + If a statically linked agent L exports a function called + Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad + function will be ignored. +

+ If an agent L is statically linked, an Agent_OnAttach_L function + will be invoked with the same arguments and expected return value as + specified for the Agent_OnAttach function. + If a statically linked agent L exports a function called + Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach + function will be ignored. + The term "command-line option" is used below to @@ -455,7 +489,7 @@

The name following -agentlib: is the name of the library to load. Lookup of the library, both its full name and location, - proceeds in a platform-specific manner. + proceeds in a platform-specific manner. Typically, the <agent-lib-name> is expanded to an operating system specific file name. The <options> will be passed to the agent on start-up. @@ -463,7 +497,11 @@ -agentlib:foo=opt1,opt2 is specified, the VM will attempt to load the shared library foo.dll from the system PATH under Windows or libfoo.so from the - LD_LIBRARY_PATH under the Solaris operating environment. + LD_LIBRARY_PATH under the Solaris operating + environment. + If the agent library is statically linked into the executable + then no actual loading takes place. +

-agentpath:<path-to-agent>=<options>
@@ -473,11 +511,16 @@ The <options> will be passed to the agent on start-up. For example, if the option -agentpath:c:\myLibs\foo.dll=opt1,opt2 is specified, the VM will attempt to - load the shared library c:\myLibs\foo.dll. + load the shared library c:\myLibs\foo.dll. If the agent + library is statically linked into the executable + then no actual loading takes place. +

- The start-up routine Agent_OnLoad - in the library will be invoked. + For a dynamic shared library agent, the start-up routine Agent_OnLoad + in the library will be invoked. If the agent library is statically linked + into the executable then the system will attempt to invoke the Agent_OnLoad_<agent-lib-name> entry point where <agent-lib-name> is the basename of the + agent. In the above example -agentpath:c:\myLibs\foo.dll=opt1,opt2, the system will attempt to find and call the Agent_OnLoad_foo start-up routine.

Libraries loaded with -agentlib: or -agentpath: will be searched for JNI native method implementations to facilitate the @@ -502,11 +545,13 @@ If the agent is started in the OnLoad phase the function Agent_OnLoad - will be invoked. + or Agent_OnLoad_L + for statically linked agents will be invoked. If the agent is started in the live phase the function Agent_OnAttach - will be invoked. + or Agent_OnAttach_L + for statically linked agents will be invoked. Exactly one call to a start-up function is made per agent. @@ -516,6 +561,11 @@ JNIEXPORT jint JNICALL Agent_OnLoad(JavaVM *vm, char *options, void *reserved) + Or for a statically linked agent named 'L': + +JNIEXPORT jint JNICALL +Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved) + The VM will start the agent by calling this function. It will be called early enough in VM initialization that:

- The VM will call the Agent_OnLoad function with + The VM will call the Agent_OnLoad or Agent_OnLoad_<agent-lib-name> function with <options> as the second argument - that is, using the command-line option examples, "opt1,opt2" will be passed to the char *options @@ -540,7 +590,7 @@ modified UTF-8 string. If =<options> is not specified, a zero length string is passed to options. - The lifespan of the options string is the Agent_OnLoad + The lifespan of the options string is the Agent_OnLoad or Agent_OnLoad_<agent-lib-name> call. If needed beyond this time the string or parts of the string must be copied. The period between when Agent_OnLoad is called and when it @@ -570,7 +620,7 @@ their functionality.

- The return value from Agent_OnLoad is used to indicate an error. + The return value from Agent_OnLoad or Agent_OnLoad_<agent-lib-name> is used to indicate an error. Any value other than zero indicates an error and causes termination of the VM. @@ -587,6 +637,11 @@ JNIEXPORT jint JNICALL Agent_OnAttach(JavaVM* vm, char *options, void *reserved) +Or for a statically linked agent named 'L': + +JNIEXPORT jint JNICALL +Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved) +

The VM will start the agent by calling this function. It will be called in the context of a thread @@ -596,13 +651,13 @@ string. If startup options were not provided, a zero length string is passed to options. The lifespan of the options string is the - Agent_OnAttach call. If needed beyond this time the string or parts of + Agent_OnAttach or Agent_OnAttach_<agent-lib-name> call. If needed beyond this time the string or parts of the string must be copied.

Note that some capabilities may not be available in the live phase.

- The Agent_OnAttach function initializes the agent and returns a value + The Agent_OnAttach or Agent_OnAttach_<agent-lib-name> 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, @@ -615,8 +670,13 @@ JNIEXPORT void JNICALL Agent_OnUnload(JavaVM *vm) + Or for a statically linked agent named 'L': + +JNIEXPORT void JNICALL +Agent_OnUnload_L(JavaVM *vm) + 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 + The library will be unloaded (unless it is statically linked into the executable) 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. @@ -625,8 +685,8 @@ VM Death event: for the VM Death event to be sent, the VM must have run at least to the point of initialization and a valid environment must exist which has set a callback for VMDeath - and enabled the event - None of these are required for Agent_OnUnload and this function + and enabled the event. + None of these are required for Agent_OnUnload or Agent_OnUnload_<agent-lib-name> 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). @@ -10701,10 +10761,10 @@ OnLoad phase: while in the - Agent_OnLoad function. + Agent_OnLoad or, for statically linked agents, the Agent_OnLoad_<agent-lib-name> function. - Primordial phase: between return from Agent_OnLoad and the + Primordial phase: between return from Agent_OnLoad or Agent_OnLoad_<agent-lib-name> and the VMStart event. @@ -14261,6 +14321,9 @@ Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. + + Added support for statically linked agents. +