JDK-6681965 : The documentation for GetStringChars and GetStringUTFChars is unclear
  • Type: Enhancement
  • Component: hotspot
  • Sub-Component: runtime
  • Affected Version: 6u3
  • Priority: P3
  • Status: Closed
  • Resolution: Duplicate
  • OS: generic
  • CPU: generic
  • Submitted: 2008-03-31
  • Updated: 2015-06-02
  • Resolved: 2015-06-02
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 9
9Resolved
Related Reports
Duplicate :  
JDK-8038005 - Improve JNI spec for string methods
Duplicate :  
JDK-8079466 - JNI Specification Update and Clean-up (JDK 8)
Duplicate :  
JDK-8037115 - Clarify exceptions thrown in JNI
Relates :  
JDK-4616318 - Spec for JNI's GetStringChars() is incomplete
Relates :  
JDK-8079466 - JNI Specification Update and Clean-up (JDK 8)
Relates :  
JDK-8038005 - Improve JNI spec for string methods
Description
FULL PRODUCT VERSION :
java version "1.6.0_03"
Java(TM) SE Runtime Environment (build 1.6.0_03-b05)
Java HotSpot(TM) Client VM (build 1.6.0_03-b05, mixed mode)

ADDITIONAL OS VERSION INFORMATION :
 Windows Vista [Version 6.0.6000]

A DESCRIPTION OF THE PROBLEM :
The documentation for GetStringChars and GetStringUTFChars
is unclear on whether you can count on a null char being appended automatically on the result.

docs/technotes/guides/jni/spec/functions.html#wp17265

STEPS TO FOLLOW TO REPRODUCE THE PROBLEM :
read the bundled docs. Read Sheng Liang's The Java Native Inferface. It has the same omission.

EXPECTED VERSUS ACTUAL BEHAVIOR :
EXPECTED -
It should say explicitly if the string returned can be counted on to have a terminating null.


REPRODUCIBILITY :
This bug can be reproduced always.

CUSTOMER SUBMITTED WORKAROUND :
Presume null is sometimes returned and write voluminous code to deal with either possibility.
Comments
Merged into 8079466
02-06-2015
Reviewed: http://cr.openjdk.java.net/~dsimms/jnispec/6681965/ Assigned to tech writer: JDK-8042218
15-05-2014
There are number of mail threads asking for clarification surrounding string operations, and whether the results should be NULL terminated. Functions affected: const jchar * GetStringChars(JNIEnv *env, jstring string, jboolean *isCopy); const char * GetStringUTFChars(JNIEnv *env, jstring string, jboolean *isCopy); void GetStringRegion(JNIEnv *env, jstring str, jsize start, jsize len, jchar *buf); void GetStringUTFRegion(JNIEnv *env, jstring str, jsize start, jsize len, char *buf); const jchar * GetStringCritical(JNIEnv *env, jstring string, jboolean *isCopy); There are two stories here, how the particular JVM implements Java Strings internally, and the JNI Specification. I believe these two things are separate: From a HotSpot JVM perspective, null-terminating strings might be seen as "safety first". There may be other JVM implementations whom, for argument sake, that never garbage collect and always use direct heap pointers. Such implementations have no reason to null-terminate... ...indeed HotSpot's "GetStringCritical()" implementation does no such thing. Currently the JNI Specification does not mention null-termination, and given we are not dealing with c-strings, but Java Strings, that is because it's not required. "GetStringUTFRegion()" as currently implemented by HotSpot has an issue, it is possible to null-terminate past the user specified length (which in itself a bit of an issue, its related to the input, not output, being UTF-16 length != UT8 encoded length). I'm not advocating removing the current null-termination where HotSpot supplies the buffers. In fact I'm worried will break too much existing code. There is no harm in null-termination where the JVM has control over the buffer. JNI Specification text change: clarify NULL-termination, or rather lack of, for string operations. Additional text at the beginning of the "String Operations" section: ------------------------------------------------------------------------ String Operations This specification makes no assumptions on how a JVM represents Java strings internally. Strings returned from these operations: GetStringChars() GetStringUTFChars() GetStringRegion() GetStringUTFRegion() GetStringCritical() are therefore not required to be NULL terminated. Programmers are expected to determine buffer capacity requirements via GetStringLength() or GetStringUTFLength(). ------------------------------------------------------------------------
14-05-2014
Closing JDK-8038005 as dup of this, text describes same problem "to spec if the returned string is null-terminated": "I would like the doc for GetStringUTFChars() to spec if the returned string is null-terminated. Since JNI also provides a GetStringUTFLength() it would be technically possible to use the result of GetStringUTFChars() without null-termination. Same is true for GetStringChars() /GetStringLength(). and GetStringCritical(). "
02-04-2014
Summary - GetStringChars/GetStringUTFChars do not throw exceptions, which matches the specification. Specification needs update to clarify that they are not required to return null terminated strings, and use GetStringLength to get the string length as David Holmes quotes Alan Bateman above.
24-03-2014
On 3/19/14 11:05 AM, Daniel D. Daugherty wrote: Here's how I would analyze JNI GetStringChars(). I always start with a link like this one for the most recent release: http://docs.oracle.com/javase/7/docs/ which leads me to when I click the "JNI" box in the diagram: http://docs.oracle.com/javase/7/docs/technotes/guides/jni/index.html which leads me to another page where I can get to the "JNI 6.0 API Specification". Please take care to notice the words "JNI 6.0 API Specification". I could be wrong here, but that tends to indicate that I've found the specification for JNI: http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/jniTOC.html which is just a table-of-contents, but I'm close... Way down in the "String Operations" section is a link for JNI GetStringChars(). http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp17158 > GetStringChars > > const jchar * GetStringChars(JNIEnv *env, jstring string, > jboolean *isCopy); > > Returns a pointer to the array of Unicode characters of the string. > This pointer is valid until ReleaseStringchars() is called. > > If isCopy is not NULL, then *isCopy is set to JNI_TRUE if a copy is made; > or it is set to JNI_FALSE if no copy is made. > > LINKAGE: > Index 165 in the JNIEnv interface function table. > PARAMETERS: > > env: the JNI interface pointer. > > string: a Java string object. > > isCopy: a pointer to a boolean. > > RETURNS: > Returns a pointer to a Unicode string, or NULL if the operation fails. This function does not include a "THROWS:" section like JNI NewStringUTF() so I'm leaning toward the function not throwing any exceptions. However, it possible that the JNI spec has some words about general exceptions that functions can throw; the JVM/TI spec does this, but the JVM/TI spec is about a decade newer. I searched these sections for "exception" and I don't see any wording that permits functions to throw general exceptions that are not documented in their function specifications: 1. Introduction http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/intro.html#wp9502 2 hits - nothing useful 2. Design Overview http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/design.html#wp9502 41 hits - useful, but nothing about general exceptions 3. JNI Types and Data Structures http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/types.html#wp9502 no hits - but I didn't expect any 4. JNI Functions http://docs.oracle.com/javase/7/docs/technotes/guides/jni/spec/functions.html#wp9502 58 hits - useful, but nothing about general exceptions Based on this analysis, my opinion is that JNI NewStringUTF() should never throw an exception and if it does so, then that violates the spec.
19-03-2014
EVALUATION This appears to be a dup of 4616318 which is a long standing CR to get the JNI spec updated. Also see: http://mail.openjdk.java.net/pipermail/core-libs-dev/2008-January/000183.html Alan Bateman wrote (about GetStringChars): > [...] is length+1 and zero terminated. There is a long-standing bug to clarify the JNI specification on this topic. I believe it should say that the returned array of Unicode characters is not required to be zero terminated and that one should use GetStringLength to determine the length.
17-08-2010