stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

8260194: Update the documentation for -Xcheck:jni

Browse Source 
Reviewed-by: coleenp, hseigel
This commit is contained in:
David Holmes 2021-06-16 23:58:24 +00:00
parent ee03bc6d0a
commit 9f7851b5f5
1 changed files with 62 additions and 6 deletions

68
src/java.base/share/man/java.1

@ -794,13 +794,69 @@ list.
.TP
.B \f[CB]\-Xcheck:jni\f[R]
Performs additional checks for Java Native Interface (JNI) functions.
Specifically, it validates the parameters passed to the JNI function and
the runtime environment data before processing the JNI request.
It also checks for pending exceptions between JNI calls.
Any invalid data encountered indicates a problem in the native code, and
the JVM terminates with an irrecoverable error in such cases.
Expect a performance degradation when this option is used.
.RS
.PP
The following checks are considered indicative of significant problems
with the native code, and the JVM terminates with an irrecoverable error
in such cases:
.IP \[bu] 2
The thread doing the call is not attached to the JVM.
.IP \[bu] 2
The thread doing the call is using the \f[CB]JNIEnv\f[R] belonging to
another thread.
.IP \[bu] 2
A parameter validation check fails:
.RS 2
.IP \[bu] 2
A \f[CB]jfieldID\f[R], or \f[CB]jmethodID\f[R], is detected as being
invalid.
For example:
.RS 2
.IP \[bu] 2
Of the wrong type
.IP \[bu] 2
Associated with the wrong class
.RE
.IP \[bu] 2
A parameter of the wrong type is detected.
.IP \[bu] 2
An invalid parameter value is detected.
For example:
.RS 2
.IP \[bu] 2
NULL where not permitted
.IP \[bu] 2
An out\-of\-bounds array index, or frame capacity
.IP \[bu] 2
A non\-UTF\-8 string
.IP \[bu] 2
An invalid JNI reference
.IP \[bu] 2
An attempt to use a \f[CB]ReleaseXXX\f[R] function on a parameter not
produced by the corresponding \f[CB]GetXXX\f[R] function
.RE
.RE
.PP
The following checks only result in warnings being printed:
.IP \[bu] 2
A JNI call was made without checking for a pending exception from a
previous JNI call, and the current call is not safe when an exception
may be pending.
.IP \[bu] 2
The number of JNI local references existing when a JNI function
terminates exceeds the number guaranteed to be available.
See the \f[CB]EnsureLocalcapacity\f[R] function.
.IP \[bu] 2
A class descriptor is in decorated format (\f[CB]Lname;\f[R]) when it
should not be.
.IP \[bu] 2
A \f[CB]NULL\f[R] parameter is allowed, but its use is questionable.
.IP \[bu] 2
Calling other JNI functions in the scope of
\f[CB]Get/ReleasePrimitiveArrayCritical\f[R] or
\f[CB]Get/ReleaseStringCritical\f[R]
.PP
Expect a performance degradation when this option is used.
.RE
.TP
.B \f[CB]\-Xdebug\f[R]