Stack Allocation (Using the GNU Compiler Collection (GCC))

### 7.3 Builtins for Stack Allocation ¶

Built-in Function: `void *` __builtin_alloca `(size_t size)` ¶

  The `__builtin_alloca` function must be called at block scope. The function allocates an object size bytes large on the stack of the calling function. The object is aligned on the default stack alignment boundary for the target determined by the `__BIGGEST_ALIGNMENT__` macro. The `__builtin_alloca` function 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 `__builtin_alloca` is called within a nested block.

  For example, the following function allocates eight objects of `n` bytes each on the stack, storing a pointer to each in consecutive elements of the array `a`. It then passes the array to function `g` which can safely use the storage pointed to by each of the array elements.

      void f (unsigned n)
      {
        void *a [8];
        for (int i = 0; i != 8; ++i)
          a [i] = __builtin_alloca (n);

        g (a, n);   // safe
      }

  Since the `__builtin_alloca` function doesn’t validate its argument it is the responsibility of its caller to make sure the argument doesn’t cause it to exceed the stack size limit. The `__builtin_alloca` function is provided to make it possible to allocate on the stack arrays of bytes with an upper bound that may be computed at run time. 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. See Arrays of Variable Length, for details.

Built-in Function: `void *` __builtin_alloca_with_align `(size_t size, size_t alignment)` ¶

  The `__builtin_alloca_with_align` function must be called at block scope. The function allocates an object size bytes large on the stack of the calling function. The allocated object is aligned on the boundary specified by the argument alignment whose unit is given in bits (not bytes). The size argument must be positive and not exceed the stack size limit. The alignment argument must be a constant integer expression that evaluates to a power of 2 greater than or equal to `CHAR_BIT` and less than some unspecified maximum. Invocations with other values are rejected with an error indicating the valid bounds. 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 at the end of the block in which the function was called.

  For example, in the following function the call to `g` is unsafe because when `overalign` is non-zero, the space allocated by `__builtin_alloca_with_align` may have been released at the end of the `if` statement in which it was called.

      void f (unsigned n, bool overalign)
      {
        void *p;
        if (overalign)
          p = __builtin_alloca_with_align (n, 64 /* bits */);
        else
          p = __builtin_alloc (n);

        g (p, n);   // unsafe
      }

  Since the `__builtin_alloca_with_align` function doesn’t validate its 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 `__builtin_alloca_with_align` function is provided to make it possible to allocate on the stack overaligned arrays of bytes with an upper bound that may be computed at run time. 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. See Arrays of Variable Length, for details.

Built-in Function: `void *` __builtin_alloca_with_align_and_max `(size_t size, size_t alignment, size_t max_size)` ¶

  Similar to `__builtin_alloca_with_align` but takes an extra argument specifying an upper bound for size in case its value cannot be computed at compile time, for use by `-fstack-usage`, `-Wstack-usage` and `-Walloca-larger-than`. max_size must be a constant integer expression, it has no effect on code generation and no attempt is made to check its compatibility with size.