2 @c @node Tunables, , Internal Probes, Top
3 @c %MENU% Tunable switches to alter libc internal behavior
7 @dfn{Tunables} are a feature in @theglibc{} that allows application authors and
8 distribution maintainers to alter the runtime library behavior to match
9 their workload. These are implemented as a set of switches that may be
10 modified in different ways. The current default method to do this is via
11 the @env{GLIBC_TUNABLES} environment variable by setting it to a string
12 of colon-separated @var{name}=@var{value} pairs. For example, the following
13 example enables malloc checking and sets the malloc trim threshold to 128
17 GLIBC_TUNABLES=glibc.malloc.trim_threshold=128:glibc.malloc.check=3
21 Tunables are not part of the @glibcadj{} stable ABI, and they are
22 subject to change or removal across releases. Additionally, the method to
23 modify tunable values may change between releases and across distributions.
24 It is possible to implement multiple `frontends' for the tunables allowing
25 distributions to choose their preferred method at build time.
27 Finally, the set of tunables available may vary between distributions as
28 the tunables feature allows distributions to add their own tunables under
32 * Tunable names:: The structure of a tunable name
33 * Memory Allocation Tunables:: Tunables in the memory allocation subsystem
34 * Hardware Capability Tunables:: Tunables that modify the hardware
35 capabilities seen by @theglibc{}
39 @section Tunable names
41 @cindex Tunable namespaces
43 A tunable name is split into three components, a top namespace, a tunable
44 namespace and the tunable name. The top namespace for tunables implemented in
45 @theglibc{} is @code{glibc}. Distributions that choose to add custom tunables
46 in their maintained versions of @theglibc{} may choose to do so under their own
49 The tunable namespace is a logical grouping of tunables in a single
50 module. This currently holds no special significance, although that may
53 The tunable name is the actual name of the tunable. It is possible that
54 different tunable namespaces may have tunables within them that have the
55 same name, likewise for top namespaces. Hence, we only support
56 identification of tunables by their full name, i.e. with the top
57 namespace, tunable namespace and tunable name, separated by periods.
59 @node Memory Allocation Tunables
60 @section Memory Allocation Tunables
61 @cindex memory allocation tunables
62 @cindex malloc tunables
63 @cindex tunables, malloc
65 @deftp {Tunable namespace} glibc.malloc
66 Memory allocation behavior can be modified by setting any of the
67 following tunables in the @code{malloc} namespace:
70 @deftp Tunable glibc.malloc.check
71 This tunable supersedes the @env{MALLOC_CHECK_} environment variable and is
72 identical in features.
74 Setting this tunable enables a special (less efficient) memory allocator for
75 the malloc family of functions that is designed to be tolerant against simple
76 errors such as double calls of free with the same argument, or overruns of a
77 single byte (off-by-one bugs). Not all such errors can be protected against,
78 however, and memory leaks can result. The following list describes the values
79 that this tunable can take and the effect they have on malloc functionality:
82 @item @code{0} Ignore all errors. The default allocator continues to be in
83 use, but all errors are silently ignored.
84 @item @code{1} Report errors. The alternate allocator is selected and heap
85 corruption, if detected, is reported as diagnostic messages to @code{stderr}
86 and the program continues execution.
87 @item @code{2} Abort on errors. The alternate allocator is selected and if
88 heap corruption is detected, the program is ended immediately by calling
90 @item @code{3} Fully enabled. The alternate allocator is selected and is fully
91 functional. That is, if heap corruption is detected, a verbose diagnostic
92 message is printed to @code{stderr} and the program is ended by calling
96 Like @env{MALLOC_CHECK_}, @code{glibc.malloc.check} has a problem in that it
97 diverges from normal program behavior by writing to @code{stderr}, which could
98 by exploited in SUID and SGID binaries. Therefore, @code{glibc.malloc.check}
99 is disabled by default for SUID and SGID binaries. This can be enabled again
100 by the system administrator by adding a file @file{/etc/suid-debug}; the
101 content of the file could be anything or even empty.
104 @deftp Tunable glibc.malloc.top_pad
105 This tunable supersedes the @env{MALLOC_TOP_PAD_} environment variable and is
106 identical in features.
108 This tunable determines the amount of extra memory in bytes to obtain from the
109 system when any of the arenas need to be extended. It also specifies the
110 number of bytes to retain when shrinking any of the arenas. This provides the
111 necessary hysteresis in heap size such that excessive amounts of system calls
114 The default value of this tunable is @samp{0}.
117 @deftp Tunable glibc.malloc.perturb
118 This tunable supersedes the @env{MALLOC_PERTURB_} environment variable and is
119 identical in features.
121 If set to a non-zero value, memory blocks are initialized with values depending
122 on some low order bits of this tunable when they are allocated (except when
123 allocated by calloc) and freed. This can be used to debug the use of
124 uninitialized or freed heap memory. Note that this option does not guarantee
125 that the freed block will have any specific values. It only guarantees that the
126 content the block had before it was freed will be overwritten.
128 The default value of this tunable is @samp{0}.
131 @deftp Tunable glibc.malloc.mmap_threshold
132 This tunable supersedes the @env{MALLOC_MMAP_THRESHOLD_} environment variable
133 and is identical in features.
135 When this tunable is set, all chunks larger than this value in bytes are
136 allocated outside the normal heap, using the @code{mmap} system call. This way
137 it is guaranteed that the memory for these chunks can be returned to the system
138 on @code{free}. Note that requests smaller than this threshold might still be
139 allocated via @code{mmap}.
141 If this tunable is not set, the default value is set to @samp{131072} bytes and
142 the threshold is adjusted dynamically to suit the allocation patterns of the
143 program. If the tunable is set, the dynamic adjustment is disabled and the
144 value is set as static.
147 @deftp Tunable glibc.malloc.trim_threshold
148 This tunable supersedes the @env{MALLOC_TRIM_THRESHOLD_} environment variable
149 and is identical in features.
151 The value of this tunable is the minimum size (in bytes) of the top-most,
152 releasable chunk in an arena that will trigger a system call in order to return
153 memory to the system from that arena.
155 If this tunable is not set, the default value is set as 128 KB and the
156 threshold is adjusted dynamically to suit the allocation patterns of the
157 program. If the tunable is set, the dynamic adjustment is disabled and the
158 value is set as static.
161 @deftp Tunable glibc.malloc.mmap_max
162 This tunable supersedes the @env{MALLOC_MMAP_MAX_} environment variable and is
163 identical in features.
165 The value of this tunable is maximum number of chunks to allocate with
166 @code{mmap}. Setting this to zero disables all use of @code{mmap}.
168 The default value of this tunable is @samp{65536}.
171 @deftp Tunable glibc.malloc.arena_test
172 This tunable supersedes the @env{MALLOC_ARENA_TEST} environment variable and is
173 identical in features.
175 The @code{glibc.malloc.arena_test} tunable specifies the number of arenas that
176 can be created before the test on the limit to the number of arenas is
177 conducted. The value is ignored if @code{glibc.malloc.arena_max} is set.
179 The default value of this tunable is 2 for 32-bit systems and 8 for 64-bit
183 @deftp Tunable glibc.malloc.arena_max
184 This tunable supersedes the @env{MALLOC_ARENA_MAX} environment variable and is
185 identical in features.
187 This tunable sets the number of arenas to use in a process regardless of the
188 number of cores in the system.
190 The default value of this tunable is @code{0}, meaning that the limit on the
191 number of arenas is determined by the number of CPU cores online. For 32-bit
192 systems the limit is twice the number of cores online and on 64-bit systems, it
193 is 8 times the number of cores online.
196 @node Hardware Capability Tunables
197 @section Hardware Capability Tunables
198 @cindex hardware capability tunables
199 @cindex hwcap tunables
200 @cindex tunables, hwcap
201 @cindex hwcaps tunables
202 @cindex tunables, hwcaps
203 @cindex data_cache_size tunables
204 @cindex tunables, data_cache_size
205 @cindex shared_cache_size tunables
206 @cindex tunables, shared_cache_size
207 @cindex non_temporal_threshold tunables
208 @cindex tunables, non_temporal_threshold
210 @deftp {Tunable namespace} glibc.tune
211 Behavior of @theglibc{} can be tuned to assume specific hardware capabilities
212 by setting the following tunables in the @code{tune} namespace:
215 @deftp Tunable glibc.tune.hwcap_mask
216 This tunable supersedes the @env{LD_HWCAP_MASK} environment variable and is
217 identical in features.
219 The @code{AT_HWCAP} key in the Auxilliary Vector specifies instruction set
220 extensions available in the processor at runtime for some architectures. The
221 @code{glibc.tune.hwcap_mask} tunable allows the user to mask out those
222 capabilities at runtime, thus disabling use of those extensions.
225 @deftp Tunable glibc.tune.hwcaps
226 The @code{glibc.tune.hwcaps=-xxx,yyy,-zzz...} tunable allows the user to
227 enable CPU/ARCH feature @code{yyy}, disable CPU/ARCH feature @code{xxx}
228 and @code{zzz} where the feature name is case-sensitive and has to match
229 the ones in @code{sysdeps/x86/cpu-features.h}.
231 This tunable is specific to i386 and x86-64.
234 @deftp Tunable glibc.tune.cpu
235 The @code{glibc.tune.cpu=xxx} tunable allows the user to tell @theglibc{} to
236 assume that the CPU is @code{xxx} where xxx may have one of these values:
237 @code{generic}, @code{thunderxt88}.
239 This tunable is specific to aarch64.
242 @deftp Tunable glibc.tune.x86_data_cache_size
243 The @code{glibc.tune.x86_data_cache_size} tunable allows the user to set
244 data cache size in bytes for use in memory and string routines.
246 This tunable is specific to i386 and x86-64.
249 @deftp Tunable glibc.tune.x86_shared_cache_size
250 The @code{glibc.tune.x86_shared_cache_size} tunable allows the user to
251 set shared cache size in bytes for use in memory and string routines.
254 @deftp Tunable glibc.tune.x86_non_temporal_threshold
255 The @code{glibc.tune.x86_non_temporal_threshold} tunable allows the user
256 to set threshold in bytes for non temporal store.
258 This tunable is specific to i386 and x86-64.