alloca() in gdbint.texi

[Nick Duffek]

On 30-Nov-2000, Andrew Cagney wrote:

>Looks like the alloca() discussion has died down.  If you're still
>motivated then now is probably the time to go back through and come up
>with a section explaining alloca() and its limitations.

Here's a revised section that incorporates many of the suggestions made
during the discussion.  It's a subsection of the "GDB Coding Standards".

Memory Allocation
-----------------

   Heap memory must be allocated using libiberty's `xmalloc',
`xcalloc', `xrealloc', `xstrdup', and `xmemdup' functions, which have
the following advantages over their C library counterparts:

   * The size parameter to `xmalloc', `xcalloc', and `xrealloc' may be
     0.

   * The pointer parameter to `xrealloc' may be NULL.

   * Out-of-memory conditions are handled gracefully.

   In addition, small amounts of memory may be allocated from the stack
using `alloca', which is useful for avoiding cleanup chains in
functions that might return nonlocally.

   However, `alloca' should be used sparingly because:

   * Stack space often is limited.  For example, the default stack
     limit is 8 megabytes on many UNIXes, 2 megabytes on Digital UNIX,
     and 512 kilobytes in DJGPP-compiled programs.

   * Some systems impose limits on stack frame sizes.  It is rumored
     that AIX limits stack frames to 64 kilobytes, and other systems may
     have problems with frames larger than a page.

   * Out-of-stack conditions are not handled gracefully.

   As a rule of thumb, `alloca' should be used only for allocations
guaranteed to be less than a kilobyte or so.

   On some systems, GDB uses libiberty's `alloca' emulation because a
native `alloca' is not available.  To support those systems, it is
important that GDB garbage-collect freed space by calling `alloca' when
the stack is shallow.  Toward that end, each interface to the GDB core
-- for example, GDBTK, libgdb, and the text console -- should ensure
that `alloca (0)' is called periodically.  In addition, GDB calls
`alloca (0)' once per inferior wait.

   Because GDB and other GNU programs use `alloca', they are not
portable to systems that neither provide a native `alloca' nor support
libiberty's `alloca' emulation.  Since GCC provides a native `alloca',
such systems are rare.

Nick