JDK-4904617 : JVM_Read needs better documentation
  • Type: Bug
  • Component: hotspot
  • Sub-Component: runtime
  • Affected Version: 5.0
  • Priority: P4
  • Status: Closed
  • Resolution: Not an Issue
  • OS: generic
  • CPU: generic
  • Submitted: 2003-08-11
  • Updated: 2019-01-15
  • Resolved: 2014-03-14
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.
The hotspot and j2se workspaces both contain a copy of jvm.h.
(These two files have been diverging.  That should probably be fixed.)

In both of these files, JVM_Read() is documented like this:

 * Read data from a file decriptor into a char array.
 * fd        the file descriptor to read from.
 * buf       the buffer where to put the read data.
 * nbytes    the number of bytes to read.
 * This function returns -1 on error, and 0 on success.
JVM_Read(jint fd, char *buf, jint nbytes);

This documentation needs fixing in the following ways:

- This function actually appears to return:
  the number of bytes read, or JVM_IO_ERR, or JVM_IO_INTR

- A maintainer of j2se native code needs guidance regarding the following:

  - When should one use JVM_Read() instead of native read()?

  - How should a caller deal with interrupted system calls?
    Apparently the right thing to do is to use something like this
    (completely untested):

jint JVM_RestartingRead(jint fd, char *buf, jint nbytes)
    jint n;
    do { n = JVM_Read(fd, buf, nbytes); }
    while (n == JVM_IO_ERR && errno == EINTR);
    return n;

  Perhaps the above function should be made part of the JVM interface?

  - How should a caller deal with JVM_IO_INTR?
    This is extremely tricky, especially given the confusion
    with EINTR.

- "decriptor" typo.
###@###.### 2003-08-11

We don't think this is an issue anymore, interruptible I/O is removed in JDK9 as well.

EVALUATION The VM header file will be updated and corrected, then put back into the J2SE tree with any customization needed so the definitions and comments are sync'd. Consultation with release engineering has started to consider an automated means of maintaining sync but this latter aspect might not get into Tiger. A request for policy discussion about use of common interfaces vs "direct calls" into OS services is being drafted for submission to management and routing to the appropriate tech leads. ###@###.### 2003-10-29