1MALLOPT(3) Linux Programmer's Manual MALLOPT(3)
2
6 mallopt - set memory allocation parameters
7
9 #include <malloc.h>
10 int mallopt(int param, int value);
12
14 The mallopt() function adjusts parameters that control the behavior of
15 the memory-allocation functions (see malloc(3)). The param argument
16 specifies the parameter to be modified, and value specifies the new
17 value for that parameter.
18 The following values can be specified for param:
20 M_CHECK_ACTION
22 Setting this parameter controls how glibc responds when various
23 kinds of programming errors are detected (e.g., freeing the same
24 pointer twice). The 3 least significant bits (2, 1, and 0) of
25 the value assigned to this parameter determine the glibc behav‐
26 ior, as follows:
27 Bit 0 If this bit is set, then print a one-line message on
29 stderr that provides details about the error. The mes‐
30 sage starts with the string "*** glibc detected ***",
31 followed by the program name, the name of the memory-
32 allocation function in which the error was detected, a
33 brief description of the error, and the memory address
34 where the error was detected.
35 Bit 1 If this bit is set, then, after printing any error mes‐
37 sage specified by bit 0, the program is terminated by
38 calling abort(3). In glibc versions since 2.4, if bit 0
39 is also set, then, between printing the error message and
40 aborting, the program also prints a stack trace in the
41 manner of backtrace(3), and prints the process's memory
42 mapping in the style of /proc/[pid]/maps (see proc(5)).
43 Bit 2 (since glibc 2.4)
45 This bit has an effect only if bit 0 is also set. If
46 this bit is set, then the one-line message describing the
47 error is simplified to contain just the name of the func‐
48 tion where the error was detected and the brief descrip‐
49 tion of the error.
50 The remaining bits in value are ignored.
52 Combining the above details, the following numeric values are
54 meaningful for M_CHECK_ACTION:
55 0 Ignore error conditions; continue execution (with unde‐
57 fined results).
58 1 Print a detailed error message and continue execution.
60 2 Abort the program.
62 3 Print detailed error message, stack trace, and memory
64 mappings, and abort the program.
65 5 Print a simple error message and continue execution.
67 7 Print simple error message, stack trace, and memory map‐
69 pings, and abort the program.
70 Since glibc 2.3.4, the default value for the M_CHECK_ACTION
72 parameter is 3. In glibc version 2.3.3 and earlier, the default
73 value is 1.
74 Using a nonzero M_CHECK_ACTION value can be useful because oth‐
76 erwise a crash may happen much later, and the true cause of the
77 problem is then very hard to track down.
78 M_MMAP_MAX
80 This parameter specifies the maximum number of allocation
81 requests that may be simultaneously serviced using mmap(2).
82 This parameter exists because some systems have a limited number
83 of internal tables for use by mmap(2), and using more than a few
84 of them may degrade performance.
85 The default value is 65,536, a value which has no special sig‐
87 nificance and which servers only as a safeguard. Setting this
88 parameter to 0 disables the use of mmap(2) for servicing large
89 allocation requests.
90 M_MMAP_THRESHOLD
92 For allocations greater than or equal to the limit specified (in
93 bytes) by M_MMAP_THRESHOLD that can't be satisfied from the free
94 list, the memory-allocation functions employ mmap(2) instead of
95 increasing the program break using sbrk(2).
96 Allocating memory using mmap(2) has the significant advantage
98 that the allocated memory blocks can always be independently
99 released back to the system. (By contrast, the heap can be
100 trimmed only if memory is freed at the top end.) On the other
101 hand, there are some disadvantages to the use of mmap(2): deal‐
102 located space is not placed on the free list for reuse by later
103 allocations; memory may be wasted because mmap(2) allocations
104 must be page-aligned; and the kernel must perform the expensive
105 task of zeroing out memory allocated via mmap(2). Balancing
106 these factors leads to a default setting of 128*1024 for the
107 M_MMAP_THRESHOLD parameter.
108 The lower limit for this parameter is 0. The upper limit is
110 DEFAULT_MMAP_THRESHOLD_MAX: 512*1024 on 32-bit systems or
111 4*1024*1024*sizeof(long) on 64-bit systems.
112 Note: Nowadays, glibc uses a dynamic mmap threshold by default.
114 The initial value of the threshold is 128*1024, but when blocks
115 larger than the current threshold and less than or equal to
116 DEFAULT_MMAP_THRESHOLD_MAX are freed, the threshold is adjusted
117 upwards to the size of the freed block. When dynamic mmap
118 thresholding is in effect, the threshold for trimming the heap
119 is also dynamically adjusted to be twice the dynamic mmap
120 threshold. Dynamic adjustment of the mmap threshold is disabled
121 if any of the M_TRIM_THRESHOLD, M_TOP_PAD, M_MMAP_THRESHOLD, or
122 M_MMAP_MAX parameters is set.
123 M_MXFAST (since glibc 2.3)
125 Set the upper limit for memory allocation requests that are sat‐
126 isfied using "fastbins". (The measurement unit for this parame‐
127 ter is bytes.) Fastbins are storage areas that hold deallocated
128 blocks of memory of the same size without merging adjacent free
129 blocks. Subsequent reallocation of blocks of the same size can
130 be handled very quickly by allocating from the fastbin, although
131 memory fragmentation and the overall memory footprint of the
132 program can increase. The default value for this parameter is
133 64*sizeof(size_t)/4 (i.e., 64 on 32-bit architectures). The
134 range for this parameter is 0 to 80*sizeof(size_t)/4. Setting
135 M_MXFAST to 0 disables the use of fastbins.
136 M_PERTURB (since glibc 2.4)
138 If this parameter is set to a nonzero value, then bytes of allo‐
139 cated memory (other than allocations via calloc(3)) are initial‐
140 ized to the complement of the value in the least significant
141 byte of value, and when allocated memory is released using
142 free(3), the freed bytes are set to the least significant byte
143 of value. This can be useful for detecting errors where pro‐
144 grams incorrectly rely on allocated memory being initialized to
145 zero, or reuse values in memory that has already been freed.
146 M_TOP_PAD
148 This parameter defines the amount of padding to employ when
149 calling sbrk(2) to modify the program break. (The measurement
150 unit for this parameter is bytes.) This parameter has an effect
151 in the following circumstances:
152 * When the program break is increased, then M_TOP_PAD bytes are
154 added to the sbrk(2) request.
155 * When the heap is trimmed as a consequence of calling free(3)
157 (see the discussion of M_TRIM_THRESHOLD) this much free space
158 is preserved at the top of the heap.
159 In either case, the amount of padding is always rounded to a
161 system page boundary.
162 Modifying M_TOP_PAD is a trade-off between increasing the number
164 of system calls (when the parameter is set low) and wasting
165 unused memory at the top of the heap (when the parameter is set
166 high).
167 The default value for this parameter is 128*1024.
169 M_TRIM_THRESHOLD
171 When the amount of contiguous free memory at the top of the heap
172 grows sufficiently large, free(3) employs sbrk(2) to release
173 this memory back to the system. (This can be useful in programs
174 that continue to execute for a long period after freeing a sig‐
175 nificant amount of memory.) The M_TRIM_THRESHOLD parameter
176 specifies the minimum size (in bytes) that this block of memory
177 must reach before sbrk(2) is used to trim the heap.
178 The default value for this parameter is 128*1024. Setting
180 M_TRIM_THRESHOLD to -1 disables trimming completely.
181 Modifying M_TRIM_THRESHOLD is a trade-off between increasing the
183 number of system calls (when the parameter is set low) and wast‐
184 ing unused memory at the top of the heap (when the parameter is
185 set high).
186 Environment variables
188 A number of environment variables can be defined to modify some of the
189 same parameters as are controlled by mallopt(). Using these variables
190 has the advantage that the source code of the program need not be
191 changed. To be effective, these variables must be defined before the
192 first call to a memory-allocation function. (If the same parameters
193 are adjusted via mallopt() then the mallopt() settings take prece‐
194 dence.) For security reasons, these variables are ignored in set-user-
195 ID and set-group-ID programs.
196 The environment variables are as follows (note the trailing underscore
198 at the end of the name of each variable):
199 MALLOC_CHECK_
201 This environment variable controls the same parameter as mal‐
202 lopt() M_CHECK_ACTION. If this variable is set to a nonzero
203 value, then a special implementation of the memory-allocation
204 functions is used. (This is accomplished using the mal‐
205 loc_hook(3) feature.) This implementation performs additional
206 error checking, but is slower than the standard set of memory-
207 allocation functions. (This implementation does not detect all
208 possible errors; memory leaks can still occur.)
209 The value assigned to this environment variable should be a sin‐
211 gle digit, whose meaning is as described for M_CHECK_ACTION.
212 Any characters beyond the initial digit are ignored.
213 For security reasons, the effect of MALLOC_CHECK_ is disabled by
215 default for set-user-ID and set-group-ID programs. However, if
216 the file /etc/suid-debug exists (the content of the file is
217 irrelevant), then MALLOC_CHECK_ also has an effect for set-user-
218 ID and set-group-ID programs.
219 MALLOC_MMAP_MAX_
221 Controls the same parameter as mallopt() M_MMAP_MAX.
222 MALLOC_MMAP_THRESHOLD_
224 Controls the same parameter as mallopt() M_MMAP_THRESHOLD.
225 MALLOC_PERTURB_
227 Controls the same parameter as mallopt() M_PERTURB.
228 MALLOC_TRIM_THRESHOLD_
230 Controls the same parameter as mallopt() M_TRIM_THRESHOLD.
231 MALLOC_TOP_PAD_
233 Controls the same parameter as mallopt() M_TOP_PAD.
234
236 On success, mallopt() returns 1. On error, it returns 0.
237
239 On error, errno is not set.
240
242 This function is not specified by POSIX or the C standards. A similar
243 function exists on many System V derivatives, but the range of values
244 for param varies across systems. The SVID defined options M_MXFAST,
245 M_NLBLKS, M_GRAIN, and M_KEEP, but only the first of these is imple‐
246 mented in glibc.
247
249 Specifying an invalid value for param does not generate an error.
250 A calculation error within the glibc implementation means that a call
252 of the form:
253 mallopt(M_MXFAST, n)
255 does not result in fastbins being employed for all allocations of size
257 up to n. To ensure desired results, n should be rounded up to the next
258 multiple greater than or equal to (2k+1)*sizeof(size_t), where k is an
259 integer.
260 The MALLOC_MMAP_THRESHOLD_ and MALLOC_MMAP_MAX_ variables are not
262 ignored in set-group-ID programs.
263 If mallopt() is used to set M_PERTURB, then, as expected, the bytes of
265 allocated memory are initialized to the complement of the byte in
266 value, and when that memory is freed, the bytes of the region are ini‐
267 tialized to the byte specified in value. However, there is an off-by-
268 sizeof(size_t) error in the implementation: instead of initializing
269 precisely the block of memory being freed by the call free(p), the
270 block starting at p+sizeof(size_t) is initialized.
271
273 The program below demonstrates the use of M_CHECK_ACTION. If the pro‐
274 gram is supplied with an (integer) command-line argument, then that
275 argument is used to set the M_CHECK_ACTION parameter. The program then
276 allocates a block of memory, and frees it twice (an error).
277 The following shell session shows what happens when we run this program
279 under glibc, with the default value for M_CHECK_ACTION:
280 $ ./a.out
282 main(): returned from first free() call
283 *** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 ***
284 ======= Backtrace: =========
285 /lib/libc.so.6(+0x6c501)[0x523501]
286 /lib/libc.so.6(+0x6dd70)[0x524d70]
287 /lib/libc.so.6(cfree+0x6d)[0x527e5d]
288 ./a.out[0x80485db]
289 /lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]
290 ./a.out[0x8048471]
291 ======= Memory map: ========
292 001e4000-001fe000 r-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1
293 001fe000-001ff000 r--p 00019000 08:06 1083555 /lib/libgcc_s.so.1
294 [some lines omitted]
295 b7814000-b7817000 rw-p 00000000 00:00 0
296 bff53000-bff74000 rw-p 00000000 00:00 0 [stack]
297 Aborted (core dumped)
298 The following runs show the results when employing other values for
300 M_CHECK_ACTION:
301 $ ./a.out 1 # Diagnose error and continue
303 main(): returned from first free() call
304 *** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 ***
305 main(): returned from second free() call
306 $ ./a.out 2 # Abort without error message
307 main(): returned from first free() call
308 Aborted (core dumped)
309 $ ./a.out 0 # Ignore error and continue
310 main(): returned from first free() call
311 main(): returned from second free() call
312 The next run shows how to set the same parameter using the MAL‐
314 LOC_CHECK_ environment variable:
315 $ MALLOC_CHECK_=1 ./a.out
317 main(): returned from first free() call
318 *** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***
319 main(): returned from second free() call
320 Program source
322 #include <malloc.h>
324 #include <stdio.h>
325 #include <stdlib.h>
326 int
328 main(int argc, char *argv[])
329 {
330 char *p;
331 if (argc > 1) {
333 if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {
334 fprintf(stderr, "mallopt() failed");
335 exit(EXIT_FAILURE);
336 }
337 }
338 p = malloc(1000);
340 if (p == NULL) {
341 fprintf(stderr, "malloc() failed");
342 exit(EXIT_FAILURE);
343 }
344 free(p);
346 printf("main(): returned from first free() call\n");
347 free(p);
349 printf("main(): returned from second free() call\n");
350 exit(EXIT_SUCCESS);
352 }
353
355 mmap(2), sbrk(2), mallinfo(3), malloc(3), malloc_hook(3),
356 malloc_info(3), malloc_stats(3), malloc_trim(3), mcheck(3), mtrace(3),
357 posix_memalign(3)
358
360 This page is part of release 3.53 of the Linux man-pages project. A
361 description of the project, and information about reporting bugs, can
362 be found at http://www.kernel.org/doc/man-pages/.
363Linux 2012-04-30 MALLOPT(3)