ka_GE locale: Fix yesexp to make it agree with CLDR.
[glibc.git] / manual / tunables.texi
blobf503daef56239acad323698f74382e06194704e6
1 @node Tunables
2 @c @node Tunables, , Internal Probes, Top
3 @c %MENU% Tunable switches to alter libc internal behavior
4 @chapter Tunables
5 @cindex tunables
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
14 bytes:
16 @example
17 GLIBC_TUNABLES=glibc.malloc.trim_threshold=128:glibc.malloc.check=3
18 export GLIBC_TUNABLES
19 @end example
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
29 their own namespace.
31 @menu
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{}
36 @end menu
38 @node Tunable names
39 @section Tunable names
40 @cindex 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
47 top namespace.
49 The tunable namespace is a logical grouping of tunables in a single
50 module. This currently holds no special significance, although that may
51 change in the future.
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:
68 @end deftp
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 to a non-zero value enables a special (less
75 efficient) memory allocator for the malloc family of functions that is
76 designed to be tolerant against simple errors such as double calls of
77 free with the same argument, or overruns of a single byte (off-by-one
78 bugs). Not all such errors can be protected against, however, and memory
79 leaks can result.  Any detected heap corruption results in immediate
80 termination of the process.
82 Like @env{MALLOC_CHECK_}, @code{glibc.malloc.check} has a problem in that it
83 diverges from normal program behavior by writing to @code{stderr}, which could
84 by exploited in SUID and SGID binaries.  Therefore, @code{glibc.malloc.check}
85 is disabled by default for SUID and SGID binaries.  This can be enabled again
86 by the system administrator by adding a file @file{/etc/suid-debug}; the
87 content of the file could be anything or even empty.
88 @end deftp
90 @deftp Tunable glibc.malloc.top_pad
91 This tunable supersedes the @env{MALLOC_TOP_PAD_} environment variable and is
92 identical in features.
94 This tunable determines the amount of extra memory in bytes to obtain from the
95 system when any of the arenas need to be extended.  It also specifies the
96 number of bytes to retain when shrinking any of the arenas.  This provides the
97 necessary hysteresis in heap size such that excessive amounts of system calls
98 can be avoided.
100 The default value of this tunable is @samp{0}.
101 @end deftp
103 @deftp Tunable glibc.malloc.perturb
104 This tunable supersedes the @env{MALLOC_PERTURB_} environment variable and is
105 identical in features.
107 If set to a non-zero value, memory blocks are initialized with values depending
108 on some low order bits of this tunable when they are allocated (except when
109 allocated by calloc) and freed.  This can be used to debug the use of
110 uninitialized or freed heap memory. Note that this option does not guarantee
111 that the freed block will have any specific values. It only guarantees that the
112 content the block had before it was freed will be overwritten.
114 The default value of this tunable is @samp{0}.
115 @end deftp
117 @deftp Tunable glibc.malloc.mmap_threshold
118 This tunable supersedes the @env{MALLOC_MMAP_THRESHOLD_} environment variable
119 and is identical in features.
121 When this tunable is set, all chunks larger than this value in bytes are
122 allocated outside the normal heap, using the @code{mmap} system call. This way
123 it is guaranteed that the memory for these chunks can be returned to the system
124 on @code{free}. Note that requests smaller than this threshold might still be
125 allocated via @code{mmap}.
127 If this tunable is not set, the default value is set to @samp{131072} bytes and
128 the threshold is adjusted dynamically to suit the allocation patterns of the
129 program.  If the tunable is set, the dynamic adjustment is disabled and the
130 value is set as static.
131 @end deftp
133 @deftp Tunable glibc.malloc.trim_threshold
134 This tunable supersedes the @env{MALLOC_TRIM_THRESHOLD_} environment variable
135 and is identical in features.
137 The value of this tunable is the minimum size (in bytes) of the top-most,
138 releasable chunk in an arena that will trigger a system call in order to return
139 memory to the system from that arena.
141 If this tunable is not set, the default value is set as 128 KB and the
142 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.
145 @end deftp
147 @deftp Tunable glibc.malloc.mmap_max
148 This tunable supersedes the @env{MALLOC_MMAP_MAX_} environment variable and is
149 identical in features.
151 The value of this tunable is maximum number of chunks to allocate with
152 @code{mmap}.  Setting this to zero disables all use of @code{mmap}.
154 The default value of this tunable is @samp{65536}.
155 @end deftp
157 @deftp Tunable glibc.malloc.arena_test
158 This tunable supersedes the @env{MALLOC_ARENA_TEST} environment variable and is
159 identical in features.
161 The @code{glibc.malloc.arena_test} tunable specifies the number of arenas that
162 can be created before the test on the limit to the number of arenas is
163 conducted.  The value is ignored if @code{glibc.malloc.arena_max} is set.
165 The default value of this tunable is 2 for 32-bit systems and 8 for 64-bit
166 systems.
167 @end deftp
169 @deftp Tunable glibc.malloc.arena_max
170 This tunable supersedes the @env{MALLOC_ARENA_MAX} environment variable and is
171 identical in features.
173 This tunable sets the number of arenas to use in a process regardless of the
174 number of cores in the system.
176 The default value of this tunable is @code{0}, meaning that the limit on the
177 number of arenas is determined by the number of CPU cores online.  For 32-bit
178 systems the limit is twice the number of cores online and on 64-bit systems, it
179 is 8 times the number of cores online.
180 @end deftp
182 @deftp Tunable glibc.malloc.tcache_max
183 The maximum size of a request (in bytes) which may be met via the
184 per-thread cache.  The default (and maximum) value is 1032 bytes on
185 64-bit systems and 516 bytes on 32-bit systems.
186 @end deftp
188 @deftp Tunable glibc.malloc.tcache_count
189 The maximum number of chunks of each size to cache. The default is 7.
190 There is no upper limit, other than available system memory.  If set
191 to zero, the per-thread cache is effectively disabled.
193 The approximate maximum overhead of the per-thread cache is thus equal
194 to the number of bins times the chunk count in each bin times the size
195 of each chunk.  With defaults, the approximate maximum overhead of the
196 per-thread cache is approximately 236 KB on 64-bit systems and 118 KB
197 on 32-bit systems.
198 @end deftp
200 @deftp Tunable glibc.malloc.tcache_unsorted_limit
201 When the user requests memory and the request cannot be met via the
202 per-thread cache, the arenas are used to meet the request.  At this
203 time, additional chunks will be moved from existing arena lists to
204 pre-fill the corresponding cache.  While copies from the fastbins,
205 smallbins, and regular bins are bounded and predictable due to the bin
206 sizes, copies from the unsorted bin are not bounded, and incur
207 additional time penalties as they need to be sorted as they're
208 scanned.  To make scanning the unsorted list more predictable and
209 bounded, the user may set this tunable to limit the number of chunks
210 that are scanned from the unsorted list while searching for chunks to
211 pre-fill the per-thread cache with.  The default, or when set to zero,
212 is no limit.
213 @end deftp
215 @node Hardware Capability Tunables
216 @section Hardware Capability Tunables
217 @cindex hardware capability tunables
218 @cindex hwcap tunables
219 @cindex tunables, hwcap
220 @cindex hwcaps tunables
221 @cindex tunables, hwcaps
222 @cindex data_cache_size tunables
223 @cindex tunables, data_cache_size
224 @cindex shared_cache_size tunables
225 @cindex tunables, shared_cache_size
226 @cindex non_temporal_threshold tunables
227 @cindex tunables, non_temporal_threshold
229 @deftp {Tunable namespace} glibc.tune
230 Behavior of @theglibc{} can be tuned to assume specific hardware capabilities
231 by setting the following tunables in the @code{tune} namespace:
232 @end deftp
234 @deftp Tunable glibc.tune.hwcap_mask
235 This tunable supersedes the @env{LD_HWCAP_MASK} environment variable and is
236 identical in features.
238 The @code{AT_HWCAP} key in the Auxilliary Vector specifies instruction set
239 extensions available in the processor at runtime for some architectures.  The
240 @code{glibc.tune.hwcap_mask} tunable allows the user to mask out those
241 capabilities at runtime, thus disabling use of those extensions.
242 @end deftp
244 @deftp Tunable glibc.tune.hwcaps
245 The @code{glibc.tune.hwcaps=-xxx,yyy,-zzz...} tunable allows the user to
246 enable CPU/ARCH feature @code{yyy}, disable CPU/ARCH feature @code{xxx}
247 and @code{zzz} where the feature name is case-sensitive and has to match
248 the ones in @code{sysdeps/x86/cpu-features.h}.
250 This tunable is specific to i386 and x86-64.
251 @end deftp
253 @deftp Tunable glibc.tune.cpu
254 The @code{glibc.tune.cpu=xxx} tunable allows the user to tell @theglibc{} to
255 assume that the CPU is @code{xxx} where xxx may have one of these values:
256 @code{generic}, @code{falkor}, @code{thunderxt88}, @code{thunderx2t99},
257 @code{thunderx2t99p1}.
259 This tunable is specific to aarch64.
260 @end deftp
262 @deftp Tunable glibc.tune.x86_data_cache_size
263 The @code{glibc.tune.x86_data_cache_size} tunable allows the user to set
264 data cache size in bytes for use in memory and string routines.
266 This tunable is specific to i386 and x86-64.
267 @end deftp
269 @deftp Tunable glibc.tune.x86_shared_cache_size
270 The @code{glibc.tune.x86_shared_cache_size} tunable allows the user to
271 set shared cache size in bytes for use in memory and string routines.
272 @end deftp
274 @deftp Tunable glibc.tune.x86_non_temporal_threshold
275 The @code{glibc.tune.x86_non_temporal_threshold} tunable allows the user
276 to set threshold in bytes for non temporal store.
278 This tunable is specific to i386 and x86-64.
279 @end deftp