2004-10-17 Roland McGrath <roland@frob.com>
[kopensolaris-gnu/glibc.git] / manual / memory.texi
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
6
7 This chapter describes how processes manage and use memory in a system
8 that uses the GNU C library.
9
10 The GNU C Library 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.
14
15
16 @menu
17 * Memory Concepts::             An introduction to concepts and terminology.
18 * Memory Allocation::           Allocating storage for your program data
19 * Locking Pages::               Preventing page faults
20 * Resizing the Data Segment::   @code{brk}, @code{sbrk}
21 @end menu
22
23 Memory mapped I/O is not discussed in this chapter.  @xref{Memory-mapped I/O}.
24
25
26
27 @node Memory Concepts
28 @section Process Memory Concepts
29
30 One of the most basic resources a process has available to it is memory.
31 There are a lot of different ways systems organize memory, but in a
32 typical one, each process has one linear virtual address space, with
33 addresses running from zero to some huge maximum.  It need not be
34 contiguous; i.e.  not all of these addresses actually can be used to
35 store data.
36
37 The virtual memory is divided into pages (4 kilobytes is typical).
38 Backing each page of virtual memory is a page of real memory (called a
39 @dfn{frame}) or some secondary storage, usually disk space.  The disk
40 space might be swap space or just some ordinary disk file.  Actually, a
41 page of all zeroes sometimes has nothing at all backing it -- there's
42 just a flag saying it is all zeroes.
43 @cindex page frame
44 @cindex frame, real memory
45 @cindex swap space
46 @cindex page, virtual memory
47
48 The same frame of real memory or backing store can back multiple virtual
49 pages belonging to multiple processes.  This is normally the case, for
50 example, with virtual memory occupied by GNU C library code.  The same
51 real memory frame containing the @code{printf} function backs a virtual
52 memory page in each of the existing processes that has a @code{printf}
53 call in its program.
54
55 In order for a program to access any part of a virtual page, the page
56 must at that moment be backed by (``connected to'') a real frame.  But
57 because there is usually a lot more virtual memory than real memory, the
58 pages must move back and forth between real memory and backing store
59 regularly, coming into real memory when a process needs to access them
60 and then retreating to backing store when not needed anymore.  This
61 movement is called @dfn{paging}.
62
63 When a program attempts to access a page which is not at that moment
64 backed by real memory, this is known as a @dfn{page fault}.  When a page
65 fault occurs, the kernel suspends the process, places the page into a
66 real page frame (this is called ``paging in'' or ``faulting in''), then
67 resumes the process so that from the process' point of view, the page
68 was in real memory all along.  In fact, to the process, all pages always
69 seem to be in real memory.  Except for one thing: the elapsed execution
70 time of an instruction that would normally be a few nanoseconds is
71 suddenly much, much, longer (because the kernel normally has to do I/O
72 to complete the page-in).  For programs sensitive to that, the functions
73 described in @ref{Locking Pages} can control it.
74 @cindex page fault
75 @cindex paging
76
77 Within each virtual address space, a process has to keep track of what
78 is at which addresses, and that process is called memory allocation.
79 Allocation usually brings to mind meting out scarce resources, but in
80 the case of virtual memory, that's not a major goal, because there is
81 generally much more of it than anyone needs.  Memory allocation within a
82 process is mainly just a matter of making sure that the same byte of
83 memory isn't used to store two different things.
84
85 Processes allocate memory in two major ways: by exec and
86 programmatically.  Actually, forking is a third way, but it's not very
87 interesting.  @xref{Creating a Process}.
88
89 Exec is the operation of creating a virtual address space for a process,
90 loading its basic program into it, and executing the program.  It is
91 done by the ``exec'' family of functions (e.g. @code{execl}).  The
92 operation takes a program file (an executable), it allocates space to
93 load all the data in the executable, loads it, and transfers control to
94 it.  That data is most notably the instructions of the program (the
95 @dfn{text}), but also literals and constants in the program and even
96 some variables: C variables with the static storage class (@pxref{Memory
97 Allocation and C}).
98 @cindex executable
99 @cindex literals
100 @cindex constants
101
102 Once that program begins to execute, it uses programmatic allocation to
103 gain additional memory.  In a C program with the GNU C library, there
104 are two kinds of programmatic allocation: automatic and dynamic.
105 @xref{Memory Allocation and C}.
106
107 Memory-mapped I/O is another form of dynamic virtual memory allocation.
108 Mapping memory to a file means declaring that the contents of certain
109 range of a process' addresses shall be identical to the contents of a
110 specified regular file.  The system makes the virtual memory initially
111 contain the contents of the file, and if you modify the memory, the
112 system writes the same modification to the file.  Note that due to the
113 magic of virtual memory and page faults, there is no reason for the
114 system to do I/O to read the file, or allocate real memory for its
115 contents, until the program accesses the virtual memory.
116 @xref{Memory-mapped I/O}.
117 @cindex memory mapped I/O
118 @cindex memory mapped file
119 @cindex files, accessing
120
121 Just as it programmatically allocates memory, the program can
122 programmatically deallocate (@dfn{free}) it.  You can't free the memory
123 that was allocated by exec.  When the program exits or execs, you might
124 say that all its memory gets freed, but since in both cases the address
125 space ceases to exist, the point is really moot.  @xref{Program
126 Termination}.
127 @cindex execing a program
128 @cindex freeing memory
129 @cindex exiting a program
130
131 A process' virtual address space is divided into segments.  A segment is
132 a contiguous range of virtual addresses.  Three important segments are:
133
134 @itemize @bullet
135
136 @item
137
138 The @dfn{text segment} contains a program's instructions and literals and
139 static constants.  It is allocated by exec and stays the same size for
140 the life of the virtual address space.
141
142 @item
143 The @dfn{data segment} is working storage for the program.  It can be
144 preallocated and preloaded by exec and the process can extend or shrink
145 it by calling functions as described in @xref{Resizing the Data
146 Segment}.  Its lower end is fixed.
147
148 @item
149 The @dfn{stack segment} contains a program stack.  It grows as the stack
150 grows, but doesn't shrink when the stack shrinks.
151
152 @end itemize
153
154
155
156 @node Memory Allocation
157 @section Allocating Storage For Program Data
158
159 This section covers how ordinary programs manage storage for their data,
160 including the famous @code{malloc} function and some fancier facilities
161 special the GNU C library and GNU Compiler.
162
163 @menu
164 * Memory Allocation and C::     How to get different kinds of allocation in C.
165 * Unconstrained Allocation::    The @code{malloc} facility allows fully general
166                                  dynamic allocation.
167 * Allocation Debugging::        Finding memory leaks and not freed memory.
168 * Obstacks::                    Obstacks are less general than malloc
169                                  but more efficient and convenient.
170 * Variable Size Automatic::     Allocation of variable-sized blocks
171                                  of automatic storage that are freed when the
172                                  calling function returns.
173 @end menu
174
175
176 @node Memory Allocation and C
177 @subsection Memory Allocation in C Programs
178
179 The C language supports two kinds of memory allocation through the
180 variables in C programs:
181
182 @itemize @bullet
183 @item
184 @dfn{Static allocation} is what happens when you declare a static or
185 global variable.  Each static or global variable defines one block of
186 space, of a fixed size.  The space is allocated once, when your program
187 is started (part of the exec operation), and is never freed.
188 @cindex static memory allocation
189 @cindex static storage class
190
191 @item
192 @dfn{Automatic allocation} happens when you declare an automatic
193 variable, such as a function argument or a local variable.  The space
194 for an automatic variable is allocated when the compound statement
195 containing the declaration is entered, and is freed when that
196 compound statement is exited.
197 @cindex automatic memory allocation
198 @cindex automatic storage class
199
200 In GNU C, the size of the automatic storage can be an expression
201 that varies.  In other C implementations, it must be a constant.
202 @end itemize
203
204 A third important kind of memory allocation, @dfn{dynamic allocation},
205 is not supported by C variables but is available via GNU C library
206 functions.
207 @cindex dynamic memory allocation
208
209 @subsubsection Dynamic Memory Allocation
210 @cindex dynamic memory allocation
211
212 @dfn{Dynamic memory allocation} is a technique in which programs
213 determine as they are running where to store some information.  You need
214 dynamic allocation when the amount of memory you need, or how long you
215 continue to need it, depends on factors that are not known before the
216 program runs.
217
218 For example, you may need a block to store a line read from an input
219 file; since there is no limit to how long a line can be, you must
220 allocate the memory dynamically and make it dynamically larger as you
221 read more of the line.
222
223 Or, you may need a block for each record or each definition in the input
224 data; since you can't know in advance how many there will be, you must
225 allocate a new block for each record or definition as you read it.
226
227 When you use dynamic allocation, the allocation of a block of memory is
228 an action that the program requests explicitly.  You call a function or
229 macro when you want to allocate space, and specify the size with an
230 argument.  If you want to free the space, you do so by calling another
231 function or macro.  You can do these things whenever you want, as often
232 as you want.
233
234 Dynamic allocation is not supported by C variables; there is no storage
235 class ``dynamic'', and there can never be a C variable whose value is
236 stored in dynamically allocated space.  The only way to get dynamically
237 allocated memory is via a system call (which is generally via a GNU C
238 library function call), and the only way to refer to dynamically
239 allocated space is through a pointer.  Because it is less convenient,
240 and because the actual process of dynamic allocation requires more
241 computation time, programmers generally use dynamic allocation only when
242 neither static nor automatic allocation will serve.
243
244 For example, if you want to allocate dynamically some space to hold a
245 @code{struct foobar}, you cannot declare a variable of type @code{struct
246 foobar} whose contents are the dynamically allocated space.  But you can
247 declare a variable of pointer type @code{struct foobar *} and assign it the
248 address of the space.  Then you can use the operators @samp{*} and
249 @samp{->} on this pointer variable to refer to the contents of the space:
250
251 @smallexample
252 @{
253   struct foobar *ptr
254      = (struct foobar *) malloc (sizeof (struct foobar));
255   ptr->name = x;
256   ptr->next = current_foobar;
257   current_foobar = ptr;
258 @}
259 @end smallexample
260
261 @node Unconstrained Allocation
262 @subsection Unconstrained Allocation
263 @cindex unconstrained memory allocation
264 @cindex @code{malloc} function
265 @cindex heap, dynamic allocation from
266
267 The most general dynamic allocation facility is @code{malloc}.  It
268 allows you to allocate blocks of memory of any size at any time, make
269 them bigger or smaller at any time, and free the blocks individually at
270 any time (or never).
271
272 @menu
273 * Basic Allocation::            Simple use of @code{malloc}.
274 * Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
275 * Freeing after Malloc::        Use @code{free} to free a block you
276                                  got with @code{malloc}.
277 * Changing Block Size::         Use @code{realloc} to make a block
278                                  bigger or smaller.
279 * Allocating Cleared Space::    Use @code{calloc} to allocate a
280                                  block and clear it.
281 * Efficiency and Malloc::       Efficiency considerations in use of
282                                  these functions.
283 * Aligned Memory Blocks::       Allocating specially aligned memory.
284 * Malloc Tunable Parameters::   Use @code{mallopt} to adjust allocation
285                                  parameters.
286 * Heap Consistency Checking::   Automatic checking for errors.
287 * Hooks for Malloc::            You can use these hooks for debugging
288                                  programs that use @code{malloc}.
289 * Statistics of Malloc::        Getting information about how much
290                                  memory your program is using.
291 * Summary of Malloc::           Summary of @code{malloc} and related functions.
292 @end menu
293
294 @node Basic Allocation
295 @subsubsection Basic Memory Allocation
296 @cindex allocation of memory with @code{malloc}
297
298 To allocate a block of memory, call @code{malloc}.  The prototype for
299 this function is in @file{stdlib.h}.
300 @pindex stdlib.h
301
302 @comment malloc.h stdlib.h
303 @comment ISO
304 @deftypefun {void *} malloc (size_t @var{size})
305 This function returns a pointer to a newly allocated block @var{size}
306 bytes long, or a null pointer if the block could not be allocated.
307 @end deftypefun
308
309 The contents of the block are undefined; you must initialize it yourself
310 (or use @code{calloc} instead; @pxref{Allocating Cleared Space}).
311 Normally you would cast the value as a pointer to the kind of object
312 that you want to store in the block.  Here we show an example of doing
313 so, and of initializing the space with zeros using the library function
314 @code{memset} (@pxref{Copying and Concatenation}):
315
316 @smallexample
317 struct foo *ptr;
318 @dots{}
319 ptr = (struct foo *) malloc (sizeof (struct foo));
320 if (ptr == 0) abort ();
321 memset (ptr, 0, sizeof (struct foo));
322 @end smallexample
323
324 You can store the result of @code{malloc} into any pointer variable
325 without a cast, because @w{ISO C} automatically converts the type
326 @code{void *} to another type of pointer when necessary.  But the cast
327 is necessary in contexts other than assignment operators or if you might
328 want your code to run in traditional C.
329
330 Remember that when allocating space for a string, the argument to
331 @code{malloc} must be one plus the length of the string.  This is
332 because a string is terminated with a null character that doesn't count
333 in the ``length'' of the string but does need space.  For example:
334
335 @smallexample
336 char *ptr;
337 @dots{}
338 ptr = (char *) malloc (length + 1);
339 @end smallexample
340
341 @noindent
342 @xref{Representation of Strings}, for more information about this.
343
344 @node Malloc Examples
345 @subsubsection Examples of @code{malloc}
346
347 If no more space is available, @code{malloc} returns a null pointer.
348 You should check the value of @emph{every} call to @code{malloc}.  It is
349 useful to write a subroutine that calls @code{malloc} and reports an
350 error if the value is a null pointer, returning only if the value is
351 nonzero.  This function is conventionally called @code{xmalloc}.  Here
352 it is:
353
354 @smallexample
355 void *
356 xmalloc (size_t size)
357 @{
358   register void *value = malloc (size);
359   if (value == 0)
360     fatal ("virtual memory exhausted");
361   return value;
362 @}
363 @end smallexample
364
365 Here is a real example of using @code{malloc} (by way of @code{xmalloc}).
366 The function @code{savestring} will copy a sequence of characters into
367 a newly allocated null-terminated string:
368
369 @smallexample
370 @group
371 char *
372 savestring (const char *ptr, size_t len)
373 @{
374   register char *value = (char *) xmalloc (len + 1);
375   value[len] = '\0';
376   return (char *) memcpy (value, ptr, len);
377 @}
378 @end group
379 @end smallexample
380
381 The block that @code{malloc} gives you is guaranteed to be aligned so
382 that it can hold any type of data.  In the GNU system, the address is
383 always a multiple of eight on most systems, and a multiple of 16 on
384 64-bit systems.  Only rarely is any higher boundary (such as a page
385 boundary) necessary; for those cases, use @code{memalign},
386 @code{posix_memalign} or @code{valloc} (@pxref{Aligned Memory Blocks}).
387
388 Note that the memory located after the end of the block is likely to be
389 in use for something else; perhaps a block already allocated by another
390 call to @code{malloc}.  If you attempt to treat the block as longer than
391 you asked for it to be, you are liable to destroy the data that
392 @code{malloc} uses to keep track of its blocks, or you may destroy the
393 contents of another block.  If you have already allocated a block and
394 discover you want it to be bigger, use @code{realloc} (@pxref{Changing
395 Block Size}).
396
397 @node Freeing after Malloc
398 @subsubsection Freeing Memory Allocated with @code{malloc}
399 @cindex freeing memory allocated with @code{malloc}
400 @cindex heap, freeing memory from
401
402 When you no longer need a block that you got with @code{malloc}, use the
403 function @code{free} to make the block available to be allocated again.
404 The prototype for this function is in @file{stdlib.h}.
405 @pindex stdlib.h
406
407 @comment malloc.h stdlib.h
408 @comment ISO
409 @deftypefun void free (void *@var{ptr})
410 The @code{free} function deallocates the block of memory pointed at
411 by @var{ptr}.
412 @end deftypefun
413
414 @comment stdlib.h
415 @comment Sun
416 @deftypefun void cfree (void *@var{ptr})
417 This function does the same thing as @code{free}.  It's provided for
418 backward compatibility with SunOS; you should use @code{free} instead.
419 @end deftypefun
420
421 Freeing a block alters the contents of the block.  @strong{Do not expect to
422 find any data (such as a pointer to the next block in a chain of blocks) in
423 the block after freeing it.}  Copy whatever you need out of the block before
424 freeing it!  Here is an example of the proper way to free all the blocks in
425 a chain, and the strings that they point to:
426
427 @smallexample
428 struct chain
429   @{
430     struct chain *next;
431     char *name;
432   @}
433
434 void
435 free_chain (struct chain *chain)
436 @{
437   while (chain != 0)
438     @{
439       struct chain *next = chain->next;
440       free (chain->name);
441       free (chain);
442       chain = next;
443     @}
444 @}
445 @end smallexample
446
447 Occasionally, @code{free} can actually return memory to the operating
448 system and make the process smaller.  Usually, all it can do is allow a
449 later call to @code{malloc} to reuse the space.  In the meantime, the
450 space remains in your program as part of a free-list used internally by
451 @code{malloc}.
452
453 There is no point in freeing blocks at the end of a program, because all
454 of the program's space is given back to the system when the process
455 terminates.
456
457 @node Changing Block Size
458 @subsubsection Changing the Size of a Block
459 @cindex changing the size of a block (@code{malloc})
460
461 Often you do not know for certain how big a block you will ultimately need
462 at the time you must begin to use the block.  For example, the block might
463 be a buffer that you use to hold a line being read from a file; no matter
464 how long you make the buffer initially, you may encounter a line that is
465 longer.
466
467 You can make the block longer by calling @code{realloc}.  This function
468 is declared in @file{stdlib.h}.
469 @pindex stdlib.h
470
471 @comment malloc.h stdlib.h
472 @comment ISO
473 @deftypefun {void *} realloc (void *@var{ptr}, size_t @var{newsize})
474 The @code{realloc} function changes the size of the block whose address is
475 @var{ptr} to be @var{newsize}.
476
477 Since the space after the end of the block may be in use, @code{realloc}
478 may find it necessary to copy the block to a new address where more free
479 space is available.  The value of @code{realloc} is the new address of the
480 block.  If the block needs to be moved, @code{realloc} copies the old
481 contents.
482
483 If you pass a null pointer for @var{ptr}, @code{realloc} behaves just
484 like @samp{malloc (@var{newsize})}.  This can be convenient, but beware
485 that older implementations (before @w{ISO C}) may not support this
486 behavior, and will probably crash when @code{realloc} is passed a null
487 pointer.
488 @end deftypefun
489
490 Like @code{malloc}, @code{realloc} may return a null pointer if no
491 memory space is available to make the block bigger.  When this happens,
492 the original block is untouched; it has not been modified or relocated.
493
494 In most cases it makes no difference what happens to the original block
495 when @code{realloc} fails, because the application program cannot continue
496 when it is out of memory, and the only thing to do is to give a fatal error
497 message.  Often it is convenient to write and use a subroutine,
498 conventionally called @code{xrealloc}, that takes care of the error message
499 as @code{xmalloc} does for @code{malloc}:
500
501 @smallexample
502 void *
503 xrealloc (void *ptr, size_t size)
504 @{
505   register void *value = realloc (ptr, size);
506   if (value == 0)
507     fatal ("Virtual memory exhausted");
508   return value;
509 @}
510 @end smallexample
511
512 You can also use @code{realloc} to make a block smaller.  The reason you
513 would do this is to avoid tying up a lot of memory space when only a little
514 is needed.
515 @comment The following is no longer true with the new malloc.
516 @comment But it seems wise to keep the warning for other implementations.
517 In several allocation implementations, making a block smaller sometimes
518 necessitates copying it, so it can fail if no other space is available.
519
520 If the new size you specify is the same as the old size, @code{realloc}
521 is guaranteed to change nothing and return the same address that you gave.
522
523 @node Allocating Cleared Space
524 @subsubsection Allocating Cleared Space
525
526 The function @code{calloc} allocates memory and clears it to zero.  It
527 is declared in @file{stdlib.h}.
528 @pindex stdlib.h
529
530 @comment malloc.h stdlib.h
531 @comment ISO
532 @deftypefun {void *} calloc (size_t @var{count}, size_t @var{eltsize})
533 This function allocates a block long enough to contain a vector of
534 @var{count} elements, each of size @var{eltsize}.  Its contents are
535 cleared to zero before @code{calloc} returns.
536 @end deftypefun
537
538 You could define @code{calloc} as follows:
539
540 @smallexample
541 void *
542 calloc (size_t count, size_t eltsize)
543 @{
544   size_t size = count * eltsize;
545   void *value = malloc (size);
546   if (value != 0)
547     memset (value, 0, size);
548   return value;
549 @}
550 @end smallexample
551
552 But in general, it is not guaranteed that @code{calloc} calls
553 @code{malloc} internally.  Therefore, if an application provides its own
554 @code{malloc}/@code{realloc}/@code{free} outside the C library, it
555 should always define @code{calloc}, too.
556
557 @node Efficiency and Malloc
558 @subsubsection Efficiency Considerations for @code{malloc}
559 @cindex efficiency and @code{malloc}
560
561
562
563
564 @ignore
565
566 @c No longer true, see below instead.
567 To make the best use of @code{malloc}, it helps to know that the GNU
568 version of @code{malloc} always dispenses small amounts of memory in
569 blocks whose sizes are powers of two.  It keeps separate pools for each
570 power of two.  This holds for sizes up to a page size.  Therefore, if
571 you are free to choose the size of a small block in order to make
572 @code{malloc} more efficient, make it a power of two.
573 @c !!! xref getpagesize
574
575 Once a page is split up for a particular block size, it can't be reused
576 for another size unless all the blocks in it are freed.  In many
577 programs, this is unlikely to happen.  Thus, you can sometimes make a
578 program use memory more efficiently by using blocks of the same size for
579 many different purposes.
580
581 When you ask for memory blocks of a page or larger, @code{malloc} uses a
582 different strategy; it rounds the size up to a multiple of a page, and
583 it can coalesce and split blocks as needed.
584
585 The reason for the two strategies is that it is important to allocate
586 and free small blocks as fast as possible, but speed is less important
587 for a large block since the program normally spends a fair amount of
588 time using it.  Also, large blocks are normally fewer in number.
589 Therefore, for large blocks, it makes sense to use a method which takes
590 more time to minimize the wasted space.
591
592 @end ignore
593
594 As opposed to other versions, the @code{malloc} in the GNU C Library
595 does not round up block sizes to powers of two, neither for large nor
596 for small sizes.  Neighboring chunks can be coalesced on a @code{free}
597 no matter what their size is.  This makes the implementation suitable
598 for all kinds of allocation patterns without generally incurring high
599 memory waste through fragmentation.
600
601 Very large blocks (much larger than a page) are allocated with
602 @code{mmap} (anonymous or via @code{/dev/zero}) by this implementation.
603 This has the great advantage that these chunks are returned to the
604 system immediately when they are freed.  Therefore, it cannot happen
605 that a large chunk becomes ``locked'' in between smaller ones and even
606 after calling @code{free} wastes memory.  The size threshold for
607 @code{mmap} to be used can be adjusted with @code{mallopt}.  The use of
608 @code{mmap} can also be disabled completely.
609
610 @node Aligned Memory Blocks
611 @subsubsection Allocating Aligned Memory Blocks
612
613 @cindex page boundary
614 @cindex alignment (with @code{malloc})
615 @pindex stdlib.h
616 The address of a block returned by @code{malloc} or @code{realloc} in
617 the GNU system is always a multiple of eight (or sixteen on 64-bit
618 systems).  If you need a block whose address is a multiple of a higher
619 power of two than that, use @code{memalign}, @code{posix_memalign}, or
620 @code{valloc}.  @code{memalign} is declared in @file{malloc.h} and
621 @code{posix_memalign} is declared in @file{stdlib.h}.
622
623 With the GNU library, you can use @code{free} to free the blocks that
624 @code{memalign}, @code{posix_memalign}, and @code{valloc} return.  That
625 does not work in BSD, however---BSD does not provide any way to free
626 such blocks.
627
628 @comment malloc.h
629 @comment BSD
630 @deftypefun {void *} memalign (size_t @var{boundary}, size_t @var{size})
631 The @code{memalign} function allocates a block of @var{size} bytes whose
632 address is a multiple of @var{boundary}.  The @var{boundary} must be a
633 power of two!  The function @code{memalign} works by allocating a
634 somewhat larger block, and then returning an address within the block
635 that is on the specified boundary.
636 @end deftypefun
637
638 @comment stdlib.h
639 @comment POSIX
640 @deftypefun int posix_memalign (void **@var{memptr}, size_t @var{alignment}, size_t @var{size})
641 The @code{posix_memalign} function is similar to the @code{memalign}
642 function in that it returns a buffer of @var{size} bytes aligned to a
643 multiple of @var{alignment}.  But it adds one requirement to the
644 parameter @var{alignment}: the value must be a power of two multiple of
645 @code{sizeof (void *)}.
646
647 If the function succeeds in allocation memory a pointer to the allocated
648 memory is returned in @code{*@var{memptr}} and the return value is zero.
649 Otherwise the function returns an error value indicating the problem.
650
651 This function was introduced in POSIX 1003.1d.
652 @end deftypefun
653
654 @comment malloc.h stdlib.h
655 @comment BSD
656 @deftypefun {void *} valloc (size_t @var{size})
657 Using @code{valloc} is like using @code{memalign} and passing the page size
658 as the value of the second argument.  It is implemented like this:
659
660 @smallexample
661 void *
662 valloc (size_t size)
663 @{
664   return memalign (getpagesize (), size);
665 @}
666 @end smallexample
667
668 @ref{Query Memory Parameters} for more information about the memory
669 subsystem.
670 @end deftypefun
671
672 @node Malloc Tunable Parameters
673 @subsubsection Malloc Tunable Parameters
674
675 You can adjust some parameters for dynamic memory allocation with the
676 @code{mallopt} function.  This function is the general SVID/XPG
677 interface, defined in @file{malloc.h}.
678 @pindex malloc.h
679
680 @deftypefun int mallopt (int @var{param}, int @var{value})
681 When calling @code{mallopt}, the @var{param} argument specifies the
682 parameter to be set, and @var{value} the new value to be set.  Possible
683 choices for @var{param}, as defined in @file{malloc.h}, are:
684
685 @table @code
686 @item M_TRIM_THRESHOLD
687 This is the minimum size (in bytes) of the top-most, releasable chunk
688 that will cause @code{sbrk} to be called with a negative argument in
689 order to return memory to the system.
690 @item M_TOP_PAD
691 This parameter determines the amount of extra memory to obtain from the
692 system when a call to @code{sbrk} is required.  It also specifies the
693 number of bytes to retain when shrinking the heap by calling @code{sbrk}
694 with a negative argument.  This provides the necessary hysteresis in
695 heap size such that excessive amounts of system calls can be avoided.
696 @item M_MMAP_THRESHOLD
697 All chunks larger than this value are allocated outside the normal
698 heap, using the @code{mmap} system call.  This way it is guaranteed
699 that the memory for these chunks can be returned to the system on
700 @code{free}.  Note that requests smaller than this threshold might still
701 be allocated via @code{mmap}.
702 @item M_MMAP_MAX
703 The maximum number of chunks to allocate with @code{mmap}.  Setting this
704 to zero disables all use of @code{mmap}.
705 @end table
706
707 @end deftypefun
708
709 @node Heap Consistency Checking
710 @subsubsection Heap Consistency Checking
711
712 @cindex heap consistency checking
713 @cindex consistency checking, of heap
714
715 You can ask @code{malloc} to check the consistency of dynamic memory by
716 using the @code{mcheck} function.  This function is a GNU extension,
717 declared in @file{mcheck.h}.
718 @pindex mcheck.h
719
720 @comment mcheck.h
721 @comment GNU
722 @deftypefun int mcheck (void (*@var{abortfn}) (enum mcheck_status @var{status}))
723 Calling @code{mcheck} tells @code{malloc} to perform occasional
724 consistency checks.  These will catch things such as writing
725 past the end of a block that was allocated with @code{malloc}.
726
727 The @var{abortfn} argument is the function to call when an inconsistency
728 is found.  If you supply a null pointer, then @code{mcheck} uses a
729 default function which prints a message and calls @code{abort}
730 (@pxref{Aborting a Program}).  The function you supply is called with
731 one argument, which says what sort of inconsistency was detected; its
732 type is described below.
733
734 It is too late to begin allocation checking once you have allocated
735 anything with @code{malloc}.  So @code{mcheck} does nothing in that
736 case.  The function returns @code{-1} if you call it too late, and
737 @code{0} otherwise (when it is successful).
738
739 The easiest way to arrange to call @code{mcheck} early enough is to use
740 the option @samp{-lmcheck} when you link your program; then you don't
741 need to modify your program source at all.  Alternatively you might use
742 a debugger to insert a call to @code{mcheck} whenever the program is
743 started, for example these gdb commands will automatically call @code{mcheck}
744 whenever the program starts:
745
746 @smallexample
747 (gdb) break main
748 Breakpoint 1, main (argc=2, argv=0xbffff964) at whatever.c:10
749 (gdb) command 1
750 Type commands for when breakpoint 1 is hit, one per line.
751 End with a line saying just "end".
752 >call mcheck(0)
753 >continue
754 >end
755 (gdb) @dots{}
756 @end smallexample
757
758 This will however only work if no initialization function of any object
759 involved calls any of the @code{malloc} functions since @code{mcheck}
760 must be called before the first such function.
761
762 @end deftypefun
763
764 @deftypefun {enum mcheck_status} mprobe (void *@var{pointer})
765 The @code{mprobe} function lets you explicitly check for inconsistencies
766 in a particular allocated block.  You must have already called
767 @code{mcheck} at the beginning of the program, to do its occasional
768 checks; calling @code{mprobe} requests an additional consistency check
769 to be done at the time of the call.
770
771 The argument @var{pointer} must be a pointer returned by @code{malloc}
772 or @code{realloc}.  @code{mprobe} returns a value that says what
773 inconsistency, if any, was found.  The values are described below.
774 @end deftypefun
775
776 @deftp {Data Type} {enum mcheck_status}
777 This enumerated type describes what kind of inconsistency was detected
778 in an allocated block, if any.  Here are the possible values:
779
780 @table @code
781 @item MCHECK_DISABLED
782 @code{mcheck} was not called before the first allocation.
783 No consistency checking can be done.
784 @item MCHECK_OK
785 No inconsistency detected.
786 @item MCHECK_HEAD
787 The data immediately before the block was modified.
788 This commonly happens when an array index or pointer
789 is decremented too far.
790 @item MCHECK_TAIL
791 The data immediately after the block was modified.
792 This commonly happens when an array index or pointer
793 is incremented too far.
794 @item MCHECK_FREE
795 The block was already freed.
796 @end table
797 @end deftp
798
799 Another possibility to check for and guard against bugs in the use of
800 @code{malloc}, @code{realloc} and @code{free} is to set the environment
801 variable @code{MALLOC_CHECK_}.  When @code{MALLOC_CHECK_} is set, a
802 special (less efficient) implementation is used which is designed to be
803 tolerant against simple errors, such as double calls of @code{free} with
804 the same argument, or overruns of a single byte (off-by-one bugs).  Not
805 all such errors can be protected against, however, and memory leaks can
806 result.  If @code{MALLOC_CHECK_} is set to @code{0}, any detected heap
807 corruption is silently ignored; if set to @code{1}, a diagnostic is
808 printed on @code{stderr}; if set to @code{2}, @code{abort} is called
809 immediately.  This can be useful because otherwise a crash may happen
810 much later, and the true cause for the problem is then very hard to
811 track down.
812
813 There is one problem with @code{MALLOC_CHECK_}: in SUID or SGID binaries
814 it could possibly be exploited since diverging from the normal programs
815 behavior it now writes something to the standard error descriptor.
816 Therefore the use of @code{MALLOC_CHECK_} is disabled by default for
817 SUID and SGID binaries.  It can be enabled again by the system
818 administrator by adding a file @file{/etc/suid-debug} (the content is
819 not important it could be empty).
820
821 So, what's the difference between using @code{MALLOC_CHECK_} and linking
822 with @samp{-lmcheck}?  @code{MALLOC_CHECK_} is orthogonal with respect to
823 @samp{-lmcheck}.  @samp{-lmcheck} has been added for backward
824 compatibility.  Both @code{MALLOC_CHECK_} and @samp{-lmcheck} should
825 uncover the same bugs - but using @code{MALLOC_CHECK_} you don't need to
826 recompile your application.
827
828 @node Hooks for Malloc
829 @subsubsection Memory Allocation Hooks
830 @cindex allocation hooks, for @code{malloc}
831
832 The GNU C library lets you modify the behavior of @code{malloc},
833 @code{realloc}, and @code{free} by specifying appropriate hook
834 functions.  You can use these hooks to help you debug programs that use
835 dynamic memory allocation, for example.
836
837 The hook variables are declared in @file{malloc.h}.
838 @pindex malloc.h
839
840 @comment malloc.h
841 @comment GNU
842 @defvar __malloc_hook
843 The value of this variable is a pointer to the function that
844 @code{malloc} uses whenever it is called.  You should define this
845 function to look like @code{malloc}; that is, like:
846
847 @smallexample
848 void *@var{function} (size_t @var{size}, const void *@var{caller})
849 @end smallexample
850
851 The value of @var{caller} is the return address found on the stack when
852 the @code{malloc} function was called.  This value allows you to trace
853 the memory consumption of the program.
854 @end defvar
855
856 @comment malloc.h
857 @comment GNU
858 @defvar __realloc_hook
859 The value of this variable is a pointer to function that @code{realloc}
860 uses whenever it is called.  You should define this function to look
861 like @code{realloc}; that is, like:
862
863 @smallexample
864 void *@var{function} (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
865 @end smallexample
866
867 The value of @var{caller} is the return address found on the stack when
868 the @code{realloc} function was called.  This value allows you to trace the
869 memory consumption of the program.
870 @end defvar
871
872 @comment malloc.h
873 @comment GNU
874 @defvar __free_hook
875 The value of this variable is a pointer to function that @code{free}
876 uses whenever it is called.  You should define this function to look
877 like @code{free}; that is, like:
878
879 @smallexample
880 void @var{function} (void *@var{ptr}, const void *@var{caller})
881 @end smallexample
882
883 The value of @var{caller} is the return address found on the stack when
884 the @code{free} function was called.  This value allows you to trace the
885 memory consumption of the program.
886 @end defvar
887
888 @comment malloc.h
889 @comment GNU
890 @defvar __memalign_hook
891 The value of this variable is a pointer to function that @code{memalign}
892 uses whenever it is called.  You should define this function to look
893 like @code{memalign}; that is, like:
894
895 @smallexample
896 void *@var{function} (size_t @var{alignment}, size_t @var{size}, const void *@var{caller})
897 @end smallexample
898
899 The value of @var{caller} is the return address found on the stack when
900 the @code{memalign} function was called.  This value allows you to trace the
901 memory consumption of the program.
902 @end defvar
903
904 You must make sure that the function you install as a hook for one of
905 these functions does not call that function recursively without restoring
906 the old value of the hook first!  Otherwise, your program will get stuck
907 in an infinite recursion.  Before calling the function recursively, one
908 should make sure to restore all the hooks to their previous value.  When
909 coming back from the recursive call, all the hooks should be resaved
910 since a hook might modify itself.
911
912 @comment malloc.h
913 @comment GNU
914 @defvar __malloc_initialize_hook
915 The value of this variable is a pointer to a function that is called
916 once when the malloc implementation is initialized.  This is a weak
917 variable, so it can be overridden in the application with a definition
918 like the following:
919
920 @smallexample
921 void (*@var{__malloc_initialize_hook}) (void) = my_init_hook;
922 @end smallexample
923 @end defvar
924
925 An issue to look out for is the time at which the malloc hook functions
926 can be safely installed.  If the hook functions call the malloc-related
927 functions recursively, it is necessary that malloc has already properly
928 initialized itself at the time when @code{__malloc_hook} etc. is
929 assigned to.  On the other hand, if the hook functions provide a
930 complete malloc implementation of their own, it is vital that the hooks
931 are assigned to @emph{before} the very first @code{malloc} call has
932 completed, because otherwise a chunk obtained from the ordinary,
933 un-hooked malloc may later be handed to @code{__free_hook}, for example.
934
935 In both cases, the problem can be solved by setting up the hooks from
936 within a user-defined function pointed to by
937 @code{__malloc_initialize_hook}---then the hooks will be set up safely
938 at the right time.
939
940 Here is an example showing how to use @code{__malloc_hook} and
941 @code{__free_hook} properly.  It installs a function that prints out
942 information every time @code{malloc} or @code{free} is called.  We just
943 assume here that @code{realloc} and @code{memalign} are not used in our
944 program.
945
946 @smallexample
947 /* Prototypes for __malloc_hook, __free_hook */
948 #include <malloc.h>
949
950 /* Prototypes for our hooks.  */
951 static void *my_init_hook (void);
952 static void *my_malloc_hook (size_t, const void *);
953 static void my_free_hook (void*, const void *);
954
955 /* Override initializing hook from the C library. */
956 void (*__malloc_initialize_hook) (void) = my_init_hook;
957
958 static void
959 my_init_hook (void)
960 @{
961   old_malloc_hook = __malloc_hook;
962   old_free_hook = __free_hook;
963   __malloc_hook = my_malloc_hook;
964   __free_hook = my_free_hook;
965 @}
966
967 static void *
968 my_malloc_hook (size_t size, const void *caller)
969 @{
970   void *result;
971   /* Restore all old hooks */
972   __malloc_hook = old_malloc_hook;
973   __free_hook = old_free_hook;
974   /* Call recursively */
975   result = malloc (size);
976   /* Save underlying hooks */
977   old_malloc_hook = __malloc_hook;
978   old_free_hook = __free_hook;
979   /* @r{@code{printf} might call @code{malloc}, so protect it too.} */
980   printf ("malloc (%u) returns %p\n", (unsigned int) size, result);
981   /* Restore our own hooks */
982   __malloc_hook = my_malloc_hook;
983   __free_hook = my_free_hook;
984   return result;
985 @}
986
987 static void *
988 my_free_hook (void *ptr, const void *caller)
989 @{
990   /* Restore all old hooks */
991   __malloc_hook = old_malloc_hook;
992   __free_hook = old_free_hook;
993   /* Call recursively */
994   free (ptr);
995   /* Save underlying hooks */
996   old_malloc_hook = __malloc_hook;
997   old_free_hook = __free_hook;
998   /* @r{@code{printf} might call @code{free}, so protect it too.} */
999   printf ("freed pointer %p\n", ptr);
1000   /* Restore our own hooks */
1001   __malloc_hook = my_malloc_hook;
1002   __free_hook = my_free_hook;
1003 @}
1004
1005 main ()
1006 @{
1007   @dots{}
1008 @}
1009 @end smallexample
1010
1011 The @code{mcheck} function (@pxref{Heap Consistency Checking}) works by
1012 installing such hooks.
1013
1014 @c __morecore, __after_morecore_hook are undocumented
1015 @c It's not clear whether to document them.
1016
1017 @node Statistics of Malloc
1018 @subsubsection Statistics for Memory Allocation with @code{malloc}
1019
1020 @cindex allocation statistics
1021 You can get information about dynamic memory allocation by calling the
1022 @code{mallinfo} function.  This function and its associated data type
1023 are declared in @file{malloc.h}; they are an extension of the standard
1024 SVID/XPG version.
1025 @pindex malloc.h
1026
1027 @comment malloc.h
1028 @comment GNU
1029 @deftp {Data Type} {struct mallinfo}
1030 This structure type is used to return information about the dynamic
1031 memory allocator.  It contains the following members:
1032
1033 @table @code
1034 @item int arena
1035 This is the total size of memory allocated with @code{sbrk} by
1036 @code{malloc}, in bytes.
1037
1038 @item int ordblks
1039 This is the number of chunks not in use.  (The memory allocator
1040 internally gets chunks of memory from the operating system, and then
1041 carves them up to satisfy individual @code{malloc} requests; see
1042 @ref{Efficiency and Malloc}.)
1043
1044 @item int smblks
1045 This field is unused.
1046
1047 @item int hblks
1048 This is the total number of chunks allocated with @code{mmap}.
1049
1050 @item int hblkhd
1051 This is the total size of memory allocated with @code{mmap}, in bytes.
1052
1053 @item int usmblks
1054 This field is unused.
1055
1056 @item int fsmblks
1057 This field is unused.
1058
1059 @item int uordblks
1060 This is the total size of memory occupied by chunks handed out by
1061 @code{malloc}.
1062
1063 @item int fordblks
1064 This is the total size of memory occupied by free (not in use) chunks.
1065
1066 @item int keepcost
1067 This is the size of the top-most releasable chunk that normally
1068 borders the end of the heap (i.e. the high end of the virtual address
1069 space's data segment).
1070
1071 @end table
1072 @end deftp
1073
1074 @comment malloc.h
1075 @comment SVID
1076 @deftypefun {struct mallinfo} mallinfo (void)
1077 This function returns information about the current dynamic memory usage
1078 in a structure of type @code{struct mallinfo}.
1079 @end deftypefun
1080
1081 @node Summary of Malloc
1082 @subsubsection Summary of @code{malloc}-Related Functions
1083
1084 Here is a summary of the functions that work with @code{malloc}:
1085
1086 @table @code
1087 @item void *malloc (size_t @var{size})
1088 Allocate a block of @var{size} bytes.  @xref{Basic Allocation}.
1089
1090 @item void free (void *@var{addr})
1091 Free a block previously allocated by @code{malloc}.  @xref{Freeing after
1092 Malloc}.
1093
1094 @item void *realloc (void *@var{addr}, size_t @var{size})
1095 Make a block previously allocated by @code{malloc} larger or smaller,
1096 possibly by copying it to a new location.  @xref{Changing Block Size}.
1097
1098 @item void *calloc (size_t @var{count}, size_t @var{eltsize})
1099 Allocate a block of @var{count} * @var{eltsize} bytes using
1100 @code{malloc}, and set its contents to zero.  @xref{Allocating Cleared
1101 Space}.
1102
1103 @item void *valloc (size_t @var{size})
1104 Allocate a block of @var{size} bytes, starting on a page boundary.
1105 @xref{Aligned Memory Blocks}.
1106
1107 @item void *memalign (size_t @var{size}, size_t @var{boundary})
1108 Allocate a block of @var{size} bytes, starting on an address that is a
1109 multiple of @var{boundary}.  @xref{Aligned Memory Blocks}.
1110
1111 @item int mallopt (int @var{param}, int @var{value})
1112 Adjust a tunable parameter.  @xref{Malloc Tunable Parameters}.
1113
1114 @item int mcheck (void (*@var{abortfn}) (void))
1115 Tell @code{malloc} to perform occasional consistency checks on
1116 dynamically allocated memory, and to call @var{abortfn} when an
1117 inconsistency is found.  @xref{Heap Consistency Checking}.
1118
1119 @item void *(*__malloc_hook) (size_t @var{size}, const void *@var{caller})
1120 A pointer to a function that @code{malloc} uses whenever it is called.
1121
1122 @item void *(*__realloc_hook) (void *@var{ptr}, size_t @var{size}, const void *@var{caller})
1123 A pointer to a function that @code{realloc} uses whenever it is called.
1124
1125 @item void (*__free_hook) (void *@var{ptr}, const void *@var{caller})
1126 A pointer to a function that @code{free} uses whenever it is called.
1127
1128 @item void (*__memalign_hook) (size_t @var{size}, size_t @var{alignment}, const void *@var{caller})
1129 A pointer to a function that @code{memalign} uses whenever it is called.
1130
1131 @item struct mallinfo mallinfo (void)
1132 Return information about the current dynamic memory usage.
1133 @xref{Statistics of Malloc}.
1134 @end table
1135
1136 @node Allocation Debugging
1137 @subsection Allocation Debugging
1138 @cindex allocation debugging
1139 @cindex malloc debugger
1140
1141 A complicated task when programming with languages which do not use
1142 garbage collected dynamic memory allocation is to find memory leaks.
1143 Long running programs must assure that dynamically allocated objects are
1144 freed at the end of their lifetime.  If this does not happen the system
1145 runs out of memory, sooner or later.
1146
1147 The @code{malloc} implementation in the GNU C library provides some
1148 simple means to detect such leaks and obtain some information to find
1149 the location.  To do this the application must be started in a special
1150 mode which is enabled by an environment variable.  There are no speed
1151 penalties for the program if the debugging mode is not enabled.
1152
1153 @menu
1154 * Tracing malloc::               How to install the tracing functionality.
1155 * Using the Memory Debugger::    Example programs excerpts.
1156 * Tips for the Memory Debugger:: Some more or less clever ideas.
1157 * Interpreting the traces::      What do all these lines mean?
1158 @end menu
1159
1160 @node Tracing malloc
1161 @subsubsection How to install the tracing functionality
1162
1163 @comment mcheck.h
1164 @comment GNU
1165 @deftypefun void mtrace (void)
1166 When the @code{mtrace} function is called it looks for an environment
1167 variable named @code{MALLOC_TRACE}.  This variable is supposed to
1168 contain a valid file name.  The user must have write access.  If the
1169 file already exists it is truncated.  If the environment variable is not
1170 set or it does not name a valid file which can be opened for writing
1171 nothing is done.  The behavior of @code{malloc} etc. is not changed.
1172 For obvious reasons this also happens if the application is installed
1173 with the SUID or SGID bit set.
1174
1175 If the named file is successfully opened, @code{mtrace} installs special
1176 handlers for the functions @code{malloc}, @code{realloc}, and
1177 @code{free} (@pxref{Hooks for Malloc}).  From then on, all uses of these
1178 functions are traced and protocolled into the file.  There is now of
1179 course a speed penalty for all calls to the traced functions so tracing
1180 should not be enabled during normal use.
1181
1182 This function is a GNU extension and generally not available on other
1183 systems.  The prototype can be found in @file{mcheck.h}.
1184 @end deftypefun
1185
1186 @comment mcheck.h
1187 @comment GNU
1188 @deftypefun void muntrace (void)
1189 The @code{muntrace} function can be called after @code{mtrace} was used
1190 to enable tracing the @code{malloc} calls.  If no (successful) call of
1191 @code{mtrace} was made @code{muntrace} does nothing.
1192
1193 Otherwise it deinstalls the handlers for @code{malloc}, @code{realloc},
1194 and @code{free} and then closes the protocol file.  No calls are
1195 protocolled anymore and the program runs again at full speed.
1196
1197 This function is a GNU extension and generally not available on other
1198 systems.  The prototype can be found in @file{mcheck.h}.
1199 @end deftypefun
1200
1201 @node Using the Memory Debugger
1202 @subsubsection Example program excerpts
1203
1204 Even though the tracing functionality does not influence the runtime
1205 behavior of the program it is not a good idea to call @code{mtrace} in
1206 all programs.  Just imagine that you debug a program using @code{mtrace}
1207 and all other programs used in the debugging session also trace their
1208 @code{malloc} calls.  The output file would be the same for all programs
1209 and thus is unusable.  Therefore one should call @code{mtrace} only if
1210 compiled for debugging.  A program could therefore start like this:
1211
1212 @example
1213 #include <mcheck.h>
1214
1215 int
1216 main (int argc, char *argv[])
1217 @{
1218 #ifdef DEBUGGING
1219   mtrace ();
1220 #endif
1221   @dots{}
1222 @}
1223 @end example
1224
1225 This is all what is needed if you want to trace the calls during the
1226 whole runtime of the program.  Alternatively you can stop the tracing at
1227 any time with a call to @code{muntrace}.  It is even possible to restart
1228 the tracing again with a new call to @code{mtrace}.  But this can cause
1229 unreliable results since there may be calls of the functions which are
1230 not called.  Please note that not only the application uses the traced
1231 functions, also libraries (including the C library itself) use these
1232 functions.
1233
1234 This last point is also why it is no good idea to call @code{muntrace}
1235 before the program terminated.  The libraries are informed about the
1236 termination of the program only after the program returns from
1237 @code{main} or calls @code{exit} and so cannot free the memory they use
1238 before this time.
1239
1240 So the best thing one can do is to call @code{mtrace} as the very first
1241 function in the program and never call @code{muntrace}.  So the program
1242 traces almost all uses of the @code{malloc} functions (except those
1243 calls which are executed by constructors of the program or used
1244 libraries).
1245
1246 @node Tips for the Memory Debugger
1247 @subsubsection Some more or less clever ideas
1248
1249 You know the situation.  The program is prepared for debugging and in
1250 all debugging sessions it runs well.  But once it is started without
1251 debugging the error shows up.  A typical example is a memory leak that
1252 becomes visible only when we turn off the debugging.  If you foresee
1253 such situations you can still win.  Simply use something equivalent to
1254 the following little program:
1255
1256 @example
1257 #include <mcheck.h>
1258 #include <signal.h>
1259
1260 static void
1261 enable (int sig)
1262 @{
1263   mtrace ();
1264   signal (SIGUSR1, enable);
1265 @}
1266
1267 static void
1268 disable (int sig)
1269 @{
1270   muntrace ();
1271   signal (SIGUSR2, disable);
1272 @}
1273
1274 int
1275 main (int argc, char *argv[])
1276 @{
1277   @dots{}
1278
1279   signal (SIGUSR1, enable);
1280   signal (SIGUSR2, disable);
1281
1282   @dots{}
1283 @}
1284 @end example
1285
1286 I.e., the user can start the memory debugger any time s/he wants if the
1287 program was started with @code{MALLOC_TRACE} set in the environment.
1288 The output will of course not show the allocations which happened before
1289 the first signal but if there is a memory leak this will show up
1290 nevertheless.
1291
1292 @node Interpreting the traces
1293 @subsubsection Interpreting the traces
1294
1295 If you take a look at the output it will look similar to this:
1296
1297 @example
1298 = Start
1299 @ [0x8048209] - 0x8064cc8
1300 @ [0x8048209] - 0x8064ce0
1301 @ [0x8048209] - 0x8064cf8
1302 @ [0x80481eb] + 0x8064c48 0x14
1303 @ [0x80481eb] + 0x8064c60 0x14
1304 @ [0x80481eb] + 0x8064c78 0x14
1305 @ [0x80481eb] + 0x8064c90 0x14
1306 = End
1307 @end example
1308
1309 What this all means is not really important since the trace file is not
1310 meant to be read by a human.  Therefore no attention is given to
1311 readability.  Instead there is a program which comes with the GNU C
1312 library which interprets the traces and outputs a summary in an
1313 user-friendly way.  The program is called @code{mtrace} (it is in fact a
1314 Perl script) and it takes one or two arguments.  In any case the name of
1315 the file with the trace output must be specified.  If an optional
1316 argument precedes the name of the trace file this must be the name of
1317 the program which generated the trace.
1318
1319 @example
1320 drepper$ mtrace tst-mtrace log
1321 No memory leaks.
1322 @end example
1323
1324 In this case the program @code{tst-mtrace} was run and it produced a
1325 trace file @file{log}.  The message printed by @code{mtrace} shows there
1326 are no problems with the code, all allocated memory was freed
1327 afterwards.
1328
1329 If we call @code{mtrace} on the example trace given above we would get a
1330 different outout:
1331
1332 @example
1333 drepper$ mtrace errlog
1334 - 0x08064cc8 Free 2 was never alloc'd 0x8048209
1335 - 0x08064ce0 Free 3 was never alloc'd 0x8048209
1336 - 0x08064cf8 Free 4 was never alloc'd 0x8048209
1337
1338 Memory not freed:
1339 -----------------
1340    Address     Size     Caller
1341 0x08064c48     0x14  at 0x80481eb
1342 0x08064c60     0x14  at 0x80481eb
1343 0x08064c78     0x14  at 0x80481eb
1344 0x08064c90     0x14  at 0x80481eb
1345 @end example
1346
1347 We have called @code{mtrace} with only one argument and so the script
1348 has no chance to find out what is meant with the addresses given in the
1349 trace.  We can do better:
1350
1351 @example
1352 drepper$ mtrace tst errlog
1353 - 0x08064cc8 Free 2 was never alloc'd /home/drepper/tst.c:39
1354 - 0x08064ce0 Free 3 was never alloc'd /home/drepper/tst.c:39
1355 - 0x08064cf8 Free 4 was never alloc'd /home/drepper/tst.c:39
1356
1357 Memory not freed:
1358 -----------------
1359    Address     Size     Caller
1360 0x08064c48     0x14  at /home/drepper/tst.c:33
1361 0x08064c60     0x14  at /home/drepper/tst.c:33
1362 0x08064c78     0x14  at /home/drepper/tst.c:33
1363 0x08064c90     0x14  at /home/drepper/tst.c:33
1364 @end example
1365
1366 Suddenly the output makes much more sense and the user can see
1367 immediately where the function calls causing the trouble can be found.
1368
1369 Interpreting this output is not complicated.  There are at most two
1370 different situations being detected.  First, @code{free} was called for
1371 pointers which were never returned by one of the allocation functions.
1372 This is usually a very bad problem and what this looks like is shown in
1373 the first three lines of the output.  Situations like this are quite
1374 rare and if they appear they show up very drastically: the program
1375 normally crashes.
1376
1377 The other situation which is much harder to detect are memory leaks.  As
1378 you can see in the output the @code{mtrace} function collects all this
1379 information and so can say that the program calls an allocation function
1380 from line 33 in the source file @file{/home/drepper/tst-mtrace.c} four
1381 times without freeing this memory before the program terminates.
1382 Whether this is a real problem remains to be investigated.
1383
1384 @node Obstacks
1385 @subsection Obstacks
1386 @cindex obstacks
1387
1388 An @dfn{obstack} is a pool of memory containing a stack of objects.  You
1389 can create any number of separate obstacks, and then allocate objects in
1390 specified obstacks.  Within each obstack, the last object allocated must
1391 always be the first one freed, but distinct obstacks are independent of
1392 each other.
1393
1394 Aside from this one constraint of order of freeing, obstacks are totally
1395 general: an obstack can contain any number of objects of any size.  They
1396 are implemented with macros, so allocation is usually very fast as long as
1397 the objects are usually small.  And the only space overhead per object is
1398 the padding needed to start each object on a suitable boundary.
1399
1400 @menu
1401 * Creating Obstacks::           How to declare an obstack in your program.
1402 * Preparing for Obstacks::      Preparations needed before you can
1403                                  use obstacks.
1404 * Allocation in an Obstack::    Allocating objects in an obstack.
1405 * Freeing Obstack Objects::     Freeing objects in an obstack.
1406 * Obstack Functions::           The obstack functions are both
1407                                  functions and macros.
1408 * Growing Objects::             Making an object bigger by stages.
1409 * Extra Fast Growing::          Extra-high-efficiency (though more
1410                                  complicated) growing objects.
1411 * Status of an Obstack::        Inquiries about the status of an obstack.
1412 * Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
1413 * Obstack Chunks::              How obstacks obtain and release chunks;
1414                                  efficiency considerations.
1415 * Summary of Obstacks::
1416 @end menu
1417
1418 @node Creating Obstacks
1419 @subsubsection Creating Obstacks
1420
1421 The utilities for manipulating obstacks are declared in the header
1422 file @file{obstack.h}.
1423 @pindex obstack.h
1424
1425 @comment obstack.h
1426 @comment GNU
1427 @deftp {Data Type} {struct obstack}
1428 An obstack is represented by a data structure of type @code{struct
1429 obstack}.  This structure has a small fixed size; it records the status
1430 of the obstack and how to find the space in which objects are allocated.
1431 It does not contain any of the objects themselves.  You should not try
1432 to access the contents of the structure directly; use only the functions
1433 described in this chapter.
1434 @end deftp
1435
1436 You can declare variables of type @code{struct obstack} and use them as
1437 obstacks, or you can allocate obstacks dynamically like any other kind
1438 of object.  Dynamic allocation of obstacks allows your program to have a
1439 variable number of different stacks.  (You can even allocate an
1440 obstack structure in another obstack, but this is rarely useful.)
1441
1442 All the functions that work with obstacks require you to specify which
1443 obstack to use.  You do this with a pointer of type @code{struct obstack
1444 *}.  In the following, we often say ``an obstack'' when strictly
1445 speaking the object at hand is such a pointer.
1446
1447 The objects in the obstack are packed into large blocks called
1448 @dfn{chunks}.  The @code{struct obstack} structure points to a chain of
1449 the chunks currently in use.
1450
1451 The obstack library obtains a new chunk whenever you allocate an object
1452 that won't fit in the previous chunk.  Since the obstack library manages
1453 chunks automatically, you don't need to pay much attention to them, but
1454 you do need to supply a function which the obstack library should use to
1455 get a chunk.  Usually you supply a function which uses @code{malloc}
1456 directly or indirectly.  You must also supply a function to free a chunk.
1457 These matters are described in the following section.
1458
1459 @node Preparing for Obstacks
1460 @subsubsection Preparing for Using Obstacks
1461
1462 Each source file in which you plan to use the obstack functions
1463 must include the header file @file{obstack.h}, like this:
1464
1465 @smallexample
1466 #include <obstack.h>
1467 @end smallexample
1468
1469 @findex obstack_chunk_alloc
1470 @findex obstack_chunk_free
1471 Also, if the source file uses the macro @code{obstack_init}, it must
1472 declare or define two functions or macros that will be called by the
1473 obstack library.  One, @code{obstack_chunk_alloc}, is used to allocate
1474 the chunks of memory into which objects are packed.  The other,
1475 @code{obstack_chunk_free}, is used to return chunks when the objects in
1476 them are freed.  These macros should appear before any use of obstacks
1477 in the source file.
1478
1479 Usually these are defined to use @code{malloc} via the intermediary
1480 @code{xmalloc} (@pxref{Unconstrained Allocation}).  This is done with
1481 the following pair of macro definitions:
1482
1483 @smallexample
1484 #define obstack_chunk_alloc xmalloc
1485 #define obstack_chunk_free free
1486 @end smallexample
1487
1488 @noindent
1489 Though the memory you get using obstacks really comes from @code{malloc},
1490 using obstacks is faster because @code{malloc} is called less often, for
1491 larger blocks of memory.  @xref{Obstack Chunks}, for full details.
1492
1493 At run time, before the program can use a @code{struct obstack} object
1494 as an obstack, it must initialize the obstack by calling
1495 @code{obstack_init}.
1496
1497 @comment obstack.h
1498 @comment GNU
1499 @deftypefun int obstack_init (struct obstack *@var{obstack-ptr})
1500 Initialize obstack @var{obstack-ptr} for allocation of objects.  This
1501 function calls the obstack's @code{obstack_chunk_alloc} function.  If
1502 allocation of memory fails, the function pointed to by
1503 @code{obstack_alloc_failed_handler} is called.  The @code{obstack_init}
1504 function always returns 1 (Compatibility notice: Former versions of
1505 obstack returned 0 if allocation failed).
1506 @end deftypefun
1507
1508 Here are two examples of how to allocate the space for an obstack and
1509 initialize it.  First, an obstack that is a static variable:
1510
1511 @smallexample
1512 static struct obstack myobstack;
1513 @dots{}
1514 obstack_init (&myobstack);
1515 @end smallexample
1516
1517 @noindent
1518 Second, an obstack that is itself dynamically allocated:
1519
1520 @smallexample
1521 struct obstack *myobstack_ptr
1522   = (struct obstack *) xmalloc (sizeof (struct obstack));
1523
1524 obstack_init (myobstack_ptr);
1525 @end smallexample
1526
1527 @comment obstack.h
1528 @comment GNU
1529 @defvar obstack_alloc_failed_handler
1530 The value of this variable is a pointer to a function that
1531 @code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate
1532 memory.  The default action is to print a message and abort.
1533 You should supply a function that either calls @code{exit}
1534 (@pxref{Program Termination}) or @code{longjmp} (@pxref{Non-Local
1535 Exits}) and doesn't return.
1536
1537 @smallexample
1538 void my_obstack_alloc_failed (void)
1539 @dots{}
1540 obstack_alloc_failed_handler = &my_obstack_alloc_failed;
1541 @end smallexample
1542
1543 @end defvar
1544
1545 @node Allocation in an Obstack
1546 @subsubsection Allocation in an Obstack
1547 @cindex allocation (obstacks)
1548
1549 The most direct way to allocate an object in an obstack is with
1550 @code{obstack_alloc}, which is invoked almost like @code{malloc}.
1551
1552 @comment obstack.h
1553 @comment GNU
1554 @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
1555 This allocates an uninitialized block of @var{size} bytes in an obstack
1556 and returns its address.  Here @var{obstack-ptr} specifies which obstack
1557 to allocate the block in; it is the address of the @code{struct obstack}
1558 object which represents the obstack.  Each obstack function or macro
1559 requires you to specify an @var{obstack-ptr} as the first argument.
1560
1561 This function calls the obstack's @code{obstack_chunk_alloc} function if
1562 it needs to allocate a new chunk of memory; it calls
1563 @code{obstack_alloc_failed_handler} if allocation of memory by
1564 @code{obstack_chunk_alloc} failed.
1565 @end deftypefun
1566
1567 For example, here is a function that allocates a copy of a string @var{str}
1568 in a specific obstack, which is in the variable @code{string_obstack}:
1569
1570 @smallexample
1571 struct obstack string_obstack;
1572
1573 char *
1574 copystring (char *string)
1575 @{
1576   size_t len = strlen (string) + 1;
1577   char *s = (char *) obstack_alloc (&string_obstack, len);
1578   memcpy (s, string, len);
1579   return s;
1580 @}
1581 @end smallexample
1582
1583 To allocate a block with specified contents, use the function
1584 @code{obstack_copy}, declared like this:
1585
1586 @comment obstack.h
1587 @comment GNU
1588 @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
1589 This allocates a block and initializes it by copying @var{size}
1590 bytes of data starting at @var{address}.  It calls
1591 @code{obstack_alloc_failed_handler} if allocation of memory by
1592 @code{obstack_chunk_alloc} failed.
1593 @end deftypefun
1594
1595 @comment obstack.h
1596 @comment GNU
1597 @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
1598 Like @code{obstack_copy}, but appends an extra byte containing a null
1599 character.  This extra byte is not counted in the argument @var{size}.
1600 @end deftypefun
1601
1602 The @code{obstack_copy0} function is convenient for copying a sequence
1603 of characters into an obstack as a null-terminated string.  Here is an
1604 example of its use:
1605
1606 @smallexample
1607 char *
1608 obstack_savestring (char *addr, int size)
1609 @{
1610   return obstack_copy0 (&myobstack, addr, size);
1611 @}
1612 @end smallexample
1613
1614 @noindent
1615 Contrast this with the previous example of @code{savestring} using
1616 @code{malloc} (@pxref{Basic Allocation}).
1617
1618 @node Freeing Obstack Objects
1619 @subsubsection Freeing Objects in an Obstack
1620 @cindex freeing (obstacks)
1621
1622 To free an object allocated in an obstack, use the function
1623 @code{obstack_free}.  Since the obstack is a stack of objects, freeing
1624 one object automatically frees all other objects allocated more recently
1625 in the same obstack.
1626
1627 @comment obstack.h
1628 @comment GNU
1629 @deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
1630 If @var{object} is a null pointer, everything allocated in the obstack
1631 is freed.  Otherwise, @var{object} must be the address of an object
1632 allocated in the obstack.  Then @var{object} is freed, along with
1633 everything allocated in @var{obstack} since @var{object}.
1634 @end deftypefun
1635
1636 Note that if @var{object} is a null pointer, the result is an
1637 uninitialized obstack.  To free all memory in an obstack but leave it
1638 valid for further allocation, call @code{obstack_free} with the address
1639 of the first object allocated on the obstack:
1640
1641 @smallexample
1642 obstack_free (obstack_ptr, first_object_allocated_ptr);
1643 @end smallexample
1644
1645 Recall that the objects in an obstack are grouped into chunks.  When all
1646 the objects in a chunk become free, the obstack library automatically
1647 frees the chunk (@pxref{Preparing for Obstacks}).  Then other
1648 obstacks, or non-obstack allocation, can reuse the space of the chunk.
1649
1650 @node Obstack Functions
1651 @subsubsection Obstack Functions and Macros
1652 @cindex macros
1653
1654 The interfaces for using obstacks may be defined either as functions or
1655 as macros, depending on the compiler.  The obstack facility works with
1656 all C compilers, including both @w{ISO C} and traditional C, but there are
1657 precautions you must take if you plan to use compilers other than GNU C.
1658
1659 If you are using an old-fashioned @w{non-ISO C} compiler, all the obstack
1660 ``functions'' are actually defined only as macros.  You can call these
1661 macros like functions, but you cannot use them in any other way (for
1662 example, you cannot take their address).
1663
1664 Calling the macros requires a special precaution: namely, the first
1665 operand (the obstack pointer) may not contain any side effects, because
1666 it may be computed more than once.  For example, if you write this:
1667
1668 @smallexample
1669 obstack_alloc (get_obstack (), 4);
1670 @end smallexample
1671
1672 @noindent
1673 you will find that @code{get_obstack} may be called several times.
1674 If you use @code{*obstack_list_ptr++} as the obstack pointer argument,
1675 you will get very strange results since the incrementation may occur
1676 several times.
1677
1678 In @w{ISO C}, each function has both a macro definition and a function
1679 definition.  The function definition is used if you take the address of the
1680 function without calling it.  An ordinary call uses the macro definition by
1681 default, but you can request the function definition instead by writing the
1682 function name in parentheses, as shown here:
1683
1684 @smallexample
1685 char *x;
1686 void *(*funcp) ();
1687 /* @r{Use the macro}.  */
1688 x = (char *) obstack_alloc (obptr, size);
1689 /* @r{Call the function}.  */
1690 x = (char *) (obstack_alloc) (obptr, size);
1691 /* @r{Take the address of the function}.  */
1692 funcp = obstack_alloc;
1693 @end smallexample
1694
1695 @noindent
1696 This is the same situation that exists in @w{ISO C} for the standard library
1697 functions.  @xref{Macro Definitions}.
1698
1699 @strong{Warning:} When you do use the macros, you must observe the
1700 precaution of avoiding side effects in the first operand, even in @w{ISO C}.
1701
1702 If you use the GNU C compiler, this precaution is not necessary, because
1703 various language extensions in GNU C permit defining the macros so as to
1704 compute each argument only once.
1705
1706 @node Growing Objects
1707 @subsubsection Growing Objects
1708 @cindex growing objects (in obstacks)
1709 @cindex changing the size of a block (obstacks)
1710
1711 Because memory in obstack chunks is used sequentially, it is possible to
1712 build up an object step by step, adding one or more bytes at a time to the
1713 end of the object.  With this technique, you do not need to know how much
1714 data you will put in the object until you come to the end of it.  We call
1715 this the technique of @dfn{growing objects}.  The special functions
1716 for adding data to the growing object are described in this section.
1717
1718 You don't need to do anything special when you start to grow an object.
1719 Using one of the functions to add data to the object automatically
1720 starts it.  However, it is necessary to say explicitly when the object is
1721 finished.  This is done with the function @code{obstack_finish}.
1722
1723 The actual address of the object thus built up is not known until the
1724 object is finished.  Until then, it always remains possible that you will
1725 add so much data that the object must be copied into a new chunk.
1726
1727 While the obstack is in use for a growing object, you cannot use it for
1728 ordinary allocation of another object.  If you try to do so, the space
1729 already added to the growing object will become part of the other object.
1730
1731 @comment obstack.h
1732 @comment GNU
1733 @deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
1734 The most basic function for adding to a growing object is
1735 @code{obstack_blank}, which adds space without initializing it.
1736 @end deftypefun
1737
1738 @comment obstack.h
1739 @comment GNU
1740 @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
1741 To add a block of initialized space, use @code{obstack_grow}, which is
1742 the growing-object analogue of @code{obstack_copy}.  It adds @var{size}
1743 bytes of data to the growing object, copying the contents from
1744 @var{data}.
1745 @end deftypefun
1746
1747 @comment obstack.h
1748 @comment GNU
1749 @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, int @var{size})
1750 This is the growing-object analogue of @code{obstack_copy0}.  It adds
1751 @var{size} bytes copied from @var{data}, followed by an additional null
1752 character.
1753 @end deftypefun
1754
1755 @comment obstack.h
1756 @comment GNU
1757 @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
1758 To add one character at a time, use the function @code{obstack_1grow}.
1759 It adds a single byte containing @var{c} to the growing object.
1760 @end deftypefun
1761
1762 @comment obstack.h
1763 @comment GNU
1764 @deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
1765 Adding the value of a pointer one can use the function
1766 @code{obstack_ptr_grow}.  It adds @code{sizeof (void *)} bytes
1767 containing the value of @var{data}.
1768 @end deftypefun
1769
1770 @comment obstack.h
1771 @comment GNU
1772 @deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
1773 A single value of type @code{int} can be added by using the
1774 @code{obstack_int_grow} function.  It adds @code{sizeof (int)} bytes to
1775 the growing object and initializes them with the value of @var{data}.
1776 @end deftypefun
1777
1778 @comment obstack.h
1779 @comment GNU
1780 @deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
1781 When you are finished growing the object, use the function
1782 @code{obstack_finish} to close it off and return its final address.
1783
1784 Once you have finished the object, the obstack is available for ordinary
1785 allocation or for growing another object.
1786
1787 This function can return a null pointer under the same conditions as
1788 @code{obstack_alloc} (@pxref{Allocation in an Obstack}).
1789 @end deftypefun
1790
1791 When you build an object by growing it, you will probably need to know
1792 afterward how long it became.  You need not keep track of this as you grow
1793 the object, because you can find out the length from the obstack just
1794 before finishing the object with the function @code{obstack_object_size},
1795 declared as follows:
1796
1797 @comment obstack.h
1798 @comment GNU
1799 @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
1800 This function returns the current size of the growing object, in bytes.
1801 Remember to call this function @emph{before} finishing the object.
1802 After it is finished, @code{obstack_object_size} will return zero.
1803 @end deftypefun
1804
1805 If you have started growing an object and wish to cancel it, you should
1806 finish it and then free it, like this:
1807
1808 @smallexample
1809 obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
1810 @end smallexample
1811
1812 @noindent
1813 This has no effect if no object was growing.
1814
1815 @cindex shrinking objects
1816 You can use @code{obstack_blank} with a negative size argument to make
1817 the current object smaller.  Just don't try to shrink it beyond zero
1818 length---there's no telling what will happen if you do that.
1819
1820 @node Extra Fast Growing
1821 @subsubsection Extra Fast Growing Objects
1822 @cindex efficiency and obstacks
1823
1824 The usual functions for growing objects incur overhead for checking
1825 whether there is room for the new growth in the current chunk.  If you
1826 are frequently constructing objects in small steps of growth, this
1827 overhead can be significant.
1828
1829 You can reduce the overhead by using special ``fast growth''
1830 functions that grow the object without checking.  In order to have a
1831 robust program, you must do the checking yourself.  If you do this checking
1832 in the simplest way each time you are about to add data to the object, you
1833 have not saved anything, because that is what the ordinary growth
1834 functions do.  But if you can arrange to check less often, or check
1835 more efficiently, then you make the program faster.
1836
1837 The function @code{obstack_room} returns the amount of room available
1838 in the current chunk.  It is declared as follows:
1839
1840 @comment obstack.h
1841 @comment GNU
1842 @deftypefun int obstack_room (struct obstack *@var{obstack-ptr})
1843 This returns the number of bytes that can be added safely to the current
1844 growing object (or to an object about to be started) in obstack
1845 @var{obstack} using the fast growth functions.
1846 @end deftypefun
1847
1848 While you know there is room, you can use these fast growth functions
1849 for adding data to a growing object:
1850
1851 @comment obstack.h
1852 @comment GNU
1853 @deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
1854 The function @code{obstack_1grow_fast} adds one byte containing the
1855 character @var{c} to the growing object in obstack @var{obstack-ptr}.
1856 @end deftypefun
1857
1858 @comment obstack.h
1859 @comment GNU
1860 @deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
1861 The function @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
1862 bytes containing the value of @var{data} to the growing object in
1863 obstack @var{obstack-ptr}.
1864 @end deftypefun
1865
1866 @comment obstack.h
1867 @comment GNU
1868 @deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
1869 The function @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
1870 containing the value of @var{data} to the growing object in obstack
1871 @var{obstack-ptr}.
1872 @end deftypefun
1873
1874 @comment obstack.h
1875 @comment GNU
1876 @deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
1877 The function @code{obstack_blank_fast} adds @var{size} bytes to the
1878 growing object in obstack @var{obstack-ptr} without initializing them.
1879 @end deftypefun
1880
1881 When you check for space using @code{obstack_room} and there is not
1882 enough room for what you want to add, the fast growth functions
1883 are not safe.  In this case, simply use the corresponding ordinary
1884 growth function instead.  Very soon this will copy the object to a
1885 new chunk; then there will be lots of room available again.
1886
1887 So, each time you use an ordinary growth function, check afterward for
1888 sufficient space using @code{obstack_room}.  Once the object is copied
1889 to a new chunk, there will be plenty of space again, so the program will
1890 start using the fast growth functions again.
1891
1892 Here is an example:
1893
1894 @smallexample
1895 @group
1896 void
1897 add_string (struct obstack *obstack, const char *ptr, int len)
1898 @{
1899   while (len > 0)
1900     @{
1901       int room = obstack_room (obstack);
1902       if (room == 0)
1903         @{
1904           /* @r{Not enough room. Add one character slowly,}
1905              @r{which may copy to a new chunk and make room.}  */
1906           obstack_1grow (obstack, *ptr++);
1907           len--;
1908         @}
1909       else
1910         @{
1911           if (room > len)
1912             room = len;
1913           /* @r{Add fast as much as we have room for.} */
1914           len -= room;
1915           while (room-- > 0)
1916             obstack_1grow_fast (obstack, *ptr++);
1917         @}
1918     @}
1919 @}
1920 @end group
1921 @end smallexample
1922
1923 @node Status of an Obstack
1924 @subsubsection Status of an Obstack
1925 @cindex obstack status
1926 @cindex status of obstack
1927
1928 Here are functions that provide information on the current status of
1929 allocation in an obstack.  You can use them to learn about an object while
1930 still growing it.
1931
1932 @comment obstack.h
1933 @comment GNU
1934 @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
1935 This function returns the tentative address of the beginning of the
1936 currently growing object in @var{obstack-ptr}.  If you finish the object
1937 immediately, it will have that address.  If you make it larger first, it
1938 may outgrow the current chunk---then its address will change!
1939
1940 If no object is growing, this value says where the next object you
1941 allocate will start (once again assuming it fits in the current
1942 chunk).
1943 @end deftypefun
1944
1945 @comment obstack.h
1946 @comment GNU
1947 @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
1948 This function returns the address of the first free byte in the current
1949 chunk of obstack @var{obstack-ptr}.  This is the end of the currently
1950 growing object.  If no object is growing, @code{obstack_next_free}
1951 returns the same value as @code{obstack_base}.
1952 @end deftypefun
1953
1954 @comment obstack.h
1955 @comment GNU
1956 @deftypefun int obstack_object_size (struct obstack *@var{obstack-ptr})
1957 This function returns the size in bytes of the currently growing object.
1958 This is equivalent to
1959
1960 @smallexample
1961 obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})
1962 @end smallexample
1963 @end deftypefun
1964
1965 @node Obstacks Data Alignment
1966 @subsubsection Alignment of Data in Obstacks
1967 @cindex alignment (in obstacks)
1968
1969 Each obstack has an @dfn{alignment boundary}; each object allocated in
1970 the obstack automatically starts on an address that is a multiple of the
1971 specified boundary.  By default, this boundary is 4 bytes.
1972
1973 To access an obstack's alignment boundary, use the macro
1974 @code{obstack_alignment_mask}, whose function prototype looks like
1975 this:
1976
1977 @comment obstack.h
1978 @comment GNU
1979 @deftypefn Macro int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
1980 The value is a bit mask; a bit that is 1 indicates that the corresponding
1981 bit in the address of an object should be 0.  The mask value should be one
1982 less than a power of 2; the effect is that all object addresses are
1983 multiples of that power of 2.  The default value of the mask is 3, so that
1984 addresses are multiples of 4.  A mask value of 0 means an object can start
1985 on any multiple of 1 (that is, no alignment is required).
1986
1987 The expansion of the macro @code{obstack_alignment_mask} is an lvalue,
1988 so you can alter the mask by assignment.  For example, this statement:
1989
1990 @smallexample
1991 obstack_alignment_mask (obstack_ptr) = 0;
1992 @end smallexample
1993
1994 @noindent
1995 has the effect of turning off alignment processing in the specified obstack.
1996 @end deftypefn
1997
1998 Note that a change in alignment mask does not take effect until
1999 @emph{after} the next time an object is allocated or finished in the
2000 obstack.  If you are not growing an object, you can make the new
2001 alignment mask take effect immediately by calling @code{obstack_finish}.
2002 This will finish a zero-length object and then do proper alignment for
2003 the next object.
2004
2005 @node Obstack Chunks
2006 @subsubsection Obstack Chunks
2007 @cindex efficiency of chunks
2008 @cindex chunks
2009
2010 Obstacks work by allocating space for themselves in large chunks, and
2011 then parceling out space in the chunks to satisfy your requests.  Chunks
2012 are normally 4096 bytes long unless you specify a different chunk size.
2013 The chunk size includes 8 bytes of overhead that are not actually used
2014 for storing objects.  Regardless of the specified size, longer chunks
2015 will be allocated when necessary for long objects.
2016
2017 The obstack library allocates chunks by calling the function
2018 @code{obstack_chunk_alloc}, which you must define.  When a chunk is no
2019 longer needed because you have freed all the objects in it, the obstack
2020 library frees the chunk by calling @code{obstack_chunk_free}, which you
2021 must also define.
2022
2023 These two must be defined (as macros) or declared (as functions) in each
2024 source file that uses @code{obstack_init} (@pxref{Creating Obstacks}).
2025 Most often they are defined as macros like this:
2026
2027 @smallexample
2028 #define obstack_chunk_alloc malloc
2029 #define obstack_chunk_free free
2030 @end smallexample
2031
2032 Note that these are simple macros (no arguments).  Macro definitions with
2033 arguments will not work!  It is necessary that @code{obstack_chunk_alloc}
2034 or @code{obstack_chunk_free}, alone, expand into a function name if it is
2035 not itself a function name.
2036
2037 If you allocate chunks with @code{malloc}, the chunk size should be a
2038 power of 2.  The default chunk size, 4096, was chosen because it is long
2039 enough to satisfy many typical requests on the obstack yet short enough
2040 not to waste too much memory in the portion of the last chunk not yet used.
2041
2042 @comment obstack.h
2043 @comment GNU
2044 @deftypefn Macro int obstack_chunk_size (struct obstack *@var{obstack-ptr})
2045 This returns the chunk size of the given obstack.
2046 @end deftypefn
2047
2048 Since this macro expands to an lvalue, you can specify a new chunk size by
2049 assigning it a new value.  Doing so does not affect the chunks already
2050 allocated, but will change the size of chunks allocated for that particular
2051 obstack in the future.  It is unlikely to be useful to make the chunk size
2052 smaller, but making it larger might improve efficiency if you are
2053 allocating many objects whose size is comparable to the chunk size.  Here
2054 is how to do so cleanly:
2055
2056 @smallexample
2057 if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size})
2058   obstack_chunk_size (obstack_ptr) = @var{new-chunk-size};
2059 @end smallexample
2060
2061 @node Summary of Obstacks
2062 @subsubsection Summary of Obstack Functions
2063
2064 Here is a summary of all the functions associated with obstacks.  Each
2065 takes the address of an obstack (@code{struct obstack *}) as its first
2066 argument.
2067
2068 @table @code
2069 @item void obstack_init (struct obstack *@var{obstack-ptr})
2070 Initialize use of an obstack.  @xref{Creating Obstacks}.
2071
2072 @item void *obstack_alloc (struct obstack *@var{obstack-ptr}, int @var{size})
2073 Allocate an object of @var{size} uninitialized bytes.
2074 @xref{Allocation in an Obstack}.
2075
2076 @item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2077 Allocate an object of @var{size} bytes, with contents copied from
2078 @var{address}.  @xref{Allocation in an Obstack}.
2079
2080 @item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2081 Allocate an object of @var{size}+1 bytes, with @var{size} of them copied
2082 from @var{address}, followed by a null character at the end.
2083 @xref{Allocation in an Obstack}.
2084
2085 @item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object})
2086 Free @var{object} (and everything allocated in the specified obstack
2087 more recently than @var{object}).  @xref{Freeing Obstack Objects}.
2088
2089 @item void obstack_blank (struct obstack *@var{obstack-ptr}, int @var{size})
2090 Add @var{size} uninitialized bytes to a growing object.
2091 @xref{Growing Objects}.
2092
2093 @item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2094 Add @var{size} bytes, copied from @var{address}, to a growing object.
2095 @xref{Growing Objects}.
2096
2097 @item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, int @var{size})
2098 Add @var{size} bytes, copied from @var{address}, to a growing object,
2099 and then add another byte containing a null character.  @xref{Growing
2100 Objects}.
2101
2102 @item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char})
2103 Add one byte containing @var{data-char} to a growing object.
2104 @xref{Growing Objects}.
2105
2106 @item void *obstack_finish (struct obstack *@var{obstack-ptr})
2107 Finalize the object that is growing and return its permanent address.
2108 @xref{Growing Objects}.
2109
2110 @item int obstack_object_size (struct obstack *@var{obstack-ptr})
2111 Get the current size of the currently growing object.  @xref{Growing
2112 Objects}.
2113
2114 @item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, int @var{size})
2115 Add @var{size} uninitialized bytes to a growing object without checking
2116 that there is enough room.  @xref{Extra Fast Growing}.
2117
2118 @item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char})
2119 Add one byte containing @var{data-char} to a growing object without
2120 checking that there is enough room.  @xref{Extra Fast Growing}.
2121
2122 @item int obstack_room (struct obstack *@var{obstack-ptr})
2123 Get the amount of room now available for growing the current object.
2124 @xref{Extra Fast Growing}.
2125
2126 @item int obstack_alignment_mask (struct obstack *@var{obstack-ptr})
2127 The mask used for aligning the beginning of an object.  This is an
2128 lvalue.  @xref{Obstacks Data Alignment}.
2129
2130 @item int obstack_chunk_size (struct obstack *@var{obstack-ptr})
2131 The size for allocating chunks.  This is an lvalue.  @xref{Obstack Chunks}.
2132
2133 @item void *obstack_base (struct obstack *@var{obstack-ptr})
2134 Tentative starting address of the currently growing object.
2135 @xref{Status of an Obstack}.
2136
2137 @item void *obstack_next_free (struct obstack *@var{obstack-ptr})
2138 Address just after the end of the currently growing object.
2139 @xref{Status of an Obstack}.
2140 @end table
2141
2142 @node Variable Size Automatic
2143 @subsection Automatic Storage with Variable Size
2144 @cindex automatic freeing
2145 @cindex @code{alloca} function
2146 @cindex automatic storage with variable size
2147
2148 The function @code{alloca} supports a kind of half-dynamic allocation in
2149 which blocks are allocated dynamically but freed automatically.
2150
2151 Allocating a block with @code{alloca} is an explicit action; you can
2152 allocate as many blocks as you wish, and compute the size at run time.  But
2153 all the blocks are freed when you exit the function that @code{alloca} was
2154 called from, just as if they were automatic variables declared in that
2155 function.  There is no way to free the space explicitly.
2156
2157 The prototype for @code{alloca} is in @file{stdlib.h}.  This function is
2158 a BSD extension.
2159 @pindex stdlib.h
2160
2161 @comment stdlib.h
2162 @comment GNU, BSD
2163 @deftypefun {void *} alloca (size_t @var{size});
2164 The return value of @code{alloca} is the address of a block of @var{size}
2165 bytes of memory, allocated in the stack frame of the calling function.
2166 @end deftypefun
2167
2168 Do not use @code{alloca} inside the arguments of a function call---you
2169 will get unpredictable results, because the stack space for the
2170 @code{alloca} would appear on the stack in the middle of the space for
2171 the function arguments.  An example of what to avoid is @code{foo (x,
2172 alloca (4), y)}.
2173 @c This might get fixed in future versions of GCC, but that won't make
2174 @c it safe with compilers generally.
2175
2176 @menu
2177 * Alloca Example::              Example of using @code{alloca}.
2178 * Advantages of Alloca::        Reasons to use @code{alloca}.
2179 * Disadvantages of Alloca::     Reasons to avoid @code{alloca}.
2180 * GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
2181                                  method of allocating dynamically and
2182                                  freeing automatically.
2183 @end menu
2184
2185 @node Alloca Example
2186 @subsubsection @code{alloca} Example
2187
2188 As an example of the use of @code{alloca}, here is a function that opens
2189 a file name made from concatenating two argument strings, and returns a
2190 file descriptor or minus one signifying failure:
2191
2192 @smallexample
2193 int
2194 open2 (char *str1, char *str2, int flags, int mode)
2195 @{
2196   char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
2197   stpcpy (stpcpy (name, str1), str2);
2198   return open (name, flags, mode);
2199 @}
2200 @end smallexample
2201
2202 @noindent
2203 Here is how you would get the same results with @code{malloc} and
2204 @code{free}:
2205
2206 @smallexample
2207 int
2208 open2 (char *str1, char *str2, int flags, int mode)
2209 @{
2210   char *name = (char *) malloc (strlen (str1) + strlen (str2) + 1);
2211   int desc;
2212   if (name == 0)
2213     fatal ("virtual memory exceeded");
2214   stpcpy (stpcpy (name, str1), str2);
2215   desc = open (name, flags, mode);
2216   free (name);
2217   return desc;
2218 @}
2219 @end smallexample
2220
2221 As you can see, it is simpler with @code{alloca}.  But @code{alloca} has
2222 other, more important advantages, and some disadvantages.
2223
2224 @node Advantages of Alloca
2225 @subsubsection Advantages of @code{alloca}
2226
2227 Here are the reasons why @code{alloca} may be preferable to @code{malloc}:
2228
2229 @itemize @bullet
2230 @item
2231 Using @code{alloca} wastes very little space and is very fast.  (It is
2232 open-coded by the GNU C compiler.)
2233
2234 @item
2235 Since @code{alloca} does not have separate pools for different sizes of
2236 block, space used for any size block can be reused for any other size.
2237 @code{alloca} does not cause memory fragmentation.
2238
2239 @item
2240 @cindex longjmp
2241 Nonlocal exits done with @code{longjmp} (@pxref{Non-Local Exits})
2242 automatically free the space allocated with @code{alloca} when they exit
2243 through the function that called @code{alloca}.  This is the most
2244 important reason to use @code{alloca}.
2245
2246 To illustrate this, suppose you have a function
2247 @code{open_or_report_error} which returns a descriptor, like
2248 @code{open}, if it succeeds, but does not return to its caller if it
2249 fails.  If the file cannot be opened, it prints an error message and
2250 jumps out to the command level of your program using @code{longjmp}.
2251 Let's change @code{open2} (@pxref{Alloca Example}) to use this
2252 subroutine:@refill
2253
2254 @smallexample
2255 int
2256 open2 (char *str1, char *str2, int flags, int mode)
2257 @{
2258   char *name = (char *) alloca (strlen (str1) + strlen (str2) + 1);
2259   stpcpy (stpcpy (name, str1), str2);
2260   return open_or_report_error (name, flags, mode);
2261 @}
2262 @end smallexample
2263
2264 @noindent
2265 Because of the way @code{alloca} works, the memory it allocates is
2266 freed even when an error occurs, with no special effort required.
2267
2268 By contrast, the previous definition of @code{open2} (which uses
2269 @code{malloc} and @code{free}) would develop a memory leak if it were
2270 changed in this way.  Even if you are willing to make more changes to
2271 fix it, there is no easy way to do so.
2272 @end itemize
2273
2274 @node Disadvantages of Alloca
2275 @subsubsection Disadvantages of @code{alloca}
2276
2277 @cindex @code{alloca} disadvantages
2278 @cindex disadvantages of @code{alloca}
2279 These are the disadvantages of @code{alloca} in comparison with
2280 @code{malloc}:
2281
2282 @itemize @bullet
2283 @item
2284 If you try to allocate more memory than the machine can provide, you
2285 don't get a clean error message.  Instead you get a fatal signal like
2286 the one you would get from an infinite recursion; probably a
2287 segmentation violation (@pxref{Program Error Signals}).
2288
2289 @item
2290 Some non-GNU systems fail to support @code{alloca}, so it is less
2291 portable.  However, a slower emulation of @code{alloca} written in C
2292 is available for use on systems with this deficiency.
2293 @end itemize
2294
2295 @node GNU C Variable-Size Arrays
2296 @subsubsection GNU C Variable-Size Arrays
2297 @cindex variable-sized arrays
2298
2299 In GNU C, you can replace most uses of @code{alloca} with an array of
2300 variable size.  Here is how @code{open2} would look then:
2301
2302 @smallexample
2303 int open2 (char *str1, char *str2, int flags, int mode)
2304 @{
2305   char name[strlen (str1) + strlen (str2) + 1];
2306   stpcpy (stpcpy (name, str1), str2);
2307   return open (name, flags, mode);
2308 @}
2309 @end smallexample
2310
2311 But @code{alloca} is not always equivalent to a variable-sized array, for
2312 several reasons:
2313
2314 @itemize @bullet
2315 @item
2316 A variable size array's space is freed at the end of the scope of the
2317 name of the array.  The space allocated with @code{alloca}
2318 remains until the end of the function.
2319
2320 @item
2321 It is possible to use @code{alloca} within a loop, allocating an
2322 additional block on each iteration.  This is impossible with
2323 variable-sized arrays.
2324 @end itemize
2325
2326 @strong{Note:} If you mix use of @code{alloca} and variable-sized arrays
2327 within one function, exiting a scope in which a variable-sized array was
2328 declared frees all blocks allocated with @code{alloca} during the
2329 execution of that scope.
2330
2331
2332 @node Resizing the Data Segment
2333 @section Resizing the Data Segment
2334
2335 The symbols in this section are declared in @file{unistd.h}.
2336
2337 You will not normally use the functions in this section, because the
2338 functions described in @ref{Memory Allocation} are easier to use.  Those
2339 are interfaces to a GNU C Library memory allocator that uses the
2340 functions below itself.  The functions below are simple interfaces to
2341 system calls.
2342
2343 @comment unistd.h
2344 @comment BSD
2345 @deftypefun int brk (void *@var{addr})
2346
2347 @code{brk} sets the high end of the calling process' data segment to
2348 @var{addr}.
2349
2350 The address of the end of a segment is defined to be the address of the
2351 last byte in the segment plus 1.
2352
2353 The function has no effect if @var{addr} is lower than the low end of
2354 the data segment.  (This is considered success, by the way).
2355
2356 The function fails if it would cause the data segment to overlap another
2357 segment or exceed the process' data storage limit (@pxref{Limits on
2358 Resources}).
2359
2360 The function is named for a common historical case where data storage
2361 and the stack are in the same segment.  Data storage allocation grows
2362 upward from the bottom of the segment while the stack grows downward
2363 toward it from the top of the segment and the curtain between them is
2364 called the @dfn{break}.
2365
2366 The return value is zero on success.  On failure, the return value is
2367 @code{-1} and @code{errno} is set accordingly.  The following @code{errno}
2368 values are specific to this function:
2369
2370 @table @code
2371 @item ENOMEM
2372 The request would cause the data segment to overlap another segment or
2373 exceed the process' data storage limit.
2374 @end table
2375
2376 @c The Brk system call in Linux (as opposed to the GNU C Library function)
2377 @c is considerably different.  It always returns the new end of the data
2378 @c segment, whether it succeeds or fails.  The GNU C library Brk determines
2379 @c it's a failure if and only if if the system call returns an address less
2380 @c than the address requested.
2381
2382 @end deftypefun
2383
2384
2385 @comment unistd.h
2386 @comment BSD
2387 @deftypefun int sbrk (ptrdiff_t @var{delta})
2388 This function is the same as @code{brk} except that you specify the new
2389 end of the data segment as an offset @var{delta} from the current end
2390 and on success the return value is the address of the resulting end of
2391 the data segment instead of zero.
2392
2393 This means you can use @samp{sbrk(0)} to find out what the current end
2394 of the data segment is.
2395
2396 @end deftypefun
2397
2398
2399
2400 @node Locking Pages
2401 @section Locking Pages
2402 @cindex locking pages
2403 @cindex memory lock
2404 @cindex paging
2405
2406 You can tell the system to associate a particular virtual memory page
2407 with a real page frame and keep it that way --- i.e. cause the page to
2408 be paged in if it isn't already and mark it so it will never be paged
2409 out and consequently will never cause a page fault.  This is called
2410 @dfn{locking} a page.
2411
2412 The functions in this chapter lock and unlock the calling process'
2413 pages.
2414
2415 @menu
2416 * Why Lock Pages::                Reasons to read this section.
2417 * Locked Memory Details::         Everything you need to know locked
2418                                     memory
2419 * Page Lock Functions::           Here's how to do it.
2420 @end menu
2421
2422 @node Why Lock Pages
2423 @subsection Why Lock Pages
2424
2425 Because page faults cause paged out pages to be paged in transparently,
2426 a process rarely needs to be concerned about locking pages.  However,
2427 there are two reasons people sometimes are:
2428
2429 @itemize @bullet
2430
2431 @item
2432 Speed.  A page fault is transparent only insofar as the process is not
2433 sensitive to how long it takes to do a simple memory access.  Time-critical
2434 processes, especially realtime processes, may not be able to wait or
2435 may not be able to tolerate variance in execution speed.
2436 @cindex realtime processing
2437 @cindex speed of execution
2438
2439 A process that needs to lock pages for this reason probably also needs
2440 priority among other processes for use of the CPU.  @xref{Priority}.
2441
2442 In some cases, the programmer knows better than the system's demand
2443 paging allocator which pages should remain in real memory to optimize
2444 system performance.  In this case, locking pages can help.
2445
2446 @item
2447 Privacy.  If you keep secrets in virtual memory and that virtual memory
2448 gets paged out, that increases the chance that the secrets will get out.
2449 If a password gets written out to disk swap space, for example, it might
2450 still be there long after virtual and real memory have been wiped clean.
2451
2452 @end itemize
2453
2454 Be aware that when you lock a page, that's one fewer page frame that can
2455 be used to back other virtual memory (by the same or other processes),
2456 which can mean more page faults, which means the system runs more
2457 slowly.  In fact, if you lock enough memory, some programs may not be
2458 able to run at all for lack of real memory.
2459
2460 @node Locked Memory Details
2461 @subsection Locked Memory Details
2462
2463 A memory lock is associated with a virtual page, not a real frame.  The
2464 paging rule is: If a frame backs at least one locked page, don't page it
2465 out.
2466
2467 Memory locks do not stack.  I.e. you can't lock a particular page twice
2468 so that it has to be unlocked twice before it is truly unlocked.  It is
2469 either locked or it isn't.
2470
2471 A memory lock persists until the process that owns the memory explicitly
2472 unlocks it.  (But process termination and exec cause the virtual memory
2473 to cease to exist, which you might say means it isn't locked any more).
2474
2475 Memory locks are not inherited by child processes.  (But note that on a
2476 modern Unix system, immediately after a fork, the parent's and the
2477 child's virtual address space are backed by the same real page frames,
2478 so the child enjoys the parent's locks).  @xref{Creating a Process}.
2479
2480 Because of its ability to impact other processes, only the superuser can
2481 lock a page.  Any process can unlock its own page.
2482
2483 The system sets limits on the amount of memory a process can have locked
2484 and the amount of real memory it can have dedicated to it.  @xref{Limits
2485 on Resources}.
2486
2487 In Linux, locked pages aren't as locked as you might think.
2488 Two virtual pages that are not shared memory can nonetheless be backed
2489 by the same real frame.  The kernel does this in the name of efficiency
2490 when it knows both virtual pages contain identical data, and does it
2491 even if one or both of the virtual pages are locked.
2492
2493 But when a process modifies one of those pages, the kernel must get it a
2494 separate frame and fill it with the page's data.  This is known as a
2495 @dfn{copy-on-write page fault}.  It takes a small amount of time and in
2496 a pathological case, getting that frame may require I/O.
2497 @cindex copy-on-write page fault
2498 @cindex page fault, copy-on-write
2499
2500 To make sure this doesn't happen to your program, don't just lock the
2501 pages.  Write to them as well, unless you know you won't write to them
2502 ever.  And to make sure you have pre-allocated frames for your stack,
2503 enter a scope that declares a C automatic variable larger than the
2504 maximum stack size you will need, set it to something, then return from
2505 its scope.
2506
2507 @node Page Lock Functions
2508 @subsection Functions To Lock And Unlock Pages
2509
2510 The symbols in this section are declared in @file{sys/mman.h}.  These
2511 functions are defined by POSIX.1b, but their availability depends on
2512 your kernel.  If your kernel doesn't allow these functions, they exist
2513 but always fail.  They @emph{are} available with a Linux kernel.
2514
2515 @strong{Portability Note:} POSIX.1b requires that when the @code{mlock}
2516 and @code{munlock} functions are available, the file @file{unistd.h}
2517 define the macro @code{_POSIX_MEMLOCK_RANGE} and the file
2518 @code{limits.h} define the macro @code{PAGESIZE} to be the size of a
2519 memory page in bytes.  It requires that when the @code{mlockall} and
2520 @code{munlockall} functions are available, the @file{unistd.h} file
2521 define the macro @code{_POSIX_MEMLOCK}.  The GNU C library conforms to
2522 this requirement.
2523
2524 @comment sys/mman.h
2525 @comment POSIX.1b
2526 @deftypefun int mlock (const void *@var{addr}, size_t @var{len})
2527
2528 @code{mlock} locks a range of the calling process' virtual pages.
2529
2530 The range of memory starts at address @var{addr} and is @var{len} bytes
2531 long.  Actually, since you must lock whole pages, it is the range of
2532 pages that include any part of the specified range.
2533
2534 When the function returns successfully, each of those pages is backed by
2535 (connected to) a real frame (is resident) and is marked to stay that
2536 way.  This means the function may cause page-ins and have to wait for
2537 them.
2538
2539 When the function fails, it does not affect the lock status of any
2540 pages.
2541
2542 The return value is zero if the function succeeds.  Otherwise, it is
2543 @code{-1} and @code{errno} is set accordingly.  @code{errno} values
2544 specific to this function are:
2545
2546 @table @code
2547 @item ENOMEM
2548 @itemize @bullet
2549 @item
2550 At least some of the specified address range does not exist in the
2551 calling process' virtual address space.
2552 @item
2553 The locking would cause the process to exceed its locked page limit.
2554 @end itemize
2555
2556 @item EPERM
2557 The calling process is not superuser.
2558
2559 @item EINVAL
2560 @var{len} is not positive.
2561
2562 @item ENOSYS
2563 The kernel does not provide @code{mlock} capability.
2564
2565 @end table
2566
2567 You can lock @emph{all} a process' memory with @code{mlockall}.  You
2568 unlock memory with @code{munlock} or @code{munlockall}.
2569
2570 To avoid all page faults in a C program, you have to use
2571 @code{mlockall}, because some of the memory a program uses is hidden
2572 from the C code, e.g. the stack and automatic variables, and you
2573 wouldn't know what address to tell @code{mlock}.
2574
2575 @end deftypefun
2576
2577 @comment sys/mman.h
2578 @comment POSIX.1b
2579 @deftypefun int munlock (const void *@var{addr}, size_t @var{len})
2580
2581 @code{munlock} unlocks a range of the calling process' virtual pages.
2582
2583 @code{munlock} is the inverse of @code{mlock} and functions completely
2584 analogously to @code{mlock}, except that there is no @code{EPERM}
2585 failure.
2586
2587 @end deftypefun
2588
2589 @comment sys/mman.h
2590 @comment POSIX.1b
2591 @deftypefun int mlockall (int @var{flags})
2592
2593 @code{mlockall} locks all the pages in a process' virtual memory address
2594 space, and/or any that are added to it in the future.  This includes the
2595 pages of the code, data and stack segment, as well as shared libraries,
2596 user space kernel data, shared memory, and memory mapped files.
2597
2598 @var{flags} is a string of single bit flags represented by the following
2599 macros.  They tell @code{mlockall} which of its functions you want.  All
2600 other bits must be zero.
2601
2602 @table @code
2603
2604 @item MCL_CURRENT
2605 Lock all pages which currently exist in the calling process' virtual
2606 address space.
2607
2608 @item MCL_FUTURE
2609 Set a mode such that any pages added to the process' virtual address
2610 space in the future will be locked from birth.  This mode does not
2611 affect future address spaces owned by the same process so exec, which
2612 replaces a process' address space, wipes out @code{MCL_FUTURE}.
2613 @xref{Executing a File}.
2614
2615 @end table
2616
2617 When the function returns successfully, and you specified
2618 @code{MCL_CURRENT}, all of the process' pages are backed by (connected
2619 to) real frames (they are resident) and are marked to stay that way.
2620 This means the function may cause page-ins and have to wait for them.
2621
2622 When the process is in @code{MCL_FUTURE} mode because it successfully
2623 executed this function and specified @code{MCL_CURRENT}, any system call
2624 by the process that requires space be added to its virtual address space
2625 fails with @code{errno} = @code{ENOMEM} if locking the additional space
2626 would cause the process to exceed its locked page limit.  In the case
2627 that the address space addition that can't be accommodated is stack
2628 expansion, the stack expansion fails and the kernel sends a
2629 @code{SIGSEGV} signal to the process.
2630
2631 When the function fails, it does not affect the lock status of any pages
2632 or the future locking mode.
2633
2634 The return value is zero if the function succeeds.  Otherwise, it is
2635 @code{-1} and @code{errno} is set accordingly.  @code{errno} values
2636 specific to this function are:
2637
2638 @table @code
2639 @item ENOMEM
2640 @itemize @bullet
2641 @item
2642 At least some of the specified address range does not exist in the
2643 calling process' virtual address space.
2644 @item
2645 The locking would cause the process to exceed its locked page limit.
2646 @end itemize
2647
2648 @item EPERM
2649 The calling process is not superuser.
2650
2651 @item EINVAL
2652 Undefined bits in @var{flags} are not zero.
2653
2654 @item ENOSYS
2655 The kernel does not provide @code{mlockall} capability.
2656
2657 @end table
2658
2659 You can lock just specific pages with @code{mlock}.  You unlock pages
2660 with @code{munlockall} and @code{munlock}.
2661
2662 @end deftypefun
2663
2664
2665 @comment sys/mman.h
2666 @comment POSIX.1b
2667 @deftypefun int munlockall (void)
2668
2669 @code{munlockall} unlocks every page in the calling process' virtual
2670 address space and turn off @code{MCL_FUTURE} future locking mode.
2671
2672 The return value is zero if the function succeeds.  Otherwise, it is
2673 @code{-1} and @code{errno} is set accordingly.  The only way this
2674 function can fail is for generic reasons that all functions and system
2675 calls can fail, so there are no specific @code{errno} values.
2676
2677 @end deftypefun
2678
2679
2680
2681
2682 @ignore
2683 @c This was never actually implemented.  -zw
2684 @node Relocating Allocator
2685 @section Relocating Allocator
2686
2687 @cindex relocating memory allocator
2688 Any system of dynamic memory allocation has overhead: the amount of
2689 space it uses is more than the amount the program asks for.  The
2690 @dfn{relocating memory allocator} achieves very low overhead by moving
2691 blocks in memory as necessary, on its own initiative.
2692
2693 @c @menu
2694 @c * Relocator Concepts::               How to understand relocating allocation.
2695 @c * Using Relocator::          Functions for relocating allocation.
2696 @c @end menu
2697
2698 @node Relocator Concepts
2699 @subsection Concepts of Relocating Allocation
2700
2701 @ifinfo
2702 The @dfn{relocating memory allocator} achieves very low overhead by
2703 moving blocks in memory as necessary, on its own initiative.
2704 @end ifinfo
2705
2706 When you allocate a block with @code{malloc}, the address of the block
2707 never changes unless you use @code{realloc} to change its size.  Thus,
2708 you can safely store the address in various places, temporarily or
2709 permanently, as you like.  This is not safe when you use the relocating
2710 memory allocator, because any and all relocatable blocks can move
2711 whenever you allocate memory in any fashion.  Even calling @code{malloc}
2712 or @code{realloc} can move the relocatable blocks.
2713
2714 @cindex handle
2715 For each relocatable block, you must make a @dfn{handle}---a pointer
2716 object in memory, designated to store the address of that block.  The
2717 relocating allocator knows where each block's handle is, and updates the
2718 address stored there whenever it moves the block, so that the handle
2719 always points to the block.  Each time you access the contents of the
2720 block, you should fetch its address anew from the handle.
2721
2722 To call any of the relocating allocator functions from a signal handler
2723 is almost certainly incorrect, because the signal could happen at any
2724 time and relocate all the blocks.  The only way to make this safe is to
2725 block the signal around any access to the contents of any relocatable
2726 block---not a convenient mode of operation.  @xref{Nonreentrancy}.
2727
2728 @node Using Relocator
2729 @subsection Allocating and Freeing Relocatable Blocks
2730
2731 @pindex malloc.h
2732 In the descriptions below, @var{handleptr} designates the address of the
2733 handle.  All the functions are declared in @file{malloc.h}; all are GNU
2734 extensions.
2735
2736 @comment malloc.h
2737 @comment GNU
2738 @c @deftypefun {void *} r_alloc (void **@var{handleptr}, size_t @var{size})
2739 This function allocates a relocatable block of size @var{size}.  It
2740 stores the block's address in @code{*@var{handleptr}} and returns
2741 a non-null pointer to indicate success.
2742
2743 If @code{r_alloc} can't get the space needed, it stores a null pointer
2744 in @code{*@var{handleptr}}, and returns a null pointer.
2745 @end deftypefun
2746
2747 @comment malloc.h
2748 @comment GNU
2749 @c @deftypefun void r_alloc_free (void **@var{handleptr})
2750 This function is the way to free a relocatable block.  It frees the
2751 block that @code{*@var{handleptr}} points to, and stores a null pointer
2752 in @code{*@var{handleptr}} to show it doesn't point to an allocated
2753 block any more.
2754 @end deftypefun
2755
2756 @comment malloc.h
2757 @comment GNU
2758 @c @deftypefun {void *} r_re_alloc (void **@var{handleptr}, size_t @var{size})
2759 The function @code{r_re_alloc} adjusts the size of the block that
2760 @code{*@var{handleptr}} points to, making it @var{size} bytes long.  It
2761 stores the address of the resized block in @code{*@var{handleptr}} and
2762 returns a non-null pointer to indicate success.
2763
2764 If enough memory is not available, this function returns a null pointer
2765 and does not modify @code{*@var{handleptr}}.
2766 @end deftypefun
2767 @end ignore
2768
2769
2770
2771
2772 @ignore
2773 @comment No longer available...
2774
2775 @comment @node Memory Warnings
2776 @comment @section Memory Usage Warnings
2777 @comment @cindex memory usage warnings
2778 @comment @cindex warnings of memory almost full
2779
2780 @pindex malloc.c
2781 You can ask for warnings as the program approaches running out of memory
2782 space, by calling @code{memory_warnings}.  This tells @code{malloc} to
2783 check memory usage every time it asks for more memory from the operating
2784 system.  This is a GNU extension declared in @file{malloc.h}.
2785
2786 @comment malloc.h
2787 @comment GNU
2788 @comment @deftypefun void memory_warnings (void *@var{start}, void (*@var{warn-func}) (const char *))
2789 Call this function to request warnings for nearing exhaustion of virtual
2790 memory.
2791
2792 The argument @var{start} says where data space begins, in memory.  The
2793 allocator compares this against the last address used and against the
2794 limit of data space, to determine the fraction of available memory in
2795 use.  If you supply zero for @var{start}, then a default value is used
2796 which is right in most circumstances.
2797
2798 For @var{warn-func}, supply a function that @code{malloc} can call to
2799 warn you.  It is called with a string (a warning message) as argument.
2800 Normally it ought to display the string for the user to read.
2801 @end deftypefun
2802
2803 The warnings come when memory becomes 75% full, when it becomes 85%
2804 full, and when it becomes 95% full.  Above 95% you get another warning
2805 each time memory usage increases.
2806
2807 @end ignore