The JVM TI specification (1.1.95) at:
http://download.java.net/jdk6/doc/platform/jvmti/jvmti.html
states as follows about native agent's loading in OnLoad and Live Phase:
--- Excerpt-from-spec ---
...
Agent Start-Up (OnLoad phase)
If an agent is started during the OnLoad phase then it must export a start-up
function with the following prototype:
JNIEXPORT jint JNICALL
Agent_OnLoad(JavaVM *vm, char *options, void *reserved)
This function will be called by the VM when the library is loaded.
...
As the agent is started in the OnLoad phase, the Agent_OnAttach is not invoked.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
--- End-of-excerpt-from-spec ---
and
--- Excerpt-from-spec ---
...
Agent Start-Up (Live phase)
If an agent is started during the live phase then it must export a start-up
function with the following prototype:
JNIEXPORT jint JNICALL
Agent_OnAttach(JavaVM* vm, char *options, void *reserved)
As the agent is started in the live phase the Agent_OnLoad function is not invoked.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note that some capabilities may not be available in the live phase.
...
--- End-of-excerpt-from-spec ---
It's not fully clear from the spec that if an agent library is specified
with -agentlib/-agentpath then only Agent_OnLoad is called, and, similarly,
if an agent library is loaded into a running system then only Agent_OnAttach
is called.
There is another aspect of this that is unclear, or worse, it says
"when the library is loaded". What if one "foo" agent is launched on
the command line, and later another "foo" agent is launched via attach.
It looks like Agent_OnLoad should be called for the first and
Agent_OnAttach for the second even though the library is already loaded.
Similarly for two agents loaded from the command line.
The JVM TI specification should be more descriptive here.