From ce5de1c1b35f8fcc69b9a2c2f1fcc59f1f3ee5cc Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Sat, 18 Dec 2004 16:27:31 +0000 Subject: [PATCH] Documentation of 'alloca' and 'alloca-opt' modules. --- doc/ChangeLog | 5 +++++ doc/alloca-opt.texi | 16 ++++++++++++++++ doc/alloca.texi | 19 +++++++++++++++++++ 3 files changed, 40 insertions(+) create mode 100644 doc/alloca-opt.texi create mode 100644 doc/alloca.texi diff --git a/doc/ChangeLog b/doc/ChangeLog index 974f421d17..fd25789aa2 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,8 @@ +2004-12-18 Bruno Haible + + * alloca.texi: New file. + * alloca-opt.texi: New file. + 2004-12-08 Paul Eggert * 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 index 0000000000..86f17cf6a4 --- /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 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 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 index 0000000000..e1421f0b0d --- /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 and use alloca() on all platforms. Note +that the #include 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. -- 2.30.2