Adjust name of ld.so in test-container.c.
[glibc.git] / manual / memory.texi
bloba1435aad1acd3239d1bf8331a4863a399877d968
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 * Memory Protection::           Controlling access to memory regions.
21 * Locking Pages::               Preventing page faults
22 @end menu
24 Memory mapped I/O is not discussed in this chapter.  @xref{Memory-mapped I/O}.
28 @node Memory Concepts
29 @section Process Memory Concepts
31 One of the most basic resources a process has available to it is memory.
32 There are a lot of different ways systems organize memory, but in a
33 typical one, each process has one linear virtual address space, with
34 addresses running from zero to some huge maximum.  It need not be
35 contiguous; i.e., not all of these addresses actually can be used to
36 store data.
38 The virtual memory is divided into pages (4 kilobytes is typical).
39 Backing each page of virtual memory is a page of real memory (called a
40 @dfn{frame}) or some secondary storage, usually disk space.  The disk
41 space might be swap space or just some ordinary disk file.  Actually, a
42 page of all zeroes sometimes has nothing at all backing it -- there's
43 just a flag saying it is all zeroes.
44 @cindex page frame
45 @cindex frame, real memory
46 @cindex swap space
47 @cindex page, virtual memory
49 The same frame of real memory or backing store can back multiple virtual
50 pages belonging to multiple processes.  This is normally the case, for
51 example, with virtual memory occupied by @glibcadj{} code.  The same
52 real memory frame containing the @code{printf} function backs a virtual
53 memory page in each of the existing processes that has a @code{printf}
54 call in its program.
56 In order for a program to access any part of a virtual page, the page
57 must at that moment be backed by (``connected to'') a real frame.  But
58 because there is usually a lot more virtual memory than real memory, the
59 pages must move back and forth between real memory and backing store
60 regularly, coming into real memory when a process needs to access them
61 and then retreating to backing store when not needed anymore.  This
62 movement is called @dfn{paging}.
64 When a program attempts to access a page which is not at that moment
65 backed by real memory, this is known as a @dfn{page fault}.  When a page
66 fault occurs, the kernel suspends the process, places the page into a
67 real page frame (this is called ``paging in'' or ``faulting in''), then
68 resumes the process so that from the process' point of view, the page
69 was in real memory all along.  In fact, to the process, all pages always
70 seem to be in real memory.  Except for one thing: the elapsed execution
71 time of an instruction that would normally be a few nanoseconds is
72 suddenly much, much, longer (because the kernel normally has to do I/O
73 to complete the page-in).  For programs sensitive to that, the functions
74 described in @ref{Locking Pages} can control it.
75 @cindex page fault
76 @cindex paging
78 Within each virtual address space, a process has to keep track of what
79 is at which addresses, and that process is called memory allocation.
80 Allocation usually brings to mind meting out scarce resources, but in
81 the case of virtual memory, that's not a major goal, because there is
82 generally much more of it than anyone needs.  Memory allocation within a
83 process is mainly just a matter of making sure that the same byte of
84 memory isn't used to store two different things.
86 Processes allocate memory in two major ways: by exec and
87 programmatically.  Actually, forking is a third way, but it's not very
88 interesting.  @xref{Creating a Process}.
90 Exec is the operation of creating a virtual address space for a process,
91 loading its basic program into it, and executing the program.  It is
92 done by the ``exec'' family of functions (e.g. @code{execl}).  The
93 operation takes a program file (an executable), it allocates space to
94 load all the data in the executable, loads it, and transfers control to
95 it.  That data is most notably the instructions of the program (the
96 @dfn{text}), but also literals and constants in the program and even
97 some variables: C variables with the static storage class (@pxref{Memory
98 Allocation and C}).
99 @cindex executable
100 @cindex literals
101 @cindex constants
103 Once that program begins to execute, it uses programmatic allocation to
104 gain additional memory.  In a C program with @theglibc{}, there
105 are two kinds of programmatic allocation: automatic and dynamic.
106 @xref{Memory Allocation and C}.
108 Memory-mapped I/O is another form of dynamic virtual memory allocation.
109 Mapping memory to a file means declaring that the contents of certain
110 range of a process' addresses shall be identical to the contents of a
111 specified regular file.  The system makes the virtual memory initially
112 contain the contents of the file, and if you modify the memory, the
113 system writes the same modification to the file.  Note that due to the
114 magic of virtual memory and page faults, there is no reason for the
115 system to do I/O to read the file, or allocate real memory for its
116 contents, until the program accesses the virtual memory.
117 @xref{Memory-mapped I/O}.
118 @cindex memory mapped I/O
119 @cindex memory mapped file
120 @cindex files, accessing
122 Just as it programmatically allocates memory, the program can
123 programmatically deallocate (@dfn{free}) it.  You can't free the memory
124 that was allocated by exec.  When the program exits or execs, you might
125 say that all its memory gets freed, but since in both cases the address
126 space ceases to exist, the point is really moot.  @xref{Program
127 Termination}.
128 @cindex execing a program
129 @cindex freeing memory
130 @cindex exiting a program
132 A process' virtual address space is divided into segments.  A segment is
133 a contiguous range of virtual addresses.  Three important segments are:
135 @itemize @bullet
137 @item
139 The @dfn{text segment} contains a program's instructions and literals and
140 static constants.  It is allocated by exec and stays the same size for
141 the life of the virtual address space.
143 @item
144 The @dfn{data segment} is working storage for the program.  It can be
145 preallocated and preloaded by exec and the process can extend or shrink
146 it by calling functions as described in @xref{Resizing the Data
147 Segment}.  Its lower end is fixed.
149 @item
150 The @dfn{stack segment} contains a program stack.  It grows as the stack
151 grows, but doesn't shrink when the stack shrinks.
153 @end itemize
157 @node Memory Allocation
158 @section Allocating Storage For Program Data
160 This section covers how ordinary programs manage storage for their data,
161 including the famous @code{malloc} function and some fancier facilities
162 special to @theglibc{} and GNU Compiler.
164 @menu
165 * Memory Allocation and C::     How to get different kinds of allocation in C.
166 * The GNU Allocator::           An overview of the GNU @code{malloc}
167                                 implementation.
168 * Unconstrained Allocation::    The @code{malloc} facility allows fully general
169                                  dynamic allocation.
170 * Allocation Debugging::        Finding memory leaks and not freed memory.
171 * Replacing malloc::            Using your own @code{malloc}-style allocator.
172 * Obstacks::                    Obstacks are less general than malloc
173                                  but more efficient and convenient.
174 * Variable Size Automatic::     Allocation of variable-sized blocks
175                                  of automatic storage that are freed when the
176                                  calling function returns.
177 @end menu
180 @node Memory Allocation and C
181 @subsection Memory Allocation in C Programs
183 The C language supports two kinds of memory allocation through the
184 variables in C programs:
186 @itemize @bullet
187 @item
188 @dfn{Static allocation} is what happens when you declare a static or
189 global variable.  Each static or global variable defines one block of
190 space, of a fixed size.  The space is allocated once, when your program
191 is started (part of the exec operation), and is never freed.
192 @cindex static memory allocation
193 @cindex static storage class
195 @item
196 @dfn{Automatic allocation} happens when you declare an automatic
197 variable, such as a function argument or a local variable.  The space
198 for an automatic variable is allocated when the compound statement
199 containing the declaration is entered, and is freed when that
200 compound statement is exited.
201 @cindex automatic memory allocation
202 @cindex automatic storage class
204 In GNU C, the size of the automatic storage can be an expression
205 that varies.  In other C implementations, it must be a constant.
206 @end itemize
208 A third important kind of memory allocation, @dfn{dynamic allocation},
209 is not supported by C variables but is available via @glibcadj{}
210 functions.
211 @cindex dynamic memory allocation
213 @subsubsection Dynamic Memory Allocation
214 @cindex dynamic memory allocation
216 @dfn{Dynamic memory allocation} is a technique in which programs
217 determine as they are running where to store some information.  You need
218 dynamic allocation when the amount of memory you need, or how long you
219 continue to need it, depends on factors that are not known before the
220 program runs.
222 For example, you may need a block to store a line read from an input
223 file; since there is no limit to how long a line can be, you must
224 allocate the memory dynamically and make it dynamically larger as you
225 read more of the line.
227 Or, you may need a block for each record or each definition in the input
228 data; since you can't know in advance how many there will be, you must
229 allocate a new block for each record or definition as you read it.
231 When you use dynamic allocation, the allocation of a block of memory is
232 an action that the program requests explicitly.  You call a function or
233 macro when you want to allocate space, and specify the size with an
234 argument.  If you want to free the space, you do so by calling another
235 function or macro.  You can do these things whenever you want, as often
236 as you want.
238 Dynamic allocation is not supported by C variables; there is no storage
239 class ``dynamic'', and there can never be a C variable whose value is
240 stored in dynamically allocated space.  The only way to get dynamically
241 allocated memory is via a system call (which is generally via a @glibcadj{}
242 function call), and the only way to refer to dynamically
243 allocated space is through a pointer.  Because it is less convenient,
244 and because the actual process of dynamic allocation requires more
245 computation time, programmers generally use dynamic allocation only when
246 neither static nor automatic allocation will serve.
248 For example, if you want to allocate dynamically some space to hold a
249 @code{struct foobar}, you cannot declare a variable of type @code{struct
250 foobar} whose contents are the dynamically allocated space.  But you can
251 declare a variable of pointer type @code{struct foobar *} and assign it the
252 address of the space.  Then you can use the operators @samp{*} and
253 @samp{->} on this pointer variable to refer to the contents of the space:
255 @smallexample
257   struct foobar *ptr
258      = (struct foobar *) malloc (sizeof (struct foobar));
259   ptr->name = x;
260   ptr->next = current_foobar;
261   current_foobar = ptr;
263 @end smallexample
265 @node The GNU Allocator
266 @subsection The GNU Allocator
267 @cindex gnu allocator
269 The @code{malloc} implementation in @theglibc{} is derived from ptmalloc
270 (pthreads malloc), which in turn is derived from dlmalloc (Doug Lea malloc).
271 This malloc may allocate memory in two different ways depending on their size
272 and certain parameters that may be controlled by users. The most common way is
273 to allocate portions of memory (called chunks) from a large contiguous area of
274 memory and manage these areas to optimize their use and reduce wastage in the
275 form of unusable chunks. Traditionally the system heap was set up to be the one
276 large memory area but the @glibcadj{} @code{malloc} implementation maintains
277 multiple such areas to optimize their use in multi-threaded applications.  Each
278 such area is internally referred to as an @dfn{arena}.
280 As opposed to other versions, the @code{malloc} in @theglibc{} does not round
281 up chunk sizes to powers of two, neither for large nor for small sizes.
282 Neighboring chunks can be coalesced on a @code{free} no matter what their size
283 is.  This makes the implementation suitable for all kinds of allocation
284 patterns without generally incurring high memory waste through fragmentation.
285 The presence of multiple arenas allows multiple threads to allocate
286 memory simultaneously in separate arenas, thus improving performance.
288 The other way of memory allocation is for very large blocks, i.e. much larger
289 than a page. These requests are allocated with @code{mmap} (anonymous or via
290 @file{/dev/zero}; @pxref{Memory-mapped I/O})). This has the great advantage
291 that these chunks are returned to the system immediately when they are freed.
292 Therefore, it cannot happen that a large chunk becomes ``locked'' in between
293 smaller ones and even after calling @code{free} wastes memory.  The size
294 threshold for @code{mmap} to be used is dynamic and gets adjusted according to
295 allocation patterns of the program.  @code{mallopt} can be used to statically
296 adjust the threshold using @code{M_MMAP_THRESHOLD} and the use of @code{mmap}
297 can be disabled completely with @code{M_MMAP_MAX};
298 @pxref{Malloc Tunable Parameters}.
300 A more detailed technical description of the GNU Allocator is maintained in
301 the @glibcadj{} wiki. See
302 @uref{https://sourceware.org/glibc/wiki/MallocInternals}.
304 It is possible to use your own custom @code{malloc} instead of the
305 built-in allocator provided by @theglibc{}.  @xref{Replacing malloc}.
307 @node Unconstrained Allocation
308 @subsection Unconstrained Allocation
309 @cindex unconstrained memory allocation
310 @cindex @code{malloc} function
311 @cindex heap, dynamic allocation from
313 The most general dynamic allocation facility is @code{malloc}.  It
314 allows you to allocate blocks of memory of any size at any time, make
315 them bigger or smaller at any time, and free the blocks individually at
316 any time (or never).
318 @menu
319 * Basic Allocation::            Simple use of @code{malloc}.
320 * Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
321 * Freeing after Malloc::        Use @code{free} to free a block you
322                                  got with @code{malloc}.
323 * Changing Block Size::         Use @code{realloc} to make a block
324                                  bigger or smaller.
325 * Allocating Cleared Space::    Use @code{calloc} to allocate a
326                                  block and clear it.
327 * Aligned Memory Blocks::       Allocating specially aligned memory.
328 * Malloc Tunable Parameters::   Use @code{mallopt} to adjust allocation
329                                  parameters.
330 * Heap Consistency Checking::   Automatic checking for errors.
331 * Hooks for Malloc::            You can use these hooks for debugging
332                                  programs that use @code{malloc}.
333 * Statistics of Malloc::        Getting information about how much
334                                  memory your program is using.
335 * Summary of Malloc::           Summary of @code{malloc} and related functions.
336 @end menu
338 @node Basic Allocation
339 @subsubsection Basic Memory Allocation
340 @cindex allocation of memory with @code{malloc}
342 To allocate a block of memory, call @code{malloc}.  The prototype for
343 this function is in @file{stdlib.h}.
344 @pindex stdlib.h
346 @deftypefun {void *} malloc (size_t @var{size})
347 @standards{ISO, malloc.h}
348 @standards{ISO, stdlib.h}
349 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
350 @c Malloc hooks and __morecore pointers, as well as such parameters as
351 @c max_n_mmaps and max_mmapped_mem, are accessed without guards, so they
352 @c could pose a thread safety issue; in order to not declare malloc
353 @c MT-unsafe, it's modifying the hooks and parameters while multiple
354 @c threads are active that is regarded as unsafe.  An arena's next field
355 @c is initialized and never changed again, except for main_arena's,
356 @c that's protected by list_lock; next_free is only modified while
357 @c list_lock is held too.  All other data members of an arena, as well
358 @c as the metadata of the memory areas assigned to it, are only modified
359 @c while holding the arena's mutex (fastbin pointers use catomic ops
360 @c because they may be modified by free without taking the arena's
361 @c lock).  Some reassurance was needed for fastbins, for it wasn't clear
362 @c how they were initialized.  It turns out they are always
363 @c zero-initialized: main_arena's, for being static data, and other
364 @c arena's, for being just-mmapped memory.
366 @c Leaking file descriptors and memory in case of cancellation is
367 @c unavoidable without disabling cancellation, but the lock situation is
368 @c a bit more complicated: we don't have fallback arenas for malloc to
369 @c be safe to call from within signal handlers.  Error-checking mutexes
370 @c or trylock could enable us to try and use alternate arenas, even with
371 @c -DPER_THREAD (enabled by default), but supporting interruption
372 @c (cancellation or signal handling) while holding the arena list mutex
373 @c would require more work; maybe blocking signals and disabling async
374 @c cancellation while manipulating the arena lists?
376 @c __libc_malloc @asulock @aculock @acsfd @acsmem
377 @c  force_reg ok
378 @c  *malloc_hook unguarded
379 @c  arena_lock @asulock @aculock @acsfd @acsmem
380 @c   mutex_lock @asulock @aculock
381 @c   arena_get2 @asulock @aculock @acsfd @acsmem
382 @c    get_free_list @asulock @aculock
383 @c     mutex_lock (list_lock) dup @asulock @aculock
384 @c     mutex_unlock (list_lock) dup @aculock
385 @c     mutex_lock (arena lock) dup @asulock @aculock [returns locked]
386 @c    __get_nprocs ext ok @acsfd
387 @c    NARENAS_FROM_NCORES ok
388 @c    catomic_compare_and_exchange_bool_acq ok
389 @c    _int_new_arena ok @asulock @aculock @acsmem
390 @c     new_heap ok @acsmem
391 @c      mmap ok @acsmem
392 @c      munmap ok @acsmem
393 @c      mprotect ok
394 @c     chunk2mem ok
395 @c     set_head ok
396 @c     tsd_setspecific dup ok
397 @c     mutex_init ok
398 @c     mutex_lock (just-created mutex) ok, returns locked
399 @c     mutex_lock (list_lock) dup @asulock @aculock
400 @c     atomic_write_barrier ok
401 @c     mutex_unlock (list_lock) @aculock
402 @c    catomic_decrement ok
403 @c    reused_arena @asulock @aculock
404 @c      reads&writes next_to_use and iterates over arena next without guards
405 @c      those are harmless as long as we don't drop arenas from the
406 @c      NEXT list, and we never do; when a thread terminates,
407 @c      __malloc_arena_thread_freeres prepends the arena to the free_list
408 @c      NEXT_FREE list, but NEXT is never modified, so it's safe!
409 @c     mutex_trylock (arena lock) @asulock @aculock
410 @c     mutex_lock (arena lock) dup @asulock @aculock
411 @c     tsd_setspecific dup ok
412 @c  _int_malloc @acsfd @acsmem
413 @c   checked_request2size ok
414 @c    REQUEST_OUT_OF_RANGE ok
415 @c    request2size ok
416 @c   get_max_fast ok
417 @c   fastbin_index ok
418 @c   fastbin ok
419 @c   catomic_compare_and_exhange_val_acq ok
420 @c   malloc_printerr dup @mtsenv
421 @c     if we get to it, we're toast already, undefined behavior must have
422 @c     been invoked before
423 @c    libc_message @mtsenv [no leaks with cancellation disabled]
424 @c     FATAL_PREPARE ok
425 @c      pthread_setcancelstate disable ok
426 @c     libc_secure_getenv @mtsenv
427 @c      getenv @mtsenv
428 @c     open_not_cancel_2 dup @acsfd
429 @c     strchrnul ok
430 @c     WRITEV_FOR_FATAL ok
431 @c      writev ok
432 @c     mmap ok @acsmem
433 @c     munmap ok @acsmem
434 @c     BEFORE_ABORT @acsfd
435 @c      backtrace ok
436 @c      write_not_cancel dup ok
437 @c      backtrace_symbols_fd @aculock
438 @c      open_not_cancel_2 dup @acsfd
439 @c      read_not_cancel dup ok
440 @c      close_not_cancel_no_status dup @acsfd
441 @c     abort ok
442 @c    itoa_word ok
443 @c    abort ok
444 @c   check_remalloced_chunk ok/disabled
445 @c   chunk2mem dup ok
446 @c   alloc_perturb ok
447 @c   in_smallbin_range ok
448 @c   smallbin_index ok
449 @c   bin_at ok
450 @c   last ok
451 @c   malloc_consolidate ok
452 @c    get_max_fast dup ok
453 @c    clear_fastchunks ok
454 @c    unsorted_chunks dup ok
455 @c    fastbin dup ok
456 @c    atomic_exchange_acq ok
457 @c    check_inuse_chunk dup ok/disabled
458 @c    chunk_at_offset dup ok
459 @c    chunksize dup ok
460 @c    inuse_bit_at_offset dup ok
461 @c    unlink dup ok
462 @c    clear_inuse_bit_at_offset dup ok
463 @c    in_smallbin_range dup ok
464 @c    set_head dup ok
465 @c    malloc_init_state ok
466 @c     bin_at dup ok
467 @c     set_noncontiguous dup ok
468 @c     set_max_fast dup ok
469 @c     initial_top ok
470 @c      unsorted_chunks dup ok
471 @c    check_malloc_state ok/disabled
472 @c   set_inuse_bit_at_offset ok
473 @c   check_malloced_chunk ok/disabled
474 @c   largebin_index ok
475 @c   have_fastchunks ok
476 @c   unsorted_chunks ok
477 @c    bin_at ok
478 @c   chunksize ok
479 @c   chunk_at_offset ok
480 @c   set_head ok
481 @c   set_foot ok
482 @c   mark_bin ok
483 @c    idx2bit ok
484 @c   first ok
485 @c   unlink ok
486 @c    malloc_printerr dup ok
487 @c    in_smallbin_range dup ok
488 @c   idx2block ok
489 @c   idx2bit dup ok
490 @c   next_bin ok
491 @c   sysmalloc @acsfd @acsmem
492 @c    MMAP @acsmem
493 @c    set_head dup ok
494 @c    check_chunk ok/disabled
495 @c    chunk2mem dup ok
496 @c    chunksize dup ok
497 @c    chunk_at_offset dup ok
498 @c    heap_for_ptr ok
499 @c    grow_heap ok
500 @c     mprotect ok
501 @c    set_head dup ok
502 @c    new_heap @acsmem
503 @c     MMAP dup @acsmem
504 @c     munmap @acsmem
505 @c    top ok
506 @c    set_foot dup ok
507 @c    contiguous ok
508 @c    MORECORE ok
509 @c     *__morecore ok unguarded
510 @c      __default_morecore
511 @c       sbrk ok
512 @c    force_reg dup ok
513 @c    *__after_morecore_hook unguarded
514 @c    set_noncontiguous ok
515 @c    malloc_printerr dup ok
516 @c    _int_free (have_lock) @acsfd @acsmem [@asulock @aculock]
517 @c     chunksize dup ok
518 @c     mutex_unlock dup @aculock/!have_lock
519 @c     malloc_printerr dup ok
520 @c     check_inuse_chunk ok/disabled
521 @c     chunk_at_offset dup ok
522 @c     mutex_lock dup @asulock @aculock/@have_lock
523 @c     chunk2mem dup ok
524 @c     free_perturb ok
525 @c     set_fastchunks ok
526 @c      catomic_and ok
527 @c     fastbin_index dup ok
528 @c     fastbin dup ok
529 @c     catomic_compare_and_exchange_val_rel ok
530 @c     chunk_is_mmapped ok
531 @c     contiguous dup ok
532 @c     prev_inuse ok
533 @c     unlink dup ok
534 @c     inuse_bit_at_offset dup ok
535 @c     clear_inuse_bit_at_offset ok
536 @c     unsorted_chunks dup ok
537 @c     in_smallbin_range dup ok
538 @c     set_head dup ok
539 @c     set_foot dup ok
540 @c     check_free_chunk ok/disabled
541 @c     check_chunk dup ok/disabled
542 @c     have_fastchunks dup ok
543 @c     malloc_consolidate dup ok
544 @c     systrim ok
545 @c      MORECORE dup ok
546 @c      *__after_morecore_hook dup unguarded
547 @c      set_head dup ok
548 @c      check_malloc_state ok/disabled
549 @c     top dup ok
550 @c     heap_for_ptr dup ok
551 @c     heap_trim @acsfd @acsmem
552 @c      top dup ok
553 @c      chunk_at_offset dup ok
554 @c      prev_chunk ok
555 @c      chunksize dup ok
556 @c      prev_inuse dup ok
557 @c      delete_heap @acsmem
558 @c       munmap dup @acsmem
559 @c      unlink dup ok
560 @c      set_head dup ok
561 @c      shrink_heap @acsfd
562 @c       check_may_shrink_heap @acsfd
563 @c        open_not_cancel_2 @acsfd
564 @c        read_not_cancel ok
565 @c        close_not_cancel_no_status @acsfd
566 @c       MMAP dup ok
567 @c       madvise ok
568 @c     munmap_chunk @acsmem
569 @c      chunksize dup ok
570 @c      chunk_is_mmapped dup ok
571 @c      chunk2mem dup ok
572 @c      malloc_printerr dup ok
573 @c      munmap dup @acsmem
574 @c    check_malloc_state ok/disabled
575 @c  arena_get_retry @asulock @aculock @acsfd @acsmem
576 @c   mutex_unlock dup @aculock
577 @c   mutex_lock dup @asulock @aculock
578 @c   arena_get2 dup @asulock @aculock @acsfd @acsmem
579 @c  mutex_unlock @aculock
580 @c  mem2chunk ok
581 @c  chunk_is_mmapped ok
582 @c  arena_for_chunk ok
583 @c   chunk_non_main_arena ok
584 @c   heap_for_ptr ok
585 This function returns a pointer to a newly allocated block @var{size}
586 bytes long, or a null pointer if the block could not be allocated.
587 @end deftypefun
589 The contents of the block are undefined; you must initialize it yourself
590 (or use @code{calloc} instead; @pxref{Allocating Cleared Space}).
591 Normally you would cast the value as a pointer to the kind of object
592 that you want to store in the block.  Here we show an example of doing
593 so, and of initializing the space with zeros using the library function
594 @code{memset} (@pxref{Copying Strings and Arrays}):
596 @smallexample
597 struct foo *ptr;
598 @dots{}
599 ptr = (struct foo *) malloc (sizeof (struct foo));
600 if (ptr == 0) abort ();
601 memset (ptr, 0, sizeof (struct foo));
602 @end smallexample
604 You can store the result of @code{malloc} into any pointer variable
605 without a cast, because @w{ISO C} automatically converts the type
606 @code{void *} to another type of pointer when necessary.  But the cast
607 is necessary in contexts other than assignment operators or if you might
608 want your code to run in traditional C.
610 Remember that when allocating space for a string, the argument to
611 @code{malloc} must be one plus the length of the string.  This is
612 because a string is terminated with a null character that doesn't count
613 in the ``length'' of the string but does need space.  For example:
615 @smallexample
616 char *ptr;
617 @dots{}
618 ptr = (char *) malloc (length + 1);
619 @end smallexample
621 @noindent
622 @xref{Representation of Strings}, for more information about this.
624 @node Malloc Examples
625 @subsubsection Examples of @code{malloc}
627 If no more space is available, @code{malloc} returns a null pointer.
628 You should check the value of @emph{every} call to @code{malloc}.  It is
629 useful to write a subroutine that calls @code{malloc} and reports an
630 error if the value is a null pointer, returning only if the value is
631 nonzero.  This function is conventionally called @code{xmalloc}.  Here
632 it is:
634 @smallexample
635 void *
636 xmalloc (size_t size)
638   void *value = malloc (size);
639   if (value == 0)
640     fatal ("virtual memory exhausted");
641   return value;
643 @end smallexample
645 Here is a real example of using @code{malloc} (by way of @code{xmalloc}).
646 The function @code{savestring} will copy a sequence of characters into
647 a newly allocated null-terminated string:
649 @smallexample
650 @group
651 char *
652 savestring (const char *ptr, size_t len)
654   char *value = (char *) xmalloc (len + 1);
655   value[len] = '\0';
656   return (char *) memcpy (value, ptr, len);
658 @end group
659 @end smallexample
661 The block that @code{malloc} gives you is guaranteed to be aligned so
662 that it can hold any type of data.  On @gnusystems{}, the address is
663 always a multiple of eight on 32-bit systems, and a multiple of 16 on
664 64-bit systems.  Only rarely is any higher boundary (such as a page
665 boundary) necessary; for those cases, use @code{aligned_alloc} or
666 @code{posix_memalign} (@pxref{Aligned Memory Blocks}).
668 Note that the memory located after the end of the block is likely to be
669 in use for something else; perhaps a block already allocated by another
670 call to @code{malloc}.  If you attempt to treat the block as longer than
671 you asked for it to be, you are liable to destroy the data that
672 @code{malloc} uses to keep track of its blocks, or you may destroy the
673 contents of another block.  If you have already allocated a block and
674 discover you want it to be bigger, use @code{realloc} (@pxref{Changing
675 Block Size}).
677 @node Freeing after Malloc
678 @subsubsection Freeing Memory Allocated with @code{malloc}
679 @cindex freeing memory allocated with @code{malloc}
680 @cindex heap, freeing memory from
682 When you no longer need a block that you got with @code{malloc}, use the
683 function @code{free} to make the block available to be allocated again.
684 The prototype for this function is in @file{stdlib.h}.
685 @pindex stdlib.h
687 @deftypefun void free (void *@var{ptr})
688 @standards{ISO, malloc.h}
689 @standards{ISO, stdlib.h}
690 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
691 @c __libc_free @asulock @aculock @acsfd @acsmem
692 @c   releasing memory into fastbins modifies the arena without taking
693 @c   its mutex, but catomic operations ensure safety.  If two (or more)
694 @c   threads are running malloc and have their own arenas locked when
695 @c   each gets a signal whose handler free()s large (non-fastbin-able)
696 @c   blocks from each other's arena, we deadlock; this is a more general
697 @c   case of @asulock.
698 @c  *__free_hook unguarded
699 @c  mem2chunk ok
700 @c  chunk_is_mmapped ok, chunk bits not modified after allocation
701 @c  chunksize ok
702 @c  munmap_chunk dup @acsmem
703 @c  arena_for_chunk dup ok
704 @c  _int_free (!have_lock) dup @asulock @aculock @acsfd @acsmem
705 The @code{free} function deallocates the block of memory pointed at
706 by @var{ptr}.
707 @end deftypefun
709 Freeing a block alters the contents of the block.  @strong{Do not expect to
710 find any data (such as a pointer to the next block in a chain of blocks) in
711 the block after freeing it.}  Copy whatever you need out of the block before
712 freeing it!  Here is an example of the proper way to free all the blocks in
713 a chain, and the strings that they point to:
715 @smallexample
716 struct chain
717   @{
718     struct chain *next;
719     char *name;
720   @}
722 void
723 free_chain (struct chain *chain)
725   while (chain != 0)
726     @{
727       struct chain *next = chain->next;
728       free (chain->name);
729       free (chain);
730       chain = next;
731     @}
733 @end smallexample
735 Occasionally, @code{free} can actually return memory to the operating
736 system and make the process smaller.  Usually, all it can do is allow a
737 later call to @code{malloc} to reuse the space.  In the meantime, the
738 space remains in your program as part of a free-list used internally by
739 @code{malloc}.
741 There is no point in freeing blocks at the end of a program, because all
742 of the program's space is given back to the system when the process
743 terminates.
745 @node Changing Block Size
746 @subsubsection Changing the Size of a Block
747 @cindex changing the size of a block (@code{malloc})
749 Often you do not know for certain how big a block you will ultimately need
750 at the time you must begin to use the block.  For example, the block might
751 be a buffer that you use to hold a line being read from a file; no matter
752 how long you make the buffer initially, you may encounter a line that is
753 longer.
755 You can make the block longer by calling @code{realloc} or
756 @code{reallocarray}.  These functions are declared in @file{stdlib.h}.
757 @pindex stdlib.h
759 @deftypefun {void *} realloc (void *@var{ptr}, size_t @var{newsize})
760 @standards{ISO, malloc.h}
761 @standards{ISO, stdlib.h}
762 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
763 @c It may call the implementations of malloc and free, so all of their
764 @c issues arise, plus the realloc hook, also accessed without guards.
766 @c __libc_realloc @asulock @aculock @acsfd @acsmem
767 @c  *__realloc_hook unguarded
768 @c  __libc_free dup @asulock @aculock @acsfd @acsmem
769 @c  __libc_malloc dup @asulock @aculock @acsfd @acsmem
770 @c  mem2chunk dup ok
771 @c  chunksize dup ok
772 @c  malloc_printerr dup ok
773 @c  checked_request2size dup ok
774 @c  chunk_is_mmapped dup ok
775 @c  mremap_chunk
776 @c   chunksize dup ok
777 @c   __mremap ok
778 @c   set_head dup ok
779 @c  MALLOC_COPY ok
780 @c   memcpy ok
781 @c  munmap_chunk dup @acsmem
782 @c  arena_for_chunk dup ok
783 @c  mutex_lock (arena mutex) dup @asulock @aculock
784 @c  _int_realloc @acsfd @acsmem
785 @c   malloc_printerr dup ok
786 @c   check_inuse_chunk dup ok/disabled
787 @c   chunk_at_offset dup ok
788 @c   chunksize dup ok
789 @c   set_head_size dup ok
790 @c   chunk_at_offset dup ok
791 @c   set_head dup ok
792 @c   chunk2mem dup ok
793 @c   inuse dup ok
794 @c   unlink dup ok
795 @c   _int_malloc dup @acsfd @acsmem
796 @c   mem2chunk dup ok
797 @c   MALLOC_COPY dup ok
798 @c   _int_free (have_lock) dup @acsfd @acsmem
799 @c   set_inuse_bit_at_offset dup ok
800 @c   set_head dup ok
801 @c  mutex_unlock (arena mutex) dup @aculock
802 @c  _int_free (!have_lock) dup @asulock @aculock @acsfd @acsmem
804 The @code{realloc} function changes the size of the block whose address is
805 @var{ptr} to be @var{newsize}.
807 Since the space after the end of the block may be in use, @code{realloc}
808 may find it necessary to copy the block to a new address where more free
809 space is available.  The value of @code{realloc} is the new address of the
810 block.  If the block needs to be moved, @code{realloc} copies the old
811 contents.
813 If you pass a null pointer for @var{ptr}, @code{realloc} behaves just
814 like @samp{malloc (@var{newsize})}.  This can be convenient, but beware
815 that older implementations (before @w{ISO C}) may not support this
816 behavior, and will probably crash when @code{realloc} is passed a null
817 pointer.
818 @end deftypefun
820 @deftypefun {void *} reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size})
821 @standards{BSD, malloc.h}
822 @standards{BSD, stdlib.h}
823 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
825 The @code{reallocarray} function changes the size of the block whose address
826 is @var{ptr} to be long enough to contain a vector of @var{nmemb} elements,
827 each of size @var{size}.  It is equivalent to @samp{realloc (@var{ptr},
828 @var{nmemb} * @var{size})}, except that @code{reallocarray} fails safely if
829 the multiplication overflows, by setting @code{errno} to @code{ENOMEM},
830 returning a null pointer, and leaving the original block unchanged.
832 @code{reallocarray} should be used instead of @code{realloc} when the new size
833 of the allocated block is the result of a multiplication that might overflow.
835 @strong{Portability Note:} This function is not part of any standard.  It was
836 first introduced in OpenBSD 5.6.
837 @end deftypefun
839 Like @code{malloc}, @code{realloc} and @code{reallocarray} may return a null
840 pointer if no memory space is available to make the block bigger.  When this
841 happens, the original block is untouched; it has not been modified or
842 relocated.
844 In most cases it makes no difference what happens to the original block
845 when @code{realloc} fails, because the application program cannot continue
846 when it is out of memory, and the only thing to do is to give a fatal error
847 message.  Often it is convenient to write and use a subroutine,
848 conventionally called @code{xrealloc}, that takes care of the error message
849 as @code{xmalloc} does for @code{malloc}:
851 @smallexample
852 void *
853 xrealloc (void *ptr, size_t size)
855   void *value = realloc (ptr, size);
856   if (value == 0)
857     fatal ("Virtual memory exhausted");
858   return value;
860 @end smallexample
862 You can also use @code{realloc} or @code{reallocarray} to make a block
863 smaller.  The reason you would do this is to avoid tying up a lot of memory
864 space when only a little is needed.
865 @comment The following is no longer true with the new malloc.
866 @comment But it seems wise to keep the warning for other implementations.
867 In several allocation implementations, making a block smaller sometimes
868 necessitates copying it, so it can fail if no other space is available.
870 If the new size you specify is the same as the old size, @code{realloc} and
871 @code{reallocarray} are guaranteed to change nothing and return the same
872 address that you gave.
874 @node Allocating Cleared Space
875 @subsubsection Allocating Cleared Space
877 The function @code{calloc} allocates memory and clears it to zero.  It
878 is declared in @file{stdlib.h}.
879 @pindex stdlib.h
881 @deftypefun {void *} calloc (size_t @var{count}, size_t @var{eltsize})
882 @standards{ISO, malloc.h}
883 @standards{ISO, stdlib.h}
884 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
885 @c Same caveats as malloc.
887 @c __libc_calloc @asulock @aculock @acsfd @acsmem
888 @c  *__malloc_hook dup unguarded
889 @c  memset dup ok
890 @c  arena_get @asulock @aculock @acsfd @acsmem
891 @c   arena_lock dup @asulock @aculock @acsfd @acsmem
892 @c  top dup ok
893 @c  chunksize dup ok
894 @c  heap_for_ptr dup ok
895 @c  _int_malloc dup @acsfd @acsmem
896 @c  arena_get_retry dup @asulock @aculock @acsfd @acsmem
897 @c  mutex_unlock dup @aculock
898 @c  mem2chunk dup ok
899 @c  chunk_is_mmapped dup ok
900 @c  MALLOC_ZERO ok
901 @c   memset dup ok
902 This function allocates a block long enough to contain a vector of
903 @var{count} elements, each of size @var{eltsize}.  Its contents are
904 cleared to zero before @code{calloc} returns.
905 @end deftypefun
907 You could define @code{calloc} as follows:
909 @smallexample
910 void *
911 calloc (size_t count, size_t eltsize)
913   size_t size = count * eltsize;
914   void *value = malloc (size);
915   if (value != 0)
916     memset (value, 0, size);
917   return value;
919 @end smallexample
921 But in general, it is not guaranteed that @code{calloc} calls
922 @code{malloc} internally.  Therefore, if an application provides its own
923 @code{malloc}/@code{realloc}/@code{free} outside the C library, it
924 should always define @code{calloc}, too.
926 @node Aligned Memory Blocks
927 @subsubsection Allocating Aligned Memory Blocks
929 @cindex page boundary
930 @cindex alignment (with @code{malloc})
931 @pindex stdlib.h
932 The address of a block returned by @code{malloc} or @code{realloc} in
933 @gnusystems{} is always a multiple of eight (or sixteen on 64-bit
934 systems).  If you need a block whose address is a multiple of a higher
935 power of two than that, use @code{aligned_alloc} or @code{posix_memalign}.
936 @code{aligned_alloc} and @code{posix_memalign} are declared in
937 @file{stdlib.h}.
939 @deftypefun {void *} aligned_alloc (size_t @var{alignment}, size_t @var{size})
940 @standards{???, stdlib.h}
941 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
942 @c Alias to memalign.
943 The @code{aligned_alloc} function allocates a block of @var{size} bytes whose
944 address is a multiple of @var{alignment}.  The @var{alignment} must be a
945 power of two and @var{size} must be a multiple of @var{alignment}.
947 The @code{aligned_alloc} function returns a null pointer on error and sets
948 @code{errno} to one of the following values:
950 @table @code
951 @item ENOMEM
952 There was insufficient memory available to satisfy the request.
954 @item EINVAL
955 @var{alignment} is not a power of two.
957 This function was introduced in @w{ISO C11} and hence may have better
958 portability to modern non-POSIX systems than @code{posix_memalign}.
959 @end table
961 @end deftypefun
963 @deftypefun {void *} memalign (size_t @var{boundary}, size_t @var{size})
964 @standards{BSD, malloc.h}
965 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
966 @c Same issues as malloc.  The padding bytes are safely freed in
967 @c _int_memalign, with the arena still locked.
969 @c __libc_memalign @asulock @aculock @acsfd @acsmem
970 @c  *__memalign_hook dup unguarded
971 @c  __libc_malloc dup @asulock @aculock @acsfd @acsmem
972 @c  arena_get dup @asulock @aculock @acsfd @acsmem
973 @c  _int_memalign @acsfd @acsmem
974 @c   _int_malloc dup @acsfd @acsmem
975 @c   checked_request2size dup ok
976 @c   mem2chunk dup ok
977 @c   chunksize dup ok
978 @c   chunk_is_mmapped dup ok
979 @c   set_head dup ok
980 @c   chunk2mem dup ok
981 @c   set_inuse_bit_at_offset dup ok
982 @c   set_head_size dup ok
983 @c   _int_free (have_lock) dup @acsfd @acsmem
984 @c   chunk_at_offset dup ok
985 @c   check_inuse_chunk dup ok
986 @c  arena_get_retry dup @asulock @aculock @acsfd @acsmem
987 @c  mutex_unlock dup @aculock
988 The @code{memalign} function allocates a block of @var{size} bytes whose
989 address is a multiple of @var{boundary}.  The @var{boundary} must be a
990 power of two!  The function @code{memalign} works by allocating a
991 somewhat larger block, and then returning an address within the block
992 that is on the specified boundary.
994 The @code{memalign} function returns a null pointer on error and sets
995 @code{errno} to one of the following values:
997 @table @code
998 @item ENOMEM
999 There was insufficient memory available to satisfy the request.
1001 @item EINVAL
1002 @var{boundary} is not a power of two.
1004 @end table
1006 The @code{memalign} function is obsolete and @code{aligned_alloc} or
1007 @code{posix_memalign} should be used instead.
1008 @end deftypefun
1010 @deftypefun int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
1011 @standards{POSIX, stdlib.h}
1012 @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
1013 @c Calls memalign unless the requirements are not met (powerof2 macro is
1014 @c safe given an automatic variable as an argument) or there's a
1015 @c memalign hook (accessed unguarded, but safely).
1016 The @code{posix_memalign} function is similar to the @code{memalign}
1017 function in that it returns a buffer of @var{size} bytes aligned to a
1018 multiple of @var{alignment}.  But it adds one requirement to the
1019 parameter @var{alignment}: the value must be a power of two multiple of
1020 @code{sizeof (void *)}.
1022 If the function succeeds in allocation memory a pointer to the allocated
1023 memory is returned in @code{*@var{memptr}} and the return value is zero.
1024 Otherwise the function returns an error value indicating the problem.
1025 The possible error values returned are:
1027 @table @code
1028 @item ENOMEM
1029 There was insufficient memory available to satisfy the request.
1031 @item EINVAL
1032 @var{alignment} is not a power of two multiple of @code{sizeof (void *)}.
1034 @end table
1036 This function was introduced in POSIX 1003.1d.  Although this function is
1037 superseded by @code{aligned_alloc}, it is more portable to older POSIX
1038 systems that do not support @w{ISO C11}.
1039 @end deftypefun
1041 @deftypefun {void *} valloc (size_t @var{size})
1042 @standards{BSD, malloc.h}
1043 @standards{BSD, stdlib.h}
1044 @safety{@prelim{}@mtunsafe{@mtuinit{}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{} @acsfd{} @acsmem{}}}
1045 @c __libc_valloc @mtuinit @asuinit @asulock @aculock @acsfd @acsmem
1046 @c  ptmalloc_init (once) @mtsenv @asulock @aculock @acsfd @acsmem
1047 @c   _dl_addr @asucorrupt? @aculock
1048 @c    __rtld_lock_lock_recursive (dl_load_lock) @asucorrupt? @aculock
1049 @c    _dl_find_dso_for_object ok, iterates over dl_ns and its _ns_loaded objs
1050 @c      the ok above assumes no partial updates on dl_ns and _ns_loaded
1051 @c      that could confuse a _dl_addr call in a signal handler
1052 @c     _dl_addr_inside_object ok
1053 @c    determine_info ok
1054 @c    __rtld_lock_unlock_recursive (dl_load_lock) @aculock
1055 @c   *_environ @mtsenv
1056 @c   next_env_entry ok
1057 @c   strcspn dup ok
1058 @c   __libc_mallopt dup @mtasuconst:mallopt [setting mp_]
1059 @c   __malloc_check_init @mtasuconst:malloc_hooks [setting hooks]
1060 @c   *__malloc_initialize_hook unguarded, ok
1061 @c  *__memalign_hook dup ok, unguarded
1062 @c  arena_get dup @asulock @aculock @acsfd @acsmem
1063 @c  _int_valloc @acsfd @acsmem
1064 @c   malloc_consolidate dup ok
1065 @c   _int_memalign dup @acsfd @acsmem
1066 @c  arena_get_retry dup @asulock @aculock @acsfd @acsmem
1067 @c  _int_memalign dup @acsfd @acsmem
1068 @c  mutex_unlock dup @aculock
1069 Using @code{valloc} is like using @code{memalign} and passing the page size
1070 as the value of the first argument.  It is implemented like this:
1072 @smallexample
1073 void *
1074 valloc (size_t size)
1076   return memalign (getpagesize (), size);
1078 @end smallexample
1080 @ref{Query Memory Parameters} for more information about the memory
1081 subsystem.
1083 The @code{valloc} function is obsolete and @code{aligned_alloc} or
1084 @code{posix_memalign} should be used instead.
1085 @end deftypefun
1087 @node Malloc Tunable Parameters
1088 @subsubsection Malloc Tunable Parameters
1090 You can adjust some parameters for dynamic memory allocation with the
1091 @code{mallopt} function.  This function is the general SVID/XPG
1092 interface, defined in @file{malloc.h}.
1093 @pindex malloc.h
1095 @deftypefun int mallopt (int @var{param}, int @var{value})
1096 @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
1097 @c __libc_mallopt @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock
1098 @c  ptmalloc_init (once) dup @mtsenv @asulock @aculock @acsfd @acsmem
1099 @c  mutex_lock (main_arena->mutex) @asulock @aculock
1100 @c  malloc_consolidate dup ok
1101 @c  set_max_fast ok
1102 @c  mutex_unlock dup @aculock
1104 When calling @code{mallopt}, the @var{param} argument specifies the
1105 parameter to be set, and @var{value} the new value to be set.  Possible
1106 choices for @var{param}, as defined in @file{malloc.h}, are:
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 to a
1313 non-zero value, a special (less efficient) implementation is used which
1314 is designed to be tolerant against simple errors, such as double calls
1315 of @code{free} with the same argument, or overruns of a single byte
1316 (off-by-one bugs).  Not all such errors can be protected against,
1317 however, and memory leaks can result.
1319 Any detected heap corruption results in immediate termination of the
1320 process.
1322 There is one problem with @code{MALLOC_CHECK_}: in SUID or SGID binaries
1323 it could possibly be exploited since diverging from the normal programs
1324 behavior it now writes something to the standard error descriptor.
1325 Therefore the use of @code{MALLOC_CHECK_} is disabled by default for
1326 SUID and SGID binaries.  It can be enabled again by the system
1327 administrator by adding a file @file{/etc/suid-debug} (the content is
1328 not important it could be empty).
1330 So, what's the difference between using @code{MALLOC_CHECK_} and linking
1331 with @samp{-lmcheck}?  @code{MALLOC_CHECK_} is orthogonal with respect to
1332 @samp{-lmcheck}.  @samp{-lmcheck} has been added for backward
1333 compatibility.  Both @code{MALLOC_CHECK_} and @samp{-lmcheck} should
1334 uncover the same bugs - but using @code{MALLOC_CHECK_} you don't need to
1335 recompile your application.
1337 @node Hooks for Malloc
1338 @subsubsection Memory Allocation Hooks
1339 @cindex allocation hooks, for @code{malloc}
1341 @Theglibc{} lets you modify the behavior of @code{malloc},
1342 @code{realloc}, and @code{free} by specifying appropriate hook
1343 functions.  You can use these hooks to help you debug programs that use
1344 dynamic memory allocation, for example.
1346 The hook variables are declared in @file{malloc.h}.
1347 @pindex malloc.h
1349 @defvar __malloc_hook
1350 @standards{GNU, malloc.h}
1351 The value of this variable is a pointer to the function that
1352 @code{malloc} uses whenever it is called.  You should define this
1353 function to look like @code{malloc}; that is, like:
1355 @smallexample
1356 void *@var{function} (size_t @var{size}, const void *@var{caller})
1357 @end smallexample
1359 The value of @var{caller} is the return address found on the stack when
1360 the @code{malloc} function was called.  This value allows you to trace
1361 the memory consumption of the program.
1362 @end defvar
1364 @defvar __realloc_hook
1365 @standards{GNU, malloc.h}
1366 The value of this variable is a pointer to function that @code{realloc}
1367 uses whenever it is called.  You should define this function to look
1368 like @code{realloc}; that is, like:
1370 @smallexample
1371 void *@var{function} (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
1372 @end smallexample
1374 The value of @var{caller} is the return address found on the stack when
1375 the @code{realloc} function was called.  This value allows you to trace the
1376 memory consumption of the program.
1377 @end defvar
1379 @defvar __free_hook
1380 @standards{GNU, malloc.h}
1381 The value of this variable is a pointer to function that @code{free}
1382 uses whenever it is called.  You should define this function to look
1383 like @code{free}; that is, like:
1385 @smallexample
1386 void @var{function} (void *@var{ptr}, const void *@var{caller})
1387 @end smallexample
1389 The value of @var{caller} is the return address found on the stack when
1390 the @code{free} function was called.  This value allows you to trace the
1391 memory consumption of the program.
1392 @end defvar
1394 @defvar __memalign_hook
1395 @standards{GNU, malloc.h}
1396 The value of this variable is a pointer to function that @code{aligned_alloc},
1397 @code{memalign}, @code{posix_memalign} and @code{valloc} use whenever they
1398 are called.  You should define this function to look like @code{aligned_alloc};
1399 that is, like:
1401 @smallexample
1402 void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller})
1403 @end smallexample
1405 The value of @var{caller} is the return address found on the stack when
1406 the @code{aligned_alloc}, @code{memalign}, @code{posix_memalign} or
1407 @code{valloc} functions are called.  This value allows you to trace the
1408 memory consumption of the program.
1409 @end defvar
1411 You must make sure that the function you install as a hook for one of
1412 these functions does not call that function recursively without restoring
1413 the old value of the hook first!  Otherwise, your program will get stuck
1414 in an infinite recursion.  Before calling the function recursively, one
1415 should make sure to restore all the hooks to their previous value.  When
1416 coming back from the recursive call, all the hooks should be resaved
1417 since a hook might modify itself.
1419 An issue to look out for is the time at which the malloc hook functions
1420 can be safely installed.  If the hook functions call the malloc-related
1421 functions recursively, it is necessary that malloc has already properly
1422 initialized itself at the time when @code{__malloc_hook} etc. is
1423 assigned to.  On the other hand, if the hook functions provide a
1424 complete malloc implementation of their own, it is vital that the hooks
1425 are assigned to @emph{before} the very first @code{malloc} call has
1426 completed, because otherwise a chunk obtained from the ordinary,
1427 un-hooked malloc may later be handed to @code{__free_hook}, for example.
1429 Here is an example showing how to use @code{__malloc_hook} and
1430 @code{__free_hook} properly.  It installs a function that prints out
1431 information every time @code{malloc} or @code{free} is called.  We just
1432 assume here that @code{realloc} and @code{memalign} are not used in our
1433 program.
1435 @smallexample
1436 /* Prototypes for __malloc_hook, __free_hook */
1437 #include <malloc.h>
1439 /* Prototypes for our hooks.  */
1440 static void my_init_hook (void);
1441 static void *my_malloc_hook (size_t, const void *);
1442 static void my_free_hook (void*, const void *);
1444 static void
1445 my_init (void)
1447   old_malloc_hook = __malloc_hook;
1448   old_free_hook = __free_hook;
1449   __malloc_hook = my_malloc_hook;
1450   __free_hook = my_free_hook;
1453 static void *
1454 my_malloc_hook (size_t size, const void *caller)
1456   void *result;
1457   /* Restore all old hooks */
1458   __malloc_hook = old_malloc_hook;
1459   __free_hook = old_free_hook;
1460   /* Call recursively */
1461   result = malloc (size);
1462   /* Save underlying hooks */
1463   old_malloc_hook = __malloc_hook;
1464   old_free_hook = __free_hook;
1465   /* @r{@code{printf} might call @code{malloc}, so protect it too.} */
1466   printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
1467   /* Restore our own hooks */
1468   __malloc_hook = my_malloc_hook;
1469   __free_hook = my_free_hook;
1470   return result;
1473 static void
1474 my_free_hook (void *ptr, const void *caller)
1476   /* Restore all old hooks */
1477   __malloc_hook = old_malloc_hook;
1478   __free_hook = old_free_hook;
1479   /* Call recursively */
1480   free (ptr);
1481   /* Save underlying hooks */
1482   old_malloc_hook = __malloc_hook;
1483   old_free_hook = __free_hook;
1484   /* @r{@code{printf} might call @code{free}, so protect it too.} */
1485   printf ("freed pointer %p\n", ptr);
1486   /* Restore our own hooks */
1487   __malloc_hook = my_malloc_hook;
1488   __free_hook = my_free_hook;
1491 main ()
1493   my_init ();
1494   @dots{}
1496 @end smallexample
1498 The @code{mcheck} function (@pxref{Heap Consistency Checking}) works by
1499 installing such hooks.
1501 @c __morecore, __after_morecore_hook are undocumented
1502 @c It's not clear whether to document them.
1504 @node Statistics of Malloc
1505 @subsubsection Statistics for Memory Allocation with @code{malloc}
1507 @cindex allocation statistics
1508 You can get information about dynamic memory allocation by calling the
1509 @code{mallinfo} function.  This function and its associated data type
1510 are declared in @file{malloc.h}; they are an extension of the standard
1511 SVID/XPG version.
1512 @pindex malloc.h
1514 @deftp {Data Type} {struct mallinfo}
1515 @standards{GNU, malloc.h}
1516 This structure type is used to return information about the dynamic
1517 memory allocator.  It contains the following members:
1519 @table @code
1520 @item int arena
1521 This is the total size of memory allocated with @code{sbrk} by
1522 @code{malloc}, in bytes.
1524 @item int ordblks
1525 This is the number of chunks not in use.  (The memory allocator
1526 internally gets chunks of memory from the operating system, and then
1527 carves them up to satisfy individual @code{malloc} requests;
1528 @pxref{The GNU Allocator}.)
1530 @item int smblks
1531 This field is unused.
1533 @item int hblks
1534 This is the total number of chunks allocated with @code{mmap}.
1536 @item int hblkhd
1537 This is the total size of memory allocated with @code{mmap}, in bytes.
1539 @item int usmblks
1540 This field is unused and always 0.
1542 @item int fsmblks
1543 This field is unused.
1545 @item int uordblks
1546 This is the total size of memory occupied by chunks handed out by
1547 @code{malloc}.
1549 @item int fordblks
1550 This is the total size of memory occupied by free (not in use) chunks.
1552 @item int keepcost
1553 This is the size of the top-most releasable chunk that normally
1554 borders the end of the heap (i.e., the high end of the virtual address
1555 space's data segment).
1557 @end table
1558 @end deftp
1560 @deftypefun {struct mallinfo} mallinfo (void)
1561 @standards{SVID, malloc.h}
1562 @safety{@prelim{}@mtunsafe{@mtuinit{} @mtasuconst{:mallopt}}@asunsafe{@asuinit{} @asulock{}}@acunsafe{@acuinit{} @aculock{}}}
1563 @c Accessing mp_.n_mmaps and mp_.max_mmapped_mem, modified with atomics
1564 @c but non-atomically elsewhere, may get us inconsistent results.  We
1565 @c mark the statistics as unsafe, rather than the fast-path functions
1566 @c that collect the possibly inconsistent data.
1568 @c __libc_mallinfo @mtuinit @mtasuconst:mallopt @asuinit @asulock @aculock
1569 @c  ptmalloc_init (once) dup @mtsenv @asulock @aculock @acsfd @acsmem
1570 @c  mutex_lock dup @asulock @aculock
1571 @c  int_mallinfo @mtasuconst:mallopt [mp_ access on main_arena]
1572 @c   malloc_consolidate dup ok
1573 @c   check_malloc_state dup ok/disabled
1574 @c   chunksize dup ok
1575 @c   fastbin dupo ok
1576 @c   bin_at dup ok
1577 @c   last dup ok
1578 @c  mutex_unlock @aculock
1580 This function returns information about the current dynamic memory usage
1581 in a structure of type @code{struct mallinfo}.
1582 @end deftypefun
1584 @node Summary of Malloc
1585 @subsubsection Summary of @code{malloc}-Related Functions
1587 Here is a summary of the functions that work with @code{malloc}:
1589 @table @code
1590 @item void *malloc (size_t @var{size})
1591 Allocate a block of @var{size} bytes.  @xref{Basic Allocation}.
1593 @item void free (void *@var{addr})
1594 Free a block previously allocated by @code{malloc}.  @xref{Freeing after
1595 Malloc}.
1597 @item void *realloc (void *@var{addr}, size_t @var{size})
1598 Make a block previously allocated by @code{malloc} larger or smaller,
1599 possibly by copying it to a new location.  @xref{Changing Block Size}.
1601 @item void *reallocarray (void *@var{ptr}, size_t @var{nmemb}, size_t @var{size})
1602 Change the size of a block previously allocated by @code{malloc} to
1603 @code{@var{nmemb} * @var{size}} bytes as with @code{realloc}.  @xref{Changing
1604 Block Size}.
1606 @item void *calloc (size_t @var{count}, size_t @var{eltsize})
1607 Allocate a block of @var{count} * @var{eltsize} bytes using
1608 @code{malloc}, and set its contents to zero.  @xref{Allocating Cleared
1609 Space}.
1611 @item void *valloc (size_t @var{size})
1612 Allocate a block of @var{size} bytes, starting on a page boundary.
1613 @xref{Aligned Memory Blocks}.
1615 @item void *aligned_alloc (size_t @var{size}, size_t @var{alignment})
1616 Allocate a block of @var{size} bytes, starting on an address that is a
1617 multiple of @var{alignment}.  @xref{Aligned Memory Blocks}.
1619 @item int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
1620 Allocate a block of @var{size} bytes, starting on an address that is a
1621 multiple of @var{alignment}.  @xref{Aligned Memory Blocks}.
1623 @item void *memalign (size_t @var{size}, size_t @var{boundary})
1624 Allocate a block of @var{size} bytes, starting on an address that is a
1625 multiple of @var{boundary}.  @xref{Aligned Memory Blocks}.
1627 @item int mallopt (int @var{param}, int @var{value})
1628 Adjust a tunable parameter.  @xref{Malloc Tunable Parameters}.
1630 @item int mcheck (void (*@var{abortfn}) (void))
1631 Tell @code{malloc} to perform occasional consistency checks on
1632 dynamically allocated memory, and to call @var{abortfn} when an
1633 inconsistency is found.  @xref{Heap Consistency Checking}.
1635 @item void *(*__malloc_hook) (size_t @var{size}, const void *@var{caller})
1636 A pointer to a function that @code{malloc} uses whenever it is called.
1638 @item void *(*__realloc_hook) (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
1639 A pointer to a function that @code{realloc} uses whenever it is called.
1641 @item void (*__free_hook) (void *@var{ptr}, const void *@var{caller})
1642 A pointer to a function that @code{free} uses whenever it is called.
1644 @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller})
1645 A pointer to a function that @code{aligned_alloc}, @code{memalign},
1646 @code{posix_memalign} and @code{valloc} use whenever they are called.
1648 @item struct mallinfo mallinfo (void)
1649 Return information about the current dynamic memory usage.
1650 @xref{Statistics of Malloc}.
1651 @end table
1653 @node Allocation Debugging
1654 @subsection Allocation Debugging
1655 @cindex allocation debugging
1656 @cindex malloc debugger
1658 A complicated task when programming with languages which do not use
1659 garbage collected dynamic memory allocation is to find memory leaks.
1660 Long running programs must ensure that dynamically allocated objects are
1661 freed at the end of their lifetime.  If this does not happen the system
1662 runs out of memory, sooner or later.
1664 The @code{malloc} implementation in @theglibc{} provides some
1665 simple means to detect such leaks and obtain some information to find
1666 the location.  To do this the application must be started in a special
1667 mode which is enabled by an environment variable.  There are no speed
1668 penalties for the program if the debugging mode is not enabled.
1670 @menu
1671 * Tracing malloc::               How to install the tracing functionality.
1672 * Using the Memory Debugger::    Example programs excerpts.
1673 * Tips for the Memory Debugger:: Some more or less clever ideas.
1674 * Interpreting the traces::      What do all these lines mean?
1675 @end menu
1677 @node Tracing malloc
1678 @subsubsection How to install the tracing functionality
1680 @deftypefun void mtrace (void)
1681 @standards{GNU, mcheck.h}
1682 @safety{@prelim{}@mtunsafe{@mtsenv{} @mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtuinit{}}@asunsafe{@asuinit{} @ascuheap{} @asucorrupt{} @asulock{}}@acunsafe{@acuinit{} @acucorrupt{} @aculock{} @acsfd{} @acsmem{}}}
1683 @c Like the mcheck hooks, these are not designed with thread safety in
1684 @c mind, because the hook pointers are temporarily modified without
1685 @c regard to other threads, signals or cancellation.
1687 @c mtrace @mtuinit @mtasurace:mtrace @mtsenv @asuinit @ascuheap @asucorrupt @acuinit @acucorrupt @aculock @acsfd @acsmem
1688 @c  __libc_secure_getenv dup @mtsenv
1689 @c  malloc dup @ascuheap @acsmem
1690 @c  fopen dup @ascuheap @asulock @aculock @acsmem @acsfd
1691 @c  fcntl dup ok
1692 @c  setvbuf dup @aculock
1693 @c  fprintf dup (on newly-created stream) @aculock
1694 @c  __cxa_atexit (once) dup @asulock @aculock @acsmem
1695 @c  free dup @ascuheap @acsmem
1696 When the @code{mtrace} function is called it looks for an environment
1697 variable named @code{MALLOC_TRACE}.  This variable is supposed to
1698 contain a valid file name.  The user must have write access.  If the
1699 file already exists it is truncated.  If the environment variable is not
1700 set or it does not name a valid file which can be opened for writing
1701 nothing is done.  The behavior of @code{malloc} etc. is not changed.
1702 For obvious reasons this also happens if the application is installed
1703 with the SUID or SGID bit set.
1705 If the named file is successfully opened, @code{mtrace} installs special
1706 handlers for the functions @code{malloc}, @code{realloc}, and
1707 @code{free} (@pxref{Hooks for Malloc}).  From then on, all uses of these
1708 functions are traced and protocolled into the file.  There is now of
1709 course a speed penalty for all calls to the traced functions so tracing
1710 should not be enabled during normal use.
1712 This function is a GNU extension and generally not available on other
1713 systems.  The prototype can be found in @file{mcheck.h}.
1714 @end deftypefun
1716 @deftypefun void muntrace (void)
1717 @standards{GNU, mcheck.h}
1718 @safety{@prelim{}@mtunsafe{@mtasurace{:mtrace} @mtasuconst{:malloc_hooks} @mtslocale{}}@asunsafe{@asucorrupt{} @ascuheap{}}@acunsafe{@acucorrupt{} @acsmem{} @aculock{} @acsfd{}}}
1720 @c muntrace @mtasurace:mtrace @mtslocale @asucorrupt @ascuheap @acucorrupt @acsmem @aculock @acsfd
1721 @c  fprintf (fputs) dup @mtslocale @asucorrupt @ascuheap @acsmem @aculock @acucorrupt
1722 @c  fclose dup @ascuheap @asulock @aculock @acsmem @acsfd
1723 The @code{muntrace} function can be called after @code{mtrace} was used
1724 to enable tracing the @code{malloc} calls.  If no (successful) call of
1725 @code{mtrace} was made @code{muntrace} does nothing.
1727 Otherwise it deinstalls the handlers for @code{malloc}, @code{realloc},
1728 and @code{free} and then closes the protocol file.  No calls are
1729 protocolled anymore and the program runs again at full speed.
1731 This function is a GNU extension and generally not available on other
1732 systems.  The prototype can be found in @file{mcheck.h}.
1733 @end deftypefun
1735 @node Using the Memory Debugger
1736 @subsubsection Example program excerpts
1738 Even though the tracing functionality does not influence the runtime
1739 behavior of the program it is not a good idea to call @code{mtrace} in
1740 all programs.  Just imagine that you debug a program using @code{mtrace}
1741 and all other programs used in the debugging session also trace their
1742 @code{malloc} calls.  The output file would be the same for all programs
1743 and thus is unusable.  Therefore one should call @code{mtrace} only if
1744 compiled for debugging.  A program could therefore start like this:
1746 @example
1747 #include <mcheck.h>
1750 main (int argc, char *argv[])
1752 #ifdef DEBUGGING
1753   mtrace ();
1754 #endif
1755   @dots{}
1757 @end example
1759 This is all that is needed if you want to trace the calls during the
1760 whole runtime of the program.  Alternatively you can stop the tracing at
1761 any time with a call to @code{muntrace}.  It is even possible to restart
1762 the tracing again with a new call to @code{mtrace}.  But this can cause
1763 unreliable results since there may be calls of the functions which are
1764 not called.  Please note that not only the application uses the traced
1765 functions, also libraries (including the C library itself) use these
1766 functions.
1768 This last point is also why it is not a good idea to call @code{muntrace}
1769 before the program terminates.  The libraries are informed about the
1770 termination of the program only after the program returns from
1771 @code{main} or calls @code{exit} and so cannot free the memory they use
1772 before this time.
1774 So the best thing one can do is to call @code{mtrace} as the very first
1775 function in the program and never call @code{muntrace}.  So the program
1776 traces almost all uses of the @code{malloc} functions (except those
1777 calls which are executed by constructors of the program or used
1778 libraries).
1780 @node Tips for the Memory Debugger
1781 @subsubsection Some more or less clever ideas
1783 You know the situation.  The program is prepared for debugging and in
1784 all debugging sessions it runs well.  But once it is started without
1785 debugging the error shows up.  A typical example is a memory leak that
1786 becomes visible only when we turn off the debugging.  If you foresee
1787 such situations you can still win.  Simply use something equivalent to
1788 the following little program:
1790 @example
1791 #include <mcheck.h>
1792 #include <signal.h>
1794 static void
1795 enable (int sig)
1797   mtrace ();
1798   signal (SIGUSR1, enable);
1801 static void
1802 disable (int sig)
1804   muntrace ();
1805   signal (SIGUSR2, disable);
1809 main (int argc, char *argv[])
1811   @dots{}
1813   signal (SIGUSR1, enable);
1814   signal (SIGUSR2, disable);
1816   @dots{}
1818 @end example
1820 I.e., the user can start the memory debugger any time s/he wants if the
1821 program was started with @code{MALLOC_TRACE} set in the environment.
1822 The output will of course not show the allocations which happened before
1823 the first signal but if there is a memory leak this will show up
1824 nevertheless.
1826 @node Interpreting the traces
1827 @subsubsection Interpreting the traces
1829 If you take a look at the output it will look similar to this:
1831 @example
1832 = Start
1833 @ [0x8048209] - 0x8064cc8
1834 @ [0x8048209] - 0x8064ce0
1835 @ [0x8048209] - 0x8064cf8
1836 @ [0x80481eb] + 0x8064c48 0x14
1837 @ [0x80481eb] + 0x8064c60 0x14
1838 @ [0x80481eb] + 0x8064c78 0x14
1839 @ [0x80481eb] + 0x8064c90 0x14
1840 = End
1841 @end example
1843 What this all means is not really important since the trace file is not
1844 meant to be read by a human.  Therefore no attention is given to
1845 readability.  Instead there is a program which comes with @theglibc{}
1846 which interprets the traces and outputs a summary in an
1847 user-friendly way.  The program is called @code{mtrace} (it is in fact a
1848 Perl script) and it takes one or two arguments.  In any case the name of
1849 the file with the trace output must be specified.  If an optional
1850 argument precedes the name of the trace file this must be the name of
1851 the program which generated the trace.
1853 @example
1854 drepper$ mtrace tst-mtrace log
1855 No memory leaks.
1856 @end example
1858 In this case the program @code{tst-mtrace} was run and it produced a
1859 trace file @file{log}.  The message printed by @code{mtrace} shows there
1860 are no problems with the code, all allocated memory was freed
1861 afterwards.
1863 If we call @code{mtrace} on the example trace given above we would get a
1864 different outout:
1866 @example
1867 drepper$ mtrace errlog
1868 - 0x08064cc8 Free 2 was never alloc'd 0x8048209
1869 - 0x08064ce0 Free 3 was never alloc'd 0x8048209
1870 - 0x08064cf8 Free 4 was never alloc'd 0x8048209
1872 Memory not freed:
1873 -----------------
1874    Address     Size     Caller
1875 0x08064c48     0x14  at 0x80481eb
1876 0x08064c60     0x14  at 0x80481eb
1877 0x08064c78     0x14  at 0x80481eb
1878 0x08064c90     0x14  at 0x80481eb
1879 @end example
1881 We have called @code{mtrace} with only one argument and so the script
1882 has no chance to find out what is meant with the addresses given in the
1883 trace.  We can do better:
1885 @example
1886 drepper$ mtrace tst errlog
1887 - 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
1888 - 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
1889 - 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39
1891 Memory not freed:
1892 -----------------
1893    Address     Size     Caller
1894 0x08064c48     0x14  at /home/drepper/tst.c:33
1895 0x08064c60     0x14  at /home/drepper/tst.c:33
1896 0x08064c78     0x14  at /home/drepper/tst.c:33
1897 0x08064c90     0x14  at /home/drepper/tst.c:33
1898 @end example
1900 Suddenly the output makes much more sense and the user can see
1901 immediately where the function calls causing the trouble can be found.
1903 Interpreting this output is not complicated.  There are at most two
1904 different situations being detected.  First, @code{free} was called for
1905 pointers which were never returned by one of the allocation functions.
1906 This is usually a very bad problem and what this looks like is shown in
1907 the first three lines of the output.  Situations like this are quite
1908 rare and if they appear they show up very drastically: the program
1909 normally crashes.
1911 The other situation which is much harder to detect are memory leaks.  As
1912 you can see in the output the @code{mtrace} function collects all this
1913 information and so can say that the program calls an allocation function
1914 from line 33 in the source file @file{/home/drepper/tst-mtrace.c} four
1915 times without freeing this memory before the program terminates.
1916 Whether this is a real problem remains to be investigated.
1918 @node Replacing malloc
1919 @subsection Replacing @code{malloc}
1921 @cindex @code{malloc} replacement
1922 @cindex @code{LD_PRELOAD} and @code{malloc}
1923 @cindex alternative @code{malloc} implementations
1924 @cindex customizing @code{malloc}
1925 @cindex interposing @code{malloc}
1926 @cindex preempting @code{malloc}
1927 @cindex replacing @code{malloc}
1928 @Theglibc{} supports replacing the built-in @code{malloc} implementation
1929 with a different allocator with the same interface.  For dynamically
1930 linked programs, this happens through ELF symbol interposition, either
1931 using shared object dependencies or @code{LD_PRELOAD}.  For static
1932 linking, the @code{malloc} replacement library must be linked in before
1933 linking against @code{libc.a} (explicitly or implicitly).
1935 @strong{Note:} Failure to provide a complete set of replacement
1936 functions (that is, all the functions used by the application,
1937 @theglibc{}, and other linked-in libraries) can lead to static linking
1938 failures, and, at run time, to heap corruption and application crashes.
1940 The minimum set of functions which has to be provided by a custom
1941 @code{malloc} is given in the table below.
1943 @table @code
1944 @item malloc
1945 @item free
1946 @item calloc
1947 @item realloc
1948 @end table
1950 These @code{malloc}-related functions are required for @theglibc{} to
1951 work.@footnote{Versions of @theglibc{} before 2.25 required that a
1952 custom @code{malloc} defines @code{__libc_memalign} (with the same
1953 interface as the @code{memalign} function).}
1955 The @code{malloc} implementation in @theglibc{} provides additional
1956 functionality not used by the library itself, but which is often used by
1957 other system libraries and applications.  A general-purpose replacement
1958 @code{malloc} implementation should provide definitions of these
1959 functions, too.  Their names are listed in the following table.
1961 @table @code
1962 @item aligned_alloc
1963 @item malloc_usable_size
1964 @item memalign
1965 @item posix_memalign
1966 @item pvalloc
1967 @item valloc
1968 @end table
1970 In addition, very old applications may use the obsolete @code{cfree}
1971 function.
1973 Further @code{malloc}-related functions such as @code{mallopt} or
1974 @code{mallinfo} will not have any effect or return incorrect statistics
1975 when a replacement @code{malloc} is in use.  However, failure to replace
1976 these functions typically does not result in crashes or other incorrect
1977 application behavior, but may result in static linking failures.
1979 @node Obstacks
1980 @subsection Obstacks
1981 @cindex obstacks
1983 An @dfn{obstack} is a pool of memory containing a stack of objects.  You
1984 can create any number of separate obstacks, and then allocate objects in
1985 specified obstacks.  Within each obstack, the last object allocated must
1986 always be the first one freed, but distinct obstacks are independent of
1987 each other.
1989 Aside from this one constraint of order of freeing, obstacks are totally
1990 general: an obstack can contain any number of objects of any size.  They
1991 are implemented with macros, so allocation is usually very fast as long as
1992 the objects are usually small.  And the only space overhead per object is
1993 the padding needed to start each object on a suitable boundary.
1995 @menu
1996 * Creating Obstacks::           How to declare an obstack in your program.
1997 * Preparing for Obstacks::      Preparations needed before you can
1998                                  use obstacks.
1999 * Allocation in an Obstack::    Allocating objects in an obstack.
2000 * Freeing Obstack Objects::     Freeing objects in an obstack.
2001 * Obstack Functions::           The obstack functions are both
2002                                  functions and macros.
2003 * Growing Objects::             Making an object bigger by stages.
2004 * Extra Fast Growing::          Extra-high-efficiency (though more
2005                                  complicated) growing objects.
2006 * Status of an Obstack::        Inquiries about the status of an obstack.
2007 * Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
2008 * Obstack Chunks::              How obstacks obtain and release chunks;
2009                                  efficiency considerations.
2010 * Summary of Obstacks::
2011 @end menu
2013 @node Creating Obstacks
2014 @subsubsection Creating Obstacks
2016 The utilities for manipulating obstacks are declared in the header
2017 file @file{obstack.h}.
2018 @pindex obstack.h
2020 @deftp {Data Type} {struct obstack}
2021 @standards{GNU, obstack.h}
2022 An obstack is represented by a data structure of type @code{struct
2023 obstack}.  This structure has a small fixed size; it records the status
2024 of the obstack and how to find the space in which objects are allocated.
2025 It does not contain any of the objects themselves.  You should not try
2026 to access the contents of the structure directly; use only the functions
2027 described in this chapter.
2028 @end deftp
2030 You can declare variables of type @code{struct obstack} and use them as
2031 obstacks, or you can allocate obstacks dynamically like any other kind
2032 of object.  Dynamic allocation of obstacks allows your program to have a
2033 variable number of different stacks.  (You can even allocate an
2034 obstack structure in another obstack, but this is rarely useful.)
2036 All the functions that work with obstacks require you to specify which
2037 obstack to use.  You do this with a pointer of type @code{struct obstack
2038 *}.  In the following, we often say ``an obstack'' when strictly
2039 speaking the object at hand is such a pointer.
2041 The objects in the obstack are packed into large blocks called
2042 @dfn{chunks}.  The @code{struct obstack} structure points to a chain of
2043 the chunks currently in use.
2045 The obstack library obtains a new chunk whenever you allocate an object
2046 that won't fit in the previous chunk.  Since the obstack library manages
2047 chunks automatically, you don't need to pay much attention to them, but
2048 you do need to supply a function which the obstack library should use to
2049 get a chunk.  Usually you supply a function which uses @code{malloc}
2050 directly or indirectly.  You must also supply a function to free a chunk.
2051 These matters are described in the following section.
2053 @node Preparing for Obstacks
2054 @subsubsection Preparing for Using Obstacks
2056 Each source file in which you plan to use the obstack functions
2057 must include the header file @file{obstack.h}, like this:
2059 @smallexample
2060 #include <obstack.h>
2061 @end smallexample
2063 @findex obstack_chunk_alloc
2064 @findex obstack_chunk_free
2065 Also, if the source file uses the macro @code{obstack_init}, it must
2066 declare or define two functions or macros that will be called by the
2067 obstack library.  One, @code{obstack_chunk_alloc}, is used to allocate
2068 the chunks of memory into which objects are packed.  The other,
2069 @code{obstack_chunk_free}, is used to return chunks when the objects in
2070 them are freed.  These macros should appear before any use of obstacks
2071 in the source file.
2073 Usually these are defined to use @code{malloc} via the intermediary
2074 @code{xmalloc} (@pxref{Unconstrained Allocation}).  This is done with
2075 the following pair of macro definitions:
2077 @smallexample
2078 #define obstack_chunk_alloc xmalloc
2079 #define obstack_chunk_free free
2080 @end smallexample
2082 @noindent
2083 Though the memory you get using obstacks really comes from @code{malloc},
2084 using obstacks is faster because @code{malloc} is called less often, for
2085 larger blocks of memory.  @xref{Obstack Chunks}, for full details.
2087 At run time, before the program can use a @code{struct obstack} object
2088 as an obstack, it must initialize the obstack by calling
2089 @code{obstack_init}.
2091 @deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
2092 @standards{GNU, obstack.h}
2093 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{@acsmem{}}}
2094 @c obstack_init @mtsrace:obstack-ptr @acsmem
2095 @c  _obstack_begin @acsmem
2096 @c    chunkfun = obstack_chunk_alloc (suggested malloc)
2097 @c    freefun = obstack_chunk_free (suggested free)
2098 @c   *chunkfun @acsmem
2099 @c    obstack_chunk_alloc user-supplied
2100 @c   *obstack_alloc_failed_handler user-supplied
2101 @c    -> print_and_abort (default)
2103 @c print_and_abort
2104 @c  _ dup @ascuintl
2105 @c  fxprintf dup @asucorrupt @aculock @acucorrupt
2106 @c  exit @acucorrupt?
2107 Initialize obstack @var{obstack-ptr} for allocation of objects.  This
2108 function calls the obstack's @code{obstack_chunk_alloc} function.  If
2109 allocation of memory fails, the function pointed to by
2110 @code{obstack_alloc_failed_handler} is called.  The @code{obstack_init}
2111 function always returns 1 (Compatibility notice: Former versions of
2112 obstack returned 0 if allocation failed).
2113 @end deftypefun
2115 Here are two examples of how to allocate the space for an obstack and
2116 initialize it.  First, an obstack that is a static variable:
2118 @smallexample
2119 static struct obstack myobstack;
2120 @dots{}
2121 obstack_init (&myobstack);
2122 @end smallexample
2124 @noindent
2125 Second, an obstack that is itself dynamically allocated:
2127 @smallexample
2128 struct obstack *myobstack_ptr
2129   = (struct obstack *) xmalloc (sizeof (struct obstack));
2131 obstack_init (myobstack_ptr);
2132 @end smallexample
2134 @defvar obstack_alloc_failed_handler
2135 @standards{GNU, obstack.h}
2136 The value of this variable is a pointer to a function that
2137 @code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
2138 memory.  The default action is to print a message and abort.
2139 You should supply a function that either calls @code{exit}
2140 (@pxref{Program Termination}) or @code{longjmp} (@pxref{Non-Local
2141 Exits}) and doesn't return.
2143 @smallexample
2144 void my_obstack_alloc_failed (void)
2145 @dots{}
2146 obstack_alloc_failed_handler = &my_obstack_alloc_failed;
2147 @end smallexample
2149 @end defvar
2151 @node Allocation in an Obstack
2152 @subsubsection Allocation in an Obstack
2153 @cindex allocation (obstacks)
2155 The most direct way to allocate an object in an obstack is with
2156 @code{obstack_alloc}, which is invoked almost like @code{malloc}.
2158 @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
2159 @standards{GNU, obstack.h}
2160 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2161 @c obstack_alloc @mtsrace:obstack-ptr @acucorrupt @acsmem
2162 @c  obstack_blank dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2163 @c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2164 This allocates an uninitialized block of @var{size} bytes in an obstack
2165 and returns its address.  Here @var{obstack-ptr} specifies which obstack
2166 to allocate the block in; it is the address of the @code{struct obstack}
2167 object which represents the obstack.  Each obstack function or macro
2168 requires you to specify an @var{obstack-ptr} as the first argument.
2170 This function calls the obstack's @code{obstack_chunk_alloc} function if
2171 it needs to allocate a new chunk of memory; it calls
2172 @code{obstack_alloc_failed_handler} if allocation of memory by
2173 @code{obstack_chunk_alloc} failed.
2174 @end deftypefun
2176 For example, here is a function that allocates a copy of a string @var{str}
2177 in a specific obstack, which is in the variable @code{string_obstack}:
2179 @smallexample
2180 struct obstack string_obstack;
2182 char *
2183 copystring (char *string)
2185   size_t len = strlen (string) + 1;
2186   char *s = (char *) obstack_alloc (&string_obstack, len);
2187   memcpy (s, string, len);
2188   return s;
2190 @end smallexample
2192 To allocate a block with specified contents, use the function
2193 @code{obstack_copy}, declared like this:
2195 @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2196 @standards{GNU, obstack.h}
2197 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2198 @c obstack_copy @mtsrace:obstack-ptr @acucorrupt @acsmem
2199 @c  obstack_grow dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2200 @c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2201 This allocates a block and initializes it by copying @var{size}
2202 bytes of data starting at @var{address}.  It calls
2203 @code{obstack_alloc_failed_handler} if allocation of memory by
2204 @code{obstack_chunk_alloc} failed.
2205 @end deftypefun
2207 @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2208 @standards{GNU, obstack.h}
2209 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2210 @c obstack_copy0 @mtsrace:obstack-ptr @acucorrupt @acsmem
2211 @c  obstack_grow0 dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2212 @c  obstack_finish dup @mtsrace:obstack-ptr @acucorrupt
2213 Like @code{obstack_copy}, but appends an extra byte containing a null
2214 character.  This extra byte is not counted in the argument @var{size}.
2215 @end deftypefun
2217 The @code{obstack_copy0} function is convenient for copying a sequence
2218 of characters into an obstack as a null-terminated string.  Here is an
2219 example of its use:
2221 @smallexample
2222 char *
2223 obstack_savestring (char *addr, int size)
2225   return obstack_copy0 (&myobstack, addr, size);
2227 @end smallexample
2229 @noindent
2230 Contrast this with the previous example of @code{savestring} using
2231 @code{malloc} (@pxref{Basic Allocation}).
2233 @node Freeing Obstack Objects
2234 @subsubsection Freeing Objects in an Obstack
2235 @cindex freeing (obstacks)
2237 To free an object allocated in an obstack, use the function
2238 @code{obstack_free}.  Since the obstack is a stack of objects, freeing
2239 one object automatically frees all other objects allocated more recently
2240 in the same obstack.
2242 @deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
2243 @standards{GNU, obstack.h}
2244 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
2245 @c obstack_free @mtsrace:obstack-ptr @acucorrupt
2246 @c  (obstack_free) @mtsrace:obstack-ptr @acucorrupt
2247 @c   *freefun dup user-supplied
2248 If @var{object} is a null pointer, everything allocated in the obstack
2249 is freed.  Otherwise, @var{object} must be the address of an object
2250 allocated in the obstack.  Then @var{object} is freed, along with
2251 everything allocated in @var{obstack-ptr} since @var{object}.
2252 @end deftypefun
2254 Note that if @var{object} is a null pointer, the result is an
2255 uninitialized obstack.  To free all memory in an obstack but leave it
2256 valid for further allocation, call @code{obstack_free} with the address
2257 of the first object allocated on the obstack:
2259 @smallexample
2260 obstack_free (obstack_ptr, first_object_allocated_ptr);
2261 @end smallexample
2263 Recall that the objects in an obstack are grouped into chunks.  When all
2264 the objects in a chunk become free, the obstack library automatically
2265 frees the chunk (@pxref{Preparing for Obstacks}).  Then other
2266 obstacks, or non-obstack allocation, can reuse the space of the chunk.
2268 @node Obstack Functions
2269 @subsubsection Obstack Functions and Macros
2270 @cindex macros
2272 The interfaces for using obstacks may be defined either as functions or
2273 as macros, depending on the compiler.  The obstack facility works with
2274 all C compilers, including both @w{ISO C} and traditional C, but there are
2275 precautions you must take if you plan to use compilers other than GNU C.
2277 If you are using an old-fashioned @w{non-ISO C} compiler, all the obstack
2278 ``functions'' are actually defined only as macros.  You can call these
2279 macros like functions, but you cannot use them in any other way (for
2280 example, you cannot take their address).
2282 Calling the macros requires a special precaution: namely, the first
2283 operand (the obstack pointer) may not contain any side effects, because
2284 it may be computed more than once.  For example, if you write this:
2286 @smallexample
2287 obstack_alloc (get_obstack (), 4);
2288 @end smallexample
2290 @noindent
2291 you will find that @code{get_obstack} may be called several times.
2292 If you use @code{*obstack_list_ptr++} as the obstack pointer argument,
2293 you will get very strange results since the incrementation may occur
2294 several times.
2296 In @w{ISO C}, each function has both a macro definition and a function
2297 definition.  The function definition is used if you take the address of the
2298 function without calling it.  An ordinary call uses the macro definition by
2299 default, but you can request the function definition instead by writing the
2300 function name in parentheses, as shown here:
2302 @smallexample
2303 char *x;
2304 void *(*funcp) ();
2305 /* @r{Use the macro}.  */
2306 x = (char *) obstack_alloc (obptr, size);
2307 /* @r{Call the function}.  */
2308 x = (char *) (obstack_alloc) (obptr, size);
2309 /* @r{Take the address of the function}.  */
2310 funcp = obstack_alloc;
2311 @end smallexample
2313 @noindent
2314 This is the same situation that exists in @w{ISO C} for the standard library
2315 functions.  @xref{Macro Definitions}.
2317 @strong{Warning:} When you do use the macros, you must observe the
2318 precaution of avoiding side effects in the first operand, even in @w{ISO C}.
2320 If you use the GNU C compiler, this precaution is not necessary, because
2321 various language extensions in GNU C permit defining the macros so as to
2322 compute each argument only once.
2324 @node Growing Objects
2325 @subsubsection Growing Objects
2326 @cindex growing objects (in obstacks)
2327 @cindex changing the size of a block (obstacks)
2329 Because memory in obstack chunks is used sequentially, it is possible to
2330 build up an object step by step, adding one or more bytes at a time to the
2331 end of the object.  With this technique, you do not need to know how much
2332 data you will put in the object until you come to the end of it.  We call
2333 this the technique of @dfn{growing objects}.  The special functions
2334 for adding data to the growing object are described in this section.
2336 You don't need to do anything special when you start to grow an object.
2337 Using one of the functions to add data to the object automatically
2338 starts it.  However, it is necessary to say explicitly when the object is
2339 finished.  This is done with the function @code{obstack_finish}.
2341 The actual address of the object thus built up is not known until the
2342 object is finished.  Until then, it always remains possible that you will
2343 add so much data that the object must be copied into a new chunk.
2345 While the obstack is in use for a growing object, you cannot use it for
2346 ordinary allocation of another object.  If you try to do so, the space
2347 already added to the growing object will become part of the other object.
2349 @deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
2350 @standards{GNU, obstack.h}
2351 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2352 @c obstack_blank @mtsrace:obstack-ptr @acucorrupt @acsmem
2353 @c  _obstack_newchunk @mtsrace:obstack-ptr @acucorrupt @acsmem
2354 @c   *chunkfun dup @acsmem
2355 @c   *obstack_alloc_failed_handler dup user-supplied
2356 @c   *freefun
2357 @c  obstack_blank_fast dup @mtsrace:obstack-ptr
2358 The most basic function for adding to a growing object is
2359 @code{obstack_blank}, which adds space without initializing it.
2360 @end deftypefun
2362 @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
2363 @standards{GNU, obstack.h}
2364 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2365 @c obstack_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2366 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2367 @c  memcpy ok
2368 To add a block of initialized space, use @code{obstack_grow}, which is
2369 the growing-object analogue of @code{obstack_copy}.  It adds @var{size}
2370 bytes of data to the growing object, copying the contents from
2371 @var{data}.
2372 @end deftypefun
2374 @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
2375 @standards{GNU, obstack.h}
2376 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2377 @c obstack_grow0 @mtsrace:obstack-ptr @acucorrupt @acsmem
2378 @c   (no sequence point between storing NUL and incrementing next_free)
2379 @c   (multiple changes to next_free => @acucorrupt)
2380 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2381 @c  memcpy ok
2382 This is the growing-object analogue of @code{obstack_copy0}.  It adds
2383 @var{size} bytes copied from @var{data}, followed by an additional null
2384 character.
2385 @end deftypefun
2387 @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
2388 @standards{GNU, obstack.h}
2389 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2390 @c obstack_1grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2391 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2392 @c  obstack_1grow_fast dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2393 To add one character at a time, use the function @code{obstack_1grow}.
2394 It adds a single byte containing @var{c} to the growing object.
2395 @end deftypefun
2397 @deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
2398 @standards{GNU, obstack.h}
2399 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2400 @c obstack_ptr_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2401 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2402 @c  obstack_ptr_grow_fast dup @mtsrace:obstack-ptr
2403 Adding the value of a pointer one can use the function
2404 @code{obstack_ptr_grow}.  It adds @code{sizeof (void *)} bytes
2405 containing the value of @var{data}.
2406 @end deftypefun
2408 @deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
2409 @standards{GNU, obstack.h}
2410 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2411 @c obstack_int_grow @mtsrace:obstack-ptr @acucorrupt @acsmem
2412 @c  _obstack_newchunk dup @mtsrace:obstack-ptr @acucorrupt @acsmem
2413 @c  obstack_int_grow_fast dup @mtsrace:obstack-ptr
2414 A single value of type @code{int} can be added by using the
2415 @code{obstack_int_grow} function.  It adds @code{sizeof (int)} bytes to
2416 the growing object and initializes them with the value of @var{data}.
2417 @end deftypefun
2419 @deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
2420 @standards{GNU, obstack.h}
2421 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{}}}
2422 @c obstack_finish @mtsrace:obstack-ptr @acucorrupt
2423 When you are finished growing the object, use the function
2424 @code{obstack_finish} to close it off and return its final address.
2426 Once you have finished the object, the obstack is available for ordinary
2427 allocation or for growing another object.
2429 This function can return a null pointer under the same conditions as
2430 @code{obstack_alloc} (@pxref{Allocation in an Obstack}).
2431 @end deftypefun
2433 When you build an object by growing it, you will probably need to know
2434 afterward how long it became.  You need not keep track of this as you grow
2435 the object, because you can find out the length from the obstack just
2436 before finishing the object with the function @code{obstack_object_size},
2437 declared as follows:
2439 @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
2440 @standards{GNU, obstack.h}
2441 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2442 This function returns the current size of the growing object, in bytes.
2443 Remember to call this function @emph{before} finishing the object.
2444 After it is finished, @code{obstack_object_size} will return zero.
2445 @end deftypefun
2447 If you have started growing an object and wish to cancel it, you should
2448 finish it and then free it, like this:
2450 @smallexample
2451 obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
2452 @end smallexample
2454 @noindent
2455 This has no effect if no object was growing.
2457 @cindex shrinking objects
2458 You can use @code{obstack_blank} with a negative size argument to make
2459 the current object smaller.  Just don't try to shrink it beyond zero
2460 length---there's no telling what will happen if you do that.
2462 @node Extra Fast Growing
2463 @subsubsection Extra Fast Growing Objects
2464 @cindex efficiency and obstacks
2466 The usual functions for growing objects incur overhead for checking
2467 whether there is room for the new growth in the current chunk.  If you
2468 are frequently constructing objects in small steps of growth, this
2469 overhead can be significant.
2471 You can reduce the overhead by using special ``fast growth''
2472 functions that grow the object without checking.  In order to have a
2473 robust program, you must do the checking yourself.  If you do this checking
2474 in the simplest way each time you are about to add data to the object, you
2475 have not saved anything, because that is what the ordinary growth
2476 functions do.  But if you can arrange to check less often, or check
2477 more efficiently, then you make the program faster.
2479 The function @code{obstack_room} returns the amount of room available
2480 in the current chunk.  It is declared as follows:
2482 @deftypefun int obstack_room (struct obstack *@var{obstack-ptr})
2483 @standards{GNU, obstack.h}
2484 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2485 This returns the number of bytes that can be added safely to the current
2486 growing object (or to an object about to be started) in obstack
2487 @var{obstack-ptr} using the fast growth functions.
2488 @end deftypefun
2490 While you know there is room, you can use these fast growth functions
2491 for adding data to a growing object:
2493 @deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
2494 @standards{GNU, obstack.h}
2495 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acunsafe{@acucorrupt{} @acsmem{}}}
2496 @c obstack_1grow_fast @mtsrace:obstack-ptr @acucorrupt @acsmem
2497 @c   (no sequence point between copying c and incrementing next_free)
2498 The function @code{obstack_1grow_fast} adds one byte containing the
2499 character @var{c} to the growing object in obstack @var{obstack-ptr}.
2500 @end deftypefun
2502 @deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
2503 @standards{GNU, obstack.h}
2504 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2505 @c obstack_ptr_grow_fast @mtsrace:obstack-ptr
2506 The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
2507 bytes containing the value of @var{data} to the growing object in
2508 obstack @var{obstack-ptr}.
2509 @end deftypefun
2511 @deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
2512 @standards{GNU, obstack.h}
2513 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2514 @c obstack_int_grow_fast @mtsrace:obstack-ptr
2515 The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
2516 containing the value of @var{data} to the growing object in obstack
2517 @var{obstack-ptr}.
2518 @end deftypefun
2520 @deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
2521 @standards{GNU, obstack.h}
2522 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2523 @c obstack_blank_fast @mtsrace:obstack-ptr
2524 The function @code{obstack_blank_fast} adds @var{size} bytes to the
2525 growing object in obstack @var{obstack-ptr} without initializing them.
2526 @end deftypefun
2528 When you check for space using @code{obstack_room} and there is not
2529 enough room for what you want to add, the fast growth functions
2530 are not safe.  In this case, simply use the corresponding ordinary
2531 growth function instead.  Very soon this will copy the object to a
2532 new chunk; then there will be lots of room available again.
2534 So, each time you use an ordinary growth function, check afterward for
2535 sufficient space using @code{obstack_room}.  Once the object is copied
2536 to a new chunk, there will be plenty of space again, so the program will
2537 start using the fast growth functions again.
2539 Here is an example:
2541 @smallexample
2542 @group
2543 void
2544 add_string (struct obstack *obstack, const char *ptr, int len)
2546   while (len > 0)
2547     @{
2548       int room = obstack_room (obstack);
2549       if (room == 0)
2550         @{
2551           /* @r{Not enough room.  Add one character slowly,}
2552              @r{which may copy to a new chunk and make room.}  */
2553           obstack_1grow (obstack, *ptr++);
2554           len--;
2555         @}
2556       else
2557         @{
2558           if (room > len)
2559             room = len;
2560           /* @r{Add fast as much as we have room for.} */
2561           len -= room;
2562           while (room-- > 0)
2563             obstack_1grow_fast (obstack, *ptr++);
2564         @}
2565     @}
2567 @end group
2568 @end smallexample
2570 @node Status of an Obstack
2571 @subsubsection Status of an Obstack
2572 @cindex obstack status
2573 @cindex status of obstack
2575 Here are functions that provide information on the current status of
2576 allocation in an obstack.  You can use them to learn about an object while
2577 still growing it.
2579 @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
2580 @standards{GNU, obstack.h}
2581 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
2582 This function returns the tentative address of the beginning of the
2583 currently growing object in @var{obstack-ptr}.  If you finish the object
2584 immediately, it will have that address.  If you make it larger first, it
2585 may outgrow the current chunk---then its address will change!
2587 If no object is growing, this value says where the next object you
2588 allocate will start (once again assuming it fits in the current
2589 chunk).
2590 @end deftypefun
2592 @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
2593 @standards{GNU, obstack.h}
2594 @safety{@prelim{}@mtsafe{}@asunsafe{@asucorrupt{}}@acsafe{}}
2595 This function returns the address of the first free byte in the current
2596 chunk of obstack @var{obstack-ptr}.  This is the end of the currently
2597 growing object.  If no object is growing, @code{obstack_next_free}
2598 returns the same value as @code{obstack_base}.
2599 @end deftypefun
2601 @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
2602 @standards{GNU, obstack.h}
2603 @c dup
2604 @safety{@prelim{}@mtsafe{@mtsrace{:obstack-ptr}}@assafe{}@acsafe{}}
2605 This function returns the size in bytes of the currently growing object.
2606 This is equivalent to
2608 @smallexample
2609 obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})
2610 @end smallexample
2611 @end deftypefun
2613 @node Obstacks Data Alignment
2614 @subsubsection Alignment of Data in Obstacks
2615 @cindex alignment (in obstacks)
2617 Each obstack has an @dfn{alignment boundary}; each object allocated in
2618 the obstack automatically starts on an address that is a multiple of the
2619 specified boundary.  By default, this boundary is aligned so that
2620 the object can hold any type of data.
2622 To access an obstack's alignment boundary, use the macro
2623 @code{obstack_alignment_mask}, whose function prototype looks like
2624 this:
2626 @deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
2627 @standards{GNU, obstack.h}
2628 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2629 The value is a bit mask; a bit that is 1 indicates that the corresponding
2630 bit in the address of an object should be 0.  The mask value should be one
2631 less than a power of 2; the effect is that all object addresses are
2632 multiples of that power of 2.  The default value of the mask is a value
2633 that allows aligned objects to hold any type of data: for example, if
2634 its value is 3, any type of data can be stored at locations whose
2635 addresses are multiples of 4.  A mask value of 0 means an object can start
2636 on any multiple of 1 (that is, no alignment is required).
2638 The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
2639 so you can alter the mask by assignment.  For example, this statement:
2641 @smallexample
2642 obstack_alignment_mask (obstack_ptr) = 0;
2643 @end smallexample
2645 @noindent
2646 has the effect of turning off alignment processing in the specified obstack.
2647 @end deftypefn
2649 Note that a change in alignment mask does not take effect until
2650 @emph{after} the next time an object is allocated or finished in the
2651 obstack.  If you are not growing an object, you can make the new
2652 alignment mask take effect immediately by calling @code{obstack_finish}.
2653 This will finish a zero-length object and then do proper alignment for
2654 the next object.
2656 @node Obstack Chunks
2657 @subsubsection Obstack Chunks
2658 @cindex efficiency of chunks
2659 @cindex chunks
2661 Obstacks work by allocating space for themselves in large chunks, and
2662 then parceling out space in the chunks to satisfy your requests.  Chunks
2663 are normally 4096 bytes long unless you specify a different chunk size.
2664 The chunk size includes 8 bytes of overhead that are not actually used
2665 for storing objects.  Regardless of the specified size, longer chunks
2666 will be allocated when necessary for long objects.
2668 The obstack library allocates chunks by calling the function
2669 @code{obstack_chunk_alloc}, which you must define.  When a chunk is no
2670 longer needed because you have freed all the objects in it, the obstack
2671 library frees the chunk by calling @code{obstack_chunk_free}, which you
2672 must also define.
2674 These two must be defined (as macros) or declared (as functions) in each
2675 source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
2676 Most often they are defined as macros like this:
2678 @smallexample
2679 #define obstack_chunk_alloc malloc
2680 #define obstack_chunk_free free
2681 @end smallexample
2683 Note that these are simple macros (no arguments).  Macro definitions with
2684 arguments will not work!  It is necessary that @code{obstack_chunk_alloc}
2685 or @code{obstack_chunk_free}, alone, expand into a function name if it is
2686 not itself a function name.
2688 If you allocate chunks with @code{malloc}, the chunk size should be a
2689 power of 2.  The default chunk size, 4096, was chosen because it is long
2690 enough to satisfy many typical requests on the obstack yet short enough
2691 not to waste too much memory in the portion of the last chunk not yet used.
2693 @deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr})
2694 @standards{GNU, obstack.h}
2695 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2696 This returns the chunk size of the given obstack.
2697 @end deftypefn
2699 Since this macro expands to an lvalue, you can specify a new chunk size by
2700 assigning it a new value.  Doing so does not affect the chunks already
2701 allocated, but will change the size of chunks allocated for that particular
2702 obstack in the future.  It is unlikely to be useful to make the chunk size
2703 smaller, but making it larger might improve efficiency if you are
2704 allocating many objects whose size is comparable to the chunk size.  Here
2705 is how to do so cleanly:
2707 @smallexample
2708 if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
2709   obstack_chunk_size (obstack_ptr) = @var{new-chunk-size};
2710 @end smallexample
2712 @node Summary of Obstacks
2713 @subsubsection Summary of Obstack Functions
2715 Here is a summary of all the functions associated with obstacks.  Each
2716 takes the address of an obstack (@code{struct obstack *}) as its first
2717 argument.
2719 @table @code
2720 @item void obstack_init (struct obstack *@var{obstack-ptr})
2721 Initialize use of an obstack.  @xref{Creating Obstacks}.
2723 @item void *obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
2724 Allocate an object of @var{size} uninitialized bytes.
2725 @xref{Allocation in an Obstack}.
2727 @item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2728 Allocate an object of @var{size} bytes, with contents copied from
2729 @var{address}.  @xref{Allocation in an Obstack}.
2731 @item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2732 Allocate an object of @var{size}+1 bytes, with @var{size} of them copied
2733 from @var{address}, followed by a null character at the end.
2734 @xref{Allocation in an Obstack}.
2736 @item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
2737 Free @var{object} (and everything allocated in the specified obstack
2738 more recently than @var{object}).  @xref{Freeing Obstack Objects}.
2740 @item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
2741 Add @var{size} uninitialized bytes to a growing object.
2742 @xref{Growing Objects}.
2744 @item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2745 Add @var{size} bytes, copied from @var{address}, to a growing object.
2746 @xref{Growing Objects}.
2748 @item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2749 Add @var{size} bytes, copied from @var{address}, to a growing object,
2750 and then add another byte containing a null character.  @xref{Growing
2751 Objects}.
2753 @item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
2754 Add one byte containing @var{data-char} to a growing object.
2755 @xref{Growing Objects}.
2757 @item void *obstack_finish (struct obstack *@var{obstack-ptr})
2758 Finalize the object that is growing and return its permanent address.
2759 @xref{Growing Objects}.
2761 @item int obstack_object_size (struct obstack *@var{obstack-ptr})
2762 Get the current size of the currently growing object.  @xref{Growing
2763 Objects}.
2765 @item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
2766 Add @var{size} uninitialized bytes to a growing object without checking
2767 that there is enough room.  @xref{Extra Fast Growing}.
2769 @item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
2770 Add one byte containing @var{data-char} to a growing object without
2771 checking that there is enough room.  @xref{Extra Fast Growing}.
2773 @item int obstack_room (struct obstack *@var{obstack-ptr})
2774 Get the amount of room now available for growing the current object.
2775 @xref{Extra Fast Growing}.
2777 @item int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
2778 The mask used for aligning the beginning of an object.  This is an
2779 lvalue.  @xref{Obstacks Data Alignment}.
2781 @item int obstack_chunk_size (struct obstack *@var{obstack-ptr})
2782 The size for allocating chunks.  This is an lvalue.  @xref{Obstack Chunks}.
2784 @item void *obstack_base (struct obstack *@var{obstack-ptr})
2785 Tentative starting address of the currently growing object.
2786 @xref{Status of an Obstack}.
2788 @item void *obstack_next_free (struct obstack *@var{obstack-ptr})
2789 Address just after the end of the currently growing object.
2790 @xref{Status of an Obstack}.
2791 @end table
2793 @node Variable Size Automatic
2794 @subsection Automatic Storage with Variable Size
2795 @cindex automatic freeing
2796 @cindex @code{alloca} function
2797 @cindex automatic storage with variable size
2799 The function @code{alloca} supports a kind of half-dynamic allocation in
2800 which blocks are allocated dynamically but freed automatically.
2802 Allocating a block with @code{alloca} is an explicit action; you can
2803 allocate as many blocks as you wish, and compute the size at run time.  But
2804 all the blocks are freed when you exit the function that @code{alloca} was
2805 called from, just as if they were automatic variables declared in that
2806 function.  There is no way to free the space explicitly.
2808 The prototype for @code{alloca} is in @file{stdlib.h}.  This function is
2809 a BSD extension.
2810 @pindex stdlib.h
2812 @deftypefun {void *} alloca (size_t @var{size})
2813 @standards{GNU, stdlib.h}
2814 @standards{BSD, stdlib.h}
2815 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2816 The return value of @code{alloca} is the address of a block of @var{size}
2817 bytes of memory, allocated in the stack frame of the calling function.
2818 @end deftypefun
2820 Do not use @code{alloca} inside the arguments of a function call---you
2821 will get unpredictable results, because the stack space for the
2822 @code{alloca} would appear on the stack in the middle of the space for
2823 the function arguments.  An example of what to avoid is @code{foo (x,
2824 alloca (4), y)}.
2825 @c This might get fixed in future versions of GCC, but that won't make
2826 @c it safe with compilers generally.
2828 @menu
2829 * Alloca Example::              Example of using @code{alloca}.
2830 * Advantages of Alloca::        Reasons to use @code{alloca}.
2831 * Disadvantages of Alloca::     Reasons to avoid @code{alloca}.
2832 * GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
2833                                  method of allocating dynamically and
2834                                  freeing automatically.
2835 @end menu
2837 @node Alloca Example
2838 @subsubsection @code{alloca} Example
2840 As an example of the use of @code{alloca}, here is a function that opens
2841 a file name made from concatenating two argument strings, and returns a
2842 file descriptor or minus one signifying failure:
2844 @smallexample
2846 open2 (char *str1, char *str2, int flags, int mode)
2848   char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
2849   stpcpy (stpcpy (name, str1), str2);
2850   return open (name, flags, mode);
2852 @end smallexample
2854 @noindent
2855 Here is how you would get the same results with @code{malloc} and
2856 @code{free}:
2858 @smallexample
2860 open2 (char *str1, char *str2, int flags, int mode)
2862   char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
2863   int desc;
2864   if (name == 0)
2865     fatal ("virtual memory exceeded");
2866   stpcpy (stpcpy (name, str1), str2);
2867   desc = open (name, flags, mode);
2868   free (name);
2869   return desc;
2871 @end smallexample
2873 As you can see, it is simpler with @code{alloca}.  But @code{alloca} has
2874 other, more important advantages, and some disadvantages.
2876 @node Advantages of Alloca
2877 @subsubsection Advantages of @code{alloca}
2879 Here are the reasons why @code{alloca} may be preferable to @code{malloc}:
2881 @itemize @bullet
2882 @item
2883 Using @code{alloca} wastes very little space and is very fast.  (It is
2884 open-coded by the GNU C compiler.)
2886 @item
2887 Since @code{alloca} does not have separate pools for different sizes of
2888 blocks, space used for any size block can be reused for any other size.
2889 @code{alloca} does not cause memory fragmentation.
2891 @item
2892 @cindex longjmp
2893 Nonlocal exits done with @code{longjmp} (@pxref{Non-Local Exits})
2894 automatically free the space allocated with @code{alloca} when they exit
2895 through the function that called @code{alloca}.  This is the most
2896 important reason to use @code{alloca}.
2898 To illustrate this, suppose you have a function
2899 @code{open_or_report_error} which returns a descriptor, like
2900 @code{open}, if it succeeds, but does not return to its caller if it
2901 fails.  If the file cannot be opened, it prints an error message and
2902 jumps out to the command level of your program using @code{longjmp}.
2903 Let's change @code{open2} (@pxref{Alloca Example}) to use this
2904 subroutine:@refill
2906 @smallexample
2908 open2 (char *str1, char *str2, int flags, int mode)
2910   char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
2911   stpcpy (stpcpy (name, str1), str2);
2912   return open_or_report_error (name, flags, mode);
2914 @end smallexample
2916 @noindent
2917 Because of the way @code{alloca} works, the memory it allocates is
2918 freed even when an error occurs, with no special effort required.
2920 By contrast, the previous definition of @code{open2} (which uses
2921 @code{malloc} and @code{free}) would develop a memory leak if it were
2922 changed in this way.  Even if you are willing to make more changes to
2923 fix it, there is no easy way to do so.
2924 @end itemize
2926 @node Disadvantages of Alloca
2927 @subsubsection Disadvantages of @code{alloca}
2929 @cindex @code{alloca} disadvantages
2930 @cindex disadvantages of @code{alloca}
2931 These are the disadvantages of @code{alloca} in comparison with
2932 @code{malloc}:
2934 @itemize @bullet
2935 @item
2936 If you try to allocate more memory than the machine can provide, you
2937 don't get a clean error message.  Instead you get a fatal signal like
2938 the one you would get from an infinite recursion; probably a
2939 segmentation violation (@pxref{Program Error Signals}).
2941 @item
2942 Some @nongnusystems{} fail to support @code{alloca}, so it is less
2943 portable.  However, a slower emulation of @code{alloca} written in C
2944 is available for use on systems with this deficiency.
2945 @end itemize
2947 @node GNU C Variable-Size Arrays
2948 @subsubsection GNU C Variable-Size Arrays
2949 @cindex variable-sized arrays
2951 In GNU C, you can replace most uses of @code{alloca} with an array of
2952 variable size.  Here is how @code{open2} would look then:
2954 @smallexample
2955 int open2 (char *str1, char *str2, int flags, int mode)
2957   char name[strlen (str1) + strlen (str2) + 1];
2958   stpcpy (stpcpy (name, str1), str2);
2959   return open (name, flags, mode);
2961 @end smallexample
2963 But @code{alloca} is not always equivalent to a variable-sized array, for
2964 several reasons:
2966 @itemize @bullet
2967 @item
2968 A variable size array's space is freed at the end of the scope of the
2969 name of the array.  The space allocated with @code{alloca}
2970 remains until the end of the function.
2972 @item
2973 It is possible to use @code{alloca} within a loop, allocating an
2974 additional block on each iteration.  This is impossible with
2975 variable-sized arrays.
2976 @end itemize
2978 @strong{NB:} If you mix use of @code{alloca} and variable-sized arrays
2979 within one function, exiting a scope in which a variable-sized array was
2980 declared frees all blocks allocated with @code{alloca} during the
2981 execution of that scope.
2984 @node Resizing the Data Segment
2985 @section Resizing the Data Segment
2987 The symbols in this section are declared in @file{unistd.h}.
2989 You will not normally use the functions in this section, because the
2990 functions described in @ref{Memory Allocation} are easier to use.  Those
2991 are interfaces to a @glibcadj{} memory allocator that uses the
2992 functions below itself.  The functions below are simple interfaces to
2993 system calls.
2995 @deftypefun int brk (void *@var{addr})
2996 @standards{BSD, unistd.h}
2997 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
2999 @code{brk} sets the high end of the calling process' data segment to
3000 @var{addr}.
3002 The address of the end of a segment is defined to be the address of the
3003 last byte in the segment plus 1.
3005 The function has no effect if @var{addr} is lower than the low end of
3006 the data segment.  (This is considered success, by the way.)
3008 The function fails if it would cause the data segment to overlap another
3009 segment or exceed the process' data storage limit (@pxref{Limits on
3010 Resources}).
3012 The function is named for a common historical case where data storage
3013 and the stack are in the same segment.  Data storage allocation grows
3014 upward from the bottom of the segment while the stack grows downward
3015 toward it from the top of the segment and the curtain between them is
3016 called the @dfn{break}.
3018 The return value is zero on success.  On failure, the return value is
3019 @code{-1} and @code{errno} is set accordingly.  The following @code{errno}
3020 values are specific to this function:
3022 @table @code
3023 @item ENOMEM
3024 The request would cause the data segment to overlap another segment or
3025 exceed the process' data storage limit.
3026 @end table
3028 @c The Brk system call in Linux (as opposed to the GNU C Library function)
3029 @c is considerably different.  It always returns the new end of the data
3030 @c segment, whether it succeeds or fails.  The GNU C library Brk determines
3031 @c it's a failure if and only if the system call returns an address less
3032 @c than the address requested.
3034 @end deftypefun
3037 @deftypefun void *sbrk (ptrdiff_t @var{delta})
3038 @standards{BSD, unistd.h}
3039 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3041 This function is the same as @code{brk} except that you specify the new
3042 end of the data segment as an offset @var{delta} from the current end
3043 and on success the return value is the address of the resulting end of
3044 the data segment instead of zero.
3046 This means you can use @samp{sbrk(0)} to find out what the current end
3047 of the data segment is.
3049 @end deftypefun
3051 @node Memory Protection
3052 @section Memory Protection
3053 @cindex memory protection
3054 @cindex page protection
3055 @cindex protection flags
3057 When a page is mapped using @code{mmap}, page protection flags can be
3058 specified using the protection flags argument.  @xref{Memory-mapped
3059 I/O}.
3061 The following flags are available:
3063 @vtable @code
3064 @item PROT_WRITE
3065 @standards{POSIX, sys/mman.h}
3066 The memory can be written to.
3068 @item PROT_READ
3069 @standards{POSIX, sys/mman.h}
3070 The memory can be read.  On some architectures, this flag implies that
3071 the memory can be executed as well (as if @code{PROT_EXEC} had been
3072 specified at the same time).
3074 @item PROT_EXEC
3075 @standards{POSIX, sys/mman.h}
3076 The memory can be used to store instructions which can then be executed.
3077 On most architectures, this flag implies that the memory can be read (as
3078 if @code{PROT_READ} had been specified).
3080 @item PROT_NONE
3081 @standards{POSIX, sys/mman.h}
3082 This flag must be specified on its own.
3084 The memory is reserved, but cannot be read, written, or executed.  If
3085 this flag is specified in a call to @code{mmap}, a virtual memory area
3086 will be set aside for future use in the process, and @code{mmap} calls
3087 without the @code{MAP_FIXED} flag will not use it for subsequent
3088 allocations.  For anonymous mappings, the kernel will not reserve any
3089 physical memory for the allocation at the time the mapping is created.
3090 @end vtable
3092 The operating system may keep track of these flags separately even if
3093 the underlying hardware treats them the same for the purposes of access
3094 checking (as happens with @code{PROT_READ} and @code{PROT_EXEC} on some
3095 platforms).  On GNU systems, @code{PROT_EXEC} always implies
3096 @code{PROT_READ}, so that users can view the machine code which is
3097 executing on their system.
3099 Inappropriate access will cause a segfault (@pxref{Program Error
3100 Signals}).
3102 After allocation, protection flags can be changed using the
3103 @code{mprotect} function.
3105 @deftypefun int mprotect (void *@var{address}, size_t @var{length}, int @var{protection})
3106 @standards{POSIX, sys/mman.h}
3107 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3109 A successful call to the @code{mprotect} function changes the protection
3110 flags of at least @var{length} bytes of memory, starting at
3111 @var{address}.
3113 @var{address} must be aligned to the page size for the mapping.  The
3114 system page size can be obtained by calling @code{sysconf} with the
3115 @code{_SC_PAGESIZE} parameter (@pxref{Sysconf Definition}).  The system
3116 page size is the granularity in which the page protection of anonymous
3117 memory mappings and most file mappings can be changed.  Memory which is
3118 mapped from special files or devices may have larger page granularity
3119 than the system page size and may require larger alignment.
3121 @var{length} is the number of bytes whose protection flags must be
3122 changed.  It is automatically rounded up to the next multiple of the
3123 system page size.
3125 @var{protection} is a combination of the @code{PROT_*} flags described
3126 above.
3128 The @code{mprotect} function returns @math{0} on success and @math{-1}
3129 on failure.
3131 The following @code{errno} error conditions are defined for this
3132 function:
3134 @table @code
3135 @item ENOMEM
3136 The system was not able to allocate resources to fulfill the request.
3137 This can happen if there is not enough physical memory in the system for
3138 the allocation of backing storage.  The error can also occur if the new
3139 protection flags would cause the memory region to be split from its
3140 neighbors, and the process limit for the number of such distinct memory
3141 regions would be exceeded.
3143 @item EINVAL
3144 @var{address} is not properly aligned to a page boundary for the
3145 mapping, or @var{length} (after rounding up to the system page size) is
3146 not a multiple of the applicable page size for the mapping, or the
3147 combination of flags in @var{protection} is not valid.
3149 @item EACCES
3150 The file for a file-based mapping was not opened with open flags which
3151 are compatible with @var{protection}.
3153 @item EPERM
3154 The system security policy does not allow a mapping with the specified
3155 flags.  For example, mappings which are both @code{PROT_EXEC} and
3156 @code{PROT_WRITE} at the same time might not be allowed.
3157 @end table
3158 @end deftypefun
3160 If the @code{mprotect} function is used to make a region of memory
3161 inaccessible by specifying the @code{PROT_NONE} protection flag and
3162 access is later restored, the memory retains its previous contents.
3164 On some systems, it may not be possible to specify additional flags
3165 which were not present when the mapping was first created.  For example,
3166 an attempt to make a region of memory executable could fail if the
3167 initial protection flags were @samp{PROT_READ | PROT_WRITE}.
3169 In general, the @code{mprotect} function can be used to change any
3170 process memory, no matter how it was allocated.  However, portable use
3171 of the function requires that it is only used with memory regions
3172 returned by @code{mmap} or @code{mmap64}.
3174 @subsection Memory Protection Keys
3176 @cindex memory protection key
3177 @cindex protection key
3178 @cindex MPK
3179 On some systems, further restrictions can be added to specific pages
3180 using @dfn{memory protection keys}.  These restrictions work as follows:
3182 @itemize @bullet
3183 @item
3184 All memory pages are associated with a protection key.  The default
3185 protection key does not cause any additional protections to be applied
3186 during memory accesses.  New keys can be allocated with the
3187 @code{pkey_alloc} function, and applied to pages using
3188 @code{pkey_mprotect}.
3190 @item
3191 Each thread has a set of separate access right restriction for each
3192 protection key.  These access rights can be manipulated using the
3193 @code{pkey_set} and @code{pkey_get} functions.
3195 @item
3196 During a memory access, the system obtains the protection key for the
3197 accessed page and uses that to determine the applicable access rights,
3198 as configured for the current thread.  If the access is restricted, a
3199 segmentation fault is the result ((@pxref{Program Error Signals}).
3200 These checks happen in addition to the @code{PROT_}* protection flags
3201 set by @code{mprotect} or @code{pkey_mprotect}.
3202 @end itemize
3204 New threads and subprocesses inherit the access rights of the current
3205 thread.  If a protection key is allocated subsequently, existing threads
3206 (except the current) will use an unspecified system default for the
3207 access rights associated with newly allocated keys.
3209 Upon entering a signal handler, the system resets the access rights of
3210 the current thread so that pages with the default key can be accessed,
3211 but the access rights for other protection keys are unspecified.
3213 Applications are expected to allocate a key once using
3214 @code{pkey_alloc}, and apply the key to memory regions which need
3215 special protection with @code{pkey_mprotect}:
3217 @smallexample
3218   int key = pkey_alloc (0, PKEY_DISABLE_ACCESS);
3219   if (key < 0)
3220     /* Perform error checking, including fallback for lack of support.  */
3221     ...;
3223   /* Apply the key to a special memory region used to store critical
3224      data.  */
3225   if (pkey_mprotect (region, region_length,
3226                      PROT_READ | PROT_WRITE, key) < 0)
3227     ...; /* Perform error checking (generally fatal).  */
3228 @end smallexample
3230 If the key allocation fails due to lack of support for memory protection
3231 keys, the @code{pkey_mprotect} call can usually be skipped.  In this
3232 case, the region will not be protected by default.  It is also possible
3233 to call @code{pkey_mprotect} with a key value of @math{-1}, in which
3234 case it will behave in the same way as @code{mprotect}.
3236 After key allocation assignment to memory pages, @code{pkey_set} can be
3237 used to temporarily acquire access to the memory region and relinquish
3238 it again:
3240 @smallexample
3241   if (key >= 0 && pkey_set (key, 0) < 0)
3242     ...; /* Perform error checking (generally fatal).  */
3243   /* At this point, the current thread has read-write access to the
3244      memory region.  */
3245   ...
3246   /* Revoke access again.  */
3247   if (key >= 0 && pkey_set (key, PKEY_DISABLE_ACCESS) < 0)
3248     ...; /* Perform error checking (generally fatal).  */
3249 @end smallexample
3251 In this example, a negative key value indicates that no key had been
3252 allocated, which means that the system lacks support for memory
3253 protection keys and it is not necessary to change the the access rights
3254 of the current thread (because it always has access).
3256 Compared to using @code{mprotect} to change the page protection flags,
3257 this approach has two advantages: It is thread-safe in the sense that
3258 the access rights are only changed for the current thread, so another
3259 thread which changes its own access rights concurrently to gain access
3260 to the mapping will not suddenly see its access rights revoked.  And
3261 @code{pkey_set} typically does not involve a call into the kernel and a
3262 context switch, so it is more efficient.
3264 @deftypefun int pkey_alloc (unsigned int @var{flags}, unsigned int @var{restrictions})
3265 @standards{Linux, sys/mman.h}
3266 @safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
3267 Allocate a new protection key.  The @var{flags} argument is reserved and
3268 must be zero.  The @var{restrictions} argument specifies access rights
3269 which are applied to the current thread (as if with @code{pkey_set}
3270 below).  Access rights of other threads are not changed.
3272 The function returns the new protection key, a non-negative number, or
3273 @math{-1} on error.
3275 The following @code{errno} error conditions are defined for this
3276 function:
3278 @table @code
3279 @item ENOSYS
3280 The system does not implement memory protection keys.
3282 @item EINVAL
3283 The @var{flags} argument is not zero.
3285 The @var{restrictions} argument is invalid.
3287 The system does not implement memory protection keys or runs in a mode
3288 in which memory protection keys are disabled.
3290 @item ENOSPC
3291 All available protection keys already have been allocated.
3292 @end table
3293 @end deftypefun
3295 @deftypefun int pkey_free (int @var{key})
3296 @standards{Linux, sys/mman.h}
3297 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3298 Deallocate the protection key, so that it can be reused by
3299 @code{pkey_alloc}.
3301 Calling this function does not change the access rights of the freed
3302 protection key.  The calling thread and other threads may retain access
3303 to it, even if it is subsequently allocated again.  For this reason, it
3304 is not recommended to call the @code{pkey_free} function.
3306 @table @code
3307 @item ENOSYS
3308 The system does not implement memory protection keys.
3310 @item EINVAL
3311 The @var{key} argument is not a valid protection key.
3312 @end table
3313 @end deftypefun
3315 @deftypefun int pkey_mprotect (void *@var{address}, size_t @var{length}, int @var{protection}, int @var{key})
3316 @standards{Linux, sys/mman.h}
3317 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3318 Similar to @code{mprotect}, but also set the memory protection key for
3319 the memory region to @code{key}.
3321 Some systems use memory protection keys to emulate certain combinations
3322 of @var{protection} flags.  Under such circumstances, specifying an
3323 explicit protection key may behave as if additional flags have been
3324 specified in @var{protection}, even though this does not happen with the
3325 default protection key.  For example, some systems can support
3326 @code{PROT_EXEC}-only mappings only with a default protection key, and
3327 memory with a key which was allocated using @code{pkey_alloc} will still
3328 be readable if @code{PROT_EXEC} is specified without @code{PROT_READ}.
3330 If @var{key} is @math{-1}, the default protection key is applied to the
3331 mapping, just as if @code{mprotect} had been called.
3333 The @code{pkey_mprotect} function returns @math{0} on success and
3334 @math{-1} on failure.  The same @code{errno} error conditions as for
3335 @code{mprotect} are defined for this function, with the following
3336 addition:
3338 @table @code
3339 @item EINVAL
3340 The @var{key} argument is not @math{-1} or a valid memory protection
3341 key allocated using @code{pkey_alloc}.
3343 @item ENOSYS
3344 The system does not implement memory protection keys, and @var{key} is
3345 not @math{-1}.
3346 @end table
3347 @end deftypefun
3349 @deftypefun int pkey_set (int @var{key}, unsigned int @var{rights})
3350 @standards{Linux, sys/mman.h}
3351 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3352 Change the access rights of the current thread for memory pages with the
3353 protection key @var{key} to @var{rights}.  If @var{rights} is zero, no
3354 additional access restrictions on top of the page protection flags are
3355 applied.  Otherwise, @var{rights} is a combination of the following
3356 flags:
3358 @vtable @code
3359 @item PKEY_DISABLE_WRITE
3360 @standards{Linux, sys/mman.h}
3361 Subsequent attempts to write to memory with the specified protection
3362 key will fault.
3364 @item PKEY_DISABLE_ACCESS
3365 @standards{Linux, sys/mman.h}
3366 Subsequent attempts to write to or read from memory with the specified
3367 protection key will fault.
3368 @end vtable
3370 Operations not specified as flags are not restricted.  In particular,
3371 this means that the memory region will remain executable if it was
3372 mapped with the @code{PROT_EXEC} protection flag and
3373 @code{PKEY_DISABLE_ACCESS} has been specified.
3375 Calling the @code{pkey_set} function with a protection key which was not
3376 allocated by @code{pkey_alloc} results in undefined behavior.  This
3377 means that calling this function on systems which do not support memory
3378 protection keys is undefined.
3380 The @code{pkey_set} function returns @math{0} on success and @math{-1}
3381 on failure.
3383 The following @code{errno} error conditions are defined for this
3384 function:
3386 @table @code
3387 @item EINVAL
3388 The system does not support the access rights restrictions expressed in
3389 the @var{rights} argument.
3390 @end table
3391 @end deftypefun
3393 @deftypefun int pkey_get (int @var{key})
3394 @standards{Linux, sys/mman.h}
3395 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3396 Return the access rights of the current thread for memory pages with
3397 protection key @var{key}.  The return value is zero or a combination of
3398 the @code{PKEY_DISABLE_}* flags; see the @code{pkey_set} function.
3400 Calling the @code{pkey_get} function with a protection key which was not
3401 allocated by @code{pkey_alloc} results in undefined behavior.  This
3402 means that calling this function on systems which do not support memory
3403 protection keys is undefined.
3404 @end deftypefun
3406 @node Locking Pages
3407 @section Locking Pages
3408 @cindex locking pages
3409 @cindex memory lock
3410 @cindex paging
3412 You can tell the system to associate a particular virtual memory page
3413 with a real page frame and keep it that way --- i.e., cause the page to
3414 be paged in if it isn't already and mark it so it will never be paged
3415 out and consequently will never cause a page fault.  This is called
3416 @dfn{locking} a page.
3418 The functions in this chapter lock and unlock the calling process'
3419 pages.
3421 @menu
3422 * Why Lock Pages::                Reasons to read this section.
3423 * Locked Memory Details::         Everything you need to know locked
3424                                     memory
3425 * Page Lock Functions::           Here's how to do it.
3426 @end menu
3428 @node Why Lock Pages
3429 @subsection Why Lock Pages
3431 Because page faults cause paged out pages to be paged in transparently,
3432 a process rarely needs to be concerned about locking pages.  However,
3433 there are two reasons people sometimes are:
3435 @itemize @bullet
3437 @item
3438 Speed.  A page fault is transparent only insofar as the process is not
3439 sensitive to how long it takes to do a simple memory access.  Time-critical
3440 processes, especially realtime processes, may not be able to wait or
3441 may not be able to tolerate variance in execution speed.
3442 @cindex realtime processing
3443 @cindex speed of execution
3445 A process that needs to lock pages for this reason probably also needs
3446 priority among other processes for use of the CPU.  @xref{Priority}.
3448 In some cases, the programmer knows better than the system's demand
3449 paging allocator which pages should remain in real memory to optimize
3450 system performance.  In this case, locking pages can help.
3452 @item
3453 Privacy.  If you keep secrets in virtual memory and that virtual memory
3454 gets paged out, that increases the chance that the secrets will get out.
3455 If a passphrase gets written out to disk swap space, for example, it might
3456 still be there long after virtual and real memory have been wiped clean.
3458 @end itemize
3460 Be aware that when you lock a page, that's one fewer page frame that can
3461 be used to back other virtual memory (by the same or other processes),
3462 which can mean more page faults, which means the system runs more
3463 slowly.  In fact, if you lock enough memory, some programs may not be
3464 able to run at all for lack of real memory.
3466 @node Locked Memory Details
3467 @subsection Locked Memory Details
3469 A memory lock is associated with a virtual page, not a real frame.  The
3470 paging rule is: If a frame backs at least one locked page, don't page it
3471 out.
3473 Memory locks do not stack.  I.e., you can't lock a particular page twice
3474 so that it has to be unlocked twice before it is truly unlocked.  It is
3475 either locked or it isn't.
3477 A memory lock persists until the process that owns the memory explicitly
3478 unlocks it.  (But process termination and exec cause the virtual memory
3479 to cease to exist, which you might say means it isn't locked any more).
3481 Memory locks are not inherited by child processes.  (But note that on a
3482 modern Unix system, immediately after a fork, the parent's and the
3483 child's virtual address space are backed by the same real page frames,
3484 so the child enjoys the parent's locks).  @xref{Creating a Process}.
3486 Because of its ability to impact other processes, only the superuser can
3487 lock a page.  Any process can unlock its own page.
3489 The system sets limits on the amount of memory a process can have locked
3490 and the amount of real memory it can have dedicated to it.  @xref{Limits
3491 on Resources}.
3493 In Linux, locked pages aren't as locked as you might think.
3494 Two virtual pages that are not shared memory can nonetheless be backed
3495 by the same real frame.  The kernel does this in the name of efficiency
3496 when it knows both virtual pages contain identical data, and does it
3497 even if one or both of the virtual pages are locked.
3499 But when a process modifies one of those pages, the kernel must get it a
3500 separate frame and fill it with the page's data.  This is known as a
3501 @dfn{copy-on-write page fault}.  It takes a small amount of time and in
3502 a pathological case, getting that frame may require I/O.
3503 @cindex copy-on-write page fault
3504 @cindex page fault, copy-on-write
3506 To make sure this doesn't happen to your program, don't just lock the
3507 pages.  Write to them as well, unless you know you won't write to them
3508 ever.  And to make sure you have pre-allocated frames for your stack,
3509 enter a scope that declares a C automatic variable larger than the
3510 maximum stack size you will need, set it to something, then return from
3511 its scope.
3513 @node Page Lock Functions
3514 @subsection Functions To Lock And Unlock Pages
3516 The symbols in this section are declared in @file{sys/mman.h}.  These
3517 functions are defined by POSIX.1b, but their availability depends on
3518 your kernel.  If your kernel doesn't allow these functions, they exist
3519 but always fail.  They @emph{are} available with a Linux kernel.
3521 @strong{Portability Note:} POSIX.1b requires that when the @code{mlock}
3522 and @code{munlock} functions are available, the file @file{unistd.h}
3523 define the macro @code{_POSIX_MEMLOCK_RANGE} and the file
3524 @code{limits.h} define the macro @code{PAGESIZE} to be the size of a
3525 memory page in bytes.  It requires that when the @code{mlockall} and
3526 @code{munlockall} functions are available, the @file{unistd.h} file
3527 define the macro @code{_POSIX_MEMLOCK}.  @Theglibc{} conforms to
3528 this requirement.
3530 @deftypefun int mlock (const void *@var{addr}, size_t @var{len})
3531 @standards{POSIX.1b, sys/mman.h}
3532 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3534 @code{mlock} locks a range of the calling process' virtual pages.
3536 The range of memory starts at address @var{addr} and is @var{len} bytes
3537 long.  Actually, since you must lock whole pages, it is the range of
3538 pages that include any part of the specified range.
3540 When the function returns successfully, each of those pages is backed by
3541 (connected to) a real frame (is resident) and is marked to stay that
3542 way.  This means the function may cause page-ins and have to wait for
3543 them.
3545 When the function fails, it does not affect the lock status of any
3546 pages.
3548 The return value is zero if the function succeeds.  Otherwise, it is
3549 @code{-1} and @code{errno} is set accordingly.  @code{errno} values
3550 specific to this function are:
3552 @table @code
3553 @item ENOMEM
3554 @itemize @bullet
3555 @item
3556 At least some of the specified address range does not exist in the
3557 calling process' virtual address space.
3558 @item
3559 The locking would cause the process to exceed its locked page limit.
3560 @end itemize
3562 @item EPERM
3563 The calling process is not superuser.
3565 @item EINVAL
3566 @var{len} is not positive.
3568 @item ENOSYS
3569 The kernel does not provide @code{mlock} capability.
3571 @end table
3572 @end deftypefun
3574 @deftypefun int mlock2 (const void *@var{addr}, size_t @var{len}, unsigned int @var{flags})
3575 @standards{Linux, sys/mman.h}
3576 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3578 This function is similar to @code{mlock}.  If @var{flags} is zero, a
3579 call to @code{mlock2} behaves exactly as the equivalent call to @code{mlock}.
3581 The @var{flags} argument must be a combination of zero or more of the
3582 following flags:
3584 @vtable @code
3585 @item MLOCK_ONFAULT
3586 @standards{Linux, sys/mman.h}
3587 Only those pages in the specified address range which are already in
3588 memory are locked immediately.  Additional pages in the range are
3589 automatically locked in case of a page fault and allocation of memory.
3590 @end vtable
3592 Like @code{mlock}, @code{mlock2} returns zero on success and @code{-1}
3593 on failure, setting @code{errno} accordingly.  Additional @code{errno}
3594 values defined for @code{mlock2} are:
3596 @table @code
3597 @item EINVAL
3598 The specified (non-zero) @var{flags} argument is not supported by this
3599 system.
3600 @end table
3601 @end deftypefun
3603 You can lock @emph{all} a process' memory with @code{mlockall}.  You
3604 unlock memory with @code{munlock} or @code{munlockall}.
3606 To avoid all page faults in a C program, you have to use
3607 @code{mlockall}, because some of the memory a program uses is hidden
3608 from the C code, e.g. the stack and automatic variables, and you
3609 wouldn't know what address to tell @code{mlock}.
3611 @deftypefun int munlock (const void *@var{addr}, size_t @var{len})
3612 @standards{POSIX.1b, sys/mman.h}
3613 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3615 @code{munlock} unlocks a range of the calling process' virtual pages.
3617 @code{munlock} is the inverse of @code{mlock} and functions completely
3618 analogously to @code{mlock}, except that there is no @code{EPERM}
3619 failure.
3621 @end deftypefun
3623 @deftypefun int mlockall (int @var{flags})
3624 @standards{POSIX.1b, sys/mman.h}
3625 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3627 @code{mlockall} locks all the pages in a process' virtual memory address
3628 space, and/or any that are added to it in the future.  This includes the
3629 pages of the code, data and stack segment, as well as shared libraries,
3630 user space kernel data, shared memory, and memory mapped files.
3632 @var{flags} is a string of single bit flags represented by the following
3633 macros.  They tell @code{mlockall} which of its functions you want.  All
3634 other bits must be zero.
3636 @vtable @code
3638 @item MCL_CURRENT
3639 Lock all pages which currently exist in the calling process' virtual
3640 address space.
3642 @item MCL_FUTURE
3643 Set a mode such that any pages added to the process' virtual address
3644 space in the future will be locked from birth.  This mode does not
3645 affect future address spaces owned by the same process so exec, which
3646 replaces a process' address space, wipes out @code{MCL_FUTURE}.
3647 @xref{Executing a File}.
3649 @end vtable
3651 When the function returns successfully, and you specified
3652 @code{MCL_CURRENT}, all of the process' pages are backed by (connected
3653 to) real frames (they are resident) and are marked to stay that way.
3654 This means the function may cause page-ins and have to wait for them.
3656 When the process is in @code{MCL_FUTURE} mode because it successfully
3657 executed this function and specified @code{MCL_CURRENT}, any system call
3658 by the process that requires space be added to its virtual address space
3659 fails with @code{errno} = @code{ENOMEM} if locking the additional space
3660 would cause the process to exceed its locked page limit.  In the case
3661 that the address space addition that can't be accommodated is stack
3662 expansion, the stack expansion fails and the kernel sends a
3663 @code{SIGSEGV} signal to the process.
3665 When the function fails, it does not affect the lock status of any pages
3666 or the future locking mode.
3668 The return value is zero if the function succeeds.  Otherwise, it is
3669 @code{-1} and @code{errno} is set accordingly.  @code{errno} values
3670 specific to this function are:
3672 @table @code
3673 @item ENOMEM
3674 @itemize @bullet
3675 @item
3676 At least some of the specified address range does not exist in the
3677 calling process' virtual address space.
3678 @item
3679 The locking would cause the process to exceed its locked page limit.
3680 @end itemize
3682 @item EPERM
3683 The calling process is not superuser.
3685 @item EINVAL
3686 Undefined bits in @var{flags} are not zero.
3688 @item ENOSYS
3689 The kernel does not provide @code{mlockall} capability.
3691 @end table
3693 You can lock just specific pages with @code{mlock}.  You unlock pages
3694 with @code{munlockall} and @code{munlock}.
3696 @end deftypefun
3699 @deftypefun int munlockall (void)
3700 @standards{POSIX.1b, sys/mman.h}
3701 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
3703 @code{munlockall} unlocks every page in the calling process' virtual
3704 address space and turns off @code{MCL_FUTURE} future locking mode.
3706 The return value is zero if the function succeeds.  Otherwise, it is
3707 @code{-1} and @code{errno} is set accordingly.  The only way this
3708 function can fail is for generic reasons that all functions and system
3709 calls can fail, so there are no specific @code{errno} values.
3711 @end deftypefun
3716 @ignore
3717 @c This was never actually implemented.  -zw
3718 @node Relocating Allocator
3719 @section Relocating Allocator
3721 @cindex relocating memory allocator
3722 Any system of dynamic memory allocation has overhead: the amount of
3723 space it uses is more than the amount the program asks for.  The
3724 @dfn{relocating memory allocator} achieves very low overhead by moving
3725 blocks in memory as necessary, on its own initiative.
3727 @c @menu
3728 @c * Relocator Concepts::               How to understand relocating allocation.
3729 @c * Using Relocator::          Functions for relocating allocation.
3730 @c @end menu
3732 @node Relocator Concepts
3733 @subsection Concepts of Relocating Allocation
3735 @ifinfo
3736 The @dfn{relocating memory allocator} achieves very low overhead by
3737 moving blocks in memory as necessary, on its own initiative.
3738 @end ifinfo
3740 When you allocate a block with @code{malloc}, the address of the block
3741 never changes unless you use @code{realloc} to change its size.  Thus,
3742 you can safely store the address in various places, temporarily or
3743 permanently, as you like.  This is not safe when you use the relocating
3744 memory allocator, because any and all relocatable blocks can move
3745 whenever you allocate memory in any fashion.  Even calling @code{malloc}
3746 or @code{realloc} can move the relocatable blocks.
3748 @cindex handle
3749 For each relocatable block, you must make a @dfn{handle}---a pointer
3750 object in memory, designated to store the address of that block.  The
3751 relocating allocator knows where each block's handle is, and updates the
3752 address stored there whenever it moves the block, so that the handle
3753 always points to the block.  Each time you access the contents of the
3754 block, you should fetch its address anew from the handle.
3756 To call any of the relocating allocator functions from a signal handler
3757 is almost certainly incorrect, because the signal could happen at any
3758 time and relocate all the blocks.  The only way to make this safe is to
3759 block the signal around any access to the contents of any relocatable
3760 block---not a convenient mode of operation.  @xref{Nonreentrancy}.
3762 @node Using Relocator
3763 @subsection Allocating and Freeing Relocatable Blocks
3765 @pindex malloc.h
3766 In the descriptions below, @var{handleptr} designates the address of the
3767 handle.  All the functions are declared in @file{malloc.h}; all are GNU
3768 extensions.
3770 @comment malloc.h
3771 @comment GNU
3772 @c @deftypefun {void *} r_alloc (void **@var{handleptr}, size_t @var{size})
3773 This function allocates a relocatable block of size @var{size}.  It
3774 stores the block's address in @code{*@var{handleptr}} and returns
3775 a non-null pointer to indicate success.
3777 If @code{r_alloc} can't get the space needed, it stores a null pointer
3778 in @code{*@var{handleptr}}, and returns a null pointer.
3779 @end deftypefun
3781 @comment malloc.h
3782 @comment GNU
3783 @c @deftypefun void r_alloc_free (void **@var{handleptr})
3784 This function is the way to free a relocatable block.  It frees the
3785 block that @code{*@var{handleptr}} points to, and stores a null pointer
3786 in @code{*@var{handleptr}} to show it doesn't point to an allocated
3787 block any more.
3788 @end deftypefun
3790 @comment malloc.h
3791 @comment GNU
3792 @c @deftypefun {void *} r_re_alloc (void **@var{handleptr}, size_t @var{size})
3793 The function @code{r_re_alloc} adjusts the size of the block that
3794 @code{*@var{handleptr}} points to, making it @var{size} bytes long.  It
3795 stores the address of the resized block in @code{*@var{handleptr}} and
3796 returns a non-null pointer to indicate success.
3798 If enough memory is not available, this function returns a null pointer
3799 and does not modify @code{*@var{handleptr}}.
3800 @end deftypefun
3801 @end ignore
3806 @ignore
3807 @comment No longer available...
3809 @comment @node Memory Warnings
3810 @comment @section Memory Usage Warnings
3811 @comment @cindex memory usage warnings
3812 @comment @cindex warnings of memory almost full
3814 @pindex malloc.c
3815 You can ask for warnings as the program approaches running out of memory
3816 space, by calling @code{memory_warnings}.  This tells @code{malloc} to
3817 check memory usage every time it asks for more memory from the operating
3818 system.  This is a GNU extension declared in @file{malloc.h}.
3820 @comment malloc.h
3821 @comment GNU
3822 @comment @deftypefun void memory_warnings (void *@var{start}, void (*@var{warn-func}) (const char *))
3823 Call this function to request warnings for nearing exhaustion of virtual
3824 memory.
3826 The argument @var{start} says where data space begins, in memory.  The
3827 allocator compares this against the last address used and against the
3828 limit of data space, to determine the fraction of available memory in
3829 use.  If you supply zero for @var{start}, then a default value is used
3830 which is right in most circumstances.
3832 For @var{warn-func}, supply a function that @code{malloc} can call to
3833 warn you.  It is called with a string (a warning message) as argument.
3834 Normally it ought to display the string for the user to read.
3835 @end deftypefun
3837 The warnings come when memory becomes 75% full, when it becomes 85%
3838 full, and when it becomes 95% full.  Above 95% you get another warning
3839 each time memory usage increases.
3841 @end ignore