2 .\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH MALLOPT 3 2014-07-08 "Linux" "Linux Programmer's Manual"
28 mallopt \- set memory allocation parameters
30 .B #include <malloc.h>
32 .BI "int mallopt(int " param ", int " value );
36 function adjusts parameters that control the behavior of the
37 memory-allocation functions (see
41 argument specifies the parameter to be modified, and
43 specifies the new value for that parameter.
45 The following values can be specified for
49 Setting this parameter controls how glibc responds when various kinds
50 of programming errors are detected (e.g., freeing the same pointer twice).
51 The 3 least significant bits (2, 1, and 0) of the value assigned
52 to this parameter determine the glibc behavior, as follows:
56 If this bit is set, then print a one-line message on
58 that provides details about the error.
59 The message starts with the string "***\ glibc detected\ ***",
60 followed by the program name,
61 the name of the memory-allocation function in which the error was detected,
62 a brief description of the error,
63 and the memory address where the error was detected.
66 If this bit is set, then,
67 after printing any error message specified by bit 0,
68 the program is terminated by calling
70 In glibc versions since 2.4,
72 then, between printing the error message and aborting,
73 the program also prints a stack trace in the manner of
75 and prints the process's memory mapping in the style of
80 Bit 2 (since glibc 2.4)
81 This bit has an effect only if bit 0 is also set.
83 then the one-line message describing the error is simplified
84 to contain just the name of the function where the error
85 was detected and the brief description of the error.
92 Combining the above details,
93 the following numeric values are meaningful for
97 Ignore error conditions; continue execution (with undefined results).
99 Print a detailed error message and continue execution.
103 Print detailed error message, stack trace, and memory mappings,
104 and abort the program.
106 Print a simple error message and continue execution.
108 Print simple error message, stack trace, and memory mappings,
109 and abort the program.
112 Since glibc 2.3.4, the default value for the
115 In glibc version 2.3.3 and earlier, the default value is 1.
119 value can be useful because otherwise a crash may happen much later,
120 and the true cause of the problem is then very hard to track down.
123 .\" The following text adapted from comments in the glibc source:
124 This parameter specifies the maximum number of allocation requests that
125 may be simultaneously serviced using
127 This parameter exists because some systems have a limited number
128 of internal tables for use by
130 and using more than a few of them may degrade performance.
132 The default value is 65,536,
133 a value which has no special significance and
134 which servers only as a safeguard.
135 Setting this parameter to 0 disables the use of
137 for servicing large allocation requests.
140 For allocations greater than or equal to the limit specified (in bytes) by
142 that can't be satisfied from the free list,
143 the memory-allocation functions employ
145 instead of increasing the program break using
148 Allocating memory using
150 has the significant advantage that the allocated memory blocks
151 can always be independently released back to the system.
153 the heap can be trimmed only if memory is freed at the top end.)
154 On the other hand, there are some disadvantages to the use of
156 deallocated space is not placed on the free list
157 for reuse by later allocations;
158 memory may be wasted because
160 allocations must be page-aligned;
161 and the kernel must perform the expensive task of zeroing out
164 Balancing these factors leads to a default setting of 128*1024 for the
168 The lower limit for this parameter is 0.
170 .BR DEFAULT_MMAP_THRESHOLD_MAX :
171 512*1024 on 32-bit systems or
172 .IR 4*1024*1024*sizeof(long)
176 Nowadays, glibc uses a dynamic mmap threshold by default.
177 The initial value of the threshold is 128*1024,
178 but when blocks larger than the current threshold and less than or equal to
179 .BR DEFAULT_MMAP_THRESHOLD_MAX
181 the threshold is adjusted upward to the size of the freed block.
182 When dynamic mmap thresholding is in effect,
183 the threshold for trimming the heap is also dynamically adjusted
184 to be twice the dynamic mmap threshold.
185 Dynamic adjustment of the mmap threshold is disabled if any of the
186 .BR M_TRIM_THRESHOLD ,
188 .BR M_MMAP_THRESHOLD ,
193 .BR M_MXFAST " (since glibc 2.3)"
194 .\" The following text adapted from comments in the glibc sources:
195 Set the upper limit for memory allocation requests that are satisfied
197 (The measurement unit for this parameter is bytes.)
198 Fastbins are storage areas that hold deallocated blocks of memory
199 of the same size without merging adjacent free blocks.
200 Subsequent reallocation of blocks of the same size can be handled
201 very quickly by allocating from the fastbin,
202 although memory fragmentation and the overall memory footprint
203 of the program can increase.
204 The default value for this parameter is
205 .IR "64*sizeof(size_t)/4"
206 (i.e., 64 on 32-bit architectures).
207 The range for this parameter is 0 to
208 .IR "80*sizeof(size_t)/4" .
211 to 0 disables the use of fastbins.
213 .BR M_PERTURB " (since glibc 2.4)"
214 If this parameter is set to a nonzero value,
215 then bytes of allocated memory (other than allocations via
217 are initialized to the complement of the value
218 in the least significant byte of
220 and when allocated memory is released using
222 the freed bytes are set to the least significant byte of
224 This can be useful for detecting errors where programs
225 incorrectly rely on allocated memory being initialized to zero,
226 or reuse values in memory that has already been freed.
229 This parameter defines the amount of padding to employ when calling
231 to modify the program break.
232 (The measurement unit for this parameter is bytes.)
233 This parameter has an effect in the following circumstances:
236 When the program break is increased, then
238 bytes are added to the
242 When the heap is trimmed as a consequence of calling
244 (see the discussion of
245 .BR M_TRIM_THRESHOLD )
246 this much free space is preserved at the top of the heap.
250 the amount of padding is always rounded to a system page boundary.
254 is a trade-off between increasing the number of system calls
255 (when the parameter is set low)
256 and wasting unused memory at the top of the heap
257 (when the parameter is set high).
259 The default value for this parameter is 128*1024.
260 .\" DEFAULT_TOP_PAD in glibc source
263 When the amount of contiguous free memory at the top of the heap
264 grows sufficiently large,
268 to release this memory back to the system.
269 (This can be useful in programs that continue to execute for
270 a long period after freeing a significant amount of memory.)
273 parameter specifies the minimum size (in bytes) that
274 this block of memory must reach before
276 is used to trim the heap.
278 The default value for this parameter is 128*1024.
281 to \-1 disables trimming completely.
285 is a trade-off between increasing the number of system calls
286 (when the parameter is set low)
287 and wasting unused memory at the top of the heap
288 (when the parameter is set high).
289 .\" FIXME Do the arena parameters need to be documented?
291 .\" .BR M_ARENA_TEST " (since glibc 2.10)"
293 .\" .BR M_ARENA_MAX " (since glibc 2.10)"
295 .\" Environment variables
296 .\" MALLOC_ARENA_MAX_
297 .\" MALLOC_ARENA_TEST_
299 .\" http://udrepper.livejournal.com/20948.html describes some details
300 .\" of the MALLOC_ARENA_* environment variables.
302 .\" These macros aren't enabled in production releases until 2.15?
303 .\" (see glibc malloc/Makefile)
305 .SS Environment variables
306 A number of environment variables can be defined
307 to modify some of the same parameters as are controlled by
309 Using these variables has the advantage that the source code
310 of the program need not be changed.
311 To be effective, these variables must be defined before the
312 first call to a memory-allocation function.
313 (If the same parameters are adjusted via
317 settings take precedence.)
318 For security reasons,
319 these variables are ignored in set-user-ID and set-group-ID programs.
321 The environment variables are as follows
322 (note the trailing underscore at the end of the name of each variable):
325 This environment variable controls the same parameter as
328 If this variable is set to a nonzero value,
329 then a special implementation of the memory-allocation functions is used.
330 (This is accomplished using the
333 This implementation performs additional error checking,
335 .\" On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower
336 .\" when MALLOC_CHECK_ was set.
337 than the standard set of memory-allocation functions.
338 (This implementation does not detect all possible errors;
339 memory leaks can still occur.)
341 The value assigned to this environment variable should be a single digit,
342 whose meaning is as described for
344 Any characters beyond the initial digit are ignored.
346 For security reasons, the effect of
348 is disabled by default for set-user-ID and set-group-ID programs.
351 exists (the content of the file is irrelevant), then
353 also has an effect for set-user-ID and set-group-ID programs.
356 Controls the same parameter as
360 .BR MALLOC_MMAP_THRESHOLD_
361 Controls the same parameter as
363 .BR M_MMAP_THRESHOLD .
366 Controls the same parameter as
370 .BR MALLOC_TRIM_THRESHOLD_
371 Controls the same parameter as
373 .BR M_TRIM_THRESHOLD .
376 Controls the same parameter as
383 On error, it returns 0.
391 .\" Available already in glibc 2.0, possibly earlier
393 This function is not specified by POSIX or the C standards.
394 A similar function exists on many System V derivatives,
395 but the range of values for
397 varies across systems.
398 The SVID defined options
404 but only the first of these is implemented in glibc.
407 Specifying an invalid value for
409 does not generate an error.
411 A calculation error within the glibc implementation means that
413 .\" FIXME . This looks buggy:
414 .\" setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK)
415 .\" malloc requests are rounded up:
416 .\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK
417 .\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=12129
423 does not result in fastbins being employed for all allocations of size up to
425 To ensure desired results,
427 should be rounded up to the next multiple greater than or equal to
428 .IR (2k+1)*sizeof(size_t) ,
432 .\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t)
438 then, as expected, the bytes of allocated memory are initialized
439 to the complement of the byte in
441 and when that memory is freed,
442 the bytes of the region are initialized to the byte specified in
445 .RI off-by- sizeof(size_t)
446 error in the implementation:
447 .\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12140
448 instead of initializing precisely the block of memory
449 being freed by the call
451 the block starting at
455 The program below demonstrates the use of
457 If the program is supplied with an (integer) command-line argument,
458 then that argument is used to set the
461 The program then allocates a block of memory,
462 and frees it twice (an error).
464 The following shell session shows what happens when we run this program
465 under glibc, with the default value for
471 main(): returned from first free() call
472 *** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 ***
473 ======= Backtrace: =========
474 /lib/libc.so.6(+0x6c501)[0x523501]
475 /lib/libc.so.6(+0x6dd70)[0x524d70]
476 /lib/libc.so.6(cfree+0x6d)[0x527e5d]
478 /lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]
480 ======= Memory map: ========
481 001e4000\-001fe000 r\-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1
482 001fe000\-001ff000 r\-\-p 00019000 08:06 1083555 /lib/libgcc_s.so.1
484 b7814000\-b7817000 rw\-p 00000000 00:00 0
485 bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack]
486 Aborted (core dumped)
490 The following runs show the results when employing other values for
495 $ \fB./a.out 1\fP # Diagnose error and continue
496 main(): returned from first free() call
497 *** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 ***
498 main(): returned from second free() call
499 $ \fB./a.out 2\fP # Abort without error message
500 main(): returned from first free() call
501 Aborted (core dumped)
502 $ \fB./a.out 0\fP # Ignore error and continue
503 main(): returned from first free() call
504 main(): returned from second free() call
508 The next run shows how to set the same parameter using the
510 environment variable:
514 $ \fBMALLOC_CHECK_=1 ./a.out\fP
515 main(): returned from first free() call
516 *** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***
517 main(): returned from second free() call
528 main(int argc, char *argv[])
533 if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {
534 fprintf(stderr, "mallopt() failed");
541 fprintf(stderr, "malloc() failed");
546 printf("main(): returned from first free() call\\n");
549 printf("main(): returned from second free() call\\n");
563 .BR malloc_stats (3),
567 .BR posix_memalign (3)