diff options
author | Bruno Haible <bruno@clisp.org> | 2007-12-26 16:31:08 +0100 |
---|---|---|
committer | Bruno Haible <bruno@clisp.org> | 2007-12-26 16:31:08 +0100 |
commit | f0081f71b5ac063b48f242d6f770d7826f2ec196 (patch) | |
tree | 346b060fb346247031424b3238a728bfc2606dd9 /doc | |
parent | c293bc46ac85a0507c1fc0210529ab16d0c3260b (diff) | |
download | gnulib-f0081f71b5ac063b48f242d6f770d7826f2ec196.tar.gz |
Avoid using the syntax symbol() in formatted documentation.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/alloca-opt.texi | 40 | ||||
-rw-r--r-- | doc/alloca.texi | 39 | ||||
-rw-r--r-- | doc/error.texi | 2 | ||||
-rw-r--r-- | doc/gnulib-intro.texi | 4 | ||||
-rw-r--r-- | doc/gnulib.texi | 12 |
5 files changed, 70 insertions, 27 deletions
diff --git a/doc/alloca-opt.texi b/doc/alloca-opt.texi index 307a8f12f6..3fea8f359a 100644 --- a/doc/alloca-opt.texi +++ b/doc/alloca-opt.texi @@ -1,6 +1,6 @@ @c Documentation of gnulib module 'alloca-opt'. -@c Copyright (C) 2004 Free Software Foundation, Inc. +@c Copyright (C) 2004, 2007 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.2 or @@ -9,17 +9,33 @@ @c Texts. A copy of the license is included in the ``GNU Free @c Documentation License'' file as part of this distribution. -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. +The alloca-opt module provides for a function @code{alloca} which allocates +memory on the stack, where the system allows it. A memory block allocated with +@code{alloca} exists only until the function that calls @code{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. +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! +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: + +@smallexample +#ifdef __GNUC__ +__attribute__ ((__noinline__)) +#endif +@end smallexample diff --git a/doc/alloca.texi b/doc/alloca.texi index 704103912e..975cb998de 100644 --- a/doc/alloca.texi +++ b/doc/alloca.texi @@ -1,6 +1,6 @@ @c Documentation of gnulib module 'alloca'. -@c Copyright (C) 2004 Free Software Foundation, Inc. +@c Copyright (C) 2004, 2007 Free Software Foundation, Inc. @c Permission is granted to copy, distribute and/or modify this document @c under the terms of the GNU Free Documentation License, Version 1.2 or @@ -9,20 +9,35 @@ @c Texts. A copy of the license is included in the ``GNU Free @c Documentation License'' file as part of this distribution. -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. +The alloca module provides for a function @code{alloca} which allocates +memory on the stack, where the system allows it. A memory block allocated with +@code{alloca} exists only until the function that calls @code{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 +module provides a @code{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. +wait until the next @code{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! +The user can @code{#include <alloca.h>} and use @code{alloca} on all platforms. +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! -An alternative to this module is the 'alloca-opt' module. +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: + +@smallexample +#ifdef __GNUC__ +__attribute__ ((__noinline__)) +#endif +@end smallexample + +An alternative to this module is the @samp{alloca-opt} module. diff --git a/doc/error.texi b/doc/error.texi index 3a80486f34..2f669db789 100644 --- a/doc/error.texi +++ b/doc/error.texi @@ -22,5 +22,5 @@ replacement @code{program_name}, and a GPL user should manually specify using the @code{progname} module. Additionally, using the @code{progname} module is not something that -can be done implicitly. It requires that every @code{main()} function +can be done implicitly. It requires that every @code{main} function be modified to set @code{program_name} as one of its first actions. diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi index d5d7408086..c42a208034 100644 --- a/doc/gnulib-intro.texi +++ b/doc/gnulib-intro.texi @@ -35,7 +35,7 @@ that. Similarly, Gnulib has a facility for executing a command in a subprocess. It is at the same time a portability enhancement (it works on GNU, Unix, and Windows, compared to the classical -@code{fork()}/@code{exec()} which is not portable to Windows), as well +@code{fork}/@code{exec} idiom which is not portable to Windows), as well as an application aid: it takes care of redirecting stdin and/or stdout if desired, and emits an error message if the subprocess failed. @@ -175,7 +175,7 @@ C++ language or from the Linux kernel. @subsection Interfaces to external libraries Examples are the @samp{iconv} module, which interfaces to the -@code{iconv()} facility, regardless whether it is contained in libc or in +@code{iconv} facility, regardless whether it is contained in libc or in an external @code{libiconv}. Or the @samp{readline} module, which interfaces to the GNU readline library. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index ca52fdc9c7..c4f285d3c8 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -2891,6 +2891,8 @@ If you need this particular function, you may write to @chapter Particular Modules @menu +* alloca:: +* alloca-opt:: * Quoting:: * error and progname:: * gcd:: @@ -2898,6 +2900,16 @@ If you need this particular function, you may write to * Supporting Relocation:: @end menu +@node alloca +@section alloca +@findex alloca +@include alloca.texi + +@node alloca-opt +@section alloca-opt +@findex alloca +@include alloca-opt.texi + @include quote.texi @include error.texi @include gcd.texi |