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 <jvmti.h>
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><agent-lib-name></i><code>=</code><i><options></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><agent-lib-name></i> is expanded to an
460 operating system specific file name.
461 The <i><options></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><path-to-agent></i><code>=</code><i><options></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><options></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><options></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>=<options></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><vm></i> is the Java VM.
594 The <i><options></i> argument is the startup options provided to the agent.
595 <i><options></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:
|
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 <jvmti.h>
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><agent-lib-name></i><code>=</code><i><options></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><agent-lib-name></i> is expanded to an
494 operating system specific file name.
495 The <i><options></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><path-to-agent></i><code>=</code><i><options></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><options></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 <internallink id="onload"><code>Agent_OnLoad</code></internallink>
521 in the library will be invoked. If the agent library is statically linked
522 into the executable then the system will attempt to invoke the <code>Agent_OnLoad_<agent-lib-name></code> entry point where <agent-lib-name> is the basename of the
523 agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>, the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine.
524 <p/>
525 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
526 will be searched for JNI native method implementations to facilitate the
527 use of Java programming language code in tools, as is needed for
528 <internallink id="bci">bytecode instrumentation</internallink>.
529 <p/>
530 The agent libraries will be searched after all other libraries have been
531 searched (agents wishing to override or intercept the native method
532 implementations of non-agent methods can use the
533 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
534 <p/>
535 These switches do the above and nothing more - they do not change the
536 state of the VM or <jvmti/>. No command line options are needed
537 to enable <jvmti/>
538 or aspects of <jvmti/>, this is handled programmatically
539 by the use of
540 <internallink id="capability">capabilities</internallink>.
541 </intro>
542
543 <intro id="startup" label="Agent Start-Up">
544 The VM starts each agent by invoking a start-up function.
545 If the agent is started in the <code>OnLoad</code>
546 <functionlink id="GetPhase">phase</functionlink> the function
547 <internallink id="onload"><code>Agent_OnLoad</code></internallink>
548 or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
549 for statically linked agents will be invoked.
550 If the agent is started in the live
551 <functionlink id="GetPhase">phase</functionlink> the function
552 <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
553 or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
554 for statically linked agents will be invoked.
555 Exactly one call to a start-up function is made per agent.
556 </intro>
557
558 <intro id="onload" label="Agent Start-Up (OnLoad phase)">
559 If an agent is started during the <code>OnLoad</code> phase then its
560 agent library must export a start-up function with the following prototype:
561 <example>
562 JNIEXPORT jint JNICALL
563 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example>
564 Or for a statically linked agent named 'L':
565 <example>
566 JNIEXPORT jint JNICALL
567 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example>
568
569 The VM will start the agent by calling this function.
570 It will be called early enough in VM initialization that:
571 <ul>
572 <li><functionlink id="SetSystemProperty">system properties</functionlink>
573 may be set before they have been used in the start-up of the VM</li>
574 <li>the full set of
575 <internallink id="capability">capabilities</internallink>
576 is still available (note that capabilities that configure the VM
577 may only be available at this time--see the
578 <internallink id="capability">Capability function section</internallink>)</li>
579 <li>no bytecodes have executed</li>
580 <li>no classes have been loaded</li>
581 <li>no objects have been created</li>
582 </ul>
583 <p/>
584 The VM will call the <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code> function with
585 <i><options></i> as the second argument -
586 that is, using the command-line option examples,
587 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
588 argument of <code>Agent_OnLoad</code>.
589 The <code>options</code> argument is encoded as a
590 <internallink id="mUTF">modified UTF-8</internallink> string.
591 If <i>=<options></i> is not specified,
592 a zero length string is passed to <code>options</code>.
593 The lifespan of the <code>options</code> string is the <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code>
594 call. If needed beyond this time the string or parts of the string must
595 be copied.
596 The period between when <code>Agent_OnLoad</code> is called and when it
597 returns is called the <i>OnLoad phase</i>.
598 Since the VM is not initialized during the OnLoad
599 <functionlink id="GetPhase">phase</functionlink>,
600 the set of allowed operations
601 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
602 functionality available at this time).
603 The agent can safely process the options and set
604 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once
605 the VM initialization event is received
606 (that is, the <eventlink id="VMInit">VMInit</eventlink>
607 callback is invoked), the agent
608 can complete its initialization.
609 <rationale>
610 Early startup is required so that agents can set the desired capabilities,
611 many of which must be set before the VM is initialized.
612 In JVMDI, the -Xdebug command-line option provided
613 very coarse-grain control of capabilities.
614 JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
615 No reasonable command-line
616 option could provide the fine-grain of control required to balance needed capabilities vs
617 performance impact.
618 Early startup is also needed so that agents can control the execution
619 environment - modifying the file system and system properties to install
620 their functionality.
621 </rationale>
622 <p/>
623 The return value from <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error.
624 Any value other than zero indicates an error and causes termination of the VM.
625 </intro>
626
627 <intro id="onattach" label="Agent Start-Up (Live phase)">
628 A VM may support a mechanism that allows agents to be started in the VM during the live
629 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
630 are implementation specific. For example, a tool may use some platform specific mechanism,
631 or implementation specific API, to attach to the running VM, and request it start a given
632 agent.
633 <p/>
634 If an agent is started during the live phase then its agent library
635 must export a start-up function
636 with the following prototype:
637 <example>
638 JNIEXPORT jint JNICALL
639 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example>
640 Or for a statically linked agent named 'L':
641 <example>
642 JNIEXPORT jint JNICALL
643 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example>
644
645 <p/>
646 The VM will start the agent by calling this function.
647 It will be called in the context of a thread
648 that is attached to the VM. The first argument <i><vm></i> is the Java VM.
649 The <i><options></i> argument is the startup options provided to the agent.
650 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8
651 </internallink> string.
652 If startup options were not provided, a zero length string is passed to
653 <code>options</code>. The lifespan of the <code>options</code> string is the
654 <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call. If needed beyond this time the string or parts of
655 the string must be copied.
656 <p/>
657 Note that some <internallink id="capability">capabilities</internallink>
658 may not be available in the live phase.
659 <p/>
660 The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> function initializes the agent and returns a value
661 to the VM to indicate if an error occurred. Any value other than zero indicates an error.
662 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes
663 some implementation specific action -- for example it might print an error to standard error,
664 or record the error in a system log.
665 </intro>
666
667 <intro id="onunload" label="Agent Shutdown">
668 The library may optionally export a
669 shutdown function with the following prototype:
670 <example>
671 JNIEXPORT void JNICALL
672 Agent_OnUnload(JavaVM *vm)</example>
673 Or for a statically linked agent named 'L':
674 <example>
675 JNIEXPORT void JNICALL
676 Agent_OnUnload_L(JavaVM *vm)</example>
677
678 This function will be called by the VM when the library is about to be unloaded.
679 The library will be unloaded (unless it is statically linked into the executable) and this function will be called if some platform specific
680 mechanism causes the unload (an unload mechanism is not specified in this document)
681 or the library is (in effect) unloaded by the termination of the VM whether through
682 normal termination or VM failure, including start-up failure.
683 Uncontrolled shutdown is, of couse, an exception to this rule.
684 Note the distinction between this function and the
685 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
686 to be sent, the VM must have run at least to the point of initialization and a valid
687 <jvmti/> environment must exist which has set a callback for VMDeath
688 and enabled the event.
689 None of these are required for <code>Agent_OnUnload</code> or <code>Agent_OnUnload_<agent-lib-name></code> and this function
690 is also called if the library is unloaded for other reasons.
691 In the case that a VM Death event is sent, it will be sent before this
692 function is called (assuming this function is called due to VM termination).
693 This function can be used to clean-up resources allocated by the agent.
694 </intro>
695
696 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
697 Since the command-line cannot always be accessed or modified, for example in embedded VMs
698 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
699 provided so that agents may be launched in these cases.
700 <p/>
701 Platforms which support environment variables or other named strings, may support the
702 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space
703 boundaries. White-space characters include space, tab, carriage-return, new-line,
704 vertical-tab, and form-feed. Sequences of white-space characters are considered
705 equivalent to a single white-space character. No white-space is included in the options
706 unless quoted. Quoting is as follows:
707 <ul>
708 <li>All characters enclosed between a pair of single quote marks (''), except a single
709 quote, are quoted.</li>
10744 This property is not available or is not writeable.
10745 </error>
10746 </errors>
10747 </function>
10748
10749 </category>
10750
10751 <category id="general" label="General">
10752
10753 <intro>
10754 </intro>
10755
10756 <function id="GetPhase" jkernel="yes" phase="any" num="133">
10757 <synopsis>Get Phase</synopsis>
10758 <description>
10759 Return the current phase of VM execution.
10760 The phases proceed in sequence:
10761 <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
10762 <constant id="JVMTI_PHASE_ONLOAD" num="1">
10763 <code>OnLoad</code> phase: while in the
10764 <internallink id="onload"><code>Agent_OnLoad</code></internallink> or, for statically linked agents, the <internallink id="onload"><code>Agent_OnLoad_<agent-lib-name></code></internallink> function.
10765 </constant>
10766 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
10767 Primordial phase: between return from <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code> and the
10768 <code>VMStart</code> event.
10769 </constant>
10770 <constant id="JVMTI_PHASE_START" num="6">
10771 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event
10772 is sent and until the <code>VMInit</code> event is sent.
10773 </constant>
10774 <constant id="JVMTI_PHASE_LIVE" num="4">
10775 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
10776 and until the <eventlink id="VMDeath"></eventlink> event returns.
10777 </constant>
10778 <constant id="JVMTI_PHASE_DEAD" num="8">
10779 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
10780 start-up failure.
10781 </constant>
10782 </constants>
10783 In the case of start-up failure the VM will proceed directly to the dead
10784 phase skipping intermediate phases and neither a <code>VMInit</code> nor
10785 <code>VMDeath</code> event will be sent.
10786 <p/>
10787 Most <jvmti/> functions operate only in the live phase.
14303 </change>
14304 <change date="28 June 2006" version="1.1.98">
14305 Clarify DisposeEnvironment; add warning.
14306 Fix typos in SetLocalXXX "retrieve" => "set".
14307 Clarify that native method prefixes must remain set while used.
14308 Clarify that exactly one Agent_OnXXX is called per agent.
14309 Clarify that library loading is independent from start-up.
14310 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14311 </change>
14312 <change date="31 July 2006" version="1.1.99">
14313 Clarify the interaction between functions and exceptions.
14314 Clarify and give examples of field indices.
14315 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14316 Update links to point to Java 6.
14317 </change>
14318 <change date="6 August 2006" version="1.1.102">
14319 Add ResourceExhaustedEvent.
14320 </change>
14321 <change date="11 October 2012" version="1.2.2">
14322 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14323 </change>
14324 <change date="19 June 2013" version="1.2.3">
14325 Added support for statically linked agents.
14326 </change>
14327 </changehistory>
14328
14329 </specification>
14330 <!-- Keep this comment at the end of the file
14331 Local variables:
14332 mode: sgml
14333 sgml-omittag:t
14334 sgml-shorttag:t
14335 sgml-namecase-general:t
14336 sgml-general-insert-case:lower
14337 sgml-minimize-attributes:nil
14338 sgml-always-quote-attributes:t
14339 sgml-indent-step:2
14340 sgml-indent-data:t
14341 sgml-parent-document:nil
14342 sgml-exposed-tags:nil
14343 sgml-local-catalogs:nil
14344 sgml-local-ecat-files:nil
14345 End:
|