1 @node Memory, Character Handling, Error Reporting, Top
2 @chapter Virtual Memory Allocation And Paging
3 @c %MENU% Allocating virtual memory and controlling paging
4 @cindex memory allocation
5 @cindex storage allocation
7 This chapter describes how processes manage and use memory in a system
10 @Theglibc{} has several functions for dynamically allocating
11 virtual memory in various ways. They vary in generality and in
12 efficiency. The library also provides functions for controlling paging
13 and allocation of real memory.
17 * Memory Concepts:: An introduction to concepts and terminology.
18 * Memory Allocation:: Allocating storage for your program data
19 * Resizing the Data Segment:: @code{brk}, @code{sbrk}
20 * Locking Pages:: Preventing page faults
23 Memory mapped I/O is not discussed in this chapter. @xref{Memory-mapped I/O}.
28 @section Process Memory Concepts
30 One of the most basic resources a process has available to it is memory.
31 There are a lot of different ways systems organize memory, but in a
32 typical one, each process has one linear virtual address space, with
33 addresses running from zero to some huge maximum. It need not be
34 contiguous; i.e., not all of these addresses actually can be used to
37 The virtual memory is divided into pages (4 kilobytes is typical).
38 Backing each page of virtual memory is a page of real memory (called a
39 @dfn{frame}) or some secondary storage, usually disk space. The disk
40 space might be swap space or just some ordinary disk file. Actually, a
41 page of all zeroes sometimes has nothing at all backing it -- there's
42 just a flag saying it is all zeroes.
44 @cindex frame, real memory
46 @cindex page, virtual memory
48 The same frame of real memory or backing store can back multiple virtual
49 pages belonging to multiple processes. This is normally the case, for
50 example, with virtual memory occupied by @glibcadj{} code. The same
51 real memory frame containing the @code{printf} function backs a virtual
52 memory page in each of the existing processes that has a @code{printf}
55 In order for a program to access any part of a virtual page, the page
56 must at that moment be backed by (``connected to'') a real frame. But
57 because there is usually a lot more virtual memory than real memory, the
58 pages must move back and forth between real memory and backing store
59 regularly, coming into real memory when a process needs to access them
60 and then retreating to backing store when not needed anymore. This
61 movement is called @dfn{paging}.
63 When a program attempts to access a page which is not at that moment
64 backed by real memory, this is known as a @dfn{page fault}. When a page
65 fault occurs, the kernel suspends the process, places the page into a
66 real page frame (this is called ``paging in'' or ``faulting in''), then
67 resumes the process so that from the process' point of view, the page
68 was in real memory all along. In fact, to the process, all pages always
69 seem to be in real memory. Except for one thing: the elapsed execution
70 time of an instruction that would normally be a few nanoseconds is
71 suddenly much, much, longer (because the kernel normally has to do I/O
72 to complete the page-in). For programs sensitive to that, the functions
73 described in @ref{Locking Pages} can control it.
77 Within each virtual address space, a process has to keep track of what
78 is at which addresses, and that process is called memory allocation.
79 Allocation usually brings to mind meting out scarce resources, but in
80 the case of virtual memory, that's not a major goal, because there is
81 generally much more of it than anyone needs. Memory allocation within a
82 process is mainly just a matter of making sure that the same byte of
83 memory isn't used to store two different things.
85 Processes allocate memory in two major ways: by exec and
86 programmatically. Actually, forking is a third way, but it's not very
87 interesting. @xref{Creating a Process}.
89 Exec is the operation of creating a virtual address space for a process,
90 loading its basic program into it, and executing the program. It is
91 done by the ``exec'' family of functions (e.g. @code{execl}). The
92 operation takes a program file (an executable), it allocates space to
93 load all the data in the executable, loads it, and transfers control to
94 it. That data is most notably the instructions of the program (the
95 @dfn{text}), but also literals and constants in the program and even
96 some variables: C variables with the static storage class (@pxref{Memory
102 Once that program begins to execute, it uses programmatic allocation to
103 gain additional memory. In a C program with @theglibc{}, there
104 are two kinds of programmatic allocation: automatic and dynamic.
105 @xref{Memory Allocation and C}.
107 Memory-mapped I/O is another form of dynamic virtual memory allocation.
108 Mapping memory to a file means declaring that the contents of certain
109 range of a process' addresses shall be identical to the contents of a
110 specified regular file. The system makes the virtual memory initially
111 contain the contents of the file, and if you modify the memory, the
112 system writes the same modification to the file. Note that due to the
113 magic of virtual memory and page faults, there is no reason for the
114 system to do I/O to read the file, or allocate real memory for its
115 contents, until the program accesses the virtual memory.
116 @xref{Memory-mapped I/O}.
117 @cindex memory mapped I/O
118 @cindex memory mapped file
119 @cindex files, accessing
121 Just as it programmatically allocates memory, the program can
122 programmatically deallocate (@dfn{free}) it. You can't free the memory
123 that was allocated by exec. When the program exits or execs, you might
124 say that all its memory gets freed, but since in both cases the address
125 space ceases to exist, the point is really moot. @xref{Program
127 @cindex execing a program
128 @cindex freeing memory
129 @cindex exiting a program
131 A process' virtual address space is divided into segments. A segment is
132 a contiguous range of virtual addresses. Three important segments are:
138 The @dfn{text segment} contains a program's instructions and literals and
139 static constants. It is allocated by exec and stays the same size for
140 the life of the virtual address space.
143 The @dfn{data segment} is working storage for the program. It can be
144 preallocated and preloaded by exec and the process can extend or shrink
145 it by calling functions as described in @xref{Resizing the Data
146 Segment}. Its lower end is fixed.
149 The @dfn{stack segment} contains a program stack. It grows as the stack
150 grows, but doesn't shrink when the stack shrinks.
156 @node Memory Allocation
157 @section Allocating Storage For Program Data
159 This section covers how ordinary programs manage storage for their data,
160 including the famous @code{malloc} function and some fancier facilities
161 special @theglibc{} and GNU Compiler.
164 * Memory Allocation and C:: How to get different kinds of allocation in C.
165 * Unconstrained Allocation:: The @code{malloc} facility allows fully general
167 * Allocation Debugging:: Finding memory leaks and not freed memory.
168 * Obstacks:: Obstacks are less general than malloc
169 but more efficient and convenient.
170 * Variable Size Automatic:: Allocation of variable-sized blocks
171 of automatic storage that are freed when the
172 calling function returns.
176 @node Memory Allocation and C
177 @subsection Memory Allocation in C Programs
179 The C language supports two kinds of memory allocation through the
180 variables in C programs:
184 @dfn{Static allocation} is what happens when you declare a static or
185 global variable. Each static or global variable defines one block of
186 space, of a fixed size. The space is allocated once, when your program
187 is started (part of the exec operation), and is never freed.
188 @cindex static memory allocation
189 @cindex static storage class
192 @dfn{Automatic allocation} happens when you declare an automatic
193 variable, such as a function argument or a local variable. The space
194 for an automatic variable is allocated when the compound statement
195 containing the declaration is entered, and is freed when that
196 compound statement is exited.
197 @cindex automatic memory allocation
198 @cindex automatic storage class
200 In GNU C, the size of the automatic storage can be an expression
201 that varies. In other C implementations, it must be a constant.
204 A third important kind of memory allocation, @dfn{dynamic allocation},
205 is not supported by C variables but is available via @glibcadj{}
207 @cindex dynamic memory allocation
209 @subsubsection Dynamic Memory Allocation
210 @cindex dynamic memory allocation
212 @dfn{Dynamic memory allocation} is a technique in which programs
213 determine as they are running where to store some information. You need
214 dynamic allocation when the amount of memory you need, or how long you
215 continue to need it, depends on factors that are not known before the
218 For example, you may need a block to store a line read from an input
219 file; since there is no limit to how long a line can be, you must
220 allocate the memory dynamically and make it dynamically larger as you
221 read more of the line.
223 Or, you may need a block for each record or each definition in the input
224 data; since you can't know in advance how many there will be, you must
225 allocate a new block for each record or definition as you read it.
227 When you use dynamic allocation, the allocation of a block of memory is
228 an action that the program requests explicitly. You call a function or
229 macro when you want to allocate space, and specify the size with an
230 argument. If you want to free the space, you do so by calling another
231 function or macro. You can do these things whenever you want, as often
234 Dynamic allocation is not supported by C variables; there is no storage
235 class ``dynamic'', and there can never be a C variable whose value is
236 stored in dynamically allocated space. The only way to get dynamically
237 allocated memory is via a system call (which is generally via a @glibcadj{}
238 function call), and the only way to refer to dynamically
239 allocated space is through a pointer. Because it is less convenient,
240 and because the actual process of dynamic allocation requires more
241 computation time, programmers generally use dynamic allocation only when
242 neither static nor automatic allocation will serve.
244 For example, if you want to allocate dynamically some space to hold a
245 @code{struct foobar}, you cannot declare a variable of type @code{struct
246 foobar} whose contents are the dynamically allocated space. But you can
247 declare a variable of pointer type @code{struct foobar *} and assign it the
248 address of the space. Then you can use the operators @samp{*} and
249 @samp{->} on this pointer variable to refer to the contents of the space:
254 = (struct foobar *) malloc (sizeof (struct foobar));
256 ptr->next = current_foobar;
257 current_foobar = ptr;
261 @node Unconstrained Allocation
262 @subsection Unconstrained Allocation
263 @cindex unconstrained memory allocation
264 @cindex @code{malloc} function
265 @cindex heap, dynamic allocation from
267 The most general dynamic allocation facility is @code{malloc}. It
268 allows you to allocate blocks of memory of any size at any time, make
269 them bigger or smaller at any time, and free the blocks individually at
273 * Basic Allocation:: Simple use of @code{malloc}.
274 * Malloc Examples:: Examples of @code{malloc}. @code{xmalloc}.
275 * Freeing after Malloc:: Use @code{free} to free a block you
276 got with @code{malloc}.
277 * Changing Block Size:: Use @code{realloc} to make a block
279 * Allocating Cleared Space:: Use @code{calloc} to allocate a
281 * Efficiency and Malloc:: Efficiency considerations in use of
283 * Aligned Memory Blocks:: Allocating specially aligned memory.
284 * Malloc Tunable Parameters:: Use @code{mallopt} to adjust allocation
286 * Heap Consistency Checking:: Automatic checking for errors.
287 * Hooks for Malloc:: You can use these hooks for debugging
288 programs that use @code{malloc}.
289 * Statistics of Malloc:: Getting information about how much
290 memory your program is using.
291 * Summary of Malloc:: Summary of @code{malloc} and related functions.
294 @node Basic Allocation
295 @subsubsection Basic Memory Allocation
296 @cindex allocation of memory with @code{malloc}
298 To allocate a block of memory, call @code{malloc}. The prototype for
299 this function is in @file{stdlib.h}.
302 @comment malloc.h stdlib.h
304 @deftypefun {void *} malloc (size_t @var{size})
305 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
306 @c Malloc hooks and __morecore pointers, as well as such parameters as
307 @c max_n_mmaps and max_mmapped_mem, are accessed without guards, so they
308 @c could pose a thread safety issue; in order to not declare malloc
309 @c MT-unsafe, it's modifying the hooks and parameters while multiple
310 @c threads are active that is regarded as unsafe. An arena's next field
311 @c is initialized and never changed again, except for main_arena's,
312 @c that's protected by list_lock; next_free is only modified while
313 @c list_lock is held too. All other data members of an arena, as well
314 @c as the metadata of the memory areas assigned to it, are only modified
315 @c while holding the arena's mutex (fastbin pointers use catomic ops
316 @c because they may be modified by free without taking the arena's
317 @c lock). Some reassurance was needed for fastbins, for it wasn't clear
318 @c how they were initialized. It turns out they are always
319 @c zero-initialized: main_arena's, for being static data, and other
320 @c arena's, for being just-mmapped memory.
322 @c Leaking file descriptors and memory in case of cancellation is
323 @c unavoidable without disabling cancellation, but the lock situation is
324 @c a bit more complicated: we don't have fallback arenas for malloc to
325 @c be safe to call from within signal handlers. Error-checking mutexes
326 @c or trylock could enable us to try and use alternate arenas, even with
327 @c -DPER_THREAD (enabled by default), but supporting interruption
328 @c (cancellation or signal handling) while holding the arena list mutex
329 @c would require more work; maybe blocking signals and disabling async
330 @c cancellation while manipulating the arena lists?
332 @c __libc_malloc @asulock @aculock @acsfd @acsmem
334 @c *malloc_hook unguarded
335 @c arena_lock @asulock @aculock @acsfd @acsmem
336 @c mutex_lock @asulock @aculock
337 @c arena_get2 @asulock @aculock @acsfd @acsmem
338 @c get_free_list @asulock @aculock
339 @c mutex_lock (list_lock) dup @asulock @aculock
340 @c mutex_unlock (list_lock) dup @aculock
341 @c mutex_lock (arena lock) dup @asulock @aculock [returns locked]
342 @c __get_nprocs ext ok @acsfd
343 @c NARENAS_FROM_NCORES ok
344 @c catomic_compare_and_exchange_bool_acq ok
345 @c _int_new_arena ok @asulock @aculock @acsmem
346 @c new_heap ok @acsmem
352 @c tsd_setspecific dup ok
354 @c mutex_lock (just-created mutex) ok, returns locked
355 @c mutex_lock (list_lock) dup @asulock @aculock
356 @c atomic_write_barrier ok
357 @c mutex_unlock (list_lock) @aculock
358 @c catomic_decrement ok
359 @c reused_arena @asulock @aculock
360 @c reads&writes next_to_use and iterates over arena next without guards
361 @c those are harmless as long as we don't drop arenas from the
362 @c NEXT list, and we never do; when a thread terminates,
363 @c arena_thread_freeres prepends the arena to the free_list
364 @c NEXT_FREE list, but NEXT is never modified, so it's safe!
365 @c mutex_trylock (arena lock) @asulock @aculock
366 @c mutex_lock (arena lock) dup @asulock @aculock
367 @c tsd_setspecific dup ok
368 @c _int_malloc @acsfd @acsmem
369 @c checked_request2size ok
370 @c REQUEST_OUT_OF_RANGE ok
375 @c catomic_compare_and_exhange_val_acq ok
376 @c malloc_printerr dup @mtsenv
377 @c if we get to it, we're toast already, undefined behavior must have
378 @c been invoked before
379 @c libc_message @mtsenv [no leaks with cancellation disabled]
381 @c pthread_setcancelstate disable ok
382 @c libc_secure_getenv @mtsenv
384 @c open_not_cancel_2 dup @acsfd
386 @c WRITEV_FOR_FATAL ok
390 @c BEFORE_ABORT @acsfd
392 @c write_not_cancel dup ok
393 @c backtrace_symbols_fd @aculock
394 @c open_not_cancel_2 dup @acsfd
395 @c read_not_cancel dup ok
396 @c close_not_cancel_no_status dup @acsfd
400 @c check_remalloced_chunk ok/disabled
403 @c in_smallbin_range ok
407 @c malloc_consolidate ok
408 @c get_max_fast dup ok
409 @c clear_fastchunks ok
410 @c unsorted_chunks dup ok
412 @c atomic_exchange_acq ok
413 @c check_inuse_chunk dup ok/disabled
414 @c chunk_at_offset dup ok
416 @c inuse_bit_at_offset dup ok
418 @c clear_inuse_bit_at_offset dup ok
419 @c in_smallbin_range dup ok
421 @c malloc_init_state ok
423 @c set_noncontiguous dup ok
424 @c set_max_fast dup ok
426 @c unsorted_chunks dup ok
427 @c check_malloc_state ok/disabled
428 @c set_inuse_bit_at_offset ok
429 @c check_malloced_chunk ok/disabled
431 @c have_fastchunks ok
432 @c unsorted_chunks ok
435 @c chunk_at_offset ok
442 @c malloc_printerr dup ok
443 @c in_smallbin_range dup ok
447 @c sysmalloc @acsfd @acsmem
450 @c check_chunk ok/disabled
453 @c chunk_at_offset dup ok
465 @c *__morecore ok unguarded
466 @c __default_morecore
469 @c *__after_morecore_hook unguarded
470 @c set_noncontiguous ok
471 @c malloc_printerr dup ok
472 @c _int_free (have_lock) @acsfd @acsmem [@asulock @aculock]
474 @c mutex_unlock dup @aculock/!have_lock
475 @c malloc_printerr dup ok
476 @c check_inuse_chunk ok/disabled
477 @c chunk_at_offset dup ok
478 @c mutex_lock dup @asulock @aculock/@have_lock
483 @c fastbin_index dup ok
485 @c catomic_compare_and_exchange_val_rel ok
486 @c chunk_is_mmapped ok
490 @c inuse_bit_at_offset dup ok
491 @c clear_inuse_bit_at_offset ok
492 @c unsorted_chunks dup ok
493 @c in_smallbin_range dup ok
496 @c check_free_chunk ok/disabled
497 @c check_chunk dup ok/disabled
498 @c have_fastchunks dup ok
499 @c malloc_consolidate dup ok
502 @c *__after_morecore_hook dup unguarded
504 @c check_malloc_state ok/disabled
506 @c heap_for_ptr dup ok
507 @c heap_trim @acsfd @acsmem
509 @c chunk_at_offset dup ok
513 @c delete_heap @acsmem
514 @c munmap dup @acsmem
517 @c shrink_heap @acsfd
518 @c check_may_shrink_heap @acsfd
519 @c open_not_cancel_2 @acsfd
520 @c read_not_cancel ok
521 @c close_not_cancel_no_status @acsfd
524 @c munmap_chunk @acsmem
526 @c chunk_is_mmapped dup ok
528 @c malloc_printerr dup ok
529 @c munmap dup @acsmem
530 @c check_malloc_state ok/disabled
531 @c arena_get_retry @asulock @aculock @acsfd @acsmem
532 @c mutex_unlock dup @aculock
533 @c mutex_lock dup @asulock @aculock
534 @c arena_get2 dup @asulock @aculock @acsfd @acsmem
535 @c mutex_unlock @aculock
537 @c chunk_is_mmapped ok
538 @c arena_for_chunk ok
539 @c chunk_non_main_arena ok
541 This function returns a pointer to a newly allocated block @var{size}
542 bytes long, or a null pointer if the block could not be allocated.
545 The contents of the block are undefined; you must initialize it yourself
546 (or use @code{calloc} instead; @pxref{Allocating Cleared Space}).
547 Normally you would cast the value as a pointer to the kind of object
548 that you want to store in the block. Here we show an example of doing
549 so, and of initializing the space with zeros using the library function
550 @code{memset} (@pxref{Copying Strings and Arrays}):
555 ptr = (struct foo *) malloc (sizeof (struct foo));
556 if (ptr == 0) abort ();
557 memset (ptr, 0, sizeof (struct foo));
560 You can store the result of @code{malloc} into any pointer variable
561 without a cast, because @w{ISO C} automatically converts the type
562 @code{void *} to another type of pointer when necessary. But the cast
563 is necessary in contexts other than assignment operators or if you might
564 want your code to run in traditional C.
566 Remember that when allocating space for a string, the argument to
567 @code{malloc} must be one plus the length of the string. This is
568 because a string is terminated with a null character that doesn't count
569 in the ``length'' of the string but does need space. For example:
574 ptr = (char *) malloc (length + 1);
578 @xref{Representation of Strings}, for more information about this.
580 @node Malloc Examples
581 @subsubsection Examples of @code{malloc}
583 If no more space is available, @code{malloc} returns a null pointer.
584 You should check the value of @emph{every} call to @code{malloc}. It is
585 useful to write a subroutine that calls @code{malloc} and reports an
586 error if the value is a null pointer, returning only if the value is
587 nonzero. This function is conventionally called @code{xmalloc}. Here
592 xmalloc (size_t size)
594 void *value = malloc (size);
596 fatal ("virtual memory exhausted");
601 Here is a real example of using @code{malloc} (by way of @code{xmalloc}).
602 The function @code{savestring} will copy a sequence of characters into
603 a newly allocated null-terminated string:
608 savestring (const char *ptr, size_t len)
610 char *value = (char *) xmalloc (len + 1);
612 return (char *) memcpy (value, ptr, len);
617 The block that @code{malloc} gives you is guaranteed to be aligned so
618 that it can hold any type of data. On @gnusystems{}, the address is
619 always a multiple of eight on 32-bit systems, and a multiple of 16 on
620 64-bit systems. Only rarely is any higher boundary (such as a page
621 boundary) necessary; for those cases, use @code{aligned_alloc} or
622 @code{posix_memalign} (@pxref{Aligned Memory Blocks}).
624 Note that the memory located after the end of the block is likely to be
625 in use for something else; perhaps a block already allocated by another
626 call to @code{malloc}. If you attempt to treat the block as longer than
627 you asked for it to be, you are liable to destroy the data that
628 @code{malloc} uses to keep track of its blocks, or you may destroy the
629 contents of another block. If you have already allocated a block and
630 discover you want it to be bigger, use @code{realloc} (@pxref{Changing
633 @node Freeing after Malloc
634 @subsubsection Freeing Memory Allocated with @code{malloc}
635 @cindex freeing memory allocated with @code{malloc}
636 @cindex heap, freeing memory from
638 When you no longer need a block that you got with @code{malloc}, use the
639 function @code{free} to make the block available to be allocated again.
640 The prototype for this function is in @file{stdlib.h}.
643 @comment malloc.h stdlib.h
645 @deftypefun void free (void *@var{ptr})
646 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
647 @c __libc_free @asulock @aculock @acsfd @acsmem
648 @c releasing memory into fastbins modifies the arena without taking
649 @c its mutex, but catomic operations ensure safety. If two (or more)
650 @c threads are running malloc and have their own arenas locked when
651 @c each gets a signal whose handler free()s large (non-fastbin-able)
652 @c blocks from each other's arena, we deadlock; this is a more general
654 @c *__free_hook unguarded
656 @c chunk_is_mmapped ok, chunk bits not modified after allocation
658 @c munmap_chunk dup @acsmem
659 @c arena_for_chunk dup ok
660 @c _int_free (!have_lock) dup @asulock @aculock @acsfd @acsmem
661 The @code{free} function deallocates the block of memory pointed at
667 @deftypefun void cfree (void *@var{ptr})
668 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
670 This function does the same thing as @code{free}. It's provided for
671 backward compatibility with SunOS; you should use @code{free} instead.
674 Freeing a block alters the contents of the block. @strong{Do not expect to
675 find any data (such as a pointer to the next block in a chain of blocks) in
676 the block after freeing it.} Copy whatever you need out of the block before
677 freeing it! Here is an example of the proper way to free all the blocks in
678 a chain, and the strings that they point to:
688 free_chain (struct chain *chain)
692 struct chain *next = chain->next;
700 Occasionally, @code{free} can actually return memory to the operating
701 system and make the process smaller. Usually, all it can do is allow a
702 later call to @code{malloc} to reuse the space. In the meantime, the
703 space remains in your program as part of a free-list used internally by
706 There is no point in freeing blocks at the end of a program, because all
707 of the program's space is given back to the system when the process
710 @node Changing Block Size
711 @subsubsection Changing the Size of a Block
712 @cindex changing the size of a block (@code{malloc})
714 Often you do not know for certain how big a block you will ultimately need
715 at the time you must begin to use the block. For example, the block might
716 be a buffer that you use to hold a line being read from a file; no matter
717 how long you make the buffer initially, you may encounter a line that is
720 You can make the block longer by calling @code{realloc}. This function
721 is declared in @file{stdlib.h}.
724 @comment malloc.h stdlib.h
726 @deftypefun {void *} realloc (void *@var{ptr}, size_t @var{newsize})
727 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
728 @c It may call the implementations of malloc and free, so all of their
729 @c issues arise, plus the realloc hook, also accessed without guards.
731 @c __libc_realloc @asulock @aculock @acsfd @acsmem
732 @c *__realloc_hook unguarded
733 @c __libc_free dup @asulock @aculock @acsfd @acsmem
734 @c __libc_malloc dup @asulock @aculock @acsfd @acsmem
737 @c malloc_printerr dup ok
738 @c checked_request2size dup ok
739 @c chunk_is_mmapped dup ok
746 @c munmap_chunk dup @acsmem
747 @c arena_for_chunk dup ok
748 @c mutex_lock (arena mutex) dup @asulock @aculock
749 @c _int_realloc @acsfd @acsmem
750 @c malloc_printerr dup ok
751 @c check_inuse_chunk dup ok/disabled
752 @c chunk_at_offset dup ok
754 @c set_head_size dup ok
755 @c chunk_at_offset dup ok
760 @c _int_malloc dup @acsfd @acsmem
762 @c MALLOC_COPY dup ok
763 @c _int_free (have_lock) dup @acsfd @acsmem
764 @c set_inuse_bit_at_offset dup ok
766 @c mutex_unlock (arena mutex) dup @aculock
767 @c _int_free (!have_lock) dup @asulock @aculock @acsfd @acsmem
769 The @code{realloc} function changes the size of the block whose address is
770 @var{ptr} to be @var{newsize}.
772 Since the space after the end of the block may be in use, @code{realloc}
773 may find it necessary to copy the block to a new address where more free
774 space is available. The value of @code{realloc} is the new address of the
775 block. If the block needs to be moved, @code{realloc} copies the old
778 If you pass a null pointer for @var{ptr}, @code{realloc} behaves just
779 like @samp{malloc (@var{newsize})}. This can be convenient, but beware
780 that older implementations (before @w{ISO C}) may not support this
781 behavior, and will probably crash when @code{realloc} is passed a null
785 Like @code{malloc}, @code{realloc} may return a null pointer if no
786 memory space is available to make the block bigger. When this happens,
787 the original block is untouched; it has not been modified or relocated.
789 In most cases it makes no difference what happens to the original block
790 when @code{realloc} fails, because the application program cannot continue
791 when it is out of memory, and the only thing to do is to give a fatal error
792 message. Often it is convenient to write and use a subroutine,
793 conventionally called @code{xrealloc}, that takes care of the error message
794 as @code{xmalloc} does for @code{malloc}:
798 xrealloc (void *ptr, size_t size)
800 void *value = realloc (ptr, size);
802 fatal ("Virtual memory exhausted");
807 You can also use @code{realloc} to make a block smaller. The reason you
808 would do this is to avoid tying up a lot of memory space when only a little
810 @comment The following is no longer true with the new malloc.
811 @comment But it seems wise to keep the warning for other implementations.
812 In several allocation implementations, making a block smaller sometimes
813 necessitates copying it, so it can fail if no other space is available.
815 If the new size you specify is the same as the old size, @code{realloc}
816 is guaranteed to change nothing and return the same address that you gave.
818 @node Allocating Cleared Space
819 @subsubsection Allocating Cleared Space
821 The function @code{calloc} allocates memory and clears it to zero. It
822 is declared in @file{stdlib.h}.
825 @comment malloc.h stdlib.h
827 @deftypefun {void *} calloc (size_t @var{count}, size_t @var{eltsize})
828 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
829 @c Same caveats as malloc.
831 @c __libc_calloc @asulock @aculock @acsfd @acsmem
832 @c *__malloc_hook dup unguarded
834 @c arena_get @asulock @aculock @acsfd @acsmem
835 @c arena_lock dup @asulock @aculock @acsfd @acsmem
838 @c heap_for_ptr dup ok
839 @c _int_malloc dup @acsfd @acsmem
840 @c arena_get_retry dup @asulock @aculock @acsfd @acsmem
841 @c mutex_unlock dup @aculock
843 @c chunk_is_mmapped dup ok
846 This function allocates a block long enough to contain a vector of
847 @var{count} elements, each of size @var{eltsize}. Its contents are
848 cleared to zero before @code{calloc} returns.
851 You could define @code{calloc} as follows:
855 calloc (size_t count, size_t eltsize)
857 size_t size = count * eltsize;
858 void *value = malloc (size);
860 memset (value, 0, size);
865 But in general, it is not guaranteed that @code{calloc} calls
866 @code{malloc} internally. Therefore, if an application provides its own
867 @code{malloc}/@code{realloc}/@code{free} outside the C library, it
868 should always define @code{calloc}, too.
870 @node Efficiency and Malloc
871 @subsubsection Efficiency Considerations for @code{malloc}
872 @cindex efficiency and @code{malloc}
879 @c No longer true, see below instead.
880 To make the best use of @code{malloc}, it helps to know that the GNU
881 version of @code{malloc} always dispenses small amounts of memory in
882 blocks whose sizes are powers of two. It keeps separate pools for each
883 power of two. This holds for sizes up to a page size. Therefore, if
884 you are free to choose the size of a small block in order to make
885 @code{malloc} more efficient, make it a power of two.
886 @c !!! xref getpagesize
888 Once a page is split up for a particular block size, it can't be reused
889 for another size unless all the blocks in it are freed. In many
890 programs, this is unlikely to happen. Thus, you can sometimes make a
891 program use memory more efficiently by using blocks of the same size for
892 many different purposes.
894 When you ask for memory blocks of a page or larger, @code{malloc} uses a
895 different strategy; it rounds the size up to a multiple of a page, and
896 it can coalesce and split blocks as needed.
898 The reason for the two strategies is that it is important to allocate
899 and free small blocks as fast as possible, but speed is less important
900 for a large block since the program normally spends a fair amount of
901 time using it. Also, large blocks are normally fewer in number.
902 Therefore, for large blocks, it makes sense to use a method which takes
903 more time to minimize the wasted space.
907 As opposed to other versions, the @code{malloc} in @theglibc{}
908 does not round up block sizes to powers of two, neither for large nor
909 for small sizes. Neighboring chunks can be coalesced on a @code{free}
910 no matter what their size is. This makes the implementation suitable
911 for all kinds of allocation patterns without generally incurring high
912 memory waste through fragmentation.
914 Very large blocks (much larger than a page) are allocated with
915 @code{mmap} (anonymous or via @code{/dev/zero}) by this implementation.
916 This has the great advantage that these chunks are returned to the
917 system immediately when they are freed. Therefore, it cannot happen
918 that a large chunk becomes ``locked'' in between smaller ones and even
919 after calling @code{free} wastes memory. The size threshold for
920 @code{mmap} to be used can be adjusted with @code{mallopt}. The use of
921 @code{mmap} can also be disabled completely.
923 @node Aligned Memory Blocks
924 @subsubsection Allocating Aligned Memory Blocks
926 @cindex page boundary
927 @cindex alignment (with @code{malloc})
929 The address of a block returned by @code{malloc} or @code{realloc} in
930 @gnusystems{} is always a multiple of eight (or sixteen on 64-bit
931 systems). If you need a block whose address is a multiple of a higher
932 power of two than that, use @code{aligned_alloc} or @code{posix_memalign}.
933 @code{aligned_alloc} and @code{posix_memalign} are declared in
937 @deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size})
938 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
939 @c Alias to memalign.
940 The @code{aligned_alloc} function allocates a block of @var{size} bytes whose
941 address is a multiple of @var{alignment}. The @var{alignment} must be a
942 power of two and @var{size} must be a multiple of @var{alignment}.
944 The @code{aligned_alloc} function returns a null pointer on error and sets
945 @code{errno} to one of the following values:
949 There was insufficient memory available to satisfy the request.
952 @var{alignment} is not a power of two.
954 This function was introduced in @w{ISO C11} and hence may have better
955 portability to modern non-POSIX systems than @code{posix_memalign}.
962 @deftypefun {void *} memalign (size_t @var{boundary}, size_t @var{size})
963 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
964 @c Same issues as malloc. The padding bytes are safely freed in
965 @c _int_memalign, with the arena still locked.
967 @c __libc_memalign @asulock @aculock @acsfd @acsmem
968 @c *__memalign_hook dup unguarded
969 @c __libc_malloc dup @asulock @aculock @acsfd @acsmem
970 @c arena_get dup @asulock @aculock @acsfd @acsmem
971 @c _int_memalign @acsfd @acsmem
972 @c _int_malloc dup @acsfd @acsmem
973 @c checked_request2size dup ok
976 @c chunk_is_mmapped dup ok
979 @c set_inuse_bit_at_offset dup ok
980 @c set_head_size dup ok
981 @c _int_free (have_lock) dup @acsfd @acsmem
982 @c chunk_at_offset dup ok
983 @c check_inuse_chunk dup ok
984 @c arena_get_retry dup @asulock @aculock @acsfd @acsmem
985 @c mutex_unlock dup @aculock
986 The @code{memalign} function allocates a block of @var{size} bytes whose
987 address is a multiple of @var{boundary}. The @var{boundary} must be a
988 power of two! The function @code{memalign} works by allocating a
989 somewhat larger block, and then returning an address within the block
990 that is on the specified boundary.
992 The @code{memalign} function returns a null pointer on error and sets
993 @code{errno} to one of the following values:
997 There was insufficient memory available to satisfy the request.
1000 @var{alignment} is not a power of two.
1004 The @code{memalign} function is obsolete and @code{aligned_alloc} or
1005 @code{posix_memalign} should be used instead.
1010 @deftypefun int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
1011 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
1012 @c Calls memalign unless the requirements are not met (powerof2 macro is
1013 @c safe given an automatic variable as an argument) or there's a
1014 @c memalign hook (accessed unguarded, but safely).
1015 The @code{posix_memalign} function is similar to the @code{memalign}
1016 function in that it returns a buffer of @var{size} bytes aligned to a
1017 multiple of @var{alignment}. But it adds one requirement to the
1018 parameter @var{alignment}: the value must be a power of two multiple of
1019 @code{sizeof (void *)}.
1021 If the function succeeds in allocation memory a pointer to the allocated
1022 memory is returned in @code{*@var{memptr}} and the return value is zero.
1023 Otherwise the function returns an error value indicating the problem.
1024 The possible error values returned are:
1028 There was insufficient memory available to satisfy the request.
1031 @var{alignment} is not a power of two multiple of @code{sizeof (void *)}.
1035 This function was introduced in POSIX 1003.1d. Although this function is
1036 superseded by @code{aligned_alloc}, it is more portable to older POSIX
1037 systems that do not support @w{ISO C11}.
1040 @comment malloc.h stdlib.h
1042 @deftypefun {void *} valloc (size_t @var{size})
1043 @safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{} @acsfd{} @acsmem{}}}
1044 @c __libc_valloc @mtuinit @asuinit @asulock @aculock @acsfd @acsmem
1045 @c ptmalloc_init (once) @mtsenv @asulock @aculock @acsfd @acsmem
1046 @c _dl_addr @asucorrupt? @aculock
1047 @c __rtld_lock_lock_recursive (dl_load_lock) @asucorrupt? @aculock
1048 @c _dl_find_dso_for_object ok, iterates over dl_ns and its _ns_loaded objs
1049 @c the ok above assumes no partial updates on dl_ns and _ns_loaded
1050 @c that could confuse a _dl_addr call in a signal handler
1051 @c _dl_addr_inside_object ok
1052 @c determine_info ok
1053 @c __rtld_lock_unlock_recursive (dl_load_lock) @aculock
1054 @c *_environ @mtsenv
1055 @c next_env_entry ok
1057 @c __libc_mallopt dup @mtasuconst:mallopt [setting mp_]
1058 @c __malloc_check_init @mtasuconst:malloc_hooks [setting hooks]
1059 @c *__malloc_initialize_hook unguarded, ok
1060 @c *__memalign_hook dup ok, unguarded
1061 @c arena_get dup @asulock @aculock @acsfd @acsmem
1062 @c _int_valloc @acsfd @acsmem
1063 @c malloc_consolidate dup ok
1064 @c _int_memalign dup @acsfd @acsmem
1065 @c arena_get_retry dup @asulock @aculock @acsfd @acsmem
1066 @c _int_memalign dup @acsfd @acsmem
1067 @c mutex_unlock dup @aculock
1068 Using @code{valloc} is like using @code{memalign} and passing the page size
1069 as the value of the second argument. It is implemented like this:
1073 valloc (size_t size)
1075 return memalign (getpagesize (), size);
1079 @ref{Query Memory Parameters} for more information about the memory
1082 The @code{valloc} function is obsolete and @code{aligned_alloc} or
1083 @code{posix_memalign} should be used instead.
1086 @node Malloc Tunable Parameters
1087 @subsubsection Malloc Tunable Parameters
1089 You can adjust some parameters for dynamic memory allocation with the
1090 @code{mallopt} function. This function is the general SVID/XPG
1091 interface, defined in @file{malloc.h}.
1094 @deftypefun int mallopt (int @var{param}, int @var{value})
1095 @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
1096 @c __libc_mallopt @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock
1097 @c ptmalloc_init (once) dup @mtsenv @asulock @aculock @acsfd @acsmem
1098 @c mutex_lock (main_arena->mutex) @asulock @aculock
1099 @c malloc_consolidate dup ok
1101 @c mutex_unlock dup @aculock
1103 When calling @code{mallopt}, the @var{param} argument specifies the
1104 parameter to be set, and @var{value} the new value to be set. Possible
1105 choices for @var{param}, as defined in @file{malloc.h}, are:
1108 @comment TODO: @item M_ARENA_MAX
1109 @comment - Document ARENA_MAX env var.
1110 @comment TODO: @item M_ARENA_TEST
1111 @comment - Document ARENA_TEST env var.
1112 @comment TODO: @item M_CHECK_ACTION
1114 The maximum number of chunks to allocate with @code{mmap}. Setting this
1115 to zero disables all use of @code{mmap}.
1116 @item M_MMAP_THRESHOLD
1117 All chunks larger than this value are allocated outside the normal
1118 heap, using the @code{mmap} system call. This way it is guaranteed
1119 that the memory for these chunks can be returned to the system on
1120 @code{free}. Note that requests smaller than this threshold might still
1121 be allocated via @code{mmap}.
1122 @comment TODO: @item M_MXFAST
1124 If non-zero, memory blocks are filled with values depending on some
1125 low order bits of this parameter when they are allocated (except when
1126 allocated by @code{calloc}) and freed. This can be used to debug the
1127 use of uninitialized or freed heap memory. Note that this option does not
1128 guarantee that the freed block will have any specific values. It only
1129 guarantees that the content the block had before it was freed will be
1132 This parameter determines the amount of extra memory to obtain from the
1133 system when a call to @code{sbrk} is required. It also specifies the
1134 number of bytes to retain when shrinking the heap by calling @code{sbrk}
1135 with a negative argument. This provides the necessary hysteresis in
1136 heap size such that excessive amounts of system calls can be avoided.
1137 @item M_TRIM_THRESHOLD
1138 This is the minimum size (in bytes) of the top-most, releasable chunk
1139 that will cause @code{sbrk} to be called with a negative argument in
1140 order to return memory to the system.
1145 @node Heap Consistency Checking
1146 @subsubsection Heap Consistency Checking
1148 @cindex heap consistency checking
1149 @cindex consistency checking, of heap
1151 You can ask @code{malloc} to check the consistency of dynamic memory by
1152 using the @code{mcheck} function. This function is a GNU extension,
1153 declared in @file{mcheck.h}.
1158 @deftypefun int mcheck (void (*@var{abortfn}) (enum mcheck_status @var{status}))
1159 @safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1160 @c The hooks must be set up before malloc is first used, which sort of
1161 @c implies @mtuinit/@asuinit but since the function is a no-op if malloc
1162 @c was already used, that doesn't pose any safety issues. The actual
1163 @c problem is with the hooks, designed for single-threaded
1164 @c fully-synchronous operation: they manage an unguarded linked list of
1165 @c allocated blocks, and get temporarily overwritten before calling the
1166 @c allocation functions recursively while holding the old hooks. There
1167 @c are no guards for thread safety, and inconsistent hooks may be found
1168 @c within signal handlers or left behind in case of cancellation.
1170 Calling @code{mcheck} tells @code{malloc} to perform occasional
1171 consistency checks. These will catch things such as writing
1172 past the end of a block that was allocated with @code{malloc}.
1174 The @var{abortfn} argument is the function to call when an inconsistency
1175 is found. If you supply a null pointer, then @code{mcheck} uses a
1176 default function which prints a message and calls @code{abort}
1177 (@pxref{Aborting a Program}). The function you supply is called with
1178 one argument, which says what sort of inconsistency was detected; its
1179 type is described below.
1181 It is too late to begin allocation checking once you have allocated
1182 anything with @code{malloc}. So @code{mcheck} does nothing in that
1183 case. The function returns @code{-1} if you call it too late, and
1184 @code{0} otherwise (when it is successful).
1186 The easiest way to arrange to call @code{mcheck} early enough is to use
1187 the option @samp{-lmcheck} when you link your program; then you don't
1188 need to modify your program source at all. Alternatively you might use
1189 a debugger to insert a call to @code{mcheck} whenever the program is
1190 started, for example these gdb commands will automatically call @code{mcheck}
1191 whenever the program starts:
1195 Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10
1197 Type commands for when breakpoint 1 is hit, one per line.
1198 End with a line saying just "end".
1205 This will however only work if no initialization function of any object
1206 involved calls any of the @code{malloc} functions since @code{mcheck}
1207 must be called before the first such function.
1211 @deftypefun {enum mcheck_status} mprobe (void *@var{pointer})
1212 @safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1213 @c The linked list of headers may be modified concurrently by other
1214 @c threads, and it may find a partial update if called from a signal
1215 @c handler. It's mostly read only, so cancelling it might be safe, but
1216 @c it will modify global state that, if cancellation hits at just the
1217 @c right spot, may be left behind inconsistent. This path is only taken
1218 @c if checkhdr finds an inconsistency. If the inconsistency could only
1219 @c occur because of earlier undefined behavior, that wouldn't be an
1220 @c additional safety issue problem, but because of the other concurrency
1221 @c issues in the mcheck hooks, the apparent inconsistency could be the
1222 @c result of mcheck's own internal data race. So, AC-Unsafe it is.
1224 The @code{mprobe} function lets you explicitly check for inconsistencies
1225 in a particular allocated block. You must have already called
1226 @code{mcheck} at the beginning of the program, to do its occasional
1227 checks; calling @code{mprobe} requests an additional consistency check
1228 to be done at the time of the call.
1230 The argument @var{pointer} must be a pointer returned by @code{malloc}
1231 or @code{realloc}. @code{mprobe} returns a value that says what
1232 inconsistency, if any, was found. The values are described below.
1235 @deftp {Data Type} {enum mcheck_status}
1236 This enumerated type describes what kind of inconsistency was detected
1237 in an allocated block, if any. Here are the possible values:
1240 @item MCHECK_DISABLED
1241 @code{mcheck} was not called before the first allocation.
1242 No consistency checking can be done.
1244 No inconsistency detected.
1246 The data immediately before the block was modified.
1247 This commonly happens when an array index or pointer
1248 is decremented too far.
1250 The data immediately after the block was modified.
1251 This commonly happens when an array index or pointer
1252 is incremented too far.
1254 The block was already freed.
1258 Another possibility to check for and guard against bugs in the use of
1259 @code{malloc}, @code{realloc} and @code{free} is to set the environment
1260 variable @code{MALLOC_CHECK_}. When @code{MALLOC_CHECK_} is set, a
1261 special (less efficient) implementation is used which is designed to be
1262 tolerant against simple errors, such as double calls of @code{free} with
1263 the same argument, or overruns of a single byte (off-by-one bugs). Not
1264 all such errors can be protected against, however, and memory leaks can
1265 result. If @code{MALLOC_CHECK_} is set to @code{0}, any detected heap
1266 corruption is silently ignored; if set to @code{1}, a diagnostic is
1267 printed on @code{stderr}; if set to @code{2}, @code{abort} is called
1268 immediately. This can be useful because otherwise a crash may happen
1269 much later, and the true cause for the problem is then very hard to
1272 There is one problem with @code{MALLOC_CHECK_}: in SUID or SGID binaries
1273 it could possibly be exploited since diverging from the normal programs
1274 behavior it now writes something to the standard error descriptor.
1275 Therefore the use of @code{MALLOC_CHECK_} is disabled by default for
1276 SUID and SGID binaries. It can be enabled again by the system
1277 administrator by adding a file @file{/etc/suid-debug} (the content is
1278 not important it could be empty).
1280 So, what's the difference between using @code{MALLOC_CHECK_} and linking
1281 with @samp{-lmcheck}? @code{MALLOC_CHECK_} is orthogonal with respect to
1282 @samp{-lmcheck}. @samp{-lmcheck} has been added for backward
1283 compatibility. Both @code{MALLOC_CHECK_} and @samp{-lmcheck} should
1284 uncover the same bugs - but using @code{MALLOC_CHECK_} you don't need to
1285 recompile your application.
1287 @node Hooks for Malloc
1288 @subsubsection Memory Allocation Hooks
1289 @cindex allocation hooks, for @code{malloc}
1291 @Theglibc{} lets you modify the behavior of @code{malloc},
1292 @code{realloc}, and @code{free} by specifying appropriate hook
1293 functions. You can use these hooks to help you debug programs that use
1294 dynamic memory allocation, for example.
1296 The hook variables are declared in @file{malloc.h}.
1301 @defvar __malloc_hook
1302 The value of this variable is a pointer to the function that
1303 @code{malloc} uses whenever it is called. You should define this
1304 function to look like @code{malloc}; that is, like:
1307 void *@var{function} (size_t @var{size}, const void *@var{caller})
1310 The value of @var{caller} is the return address found on the stack when
1311 the @code{malloc} function was called. This value allows you to trace
1312 the memory consumption of the program.
1317 @defvar __realloc_hook
1318 The value of this variable is a pointer to function that @code{realloc}
1319 uses whenever it is called. You should define this function to look
1320 like @code{realloc}; that is, like:
1323 void *@var{function} (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
1326 The value of @var{caller} is the return address found on the stack when
1327 the @code{realloc} function was called. This value allows you to trace the
1328 memory consumption of the program.
1334 The value of this variable is a pointer to function that @code{free}
1335 uses whenever it is called. You should define this function to look
1336 like @code{free}; that is, like:
1339 void @var{function} (void *@var{ptr}, const void *@var{caller})
1342 The value of @var{caller} is the return address found on the stack when
1343 the @code{free} function was called. This value allows you to trace the
1344 memory consumption of the program.
1349 @defvar __memalign_hook
1350 The value of this variable is a pointer to function that @code{aligned_alloc},
1351 @code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they
1352 are called. You should define this function to look like @code{aligned_alloc};
1356 void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller})
1359 The value of @var{caller} is the return address found on the stack when
1360 the @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} or
1361 @code{valloc} functions are called. This value allows you to trace the
1362 memory consumption of the program.
1365 You must make sure that the function you install as a hook for one of
1366 these functions does not call that function recursively without restoring
1367 the old value of the hook first! Otherwise, your program will get stuck
1368 in an infinite recursion. Before calling the function recursively, one
1369 should make sure to restore all the hooks to their previous value. When
1370 coming back from the recursive call, all the hooks should be resaved
1371 since a hook might modify itself.
1375 @defvar __malloc_initialize_hook
1376 The value of this variable is a pointer to a function that is called
1377 once when the malloc implementation is initialized. This is a weak
1378 variable, so it can be overridden in the application with a definition
1382 void (*@var{__malloc_initialize_hook}) (void) = my_init_hook;
1386 An issue to look out for is the time at which the malloc hook functions
1387 can be safely installed. If the hook functions call the malloc-related
1388 functions recursively, it is necessary that malloc has already properly
1389 initialized itself at the time when @code{__malloc_hook} etc. is
1390 assigned to. On the other hand, if the hook functions provide a
1391 complete malloc implementation of their own, it is vital that the hooks
1392 are assigned to @emph{before} the very first @code{malloc} call has
1393 completed, because otherwise a chunk obtained from the ordinary,
1394 un-hooked malloc may later be handed to @code{__free_hook}, for example.
1396 In both cases, the problem can be solved by setting up the hooks from
1397 within a user-defined function pointed to by
1398 @code{__malloc_initialize_hook}---then the hooks will be set up safely
1401 Here is an example showing how to use @code{__malloc_hook} and
1402 @code{__free_hook} properly. It installs a function that prints out
1403 information every time @code{malloc} or @code{free} is called. We just
1404 assume here that @code{realloc} and @code{memalign} are not used in our
1408 /* Prototypes for __malloc_hook, __free_hook */
1411 /* Prototypes for our hooks. */
1412 static void my_init_hook (void);
1413 static void *my_malloc_hook (size_t, const void *);
1414 static void my_free_hook (void*, const void *);
1416 /* Override initializing hook from the C library. */
1417 void (*__malloc_initialize_hook) (void) = my_init_hook;
1422 old_malloc_hook = __malloc_hook;
1423 old_free_hook = __free_hook;
1424 __malloc_hook = my_malloc_hook;
1425 __free_hook = my_free_hook;
1429 my_malloc_hook (size_t size, const void *caller)
1432 /* Restore all old hooks */
1433 __malloc_hook = old_malloc_hook;
1434 __free_hook = old_free_hook;
1435 /* Call recursively */
1436 result = malloc (size);
1437 /* Save underlying hooks */
1438 old_malloc_hook = __malloc_hook;
1439 old_free_hook = __free_hook;
1440 /* @r{@code{printf} might call @code{malloc}, so protect it too.} */
1441 printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
1442 /* Restore our own hooks */
1443 __malloc_hook = my_malloc_hook;
1444 __free_hook = my_free_hook;
1449 my_free_hook (void *ptr, const void *caller)
1451 /* Restore all old hooks */
1452 __malloc_hook = old_malloc_hook;
1453 __free_hook = old_free_hook;
1454 /* Call recursively */
1456 /* Save underlying hooks */
1457 old_malloc_hook = __malloc_hook;
1458 old_free_hook = __free_hook;
1459 /* @r{@code{printf} might call @code{free}, so protect it too.} */
1460 printf ("freed pointer %p\n", ptr);
1461 /* Restore our own hooks */
1462 __malloc_hook = my_malloc_hook;
1463 __free_hook = my_free_hook;
1472 The @code{mcheck} function (@pxref{Heap Consistency Checking}) works by
1473 installing such hooks.
1475 @c __morecore, __after_morecore_hook are undocumented
1476 @c It's not clear whether to document them.
1478 @node Statistics of Malloc
1479 @subsubsection Statistics for Memory Allocation with @code{malloc}
1481 @cindex allocation statistics
1482 You can get information about dynamic memory allocation by calling the
1483 @code{mallinfo} function. This function and its associated data type
1484 are declared in @file{malloc.h}; they are an extension of the standard
1490 @deftp {Data Type} {struct mallinfo}
1491 This structure type is used to return information about the dynamic
1492 memory allocator. It contains the following members:
1496 This is the total size of memory allocated with @code{sbrk} by
1497 @code{malloc}, in bytes.
1500 This is the number of chunks not in use. (The memory allocator
1501 internally gets chunks of memory from the operating system, and then
1502 carves them up to satisfy individual @code{malloc} requests; see
1503 @ref{Efficiency and Malloc}.)
1506 This field is unused.
1509 This is the total number of chunks allocated with @code{mmap}.
1512 This is the total size of memory allocated with @code{mmap}, in bytes.
1515 This field is unused and always 0.
1518 This field is unused.
1521 This is the total size of memory occupied by chunks handed out by
1525 This is the total size of memory occupied by free (not in use) chunks.
1528 This is the size of the top-most releasable chunk that normally
1529 borders the end of the heap (i.e., the high end of the virtual address
1530 space's data segment).
1537 @deftypefun {struct mallinfo} mallinfo (void)
1538 @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
1539 @c Accessing mp_.n_mmaps and mp_.max_mmapped_mem, modified with atomics
1540 @c but non-atomically elsewhere, may get us inconsistent results. We
1541 @c mark the statistics as unsafe, rather than the fast-path functions
1542 @c that collect the possibly inconsistent data.
1544 @c __libc_mallinfo @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock
1545 @c ptmalloc_init (once) dup @mtsenv @asulock @aculock @acsfd @acsmem
1546 @c mutex_lock dup @asulock @aculock
1547 @c int_mallinfo @mtasuconst:mallopt [mp_ access on main_arena]
1548 @c malloc_consolidate dup ok
1549 @c check_malloc_state dup ok/disabled
1554 @c mutex_unlock @aculock
1556 This function returns information about the current dynamic memory usage
1557 in a structure of type @code{struct mallinfo}.
1560 @node Summary of Malloc
1561 @subsubsection Summary of @code{malloc}-Related Functions
1563 Here is a summary of the functions that work with @code{malloc}:
1566 @item void *malloc (size_t @var{size})
1567 Allocate a block of @var{size} bytes. @xref{Basic Allocation}.
1569 @item void free (void *@var{addr})
1570 Free a block previously allocated by @code{malloc}. @xref{Freeing after
1573 @item void *realloc (void *@var{addr}, size_t @var{size})
1574 Make a block previously allocated by @code{malloc} larger or smaller,
1575 possibly by copying it to a new location. @xref{Changing Block Size}.
1577 @item void *calloc (size_t @var{count}, size_t @var{eltsize})
1578 Allocate a block of @var{count} * @var{eltsize} bytes using
1579 @code{malloc}, and set its contents to zero. @xref{Allocating Cleared
1582 @item void *valloc (size_t @var{size})
1583 Allocate a block of @var{size} bytes, starting on a page boundary.
1584 @xref{Aligned Memory Blocks}.
1586 @item void *aligned_alloc (size_t @var{size}, size_t @var{alignment})
1587 Allocate a block of @var{size} bytes, starting on an address that is a
1588 multiple of @var{alignment}. @xref{Aligned Memory Blocks}.
1590 @item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
1591 Allocate a block of @var{size} bytes, starting on an address that is a
1592 multiple of @var{alignment}. @xref{Aligned Memory Blocks}.
1594 @item void *memalign (size_t @var{size}, size_t @var{boundary})
1595 Allocate a block of @var{size} bytes, starting on an address that is a
1596 multiple of @var{boundary}. @xref{Aligned Memory Blocks}.
1598 @item int mallopt (int @var{param}, int @var{value})
1599 Adjust a tunable parameter. @xref{Malloc Tunable Parameters}.
1601 @item int mcheck (void (*@var{abortfn}) (void))
1602 Tell @code{malloc} to perform occasional consistency checks on
1603 dynamically allocated memory, and to call @var{abortfn} when an
1604 inconsistency is found. @xref{Heap Consistency Checking}.
1606 @item void *(*__malloc_hook) (size_t @var{size}, const void *@var{caller})
1607 A pointer to a function that @code{malloc} uses whenever it is called.
1609 @item void *(*__realloc_hook) (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
1610 A pointer to a function that @code{realloc} uses whenever it is called.
1612 @item void (*__free_hook) (void *@var{ptr}, const void *@var{caller})
1613 A pointer to a function that @code{free} uses whenever it is called.
1615 @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller})
1616 A pointer to a function that @code{aligned_alloc}, @code{memalign},
1617 @code{posix_memalign} and @code{valloc} use whenever they are called.
1619 @item struct mallinfo mallinfo (void)
1620 Return information about the current dynamic memory usage.
1621 @xref{Statistics of Malloc}.
1624 @node Allocation Debugging
1625 @subsection Allocation Debugging
1626 @cindex allocation debugging
1627 @cindex malloc debugger
1629 A complicated task when programming with languages which do not use
1630 garbage collected dynamic memory allocation is to find memory leaks.
1631 Long running programs must assure that dynamically allocated objects are
1632 freed at the end of their lifetime. If this does not happen the system
1633 runs out of memory, sooner or later.
1635 The @code{malloc} implementation in @theglibc{} provides some
1636 simple means to detect such leaks and obtain some information to find
1637 the location. To do this the application must be started in a special
1638 mode which is enabled by an environment variable. There are no speed
1639 penalties for the program if the debugging mode is not enabled.
1642 * Tracing malloc:: How to install the tracing functionality.
1643 * Using the Memory Debugger:: Example programs excerpts.
1644 * Tips for the Memory Debugger:: Some more or less clever ideas.
1645 * Interpreting the traces:: What do all these lines mean?
1648 @node Tracing malloc
1649 @subsubsection How to install the tracing functionality
1653 @deftypefun void mtrace (void)
1654 @safety{@prelim{}@mtunsafe{@mtsenv{} @mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtuinit{}}@asunsafe{@asuinit{} @ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1655 @c Like the mcheck hooks, these are not designed with thread safety in
1656 @c mind, because the hook pointers are temporarily modified without
1657 @c regard to other threads, signals or cancellation.
1659 @c mtrace @mtuinit @mtasurace:mtrace @mtsenv @asuinit @ascuheap @asucorrupt @acuinit @acucorrupt @aculock @acsfd @acsmem
1660 @c __libc_secure_getenv dup @mtsenv
1661 @c malloc dup @ascuheap @acsmem
1662 @c fopen dup @ascuheap @asulock @aculock @acsmem @acsfd
1664 @c setvbuf dup @aculock
1665 @c fprintf dup (on newly-created stream) @aculock
1666 @c __cxa_atexit (once) dup @asulock @aculock @acsmem
1667 @c free dup @ascuheap @acsmem
1668 When the @code{mtrace} function is called it looks for an environment
1669 variable named @code{MALLOC_TRACE}. This variable is supposed to
1670 contain a valid file name. The user must have write access. If the
1671 file already exists it is truncated. If the environment variable is not
1672 set or it does not name a valid file which can be opened for writing
1673 nothing is done. The behavior of @code{malloc} etc. is not changed.
1674 For obvious reasons this also happens if the application is installed
1675 with the SUID or SGID bit set.
1677 If the named file is successfully opened, @code{mtrace} installs special
1678 handlers for the functions @code{malloc}, @code{realloc}, and
1679 @code{free} (@pxref{Hooks for Malloc}). From then on, all uses of these
1680 functions are traced and protocolled into the file. There is now of
1681 course a speed penalty for all calls to the traced functions so tracing
1682 should not be enabled during normal use.
1684 This function is a GNU extension and generally not available on other
1685 systems. The prototype can be found in @file{mcheck.h}.
1690 @deftypefun void muntrace (void)
1691 @safety{@prelim{}@mtunsafe{@mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{} @aculock{} @acsfd{}}}
1693 @c muntrace @mtasurace:mtrace @mtslocale @asucorrupt @ascuheap @acucorrupt @acsmem @aculock @acsfd
1694 @c fprintf (fputs) dup @mtslocale @asucorrupt @ascuheap @acsmem @aculock @acucorrupt
1695 @c fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
1696 The @code{muntrace} function can be called after @code{mtrace} was used
1697 to enable tracing the @code{malloc} calls. If no (successful) call of
1698 @code{mtrace} was made @code{muntrace} does nothing.
1700 Otherwise it deinstalls the handlers for @code{malloc}, @code{realloc},
1701 and @code{free} and then closes the protocol file. No calls are
1702 protocolled anymore and the program runs again at full speed.
1704 This function is a GNU extension and generally not available on other
1705 systems. The prototype can be found in @file{mcheck.h}.
1708 @node Using the Memory Debugger
1709 @subsubsection Example program excerpts
1711 Even though the tracing functionality does not influence the runtime
1712 behavior of the program it is not a good idea to call @code{mtrace} in
1713 all programs. Just imagine that you debug a program using @code{mtrace}
1714 and all other programs used in the debugging session also trace their
1715 @code{malloc} calls. The output file would be the same for all programs
1716 and thus is unusable. Therefore one should call @code{mtrace} only if
1717 compiled for debugging. A program could therefore start like this:
1723 main (int argc, char *argv[])
1732 This is all what is needed if you want to trace the calls during the
1733 whole runtime of the program. Alternatively you can stop the tracing at
1734 any time with a call to @code{muntrace}. It is even possible to restart
1735 the tracing again with a new call to @code{mtrace}. But this can cause
1736 unreliable results since there may be calls of the functions which are
1737 not called. Please note that not only the application uses the traced
1738 functions, also libraries (including the C library itself) use these
1741 This last point is also why it is no good idea to call @code{muntrace}
1742 before the program terminated. The libraries are informed about the
1743 termination of the program only after the program returns from
1744 @code{main} or calls @code{exit} and so cannot free the memory they use
1747 So the best thing one can do is to call @code{mtrace} as the very first
1748 function in the program and never call @code{muntrace}. So the program
1749 traces almost all uses of the @code{malloc} functions (except those
1750 calls which are executed by constructors of the program or used
1753 @node Tips for the Memory Debugger
1754 @subsubsection Some more or less clever ideas
1756 You know the situation. The program is prepared for debugging and in
1757 all debugging sessions it runs well. But once it is started without
1758 debugging the error shows up. A typical example is a memory leak that
1759 becomes visible only when we turn off the debugging. If you foresee
1760 such situations you can still win. Simply use something equivalent to
1761 the following little program:
1771 signal (SIGUSR1, enable);
1778 signal (SIGUSR2, disable);
1782 main (int argc, char *argv[])
1786 signal (SIGUSR1, enable);
1787 signal (SIGUSR2, disable);
1793 I.e., the user can start the memory debugger any time s/he wants if the
1794 program was started with @code{MALLOC_TRACE} set in the environment.
1795 The output will of course not show the allocations which happened before
1796 the first signal but if there is a memory leak this will show up
1799 @node Interpreting the traces
1800 @subsubsection Interpreting the traces
1802 If you take a look at the output it will look similar to this:
1806 @ [0x8048209] - 0x8064cc8
1807 @ [0x8048209] - 0x8064ce0
1808 @ [0x8048209] - 0x8064cf8
1809 @ [0x80481eb] + 0x8064c48 0x14
1810 @ [0x80481eb] + 0x8064c60 0x14
1811 @ [0x80481eb] + 0x8064c78 0x14
1812 @ [0x80481eb] + 0x8064c90 0x14
1816 What this all means is not really important since the trace file is not
1817 meant to be read by a human. Therefore no attention is given to
1818 readability. Instead there is a program which comes with @theglibc{}
1819 which interprets the traces and outputs a summary in an
1820 user-friendly way. The program is called @code{mtrace} (it is in fact a
1821 Perl script) and it takes one or two arguments. In any case the name of
1822 the file with the trace output must be specified. If an optional
1823 argument precedes the name of the trace file this must be the name of
1824 the program which generated the trace.
1827 drepper$ mtrace tst-mtrace log
1831 In this case the program @code{tst-mtrace} was run and it produced a
1832 trace file @file{log}. The message printed by @code{mtrace} shows there
1833 are no problems with the code, all allocated memory was freed
1836 If we call @code{mtrace} on the example trace given above we would get a
1840 drepper$ mtrace errlog
1841 - 0x08064cc8 Free 2 was never alloc'd 0x8048209
1842 - 0x08064ce0 Free 3 was never alloc'd 0x8048209
1843 - 0x08064cf8 Free 4 was never alloc'd 0x8048209
1848 0x08064c48 0x14 at 0x80481eb
1849 0x08064c60 0x14 at 0x80481eb
1850 0x08064c78 0x14 at 0x80481eb
1851 0x08064c90 0x14 at 0x80481eb
1854 We have called @code{mtrace} with only one argument and so the script
1855 has no chance to find out what is meant with the addresses given in the
1856 trace. We can do better:
1859 drepper$ mtrace tst errlog
1860 - 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
1861 - 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
1862 - 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39
1867 0x08064c48 0x14 at /home/drepper/tst.c:33
1868 0x08064c60 0x14 at /home/drepper/tst.c:33
1869 0x08064c78 0x14 at /home/drepper/tst.c:33
1870 0x08064c90 0x14 at /home/drepper/tst.c:33
1873 Suddenly the output makes much more sense and the user can see
1874 immediately where the function calls causing the trouble can be found.
1876 Interpreting this output is not complicated. There are at most two
1877 different situations being detected. First, @code{free} was called for
1878 pointers which were never returned by one of the allocation functions.
1879 This is usually a very bad problem and what this looks like is shown in
1880 the first three lines of the output. Situations like this are quite
1881 rare and if they appear they show up very drastically: the program
1884 The other situation which is much harder to detect are memory leaks. As
1885 you can see in the output the @code{mtrace} function collects all this
1886 information and so can say that the program calls an allocation function
1887 from line 33 in the source file @file{/home/drepper/tst-mtrace.c} four
1888 times without freeing this memory before the program terminates.
1889 Whether this is a real problem remains to be investigated.
1892 @subsection Obstacks
1895 An @dfn{obstack} is a pool of memory containing a stack of objects. You
1896 can create any number of separate obstacks, and then allocate objects in
1897 specified obstacks. Within each obstack, the last object allocated must
1898 always be the first one freed, but distinct obstacks are independent of
1901 Aside from this one constraint of order of freeing, obstacks are totally
1902 general: an obstack can contain any number of objects of any size. They
1903 are implemented with macros, so allocation is usually very fast as long as
1904 the objects are usually small. And the only space overhead per object is
1905 the padding needed to start each object on a suitable boundary.
1908 * Creating Obstacks:: How to declare an obstack in your program.
1909 * Preparing for Obstacks:: Preparations needed before you can
1911 * Allocation in an Obstack:: Allocating objects in an obstack.
1912 * Freeing Obstack Objects:: Freeing objects in an obstack.
1913 * Obstack Functions:: The obstack functions are both
1914 functions and macros.
1915 * Growing Objects:: Making an object bigger by stages.
1916 * Extra Fast Growing:: Extra-high-efficiency (though more
1917 complicated) growing objects.
1918 * Status of an Obstack:: Inquiries about the status of an obstack.
1919 * Obstacks Data Alignment:: Controlling alignment of objects in obstacks.
1920 * Obstack Chunks:: How obstacks obtain and release chunks;
1921 efficiency considerations.
1922 * Summary of Obstacks::
1925 @node Creating Obstacks
1926 @subsubsection Creating Obstacks
1928 The utilities for manipulating obstacks are declared in the header
1929 file @file{obstack.h}.
1934 @deftp {Data Type} {struct obstack}
1935 An obstack is represented by a data structure of type @code{struct
1936 obstack}. This structure has a small fixed size; it records the status
1937 of the obstack and how to find the space in which objects are allocated.
1938 It does not contain any of the objects themselves. You should not try
1939 to access the contents of the structure directly; use only the functions
1940 described in this chapter.
1943 You can declare variables of type @code{struct obstack} and use them as
1944 obstacks, or you can allocate obstacks dynamically like any other kind
1945 of object. Dynamic allocation of obstacks allows your program to have a
1946 variable number of different stacks. (You can even allocate an
1947 obstack structure in another obstack, but this is rarely useful.)
1949 All the functions that work with obstacks require you to specify which
1950 obstack to use. You do this with a pointer of type @code{struct obstack
1951 *}. In the following, we often say ``an obstack'' when strictly
1952 speaking the object at hand is such a pointer.
1954 The objects in the obstack are packed into large blocks called
1955 @dfn{chunks}. The @code{struct obstack} structure points to a chain of
1956 the chunks currently in use.
1958 The obstack library obtains a new chunk whenever you allocate an object
1959 that won't fit in the previous chunk. Since the obstack library manages
1960 chunks automatically, you don't need to pay much attention to them, but
1961 you do need to supply a function which the obstack library should use to
1962 get a chunk. Usually you supply a function which uses @code{malloc}
1963 directly or indirectly. You must also supply a function to free a chunk.
1964 These matters are described in the following section.
1966 @node Preparing for Obstacks
1967 @subsubsection Preparing for Using Obstacks
1969 Each source file in which you plan to use the obstack functions
1970 must include the header file @file{obstack.h}, like this:
1973 #include <obstack.h>
1976 @findex obstack_chunk_alloc
1977 @findex obstack_chunk_free
1978 Also, if the source file uses the macro @code{obstack_init}, it must
1979 declare or define two functions or macros that will be called by the
1980 obstack library. One, @code{obstack_chunk_alloc}, is used to allocate
1981 the chunks of memory into which objects are packed. The other,
1982 @code{obstack_chunk_free}, is used to return chunks when the objects in
1983 them are freed. These macros should appear before any use of obstacks
1986 Usually these are defined to use @code{malloc} via the intermediary
1987 @code{xmalloc} (@pxref{Unconstrained Allocation}). This is done with
1988 the following pair of macro definitions:
1991 #define obstack_chunk_alloc xmalloc
1992 #define obstack_chunk_free free
1996 Though the memory you get using obstacks really comes from @code{malloc},
1997 using obstacks is faster because @code{malloc} is called less often, for
1998 larger blocks of memory. @xref{Obstack Chunks}, for full details.
2000 At run time, before the program can use a @code{struct obstack} object
2001 as an obstack, it must initialize the obstack by calling
2002 @code{obstack_init}.
2006 @deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
2007 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{@acsmem{}}}
2008 @c obstack_init @mtsrace:obstack-ptr @acsmem
2009 @c _obstack_begin @acsmem
2010 @c chunkfun = obstack_chunk_alloc (suggested malloc)
2011 @c freefun = obstack_chunk_free (suggested free)
2012 @c *chunkfun @acsmem
2013 @c obstack_chunk_alloc user-supplied
2014 @c *obstack_alloc_failed_handler user-supplied
2015 @c -> print_and_abort (default)
2019 @c fxprintf dup @asucorrupt @aculock @acucorrupt
2020 @c exit @acucorrupt?
2021 Initialize obstack @var{obstack-ptr} for allocation of objects. This
2022 function calls the obstack's @code{obstack_chunk_alloc} function. If
2023 allocation of memory fails, the function pointed to by
2024 @code{obstack_alloc_failed_handler} is called. The @code{obstack_init}
2025 function always returns 1 (Compatibility notice: Former versions of
2026 obstack returned 0 if allocation failed).
2029 Here are two examples of how to allocate the space for an obstack and
2030 initialize it. First, an obstack that is a static variable:
2033 static struct obstack myobstack;
2035 obstack_init (&myobstack);
2039 Second, an obstack that is itself dynamically allocated:
2042 struct obstack *myobstack_ptr
2043 = (struct obstack *) xmalloc (sizeof (struct obstack));
2045 obstack_init (myobstack_ptr);
2050 @defvar obstack_alloc_failed_handler
2051 The value of this variable is a pointer to a function that
2052 @code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
2053 memory. The default action is to print a message and abort.
2054 You should supply a function that either calls @code{exit}
2055 (@pxref{Program Termination}) or @code{longjmp} (@pxref{Non-Local
2056 Exits}) and doesn't return.
2059 void my_obstack_alloc_failed (void)
2061 obstack_alloc_failed_handler = &my_obstack_alloc_failed;
2066 @node Allocation in an Obstack
2067 @subsubsection Allocation in an Obstack
2068 @cindex allocation (obstacks)
2070 The most direct way to allocate an object in an obstack is with
2071 @code{obstack_alloc}, which is invoked almost like @code{malloc}.
2075 @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
2076 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2077 @c obstack_alloc @mtsrace:obstack-ptr @acucorrupt @acsmem
2078 @c obstack_blank dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2079 @c obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2080 This allocates an uninitialized block of @var{size} bytes in an obstack
2081 and returns its address. Here @var{obstack-ptr} specifies which obstack
2082 to allocate the block in; it is the address of the @code{struct obstack}
2083 object which represents the obstack. Each obstack function or macro
2084 requires you to specify an @var{obstack-ptr} as the first argument.
2086 This function calls the obstack's @code{obstack_chunk_alloc} function if
2087 it needs to allocate a new chunk of memory; it calls
2088 @code{obstack_alloc_failed_handler} if allocation of memory by
2089 @code{obstack_chunk_alloc} failed.
2092 For example, here is a function that allocates a copy of a string @var{str}
2093 in a specific obstack, which is in the variable @code{string_obstack}:
2096 struct obstack string_obstack;
2099 copystring (char *string)
2101 size_t len = strlen (string) + 1;
2102 char *s = (char *) obstack_alloc (&string_obstack, len);
2103 memcpy (s, string, len);
2108 To allocate a block with specified contents, use the function
2109 @code{obstack_copy}, declared like this:
2113 @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2114 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2115 @c obstack_copy @mtsrace:obstack-ptr @acucorrupt @acsmem
2116 @c obstack_grow dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2117 @c obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2118 This allocates a block and initializes it by copying @var{size}
2119 bytes of data starting at @var{address}. It calls
2120 @code{obstack_alloc_failed_handler} if allocation of memory by
2121 @code{obstack_chunk_alloc} failed.
2126 @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2127 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2128 @c obstack_copy0 @mtsrace:obstack-ptr @acucorrupt @acsmem
2129 @c obstack_grow0 dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2130 @c obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2131 Like @code{obstack_copy}, but appends an extra byte containing a null
2132 character. This extra byte is not counted in the argument @var{size}.
2135 The @code{obstack_copy0} function is convenient for copying a sequence
2136 of characters into an obstack as a null-terminated string. Here is an
2141 obstack_savestring (char *addr, int size)
2143 return obstack_copy0 (&myobstack, addr, size);
2148 Contrast this with the previous example of @code{savestring} using
2149 @code{malloc} (@pxref{Basic Allocation}).
2151 @node Freeing Obstack Objects
2152 @subsubsection Freeing Objects in an Obstack
2153 @cindex freeing (obstacks)
2155 To free an object allocated in an obstack, use the function
2156 @code{obstack_free}. Since the obstack is a stack of objects, freeing
2157 one object automatically frees all other objects allocated more recently
2158 in the same obstack.
2162 @deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
2163 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
2164 @c obstack_free @mtsrace:obstack-ptr @acucorrupt
2165 @c (obstack_free) @mtsrace:obstack-ptr @acucorrupt
2166 @c *freefun dup user-supplied
2167 If @var{object} is a null pointer, everything allocated in the obstack
2168 is freed. Otherwise, @var{object} must be the address of an object
2169 allocated in the obstack. Then @var{object} is freed, along with
2170 everything allocated in @var{obstack} since @var{object}.
2173 Note that if @var{object} is a null pointer, the result is an
2174 uninitialized obstack. To free all memory in an obstack but leave it
2175 valid for further allocation, call @code{obstack_free} with the address
2176 of the first object allocated on the obstack:
2179 obstack_free (obstack_ptr, first_object_allocated_ptr);
2182 Recall that the objects in an obstack are grouped into chunks. When all
2183 the objects in a chunk become free, the obstack library automatically
2184 frees the chunk (@pxref{Preparing for Obstacks}). Then other
2185 obstacks, or non-obstack allocation, can reuse the space of the chunk.
2187 @node Obstack Functions
2188 @subsubsection Obstack Functions and Macros
2191 The interfaces for using obstacks may be defined either as functions or
2192 as macros, depending on the compiler. The obstack facility works with
2193 all C compilers, including both @w{ISO C} and traditional C, but there are
2194 precautions you must take if you plan to use compilers other than GNU C.
2196 If you are using an old-fashioned @w{non-ISO C} compiler, all the obstack
2197 ``functions'' are actually defined only as macros. You can call these
2198 macros like functions, but you cannot use them in any other way (for
2199 example, you cannot take their address).
2201 Calling the macros requires a special precaution: namely, the first
2202 operand (the obstack pointer) may not contain any side effects, because
2203 it may be computed more than once. For example, if you write this:
2206 obstack_alloc (get_obstack (), 4);
2210 you will find that @code{get_obstack} may be called several times.
2211 If you use @code{*obstack_list_ptr++} as the obstack pointer argument,
2212 you will get very strange results since the incrementation may occur
2215 In @w{ISO C}, each function has both a macro definition and a function
2216 definition. The function definition is used if you take the address of the
2217 function without calling it. An ordinary call uses the macro definition by
2218 default, but you can request the function definition instead by writing the
2219 function name in parentheses, as shown here:
2224 /* @r{Use the macro}. */
2225 x = (char *) obstack_alloc (obptr, size);
2226 /* @r{Call the function}. */
2227 x = (char *) (obstack_alloc) (obptr, size);
2228 /* @r{Take the address of the function}. */
2229 funcp = obstack_alloc;
2233 This is the same situation that exists in @w{ISO C} for the standard library
2234 functions. @xref{Macro Definitions}.
2236 @strong{Warning:} When you do use the macros, you must observe the
2237 precaution of avoiding side effects in the first operand, even in @w{ISO C}.
2239 If you use the GNU C compiler, this precaution is not necessary, because
2240 various language extensions in GNU C permit defining the macros so as to
2241 compute each argument only once.
2243 @node Growing Objects
2244 @subsubsection Growing Objects
2245 @cindex growing objects (in obstacks)
2246 @cindex changing the size of a block (obstacks)
2248 Because memory in obstack chunks is used sequentially, it is possible to
2249 build up an object step by step, adding one or more bytes at a time to the
2250 end of the object. With this technique, you do not need to know how much
2251 data you will put in the object until you come to the end of it. We call
2252 this the technique of @dfn{growing objects}. The special functions
2253 for adding data to the growing object are described in this section.
2255 You don't need to do anything special when you start to grow an object.
2256 Using one of the functions to add data to the object automatically
2257 starts it. However, it is necessary to say explicitly when the object is
2258 finished. This is done with the function @code{obstack_finish}.
2260 The actual address of the object thus built up is not known until the
2261 object is finished. Until then, it always remains possible that you will
2262 add so much data that the object must be copied into a new chunk.
2264 While the obstack is in use for a growing object, you cannot use it for
2265 ordinary allocation of another object. If you try to do so, the space
2266 already added to the growing object will become part of the other object.
2270 @deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
2271 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2272 @c obstack_blank @mtsrace:obstack-ptr @acucorrupt @acsmem
2273 @c _obstack_newchunk @mtsrace:obstack-ptr @acucorrupt @acsmem
2274 @c *chunkfun dup @acsmem
2275 @c *obstack_alloc_failed_handler dup user-supplied
2277 @c obstack_blank_fast dup @mtsrace:obstack-ptr
2278 The most basic function for adding to a growing object is
2279 @code{obstack_blank}, which adds space without initializing it.
2284 @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
2285 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2286 @c obstack_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2287 @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2289 To add a block of initialized space, use @code{obstack_grow}, which is
2290 the growing-object analogue of @code{obstack_copy}. It adds @var{size}
2291 bytes of data to the growing object, copying the contents from
2297 @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
2298 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2299 @c obstack_grow0 @mtsrace:obstack-ptr @acucorrupt @acsmem
2300 @c (no sequence point between storing NUL and incrementing next_free)
2301 @c (multiple changes to next_free => @acucorrupt)
2302 @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2304 This is the growing-object analogue of @code{obstack_copy0}. It adds
2305 @var{size} bytes copied from @var{data}, followed by an additional null
2311 @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
2312 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2313 @c obstack_1grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2314 @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2315 @c obstack_1grow_fast dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2316 To add one character at a time, use the function @code{obstack_1grow}.
2317 It adds a single byte containing @var{c} to the growing object.
2322 @deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
2323 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2324 @c obstack_ptr_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2325 @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2326 @c obstack_ptr_grow_fast dup @mtsrace:obstack-ptr
2327 Adding the value of a pointer one can use the function
2328 @code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes
2329 containing the value of @var{data}.
2334 @deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
2335 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2336 @c obstack_int_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2337 @c _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2338 @c obstack_int_grow_fast dup @mtsrace:obstack-ptr
2339 A single value of type @code{int} can be added by using the
2340 @code{obstack_int_grow} function. It adds @code{sizeof (int)} bytes to
2341 the growing object and initializes them with the value of @var{data}.
2346 @deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
2347 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
2348 @c obstack_finish @mtsrace:obstack-ptr @acucorrupt
2349 When you are finished growing the object, use the function
2350 @code{obstack_finish} to close it off and return its final address.
2352 Once you have finished the object, the obstack is available for ordinary
2353 allocation or for growing another object.
2355 This function can return a null pointer under the same conditions as
2356 @code{obstack_alloc} (@pxref{Allocation in an Obstack}).
2359 When you build an object by growing it, you will probably need to know
2360 afterward how long it became. You need not keep track of this as you grow
2361 the object, because you can find out the length from the obstack just
2362 before finishing the object with the function @code{obstack_object_size},
2363 declared as follows:
2367 @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
2368 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2369 This function returns the current size of the growing object, in bytes.
2370 Remember to call this function @emph{before} finishing the object.
2371 After it is finished, @code{obstack_object_size} will return zero.
2374 If you have started growing an object and wish to cancel it, you should
2375 finish it and then free it, like this:
2378 obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
2382 This has no effect if no object was growing.
2384 @cindex shrinking objects
2385 You can use @code{obstack_blank} with a negative size argument to make
2386 the current object smaller. Just don't try to shrink it beyond zero
2387 length---there's no telling what will happen if you do that.
2389 @node Extra Fast Growing
2390 @subsubsection Extra Fast Growing Objects
2391 @cindex efficiency and obstacks
2393 The usual functions for growing objects incur overhead for checking
2394 whether there is room for the new growth in the current chunk. If you
2395 are frequently constructing objects in small steps of growth, this
2396 overhead can be significant.
2398 You can reduce the overhead by using special ``fast growth''
2399 functions that grow the object without checking. In order to have a
2400 robust program, you must do the checking yourself. If you do this checking
2401 in the simplest way each time you are about to add data to the object, you
2402 have not saved anything, because that is what the ordinary growth
2403 functions do. But if you can arrange to check less often, or check
2404 more efficiently, then you make the program faster.
2406 The function @code{obstack_room} returns the amount of room available
2407 in the current chunk. It is declared as follows:
2411 @deftypefun int obstack_room (struct obstack *@var{obstack-ptr})
2412 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2413 This returns the number of bytes that can be added safely to the current
2414 growing object (or to an object about to be started) in obstack
2415 @var{obstack} using the fast growth functions.
2418 While you know there is room, you can use these fast growth functions
2419 for adding data to a growing object:
2423 @deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
2424 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2425 @c obstack_1grow_fast @mtsrace:obstack-ptr @acucorrupt @acsmem
2426 @c (no sequence point between copying c and incrementing next_free)
2427 The function @code{obstack_1grow_fast} adds one byte containing the
2428 character @var{c} to the growing object in obstack @var{obstack-ptr}.
2433 @deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
2434 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2435 @c obstack_ptr_grow_fast @mtsrace:obstack-ptr
2436 The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
2437 bytes containing the value of @var{data} to the growing object in
2438 obstack @var{obstack-ptr}.
2443 @deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
2444 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2445 @c obstack_int_grow_fast @mtsrace:obstack-ptr
2446 The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
2447 containing the value of @var{data} to the growing object in obstack
2453 @deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
2454 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2455 @c obstack_blank_fast @mtsrace:obstack-ptr
2456 The function @code{obstack_blank_fast} adds @var{size} bytes to the
2457 growing object in obstack @var{obstack-ptr} without initializing them.
2460 When you check for space using @code{obstack_room} and there is not
2461 enough room for what you want to add, the fast growth functions
2462 are not safe. In this case, simply use the corresponding ordinary
2463 growth function instead. Very soon this will copy the object to a
2464 new chunk; then there will be lots of room available again.
2466 So, each time you use an ordinary growth function, check afterward for
2467 sufficient space using @code{obstack_room}. Once the object is copied
2468 to a new chunk, there will be plenty of space again, so the program will
2469 start using the fast growth functions again.
2476 add_string (struct obstack *obstack, const char *ptr, int len)
2480 int room = obstack_room (obstack);
2483 /* @r{Not enough room. Add one character slowly,}
2484 @r{which may copy to a new chunk and make room.} */
2485 obstack_1grow (obstack, *ptr++);
2492 /* @r{Add fast as much as we have room for.} */
2495 obstack_1grow_fast (obstack, *ptr++);
2502 @node Status of an Obstack
2503 @subsubsection Status of an Obstack
2504 @cindex obstack status
2505 @cindex status of obstack
2507 Here are functions that provide information on the current status of
2508 allocation in an obstack. You can use them to learn about an object while
2513 @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
2514 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
2515 This function returns the tentative address of the beginning of the
2516 currently growing object in @var{obstack-ptr}. If you finish the object
2517 immediately, it will have that address. If you make it larger first, it
2518 may outgrow the current chunk---then its address will change!
2520 If no object is growing, this value says where the next object you
2521 allocate will start (once again assuming it fits in the current
2527 @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
2528 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
2529 This function returns the address of the first free byte in the current
2530 chunk of obstack @var{obstack-ptr}. This is the end of the currently
2531 growing object. If no object is growing, @code{obstack_next_free}
2532 returns the same value as @code{obstack_base}.
2537 @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
2539 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2540 This function returns the size in bytes of the currently growing object.
2541 This is equivalent to
2544 obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})
2548 @node Obstacks Data Alignment
2549 @subsubsection Alignment of Data in Obstacks
2550 @cindex alignment (in obstacks)
2552 Each obstack has an @dfn{alignment boundary}; each object allocated in
2553 the obstack automatically starts on an address that is a multiple of the
2554 specified boundary. By default, this boundary is aligned so that
2555 the object can hold any type of data.
2557 To access an obstack's alignment boundary, use the macro
2558 @code{obstack_alignment_mask}, whose function prototype looks like
2563 @deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
2564 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2565 The value is a bit mask; a bit that is 1 indicates that the corresponding
2566 bit in the address of an object should be 0. The mask value should be one
2567 less than a power of 2; the effect is that all object addresses are
2568 multiples of that power of 2. The default value of the mask is a value
2569 that allows aligned objects to hold any type of data: for example, if
2570 its value is 3, any type of data can be stored at locations whose
2571 addresses are multiples of 4. A mask value of 0 means an object can start
2572 on any multiple of 1 (that is, no alignment is required).
2574 The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
2575 so you can alter the mask by assignment. For example, this statement:
2578 obstack_alignment_mask (obstack_ptr) = 0;
2582 has the effect of turning off alignment processing in the specified obstack.
2585 Note that a change in alignment mask does not take effect until
2586 @emph{after} the next time an object is allocated or finished in the
2587 obstack. If you are not growing an object, you can make the new
2588 alignment mask take effect immediately by calling @code{obstack_finish}.
2589 This will finish a zero-length object and then do proper alignment for
2592 @node Obstack Chunks
2593 @subsubsection Obstack Chunks
2594 @cindex efficiency of chunks
2597 Obstacks work by allocating space for themselves in large chunks, and
2598 then parceling out space in the chunks to satisfy your requests. Chunks
2599 are normally 4096 bytes long unless you specify a different chunk size.
2600 The chunk size includes 8 bytes of overhead that are not actually used
2601 for storing objects. Regardless of the specified size, longer chunks
2602 will be allocated when necessary for long objects.
2604 The obstack library allocates chunks by calling the function
2605 @code{obstack_chunk_alloc}, which you must define. When a chunk is no
2606 longer needed because you have freed all the objects in it, the obstack
2607 library frees the chunk by calling @code{obstack_chunk_free}, which you
2610 These two must be defined (as macros) or declared (as functions) in each
2611 source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
2612 Most often they are defined as macros like this:
2615 #define obstack_chunk_alloc malloc
2616 #define obstack_chunk_free free
2619 Note that these are simple macros (no arguments). Macro definitions with
2620 arguments will not work! It is necessary that @code{obstack_chunk_alloc}
2621 or @code{obstack_chunk_free}, alone, expand into a function name if it is
2622 not itself a function name.
2624 If you allocate chunks with @code{malloc}, the chunk size should be a
2625 power of 2. The default chunk size, 4096, was chosen because it is long
2626 enough to satisfy many typical requests on the obstack yet short enough
2627 not to waste too much memory in the portion of the last chunk not yet used.
2631 @deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr})
2632 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2633 This returns the chunk size of the given obstack.
2636 Since this macro expands to an lvalue, you can specify a new chunk size by
2637 assigning it a new value. Doing so does not affect the chunks already
2638 allocated, but will change the size of chunks allocated for that particular
2639 obstack in the future. It is unlikely to be useful to make the chunk size
2640 smaller, but making it larger might improve efficiency if you are
2641 allocating many objects whose size is comparable to the chunk size. Here
2642 is how to do so cleanly:
2645 if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
2646 obstack_chunk_size (obstack_ptr) = @var{new-chunk-size};
2649 @node Summary of Obstacks
2650 @subsubsection Summary of Obstack Functions
2652 Here is a summary of all the functions associated with obstacks. Each
2653 takes the address of an obstack (@code{struct obstack *}) as its first
2657 @item void obstack_init (struct obstack *@var{obstack-ptr})
2658 Initialize use of an obstack. @xref{Creating Obstacks}.
2660 @item void *obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
2661 Allocate an object of @var{size} uninitialized bytes.
2662 @xref{Allocation in an Obstack}.
2664 @item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2665 Allocate an object of @var{size} bytes, with contents copied from
2666 @var{address}. @xref{Allocation in an Obstack}.
2668 @item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2669 Allocate an object of @var{size}+1 bytes, with @var{size} of them copied
2670 from @var{address}, followed by a null character at the end.
2671 @xref{Allocation in an Obstack}.
2673 @item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
2674 Free @var{object} (and everything allocated in the specified obstack
2675 more recently than @var{object}). @xref{Freeing Obstack Objects}.
2677 @item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
2678 Add @var{size} uninitialized bytes to a growing object.
2679 @xref{Growing Objects}.
2681 @item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2682 Add @var{size} bytes, copied from @var{address}, to a growing object.
2683 @xref{Growing Objects}.
2685 @item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2686 Add @var{size} bytes, copied from @var{address}, to a growing object,
2687 and then add another byte containing a null character. @xref{Growing
2690 @item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
2691 Add one byte containing @var{data-char} to a growing object.
2692 @xref{Growing Objects}.
2694 @item void *obstack_finish (struct obstack *@var{obstack-ptr})
2695 Finalize the object that is growing and return its permanent address.
2696 @xref{Growing Objects}.
2698 @item int obstack_object_size (struct obstack *@var{obstack-ptr})
2699 Get the current size of the currently growing object. @xref{Growing
2702 @item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
2703 Add @var{size} uninitialized bytes to a growing object without checking
2704 that there is enough room. @xref{Extra Fast Growing}.
2706 @item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
2707 Add one byte containing @var{data-char} to a growing object without
2708 checking that there is enough room. @xref{Extra Fast Growing}.
2710 @item int obstack_room (struct obstack *@var{obstack-ptr})
2711 Get the amount of room now available for growing the current object.
2712 @xref{Extra Fast Growing}.
2714 @item int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
2715 The mask used for aligning the beginning of an object. This is an
2716 lvalue. @xref{Obstacks Data Alignment}.
2718 @item int obstack_chunk_size (struct obstack *@var{obstack-ptr})
2719 The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}.
2721 @item void *obstack_base (struct obstack *@var{obstack-ptr})
2722 Tentative starting address of the currently growing object.
2723 @xref{Status of an Obstack}.
2725 @item void *obstack_next_free (struct obstack *@var{obstack-ptr})
2726 Address just after the end of the currently growing object.
2727 @xref{Status of an Obstack}.
2730 @node Variable Size Automatic
2731 @subsection Automatic Storage with Variable Size
2732 @cindex automatic freeing
2733 @cindex @code{alloca} function
2734 @cindex automatic storage with variable size
2736 The function @code{alloca} supports a kind of half-dynamic allocation in
2737 which blocks are allocated dynamically but freed automatically.
2739 Allocating a block with @code{alloca} is an explicit action; you can
2740 allocate as many blocks as you wish, and compute the size at run time. But
2741 all the blocks are freed when you exit the function that @code{alloca} was
2742 called from, just as if they were automatic variables declared in that
2743 function. There is no way to free the space explicitly.
2745 The prototype for @code{alloca} is in @file{stdlib.h}. This function is
2751 @deftypefun {void *} alloca (size_t @var{size})
2752 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2753 The return value of @code{alloca} is the address of a block of @var{size}
2754 bytes of memory, allocated in the stack frame of the calling function.
2757 Do not use @code{alloca} inside the arguments of a function call---you
2758 will get unpredictable results, because the stack space for the
2759 @code{alloca} would appear on the stack in the middle of the space for
2760 the function arguments. An example of what to avoid is @code{foo (x,
2762 @c This might get fixed in future versions of GCC, but that won't make
2763 @c it safe with compilers generally.
2766 * Alloca Example:: Example of using @code{alloca}.
2767 * Advantages of Alloca:: Reasons to use @code{alloca}.
2768 * Disadvantages of Alloca:: Reasons to avoid @code{alloca}.
2769 * GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative
2770 method of allocating dynamically and
2771 freeing automatically.
2774 @node Alloca Example
2775 @subsubsection @code{alloca} Example
2777 As an example of the use of @code{alloca}, here is a function that opens
2778 a file name made from concatenating two argument strings, and returns a
2779 file descriptor or minus one signifying failure:
2783 open2 (char *str1, char *str2, int flags, int mode)
2785 char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
2786 stpcpy (stpcpy (name, str1), str2);
2787 return open (name, flags, mode);
2792 Here is how you would get the same results with @code{malloc} and
2797 open2 (char *str1, char *str2, int flags, int mode)
2799 char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
2802 fatal ("virtual memory exceeded");
2803 stpcpy (stpcpy (name, str1), str2);
2804 desc = open (name, flags, mode);
2810 As you can see, it is simpler with @code{alloca}. But @code{alloca} has
2811 other, more important advantages, and some disadvantages.
2813 @node Advantages of Alloca
2814 @subsubsection Advantages of @code{alloca}
2816 Here are the reasons why @code{alloca} may be preferable to @code{malloc}:
2820 Using @code{alloca} wastes very little space and is very fast. (It is
2821 open-coded by the GNU C compiler.)
2824 Since @code{alloca} does not have separate pools for different sizes of
2825 block, space used for any size block can be reused for any other size.
2826 @code{alloca} does not cause memory fragmentation.
2830 Nonlocal exits done with @code{longjmp} (@pxref{Non-Local Exits})
2831 automatically free the space allocated with @code{alloca} when they exit
2832 through the function that called @code{alloca}. This is the most
2833 important reason to use @code{alloca}.
2835 To illustrate this, suppose you have a function
2836 @code{open_or_report_error} which returns a descriptor, like
2837 @code{open}, if it succeeds, but does not return to its caller if it
2838 fails. If the file cannot be opened, it prints an error message and
2839 jumps out to the command level of your program using @code{longjmp}.
2840 Let's change @code{open2} (@pxref{Alloca Example}) to use this
2845 open2 (char *str1, char *str2, int flags, int mode)
2847 char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
2848 stpcpy (stpcpy (name, str1), str2);
2849 return open_or_report_error (name, flags, mode);
2854 Because of the way @code{alloca} works, the memory it allocates is
2855 freed even when an error occurs, with no special effort required.
2857 By contrast, the previous definition of @code{open2} (which uses
2858 @code{malloc} and @code{free}) would develop a memory leak if it were
2859 changed in this way. Even if you are willing to make more changes to
2860 fix it, there is no easy way to do so.
2863 @node Disadvantages of Alloca
2864 @subsubsection Disadvantages of @code{alloca}
2866 @cindex @code{alloca} disadvantages
2867 @cindex disadvantages of @code{alloca}
2868 These are the disadvantages of @code{alloca} in comparison with
2873 If you try to allocate more memory than the machine can provide, you
2874 don't get a clean error message. Instead you get a fatal signal like
2875 the one you would get from an infinite recursion; probably a
2876 segmentation violation (@pxref{Program Error Signals}).
2879 Some @nongnusystems{} fail to support @code{alloca}, so it is less
2880 portable. However, a slower emulation of @code{alloca} written in C
2881 is available for use on systems with this deficiency.
2884 @node GNU C Variable-Size Arrays
2885 @subsubsection GNU C Variable-Size Arrays
2886 @cindex variable-sized arrays
2888 In GNU C, you can replace most uses of @code{alloca} with an array of
2889 variable size. Here is how @code{open2} would look then:
2892 int open2 (char *str1, char *str2, int flags, int mode)
2894 char name[strlen (str1) + strlen (str2) + 1];
2895 stpcpy (stpcpy (name, str1), str2);
2896 return open (name, flags, mode);
2900 But @code{alloca} is not always equivalent to a variable-sized array, for
2905 A variable size array's space is freed at the end of the scope of the
2906 name of the array. The space allocated with @code{alloca}
2907 remains until the end of the function.
2910 It is possible to use @code{alloca} within a loop, allocating an
2911 additional block on each iteration. This is impossible with
2912 variable-sized arrays.
2915 @strong{NB:} If you mix use of @code{alloca} and variable-sized arrays
2916 within one function, exiting a scope in which a variable-sized array was
2917 declared frees all blocks allocated with @code{alloca} during the
2918 execution of that scope.
2921 @node Resizing the Data Segment
2922 @section Resizing the Data Segment
2924 The symbols in this section are declared in @file{unistd.h}.
2926 You will not normally use the functions in this section, because the
2927 functions described in @ref{Memory Allocation} are easier to use. Those
2928 are interfaces to a @glibcadj{} memory allocator that uses the
2929 functions below itself. The functions below are simple interfaces to
2934 @deftypefun int brk (void *@var{addr})
2935 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2937 @code{brk} sets the high end of the calling process' data segment to
2940 The address of the end of a segment is defined to be the address of the
2941 last byte in the segment plus 1.
2943 The function has no effect if @var{addr} is lower than the low end of
2944 the data segment. (This is considered success, by the way).
2946 The function fails if it would cause the data segment to overlap another
2947 segment or exceed the process' data storage limit (@pxref{Limits on
2950 The function is named for a common historical case where data storage
2951 and the stack are in the same segment. Data storage allocation grows
2952 upward from the bottom of the segment while the stack grows downward
2953 toward it from the top of the segment and the curtain between them is
2954 called the @dfn{break}.
2956 The return value is zero on success. On failure, the return value is
2957 @code{-1} and @code{errno} is set accordingly. The following @code{errno}
2958 values are specific to this function:
2962 The request would cause the data segment to overlap another segment or
2963 exceed the process' data storage limit.
2966 @c The Brk system call in Linux (as opposed to the GNU C Library function)
2967 @c is considerably different. It always returns the new end of the data
2968 @c segment, whether it succeeds or fails. The GNU C library Brk determines
2969 @c it's a failure if and only if the system call returns an address less
2970 @c than the address requested.
2977 @deftypefun void *sbrk (ptrdiff_t @var{delta})
2978 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2980 This function is the same as @code{brk} except that you specify the new
2981 end of the data segment as an offset @var{delta} from the current end
2982 and on success the return value is the address of the resulting end of
2983 the data segment instead of zero.
2985 This means you can use @samp{sbrk(0)} to find out what the current end
2986 of the data segment is.
2993 @section Locking Pages
2994 @cindex locking pages
2998 You can tell the system to associate a particular virtual memory page
2999 with a real page frame and keep it that way --- i.e., cause the page to
3000 be paged in if it isn't already and mark it so it will never be paged
3001 out and consequently will never cause a page fault. This is called
3002 @dfn{locking} a page.
3004 The functions in this chapter lock and unlock the calling process'
3008 * Why Lock Pages:: Reasons to read this section.
3009 * Locked Memory Details:: Everything you need to know locked
3011 * Page Lock Functions:: Here's how to do it.
3014 @node Why Lock Pages
3015 @subsection Why Lock Pages
3017 Because page faults cause paged out pages to be paged in transparently,
3018 a process rarely needs to be concerned about locking pages. However,
3019 there are two reasons people sometimes are:
3024 Speed. A page fault is transparent only insofar as the process is not
3025 sensitive to how long it takes to do a simple memory access. Time-critical
3026 processes, especially realtime processes, may not be able to wait or
3027 may not be able to tolerate variance in execution speed.
3028 @cindex realtime processing
3029 @cindex speed of execution
3031 A process that needs to lock pages for this reason probably also needs
3032 priority among other processes for use of the CPU. @xref{Priority}.
3034 In some cases, the programmer knows better than the system's demand
3035 paging allocator which pages should remain in real memory to optimize
3036 system performance. In this case, locking pages can help.
3039 Privacy. If you keep secrets in virtual memory and that virtual memory
3040 gets paged out, that increases the chance that the secrets will get out.
3041 If a password gets written out to disk swap space, for example, it might
3042 still be there long after virtual and real memory have been wiped clean.
3046 Be aware that when you lock a page, that's one fewer page frame that can
3047 be used to back other virtual memory (by the same or other processes),
3048 which can mean more page faults, which means the system runs more
3049 slowly. In fact, if you lock enough memory, some programs may not be
3050 able to run at all for lack of real memory.
3052 @node Locked Memory Details
3053 @subsection Locked Memory Details
3055 A memory lock is associated with a virtual page, not a real frame. The
3056 paging rule is: If a frame backs at least one locked page, don't page it
3059 Memory locks do not stack. I.e., you can't lock a particular page twice
3060 so that it has to be unlocked twice before it is truly unlocked. It is
3061 either locked or it isn't.
3063 A memory lock persists until the process that owns the memory explicitly
3064 unlocks it. (But process termination and exec cause the virtual memory
3065 to cease to exist, which you might say means it isn't locked any more).
3067 Memory locks are not inherited by child processes. (But note that on a
3068 modern Unix system, immediately after a fork, the parent's and the
3069 child's virtual address space are backed by the same real page frames,
3070 so the child enjoys the parent's locks). @xref{Creating a Process}.
3072 Because of its ability to impact other processes, only the superuser can
3073 lock a page. Any process can unlock its own page.
3075 The system sets limits on the amount of memory a process can have locked
3076 and the amount of real memory it can have dedicated to it. @xref{Limits
3079 In Linux, locked pages aren't as locked as you might think.
3080 Two virtual pages that are not shared memory can nonetheless be backed
3081 by the same real frame. The kernel does this in the name of efficiency
3082 when it knows both virtual pages contain identical data, and does it
3083 even if one or both of the virtual pages are locked.
3085 But when a process modifies one of those pages, the kernel must get it a
3086 separate frame and fill it with the page's data. This is known as a
3087 @dfn{copy-on-write page fault}. It takes a small amount of time and in
3088 a pathological case, getting that frame may require I/O.
3089 @cindex copy-on-write page fault
3090 @cindex page fault, copy-on-write
3092 To make sure this doesn't happen to your program, don't just lock the
3093 pages. Write to them as well, unless you know you won't write to them
3094 ever. And to make sure you have pre-allocated frames for your stack,
3095 enter a scope that declares a C automatic variable larger than the
3096 maximum stack size you will need, set it to something, then return from
3099 @node Page Lock Functions
3100 @subsection Functions To Lock And Unlock Pages
3102 The symbols in this section are declared in @file{sys/mman.h}. These
3103 functions are defined by POSIX.1b, but their availability depends on
3104 your kernel. If your kernel doesn't allow these functions, they exist
3105 but always fail. They @emph{are} available with a Linux kernel.
3107 @strong{Portability Note:} POSIX.1b requires that when the @code{mlock}
3108 and @code{munlock} functions are available, the file @file{unistd.h}
3109 define the macro @code{_POSIX_MEMLOCK_RANGE} and the file
3110 @code{limits.h} define the macro @code{PAGESIZE} to be the size of a
3111 memory page in bytes. It requires that when the @code{mlockall} and
3112 @code{munlockall} functions are available, the @file{unistd.h} file
3113 define the macro @code{_POSIX_MEMLOCK}. @Theglibc{} conforms to
3118 @deftypefun int mlock (const void *@var{addr}, size_t @var{len})
3119 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3121 @code{mlock} locks a range of the calling process' virtual pages.
3123 The range of memory starts at address @var{addr} and is @var{len} bytes
3124 long. Actually, since you must lock whole pages, it is the range of
3125 pages that include any part of the specified range.
3127 When the function returns successfully, each of those pages is backed by
3128 (connected to) a real frame (is resident) and is marked to stay that
3129 way. This means the function may cause page-ins and have to wait for
3132 When the function fails, it does not affect the lock status of any
3135 The return value is zero if the function succeeds. Otherwise, it is
3136 @code{-1} and @code{errno} is set accordingly. @code{errno} values
3137 specific to this function are:
3143 At least some of the specified address range does not exist in the
3144 calling process' virtual address space.
3146 The locking would cause the process to exceed its locked page limit.
3150 The calling process is not superuser.
3153 @var{len} is not positive.
3156 The kernel does not provide @code{mlock} capability.
3160 You can lock @emph{all} a process' memory with @code{mlockall}. You
3161 unlock memory with @code{munlock} or @code{munlockall}.
3163 To avoid all page faults in a C program, you have to use
3164 @code{mlockall}, because some of the memory a program uses is hidden
3165 from the C code, e.g. the stack and automatic variables, and you
3166 wouldn't know what address to tell @code{mlock}.
3172 @deftypefun int munlock (const void *@var{addr}, size_t @var{len})
3173 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3175 @code{munlock} unlocks a range of the calling process' virtual pages.
3177 @code{munlock} is the inverse of @code{mlock} and functions completely
3178 analogously to @code{mlock}, except that there is no @code{EPERM}
3185 @deftypefun int mlockall (int @var{flags})
3186 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3188 @code{mlockall} locks all the pages in a process' virtual memory address
3189 space, and/or any that are added to it in the future. This includes the
3190 pages of the code, data and stack segment, as well as shared libraries,
3191 user space kernel data, shared memory, and memory mapped files.
3193 @var{flags} is a string of single bit flags represented by the following
3194 macros. They tell @code{mlockall} which of its functions you want. All
3195 other bits must be zero.
3200 Lock all pages which currently exist in the calling process' virtual
3204 Set a mode such that any pages added to the process' virtual address
3205 space in the future will be locked from birth. This mode does not
3206 affect future address spaces owned by the same process so exec, which
3207 replaces a process' address space, wipes out @code{MCL_FUTURE}.
3208 @xref{Executing a File}.
3212 When the function returns successfully, and you specified
3213 @code{MCL_CURRENT}, all of the process' pages are backed by (connected
3214 to) real frames (they are resident) and are marked to stay that way.
3215 This means the function may cause page-ins and have to wait for them.
3217 When the process is in @code{MCL_FUTURE} mode because it successfully
3218 executed this function and specified @code{MCL_CURRENT}, any system call
3219 by the process that requires space be added to its virtual address space
3220 fails with @code{errno} = @code{ENOMEM} if locking the additional space
3221 would cause the process to exceed its locked page limit. In the case
3222 that the address space addition that can't be accommodated is stack
3223 expansion, the stack expansion fails and the kernel sends a
3224 @code{SIGSEGV} signal to the process.
3226 When the function fails, it does not affect the lock status of any pages
3227 or the future locking mode.
3229 The return value is zero if the function succeeds. Otherwise, it is
3230 @code{-1} and @code{errno} is set accordingly. @code{errno} values
3231 specific to this function are:
3237 At least some of the specified address range does not exist in the
3238 calling process' virtual address space.
3240 The locking would cause the process to exceed its locked page limit.
3244 The calling process is not superuser.
3247 Undefined bits in @var{flags} are not zero.
3250 The kernel does not provide @code{mlockall} capability.
3254 You can lock just specific pages with @code{mlock}. You unlock pages
3255 with @code{munlockall} and @code{munlock}.
3262 @deftypefun int munlockall (void)
3263 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3265 @code{munlockall} unlocks every page in the calling process' virtual
3266 address space and turn off @code{MCL_FUTURE} future locking mode.
3268 The return value is zero if the function succeeds. Otherwise, it is
3269 @code{-1} and @code{errno} is set accordingly. The only way this
3270 function can fail is for generic reasons that all functions and system
3271 calls can fail, so there are no specific @code{errno} values.
3279 @c This was never actually implemented. -zw
3280 @node Relocating Allocator
3281 @section Relocating Allocator
3283 @cindex relocating memory allocator
3284 Any system of dynamic memory allocation has overhead: the amount of
3285 space it uses is more than the amount the program asks for. The
3286 @dfn{relocating memory allocator} achieves very low overhead by moving
3287 blocks in memory as necessary, on its own initiative.
3290 @c * Relocator Concepts:: How to understand relocating allocation.
3291 @c * Using Relocator:: Functions for relocating allocation.
3294 @node Relocator Concepts
3295 @subsection Concepts of Relocating Allocation
3298 The @dfn{relocating memory allocator} achieves very low overhead by
3299 moving blocks in memory as necessary, on its own initiative.
3302 When you allocate a block with @code{malloc}, the address of the block
3303 never changes unless you use @code{realloc} to change its size. Thus,
3304 you can safely store the address in various places, temporarily or
3305 permanently, as you like. This is not safe when you use the relocating
3306 memory allocator, because any and all relocatable blocks can move
3307 whenever you allocate memory in any fashion. Even calling @code{malloc}
3308 or @code{realloc} can move the relocatable blocks.
3311 For each relocatable block, you must make a @dfn{handle}---a pointer
3312 object in memory, designated to store the address of that block. The
3313 relocating allocator knows where each block's handle is, and updates the
3314 address stored there whenever it moves the block, so that the handle
3315 always points to the block. Each time you access the contents of the
3316 block, you should fetch its address anew from the handle.
3318 To call any of the relocating allocator functions from a signal handler
3319 is almost certainly incorrect, because the signal could happen at any
3320 time and relocate all the blocks. The only way to make this safe is to
3321 block the signal around any access to the contents of any relocatable
3322 block---not a convenient mode of operation. @xref{Nonreentrancy}.
3324 @node Using Relocator
3325 @subsection Allocating and Freeing Relocatable Blocks
3328 In the descriptions below, @var{handleptr} designates the address of the
3329 handle. All the functions are declared in @file{malloc.h}; all are GNU
3334 @c @deftypefun {void *} r_alloc (void **@var{handleptr}, size_t @var{size})
3335 This function allocates a relocatable block of size @var{size}. It
3336 stores the block's address in @code{*@var{handleptr}} and returns
3337 a non-null pointer to indicate success.
3339 If @code{r_alloc} can't get the space needed, it stores a null pointer
3340 in @code{*@var{handleptr}}, and returns a null pointer.
3345 @c @deftypefun void r_alloc_free (void **@var{handleptr})
3346 This function is the way to free a relocatable block. It frees the
3347 block that @code{*@var{handleptr}} points to, and stores a null pointer
3348 in @code{*@var{handleptr}} to show it doesn't point to an allocated
3354 @c @deftypefun {void *} r_re_alloc (void **@var{handleptr}, size_t @var{size})
3355 The function @code{r_re_alloc} adjusts the size of the block that
3356 @code{*@var{handleptr}} points to, making it @var{size} bytes long. It
3357 stores the address of the resized block in @code{*@var{handleptr}} and
3358 returns a non-null pointer to indicate success.
3360 If enough memory is not available, this function returns a null pointer
3361 and does not modify @code{*@var{handleptr}}.
3369 @comment No longer available...
3371 @comment @node Memory Warnings
3372 @comment @section Memory Usage Warnings
3373 @comment @cindex memory usage warnings
3374 @comment @cindex warnings of memory almost full
3377 You can ask for warnings as the program approaches running out of memory
3378 space, by calling @code{memory_warnings}. This tells @code{malloc} to
3379 check memory usage every time it asks for more memory from the operating
3380 system. This is a GNU extension declared in @file{malloc.h}.
3384 @comment @deftypefun void memory_warnings (void *@var{start}, void (*@var{warn-func}) (const char *))
3385 Call this function to request warnings for nearing exhaustion of virtual
3388 The argument @var{start} says where data space begins, in memory. The
3389 allocator compares this against the last address used and against the
3390 limit of data space, to determine the fraction of available memory in
3391 use. If you supply zero for @var{start}, then a default value is used
3392 which is right in most circumstances.
3394 For @var{warn-func}, supply a function that @code{malloc} can call to
3395 warn you. It is called with a string (a warning message) as argument.
3396 Normally it ought to display the string for the user to read.
3399 The warnings come when memory becomes 75% full, when it becomes 85%
3400 full, and when it becomes 95% full. Above 95% you get another warning
3401 each time memory usage increases.