IBM JVMTI extensions - API reference

Reference information for the IBM® SDK extensions to the JVMTI.

Setting JVM dump options

To set a JVM dump option use:
jvmtiError jvmtiSetVmDump(jvmtiEnv* jvmti_env, char* option)
The dump option is passed in as an ASCII character string. Use the same syntax as the -Xdump command-line option, with the initial -Xdump: omitted. See Using the -Xdump option.
When dumps are in progress, the dump configuration is locked, and calls to jvmtiSetVmDump() fail with a return value of JVMTI_ERROR_NOT_AVAILABLE.
Parameters:
jvmti_env: A pointer to the JVMTI environment.
option: The JVM dump option string.
Returns:
JVMTI_ERROR_NONE: Success.
JVMTI_ERROR_NULL_POINTER: The parameter option is null.
JVMTI_ERROR_OUT_OF_MEMORY: There is insufficient system memory to process the request.
JVMTI_ERROR_INVALID_ENVIRONMENT: The jvmti_env parameter is invalid.
JVMTI_ERROR_WRONG_PHASE: The extension has been called outside the JVMTI live phase.
JVMTI_ERROR_NOT_AVAILABLE: The dump configuration is locked because a dump is in progress.
JVMTI_ERROR_ILLEGAL_ARGUMENT: The parameter option contains an invalid -Xdump string.
Note: On z/OS®, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.

Querying JVM dump options

To query the current JVM dump options, use:
jvmtiError jvmtiQueryVmDump(jvmtiEnv* jvmti_env, jint buffer_size, void* options_buffer, jint* data_size_ptr)
This extension returns a set of dump option specifications as ASCII strings. The syntax of the option string is the same as the -Xdump command-line option, with the initial -Xdump: omitted. See Using the -Xdump option. The option strings are separated by newline characters. If the memory buffer is too small to contain the current JVM dump option strings, you can expect the following results:
  • The error message JVMTI_ERROR_ILLEGAL_ARGUMENT is returned.
  • The variable for data_size_ptr is set to the required buffer size.
Parameters:
jvmti_env: A pointer to the JVMTI environment.
buffer_size: The size of the supplied memory buffer in bytes.
options_buffer: A pointer to the supplied memory buffer.
data_size_ptr: A pointer to a variable, used to return the total size of the option strings.
Returns:
JVMTI_ERROR_NONE: Success
JVMTI_ERROR_NULL_POINTER: The options_buffer or data_size_ptr parameters are null.
JVMTI_ERROR_OUT_OF_MEMORY: There is insufficient system memory to process the request.
JVMTI_ERROR_INVALID_ENVIRONMENT: The jvmti_env parameter is invalid.
JVMTI_ERROR_WRONG_PHASE: The extension has been called outside the JVMTI live phase.
JVMTI_ERROR_NOT_AVAILABLE: The dump configuration is locked because a dump is in progress.
JVMTI_ERROR_ILLEGAL_ARGUMENT: The supplied memory buffer in options_buffer is too small.

Resetting JVM dump options

To reset the JVM dump options to the values at JVM initialization, use:
jvmtiError jvmtiResetVmDump(jvmtiEnv* jvmti_env)
Parameters:
jvmti_env: The JVMTI environment pointer.
Returns:
JVMTI_ERROR_NONE: Success.
JVMTI_ERROR_OUT_OF_MEMORY: There is insufficient system memory to process the request.
JVMTI_ERROR_INVALID_ENVIRONMENT: The jvmti_env parameter is invalid.
JVMTI_ERROR_WRONG_PHASE: The extension has been called outside the JVMTI live phase.
JVMTI_ERROR_NOT_AVAILABLE: The dump configuration is locked because a dump is in progress.

Triggering a JVM dump

To trigger a JVM dump, use:
jvmtiError jvmtiTriggerVmDump(jvmtiEnv* jvmti_env, char* option)
Choose the type of dump required by specifying an ASCII string that contains one of the supported dump agent types. See Dump agents. JVMTI events are provided at the start and end of the dump.
Parameters:
jvmti_env: A pointer to the JVMTI environment.
option: A pointer to the dump type string, which can be one of the following types:
  • stack
  • java
  • system
  • console
  • tool
  • heap
  • snap
  • ceedump (z/OS only)
Returns:
JVMTI_ERROR_NONE: Success.
JVMTI_ERROR_NULL_POINTER: The option parameter is null.
JVMTI_ERROR_OUT_OF_MEMORY: There is insufficient system memory to process the request.
JVMTI_ERROR_INVALID_ENVIRONMENT: The jvmti_env parameter is invalid.
JVMTI_ERROR_WRONG_PHASE: The extension has been called outside the JVMTI live phase.
JVMTI_ERROR_NOT_AVAILABLE: The dump configuration is locked because a dump is in progress.
Note: On z/OS, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.

Setting JVM trace options

To set a JVM trace option, use:
jvmtiError jvmtiSetVmTrace(jvmtiEnv* jvmti_env, char* option)
The trace option is passed in as an ASCII character string. Use the same syntax as the -Xtrace command-line option, with the initial -Xtrace: omitted. See Detailed descriptions of trace options.
Parameters:
jvmti_env: JVMTI environment pointer.
option: Enter the JVM trace option string.
Returns:
JVMTI_ERROR_NONE: Success.
JVMTI_ERROR_NULL_POINTER: The option parameter is null.
JVMTI_ERROR_OUT_OF_MEMORY: There is insufficient system memory to process the request.
JVMTI_ERROR_INVALID_ENVIRONMENT: The jvmti_env parameter is invalid.
JVMTI_ERROR_WRONG_PHASE: The extension has been called outside the JVMTI live phase.
JVMTI_ERROR_ILLEGAL_ARGUMENT: The option parameter contains an invalid -Xtrace string.
Note: On z/OS, you might need to convert the option string from EBCDIC to ASCII before using this JVMTI extension function.

JVMTI event function - start dump

The following JVMTI event function is called when a JVM dump starts.
void JNICALL
VMDumpStart(jvmtiEnv *jvmti_env, JNIEnv* jni_env, char* label, char* event, char* detail)
The event function provides the dump file name and the name of the JVM event that triggered the dump. For more information about dump events, see Dump events.
Parameters:
jvmti_env: JVMTI environment pointer.
jni_env: JNI environment pointer for the thread on which the event occurred.
label: The dump file name, including directory path.
event: The extension event name, such as com.ibm.VmDumpStart.
detail: The dump event name.
Returns:
None

JVMTI event function - end dump

The following JVMTI event function is called when a JVM dump ends.
void JNICALL
VMDumpEnd(jvmtiEnv *jvmti_env, JNIEnv* jni_env, char* label, char* event, char* detail)
This event function provides the dump file name and the name of the JVM event that triggered the dump. For more information about dump events, see Dump events.
Parameters:
jvmti_env: JVMTI environment pointer.
jni_env: JNI environment pointer for the thread on which the event occurred.
label: The dump file name, including directory path.
event: The extension event name, such as com.ibm.VmDumpStart.
detail: The dump event name.
Returns:
None


© Copyright IBM Corporation 2005, 2010. All Rights Reserved.
© Copyright Sun Microsystems, Inc. 1997, 2007, 901 San Antonio Rd., Palo Alto, CA 94303 USA. All rights reserved.
US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
This information center is powered by Eclipse technology. (http://www.eclipse.org/)