|
Packit |
7cfc04 |
'\" t
|
|
Packit |
7cfc04 |
.\" Copyright (c) 2012 by Michael Kerrisk <mtk.manpages@gmail.com>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH MALLOPT 3 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
mallopt \- set memory allocation parameters
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.B #include <malloc.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int mallopt(int " param ", int " value );
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
function adjusts parameters that control the behavior of the
|
|
Packit |
7cfc04 |
memory-allocation functions (see
|
|
Packit |
7cfc04 |
.BR malloc (3)).
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.IR param
|
|
Packit |
7cfc04 |
argument specifies the parameter to be modified, and
|
|
Packit |
7cfc04 |
.I value
|
|
Packit |
7cfc04 |
specifies the new value for that parameter.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The following values can be specified for
|
|
Packit |
7cfc04 |
.IR param :
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_ARENA_MAX
|
|
Packit |
7cfc04 |
If this parameter has a nonzero value,
|
|
Packit |
7cfc04 |
it defines a hard limit on the maximum number of arenas that can be created.
|
|
Packit |
7cfc04 |
An arena represents a pool of memory that can be used by
|
|
Packit |
7cfc04 |
.BR malloc (3)
|
|
Packit |
7cfc04 |
(and similar) calls to service allocation requests.
|
|
Packit |
7cfc04 |
Arenas are thread safe and
|
|
Packit |
7cfc04 |
therefore may have multiple concurrent memory requests.
|
|
Packit |
7cfc04 |
The trade-off is between the number of threads and the number of arenas.
|
|
Packit |
7cfc04 |
The more arenas you have, the lower the per-thread contention,
|
|
Packit |
7cfc04 |
but the higher the memory usage.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The default value of this parameter is 0,
|
|
Packit |
7cfc04 |
meaning that the limit on the number of arenas is determined
|
|
Packit |
7cfc04 |
according to the setting of
|
|
Packit |
7cfc04 |
.BR M_ARENA_TEST .
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
This parameter has been available since glibc 2.10 via
|
|
Packit |
7cfc04 |
.BR \-\-enable\-experimental\-malloc ,
|
|
Packit |
7cfc04 |
and since glibc 2.15 by default.
|
|
Packit |
7cfc04 |
In some versions of the allocator there was no limit on the number
|
|
Packit |
7cfc04 |
of created arenas (e.g., CentOS 5, RHEL 5).
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
When employing newer glibc versions, applications may in
|
|
Packit |
7cfc04 |
some cases exhibit high contention when accessing arenas.
|
|
Packit |
7cfc04 |
In these cases, it may be beneficial to increase
|
|
Packit |
7cfc04 |
.B M_ARENA_MAX
|
|
Packit |
7cfc04 |
to match the number of threads.
|
|
Packit |
7cfc04 |
This is similar in behavior to strategies taken by tcmalloc and jemalloc
|
|
Packit |
7cfc04 |
(e.g., per-thread allocation pools).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_ARENA_TEST
|
|
Packit |
7cfc04 |
This parameter specifies a value, in number of arenas created,
|
|
Packit |
7cfc04 |
at which point the system configuration will be examined
|
|
Packit |
7cfc04 |
to determine a hard limit on the number of created arenas.
|
|
Packit |
7cfc04 |
(See
|
|
Packit |
7cfc04 |
.B M_ARENA_MAX
|
|
Packit |
7cfc04 |
for the definition of an arena.)
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The computation of the arena hard limit is implementation-defined
|
|
Packit |
7cfc04 |
and is usually calculated as a multiple of the number of available CPUs.
|
|
Packit |
7cfc04 |
Once the hard limit is computed, the result is final and constrains
|
|
Packit |
7cfc04 |
the total number of arenas.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The default value for the
|
|
Packit |
7cfc04 |
.B M_ARENA_TEST
|
|
Packit |
7cfc04 |
parameter is 2 on systems where
|
|
Packit |
7cfc04 |
.IR sizeof(long)
|
|
Packit |
7cfc04 |
is 4; otherwise the default value is 8.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
This parameter has been available since glibc 2.10 via
|
|
Packit |
7cfc04 |
.BR \-\-enable\-experimental\-malloc ,
|
|
Packit |
7cfc04 |
and since glibc 2.15 by default.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The value of
|
|
Packit |
7cfc04 |
.B M_ARENA_TEST
|
|
Packit |
7cfc04 |
is not used when
|
|
Packit |
7cfc04 |
.B M_ARENA_MAX
|
|
Packit |
7cfc04 |
has a nonzero value.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION
|
|
Packit |
7cfc04 |
Setting this parameter controls how glibc responds when various kinds
|
|
Packit |
7cfc04 |
of programming errors are detected (e.g., freeing the same pointer twice).
|
|
Packit |
7cfc04 |
The 3 least significant bits (2, 1, and 0) of the value assigned
|
|
Packit |
7cfc04 |
to this parameter determine the glibc behavior, as follows:
|
|
Packit |
7cfc04 |
.RS
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
Bit 0
|
|
Packit |
7cfc04 |
If this bit is set, then print a one-line message on
|
|
Packit |
7cfc04 |
.I stderr
|
|
Packit |
7cfc04 |
that provides details about the error.
|
|
Packit |
7cfc04 |
The message starts with the string "***\ glibc detected\ ***",
|
|
Packit |
7cfc04 |
followed by the program name,
|
|
Packit |
7cfc04 |
the name of the memory-allocation function in which the error was detected,
|
|
Packit |
7cfc04 |
a brief description of the error,
|
|
Packit |
7cfc04 |
and the memory address where the error was detected.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
Bit 1
|
|
Packit |
7cfc04 |
If this bit is set, then,
|
|
Packit |
7cfc04 |
after printing any error message specified by bit 0,
|
|
Packit |
7cfc04 |
the program is terminated by calling
|
|
Packit |
7cfc04 |
.BR abort (3).
|
|
Packit |
7cfc04 |
In glibc versions since 2.4,
|
|
Packit |
7cfc04 |
if bit 0 is also set,
|
|
Packit |
7cfc04 |
then, between printing the error message and aborting,
|
|
Packit |
7cfc04 |
the program also prints a stack trace in the manner of
|
|
Packit |
7cfc04 |
.BR backtrace (3),
|
|
Packit |
7cfc04 |
and prints the process's memory mapping in the style of
|
|
Packit |
7cfc04 |
.IR /proc/[pid]/maps
|
|
Packit |
7cfc04 |
(see
|
|
Packit |
7cfc04 |
.BR proc (5)).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
Bit 2 (since glibc 2.4)
|
|
Packit |
7cfc04 |
This bit has an effect only if bit 0 is also set.
|
|
Packit |
7cfc04 |
If this bit is set,
|
|
Packit |
7cfc04 |
then the one-line message describing the error is simplified
|
|
Packit |
7cfc04 |
to contain just the name of the function where the error
|
|
Packit |
7cfc04 |
was detected and the brief description of the error.
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The remaining bits in
|
|
Packit |
7cfc04 |
.I value
|
|
Packit |
7cfc04 |
are ignored.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
Combining the above details,
|
|
Packit |
7cfc04 |
the following numeric values are meaningful for
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION :
|
|
Packit |
7cfc04 |
.RS 12
|
|
Packit |
7cfc04 |
.IP 0 3
|
|
Packit |
7cfc04 |
Ignore error conditions; continue execution (with undefined results).
|
|
Packit |
7cfc04 |
.IP 1
|
|
Packit |
7cfc04 |
Print a detailed error message and continue execution.
|
|
Packit |
7cfc04 |
.IP 2
|
|
Packit |
7cfc04 |
Abort the program.
|
|
Packit |
7cfc04 |
.IP 3
|
|
Packit |
7cfc04 |
Print detailed error message, stack trace, and memory mappings,
|
|
Packit |
7cfc04 |
and abort the program.
|
|
Packit |
7cfc04 |
.IP 5
|
|
Packit |
7cfc04 |
Print a simple error message and continue execution.
|
|
Packit |
7cfc04 |
.IP 7
|
|
Packit |
7cfc04 |
Print simple error message, stack trace, and memory mappings,
|
|
Packit |
7cfc04 |
and abort the program.
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
Since glibc 2.3.4, the default value for the
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION
|
|
Packit |
7cfc04 |
parameter is 3.
|
|
Packit |
7cfc04 |
In glibc version 2.3.3 and earlier, the default value is 1.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
Using a nonzero
|
|
Packit |
7cfc04 |
.B M_CHECK_ACTION
|
|
Packit |
7cfc04 |
value can be useful because otherwise a crash may happen much later,
|
|
Packit |
7cfc04 |
and the true cause of the problem is then very hard to track down.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_MMAP_MAX
|
|
Packit |
7cfc04 |
.\" The following text adapted from comments in the glibc source:
|
|
Packit |
7cfc04 |
This parameter specifies the maximum number of allocation requests that
|
|
Packit |
7cfc04 |
may be simultaneously serviced using
|
|
Packit |
7cfc04 |
.BR mmap (2).
|
|
Packit |
7cfc04 |
This parameter exists because some systems have a limited number
|
|
Packit |
7cfc04 |
of internal tables for use by
|
|
Packit |
7cfc04 |
.BR mmap (2),
|
|
Packit |
7cfc04 |
and using more than a few of them may degrade performance.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The default value is 65,536,
|
|
Packit |
7cfc04 |
a value which has no special significance and
|
|
Packit |
7cfc04 |
which serves only as a safeguard.
|
|
Packit |
7cfc04 |
Setting this parameter to 0 disables the use of
|
|
Packit |
7cfc04 |
.BR mmap (2)
|
|
Packit |
7cfc04 |
for servicing large allocation requests.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_MMAP_THRESHOLD
|
|
Packit |
7cfc04 |
For allocations greater than or equal to the limit specified (in bytes) by
|
|
Packit |
7cfc04 |
.BR M_MMAP_THRESHOLD
|
|
Packit |
7cfc04 |
that can't be satisfied from the free list,
|
|
Packit |
7cfc04 |
the memory-allocation functions employ
|
|
Packit |
7cfc04 |
.BR mmap (2)
|
|
Packit |
7cfc04 |
instead of increasing the program break using
|
|
Packit |
7cfc04 |
.BR sbrk (2).
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
Allocating memory using
|
|
Packit |
7cfc04 |
.BR mmap (2)
|
|
Packit |
7cfc04 |
has the significant advantage that the allocated memory blocks
|
|
Packit |
7cfc04 |
can always be independently released back to the system.
|
|
Packit |
7cfc04 |
(By contrast,
|
|
Packit |
7cfc04 |
the heap can be trimmed only if memory is freed at the top end.)
|
|
Packit |
7cfc04 |
On the other hand, there are some disadvantages to the use of
|
|
Packit |
7cfc04 |
.BR mmap (2):
|
|
Packit |
7cfc04 |
deallocated space is not placed on the free list
|
|
Packit |
7cfc04 |
for reuse by later allocations;
|
|
Packit |
7cfc04 |
memory may be wasted because
|
|
Packit |
7cfc04 |
.BR mmap (2)
|
|
Packit |
7cfc04 |
allocations must be page-aligned;
|
|
Packit |
7cfc04 |
and the kernel must perform the expensive task of zeroing out
|
|
Packit |
7cfc04 |
memory allocated via
|
|
Packit |
7cfc04 |
.BR mmap (2).
|
|
Packit |
7cfc04 |
Balancing these factors leads to a default setting of 128*1024 for the
|
|
Packit |
7cfc04 |
.BR M_MMAP_THRESHOLD
|
|
Packit |
7cfc04 |
parameter.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The lower limit for this parameter is 0.
|
|
Packit |
7cfc04 |
The upper limit is
|
|
Packit |
7cfc04 |
.BR DEFAULT_MMAP_THRESHOLD_MAX :
|
|
Packit |
7cfc04 |
512*1024 on 32-bit systems or
|
|
Packit |
7cfc04 |
.IR 4*1024*1024*sizeof(long)
|
|
Packit |
7cfc04 |
on 64-bit systems.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
.IR Note:
|
|
Packit |
7cfc04 |
Nowadays, glibc uses a dynamic mmap threshold by default.
|
|
Packit |
7cfc04 |
The initial value of the threshold is 128*1024,
|
|
Packit |
7cfc04 |
but when blocks larger than the current threshold and less than or equal to
|
|
Packit |
7cfc04 |
.BR DEFAULT_MMAP_THRESHOLD_MAX
|
|
Packit |
7cfc04 |
are freed,
|
|
Packit |
7cfc04 |
the threshold is adjusted upward to the size of the freed block.
|
|
Packit |
7cfc04 |
When dynamic mmap thresholding is in effect,
|
|
Packit |
7cfc04 |
the threshold for trimming the heap is also dynamically adjusted
|
|
Packit |
7cfc04 |
to be twice the dynamic mmap threshold.
|
|
Packit |
7cfc04 |
Dynamic adjustment of the mmap threshold is disabled if any of the
|
|
Packit |
7cfc04 |
.BR M_TRIM_THRESHOLD ,
|
|
Packit |
7cfc04 |
.BR M_TOP_PAD ,
|
|
Packit |
7cfc04 |
.BR M_MMAP_THRESHOLD ,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR M_MMAP_MAX
|
|
Packit |
7cfc04 |
parameters is set.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_MXFAST " (since glibc 2.3)"
|
|
Packit |
7cfc04 |
.\" The following text adapted from comments in the glibc sources:
|
|
Packit |
7cfc04 |
Set the upper limit for memory allocation requests that are satisfied
|
|
Packit |
7cfc04 |
using "fastbins".
|
|
Packit |
7cfc04 |
(The measurement unit for this parameter is bytes.)
|
|
Packit |
7cfc04 |
Fastbins are storage areas that hold deallocated blocks of memory
|
|
Packit |
7cfc04 |
of the same size without merging adjacent free blocks.
|
|
Packit |
7cfc04 |
Subsequent reallocation of blocks of the same size can be handled
|
|
Packit |
7cfc04 |
very quickly by allocating from the fastbin,
|
|
Packit |
7cfc04 |
although memory fragmentation and the overall memory footprint
|
|
Packit |
7cfc04 |
of the program can increase.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The default value for this parameter is
|
|
Packit |
7cfc04 |
.IR "64*sizeof(size_t)/4"
|
|
Packit |
7cfc04 |
(i.e., 64 on 32-bit architectures).
|
|
Packit |
7cfc04 |
The range for this parameter is 0 to
|
|
Packit |
7cfc04 |
.IR "80*sizeof(size_t)/4" .
|
|
Packit |
7cfc04 |
Setting
|
|
Packit |
7cfc04 |
.B M_MXFAST
|
|
Packit |
7cfc04 |
to 0 disables the use of fastbins.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_PERTURB " (since glibc 2.4)"
|
|
Packit |
7cfc04 |
If this parameter is set to a nonzero value,
|
|
Packit |
7cfc04 |
then bytes of allocated memory (other than allocations via
|
|
Packit |
7cfc04 |
.BR calloc (3))
|
|
Packit |
7cfc04 |
are initialized to the complement of the value
|
|
Packit |
7cfc04 |
in the least significant byte of
|
|
Packit |
7cfc04 |
.IR value ,
|
|
Packit |
7cfc04 |
and when allocated memory is released using
|
|
Packit |
7cfc04 |
.BR free (3),
|
|
Packit |
7cfc04 |
the freed bytes are set to the least significant byte of
|
|
Packit |
7cfc04 |
.IR value .
|
|
Packit |
7cfc04 |
This can be useful for detecting errors where programs
|
|
Packit |
7cfc04 |
incorrectly rely on allocated memory being initialized to zero,
|
|
Packit |
7cfc04 |
or reuse values in memory that has already been freed.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The default value for this parameter is 0.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_TOP_PAD
|
|
Packit |
7cfc04 |
This parameter defines the amount of padding to employ when calling
|
|
Packit |
7cfc04 |
.BR sbrk (2)
|
|
Packit |
7cfc04 |
to modify the program break.
|
|
Packit |
7cfc04 |
(The measurement unit for this parameter is bytes.)
|
|
Packit |
7cfc04 |
This parameter has an effect in the following circumstances:
|
|
Packit |
7cfc04 |
.RS
|
|
Packit |
7cfc04 |
.IP * 3
|
|
Packit |
7cfc04 |
When the program break is increased, then
|
|
Packit |
7cfc04 |
.BR M_TOP_PAD
|
|
Packit |
7cfc04 |
bytes are added to the
|
|
Packit |
7cfc04 |
.BR sbrk (2)
|
|
Packit |
7cfc04 |
request.
|
|
Packit |
7cfc04 |
.IP *
|
|
Packit |
7cfc04 |
When the heap is trimmed as a consequence of calling
|
|
Packit |
7cfc04 |
.BR free (3)
|
|
Packit |
7cfc04 |
(see the discussion of
|
|
Packit |
7cfc04 |
.BR M_TRIM_THRESHOLD )
|
|
Packit |
7cfc04 |
this much free space is preserved at the top of the heap.
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
In either case,
|
|
Packit |
7cfc04 |
the amount of padding is always rounded to a system page boundary.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
Modifying
|
|
Packit |
7cfc04 |
.BR M_TOP_PAD
|
|
Packit |
7cfc04 |
is a trade-off between increasing the number of system calls
|
|
Packit |
7cfc04 |
(when the parameter is set low)
|
|
Packit |
7cfc04 |
and wasting unused memory at the top of the heap
|
|
Packit |
7cfc04 |
(when the parameter is set high).
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The default value for this parameter is 128*1024.
|
|
Packit |
7cfc04 |
.\" DEFAULT_TOP_PAD in glibc source
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR M_TRIM_THRESHOLD
|
|
Packit |
7cfc04 |
When the amount of contiguous free memory at the top of the heap
|
|
Packit |
7cfc04 |
grows sufficiently large,
|
|
Packit |
7cfc04 |
.BR free (3)
|
|
Packit |
7cfc04 |
employs
|
|
Packit |
7cfc04 |
.BR sbrk (2)
|
|
Packit |
7cfc04 |
to release this memory back to the system.
|
|
Packit |
7cfc04 |
(This can be useful in programs that continue to execute for
|
|
Packit |
7cfc04 |
a long period after freeing a significant amount of memory.)
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.BR M_TRIM_THRESHOLD
|
|
Packit |
7cfc04 |
parameter specifies the minimum size (in bytes) that
|
|
Packit |
7cfc04 |
this block of memory must reach before
|
|
Packit |
7cfc04 |
.BR sbrk (2)
|
|
Packit |
7cfc04 |
is used to trim the heap.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The default value for this parameter is 128*1024.
|
|
Packit |
7cfc04 |
Setting
|
|
Packit |
7cfc04 |
.BR M_TRIM_THRESHOLD
|
|
Packit |
7cfc04 |
to \-1 disables trimming completely.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
Modifying
|
|
Packit |
7cfc04 |
.BR M_TRIM_THRESHOLD
|
|
Packit |
7cfc04 |
is a trade-off between increasing the number of system calls
|
|
Packit |
7cfc04 |
(when the parameter is set low)
|
|
Packit |
7cfc04 |
and wasting unused memory at the top of the heap
|
|
Packit |
7cfc04 |
(when the parameter is set high).
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.SS Environment variables
|
|
Packit |
7cfc04 |
A number of environment variables can be defined
|
|
Packit |
7cfc04 |
to modify some of the same parameters as are controlled by
|
|
Packit |
7cfc04 |
.BR mallopt ().
|
|
Packit |
7cfc04 |
Using these variables has the advantage that the source code
|
|
Packit |
7cfc04 |
of the program need not be changed.
|
|
Packit |
7cfc04 |
To be effective, these variables must be defined before the
|
|
Packit |
7cfc04 |
first call to a memory-allocation function.
|
|
Packit |
7cfc04 |
(If the same parameters are adjusted via
|
|
Packit |
7cfc04 |
.BR mallopt (),
|
|
Packit |
7cfc04 |
then the
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
settings take precedence.)
|
|
Packit |
7cfc04 |
For security reasons,
|
|
Packit |
7cfc04 |
these variables are ignored in set-user-ID and set-group-ID programs.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The environment variables are as follows
|
|
Packit |
7cfc04 |
(note the trailing underscore at the end of the name of some variables):
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MALLOC_ARENA_MAX
|
|
Packit |
7cfc04 |
Controls the same parameter as
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
.BR M_ARENA_MAX .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MALLOC_ARENA_TEST
|
|
Packit |
7cfc04 |
Controls the same parameter as
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
.BR M_ARENA_TEST .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MALLOC_CHECK_
|
|
Packit |
7cfc04 |
This environment variable controls the same parameter as
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION .
|
|
Packit |
7cfc04 |
If this variable is set to a nonzero value,
|
|
Packit |
7cfc04 |
then a special implementation of the memory-allocation functions is used.
|
|
Packit |
7cfc04 |
(This is accomplished using the
|
|
Packit |
7cfc04 |
.BR malloc_hook (3)
|
|
Packit |
7cfc04 |
feature.)
|
|
Packit |
7cfc04 |
This implementation performs additional error checking,
|
|
Packit |
7cfc04 |
but is slower
|
|
Packit |
7cfc04 |
.\" On glibc 2.12/x86, a simple malloc()+free() loop is about 70% slower
|
|
Packit |
7cfc04 |
.\" when MALLOC_CHECK_ was set.
|
|
Packit |
7cfc04 |
than the standard set of memory-allocation functions.
|
|
Packit |
7cfc04 |
(This implementation does not detect all possible errors;
|
|
Packit |
7cfc04 |
memory leaks can still occur.)
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The value assigned to this environment variable should be a single digit,
|
|
Packit |
7cfc04 |
whose meaning is as described for
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION .
|
|
Packit |
7cfc04 |
Any characters beyond the initial digit are ignored.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
For security reasons, the effect of
|
|
Packit |
7cfc04 |
.BR MALLOC_CHECK_
|
|
Packit |
7cfc04 |
is disabled by default for set-user-ID and set-group-ID programs.
|
|
Packit |
7cfc04 |
However, if the file
|
|
Packit |
7cfc04 |
.IR /etc/suid\-debug
|
|
Packit |
7cfc04 |
exists (the content of the file is irrelevant), then
|
|
Packit |
7cfc04 |
.BR MALLOC_CHECK_
|
|
Packit |
7cfc04 |
also has an effect for set-user-ID and set-group-ID programs.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MALLOC_MMAP_MAX_
|
|
Packit |
7cfc04 |
Controls the same parameter as
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
.BR M_MMAP_MAX .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MALLOC_MMAP_THRESHOLD_
|
|
Packit |
7cfc04 |
Controls the same parameter as
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
.BR M_MMAP_THRESHOLD .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MALLOC_PERTURB_
|
|
Packit |
7cfc04 |
Controls the same parameter as
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
.BR M_PERTURB .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MALLOC_TRIM_THRESHOLD_
|
|
Packit |
7cfc04 |
Controls the same parameter as
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
.BR M_TRIM_THRESHOLD .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR MALLOC_TOP_PAD_
|
|
Packit |
7cfc04 |
Controls the same parameter as
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
.BR M_TOP_PAD .
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
On success,
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
returns 1.
|
|
Packit |
7cfc04 |
On error, it returns 0.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
On error,
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
is
|
|
Packit |
7cfc04 |
.I not
|
|
Packit |
7cfc04 |
set.
|
|
Packit |
7cfc04 |
.\" .SH VERSIONS
|
|
Packit |
7cfc04 |
.\" Available already in glibc 2.0, possibly earlier
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
This function is not specified by POSIX or the C standards.
|
|
Packit |
7cfc04 |
A similar function exists on many System V derivatives,
|
|
Packit |
7cfc04 |
but the range of values for
|
|
Packit |
7cfc04 |
.IR param
|
|
Packit |
7cfc04 |
varies across systems.
|
|
Packit |
7cfc04 |
The SVID defined options
|
|
Packit |
7cfc04 |
.BR M_MXFAST ,
|
|
Packit |
7cfc04 |
.BR M_NLBLKS ,
|
|
Packit |
7cfc04 |
.BR M_GRAIN ,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR M_KEEP ,
|
|
Packit |
7cfc04 |
but only the first of these is implemented in glibc.
|
|
Packit |
7cfc04 |
.\" .SH NOTES
|
|
Packit |
7cfc04 |
.SH BUGS
|
|
Packit |
7cfc04 |
Specifying an invalid value for
|
|
Packit |
7cfc04 |
.I param
|
|
Packit |
7cfc04 |
does not generate an error.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
A calculation error within the glibc implementation means that
|
|
Packit |
7cfc04 |
a call of the form:
|
|
Packit |
7cfc04 |
.\" FIXME . This looks buggy:
|
|
Packit |
7cfc04 |
.\" setting the M_MXFAST limit rounds up: (s + SIZE_SZ) & ~MALLOC_ALIGN_MASK)
|
|
Packit |
7cfc04 |
.\" malloc requests are rounded up:
|
|
Packit |
7cfc04 |
.\" (req) + SIZE_SZ + MALLOC_ALIGN_MASK) & ~MALLOC_ALIGN_MASK
|
|
Packit |
7cfc04 |
.\" http://sources.redhat.com/bugzilla/show_bug.cgi?id=12129
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
mallopt(M_MXFAST, n)
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
does not result in fastbins being employed for all allocations of size up to
|
|
Packit |
7cfc04 |
.IR n .
|
|
Packit |
7cfc04 |
To ensure desired results,
|
|
Packit |
7cfc04 |
.I n
|
|
Packit |
7cfc04 |
should be rounded up to the next multiple greater than or equal to
|
|
Packit |
7cfc04 |
.IR (2k+1)*sizeof(size_t) ,
|
|
Packit |
7cfc04 |
where
|
|
Packit |
7cfc04 |
.I k
|
|
Packit |
7cfc04 |
is an integer.
|
|
Packit |
7cfc04 |
.\" Bins are multiples of 2 * sizeof(size_t) + sizeof(size_t)
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.BR mallopt ()
|
|
Packit |
7cfc04 |
is used to set
|
|
Packit |
7cfc04 |
.BR M_PERTURB ,
|
|
Packit |
7cfc04 |
then, as expected, the bytes of allocated memory are initialized
|
|
Packit |
7cfc04 |
to the complement of the byte in
|
|
Packit |
7cfc04 |
.IR value ,
|
|
Packit |
7cfc04 |
and when that memory is freed,
|
|
Packit |
7cfc04 |
the bytes of the region are initialized to the byte specified in
|
|
Packit |
7cfc04 |
.IR value .
|
|
Packit |
7cfc04 |
However, there is an
|
|
Packit |
7cfc04 |
.RI off-by- sizeof(size_t)
|
|
Packit |
7cfc04 |
error in the implementation:
|
|
Packit |
7cfc04 |
.\" FIXME . http://sources.redhat.com/bugzilla/show_bug.cgi?id=12140
|
|
Packit |
7cfc04 |
instead of initializing precisely the block of memory
|
|
Packit |
7cfc04 |
being freed by the call
|
|
Packit |
7cfc04 |
.IR free(p) ,
|
|
Packit |
7cfc04 |
the block starting at
|
|
Packit |
7cfc04 |
.I p+sizeof(size_t)
|
|
Packit |
7cfc04 |
is initialized.
|
|
Packit |
7cfc04 |
.SH EXAMPLE
|
|
Packit |
7cfc04 |
The program below demonstrates the use of
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION .
|
|
Packit |
7cfc04 |
If the program is supplied with an (integer) command-line argument,
|
|
Packit |
7cfc04 |
then that argument is used to set the
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION
|
|
Packit |
7cfc04 |
parameter.
|
|
Packit |
7cfc04 |
The program then allocates a block of memory,
|
|
Packit |
7cfc04 |
and frees it twice (an error).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The following shell session shows what happens when we run this program
|
|
Packit |
7cfc04 |
under glibc, with the default value for
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION :
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
$ \fB./a.out\fP
|
|
Packit |
7cfc04 |
main(): returned from first free() call
|
|
Packit |
7cfc04 |
*** glibc detected *** ./a.out: double free or corruption (top): 0x09d30008 ***
|
|
Packit |
7cfc04 |
======= Backtrace: =========
|
|
Packit |
7cfc04 |
/lib/libc.so.6(+0x6c501)[0x523501]
|
|
Packit |
7cfc04 |
/lib/libc.so.6(+0x6dd70)[0x524d70]
|
|
Packit |
7cfc04 |
/lib/libc.so.6(cfree+0x6d)[0x527e5d]
|
|
Packit |
7cfc04 |
\&./a.out[0x80485db]
|
|
Packit |
7cfc04 |
/lib/libc.so.6(__libc_start_main+0xe7)[0x4cdce7]
|
|
Packit |
7cfc04 |
\&./a.out[0x8048471]
|
|
Packit |
7cfc04 |
======= Memory map: ========
|
|
Packit |
7cfc04 |
001e4000\-001fe000 r\-xp 00000000 08:06 1083555 /lib/libgcc_s.so.1
|
|
Packit |
7cfc04 |
001fe000\-001ff000 r\-\-p 00019000 08:06 1083555 /lib/libgcc_s.so.1
|
|
Packit |
7cfc04 |
[some lines omitted]
|
|
Packit |
7cfc04 |
b7814000\-b7817000 rw\-p 00000000 00:00 0
|
|
Packit |
7cfc04 |
bff53000\-bff74000 rw\-p 00000000 00:00 0 [stack]
|
|
Packit |
7cfc04 |
Aborted (core dumped)
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The following runs show the results when employing other values for
|
|
Packit |
7cfc04 |
.BR M_CHECK_ACTION :
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
$ \fB./a.out 1\fP # Diagnose error and continue
|
|
Packit |
7cfc04 |
main(): returned from first free() call
|
|
Packit |
7cfc04 |
*** glibc detected *** ./a.out: double free or corruption (top): 0x09cbe008 ***
|
|
Packit |
7cfc04 |
main(): returned from second free() call
|
|
Packit |
7cfc04 |
$ \fB./a.out 2\fP # Abort without error message
|
|
Packit |
7cfc04 |
main(): returned from first free() call
|
|
Packit |
7cfc04 |
Aborted (core dumped)
|
|
Packit |
7cfc04 |
$ \fB./a.out 0\fP # Ignore error and continue
|
|
Packit |
7cfc04 |
main(): returned from first free() call
|
|
Packit |
7cfc04 |
main(): returned from second free() call
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The next run shows how to set the same parameter using the
|
|
Packit |
7cfc04 |
.B MALLOC_CHECK_
|
|
Packit |
7cfc04 |
environment variable:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
$ \fBMALLOC_CHECK_=1 ./a.out\fP
|
|
Packit |
7cfc04 |
main(): returned from first free() call
|
|
Packit |
7cfc04 |
*** glibc detected *** ./a.out: free(): invalid pointer: 0x092c2008 ***
|
|
Packit |
7cfc04 |
main(): returned from second free() call
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.SS Program source
|
|
Packit |
7cfc04 |
\&
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
#include <malloc.h>
|
|
Packit |
7cfc04 |
#include <stdio.h>
|
|
Packit |
7cfc04 |
#include <stdlib.h>
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
int
|
|
Packit |
7cfc04 |
main(int argc, char *argv[])
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
char *p;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
if (argc > 1) {
|
|
Packit |
7cfc04 |
if (mallopt(M_CHECK_ACTION, atoi(argv[1])) != 1) {
|
|
Packit |
7cfc04 |
fprintf(stderr, "mallopt() failed");
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
p = malloc(1000);
|
|
Packit |
7cfc04 |
if (p == NULL) {
|
|
Packit |
7cfc04 |
fprintf(stderr, "malloc() failed");
|
|
Packit |
7cfc04 |
exit(EXIT_FAILURE);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
free(p);
|
|
Packit |
7cfc04 |
printf("main(): returned from first free() call\\n");
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
free(p);
|
|
Packit |
7cfc04 |
printf("main(): returned from second free() call\\n");
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
exit(EXIT_SUCCESS);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.ad l
|
|
Packit |
7cfc04 |
.nh
|
|
Packit |
7cfc04 |
.BR mmap (2),
|
|
Packit |
7cfc04 |
.BR sbrk (2),
|
|
Packit |
7cfc04 |
.BR mallinfo (3),
|
|
Packit |
7cfc04 |
.BR malloc (3),
|
|
Packit |
7cfc04 |
.BR malloc_hook (3),
|
|
Packit |
7cfc04 |
.BR malloc_info (3),
|
|
Packit |
7cfc04 |
.BR malloc_stats (3),
|
|
Packit |
7cfc04 |
.BR malloc_trim (3),
|
|
Packit |
7cfc04 |
.BR mcheck (3),
|
|
Packit |
7cfc04 |
.BR mtrace (3),
|
|
Packit |
7cfc04 |
.BR posix_memalign (3)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|