2 Copyright 1988-2022 Free Software Foundation, Inc.
3 This is part of the GCC manual.
4 For copying conditions, see the copyright.rst file.
6 .. index:: extensions, functions, extension
13 ``libiberty`` includes additional functionality above and beyond standard
14 functions, which has proven generically useful in GNU programs, such as
15 obstacks and regex. These functions are often copied from other
16 projects as they gain popularity, and are included here to provide a
17 central location from which to use, maintain, and distribute them.
23 .. This is generated from the glibc manual using contrib/make-obstacks-texi.pl
32 An :dfn:`obstack` is a pool of memory containing a stack of objects. You
33 can create any number of separate obstacks, and then allocate objects in
34 specified obstacks. Within each obstack, the last object allocated must
35 always be the first one freed, but distinct obstacks are independent of
38 Aside from this one constraint of order of freeing, obstacks are totally
39 general: an obstack can contain any number of objects of any size. They
40 are implemented with macros, so allocation is usually very fast as long as
41 the objects are usually small. And the only space overhead per object is
42 the padding needed to start each object on a suitable boundary.
48 .. _creating-obstacks:
53 The utilities for manipulating obstacks are declared in the header
54 file :samp:`obstack.h`.
56 .. index:: obstack.h, struct obstack
58 Data Type struct obstackAn obstack is represented by a data structure of type ``struct
59 obstack``. This structure has a small fixed size; it records the status
60 of the obstack and how to find the space in which objects are allocated.
61 It does not contain any of the objects themselves. You should not try
62 to access the contents of the structure directly; use only the macros
63 described in this chapter.
65 You can declare variables of type ``struct obstack`` and use them as
66 obstacks, or you can allocate obstacks dynamically like any other kind
67 of object. Dynamic allocation of obstacks allows your program to have a
68 variable number of different stacks. (You can even allocate an
69 obstack structure in another obstack, but this is rarely useful.)
71 All the macros that work with obstacks require you to specify which
72 obstack to use. You do this with a pointer of type ``struct obstack
73 *``. In the following, we often say 'an obstack' when strictly
74 speaking the object at hand is such a pointer.
76 The objects in the obstack are packed into large blocks called
77 :dfn:`chunks`. The ``struct obstack`` structure points to a chain of
78 the chunks currently in use.
80 The obstack library obtains a new chunk whenever you allocate an object
81 that won't fit in the previous chunk. Since the obstack library manages
82 chunks automatically, you don't need to pay much attention to them, but
83 you do need to supply a function which the obstack library should use to
84 get a chunk. Usually you supply a function which uses ``malloc``
85 directly or indirectly. You must also supply a function to free a chunk.
86 These matters are described in the following section.
88 .. _preparing-for-obstacks:
90 Preparing for Using Obstacks
91 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93 Each source file in which you plan to use obstacks
94 must include the header file :samp:`obstack.h`, like this:
100 .. index:: obstack_chunk_alloc, obstack_chunk_free
102 Also, if the source file uses the macro ``obstack_init``, it must
103 declare or define two macros that will be called by the
104 obstack library. One, ``obstack_chunk_alloc``, is used to allocate
105 the chunks of memory into which objects are packed. The other,
106 ``obstack_chunk_free``, is used to return chunks when the objects in
107 them are freed. These macros should appear before any use of obstacks
110 Usually these are defined to use ``malloc`` via the intermediary
111 ``xmalloc`` (see `Unconstrained Allocation <https://www.gnu.org/software/libc/manual/html_node/Unconstrained-Allocation.html>`_
112 in The GNU C Library Reference Manual). This is done with
113 the following pair of macro definitions:
117 #define obstack_chunk_alloc xmalloc
118 #define obstack_chunk_free free
120 Though the memory you get using obstacks really comes from ``malloc``,
121 using obstacks is faster because ``malloc`` is called less often, for
122 larger blocks of memory. See :ref:`obstack-chunks`, for full details.
124 At run time, before the program can use a ``struct obstack`` object
125 as an obstack, it must initialize the obstack by calling
126 ``obstack_init`` or one of its variants, ``obstack_begin``,
127 ``obstack_specify_allocation``, or
128 ``obstack_specify_allocation_with_arg``.
130 .. function:: int obstack_init (struct obstack *obstack_ptr)
132 Initialize obstack :samp:`{obstack_ptr}` for allocation of objects. This
133 macro calls the obstack's ``obstack_chunk_alloc`` function. If
134 allocation of memory fails, the function pointed to by
135 ``obstack_alloc_failed_handler`` is called. The ``obstack_init``
136 macro always returns 1 (Compatibility notice: Former versions of
137 obstack returned 0 if allocation failed).
139 Here are two examples of how to allocate the space for an obstack and
140 initialize it. First, an obstack that is a static variable:
144 static struct obstack myobstack;
146 obstack_init (&myobstack);
148 Second, an obstack that is itself dynamically allocated:
152 struct obstack *myobstack_ptr
153 = (struct obstack *) xmalloc (sizeof (struct obstack));
155 obstack_init (myobstack_ptr);
157 .. function:: int obstack_begin (struct obstack *obstack_ptr, size_t chunk_size)
159 Like ``obstack_init``, but specify chunks to be at least
160 :samp:`{chunk_size}` bytes in size.
162 .. function:: int obstack_specify_allocation (struct obstack *obstack_ptr, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *))
164 Like ``obstack_init``, specifying chunk size, chunk
165 alignment, and memory allocation functions. A :samp:`{chunk_size}` or
166 :samp:`{alignment}` of zero results in the default size or alignment
167 respectively being used.
169 .. function:: int obstack_specify_allocation_with_arg (struct obstack *obstack_ptr, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg)
171 Like ``obstack_specify_allocation``, but specifying memory
172 allocation functions that take an extra first argument, :samp:`{arg}`.
174 .. index:: obstack_alloc_failed_handler
176 Variable obstack_alloc_failed_handlerThe value of this variable is a pointer to a function that
177 ``obstack`` uses when ``obstack_chunk_alloc`` fails to allocate
178 memory. The default action is to print a message and abort.
179 You should supply a function that either calls ``exit``
180 (see `Program Termination <https://www.gnu.org/software/libc/manual/html_node/Program-Termination.html>`_ in The GNU C Library Reference Manual)
181 or ``longjmp`` and doesn't return.
185 void my_obstack_alloc_failed (void)
187 obstack_alloc_failed_handler = &my_obstack_alloc_failed;
189 .. index:: allocation (obstacks)
191 .. _allocation-in-an-obstack:
193 Allocation in an Obstack
194 ~~~~~~~~~~~~~~~~~~~~~~~~
196 The most direct way to allocate an object in an obstack is with
197 ``obstack_alloc``, which is invoked almost like ``malloc``.
199 .. function:: void * obstack_alloc (struct obstack *obstack_ptr, size_t size)
201 This allocates an uninitialized block of :samp:`{size}` bytes in an obstack
202 and returns its address. Here :samp:`{obstack_ptr}` specifies which obstack
203 to allocate the block in; it is the address of the ``struct obstack``
204 object which represents the obstack. Each obstack macro
205 requires you to specify an :samp:`{obstack_ptr}` as the first argument.
207 This macro calls the obstack's ``obstack_chunk_alloc`` function if
208 it needs to allocate a new chunk of memory; it calls
209 ``obstack_alloc_failed_handler`` if allocation of memory by
210 ``obstack_chunk_alloc`` failed.
212 For example, here is a function that allocates a copy of a string :samp:`{str}`
213 in a specific obstack, which is in the variable ``string_obstack`` :
217 struct obstack string_obstack;
220 copystring (char *string)
222 size_t len = strlen (string) + 1;
223 char *s = (char *) obstack_alloc (&string_obstack, len);
224 memcpy (s, string, len);
228 To allocate a block with specified contents, use the macro ``obstack_copy``.
230 .. function:: void * obstack_copy (struct obstack *obstack_ptr, void *address, size_t size)
232 This allocates a block and initializes it by copying :samp:`{size}`
233 bytes of data starting at :samp:`{address}`. It calls
234 ``obstack_alloc_failed_handler`` if allocation of memory by
235 ``obstack_chunk_alloc`` failed.
237 .. function:: void * obstack_copy0 (struct obstack *obstack_ptr, void *address, size_t size)
239 Like ``obstack_copy``, but appends an extra byte containing a null
240 character. This extra byte is not counted in the argument :samp:`{size}`.
242 The ``obstack_copy0`` macro is convenient for copying a sequence
243 of characters into an obstack as a null-terminated string. Here is an
249 obstack_savestring (char *addr, size_t size)
251 return obstack_copy0 (&myobstack, addr, size);
254 Contrast this with the previous example of ``savestring`` using
255 ``malloc`` see (`Basic Allocation <http://www.gnu.org/software/libc/manual/html_node/Basic-Allocation.html#Basic-Allocation>`_).
257 .. index:: freeing (obstacks)
259 .. _freeing-obstack-objects:
261 Freeing Objects in an Obstack
262 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
264 To free an object allocated in an obstack, use the macro
265 ``obstack_free``. Since the obstack is a stack of objects, freeing
266 one object automatically frees all other objects allocated more recently
269 .. function:: void obstack_free (struct obstack *obstack_ptr, void *object)
271 If :samp:`{object}` is a null pointer, everything allocated in the obstack
272 is freed. Otherwise, :samp:`{object}` must be the address of an object
273 allocated in the obstack. Then :samp:`{object}` is freed, along with
274 everything allocated in :samp:`{obstack}` since :samp:`{object}`.
276 Note that if :samp:`{object}` is a null pointer, the result is an
277 uninitialized obstack. To free all memory in an obstack but leave it
278 valid for further allocation, call ``obstack_free`` with the address
279 of the first object allocated on the obstack:
283 obstack_free (obstack_ptr, first_object_allocated_ptr);
285 Recall that the objects in an obstack are grouped into chunks. When all
286 the objects in a chunk become free, the obstack library automatically
287 frees the chunk (see :ref:`preparing-for-obstacks`). Then other
288 obstacks, or non-obstack allocation, can reuse the space of the chunk.
292 .. _obstack-functions:
294 Obstack Functions and Macros
295 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
297 The interfaces for using obstacks are shown here as functions to
298 specify the return type and argument types, but they are really
299 defined as macros. This means that the arguments don't actually have
300 types, but they generally behave as if they have the types shown.
301 You can call these macros like functions, but you cannot use them in
302 any other way (for example, you cannot take their address).
304 Calling the macros requires a special precaution: namely, the first
305 operand (the obstack pointer) may not contain any side effects, because
306 it may be computed more than once. For example, if you write this:
310 obstack_alloc (get_obstack (), 4);
312 you will find that ``get_obstack`` may be called several times.
313 If you use ``*obstack_list_ptr++`` as the obstack pointer argument,
314 you will get very strange results since the incrementation may occur
317 If you use the GNU C compiler, this precaution is not necessary, because
318 various language extensions in GNU C permit defining the macros so as to
319 compute each argument only once.
321 Note that arguments other than the first will only be evaluated once,
322 even when not using GNU C.
324 ``obstack.h`` does declare a number of functions,
325 ``_obstack_begin``, ``_obstack_begin_1``,
326 ``_obstack_newchunk``, ``_obstack_free``, and
327 ``_obstack_memory_used``. You should not call these directly.
329 .. index:: growing objects (in obstacks), changing the size of a block (obstacks)
336 Because memory in obstack chunks is used sequentially, it is possible to
337 build up an object step by step, adding one or more bytes at a time to the
338 end of the object. With this technique, you do not need to know how much
339 data you will put in the object until you come to the end of it. We call
340 this the technique of :dfn:`growing objects`. The special macros
341 for adding data to the growing object are described in this section.
343 You don't need to do anything special when you start to grow an object.
344 Using one of the macros to add data to the object automatically
345 starts it. However, it is necessary to say explicitly when the object is
346 finished. This is done with ``obstack_finish``.
348 The actual address of the object thus built up is not known until the
349 object is finished. Until then, it always remains possible that you will
350 add so much data that the object must be copied into a new chunk.
352 While the obstack is in use for a growing object, you cannot use it for
353 ordinary allocation of another object. If you try to do so, the space
354 already added to the growing object will become part of the other object.
356 .. function:: void obstack_blank (struct obstack *obstack_ptr, size_t size)
358 The most basic macro for adding to a growing object is
359 ``obstack_blank``, which adds space without initializing it.
361 .. function:: void obstack_grow (struct obstack *obstack_ptr, void *data, size_t size)
363 To add a block of initialized space, use ``obstack_grow``, which is
364 the growing-object analogue of ``obstack_copy``. It adds :samp:`{size}`
365 bytes of data to the growing object, copying the contents from
368 .. function:: void obstack_grow0 (struct obstack *obstack_ptr, void *data, size_t size)
370 This is the growing-object analogue of ``obstack_copy0``. It adds
371 :samp:`{size}` bytes copied from :samp:`{data}`, followed by an additional null
374 .. function:: void obstack_1grow (struct obstack *obstack_ptr, char c)
376 To add one character at a time, use ``obstack_1grow``.
377 It adds a single byte containing :samp:`{c}` to the growing object.
379 .. function:: void obstack_ptr_grow (struct obstack *obstack_ptr, void *data)
381 Adding the value of a pointer one can use
382 ``obstack_ptr_grow``. It adds ``sizeof (void *)`` bytes
383 containing the value of :samp:`{data}`.
385 .. function:: void obstack_int_grow (struct obstack *obstack_ptr, int data)
387 A single value of type ``int`` can be added by using
388 ``obstack_int_grow``. It adds ``sizeof (int)`` bytes to
389 the growing object and initializes them with the value of :samp:`{data}`.
391 .. function:: void * obstack_finish (struct obstack *obstack_ptr)
393 When you are finished growing the object, use
394 ``obstack_finish`` to close it off and return its final address.
396 Once you have finished the object, the obstack is available for ordinary
397 allocation or for growing another object.
399 When you build an object by growing it, you will probably need to know
400 afterward how long it became. You need not keep track of this as you grow
401 the object, because you can find out the length from the obstack
402 with ``obstack_object_size``, before finishing the object.
404 .. function:: size_t obstack_object_size (struct obstack *obstack_ptr)
406 This macro returns the current size of the growing object, in bytes.
407 Remember to call ``obstack_object_size`` *before* finishing the object.
408 After it is finished, ``obstack_object_size`` will return zero.
410 If you have started growing an object and wish to cancel it, you should
411 finish it and then free it, like this:
415 obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
417 This has no effect if no object was growing.
419 .. index:: efficiency and obstacks
421 .. _extra-fast-growing:
423 Extra Fast Growing Objects
424 ~~~~~~~~~~~~~~~~~~~~~~~~~~
426 The usual macros for growing objects incur overhead for checking
427 whether there is room for the new growth in the current chunk. If you
428 are frequently constructing objects in small steps of growth, this
429 overhead can be significant.
431 You can reduce the overhead by using special 'fast growth'
432 macros that grow the object without checking. In order to have a
433 robust program, you must do the checking yourself. If you do this checking
434 in the simplest way each time you are about to add data to the object, you
435 have not saved anything, because that is what the ordinary growth
436 macros do. But if you can arrange to check less often, or check
437 more efficiently, then you make the program faster.
439 ``obstack_room`` returns the amount of room available
440 in the current chunk.
442 .. function:: size_t obstack_room (struct obstack *obstack_ptr)
444 This returns the number of bytes that can be added safely to the current
445 growing object (or to an object about to be started) in obstack
446 :samp:`{obstack}` using the fast growth macros.
448 While you know there is room, you can use these fast growth macros
449 for adding data to a growing object:
451 .. function:: void obstack_1grow_fast (struct obstack *obstack_ptr, char c)
453 ``obstack_1grow_fast`` adds one byte containing the
454 character :samp:`{c}` to the growing object in obstack :samp:`{obstack_ptr}`.
456 .. function:: void obstack_ptr_grow_fast (struct obstack *obstack_ptr, void *data)
458 ``obstack_ptr_grow_fast`` adds ``sizeof (void *)``
459 bytes containing the value of :samp:`{data}` to the growing object in
460 obstack :samp:`{obstack_ptr}`.
462 .. function:: void obstack_int_grow_fast (struct obstack *obstack_ptr, int data)
464 ``obstack_int_grow_fast`` adds ``sizeof (int)`` bytes
465 containing the value of :samp:`{data}` to the growing object in obstack
466 :samp:`{obstack_ptr}`.
468 .. function:: void obstack_blank_fast (struct obstack *obstack_ptr, size_t size)
470 ``obstack_blank_fast`` adds :samp:`{size}` bytes to the
471 growing object in obstack :samp:`{obstack_ptr}` without initializing them.
473 When you check for space using ``obstack_room`` and there is not
474 enough room for what you want to add, the fast growth macros
475 are not safe. In this case, simply use the corresponding ordinary
476 growth macro instead. Very soon this will copy the object to a
477 new chunk; then there will be lots of room available again.
479 So, each time you use an ordinary growth macro, check afterward for
480 sufficient space using ``obstack_room``. Once the object is copied
481 to a new chunk, there will be plenty of space again, so the program will
482 start using the fast growth macros again.
489 add_string (struct obstack *obstack, const char *ptr, size_t len)
493 size_t room = obstack_room (obstack);
496 /* Not enough room. Add one character slowly,
497 which may copy to a new chunk and make room. */
498 obstack_1grow (obstack, *ptr++);
505 /* Add fast as much as we have room for. */
508 obstack_1grow_fast (obstack, *ptr++);
513 .. index:: shrinking objects
515 You can use ``obstack_blank_fast`` with a 'negative' size
516 argument to make the current object smaller. Just don't try to shrink
517 it beyond zero length---there's no telling what will happen if you do
518 that. Earlier versions of obstacks allowed you to use
519 ``obstack_blank`` to shrink objects. This will no longer work.
521 .. index:: obstack status, status of obstack
523 .. _status-of-an-obstack:
528 Here are macros that provide information on the current status of
529 allocation in an obstack. You can use them to learn about an object while
532 .. function:: void * obstack_base (struct obstack *obstack_ptr)
534 This macro returns the tentative address of the beginning of the
535 currently growing object in :samp:`{obstack_ptr}`. If you finish the object
536 immediately, it will have that address. If you make it larger first, it
537 may outgrow the current chunk---then its address will change!
539 If no object is growing, this value says where the next object you
540 allocate will start (once again assuming it fits in the current
543 .. function:: void * obstack_next_free (struct obstack *obstack_ptr)
545 This macro returns the address of the first free byte in the current
546 chunk of obstack :samp:`{obstack_ptr}`. This is the end of the currently
547 growing object. If no object is growing, ``obstack_next_free``
548 returns the same value as ``obstack_base``.
550 .. function:: size_t obstack_object_size (struct obstack *obstack_ptr)
552 This macro returns the size in bytes of the currently growing object.
553 This is equivalent to
557 ((size_t) (obstack_next_free (obstack_ptr) - obstack_base (obstack_ptr)))
559 .. index:: alignment (in obstacks)
561 .. _obstacks-data-alignment:
563 Alignment of Data in Obstacks
564 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
566 Each obstack has an :dfn:`alignment boundary`; each object allocated in
567 the obstack automatically starts on an address that is a multiple of the
568 specified boundary. By default, this boundary is aligned so that
569 the object can hold any type of data.
571 To access an obstack's alignment boundary, use the macro
572 ``obstack_alignment_mask``.
574 .. function:: size_t obstack_alignment_mask (struct obstack *obstack_ptr)
576 The value is a bit mask; a bit that is 1 indicates that the corresponding
577 bit in the address of an object should be 0. The mask value should be one
578 less than a power of 2; the effect is that all object addresses are
579 multiples of that power of 2. The default value of the mask is a value
580 that allows aligned objects to hold any type of data: for example, if
581 its value is 3, any type of data can be stored at locations whose
582 addresses are multiples of 4. A mask value of 0 means an object can start
583 on any multiple of 1 (that is, no alignment is required).
585 The expansion of the macro ``obstack_alignment_mask`` is an lvalue,
586 so you can alter the mask by assignment. For example, this statement:
590 obstack_alignment_mask (obstack_ptr) = 0;
592 has the effect of turning off alignment processing in the specified obstack.
594 Note that a change in alignment mask does not take effect until
595 *after* the next time an object is allocated or finished in the
596 obstack. If you are not growing an object, you can make the new
597 alignment mask take effect immediately by calling ``obstack_finish``.
598 This will finish a zero-length object and then do proper alignment for
601 .. index:: efficiency of chunks, chunks
608 Obstacks work by allocating space for themselves in large chunks, and
609 then parceling out space in the chunks to satisfy your requests. Chunks
610 are normally 4096 bytes long unless you specify a different chunk size.
611 The chunk size includes 8 bytes of overhead that are not actually used
612 for storing objects. Regardless of the specified size, longer chunks
613 will be allocated when necessary for long objects.
615 The obstack library allocates chunks by calling the function
616 ``obstack_chunk_alloc``, which you must define. When a chunk is no
617 longer needed because you have freed all the objects in it, the obstack
618 library frees the chunk by calling ``obstack_chunk_free``, which you
621 These two must be defined (as macros) or declared (as functions) in each
622 source file that uses ``obstack_init`` (see :ref:`creating-obstacks`).
623 Most often they are defined as macros like this:
627 #define obstack_chunk_alloc malloc
628 #define obstack_chunk_free free
630 Note that these are simple macros (no arguments). Macro definitions with
631 arguments will not work! It is necessary that ``obstack_chunk_alloc``
632 or ``obstack_chunk_free``, alone, expand into a function name if it is
633 not itself a function name.
635 If you allocate chunks with ``malloc``, the chunk size should be a
636 power of 2. The default chunk size, 4096, was chosen because it is long
637 enough to satisfy many typical requests on the obstack yet short enough
638 not to waste too much memory in the portion of the last chunk not yet used.
640 .. function:: size_t obstack_chunk_size (struct obstack *obstack_ptr)
642 This returns the chunk size of the given obstack.
644 Since this macro expands to an lvalue, you can specify a new chunk size by
645 assigning it a new value. Doing so does not affect the chunks already
646 allocated, but will change the size of chunks allocated for that particular
647 obstack in the future. It is unlikely to be useful to make the chunk size
648 smaller, but making it larger might improve efficiency if you are
649 allocating many objects whose size is comparable to the chunk size. Here
650 is how to do so cleanly:
654 if (obstack_chunk_size (obstack_ptr) < new-chunk-size)
655 obstack_chunk_size (obstack_ptr) = new-chunk-size;
657 .. _summary-of-obstacks:
659 Summary of Obstack Macros
660 ~~~~~~~~~~~~~~~~~~~~~~~~~
662 Here is a summary of all the macros associated with obstacks. Each
663 takes the address of an obstack (``struct obstack *``) as its first
666 .. function:: int obstack_init (struct obstack *obstack_ptr)
668 Initialize use of an obstack. See :ref:`creating-obstacks`.
670 .. function:: int obstack_begin (struct obstack *obstack_ptr, size_t chunk_size)
672 Initialize use of an obstack, with an initial chunk of
673 :samp:`{chunk_size}` bytes.
675 .. function:: int obstack_specify_allocation (struct obstack *obstack_ptr, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *))
677 Initialize use of an obstack, specifying intial chunk size, chunk
678 alignment, and memory allocation functions.
680 .. function:: int obstack_specify_allocation_with_arg (struct obstack *obstack_ptr, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg)
682 Like ``obstack_specify_allocation``, but specifying memory
683 allocation functions that take an extra first argument, :samp:`{arg}`.
685 .. function:: void *obstack_alloc (struct obstack *obstack_ptr, size_t size)
687 Allocate an object of :samp:`{size}` uninitialized bytes.
688 See :ref:`allocation-in-an-obstack`.
690 .. function:: void *obstack_copy (struct obstack *obstack_ptr, void *address, size_t size)
692 Allocate an object of :samp:`{size}` bytes, with contents copied from
693 :samp:`{address}`. See :ref:`allocation-in-an-obstack`.
695 .. function:: void *obstack_copy0 (struct obstack *obstack_ptr, void *address, size_t size)
697 Allocate an object of :samp:`{size}` +1 bytes, with :samp:`{size}` of them copied
698 from :samp:`{address}`, followed by a null character at the end.
699 See :ref:`allocation-in-an-obstack`.
701 .. function:: void obstack_free (struct obstack *obstack_ptr, void *object)
703 Free :samp:`{object}` (and everything allocated in the specified obstack
704 more recently than :samp:`{object}`). See :ref:`freeing-obstack-objects`.
706 .. function:: void obstack_blank (struct obstack *obstack_ptr, size_t size)
708 Add :samp:`{size}` uninitialized bytes to a growing object.
709 See :ref:`growing-objects`.
711 .. function:: void obstack_grow (struct obstack *obstack_ptr, void *address, size_t size)
713 Add :samp:`{size}` bytes, copied from :samp:`{address}`, to a growing object.
714 See :ref:`growing-objects`.
716 .. function:: void obstack_grow0 (struct obstack *obstack_ptr, void *address, size_t size)
718 Add :samp:`{size}` bytes, copied from :samp:`{address}`, to a growing object,
719 and then add another byte containing a null character. See :ref:`growing-objects`.
721 .. function:: void obstack_1grow (struct obstack *obstack_ptr, char data_char)
723 Add one byte containing :samp:`{data-char}` to a growing object.
724 See :ref:`growing-objects`.
726 .. function:: void *obstack_finish (struct obstack *obstack_ptr)
728 Finalize the object that is growing and return its permanent address.
729 See :ref:`growing-objects`.
731 .. function:: size_t obstack_object_size (struct obstack *obstack_ptr)
733 Get the current size of the currently growing object. See :ref:`growing-objects`.
735 .. function:: void obstack_blank_fast (struct obstack *obstack_ptr, size_t size)
737 Add :samp:`{size}` uninitialized bytes to a growing object without checking
738 that there is enough room. See :ref:`extra-fast-growing`.
740 .. function:: void obstack_1grow_fast (struct obstack *obstack_ptr, char data_char)
742 Add one byte containing :samp:`{data-char}` to a growing object without
743 checking that there is enough room. See :ref:`extra-fast-growing`.
745 .. function:: size_t obstack_room (struct obstack *obstack_ptr)
747 Get the amount of room now available for growing the current object.
748 See :ref:`extra-fast-growing`.
750 .. function:: size_t obstack_alignment_mask (struct obstack *obstack_ptr)
752 The mask used for aligning the beginning of an object. This is an
753 lvalue. See :ref:`obstacks-data-alignment`.
755 .. function:: size_t obstack_chunk_size (struct obstack *obstack_ptr)
757 The size for allocating chunks. This is an lvalue. See :ref:`obstack-chunks`.
759 .. function:: void *obstack_base (struct obstack *obstack_ptr)
761 Tentative starting address of the currently growing object.
762 See :ref:`status-of-an-obstack`.
764 .. function:: void *obstack_next_free (struct obstack *obstack_ptr)
766 Address just after the end of the currently growing object.
767 See :ref:`status-of-an-obstack`.