Debian Codegraph @

upstream/debian-unstable/man3/mallopt.3

raw
1 .\" Copyright 2012, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH mallopt 3 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 mallopt \- set memory allocation parameters
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <malloc.h>
15 .P
16 .BI "int mallopt(int " param ", int " value );
17 .fi
18 .SH DESCRIPTION
19 The
20 .BR mallopt ()
21 function adjusts parameters that control the behavior of the
22 memory-allocation functions (see
23 .BR malloc (3)).
24 The
25 .I param
26 argument specifies the parameter to be modified, and
27 .I value
28 specifies the new value for that parameter.
29 .P
30 The following values can be specified for
31 .IR param :
32 .TP
33 .B M_ARENA_MAX
34 If this parameter has a nonzero value,
35 it defines a hard limit on the maximum number of arenas that can be created.
36 An arena represents a pool of memory that can be used by
37 .BR malloc (3)
38 (and similar) calls to service allocation requests.
39 Arenas are thread safe and
40 therefore may have multiple concurrent memory requests.
41 The trade-off is between the number of threads and the number of arenas.
42 The more arenas you have, the lower the per-thread contention,
43 but the higher the memory usage.
44 .IP
45 The default value of this parameter is 0,
46 meaning that the limit on the number of arenas is determined
47 according to the setting of
48 .BR M_ARENA_TEST .
49 .IP
50 This parameter has been available since glibc 2.10 via
51 .BR \-\-enable\-experimental\-malloc ,
52 and since glibc 2.15 by default.
53 In some versions of the allocator there was no limit on the number
54 of created arenas (e.g., CentOS 5, RHEL 5).
55 .IP
56 When employing newer glibc versions, applications may in
57 some cases exhibit high contention when accessing arenas.
58 In these cases, it may be beneficial to increase
59 .B M_ARENA_MAX
60 to match the number of threads.
61 This is similar in behavior to strategies taken by tcmalloc and jemalloc
62 (e.g., per-thread allocation pools).
63 .TP
64 .B M_ARENA_TEST
65 This parameter specifies a value, in number of arenas created,
66 at which point the system configuration will be examined
67 to determine a hard limit on the number of created arenas.
68 (See
69 .B M_ARENA_MAX
70 for the definition of an arena.)
71 .IP
72 The computation of the arena hard limit is implementation-defined
73 and is usually calculated as a multiple of the number of available CPUs.
74 Once the hard limit is computed, the result is final and constrains
75 the total number of arenas.
76 .IP
77 The default value for the
78 .B M_ARENA_TEST
79 parameter is 2 on systems where
80 .I sizeof(long)
81 is 4;
82 otherwise the default value is 8.
83 .IP
84 This parameter has been available since glibc 2.10 via
85 .BR \-\-enable\-experimental\-malloc ,
86 and since glibc 2.15 by default.
87 .IP
88 The value of
89 .B M_ARENA_TEST
90 is not used when
91 .B M_ARENA_MAX
92 has a nonzero value.
93 .TP
94 .B M_CHECK_ACTION
95 Setting this parameter controls how glibc responds when various kinds
96 of programming errors are detected (e.g., freeing the same pointer twice).
97 The 3 least significant bits (2, 1, and 0) of the value assigned
98 to this parameter determine the glibc behavior, as follows:
99 .RS
100 .TP
101 Bit 0
102 If this bit is set, then print a one-line message on
103 .I stderr
104 that provides details about the error.
105 The message starts with the string "***\ glibc detected\ ***",
106 followed by the program name,
107 the name of the memory-allocation function in which the error was detected,
108 a brief description of the error,
109 and the memory address where the error was detected.
110 .TP
111 Bit 1
112 If this bit is set, then,
113 after printing any error message specified by bit 0,
114 the program is terminated by calling
115 .BR abort (3).
116 Since glibc 2.4,
117 if bit 0 is also set,
118 then, between printing the error message and aborting,
119 the program also prints a stack trace in the manner of
120 .BR backtrace (3),
121 and prints the process's memory mapping in the style of
122 .IR /proc/ pid /maps
123 (see
124 .BR proc (5)).
125 .TP
126 Bit 2 (since glibc 2.4)
127 This bit has an effect only if bit 0 is also set.
128 If this bit is set,
129 then the one-line message describing the error is simplified
130 to contain just the name of the function where the error
131 was detected and the brief description of the error.
132 .RE
133 .IP
134 The remaining bits in
135 .I value
136 are ignored.
137 .IP
138 Combining the above details,
139 the following numeric values are meaningful for
140 .BR M_CHECK_ACTION :
141 .RS 12
142 .TP
143 .B 0
144 Ignore error conditions;
145 continue execution
146 (with undefined results).
147 .TP
148 .B 1
149 Print a detailed error message and continue execution.
150 .TP
151 .B 2
152 Abort the program.
153 .TP
154 .B 3
155 Print detailed error message, stack trace, and memory mappings,
156 and abort the program.
157 .TP
158 .B 5
159 Print a simple error message and continue execution.
160 .TP
161 .B 7
162 Print simple error message, stack trace, and memory mappings,
163 and abort the program.
164 .RE
165 .IP
166 Since glibc 2.3.4, the default value for the
167 .B M_CHECK_ACTION
168 parameter is 3.
169 In glibc 2.3.3 and earlier, the default value is 1.
170 .IP
171 Using a nonzero
172 .B M_CHECK_ACTION
173 value can be useful because otherwise a crash may happen much later,
174 and the true cause of the problem is then very hard to track down.
175 .TP
176 .B M_MMAP_MAX
177 .\" The following text adapted from comments in the glibc source:
178 This parameter specifies the maximum number of allocation requests that
179 may be simultaneously serviced using
180 .BR mmap (2).
181 This parameter exists because some systems have a limited number
182 of internal tables for use by
183 .BR mmap (2),
184 and using more than a few of them may degrade performance.
185 .IP
186 The default value is 65,536,
187 a value which has no special significance and
188 which serves only as a safeguard.
189 Setting this parameter to 0 disables the use of
190 .BR mmap (2)
191 for servicing large allocation requests.
192 .TP
193 .B M_MMAP_THRESHOLD
194 For allocations greater than or equal to the limit specified (in bytes) by
195 .B M_MMAP_THRESHOLD
196 that can't be satisfied from the free list,
197 the memory-allocation functions employ
198 .BR mmap (2)
199 instead of increasing the program break using
200 .BR sbrk (2).
201 .IP
202 Allocating memory using
203 .BR mmap (2)
204 has the significant advantage that the allocated memory blocks
205 can always be independently released back to the system.
206 (By contrast,
207 the heap can be trimmed only if memory is freed at the top end.)
208 On the other hand, there are some disadvantages to the use of
209 .BR mmap (2):
210 deallocated space is not placed on the free list
211 for reuse by later allocations;
212 memory may be wasted because
213 .BR mmap (2)
214 allocations must be page-aligned;
215 and the kernel must perform the expensive task of zeroing out
216 memory allocated via
217 .BR mmap (2).
218 Balancing these factors leads to a default setting of 128*1024 for the
219 .B M_MMAP_THRESHOLD
220 parameter.
221 .IP
222 The lower limit for this parameter is 0.
223 The upper limit is
224 .BR DEFAULT_MMAP_THRESHOLD_MAX :
225 512*1024 on 32-bit systems or
226 .I 4*1024*1024*sizeof(long)
227 on 64-bit systems.
228 .IP
229 .IR Note :
230 Nowadays, glibc uses a dynamic mmap threshold by default.
231 The initial value of the threshold is 128*1024,
232 but when blocks larger than the current threshold and less than or equal to
233 .B DEFAULT_MMAP_THRESHOLD_MAX
234 are freed,
235 the threshold is adjusted upward to the size of the freed block.
236 When dynamic mmap thresholding is in effect,
237 the threshold for trimming the heap is also dynamically adjusted
238 to be twice the dynamic mmap threshold.
239 Dynamic adjustment of the mmap threshold is disabled if any of the
240 .BR M_TRIM_THRESHOLD ,
241 .BR M_TOP_PAD ,
242 .BR M_MMAP_THRESHOLD ,
243 or
244 .B M_MMAP_MAX
245 parameters is set.
246 .TP
247 .BR M_MXFAST " (since glibc 2.3)"
248 .\" The following text adapted from comments in the glibc sources:
249 Set the upper limit for memory allocation requests that are satisfied
250 using "fastbins".
251 (The measurement unit for this parameter is bytes.)
252 Fastbins are storage areas that hold deallocated blocks of memory
253 of the same size without merging adjacent free blocks.
254 Subsequent reallocation of blocks of the same size can be handled
255 very quickly by allocating from the fastbin,
256 although memory fragmentation and the overall memory footprint
257 of the program can increase.
258 .IP
259 The default value for this parameter is
260 .I 64*sizeof(size_t)/4
261 (i.e., 64 on 32-bit architectures).
262 The range for this parameter is 0 to
263 .IR 80*sizeof(size_t)/4 .
264 Setting
265 .B M_MXFAST
266 to 0 disables the use of fastbins.
267 .TP
268 .BR M_PERTURB " (since glibc 2.4)"
269 If this parameter is set to a nonzero value,
270 then bytes of allocated memory (other than allocations via
271 .BR calloc (3))
272 are initialized to the complement of the value
273 in the least significant byte of
274 .IR value ,
275 and when allocated memory is released using
276 .BR free (3),
277 the freed bytes are set to the least significant byte of
278 .IR value .
279 This can be useful for detecting errors where programs
280 incorrectly rely on allocated memory being initialized to zero,
281 or reuse values in memory that has already been freed.
282 .IP
283 The default value for this parameter is 0.
284 .TP
285 .B M_TOP_PAD
286 This parameter defines the amount of padding to employ when calling
287 .BR sbrk (2)
288 to modify the program break.
289 (The measurement unit for this parameter is bytes.)
290 This parameter has an effect in the following circumstances:
291 .RS
292 .IP \[bu] 3
293 When the program break is increased, then
294 .B M_TOP_PAD
295 bytes are added to the
296 .BR sbrk (2)
297 request.
298 .IP \[bu]
299 When the heap is trimmed as a consequence of calling
300 .BR free (3)
301 (see the discussion of
302 .BR M_TRIM_THRESHOLD )
303 this much free space is preserved at the top of the heap.
304 .RE
305 .IP
306 In either case,
307 the amount of padding is always rounded to a system page boundary.
308 .IP
309 Modifying
310 .B M_TOP_PAD
311 is a trade-off between increasing the number of system calls
312 (when the parameter is set low)
313 and wasting unused memory at the top of the heap
314 (when the parameter is set high).
315 .IP
316 The default value for this parameter is 128*1024.
317 .\" DEFAULT_TOP_PAD in glibc source
318 .TP
319 .B M_TRIM_THRESHOLD
320 When the amount of contiguous free memory at the top of the heap
321 grows sufficiently large,
322 .BR free (3)
323 employs
324 .BR sbrk (2)
325 to release this memory back to the system.
326 (This can be useful in programs that continue to execute for
327 a long period after freeing a significant amount of memory.)
328 The
329 .B M_TRIM_THRESHOLD
330 parameter specifies the minimum size (in bytes) that
331 this block of memory must reach before
332 .BR sbrk (2)
333 is used to trim the heap.
334 .IP
335 The default value for this parameter is 128*1024.
336 Setting
337 .B M_TRIM_THRESHOLD
338 to \-1 disables trimming completely.
339 .IP
340 Modifying
341 .B M_TRIM_THRESHOLD
342 is a trade-off between increasing the number of system calls
343 (when the parameter is set low)
344 and wasting unused memory at the top of the heap
345 (when the parameter is set high).
346 .\"
347 .SS Environment variables
348 A number of environment variables can be defined
349 to modify some of the same parameters as are controlled by
350 .BR mallopt ().
351 Using these variables has the advantage that the source code
352 of the program need not be changed.
353 To be effective, these variables must be defined before the
354 first call to a memory-allocation function.
355 (If the same parameters are adjusted via
356 .BR mallopt (),
357 then the
358 .BR mallopt ()
359 settings take precedence.)
360 For security reasons,
361 these variables are ignored in set-user-ID and set-group-ID programs.
362 .P
363 The environment variables are as follows
364 (note the trailing underscore at the end of the name of some variables):
365 .TP
366 .B MALLOC_ARENA_MAX
367 Controls the same parameter as
368 .BR mallopt ()
369 .BR M_ARENA_MAX .
370 .TP
371 .B MALLOC_ARENA_TEST
372 Controls the same parameter as
373 .BR mallopt ()
374 .BR M_ARENA_TEST .
375 .TP
376 .B MALLOC_CHECK_
377 This environment variable controls the same parameter as
378 .BR mallopt ()
379 .BR M_CHECK_ACTION .
380 If this variable is set to a nonzero value,
381 then a special implementation of the memory-allocation functions is used.
382 (This is accomplished using the
383 .BR malloc_hook (3)
384 feature.)
385 This implementation performs additional error checking,
386 but is slower
387 .\" On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower
388 .\" when MALLOC_CHECK_ was set.
389 than the standard set of memory-allocation functions.
390 (This implementation does not detect all possible errors;
391 memory leaks can still occur.)
392 .IP
393 The value assigned to this environment variable should be a single digit,
394 whose meaning is as described for
395 .BR M_CHECK_ACTION .
396 Any characters beyond the initial digit are ignored.
397 .IP
398 For security reasons, the effect of
399 .B MALLOC_CHECK_
400 is disabled by default for set-user-ID and set-group-ID programs.
401 However, if the file
402 .I /etc/suid\-debug
403 exists (the content of the file is irrelevant), then
404 .B MALLOC_CHECK_
405 also has an effect for set-user-ID and set-group-ID programs.
406 .TP
407 .B MALLOC_MMAP_MAX_
408 Controls the same parameter as
409 .BR mallopt ()
410 .BR M_MMAP_MAX .
411 .TP
412 .B MALLOC_MMAP_THRESHOLD_
413 Controls the same parameter as
414 .BR mallopt ()
415 .BR M_MMAP_THRESHOLD .
416 .TP
417 .B MALLOC_PERTURB_
418 Controls the same parameter as
419 .BR mallopt ()
420 .BR M_PERTURB .
421 .TP
422 .B MALLOC_TRIM_THRESHOLD_
423 Controls the same parameter as
424 .BR mallopt ()
425 .BR M_TRIM_THRESHOLD .
426 .TP
427 .B MALLOC_TOP_PAD_
428 Controls the same parameter as
429 .BR mallopt ()
430 .BR M_TOP_PAD .
431 .SH RETURN VALUE
432 On success,
433 .BR mallopt ()
434 returns 1.
435 On error, it returns 0.
436 .SH ERRORS
437 On error,
438 .I errno
439 is
440 .I not
441 set.
442 .SH VERSIONS
443 A similar function exists on many System V derivatives,
444 but the range of values for
445 .I param
446 varies across systems.
447 The SVID defined options
448 .BR M_MXFAST ,
449 .BR M_NLBLKS ,
450 .BR M_GRAIN ,
451 and
452 .BR M_KEEP ,
453 but only the first of these is implemented in glibc.
454 .SH STANDARDS
455 None.
456 .SH HISTORY
457 glibc 2.0.
458 .SH BUGS
459 Specifying an invalid value for
460 .I param
461 does not generate an error.
462 .P
463 A calculation error within the glibc implementation means that
464 a call of the form:
465 .\" FIXME . This looks buggy:
466 .\" setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK)
467 .\" malloc requests are rounded up:
468 .\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK
469 .\" https://www.sourceware.org/bugzilla/show_bug.cgi?id=12129
470 .P
471 .in +4n
472 .EX
473 mallopt(M_MXFAST, n)
474 .EE
475 .in
476 .P
477 does not result in fastbins being employed for all allocations of size up to
478 .IR n .
479 To ensure desired results,
480 .I n
481 should be rounded up to the next multiple greater than or equal to
482 .IR (2k+1)*sizeof(size_t) ,
483 where
484 .I k
485 is an integer.
486 .\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t)
487 .P
488 If
489 .BR mallopt ()
490 is used to set
491 .BR M_PERTURB ,
492 then, as expected, the bytes of allocated memory are initialized
493 to the complement of the byte in
494 .IR value ,
495 and when that memory is freed,
496 the bytes of the region are initialized to the byte specified in
497 .IR value .
498 However, there is an
499 .RI off-by- sizeof(size_t)
500 error in the implementation:
501 .\" FIXME . https://www.sourceware.org/bugzilla/show_bug.cgi?id=12140
502 instead of initializing precisely the block of memory
503 being freed by the call
504 .IR free(p) ,
505 the block starting at
506 .I p+sizeof(size_t)
507 is initialized.
508 .SH EXAMPLES
509 The program below demonstrates the use of
510 .BR M_CHECK_ACTION .
511 If the program is supplied with an (integer) command-line argument,
512 then that argument is used to set the
513 .B M_CHECK_ACTION
514 parameter.
515 The program then allocates a block of memory,
516 and frees it twice (an error).
517 .P
518 The following shell session shows what happens when we run this program
519 under glibc, with the default value for
520 .BR M_CHECK_ACTION :
521 .P
522 .in +4n
523 .EX
524 .RB $ " ./a.out" ;
525 main(): returned from first free() call
526 *** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 ***
527 ======= Backtrace: =========
528 /lib/libc.so.6(+0x6c501)[0x523501]
529 /lib/libc.so.6(+0x6dd70)[0x524d70]
530 /lib/libc.so.6(cfree+0x6d)[0x527e5d]
531 \&./a.out[0x80485db]
532 /lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]
533 \&./a.out[0x8048471]
534 ======= Memory map: ========
535 001e4000\-001fe000 r\-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1
536 001fe000\-001ff000 r\-\-p 00019000 08:06 1083555 /lib/libgcc_s.so.1
537 [some lines omitted]
538 b7814000\-b7817000 rw\-p 00000000 00:00 0
539 bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack]
540 Aborted (core dumped)
541 .EE
542 .in
543 .P
544 The following runs show the results when employing other values for
545 .BR M_CHECK_ACTION :
546 .P
547 .in +4n
548 .EX
549 .RB $ " ./a.out 1" "; # Diagnose error and continue"
550 main(): returned from first free() call
551 *** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 ***
552 main(): returned from second free() call
553 .RB $ " ./a.out 2" "; # Abort without error message"
554 main(): returned from first free() call
555 Aborted (core dumped)
556 .RB $ " ./a.out 0" "; # Ignore error and continue"
557 main(): returned from first free() call
558 main(): returned from second free() call
559 .EE
560 .in
561 .P
562 The next run shows how to set the same parameter using the
563 .B MALLOC_CHECK_
564 environment variable:
565 .P
566 .in +4n
567 .EX
568 .RB $ " MALLOC_CHECK_=1 ./a.out" ;
569 main(): returned from first free() call
570 *** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***
571 main(): returned from second free() call
572 .EE
573 .in
574 .SS Program source
575 \&
576 .\" SRC BEGIN (mallopt.c)
577 .EX
578 #include <malloc.h>
579 #include <stdio.h>
580 #include <stdlib.h>
581 \&
582 int
583 main(int argc, char *argv[])
584 {
585 char *p;
586 \&
587 if (argc > 1) {
588 if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {
589 fprintf(stderr, "mallopt() failed");
590 exit(EXIT_FAILURE);
591 }
592 }
593 \&
594 p = malloc(1000);
595 if (p == NULL) {
596 fprintf(stderr, "malloc() failed");
597 exit(EXIT_FAILURE);
598 }
599 \&
600 free(p);
601 printf("%s(): returned from first free() call\[rs]n", __func__);
602 \&
603 free(p);
604 printf("%s(): returned from second free() call\[rs]n", __func__);
605 \&
606 exit(EXIT_SUCCESS);
607 }
608 .EE
609 .\" SRC END
610 .SH SEE ALSO
611 .ad l
612 .nh
613 .BR mmap (2),
614 .BR sbrk (2),
615 .BR mallinfo (3),
616 .BR malloc (3),
617 .BR malloc_hook (3),
618 .BR malloc_info (3),
619 .BR malloc_stats (3),
620 .BR malloc_trim (3),
621 .BR mcheck (3),
622 .BR mtrace (3),
623 .BR posix_memalign (3)