>From 1631ac751e1dfdf09816e719e1571ab0d0e3ba88 Mon Sep 17 00:00:00 2001
From: Paul Eggert <address@hidden>
Date: Sat, 2 Feb 2019 14:39:59 -0800
Subject: [PATCH] vla: add commentary about VLA_ELEMS
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* lib/vla.h (VLA_ELEMS): Add commentary,
some inspired by Bruno Haible’s proposal in:
https://lists.gnu.org/r/bug-gnulib/2019-01/msg00109.html
---
 ChangeLog |  5 +++++
 lib/vla.h | 26 ++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)

diff --git a/ChangeLog b/ChangeLog
index 91ff7eaed..d16d437a2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2019-02-02  Paul Eggert  <address@hidden>
 
+	vla: add commentary about VLA_ELEMS
+	* lib/vla.h (VLA_ELEMS): Add commentary,
+	some inspired by Bruno Haible’s proposal in:
+	https://lists.gnu.org/r/bug-gnulib/2019-01/msg00109.html
+
 	dtoastr,ftoastr,ldtoastr: port to c-strtod changes
 	Decouple these modules from c-strtod.  Nowadays it’s reasonable to
 	assume the C99 signatures for strtod and strtold.  Programs that
diff --git a/lib/vla.h b/lib/vla.h
index f6ebba0ed..8f5dea76f 100644
--- a/lib/vla.h
+++ b/lib/vla.h
@@ -17,6 +17,20 @@
 
    Written by Paul Eggert.  */
 
+/* The VLA_ELEMS macro does not allocate variable-length arrays (VLAs),
+   so it does not have the security or performance issues commonly
+   associated with VLAs.  VLA_ELEMS is for exploiting a C11 feature
+   where a function can start like this:
+
+     double scan_array (int n, double v[static n])
+
+   to require a caller to pass a vector V with at least N elements;
+   this allows better static checking and performance in some cases.
+   In C11 this feature means that V is a VLA, so the feature is
+   supported only if __STDC_NO_VLA__ is defined, and for compatibility
+   to platforms that do not support VLAs, VLA_ELEMS (n) expands to
+   nothing when __STDC_NO_VLA__ is not defined.  */
+
 /* A function's argument must point to an array with at least N elements.
    Example: 'int main (int argc, char *argv[VLA_ELEMS (argc)]);'.  */
 
@@ -25,3 +39,15 @@
 #else
 # define VLA_ELEMS(n) static n
 #endif
+
+/* Although C99 requires support for variable-length arrays (VLAs),
+   some C compilers never supported VLAs and VLAs are optional in C11.
+   VLAs are controversial because their allocation may be unintended
+   or awkward to support, and large VLAs might cause security or
+   performance problems.  GCC can diagnose the use of VLAs via the
+   -Wvla and -Wvla-larger-than warnings options, and defining the
+   macro GNULIB_NO_VLA disables the allocation of VLAs in Gnulib code.
+
+   The VLA_ELEMS macro is unaffected by GNULIB_NO_VLA, since it does
+   not allocate VLAs.  Programs that use VLA_ELEMS should be compiled
+   with 'gcc -Wvla-larger-than' instead of with 'gcc -Wvla'.  */
-- 
2.17.1