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