1 <?xml version='
1.0' encoding='UTF-
8'
?>
2 <?xml-stylesheet type=
"text/xsl"
3 href=
"http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
4 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.4//EN"
5 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
10 <title>User Manual
</title>
11 <productname>jemalloc
</productname>
12 <releaseinfo role=
"version">@jemalloc_version@
</releaseinfo>
15 <firstname>Jason
</firstname>
16 <surname>Evans
</surname>
17 <personblurb>Author
</personblurb>
22 <refentrytitle>JEMALLOC
</refentrytitle>
23 <manvolnum>3</manvolnum>
26 <refdescriptor>jemalloc
</refdescriptor>
27 <refname>jemalloc
</refname>
28 <!-- Each refname causes a man page file to be created. Only if this were
29 the system malloc(3) implementation would these files be appropriate.
30 <refname>malloc</refname>
31 <refname>calloc</refname>
32 <refname>posix_memalign</refname>
33 <refname>aligned_alloc</refname>
34 <refname>realloc</refname>
35 <refname>free</refname>
36 <refname>malloc_usable_size</refname>
37 <refname>malloc_stats_print</refname>
38 <refname>mallctl</refname>
39 <refname>mallctlnametomib</refname>
40 <refname>mallctlbymib</refname>
41 <refname>allocm</refname>
42 <refname>rallocm</refname>
43 <refname>sallocm</refname>
44 <refname>dallocm</refname>
45 <refname>nallocm</refname>
47 <refpurpose>general purpose memory allocation functions
</refpurpose>
49 <refsect1 id=
"library">
50 <title>LIBRARY
</title>
51 <para>This manual describes jemalloc @jemalloc_version@. More information
52 can be found at the
<ulink
53 url=
"http://www.canonware.com/jemalloc/">jemalloc website
</ulink>.
</para>
56 <title>SYNOPSIS
</title>
58 <funcsynopsisinfo>#include
<<filename class=
"headerfile">stdlib.h
</filename>>
59 #include
<<filename class=
"headerfile">jemalloc/jemalloc.h
</filename>></funcsynopsisinfo>
61 <title>Standard API
</title>
63 <funcdef>void *
<function>malloc
</function></funcdef>
64 <paramdef>size_t
<parameter>size
</parameter></paramdef>
67 <funcdef>void *
<function>calloc
</function></funcdef>
68 <paramdef>size_t
<parameter>number
</parameter></paramdef>
69 <paramdef>size_t
<parameter>size
</parameter></paramdef>
72 <funcdef>int
<function>posix_memalign
</function></funcdef>
73 <paramdef>void **
<parameter>ptr
</parameter></paramdef>
74 <paramdef>size_t
<parameter>alignment
</parameter></paramdef>
75 <paramdef>size_t
<parameter>size
</parameter></paramdef>
78 <funcdef>void *
<function>aligned_alloc
</function></funcdef>
79 <paramdef>size_t
<parameter>alignment
</parameter></paramdef>
80 <paramdef>size_t
<parameter>size
</parameter></paramdef>
83 <funcdef>void *
<function>realloc
</function></funcdef>
84 <paramdef>void *
<parameter>ptr
</parameter></paramdef>
85 <paramdef>size_t
<parameter>size
</parameter></paramdef>
88 <funcdef>void
<function>free
</function></funcdef>
89 <paramdef>void *
<parameter>ptr
</parameter></paramdef>
93 <title>Non-standard API
</title>
95 <funcdef>size_t
<function>malloc_usable_size
</function></funcdef>
96 <paramdef>const void *
<parameter>ptr
</parameter></paramdef>
99 <funcdef>void
<function>malloc_stats_print
</function></funcdef>
100 <paramdef>void
<parameter>(*write_cb)
</parameter>
101 <funcparams>void *, const char *
</funcparams>
103 <paramdef>void *
<parameter>cbopaque
</parameter></paramdef>
104 <paramdef>const char *
<parameter>opts
</parameter></paramdef>
107 <funcdef>int
<function>mallctl
</function></funcdef>
108 <paramdef>const char *
<parameter>name
</parameter></paramdef>
109 <paramdef>void *
<parameter>oldp
</parameter></paramdef>
110 <paramdef>size_t *
<parameter>oldlenp
</parameter></paramdef>
111 <paramdef>void *
<parameter>newp
</parameter></paramdef>
112 <paramdef>size_t
<parameter>newlen
</parameter></paramdef>
115 <funcdef>int
<function>mallctlnametomib
</function></funcdef>
116 <paramdef>const char *
<parameter>name
</parameter></paramdef>
117 <paramdef>size_t *
<parameter>mibp
</parameter></paramdef>
118 <paramdef>size_t *
<parameter>miblenp
</parameter></paramdef>
121 <funcdef>int
<function>mallctlbymib
</function></funcdef>
122 <paramdef>const size_t *
<parameter>mib
</parameter></paramdef>
123 <paramdef>size_t
<parameter>miblen
</parameter></paramdef>
124 <paramdef>void *
<parameter>oldp
</parameter></paramdef>
125 <paramdef>size_t *
<parameter>oldlenp
</parameter></paramdef>
126 <paramdef>void *
<parameter>newp
</parameter></paramdef>
127 <paramdef>size_t
<parameter>newlen
</parameter></paramdef>
130 <funcdef>void
<function>(*malloc_message)
</function></funcdef>
131 <paramdef>void *
<parameter>cbopaque
</parameter></paramdef>
132 <paramdef>const char *
<parameter>s
</parameter></paramdef>
134 <para><type>const char *
</type><varname>malloc_conf
</varname>;
</para>
137 <title>Experimental API
</title>
139 <funcdef>int
<function>allocm
</function></funcdef>
140 <paramdef>void **
<parameter>ptr
</parameter></paramdef>
141 <paramdef>size_t *
<parameter>rsize
</parameter></paramdef>
142 <paramdef>size_t
<parameter>size
</parameter></paramdef>
143 <paramdef>int
<parameter>flags
</parameter></paramdef>
146 <funcdef>int
<function>rallocm
</function></funcdef>
147 <paramdef>void **
<parameter>ptr
</parameter></paramdef>
148 <paramdef>size_t *
<parameter>rsize
</parameter></paramdef>
149 <paramdef>size_t
<parameter>size
</parameter></paramdef>
150 <paramdef>size_t
<parameter>extra
</parameter></paramdef>
151 <paramdef>int
<parameter>flags
</parameter></paramdef>
154 <funcdef>int
<function>sallocm
</function></funcdef>
155 <paramdef>const void *
<parameter>ptr
</parameter></paramdef>
156 <paramdef>size_t *
<parameter>rsize
</parameter></paramdef>
157 <paramdef>int
<parameter>flags
</parameter></paramdef>
160 <funcdef>int
<function>dallocm
</function></funcdef>
161 <paramdef>void *
<parameter>ptr
</parameter></paramdef>
162 <paramdef>int
<parameter>flags
</parameter></paramdef>
165 <funcdef>int
<function>nallocm
</function></funcdef>
166 <paramdef>size_t *
<parameter>rsize
</parameter></paramdef>
167 <paramdef>size_t
<parameter>size
</parameter></paramdef>
168 <paramdef>int
<parameter>flags
</parameter></paramdef>
173 <refsect1 id=
"description">
174 <title>DESCRIPTION
</title>
176 <title>Standard API
</title>
178 <para>The
<function>malloc
<parameter/></function> function allocates
179 <parameter>size
</parameter> bytes of uninitialized memory. The allocated
180 space is suitably aligned (after possible pointer coercion) for storage
181 of any type of object.
</para>
183 <para>The
<function>calloc
<parameter/></function> function allocates
184 space for
<parameter>number
</parameter> objects, each
185 <parameter>size
</parameter> bytes in length. The result is identical to
186 calling
<function>malloc
<parameter/></function> with an argument of
187 <parameter>number
</parameter> *
<parameter>size
</parameter>, with the
188 exception that the allocated memory is explicitly initialized to zero
191 <para>The
<function>posix_memalign
<parameter/></function> function
192 allocates
<parameter>size
</parameter> bytes of memory such that the
193 allocation's base address is an even multiple of
194 <parameter>alignment
</parameter>, and returns the allocation in the value
195 pointed to by
<parameter>ptr
</parameter>. The requested
196 <parameter>alignment
</parameter> must be a power of
2 at least as large
197 as
<code language=
"C">sizeof(
<type>void *
</type>)
</code>.
</para>
199 <para>The
<function>aligned_alloc
<parameter/></function> function
200 allocates
<parameter>size
</parameter> bytes of memory such that the
201 allocation's base address is an even multiple of
202 <parameter>alignment
</parameter>. The requested
203 <parameter>alignment
</parameter> must be a power of
2. Behavior is
204 undefined if
<parameter>size
</parameter> is not an integral multiple of
205 <parameter>alignment
</parameter>.
</para>
207 <para>The
<function>realloc
<parameter/></function> function changes the
208 size of the previously allocated memory referenced by
209 <parameter>ptr
</parameter> to
<parameter>size
</parameter> bytes. The
210 contents of the memory are unchanged up to the lesser of the new and old
211 sizes. If the new size is larger, the contents of the newly allocated
212 portion of the memory are undefined. Upon success, the memory referenced
213 by
<parameter>ptr
</parameter> is freed and a pointer to the newly
214 allocated memory is returned. Note that
215 <function>realloc
<parameter/></function> may move the memory allocation,
216 resulting in a different return value than
<parameter>ptr
</parameter>.
217 If
<parameter>ptr
</parameter> is
<constant>NULL
</constant>, the
218 <function>realloc
<parameter/></function> function behaves identically to
219 <function>malloc
<parameter/></function> for the specified size.
</para>
221 <para>The
<function>free
<parameter/></function> function causes the
222 allocated memory referenced by
<parameter>ptr
</parameter> to be made
223 available for future allocations. If
<parameter>ptr
</parameter> is
224 <constant>NULL
</constant>, no action occurs.
</para>
227 <title>Non-standard API
</title>
229 <para>The
<function>malloc_usable_size
<parameter/></function> function
230 returns the usable size of the allocation pointed to by
231 <parameter>ptr
</parameter>. The return value may be larger than the size
232 that was requested during allocation. The
233 <function>malloc_usable_size
<parameter/></function> function is not a
234 mechanism for in-place
<function>realloc
<parameter/></function>; rather
235 it is provided solely as a tool for introspection purposes. Any
236 discrepancy between the requested allocation size and the size reported
237 by
<function>malloc_usable_size
<parameter/></function> should not be
238 depended on, since such behavior is entirely implementation-dependent.
241 <para>The
<function>malloc_stats_print
<parameter/></function> function
242 writes human-readable summary statistics via the
243 <parameter>write_cb
</parameter> callback function pointer and
244 <parameter>cbopaque
</parameter> data passed to
245 <parameter>write_cb
</parameter>, or
246 <function>malloc_message
<parameter/></function> if
247 <parameter>write_cb
</parameter> is
<constant>NULL
</constant>. This
248 function can be called repeatedly. General information that never
249 changes during execution can be omitted by specifying
"g" as a character
250 within the
<parameter>opts
</parameter> string. Note that
251 <function>malloc_message
<parameter/></function> uses the
252 <function>mallctl*
<parameter/></function> functions internally, so
253 inconsistent statistics can be reported if multiple threads use these
254 functions simultaneously. If
<option>--enable-stats
</option> is
255 specified during configuration,
“m
” and
“a
” can
256 be specified to omit merged arena and per arena statistics, respectively;
257 “b
” and
“l
” can be specified to omit per size
258 class statistics for bins and large objects, respectively. Unrecognized
259 characters are silently ignored. Note that thread caching may prevent
260 some statistics from being completely up to date, since extra locking
261 would be required to merge counters that track thread cache operations.
264 <para>The
<function>mallctl
<parameter/></function> function provides a
265 general interface for introspecting the memory allocator, as well as
266 setting modifiable parameters and triggering actions. The
267 period-separated
<parameter>name
</parameter> argument specifies a
268 location in a tree-structured namespace; see the
<xref
269 linkend=
"mallctl_namespace" xrefstyle=
"template:%t"/> section for
270 documentation on the tree contents. To read a value, pass a pointer via
271 <parameter>oldp
</parameter> to adequate space to contain the value, and a
272 pointer to its length via
<parameter>oldlenp
</parameter>; otherwise pass
273 <constant>NULL
</constant> and
<constant>NULL
</constant>. Similarly, to
274 write a value, pass a pointer to the value via
275 <parameter>newp
</parameter>, and its length via
276 <parameter>newlen
</parameter>; otherwise pass
<constant>NULL
</constant>
277 and
<constant>0</constant>.
</para>
279 <para>The
<function>mallctlnametomib
<parameter/></function> function
280 provides a way to avoid repeated name lookups for applications that
281 repeatedly query the same portion of the namespace, by translating a name
282 to a
“Management Information Base
” (MIB) that can be passed
283 repeatedly to
<function>mallctlbymib
<parameter/></function>. Upon
284 successful return from
<function>mallctlnametomib
<parameter/></function>,
285 <parameter>mibp
</parameter> contains an array of
286 <parameter>*miblenp
</parameter> integers, where
287 <parameter>*miblenp
</parameter> is the lesser of the number of components
288 in
<parameter>name
</parameter> and the input value of
289 <parameter>*miblenp
</parameter>. Thus it is possible to pass a
290 <parameter>*miblenp
</parameter> that is smaller than the number of
291 period-separated name components, which results in a partial MIB that can
292 be used as the basis for constructing a complete MIB. For name
293 components that are integers (e.g. the
2 in
295 linkend=
"arenas.bin.i.size"><mallctl>arenas.bin
.2.size
</mallctl></link>),
296 the corresponding MIB component will always be that integer. Therefore,
297 it is legitimate to construct code like the following:
<programlisting
298 language=
"C"><![CDATA[
305 mallctl(
"arenas.nbins", &nbins, &len, NULL,
0);
308 mallnametomib(
"arenas.bin.0.size", mib, &miblen);
309 for (i =
0; i < nbins; i++) {
313 len = sizeof(bin_size);
314 mallctlbymib(mib, miblen, &bin_size, &len, NULL,
0);
315 /* Do something with bin_size... */
316 }]]
></programlisting></para>
319 <title>Experimental API
</title>
320 <para>The experimental API is subject to change or removal without regard
321 for backward compatibility. If
<option>--disable-experimental
</option>
322 is specified during configuration, the experimental API is
325 <para>The
<function>allocm
<parameter/></function>,
326 <function>rallocm
<parameter/></function>,
327 <function>sallocm
<parameter/></function>,
328 <function>dallocm
<parameter/></function>, and
329 <function>nallocm
<parameter/></function> functions all have a
330 <parameter>flags
</parameter> argument that can be used to specify
331 options. The functions only check the options that are contextually
332 relevant. Use bitwise or (
<code language=
"C">|
</code>) operations to
333 specify one or more of the following:
336 <term><constant>ALLOCM_LG_ALIGN(
<parameter>la
</parameter>)
339 <listitem><para>Align the memory allocation to start at an address
340 that is a multiple of
<code language=
"C">(
1 <<
341 <parameter>la
</parameter>)
</code>. This macro does not validate
342 that
<parameter>la
</parameter> is within the valid
343 range.
</para></listitem>
346 <term><constant>ALLOCM_ALIGN(
<parameter>a
</parameter>)
349 <listitem><para>Align the memory allocation to start at an address
350 that is a multiple of
<parameter>a
</parameter>, where
351 <parameter>a
</parameter> is a power of two. This macro does not
352 validate that
<parameter>a
</parameter> is a power of
2.
356 <term><constant>ALLOCM_ZERO
</constant></term>
358 <listitem><para>Initialize newly allocated memory to contain zero
359 bytes. In the growing reallocation case, the real size prior to
360 reallocation defines the boundary between untouched bytes and those
361 that are initialized to contain zero bytes. If this option is
362 absent, newly allocated memory is uninitialized.
</para></listitem>
365 <term><constant>ALLOCM_NO_MOVE
</constant></term>
367 <listitem><para>For reallocation, fail rather than moving the
368 object. This constraint can apply to both growth and
369 shrinkage.
</para></listitem>
372 <term><constant>ALLOCM_ARENA(
<parameter>a
</parameter>)
375 <listitem><para>Use the arena specified by the index
376 <parameter>a
</parameter>. This macro does not validate that
377 <parameter>a
</parameter> specifies an arena in the valid
378 range.
</para></listitem>
383 <para>The
<function>allocm
<parameter/></function> function allocates at
384 least
<parameter>size
</parameter> bytes of memory, sets
385 <parameter>*ptr
</parameter> to the base address of the allocation, and
386 sets
<parameter>*rsize
</parameter> to the real size of the allocation if
387 <parameter>rsize
</parameter> is not
<constant>NULL
</constant>. Behavior
388 is undefined if
<parameter>size
</parameter> is
389 <constant>0</constant>.
</para>
391 <para>The
<function>rallocm
<parameter/></function> function resizes the
392 allocation at
<parameter>*ptr
</parameter> to be at least
393 <parameter>size
</parameter> bytes, sets
<parameter>*ptr
</parameter> to
394 the base address of the allocation if it moved, and sets
395 <parameter>*rsize
</parameter> to the real size of the allocation if
396 <parameter>rsize
</parameter> is not
<constant>NULL
</constant>. If
397 <parameter>extra
</parameter> is non-zero, an attempt is made to resize
398 the allocation to be at least
<code
399 language=
"C"><parameter>size
</parameter> +
400 <parameter>extra
</parameter>)
</code> bytes, though inability to allocate
401 the extra byte(s) will not by itself result in failure. Behavior is
402 undefined if
<parameter>size
</parameter> is
<constant>0</constant>, or if
403 <code language=
"C">(
<parameter>size
</parameter> +
404 <parameter>extra
</parameter> >
405 <constant>SIZE_T_MAX
</constant>)
</code>.
</para>
407 <para>The
<function>sallocm
<parameter/></function> function sets
408 <parameter>*rsize
</parameter> to the real size of the allocation.
</para>
410 <para>The
<function>dallocm
<parameter/></function> function causes the
411 memory referenced by
<parameter>ptr
</parameter> to be made available for
412 future allocations.
</para>
414 <para>The
<function>nallocm
<parameter/></function> function allocates no
415 memory, but it performs the same size computation as the
416 <function>allocm
<parameter/></function> function, and if
417 <parameter>rsize
</parameter> is not
<constant>NULL
</constant> it sets
418 <parameter>*rsize
</parameter> to the real size of the allocation that
419 would result from the equivalent
<function>allocm
<parameter/></function>
420 function call. Behavior is undefined if
421 <parameter>size
</parameter> is
<constant>0</constant>.
</para>
424 <refsect1 id=
"tuning">
425 <title>TUNING
</title>
426 <para>Once, when the first call is made to one of the memory allocation
427 routines, the allocator initializes its internals based in part on various
428 options that can be specified at compile- or run-time.
</para>
430 <para>The string pointed to by the global variable
431 <varname>malloc_conf
</varname>, the
“name
” of the file
432 referenced by the symbolic link named
<filename
433 class=
"symlink">/etc/malloc.conf
</filename>, and the value of the
434 environment variable
<envar>MALLOC_CONF
</envar>, will be interpreted, in
435 that order, from left to right as options. Note that
436 <varname>malloc_conf
</varname> may be read before
437 <function>main
<parameter/></function> is entered, so the declaration of
438 <varname>malloc_conf
</varname> should specify an initializer that contains
439 the final value to be read by jemalloc.
<varname>malloc_conf
</varname> is
440 a compile-time setting, whereas
<filename
441 class=
"symlink">/etc/malloc.conf
</filename> and
<envar>MALLOC_CONF
</envar>
442 can be safely set any time prior to program invocation.
</para>
444 <para>An options string is a comma-separated list of option:value pairs.
445 There is one key corresponding to each
<link
446 linkend=
"opt.abort"><mallctl>opt.*
</mallctl></link> mallctl (see the
<xref
447 linkend=
"mallctl_namespace" xrefstyle=
"template:%t"/> section for options
448 documentation). For example,
<literal>abort:true,narenas:
1</literal> sets
449 the
<link linkend=
"opt.abort"><mallctl>opt.abort
</mallctl></link> and
<link
450 linkend=
"opt.narenas"><mallctl>opt.narenas
</mallctl></link> options. Some
451 options have boolean values (true/false), others have integer values (base
452 8,
10, or
16, depending on prefix), and yet others have raw string
455 <refsect1 id=
"implementation_notes">
456 <title>IMPLEMENTATION NOTES
</title>
457 <para>Traditionally, allocators have used
458 <citerefentry><refentrytitle>sbrk
</refentrytitle>
459 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is
460 suboptimal for several reasons, including race conditions, increased
461 fragmentation, and artificial limitations on maximum usable memory. If
462 <option>--enable-dss
</option> is specified during configuration, this
463 allocator uses both
<citerefentry><refentrytitle>mmap
</refentrytitle>
464 <manvolnum>2</manvolnum></citerefentry> and
465 <citerefentry><refentrytitle>sbrk
</refentrytitle>
466 <manvolnum>2</manvolnum></citerefentry>, in that order of preference;
467 otherwise only
<citerefentry><refentrytitle>mmap
</refentrytitle>
468 <manvolnum>2</manvolnum></citerefentry> is used.
</para>
470 <para>This allocator uses multiple arenas in order to reduce lock
471 contention for threaded programs on multi-processor systems. This works
472 well with regard to threading scalability, but incurs some costs. There is
473 a small fixed per-arena overhead, and additionally, arenas manage memory
474 completely independently of each other, which means a small fixed increase
475 in overall memory fragmentation. These overheads are not generally an
476 issue, given the number of arenas normally used. Note that using
477 substantially more arenas than the default is not likely to improve
478 performance, mainly due to reduced cache performance. However, it may make
479 sense to reduce the number of arenas if an application does not make much
480 use of the allocation functions.
</para>
482 <para>In addition to multiple arenas, unless
483 <option>--disable-tcache
</option> is specified during configuration, this
484 allocator supports thread-specific caching for small and large objects, in
485 order to make it possible to completely avoid synchronization for most
486 allocation requests. Such caching allows very fast allocation in the
487 common case, but it increases memory usage and fragmentation, since a
488 bounded number of objects can remain allocated in each thread cache.
</para>
490 <para>Memory is conceptually broken into equal-sized chunks, where the
491 chunk size is a power of two that is greater than the page size. Chunks
492 are always aligned to multiples of the chunk size. This alignment makes it
493 possible to find metadata for user objects very quickly.
</para>
495 <para>User objects are broken into three categories according to size:
496 small, large, and huge. Small objects are smaller than one page. Large
497 objects are smaller than the chunk size. Huge objects are a multiple of
498 the chunk size. Small and large objects are managed by arenas; huge
499 objects are managed separately in a single data structure that is shared by
500 all threads. Huge objects are used by applications infrequently enough
501 that this single data structure is not a scalability issue.
</para>
503 <para>Each chunk that is managed by an arena tracks its contents as runs of
504 contiguous pages (unused, backing a set of small objects, or backing one
505 large object). The combination of chunk alignment and chunk page maps
506 makes it possible to determine all metadata regarding small and large
507 allocations in constant time.
</para>
509 <para>Small objects are managed in groups by page runs. Each run maintains
510 a frontier and free list to track which regions are in use. Allocation
511 requests that are no more than half the quantum (
8 or
16, depending on
512 architecture) are rounded up to the nearest power of two that is at least
513 <code language=
"C">sizeof(
<type>double
</type>)
</code>. All other small
514 object size classes are multiples of the quantum, spaced such that internal
515 fragmentation is limited to approximately
25% for all but the smallest size
516 classes. Allocation requests that are larger than the maximum small size
517 class, but small enough to fit in an arena-managed chunk (see the
<link
518 linkend=
"opt.lg_chunk"><mallctl>opt.lg_chunk
</mallctl></link> option), are
519 rounded up to the nearest run size. Allocation requests that are too large
520 to fit in an arena-managed chunk are rounded up to the nearest multiple of
521 the chunk size.
</para>
523 <para>Allocations are packed tightly together, which can be an issue for
524 multi-threaded applications. If you need to assure that allocations do not
525 suffer from cacheline sharing, round your allocation requests up to the
526 nearest multiple of the cacheline size, or specify cacheline alignment when
529 <para>Assuming
4 MiB chunks,
4 KiB pages, and a
16-byte quantum on a
64-bit
530 system, the size classes in each category are as shown in
<xref
531 linkend=
"size_classes" xrefstyle=
"template:Table %n"/>.
</para>
533 <table xml:
id=
"size_classes" frame=
"all">
534 <title>Size classes
</title>
535 <tgroup cols=
"3" colsep=
"1" rowsep=
"1">
536 <colspec colname=
"c1" align=
"left"/>
537 <colspec colname=
"c2" align=
"right"/>
538 <colspec colname=
"c3" align=
"left"/>
541 <entry>Category
</entry>
542 <entry>Spacing
</entry>
548 <entry morerows=
"6">Small
</entry>
554 <entry>[
16,
32,
48, ...,
128]
</entry>
558 <entry>[
160,
192,
224,
256]
</entry>
562 <entry>[
320,
384,
448,
512]
</entry>
566 <entry>[
640,
768,
896,
1024]
</entry>
570 <entry>[
1280,
1536,
1792,
2048]
</entry>
574 <entry>[
2560,
3072,
3584]
</entry>
579 <entry>[
4 KiB,
8 KiB,
12 KiB, ...,
4072 KiB]
</entry>
584 <entry>[
4 MiB,
8 MiB,
12 MiB, ...]
</entry>
590 <refsect1 id=
"mallctl_namespace">
591 <title>MALLCTL NAMESPACE
</title>
592 <para>The following names are defined in the namespace accessible via the
593 <function>mallctl*
<parameter/></function> functions. Value types are
594 specified in parentheses, their readable/writable statuses are encoded as
595 <literal>rw
</literal>,
<literal>r-
</literal>,
<literal>-w
</literal>, or
596 <literal>--
</literal>, and required build configuration flags follow, if
597 any. A name element encoded as
<literal><i
></literal> or
598 <literal><j
></literal> indicates an integer component, where the
599 integer varies from
0 to some upper value that must be determined via
600 introspection. In the case of
<mallctl>stats.arenas.
<i
>.*
</mallctl>,
601 <literal><i
></literal> equal to
<link
602 linkend=
"arenas.narenas"><mallctl>arenas.narenas
</mallctl></link> can be
603 used to access the summation of statistics from all arenas. Take special
604 note of the
<link linkend=
"epoch"><mallctl>epoch
</mallctl></link> mallctl,
605 which controls refreshing of cached dynamic statistics.
</para>
610 <mallctl>version
</mallctl>
611 (
<type>const char *
</type>)
612 <literal>r-
</literal>
614 <listitem><para>Return the jemalloc version string.
</para></listitem>
617 <varlistentry id=
"epoch">
619 <mallctl>epoch
</mallctl>
620 (
<type>uint64_t
</type>)
621 <literal>rw
</literal>
623 <listitem><para>If a value is passed in, refresh the data from which
624 the
<function>mallctl*
<parameter/></function> functions report values,
625 and increment the epoch. Return the current epoch. This is useful for
626 detecting whether another thread caused a refresh.
</para></listitem>
631 <mallctl>config.debug
</mallctl>
633 <literal>r-
</literal>
635 <listitem><para><option>--enable-debug
</option> was specified during
636 build configuration.
</para></listitem>
641 <mallctl>config.dss
</mallctl>
643 <literal>r-
</literal>
645 <listitem><para><option>--enable-dss
</option> was specified during
646 build configuration.
</para></listitem>
651 <mallctl>config.fill
</mallctl>
653 <literal>r-
</literal>
655 <listitem><para><option>--enable-fill
</option> was specified during
656 build configuration.
</para></listitem>
661 <mallctl>config.lazy_lock
</mallctl>
663 <literal>r-
</literal>
665 <listitem><para><option>--enable-lazy-lock
</option> was specified
666 during build configuration.
</para></listitem>
671 <mallctl>config.mremap
</mallctl>
673 <literal>r-
</literal>
675 <listitem><para><option>--enable-mremap
</option> was specified during
676 build configuration.
</para></listitem>
681 <mallctl>config.munmap
</mallctl>
683 <literal>r-
</literal>
685 <listitem><para><option>--enable-munmap
</option> was specified during
686 build configuration.
</para></listitem>
691 <mallctl>config.prof
</mallctl>
693 <literal>r-
</literal>
695 <listitem><para><option>--enable-prof
</option> was specified during
696 build configuration.
</para></listitem>
701 <mallctl>config.prof_libgcc
</mallctl>
703 <literal>r-
</literal>
705 <listitem><para><option>--disable-prof-libgcc
</option> was not
706 specified during build configuration.
</para></listitem>
711 <mallctl>config.prof_libunwind
</mallctl>
713 <literal>r-
</literal>
715 <listitem><para><option>--enable-prof-libunwind
</option> was specified
716 during build configuration.
</para></listitem>
721 <mallctl>config.stats
</mallctl>
723 <literal>r-
</literal>
725 <listitem><para><option>--enable-stats
</option> was specified during
726 build configuration.
</para></listitem>
731 <mallctl>config.tcache
</mallctl>
733 <literal>r-
</literal>
735 <listitem><para><option>--disable-tcache
</option> was not specified
736 during build configuration.
</para></listitem>
741 <mallctl>config.tls
</mallctl>
743 <literal>r-
</literal>
745 <listitem><para><option>--disable-tls
</option> was not specified during
746 build configuration.
</para></listitem>
751 <mallctl>config.utrace
</mallctl>
753 <literal>r-
</literal>
755 <listitem><para><option>--enable-utrace
</option> was specified during
756 build configuration.
</para></listitem>
761 <mallctl>config.valgrind
</mallctl>
763 <literal>r-
</literal>
765 <listitem><para><option>--enable-valgrind
</option> was specified during
766 build configuration.
</para></listitem>
771 <mallctl>config.xmalloc
</mallctl>
773 <literal>r-
</literal>
775 <listitem><para><option>--enable-xmalloc
</option> was specified during
776 build configuration.
</para></listitem>
779 <varlistentry id=
"opt.abort">
781 <mallctl>opt.abort
</mallctl>
783 <literal>r-
</literal>
785 <listitem><para>Abort-on-warning enabled/disabled. If true, most
786 warnings are fatal. The process will call
787 <citerefentry><refentrytitle>abort
</refentrytitle>
788 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is
789 disabled by default unless
<option>--enable-debug
</option> is
790 specified during configuration, in which case it is enabled by default.
794 <varlistentry id=
"opt.lg_chunk">
796 <mallctl>opt.lg_chunk
</mallctl>
797 (
<type>size_t
</type>)
798 <literal>r-
</literal>
800 <listitem><para>Virtual memory chunk size (log base
2). If a chunk
801 size outside the supported size range is specified, the size is
802 silently clipped to the minimum/maximum supported size. The default
803 chunk size is
4 MiB (
2^
22).
807 <varlistentry id=
"opt.dss">
809 <mallctl>opt.dss
</mallctl>
810 (
<type>const char *
</type>)
811 <literal>r-
</literal>
813 <listitem><para>dss (
<citerefentry><refentrytitle>sbrk
</refentrytitle>
814 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as
815 related to
<citerefentry><refentrytitle>mmap
</refentrytitle>
816 <manvolnum>2</manvolnum></citerefentry> allocation. The following
817 settings are supported:
“disabled
”,
“primary
”,
818 and
“secondary
” (default).
</para></listitem>
821 <varlistentry id=
"opt.narenas">
823 <mallctl>opt.narenas
</mallctl>
824 (
<type>size_t
</type>)
825 <literal>r-
</literal>
827 <listitem><para>Maximum number of arenas to use for automatic
828 multiplexing of threads and arenas. The default is four times the
829 number of CPUs, or one if there is a single CPU.
</para></listitem>
832 <varlistentry id=
"opt.lg_dirty_mult">
834 <mallctl>opt.lg_dirty_mult
</mallctl>
835 (
<type>ssize_t
</type>)
836 <literal>r-
</literal>
838 <listitem><para>Per-arena minimum ratio (log base
2) of active to dirty
839 pages. Some dirty unused pages may be allowed to accumulate, within
840 the limit set by the ratio (or one chunk worth of dirty pages,
841 whichever is greater), before informing the kernel about some of those
842 pages via
<citerefentry><refentrytitle>madvise
</refentrytitle>
843 <manvolnum>2</manvolnum></citerefentry> or a similar system call. This
844 provides the kernel with sufficient information to recycle dirty pages
845 if physical memory becomes scarce and the pages remain unused. The
846 default minimum ratio is
8:
1 (
2^
3:
1); an option value of -
1 will
847 disable dirty page purging.
</para></listitem>
850 <varlistentry id=
"opt.stats_print">
852 <mallctl>opt.stats_print
</mallctl>
854 <literal>r-
</literal>
856 <listitem><para>Enable/disable statistics printing at exit. If
857 enabled, the
<function>malloc_stats_print
<parameter/></function>
858 function is called at program exit via an
859 <citerefentry><refentrytitle>atexit
</refentrytitle>
860 <manvolnum>3</manvolnum></citerefentry> function. If
861 <option>--enable-stats
</option> is specified during configuration, this
862 has the potential to cause deadlock for a multi-threaded process that
863 exits while one or more threads are executing in the memory allocation
864 functions. Therefore, this option should only be used with care; it is
865 primarily intended as a performance tuning aid during application
866 development. This option is disabled by default.
</para></listitem>
869 <varlistentry id=
"opt.junk">
871 <mallctl>opt.junk
</mallctl>
873 <literal>r-
</literal>
874 [
<option>--enable-fill
</option>]
876 <listitem><para>Junk filling enabled/disabled. If enabled, each byte
877 of uninitialized allocated memory will be initialized to
878 <literal>0xa5</literal>. All deallocated memory will be initialized to
879 <literal>0x5a</literal>. This is intended for debugging and will
880 impact performance negatively. This option is disabled by default
881 unless
<option>--enable-debug
</option> is specified during
882 configuration, in which case it is enabled by default unless running
884 url=
"http://valgrind.org/">Valgrind
</ulink>.
</para></listitem>
887 <varlistentry id=
"opt.quarantine">
889 <mallctl>opt.quarantine
</mallctl>
890 (
<type>size_t
</type>)
891 <literal>r-
</literal>
892 [
<option>--enable-fill
</option>]
894 <listitem><para>Per thread quarantine size in bytes. If non-zero, each
895 thread maintains a FIFO object quarantine that stores up to the
896 specified number of bytes of memory. The quarantined memory is not
897 freed until it is released from quarantine, though it is immediately
898 junk-filled if the
<link
899 linkend=
"opt.junk"><mallctl>opt.junk
</mallctl></link> option is
900 enabled. This feature is of particular use in combination with
<ulink
901 url=
"http://valgrind.org/">Valgrind
</ulink>, which can detect attempts
902 to access quarantined objects. This is intended for debugging and will
903 impact performance negatively. The default quarantine size is
0 unless
904 running inside Valgrind, in which case the default is
16
905 MiB.
</para></listitem>
908 <varlistentry id=
"opt.redzone">
910 <mallctl>opt.redzone
</mallctl>
912 <literal>r-
</literal>
913 [
<option>--enable-fill
</option>]
915 <listitem><para>Redzones enabled/disabled. If enabled, small
916 allocations have redzones before and after them. Furthermore, if the
917 <link linkend=
"opt.junk"><mallctl>opt.junk
</mallctl></link> option is
918 enabled, the redzones are checked for corruption during deallocation.
919 However, the primary intended purpose of this feature is to be used in
920 combination with
<ulink url=
"http://valgrind.org/">Valgrind
</ulink>,
921 which needs redzones in order to do effective buffer overflow/underflow
922 detection. This option is intended for debugging and will impact
923 performance negatively. This option is disabled by
924 default unless running inside Valgrind.
</para></listitem>
927 <varlistentry id=
"opt.zero">
929 <mallctl>opt.zero
</mallctl>
931 <literal>r-
</literal>
932 [
<option>--enable-fill
</option>]
934 <listitem><para>Zero filling enabled/disabled. If enabled, each byte
935 of uninitialized allocated memory will be initialized to
0. Note that
936 this initialization only happens once for each byte, so
937 <function>realloc
<parameter/></function> and
938 <function>rallocm
<parameter/></function> calls do not zero memory that
939 was previously allocated. This is intended for debugging and will
940 impact performance negatively. This option is disabled by default.
944 <varlistentry id=
"opt.utrace">
946 <mallctl>opt.utrace
</mallctl>
948 <literal>r-
</literal>
949 [
<option>--enable-utrace
</option>]
951 <listitem><para>Allocation tracing based on
952 <citerefentry><refentrytitle>utrace
</refentrytitle>
953 <manvolnum>2</manvolnum></citerefentry> enabled/disabled. This option
954 is disabled by default.
</para></listitem>
957 <varlistentry id=
"opt.valgrind">
959 <mallctl>opt.valgrind
</mallctl>
961 <literal>r-
</literal>
962 [
<option>--enable-valgrind
</option>]
964 <listitem><para><ulink url=
"http://valgrind.org/">Valgrind
</ulink>
965 support enabled/disabled. This option is vestigal because jemalloc
966 auto-detects whether it is running inside Valgrind. This option is
967 disabled by default, unless running inside Valgrind.
</para></listitem>
970 <varlistentry id=
"opt.xmalloc">
972 <mallctl>opt.xmalloc
</mallctl>
974 <literal>r-
</literal>
975 [
<option>--enable-xmalloc
</option>]
977 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled,
978 rather than returning failure for any allocation function, display a
979 diagnostic message on
<constant>STDERR_FILENO
</constant> and cause the
980 program to drop core (using
981 <citerefentry><refentrytitle>abort
</refentrytitle>
982 <manvolnum>3</manvolnum></citerefentry>). If an application is
983 designed to depend on this behavior, set the option at compile time by
984 including the following in the source code:
985 <programlisting language=
"C"><![CDATA[
986 malloc_conf =
"xmalloc:true";]]
></programlisting>
987 This option is disabled by default.
</para></listitem>
990 <varlistentry id=
"opt.tcache">
992 <mallctl>opt.tcache
</mallctl>
994 <literal>r-
</literal>
995 [
<option>--enable-tcache
</option>]
997 <listitem><para>Thread-specific caching enabled/disabled. When there
998 are multiple threads, each thread uses a thread-specific cache for
999 objects up to a certain size. Thread-specific caching allows many
1000 allocations to be satisfied without performing any thread
1001 synchronization, at the cost of increased memory use. See the
1003 linkend=
"opt.lg_tcache_max"><mallctl>opt.lg_tcache_max
</mallctl></link>
1004 option for related tuning information. This option is enabled by
1005 default unless running inside
<ulink
1006 url=
"http://valgrind.org/">Valgrind
</ulink>.
</para></listitem>
1009 <varlistentry id=
"opt.lg_tcache_max">
1011 <mallctl>opt.lg_tcache_max
</mallctl>
1012 (
<type>size_t
</type>)
1013 <literal>r-
</literal>
1014 [
<option>--enable-tcache
</option>]
1016 <listitem><para>Maximum size class (log base
2) to cache in the
1017 thread-specific cache. At a minimum, all small size classes are
1018 cached, and at a maximum all large size classes are cached. The
1019 default maximum is
32 KiB (
2^
15).
</para></listitem>
1022 <varlistentry id=
"opt.prof">
1024 <mallctl>opt.prof
</mallctl>
1026 <literal>r-
</literal>
1027 [
<option>--enable-prof
</option>]
1029 <listitem><para>Memory profiling enabled/disabled. If enabled, profile
1030 memory allocation activity. See the
<link
1031 linkend=
"opt.prof_active"><mallctl>opt.prof_active
</mallctl></link>
1032 option for on-the-fly activation/deactivation. See the
<link
1033 linkend=
"opt.lg_prof_sample"><mallctl>opt.lg_prof_sample
</mallctl></link>
1034 option for probabilistic sampling control. See the
<link
1035 linkend=
"opt.prof_accum"><mallctl>opt.prof_accum
</mallctl></link>
1036 option for control of cumulative sample reporting. See the
<link
1037 linkend=
"opt.lg_prof_interval"><mallctl>opt.lg_prof_interval
</mallctl></link>
1038 option for information on interval-triggered profile dumping, the
<link
1039 linkend=
"opt.prof_gdump"><mallctl>opt.prof_gdump
</mallctl></link>
1040 option for information on high-water-triggered profile dumping, and the
1041 <link linkend=
"opt.prof_final"><mallctl>opt.prof_final
</mallctl></link>
1042 option for final profile dumping. Profile output is compatible with
1043 the included
<command>pprof
</command> Perl script, which originates
1044 from the
<ulink url=
"http://code.google.com/p/gperftools/">gperftools
1045 package
</ulink>.
</para></listitem>
1048 <varlistentry id=
"opt.prof_prefix">
1050 <mallctl>opt.prof_prefix
</mallctl>
1051 (
<type>const char *
</type>)
1052 <literal>r-
</literal>
1053 [
<option>--enable-prof
</option>]
1055 <listitem><para>Filename prefix for profile dumps. If the prefix is
1056 set to the empty string, no automatic dumps will occur; this is
1057 primarily useful for disabling the automatic final heap dump (which
1058 also disables leak reporting, if enabled). The default prefix is
1059 <filename>jeprof
</filename>.
</para></listitem>
1062 <varlistentry id=
"opt.prof_active">
1064 <mallctl>opt.prof_active
</mallctl>
1066 <literal>r-
</literal>
1067 [
<option>--enable-prof
</option>]
1069 <listitem><para>Profiling activated/deactivated. This is a secondary
1070 control mechanism that makes it possible to start the application with
1071 profiling enabled (see the
<link
1072 linkend=
"opt.prof"><mallctl>opt.prof
</mallctl></link> option) but
1073 inactive, then toggle profiling at any time during program execution
1075 linkend=
"prof.active"><mallctl>prof.active
</mallctl></link> mallctl.
1076 This option is enabled by default.
</para></listitem>
1079 <varlistentry id=
"opt.lg_prof_sample">
1081 <mallctl>opt.lg_prof_sample
</mallctl>
1082 (
<type>ssize_t
</type>)
1083 <literal>r-
</literal>
1084 [
<option>--enable-prof
</option>]
1086 <listitem><para>Average interval (log base
2) between allocation
1087 samples, as measured in bytes of allocation activity. Increasing the
1088 sampling interval decreases profile fidelity, but also decreases the
1089 computational overhead. The default sample interval is
512 KiB (
2^
19
1090 B).
</para></listitem>
1093 <varlistentry id=
"opt.prof_accum">
1095 <mallctl>opt.prof_accum
</mallctl>
1097 <literal>r-
</literal>
1098 [
<option>--enable-prof
</option>]
1100 <listitem><para>Reporting of cumulative object/byte counts in profile
1101 dumps enabled/disabled. If this option is enabled, every unique
1102 backtrace must be stored for the duration of execution. Depending on
1103 the application, this can impose a large memory overhead, and the
1104 cumulative counts are not always of interest. This option is disabled
1105 by default.
</para></listitem>
1108 <varlistentry id=
"opt.lg_prof_interval">
1110 <mallctl>opt.lg_prof_interval
</mallctl>
1111 (
<type>ssize_t
</type>)
1112 <literal>r-
</literal>
1113 [
<option>--enable-prof
</option>]
1115 <listitem><para>Average interval (log base
2) between memory profile
1116 dumps, as measured in bytes of allocation activity. The actual
1117 interval between dumps may be sporadic because decentralized allocation
1118 counters are used to avoid synchronization bottlenecks. Profiles are
1119 dumped to files named according to the pattern
1120 <filename><prefix
>.
<pid
>.
<seq
>.i
<iseq
>.heap
</filename>,
1121 where
<literal><prefix
></literal> is controlled by the
1123 linkend=
"opt.prof_prefix"><mallctl>opt.prof_prefix
</mallctl></link>
1124 option. By default, interval-triggered profile dumping is disabled
1129 <varlistentry id=
"opt.prof_gdump">
1131 <mallctl>opt.prof_gdump
</mallctl>
1133 <literal>r-
</literal>
1134 [
<option>--enable-prof
</option>]
1136 <listitem><para>Trigger a memory profile dump every time the total
1137 virtual memory exceeds the previous maximum. Profiles are dumped to
1138 files named according to the pattern
1139 <filename><prefix
>.
<pid
>.
<seq
>.u
<useq
>.heap
</filename>,
1140 where
<literal><prefix
></literal> is controlled by the
<link
1141 linkend=
"opt.prof_prefix"><mallctl>opt.prof_prefix
</mallctl></link>
1142 option. This option is disabled by default.
</para></listitem>
1145 <varlistentry id=
"opt.prof_final">
1147 <mallctl>opt.prof_final
</mallctl>
1149 <literal>r-
</literal>
1150 [
<option>--enable-prof
</option>]
1152 <listitem><para>Use an
1153 <citerefentry><refentrytitle>atexit
</refentrytitle>
1154 <manvolnum>3</manvolnum></citerefentry> function to dump final memory
1155 usage to a file named according to the pattern
1156 <filename><prefix
>.
<pid
>.
<seq
>.f.heap
</filename>,
1157 where
<literal><prefix
></literal> is controlled by the
<link
1158 linkend=
"opt.prof_prefix"><mallctl>opt.prof_prefix
</mallctl></link>
1159 option. This option is enabled by default.
</para></listitem>
1162 <varlistentry id=
"opt.prof_leak">
1164 <mallctl>opt.prof_leak
</mallctl>
1166 <literal>r-
</literal>
1167 [
<option>--enable-prof
</option>]
1169 <listitem><para>Leak reporting enabled/disabled. If enabled, use an
1170 <citerefentry><refentrytitle>atexit
</refentrytitle>
1171 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks
1172 detected by allocation sampling. See the
1173 <link linkend=
"opt.prof"><mallctl>opt.prof
</mallctl></link> option for
1174 information on analyzing heap profile output. This option is disabled
1175 by default.
</para></listitem>
1180 <mallctl>thread.arena
</mallctl>
1181 (
<type>unsigned
</type>)
1182 <literal>rw
</literal>
1184 <listitem><para>Get or set the arena associated with the calling
1185 thread. If the specified arena was not initialized beforehand (see the
1187 linkend=
"arenas.initialized"><mallctl>arenas.initialized
</mallctl></link>
1188 mallctl), it will be automatically initialized as a side effect of
1189 calling this interface.
</para></listitem>
1192 <varlistentry id=
"thread.allocated">
1194 <mallctl>thread.allocated
</mallctl>
1195 (
<type>uint64_t
</type>)
1196 <literal>r-
</literal>
1197 [
<option>--enable-stats
</option>]
1199 <listitem><para>Get the total number of bytes ever allocated by the
1200 calling thread. This counter has the potential to wrap around; it is
1201 up to the application to appropriately interpret the counter in such
1202 cases.
</para></listitem>
1207 <mallctl>thread.allocatedp
</mallctl>
1208 (
<type>uint64_t *
</type>)
1209 <literal>r-
</literal>
1210 [
<option>--enable-stats
</option>]
1212 <listitem><para>Get a pointer to the the value that is returned by the
1214 linkend=
"thread.allocated"><mallctl>thread.allocated
</mallctl></link>
1215 mallctl. This is useful for avoiding the overhead of repeated
1216 <function>mallctl*
<parameter/></function> calls.
</para></listitem>
1219 <varlistentry id=
"thread.deallocated">
1221 <mallctl>thread.deallocated
</mallctl>
1222 (
<type>uint64_t
</type>)
1223 <literal>r-
</literal>
1224 [
<option>--enable-stats
</option>]
1226 <listitem><para>Get the total number of bytes ever deallocated by the
1227 calling thread. This counter has the potential to wrap around; it is
1228 up to the application to appropriately interpret the counter in such
1229 cases.
</para></listitem>
1234 <mallctl>thread.deallocatedp
</mallctl>
1235 (
<type>uint64_t *
</type>)
1236 <literal>r-
</literal>
1237 [
<option>--enable-stats
</option>]
1239 <listitem><para>Get a pointer to the the value that is returned by the
1241 linkend=
"thread.deallocated"><mallctl>thread.deallocated
</mallctl></link>
1242 mallctl. This is useful for avoiding the overhead of repeated
1243 <function>mallctl*
<parameter/></function> calls.
</para></listitem>
1248 <mallctl>thread.tcache.enabled
</mallctl>
1250 <literal>rw
</literal>
1251 [
<option>--enable-tcache
</option>]
1253 <listitem><para>Enable/disable calling thread's tcache. The tcache is
1254 implicitly flushed as a side effect of becoming
1256 lenkend=
"thread.tcache.flush"><mallctl>thread.tcache.flush
</mallctl></link>).
1262 <mallctl>thread.tcache.flush
</mallctl>
1264 <literal>--
</literal>
1265 [
<option>--enable-tcache
</option>]
1267 <listitem><para>Flush calling thread's tcache. This interface releases
1268 all cached objects and internal data structures associated with the
1269 calling thread's thread-specific cache. Ordinarily, this interface
1270 need not be called, since automatic periodic incremental garbage
1271 collection occurs, and the thread cache is automatically discarded when
1272 a thread exits. However, garbage collection is triggered by allocation
1273 activity, so it is possible for a thread that stops
1274 allocating/deallocating to retain its cache indefinitely, in which case
1275 the developer may find manual flushing useful.
</para></listitem>
1278 <varlistentry id=
"arena.i.purge">
1280 <mallctl>arena.
<i
>.purge
</mallctl>
1281 (
<type>unsigned
</type>)
1282 <literal>--
</literal>
1284 <listitem><para>Purge unused dirty pages for arena
<i
>, or for
1285 all arenas if
<i
> equals
<link
1286 linkend=
"arenas.narenas"><mallctl>arenas.narenas
</mallctl></link>.
1290 <varlistentry id=
"arena.i.dss">
1292 <mallctl>arena.
<i
>.dss
</mallctl>
1293 (
<type>const char *
</type>)
1294 <literal>rw
</literal>
1296 <listitem><para>Set the precedence of dss allocation as related to mmap
1297 allocation for arena
<i
>, or for all arenas if
<i
> equals
1299 linkend=
"arenas.narenas"><mallctl>arenas.narenas
</mallctl></link>. See
1300 <link linkend=
"opt.dss"><mallctl>opt.dss
</mallctl></link> for supported
1305 <varlistentry id=
"arenas.narenas">
1307 <mallctl>arenas.narenas
</mallctl>
1308 (
<type>unsigned
</type>)
1309 <literal>r-
</literal>
1311 <listitem><para>Current limit on number of arenas.
</para></listitem>
1314 <varlistentry id=
"arenas.initialized">
1316 <mallctl>arenas.initialized
</mallctl>
1317 (
<type>bool *
</type>)
1318 <literal>r-
</literal>
1320 <listitem><para>An array of
<link
1321 linkend=
"arenas.narenas"><mallctl>arenas.narenas
</mallctl></link>
1322 booleans. Each boolean indicates whether the corresponding arena is
1323 initialized.
</para></listitem>
1328 <mallctl>arenas.quantum
</mallctl>
1329 (
<type>size_t
</type>)
1330 <literal>r-
</literal>
1332 <listitem><para>Quantum size.
</para></listitem>
1337 <mallctl>arenas.page
</mallctl>
1338 (
<type>size_t
</type>)
1339 <literal>r-
</literal>
1341 <listitem><para>Page size.
</para></listitem>
1346 <mallctl>arenas.tcache_max
</mallctl>
1347 (
<type>size_t
</type>)
1348 <literal>r-
</literal>
1349 [
<option>--enable-tcache
</option>]
1351 <listitem><para>Maximum thread-cached size class.
</para></listitem>
1356 <mallctl>arenas.nbins
</mallctl>
1357 (
<type>unsigned
</type>)
1358 <literal>r-
</literal>
1360 <listitem><para>Number of bin size classes.
</para></listitem>
1365 <mallctl>arenas.nhbins
</mallctl>
1366 (
<type>unsigned
</type>)
1367 <literal>r-
</literal>
1368 [
<option>--enable-tcache
</option>]
1370 <listitem><para>Total number of thread cache bin size
1371 classes.
</para></listitem>
1374 <varlistentry id=
"arenas.bin.i.size">
1376 <mallctl>arenas.bin.
<i
>.size
</mallctl>
1377 (
<type>size_t
</type>)
1378 <literal>r-
</literal>
1380 <listitem><para>Maximum size supported by size class.
</para></listitem>
1385 <mallctl>arenas.bin.
<i
>.nregs
</mallctl>
1386 (
<type>uint32_t
</type>)
1387 <literal>r-
</literal>
1389 <listitem><para>Number of regions per page run.
</para></listitem>
1394 <mallctl>arenas.bin.
<i
>.run_size
</mallctl>
1395 (
<type>size_t
</type>)
1396 <literal>r-
</literal>
1398 <listitem><para>Number of bytes per page run.
</para></listitem>
1403 <mallctl>arenas.nlruns
</mallctl>
1404 (
<type>size_t
</type>)
1405 <literal>r-
</literal>
1407 <listitem><para>Total number of large size classes.
</para></listitem>
1412 <mallctl>arenas.lrun.
<i
>.size
</mallctl>
1413 (
<type>size_t
</type>)
1414 <literal>r-
</literal>
1416 <listitem><para>Maximum size supported by this large size
1417 class.
</para></listitem>
1422 <mallctl>arenas.purge
</mallctl>
1423 (
<type>unsigned
</type>)
1424 <literal>-w
</literal>
1426 <listitem><para>Purge unused dirty pages for the specified arena, or
1427 for all arenas if none is specified.
</para></listitem>
1432 <mallctl>arenas.extend
</mallctl>
1433 (
<type>unsigned
</type>)
1434 <literal>r-
</literal>
1436 <listitem><para>Extend the array of arenas by appending a new arena,
1437 and returning the new arena index.
</para></listitem>
1440 <varlistentry id=
"prof.active">
1442 <mallctl>prof.active
</mallctl>
1444 <literal>rw
</literal>
1445 [
<option>--enable-prof
</option>]
1447 <listitem><para>Control whether sampling is currently active. See the
1449 linkend=
"opt.prof_active"><mallctl>opt.prof_active
</mallctl></link>
1450 option for additional information.
1456 <mallctl>prof.dump
</mallctl>
1457 (
<type>const char *
</type>)
1458 <literal>-w
</literal>
1459 [
<option>--enable-prof
</option>]
1461 <listitem><para>Dump a memory profile to the specified file, or if NULL
1462 is specified, to a file according to the pattern
1463 <filename><prefix
>.
<pid
>.
<seq
>.m
<mseq
>.heap
</filename>,
1464 where
<literal><prefix
></literal> is controlled by the
1466 linkend=
"opt.prof_prefix"><mallctl>opt.prof_prefix
</mallctl></link>
1467 option.
</para></listitem>
1472 <mallctl>prof.interval
</mallctl>
1473 (
<type>uint64_t
</type>)
1474 <literal>r-
</literal>
1475 [
<option>--enable-prof
</option>]
1477 <listitem><para>Average number of bytes allocated between
1478 inverval-based profile dumps. See the
1480 linkend=
"opt.lg_prof_interval"><mallctl>opt.lg_prof_interval
</mallctl></link>
1481 option for additional information.
</para></listitem>
1484 <varlistentry id=
"stats.cactive">
1486 <mallctl>stats.cactive
</mallctl>
1487 (
<type>size_t *
</type>)
1488 <literal>r-
</literal>
1489 [
<option>--enable-stats
</option>]
1491 <listitem><para>Pointer to a counter that contains an approximate count
1492 of the current number of bytes in active pages. The estimate may be
1493 high, but never low, because each arena rounds up to the nearest
1494 multiple of the chunk size when computing its contribution to the
1495 counter. Note that the
<link
1496 linkend=
"epoch"><mallctl>epoch
</mallctl></link> mallctl has no bearing
1497 on this counter. Furthermore, counter consistency is maintained via
1498 atomic operations, so it is necessary to use an atomic operation in
1499 order to guarantee a consistent read when dereferencing the pointer.
1503 <varlistentry id=
"stats.allocated">
1505 <mallctl>stats.allocated
</mallctl>
1506 (
<type>size_t
</type>)
1507 <literal>r-
</literal>
1508 [
<option>--enable-stats
</option>]
1510 <listitem><para>Total number of bytes allocated by the
1511 application.
</para></listitem>
1514 <varlistentry id=
"stats.active">
1516 <mallctl>stats.active
</mallctl>
1517 (
<type>size_t
</type>)
1518 <literal>r-
</literal>
1519 [
<option>--enable-stats
</option>]
1521 <listitem><para>Total number of bytes in active pages allocated by the
1522 application. This is a multiple of the page size, and greater than or
1524 linkend=
"stats.allocated"><mallctl>stats.allocated
</mallctl></link>.
1525 This does not include
<link linkend=
"stats.arenas.i.pdirty">
1526 <mallctl>stats.arenas.
<i
>.pdirty
</mallctl></link> and pages
1527 entirely devoted to allocator metadata.
</para></listitem>
1532 <mallctl>stats.mapped
</mallctl>
1533 (
<type>size_t
</type>)
1534 <literal>r-
</literal>
1535 [
<option>--enable-stats
</option>]
1537 <listitem><para>Total number of bytes in chunks mapped on behalf of the
1538 application. This is a multiple of the chunk size, and is at least as
1540 linkend=
"stats.active"><mallctl>stats.active
</mallctl></link>. This
1541 does not include inactive chunks.
</para></listitem>
1546 <mallctl>stats.chunks.current
</mallctl>
1547 (
<type>size_t
</type>)
1548 <literal>r-
</literal>
1549 [
<option>--enable-stats
</option>]
1551 <listitem><para>Total number of chunks actively mapped on behalf of the
1552 application. This does not include inactive chunks.
1558 <mallctl>stats.chunks.total
</mallctl>
1559 (
<type>uint64_t
</type>)
1560 <literal>r-
</literal>
1561 [
<option>--enable-stats
</option>]
1563 <listitem><para>Cumulative number of chunks allocated.
</para></listitem>
1568 <mallctl>stats.chunks.high
</mallctl>
1569 (
<type>size_t
</type>)
1570 <literal>r-
</literal>
1571 [
<option>--enable-stats
</option>]
1573 <listitem><para>Maximum number of active chunks at any time thus far.
1579 <mallctl>stats.huge.allocated
</mallctl>
1580 (
<type>size_t
</type>)
1581 <literal>r-
</literal>
1582 [
<option>--enable-stats
</option>]
1584 <listitem><para>Number of bytes currently allocated by huge objects.
1590 <mallctl>stats.huge.nmalloc
</mallctl>
1591 (
<type>uint64_t
</type>)
1592 <literal>r-
</literal>
1593 [
<option>--enable-stats
</option>]
1595 <listitem><para>Cumulative number of huge allocation requests.
1601 <mallctl>stats.huge.ndalloc
</mallctl>
1602 (
<type>uint64_t
</type>)
1603 <literal>r-
</literal>
1604 [
<option>--enable-stats
</option>]
1606 <listitem><para>Cumulative number of huge deallocation requests.
1612 <mallctl>stats.arenas.
<i
>.dss
</mallctl>
1613 (
<type>const char *
</type>)
1614 <literal>r-
</literal>
1616 <listitem><para>dss (
<citerefentry><refentrytitle>sbrk
</refentrytitle>
1617 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as
1618 related to
<citerefentry><refentrytitle>mmap
</refentrytitle>
1619 <manvolnum>2</manvolnum></citerefentry> allocation. See
<link
1620 linkend=
"opt.dss"><mallctl>opt.dss
</mallctl></link> for details.
1626 <mallctl>stats.arenas.
<i
>.nthreads
</mallctl>
1627 (
<type>unsigned
</type>)
1628 <literal>r-
</literal>
1630 <listitem><para>Number of threads currently assigned to
1631 arena.
</para></listitem>
1636 <mallctl>stats.arenas.
<i
>.pactive
</mallctl>
1637 (
<type>size_t
</type>)
1638 <literal>r-
</literal>
1640 <listitem><para>Number of pages in active runs.
</para></listitem>
1643 <varlistentry id=
"stats.arenas.i.pdirty">
1645 <mallctl>stats.arenas.
<i
>.pdirty
</mallctl>
1646 (
<type>size_t
</type>)
1647 <literal>r-
</literal>
1649 <listitem><para>Number of pages within unused runs that are potentially
1650 dirty, and for which
<function>madvise
<parameter>...
</parameter>
1651 <parameter><constant>MADV_DONTNEED
</constant></parameter></function> or
1652 similar has not been called.
</para></listitem>
1657 <mallctl>stats.arenas.
<i
>.mapped
</mallctl>
1658 (
<type>size_t
</type>)
1659 <literal>r-
</literal>
1660 [
<option>--enable-stats
</option>]
1662 <listitem><para>Number of mapped bytes.
</para></listitem>
1667 <mallctl>stats.arenas.
<i
>.npurge
</mallctl>
1668 (
<type>uint64_t
</type>)
1669 <literal>r-
</literal>
1670 [
<option>--enable-stats
</option>]
1672 <listitem><para>Number of dirty page purge sweeps performed.
1678 <mallctl>stats.arenas.
<i
>.nmadvise
</mallctl>
1679 (
<type>uint64_t
</type>)
1680 <literal>r-
</literal>
1681 [
<option>--enable-stats
</option>]
1683 <listitem><para>Number of
<function>madvise
<parameter>...
</parameter>
1684 <parameter><constant>MADV_DONTNEED
</constant></parameter></function> or
1685 similar calls made to purge dirty pages.
</para></listitem>
1690 <mallctl>stats.arenas.
<i
>.npurged
</mallctl>
1691 (
<type>uint64_t
</type>)
1692 <literal>r-
</literal>
1693 [
<option>--enable-stats
</option>]
1695 <listitem><para>Number of pages purged.
</para></listitem>
1700 <mallctl>stats.arenas.
<i
>.small.allocated
</mallctl>
1701 (
<type>size_t
</type>)
1702 <literal>r-
</literal>
1703 [
<option>--enable-stats
</option>]
1705 <listitem><para>Number of bytes currently allocated by small objects.
1711 <mallctl>stats.arenas.
<i
>.small.nmalloc
</mallctl>
1712 (
<type>uint64_t
</type>)
1713 <literal>r-
</literal>
1714 [
<option>--enable-stats
</option>]
1716 <listitem><para>Cumulative number of allocation requests served by
1717 small bins.
</para></listitem>
1722 <mallctl>stats.arenas.
<i
>.small.ndalloc
</mallctl>
1723 (
<type>uint64_t
</type>)
1724 <literal>r-
</literal>
1725 [
<option>--enable-stats
</option>]
1727 <listitem><para>Cumulative number of small objects returned to bins.
1733 <mallctl>stats.arenas.
<i
>.small.nrequests
</mallctl>
1734 (
<type>uint64_t
</type>)
1735 <literal>r-
</literal>
1736 [
<option>--enable-stats
</option>]
1738 <listitem><para>Cumulative number of small allocation requests.
1744 <mallctl>stats.arenas.
<i
>.large.allocated
</mallctl>
1745 (
<type>size_t
</type>)
1746 <literal>r-
</literal>
1747 [
<option>--enable-stats
</option>]
1749 <listitem><para>Number of bytes currently allocated by large objects.
1755 <mallctl>stats.arenas.
<i
>.large.nmalloc
</mallctl>
1756 (
<type>uint64_t
</type>)
1757 <literal>r-
</literal>
1758 [
<option>--enable-stats
</option>]
1760 <listitem><para>Cumulative number of large allocation requests served
1761 directly by the arena.
</para></listitem>
1766 <mallctl>stats.arenas.
<i
>.large.ndalloc
</mallctl>
1767 (
<type>uint64_t
</type>)
1768 <literal>r-
</literal>
1769 [
<option>--enable-stats
</option>]
1771 <listitem><para>Cumulative number of large deallocation requests served
1772 directly by the arena.
</para></listitem>
1777 <mallctl>stats.arenas.
<i
>.large.nrequests
</mallctl>
1778 (
<type>uint64_t
</type>)
1779 <literal>r-
</literal>
1780 [
<option>--enable-stats
</option>]
1782 <listitem><para>Cumulative number of large allocation requests.
1788 <mallctl>stats.arenas.
<i
>.bins.
<j
>.allocated
</mallctl>
1789 (
<type>size_t
</type>)
1790 <literal>r-
</literal>
1791 [
<option>--enable-stats
</option>]
1793 <listitem><para>Current number of bytes allocated by
1794 bin.
</para></listitem>
1799 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nmalloc
</mallctl>
1800 (
<type>uint64_t
</type>)
1801 <literal>r-
</literal>
1802 [
<option>--enable-stats
</option>]
1804 <listitem><para>Cumulative number of allocations served by bin.
1810 <mallctl>stats.arenas.
<i
>.bins.
<j
>.ndalloc
</mallctl>
1811 (
<type>uint64_t
</type>)
1812 <literal>r-
</literal>
1813 [
<option>--enable-stats
</option>]
1815 <listitem><para>Cumulative number of allocations returned to bin.
1821 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nrequests
</mallctl>
1822 (
<type>uint64_t
</type>)
1823 <literal>r-
</literal>
1824 [
<option>--enable-stats
</option>]
1826 <listitem><para>Cumulative number of allocation
1827 requests.
</para></listitem>
1832 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nfills
</mallctl>
1833 (
<type>uint64_t
</type>)
1834 <literal>r-
</literal>
1835 [
<option>--enable-stats
</option> <option>--enable-tcache
</option>]
1837 <listitem><para>Cumulative number of tcache fills.
</para></listitem>
1842 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nflushes
</mallctl>
1843 (
<type>uint64_t
</type>)
1844 <literal>r-
</literal>
1845 [
<option>--enable-stats
</option> <option>--enable-tcache
</option>]
1847 <listitem><para>Cumulative number of tcache flushes.
</para></listitem>
1852 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nruns
</mallctl>
1853 (
<type>uint64_t
</type>)
1854 <literal>r-
</literal>
1855 [
<option>--enable-stats
</option>]
1857 <listitem><para>Cumulative number of runs created.
</para></listitem>
1862 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nreruns
</mallctl>
1863 (
<type>uint64_t
</type>)
1864 <literal>r-
</literal>
1865 [
<option>--enable-stats
</option>]
1867 <listitem><para>Cumulative number of times the current run from which
1868 to allocate changed.
</para></listitem>
1873 <mallctl>stats.arenas.
<i
>.bins.
<j
>.curruns
</mallctl>
1874 (
<type>size_t
</type>)
1875 <literal>r-
</literal>
1876 [
<option>--enable-stats
</option>]
1878 <listitem><para>Current number of runs.
</para></listitem>
1883 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.nmalloc
</mallctl>
1884 (
<type>uint64_t
</type>)
1885 <literal>r-
</literal>
1886 [
<option>--enable-stats
</option>]
1888 <listitem><para>Cumulative number of allocation requests for this size
1889 class served directly by the arena.
</para></listitem>
1894 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.ndalloc
</mallctl>
1895 (
<type>uint64_t
</type>)
1896 <literal>r-
</literal>
1897 [
<option>--enable-stats
</option>]
1899 <listitem><para>Cumulative number of deallocation requests for this
1900 size class served directly by the arena.
</para></listitem>
1905 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.nrequests
</mallctl>
1906 (
<type>uint64_t
</type>)
1907 <literal>r-
</literal>
1908 [
<option>--enable-stats
</option>]
1910 <listitem><para>Cumulative number of allocation requests for this size
1911 class.
</para></listitem>
1916 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.curruns
</mallctl>
1917 (
<type>size_t
</type>)
1918 <literal>r-
</literal>
1919 [
<option>--enable-stats
</option>]
1921 <listitem><para>Current number of runs for this size class.
1926 <refsect1 id=
"debugging_malloc_problems">
1927 <title>DEBUGGING MALLOC PROBLEMS
</title>
1928 <para>When debugging, it is a good idea to configure/build jemalloc with
1929 the
<option>--enable-debug
</option> and
<option>--enable-fill
</option>
1930 options, and recompile the program with suitable options and symbols for
1931 debugger support. When so configured, jemalloc incorporates a wide variety
1932 of run-time assertions that catch application errors such as double-free,
1933 write-after-free, etc.
</para>
1935 <para>Programs often accidentally depend on
“uninitialized
”
1936 memory actually being filled with zero bytes. Junk filling
1937 (see the
<link linkend=
"opt.junk"><mallctl>opt.junk
</mallctl></link>
1938 option) tends to expose such bugs in the form of obviously incorrect
1939 results and/or coredumps. Conversely, zero
1940 filling (see the
<link
1941 linkend=
"opt.zero"><mallctl>opt.zero
</mallctl></link> option) eliminates
1942 the symptoms of such bugs. Between these two options, it is usually
1943 possible to quickly detect, diagnose, and eliminate such bugs.
</para>
1945 <para>This implementation does not provide much detail about the problems
1946 it detects, because the performance impact for storing such information
1947 would be prohibitive. However, jemalloc does integrate with the most
1948 excellent
<ulink url=
"http://valgrind.org/">Valgrind
</ulink> tool if the
1949 <option>--enable-valgrind
</option> configuration option is enabled.
</para>
1951 <refsect1 id=
"diagnostic_messages">
1952 <title>DIAGNOSTIC MESSAGES
</title>
1953 <para>If any of the memory allocation/deallocation functions detect an
1954 error or warning condition, a message will be printed to file descriptor
1955 <constant>STDERR_FILENO
</constant>. Errors will result in the process
1956 dumping core. If the
<link
1957 linkend=
"opt.abort"><mallctl>opt.abort
</mallctl></link> option is set, most
1958 warnings are treated as errors.
</para>
1960 <para>The
<varname>malloc_message
</varname> variable allows the programmer
1961 to override the function which emits the text strings forming the errors
1962 and warnings if for some reason the
<constant>STDERR_FILENO
</constant> file
1963 descriptor is not suitable for this.
1964 <function>malloc_message
<parameter/></function> takes the
1965 <parameter>cbopaque
</parameter> pointer argument that is
1966 <constant>NULL
</constant> unless overridden by the arguments in a call to
1967 <function>malloc_stats_print
<parameter/></function>, followed by a string
1968 pointer. Please note that doing anything which tries to allocate memory in
1969 this function is likely to result in a crash or deadlock.
</para>
1971 <para>All messages are prefixed by
1972 “<computeroutput><jemalloc
>:
</computeroutput>”.
</para>
1974 <refsect1 id=
"return_values">
1975 <title>RETURN VALUES
</title>
1977 <title>Standard API
</title>
1978 <para>The
<function>malloc
<parameter/></function> and
1979 <function>calloc
<parameter/></function> functions return a pointer to the
1980 allocated memory if successful; otherwise a
<constant>NULL
</constant>
1981 pointer is returned and
<varname>errno
</varname> is set to
1982 <errorname>ENOMEM
</errorname>.
</para>
1984 <para>The
<function>posix_memalign
<parameter/></function> function
1985 returns the value
0 if successful; otherwise it returns an error value.
1986 The
<function>posix_memalign
<parameter/></function> function will fail
1990 <term><errorname>EINVAL
</errorname></term>
1992 <listitem><para>The
<parameter>alignment
</parameter> parameter is
1993 not a power of
2 at least as large as
1994 <code language=
"C">sizeof(
<type>void *
</type>)
</code>.
1998 <term><errorname>ENOMEM
</errorname></term>
2000 <listitem><para>Memory allocation error.
</para></listitem>
2005 <para>The
<function>aligned_alloc
<parameter/></function> function returns
2006 a pointer to the allocated memory if successful; otherwise a
2007 <constant>NULL
</constant> pointer is returned and
2008 <varname>errno
</varname> is set. The
2009 <function>aligned_alloc
<parameter/></function> function will fail if:
2012 <term><errorname>EINVAL
</errorname></term>
2014 <listitem><para>The
<parameter>alignment
</parameter> parameter is
2019 <term><errorname>ENOMEM
</errorname></term>
2021 <listitem><para>Memory allocation error.
</para></listitem>
2026 <para>The
<function>realloc
<parameter/></function> function returns a
2027 pointer, possibly identical to
<parameter>ptr
</parameter>, to the
2028 allocated memory if successful; otherwise a
<constant>NULL
</constant>
2029 pointer is returned, and
<varname>errno
</varname> is set to
2030 <errorname>ENOMEM
</errorname> if the error was the result of an
2031 allocation failure. The
<function>realloc
<parameter/></function>
2032 function always leaves the original buffer intact when an error occurs.
2035 <para>The
<function>free
<parameter/></function> function returns no
2039 <title>Non-standard API
</title>
2040 <para>The
<function>malloc_usable_size
<parameter/></function> function
2041 returns the usable size of the allocation pointed to by
2042 <parameter>ptr
</parameter>.
</para>
2044 <para>The
<function>mallctl
<parameter/></function>,
2045 <function>mallctlnametomib
<parameter/></function>, and
2046 <function>mallctlbymib
<parameter/></function> functions return
0 on
2047 success; otherwise they return an error value. The functions will fail
2051 <term><errorname>EINVAL
</errorname></term>
2053 <listitem><para><parameter>newp
</parameter> is not
2054 <constant>NULL
</constant>, and
<parameter>newlen
</parameter> is too
2055 large or too small. Alternatively,
<parameter>*oldlenp
</parameter>
2056 is too large or too small; in this case as much data as possible
2057 are read despite the error.
</para></listitem>
2060 <term><errorname>ENOMEM
</errorname></term>
2062 <listitem><para><parameter>*oldlenp
</parameter> is too short to
2063 hold the requested value.
</para></listitem>
2066 <term><errorname>ENOENT
</errorname></term>
2068 <listitem><para><parameter>name
</parameter> or
2069 <parameter>mib
</parameter> specifies an unknown/invalid
2070 value.
</para></listitem>
2073 <term><errorname>EPERM
</errorname></term>
2075 <listitem><para>Attempt to read or write void value, or attempt to
2076 write read-only value.
</para></listitem>
2079 <term><errorname>EAGAIN
</errorname></term>
2081 <listitem><para>A memory allocation failure
2082 occurred.
</para></listitem>
2085 <term><errorname>EFAULT
</errorname></term>
2087 <listitem><para>An interface with side effects failed in some way
2088 not directly related to
<function>mallctl*
<parameter/></function>
2089 read/write processing.
</para></listitem>
2095 <title>Experimental API
</title>
2096 <para>The
<function>allocm
<parameter/></function>,
2097 <function>rallocm
<parameter/></function>,
2098 <function>sallocm
<parameter/></function>,
2099 <function>dallocm
<parameter/></function>, and
2100 <function>nallocm
<parameter/></function> functions return
2101 <constant>ALLOCM_SUCCESS
</constant> on success; otherwise they return an
2102 error value. The
<function>allocm
<parameter/></function>,
2103 <function>rallocm
<parameter/></function>, and
2104 <function>nallocm
<parameter/></function> functions will fail if:
2107 <term><errorname>ALLOCM_ERR_OOM
</errorname></term>
2109 <listitem><para>Out of memory. Insufficient contiguous memory was
2110 available to service the allocation request. The
2111 <function>allocm
<parameter/></function> function additionally sets
2112 <parameter>*ptr
</parameter> to
<constant>NULL
</constant>, whereas
2113 the
<function>rallocm
<parameter/></function> function leaves
2114 <constant>*ptr
</constant> unmodified.
</para></listitem>
2117 The
<function>rallocm
<parameter/></function> function will also
2121 <term><errorname>ALLOCM_ERR_NOT_MOVED
</errorname></term>
2123 <listitem><para><constant>ALLOCM_NO_MOVE
</constant> was specified,
2124 but the reallocation request could not be serviced without moving
2125 the object.
</para></listitem>
2131 <refsect1 id=
"environment">
2132 <title>ENVIRONMENT
</title>
2133 <para>The following environment variable affects the execution of the
2134 allocation functions:
2137 <term><envar>MALLOC_CONF
</envar></term>
2139 <listitem><para>If the environment variable
2140 <envar>MALLOC_CONF
</envar> is set, the characters it contains
2141 will be interpreted as options.
</para></listitem>
2146 <refsect1 id=
"examples">
2147 <title>EXAMPLES
</title>
2148 <para>To dump core whenever a problem occurs:
2149 <screen>ln -s 'abort:true' /etc/malloc.conf
</screen>
2151 <para>To specify in the source a chunk size that is
16 MiB:
2152 <programlisting language=
"C"><![CDATA[
2153 malloc_conf =
"lg_chunk:24";]]
></programlisting></para>
2155 <refsect1 id=
"see_also">
2156 <title>SEE ALSO
</title>
2157 <para><citerefentry><refentrytitle>madvise
</refentrytitle>
2158 <manvolnum>2</manvolnum></citerefentry>,
2159 <citerefentry><refentrytitle>mmap
</refentrytitle>
2160 <manvolnum>2</manvolnum></citerefentry>,
2161 <citerefentry><refentrytitle>sbrk
</refentrytitle>
2162 <manvolnum>2</manvolnum></citerefentry>,
2163 <citerefentry><refentrytitle>utrace
</refentrytitle>
2164 <manvolnum>2</manvolnum></citerefentry>,
2165 <citerefentry><refentrytitle>alloca
</refentrytitle>
2166 <manvolnum>3</manvolnum></citerefentry>,
2167 <citerefentry><refentrytitle>atexit
</refentrytitle>
2168 <manvolnum>3</manvolnum></citerefentry>,
2169 <citerefentry><refentrytitle>getpagesize
</refentrytitle>
2170 <manvolnum>3</manvolnum></citerefentry></para>
2172 <refsect1 id=
"standards">
2173 <title>STANDARDS
</title>
2174 <para>The
<function>malloc
<parameter/></function>,
2175 <function>calloc
<parameter/></function>,
2176 <function>realloc
<parameter/></function>, and
2177 <function>free
<parameter/></function> functions conform to ISO/IEC
2178 9899:
1990 (
“ISO C90
”).
</para>
2180 <para>The
<function>posix_memalign
<parameter/></function> function conforms
2181 to IEEE Std
1003.1-
2001 (
“POSIX
.1”).
</para>
projects / rustc.git / blob