1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
3 <!--
4 Copyright (c) 2002, 2012, Oracle and/or its affiliates. All rights reserved.
5 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
6
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
9 published by the Free Software Foundation.
10
11 This code is distributed in the hope that it will be useful, but WITHOUT
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 version 2 for more details (a copy is included in the LICENSE file that
15 accompanied this code).
16
17 You should have received a copy of the GNU General Public License version
18 2 along with this work; if not, write to the Free Software Foundation,
19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20
21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 or visit www.oracle.com if you need additional information or have any
23 questions.
24
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:
|
1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <?xml-stylesheet type="text/xsl" href="jvmti.xsl"?>
3 <!--
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.
6
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
9 published by the Free Software Foundation.
10
11 This code is distributed in the hope that it will be useful, but WITHOUT
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 version 2 for more details (a copy is included in the LICENSE file that
15 accompanied this code).
16
17 You should have received a copy of the GNU General Public License version
18 2 along with this work; if not, write to the Free Software Foundation,
19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20
21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 or visit www.oracle.com if you need additional information or have any
23 questions.
24
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
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.
528 <p/>
529 Libraries loaded with <code>-agentlib:</code> or <code>-agentpath:</code>
530 will be searched for JNI native method implementations to facilitate the
531 use of Java programming language code in tools, as is needed for
532 <internallink id="bci">bytecode instrumentation</internallink>.
533 <p/>
534 The agent libraries will be searched after all other libraries have been
535 searched (agents wishing to override or intercept the native method
536 implementations of non-agent methods can use the
537 <eventlink id="NativeMethodBind">NativeMethodBind event</eventlink>).
538 <p/>
539 These switches do the above and nothing more - they do not change the
540 state of the VM or <jvmti/>. No command line options are needed
541 to enable <jvmti/>
542 or aspects of <jvmti/>, this is handled programmatically
543 by the use of
544 <internallink id="capability">capabilities</internallink>.
545 </intro>
546
547 <intro id="startup" label="Agent Start-Up">
548 The VM starts each agent by invoking a start-up function.
549 If the agent is started in the <code>OnLoad</code>
550 <functionlink id="GetPhase">phase</functionlink> the function
551 <internallink id="onload"><code>Agent_OnLoad</code></internallink>
552 or <internallink id="onload"><code>Agent_OnLoad_L</code></internallink>
553 for statically linked agents will be invoked.
554 If the agent is started in the live
555 <functionlink id="GetPhase">phase</functionlink> the function
556 <internallink id="onattach"><code>Agent_OnAttach</code></internallink>
557 or <internallink id="onattach"><code>Agent_OnAttach_L</code></internallink>
558 for statically linked agents will be invoked.
559 Exactly one call to a start-up function is made per agent.
560 </intro>
561
562 <intro id="onload" label="Agent Start-Up (OnLoad phase)">
563 If an agent is started during the <code>OnLoad</code> phase then its
564 agent library must export a start-up function with the following prototype:
565 <example>
566 JNIEXPORT jint JNICALL
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
573 The VM will start the agent by calling this function.
574 It will be called early enough in VM initialization that:
575 <ul>
576 <li><functionlink id="SetSystemProperty">system properties</functionlink>
577 may be set before they have been used in the start-up of the VM</li>
578 <li>the full set of
579 <internallink id="capability">capabilities</internallink>
580 is still available (note that capabilities that configure the VM
581 may only be available at this time--see the
582 <internallink id="capability">Capability function section</internallink>)</li>
583 <li>no bytecodes have executed</li>
584 <li>no classes have been loaded</li>
585 <li>no objects have been created</li>
586 </ul>
587 <p/>
588 The VM will call the <code>Agent_OnLoad</code> or
589 <code>Agent_OnLoad_<agent-lib-name></code> function with
590 <i><options></i> as the second argument -
591 that is, using the command-line option examples,
592 <code>"opt1,opt2"</code> will be passed to the <code>char *options</code>
593 argument of <code>Agent_OnLoad</code>.
594 The <code>options</code> argument is encoded as a
595 <internallink id="mUTF">modified UTF-8</internallink> string.
596 If <i>=<options></i> is not specified,
597 a zero length string is passed to <code>options</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>
600 call. If needed beyond this time the string or parts of the string must
601 be copied.
602 The period between when <code>Agent_OnLoad</code> is called and when it
603 returns is called the <i>OnLoad phase</i>.
604 Since the VM is not initialized during the OnLoad
605 <functionlink id="GetPhase">phase</functionlink>,
606 the set of allowed operations
607 inside <code>Agent_OnLoad</code> is restricted (see the function descriptions for the
608 functionality available at this time).
609 The agent can safely process the options and set
610 event callbacks with <functionlink id="SetEventCallbacks"></functionlink>. Once
611 the VM initialization event is received
612 (that is, the <eventlink id="VMInit">VMInit</eventlink>
613 callback is invoked), the agent
614 can complete its initialization.
615 <rationale>
616 Early startup is required so that agents can set the desired capabilities,
617 many of which must be set before the VM is initialized.
618 In JVMDI, the -Xdebug command-line option provided
619 very coarse-grain control of capabilities.
620 JVMPI implementations use various tricks to provide a single "JVMPI on" switch.
621 No reasonable command-line
622 option could provide the fine-grain of control required to balance needed capabilities vs
623 performance impact.
624 Early startup is also needed so that agents can control the execution
625 environment - modifying the file system and system properties to install
626 their functionality.
627 </rationale>
628 <p/>
629 The return value from <code>Agent_OnLoad</code> or
630 <code>Agent_OnLoad_<agent-lib-name></code> is used to indicate an error.
631 Any value other than zero indicates an error and causes termination of the VM.
632 </intro>
633
634 <intro id="onattach" label="Agent Start-Up (Live phase)">
635 A VM may support a mechanism that allows agents to be started in the VM during the live
636 <functionlink id="GetPhase">phase</functionlink>. The details of how this is supported,
637 are implementation specific. For example, a tool may use some platform specific mechanism,
638 or implementation specific API, to attach to the running VM, and request it start a given
639 agent.
640 <p/>
641 If an agent is started during the live phase then its agent library
642 must export a start-up function
643 with the following prototype:
644 <example>
645 JNIEXPORT jint JNICALL
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
652 <p/>
653 The VM will start the agent by calling this function.
654 It will be called in the context of a thread
655 that is attached to the VM. The first argument <i><vm></i> is the Java VM.
656 The <i><options></i> argument is the startup options provided to the agent.
657 <i><options></i> is encoded as a <internallink id="mUTF">modified UTF-8
658 </internallink> string.
659 If startup options were not provided, a zero length string is passed to
660 <code>options</code>. The lifespan of the <code>options</code> string is the
661 <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name></code> call.
662 If needed beyond this time the string or parts of the string must be copied.
663 <p/>
664 Note that some <internallink id="capability">capabilities</internallink>
665 may not be available in the live phase.
666 <p/>
667 The <code>Agent_OnAttach</code> or <code>Agent_OnAttach_<agent-lib-name
668 ></code> function initializes the agent and returns a value
669 to the VM to indicate if an error occurred. Any value other than zero indicates an error.
670 An error does not cause the VM to terminate. Instead the VM ignores the error, or takes
671 some implementation specific action -- for example it might print an error to standard error,
672 or record the error in a system log.
673 </intro>
674
675 <intro id="onunload" label="Agent Shutdown">
676 The library may optionally export a
677 shutdown function with the following prototype:
678 <example>
679 JNIEXPORT void JNICALL
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
686 This function will be called by the VM when the library is about to be unloaded.
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
689 mechanism causes the unload (an unload mechanism is not specified in this document)
690 or the library is (in effect) unloaded by the termination of the VM whether through
691 normal termination or VM failure, including start-up failure.
692 Uncontrolled shutdown is, of couse, an exception to this rule.
693 Note the distinction between this function and the
694 <eventlink id="VMDeath">VM Death event</eventlink>: for the VM Death event
695 to be sent, the VM must have run at least to the point of initialization and a valid
696 <jvmti/> environment must exist which has set a callback for VMDeath
697 and enabled the event.
698 None of these are required for <code>Agent_OnUnload</code> or
699 <code>Agent_OnUnload_<agent-lib-name></code> and this function
700 is also called if the library is unloaded for other reasons.
701 In the case that a VM Death event is sent, it will be sent before this
702 function is called (assuming this function is called due to VM termination).
703 This function can be used to clean-up resources allocated by the agent.
704 </intro>
705
706 <intro id="tooloptions" label="JAVA_TOOL_OPTIONS">
707 Since the command-line cannot always be accessed or modified, for example in embedded VMs
708 or simply VMs launched deep within scripts, a <code>JAVA_TOOL_OPTIONS</code> variable is
709 provided so that agents may be launched in these cases.
710 <p/>
711 Platforms which support environment variables or other named strings, may support the
712 <code>JAVA_TOOL_OPTIONS</code> variable. This variable will be broken into options at white-space
713 boundaries. White-space characters include space, tab, carriage-return, new-line,
714 vertical-tab, and form-feed. Sequences of white-space characters are considered
715 equivalent to a single white-space character. No white-space is included in the options
716 unless quoted. Quoting is as follows:
717 <ul>
718 <li>All characters enclosed between a pair of single quote marks (''), except a single
719 quote, are quoted.</li>
10754 This property is not available or is not writeable.
10755 </error>
10756 </errors>
10757 </function>
10758
10759 </category>
10760
10761 <category id="general" label="General">
10762
10763 <intro>
10764 </intro>
10765
10766 <function id="GetPhase" jkernel="yes" phase="any" num="133">
10767 <synopsis>Get Phase</synopsis>
10768 <description>
10769 Return the current phase of VM execution.
10770 The phases proceed in sequence:
10771 <constants id="jvmtiPhase" label="Phases of execution" kind="enum">
10772 <constant id="JVMTI_PHASE_ONLOAD" num="1">
10773 <code>OnLoad</code> phase: while in the
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.
10778 </constant>
10779 <constant id="JVMTI_PHASE_PRIMORDIAL" num="2">
10780 Primordial phase: between return from <code>Agent_OnLoad</code>
10781 or <code>Agent_OnLoad_<agent-lib-name></code> and the
10782 <code>VMStart</code> event.
10783 </constant>
10784 <constant id="JVMTI_PHASE_START" num="6">
10785 Start phase: when the <eventlink id="VMStart"><code>VMStart</code></eventlink> event
10786 is sent and until the <code>VMInit</code> event is sent.
10787 </constant>
10788 <constant id="JVMTI_PHASE_LIVE" num="4">
10789 Live phase: when the <eventlink id="VMInit"><code>VMInit</code></eventlink> event is sent
10790 and until the <eventlink id="VMDeath"></eventlink> event returns.
10791 </constant>
10792 <constant id="JVMTI_PHASE_DEAD" num="8">
10793 Dead phase: after the <eventlink id="VMDeath"></eventlink> event returns or after
10794 start-up failure.
10795 </constant>
10796 </constants>
10797 In the case of start-up failure the VM will proceed directly to the dead
10798 phase skipping intermediate phases and neither a <code>VMInit</code> nor
10799 <code>VMDeath</code> event will be sent.
10800 <p/>
10801 Most <jvmti/> functions operate only in the live phase.
14317 </change>
14318 <change date="28 June 2006" version="1.1.98">
14319 Clarify DisposeEnvironment; add warning.
14320 Fix typos in SetLocalXXX "retrieve" => "set".
14321 Clarify that native method prefixes must remain set while used.
14322 Clarify that exactly one Agent_OnXXX is called per agent.
14323 Clarify that library loading is independent from start-up.
14324 Remove ambiguous reference to Agent_OnLoad in the Agent_OnUnload spec.
14325 </change>
14326 <change date="31 July 2006" version="1.1.99">
14327 Clarify the interaction between functions and exceptions.
14328 Clarify and give examples of field indices.
14329 Remove confusing "That is" sentence from MonitorWait and MonitorWaited events.
14330 Update links to point to Java 6.
14331 </change>
14332 <change date="6 August 2006" version="1.1.102">
14333 Add ResourceExhaustedEvent.
14334 </change>
14335 <change date="11 October 2012" version="1.2.2">
14336 Fixed the "HTTP" and "Missing Anchor" errors reported by the LinkCheck tool.
14337 </change>
14338 <change date="19 June 2013" version="1.2.3">
14339 Added support for statically linked agents.
14340 </change>
14341 </changehistory>
14342
14343 </specification>
14344 <!-- Keep this comment at the end of the file
14345 Local variables:
14346 mode: sgml
14347 sgml-omittag:t
14348 sgml-shorttag:t
14349 sgml-namecase-general:t
14350 sgml-general-insert-case:lower
14351 sgml-minimize-attributes:nil
14352 sgml-always-quote-attributes:t
14353 sgml-indent-step:2
14354 sgml-indent-data:t
14355 sgml-parent-document:nil
14356 sgml-exposed-tags:nil
14357 sgml-local-catalogs:nil
14358 sgml-local-ecat-files:nil
14359 End:
|