1mallopt(3)                 Library Functions Manual                 mallopt(3)
2
3
4

NAME

6       mallopt - set memory allocation parameters
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <malloc.h>
13
14       int mallopt(int param, int value);
15

DESCRIPTION

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
22       The following values can be specified for param:
23
24       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
34              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
38              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
43              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
50       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
56              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
61              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
64              This parameter has been available since  glibc  2.10  via  --en‐
65              able-experimental-malloc, and since glibc 2.15 by default.
66
67              The  value  of  M_ARENA_TEST  is not used when M_ARENA_MAX has a
68              nonzero value.
69
70       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
77              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
85              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
93              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
100              The remaining bits in value are ignored.
101
102              Combining the above details, the following  numeric  values  are
103              meaningful for M_CHECK_ACTION:
104
105                   0      Ignore  error  conditions;  continue execution (with
106                          undefined results).
107
108                   1      Print a detailed error message and  continue  execu‐
109                          tion.
110
111                   2      Abort the program.
112
113                   3      Print  detailed error message, stack trace, and mem‐
114                          ory mappings, and abort the program.
115
116                   5      Print a simple error message and continue execution.
117
118                   7      Print simple error message, stack trace, and  memory
119                          mappings, and abort the program.
120
121              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
125              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
129       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
136              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
141       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
147              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
159              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
163              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
174       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
184              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
189       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
199              The default value for this parameter is 0.
200
201       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
207              •  When the program break is increased, then M_TOP_PAD bytes are
208                 added to the sbrk(2) request.
209
210              •  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
214              In  either  case,  the  amount of padding is always rounded to a
215              system page boundary.
216
217              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
222              The default value for this parameter is 128*1024.
223
224       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
233              The  default  value  for  this  parameter  is 128*1024.  Setting
234              M_TRIM_THRESHOLD to -1 disables trimming completely.
235
236              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
241   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
251       The environment variables are as follows (note the trailing  underscore
252       at the end of the name of some variables):
253
254       MALLOC_ARENA_MAX
255              Controls the same parameter as mallopt() M_ARENA_MAX.
256
257       MALLOC_ARENA_TEST
258              Controls the same parameter as mallopt() M_ARENA_TEST.
259
260       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
270              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
274              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
280       MALLOC_MMAP_MAX_
281              Controls the same parameter as mallopt() M_MMAP_MAX.
282
283       MALLOC_MMAP_THRESHOLD_
284              Controls the same parameter as mallopt() M_MMAP_THRESHOLD.
285
286       MALLOC_PERTURB_
287              Controls the same parameter as mallopt() M_PERTURB.
288
289       MALLOC_TRIM_THRESHOLD_
290              Controls the same parameter as mallopt() M_TRIM_THRESHOLD.
291
292       MALLOC_TOP_PAD_
293              Controls the same parameter as mallopt() M_TOP_PAD.
294

RETURN VALUE

296       On success, mallopt() returns 1.  On error, it returns 0.
297

ERRORS

299       On error, errno is not set.
300

VERSIONS

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

STANDARDS

308       None.
309

HISTORY

311       glibc 2.0.
312

BUGS

314       Specifying an invalid value for param does not generate an error.
315
316       A  calculation  error within the glibc implementation means that a call
317       of the form:
318
319           mallopt(M_MXFAST, n)
320
321       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
326       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

EXAMPLES

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
340       The following shell session shows what happens when we run this program
341       under glibc, with the default value for M_CHECK_ACTION:
342
343           $ ./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
361       The  following  runs  show  the results when employing other values for
362       M_CHECK_ACTION:
363
364           $ ./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
375       The next run shows how  to  set  the  same  parameter  using  the  MAL‐
376       LOC_CHECK_ environment variable:
377
378           $ 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
383   Program source
384
385       #include <malloc.h>
386       #include <stdio.h>
387       #include <stdlib.h>
388
389       int
390       main(int argc, char *argv[])
391       {
392           char *p;
393
394           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
401           p = malloc(1000);
402           if (p == NULL) {
403               fprintf(stderr, "malloc() failed");
404               exit(EXIT_FAILURE);
405           }
406
407           free(p);
408           printf("%s(): returned from first free() call\n", __func__);
409
410           free(p);
411           printf("%s(): returned from second free() call\n", __func__);
412
413           exit(EXIT_SUCCESS);
414       }
415

SEE ALSO

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)
420
421
422
423Linux man-pages 6.04              2023-03-30                        mallopt(3)
Impressum