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

[via cfe-commits]

llvmbot wrote:


<!--LLVM PR SUMMARY COMMENT-->

@llvm/pr-subscribers-clang

Author: Aaron Ballman (AaronBallman)

<details>
<summary>Changes</summary>

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.

---
Full diff: https://github.com/llvm/llvm-project/pull/98146.diff


2 Files Affected:

- (modified) clang/docs/LanguageExtensions.rst (+3-1) 
- (added) clang/test/C/C2y/n3262.c (+20) 


``````````diff
diff --git a/clang/docs/LanguageExtensions.rst b/clang/docs/LanguageExtensions.rst
index d9439d49a2e29..90ba6d8e29987 100644
--- a/clang/docs/LanguageExtensions.rst
+++ b/clang/docs/LanguageExtensions.rst
@@ -3977,7 +3977,9 @@ 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 copy of a value of this type unless the copy was produced by
+calling ``__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() {}

``````````

</details>


https://github.com/llvm/llvm-project/pull/98146