On 02/16/2016 08:54 AM, Joseph Myers wrote:
On Tue, 16 Feb 2016, Martin Sebor wrote:
Max_align_t need not impact efficiency. In C, the malloc alignment
also need not have an impact on the type since aligned_alloc returns
storage that is (or can be) more strictly aligned.
As per the DR#445 resolution, malloc must return memory "whose alignment
is the greatest fundamental alignment". It's obviously necessary for
malloc to return memory sufficiently aligned for any object that can be
declared within the standard without using over-aligned types.
The DR #445 resolution goes against the intent of the type. It's
also incompatible with C++. Unless there's a C++ defect to change
it there too (I haven't found it), the C DR should be revisited to
make sure the languages remain compatible in this area.
If you disregard malloc, that is effectively unbounded (2^28 bytes at
least), with current GCC on ELF targets. This is not a useful thing to
query, and not useful for malloc to be required to return memory aligned
to.
Malloc is not (need not be) subject to the (original, pre-DR 445)
max_align_t alignment. What to define max_align_to when there
effectively is maximum alignment is a separate question.
But this discussion is tangential to the proposed documentation
update. After thinking about the context some more I've decided
that since code that uses __builtin_alloca or even alloca isn't
portable to begin with, mentioning max_align_t won't help it
become any more portable.
Attached is an updated patch with the mention of max_align_t
removed.
Martin
PR c/69759 - __builtin_alloca and __builtin_alloca_with_align undocumented
gcc/ChangeLog:
2016-02-16 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,89 @@ 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 default stack
+alignment boundary for the target determined by the
+@code{__BIGGEST_ALIGNMENT__} macro. @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{align} 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 called, but may be released at the end
+of 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 its
+arguments 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
