2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
24 .TH MALLOPT 3 2012-04-18 "Linux" "Linux Programmer's Manual"
26 mallopt \- set memory allocation parameters
28 .B #include <malloc.h>
30 .BI "int mallopt(int " param ", int " value );
34 function adjusts parameters that control the behavior of the
35 memory-allocation functions (see
39 argument specifies the parameter to be modified, and
41 specifies the new value for that parameter.
43 The following values can be specified for
47 Setting this parameter controls how glibc responds when various kinds
48 of programming errors are detected (e.g., freeing the same pointer twice).
49 The 3 least significant bits (2, 1, and 0) of the value assigned
50 to this parameter determine the glibc behavior, as follows:
54 If this bit is set, then print a one-line message on
56 that provides details about the error.
57 The message starts with the string "***\ glibc detected\ ***",
58 followed by the program name,
59 the name of the memory-allocation function in which the error was detected,
60 a brief description of the error,
61 and the memory address where the error was detected.
64 If this bit is set, then,
65 after printing any error message specified by bit 0,
66 the program is terminated by calling
68 In glibc versions since 2.4,
70 then, between printing the error message and aborting,
71 the program also prints a stack trace in the manner of
73 and prints the process's memory mapping in the style of
78 Bit 2 (since glibc 2.4)
79 This bit has an effect only if bit 0 is also set.
81 then the one-line message describing the error is simplified
82 to contain just the name of the function where the error
83 was detected and the brief description of the error.
90 Combining the above details,
91 the following numeric values are meaningful for
95 Ignore error conditions; continue execution (with undefined results).
97 Print a detailed error message and continue execution.
101 Print detailed error message, stack trace, and memory mappings,
102 and abort the program.
104 Print a simple error message and continue execution.
106 Print simple error message, stack trace, and memory mappings,
107 and abort the program.
110 Since glibc 2.3.4, the default value for the
113 In glibc version 2.3.3 and earlier, the default value is 1.
117 value can be useful because otherwise a crash may happen much later,
118 and the true cause of the problem is then very hard to track down.
121 .\" The following text adapted from comments in the glibc source:
122 This parameter specifies the maximum number of allocation requests that
123 may be simultaneously serviced using
125 This parameter exists because some systems have a limited number
126 of internal tables for use by
128 and using more than a few of them may degrade performance.
130 The default value is 65,536,
131 a value which has no special significance and
132 which servers only as a safeguard.
133 Setting this parameter to 0 disables the use of
135 for servicing large allocation requests.
138 For allocations greater than or equal to the limit specified (in bytes) by
140 that can't be satisfied from the free list,
141 the memory-allocation functions employ
143 instead of increasing the program break using
146 Allocating memory using
148 has the significant advantage that the allocated memory blocks
149 can always be independently released back to the system.
151 the heap can be trimmed only if memory is freed at the top end.)
152 On the other hand, there are some disadvantages to the use of
154 deallocated space is not placed on the free list
155 for reuse by later allocations;
156 memory may be wasted because
158 allocations must be page-aligned;
159 and the kernel must perform the expensive task of zeroing out
162 Balancing these factors leads to a default setting of 128*1024 for the
166 The lower limit for this parameter is 0.
168 .BR DEFAULT_MMAP_THRESHOLD_MAX :
169 512*1024 on 32-bit systems or
170 .IR 4*1024*1024*sizeof(long)
174 Nowadays, glibc uses a dynamic mmap threshold by default.
175 The initial value of the threshold is 128*1024,
176 but when blocks larger than the current threshold and less than or equal to
177 .BR DEFAULT_MMAP_THRESHOLD_MAX
179 the threshold is adjusted upwards to the size of the freed block.
180 When dynamic mmap thresholding is in effect,
181 the threshold for trimming the heap is also dynamically adjusted
182 to be twice the dynamic mmap threshold.
183 Dynamic adjustment of the mmap threshold is disabled if any of the
184 .BR M_TRIM_THRESHOLD ,
186 .BR M_MMAP_THRESHOLD ,
191 .BR M_MXFAST " (since glibc 2.3)"
192 .\" The following text adapted from comments in the glibc sources:
193 Set the upper limit for memory allocation requests that are satisfied
195 (The measurement unit for this parameter is bytes.)
196 Fastbins are storage areas that hold deallocated blocks of memory
197 of the same size without merging adjacent free blocks.
198 Subsequent reallocation of blocks of the same size can be handled
199 very quickly by allocating from the fastbin,
200 although memory fragmentation and the overall memory footprint
201 of the program can increase.
202 The default value for this parameter is
203 .IR "64*sizeof(size_t)/4"
204 (i.e., 64 on 32-bit architectures).
205 The range for this parameter is 0 to
206 .IR "80*sizeof(size_t)/4" .
209 to 0 disables the use of fastbins.
211 .BR M_PERTURB " (since glibc 2.4)"
212 If this parameter is set to a nonzero value,
213 then bytes of allocated memory (other than allocations via
215 are initialized to the complement of the value
216 in the least significant byte of
218 and when allocated memory is released using
220 the freed bytes are set to the least significant byte of
222 This can be useful for detecting errors where programs
223 incorrectly rely on allocated memory being initialized to zero,
224 or reuse values in memory that has already been freed.
227 This parameter defines the amount of padding to employ when calling
229 to modify the program break.
230 (The measurement unit for this parameter is bytes.)
231 This parameter has an effect in the following circumstances:
234 When the program break is increased, then
236 bytes are added to the
240 When the heap is trimmed as a consequence of calling
242 (see the discussion of
243 .BR M_TRIM_THRESHOLD )
244 this much free space is preserved at the top of the heap.
248 the amount of padding is always rounded to a system page boundary.
252 is a trade-off between increasing the number of system calls
253 (when the parameter is set low)
254 and wasting unused memory at the top of the heap
255 (when the parameter is set high).
257 The default value for this parameter is 128*1024.
258 .\" DEFAULT_TOP_PAD in glibc source
261 When the amount of contiguous free memory at the top of the heap
262 grows sufficiently large,
266 to release this memory back to the system.
267 (This can be useful in programs that continue to execute for
268 a long period after freeing a significant amount of memory.)
271 parameter specifies the minimum size (in bytes) that
272 this block of memory must reach before
274 is used to trim the heap.
276 The default value for this parameter is 128*1024.
279 to \-1 disables trimming completely.
283 is a trade-off between increasing the number of system calls
284 (when the parameter is set low)
285 and wasting unused memory at the top of the heap
286 (when the parameter is set high).
287 .\" FIXME Do the arena parameters need to be documented?
289 .\" .BR M_ARENA_TEST " (since glibc 2.10)"
291 .\" .BR M_ARENA_MAX " (since glibc 2.10)"
293 .\" Environment variables
294 .\" MALLOC_ARENA_MAX_
295 .\" MALLOC_ARENA_TEST_
297 .\" http://udrepper.livejournal.com/20948.html describes some details
298 .\" of the MALLOC_ARENA_* environment variables.
300 .\" These macros aren't enabled in production releases until 2.15?
301 .\" (see glibc malloc/Makefile)
303 .SS Environment Variables
304 A number of environment variables can be defined
305 to modify some of the same parameters as are controlled by
307 Using these variables has the advantage that the source code
308 of the program need not be changed.
309 To be effective, these variables must be defined before the
310 first call to a memory-allocation function.
311 (If the same parameters are adjusted via
315 settings take precedence.)
316 For security reasons,
317 these variables are ignored in set-user-ID and set-group-ID programs.
319 The environment variables are as follows
320 (note the trailing underscore at the end of the name of each variable):
323 This environment variable controls the same parameter as
326 If this variable is set to a nonzero value,
327 then a special implementation of the memory-allocation functions is used.
328 (This is accomplished using the
331 This implementation performs additional error checking,
333 .\" On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower
334 .\" when MALLOC_CHECK_ was set.
335 than the standard set of memory-allocation functions.
336 (This implementation does not detect all possible errors;
337 memory leaks can still occur.)
339 The value assigned to this environment variable should be a single digit,
340 whose meaning is as described for
342 Any characters beyond the initial digit are ignored.
344 For security reasons, the effect of
346 is disabled by default for set-user-ID and set-group-ID programs.
349 exists (the content of the file is irrelevant), then
351 also has an effect for set-user-ID and set-group-ID programs.
354 Controls the same parameter as
358 .BR MALLOC_MMAP_THRESHOLD_
359 Controls the same parameter as
361 .BR M_MMAP_THRESHOLD .
364 Controls the same parameter as
368 .BR MALLOC_TRIM_THRESHOLD_
369 Controls the same parameter as
371 .BR M_TRIM_THRESHOLD .
374 Controls the same parameter as
381 On error, it returns 0.
389 .\" Available already in glibc 2.0, possibly earlier
391 This function is not specified by POSIX or the C standards.
392 A similar function exists on many System V derivatives,
393 but the range of values for
395 varies across systems.
396 The SVID defined options
402 but only the first of these is implemented in glibc.
405 Specifying an invalid value for
407 does not generate an error.
409 A calculation error within the glibc implementation means that
411 .\" FIXME This looks buggy:
412 .\" setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK)
413 .\" malloc requests are rounded up:
414 .\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK
415 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=12129
421 does not result in fastbins being employed for all allocations of size up to
423 To ensure desired results,
425 should be rounded up to the next multiple greater than or equal to
426 .IR (2k+1)*sizeof(size_t) ,
430 .\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t)
433 .BR MALLOC_MMAP_THRESHOLD_
438 ignored in set-group-ID programs.
439 .\" FIXME MALLOC_MMAP_THRESHOLD_ and MALLOC_MMAP_MAX_
440 .\" do have an effect for set-user-ID programs (but not
441 .\" set-group-ID programs).
442 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=12155
448 then, as expected, the bytes of allocated memory are initialized
449 to the complement of the byte in
451 and when that memory is freed,
452 the bytes of the region are initialized to the byte specified in
455 .RI off-by- sizeof(size_t)
456 error in the implementation:
457 .\" FIXME http://sources.redhat.com/bugzilla/show_bug.cgi?id=12140
458 instead of initializing precisely the block of memory
459 being freed by the call
461 the block starting at
465 The program below demonstrates the use of
467 If the program is supplied with an (integer) command-line argument,
468 then that argument is used to set the
471 The program then allocates a block of memory,
472 and frees it twice (an error).
474 The following shell session shows what happens when we run this program
475 under glibc, with the default value for
481 *** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 ***
482 ======= Backtrace: =========
483 /lib/libc.so.6(+0x6c501)[0x523501]
484 /lib/libc.so.6(+0x6dd70)[0x524d70]
485 /lib/libc.so.6(cfree+0x6d)[0x527e5d]
487 /lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]
489 ======= Memory map: ========
490 001e4000\-001fe000 r\-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1
491 001fe000\-001ff000 r\-\-p 00019000 08:06 1083555 /lib/libgcc_s.so.1
493 b7814000\-b7817000 rw\-p 00000000 00:00 0
494 bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack]
495 Aborted (core dumped)
499 The following runs show the results when employing other values for
504 $ \fB./a.out 1\fP # Diagnose error and continue
505 main(): returned from first free() call
506 *** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 ***
507 main(): returned from second free() call
508 $ \fB./a.out 2\fP # Abort without error message
509 main(): returned from first free() call
510 Aborted (core dumped)
511 $ \fB./a.out 0\fP # Ignore error and continue
512 main(): returned from first free() call
513 main(): returned from second free() call
517 The next run shows how to set the same parameter using the
519 environment variable:
523 $ \fBMALLOC_CHECK_=1 ./a.out\fP
524 main(): returned from first free() call
525 *** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***
526 main(): returned from second free() call
537 main(int argc, char *argv[])
543 fprintf(stderr, "%s <M_CHECK_ACTION\-value>\\n", argv[0]);
548 if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {
549 fprintf(stderr, "mallopt() failed");
555 fprintf(stderr, "malloc() failed");
560 printf("main(): returned from first free() call\\n");
563 printf("main(): returned from second free() call\\n");
579 .BR posix_memalign (3)