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