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 @end menu
  35
  36 @node Tunable names
  37 @section Tunable names
  38 @cindex Tunable names
  39 @cindex Tunable namespaces
  40
  41 A tunable name is split into three components, a top namespace, a tunable
  42 namespace and the tunable name. The top namespace for tunables implemented in
  43 @theglibc{} is @code{glibc}. Distributions that choose to add custom tunables
  44 in their maintained versions of @theglibc{} may choose to do so under their own
  45 top namespace.
  46
  47 The tunable namespace is a logical grouping of tunables in a single
  48 module. This currently holds no special significance, although that may
  49 change in the future.
  50
  51 The tunable name is the actual name of the tunable. It is possible that
  52 different tunable namespaces may have tunables within them that have the
  53 same name, likewise for top namespaces. Hence, we only support
  54 identification of tunables by their full name, i.e. with the top
  55 namespace, tunable namespace and tunable name, separated by periods.
  56
  57 @node Memory Allocation Tunables
  58 @section Memory Allocation Tunables
  59 @cindex memory allocation tunables
  60 @cindex malloc tunables
  61 @cindex tunables, malloc
  62
  63 @deftp {Tunable namespace} glibc.malloc
  64 Memory allocation behavior can be modified by setting any of the
  65 following tunables in the @code{malloc} namespace:
  66 @end deftp
  67
  68 @deftp Tunable glibc.malloc.check
  69 This tunable supersedes the @env{MALLOC_CHECK_} environment variable and is
  70 identical in features.
  71
  72 Setting this tunable enables a special (less efficient) memory allocator for
  73 the malloc family of functions that is designed to be tolerant against simple
  74 errors such as double calls of free with the same argument, or overruns of a
  75 single byte (off-by-one bugs). Not all such errors can be protected against,
  76 however, and memory leaks can result.  The following list describes the values
  77 that this tunable can take and the effect they have on malloc functionality:
  78
  79 @itemize @bullet
  80 @item @code{0} Ignore all errors.  The default allocator continues to be in
  81 use, but all errors are silently ignored.
  82 @item @code{1} Report errors.  The alternate allocator is selected and heap
  83 corruption, if detected, is reported as diagnostic messages to @code{stderr}
  84 and the program continues execution.
  85 @item @code{2} Abort on errors.  The alternate allocator is selected and if
  86 heap corruption is detected, the program is ended immediately by calling
  87 @code{abort}.
  88 @item @code{3} Fully enabled.  The alternate allocator is selected and is fully
  89 functional.  That is, if heap corruption is detected, a verbose diagnostic
  90 message is printed to @code{stderr} and the program is ended by calling
  91 @code{abort}.
  92 @end itemize
  93
  94 Like @env{MALLOC_CHECK_}, @code{glibc.malloc.check} has a problem in that it
  95 diverges from normal program behavior by writing to @code{stderr}, which could
  96 by exploited in SUID and SGID binaries.  Therefore, @code{glibc.malloc.check}
  97 is disabled by default for SUID and SGID binaries.  This can be enabled again
  98 by the system administrator by adding a file @file{/etc/suid-debug}; the
  99 content of the file could be anything or even empty.
 100 @end deftp
 101
 102 @deftp Tunable glibc.malloc.top_pad
 103 This tunable supersedes the @env{MALLOC_TOP_PAD_} environment variable and is
 104 identical in features.
 105
 106 This tunable determines the amount of extra memory in bytes to obtain from the
 107 system when any of the arenas need to be extended.  It also specifies the
 108 number of bytes to retain when shrinking any of the arenas.  This provides the
 109 necessary hysteresis in heap size such that excessive amounts of system calls
 110 can be avoided.
 111
 112 The default value of this tunable is @samp{0}.
 113 @end deftp
 114
 115 @deftp Tunable glibc.malloc.perturb
 116 This tunable supersedes the @env{MALLOC_PERTURB_} environment variable and is
 117 identical in features.
 118
 119 If set to a non-zero value, memory blocks are initialized with values depending
 120 on some low order bits of this tunable when they are allocated (except when
 121 allocated by calloc) and freed.  This can be used to debug the use of
 122 uninitialized or freed heap memory. Note that this option does not guarantee
 123 that the freed block will have any specific values. It only guarantees that the
 124 content the block had before it was freed will be overwritten.
 125
 126 The default value of this tunable is @samp{0}.
 127 @end deftp
 128
 129 @deftp Tunable glibc.malloc.mmap_threshold
 130 This tunable supersedes the @env{MALLOC_MMAP_THRESHOLD_} environment variable
 131 and is identical in features.
 132
 133 When this tunable is set, all chunks larger than this value in bytes are
 134 allocated outside the normal heap, using the @code{mmap} system call. This way
 135 it is guaranteed that the memory for these chunks can be returned to the system
 136 on @code{free}. Note that requests smaller than this threshold might still be
 137 allocated via @code{mmap}.
 138
 139 If this tunable is not set, the default value is set to @samp{131072} bytes and
 140 the threshold is adjusted dynamically to suit the allocation patterns of the
 141 program.  If the tunable is set, the dynamic adjustment is disabled and the
 142 value is set as static.
 143 @end deftp
 144
 145 @deftp Tunable glibc.malloc.trim_threshold
 146 This tunable supersedes the @env{MALLOC_TRIM_THRESHOLD_} environment variable
 147 and is identical in features.
 148
 149 The value of this tunable is the minimum size (in bytes) of the top-most,
 150 releasable chunk in an arena that will trigger a system call in order to return
 151 memory to the system from that arena.
 152
 153 If this tunable is not set, the default value is set as 128 KB and the
 154 threshold is adjusted dynamically to suit the allocation patterns of the
 155 program.  If the tunable is set, the dynamic adjustment is disabled and the
 156 value is set as static.
 157 @end deftp
 158
 159 @deftp Tunable glibc.malloc.mmap_max
 160 This tunable supersedes the @env{MALLOC_MMAP_MAX_} environment variable and is
 161 identical in features.
 162
 163 The value of this tunable is maximum number of chunks to allocate with
 164 @code{mmap}.  Setting this to zero disables all use of @code{mmap}.
 165
 166 The default value of this tunable is @samp{65536}.
 167 @end deftp
 168
 169 @deftp Tunable glibc.malloc.arena_test
 170 This tunable supersedes the @env{MALLOC_ARENA_TEST} environment variable and is
 171 identical in features.
 172
 173 The @code{glibc.malloc.arena_test} tunable specifies the number of arenas that
 174 can be created before the test on the limit to the number of arenas is
 175 conducted.  The value is ignored if @code{glibc.malloc.arena_max} is set.
 176
 177 The default value of this tunable is 2 for 32-bit systems and 8 for 64-bit
 178 systems.
 179 @end deftp
 180
 181 @deftp Tunable glibc.malloc.arena_max
 182 This tunable supersedes the @env{MALLOC_ARENA_MAX} environment variable and is
 183 identical in features.
 184
 185 This tunable sets the number of arenas to use in a process regardless of the
 186 number of cores in the system.
 187
 188 The default value of this tunable is @code{0}, meaning that the limit on the
 189 number of arenas is determined by the number of CPU cores online.  For 32-bit
 190 systems the limit is twice the number of cores online and on 64-bit systems, it
 191 is 8 times the number of cores online.
 192 @end deftp