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