[clang] 2c2148d - [C2y] Add documentation to conform to WG14 N3262; NFC (#98146)

[via cfe-commits]

Author: Aaron Ballman
Date: 2024-07-12T07:07:27-04:00
New Revision: 2c2148de851faaca5fe0f47bcac84a10fcd53017

URL: https://github.com/llvm/llvm-project/commit/2c2148de851faaca5fe0f47bcac84a10fcd53017
DIFF: https://github.com/llvm/llvm-project/commit/2c2148de851faaca5fe0f47bcac84a10fcd53017.diff

LOG: [C2y] Add documentation to conform to WG14 N3262; NFC (#98146)

This paper is about whether a copy of a va_list object which was not
produced by calling va_copy is valid to use or not. While this may work
on some targets, we explicitly document it as undefined behavior for all
targets so there's not confusion as to when it's valid or not. It's not
a burden for a user to use va_copy explicitly.

Added: 
    clang/test/C/C2y/n3262.c

Modified: 
    clang/docs/LanguageExtensions.rst
    clang/www/c_status.html

Removed: 
    


################################################################################
diff  --git a/clang/docs/LanguageExtensions.rst b/clang/docs/LanguageExtensions.rst
index d9439d49a2e29..81784c75081ba 100644
--- a/clang/docs/LanguageExtensions.rst
+++ b/clang/docs/LanguageExtensions.rst
@@ -3977,7 +3977,10 @@ standard library ``<stdarg.h>`` header:
 
 * ``__builtin_va_list``
 
-A predefined typedef for the target-specific ``va_list`` type.
+A predefined typedef for the target-specific ``va_list`` type. It is undefined
+behavior to use a byte-wise copy of this type produced by calling ``memcpy``,
+``memmove``, or similar. Valid explicit copies are only produced by calling
+``va_copy`` or ``__builtin_va_copy``.
 
 * ``void __builtin_va_start(__builtin_va_list list, <parameter-name>)``
 

diff  --git a/clang/test/C/C2y/n3262.c b/clang/test/C/C2y/n3262.c
new file mode 100644
index 0000000000000..3ff2062d88dde
--- /dev/null
+++ b/clang/test/C/C2y/n3262.c
@@ -0,0 +1,20 @@
+// RUN: %clang_cc1 -verify -std=c2y -Wall -pedantic %s
+// expected-no-diagnostics
+
+/* WG14 N3262: Yes
+ * Usability of a byte-wise copy of va_list
+ *
+ * NB: Clang explicitly documents this as being undefined behavior. A
+ * diagnostic is produced for some targets but not for others for assignment or
+ * initialization, but no diagnostic is possible to produce for use with memcpy
+ * in the general case, nor with a manual bytewise copy via a for loop.
+ *
+ * Therefore, nothing is tested in this file; it serves as a reminder that we
+ * validated our documentation against the paper. See
+ * clang/docs/LanguageExtensions.rst for more details.
+ *
+ * FIXME: it would be nice to add ubsan support for recognizing when an invalid
+ * copy is made and diagnosing on copy (or on use of the copied va_list).
+ */
+
+int main() {}

diff  --git a/clang/www/c_status.html b/clang/www/c_status.html
index 1b0cf4065019e..22f28212132f2 100644
--- a/clang/www/c_status.html
+++ b/clang/www/c_status.html
@@ -1290,7 +1290,7 @@ <h2 id="c2y">C2y implementation status</h2>
     <tr>
       <td>Usability of a byte-wise copy of va_list</td>
       <td><a href="https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3262.pdf">N3262</a></td>
-      <td class="unknown" align="center">Unknown</td>
+      <td class="full" align="center">Yes</td>
     </tr>
     <tr>
       <td>alignof of an incomplete array type</td>