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_ARENA_MAX
22 If this parameter has a nonzero value, it defines a hard limit
23 on the maximum number of arenas that can be created. An arena
24 represents a pool of memory that can be used by malloc(3) (and
25 similar) calls to service allocation requests. Arenas are
26 thread safe and therefore may have multiple concurrent memory
27 requests. The trade-off is between the number of threads and
28 the number of arenas. The more arenas you have, the lower the
29 per-thread contention, but the higher the memory usage.
30 The default value of this parameter is 0, meaning that the limit
32 on the number of arenas is determined according to the setting
33 of M_ARENA_TEST.
34 This parameter has been available since glibc 2.10 via --en‐
36 able-experimental-malloc, and since glibc 2.15 by default. In
37 some versions of the allocator there was no limit on the number
38 of created arenas (e.g., CentOS 5, RHEL 5).
39 When employing newer glibc versions, applications may in some
41 cases exhibit high contention when accessing arenas. In these
42 cases, it may be beneficial to increase M_ARENA_MAX to match the
43 number of threads. This is similar in behavior to strategies
44 taken by tcmalloc and jemalloc (e.g., per-thread allocation
45 pools).
46 M_ARENA_TEST
48 This parameter specifies a value, in number of arenas created,
49 at which point the system configuration will be examined to de‐
50 termine a hard limit on the number of created arenas. (See
51 M_ARENA_MAX for the definition of an arena.)
52 The computation of the arena hard limit is implementation-de‐
54 fined and is usually calculated as a multiple of the number of
55 available CPUs. Once the hard limit is computed, the result is
56 final and constrains the total number of arenas.
57 The default value for the M_ARENA_TEST parameter is 2 on systems
59 where sizeof(long) is 4; otherwise the default value is 8.
60 This parameter has been available since glibc 2.10 via --en‐
62 able-experimental-malloc, and since glibc 2.15 by default.
63 The value of M_ARENA_TEST is not used when M_ARENA_MAX has a
65 nonzero value.
66 M_CHECK_ACTION
68 Setting this parameter controls how glibc responds when various
69 kinds of programming errors are detected (e.g., freeing the same
70 pointer twice). The 3 least significant bits (2, 1, and 0) of
71 the value assigned to this parameter determine the glibc behav‐
72 ior, as follows:
73 Bit 0 If this bit is set, then print a one-line message on
75 stderr that provides details about the error. The mes‐
76 sage starts with the string "*** glibc detected ***",
77 followed by the program name, the name of the memory-al‐
78 location function in which the error was detected, a
79 brief description of the error, and the memory address
80 where the error was detected.
81 Bit 1 If this bit is set, then, after printing any error mes‐
83 sage specified by bit 0, the program is terminated by
84 calling abort(3). In glibc versions since 2.4, if bit 0
85 is also set, then, between printing the error message and
86 aborting, the program also prints a stack trace in the
87 manner of backtrace(3), and prints the process's memory
88 mapping in the style of /proc/[pid]/maps (see proc(5)).
89 Bit 2 (since glibc 2.4)
91 This bit has an effect only if bit 0 is also set. If
92 this bit is set, then the one-line message describing the
93 error is simplified to contain just the name of the func‐
94 tion where the error was detected and the brief descrip‐
95 tion of the error.
96 The remaining bits in value are ignored.
98 Combining the above details, the following numeric values are
100 meaningful for M_CHECK_ACTION:
101 0 Ignore error conditions; continue execution (with unde‐
103 fined results).
104 1 Print a detailed error message and continue execution.
106 2 Abort the program.
108 3 Print detailed error message, stack trace, and memory
110 mappings, and abort the program.
111 5 Print a simple error message and continue execution.
113 7 Print simple error message, stack trace, and memory map‐
115 pings, and abort the program.
116 Since glibc 2.3.4, the default value for the M_CHECK_ACTION pa‐
118 rameter is 3. In glibc version 2.3.3 and earlier, the default
119 value is 1.
120 Using a nonzero M_CHECK_ACTION value can be useful because oth‐
122 erwise a crash may happen much later, and the true cause of the
123 problem is then very hard to track down.
124 M_MMAP_MAX
126 This parameter specifies the maximum number of allocation re‐
127 quests that may be simultaneously serviced using mmap(2). This
128 parameter exists because some systems have a limited number of
129 internal tables for use by mmap(2), and using more than a few of
130 them may degrade performance.
131 The default value is 65,536, a value which has no special sig‐
133 nificance and which serves only as a safeguard. Setting this
134 parameter to 0 disables the use of mmap(2) for servicing large
135 allocation requests.
136 M_MMAP_THRESHOLD
138 For allocations greater than or equal to the limit specified (in
139 bytes) by M_MMAP_THRESHOLD that can't be satisfied from the free
140 list, the memory-allocation functions employ mmap(2) instead of
141 increasing the program break using sbrk(2).
142 Allocating memory using mmap(2) has the significant advantage
144 that the allocated memory blocks can always be independently re‐
145 leased back to the system. (By contrast, the heap can be
146 trimmed only if memory is freed at the top end.) On the other
147 hand, there are some disadvantages to the use of mmap(2): de‐
148 allocated space is not placed on the free list for reuse by
149 later allocations; memory may be wasted because mmap(2) alloca‐
150 tions must be page-aligned; and the kernel must perform the ex‐
151 pensive task of zeroing out memory allocated via mmap(2). Bal‐
152 ancing these factors leads to a default setting of 128*1024 for
153 the M_MMAP_THRESHOLD parameter.
154 The lower limit for this parameter is 0. The upper limit is DE‐
156 FAULT_MMAP_THRESHOLD_MAX: 512*1024 on 32-bit systems or
157 4*1024*1024*sizeof(long) on 64-bit systems.
158 Note: Nowadays, glibc uses a dynamic mmap threshold by default.
160 The initial value of the threshold is 128*1024, but when blocks
161 larger than the current threshold and less than or equal to DE‐
162 FAULT_MMAP_THRESHOLD_MAX are freed, the threshold is adjusted
163 upward to the size of the freed block. When dynamic mmap
164 thresholding is in effect, the threshold for trimming the heap
165 is also dynamically adjusted to be twice the dynamic mmap
166 threshold. Dynamic adjustment of the mmap threshold is disabled
167 if any of the M_TRIM_THRESHOLD, M_TOP_PAD, M_MMAP_THRESHOLD, or
168 M_MMAP_MAX parameters is set.
169 M_MXFAST (since glibc 2.3)
171 Set the upper limit for memory allocation requests that are sat‐
172 isfied using "fastbins". (The measurement unit for this parame‐
173 ter is bytes.) Fastbins are storage areas that hold deallocated
174 blocks of memory of the same size without merging adjacent free
175 blocks. Subsequent reallocation of blocks of the same size can
176 be handled very quickly by allocating from the fastbin, although
177 memory fragmentation and the overall memory footprint of the
178 program can increase.
179 The default value for this parameter is 64*sizeof(size_t)/4
181 (i.e., 64 on 32-bit architectures). The range for this parame‐
182 ter is 0 to 80*sizeof(size_t)/4. Setting M_MXFAST to 0 disables
183 the use of fastbins.
184 M_PERTURB (since glibc 2.4)
186 If this parameter is set to a nonzero value, then bytes of allo‐
187 cated memory (other than allocations via calloc(3)) are initial‐
188 ized to the complement of the value in the least significant
189 byte of value, and when allocated memory is released using
190 free(3), the freed bytes are set to the least significant byte
191 of value. This can be useful for detecting errors where pro‐
192 grams incorrectly rely on allocated memory being initialized to
193 zero, or reuse values in memory that has already been freed.
194 The default value for this parameter is 0.
196 M_TOP_PAD
198 This parameter defines the amount of padding to employ when
199 calling sbrk(2) to modify the program break. (The measurement
200 unit for this parameter is bytes.) This parameter has an effect
201 in the following circumstances:
202 * When the program break is increased, then M_TOP_PAD bytes are
204 added to the sbrk(2) request.
205 * When the heap is trimmed as a consequence of calling free(3)
207 (see the discussion of M_TRIM_THRESHOLD) this much free space
208 is preserved at the top of the heap.
209 In either case, the amount of padding is always rounded to a
211 system page boundary.
212 Modifying M_TOP_PAD is a trade-off between increasing the number
214 of system calls (when the parameter is set low) and wasting un‐
215 used memory at the top of the heap (when the parameter is set
216 high).
217 The default value for this parameter is 128*1024.
219 M_TRIM_THRESHOLD
221 When the amount of contiguous free memory at the top of the heap
222 grows sufficiently large, free(3) employs sbrk(2) to release
223 this memory back to the system. (This can be useful in programs
224 that continue to execute for a long period after freeing a sig‐
225 nificant amount of memory.) The M_TRIM_THRESHOLD parameter
226 specifies the minimum size (in bytes) that this block of memory
227 must reach before sbrk(2) is used to trim the heap.
228 The default value for this parameter is 128*1024. Setting
230 M_TRIM_THRESHOLD to -1 disables trimming completely.
231 Modifying M_TRIM_THRESHOLD is a trade-off between increasing the
233 number of system calls (when the parameter is set low) and wast‐
234 ing unused memory at the top of the heap (when the parameter is
235 set high).
236 Environment variables
238 A number of environment variables can be defined to modify some of the
239 same parameters as are controlled by mallopt(). Using these variables
240 has the advantage that the source code of the program need not be
241 changed. To be effective, these variables must be defined before the
242 first call to a memory-allocation function. (If the same parameters
243 are adjusted via mallopt(), then the mallopt() settings take prece‐
244 dence.) For security reasons, these variables are ignored in set-user-
245 ID and set-group-ID programs.
246 The environment variables are as follows (note the trailing underscore
248 at the end of the name of some variables):
249 MALLOC_ARENA_MAX
251 Controls the same parameter as mallopt() M_ARENA_MAX.
252 MALLOC_ARENA_TEST
254 Controls the same parameter as mallopt() M_ARENA_TEST.
255 MALLOC_CHECK_
257 This environment variable controls the same parameter as mal‐
258 lopt() M_CHECK_ACTION. If this variable is set to a nonzero
259 value, then a special implementation of the memory-allocation
260 functions is used. (This is accomplished using the mal‐
261 loc_hook(3) feature.) This implementation performs additional
262 error checking, but is slower than the standard set of memory-
263 allocation functions. (This implementation does not detect all
264 possible errors; memory leaks can still occur.)
265 The value assigned to this environment variable should be a sin‐
267 gle digit, whose meaning is as described for M_CHECK_ACTION.
268 Any characters beyond the initial digit are ignored.
269 For security reasons, the effect of MALLOC_CHECK_ is disabled by
271 default for set-user-ID and set-group-ID programs. However, if
272 the file /etc/suid-debug exists (the content of the file is ir‐
273 relevant), then MALLOC_CHECK_ also has an effect for set-user-ID
274 and set-group-ID programs.
275 MALLOC_MMAP_MAX_
277 Controls the same parameter as mallopt() M_MMAP_MAX.
278 MALLOC_MMAP_THRESHOLD_
280 Controls the same parameter as mallopt() M_MMAP_THRESHOLD.
281 MALLOC_PERTURB_
283 Controls the same parameter as mallopt() M_PERTURB.
284 MALLOC_TRIM_THRESHOLD_
286 Controls the same parameter as mallopt() M_TRIM_THRESHOLD.
287 MALLOC_TOP_PAD_
289 Controls the same parameter as mallopt() M_TOP_PAD.
290
292 On success, mallopt() returns 1. On error, it returns 0.
293
295 On error, errno is not set.
296
298 This function is not specified by POSIX or the C standards. A similar
299 function exists on many System V derivatives, but the range of values
300 for param varies across systems. The SVID defined options M_MXFAST,
301 M_NLBLKS, M_GRAIN, and M_KEEP, but only the first of these is imple‐
302 mented in glibc.
303
305 Specifying an invalid value for param does not generate an error.
306 A calculation error within the glibc implementation means that a call
308 of the form:
309 mallopt(M_MXFAST, n)
311 does not result in fastbins being employed for all allocations of size
313 up to n. To ensure desired results, n should be rounded up to the next
314 multiple greater than or equal to (2k+1)*sizeof(size_t), where k is an
315 integer.
316 If mallopt() is used to set M_PERTURB, then, as expected, the bytes of
318 allocated memory are initialized to the complement of the byte in
319 value, and when that memory is freed, the bytes of the region are ini‐
320 tialized to the byte specified in value. However, there is an off-by-
321 sizeof(size_t) error in the implementation: instead of initializing
322 precisely the block of memory being freed by the call free(p), the
323 block starting at p+sizeof(size_t) is initialized.
324
326 The program below demonstrates the use of M_CHECK_ACTION. If the pro‐
327 gram is supplied with an (integer) command-line argument, then that ar‐
328 gument is used to set the M_CHECK_ACTION parameter. The program then
329 allocates a block of memory, and frees it twice (an error).
330 The following shell session shows what happens when we run this program
332 under glibc, with the default value for M_CHECK_ACTION:
333 $ ./a.out
335 main(): returned from first free() call
336 *** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 ***
337 ======= Backtrace: =========
338 /lib/libc.so.6(+0x6c501)[0x523501]
339 /lib/libc.so.6(+0x6dd70)[0x524d70]
340 /lib/libc.so.6(cfree+0x6d)[0x527e5d]
341 ./a.out[0x80485db]
342 /lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]
343 ./a.out[0x8048471]
344 ======= Memory map: ========
345 001e4000-001fe000 r-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1
346 001fe000-001ff000 r--p 00019000 08:06 1083555 /lib/libgcc_s.so.1
347 [some lines omitted]
348 b7814000-b7817000 rw-p 00000000 00:00 0
349 bff53000-bff74000 rw-p 00000000 00:00 0 [stack]
350 Aborted (core dumped)
351 The following runs show the results when employing other values for
353 M_CHECK_ACTION:
354 $ ./a.out 1 # Diagnose error and continue
356 main(): returned from first free() call
357 *** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 ***
358 main(): returned from second free() call
359 $ ./a.out 2 # Abort without error message
360 main(): returned from first free() call
361 Aborted (core dumped)
362 $ ./a.out 0 # Ignore error and continue
363 main(): returned from first free() call
364 main(): returned from second free() call
365 The next run shows how to set the same parameter using the MAL‐
367 LOC_CHECK_ environment variable:
368 $ MALLOC_CHECK_=1 ./a.out
370 main(): returned from first free() call
371 *** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***
372 main(): returned from second free() call
373 Program source
375 #include <malloc.h>
377 #include <stdio.h>
378 #include <stdlib.h>
379 int
381 main(int argc, char *argv[])
382 {
383 char *p;
384 if (argc > 1) {
386 if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {
387 fprintf(stderr, "mallopt() failed");
388 exit(EXIT_FAILURE);
389 }
390 }
391 p = malloc(1000);
393 if (p == NULL) {
394 fprintf(stderr, "malloc() failed");
395 exit(EXIT_FAILURE);
396 }
397 free(p);
399 printf("main(): returned from first free() call\n");
400 free(p);
402 printf("main(): returned from second free() call\n");
403 exit(EXIT_SUCCESS);
405 }
406
408 mmap(2), sbrk(2), mallinfo(3), malloc(3), malloc_hook(3),
409 malloc_info(3), malloc_stats(3), malloc_trim(3), mcheck(3), mtrace(3),
410 posix_memalign(3)
411
413 This page is part of release 5.12 of the Linux man-pages project. A
414 description of the project, information about reporting bugs, and the
415 latest version of this page, can be found at
416 https://www.kernel.org/doc/man-pages/.
417Linux 2021-03-22 MALLOPT(3)