Support mcount/gprof test with GCC defaulting to PIE
[glibc.git] / manual / memory.texi
blob82f473806c2cb2178cb1af110592bfe7717617be
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
8 that uses @theglibc{}.
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.
16 @menu
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
21 @end menu
23 Memory mapped I/O is not discussed in this chapter.  @xref{Memory-mapped I/O}.
27 @node Memory Concepts
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
35 store data.
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.
43 @cindex page frame
44 @cindex frame, real memory
45 @cindex swap space
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}
53 call in its program.
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.
74 @cindex page fault
75 @cindex paging
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
97 Allocation and C}).
98 @cindex executable
99 @cindex literals
100 @cindex constants
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
126 Termination}.
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:
134 @itemize @bullet
136 @item
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.
142 @item
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.
148 @item
149 The @dfn{stack segment} contains a program stack.  It grows as the stack
150 grows, but doesn't shrink when the stack shrinks.
152 @end itemize
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 to @theglibc{} and GNU Compiler.
163 @menu
164 * Memory Allocation and C::     How to get different kinds of allocation in C.
165 * The GNU Allocator::           An overview of the GNU @code{malloc}
166                                 implementation.
167 * Unconstrained Allocation::    The @code{malloc} facility allows fully general
168                                  dynamic allocation.
169 * Allocation Debugging::        Finding memory leaks and not freed memory.
170 * Replacing malloc::            Using your own @code{malloc}-style allocator.
171 * Obstacks::                    Obstacks are less general than malloc
172                                  but more efficient and convenient.
173 * Variable Size Automatic::     Allocation of variable-sized blocks
174                                  of automatic storage that are freed when the
175                                  calling function returns.
176 @end menu
179 @node Memory Allocation and C
180 @subsection Memory Allocation in C Programs
182 The C language supports two kinds of memory allocation through the
183 variables in C programs:
185 @itemize @bullet
186 @item
187 @dfn{Static allocation} is what happens when you declare a static or
188 global variable.  Each static or global variable defines one block of
189 space, of a fixed size.  The space is allocated once, when your program
190 is started (part of the exec operation), and is never freed.
191 @cindex static memory allocation
192 @cindex static storage class
194 @item
195 @dfn{Automatic allocation} happens when you declare an automatic
196 variable, such as a function argument or a local variable.  The space
197 for an automatic variable is allocated when the compound statement
198 containing the declaration is entered, and is freed when that
199 compound statement is exited.
200 @cindex automatic memory allocation
201 @cindex automatic storage class
203 In GNU C, the size of the automatic storage can be an expression
204 that varies.  In other C implementations, it must be a constant.
205 @end itemize
207 A third important kind of memory allocation, @dfn{dynamic allocation},
208 is not supported by C variables but is available via @glibcadj{}
209 functions.
210 @cindex dynamic memory allocation
212 @subsubsection Dynamic Memory Allocation
213 @cindex dynamic memory allocation
215 @dfn{Dynamic memory allocation} is a technique in which programs
216 determine as they are running where to store some information.  You need
217 dynamic allocation when the amount of memory you need, or how long you
218 continue to need it, depends on factors that are not known before the
219 program runs.
221 For example, you may need a block to store a line read from an input
222 file; since there is no limit to how long a line can be, you must
223 allocate the memory dynamically and make it dynamically larger as you
224 read more of the line.
226 Or, you may need a block for each record or each definition in the input
227 data; since you can't know in advance how many there will be, you must
228 allocate a new block for each record or definition as you read it.
230 When you use dynamic allocation, the allocation of a block of memory is
231 an action that the program requests explicitly.  You call a function or
232 macro when you want to allocate space, and specify the size with an
233 argument.  If you want to free the space, you do so by calling another
234 function or macro.  You can do these things whenever you want, as often
235 as you want.
237 Dynamic allocation is not supported by C variables; there is no storage
238 class ``dynamic'', and there can never be a C variable whose value is
239 stored in dynamically allocated space.  The only way to get dynamically
240 allocated memory is via a system call (which is generally via a @glibcadj{}
241 function call), and the only way to refer to dynamically
242 allocated space is through a pointer.  Because it is less convenient,
243 and because the actual process of dynamic allocation requires more
244 computation time, programmers generally use dynamic allocation only when
245 neither static nor automatic allocation will serve.
247 For example, if you want to allocate dynamically some space to hold a
248 @code{struct foobar}, you cannot declare a variable of type @code{struct
249 foobar} whose contents are the dynamically allocated space.  But you can
250 declare a variable of pointer type @code{struct foobar *} and assign it the
251 address of the space.  Then you can use the operators @samp{*} and
252 @samp{->} on this pointer variable to refer to the contents of the space:
254 @smallexample
256   struct foobar *ptr
257      = (struct foobar *) malloc (sizeof (struct foobar));
258   ptr->name = x;
259   ptr->next = current_foobar;
260   current_foobar = ptr;
262 @end smallexample
264 @node The GNU Allocator
265 @subsection The GNU Allocator
266 @cindex gnu allocator
268 The @code{malloc} implementation in @theglibc{} is derived from ptmalloc
269 (pthreads malloc), which in turn is derived from dlmalloc (Doug Lea malloc).
270 This malloc may allocate memory in two different ways depending on their size
271 and certain parameters that may be controlled by users. The most common way is
272 to allocate portions of memory (called chunks) from a large contiguous area of
273 memory and manage these areas to optimize their use and reduce wastage in the
274 form of unusable chunks. Traditionally the system heap was set up to be the one
275 large memory area but the @glibcadj{} @code{malloc} implementation maintains
276 multiple such areas to optimize their use in multi-threaded applications.  Each
277 such area is internally referred to as an @dfn{arena}.
279 As opposed to other versions, the @code{malloc} in @theglibc{} does not round
280 up chunk sizes to powers of two, neither for large nor for small sizes.
281 Neighboring chunks can be coalesced on a @code{free} no matter what their size
282 is.  This makes the implementation suitable for all kinds of allocation
283 patterns without generally incurring high memory waste through fragmentation.
284 The presence of multiple arenas allows multiple threads to allocate
285 memory simultaneously in separate arenas, thus improving performance.
287 The other way of memory allocation is for very large blocks, i.e. much larger
288 than a page. These requests are allocated with @code{mmap} (anonymous or via
289 @file{/dev/zero}; @pxref{Memory-mapped I/O})). This has the great advantage
290 that these chunks are returned to the system immediately when they are freed.
291 Therefore, it cannot happen that a large chunk becomes ``locked'' in between
292 smaller ones and even after calling @code{free} wastes memory.  The size
293 threshold for @code{mmap} to be used is dynamic and gets adjusted according to
294 allocation patterns of the program.  @code{mallopt} can be used to statically
295 adjust the threshold using @code{M_MMAP_THRESHOLD} and the use of @code{mmap}
296 can be disabled completely with @code{M_MMAP_MAX};
297 @pxref{Malloc Tunable Parameters}.
299 A more detailed technical description of the GNU Allocator is maintained in
300 the @glibcadj{} wiki. See
301 @uref{https://sourceware.org/glibc/wiki/MallocInternals}.
303 It is possible to use your own custom @code{malloc} instead of the
304 built-in allocator provided by @theglibc{}.  @xref{Replacing malloc}.
306 @node Unconstrained Allocation
307 @subsection Unconstrained Allocation
308 @cindex unconstrained memory allocation
309 @cindex @code{malloc} function
310 @cindex heap, dynamic allocation from
312 The most general dynamic allocation facility is @code{malloc}.  It
313 allows you to allocate blocks of memory of any size at any time, make
314 them bigger or smaller at any time, and free the blocks individually at
315 any time (or never).
317 @menu
318 * Basic Allocation::            Simple use of @code{malloc}.
319 * Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
320 * Freeing after Malloc::        Use @code{free} to free a block you
321                                  got with @code{malloc}.
322 * Changing Block Size::         Use @code{realloc} to make a block
323                                  bigger or smaller.
324 * Allocating Cleared Space::    Use @code{calloc} to allocate a
325                                  block and clear it.
326 * Aligned Memory Blocks::       Allocating specially aligned memory.
327 * Malloc Tunable Parameters::   Use @code{mallopt} to adjust allocation
328                                  parameters.
329 * Heap Consistency Checking::   Automatic checking for errors.
330 * Hooks for Malloc::            You can use these hooks for debugging
331                                  programs that use @code{malloc}.
332 * Statistics of Malloc::        Getting information about how much
333                                  memory your program is using.
334 * Summary of Malloc::           Summary of @code{malloc} and related functions.
335 @end menu
337 @node Basic Allocation
338 @subsubsection Basic Memory Allocation
339 @cindex allocation of memory with @code{malloc}
341 To allocate a block of memory, call @code{malloc}.  The prototype for
342 this function is in @file{stdlib.h}.
343 @pindex stdlib.h
345 @deftypefun {void *} malloc (size_t @var{size})
346 @standards{ISO, malloc.h}
347 @standards{ISO, stdlib.h}
348 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
349 @c Malloc hooks and __morecore pointers, as well as such parameters as
350 @c max_n_mmaps and max_mmapped_mem, are accessed without guards, so they
351 @c could pose a thread safety issue; in order to not declare malloc
352 @c MT-unsafe, it's modifying the hooks and parameters while multiple
353 @c threads are active that is regarded as unsafe.  An arena's next field
354 @c is initialized and never changed again, except for main_arena's,
355 @c that's protected by list_lock; next_free is only modified while
356 @c list_lock is held too.  All other data members of an arena, as well
357 @c as the metadata of the memory areas assigned to it, are only modified
358 @c while holding the arena's mutex (fastbin pointers use catomic ops
359 @c because they may be modified by free without taking the arena's
360 @c lock).  Some reassurance was needed for fastbins, for it wasn't clear
361 @c how they were initialized.  It turns out they are always
362 @c zero-initialized: main_arena's, for being static data, and other
363 @c arena's, for being just-mmapped memory.
365 @c Leaking file descriptors and memory in case of cancellation is
366 @c unavoidable without disabling cancellation, but the lock situation is
367 @c a bit more complicated: we don't have fallback arenas for malloc to
368 @c be safe to call from within signal handlers.  Error-checking mutexes
369 @c or trylock could enable us to try and use alternate arenas, even with
370 @c -DPER_THREAD (enabled by default), but supporting interruption
371 @c (cancellation or signal handling) while holding the arena list mutex
372 @c would require more work; maybe blocking signals and disabling async
373 @c cancellation while manipulating the arena lists?
375 @c __libc_malloc @asulock @aculock @acsfd @acsmem
376 @c  force_reg ok
377 @c  *malloc_hook unguarded
378 @c  arena_lock @asulock @aculock @acsfd @acsmem
379 @c   mutex_lock @asulock @aculock
380 @c   arena_get2 @asulock @aculock @acsfd @acsmem
381 @c    get_free_list @asulock @aculock
382 @c     mutex_lock (list_lock) dup @asulock @aculock
383 @c     mutex_unlock (list_lock) dup @aculock
384 @c     mutex_lock (arena lock) dup @asulock @aculock [returns locked]
385 @c    __get_nprocs ext ok @acsfd
386 @c    NARENAS_FROM_NCORES ok
387 @c    catomic_compare_and_exchange_bool_acq ok
388 @c    _int_new_arena ok @asulock @aculock @acsmem
389 @c     new_heap ok @acsmem
390 @c      mmap ok @acsmem
391 @c      munmap ok @acsmem
392 @c      mprotect ok
393 @c     chunk2mem ok
394 @c     set_head ok
395 @c     tsd_setspecific dup ok
396 @c     mutex_init ok
397 @c     mutex_lock (just-created mutex) ok, returns locked
398 @c     mutex_lock (list_lock) dup @asulock @aculock
399 @c     atomic_write_barrier ok
400 @c     mutex_unlock (list_lock) @aculock
401 @c    catomic_decrement ok
402 @c    reused_arena @asulock @aculock
403 @c      reads&writes next_to_use and iterates over arena next without guards
404 @c      those are harmless as long as we don't drop arenas from the
405 @c      NEXT list, and we never do; when a thread terminates,
406 @c      arena_thread_freeres prepends the arena to the free_list
407 @c      NEXT_FREE list, but NEXT is never modified, so it's safe!
408 @c     mutex_trylock (arena lock) @asulock @aculock
409 @c     mutex_lock (arena lock) dup @asulock @aculock
410 @c     tsd_setspecific dup ok
411 @c  _int_malloc @acsfd @acsmem
412 @c   checked_request2size ok
413 @c    REQUEST_OUT_OF_RANGE ok
414 @c    request2size ok
415 @c   get_max_fast ok
416 @c   fastbin_index ok
417 @c   fastbin ok
418 @c   catomic_compare_and_exhange_val_acq ok
419 @c   malloc_printerr dup @mtsenv
420 @c     if we get to it, we're toast already, undefined behavior must have
421 @c     been invoked before
422 @c    libc_message @mtsenv [no leaks with cancellation disabled]
423 @c     FATAL_PREPARE ok
424 @c      pthread_setcancelstate disable ok
425 @c     libc_secure_getenv @mtsenv
426 @c      getenv @mtsenv
427 @c     open_not_cancel_2 dup @acsfd
428 @c     strchrnul ok
429 @c     WRITEV_FOR_FATAL ok
430 @c      writev ok
431 @c     mmap ok @acsmem
432 @c     munmap ok @acsmem
433 @c     BEFORE_ABORT @acsfd
434 @c      backtrace ok
435 @c      write_not_cancel dup ok
436 @c      backtrace_symbols_fd @aculock
437 @c      open_not_cancel_2 dup @acsfd
438 @c      read_not_cancel dup ok
439 @c      close_not_cancel_no_status dup @acsfd
440 @c     abort ok
441 @c    itoa_word ok
442 @c    abort ok
443 @c   check_remalloced_chunk ok/disabled
444 @c   chunk2mem dup ok
445 @c   alloc_perturb ok
446 @c   in_smallbin_range ok
447 @c   smallbin_index ok
448 @c   bin_at ok
449 @c   last ok
450 @c   malloc_consolidate ok
451 @c    get_max_fast dup ok
452 @c    clear_fastchunks ok
453 @c    unsorted_chunks dup ok
454 @c    fastbin dup ok
455 @c    atomic_exchange_acq ok
456 @c    check_inuse_chunk dup ok/disabled
457 @c    chunk_at_offset dup ok
458 @c    chunksize dup ok
459 @c    inuse_bit_at_offset dup ok
460 @c    unlink dup ok
461 @c    clear_inuse_bit_at_offset dup ok
462 @c    in_smallbin_range dup ok
463 @c    set_head dup ok
464 @c    malloc_init_state ok
465 @c     bin_at dup ok
466 @c     set_noncontiguous dup ok
467 @c     set_max_fast dup ok
468 @c     initial_top ok
469 @c      unsorted_chunks dup ok
470 @c    check_malloc_state ok/disabled
471 @c   set_inuse_bit_at_offset ok
472 @c   check_malloced_chunk ok/disabled
473 @c   largebin_index ok
474 @c   have_fastchunks ok
475 @c   unsorted_chunks ok
476 @c    bin_at ok
477 @c   chunksize ok
478 @c   chunk_at_offset ok
479 @c   set_head ok
480 @c   set_foot ok
481 @c   mark_bin ok
482 @c    idx2bit ok
483 @c   first ok
484 @c   unlink ok
485 @c    malloc_printerr dup ok
486 @c    in_smallbin_range dup ok
487 @c   idx2block ok
488 @c   idx2bit dup ok
489 @c   next_bin ok
490 @c   sysmalloc @acsfd @acsmem
491 @c    MMAP @acsmem
492 @c    set_head dup ok
493 @c    check_chunk ok/disabled
494 @c    chunk2mem dup ok
495 @c    chunksize dup ok
496 @c    chunk_at_offset dup ok
497 @c    heap_for_ptr ok
498 @c    grow_heap ok
499 @c     mprotect ok
500 @c    set_head dup ok
501 @c    new_heap @acsmem
502 @c     MMAP dup @acsmem
503 @c     munmap @acsmem
504 @c    top ok
505 @c    set_foot dup ok
506 @c    contiguous ok
507 @c    MORECORE ok
508 @c     *__morecore ok unguarded
509 @c      __default_morecore
510 @c       sbrk ok
511 @c    force_reg dup ok
512 @c    *__after_morecore_hook unguarded
513 @c    set_noncontiguous ok
514 @c    malloc_printerr dup ok
515 @c    _int_free (have_lock) @acsfd @acsmem [@asulock @aculock]
516 @c     chunksize dup ok
517 @c     mutex_unlock dup @aculock/!have_lock
518 @c     malloc_printerr dup ok
519 @c     check_inuse_chunk ok/disabled
520 @c     chunk_at_offset dup ok
521 @c     mutex_lock dup @asulock @aculock/@have_lock
522 @c     chunk2mem dup ok
523 @c     free_perturb ok
524 @c     set_fastchunks ok
525 @c      catomic_and ok
526 @c     fastbin_index dup ok
527 @c     fastbin dup ok
528 @c     catomic_compare_and_exchange_val_rel ok
529 @c     chunk_is_mmapped ok
530 @c     contiguous dup ok
531 @c     prev_inuse ok
532 @c     unlink dup ok
533 @c     inuse_bit_at_offset dup ok
534 @c     clear_inuse_bit_at_offset ok
535 @c     unsorted_chunks dup ok
536 @c     in_smallbin_range dup ok
537 @c     set_head dup ok
538 @c     set_foot dup ok
539 @c     check_free_chunk ok/disabled
540 @c     check_chunk dup ok/disabled
541 @c     have_fastchunks dup ok
542 @c     malloc_consolidate dup ok
543 @c     systrim ok
544 @c      MORECORE dup ok
545 @c      *__after_morecore_hook dup unguarded
546 @c      set_head dup ok
547 @c      check_malloc_state ok/disabled
548 @c     top dup ok
549 @c     heap_for_ptr dup ok
550 @c     heap_trim @acsfd @acsmem
551 @c      top dup ok
552 @c      chunk_at_offset dup ok
553 @c      prev_chunk ok
554 @c      chunksize dup ok
555 @c      prev_inuse dup ok
556 @c      delete_heap @acsmem
557 @c       munmap dup @acsmem
558 @c      unlink dup ok
559 @c      set_head dup ok
560 @c      shrink_heap @acsfd
561 @c       check_may_shrink_heap @acsfd
562 @c        open_not_cancel_2 @acsfd
563 @c        read_not_cancel ok
564 @c        close_not_cancel_no_status @acsfd
565 @c       MMAP dup ok
566 @c       madvise ok
567 @c     munmap_chunk @acsmem
568 @c      chunksize dup ok
569 @c      chunk_is_mmapped dup ok
570 @c      chunk2mem dup ok
571 @c      malloc_printerr dup ok
572 @c      munmap dup @acsmem
573 @c    check_malloc_state ok/disabled
574 @c  arena_get_retry @asulock @aculock @acsfd @acsmem
575 @c   mutex_unlock dup @aculock
576 @c   mutex_lock dup @asulock @aculock
577 @c   arena_get2 dup @asulock @aculock @acsfd @acsmem
578 @c  mutex_unlock @aculock
579 @c  mem2chunk ok
580 @c  chunk_is_mmapped ok
581 @c  arena_for_chunk ok
582 @c   chunk_non_main_arena ok
583 @c   heap_for_ptr ok
584 This function returns a pointer to a newly allocated block @var{size}
585 bytes long, or a null pointer if the block could not be allocated.
586 @end deftypefun
588 The contents of the block are undefined; you must initialize it yourself
589 (or use @code{calloc} instead; @pxref{Allocating Cleared Space}).
590 Normally you would cast the value as a pointer to the kind of object
591 that you want to store in the block.  Here we show an example of doing
592 so, and of initializing the space with zeros using the library function
593 @code{memset} (@pxref{Copying Strings and Arrays}):
595 @smallexample
596 struct foo *ptr;
597 @dots{}
598 ptr = (struct foo *) malloc (sizeof (struct foo));
599 if (ptr == 0) abort ();
600 memset (ptr, 0, sizeof (struct foo));
601 @end smallexample
603 You can store the result of @code{malloc} into any pointer variable
604 without a cast, because @w{ISO C} automatically converts the type
605 @code{void *} to another type of pointer when necessary.  But the cast
606 is necessary in contexts other than assignment operators or if you might
607 want your code to run in traditional C.
609 Remember that when allocating space for a string, the argument to
610 @code{malloc} must be one plus the length of the string.  This is
611 because a string is terminated with a null character that doesn't count
612 in the ``length'' of the string but does need space.  For example:
614 @smallexample
615 char *ptr;
616 @dots{}
617 ptr = (char *) malloc (length + 1);
618 @end smallexample
620 @noindent
621 @xref{Representation of Strings}, for more information about this.
623 @node Malloc Examples
624 @subsubsection Examples of @code{malloc}
626 If no more space is available, @code{malloc} returns a null pointer.
627 You should check the value of @emph{every} call to @code{malloc}.  It is
628 useful to write a subroutine that calls @code{malloc} and reports an
629 error if the value is a null pointer, returning only if the value is
630 nonzero.  This function is conventionally called @code{xmalloc}.  Here
631 it is:
633 @smallexample
634 void *
635 xmalloc (size_t size)
637   void *value = malloc (size);
638   if (value == 0)
639     fatal ("virtual memory exhausted");
640   return value;
642 @end smallexample
644 Here is a real example of using @code{malloc} (by way of @code{xmalloc}).
645 The function @code{savestring} will copy a sequence of characters into
646 a newly allocated null-terminated string:
648 @smallexample
649 @group
650 char *
651 savestring (const char *ptr, size_t len)
653   char *value = (char *) xmalloc (len + 1);
654   value[len] = '\0';
655   return (char *) memcpy (value, ptr, len);
657 @end group
658 @end smallexample
660 The block that @code{malloc} gives you is guaranteed to be aligned so
661 that it can hold any type of data.  On @gnusystems{}, the address is
662 always a multiple of eight on 32-bit systems, and a multiple of 16 on
663 64-bit systems.  Only rarely is any higher boundary (such as a page
664 boundary) necessary; for those cases, use @code{aligned_alloc} or
665 @code{posix_memalign} (@pxref{Aligned Memory Blocks}).
667 Note that the memory located after the end of the block is likely to be
668 in use for something else; perhaps a block already allocated by another
669 call to @code{malloc}.  If you attempt to treat the block as longer than
670 you asked for it to be, you are liable to destroy the data that
671 @code{malloc} uses to keep track of its blocks, or you may destroy the
672 contents of another block.  If you have already allocated a block and
673 discover you want it to be bigger, use @code{realloc} (@pxref{Changing
674 Block Size}).
676 @node Freeing after Malloc
677 @subsubsection Freeing Memory Allocated with @code{malloc}
678 @cindex freeing memory allocated with @code{malloc}
679 @cindex heap, freeing memory from
681 When you no longer need a block that you got with @code{malloc}, use the
682 function @code{free} to make the block available to be allocated again.
683 The prototype for this function is in @file{stdlib.h}.
684 @pindex stdlib.h
686 @deftypefun void free (void *@var{ptr})
687 @standards{ISO, malloc.h}
688 @standards{ISO, stdlib.h}
689 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
690 @c __libc_free @asulock @aculock @acsfd @acsmem
691 @c   releasing memory into fastbins modifies the arena without taking
692 @c   its mutex, but catomic operations ensure safety.  If two (or more)
693 @c   threads are running malloc and have their own arenas locked when
694 @c   each gets a signal whose handler free()s large (non-fastbin-able)
695 @c   blocks from each other's arena, we deadlock; this is a more general
696 @c   case of @asulock.
697 @c  *__free_hook unguarded
698 @c  mem2chunk ok
699 @c  chunk_is_mmapped ok, chunk bits not modified after allocation
700 @c  chunksize ok
701 @c  munmap_chunk dup @acsmem
702 @c  arena_for_chunk dup ok
703 @c  _int_free (!have_lock) dup @asulock @aculock @acsfd @acsmem
704 The @code{free} function deallocates the block of memory pointed at
705 by @var{ptr}.
706 @end deftypefun
708 Freeing a block alters the contents of the block.  @strong{Do not expect to
709 find any data (such as a pointer to the next block in a chain of blocks) in
710 the block after freeing it.}  Copy whatever you need out of the block before
711 freeing it!  Here is an example of the proper way to free all the blocks in
712 a chain, and the strings that they point to:
714 @smallexample
715 struct chain
716   @{
717     struct chain *next;
718     char *name;
719   @}
721 void
722 free_chain (struct chain *chain)
724   while (chain != 0)
725     @{
726       struct chain *next = chain->next;
727       free (chain->name);
728       free (chain);
729       chain = next;
730     @}
732 @end smallexample
734 Occasionally, @code{free} can actually return memory to the operating
735 system and make the process smaller.  Usually, all it can do is allow a
736 later call to @code{malloc} to reuse the space.  In the meantime, the
737 space remains in your program as part of a free-list used internally by
738 @code{malloc}.
740 There is no point in freeing blocks at the end of a program, because all
741 of the program's space is given back to the system when the process
742 terminates.
744 @node Changing Block Size
745 @subsubsection Changing the Size of a Block
746 @cindex changing the size of a block (@code{malloc})
748 Often you do not know for certain how big a block you will ultimately need
749 at the time you must begin to use the block.  For example, the block might
750 be a buffer that you use to hold a line being read from a file; no matter
751 how long you make the buffer initially, you may encounter a line that is
752 longer.
754 You can make the block longer by calling @code{realloc} or
755 @code{reallocarray}.  These functions are declared in @file{stdlib.h}.
756 @pindex stdlib.h
758 @deftypefun {void *} realloc (void *@var{ptr}, size_t @var{newsize})
759 @standards{ISO, malloc.h}
760 @standards{ISO, stdlib.h}
761 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
762 @c It may call the implementations of malloc and free, so all of their
763 @c issues arise, plus the realloc hook, also accessed without guards.
765 @c __libc_realloc @asulock @aculock @acsfd @acsmem
766 @c  *__realloc_hook unguarded
767 @c  __libc_free dup @asulock @aculock @acsfd @acsmem
768 @c  __libc_malloc dup @asulock @aculock @acsfd @acsmem
769 @c  mem2chunk dup ok
770 @c  chunksize dup ok
771 @c  malloc_printerr dup ok
772 @c  checked_request2size dup ok
773 @c  chunk_is_mmapped dup ok
774 @c  mremap_chunk
775 @c   chunksize dup ok
776 @c   __mremap ok
777 @c   set_head dup ok
778 @c  MALLOC_COPY ok
779 @c   memcpy ok
780 @c  munmap_chunk dup @acsmem
781 @c  arena_for_chunk dup ok
782 @c  mutex_lock (arena mutex) dup @asulock @aculock
783 @c  _int_realloc @acsfd @acsmem
784 @c   malloc_printerr dup ok
785 @c   check_inuse_chunk dup ok/disabled
786 @c   chunk_at_offset dup ok
787 @c   chunksize dup ok
788 @c   set_head_size dup ok
789 @c   chunk_at_offset dup ok
790 @c   set_head dup ok
791 @c   chunk2mem dup ok
792 @c   inuse dup ok
793 @c   unlink dup ok
794 @c   _int_malloc dup @acsfd @acsmem
795 @c   mem2chunk dup ok
796 @c   MALLOC_COPY dup ok
797 @c   _int_free (have_lock) dup @acsfd @acsmem
798 @c   set_inuse_bit_at_offset dup ok
799 @c   set_head dup ok
800 @c  mutex_unlock (arena mutex) dup @aculock
801 @c  _int_free (!have_lock) dup @asulock @aculock @acsfd @acsmem
803 The @code{realloc} function changes the size of the block whose address is
804 @var{ptr} to be @var{newsize}.
806 Since the space after the end of the block may be in use, @code{realloc}
807 may find it necessary to copy the block to a new address where more free
808 space is available.  The value of @code{realloc} is the new address of the
809 block.  If the block needs to be moved, @code{realloc} copies the old
810 contents.
812 If you pass a null pointer for @var{ptr}, @code{realloc} behaves just
813 like @samp{malloc (@var{newsize})}.  This can be convenient, but beware
814 that older implementations (before @w{ISO C}) may not support this
815 behavior, and will probably crash when @code{realloc} is passed a null
816 pointer.
817 @end deftypefun
819 @deftypefun {void *} reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size})
820 @standards{BSD, malloc.h}
821 @standards{BSD, stdlib.h}
822 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
824 The @code{reallocarray} function changes the size of the block whose address
825 is @var{ptr} to be long enough to contain a vector of @var{nmemb} elements,
826 each of size @var{size}.  It is equivalent to @samp{realloc (@var{ptr},
827 @var{nmemb} * @var{size})}, except that @code{reallocarray} fails safely if
828 the multiplication overflows, by setting @code{errno} to @code{ENOMEM},
829 returning a null pointer, and leaving the original block unchanged.
831 @code{reallocarray} should be used instead of @code{realloc} when the new size
832 of the allocated block is the result of a multiplication that might overflow.
834 @strong{Portability Note:} This function is not part of any standard.  It was
835 first introduced in OpenBSD 5.6.
836 @end deftypefun
838 Like @code{malloc}, @code{realloc} and @code{reallocarray} may return a null
839 pointer if no memory space is available to make the block bigger.  When this
840 happens, the original block is untouched; it has not been modified or
841 relocated.
843 In most cases it makes no difference what happens to the original block
844 when @code{realloc} fails, because the application program cannot continue
845 when it is out of memory, and the only thing to do is to give a fatal error
846 message.  Often it is convenient to write and use a subroutine,
847 conventionally called @code{xrealloc}, that takes care of the error message
848 as @code{xmalloc} does for @code{malloc}:
850 @smallexample
851 void *
852 xrealloc (void *ptr, size_t size)
854   void *value = realloc (ptr, size);
855   if (value == 0)
856     fatal ("Virtual memory exhausted");
857   return value;
859 @end smallexample
861 You can also use @code{realloc} or @code{reallocarray} to make a block
862 smaller.  The reason you would do this is to avoid tying up a lot of memory
863 space when only a little is needed.
864 @comment The following is no longer true with the new malloc.
865 @comment But it seems wise to keep the warning for other implementations.
866 In several allocation implementations, making a block smaller sometimes
867 necessitates copying it, so it can fail if no other space is available.
869 If the new size you specify is the same as the old size, @code{realloc} and
870 @code{reallocarray} are guaranteed to change nothing and return the same
871 address that you gave.
873 @node Allocating Cleared Space
874 @subsubsection Allocating Cleared Space
876 The function @code{calloc} allocates memory and clears it to zero.  It
877 is declared in @file{stdlib.h}.
878 @pindex stdlib.h
880 @deftypefun {void *} calloc (size_t @var{count}, size_t @var{eltsize})
881 @standards{ISO, malloc.h}
882 @standards{ISO, stdlib.h}
883 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
884 @c Same caveats as malloc.
886 @c __libc_calloc @asulock @aculock @acsfd @acsmem
887 @c  *__malloc_hook dup unguarded
888 @c  memset dup ok
889 @c  arena_get @asulock @aculock @acsfd @acsmem
890 @c   arena_lock dup @asulock @aculock @acsfd @acsmem
891 @c  top dup ok
892 @c  chunksize dup ok
893 @c  heap_for_ptr dup ok
894 @c  _int_malloc dup @acsfd @acsmem
895 @c  arena_get_retry dup @asulock @aculock @acsfd @acsmem
896 @c  mutex_unlock dup @aculock
897 @c  mem2chunk dup ok
898 @c  chunk_is_mmapped dup ok
899 @c  MALLOC_ZERO ok
900 @c   memset dup ok
901 This function allocates a block long enough to contain a vector of
902 @var{count} elements, each of size @var{eltsize}.  Its contents are
903 cleared to zero before @code{calloc} returns.
904 @end deftypefun
906 You could define @code{calloc} as follows:
908 @smallexample
909 void *
910 calloc (size_t count, size_t eltsize)
912   size_t size = count * eltsize;
913   void *value = malloc (size);
914   if (value != 0)
915     memset (value, 0, size);
916   return value;
918 @end smallexample
920 But in general, it is not guaranteed that @code{calloc} calls
921 @code{malloc} internally.  Therefore, if an application provides its own
922 @code{malloc}/@code{realloc}/@code{free} outside the C library, it
923 should always define @code{calloc}, too.
925 @node Aligned Memory Blocks
926 @subsubsection Allocating Aligned Memory Blocks
928 @cindex page boundary
929 @cindex alignment (with @code{malloc})
930 @pindex stdlib.h
931 The address of a block returned by @code{malloc} or @code{realloc} in
932 @gnusystems{} is always a multiple of eight (or sixteen on 64-bit
933 systems).  If you need a block whose address is a multiple of a higher
934 power of two than that, use @code{aligned_alloc} or @code{posix_memalign}.
935 @code{aligned_alloc} and @code{posix_memalign} are declared in
936 @file{stdlib.h}.
938 @deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size})
939 @standards{???, stdlib.h}
940 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
941 @c Alias to memalign.
942 The @code{aligned_alloc} function allocates a block of @var{size} bytes whose
943 address is a multiple of @var{alignment}.  The @var{alignment} must be a
944 power of two and @var{size} must be a multiple of @var{alignment}.
946 The @code{aligned_alloc} function returns a null pointer on error and sets
947 @code{errno} to one of the following values:
949 @table @code
950 @item ENOMEM
951 There was insufficient memory available to satisfy the request.
953 @item EINVAL
954 @var{alignment} is not a power of two.
956 This function was introduced in @w{ISO C11} and hence may have better
957 portability to modern non-POSIX systems than @code{posix_memalign}.
958 @end table
960 @end deftypefun
962 @deftypefun {void *} memalign (size_t @var{boundary}, size_t @var{size})
963 @standards{BSD, malloc.h}
964 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
965 @c Same issues as malloc.  The padding bytes are safely freed in
966 @c _int_memalign, with the arena still locked.
968 @c __libc_memalign @asulock @aculock @acsfd @acsmem
969 @c  *__memalign_hook dup unguarded
970 @c  __libc_malloc dup @asulock @aculock @acsfd @acsmem
971 @c  arena_get dup @asulock @aculock @acsfd @acsmem
972 @c  _int_memalign @acsfd @acsmem
973 @c   _int_malloc dup @acsfd @acsmem
974 @c   checked_request2size dup ok
975 @c   mem2chunk dup ok
976 @c   chunksize dup ok
977 @c   chunk_is_mmapped dup ok
978 @c   set_head dup ok
979 @c   chunk2mem dup ok
980 @c   set_inuse_bit_at_offset dup ok
981 @c   set_head_size dup ok
982 @c   _int_free (have_lock) dup @acsfd @acsmem
983 @c   chunk_at_offset dup ok
984 @c   check_inuse_chunk dup ok
985 @c  arena_get_retry dup @asulock @aculock @acsfd @acsmem
986 @c  mutex_unlock dup @aculock
987 The @code{memalign} function allocates a block of @var{size} bytes whose
988 address is a multiple of @var{boundary}.  The @var{boundary} must be a
989 power of two!  The function @code{memalign} works by allocating a
990 somewhat larger block, and then returning an address within the block
991 that is on the specified boundary.
993 The @code{memalign} function returns a null pointer on error and sets
994 @code{errno} to one of the following values:
996 @table @code
997 @item ENOMEM
998 There was insufficient memory available to satisfy the request.
1000 @item EINVAL
1001 @var{boundary} is not a power of two.
1003 @end table
1005 The @code{memalign} function is obsolete and @code{aligned_alloc} or
1006 @code{posix_memalign} should be used instead.
1007 @end deftypefun
1009 @deftypefun int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
1010 @standards{POSIX, stdlib.h}
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:
1026 @table @code
1027 @item ENOMEM
1028 There was insufficient memory available to satisfy the request.
1030 @item EINVAL
1031 @var{alignment} is not a power of two multiple of @code{sizeof (void *)}.
1033 @end table
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}.
1038 @end deftypefun
1040 @deftypefun {void *} valloc (size_t @var{size})
1041 @standards{BSD, malloc.h}
1042 @standards{BSD, stdlib.h}
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
1056 @c   strcspn dup 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 first argument.  It is implemented like this:
1071 @smallexample
1072 void *
1073 valloc (size_t size)
1075   return memalign (getpagesize (), size);
1077 @end smallexample
1079 @ref{Query Memory Parameters} for more information about the memory
1080 subsystem.
1082 The @code{valloc} function is obsolete and @code{aligned_alloc} or
1083 @code{posix_memalign} should be used instead.
1084 @end deftypefun
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}.
1092 @pindex 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
1100 @c  set_max_fast 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:
1107 @comment TODO: @item M_CHECK_ACTION
1108 @vtable @code
1109 @item M_MMAP_MAX
1110 The maximum number of chunks to allocate with @code{mmap}.  Setting this
1111 to zero disables all use of @code{mmap}.
1113 The default value of this parameter is @code{65536}.
1115 This parameter can also be set for the process at startup by setting the
1116 environment variable @env{MALLOC_MMAP_MAX_} to the desired value.
1118 @item M_MMAP_THRESHOLD
1119 All chunks larger than this value are allocated outside the normal
1120 heap, using the @code{mmap} system call.  This way it is guaranteed
1121 that the memory for these chunks can be returned to the system on
1122 @code{free}.  Note that requests smaller than this threshold might still
1123 be allocated via @code{mmap}.
1125 If this parameter is not set, the default value is set as 128 KiB and the
1126 threshold is adjusted dynamically to suit the allocation patterns of the
1127 program. If the parameter is set, the dynamic adjustment is disabled and the
1128 value is set statically to the input value.
1130 This parameter can also be set for the process at startup by setting the
1131 environment variable @env{MALLOC_MMAP_THRESHOLD_} to the desired value.
1132 @comment TODO: @item M_MXFAST
1134 @item M_PERTURB
1135 If non-zero, memory blocks are filled with values depending on some
1136 low order bits of this parameter when they are allocated (except when
1137 allocated by @code{calloc}) and freed.  This can be used to debug the
1138 use of uninitialized or freed heap memory.  Note that this option does not
1139 guarantee that the freed block will have any specific values.  It only
1140 guarantees that the content the block had before it was freed will be
1141 overwritten.
1143 The default value of this parameter is @code{0}.
1145 This parameter can also be set for the process at startup by setting the
1146 environment variable @env{MALLOC_MMAP_PERTURB_} to the desired value.
1148 @item M_TOP_PAD
1149 This parameter determines the amount of extra memory to obtain from the system
1150 when an arena needs to be extended.  It also specifies the number of bytes to
1151 retain when shrinking an arena.  This provides the necessary hysteresis in heap
1152 size such that excessive amounts of system calls can be avoided.
1154 The default value of this parameter is @code{0}.
1156 This parameter can also be set for the process at startup by setting the
1157 environment variable @env{MALLOC_TOP_PAD_} to the desired value.
1159 @item M_TRIM_THRESHOLD
1160 This is the minimum size (in bytes) of the top-most, releasable chunk
1161 that will trigger a system call in order to return memory to the system.
1163 If this parameter is not set, the default value is set as 128 KiB and the
1164 threshold is adjusted dynamically to suit the allocation patterns of the
1165 program. If the parameter is set, the dynamic adjustment is disabled and the
1166 value is set statically to the provided input.
1168 This parameter can also be set for the process at startup by setting the
1169 environment variable @env{MALLOC_TRIM_THRESHOLD_} to the desired value.
1171 @item M_ARENA_TEST
1172 This parameter specifies the number of arenas that can be created before the
1173 test on the limit to the number of arenas is conducted. The value is ignored if
1174 @code{M_ARENA_MAX} is set.
1176 The default value of this parameter is 2 on 32-bit systems and 8 on 64-bit
1177 systems.
1179 This parameter can also be set for the process at startup by setting the
1180 environment variable @env{MALLOC_ARENA_TEST} to the desired value.
1182 @item M_ARENA_MAX
1183 This parameter sets the number of arenas to use regardless of the number of
1184 cores in the system.
1186 The default value of this tunable is @code{0}, meaning that the limit on the
1187 number of arenas is determined by the number of CPU cores online. For 32-bit
1188 systems the limit is twice the number of cores online and on 64-bit systems, it
1189 is eight times the number of cores online.  Note that the default value is not
1190 derived from the default value of M_ARENA_TEST and is computed independently.
1192 This parameter can also be set for the process at startup by setting the
1193 environment variable @env{MALLOC_ARENA_MAX} to the desired value.
1194 @end vtable
1196 @end deftypefun
1198 @node Heap Consistency Checking
1199 @subsubsection Heap Consistency Checking
1201 @cindex heap consistency checking
1202 @cindex consistency checking, of heap
1204 You can ask @code{malloc} to check the consistency of dynamic memory by
1205 using the @code{mcheck} function.  This function is a GNU extension,
1206 declared in @file{mcheck.h}.
1207 @pindex mcheck.h
1209 @deftypefun int mcheck (void (*@var{abortfn}) (enum mcheck_status @var{status}))
1210 @standards{GNU, mcheck.h}
1211 @safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1212 @c The hooks must be set up before malloc is first used, which sort of
1213 @c implies @mtuinit/@asuinit but since the function is a no-op if malloc
1214 @c was already used, that doesn't pose any safety issues.  The actual
1215 @c problem is with the hooks, designed for single-threaded
1216 @c fully-synchronous operation: they manage an unguarded linked list of
1217 @c allocated blocks, and get temporarily overwritten before calling the
1218 @c allocation functions recursively while holding the old hooks.  There
1219 @c are no guards for thread safety, and inconsistent hooks may be found
1220 @c within signal handlers or left behind in case of cancellation.
1222 Calling @code{mcheck} tells @code{malloc} to perform occasional
1223 consistency checks.  These will catch things such as writing
1224 past the end of a block that was allocated with @code{malloc}.
1226 The @var{abortfn} argument is the function to call when an inconsistency
1227 is found.  If you supply a null pointer, then @code{mcheck} uses a
1228 default function which prints a message and calls @code{abort}
1229 (@pxref{Aborting a Program}).  The function you supply is called with
1230 one argument, which says what sort of inconsistency was detected; its
1231 type is described below.
1233 It is too late to begin allocation checking once you have allocated
1234 anything with @code{malloc}.  So @code{mcheck} does nothing in that
1235 case.  The function returns @code{-1} if you call it too late, and
1236 @code{0} otherwise (when it is successful).
1238 The easiest way to arrange to call @code{mcheck} early enough is to use
1239 the option @samp{-lmcheck} when you link your program; then you don't
1240 need to modify your program source at all.  Alternatively you might use
1241 a debugger to insert a call to @code{mcheck} whenever the program is
1242 started, for example these gdb commands will automatically call @code{mcheck}
1243 whenever the program starts:
1245 @smallexample
1246 (gdb) break main
1247 Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10
1248 (gdb) command 1
1249 Type commands for when breakpoint 1 is hit, one per line.
1250 End with a line saying just "end".
1251 >call mcheck(0)
1252 >continue
1253 >end
1254 (gdb) @dots{}
1255 @end smallexample
1257 This will however only work if no initialization function of any object
1258 involved calls any of the @code{malloc} functions since @code{mcheck}
1259 must be called before the first such function.
1261 @end deftypefun
1263 @deftypefun {enum mcheck_status} mprobe (void *@var{pointer})
1264 @safety{@prelim{}@mtunsafe{@mtasurace{:mcheck} @mtasuconst{:malloc_hooks}}@asunsafe{@asucorrupt{}}@acunsafe{@acucorrupt{}}}
1265 @c The linked list of headers may be modified concurrently by other
1266 @c threads, and it may find a partial update if called from a signal
1267 @c handler.  It's mostly read only, so cancelling it might be safe, but
1268 @c it will modify global state that, if cancellation hits at just the
1269 @c right spot, may be left behind inconsistent.  This path is only taken
1270 @c if checkhdr finds an inconsistency.  If the inconsistency could only
1271 @c occur because of earlier undefined behavior, that wouldn't be an
1272 @c additional safety issue problem, but because of the other concurrency
1273 @c issues in the mcheck hooks, the apparent inconsistency could be the
1274 @c result of mcheck's own internal data race.  So, AC-Unsafe it is.
1276 The @code{mprobe} function lets you explicitly check for inconsistencies
1277 in a particular allocated block.  You must have already called
1278 @code{mcheck} at the beginning of the program, to do its occasional
1279 checks; calling @code{mprobe} requests an additional consistency check
1280 to be done at the time of the call.
1282 The argument @var{pointer} must be a pointer returned by @code{malloc}
1283 or @code{realloc}.  @code{mprobe} returns a value that says what
1284 inconsistency, if any, was found.  The values are described below.
1285 @end deftypefun
1287 @deftp {Data Type} {enum mcheck_status}
1288 This enumerated type describes what kind of inconsistency was detected
1289 in an allocated block, if any.  Here are the possible values:
1291 @table @code
1292 @item MCHECK_DISABLED
1293 @code{mcheck} was not called before the first allocation.
1294 No consistency checking can be done.
1295 @item MCHECK_OK
1296 No inconsistency detected.
1297 @item MCHECK_HEAD
1298 The data immediately before the block was modified.
1299 This commonly happens when an array index or pointer
1300 is decremented too far.
1301 @item MCHECK_TAIL
1302 The data immediately after the block was modified.
1303 This commonly happens when an array index or pointer
1304 is incremented too far.
1305 @item MCHECK_FREE
1306 The block was already freed.
1307 @end table
1308 @end deftp
1310 Another possibility to check for and guard against bugs in the use of
1311 @code{malloc}, @code{realloc} and @code{free} is to set the environment
1312 variable @code{MALLOC_CHECK_}.  When @code{MALLOC_CHECK_} is set, a
1313 special (less efficient) implementation is used which is designed to be
1314 tolerant against simple errors, such as double calls of @code{free} with
1315 the same argument, or overruns of a single byte (off-by-one bugs).  Not
1316 all such errors can be protected against, however, and memory leaks can
1317 result.  If @code{MALLOC_CHECK_} is set to @code{0}, any detected heap
1318 corruption is silently ignored; if set to @code{1}, a diagnostic is
1319 printed on @code{stderr}; if set to @code{2}, @code{abort} is called
1320 immediately.  This can be useful because otherwise a crash may happen
1321 much later, and the true cause for the problem is then very hard to
1322 track down.
1324 There is one problem with @code{MALLOC_CHECK_}: in SUID or SGID binaries
1325 it could possibly be exploited since diverging from the normal programs
1326 behavior it now writes something to the standard error descriptor.
1327 Therefore the use of @code{MALLOC_CHECK_} is disabled by default for
1328 SUID and SGID binaries.  It can be enabled again by the system
1329 administrator by adding a file @file{/etc/suid-debug} (the content is
1330 not important it could be empty).
1332 So, what's the difference between using @code{MALLOC_CHECK_} and linking
1333 with @samp{-lmcheck}?  @code{MALLOC_CHECK_} is orthogonal with respect to
1334 @samp{-lmcheck}.  @samp{-lmcheck} has been added for backward
1335 compatibility.  Both @code{MALLOC_CHECK_} and @samp{-lmcheck} should
1336 uncover the same bugs - but using @code{MALLOC_CHECK_} you don't need to
1337 recompile your application.
1339 @node Hooks for Malloc
1340 @subsubsection Memory Allocation Hooks
1341 @cindex allocation hooks, for @code{malloc}
1343 @Theglibc{} lets you modify the behavior of @code{malloc},
1344 @code{realloc}, and @code{free} by specifying appropriate hook
1345 functions.  You can use these hooks to help you debug programs that use
1346 dynamic memory allocation, for example.
1348 The hook variables are declared in @file{malloc.h}.
1349 @pindex malloc.h
1351 @defvar __malloc_hook
1352 @standards{GNU, malloc.h}
1353 The value of this variable is a pointer to the function that
1354 @code{malloc} uses whenever it is called.  You should define this
1355 function to look like @code{malloc}; that is, like:
1357 @smallexample
1358 void *@var{function} (size_t @var{size}, const void *@var{caller})
1359 @end smallexample
1361 The value of @var{caller} is the return address found on the stack when
1362 the @code{malloc} function was called.  This value allows you to trace
1363 the memory consumption of the program.
1364 @end defvar
1366 @defvar __realloc_hook
1367 @standards{GNU, malloc.h}
1368 The value of this variable is a pointer to function that @code{realloc}
1369 uses whenever it is called.  You should define this function to look
1370 like @code{realloc}; that is, like:
1372 @smallexample
1373 void *@var{function} (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
1374 @end smallexample
1376 The value of @var{caller} is the return address found on the stack when
1377 the @code{realloc} function was called.  This value allows you to trace the
1378 memory consumption of the program.
1379 @end defvar
1381 @defvar __free_hook
1382 @standards{GNU, malloc.h}
1383 The value of this variable is a pointer to function that @code{free}
1384 uses whenever it is called.  You should define this function to look
1385 like @code{free}; that is, like:
1387 @smallexample
1388 void @var{function} (void *@var{ptr}, const void *@var{caller})
1389 @end smallexample
1391 The value of @var{caller} is the return address found on the stack when
1392 the @code{free} function was called.  This value allows you to trace the
1393 memory consumption of the program.
1394 @end defvar
1396 @defvar __memalign_hook
1397 @standards{GNU, malloc.h}
1398 The value of this variable is a pointer to function that @code{aligned_alloc},
1399 @code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they
1400 are called.  You should define this function to look like @code{aligned_alloc};
1401 that is, like:
1403 @smallexample
1404 void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller})
1405 @end smallexample
1407 The value of @var{caller} is the return address found on the stack when
1408 the @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} or
1409 @code{valloc} functions are called.  This value allows you to trace the
1410 memory consumption of the program.
1411 @end defvar
1413 You must make sure that the function you install as a hook for one of
1414 these functions does not call that function recursively without restoring
1415 the old value of the hook first!  Otherwise, your program will get stuck
1416 in an infinite recursion.  Before calling the function recursively, one
1417 should make sure to restore all the hooks to their previous value.  When
1418 coming back from the recursive call, all the hooks should be resaved
1419 since a hook might modify itself.
1421 An issue to look out for is the time at which the malloc hook functions
1422 can be safely installed.  If the hook functions call the malloc-related
1423 functions recursively, it is necessary that malloc has already properly
1424 initialized itself at the time when @code{__malloc_hook} etc. is
1425 assigned to.  On the other hand, if the hook functions provide a
1426 complete malloc implementation of their own, it is vital that the hooks
1427 are assigned to @emph{before} the very first @code{malloc} call has
1428 completed, because otherwise a chunk obtained from the ordinary,
1429 un-hooked malloc may later be handed to @code{__free_hook}, for example.
1431 Here is an example showing how to use @code{__malloc_hook} and
1432 @code{__free_hook} properly.  It installs a function that prints out
1433 information every time @code{malloc} or @code{free} is called.  We just
1434 assume here that @code{realloc} and @code{memalign} are not used in our
1435 program.
1437 @smallexample
1438 /* Prototypes for __malloc_hook, __free_hook */
1439 #include <malloc.h>
1441 /* Prototypes for our hooks.  */
1442 static void my_init_hook (void);
1443 static void *my_malloc_hook (size_t, const void *);
1444 static void my_free_hook (void*, const void *);
1446 static void
1447 my_init (void)
1449   old_malloc_hook = __malloc_hook;
1450   old_free_hook = __free_hook;
1451   __malloc_hook = my_malloc_hook;
1452   __free_hook = my_free_hook;
1455 static void *
1456 my_malloc_hook (size_t size, const void *caller)
1458   void *result;
1459   /* Restore all old hooks */
1460   __malloc_hook = old_malloc_hook;
1461   __free_hook = old_free_hook;
1462   /* Call recursively */
1463   result = malloc (size);
1464   /* Save underlying hooks */
1465   old_malloc_hook = __malloc_hook;
1466   old_free_hook = __free_hook;
1467   /* @r{@code{printf} might call @code{malloc}, so protect it too.} */
1468   printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
1469   /* Restore our own hooks */
1470   __malloc_hook = my_malloc_hook;
1471   __free_hook = my_free_hook;
1472   return result;
1475 static void
1476 my_free_hook (void *ptr, const void *caller)
1478   /* Restore all old hooks */
1479   __malloc_hook = old_malloc_hook;
1480   __free_hook = old_free_hook;
1481   /* Call recursively */
1482   free (ptr);
1483   /* Save underlying hooks */
1484   old_malloc_hook = __malloc_hook;
1485   old_free_hook = __free_hook;
1486   /* @r{@code{printf} might call @code{free}, so protect it too.} */
1487   printf ("freed pointer %p\n", ptr);
1488   /* Restore our own hooks */
1489   __malloc_hook = my_malloc_hook;
1490   __free_hook = my_free_hook;
1493 main ()
1495   my_init ();
1496   @dots{}
1498 @end smallexample
1500 The @code{mcheck} function (@pxref{Heap Consistency Checking}) works by
1501 installing such hooks.
1503 @c __morecore, __after_morecore_hook are undocumented
1504 @c It's not clear whether to document them.
1506 @node Statistics of Malloc
1507 @subsubsection Statistics for Memory Allocation with @code{malloc}
1509 @cindex allocation statistics
1510 You can get information about dynamic memory allocation by calling the
1511 @code{mallinfo} function.  This function and its associated data type
1512 are declared in @file{malloc.h}; they are an extension of the standard
1513 SVID/XPG version.
1514 @pindex malloc.h
1516 @deftp {Data Type} {struct mallinfo}
1517 @standards{GNU, malloc.h}
1518 This structure type is used to return information about the dynamic
1519 memory allocator.  It contains the following members:
1521 @table @code
1522 @item int arena
1523 This is the total size of memory allocated with @code{sbrk} by
1524 @code{malloc}, in bytes.
1526 @item int ordblks
1527 This is the number of chunks not in use.  (The memory allocator
1528 internally gets chunks of memory from the operating system, and then
1529 carves them up to satisfy individual @code{malloc} requests;
1530 @pxref{The GNU Allocator}.)
1532 @item int smblks
1533 This field is unused.
1535 @item int hblks
1536 This is the total number of chunks allocated with @code{mmap}.
1538 @item int hblkhd
1539 This is the total size of memory allocated with @code{mmap}, in bytes.
1541 @item int usmblks
1542 This field is unused and always 0.
1544 @item int fsmblks
1545 This field is unused.
1547 @item int uordblks
1548 This is the total size of memory occupied by chunks handed out by
1549 @code{malloc}.
1551 @item int fordblks
1552 This is the total size of memory occupied by free (not in use) chunks.
1554 @item int keepcost
1555 This is the size of the top-most releasable chunk that normally
1556 borders the end of the heap (i.e., the high end of the virtual address
1557 space's data segment).
1559 @end table
1560 @end deftp
1562 @deftypefun {struct mallinfo} mallinfo (void)
1563 @standards{SVID, malloc.h}
1564 @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
1565 @c Accessing mp_.n_mmaps and mp_.max_mmapped_mem, modified with atomics
1566 @c but non-atomically elsewhere, may get us inconsistent results.  We
1567 @c mark the statistics as unsafe, rather than the fast-path functions
1568 @c that collect the possibly inconsistent data.
1570 @c __libc_mallinfo @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock
1571 @c  ptmalloc_init (once) dup @mtsenv @asulock @aculock @acsfd @acsmem
1572 @c  mutex_lock dup @asulock @aculock
1573 @c  int_mallinfo @mtasuconst:mallopt [mp_ access on main_arena]
1574 @c   malloc_consolidate dup ok
1575 @c   check_malloc_state dup ok/disabled
1576 @c   chunksize dup ok
1577 @c   fastbin dupo ok
1578 @c   bin_at dup ok
1579 @c   last dup ok
1580 @c  mutex_unlock @aculock
1582 This function returns information about the current dynamic memory usage
1583 in a structure of type @code{struct mallinfo}.
1584 @end deftypefun
1586 @node Summary of Malloc
1587 @subsubsection Summary of @code{malloc}-Related Functions
1589 Here is a summary of the functions that work with @code{malloc}:
1591 @table @code
1592 @item void *malloc (size_t @var{size})
1593 Allocate a block of @var{size} bytes.  @xref{Basic Allocation}.
1595 @item void free (void *@var{addr})
1596 Free a block previously allocated by @code{malloc}.  @xref{Freeing after
1597 Malloc}.
1599 @item void *realloc (void *@var{addr}, size_t @var{size})
1600 Make a block previously allocated by @code{malloc} larger or smaller,
1601 possibly by copying it to a new location.  @xref{Changing Block Size}.
1603 @item void *reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size})
1604 Change the size of a block previously allocated by @code{malloc} to
1605 @code{@var{nmemb} * @var{size}} bytes as with @code{realloc}.  @xref{Changing
1606 Block Size}.
1608 @item void *calloc (size_t @var{count}, size_t @var{eltsize})
1609 Allocate a block of @var{count} * @var{eltsize} bytes using
1610 @code{malloc}, and set its contents to zero.  @xref{Allocating Cleared
1611 Space}.
1613 @item void *valloc (size_t @var{size})
1614 Allocate a block of @var{size} bytes, starting on a page boundary.
1615 @xref{Aligned Memory Blocks}.
1617 @item void *aligned_alloc (size_t @var{size}, size_t @var{alignment})
1618 Allocate a block of @var{size} bytes, starting on an address that is a
1619 multiple of @var{alignment}.  @xref{Aligned Memory Blocks}.
1621 @item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
1622 Allocate a block of @var{size} bytes, starting on an address that is a
1623 multiple of @var{alignment}.  @xref{Aligned Memory Blocks}.
1625 @item void *memalign (size_t @var{size}, size_t @var{boundary})
1626 Allocate a block of @var{size} bytes, starting on an address that is a
1627 multiple of @var{boundary}.  @xref{Aligned Memory Blocks}.
1629 @item int mallopt (int @var{param}, int @var{value})
1630 Adjust a tunable parameter.  @xref{Malloc Tunable Parameters}.
1632 @item int mcheck (void (*@var{abortfn}) (void))
1633 Tell @code{malloc} to perform occasional consistency checks on
1634 dynamically allocated memory, and to call @var{abortfn} when an
1635 inconsistency is found.  @xref{Heap Consistency Checking}.
1637 @item void *(*__malloc_hook) (size_t @var{size}, const void *@var{caller})
1638 A pointer to a function that @code{malloc} uses whenever it is called.
1640 @item void *(*__realloc_hook) (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
1641 A pointer to a function that @code{realloc} uses whenever it is called.
1643 @item void (*__free_hook) (void *@var{ptr}, const void *@var{caller})
1644 A pointer to a function that @code{free} uses whenever it is called.
1646 @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller})
1647 A pointer to a function that @code{aligned_alloc}, @code{memalign},
1648 @code{posix_memalign} and @code{valloc} use whenever they are called.
1650 @item struct mallinfo mallinfo (void)
1651 Return information about the current dynamic memory usage.
1652 @xref{Statistics of Malloc}.
1653 @end table
1655 @node Allocation Debugging
1656 @subsection Allocation Debugging
1657 @cindex allocation debugging
1658 @cindex malloc debugger
1660 A complicated task when programming with languages which do not use
1661 garbage collected dynamic memory allocation is to find memory leaks.
1662 Long running programs must ensure that dynamically allocated objects are
1663 freed at the end of their lifetime.  If this does not happen the system
1664 runs out of memory, sooner or later.
1666 The @code{malloc} implementation in @theglibc{} provides some
1667 simple means to detect such leaks and obtain some information to find
1668 the location.  To do this the application must be started in a special
1669 mode which is enabled by an environment variable.  There are no speed
1670 penalties for the program if the debugging mode is not enabled.
1672 @menu
1673 * Tracing malloc::               How to install the tracing functionality.
1674 * Using the Memory Debugger::    Example programs excerpts.
1675 * Tips for the Memory Debugger:: Some more or less clever ideas.
1676 * Interpreting the traces::      What do all these lines mean?
1677 @end menu
1679 @node Tracing malloc
1680 @subsubsection How to install the tracing functionality
1682 @deftypefun void mtrace (void)
1683 @standards{GNU, mcheck.h}
1684 @safety{@prelim{}@mtunsafe{@mtsenv{} @mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtuinit{}}@asunsafe{@asuinit{} @ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1685 @c Like the mcheck hooks, these are not designed with thread safety in
1686 @c mind, because the hook pointers are temporarily modified without
1687 @c regard to other threads, signals or cancellation.
1689 @c mtrace @mtuinit @mtasurace:mtrace @mtsenv @asuinit @ascuheap @asucorrupt @acuinit @acucorrupt @aculock @acsfd @acsmem
1690 @c  __libc_secure_getenv dup @mtsenv
1691 @c  malloc dup @ascuheap @acsmem
1692 @c  fopen dup @ascuheap @asulock @aculock @acsmem @acsfd
1693 @c  fcntl dup ok
1694 @c  setvbuf dup @aculock
1695 @c  fprintf dup (on newly-created stream) @aculock
1696 @c  __cxa_atexit (once) dup @asulock @aculock @acsmem
1697 @c  free dup @ascuheap @acsmem
1698 When the @code{mtrace} function is called it looks for an environment
1699 variable named @code{MALLOC_TRACE}.  This variable is supposed to
1700 contain a valid file name.  The user must have write access.  If the
1701 file already exists it is truncated.  If the environment variable is not
1702 set or it does not name a valid file which can be opened for writing
1703 nothing is done.  The behavior of @code{malloc} etc. is not changed.
1704 For obvious reasons this also happens if the application is installed
1705 with the SUID or SGID bit set.
1707 If the named file is successfully opened, @code{mtrace} installs special
1708 handlers for the functions @code{malloc}, @code{realloc}, and
1709 @code{free} (@pxref{Hooks for Malloc}).  From then on, all uses of these
1710 functions are traced and protocolled into the file.  There is now of
1711 course a speed penalty for all calls to the traced functions so tracing
1712 should not be enabled during normal use.
1714 This function is a GNU extension and generally not available on other
1715 systems.  The prototype can be found in @file{mcheck.h}.
1716 @end deftypefun
1718 @deftypefun void muntrace (void)
1719 @standards{GNU, mcheck.h}
1720 @safety{@prelim{}@mtunsafe{@mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{} @aculock{} @acsfd{}}}
1722 @c muntrace @mtasurace:mtrace @mtslocale @asucorrupt @ascuheap @acucorrupt @acsmem @aculock @acsfd
1723 @c  fprintf (fputs) dup @mtslocale @asucorrupt @ascuheap @acsmem @aculock @acucorrupt
1724 @c  fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
1725 The @code{muntrace} function can be called after @code{mtrace} was used
1726 to enable tracing the @code{malloc} calls.  If no (successful) call of
1727 @code{mtrace} was made @code{muntrace} does nothing.
1729 Otherwise it deinstalls the handlers for @code{malloc}, @code{realloc},
1730 and @code{free} and then closes the protocol file.  No calls are
1731 protocolled anymore and the program runs again at full speed.
1733 This function is a GNU extension and generally not available on other
1734 systems.  The prototype can be found in @file{mcheck.h}.
1735 @end deftypefun
1737 @node Using the Memory Debugger
1738 @subsubsection Example program excerpts
1740 Even though the tracing functionality does not influence the runtime
1741 behavior of the program it is not a good idea to call @code{mtrace} in
1742 all programs.  Just imagine that you debug a program using @code{mtrace}
1743 and all other programs used in the debugging session also trace their
1744 @code{malloc} calls.  The output file would be the same for all programs
1745 and thus is unusable.  Therefore one should call @code{mtrace} only if
1746 compiled for debugging.  A program could therefore start like this:
1748 @example
1749 #include <mcheck.h>
1752 main (int argc, char *argv[])
1754 #ifdef DEBUGGING
1755   mtrace ();
1756 #endif
1757   @dots{}
1759 @end example
1761 This is all that is needed if you want to trace the calls during the
1762 whole runtime of the program.  Alternatively you can stop the tracing at
1763 any time with a call to @code{muntrace}.  It is even possible to restart
1764 the tracing again with a new call to @code{mtrace}.  But this can cause
1765 unreliable results since there may be calls of the functions which are
1766 not called.  Please note that not only the application uses the traced
1767 functions, also libraries (including the C library itself) use these
1768 functions.
1770 This last point is also why it is not a good idea to call @code{muntrace}
1771 before the program terminates.  The libraries are informed about the
1772 termination of the program only after the program returns from
1773 @code{main} or calls @code{exit} and so cannot free the memory they use
1774 before this time.
1776 So the best thing one can do is to call @code{mtrace} as the very first
1777 function in the program and never call @code{muntrace}.  So the program
1778 traces almost all uses of the @code{malloc} functions (except those
1779 calls which are executed by constructors of the program or used
1780 libraries).
1782 @node Tips for the Memory Debugger
1783 @subsubsection Some more or less clever ideas
1785 You know the situation.  The program is prepared for debugging and in
1786 all debugging sessions it runs well.  But once it is started without
1787 debugging the error shows up.  A typical example is a memory leak that
1788 becomes visible only when we turn off the debugging.  If you foresee
1789 such situations you can still win.  Simply use something equivalent to
1790 the following little program:
1792 @example
1793 #include <mcheck.h>
1794 #include <signal.h>
1796 static void
1797 enable (int sig)
1799   mtrace ();
1800   signal (SIGUSR1, enable);
1803 static void
1804 disable (int sig)
1806   muntrace ();
1807   signal (SIGUSR2, disable);
1811 main (int argc, char *argv[])
1813   @dots{}
1815   signal (SIGUSR1, enable);
1816   signal (SIGUSR2, disable);
1818   @dots{}
1820 @end example
1822 I.e., the user can start the memory debugger any time s/he wants if the
1823 program was started with @code{MALLOC_TRACE} set in the environment.
1824 The output will of course not show the allocations which happened before
1825 the first signal but if there is a memory leak this will show up
1826 nevertheless.
1828 @node Interpreting the traces
1829 @subsubsection Interpreting the traces
1831 If you take a look at the output it will look similar to this:
1833 @example
1834 = Start
1835 @ [0x8048209] - 0x8064cc8
1836 @ [0x8048209] - 0x8064ce0
1837 @ [0x8048209] - 0x8064cf8
1838 @ [0x80481eb] + 0x8064c48 0x14
1839 @ [0x80481eb] + 0x8064c60 0x14
1840 @ [0x80481eb] + 0x8064c78 0x14
1841 @ [0x80481eb] + 0x8064c90 0x14
1842 = End
1843 @end example
1845 What this all means is not really important since the trace file is not
1846 meant to be read by a human.  Therefore no attention is given to
1847 readability.  Instead there is a program which comes with @theglibc{}
1848 which interprets the traces and outputs a summary in an
1849 user-friendly way.  The program is called @code{mtrace} (it is in fact a
1850 Perl script) and it takes one or two arguments.  In any case the name of
1851 the file with the trace output must be specified.  If an optional
1852 argument precedes the name of the trace file this must be the name of
1853 the program which generated the trace.
1855 @example
1856 drepper$ mtrace tst-mtrace log
1857 No memory leaks.
1858 @end example
1860 In this case the program @code{tst-mtrace} was run and it produced a
1861 trace file @file{log}.  The message printed by @code{mtrace} shows there
1862 are no problems with the code, all allocated memory was freed
1863 afterwards.
1865 If we call @code{mtrace} on the example trace given above we would get a
1866 different outout:
1868 @example
1869 drepper$ mtrace errlog
1870 - 0x08064cc8 Free 2 was never alloc'd 0x8048209
1871 - 0x08064ce0 Free 3 was never alloc'd 0x8048209
1872 - 0x08064cf8 Free 4 was never alloc'd 0x8048209
1874 Memory not freed:
1875 -----------------
1876    Address     Size     Caller
1877 0x08064c48     0x14  at 0x80481eb
1878 0x08064c60     0x14  at 0x80481eb
1879 0x08064c78     0x14  at 0x80481eb
1880 0x08064c90     0x14  at 0x80481eb
1881 @end example
1883 We have called @code{mtrace} with only one argument and so the script
1884 has no chance to find out what is meant with the addresses given in the
1885 trace.  We can do better:
1887 @example
1888 drepper$ mtrace tst errlog
1889 - 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
1890 - 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
1891 - 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39
1893 Memory not freed:
1894 -----------------
1895    Address     Size     Caller
1896 0x08064c48     0x14  at /home/drepper/tst.c:33
1897 0x08064c60     0x14  at /home/drepper/tst.c:33
1898 0x08064c78     0x14  at /home/drepper/tst.c:33
1899 0x08064c90     0x14  at /home/drepper/tst.c:33
1900 @end example
1902 Suddenly the output makes much more sense and the user can see
1903 immediately where the function calls causing the trouble can be found.
1905 Interpreting this output is not complicated.  There are at most two
1906 different situations being detected.  First, @code{free} was called for
1907 pointers which were never returned by one of the allocation functions.
1908 This is usually a very bad problem and what this looks like is shown in
1909 the first three lines of the output.  Situations like this are quite
1910 rare and if they appear they show up very drastically: the program
1911 normally crashes.
1913 The other situation which is much harder to detect are memory leaks.  As
1914 you can see in the output the @code{mtrace} function collects all this
1915 information and so can say that the program calls an allocation function
1916 from line 33 in the source file @file{/home/drepper/tst-mtrace.c} four
1917 times without freeing this memory before the program terminates.
1918 Whether this is a real problem remains to be investigated.
1920 @node Replacing malloc
1921 @subsection Replacing @code{malloc}
1923 @cindex @code{malloc} replacement
1924 @cindex @code{LD_PRELOAD} and @code{malloc}
1925 @cindex alternative @code{malloc} implementations
1926 @cindex customizing @code{malloc}
1927 @cindex interposing @code{malloc}
1928 @cindex preempting @code{malloc}
1929 @cindex replacing @code{malloc}
1930 @Theglibc{} supports replacing the built-in @code{malloc} implementation
1931 with a different allocator with the same interface.  For dynamically
1932 linked programs, this happens through ELF symbol interposition, either
1933 using shared object dependencies or @code{LD_PRELOAD}.  For static
1934 linking, the @code{malloc} replacement library must be linked in before
1935 linking against @code{libc.a} (explicitly or implicitly).
1937 @strong{Note:} Failure to provide a complete set of replacement
1938 functions (that is, all the functions used by the application,
1939 @theglibc{}, and other linked-in libraries) can lead to static linking
1940 failures, and, at run time, to heap corruption and application crashes.
1942 The minimum set of functions which has to be provided by a custom
1943 @code{malloc} is given in the table below.
1945 @table @code
1946 @item malloc
1947 @item free
1948 @item calloc
1949 @item realloc
1950 @end table
1952 These @code{malloc}-related functions are required for @theglibc{} to
1953 work.@footnote{Versions of @theglibc{} before 2.25 required that a
1954 custom @code{malloc} defines @code{__libc_memalign} (with the same
1955 interface as the @code{memalign} function).}
1957 The @code{malloc} implementation in @theglibc{} provides additional
1958 functionality not used by the library itself, but which is often used by
1959 other system libraries and applications.  A general-purpose replacement
1960 @code{malloc} implementation should provide definitions of these
1961 functions, too.  Their names are listed in the following table.
1963 @table @code
1964 @item aligned_alloc
1965 @item malloc_usable_size
1966 @item memalign
1967 @item posix_memalign
1968 @item pvalloc
1969 @item valloc
1970 @end table
1972 In addition, very old applications may use the obsolete @code{cfree}
1973 function.
1975 Further @code{malloc}-related functions such as @code{mallopt} or
1976 @code{mallinfo} will not have any effect or return incorrect statistics
1977 when a replacement @code{malloc} is in use.  However, failure to replace
1978 these functions typically does not result in crashes or other incorrect
1979 application behavior, but may result in static linking failures.
1981 @node Obstacks
1982 @subsection Obstacks
1983 @cindex obstacks
1985 An @dfn{obstack} is a pool of memory containing a stack of objects.  You
1986 can create any number of separate obstacks, and then allocate objects in
1987 specified obstacks.  Within each obstack, the last object allocated must
1988 always be the first one freed, but distinct obstacks are independent of
1989 each other.
1991 Aside from this one constraint of order of freeing, obstacks are totally
1992 general: an obstack can contain any number of objects of any size.  They
1993 are implemented with macros, so allocation is usually very fast as long as
1994 the objects are usually small.  And the only space overhead per object is
1995 the padding needed to start each object on a suitable boundary.
1997 @menu
1998 * Creating Obstacks::           How to declare an obstack in your program.
1999 * Preparing for Obstacks::      Preparations needed before you can
2000                                  use obstacks.
2001 * Allocation in an Obstack::    Allocating objects in an obstack.
2002 * Freeing Obstack Objects::     Freeing objects in an obstack.
2003 * Obstack Functions::           The obstack functions are both
2004                                  functions and macros.
2005 * Growing Objects::             Making an object bigger by stages.
2006 * Extra Fast Growing::          Extra-high-efficiency (though more
2007                                  complicated) growing objects.
2008 * Status of an Obstack::        Inquiries about the status of an obstack.
2009 * Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
2010 * Obstack Chunks::              How obstacks obtain and release chunks;
2011                                  efficiency considerations.
2012 * Summary of Obstacks::
2013 @end menu
2015 @node Creating Obstacks
2016 @subsubsection Creating Obstacks
2018 The utilities for manipulating obstacks are declared in the header
2019 file @file{obstack.h}.
2020 @pindex obstack.h
2022 @deftp {Data Type} {struct obstack}
2023 @standards{GNU, obstack.h}
2024 An obstack is represented by a data structure of type @code{struct
2025 obstack}.  This structure has a small fixed size; it records the status
2026 of the obstack and how to find the space in which objects are allocated.
2027 It does not contain any of the objects themselves.  You should not try
2028 to access the contents of the structure directly; use only the functions
2029 described in this chapter.
2030 @end deftp
2032 You can declare variables of type @code{struct obstack} and use them as
2033 obstacks, or you can allocate obstacks dynamically like any other kind
2034 of object.  Dynamic allocation of obstacks allows your program to have a
2035 variable number of different stacks.  (You can even allocate an
2036 obstack structure in another obstack, but this is rarely useful.)
2038 All the functions that work with obstacks require you to specify which
2039 obstack to use.  You do this with a pointer of type @code{struct obstack
2040 *}.  In the following, we often say ``an obstack'' when strictly
2041 speaking the object at hand is such a pointer.
2043 The objects in the obstack are packed into large blocks called
2044 @dfn{chunks}.  The @code{struct obstack} structure points to a chain of
2045 the chunks currently in use.
2047 The obstack library obtains a new chunk whenever you allocate an object
2048 that won't fit in the previous chunk.  Since the obstack library manages
2049 chunks automatically, you don't need to pay much attention to them, but
2050 you do need to supply a function which the obstack library should use to
2051 get a chunk.  Usually you supply a function which uses @code{malloc}
2052 directly or indirectly.  You must also supply a function to free a chunk.
2053 These matters are described in the following section.
2055 @node Preparing for Obstacks
2056 @subsubsection Preparing for Using Obstacks
2058 Each source file in which you plan to use the obstack functions
2059 must include the header file @file{obstack.h}, like this:
2061 @smallexample
2062 #include <obstack.h>
2063 @end smallexample
2065 @findex obstack_chunk_alloc
2066 @findex obstack_chunk_free
2067 Also, if the source file uses the macro @code{obstack_init}, it must
2068 declare or define two functions or macros that will be called by the
2069 obstack library.  One, @code{obstack_chunk_alloc}, is used to allocate
2070 the chunks of memory into which objects are packed.  The other,
2071 @code{obstack_chunk_free}, is used to return chunks when the objects in
2072 them are freed.  These macros should appear before any use of obstacks
2073 in the source file.
2075 Usually these are defined to use @code{malloc} via the intermediary
2076 @code{xmalloc} (@pxref{Unconstrained Allocation}).  This is done with
2077 the following pair of macro definitions:
2079 @smallexample
2080 #define obstack_chunk_alloc xmalloc
2081 #define obstack_chunk_free free
2082 @end smallexample
2084 @noindent
2085 Though the memory you get using obstacks really comes from @code{malloc},
2086 using obstacks is faster because @code{malloc} is called less often, for
2087 larger blocks of memory.  @xref{Obstack Chunks}, for full details.
2089 At run time, before the program can use a @code{struct obstack} object
2090 as an obstack, it must initialize the obstack by calling
2091 @code{obstack_init}.
2093 @deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
2094 @standards{GNU, obstack.h}
2095 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{@acsmem{}}}
2096 @c obstack_init @mtsrace:obstack-ptr @acsmem
2097 @c  _obstack_begin @acsmem
2098 @c    chunkfun = obstack_chunk_alloc (suggested malloc)
2099 @c    freefun = obstack_chunk_free (suggested free)
2100 @c   *chunkfun @acsmem
2101 @c    obstack_chunk_alloc user-supplied
2102 @c   *obstack_alloc_failed_handler user-supplied
2103 @c    -> print_and_abort (default)
2105 @c print_and_abort
2106 @c  _ dup @ascuintl
2107 @c  fxprintf dup @asucorrupt @aculock @acucorrupt
2108 @c  exit @acucorrupt?
2109 Initialize obstack @var{obstack-ptr} for allocation of objects.  This
2110 function calls the obstack's @code{obstack_chunk_alloc} function.  If
2111 allocation of memory fails, the function pointed to by
2112 @code{obstack_alloc_failed_handler} is called.  The @code{obstack_init}
2113 function always returns 1 (Compatibility notice: Former versions of
2114 obstack returned 0 if allocation failed).
2115 @end deftypefun
2117 Here are two examples of how to allocate the space for an obstack and
2118 initialize it.  First, an obstack that is a static variable:
2120 @smallexample
2121 static struct obstack myobstack;
2122 @dots{}
2123 obstack_init (&myobstack);
2124 @end smallexample
2126 @noindent
2127 Second, an obstack that is itself dynamically allocated:
2129 @smallexample
2130 struct obstack *myobstack_ptr
2131   = (struct obstack *) xmalloc (sizeof (struct obstack));
2133 obstack_init (myobstack_ptr);
2134 @end smallexample
2136 @defvar obstack_alloc_failed_handler
2137 @standards{GNU, obstack.h}
2138 The value of this variable is a pointer to a function that
2139 @code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
2140 memory.  The default action is to print a message and abort.
2141 You should supply a function that either calls @code{exit}
2142 (@pxref{Program Termination}) or @code{longjmp} (@pxref{Non-Local
2143 Exits}) and doesn't return.
2145 @smallexample
2146 void my_obstack_alloc_failed (void)
2147 @dots{}
2148 obstack_alloc_failed_handler = &my_obstack_alloc_failed;
2149 @end smallexample
2151 @end defvar
2153 @node Allocation in an Obstack
2154 @subsubsection Allocation in an Obstack
2155 @cindex allocation (obstacks)
2157 The most direct way to allocate an object in an obstack is with
2158 @code{obstack_alloc}, which is invoked almost like @code{malloc}.
2160 @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
2161 @standards{GNU, obstack.h}
2162 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2163 @c obstack_alloc @mtsrace:obstack-ptr @acucorrupt @acsmem
2164 @c  obstack_blank dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2165 @c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2166 This allocates an uninitialized block of @var{size} bytes in an obstack
2167 and returns its address.  Here @var{obstack-ptr} specifies which obstack
2168 to allocate the block in; it is the address of the @code{struct obstack}
2169 object which represents the obstack.  Each obstack function or macro
2170 requires you to specify an @var{obstack-ptr} as the first argument.
2172 This function calls the obstack's @code{obstack_chunk_alloc} function if
2173 it needs to allocate a new chunk of memory; it calls
2174 @code{obstack_alloc_failed_handler} if allocation of memory by
2175 @code{obstack_chunk_alloc} failed.
2176 @end deftypefun
2178 For example, here is a function that allocates a copy of a string @var{str}
2179 in a specific obstack, which is in the variable @code{string_obstack}:
2181 @smallexample
2182 struct obstack string_obstack;
2184 char *
2185 copystring (char *string)
2187   size_t len = strlen (string) + 1;
2188   char *s = (char *) obstack_alloc (&string_obstack, len);
2189   memcpy (s, string, len);
2190   return s;
2192 @end smallexample
2194 To allocate a block with specified contents, use the function
2195 @code{obstack_copy}, declared like this:
2197 @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2198 @standards{GNU, obstack.h}
2199 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2200 @c obstack_copy @mtsrace:obstack-ptr @acucorrupt @acsmem
2201 @c  obstack_grow dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2202 @c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2203 This allocates a block and initializes it by copying @var{size}
2204 bytes of data starting at @var{address}.  It calls
2205 @code{obstack_alloc_failed_handler} if allocation of memory by
2206 @code{obstack_chunk_alloc} failed.
2207 @end deftypefun
2209 @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2210 @standards{GNU, obstack.h}
2211 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2212 @c obstack_copy0 @mtsrace:obstack-ptr @acucorrupt @acsmem
2213 @c  obstack_grow0 dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2214 @c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2215 Like @code{obstack_copy}, but appends an extra byte containing a null
2216 character.  This extra byte is not counted in the argument @var{size}.
2217 @end deftypefun
2219 The @code{obstack_copy0} function is convenient for copying a sequence
2220 of characters into an obstack as a null-terminated string.  Here is an
2221 example of its use:
2223 @smallexample
2224 char *
2225 obstack_savestring (char *addr, int size)
2227   return obstack_copy0 (&myobstack, addr, size);
2229 @end smallexample
2231 @noindent
2232 Contrast this with the previous example of @code{savestring} using
2233 @code{malloc} (@pxref{Basic Allocation}).
2235 @node Freeing Obstack Objects
2236 @subsubsection Freeing Objects in an Obstack
2237 @cindex freeing (obstacks)
2239 To free an object allocated in an obstack, use the function
2240 @code{obstack_free}.  Since the obstack is a stack of objects, freeing
2241 one object automatically frees all other objects allocated more recently
2242 in the same obstack.
2244 @deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
2245 @standards{GNU, obstack.h}
2246 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
2247 @c obstack_free @mtsrace:obstack-ptr @acucorrupt
2248 @c  (obstack_free) @mtsrace:obstack-ptr @acucorrupt
2249 @c   *freefun dup user-supplied
2250 If @var{object} is a null pointer, everything allocated in the obstack
2251 is freed.  Otherwise, @var{object} must be the address of an object
2252 allocated in the obstack.  Then @var{object} is freed, along with
2253 everything allocated in @var{obstack-ptr} since @var{object}.
2254 @end deftypefun
2256 Note that if @var{object} is a null pointer, the result is an
2257 uninitialized obstack.  To free all memory in an obstack but leave it
2258 valid for further allocation, call @code{obstack_free} with the address
2259 of the first object allocated on the obstack:
2261 @smallexample
2262 obstack_free (obstack_ptr, first_object_allocated_ptr);
2263 @end smallexample
2265 Recall that the objects in an obstack are grouped into chunks.  When all
2266 the objects in a chunk become free, the obstack library automatically
2267 frees the chunk (@pxref{Preparing for Obstacks}).  Then other
2268 obstacks, or non-obstack allocation, can reuse the space of the chunk.
2270 @node Obstack Functions
2271 @subsubsection Obstack Functions and Macros
2272 @cindex macros
2274 The interfaces for using obstacks may be defined either as functions or
2275 as macros, depending on the compiler.  The obstack facility works with
2276 all C compilers, including both @w{ISO C} and traditional C, but there are
2277 precautions you must take if you plan to use compilers other than GNU C.
2279 If you are using an old-fashioned @w{non-ISO C} compiler, all the obstack
2280 ``functions'' are actually defined only as macros.  You can call these
2281 macros like functions, but you cannot use them in any other way (for
2282 example, you cannot take their address).
2284 Calling the macros requires a special precaution: namely, the first
2285 operand (the obstack pointer) may not contain any side effects, because
2286 it may be computed more than once.  For example, if you write this:
2288 @smallexample
2289 obstack_alloc (get_obstack (), 4);
2290 @end smallexample
2292 @noindent
2293 you will find that @code{get_obstack} may be called several times.
2294 If you use @code{*obstack_list_ptr++} as the obstack pointer argument,
2295 you will get very strange results since the incrementation may occur
2296 several times.
2298 In @w{ISO C}, each function has both a macro definition and a function
2299 definition.  The function definition is used if you take the address of the
2300 function without calling it.  An ordinary call uses the macro definition by
2301 default, but you can request the function definition instead by writing the
2302 function name in parentheses, as shown here:
2304 @smallexample
2305 char *x;
2306 void *(*funcp) ();
2307 /* @r{Use the macro}.  */
2308 x = (char *) obstack_alloc (obptr, size);
2309 /* @r{Call the function}.  */
2310 x = (char *) (obstack_alloc) (obptr, size);
2311 /* @r{Take the address of the function}.  */
2312 funcp = obstack_alloc;
2313 @end smallexample
2315 @noindent
2316 This is the same situation that exists in @w{ISO C} for the standard library
2317 functions.  @xref{Macro Definitions}.
2319 @strong{Warning:} When you do use the macros, you must observe the
2320 precaution of avoiding side effects in the first operand, even in @w{ISO C}.
2322 If you use the GNU C compiler, this precaution is not necessary, because
2323 various language extensions in GNU C permit defining the macros so as to
2324 compute each argument only once.
2326 @node Growing Objects
2327 @subsubsection Growing Objects
2328 @cindex growing objects (in obstacks)
2329 @cindex changing the size of a block (obstacks)
2331 Because memory in obstack chunks is used sequentially, it is possible to
2332 build up an object step by step, adding one or more bytes at a time to the
2333 end of the object.  With this technique, you do not need to know how much
2334 data you will put in the object until you come to the end of it.  We call
2335 this the technique of @dfn{growing objects}.  The special functions
2336 for adding data to the growing object are described in this section.
2338 You don't need to do anything special when you start to grow an object.
2339 Using one of the functions to add data to the object automatically
2340 starts it.  However, it is necessary to say explicitly when the object is
2341 finished.  This is done with the function @code{obstack_finish}.
2343 The actual address of the object thus built up is not known until the
2344 object is finished.  Until then, it always remains possible that you will
2345 add so much data that the object must be copied into a new chunk.
2347 While the obstack is in use for a growing object, you cannot use it for
2348 ordinary allocation of another object.  If you try to do so, the space
2349 already added to the growing object will become part of the other object.
2351 @deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
2352 @standards{GNU, obstack.h}
2353 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2354 @c obstack_blank @mtsrace:obstack-ptr @acucorrupt @acsmem
2355 @c  _obstack_newchunk @mtsrace:obstack-ptr @acucorrupt @acsmem
2356 @c   *chunkfun dup @acsmem
2357 @c   *obstack_alloc_failed_handler dup user-supplied
2358 @c   *freefun
2359 @c  obstack_blank_fast dup @mtsrace:obstack-ptr
2360 The most basic function for adding to a growing object is
2361 @code{obstack_blank}, which adds space without initializing it.
2362 @end deftypefun
2364 @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
2365 @standards{GNU, obstack.h}
2366 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2367 @c obstack_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2368 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2369 @c  memcpy ok
2370 To add a block of initialized space, use @code{obstack_grow}, which is
2371 the growing-object analogue of @code{obstack_copy}.  It adds @var{size}
2372 bytes of data to the growing object, copying the contents from
2373 @var{data}.
2374 @end deftypefun
2376 @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
2377 @standards{GNU, obstack.h}
2378 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2379 @c obstack_grow0 @mtsrace:obstack-ptr @acucorrupt @acsmem
2380 @c   (no sequence point between storing NUL and incrementing next_free)
2381 @c   (multiple changes to next_free => @acucorrupt)
2382 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2383 @c  memcpy ok
2384 This is the growing-object analogue of @code{obstack_copy0}.  It adds
2385 @var{size} bytes copied from @var{data}, followed by an additional null
2386 character.
2387 @end deftypefun
2389 @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
2390 @standards{GNU, obstack.h}
2391 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2392 @c obstack_1grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2393 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2394 @c  obstack_1grow_fast dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2395 To add one character at a time, use the function @code{obstack_1grow}.
2396 It adds a single byte containing @var{c} to the growing object.
2397 @end deftypefun
2399 @deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
2400 @standards{GNU, obstack.h}
2401 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2402 @c obstack_ptr_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2403 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2404 @c  obstack_ptr_grow_fast dup @mtsrace:obstack-ptr
2405 Adding the value of a pointer one can use the function
2406 @code{obstack_ptr_grow}.  It adds @code{sizeof (void *)} bytes
2407 containing the value of @var{data}.
2408 @end deftypefun
2410 @deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
2411 @standards{GNU, obstack.h}
2412 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2413 @c obstack_int_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2414 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2415 @c  obstack_int_grow_fast dup @mtsrace:obstack-ptr
2416 A single value of type @code{int} can be added by using the
2417 @code{obstack_int_grow} function.  It adds @code{sizeof (int)} bytes to
2418 the growing object and initializes them with the value of @var{data}.
2419 @end deftypefun
2421 @deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
2422 @standards{GNU, obstack.h}
2423 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
2424 @c obstack_finish @mtsrace:obstack-ptr @acucorrupt
2425 When you are finished growing the object, use the function
2426 @code{obstack_finish} to close it off and return its final address.
2428 Once you have finished the object, the obstack is available for ordinary
2429 allocation or for growing another object.
2431 This function can return a null pointer under the same conditions as
2432 @code{obstack_alloc} (@pxref{Allocation in an Obstack}).
2433 @end deftypefun
2435 When you build an object by growing it, you will probably need to know
2436 afterward how long it became.  You need not keep track of this as you grow
2437 the object, because you can find out the length from the obstack just
2438 before finishing the object with the function @code{obstack_object_size},
2439 declared as follows:
2441 @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
2442 @standards{GNU, obstack.h}
2443 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2444 This function returns the current size of the growing object, in bytes.
2445 Remember to call this function @emph{before} finishing the object.
2446 After it is finished, @code{obstack_object_size} will return zero.
2447 @end deftypefun
2449 If you have started growing an object and wish to cancel it, you should
2450 finish it and then free it, like this:
2452 @smallexample
2453 obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
2454 @end smallexample
2456 @noindent
2457 This has no effect if no object was growing.
2459 @cindex shrinking objects
2460 You can use @code{obstack_blank} with a negative size argument to make
2461 the current object smaller.  Just don't try to shrink it beyond zero
2462 length---there's no telling what will happen if you do that.
2464 @node Extra Fast Growing
2465 @subsubsection Extra Fast Growing Objects
2466 @cindex efficiency and obstacks
2468 The usual functions for growing objects incur overhead for checking
2469 whether there is room for the new growth in the current chunk.  If you
2470 are frequently constructing objects in small steps of growth, this
2471 overhead can be significant.
2473 You can reduce the overhead by using special ``fast growth''
2474 functions that grow the object without checking.  In order to have a
2475 robust program, you must do the checking yourself.  If you do this checking
2476 in the simplest way each time you are about to add data to the object, you
2477 have not saved anything, because that is what the ordinary growth
2478 functions do.  But if you can arrange to check less often, or check
2479 more efficiently, then you make the program faster.
2481 The function @code{obstack_room} returns the amount of room available
2482 in the current chunk.  It is declared as follows:
2484 @deftypefun int obstack_room (struct obstack *@var{obstack-ptr})
2485 @standards{GNU, obstack.h}
2486 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2487 This returns the number of bytes that can be added safely to the current
2488 growing object (or to an object about to be started) in obstack
2489 @var{obstack-ptr} using the fast growth functions.
2490 @end deftypefun
2492 While you know there is room, you can use these fast growth functions
2493 for adding data to a growing object:
2495 @deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
2496 @standards{GNU, obstack.h}
2497 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2498 @c obstack_1grow_fast @mtsrace:obstack-ptr @acucorrupt @acsmem
2499 @c   (no sequence point between copying c and incrementing next_free)
2500 The function @code{obstack_1grow_fast} adds one byte containing the
2501 character @var{c} to the growing object in obstack @var{obstack-ptr}.
2502 @end deftypefun
2504 @deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
2505 @standards{GNU, obstack.h}
2506 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2507 @c obstack_ptr_grow_fast @mtsrace:obstack-ptr
2508 The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
2509 bytes containing the value of @var{data} to the growing object in
2510 obstack @var{obstack-ptr}.
2511 @end deftypefun
2513 @deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
2514 @standards{GNU, obstack.h}
2515 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2516 @c obstack_int_grow_fast @mtsrace:obstack-ptr
2517 The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
2518 containing the value of @var{data} to the growing object in obstack
2519 @var{obstack-ptr}.
2520 @end deftypefun
2522 @deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
2523 @standards{GNU, obstack.h}
2524 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2525 @c obstack_blank_fast @mtsrace:obstack-ptr
2526 The function @code{obstack_blank_fast} adds @var{size} bytes to the
2527 growing object in obstack @var{obstack-ptr} without initializing them.
2528 @end deftypefun
2530 When you check for space using @code{obstack_room} and there is not
2531 enough room for what you want to add, the fast growth functions
2532 are not safe.  In this case, simply use the corresponding ordinary
2533 growth function instead.  Very soon this will copy the object to a
2534 new chunk; then there will be lots of room available again.
2536 So, each time you use an ordinary growth function, check afterward for
2537 sufficient space using @code{obstack_room}.  Once the object is copied
2538 to a new chunk, there will be plenty of space again, so the program will
2539 start using the fast growth functions again.
2541 Here is an example:
2543 @smallexample
2544 @group
2545 void
2546 add_string (struct obstack *obstack, const char *ptr, int len)
2548   while (len > 0)
2549     @{
2550       int room = obstack_room (obstack);
2551       if (room == 0)
2552         @{
2553           /* @r{Not enough room.  Add one character slowly,}
2554              @r{which may copy to a new chunk and make room.}  */
2555           obstack_1grow (obstack, *ptr++);
2556           len--;
2557         @}
2558       else
2559         @{
2560           if (room > len)
2561             room = len;
2562           /* @r{Add fast as much as we have room for.} */
2563           len -= room;
2564           while (room-- > 0)
2565             obstack_1grow_fast (obstack, *ptr++);
2566         @}
2567     @}
2569 @end group
2570 @end smallexample
2572 @node Status of an Obstack
2573 @subsubsection Status of an Obstack
2574 @cindex obstack status
2575 @cindex status of obstack
2577 Here are functions that provide information on the current status of
2578 allocation in an obstack.  You can use them to learn about an object while
2579 still growing it.
2581 @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
2582 @standards{GNU, obstack.h}
2583 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
2584 This function returns the tentative address of the beginning of the
2585 currently growing object in @var{obstack-ptr}.  If you finish the object
2586 immediately, it will have that address.  If you make it larger first, it
2587 may outgrow the current chunk---then its address will change!
2589 If no object is growing, this value says where the next object you
2590 allocate will start (once again assuming it fits in the current
2591 chunk).
2592 @end deftypefun
2594 @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
2595 @standards{GNU, obstack.h}
2596 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
2597 This function returns the address of the first free byte in the current
2598 chunk of obstack @var{obstack-ptr}.  This is the end of the currently
2599 growing object.  If no object is growing, @code{obstack_next_free}
2600 returns the same value as @code{obstack_base}.
2601 @end deftypefun
2603 @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
2604 @standards{GNU, obstack.h}
2605 @c dup
2606 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2607 This function returns the size in bytes of the currently growing object.
2608 This is equivalent to
2610 @smallexample
2611 obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})
2612 @end smallexample
2613 @end deftypefun
2615 @node Obstacks Data Alignment
2616 @subsubsection Alignment of Data in Obstacks
2617 @cindex alignment (in obstacks)
2619 Each obstack has an @dfn{alignment boundary}; each object allocated in
2620 the obstack automatically starts on an address that is a multiple of the
2621 specified boundary.  By default, this boundary is aligned so that
2622 the object can hold any type of data.
2624 To access an obstack's alignment boundary, use the macro
2625 @code{obstack_alignment_mask}, whose function prototype looks like
2626 this:
2628 @deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
2629 @standards{GNU, obstack.h}
2630 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2631 The value is a bit mask; a bit that is 1 indicates that the corresponding
2632 bit in the address of an object should be 0.  The mask value should be one
2633 less than a power of 2; the effect is that all object addresses are
2634 multiples of that power of 2.  The default value of the mask is a value
2635 that allows aligned objects to hold any type of data: for example, if
2636 its value is 3, any type of data can be stored at locations whose
2637 addresses are multiples of 4.  A mask value of 0 means an object can start
2638 on any multiple of 1 (that is, no alignment is required).
2640 The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
2641 so you can alter the mask by assignment.  For example, this statement:
2643 @smallexample
2644 obstack_alignment_mask (obstack_ptr) = 0;
2645 @end smallexample
2647 @noindent
2648 has the effect of turning off alignment processing in the specified obstack.
2649 @end deftypefn
2651 Note that a change in alignment mask does not take effect until
2652 @emph{after} the next time an object is allocated or finished in the
2653 obstack.  If you are not growing an object, you can make the new
2654 alignment mask take effect immediately by calling @code{obstack_finish}.
2655 This will finish a zero-length object and then do proper alignment for
2656 the next object.
2658 @node Obstack Chunks
2659 @subsubsection Obstack Chunks
2660 @cindex efficiency of chunks
2661 @cindex chunks
2663 Obstacks work by allocating space for themselves in large chunks, and
2664 then parceling out space in the chunks to satisfy your requests.  Chunks
2665 are normally 4096 bytes long unless you specify a different chunk size.
2666 The chunk size includes 8 bytes of overhead that are not actually used
2667 for storing objects.  Regardless of the specified size, longer chunks
2668 will be allocated when necessary for long objects.
2670 The obstack library allocates chunks by calling the function
2671 @code{obstack_chunk_alloc}, which you must define.  When a chunk is no
2672 longer needed because you have freed all the objects in it, the obstack
2673 library frees the chunk by calling @code{obstack_chunk_free}, which you
2674 must also define.
2676 These two must be defined (as macros) or declared (as functions) in each
2677 source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
2678 Most often they are defined as macros like this:
2680 @smallexample
2681 #define obstack_chunk_alloc malloc
2682 #define obstack_chunk_free free
2683 @end smallexample
2685 Note that these are simple macros (no arguments).  Macro definitions with
2686 arguments will not work!  It is necessary that @code{obstack_chunk_alloc}
2687 or @code{obstack_chunk_free}, alone, expand into a function name if it is
2688 not itself a function name.
2690 If you allocate chunks with @code{malloc}, the chunk size should be a
2691 power of 2.  The default chunk size, 4096, was chosen because it is long
2692 enough to satisfy many typical requests on the obstack yet short enough
2693 not to waste too much memory in the portion of the last chunk not yet used.
2695 @deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr})
2696 @standards{GNU, obstack.h}
2697 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2698 This returns the chunk size of the given obstack.
2699 @end deftypefn
2701 Since this macro expands to an lvalue, you can specify a new chunk size by
2702 assigning it a new value.  Doing so does not affect the chunks already
2703 allocated, but will change the size of chunks allocated for that particular
2704 obstack in the future.  It is unlikely to be useful to make the chunk size
2705 smaller, but making it larger might improve efficiency if you are
2706 allocating many objects whose size is comparable to the chunk size.  Here
2707 is how to do so cleanly:
2709 @smallexample
2710 if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
2711   obstack_chunk_size (obstack_ptr) = @var{new-chunk-size};
2712 @end smallexample
2714 @node Summary of Obstacks
2715 @subsubsection Summary of Obstack Functions
2717 Here is a summary of all the functions associated with obstacks.  Each
2718 takes the address of an obstack (@code{struct obstack *}) as its first
2719 argument.
2721 @table @code
2722 @item void obstack_init (struct obstack *@var{obstack-ptr})
2723 Initialize use of an obstack.  @xref{Creating Obstacks}.
2725 @item void *obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
2726 Allocate an object of @var{size} uninitialized bytes.
2727 @xref{Allocation in an Obstack}.
2729 @item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2730 Allocate an object of @var{size} bytes, with contents copied from
2731 @var{address}.  @xref{Allocation in an Obstack}.
2733 @item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2734 Allocate an object of @var{size}+1 bytes, with @var{size} of them copied
2735 from @var{address}, followed by a null character at the end.
2736 @xref{Allocation in an Obstack}.
2738 @item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
2739 Free @var{object} (and everything allocated in the specified obstack
2740 more recently than @var{object}).  @xref{Freeing Obstack Objects}.
2742 @item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
2743 Add @var{size} uninitialized bytes to a growing object.
2744 @xref{Growing Objects}.
2746 @item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2747 Add @var{size} bytes, copied from @var{address}, to a growing object.
2748 @xref{Growing Objects}.
2750 @item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2751 Add @var{size} bytes, copied from @var{address}, to a growing object,
2752 and then add another byte containing a null character.  @xref{Growing
2753 Objects}.
2755 @item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
2756 Add one byte containing @var{data-char} to a growing object.
2757 @xref{Growing Objects}.
2759 @item void *obstack_finish (struct obstack *@var{obstack-ptr})
2760 Finalize the object that is growing and return its permanent address.
2761 @xref{Growing Objects}.
2763 @item int obstack_object_size (struct obstack *@var{obstack-ptr})
2764 Get the current size of the currently growing object.  @xref{Growing
2765 Objects}.
2767 @item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
2768 Add @var{size} uninitialized bytes to a growing object without checking
2769 that there is enough room.  @xref{Extra Fast Growing}.
2771 @item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
2772 Add one byte containing @var{data-char} to a growing object without
2773 checking that there is enough room.  @xref{Extra Fast Growing}.
2775 @item int obstack_room (struct obstack *@var{obstack-ptr})
2776 Get the amount of room now available for growing the current object.
2777 @xref{Extra Fast Growing}.
2779 @item int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
2780 The mask used for aligning the beginning of an object.  This is an
2781 lvalue.  @xref{Obstacks Data Alignment}.
2783 @item int obstack_chunk_size (struct obstack *@var{obstack-ptr})
2784 The size for allocating chunks.  This is an lvalue.  @xref{Obstack Chunks}.
2786 @item void *obstack_base (struct obstack *@var{obstack-ptr})
2787 Tentative starting address of the currently growing object.
2788 @xref{Status of an Obstack}.
2790 @item void *obstack_next_free (struct obstack *@var{obstack-ptr})
2791 Address just after the end of the currently growing object.
2792 @xref{Status of an Obstack}.
2793 @end table
2795 @node Variable Size Automatic
2796 @subsection Automatic Storage with Variable Size
2797 @cindex automatic freeing
2798 @cindex @code{alloca} function
2799 @cindex automatic storage with variable size
2801 The function @code{alloca} supports a kind of half-dynamic allocation in
2802 which blocks are allocated dynamically but freed automatically.
2804 Allocating a block with @code{alloca} is an explicit action; you can
2805 allocate as many blocks as you wish, and compute the size at run time.  But
2806 all the blocks are freed when you exit the function that @code{alloca} was
2807 called from, just as if they were automatic variables declared in that
2808 function.  There is no way to free the space explicitly.
2810 The prototype for @code{alloca} is in @file{stdlib.h}.  This function is
2811 a BSD extension.
2812 @pindex stdlib.h
2814 @deftypefun {void *} alloca (size_t @var{size})
2815 @standards{GNU, stdlib.h}
2816 @standards{BSD, stdlib.h}
2817 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2818 The return value of @code{alloca} is the address of a block of @var{size}
2819 bytes of memory, allocated in the stack frame of the calling function.
2820 @end deftypefun
2822 Do not use @code{alloca} inside the arguments of a function call---you
2823 will get unpredictable results, because the stack space for the
2824 @code{alloca} would appear on the stack in the middle of the space for
2825 the function arguments.  An example of what to avoid is @code{foo (x,
2826 alloca (4), y)}.
2827 @c This might get fixed in future versions of GCC, but that won't make
2828 @c it safe with compilers generally.
2830 @menu
2831 * Alloca Example::              Example of using @code{alloca}.
2832 * Advantages of Alloca::        Reasons to use @code{alloca}.
2833 * Disadvantages of Alloca::     Reasons to avoid @code{alloca}.
2834 * GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
2835                                  method of allocating dynamically and
2836                                  freeing automatically.
2837 @end menu
2839 @node Alloca Example
2840 @subsubsection @code{alloca} Example
2842 As an example of the use of @code{alloca}, here is a function that opens
2843 a file name made from concatenating two argument strings, and returns a
2844 file descriptor or minus one signifying failure:
2846 @smallexample
2848 open2 (char *str1, char *str2, int flags, int mode)
2850   char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
2851   stpcpy (stpcpy (name, str1), str2);
2852   return open (name, flags, mode);
2854 @end smallexample
2856 @noindent
2857 Here is how you would get the same results with @code{malloc} and
2858 @code{free}:
2860 @smallexample
2862 open2 (char *str1, char *str2, int flags, int mode)
2864   char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
2865   int desc;
2866   if (name == 0)
2867     fatal ("virtual memory exceeded");
2868   stpcpy (stpcpy (name, str1), str2);
2869   desc = open (name, flags, mode);
2870   free (name);
2871   return desc;
2873 @end smallexample
2875 As you can see, it is simpler with @code{alloca}.  But @code{alloca} has
2876 other, more important advantages, and some disadvantages.
2878 @node Advantages of Alloca
2879 @subsubsection Advantages of @code{alloca}
2881 Here are the reasons why @code{alloca} may be preferable to @code{malloc}:
2883 @itemize @bullet
2884 @item
2885 Using @code{alloca} wastes very little space and is very fast.  (It is
2886 open-coded by the GNU C compiler.)
2888 @item
2889 Since @code{alloca} does not have separate pools for different sizes of
2890 blocks, space used for any size block can be reused for any other size.
2891 @code{alloca} does not cause memory fragmentation.
2893 @item
2894 @cindex longjmp
2895 Nonlocal exits done with @code{longjmp} (@pxref{Non-Local Exits})
2896 automatically free the space allocated with @code{alloca} when they exit
2897 through the function that called @code{alloca}.  This is the most
2898 important reason to use @code{alloca}.
2900 To illustrate this, suppose you have a function
2901 @code{open_or_report_error} which returns a descriptor, like
2902 @code{open}, if it succeeds, but does not return to its caller if it
2903 fails.  If the file cannot be opened, it prints an error message and
2904 jumps out to the command level of your program using @code{longjmp}.
2905 Let's change @code{open2} (@pxref{Alloca Example}) to use this
2906 subroutine:@refill
2908 @smallexample
2910 open2 (char *str1, char *str2, int flags, int mode)
2912   char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
2913   stpcpy (stpcpy (name, str1), str2);
2914   return open_or_report_error (name, flags, mode);
2916 @end smallexample
2918 @noindent
2919 Because of the way @code{alloca} works, the memory it allocates is
2920 freed even when an error occurs, with no special effort required.
2922 By contrast, the previous definition of @code{open2} (which uses
2923 @code{malloc} and @code{free}) would develop a memory leak if it were
2924 changed in this way.  Even if you are willing to make more changes to
2925 fix it, there is no easy way to do so.
2926 @end itemize
2928 @node Disadvantages of Alloca
2929 @subsubsection Disadvantages of @code{alloca}
2931 @cindex @code{alloca} disadvantages
2932 @cindex disadvantages of @code{alloca}
2933 These are the disadvantages of @code{alloca} in comparison with
2934 @code{malloc}:
2936 @itemize @bullet
2937 @item
2938 If you try to allocate more memory than the machine can provide, you
2939 don't get a clean error message.  Instead you get a fatal signal like
2940 the one you would get from an infinite recursion; probably a
2941 segmentation violation (@pxref{Program Error Signals}).
2943 @item
2944 Some @nongnusystems{} fail to support @code{alloca}, so it is less
2945 portable.  However, a slower emulation of @code{alloca} written in C
2946 is available for use on systems with this deficiency.
2947 @end itemize
2949 @node GNU C Variable-Size Arrays
2950 @subsubsection GNU C Variable-Size Arrays
2951 @cindex variable-sized arrays
2953 In GNU C, you can replace most uses of @code{alloca} with an array of
2954 variable size.  Here is how @code{open2} would look then:
2956 @smallexample
2957 int open2 (char *str1, char *str2, int flags, int mode)
2959   char name[strlen (str1) + strlen (str2) + 1];
2960   stpcpy (stpcpy (name, str1), str2);
2961   return open (name, flags, mode);
2963 @end smallexample
2965 But @code{alloca} is not always equivalent to a variable-sized array, for
2966 several reasons:
2968 @itemize @bullet
2969 @item
2970 A variable size array's space is freed at the end of the scope of the
2971 name of the array.  The space allocated with @code{alloca}
2972 remains until the end of the function.
2974 @item
2975 It is possible to use @code{alloca} within a loop, allocating an
2976 additional block on each iteration.  This is impossible with
2977 variable-sized arrays.
2978 @end itemize
2980 @strong{NB:} If you mix use of @code{alloca} and variable-sized arrays
2981 within one function, exiting a scope in which a variable-sized array was
2982 declared frees all blocks allocated with @code{alloca} during the
2983 execution of that scope.
2986 @node Resizing the Data Segment
2987 @section Resizing the Data Segment
2989 The symbols in this section are declared in @file{unistd.h}.
2991 You will not normally use the functions in this section, because the
2992 functions described in @ref{Memory Allocation} are easier to use.  Those
2993 are interfaces to a @glibcadj{} memory allocator that uses the
2994 functions below itself.  The functions below are simple interfaces to
2995 system calls.
2997 @deftypefun int brk (void *@var{addr})
2998 @standards{BSD, unistd.h}
2999 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3001 @code{brk} sets the high end of the calling process' data segment to
3002 @var{addr}.
3004 The address of the end of a segment is defined to be the address of the
3005 last byte in the segment plus 1.
3007 The function has no effect if @var{addr} is lower than the low end of
3008 the data segment.  (This is considered success, by the way.)
3010 The function fails if it would cause the data segment to overlap another
3011 segment or exceed the process' data storage limit (@pxref{Limits on
3012 Resources}).
3014 The function is named for a common historical case where data storage
3015 and the stack are in the same segment.  Data storage allocation grows
3016 upward from the bottom of the segment while the stack grows downward
3017 toward it from the top of the segment and the curtain between them is
3018 called the @dfn{break}.
3020 The return value is zero on success.  On failure, the return value is
3021 @code{-1} and @code{errno} is set accordingly.  The following @code{errno}
3022 values are specific to this function:
3024 @table @code
3025 @item ENOMEM
3026 The request would cause the data segment to overlap another segment or
3027 exceed the process' data storage limit.
3028 @end table
3030 @c The Brk system call in Linux (as opposed to the GNU C Library function)
3031 @c is considerably different.  It always returns the new end of the data
3032 @c segment, whether it succeeds or fails.  The GNU C library Brk determines
3033 @c it's a failure if and only if the system call returns an address less
3034 @c than the address requested.
3036 @end deftypefun
3039 @deftypefun void *sbrk (ptrdiff_t @var{delta})
3040 @standards{BSD, unistd.h}
3041 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3043 This function is the same as @code{brk} except that you specify the new
3044 end of the data segment as an offset @var{delta} from the current end
3045 and on success the return value is the address of the resulting end of
3046 the data segment instead of zero.
3048 This means you can use @samp{sbrk(0)} to find out what the current end
3049 of the data segment is.
3051 @end deftypefun
3055 @node Locking Pages
3056 @section Locking Pages
3057 @cindex locking pages
3058 @cindex memory lock
3059 @cindex paging
3061 You can tell the system to associate a particular virtual memory page
3062 with a real page frame and keep it that way --- i.e., cause the page to
3063 be paged in if it isn't already and mark it so it will never be paged
3064 out and consequently will never cause a page fault.  This is called
3065 @dfn{locking} a page.
3067 The functions in this chapter lock and unlock the calling process'
3068 pages.
3070 @menu
3071 * Why Lock Pages::                Reasons to read this section.
3072 * Locked Memory Details::         Everything you need to know locked
3073                                     memory
3074 * Page Lock Functions::           Here's how to do it.
3075 @end menu
3077 @node Why Lock Pages
3078 @subsection Why Lock Pages
3080 Because page faults cause paged out pages to be paged in transparently,
3081 a process rarely needs to be concerned about locking pages.  However,
3082 there are two reasons people sometimes are:
3084 @itemize @bullet
3086 @item
3087 Speed.  A page fault is transparent only insofar as the process is not
3088 sensitive to how long it takes to do a simple memory access.  Time-critical
3089 processes, especially realtime processes, may not be able to wait or
3090 may not be able to tolerate variance in execution speed.
3091 @cindex realtime processing
3092 @cindex speed of execution
3094 A process that needs to lock pages for this reason probably also needs
3095 priority among other processes for use of the CPU.  @xref{Priority}.
3097 In some cases, the programmer knows better than the system's demand
3098 paging allocator which pages should remain in real memory to optimize
3099 system performance.  In this case, locking pages can help.
3101 @item
3102 Privacy.  If you keep secrets in virtual memory and that virtual memory
3103 gets paged out, that increases the chance that the secrets will get out.
3104 If a password gets written out to disk swap space, for example, it might
3105 still be there long after virtual and real memory have been wiped clean.
3107 @end itemize
3109 Be aware that when you lock a page, that's one fewer page frame that can
3110 be used to back other virtual memory (by the same or other processes),
3111 which can mean more page faults, which means the system runs more
3112 slowly.  In fact, if you lock enough memory, some programs may not be
3113 able to run at all for lack of real memory.
3115 @node Locked Memory Details
3116 @subsection Locked Memory Details
3118 A memory lock is associated with a virtual page, not a real frame.  The
3119 paging rule is: If a frame backs at least one locked page, don't page it
3120 out.
3122 Memory locks do not stack.  I.e., you can't lock a particular page twice
3123 so that it has to be unlocked twice before it is truly unlocked.  It is
3124 either locked or it isn't.
3126 A memory lock persists until the process that owns the memory explicitly
3127 unlocks it.  (But process termination and exec cause the virtual memory
3128 to cease to exist, which you might say means it isn't locked any more).
3130 Memory locks are not inherited by child processes.  (But note that on a
3131 modern Unix system, immediately after a fork, the parent's and the
3132 child's virtual address space are backed by the same real page frames,
3133 so the child enjoys the parent's locks).  @xref{Creating a Process}.
3135 Because of its ability to impact other processes, only the superuser can
3136 lock a page.  Any process can unlock its own page.
3138 The system sets limits on the amount of memory a process can have locked
3139 and the amount of real memory it can have dedicated to it.  @xref{Limits
3140 on Resources}.
3142 In Linux, locked pages aren't as locked as you might think.
3143 Two virtual pages that are not shared memory can nonetheless be backed
3144 by the same real frame.  The kernel does this in the name of efficiency
3145 when it knows both virtual pages contain identical data, and does it
3146 even if one or both of the virtual pages are locked.
3148 But when a process modifies one of those pages, the kernel must get it a
3149 separate frame and fill it with the page's data.  This is known as a
3150 @dfn{copy-on-write page fault}.  It takes a small amount of time and in
3151 a pathological case, getting that frame may require I/O.
3152 @cindex copy-on-write page fault
3153 @cindex page fault, copy-on-write
3155 To make sure this doesn't happen to your program, don't just lock the
3156 pages.  Write to them as well, unless you know you won't write to them
3157 ever.  And to make sure you have pre-allocated frames for your stack,
3158 enter a scope that declares a C automatic variable larger than the
3159 maximum stack size you will need, set it to something, then return from
3160 its scope.
3162 @node Page Lock Functions
3163 @subsection Functions To Lock And Unlock Pages
3165 The symbols in this section are declared in @file{sys/mman.h}.  These
3166 functions are defined by POSIX.1b, but their availability depends on
3167 your kernel.  If your kernel doesn't allow these functions, they exist
3168 but always fail.  They @emph{are} available with a Linux kernel.
3170 @strong{Portability Note:} POSIX.1b requires that when the @code{mlock}
3171 and @code{munlock} functions are available, the file @file{unistd.h}
3172 define the macro @code{_POSIX_MEMLOCK_RANGE} and the file
3173 @code{limits.h} define the macro @code{PAGESIZE} to be the size of a
3174 memory page in bytes.  It requires that when the @code{mlockall} and
3175 @code{munlockall} functions are available, the @file{unistd.h} file
3176 define the macro @code{_POSIX_MEMLOCK}.  @Theglibc{} conforms to
3177 this requirement.
3179 @deftypefun int mlock (const void *@var{addr}, size_t @var{len})
3180 @standards{POSIX.1b, sys/mman.h}
3181 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3183 @code{mlock} locks a range of the calling process' virtual pages.
3185 The range of memory starts at address @var{addr} and is @var{len} bytes
3186 long.  Actually, since you must lock whole pages, it is the range of
3187 pages that include any part of the specified range.
3189 When the function returns successfully, each of those pages is backed by
3190 (connected to) a real frame (is resident) and is marked to stay that
3191 way.  This means the function may cause page-ins and have to wait for
3192 them.
3194 When the function fails, it does not affect the lock status of any
3195 pages.
3197 The return value is zero if the function succeeds.  Otherwise, it is
3198 @code{-1} and @code{errno} is set accordingly.  @code{errno} values
3199 specific to this function are:
3201 @table @code
3202 @item ENOMEM
3203 @itemize @bullet
3204 @item
3205 At least some of the specified address range does not exist in the
3206 calling process' virtual address space.
3207 @item
3208 The locking would cause the process to exceed its locked page limit.
3209 @end itemize
3211 @item EPERM
3212 The calling process is not superuser.
3214 @item EINVAL
3215 @var{len} is not positive.
3217 @item ENOSYS
3218 The kernel does not provide @code{mlock} capability.
3220 @end table
3222 You can lock @emph{all} a process' memory with @code{mlockall}.  You
3223 unlock memory with @code{munlock} or @code{munlockall}.
3225 To avoid all page faults in a C program, you have to use
3226 @code{mlockall}, because some of the memory a program uses is hidden
3227 from the C code, e.g. the stack and automatic variables, and you
3228 wouldn't know what address to tell @code{mlock}.
3230 @end deftypefun
3232 @deftypefun int munlock (const void *@var{addr}, size_t @var{len})
3233 @standards{POSIX.1b, sys/mman.h}
3234 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3236 @code{munlock} unlocks a range of the calling process' virtual pages.
3238 @code{munlock} is the inverse of @code{mlock} and functions completely
3239 analogously to @code{mlock}, except that there is no @code{EPERM}
3240 failure.
3242 @end deftypefun
3244 @deftypefun int mlockall (int @var{flags})
3245 @standards{POSIX.1b, sys/mman.h}
3246 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3248 @code{mlockall} locks all the pages in a process' virtual memory address
3249 space, and/or any that are added to it in the future.  This includes the
3250 pages of the code, data and stack segment, as well as shared libraries,
3251 user space kernel data, shared memory, and memory mapped files.
3253 @var{flags} is a string of single bit flags represented by the following
3254 macros.  They tell @code{mlockall} which of its functions you want.  All
3255 other bits must be zero.
3257 @vtable @code
3259 @item MCL_CURRENT
3260 Lock all pages which currently exist in the calling process' virtual
3261 address space.
3263 @item MCL_FUTURE
3264 Set a mode such that any pages added to the process' virtual address
3265 space in the future will be locked from birth.  This mode does not
3266 affect future address spaces owned by the same process so exec, which
3267 replaces a process' address space, wipes out @code{MCL_FUTURE}.
3268 @xref{Executing a File}.
3270 @end vtable
3272 When the function returns successfully, and you specified
3273 @code{MCL_CURRENT}, all of the process' pages are backed by (connected
3274 to) real frames (they are resident) and are marked to stay that way.
3275 This means the function may cause page-ins and have to wait for them.
3277 When the process is in @code{MCL_FUTURE} mode because it successfully
3278 executed this function and specified @code{MCL_CURRENT}, any system call
3279 by the process that requires space be added to its virtual address space
3280 fails with @code{errno} = @code{ENOMEM} if locking the additional space
3281 would cause the process to exceed its locked page limit.  In the case
3282 that the address space addition that can't be accommodated is stack
3283 expansion, the stack expansion fails and the kernel sends a
3284 @code{SIGSEGV} signal to the process.
3286 When the function fails, it does not affect the lock status of any pages
3287 or the future locking mode.
3289 The return value is zero if the function succeeds.  Otherwise, it is
3290 @code{-1} and @code{errno} is set accordingly.  @code{errno} values
3291 specific to this function are:
3293 @table @code
3294 @item ENOMEM
3295 @itemize @bullet
3296 @item
3297 At least some of the specified address range does not exist in the
3298 calling process' virtual address space.
3299 @item
3300 The locking would cause the process to exceed its locked page limit.
3301 @end itemize
3303 @item EPERM
3304 The calling process is not superuser.
3306 @item EINVAL
3307 Undefined bits in @var{flags} are not zero.
3309 @item ENOSYS
3310 The kernel does not provide @code{mlockall} capability.
3312 @end table
3314 You can lock just specific pages with @code{mlock}.  You unlock pages
3315 with @code{munlockall} and @code{munlock}.
3317 @end deftypefun
3320 @deftypefun int munlockall (void)
3321 @standards{POSIX.1b, sys/mman.h}
3322 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3324 @code{munlockall} unlocks every page in the calling process' virtual
3325 address space and turns off @code{MCL_FUTURE} future locking mode.
3327 The return value is zero if the function succeeds.  Otherwise, it is
3328 @code{-1} and @code{errno} is set accordingly.  The only way this
3329 function can fail is for generic reasons that all functions and system
3330 calls can fail, so there are no specific @code{errno} values.
3332 @end deftypefun
3337 @ignore
3338 @c This was never actually implemented.  -zw
3339 @node Relocating Allocator
3340 @section Relocating Allocator
3342 @cindex relocating memory allocator
3343 Any system of dynamic memory allocation has overhead: the amount of
3344 space it uses is more than the amount the program asks for.  The
3345 @dfn{relocating memory allocator} achieves very low overhead by moving
3346 blocks in memory as necessary, on its own initiative.
3348 @c @menu
3349 @c * Relocator Concepts::               How to understand relocating allocation.
3350 @c * Using Relocator::          Functions for relocating allocation.
3351 @c @end menu
3353 @node Relocator Concepts
3354 @subsection Concepts of Relocating Allocation
3356 @ifinfo
3357 The @dfn{relocating memory allocator} achieves very low overhead by
3358 moving blocks in memory as necessary, on its own initiative.
3359 @end ifinfo
3361 When you allocate a block with @code{malloc}, the address of the block
3362 never changes unless you use @code{realloc} to change its size.  Thus,
3363 you can safely store the address in various places, temporarily or
3364 permanently, as you like.  This is not safe when you use the relocating
3365 memory allocator, because any and all relocatable blocks can move
3366 whenever you allocate memory in any fashion.  Even calling @code{malloc}
3367 or @code{realloc} can move the relocatable blocks.
3369 @cindex handle
3370 For each relocatable block, you must make a @dfn{handle}---a pointer
3371 object in memory, designated to store the address of that block.  The
3372 relocating allocator knows where each block's handle is, and updates the
3373 address stored there whenever it moves the block, so that the handle
3374 always points to the block.  Each time you access the contents of the
3375 block, you should fetch its address anew from the handle.
3377 To call any of the relocating allocator functions from a signal handler
3378 is almost certainly incorrect, because the signal could happen at any
3379 time and relocate all the blocks.  The only way to make this safe is to
3380 block the signal around any access to the contents of any relocatable
3381 block---not a convenient mode of operation.  @xref{Nonreentrancy}.
3383 @node Using Relocator
3384 @subsection Allocating and Freeing Relocatable Blocks
3386 @pindex malloc.h
3387 In the descriptions below, @var{handleptr} designates the address of the
3388 handle.  All the functions are declared in @file{malloc.h}; all are GNU
3389 extensions.
3391 @comment malloc.h
3392 @comment GNU
3393 @c @deftypefun {void *} r_alloc (void **@var{handleptr}, size_t @var{size})
3394 This function allocates a relocatable block of size @var{size}.  It
3395 stores the block's address in @code{*@var{handleptr}} and returns
3396 a non-null pointer to indicate success.
3398 If @code{r_alloc} can't get the space needed, it stores a null pointer
3399 in @code{*@var{handleptr}}, and returns a null pointer.
3400 @end deftypefun
3402 @comment malloc.h
3403 @comment GNU
3404 @c @deftypefun void r_alloc_free (void **@var{handleptr})
3405 This function is the way to free a relocatable block.  It frees the
3406 block that @code{*@var{handleptr}} points to, and stores a null pointer
3407 in @code{*@var{handleptr}} to show it doesn't point to an allocated
3408 block any more.
3409 @end deftypefun
3411 @comment malloc.h
3412 @comment GNU
3413 @c @deftypefun {void *} r_re_alloc (void **@var{handleptr}, size_t @var{size})
3414 The function @code{r_re_alloc} adjusts the size of the block that
3415 @code{*@var{handleptr}} points to, making it @var{size} bytes long.  It
3416 stores the address of the resized block in @code{*@var{handleptr}} and
3417 returns a non-null pointer to indicate success.
3419 If enough memory is not available, this function returns a null pointer
3420 and does not modify @code{*@var{handleptr}}.
3421 @end deftypefun
3422 @end ignore
3427 @ignore
3428 @comment No longer available...
3430 @comment @node Memory Warnings
3431 @comment @section Memory Usage Warnings
3432 @comment @cindex memory usage warnings
3433 @comment @cindex warnings of memory almost full
3435 @pindex malloc.c
3436 You can ask for warnings as the program approaches running out of memory
3437 space, by calling @code{memory_warnings}.  This tells @code{malloc} to
3438 check memory usage every time it asks for more memory from the operating
3439 system.  This is a GNU extension declared in @file{malloc.h}.
3441 @comment malloc.h
3442 @comment GNU
3443 @comment @deftypefun void memory_warnings (void *@var{start}, void (*@var{warn-func}) (const char *))
3444 Call this function to request warnings for nearing exhaustion of virtual
3445 memory.
3447 The argument @var{start} says where data space begins, in memory.  The
3448 allocator compares this against the last address used and against the
3449 limit of data space, to determine the fraction of available memory in
3450 use.  If you supply zero for @var{start}, then a default value is used
3451 which is right in most circumstances.
3453 For @var{warn-func}, supply a function that @code{malloc} can call to
3454 warn you.  It is called with a string (a warning message) as argument.
3455 Normally it ought to display the string for the user to read.
3456 @end deftypefun
3458 The warnings come when memory becomes 75% full, when it becomes 85%
3459 full, and when it becomes 95% full.  Above 95% you get another warning
3460 each time memory usage increases.
3462 @end ignore