the obstack automatically starts on an address that is a multiple of the
specified boundary.  By default, this boundary is 4 bytes.
<P>
To access an obstack's alignment boundary, use the macro
<CODE>obstack_alignment_mask</CODE>, whose function prototype looks like
this:
<P>
<A NAME="IDX202"></A>
<U>Macro:</U> int <B>obstack_alignment_mask</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
The value is a bit mask; a bit that is 1 indicates that the corresponding
bit in the address of an object should be 0.  The mask value should be one
less than a power of 2; the effect is that all object addresses are
multiples of that power of 2.  The default value of the mask is 3, so that
addresses are multiples of 4.  A mask value of 0 means an object can start
on any multiple of 1 (that is, no alignment is required).
<P>
The expansion of the macro <CODE>obstack_alignment_mask</CODE> is an lvalue,
so you can alter the mask by assignment.  For example, this statement:
<P>
<PRE>
obstack_alignment_mask (obstack_ptr) = 0;
</PRE>
<P>
has the effect of turning off alignment processing in the specified obstack.
<P>
Note that a change in alignment mask does not take effect until
<EM>after</EM> the next time an object is allocated or finished in the
obstack.  If you are not growing an object, you can make the new
alignment mask take effect immediately by calling <CODE>obstack_finish</CODE>.
This will finish a zero-length object and then do proper alignment for
the next object.
<P>
<A NAME="IDX203"></A>
<A NAME="IDX204"></A>
<H3><A NAME="SEC43" HREF="library_toc.html#SEC43" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC43">Obstack Chunks</A></H3>
<P>
Obstacks work by allocating space for themselves in large chunks, and
then parceling out space in the chunks to satisfy your requests.  Chunks
are normally 4096 bytes long unless you specify a different chunk size.
The chunk size includes 8 bytes of overhead that are not actually used
for storing objects.  Regardless of the specified size, longer chunks
will be allocated when necessary for long objects.
<P>
The obstack library allocates chunks by calling the function
<CODE>obstack_chunk_alloc</CODE>, which you must define.  When a chunk is no
longer needed because you have freed all the objects in it, the obstack
library frees the chunk by calling <CODE>obstack_chunk_free</CODE>, which you
must also define.
<P>
These two must be defined (as macros) or declared (as functions) in each
source file that uses <CODE>obstack_init</CODE> (see section <A HREF="library_3.html#SEC34" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC34">Creating Obstacks</A>).
Most often they are defined as macros like this:
<P>
<PRE>
#define obstack_chunk_alloc xmalloc
#define obstack_chunk_free free
</PRE>
<P>
Note that these are simple macros (no arguments).  Macro definitions with
arguments will not work!  It is necessary that <CODE>obstack_chunk_alloc</CODE>
or <CODE>obstack_chunk_free</CODE>, alone, expand into a function name if it is
not itself a function name.
<P>
The function that actually implements <CODE>obstack_chunk_alloc</CODE> cannot
return "failure" in any fashion, because the obstack library is not
prepared to handle failure.  Therefore, <CODE>malloc</CODE> itself is not
suitable.  If the function cannot obtain space, it should either
terminate the process (see section <A HREF="library_22.html#SEC395" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_22.html#SEC395">Program Termination</A>) or do a nonlocal
exit using <CODE>longjmp</CODE> (see section <A HREF="library_20.html#SEC326" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_20.html#SEC326">Non-Local Exits</A>).
<P>
If you allocate chunks with <CODE>malloc</CODE>, the chunk size should be a
power of 2.  The default chunk size, 4096, was chosen because it is long
enough to satisfy many typical requests on the obstack yet short enough
not to waste too much memory in the portion of the last chunk not yet used.
<P>
<A NAME="IDX205"></A>
<U>Macro:</U> size_t <B>obstack_chunk_size</B> <I>(struct obstack *<VAR>obstack_ptr</VAR>)</I><P>
This returns the chunk size of the given obstack.
<P>
Since this macro expands to an lvalue, you can specify a new chunk size by
assigning it a new value.  Doing so does not affect the chunks already
allocated, but will change the size of chunks allocated for that particular
obstack in the future.  It is unlikely to be useful to make the chunk size
smaller, but making it larger might improve efficiency if you are
allocating many objects whose size is comparable to the chunk size.  Here
is how to do so cleanly:
<P>
<PRE>
if (obstack_chunk_size (obstack_ptr) &#60; <VAR>new_chunk_size</VAR>)
  obstack_chunk_size (obstack_ptr) = <VAR>new_chunk_size</VAR>;
</PRE>
<P>
<H3><A NAME="SEC44" HREF="library_toc.html#SEC44" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC44">Summary of Obstack Functions</A></H3>
<P>
Here is a summary of all the functions associated with obstacks.  Each
takes the address of an obstack (<CODE>struct obstack *</CODE>) as its first
argument.
<P>
<DL COMPACT>
<DT><CODE>void obstack_init (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Initialize use of an obstack.  See section <A HREF="library_3.html#SEC34" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC34">Creating Obstacks</A>.
<P>
<DT><CODE>void *obstack_alloc (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Allocate an object of <VAR>size</VAR> uninitialized bytes.
See section <A HREF="library_3.html#SEC36" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void *obstack_copy (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Allocate an object of <VAR>size</VAR> bytes, with contents copied from
<VAR>address</VAR>.  See section <A HREF="library_3.html#SEC36" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void *obstack_copy0 (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Allocate an object of <VAR>size</VAR>+1 bytes, with <VAR>size</VAR> of them copied
from <VAR>address</VAR>, followed by a null character at the end.
See section <A HREF="library_3.html#SEC36" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC36">Allocation in an Obstack</A>.
<P>
<DT><CODE>void obstack_free (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>object</VAR>)</CODE>
<DD>Free <VAR>object</VAR> (and everything allocated in the specified obstack
more recently than <VAR>object</VAR>).  See section <A HREF="library_3.html#SEC37" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC37">Freeing Objects in an Obstack</A>.
<P>
<DT><CODE>void obstack_blank (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Add <VAR>size</VAR> uninitialized bytes to a growing object.
See section <A HREF="library_3.html#SEC39" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_grow (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Add <VAR>size</VAR> bytes, copied from <VAR>address</VAR>, to a growing object.
See section <A HREF="library_3.html#SEC39" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_grow0 (struct obstack *<VAR>obstack_ptr</VAR>, void *<VAR>address</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Add <VAR>size</VAR> bytes, copied from <VAR>address</VAR>, to a growing object,
and then add another byte containing a null character.  See section <A HREF="library_3.html#SEC39" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_1grow (struct obstack *<VAR>obstack_ptr</VAR>, char <VAR>data_char</VAR>)</CODE>
<DD>Add one byte containing <VAR>data_char</VAR> to a growing object.
See section <A HREF="library_3.html#SEC39" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void *obstack_finish (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Finalize the object that is growing and return its permanent address.
See section <A HREF="library_3.html#SEC39" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>size_t obstack_object_size (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Get the current size of the currently growing object.  See section <A HREF="library_3.html#SEC39" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC39">Growing Objects</A>.
<P>
<DT><CODE>void obstack_blank_fast (struct obstack *<VAR>obstack_ptr</VAR>, size_t <VAR>size</VAR>)</CODE>
<DD>Add <VAR>size</VAR> uninitialized bytes to a growing object without checking
that there is enough room.  See section <A HREF="library_3.html#SEC40" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>void obstack_1grow_fast (struct obstack *<VAR>obstack_ptr</VAR>, char <VAR>data_char</VAR>)</CODE>
<DD>Add one byte containing <VAR>data_char</VAR> to a growing object without
checking that there is enough room.  See section <A HREF="library_3.html#SEC40" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>size_t obstack_room (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Get the amount of room now available for growing the current object.
See section <A HREF="library_3.html#SEC40" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC40">Extra Fast Growing Objects</A>.
<P>
<DT><CODE>int obstack_alignment_mask (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>The mask used for aligning the beginning of an object.  This is an
lvalue.  See section <A HREF="library_3.html#SEC42" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC42">Alignment of Data in Obstacks</A>.
<P>
<DT><CODE>size_t obstack_chunk_size (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>The size for allocating chunks.  This is an lvalue.  See section <A HREF="library_3.html#SEC43" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC43">Obstack Chunks</A>.
<P>
<DT><CODE>void *obstack_base (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Tentative starting address of the currently growing object.
See section <A HREF="library_3.html#SEC41" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC41">Status of an Obstack</A>.
<P>
<DT><CODE>void *obstack_next_free (struct obstack *<VAR>obstack_ptr</VAR>)</CODE>
<DD>Address just after the end of the currently growing object.
See section <A HREF="library_3.html#SEC41" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC41">Status of an Obstack</A>.
</DL>
<P>
<A NAME="IDX206"></A>
<A NAME="IDX207"></A>
<A NAME="IDX208"></A>
<H2><A NAME="SEC45" HREF="library_toc.html#SEC45" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC45">Automatic Storage with Variable Size</A></H2>
<P>
The function <CODE>alloca</CODE> supports a kind of half-dynamic allocation in
which blocks are allocated dynamically but freed automatically.
<P>
Allocating a block with <CODE>alloca</CODE> is an explicit action; you can
allocate as many blocks as you wish, and compute the size at run time.  But
all the blocks are freed when you exit the function that <CODE>alloca</CODE> was
called from, just as if they were automatic variables declared in that
function.  There is no way to free the space explicitly.
<P>
The prototype for <CODE>alloca</CODE> is in <TT>`stdlib.h'</TT>.  This function is
a BSD extension.
<A NAME="IDX209"></A>
<P>
<A NAME="IDX210"></A>
<U>Function:</U> void * <B>alloca</B> <I>(size_t <VAR>size</VAR>);</I><P>
The return value of <CODE>alloca</CODE> is the address of a block of <VAR>size</VAR>
bytes of storage, allocated in the stack frame of the calling function.
<P>
Do not use <CODE>alloca</CODE> inside the arguments of a function call--you
will get unpredictable results, because the stack space for the
<CODE>alloca</CODE> would appear on the stack in the middle of the space for
the function arguments.  An example of what to avoid is <CODE>foo (x,
alloca (4), y)</CODE>.
<P>
<H3><A NAME="SEC46" HREF="library_toc.html#SEC46" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC46"><CODE>alloca</CODE> Example</A></H3>
<P>
As an example of use of <CODE>alloca</CODE>, here is a function that opens a file
name made from concatenating two argument strings, and returns a file
descriptor or minus one signifying failure:
<P>
<PRE>
int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
  strcpy (name, str1);
  strcat (name, str2);
  return open (name, flags, mode);
}
</PRE>
<P>
Here is how you would get the same results with <CODE>malloc</CODE> and
<CODE>free</CODE>:
<P>
<PRE>
int
open2 (char *str1, char *str2, int flags, int mode)
{
  char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
  int desc;
  if (name == 0)
    fatal ("virtual memory exceeded");
  strcpy (name, str1);
  strcat (name, str2);
  desc = open (name, flags, mode);
  free (name);
  return desc;
}
</PRE>
<P>
As you can see, it is simpler with <CODE>alloca</CODE>.  But <CODE>alloca</CODE> has
other, more important advantages, and some disadvantages.
<P>
<H3><A NAME="SEC47" HREF="library_toc.html#SEC47" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC47">Advantages of <CODE>alloca</CODE></A></H3>
<P>
Here are the reasons why <CODE>alloca</CODE> may be preferable to <CODE>malloc</CODE>:
<P>
<UL>
<LI>
Using <CODE>alloca</CODE> wastes very little space and is very fast.  (It is
open-coded by the GNU C compiler.)
<P>
<LI>
Since <CODE>alloca</CODE> does not have separate pools for different sizes of
block, space used for any size block can be reused for any other size.
<CODE>alloca</CODE> does not cause storage fragmentation.
<P>
<A NAME="IDX211"></A>
<LI>
Nonlocal exits done with <CODE>longjmp</CODE> (see section <A HREF="library_20.html#SEC326" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_20.html#SEC326">Non-Local Exits</A>)
automatically free the space allocated with <CODE>alloca</CODE> when they exit
through the function that ca