On 02/15/2016 04:18 PM, Joseph Myers wrote:
The description here is self-contradictory; __BIGGEST_ALIGNMENT__ bytes is
often different from the greatest fundamental alignment (fundamental
alignments and max_align_t only consider standard C types,
__BIGGEST_ALIGNMENT__ can allow for e.g. vector type extensions).
Thank you for reviewing the patch. You're right that I conflated
fundamental alignment with the strictest alignment. I've adjusted
the description to make a distinction between __BIGGEST_ALIGNMENT__
and _Alignof(max_align_t) since they, as you point out, need not be
the same (for example on i386 Linux with GLIBC I see that the former
is 16 while the latter 8, which is correct because on GLIBC's malloc
returns 8-byte aligned pointers). I've also fixed a few typos and
made additional adjustments to reflect the fixes in my patch for
bug 69780 that I anticipate committing later this week.
That said, I think it's worth pointing out that max_align_t has
nothing to do with standard C types. The intent of the type is
to expose a type with the strictest alignment supported by
an implementation for an object of any type and with any storage
duration, not the alignment of the most strictly aligned basic
(or fundamental) type.
Martin
PR c/69759 - __builtin_alloca and __builtin_alloca_with_align undocumented
gcc/ChangeLog:
2016-02-15 Martin Sebor <mse...@redhat.com>
PR c/69759
* doc/extend.texi (Other Builtins): Document __builtin_alloca and
__builtin_alloca_with_align.
Index: gcc/doc/extend.texi
===================================================================
--- gcc/doc/extend.texi (revision 233367)
+++ gcc/doc/extend.texi (working copy)
@@ -10144,6 +10144,8 @@ in the Cilk Plus language manual which c
@node Other Builtins
@section Other Built-in Functions Provided by GCC
@cindex built-in functions
+@findex __builtin_alloca
+@findex __builtin_alloca_with_align
@findex __builtin_call_with_static_chain
@findex __builtin_fpclassify
@findex __builtin_isfinite
@@ -10690,6 +10692,93 @@ In the same fashion, GCC provides @code{
@code{__builtin_} prefixed. The @code{isinf} and @code{isnan}
built-in functions appear both with and without the @code{__builtin_} prefix.
+@deftypefn {Built-in Function} void* __builtin_alloca (size_t size)
+The @code{__builtin_alloca} function must be called at block scope.
+The function allocates an object @var{size} bytes large on the stack of
+the calling function. The object is aligned at the greatest supported
+alignment boundary for the target. The greatest supported alignment
+is the value of the @code{__BIGGEST_ALIGNMENT__} macro. Portable C11
+and C++11 (or later) programs can obtain a similar value by evaluating
+the @code{_Alignof (max_align_t)} and @code{alignof (std::max_align_t)}
+expressions, respectively, which yield an alignment suitable for any
+standard type in each language. @code{__builtin_alloca} returns a pointer
+to the first byte of the allocated object. The lifetime of the allocated
+object ends just before the calling function returns to its caller. This
+is so even when @code{__builtin_alloca_with_align} is called within a nested
+block.
+
+For example, the following function allocates eight objects of @code{n}
+bytes each on the stack, storing a pointer to each in consecutive elements
+of the array @code{a}. It then passes the array to function @code{g()}
+which can safely use the storage pointed to by each of the array elements.
+
+@smallexample
+void f (unsigned n)
+@{
+ void *a [8];
+ for (int i = 0; i != 8; ++i)
+ a [i] = __builtin_alloca (n);
+
+ g (a, n); // safe
+@}
+@end smallexample
+
+Since the @code{__builtin_alloca} function doesn't validate its arguments
+it is the responsibility of its caller to make sure the argument doesn't
+cause it doesn't exceed the stack size limit.
+The @code{__builtin_alloca} function is provided to make it possible to
+allocate arrays with a runtime bound on the stack. Since C99 variable
+length arrays offer similar functionality under a portable, more convenient,
+and safer interface they are recommended instead, in both C99 and C++
+programs where GCC provides them as an extension.
+
+@end deftypefn
+
+@deftypefn {Built-in Function} void* __builtin_alloca_with_align (size_t size, size_t align)
+The @code{__builtin_alloca_with_align} function must be called at block
+scope. The function allocates an object @var{size} bytes large on
+the stack of the calling function. The allocated object is aligned on
+the boundary specified by the argument @var{align} whose unit is given
+in bits (not bytes). @var{size} must be positive and not exceed the stack
+size limit. @var{align} must be a constant integer expression that
+evaluates to a power of 2 greater than or equal to @code{__CHAR_BIT__}.
+Invocations with other values are rejected with an error. The function
+returns a pointer to the first byte of the allocated object. The lifetime
+of the allocated object ends at the end of the block in which the function
+was called. The allocated storage is released no later than just before
+the calling function returns to its caller, but may be released as early
+as when control leaves the block in which the function was called.
+
+For example, in the following function the call to @code{g()} is unsafe
+because when @code{overalign} is non-zero, the space allocated by
+@code{__builtin_alloca_with_align} may have been released at the end
+of the @code{if} statement in which it was called.
+
+@smallexample
+void f (unsigned n, bool overalign)
+@{
+ void *p;
+ if (overalign)
+ p = __builtin_alloca_with_align (n, 64);
+ else
+ p = __builtin_alloc (n);
+
+ g (p, n); // unsafe
+@}
+@end smallexample
+
+Since the @code{__builtin_alloca_with_align} function doesn't validate
+the @code{size} argument it is the responsibility of its caller to make
+sure the argument doesn't cause it to exceed the stack size limit.
+The @code{__builtin_alloca_with_align} function is provided to make
+it possible to allocate overaligned arrays with a runtime bound on
+the stack. Since C99 variable length arrays offer the same functionality
+under a portable, more convenient, and safer interface they are recommended
+instead, in both C99 and C++ programs where GCC provides them as
+an extension.
+
+@end deftypefn
+
@deftypefn {Built-in Function} int __builtin_types_compatible_p (@var{type1}, @var{type2})
You can use the built-in function @code{__builtin_types_compatible_p} to
