diff options
Diffstat (limited to 'gcc/doc/extend.texi')
| -rw-r--r-- | gcc/doc/extend.texi | 41 |
1 files changed, 36 insertions, 5 deletions
diff --git a/gcc/doc/extend.texi b/gcc/doc/extend.texi index 046de36..70adf2d 100644 --- a/gcc/doc/extend.texi +++ b/gcc/doc/extend.texi @@ -7138,9 +7138,11 @@ The @code{aligned} attribute can also be used for functions @cindex @code{counted_by} variable attribute @item counted_by (@var{count}) The @code{counted_by} attribute may be attached to the C99 flexible array -member of a structure. It indicates that the number of the elements of the -array is given by the field "@var{count}" in the same structure as the -flexible array member. +member, or a pointer field of a structure. It indicates that the number +of the elements of the array that is held by the flexible array member +field, or is pointed to by the pointer field, is given by the field +"@var{count}" in the same structure as the flexible array member or the +pointer field. This attribute is available only in C for now. In C++ this attribute is ignored. @@ -7161,8 +7163,22 @@ struct P @{ @end smallexample @noindent -specifies that the @code{array} is a flexible array member whose number of -elements is given by the field @code{count} in the same structure. +specifies that the @code{array} is a flexible array member whose number +of elements is given by the field @code{count} in the same structure. + +@smallexample +struct PP @{ + size_t count2; + char other1; + char *array2 __attribute__ ((counted_by (count2))); + int other2; +@} *pp; +@end smallexample + +@noindent +specifies that the @code{array2} is an array that is pointed by the +pointer field, and its number of elements is given by the field +@code{count2} in the same structure. The field that represents the number of the elements should have an integer type. Otherwise, the compiler reports an error and ignores @@ -7171,6 +7187,12 @@ the attribute. When the field that represents the number of the elements is assigned a negative integer value, the compiler treats the value as zero. +The @code{counted_by} attribute is not allowed for a pointer to @code{void}, +a pointer to function, or a pointer to a structure or union that includes +a flexible array member. However, it is allowed for a pointer to +non-void incomplete structure or union types, as long as the type could +be completed before the first reference to the pointer. + An explicit @code{counted_by} annotation defines a relationship between two objects, @code{p->array} and @code{p->count}, and there are the following requirements on the relationship between this pair: @@ -7186,6 +7208,13 @@ available all the time. This relationship must hold even after any of these related objects are updated during the program. @end itemize +In addition to the above requirements, there is one more requirement +between this pair if and only if @code{p->array} is an array that is +pointed by the pointer field: + +@code{p->array} and @code{p->count} can only be changed by changing the +whole structure at the same time. + It's the programmer's responsibility to make sure the above requirements to be kept all the time. Otherwise the compiler reports warnings and the results of the array bound sanitizer and the @@ -7207,6 +7236,8 @@ In the above, @code{ref1} uses @code{val1} as the number of the elements in @code{p->array}, and @code{ref2} uses @code{val2} as the number of elements in @code{p->array}. +Note, however, the above feature is not valid for the pointer field. + @cindex @code{alloc_size} variable attribute @item alloc_size (@var{position}) @itemx alloc_size (@var{position-1}, @var{position-2}) |