1MALLOPT(3)                 Linux Programmer's Manual                MALLOPT(3)
2
3
4

NAME

6       mallopt - set memory allocation parameters
7

SYNOPSIS

9       #include <malloc.h>
10
11       int mallopt(int param, int value);
12

DESCRIPTION

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
19       The following values can be specified for param:
20
21       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
31              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
35              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
40              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
47       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
53              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
58              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
61              This parameter has been available since  glibc  2.10  via  --en‐
62              able-experimental-malloc, and since glibc 2.15 by default.
63
64              The  value  of  M_ARENA_TEST  is not used when M_ARENA_MAX has a
65              nonzero value.
66
67       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
74              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
82              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
90              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
97              The remaining bits in value are ignored.
98
99              Combining the above details, the following  numeric  values  are
100              meaningful for M_CHECK_ACTION:
101
102                   0  Ignore  error conditions; continue execution (with unde‐
103                      fined results).
104
105                   1  Print a detailed error message and continue execution.
106
107                   2  Abort the program.
108
109                   3  Print detailed error message, stack  trace,  and  memory
110                      mappings, and abort the program.
111
112                   5  Print a simple error message and continue execution.
113
114                   7  Print simple error message, stack trace, and memory map‐
115                      pings, and abort the program.
116
117              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
121              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
125       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
132              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
137       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
143              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
155              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
159              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
170       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
180              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
185       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
195              The default value for this parameter is 0.
196
197       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
203              *  When the program break is increased, then M_TOP_PAD bytes are
204                 added to the sbrk(2) request.
205
206              *  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
210              In either case, the amount of padding is  always  rounded  to  a
211              system page boundary.
212
213              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
218              The default value for this parameter is 128*1024.
219
220       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
229              The default value  for  this  parameter  is  128*1024.   Setting
230              M_TRIM_THRESHOLD to -1 disables trimming completely.
231
232              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
237   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
247       The  environment variables are as follows (note the trailing underscore
248       at the end of the name of some variables):
249
250       MALLOC_ARENA_MAX
251              Controls the same parameter as mallopt() M_ARENA_MAX.
252
253       MALLOC_ARENA_TEST
254              Controls the same parameter as mallopt() M_ARENA_TEST.
255
256       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
266              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
270              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
276       MALLOC_MMAP_MAX_
277              Controls the same parameter as mallopt() M_MMAP_MAX.
278
279       MALLOC_MMAP_THRESHOLD_
280              Controls the same parameter as mallopt() M_MMAP_THRESHOLD.
281
282       MALLOC_PERTURB_
283              Controls the same parameter as mallopt() M_PERTURB.
284
285       MALLOC_TRIM_THRESHOLD_
286              Controls the same parameter as mallopt() M_TRIM_THRESHOLD.
287
288       MALLOC_TOP_PAD_
289              Controls the same parameter as mallopt() M_TOP_PAD.
290

RETURN VALUE

292       On success, mallopt() returns 1.  On error, it returns 0.
293

ERRORS

295       On error, errno is not set.
296

CONFORMING TO

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

BUGS

305       Specifying an invalid value for param does not generate an error.
306
307       A  calculation  error within the glibc implementation means that a call
308       of the form:
309
310           mallopt(M_MXFAST, n)
311
312       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
317       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

EXAMPLES

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
331       The following shell session shows what happens when we run this program
332       under glibc, with the default value for M_CHECK_ACTION:
333
334           $ ./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
352       The  following  runs  show  the results when employing other values for
353       M_CHECK_ACTION:
354
355           $ ./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
366       The next run shows how  to  set  the  same  parameter  using  the  MAL‐
367       LOC_CHECK_ environment variable:
368
369           $ 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
374   Program source
375
376       #include <malloc.h>
377       #include <stdio.h>
378       #include <stdlib.h>
379
380       int
381       main(int argc, char *argv[])
382       {
383           char *p;
384
385           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
392           p = malloc(1000);
393           if (p == NULL) {
394               fprintf(stderr, "malloc() failed");
395               exit(EXIT_FAILURE);
396           }
397
398           free(p);
399           printf("main(): returned from first free() call\n");
400
401           free(p);
402           printf("main(): returned from second free() call\n");
403
404           exit(EXIT_SUCCESS);
405       }
406

SEE ALSO

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

COLOPHON

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/.
417
418
419
420Linux                             2021-03-22                        MALLOPT(3)
Impressum