diff mbox series

PING [PATCH] update Zero-length array documentation

Message ID 79b0b9b2-0e9d-74e6-ce1c-021ce6e900ac@gmail.com
State New
Headers show
Series PING [PATCH] update Zero-length array documentation | expand

Commit Message

Martin Sebor June 18, 2018, 11 p.m. UTC 
Attached is an updated patch with the additional text as
discussed below.

Martin

On 06/11/2018 03:05 PM, Martin Sebor wrote:
> On 06/11/2018 02:03 PM, Richard Sandiford wrote:
>> Martin Sebor <msebor@gmail.com> writes:
>>> On 06/11/2018 12:08 PM, Richard Sandiford wrote:
>>>> Martin Sebor <msebor@gmail.com> writes:
>>>>> @@ -1553,12 +1553,28 @@ 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}.
>>>>> +Although the size of a zero-length array is zero, an array member of
>>>>> +this kind may increase the size 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.
>>>>>
>>>>> -In ISO C99, you would use a @dfn{flexible array member}, which is
>>>>> -slightly different in syntax and semantics:
>>>>> +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.  Although this technique is discouraged,
>>>>> GCC
>>>>> +handles trailing one-element array members similarly to zero-length
>>>>> +arrays.
>>>>
>>>> This last sentence seems a bit vague.  E.g. GCC should never diagnose
>>>> an access to element 0 of a 1-element trailing array, whereas (like you
>>>> say above) it might for zero-length trailing arrays.
>>>
>>> GCC doesn't diagnose past-the-end accesses to trailing member
>>> arrays regardless of their size.  I don't think it should start
>>> diagnosing them for zero-length arrays, and probably not even
>>> for one-element arrays (at least not in C90 mode).  I think in
>>> the future it would be worthwhile to consider diagnosing past-
>>> the-end accesses to trailing member arrays of two or more
>>> elements, but this patch isn't meant to suggest it's done yet.
>>> At the same time, I do want to leave the door open to diagnosing
>>> such accesses eventually, so I don't want to go into too much
>>> detail describing exactly what is and what isn't diagnosed today.
>>
>> Yeah, agree that we shouldn't go into detail about what is
>> and isn't diagnosed.  I just don't think we should claim that
>> one-element arrays are treated "similarly" to zero-length arrays
>> without saying what "similarly" means.  They're certainly different
>> at some level, otherwise the extension wouldn't have been added :-)
>>
>> If we don't want to give much more detail about this then I think it
>> would be better to keep the original paragraph:
>>
>>   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}.
>>
>> instead of the last one.  (The other changes look good to me FWIW.)
>
> I changed it because the text seemed both vague (why does it waste
> space and what complication to the malloc call would avoid wasting
> it?) and superfluous (it seems obvious that a one-element array
> takes up at least 1 unit worth of space, and that allocating less
> would mean changing the malloc argument).  But perhaps it would
> be helpful to be explicit about the allocation size while still
> saying as little as possible about diagnostics.  How abut this:
>
>   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.
>
>>
>> Noticed later,
>>
>>> +The preferred mechanism to declare variable-length types like
>>> +@code{struct line} above is the ISO C99 @dfn{flexible array member},
>>> +with slightly different in syntax and semantics:
>>
>> Don't think the s/which is/with/ change is correct here.
>
> Thanks, fixed.
>
> Martin

Comments

Jeff Law June 23, 2018, 4:55 a.m. UTC | #1 
On 06/18/2018 05:00 PM, Martin Sebor wrote:
> Attached is an updated patch with the additional text as
> discussed below.
OK with a ChangeLog entry.

jeff
diff mbox series

Patch

gcc/ChangeLog:

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

Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi	(revision 261716)
+++ gcc/doc/extend.texi	(working copy)
@@ -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,12 +1552,31 @@  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}.
+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.
 
-In ISO C99, you would use a @dfn{flexible array member}, which is
-slightly different in syntax and semantics:
+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
 Flexible array members are written as @code{contents[]} without