1 <?xml version="1.0" encoding="ISO-8859-1"?> |
1 <?xml version="1.0" encoding="ISO-8859-1"?> |
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> |
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?> |
3 <!-- |
3 <!-- |
4 Copyright (c) 2002, 2012, Oracle and/or its affiliates. All rights reserved. |
4 Copyright (c) 2002, 2013, Oracle and/or its affiliates. All rights reserved. |
5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
6 |
6 |
7 This code is free software; you can redistribute it and/or modify it |
7 This code is free software; you can redistribute it and/or modify it |
8 under the terms of the GNU General Public License version 2 only, as |
8 under the terms of the GNU General Public License version 2 only, as |
9 published by the Free Software Foundation. |
9 published by the Free Software Foundation. |
429 platform equivalent of a dynamic library. On the <tm>Windows</tm> operating |
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). |
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 |
431 On the <tm>Solaris</tm> Operating Environment, an agent library is a shared |
432 object (<code>.so</code> file). |
432 object (<code>.so</code> file). |
433 <p/> |
433 <p/> |
|
434 |
434 An agent may be started at VM startup by specifying the agent library |
435 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 name using a <internallink id="starting">command line option</internallink>. |
436 Some implementations may support a mechanism to <internallink id="onattach"> |
437 Some implementations may support a mechanism to <internallink id="onattach"> |
437 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. |
438 start agents</internallink> in the live <functionlink id="GetPhase">phase</functionlink>. |
438 The details of how this is initiated are implementation specific. |
439 The details of how this is initiated are implementation specific. |
439 </intro> |
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> |
440 |
474 |
441 <intro id="starting" label="Agent Command Line Options"> |
475 <intro id="starting" label="Agent Command Line Options"> |
442 The term "command-line option" is used below to |
476 The term "command-line option" is used below to |
443 mean options supplied in the <code>JavaVMInitArgs</code> argument |
477 mean options supplied in the <code>JavaVMInitArgs</code> argument |
444 to the <code>JNI_CreateJavaVM</code> function of the JNI |
478 to the <code>JNI_CreateJavaVM</code> function of the JNI |
453 <dl> |
487 <dl> |
454 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> |
488 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> |
455 <dd> |
489 <dd> |
456 The name following <code>-agentlib:</code> is the name of the |
490 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, |
491 library to load. Lookup of the library, both its full name and location, |
458 proceeds in a platform-specific manner. |
492 proceeds in a platform-specific manner. |
459 Typically, the <i><agent-lib-name></i> is expanded to an |
493 Typically, the <i><agent-lib-name></i> is expanded to an |
460 operating system specific file name. |
494 operating system specific file name. |
461 The <i><options></i> will be passed to the agent on start-up. |
495 The <i><options></i> will be passed to the agent on start-up. |
462 For example, if the option |
496 For example, if the option |
463 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to |
497 <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> |
498 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 |
499 under <tm>Windows</tm> or <code>libfoo.so</code> from the |
466 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment. |
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/> |
467 </dd> |
505 </dd> |
468 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> |
506 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> |
469 <dd> |
507 <dd> |
470 The path following <code>-agentpath:</code> is the absolute path from which |
508 The path following <code>-agentpath:</code> is the absolute path from which |
471 to load the library. |
509 to load the library. |
472 No library name expansion will occur. |
510 No library name expansion will occur. |
473 The <i><options></i> will be passed to the agent on start-up. |
511 The <i><options></i> will be passed to the agent on start-up. |
474 For example, if the option |
512 For example, if the option |
475 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to |
513 <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>. |
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/> |
477 </dd> |
518 </dd> |
478 </dl> |
519 </dl> |
479 The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
520 For a dynamic shared library agent, the start-up routine |
480 in the library will be invoked. |
521 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
|
522 in the library will be invoked. If the agent library is statically linked |
|
523 into the executable then the system will attempt to invoke the |
|
524 <code>Agent_OnLoad_<agent-lib-name></code> entry point where |
|
525 <agent-lib-name> is the basename of the |
|
526 agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>, |
|
527 the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine. |
481 <p/> |
528 <p/> |
482 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> |
529 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> |
483 will be searched for JNI native method implementations to facilitate the |
530 will be searched for JNI native method implementations to facilitate the |
484 use of Java programming language code in tools, as is needed for |
531 use of Java programming language code in tools, as is needed for |
485 <internallink id="bci">bytecode instrumentation</internallink>. |
532 <internallink id="bci">bytecode instrumentation</internallink>. |
500 <intro id="startup" label="Agent Start-Up"> |
547 <intro id="startup" label="Agent Start-Up"> |
501 The VM starts each agent by invoking a start-up function. |
548 The VM starts each agent by invoking a start-up function. |
502 If the agent is started in the <code>OnLoad</code> |
549 If the agent is started in the <code>OnLoad</code> |
503 <functionlink id="GetPhase">phase</functionlink> the function |
550 <functionlink id="GetPhase">phase</functionlink> the function |
504 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
551 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
505 will be invoked. |
552 or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink> |
|
553 for statically linked agents will be invoked. |
506 If the agent is started in the live |
554 If the agent is started in the live |
507 <functionlink id="GetPhase">phase</functionlink> the function |
555 <functionlink id="GetPhase">phase</functionlink> the function |
508 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> |
556 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> |
509 will be invoked. |
557 or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink> |
|
558 for statically linked agents will be invoked. |
510 Exactly one call to a start-up function is made per agent. |
559 Exactly one call to a start-up function is made per agent. |
511 </intro> |
560 </intro> |
512 |
561 |
513 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> |
562 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> |
514 If an agent is started during the <code>OnLoad</code> phase then its |
563 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: |
564 agent library must export a start-up function with the following prototype: |
516 <example> |
565 <example> |
517 JNIEXPORT jint JNICALL |
566 JNIEXPORT jint JNICALL |
518 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> |
567 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> |
|
568 Or for a statically linked agent named 'L': |
|
569 <example> |
|
570 JNIEXPORT jint JNICALL |
|
571 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example> |
|
572 |
519 The VM will start the agent by calling this function. |
573 The VM will start the agent by calling this function. |
520 It will be called early enough in VM initialization that: |
574 It will be called early enough in VM initialization that: |
521 <ul> |
575 <ul> |
522 <li><functionlink id="SetSystemProperty">system properties</functionlink> |
576 <li><functionlink id="SetSystemProperty">system properties</functionlink> |
523 may be set before they have been used in the start-up of the VM</li> |
577 may be set before they have been used in the start-up of the VM</li> |
529 <li>no bytecodes have executed</li> |
583 <li>no bytecodes have executed</li> |
530 <li>no classes have been loaded</li> |
584 <li>no classes have been loaded</li> |
531 <li>no objects have been created</li> |
585 <li>no objects have been created</li> |
532 </ul> |
586 </ul> |
533 <p/> |
587 <p/> |
534 The VM will call the <code>Agent_OnLoad</code> function with |
588 The VM will call the <code>Agent_OnLoad</code> or |
|
589 <code>Agent_OnLoad_<agent-lib-name></code> function with |
535 <i><options></i> as the second argument - |
590 <i><options></i> as the second argument - |
536 that is, using the command-line option examples, |
591 that is, using the command-line option examples, |
537 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> |
592 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> |
538 argument of <code>Agent_OnLoad</code>. |
593 argument of <code>Agent_OnLoad</code>. |
539 The <code>options</code> argument is encoded as a |
594 The <code>options</code> argument is encoded as a |
540 <internallink id="mUTF">modified UTF-8</internallink> string. |
595 <internallink id="mUTF">modified UTF-8</internallink> string. |
541 If <i>=<options></i> is not specified, |
596 If <i>=<options></i> is not specified, |
542 a zero length string is passed to <code>options</code>. |
597 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> |
598 The lifespan of the <code>options</code> string is the |
|
599 <code>Agent_OnLoad</code> or <code>Agent_OnLoad_<agent-lib-name></code> |
544 call. If needed beyond this time the string or parts of the string must |
600 call. If needed beyond this time the string or parts of the string must |
545 be copied. |
601 be copied. |
546 The period between when <code>Agent_OnLoad</code> is called and when it |
602 The period between when <code>Agent_OnLoad</code> is called and when it |
547 returns is called the <i>OnLoad phase</i>. |
603 returns is called the <i>OnLoad phase</i>. |
548 Since the VM is not initialized during the OnLoad |
604 Since the VM is not initialized during the OnLoad |
585 must export a start-up function |
642 must export a start-up function |
586 with the following prototype: |
643 with the following prototype: |
587 <example> |
644 <example> |
588 JNIEXPORT jint JNICALL |
645 JNIEXPORT jint JNICALL |
589 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> |
646 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> |
|
647 Or for a statically linked agent named 'L': |
|
648 <example> |
|
649 JNIEXPORT jint JNICALL |
|
650 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example> |
|
651 |
590 <p/> |
652 <p/> |
591 The VM will start the agent by calling this function. |
653 The VM will start the agent by calling this function. |
592 It will be called in the context of a thread |
654 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. |
655 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. |
656 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 |
657 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 |
596 </internallink> string. |
658 </internallink> string. |
597 If startup options were not provided, a zero length string is passed to |
659 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 |
660 <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 |
661 <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call. |
600 the string must be copied. |
662 If needed beyond this time the string or parts of the string must be copied. |
601 <p/> |
663 <p/> |
602 Note that some <internallink id="capability">capabilities</internallink> |
664 Note that some <internallink id="capability">capabilities</internallink> |
603 may not be available in the live phase. |
665 may not be available in the live phase. |
604 <p/> |
666 <p/> |
605 The <code>Agent_OnAttach</code> function initializes the agent and returns a value |
667 The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name |
|
668 ></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. |
669 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 |
670 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, |
671 some implementation specific action -- for example it might print an error to standard error, |
609 or record the error in a system log. |
672 or record the error in a system log. |
610 </intro> |
673 </intro> |
613 The library may optionally export a |
676 The library may optionally export a |
614 shutdown function with the following prototype: |
677 shutdown function with the following prototype: |
615 <example> |
678 <example> |
616 JNIEXPORT void JNICALL |
679 JNIEXPORT void JNICALL |
617 Agent_OnUnload(JavaVM *vm)</example> |
680 Agent_OnUnload(JavaVM *vm)</example> |
|
681 Or for a statically linked agent named 'L': |
|
682 <example> |
|
683 JNIEXPORT void JNICALL |
|
684 Agent_OnUnload_L(JavaVM *vm)</example> |
|
685 |
618 This function will be called by the VM when the library is about to be unloaded. |
686 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 |
687 The library will be unloaded (unless it is statically linked into the |
|
688 executable) and this function will be called if some platform specific |
620 mechanism causes the unload (an unload mechanism is not specified in this document) |
689 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 |
690 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. |
691 normal termination or VM failure, including start-up failure. |
623 Uncontrolled shutdown is, of couse, an exception to this rule. |
692 Uncontrolled shutdown is, of couse, an exception to this rule. |
624 Note the distinction between this function and the |
693 Note the distinction between this function and the |
625 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event |
694 <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 |
695 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 |
696 <jvmti/> environment must exist which has set a callback for VMDeath |
628 and enabled the event |
697 and enabled the event. |
629 None of these are required for <code>Agent_OnUnload</code> and this function |
698 None of these are required for <code>Agent_OnUnload</code> or |
|
699 <code>Agent_OnUnload_<agent-lib-name></code> and this function |
630 is also called if the library is unloaded for other reasons. |
700 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 |
701 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). |
702 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. |
703 This function can be used to clean-up resources allocated by the agent. |
634 </intro> |
704 </intro> |
10699 Return the current phase of VM execution. |
10769 Return the current phase of VM execution. |
10700 The phases proceed in sequence: |
10770 The phases proceed in sequence: |
10701 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> |
10771 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> |
10702 <constant id="JVMTI_PHASE_ONLOAD" num="1"> |
10772 <constant id="JVMTI_PHASE_ONLOAD" num="1"> |
10703 <code>OnLoad</code> phase: while in the |
10773 <code>OnLoad</code> phase: while in the |
10704 <internallink id="onload"><code>Agent_OnLoad</code></internallink> function. |
10774 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
|
10775 or, for statically linked agents, the <internallink id="onload"> |
|
10776 <code>Agent_OnLoad_<agent-lib-name> |
|
10777 </code></internallink> function. |
10705 </constant> |
10778 </constant> |
10706 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> |
10779 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> |
10707 Primordial phase: between return from <code>Agent_OnLoad</code> and the |
10780 Primordial phase: between return from <code>Agent_OnLoad</code> |
|
10781 or <code>Agent_OnLoad_<agent-lib-name></code> and the |
10708 <code>VMStart</code> event. |
10782 <code>VMStart</code> event. |
10709 </constant> |
10783 </constant> |
10710 <constant id="JVMTI_PHASE_START" num="6"> |
10784 <constant id="JVMTI_PHASE_START" num="6"> |
10711 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event |
10785 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event |
10712 is sent and until the <code>VMInit</code> event is sent. |
10786 is sent and until the <code>VMInit</code> event is sent. |