1*5ba6b03cSchristos@node Obstacks 2*5ba6b03cSchristos@subsection Obstacks 32a6b7db3Sskrll@cindex obstacks 42a6b7db3Sskrll 52a6b7db3SskrllAn @dfn{obstack} is a pool of memory containing a stack of objects. You 62a6b7db3Sskrllcan create any number of separate obstacks, and then allocate objects in 72a6b7db3Sskrllspecified obstacks. Within each obstack, the last object allocated must 82a6b7db3Sskrllalways be the first one freed, but distinct obstacks are independent of 92a6b7db3Sskrlleach other. 102a6b7db3Sskrll 112a6b7db3SskrllAside from this one constraint of order of freeing, obstacks are totally 122a6b7db3Sskrllgeneral: an obstack can contain any number of objects of any size. They 132a6b7db3Sskrllare implemented with macros, so allocation is usually very fast as long as 142a6b7db3Sskrllthe objects are usually small. And the only space overhead per object is 152a6b7db3Sskrllthe padding needed to start each object on a suitable boundary. 162a6b7db3Sskrll 172a6b7db3Sskrll@menu 182a6b7db3Sskrll* Creating Obstacks:: How to declare an obstack in your program. 192a6b7db3Sskrll* Preparing for Obstacks:: Preparations needed before you can 202a6b7db3Sskrll use obstacks. 212a6b7db3Sskrll* Allocation in an Obstack:: Allocating objects in an obstack. 222a6b7db3Sskrll* Freeing Obstack Objects:: Freeing objects in an obstack. 23*5ba6b03cSchristos* Obstack Functions:: The obstack functions are really macros. 242a6b7db3Sskrll* Growing Objects:: Making an object bigger by stages. 252a6b7db3Sskrll* Extra Fast Growing:: Extra-high-efficiency (though more 262a6b7db3Sskrll complicated) growing objects. 272a6b7db3Sskrll* Status of an Obstack:: Inquiries about the status of an obstack. 282a6b7db3Sskrll* Obstacks Data Alignment:: Controlling alignment of objects in obstacks. 292a6b7db3Sskrll* Obstack Chunks:: How obstacks obtain and release chunks; 302a6b7db3Sskrll efficiency considerations. 312a6b7db3Sskrll* Summary of Obstacks:: 322a6b7db3Sskrll@end menu 332a6b7db3Sskrll 342a6b7db3Sskrll@node Creating Obstacks 35*5ba6b03cSchristos@subsubsection Creating Obstacks 362a6b7db3Sskrll 372a6b7db3SskrllThe utilities for manipulating obstacks are declared in the header 382a6b7db3Sskrllfile @file{obstack.h}. 392a6b7db3Sskrll@pindex obstack.h 402a6b7db3Sskrll 412a6b7db3Sskrll@comment obstack.h 422a6b7db3Sskrll@comment GNU 432a6b7db3Sskrll@deftp {Data Type} {struct obstack} 442a6b7db3SskrllAn obstack is represented by a data structure of type @code{struct 452a6b7db3Sskrllobstack}. This structure has a small fixed size; it records the status 462a6b7db3Sskrllof the obstack and how to find the space in which objects are allocated. 472a6b7db3SskrllIt does not contain any of the objects themselves. You should not try 48*5ba6b03cSchristosto access the contents of the structure directly; use only the macros 492a6b7db3Sskrlldescribed in this chapter. 502a6b7db3Sskrll@end deftp 512a6b7db3Sskrll 522a6b7db3SskrllYou can declare variables of type @code{struct obstack} and use them as 532a6b7db3Sskrllobstacks, or you can allocate obstacks dynamically like any other kind 542a6b7db3Sskrllof object. Dynamic allocation of obstacks allows your program to have a 552a6b7db3Sskrllvariable number of different stacks. (You can even allocate an 562a6b7db3Sskrllobstack structure in another obstack, but this is rarely useful.) 572a6b7db3Sskrll 58*5ba6b03cSchristosAll the macros that work with obstacks require you to specify which 592a6b7db3Sskrllobstack to use. You do this with a pointer of type @code{struct obstack 602a6b7db3Sskrll*}. In the following, we often say ``an obstack'' when strictly 612a6b7db3Sskrllspeaking the object at hand is such a pointer. 622a6b7db3Sskrll 632a6b7db3SskrllThe objects in the obstack are packed into large blocks called 642a6b7db3Sskrll@dfn{chunks}. The @code{struct obstack} structure points to a chain of 652a6b7db3Sskrllthe chunks currently in use. 662a6b7db3Sskrll 672a6b7db3SskrllThe obstack library obtains a new chunk whenever you allocate an object 682a6b7db3Sskrllthat won't fit in the previous chunk. Since the obstack library manages 692a6b7db3Sskrllchunks automatically, you don't need to pay much attention to them, but 702a6b7db3Sskrllyou do need to supply a function which the obstack library should use to 712a6b7db3Sskrllget a chunk. Usually you supply a function which uses @code{malloc} 722a6b7db3Sskrlldirectly or indirectly. You must also supply a function to free a chunk. 732a6b7db3SskrllThese matters are described in the following section. 742a6b7db3Sskrll 752a6b7db3Sskrll@node Preparing for Obstacks 76*5ba6b03cSchristos@subsubsection Preparing for Using Obstacks 772a6b7db3Sskrll 78*5ba6b03cSchristosEach source file in which you plan to use obstacks 792a6b7db3Sskrllmust include the header file @file{obstack.h}, like this: 802a6b7db3Sskrll 812a6b7db3Sskrll@smallexample 822a6b7db3Sskrll#include <obstack.h> 832a6b7db3Sskrll@end smallexample 842a6b7db3Sskrll 852a6b7db3Sskrll@findex obstack_chunk_alloc 862a6b7db3Sskrll@findex obstack_chunk_free 872a6b7db3SskrllAlso, if the source file uses the macro @code{obstack_init}, it must 88*5ba6b03cSchristosdeclare or define two macros that will be called by the 892a6b7db3Sskrllobstack library. One, @code{obstack_chunk_alloc}, is used to allocate 902a6b7db3Sskrllthe chunks of memory into which objects are packed. The other, 912a6b7db3Sskrll@code{obstack_chunk_free}, is used to return chunks when the objects in 922a6b7db3Sskrllthem are freed. These macros should appear before any use of obstacks 932a6b7db3Sskrllin the source file. 942a6b7db3Sskrll 952a6b7db3SskrllUsually these are defined to use @code{malloc} via the intermediary 962a6b7db3Sskrll@code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}). This is done with 972a6b7db3Sskrllthe following pair of macro definitions: 982a6b7db3Sskrll 992a6b7db3Sskrll@smallexample 1002a6b7db3Sskrll#define obstack_chunk_alloc xmalloc 1012a6b7db3Sskrll#define obstack_chunk_free free 1022a6b7db3Sskrll@end smallexample 1032a6b7db3Sskrll 1042a6b7db3Sskrll@noindent 1052a6b7db3SskrllThough the memory you get using obstacks really comes from @code{malloc}, 1062a6b7db3Sskrllusing obstacks is faster because @code{malloc} is called less often, for 1072a6b7db3Sskrlllarger blocks of memory. @xref{Obstack Chunks}, for full details. 1082a6b7db3Sskrll 1092a6b7db3SskrllAt run time, before the program can use a @code{struct obstack} object 1102a6b7db3Sskrllas an obstack, it must initialize the obstack by calling 111*5ba6b03cSchristos@code{obstack_init} or one of its variants, @code{obstack_begin}, 112*5ba6b03cSchristos@code{obstack_specify_allocation}, or 113*5ba6b03cSchristos@code{obstack_specify_allocation_with_arg}. 1142a6b7db3Sskrll 1152a6b7db3Sskrll@comment obstack.h 1162a6b7db3Sskrll@comment GNU 1172a6b7db3Sskrll@deftypefun int obstack_init (struct obstack *@var{obstack-ptr}) 1182a6b7db3SskrllInitialize obstack @var{obstack-ptr} for allocation of objects. This 119*5ba6b03cSchristosmacro calls the obstack's @code{obstack_chunk_alloc} function. If 1202a6b7db3Sskrllallocation of memory fails, the function pointed to by 1212a6b7db3Sskrll@code{obstack_alloc_failed_handler} is called. The @code{obstack_init} 122*5ba6b03cSchristosmacro always returns 1 (Compatibility notice: Former versions of 1232a6b7db3Sskrllobstack returned 0 if allocation failed). 1242a6b7db3Sskrll@end deftypefun 1252a6b7db3Sskrll 1262a6b7db3SskrllHere are two examples of how to allocate the space for an obstack and 1272a6b7db3Sskrllinitialize it. First, an obstack that is a static variable: 1282a6b7db3Sskrll 1292a6b7db3Sskrll@smallexample 1302a6b7db3Sskrllstatic struct obstack myobstack; 1312a6b7db3Sskrll@dots{} 1322a6b7db3Sskrllobstack_init (&myobstack); 1332a6b7db3Sskrll@end smallexample 1342a6b7db3Sskrll 1352a6b7db3Sskrll@noindent 1362a6b7db3SskrllSecond, an obstack that is itself dynamically allocated: 1372a6b7db3Sskrll 1382a6b7db3Sskrll@smallexample 1392a6b7db3Sskrllstruct obstack *myobstack_ptr 1402a6b7db3Sskrll = (struct obstack *) xmalloc (sizeof (struct obstack)); 1412a6b7db3Sskrll 1422a6b7db3Sskrllobstack_init (myobstack_ptr); 1432a6b7db3Sskrll@end smallexample 1442a6b7db3Sskrll 1452a6b7db3Sskrll@comment obstack.h 1462a6b7db3Sskrll@comment GNU 147*5ba6b03cSchristos@deftypefun int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) 148*5ba6b03cSchristosLike @code{obstack_init}, but specify chunks to be at least 149*5ba6b03cSchristos@var{chunk_size} bytes in size. 150*5ba6b03cSchristos@end deftypefun 151*5ba6b03cSchristos 152*5ba6b03cSchristos@comment obstack.h 153*5ba6b03cSchristos@comment GNU 154*5ba6b03cSchristos@deftypefun int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *)) 155*5ba6b03cSchristosLike @code{obstack_init}, specifying chunk size, chunk 156*5ba6b03cSchristosalignment, and memory allocation functions. A @var{chunk_size} or 157*5ba6b03cSchristos@var{alignment} of zero results in the default size or alignment 158*5ba6b03cSchristosrespectively being used. 159*5ba6b03cSchristos@end deftypefun 160*5ba6b03cSchristos 161*5ba6b03cSchristos@comment obstack.h 162*5ba6b03cSchristos@comment GNU 163*5ba6b03cSchristos@deftypefun int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg) 164*5ba6b03cSchristosLike @code{obstack_specify_allocation}, but specifying memory 165*5ba6b03cSchristosallocation functions that take an extra first argument, @var{arg}. 166*5ba6b03cSchristos@end deftypefun 167*5ba6b03cSchristos 168*5ba6b03cSchristos@comment obstack.h 169*5ba6b03cSchristos@comment GNU 1702a6b7db3Sskrll@defvar obstack_alloc_failed_handler 1712a6b7db3SskrllThe value of this variable is a pointer to a function that 1722a6b7db3Sskrll@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate 1732a6b7db3Sskrllmemory. The default action is to print a message and abort. 1742a6b7db3SskrllYou should supply a function that either calls @code{exit} 1752a6b7db3Sskrll(@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) or @code{longjmp} (@pxref{Non-Local 1762a6b7db3SskrllExits, , , libc, The GNU C Library Reference Manual}) and doesn't return. 1772a6b7db3Sskrll 1782a6b7db3Sskrll@smallexample 1792a6b7db3Sskrllvoid my_obstack_alloc_failed (void) 1802a6b7db3Sskrll@dots{} 1812a6b7db3Sskrllobstack_alloc_failed_handler = &my_obstack_alloc_failed; 1822a6b7db3Sskrll@end smallexample 1832a6b7db3Sskrll 1842a6b7db3Sskrll@end defvar 1852a6b7db3Sskrll 1862a6b7db3Sskrll@node Allocation in an Obstack 187*5ba6b03cSchristos@subsubsection Allocation in an Obstack 1882a6b7db3Sskrll@cindex allocation (obstacks) 1892a6b7db3Sskrll 1902a6b7db3SskrllThe most direct way to allocate an object in an obstack is with 1912a6b7db3Sskrll@code{obstack_alloc}, which is invoked almost like @code{malloc}. 1922a6b7db3Sskrll 1932a6b7db3Sskrll@comment obstack.h 1942a6b7db3Sskrll@comment GNU 195*5ba6b03cSchristos@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) 1962a6b7db3SskrllThis allocates an uninitialized block of @var{size} bytes in an obstack 1972a6b7db3Sskrlland returns its address. Here @var{obstack-ptr} specifies which obstack 1982a6b7db3Sskrllto allocate the block in; it is the address of the @code{struct obstack} 199*5ba6b03cSchristosobject which represents the obstack. Each obstack macro 2002a6b7db3Sskrllrequires you to specify an @var{obstack-ptr} as the first argument. 2012a6b7db3Sskrll 202*5ba6b03cSchristosThis macro calls the obstack's @code{obstack_chunk_alloc} function if 2032a6b7db3Sskrllit needs to allocate a new chunk of memory; it calls 2042a6b7db3Sskrll@code{obstack_alloc_failed_handler} if allocation of memory by 2052a6b7db3Sskrll@code{obstack_chunk_alloc} failed. 2062a6b7db3Sskrll@end deftypefun 2072a6b7db3Sskrll 2082a6b7db3SskrllFor example, here is a function that allocates a copy of a string @var{str} 2092a6b7db3Sskrllin a specific obstack, which is in the variable @code{string_obstack}: 2102a6b7db3Sskrll 2112a6b7db3Sskrll@smallexample 2122a6b7db3Sskrllstruct obstack string_obstack; 2132a6b7db3Sskrll 2142a6b7db3Sskrllchar * 2152a6b7db3Sskrllcopystring (char *string) 2162a6b7db3Sskrll@{ 2172a6b7db3Sskrll size_t len = strlen (string) + 1; 2182a6b7db3Sskrll char *s = (char *) obstack_alloc (&string_obstack, len); 2192a6b7db3Sskrll memcpy (s, string, len); 2202a6b7db3Sskrll return s; 2212a6b7db3Sskrll@} 2222a6b7db3Sskrll@end smallexample 2232a6b7db3Sskrll 224*5ba6b03cSchristosTo allocate a block with specified contents, use the macro @code{obstack_copy}. 2252a6b7db3Sskrll 2262a6b7db3Sskrll@comment obstack.h 2272a6b7db3Sskrll@comment GNU 228*5ba6b03cSchristos@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) 2292a6b7db3SskrllThis allocates a block and initializes it by copying @var{size} 2302a6b7db3Sskrllbytes of data starting at @var{address}. It calls 2312a6b7db3Sskrll@code{obstack_alloc_failed_handler} if allocation of memory by 2322a6b7db3Sskrll@code{obstack_chunk_alloc} failed. 2332a6b7db3Sskrll@end deftypefun 2342a6b7db3Sskrll 2352a6b7db3Sskrll@comment obstack.h 2362a6b7db3Sskrll@comment GNU 237*5ba6b03cSchristos@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) 2382a6b7db3SskrllLike @code{obstack_copy}, but appends an extra byte containing a null 2392a6b7db3Sskrllcharacter. This extra byte is not counted in the argument @var{size}. 2402a6b7db3Sskrll@end deftypefun 2412a6b7db3Sskrll 242*5ba6b03cSchristosThe @code{obstack_copy0} macro is convenient for copying a sequence 2432a6b7db3Sskrllof characters into an obstack as a null-terminated string. Here is an 2442a6b7db3Sskrllexample of its use: 2452a6b7db3Sskrll 2462a6b7db3Sskrll@smallexample 2472a6b7db3Sskrllchar * 248*5ba6b03cSchristosobstack_savestring (char *addr, size_t size) 2492a6b7db3Sskrll@{ 2502a6b7db3Sskrll return obstack_copy0 (&myobstack, addr, size); 2512a6b7db3Sskrll@} 2522a6b7db3Sskrll@end smallexample 2532a6b7db3Sskrll 2542a6b7db3Sskrll@noindent 2552a6b7db3SskrllContrast this with the previous example of @code{savestring} using 2562a6b7db3Sskrll@code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}). 2572a6b7db3Sskrll 2582a6b7db3Sskrll@node Freeing Obstack Objects 259*5ba6b03cSchristos@subsubsection Freeing Objects in an Obstack 2602a6b7db3Sskrll@cindex freeing (obstacks) 2612a6b7db3Sskrll 262*5ba6b03cSchristosTo free an object allocated in an obstack, use the macro 2632a6b7db3Sskrll@code{obstack_free}. Since the obstack is a stack of objects, freeing 2642a6b7db3Sskrllone object automatically frees all other objects allocated more recently 2652a6b7db3Sskrllin the same obstack. 2662a6b7db3Sskrll 2672a6b7db3Sskrll@comment obstack.h 2682a6b7db3Sskrll@comment GNU 2692a6b7db3Sskrll@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) 2702a6b7db3SskrllIf @var{object} is a null pointer, everything allocated in the obstack 2712a6b7db3Sskrllis freed. Otherwise, @var{object} must be the address of an object 2722a6b7db3Sskrllallocated in the obstack. Then @var{object} is freed, along with 2732a6b7db3Sskrlleverything allocated in @var{obstack} since @var{object}. 2742a6b7db3Sskrll@end deftypefun 2752a6b7db3Sskrll 2762a6b7db3SskrllNote that if @var{object} is a null pointer, the result is an 2772a6b7db3Sskrlluninitialized obstack. To free all memory in an obstack but leave it 2782a6b7db3Sskrllvalid for further allocation, call @code{obstack_free} with the address 2792a6b7db3Sskrllof the first object allocated on the obstack: 2802a6b7db3Sskrll 2812a6b7db3Sskrll@smallexample 2822a6b7db3Sskrllobstack_free (obstack_ptr, first_object_allocated_ptr); 2832a6b7db3Sskrll@end smallexample 2842a6b7db3Sskrll 2852a6b7db3SskrllRecall that the objects in an obstack are grouped into chunks. When all 2862a6b7db3Sskrllthe objects in a chunk become free, the obstack library automatically 2872a6b7db3Sskrllfrees the chunk (@pxref{Preparing for Obstacks}). Then other 2882a6b7db3Sskrllobstacks, or non-obstack allocation, can reuse the space of the chunk. 2892a6b7db3Sskrll 2902a6b7db3Sskrll@node Obstack Functions 291*5ba6b03cSchristos@subsubsection Obstack Functions and Macros 2922a6b7db3Sskrll@cindex macros 2932a6b7db3Sskrll 294*5ba6b03cSchristosThe interfaces for using obstacks are shown here as functions to 295*5ba6b03cSchristosspecify the return type and argument types, but they are really 296*5ba6b03cSchristosdefined as macros. This means that the arguments don't actually have 297*5ba6b03cSchristostypes, but they generally behave as if they have the types shown. 298*5ba6b03cSchristosYou can call these macros like functions, but you cannot use them in 299*5ba6b03cSchristosany other way (for example, you cannot take their address). 3002a6b7db3Sskrll 3012a6b7db3SskrllCalling the macros requires a special precaution: namely, the first 3022a6b7db3Sskrlloperand (the obstack pointer) may not contain any side effects, because 3032a6b7db3Sskrllit may be computed more than once. For example, if you write this: 3042a6b7db3Sskrll 3052a6b7db3Sskrll@smallexample 3062a6b7db3Sskrllobstack_alloc (get_obstack (), 4); 3072a6b7db3Sskrll@end smallexample 3082a6b7db3Sskrll 3092a6b7db3Sskrll@noindent 3102a6b7db3Sskrllyou will find that @code{get_obstack} may be called several times. 3112a6b7db3SskrllIf you use @code{*obstack_list_ptr++} as the obstack pointer argument, 3122a6b7db3Sskrllyou will get very strange results since the incrementation may occur 3132a6b7db3Sskrllseveral times. 3142a6b7db3Sskrll 3152a6b7db3SskrllIf you use the GNU C compiler, this precaution is not necessary, because 3162a6b7db3Sskrllvarious language extensions in GNU C permit defining the macros so as to 3172a6b7db3Sskrllcompute each argument only once. 3182a6b7db3Sskrll 319*5ba6b03cSchristosNote that arguments other than the first will only be evaluated once, 320*5ba6b03cSchristoseven when not using GNU C. 321*5ba6b03cSchristos 322*5ba6b03cSchristos@code{obstack.h} does declare a number of functions, 323*5ba6b03cSchristos@code{_obstack_begin}, @code{_obstack_begin_1}, 324*5ba6b03cSchristos@code{_obstack_newchunk}, @code{_obstack_free}, and 325*5ba6b03cSchristos@code{_obstack_memory_used}. You should not call these directly. 326*5ba6b03cSchristos 3272a6b7db3Sskrll@node Growing Objects 328*5ba6b03cSchristos@subsubsection Growing Objects 3292a6b7db3Sskrll@cindex growing objects (in obstacks) 3302a6b7db3Sskrll@cindex changing the size of a block (obstacks) 3312a6b7db3Sskrll 3322a6b7db3SskrllBecause memory in obstack chunks is used sequentially, it is possible to 3332a6b7db3Sskrllbuild up an object step by step, adding one or more bytes at a time to the 3342a6b7db3Sskrllend of the object. With this technique, you do not need to know how much 3352a6b7db3Sskrlldata you will put in the object until you come to the end of it. We call 336*5ba6b03cSchristosthis the technique of @dfn{growing objects}. The special macros 3372a6b7db3Sskrllfor adding data to the growing object are described in this section. 3382a6b7db3Sskrll 3392a6b7db3SskrllYou don't need to do anything special when you start to grow an object. 340*5ba6b03cSchristosUsing one of the macros to add data to the object automatically 3412a6b7db3Sskrllstarts it. However, it is necessary to say explicitly when the object is 342*5ba6b03cSchristosfinished. This is done with @code{obstack_finish}. 3432a6b7db3Sskrll 3442a6b7db3SskrllThe actual address of the object thus built up is not known until the 3452a6b7db3Sskrllobject is finished. Until then, it always remains possible that you will 3462a6b7db3Sskrlladd so much data that the object must be copied into a new chunk. 3472a6b7db3Sskrll 3482a6b7db3SskrllWhile the obstack is in use for a growing object, you cannot use it for 3492a6b7db3Sskrllordinary allocation of another object. If you try to do so, the space 3502a6b7db3Sskrllalready added to the growing object will become part of the other object. 3512a6b7db3Sskrll 3522a6b7db3Sskrll@comment obstack.h 3532a6b7db3Sskrll@comment GNU 354*5ba6b03cSchristos@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) 355*5ba6b03cSchristosThe most basic macro for adding to a growing object is 3562a6b7db3Sskrll@code{obstack_blank}, which adds space without initializing it. 3572a6b7db3Sskrll@end deftypefun 3582a6b7db3Sskrll 3592a6b7db3Sskrll@comment obstack.h 3602a6b7db3Sskrll@comment GNU 361*5ba6b03cSchristos@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size}) 3622a6b7db3SskrllTo add a block of initialized space, use @code{obstack_grow}, which is 3632a6b7db3Sskrllthe growing-object analogue of @code{obstack_copy}. It adds @var{size} 3642a6b7db3Sskrllbytes of data to the growing object, copying the contents from 3652a6b7db3Sskrll@var{data}. 3662a6b7db3Sskrll@end deftypefun 3672a6b7db3Sskrll 3682a6b7db3Sskrll@comment obstack.h 3692a6b7db3Sskrll@comment GNU 370*5ba6b03cSchristos@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size}) 3712a6b7db3SskrllThis is the growing-object analogue of @code{obstack_copy0}. It adds 3722a6b7db3Sskrll@var{size} bytes copied from @var{data}, followed by an additional null 3732a6b7db3Sskrllcharacter. 3742a6b7db3Sskrll@end deftypefun 3752a6b7db3Sskrll 3762a6b7db3Sskrll@comment obstack.h 3772a6b7db3Sskrll@comment GNU 3782a6b7db3Sskrll@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) 379*5ba6b03cSchristosTo add one character at a time, use @code{obstack_1grow}. 3802a6b7db3SskrllIt adds a single byte containing @var{c} to the growing object. 3812a6b7db3Sskrll@end deftypefun 3822a6b7db3Sskrll 3832a6b7db3Sskrll@comment obstack.h 3842a6b7db3Sskrll@comment GNU 3852a6b7db3Sskrll@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data}) 386*5ba6b03cSchristosAdding the value of a pointer one can use 3872a6b7db3Sskrll@code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes 3882a6b7db3Sskrllcontaining the value of @var{data}. 3892a6b7db3Sskrll@end deftypefun 3902a6b7db3Sskrll 3912a6b7db3Sskrll@comment obstack.h 3922a6b7db3Sskrll@comment GNU 3932a6b7db3Sskrll@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data}) 394*5ba6b03cSchristosA single value of type @code{int} can be added by using 395*5ba6b03cSchristos@code{obstack_int_grow}. It adds @code{sizeof (int)} bytes to 3962a6b7db3Sskrllthe growing object and initializes them with the value of @var{data}. 3972a6b7db3Sskrll@end deftypefun 3982a6b7db3Sskrll 3992a6b7db3Sskrll@comment obstack.h 4002a6b7db3Sskrll@comment GNU 4012a6b7db3Sskrll@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr}) 402*5ba6b03cSchristosWhen you are finished growing the object, use 4032a6b7db3Sskrll@code{obstack_finish} to close it off and return its final address. 4042a6b7db3Sskrll 4052a6b7db3SskrllOnce you have finished the object, the obstack is available for ordinary 4062a6b7db3Sskrllallocation or for growing another object. 4072a6b7db3Sskrll@end deftypefun 4082a6b7db3Sskrll 4092a6b7db3SskrllWhen you build an object by growing it, you will probably need to know 4102a6b7db3Sskrllafterward how long it became. You need not keep track of this as you grow 411*5ba6b03cSchristosthe object, because you can find out the length from the obstack 412*5ba6b03cSchristoswith @code{obstack_object_size}, before finishing the object. 4132a6b7db3Sskrll 4142a6b7db3Sskrll@comment obstack.h 4152a6b7db3Sskrll@comment GNU 416*5ba6b03cSchristos@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr}) 417*5ba6b03cSchristosThis macro returns the current size of the growing object, in bytes. 418*5ba6b03cSchristosRemember to call @code{obstack_object_size} @emph{before} finishing the object. 4192a6b7db3SskrllAfter it is finished, @code{obstack_object_size} will return zero. 4202a6b7db3Sskrll@end deftypefun 4212a6b7db3Sskrll 4222a6b7db3SskrllIf you have started growing an object and wish to cancel it, you should 4232a6b7db3Sskrllfinish it and then free it, like this: 4242a6b7db3Sskrll 4252a6b7db3Sskrll@smallexample 4262a6b7db3Sskrllobstack_free (obstack_ptr, obstack_finish (obstack_ptr)); 4272a6b7db3Sskrll@end smallexample 4282a6b7db3Sskrll 4292a6b7db3Sskrll@noindent 4302a6b7db3SskrllThis has no effect if no object was growing. 4312a6b7db3Sskrll 4322a6b7db3Sskrll@node Extra Fast Growing 433*5ba6b03cSchristos@subsubsection Extra Fast Growing Objects 4342a6b7db3Sskrll@cindex efficiency and obstacks 4352a6b7db3Sskrll 436*5ba6b03cSchristosThe usual macros for growing objects incur overhead for checking 4372a6b7db3Sskrllwhether there is room for the new growth in the current chunk. If you 4382a6b7db3Sskrllare frequently constructing objects in small steps of growth, this 4392a6b7db3Sskrlloverhead can be significant. 4402a6b7db3Sskrll 4412a6b7db3SskrllYou can reduce the overhead by using special ``fast growth'' 442*5ba6b03cSchristosmacros that grow the object without checking. In order to have a 4432a6b7db3Sskrllrobust program, you must do the checking yourself. If you do this checking 4442a6b7db3Sskrllin the simplest way each time you are about to add data to the object, you 4452a6b7db3Sskrllhave not saved anything, because that is what the ordinary growth 446*5ba6b03cSchristosmacros do. But if you can arrange to check less often, or check 4472a6b7db3Sskrllmore efficiently, then you make the program faster. 4482a6b7db3Sskrll 449*5ba6b03cSchristos@code{obstack_room} returns the amount of room available 450*5ba6b03cSchristosin the current chunk. 4512a6b7db3Sskrll 4522a6b7db3Sskrll@comment obstack.h 4532a6b7db3Sskrll@comment GNU 454*5ba6b03cSchristos@deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr}) 4552a6b7db3SskrllThis returns the number of bytes that can be added safely to the current 4562a6b7db3Sskrllgrowing object (or to an object about to be started) in obstack 457*5ba6b03cSchristos@var{obstack} using the fast growth macros. 4582a6b7db3Sskrll@end deftypefun 4592a6b7db3Sskrll 460*5ba6b03cSchristosWhile you know there is room, you can use these fast growth macros 4612a6b7db3Sskrllfor adding data to a growing object: 4622a6b7db3Sskrll 4632a6b7db3Sskrll@comment obstack.h 4642a6b7db3Sskrll@comment GNU 4652a6b7db3Sskrll@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c}) 466*5ba6b03cSchristos@code{obstack_1grow_fast} adds one byte containing the 4672a6b7db3Sskrllcharacter @var{c} to the growing object in obstack @var{obstack-ptr}. 4682a6b7db3Sskrll@end deftypefun 4692a6b7db3Sskrll 4702a6b7db3Sskrll@comment obstack.h 4712a6b7db3Sskrll@comment GNU 4722a6b7db3Sskrll@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data}) 473*5ba6b03cSchristos@code{obstack_ptr_grow_fast} adds @code{sizeof (void *)} 4742a6b7db3Sskrllbytes containing the value of @var{data} to the growing object in 4752a6b7db3Sskrllobstack @var{obstack-ptr}. 4762a6b7db3Sskrll@end deftypefun 4772a6b7db3Sskrll 4782a6b7db3Sskrll@comment obstack.h 4792a6b7db3Sskrll@comment GNU 4802a6b7db3Sskrll@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data}) 481*5ba6b03cSchristos@code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes 4822a6b7db3Sskrllcontaining the value of @var{data} to the growing object in obstack 4832a6b7db3Sskrll@var{obstack-ptr}. 4842a6b7db3Sskrll@end deftypefun 4852a6b7db3Sskrll 4862a6b7db3Sskrll@comment obstack.h 4872a6b7db3Sskrll@comment GNU 488*5ba6b03cSchristos@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) 489*5ba6b03cSchristos@code{obstack_blank_fast} adds @var{size} bytes to the 4902a6b7db3Sskrllgrowing object in obstack @var{obstack-ptr} without initializing them. 4912a6b7db3Sskrll@end deftypefun 4922a6b7db3Sskrll 4932a6b7db3SskrllWhen you check for space using @code{obstack_room} and there is not 494*5ba6b03cSchristosenough room for what you want to add, the fast growth macros 4952a6b7db3Sskrllare not safe. In this case, simply use the corresponding ordinary 496*5ba6b03cSchristosgrowth macro instead. Very soon this will copy the object to a 4972a6b7db3Sskrllnew chunk; then there will be lots of room available again. 4982a6b7db3Sskrll 499*5ba6b03cSchristosSo, each time you use an ordinary growth macro, check afterward for 5002a6b7db3Sskrllsufficient space using @code{obstack_room}. Once the object is copied 5012a6b7db3Sskrllto a new chunk, there will be plenty of space again, so the program will 502*5ba6b03cSchristosstart using the fast growth macros again. 5032a6b7db3Sskrll 5042a6b7db3SskrllHere is an example: 5052a6b7db3Sskrll 5062a6b7db3Sskrll@smallexample 5072a6b7db3Sskrll@group 5082a6b7db3Sskrllvoid 509*5ba6b03cSchristosadd_string (struct obstack *obstack, const char *ptr, size_t len) 5102a6b7db3Sskrll@{ 5112a6b7db3Sskrll while (len > 0) 5122a6b7db3Sskrll @{ 513*5ba6b03cSchristos size_t room = obstack_room (obstack); 5142a6b7db3Sskrll if (room == 0) 5152a6b7db3Sskrll @{ 5162a6b7db3Sskrll /* @r{Not enough room. Add one character slowly,} 5172a6b7db3Sskrll @r{which may copy to a new chunk and make room.} */ 5182a6b7db3Sskrll obstack_1grow (obstack, *ptr++); 5192a6b7db3Sskrll len--; 5202a6b7db3Sskrll @} 5212a6b7db3Sskrll else 5222a6b7db3Sskrll @{ 5232a6b7db3Sskrll if (room > len) 5242a6b7db3Sskrll room = len; 5252a6b7db3Sskrll /* @r{Add fast as much as we have room for.} */ 5262a6b7db3Sskrll len -= room; 5272a6b7db3Sskrll while (room-- > 0) 5282a6b7db3Sskrll obstack_1grow_fast (obstack, *ptr++); 5292a6b7db3Sskrll @} 5302a6b7db3Sskrll @} 5312a6b7db3Sskrll@} 5322a6b7db3Sskrll@end group 5332a6b7db3Sskrll@end smallexample 5342a6b7db3Sskrll 535*5ba6b03cSchristos@cindex shrinking objects 536*5ba6b03cSchristosYou can use @code{obstack_blank_fast} with a ``negative'' size 537*5ba6b03cSchristosargument to make the current object smaller. Just don't try to shrink 538*5ba6b03cSchristosit beyond zero length---there's no telling what will happen if you do 539*5ba6b03cSchristosthat. Earlier versions of obstacks allowed you to use 540*5ba6b03cSchristos@code{obstack_blank} to shrink objects. This will no longer work. 541*5ba6b03cSchristos 5422a6b7db3Sskrll@node Status of an Obstack 543*5ba6b03cSchristos@subsubsection Status of an Obstack 5442a6b7db3Sskrll@cindex obstack status 5452a6b7db3Sskrll@cindex status of obstack 5462a6b7db3Sskrll 547*5ba6b03cSchristosHere are macros that provide information on the current status of 5482a6b7db3Sskrllallocation in an obstack. You can use them to learn about an object while 5492a6b7db3Sskrllstill growing it. 5502a6b7db3Sskrll 5512a6b7db3Sskrll@comment obstack.h 5522a6b7db3Sskrll@comment GNU 5532a6b7db3Sskrll@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) 554*5ba6b03cSchristosThis macro returns the tentative address of the beginning of the 5552a6b7db3Sskrllcurrently growing object in @var{obstack-ptr}. If you finish the object 5562a6b7db3Sskrllimmediately, it will have that address. If you make it larger first, it 5572a6b7db3Sskrllmay outgrow the current chunk---then its address will change! 5582a6b7db3Sskrll 5592a6b7db3SskrllIf no object is growing, this value says where the next object you 5602a6b7db3Sskrllallocate will start (once again assuming it fits in the current 5612a6b7db3Sskrllchunk). 5622a6b7db3Sskrll@end deftypefun 5632a6b7db3Sskrll 5642a6b7db3Sskrll@comment obstack.h 5652a6b7db3Sskrll@comment GNU 5662a6b7db3Sskrll@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) 567*5ba6b03cSchristosThis macro returns the address of the first free byte in the current 5682a6b7db3Sskrllchunk of obstack @var{obstack-ptr}. This is the end of the currently 5692a6b7db3Sskrllgrowing object. If no object is growing, @code{obstack_next_free} 5702a6b7db3Sskrllreturns the same value as @code{obstack_base}. 5712a6b7db3Sskrll@end deftypefun 5722a6b7db3Sskrll 5732a6b7db3Sskrll@comment obstack.h 5742a6b7db3Sskrll@comment GNU 575*5ba6b03cSchristos@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr}) 576*5ba6b03cSchristosThis macro returns the size in bytes of the currently growing object. 5772a6b7db3SskrllThis is equivalent to 5782a6b7db3Sskrll 5792a6b7db3Sskrll@smallexample 580*5ba6b03cSchristos((size_t) (obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr}))) 5812a6b7db3Sskrll@end smallexample 5822a6b7db3Sskrll@end deftypefun 5832a6b7db3Sskrll 5842a6b7db3Sskrll@node Obstacks Data Alignment 585*5ba6b03cSchristos@subsubsection Alignment of Data in Obstacks 5862a6b7db3Sskrll@cindex alignment (in obstacks) 5872a6b7db3Sskrll 5882a6b7db3SskrllEach obstack has an @dfn{alignment boundary}; each object allocated in 5892a6b7db3Sskrllthe obstack automatically starts on an address that is a multiple of the 590*5ba6b03cSchristosspecified boundary. By default, this boundary is aligned so that 591*5ba6b03cSchristosthe object can hold any type of data. 5922a6b7db3Sskrll 5932a6b7db3SskrllTo access an obstack's alignment boundary, use the macro 594*5ba6b03cSchristos@code{obstack_alignment_mask}. 5952a6b7db3Sskrll 5962a6b7db3Sskrll@comment obstack.h 5972a6b7db3Sskrll@comment GNU 598*5ba6b03cSchristos@deftypefn Macro size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr}) 5992a6b7db3SskrllThe value is a bit mask; a bit that is 1 indicates that the corresponding 6002a6b7db3Sskrllbit in the address of an object should be 0. The mask value should be one 6012a6b7db3Sskrllless than a power of 2; the effect is that all object addresses are 602*5ba6b03cSchristosmultiples of that power of 2. The default value of the mask is a value 603*5ba6b03cSchristosthat allows aligned objects to hold any type of data: for example, if 604*5ba6b03cSchristosits value is 3, any type of data can be stored at locations whose 6052a6b7db3Sskrlladdresses are multiples of 4. A mask value of 0 means an object can start 6062a6b7db3Sskrllon any multiple of 1 (that is, no alignment is required). 6072a6b7db3Sskrll 6082a6b7db3SskrllThe expansion of the macro @code{obstack_alignment_mask} is an lvalue, 6092a6b7db3Sskrllso you can alter the mask by assignment. For example, this statement: 6102a6b7db3Sskrll 6112a6b7db3Sskrll@smallexample 6122a6b7db3Sskrllobstack_alignment_mask (obstack_ptr) = 0; 6132a6b7db3Sskrll@end smallexample 6142a6b7db3Sskrll 6152a6b7db3Sskrll@noindent 6162a6b7db3Sskrllhas the effect of turning off alignment processing in the specified obstack. 6172a6b7db3Sskrll@end deftypefn 6182a6b7db3Sskrll 6192a6b7db3SskrllNote that a change in alignment mask does not take effect until 6202a6b7db3Sskrll@emph{after} the next time an object is allocated or finished in the 6212a6b7db3Sskrllobstack. If you are not growing an object, you can make the new 6222a6b7db3Sskrllalignment mask take effect immediately by calling @code{obstack_finish}. 6232a6b7db3SskrllThis will finish a zero-length object and then do proper alignment for 6242a6b7db3Sskrllthe next object. 6252a6b7db3Sskrll 6262a6b7db3Sskrll@node Obstack Chunks 627*5ba6b03cSchristos@subsubsection Obstack Chunks 6282a6b7db3Sskrll@cindex efficiency of chunks 6292a6b7db3Sskrll@cindex chunks 6302a6b7db3Sskrll 6312a6b7db3SskrllObstacks work by allocating space for themselves in large chunks, and 6322a6b7db3Sskrllthen parceling out space in the chunks to satisfy your requests. Chunks 6332a6b7db3Sskrllare normally 4096 bytes long unless you specify a different chunk size. 6342a6b7db3SskrllThe chunk size includes 8 bytes of overhead that are not actually used 6352a6b7db3Sskrllfor storing objects. Regardless of the specified size, longer chunks 6362a6b7db3Sskrllwill be allocated when necessary for long objects. 6372a6b7db3Sskrll 6382a6b7db3SskrllThe obstack library allocates chunks by calling the function 6392a6b7db3Sskrll@code{obstack_chunk_alloc}, which you must define. When a chunk is no 6402a6b7db3Sskrlllonger needed because you have freed all the objects in it, the obstack 6412a6b7db3Sskrlllibrary frees the chunk by calling @code{obstack_chunk_free}, which you 6422a6b7db3Sskrllmust also define. 6432a6b7db3Sskrll 6442a6b7db3SskrllThese two must be defined (as macros) or declared (as functions) in each 6452a6b7db3Sskrllsource file that uses @code{obstack_init} (@pxref{Creating Obstacks}). 6462a6b7db3SskrllMost often they are defined as macros like this: 6472a6b7db3Sskrll 6482a6b7db3Sskrll@smallexample 6492a6b7db3Sskrll#define obstack_chunk_alloc malloc 6502a6b7db3Sskrll#define obstack_chunk_free free 6512a6b7db3Sskrll@end smallexample 6522a6b7db3Sskrll 6532a6b7db3SskrllNote that these are simple macros (no arguments). Macro definitions with 6542a6b7db3Sskrllarguments will not work! It is necessary that @code{obstack_chunk_alloc} 6552a6b7db3Sskrllor @code{obstack_chunk_free}, alone, expand into a function name if it is 6562a6b7db3Sskrllnot itself a function name. 6572a6b7db3Sskrll 6582a6b7db3SskrllIf you allocate chunks with @code{malloc}, the chunk size should be a 6592a6b7db3Sskrllpower of 2. The default chunk size, 4096, was chosen because it is long 6602a6b7db3Sskrllenough to satisfy many typical requests on the obstack yet short enough 6612a6b7db3Sskrllnot to waste too much memory in the portion of the last chunk not yet used. 6622a6b7db3Sskrll 6632a6b7db3Sskrll@comment obstack.h 6642a6b7db3Sskrll@comment GNU 665*5ba6b03cSchristos@deftypefn Macro size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) 6662a6b7db3SskrllThis returns the chunk size of the given obstack. 6672a6b7db3Sskrll@end deftypefn 6682a6b7db3Sskrll 6692a6b7db3SskrllSince this macro expands to an lvalue, you can specify a new chunk size by 6702a6b7db3Sskrllassigning it a new value. Doing so does not affect the chunks already 6712a6b7db3Sskrllallocated, but will change the size of chunks allocated for that particular 6722a6b7db3Sskrllobstack in the future. It is unlikely to be useful to make the chunk size 6732a6b7db3Sskrllsmaller, but making it larger might improve efficiency if you are 6742a6b7db3Sskrllallocating many objects whose size is comparable to the chunk size. Here 6752a6b7db3Sskrllis how to do so cleanly: 6762a6b7db3Sskrll 6772a6b7db3Sskrll@smallexample 6782a6b7db3Sskrllif (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size}) 6792a6b7db3Sskrll obstack_chunk_size (obstack_ptr) = @var{new-chunk-size}; 6802a6b7db3Sskrll@end smallexample 6812a6b7db3Sskrll 6822a6b7db3Sskrll@node Summary of Obstacks 683*5ba6b03cSchristos@subsubsection Summary of Obstack Macros 6842a6b7db3Sskrll 685*5ba6b03cSchristosHere is a summary of all the macros associated with obstacks. Each 6862a6b7db3Sskrlltakes the address of an obstack (@code{struct obstack *}) as its first 6872a6b7db3Sskrllargument. 6882a6b7db3Sskrll 6892a6b7db3Sskrll@table @code 690*5ba6b03cSchristos@item int obstack_init (struct obstack *@var{obstack-ptr}) 6912a6b7db3SskrllInitialize use of an obstack. @xref{Creating Obstacks}. 6922a6b7db3Sskrll 693*5ba6b03cSchristos@item int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) 694*5ba6b03cSchristosInitialize use of an obstack, with an initial chunk of 695*5ba6b03cSchristos@var{chunk_size} bytes. 696*5ba6b03cSchristos 697*5ba6b03cSchristos@item int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *)) 698*5ba6b03cSchristosInitialize use of an obstack, specifying intial chunk size, chunk 699*5ba6b03cSchristosalignment, and memory allocation functions. 700*5ba6b03cSchristos 701*5ba6b03cSchristos@item int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg) 702*5ba6b03cSchristosLike @code{obstack_specify_allocation}, but specifying memory 703*5ba6b03cSchristosallocation functions that take an extra first argument, @var{arg}. 704*5ba6b03cSchristos 705*5ba6b03cSchristos@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) 7062a6b7db3SskrllAllocate an object of @var{size} uninitialized bytes. 7072a6b7db3Sskrll@xref{Allocation in an Obstack}. 7082a6b7db3Sskrll 709*5ba6b03cSchristos@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) 7102a6b7db3SskrllAllocate an object of @var{size} bytes, with contents copied from 7112a6b7db3Sskrll@var{address}. @xref{Allocation in an Obstack}. 7122a6b7db3Sskrll 713*5ba6b03cSchristos@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) 7142a6b7db3SskrllAllocate an object of @var{size}+1 bytes, with @var{size} of them copied 7152a6b7db3Sskrllfrom @var{address}, followed by a null character at the end. 7162a6b7db3Sskrll@xref{Allocation in an Obstack}. 7172a6b7db3Sskrll 7182a6b7db3Sskrll@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) 7192a6b7db3SskrllFree @var{object} (and everything allocated in the specified obstack 7202a6b7db3Sskrllmore recently than @var{object}). @xref{Freeing Obstack Objects}. 7212a6b7db3Sskrll 722*5ba6b03cSchristos@item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) 7232a6b7db3SskrllAdd @var{size} uninitialized bytes to a growing object. 7242a6b7db3Sskrll@xref{Growing Objects}. 7252a6b7db3Sskrll 726*5ba6b03cSchristos@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) 7272a6b7db3SskrllAdd @var{size} bytes, copied from @var{address}, to a growing object. 7282a6b7db3Sskrll@xref{Growing Objects}. 7292a6b7db3Sskrll 730*5ba6b03cSchristos@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) 7312a6b7db3SskrllAdd @var{size} bytes, copied from @var{address}, to a growing object, 7322a6b7db3Sskrlland then add another byte containing a null character. @xref{Growing 7332a6b7db3SskrllObjects}. 7342a6b7db3Sskrll 7352a6b7db3Sskrll@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char}) 7362a6b7db3SskrllAdd one byte containing @var{data-char} to a growing object. 7372a6b7db3Sskrll@xref{Growing Objects}. 7382a6b7db3Sskrll 7392a6b7db3Sskrll@item void *obstack_finish (struct obstack *@var{obstack-ptr}) 7402a6b7db3SskrllFinalize the object that is growing and return its permanent address. 7412a6b7db3Sskrll@xref{Growing Objects}. 7422a6b7db3Sskrll 743*5ba6b03cSchristos@item size_t obstack_object_size (struct obstack *@var{obstack-ptr}) 7442a6b7db3SskrllGet the current size of the currently growing object. @xref{Growing 7452a6b7db3SskrllObjects}. 7462a6b7db3Sskrll 747*5ba6b03cSchristos@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) 7482a6b7db3SskrllAdd @var{size} uninitialized bytes to a growing object without checking 7492a6b7db3Sskrllthat there is enough room. @xref{Extra Fast Growing}. 7502a6b7db3Sskrll 7512a6b7db3Sskrll@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char}) 7522a6b7db3SskrllAdd one byte containing @var{data-char} to a growing object without 7532a6b7db3Sskrllchecking that there is enough room. @xref{Extra Fast Growing}. 7542a6b7db3Sskrll 755*5ba6b03cSchristos@item size_t obstack_room (struct obstack *@var{obstack-ptr}) 7562a6b7db3SskrllGet the amount of room now available for growing the current object. 7572a6b7db3Sskrll@xref{Extra Fast Growing}. 7582a6b7db3Sskrll 759*5ba6b03cSchristos@item size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr}) 7602a6b7db3SskrllThe mask used for aligning the beginning of an object. This is an 7612a6b7db3Sskrlllvalue. @xref{Obstacks Data Alignment}. 7622a6b7db3Sskrll 763*5ba6b03cSchristos@item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) 7642a6b7db3SskrllThe size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}. 7652a6b7db3Sskrll 7662a6b7db3Sskrll@item void *obstack_base (struct obstack *@var{obstack-ptr}) 7672a6b7db3SskrllTentative starting address of the currently growing object. 7682a6b7db3Sskrll@xref{Status of an Obstack}. 7692a6b7db3Sskrll 7702a6b7db3Sskrll@item void *obstack_next_free (struct obstack *@var{obstack-ptr}) 7712a6b7db3SskrllAddress just after the end of the currently growing object. 7722a6b7db3Sskrll@xref{Status of an Obstack}. 7732a6b7db3Sskrll@end table 7742a6b7db3Sskrll 775