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