Mercurial > hg > truffle
comparison src/share/vm/prims/jvmti.xml @ 12355:cefad50507d8
Merge with hs25-b53
author | Gilles Duboscq <duboscq@ssw.jku.at> |
---|---|
date | Fri, 11 Oct 2013 10:38:03 +0200 |
parents | 8e94527f601e |
children |
comparison
equal
deleted
inserted
replaced
12058:ccb4f2af2319 | 12355:cefad50507d8 |
---|---|
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. |
356 ]> | 356 ]> |
357 | 357 |
358 <specification label="JVM(TM) Tool Interface" | 358 <specification label="JVM(TM) Tool Interface" |
359 majorversion="1" | 359 majorversion="1" |
360 minorversion="2" | 360 minorversion="2" |
361 microversion="2"> | 361 microversion="3"> |
362 <title subtitle="Version"> | 362 <title subtitle="Version"> |
363 <tm>JVM</tm> Tool Interface | 363 <tm>JVM</tm> Tool Interface |
364 </title> | 364 </title> |
365 | 365 |
366 <intro id="whatIs" label="What is the JVM Tool Interface?"> | 366 <intro id="whatIs" label="What is the JVM Tool Interface?"> |
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 VM execution as it would | |
462 have called the dynamic entry point Agent_OnUnLoad. A statically loaded | |
463 agent cannot be unloaded. The Agent_OnUnload_L function will still be | |
464 called to do any other agent shutdown related tasks. | |
465 If a <i>statically linked</i> agent L exports a function called | |
466 Agent_OnUnLoad_L and a function called Agent_OnUnLoad, the Agent_OnUnLoad | |
467 function will be ignored. | |
468 <p/> | |
469 If an agent L is <i>statically linked</i>, an Agent_OnAttach_L function | |
470 will be invoked with the same arguments and expected return value as | |
471 specified for the Agent_OnAttach function. | |
472 If a <i>statically linked</i> agent L exports a function called | |
473 Agent_OnAttach_L and a function called Agent_OnAttach, the Agent_OnAttach | |
474 function will be ignored. | |
475 </intro> | |
440 | 476 |
441 <intro id="starting" label="Agent Command Line Options"> | 477 <intro id="starting" label="Agent Command Line Options"> |
442 The term "command-line option" is used below to | 478 The term "command-line option" is used below to |
443 mean options supplied in the <code>JavaVMInitArgs</code> argument | 479 mean options supplied in the <code>JavaVMInitArgs</code> argument |
444 to the <code>JNI_CreateJavaVM</code> function of the JNI | 480 to the <code>JNI_CreateJavaVM</code> function of the JNI |
453 <dl> | 489 <dl> |
454 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> | 490 <dt><code>-agentlib:</code><i><agent-lib-name></i><code>=</code><i><options></i></dt> |
455 <dd> | 491 <dd> |
456 The name following <code>-agentlib:</code> is the name of the | 492 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, | 493 library to load. Lookup of the library, both its full name and location, |
458 proceeds in a platform-specific manner. | 494 proceeds in a platform-specific manner. |
459 Typically, the <i><agent-lib-name></i> is expanded to an | 495 Typically, the <i><agent-lib-name></i> is expanded to an |
460 operating system specific file name. | 496 operating system specific file name. |
461 The <i><options></i> will be passed to the agent on start-up. | 497 The <i><options></i> will be passed to the agent on start-up. |
462 For example, if the option | 498 For example, if the option |
463 <code>-agentlib:foo=opt1,opt2</code> is specified, the VM will attempt to | 499 <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> | 500 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 | 501 under <tm>Windows</tm> or <code>libfoo.so</code> from the |
466 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating environment. | 502 <code>LD_LIBRARY_PATH</code> under the <tm>Solaris</tm> operating |
503 environment. | |
504 If the agent library is statically linked into the executable | |
505 then no actual loading takes place. | |
506 <p/> | |
467 </dd> | 507 </dd> |
468 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> | 508 <dt><code>-agentpath:</code><i><path-to-agent></i><code>=</code><i><options></i></dt> |
469 <dd> | 509 <dd> |
470 The path following <code>-agentpath:</code> is the absolute path from which | 510 The path following <code>-agentpath:</code> is the absolute path from which |
471 to load the library. | 511 to load the library. |
472 No library name expansion will occur. | 512 No library name expansion will occur. |
473 The <i><options></i> will be passed to the agent on start-up. | 513 The <i><options></i> will be passed to the agent on start-up. |
474 For example, if the option | 514 For example, if the option |
475 <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code> is specified, the VM will attempt to | 515 <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>. | 516 load the shared library <code>c:\myLibs\foo.dll</code>. If the agent |
517 library is statically linked into the executable | |
518 then no actual loading takes place. | |
519 <p/> | |
477 </dd> | 520 </dd> |
478 </dl> | 521 </dl> |
479 The start-up routine <internallink id="onload"><code>Agent_OnLoad</code></internallink> | 522 For a dynamic shared library agent, the start-up routine |
480 in the library will be invoked. | 523 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
524 in the library will be invoked. If the agent library is statically linked | |
525 into the executable then the system will attempt to invoke the | |
526 <code>Agent_OnLoad_<agent-lib-name></code> entry point where | |
527 <agent-lib-name> is the basename of the | |
528 agent. In the above example <code>-agentpath:c:\myLibs\foo.dll=opt1,opt2</code>, | |
529 the system will attempt to find and call the <code>Agent_OnLoad_foo</code> start-up routine. | |
481 <p/> | 530 <p/> |
482 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> | 531 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code> |
483 will be searched for JNI native method implementations to facilitate the | 532 will be searched for JNI native method implementations to facilitate the |
484 use of Java programming language code in tools, as is needed for | 533 use of Java programming language code in tools, as is needed for |
485 <internallink id="bci">bytecode instrumentation</internallink>. | 534 <internallink id="bci">bytecode instrumentation</internallink>. |
500 <intro id="startup" label="Agent Start-Up"> | 549 <intro id="startup" label="Agent Start-Up"> |
501 The VM starts each agent by invoking a start-up function. | 550 The VM starts each agent by invoking a start-up function. |
502 If the agent is started in the <code>OnLoad</code> | 551 If the agent is started in the <code>OnLoad</code> |
503 <functionlink id="GetPhase">phase</functionlink> the function | 552 <functionlink id="GetPhase">phase</functionlink> the function |
504 <internallink id="onload"><code>Agent_OnLoad</code></internallink> | 553 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
505 will be invoked. | 554 or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink> |
555 for statically linked agents will be invoked. | |
506 If the agent is started in the live | 556 If the agent is started in the live |
507 <functionlink id="GetPhase">phase</functionlink> the function | 557 <functionlink id="GetPhase">phase</functionlink> the function |
508 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> | 558 <internallink id="onattach"><code>Agent_OnAttach</code></internallink> |
509 will be invoked. | 559 or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink> |
560 for statically linked agents will be invoked. | |
510 Exactly one call to a start-up function is made per agent. | 561 Exactly one call to a start-up function is made per agent. |
511 </intro> | 562 </intro> |
512 | 563 |
513 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> | 564 <intro id="onload" label="Agent Start-Up (OnLoad phase)"> |
514 If an agent is started during the <code>OnLoad</code> phase then its | 565 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: | 566 agent library must export a start-up function with the following prototype: |
516 <example> | 567 <example> |
517 JNIEXPORT jint JNICALL | 568 JNIEXPORT jint JNICALL |
518 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> | 569 Agent_OnLoad(JavaVM *vm, char *options, void *reserved)</example> |
570 Or for a statically linked agent named 'L': | |
571 <example> | |
572 JNIEXPORT jint JNICALL | |
573 Agent_OnLoad_L(JavaVM *vm, char *options, void *reserved)</example> | |
574 | |
519 The VM will start the agent by calling this function. | 575 The VM will start the agent by calling this function. |
520 It will be called early enough in VM initialization that: | 576 It will be called early enough in VM initialization that: |
521 <ul> | 577 <ul> |
522 <li><functionlink id="SetSystemProperty">system properties</functionlink> | 578 <li><functionlink id="SetSystemProperty">system properties</functionlink> |
523 may be set before they have been used in the start-up of the VM</li> | 579 may be set before they have been used in the start-up of the VM</li> |
529 <li>no bytecodes have executed</li> | 585 <li>no bytecodes have executed</li> |
530 <li>no classes have been loaded</li> | 586 <li>no classes have been loaded</li> |
531 <li>no objects have been created</li> | 587 <li>no objects have been created</li> |
532 </ul> | 588 </ul> |
533 <p/> | 589 <p/> |
534 The VM will call the <code>Agent_OnLoad</code> function with | 590 The VM will call the <code>Agent_OnLoad</code> or |
591 <code>Agent_OnLoad_<agent-lib-name></code> function with | |
535 <i><options></i> as the second argument - | 592 <i><options></i> as the second argument - |
536 that is, using the command-line option examples, | 593 that is, using the command-line option examples, |
537 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> | 594 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code> |
538 argument of <code>Agent_OnLoad</code>. | 595 argument of <code>Agent_OnLoad</code>. |
539 The <code>options</code> argument is encoded as a | 596 The <code>options</code> argument is encoded as a |
540 <internallink id="mUTF">modified UTF-8</internallink> string. | 597 <internallink id="mUTF">modified UTF-8</internallink> string. |
541 If <i>=<options></i> is not specified, | 598 If <i>=<options></i> is not specified, |
542 a zero length string is passed to <code>options</code>. | 599 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> | 600 The lifespan of the <code>options</code> string is the |
601 <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 | 602 call. If needed beyond this time the string or parts of the string must |
545 be copied. | 603 be copied. |
546 The period between when <code>Agent_OnLoad</code> is called and when it | 604 The period between when <code>Agent_OnLoad</code> is called and when it |
547 returns is called the <i>OnLoad phase</i>. | 605 returns is called the <i>OnLoad phase</i>. |
548 Since the VM is not initialized during the OnLoad | 606 Since the VM is not initialized during the OnLoad |
568 Early startup is also needed so that agents can control the execution | 626 Early startup is also needed so that agents can control the execution |
569 environment - modifying the file system and system properties to install | 627 environment - modifying the file system and system properties to install |
570 their functionality. | 628 their functionality. |
571 </rationale> | 629 </rationale> |
572 <p/> | 630 <p/> |
573 The return value from <code>Agent_OnLoad</code> is used to indicate an error. | 631 The return value from <code>Agent_OnLoad</code> or |
632 <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error. | |
574 Any value other than zero indicates an error and causes termination of the VM. | 633 Any value other than zero indicates an error and causes termination of the VM. |
575 </intro> | 634 </intro> |
576 | 635 |
577 <intro id="onattach" label="Agent Start-Up (Live phase)"> | 636 <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 | 637 A VM may support a mechanism that allows agents to be started in the VM during the live |
585 must export a start-up function | 644 must export a start-up function |
586 with the following prototype: | 645 with the following prototype: |
587 <example> | 646 <example> |
588 JNIEXPORT jint JNICALL | 647 JNIEXPORT jint JNICALL |
589 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> | 648 Agent_OnAttach(JavaVM* vm, char *options, void *reserved)</example> |
649 Or for a statically linked agent named 'L': | |
650 <example> | |
651 JNIEXPORT jint JNICALL | |
652 Agent_OnAttach_L(JavaVM* vm, char *options, void *reserved)</example> | |
653 | |
590 <p/> | 654 <p/> |
591 The VM will start the agent by calling this function. | 655 The VM will start the agent by calling this function. |
592 It will be called in the context of a thread | 656 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. | 657 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. | 658 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 | 659 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8 |
596 </internallink> string. | 660 </internallink> string. |
597 If startup options were not provided, a zero length string is passed to | 661 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 | 662 <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 | 663 <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call. |
600 the string must be copied. | 664 If needed beyond this time the string or parts of the string must be copied. |
601 <p/> | 665 <p/> |
602 Note that some <internallink id="capability">capabilities</internallink> | 666 Note that some <internallink id="capability">capabilities</internallink> |
603 may not be available in the live phase. | 667 may not be available in the live phase. |
604 <p/> | 668 <p/> |
605 The <code>Agent_OnAttach</code> function initializes the agent and returns a value | 669 The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name |
670 ></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. | 671 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 | 672 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, | 673 some implementation specific action -- for example it might print an error to standard error, |
609 or record the error in a system log. | 674 or record the error in a system log. |
610 </intro> | 675 </intro> |
613 The library may optionally export a | 678 The library may optionally export a |
614 shutdown function with the following prototype: | 679 shutdown function with the following prototype: |
615 <example> | 680 <example> |
616 JNIEXPORT void JNICALL | 681 JNIEXPORT void JNICALL |
617 Agent_OnUnload(JavaVM *vm)</example> | 682 Agent_OnUnload(JavaVM *vm)</example> |
683 Or for a statically linked agent named 'L': | |
684 <example> | |
685 JNIEXPORT void JNICALL | |
686 Agent_OnUnload_L(JavaVM *vm)</example> | |
687 | |
618 This function will be called by the VM when the library is about to be unloaded. | 688 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 | 689 The library will be unloaded (unless it is statically linked into the |
690 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) | 691 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 | 692 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. | 693 normal termination or VM failure, including start-up failure. |
623 Uncontrolled shutdown is, of couse, an exception to this rule. | 694 Uncontrolled shutdown is, of couse, an exception to this rule. |
624 Note the distinction between this function and the | 695 Note the distinction between this function and the |
625 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event | 696 <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 | 697 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 | 698 <jvmti/> environment must exist which has set a callback for VMDeath |
628 and enabled the event | 699 and enabled the event. |
629 None of these are required for <code>Agent_OnUnload</code> and this function | 700 None of these are required for <code>Agent_OnUnload</code> or |
701 <code>Agent_OnUnload_<agent-lib-name></code> and this function | |
630 is also called if the library is unloaded for other reasons. | 702 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 | 703 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). | 704 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. | 705 This function can be used to clean-up resources allocated by the agent. |
634 </intro> | 706 </intro> |
10699 Return the current phase of VM execution. | 10771 Return the current phase of VM execution. |
10700 The phases proceed in sequence: | 10772 The phases proceed in sequence: |
10701 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> | 10773 <constants id="jvmtiPhase" label="Phases of execution" kind="enum"> |
10702 <constant id="JVMTI_PHASE_ONLOAD" num="1"> | 10774 <constant id="JVMTI_PHASE_ONLOAD" num="1"> |
10703 <code>OnLoad</code> phase: while in the | 10775 <code>OnLoad</code> phase: while in the |
10704 <internallink id="onload"><code>Agent_OnLoad</code></internallink> function. | 10776 <internallink id="onload"><code>Agent_OnLoad</code></internallink> |
10777 or, for statically linked agents, the <internallink id="onload"> | |
10778 <code>Agent_OnLoad_<agent-lib-name> | |
10779 </code></internallink> function. | |
10705 </constant> | 10780 </constant> |
10706 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> | 10781 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2"> |
10707 Primordial phase: between return from <code>Agent_OnLoad</code> and the | 10782 Primordial phase: between return from <code>Agent_OnLoad</code> |
10783 or <code>Agent_OnLoad_<agent-lib-name></code> and the | |
10708 <code>VMStart</code> event. | 10784 <code>VMStart</code> event. |
10709 </constant> | 10785 </constant> |
10710 <constant id="JVMTI_PHASE_START" num="6"> | 10786 <constant id="JVMTI_PHASE_START" num="6"> |
10711 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event | 10787 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event |
10712 is sent and until the <code>VMInit</code> event is sent. | 10788 is sent and until the <code>VMInit</code> event is sent. |
14259 Add ResourceExhaustedEvent. | 14335 Add ResourceExhaustedEvent. |
14260 </change> | 14336 </change> |
14261 <change date="11 October 2012" version="1.2.2"> | 14337 <change date="11 October 2012" version="1.2.2"> |
14262 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. | 14338 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool. |
14263 </change> | 14339 </change> |
14340 <change date="19 June 2013" version="1.2.3"> | |
14341 Added support for statically linked agents. | |
14342 </change> | |
14264 </changehistory> | 14343 </changehistory> |
14265 | 14344 |
14266 </specification> | 14345 </specification> |
14267 <!-- Keep this comment at the end of the file | 14346 <!-- Keep this comment at the end of the file |
14268 Local variables: | 14347 Local variables: |