]>
Commit | Line | Data |
---|---|---|
b31b4d6a SP |
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 |