Expand description
§jni-simple
This crate contains a simple dumb handwritten rust wrapper around the JNI (Java Native Interface) API. It does absolutely no magic around the JNI Calls and lets you just use it as you would in C.
In addition to JNI, this crate also provides a similar simplistic wrapper for the JVMTI (Java VM Tool Interface) API. The JVMTI Api can be used to write, for example, a Java Agent (like a Java debugger) in Rust or perform similar deep instrumentation with the JVM.
If you are looking to start a jvm from rust then the entrypoints in this create are
init_dynamic_link
, load_jvm_from_library
, JNI_CreateJavaVM
and JNI_GetCreatedJavaVMs
.
If you are looking to write a jni library in rust then the types JNIEnv
and jclass, etc.
should be sufficient.
Macros§
- jtypes
- This macro is usefull for constructing jtype arrays. This is often needed when making upcalls into the jvm with many arguments using the ‘A’ type functions:
Structs§
- JNIEnv
- JNINative
Method - JVMTI
Env - JavaVM
- JavaVM
Attach Args - JavaVM
Init Args - JavaVM
Option - jniNative
Interface - jvmti
Addr Location Map - jvmti
Capabilities - jvmti
Class Definition - jvmti
Error - jvmti
Event Callbacks - jvmti
Extension Event Info - jvmti
Extension Function Info - jvmti
Heap Callbacks - jvmti
Heap Reference Info Array - jvmti
Heap Reference Info Constant Pool - jvmti
Heap Reference Info Field - jvmti
Heap Reference Info JniLocal - jvmti
Heap Reference Info Reserved - jvmti
Heap Reference Info Stack Local - jvmti
Line Number Entry - jvmti
Local Variable Entry - jvmti
Monitor Stack Depth Info - jvmti
Monitor Usage - jvmti
Param Info - jvmti
Thread Group Info - jvmti
Thread Info - jvmti
Timer Info
Enums§
- JNILinkage
- Enum of all known jni linkage numbers This is mostly useful for use with jvmti when hooking jvm functions.
- Jvmti
Error - Rust enum that mirrors jvmtiError, however it has a different repr to
c_int
causing it to be incompatible outside of rust code. - jobject
RefType - jvmti
Event - jvmti
Event Mode - jvmti
Heap Object Filter - jvmti
Heap Reference Kind - jvmti
Iteration Control - jvmti
Primitive Type - jvmti
Verbose Flag
Constants§
- JNI_
ABORT - JNI_
COMMIT - JNI_
EDETACHED - JNI_
EEXIST - JNI_
EINVAL - JNI_
ENOMEM - JNI_ERR
- JNI_
EVERSION - JNI_
FALSE - JNI_OK
- JNI_
TRUE - JNI_
VERSION_ 9 - JNI_
VERSION_ 1_ 1 - JNI_
VERSION_ 1_ 2 - JNI_
VERSION_ 1_ 4 - JNI_
VERSION_ 1_ 6 - JNI_
VERSION_ 1_ 8 - JNI_
VERSION_ 10 - JNI_
VERSION_ 19 - JNI_
VERSION_ 20 - JNI_
VERSION_ 21 - JNI_
VERSION_ 24 - JVMTI_
CLASS_ STATUS_ ARRAY - Class is an array. If set, all other bits are zero.
- JVMTI_
CLASS_ STATUS_ ERROR - Error during initialization makes class unusable
- JVMTI_
CLASS_ STATUS_ INITIALIZED - Class initialization is complete. Static initializer has been run.
- JVMTI_
CLASS_ STATUS_ PREPARED - Class preparation is complete
- JVMTI_
CLASS_ STATUS_ PRIMITIVE - Class is a primitive class (for example, java.lang.Integer.TYPE). If set, all other bits are zero.
- JVMTI_
CLASS_ STATUS_ VERIFIED - Class bytecodes have been verified
- JVMTI_
ERROR_ ABSENT_ INFORMATION - JVMTI_
ERROR_ ACCESS_ DENIED - JVMTI_
ERROR_ CIRCULAR_ CLASS_ DEFINITION - JVMTI_
ERROR_ CLASS_ LOADER_ UNSUPPORTED - JVMTI_
ERROR_ CLASS_ NOT_ PREPARED - JVMTI_
ERROR_ DUPLICATE - JVMTI_
ERROR_ FAILS_ VERIFICATION - JVMTI_
ERROR_ ILLEGAL_ ARGUMENT - JVMTI_
ERROR_ INTERNAL - JVMTI_
ERROR_ INTERRUPT - JVMTI_
ERROR_ INVALID_ CLASS - JVMTI_
ERROR_ INVALID_ CLASS_ FORMAT - JVMTI_
ERROR_ INVALID_ ENVIRONMENT - JVMTI_
ERROR_ INVALID_ EVENT_ TYPE - JVMTI_
ERROR_ INVALID_ FIELDID - JVMTI_
ERROR_ INVALID_ LOCATION - JVMTI_
ERROR_ INVALID_ METHODID - JVMTI_
ERROR_ INVALID_ MODULE - JVMTI_
ERROR_ INVALID_ MONITOR - JVMTI_
ERROR_ INVALID_ OBJECT - JVMTI_
ERROR_ INVALID_ PRIORITY - JVMTI_
ERROR_ INVALID_ SLOT - JVMTI_
ERROR_ INVALID_ THREAD - JVMTI_
ERROR_ INVALID_ THREAD_ GROUP - JVMTI_
ERROR_ INVALID_ TYPESTATE - JVMTI_
ERROR_ MAX - JVMTI_
ERROR_ MUST_ POSSESS_ CAPABILITY - JVMTI_
ERROR_ NAMES_ DONT_ MATCH - JVMTI_
ERROR_ NATIVE_ METHOD - JVMTI_
ERROR_ NONE - JVMTI_
ERROR_ NOT_ AVAILABLE - JVMTI_
ERROR_ NOT_ FOUND - JVMTI_
ERROR_ NOT_ MONITOR_ OWNER - JVMTI_
ERROR_ NO_ MORE_ FRAMES - JVMTI_
ERROR_ NULL_ POINTER - JVMTI_
ERROR_ OPAQUE_ FRAME - JVMTI_
ERROR_ OUT_ OF_ MEMORY - JVMTI_
ERROR_ THREAD_ NOT_ ALIVE - JVMTI_
ERROR_ THREAD_ NOT_ SUSPENDED - JVMTI_
ERROR_ THREAD_ SUSPENDED - JVMTI_
ERROR_ TYPE_ MISMATCH - JVMTI_
ERROR_ UNATTACHED_ THREAD - JVMTI_
ERROR_ UNMODIFIABLE_ CLASS - JVMTI_
ERROR_ UNMODIFIABLE_ MODULE - JVMTI_
ERROR_ UNSUPPORTED_ OPERATION - JVMTI_
ERROR_ UNSUPPORTED_ REDEFINITION_ CLASS_ ATTRIBUTE_ CHANGED - JVMTI_
ERROR_ UNSUPPORTED_ REDEFINITION_ CLASS_ MODIFIERS_ CHANGED - JVMTI_
ERROR_ UNSUPPORTED_ REDEFINITION_ HIERARCHY_ CHANGED - JVMTI_
ERROR_ UNSUPPORTED_ REDEFINITION_ METHOD_ ADDED - JVMTI_
ERROR_ UNSUPPORTED_ REDEFINITION_ METHOD_ DELETED - JVMTI_
ERROR_ UNSUPPORTED_ REDEFINITION_ METHOD_ MODIFIERS_ CHANGED - JVMTI_
ERROR_ UNSUPPORTED_ REDEFINITION_ SCHEMA_ CHANGED - JVMTI_
ERROR_ UNSUPPORTED_ VERSION - JVMTI_
ERROR_ WRONG_ PHASE - JVMTI_
HEAP_ FILTER_ CLASS_ TAGGED - JVMTI_
HEAP_ FILTER_ CLASS_ UNTAGGED - JVMTI_
HEAP_ FILTER_ TAGGED - JVMTI_
HEAP_ FILTER_ UNTAGGED - JVMTI_
HEAP_ REFERENCE_ ARRAY_ ELEMENT - JVMTI_
HEAP_ REFERENCE_ CLASS - JVMTI_
HEAP_ REFERENCE_ CLASS_ LOADER - JVMTI_
HEAP_ REFERENCE_ CONSTANT_ POOL - JVMTI_
HEAP_ REFERENCE_ FIELD - JVMTI_
HEAP_ REFERENCE_ INTERFACE - JVMTI_
HEAP_ REFERENCE_ JNI_ GLOBAL - JVMTI_
HEAP_ REFERENCE_ JNI_ LOCAL - JVMTI_
HEAP_ REFERENCE_ MONITOR - JVMTI_
HEAP_ REFERENCE_ OTHER - JVMTI_
HEAP_ REFERENCE_ PROTECTION_ DOMAIN - JVMTI_
HEAP_ REFERENCE_ SIGNERS - JVMTI_
HEAP_ REFERENCE_ STACK_ LOCAL - JVMTI_
HEAP_ REFERENCE_ STATIC_ FIELD - JVMTI_
HEAP_ REFERENCE_ SUPERCLASS - JVMTI_
HEAP_ REFERENCE_ SYSTEM_ CLASS - JVMTI_
HEAP_ REFERENCE_ THREAD - JVMTI_
HEAP_ ROOT_ JNI_ GLOBAL - JVMTI_
HEAP_ ROOT_ JNI_ LOCAL - JVMTI_
HEAP_ ROOT_ MONITOR - JVMTI_
HEAP_ ROOT_ OTHER - JVMTI_
HEAP_ ROOT_ STACK_ LOCAL - JVMTI_
HEAP_ ROOT_ SYSTEM_ CLASS - JVMTI_
HEAP_ ROOT_ THREAD - JVMTI_
JLOCATION_ JVMBCI - jlocation values represent virtual machine bytecode indices–that is, offsets into the virtual machine code for a method.
- JVMTI_
JLOCATION_ MACHINEPC - jlocation values represent native machine program counter values.
- JVMTI_
JLOCATION_ OTHER - jlocation values have some other representation.
- JVMTI_
KIND_ ALLOC_ ALLOC_ BUF - Outgoing allocated array of allocated arrays argument - foo***. Free with Deallocate.
- JVMTI_
KIND_ ALLOC_ BUF - Outgoing allocated array argument - foo**. Free with Deallocate.
- JVMTI_
KIND_ IN - Ingoing argument - foo.
- JVMTI_
KIND_ IN_ BUF - Ingoing array argument - const foo*.
- JVMTI_
KIND_ IN_ PTR - Ingoing pointer argument - const foo*.
- JVMTI_
KIND_ OUT - Outgoing argument - foo*.
- JVMTI_
KIND_ OUT_ BUF - Outgoing array argument (pre-allocated by agent) - foo*. Do not Deallocate.
- JVMTI_
PHASE_ DEAD - JVMTI_
PHASE_ LIVE - JVMTI_
PHASE_ ONLOAD - JVMTI_
PHASE_ PRIMORDIAL - JVMTI_
PHASE_ START - JVMTI_
PRIMITIVE_ TYPE_ BOOLEAN - JVMTI_
PRIMITIVE_ TYPE_ BYTE - JVMTI_
PRIMITIVE_ TYPE_ CHAR - JVMTI_
PRIMITIVE_ TYPE_ DOUBLE - JVMTI_
PRIMITIVE_ TYPE_ FLOAT - JVMTI_
PRIMITIVE_ TYPE_ INT - JVMTI_
PRIMITIVE_ TYPE_ LONG - JVMTI_
PRIMITIVE_ TYPE_ SHORT - JVMTI_
REFERENCE_ ARRAY_ ELEMENT - JVMTI_
REFERENCE_ CLASS - JVMTI_
REFERENCE_ CLASS_ LOADER - JVMTI_
REFERENCE_ CONSTANT_ POOL - JVMTI_
REFERENCE_ FIELD - JVMTI_
REFERENCE_ INTERFACE - JVMTI_
REFERENCE_ PROTECTION_ DOMAIN - JVMTI_
REFERENCE_ SIGNERS - JVMTI_
REFERENCE_ STATIC_ FIELD - JVMTI_
THREAD_ STATE_ ALIVE - Thread is alive. Zero if thread is new (not started) or terminated.
- JVMTI_
THREAD_ STATE_ BLOCKED_ ON_ MONITOR_ ENTER - Thread is waiting to enter a synchronized block/method or, after an
Object.wait()
, waiting to re-enter a synchronized block/method. - JVMTI_
THREAD_ STATE_ INTERRUPTED - Thread has been interrupted.
- JVMTI_
THREAD_ STATE_ IN_ NATIVE - Thread is in native code–that is, a native method is running which has not called back into the VM or Java programming language code.
- JVMTI_
THREAD_ STATE_ IN_ OBJECT_ WAIT - Thread is waiting on an object monitor – Object.wait.
- JVMTI_
THREAD_ STATE_ PARKED - Thread is parked, for example: LockSupport.park, LockSupport.parkUtil and LockSupport.parkNanos. A virtual thread that is sleeping, in Thread.sleep, may have this state flag set instead of
JVMTI_THREAD_STATE_SLEEPING
. - JVMTI_
THREAD_ STATE_ RUNNABLE - Thread is runnable.
- JVMTI_
THREAD_ STATE_ SLEEPING - Thread is sleeping – Thread.sleep.
- JVMTI_
THREAD_ STATE_ SUSPENDED - Thread is suspended by a suspend function (such as
SuspendThread
). If this bit is set, the other bits refer to the thread state before suspension. - JVMTI_
THREAD_ STATE_ TERMINATED - Thread has completed execution.
- JVMTI_
THREAD_ STATE_ VENDOR_ 1 - Defined by VM vendor.
- JVMTI_
THREAD_ STATE_ VENDOR_ 2 - Defined by VM vendor.
- JVMTI_
THREAD_ STATE_ VENDOR_ 3 - Defined by VM vendor.
- JVMTI_
THREAD_ STATE_ WAITING - Thread is waiting.
- JVMTI_
THREAD_ STATE_ WAITING_ INDEFINITELY - Thread is waiting without a timeout. For example,
Object.wait()
. - JVMTI_
THREAD_ STATE_ WAITING_ WITH_ TIMEOUT - Thread is waiting with a maximum time to wait specified. For example, Object.wait(long).
- JVMTI_
TIMER_ ELAPSED - JVMTI_
TIMER_ TOTAL_ CPU - JVMTI_
TIMER_ USER_ CPU - JVMTI_
TYPE_ CCHAR - C programming language type - char.
- JVMTI_
TYPE_ CVOID - C programming language type - void.
- JVMTI_
TYPE_ JBOOLEAN - Java programming language primitive type - boolean. JNI type jboolean.
- JVMTI_
TYPE_ JBYTE - Java programming language primitive type - byte. JNI type jbyte.
- JVMTI_
TYPE_ JCHAR - Java programming language primitive type - char. JNI type jchar.
- JVMTI_
TYPE_ JCLASS - Java programming language object type - java.lang.Class. JNI type jclass. Returned values are JNI local references and must be managed.
- JVMTI_
TYPE_ JDOUBLE - Java programming language primitive type - double. JNI type jdouble.
- JVMTI_
TYPE_ JFIELDID - Java programming language field identifier - JNI type jfieldID.
- JVMTI_
TYPE_ JFLOAT - Java programming language primitive type - float. JNI type jfloat.
- JVMTI_
TYPE_ JINT - Java programming language primitive type - int. JNI type jint.
- JVMTI_
TYPE_ JLONG - Java programming language primitive type - long. JNI type jlong.
- JVMTI_
TYPE_ JMETHODID - Java programming language method identifier - JNI type jmethodID.
- JVMTI_
TYPE_ JNIENV - JNI environment -
JNIEnv
. Should be used with the correct jvmtiParamKind to make it a pointer type. - JVMTI_
TYPE_ JOBJECT - Java programming language object type - java.lang.Object. JNI type jobject. Returned values are JNI local references and must be managed.
- JVMTI_
TYPE_ JSHORT - Java programming language primitive type - short. JNI type jshort.
- JVMTI_
TYPE_ JTHREAD - Java programming language object type - java.lang.Thread. JVM TI type jthread. Returned values are JNI local references and must be managed.
- JVMTI_
TYPE_ JVALUE - Union of all Java programming language primitive and object types - JNI type jvalue. Returned values which represent object types are JNI local references and must be managed.
- JVMTI_
VERSION_ 1 - JVMTI_
VERSION_ 9 - JVMTI_
VERSION_ 1_ 0 - JVMTI_
VERSION_ 1_ 1 - JVMTI_
VERSION_ 1_ 2 - JVMTI_
VERSION_ 11 - JVMTI_
VERSION_ 19 - JVMTI_
VERSION_ 21 - JVMTI_
VISIT_ ABORT - JVMTI_
VISIT_ OBJECTS
Traits§
- AsJNI
Linkage - JType
- Marker trait for all types that are valid to use to make variadic JNI Up-calls with.
- UseC
String - Helper trait that converts rusts various strings into a zero terminated c string for use with a JNI method.
Functions§
- JNI_
Create ⚠JavaVM - Directly calls
JNI_CreateJavaVM
with the provided arguments. - JNI_
Create ⚠JavaVM_ with_ string_ args - Convenience function to call
JNI_CreateJavaVM
with a simple list of String arguments. - JNI_
GetCreated ⚠JavaV Ms - Returns the created
JavaVMs
in the givenvms
slice. All remaining elements in the slice are set to None. The count of returnedJavaVMs
is returned in the result. - JNI_
GetCreated ⚠JavaV Ms_ first - Returns the first created
JavaVM
or None in the result. - init_
dynamic_ link - Call this function to initialize the dynamic linking to the jvm to use the provided function pointers to create the jvm.
- is_
jvm_ loaded - Returns true if the jvm was loaded by either calling
load_jvm_from_library
orinit_dynamic_link
. - load_
jvm_ ⚠from_ java_ home - Convenience method to load the jvm from the
JAVA_HOME
environment variable that is commonly set on Windows by End-User Java Setups, or on linux by distribution package installers. - load_
jvm_ ⚠from_ java_ home_ folder - Convinience method to load the jvm from a given path to a java installation.
Info: The
java_home
parameter should refer to a path of a folder, which directly contains the “bin” or “jre” folder. - load_
jvm_ ⚠from_ library - Convenience method to load the jvm from a path to libjvm.so or jvm.dll.
Type Aliases§
- jarray
- jboolean
- jboolean
Array - jbyte
- jbyte
Array - jchar
- jchar
Array - jclass
- jdouble
- jdouble
Array - jfieldID
- jfloat
- jfloat
Array - jint
- jint
Array - jlocation
- jlong
- jlong
Array - jmethodID
- jobject
- jobject
Array - jraw
MonitorID - jshort
- jshort
Array - jsize
- jstring
- jthread
- jthread
Group - jthrowable
- jvalue
- jvmti
Array Primitive Value Callback - jvmti
Event Breakpoint - jvmti
Event Class File Load Hook - jvmti
Event Class Load - jvmti
Event Class Prepare - jvmti
Event Compiled Method Load - jvmti
Event Compiled Method Unload - jvmti
Event Data Dump Request - jvmti
Event Dynamic Code Generated - jvmti
Event Exception - jvmti
Event Exception Catch - jvmti
Event Field Access - jvmti
Event Field Modification - jvmti
Event Frame Pop - jvmti
Event Garbage Collection Finish - jvmti
Event Garbage Collection Start - jvmti
Event Method Entry - jvmti
Event Method Exit - jvmti
Event Monitor Contended Enter - jvmti
Event Monitor Contended Entered - jvmti
Event Monitor Wait - jvmti
Event Monitor Waited - jvmti
Event Native Method Bind - jvmti
Event Object Free - jvmti
Event Reserved - jvmti
Event Resource Exhausted - jvmti
Event Sampled Object Alloc - jvmti
Event Single Step - jvmti
Event Thread End - jvmti
Event Thread Start - jvmti
EventVM Death - jvmti
EventVM Init - jvmti
EventVM Object Alloc - jvmti
EventVM Start - jvmti
Event Virtual Thread End - jvmti
Event Virtual Thread Start - jvmti
Extension Event - jvmti
Extension Function - jvmti
Heap Iteration Callback - jvmti
Heap Object Callback - jvmti
Heap Reference Callback - jvmti
Heap Root Callback - jvmti
Heap Root Kind - jvmtiHeapRootKind cant enum this because we are called with it, making addition in a future version of JVMTI UB in rust.
- jvmti
Jlocation Format - jvmti
Object Reference Callback - jvmti
Object Reference Kind - jvmtiHeapRootKind cant enum this because we are called with it, making addition in a future version of JVMTI UB in rust.
- jvmti
Param Kind - jvmti
Param Types - jvmti
Phase - jvmti
Primitive Field Callback - jvmti
Reserved Callback - jvmti
Stack Reference Callback - jvmti
Start Function - jvmti
String Primitive Value Callback - jvmti
Timer Kind - jweak