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