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