manual/tunables.texi

   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
   6
   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:
  15
  16 @example
  17 GLIBC_TUNABLES=glibc.malloc.trim_threshold=128:glibc.malloc.check=3
  18 export GLIBC_TUNABLES
  19 @end example
  20
  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.
  26
  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.
  30
  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
  37
  38 @node Tunable names
  39 @section Tunable names
  40 @cindex Tunable names
  41 @cindex Tunable namespaces
  42
  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.
  48
  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.
  52
  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.
  58
  59 @node Memory Allocation Tunables
  60 @section Memory Allocation Tunables
  61 @cindex memory allocation tunables
  62 @cindex malloc tunables
  63 @cindex tunables, malloc
  64
  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
  69
  70 @deftp Tunable glibc.malloc.check
  71 This tunable supersedes the @env{MALLOC_CHECK_} environment variable and is
  72 identical in features.
  73
  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:
  80
  81 @itemize @bullet
  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
  89 @code{abort}.
  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
  93 @code{abort}.
  94 @end itemize
  95
  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.
 102 @end deftp
 103
 104 @deftp Tunable glibc.malloc.top_pad
 105 This tunable supersedes the @env{MALLOC_TOP_PAD_} environment variable and is
 106 identical in features.
 107
 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
 112 can be avoided.
 113
 114 The default value of this tunable is @samp{0}.
 115 @end deftp
 116
 117 @deftp Tunable glibc.malloc.perturb
 118 This tunable supersedes the @env{MALLOC_PERTURB_} environment variable and is
 119 identical in features.
 120
 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.
 127
 128 The default value of this tunable is @samp{0}.
 129 @end deftp
 130
 131 @deftp Tunable glibc.malloc.mmap_threshold
 132 This tunable supersedes the @env{MALLOC_MMAP_THRESHOLD_} environment variable
 133 and is identical in features.
 134
 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}.
 140
 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.
 145 @end deftp
 146
 147 @deftp Tunable glibc.malloc.trim_threshold
 148 This tunable supersedes the @env{MALLOC_TRIM_THRESHOLD_} environment variable
 149 and is identical in features.
 150
 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.
 154
 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.
 159 @end deftp
 160
 161 @deftp Tunable glibc.malloc.mmap_max
 162 This tunable supersedes the @env{MALLOC_MMAP_MAX_} environment variable and is
 163 identical in features.
 164
 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}.
 167
 168 The default value of this tunable is @samp{65536}.
 169 @end deftp
 170
 171 @deftp Tunable glibc.malloc.arena_test
 172 This tunable supersedes the @env{MALLOC_ARENA_TEST} environment variable and is
 173 identical in features.
 174
 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.
 178
 179 The default value of this tunable is 2 for 32-bit systems and 8 for 64-bit
 180 systems.
 181 @end deftp
 182
 183 @deftp Tunable glibc.malloc.arena_max
 184 This tunable supersedes the @env{MALLOC_ARENA_MAX} environment variable and is
 185 identical in features.
 186
 187 This tunable sets the number of arenas to use in a process regardless of the
 188 number of cores in the system.
 189
 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.
 194 @end deftp
 195
 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
 209
 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:
 213 @end deftp
 214
 215 @deftp Tunable glibc.tune.hwcap_mask
 216 This tunable supersedes the @env{LD_HWCAP_MASK} environment variable and is
 217 identical in features.
 218
 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.
 223 @end deftp
 224
 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}.
 230
 231 This tunable is specific to i386 and x86-64.
 232 @end deftp
 233
 234 @deftp Tunable glibc.tune.x86_data_cache_size
 235 The @code{glibc.tune.x86_data_cache_size} tunable allows the user to set
 236 data cache size in bytes for use in memory and string routines.
 237
 238 This tunable is specific to i386 and x86-64.
 239 @end deftp
 240
 241 @deftp Tunable glibc.tune.x86_shared_cache_size
 242 The @code{glibc.tune.x86_shared_cache_size} tunable allows the user to
 243 set shared cache size in bytes for use in memory and string routines.
 244 @end deftp
 245
 246 @deftp Tunable glibc.tune.x86_non_temporal_threshold
 247 The @code{glibc.tune.x86_non_temporal_threshold} tunable allows the user
 248 to set threshold in bytes for non temporal store.
 249
 250 This tunable is specific to i386 and x86-64.
 251 @end deftp