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