Documentation of 'alloca' and 'alloca-opt' modules.

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 974f421..fd25789 100644 (file)
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2004-12-18  Bruno Haible  <bruno@clisp.org>
+
+       * alloca.texi: New file.
+       * alloca-opt.texi: New file.
+
 2004-12-08  Paul Eggert  <eggert@cs.ucla.edu>
 
        * getdate.texi (Time of day items, Time zone items):

diff --git a/doc/alloca-opt.texi b/doc/alloca-opt.texi
new file mode 100644 (file)
index 0000000..86f17cf
--- /dev/null
+++ b/doc/alloca-opt.texi
@@ -0,0 +1,16 @@
+@c Documentation of gnulib module 'alloca-opt'.
+
+The alloca-opt module provides for a function alloca() which allocates memory
+on the stack, where the system allows it. A memory block allocated with alloca()
+exists only until the function that calls alloca() returns or exits abruptly.
+
+There are a few systems where this is not possible: HP-UX systems, and some
+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 #include <alloca.h> on all platforms, and use 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 malloc() or - in C++ - 'new'. Note that the #include <alloca.h> must be
+the first one after the autoconf-generated config.h. Thanks to AIX for this nice
+restriction!

diff --git a/doc/alloca.texi b/doc/alloca.texi
new file mode 100644 (file)
index 0000000..e1421f0
--- /dev/null
+++ b/doc/alloca.texi
@@ -0,0 +1,19 @@
+@c Documentation of gnulib module 'alloca'.
+
+The alloca module provides for a function alloca() which allocates memory
+on the stack, where the system allows it. A memory block allocated with alloca()
+exists only until the function that calls alloca() returns or exits abruptly.
+
+There are a few systems where this is not possible: HP-UX systems, and some
+other platforms when the C++ compiler is used. On these platforms the alloca
+module provides a malloc() based emulation. This emulation will not free a
+memory block immediately when the calling function returns, but rather will
+wait until the next alloca() call from a function with the same or a shorter
+stack length. Thus, in some cases, a few memory blocks will be kept although
+they are not needed any more.
+
+The user can #include <alloca.h> and use alloca() on all platforms. Note
+that the #include <alloca.h> must be the first one after the autoconf-generated
+config.h. Thanks to AIX for this nice restriction!
+
+An alternative to this module is the 'alloca-opt' module.