extend.texi (Zero-length arrays): Update and clarify.

gcc/ChangeLog:

	* doc/extend.texi (Zero-length arrays): Update and clarify.

From-SVN: r262109

2 files changed, 31 insertions, 8 deletions

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index b5558a0..07db821 100644
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,7 @@
+2018-06-25  Martin Sebor  <msebor@redhat.com>
+
+	* doc/extend.texi (Zero-length arrays): Update and clarify.
+
 2018-06-25  Michael Meissner  <meissner@linux.ibm.com>
 
 	* config.gcc (powerpc64le*): Revert January 16th, 2018 patch that
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi
index cf88175..19c2da2 100644
--- a/gcc/doc/extend.texi
+++ b/gcc/doc/extend.texi
@@ -1537,9 +1537,9 @@ defined when these address spaces are supported.
 @cindex length-zero arrays
 @cindex flexible array members
 
-Zero-length arrays are allowed in GNU C@.  They are very useful as the
-last element of a structure that is really a header for a variable-length
-object:
+Declaring zero-length arrays is allowed in GNU C as an extension.
+A zero-length array can be useful as the last element of a structure
+that is really a header for a variable-length object:
 
 @smallexample
 struct line @{
@@ -1552,11 +1552,30 @@ struct line *thisline = (struct line *)
 thisline->length = this_length;
 @end smallexample
 
-In ISO C90, you would have to give @code{contents} a length of 1, which
-means either you waste space or complicate the argument to @code{malloc}.
-
-In ISO C99, you would use a @dfn{flexible array member}, which is
-slightly different in syntax and semantics:
+Although the size of a zero-length array is zero, an array member of
+this kind may increase the size of the enclosing type as a result of tail
+padding.  The offset of a zero-length array member from the beginning
+of the enclosing structure is the same as the offset of an array with
+one or more elements of the same type.  The alignment of a zero-length
+array is the same as the alignment of its elements.
+
+Declaring zero-length arrays in other contexts, including as interior
+members of structure objects or as non-member objects, is discouraged.
+Accessing elements of zero-length arrays declared in such contexts is
+undefined and may be diagnosed.
+
+In the absence of the zero-length array extension, in ISO C90
+the @code{contents} array in the example above would typically be declared
+to have a single element.  Unlike a zero-length array which only contributes
+to the size of the enclosing structure for the purposes of alignment,
+a one-element array always occupies at least as much space as a single
+object of the type.  Although using one-element arrays this way is
+discouraged, GCC handles accesses to trailing one-element array members
+analogously to zero-length arrays.
+
+The preferred mechanism to declare variable-length types like
+@code{struct line} above is the ISO C99 @dfn{flexible array member},
+with slightly different syntax and semantics:
 
 @itemize @bullet
 @item