Summary

Document that the absolute write method java.nio.channels.FileChannel(ByteBuffer,long) has unspecified behavior if the file is opened in append mode.

Problem

On some platforms invoking an absolute write on a FileChannel opened in append mode might write the sequence of bytes at the specified position in the file, but on other platforms the sequence might be appended to the file and the position parameter ignored. For example, on macOS the sequence of bytes would be written starting at position, but on Linux they would be appended to the file (see JDK-4950302).

Solution

Add verbiage clarifying that the behavior of write(ByteBuffer,long) is unspecified when the file was opened with StandardOpenOption.APPEND present.

Specification

--- a/src/java.base/share/classes/java/nio/channels/FileChannel.java
+++ b/src/java.base/share/classes/java/nio/channels/FileChannel.java
@@ -146,7 +146,9 @@ import jdk.internal.javac.PreviewFeature;
  * operation first advances the position to the end of the file and then writes
  * the requested data.  Whether the advancement of the position and the writing
  * of the data are done in a single atomic operation is system-dependent and
- * therefore unspecified.
+ * therefore unspecified.  In this mode an invocation of the {@linkplain
+ * #write(ByteBuffer,long) absolute write} operation leads to unspecified
+ * behavior.
  *
  * @see java.io.FileInputStream#getChannel()
  * @see java.io.FileOutputStream#getChannel()
@@ -193,7 +195,9 @@ public abstract class FileChannel
      *     the position to the end of the file and then writes the requested
      *     data. Whether the advancement of the position and the writing of the
      *     data are done in a single atomic operation is system-dependent and
-     *     therefore unspecified. This option may not be used in conjunction
+     *     therefore unspecified. The effect of performing an
+     *     {@linkplain #write(ByteBuffer,long) absolute write} with this option
+     *     present is unspecified. This option may not be used in conjunction
      *     with the {@code READ} or {@code TRUNCATE_EXISTING} options. </td>
      * </tr>
      * <tr>
@@ -809,6 +813,9 @@ public abstract class FileChannel
      * grown to accommodate the new bytes; the values of any bytes between the
      * previous end-of-file and the newly-written bytes are unspecified.  </p>
      *
+     * <p> If the file is open in <a href="#append-mode">append mode</a>, then
+     * the effect of invoking this method is unspecified.
+     *
      * @param  src
      *         The buffer from which bytes are to be transferred
      *