Summary

Specify what happens when accessing a value in a VaList using the wrong memory layout.

Problem

Accessing a value in a VaList using an incorrect memory layout result in undefined behavior. But the documentation currently doesn't say this.

Solution

Document that attempts to access a value in a VaList using the wrong memory layout results in undefined behavior.

Specification

The following is added to the class javadoc of VaList:

--- a/src/java.base/share/classes/java/lang/foreign/VaList.java
+++ b/src/java.base/share/classes/java/lang/foreign/VaList.java
@@ -52,6 +52,13 @@
  * As such, this interface only supports reading {@code int}, {@code double},
  * and any other type that fits into a {@code long}.
  * <h2 id="safety">Safety considerations</h2>
+ * Accessing a value through a variable argument list using the wrong memory layout will result in undefined behavior.
+ * For instance, if a variable argument list currently points at a C {@code int} value, then accessing it using
+ * {@link #nextVarg(ValueLayout.OfLong)} is illegal. Similarly, accessing the variable argument list with
+ * {@link #skip(MemoryLayout...)}, and providing a layout other than {@link ValueLayout.OfInt} is illegal.
+ * Any such illegal accesses might not be detected by the implementation, and can corrupt the variable argument list,
+ * so that the behavior of subsequent accesses is also undefined.
+ * <p>
  * It is possible for clients to access elements outside the spatial bounds of a variable argument list.
  * Variable argument list implementations will try to detect out-of-bounds reads on a best-effort basis.
  * <p>