-other platforms when the C++ compiler is used. On these platforms the alloca-opt
-module provides no replacement, just a preprocessor macro HAVE_ALLOCA.
+other platforms when the C++ compiler is used. On these platforms the
+alloca-opt module provides no replacement, just a preprocessor macro
+HAVE_ALLOCA.
+
+The user can @code{#include <alloca.h>} on all platforms, and use
+@code{alloca} on those platforms where the preprocessor macro HAVE_ALLOCA
+evaluates to true. If HAVE_ALLOCA is false, the code should use a heap-based
+memory allocation based on @code{malloc} or (in C++) @code{new}. Note that
+the @code{#include <alloca.h>} must be the first one after the
+autoconf-generated @file{config.h}, for AIX 3 compatibility. Thanks to IBM for
+this nice restriction!
+
+Note that GCC 3.1 and 3.2 can @emph{inline} functions that call @code{alloca}.
+When this happens, the memory blocks allocated with @code{alloca} will not be
+freed until @emph{the end of the calling function}. If this calling function
+runs a loop calling the function that uses @code{alloca}, the program easily
+gets a stack overflow and crashes. To protect against this compiler behaviour,
+you can mark the function that uses @code{alloca} with the following attribute: