xref: /redis-3.2.3/deps/jemalloc/doc/jemalloc.html (revision fceef8e0)
1*fceef8e0Santirez<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>JEMALLOC</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry"><a name="idm316394519664"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>jemalloc &#8212; general purpose memory allocation functions</p></div><div class="refsect1"><a name="library"></a><h2>LIBRARY</h2><p>This manual describes jemalloc 3.6.0-0-g46c0af68bd248b04df75e4f92d5fb804c3d75340.  More information
2*fceef8e0Santirez    can be found at the <a class="ulink" href="http://www.canonware.com/jemalloc/" target="_top">jemalloc website</a>.</p></div><div class="refsynopsisdiv"><h2>SYNOPSIS</h2><div class="funcsynopsis"><pre class="funcsynopsisinfo">#include &lt;<code class="filename">stdlib.h</code>&gt;
3*fceef8e0Santirez#include &lt;<code class="filename">jemalloc/jemalloc.h</code>&gt;</pre><div class="refsect2"><a name="idm316394002288"></a><h3>Standard API</h3><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">malloc</b>(</code></td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">calloc</b>(</code></td><td>size_t <var class="pdparam">number</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">posix_memalign</b>(</code></td><td>void **<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">alignment</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">aligned_alloc</b>(</code></td><td>size_t <var class="pdparam">alignment</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">realloc</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">free</b>(</code></td><td>void *<var class="pdparam">ptr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="refsect2"><a name="idm316393986160"></a><h3>Non-standard API</h3><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">mallocx</b>(</code></td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void *<b class="fsfunc">rallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">xallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">extra</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">sallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">dallocx</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">nallocx</b>(</code></td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctl</b>(</code></td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">oldp</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">oldlenp</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">newp</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">newlen</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctlnametomib</b>(</code></td><td>const char *<var class="pdparam">name</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">mibp</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">miblenp</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">mallctlbymib</b>(</code></td><td>const size_t *<var class="pdparam">mib</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">miblen</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">oldp</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">oldlenp</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">newp</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">newlen</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">malloc_stats_print</b>(</code></td><td>void <var class="pdparam">(*write_cb)</var>
4a78e148bSantirez            <code>(</code>void *, const char *<code>)</code>
5*fceef8e0Santirez          , </td></tr><tr><td>�</td><td>void *<var class="pdparam">cbopaque</var>, </td></tr><tr><td>�</td><td>const char *<var class="pdparam">opts</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">size_t <b class="fsfunc">malloc_usable_size</b>(</code></td><td>const void *<var class="pdparam">ptr</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">void <b class="fsfunc">(*malloc_message)</b>(</code></td><td>void *<var class="pdparam">cbopaque</var>, </td></tr><tr><td>�</td><td>const char *<var class="pdparam">s</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><p><span class="type">const char *</span><code class="varname">malloc_conf</code>;</p></div><div class="refsect2"><a name="idm316388684112"></a><h3>Experimental API</h3><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">allocm</b>(</code></td><td>void **<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">rsize</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">rallocm</b>(</code></td><td>void **<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">rsize</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">extra</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">sallocm</b>(</code></td><td>const void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>size_t *<var class="pdparam">rsize</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">dallocm</b>(</code></td><td>void *<var class="pdparam">ptr</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">int <b class="fsfunc">nallocm</b>(</code></td><td>size_t *<var class="pdparam">rsize</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>int <var class="pdparam">flags</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div></div></div><div class="refsect1"><a name="description"></a><h2>DESCRIPTION</h2><div class="refsect2"><a name="idm316388663504"></a><h3>Standard API</h3><p>The <code class="function">malloc</code>(<em class="parameter"><code></code></em>) function allocates
6a78e148bSantirez      <em class="parameter"><code>size</code></em> bytes of uninitialized memory.  The allocated
7a78e148bSantirez      space is suitably aligned (after possible pointer coercion) for storage
8a78e148bSantirez      of any type of object.</p><p>The <code class="function">calloc</code>(<em class="parameter"><code></code></em>) function allocates
9a78e148bSantirez      space for <em class="parameter"><code>number</code></em> objects, each
10a78e148bSantirez      <em class="parameter"><code>size</code></em> bytes in length.  The result is identical to
11a78e148bSantirez      calling <code class="function">malloc</code>(<em class="parameter"><code></code></em>) with an argument of
12a78e148bSantirez      <em class="parameter"><code>number</code></em> * <em class="parameter"><code>size</code></em>, with the
13a78e148bSantirez      exception that the allocated memory is explicitly initialized to zero
14a78e148bSantirez      bytes.</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function
15a78e148bSantirez      allocates <em class="parameter"><code>size</code></em> bytes of memory such that the
16a78e148bSantirez      allocation's base address is an even multiple of
17a78e148bSantirez      <em class="parameter"><code>alignment</code></em>, and returns the allocation in the value
18a78e148bSantirez      pointed to by <em class="parameter"><code>ptr</code></em>.  The requested
19a78e148bSantirez      <em class="parameter"><code>alignment</code></em> must be a power of 2 at least as large
20ad4c0b41Santirez      as <code class="code">sizeof(<span class="type">void *</span>)</code>.</p><p>The <code class="function">aligned_alloc</code>(<em class="parameter"><code></code></em>) function
21ad4c0b41Santirez      allocates <em class="parameter"><code>size</code></em> bytes of memory such that the
22ad4c0b41Santirez      allocation's base address is an even multiple of
23ad4c0b41Santirez      <em class="parameter"><code>alignment</code></em>.  The requested
24ad4c0b41Santirez      <em class="parameter"><code>alignment</code></em> must be a power of 2.  Behavior is
25ad4c0b41Santirez      undefined if <em class="parameter"><code>size</code></em> is not an integral multiple of
26ad4c0b41Santirez      <em class="parameter"><code>alignment</code></em>.</p><p>The <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function changes the
27a78e148bSantirez      size of the previously allocated memory referenced by
28a78e148bSantirez      <em class="parameter"><code>ptr</code></em> to <em class="parameter"><code>size</code></em> bytes.  The
29a78e148bSantirez      contents of the memory are unchanged up to the lesser of the new and old
30a78e148bSantirez      sizes.  If the new size is larger, the contents of the newly allocated
31a78e148bSantirez      portion of the memory are undefined.  Upon success, the memory referenced
32a78e148bSantirez      by <em class="parameter"><code>ptr</code></em> is freed and a pointer to the newly
33a78e148bSantirez      allocated memory is returned.  Note that
34a78e148bSantirez      <code class="function">realloc</code>(<em class="parameter"><code></code></em>) may move the memory allocation,
35a78e148bSantirez      resulting in a different return value than <em class="parameter"><code>ptr</code></em>.
36a78e148bSantirez      If <em class="parameter"><code>ptr</code></em> is <code class="constant">NULL</code>, the
37a78e148bSantirez      <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function behaves identically to
38a78e148bSantirez      <code class="function">malloc</code>(<em class="parameter"><code></code></em>) for the specified size.</p><p>The <code class="function">free</code>(<em class="parameter"><code></code></em>) function causes the
39a78e148bSantirez      allocated memory referenced by <em class="parameter"><code>ptr</code></em> to be made
40a78e148bSantirez      available for future allocations.  If <em class="parameter"><code>ptr</code></em> is
41*fceef8e0Santirez      <code class="constant">NULL</code>, no action occurs.</p></div><div class="refsect2"><a name="idm316388639904"></a><h3>Non-standard API</h3><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>),
42*fceef8e0Santirez      <code class="function">rallocx</code>(<em class="parameter"><code></code></em>),
43*fceef8e0Santirez      <code class="function">xallocx</code>(<em class="parameter"><code></code></em>),
44*fceef8e0Santirez      <code class="function">sallocx</code>(<em class="parameter"><code></code></em>),
45*fceef8e0Santirez      <code class="function">dallocx</code>(<em class="parameter"><code></code></em>), and
46*fceef8e0Santirez      <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) functions all have a
47*fceef8e0Santirez      <em class="parameter"><code>flags</code></em> argument that can be used to specify
48*fceef8e0Santirez      options.  The functions only check the options that are contextually
49*fceef8e0Santirez      relevant.  Use bitwise or (<code class="code">|</code>) operations to
50*fceef8e0Santirez      specify one or more of the following:
51*fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="constant">MALLOCX_LG_ALIGN(<em class="parameter"><code>la</code></em>)
52*fceef8e0Santirez            </code></span></dt><dd><p>Align the memory allocation to start at an address
53*fceef8e0Santirez            that is a multiple of <code class="code">(1 &lt;&lt;
54*fceef8e0Santirez            <em class="parameter"><code>la</code></em>)</code>.  This macro does not validate
55*fceef8e0Santirez            that <em class="parameter"><code>la</code></em> is within the valid
56*fceef8e0Santirez            range.</p></dd><dt><span class="term"><code class="constant">MALLOCX_ALIGN(<em class="parameter"><code>a</code></em>)
57*fceef8e0Santirez            </code></span></dt><dd><p>Align the memory allocation to start at an address
58*fceef8e0Santirez            that is a multiple of <em class="parameter"><code>a</code></em>, where
59*fceef8e0Santirez            <em class="parameter"><code>a</code></em> is a power of two.  This macro does not
60*fceef8e0Santirez            validate that <em class="parameter"><code>a</code></em> is a power of 2.
61*fceef8e0Santirez            </p></dd><dt><span class="term"><code class="constant">MALLOCX_ZERO</code></span></dt><dd><p>Initialize newly allocated memory to contain zero
62*fceef8e0Santirez            bytes.  In the growing reallocation case, the real size prior to
63*fceef8e0Santirez            reallocation defines the boundary between untouched bytes and those
64*fceef8e0Santirez            that are initialized to contain zero bytes.  If this macro is
65*fceef8e0Santirez            absent, newly allocated memory is uninitialized.</p></dd><dt><span class="term"><code class="constant">MALLOCX_ARENA(<em class="parameter"><code>a</code></em>)
66*fceef8e0Santirez            </code></span></dt><dd><p>Use the arena specified by the index
67*fceef8e0Santirez            <em class="parameter"><code>a</code></em> (and by necessity bypass the thread
68*fceef8e0Santirez            cache).  This macro has no effect for huge regions, nor for regions
69*fceef8e0Santirez            that were allocated via an arena other than the one specified.
70*fceef8e0Santirez            This macro does not validate that <em class="parameter"><code>a</code></em>
71*fceef8e0Santirez            specifies an arena index in the valid range.</p></dd></dl></div><p>
72*fceef8e0Santirez      </p><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function allocates at
73*fceef8e0Santirez      least <em class="parameter"><code>size</code></em> bytes of memory, and returns a pointer
74*fceef8e0Santirez      to the base address of the allocation.  Behavior is undefined if
75*fceef8e0Santirez      <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if request size
76*fceef8e0Santirez      overflows due to size class and/or alignment constraints.</p><p>The <code class="function">rallocx</code>(<em class="parameter"><code></code></em>) function resizes the
77*fceef8e0Santirez      allocation at <em class="parameter"><code>ptr</code></em> to be at least
78*fceef8e0Santirez      <em class="parameter"><code>size</code></em> bytes, and returns a pointer to the base
79*fceef8e0Santirez      address of the resulting allocation, which may or may not have moved from
80*fceef8e0Santirez      its original location.  Behavior is undefined if
81*fceef8e0Santirez      <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if request size
82*fceef8e0Santirez      overflows due to size class and/or alignment constraints.</p><p>The <code class="function">xallocx</code>(<em class="parameter"><code></code></em>) function resizes the
83*fceef8e0Santirez      allocation at <em class="parameter"><code>ptr</code></em> in place to be at least
84*fceef8e0Santirez      <em class="parameter"><code>size</code></em> bytes, and returns the real size of the
85*fceef8e0Santirez      allocation.  If <em class="parameter"><code>extra</code></em> is non-zero, an attempt is
86*fceef8e0Santirez      made to resize the allocation to be at least <code class="code">(<em class="parameter"><code>size</code></em> +
87*fceef8e0Santirez      <em class="parameter"><code>extra</code></em>)</code> bytes, though inability to allocate
88*fceef8e0Santirez      the extra byte(s) will not by itself result in failure to resize.
89*fceef8e0Santirez      Behavior is undefined if <em class="parameter"><code>size</code></em> is
90*fceef8e0Santirez      <code class="constant">0</code>, or if <code class="code">(<em class="parameter"><code>size</code></em> + <em class="parameter"><code>extra</code></em>
91*fceef8e0Santirez      &gt; <code class="constant">SIZE_T_MAX</code>)</code>.</p><p>The <code class="function">sallocx</code>(<em class="parameter"><code></code></em>) function returns the
92*fceef8e0Santirez      real size of the allocation at <em class="parameter"><code>ptr</code></em>.</p><p>The <code class="function">dallocx</code>(<em class="parameter"><code></code></em>) function causes the
93*fceef8e0Santirez      memory referenced by <em class="parameter"><code>ptr</code></em> to be made available for
94*fceef8e0Santirez      future allocations.</p><p>The <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) function allocates no
95*fceef8e0Santirez      memory, but it performs the same size computation as the
96*fceef8e0Santirez      <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function, and returns the real
97*fceef8e0Santirez      size of the allocation that would result from the equivalent
98*fceef8e0Santirez      <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function call.  Behavior is
99*fceef8e0Santirez      undefined if <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if
100*fceef8e0Santirez      request size overflows due to size class and/or alignment
101*fceef8e0Santirez      constraints.</p><p>The <code class="function">mallctl</code>(<em class="parameter"><code></code></em>) function provides a
102a78e148bSantirez      general interface for introspecting the memory allocator, as well as
103a78e148bSantirez      setting modifiable parameters and triggering actions.  The
104a78e148bSantirez      period-separated <em class="parameter"><code>name</code></em> argument specifies a
105a78e148bSantirez      location in a tree-structured namespace; see the <a class="xref" href="#mallctl_namespace" title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for
106a78e148bSantirez      documentation on the tree contents.  To read a value, pass a pointer via
107a78e148bSantirez      <em class="parameter"><code>oldp</code></em> to adequate space to contain the value, and a
108a78e148bSantirez      pointer to its length via <em class="parameter"><code>oldlenp</code></em>; otherwise pass
109a78e148bSantirez      <code class="constant">NULL</code> and <code class="constant">NULL</code>.  Similarly, to
110a78e148bSantirez      write a value, pass a pointer to the value via
111a78e148bSantirez      <em class="parameter"><code>newp</code></em>, and its length via
112a78e148bSantirez      <em class="parameter"><code>newlen</code></em>; otherwise pass <code class="constant">NULL</code>
113a78e148bSantirez      and <code class="constant">0</code>.</p><p>The <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>) function
114a78e148bSantirez      provides a way to avoid repeated name lookups for applications that
115a78e148bSantirez      repeatedly query the same portion of the namespace, by translating a name
116a78e148bSantirez      to a &#8220;Management Information Base&#8221; (MIB) that can be passed
117a78e148bSantirez      repeatedly to <code class="function">mallctlbymib</code>(<em class="parameter"><code></code></em>).  Upon
118a78e148bSantirez      successful return from <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>),
119a78e148bSantirez      <em class="parameter"><code>mibp</code></em> contains an array of
120a78e148bSantirez      <em class="parameter"><code>*miblenp</code></em> integers, where
121a78e148bSantirez      <em class="parameter"><code>*miblenp</code></em> is the lesser of the number of components
122a78e148bSantirez      in <em class="parameter"><code>name</code></em> and the input value of
123a78e148bSantirez      <em class="parameter"><code>*miblenp</code></em>.  Thus it is possible to pass a
124a78e148bSantirez      <em class="parameter"><code>*miblenp</code></em> that is smaller than the number of
125a78e148bSantirez      period-separated name components, which results in a partial MIB that can
126a78e148bSantirez      be used as the basis for constructing a complete MIB.  For name
127a78e148bSantirez      components that are integers (e.g. the 2 in
128a78e148bSantirez      <a class="link" href="#arenas.bin.i.size">
129a78e148bSantirez    "<code class="mallctl">arenas.bin.2.size</code>"
130a78e148bSantirez  </a>),
131a78e148bSantirez      the corresponding MIB component will always be that integer.  Therefore,
132a78e148bSantirez      it is legitimate to construct code like the following: </p><pre class="programlisting">
133a78e148bSantirezunsigned nbins, i;
134*fceef8e0Santirezsize_t mib[4];
135a78e148bSantirezsize_t len, miblen;
136a78e148bSantirez
137a78e148bSantirezlen = sizeof(nbins);
138a78e148bSantirezmallctl("arenas.nbins", &amp;nbins, &amp;len, NULL, 0);
139a78e148bSantirez
140a78e148bSantirezmiblen = 4;
141*fceef8e0Santirezmallctlnametomib("arenas.bin.0.size", mib, &amp;miblen);
142a78e148bSantirezfor (i = 0; i &lt; nbins; i++) {
143a78e148bSantirez	size_t bin_size;
144a78e148bSantirez
145a78e148bSantirez	mib[2] = i;
146a78e148bSantirez	len = sizeof(bin_size);
147a78e148bSantirez	mallctlbymib(mib, miblen, &amp;bin_size, &amp;len, NULL, 0);
148a78e148bSantirez	/* Do something with bin_size... */
149*fceef8e0Santirez}</pre><p>The <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>) function
150*fceef8e0Santirez      writes human-readable summary statistics via the
151*fceef8e0Santirez      <em class="parameter"><code>write_cb</code></em> callback function pointer and
152*fceef8e0Santirez      <em class="parameter"><code>cbopaque</code></em> data passed to
153*fceef8e0Santirez      <em class="parameter"><code>write_cb</code></em>, or
154*fceef8e0Santirez      <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) if
155*fceef8e0Santirez      <em class="parameter"><code>write_cb</code></em> is <code class="constant">NULL</code>.  This
156*fceef8e0Santirez      function can be called repeatedly.  General information that never
157*fceef8e0Santirez      changes during execution can be omitted by specifying "g" as a character
158*fceef8e0Santirez      within the <em class="parameter"><code>opts</code></em> string.  Note that
159*fceef8e0Santirez      <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) uses the
160*fceef8e0Santirez      <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions internally, so
161*fceef8e0Santirez      inconsistent statistics can be reported if multiple threads use these
162*fceef8e0Santirez      functions simultaneously.  If <code class="option">--enable-stats</code> is
163*fceef8e0Santirez      specified during configuration, &#8220;m&#8221; and &#8220;a&#8221; can
164*fceef8e0Santirez      be specified to omit merged arena and per arena statistics, respectively;
165*fceef8e0Santirez      &#8220;b&#8221; and &#8220;l&#8221; can be specified to omit per size
166*fceef8e0Santirez      class statistics for bins and large objects, respectively.  Unrecognized
167*fceef8e0Santirez      characters are silently ignored.  Note that thread caching may prevent
168*fceef8e0Santirez      some statistics from being completely up to date, since extra locking
169*fceef8e0Santirez      would be required to merge counters that track thread cache operations.
170*fceef8e0Santirez      </p><p>The <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function
171*fceef8e0Santirez      returns the usable size of the allocation pointed to by
172*fceef8e0Santirez      <em class="parameter"><code>ptr</code></em>.  The return value may be larger than the size
173*fceef8e0Santirez      that was requested during allocation.  The
174*fceef8e0Santirez      <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function is not a
175*fceef8e0Santirez      mechanism for in-place <code class="function">realloc</code>(<em class="parameter"><code></code></em>); rather
176*fceef8e0Santirez      it is provided solely as a tool for introspection purposes.  Any
177*fceef8e0Santirez      discrepancy between the requested allocation size and the size reported
178*fceef8e0Santirez      by <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) should not be
179*fceef8e0Santirez      depended on, since such behavior is entirely implementation-dependent.
180*fceef8e0Santirez      </p></div><div class="refsect2"><a name="idm316388574208"></a><h3>Experimental API</h3><p>The experimental API is subject to change or removal without regard
181ad4c0b41Santirez      for backward compatibility.  If <code class="option">--disable-experimental</code>
182ad4c0b41Santirez      is specified during configuration, the experimental API is
183ad4c0b41Santirez      omitted.</p><p>The <code class="function">allocm</code>(<em class="parameter"><code></code></em>),
184a78e148bSantirez      <code class="function">rallocm</code>(<em class="parameter"><code></code></em>),
185ad4c0b41Santirez      <code class="function">sallocm</code>(<em class="parameter"><code></code></em>),
186ad4c0b41Santirez      <code class="function">dallocm</code>(<em class="parameter"><code></code></em>), and
187ad4c0b41Santirez      <code class="function">nallocm</code>(<em class="parameter"><code></code></em>) functions all have a
188a78e148bSantirez      <em class="parameter"><code>flags</code></em> argument that can be used to specify
189a78e148bSantirez      options.  The functions only check the options that are contextually
190a78e148bSantirez      relevant.  Use bitwise or (<code class="code">|</code>) operations to
191a78e148bSantirez      specify one or more of the following:
192*fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="constant">ALLOCM_LG_ALIGN(<em class="parameter"><code>la</code></em>)
193a78e148bSantirez            </code></span></dt><dd><p>Align the memory allocation to start at an address
194a78e148bSantirez            that is a multiple of <code class="code">(1 &lt;&lt;
195a78e148bSantirez            <em class="parameter"><code>la</code></em>)</code>.  This macro does not validate
196a78e148bSantirez            that <em class="parameter"><code>la</code></em> is within the valid
197a78e148bSantirez            range.</p></dd><dt><span class="term"><code class="constant">ALLOCM_ALIGN(<em class="parameter"><code>a</code></em>)
198a78e148bSantirez            </code></span></dt><dd><p>Align the memory allocation to start at an address
199a78e148bSantirez            that is a multiple of <em class="parameter"><code>a</code></em>, where
200a78e148bSantirez            <em class="parameter"><code>a</code></em> is a power of two.  This macro does not
201a78e148bSantirez            validate that <em class="parameter"><code>a</code></em> is a power of 2.
202a78e148bSantirez            </p></dd><dt><span class="term"><code class="constant">ALLOCM_ZERO</code></span></dt><dd><p>Initialize newly allocated memory to contain zero
203a78e148bSantirez            bytes.  In the growing reallocation case, the real size prior to
204a78e148bSantirez            reallocation defines the boundary between untouched bytes and those
205*fceef8e0Santirez            that are initialized to contain zero bytes.  If this macro is
206a78e148bSantirez            absent, newly allocated memory is uninitialized.</p></dd><dt><span class="term"><code class="constant">ALLOCM_NO_MOVE</code></span></dt><dd><p>For reallocation, fail rather than moving the
207a78e148bSantirez            object.  This constraint can apply to both growth and
2087383c3b1Santirez            shrinkage.</p></dd><dt><span class="term"><code class="constant">ALLOCM_ARENA(<em class="parameter"><code>a</code></em>)
2097383c3b1Santirez            </code></span></dt><dd><p>Use the arena specified by the index
210*fceef8e0Santirez            <em class="parameter"><code>a</code></em> (and by necessity bypass the thread
211*fceef8e0Santirez            cache).  This macro has no effect for huge regions, nor for regions
212*fceef8e0Santirez            that were allocated via an arena other than the one specified.
213*fceef8e0Santirez            This macro does not validate that <em class="parameter"><code>a</code></em>
214*fceef8e0Santirez            specifies an arena index in the valid range.</p></dd></dl></div><p>
215a78e148bSantirez      </p><p>The <code class="function">allocm</code>(<em class="parameter"><code></code></em>) function allocates at
216a78e148bSantirez      least <em class="parameter"><code>size</code></em> bytes of memory, sets
217a78e148bSantirez      <em class="parameter"><code>*ptr</code></em> to the base address of the allocation, and
218a78e148bSantirez      sets <em class="parameter"><code>*rsize</code></em> to the real size of the allocation if
219ad4c0b41Santirez      <em class="parameter"><code>rsize</code></em> is not <code class="constant">NULL</code>.  Behavior
220*fceef8e0Santirez      is undefined if <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or
221*fceef8e0Santirez      if request size overflows due to size class and/or alignment
222*fceef8e0Santirez      constraints.</p><p>The <code class="function">rallocm</code>(<em class="parameter"><code></code></em>) function resizes the
223a78e148bSantirez      allocation at <em class="parameter"><code>*ptr</code></em> to be at least
224a78e148bSantirez      <em class="parameter"><code>size</code></em> bytes, sets <em class="parameter"><code>*ptr</code></em> to
225a78e148bSantirez      the base address of the allocation if it moved, and sets
226a78e148bSantirez      <em class="parameter"><code>*rsize</code></em> to the real size of the allocation if
227a78e148bSantirez      <em class="parameter"><code>rsize</code></em> is not <code class="constant">NULL</code>.  If
228a78e148bSantirez      <em class="parameter"><code>extra</code></em> is non-zero, an attempt is made to resize
229*fceef8e0Santirez      the allocation to be at least <code class="code">(<em class="parameter"><code>size</code></em> +
230a78e148bSantirez      <em class="parameter"><code>extra</code></em>)</code> bytes, though inability to allocate
231a78e148bSantirez      the extra byte(s) will not by itself result in failure.  Behavior is
232*fceef8e0Santirez      undefined if <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, if
233*fceef8e0Santirez      request size overflows due to size class and/or alignment constraints, or
234*fceef8e0Santirez      if <code class="code">(<em class="parameter"><code>size</code></em> +
235a78e148bSantirez      <em class="parameter"><code>extra</code></em> &gt;
236a78e148bSantirez      <code class="constant">SIZE_T_MAX</code>)</code>.</p><p>The <code class="function">sallocm</code>(<em class="parameter"><code></code></em>) function sets
237a78e148bSantirez      <em class="parameter"><code>*rsize</code></em> to the real size of the allocation.</p><p>The <code class="function">dallocm</code>(<em class="parameter"><code></code></em>) function causes the
238a78e148bSantirez      memory referenced by <em class="parameter"><code>ptr</code></em> to be made available for
239ad4c0b41Santirez      future allocations.</p><p>The <code class="function">nallocm</code>(<em class="parameter"><code></code></em>) function allocates no
240ad4c0b41Santirez      memory, but it performs the same size computation as the
241ad4c0b41Santirez      <code class="function">allocm</code>(<em class="parameter"><code></code></em>) function, and if
242ad4c0b41Santirez      <em class="parameter"><code>rsize</code></em> is not <code class="constant">NULL</code> it sets
243ad4c0b41Santirez      <em class="parameter"><code>*rsize</code></em> to the real size of the allocation that
244ad4c0b41Santirez      would result from the equivalent <code class="function">allocm</code>(<em class="parameter"><code></code></em>)
245*fceef8e0Santirez      function call.  Behavior is undefined if <em class="parameter"><code>size</code></em> is
246*fceef8e0Santirez      <code class="constant">0</code>, or if request size overflows due to size class
247*fceef8e0Santirez      and/or alignment constraints.</p></div></div><div class="refsect1"><a name="tuning"></a><h2>TUNING</h2><p>Once, when the first call is made to one of the memory allocation
248a78e148bSantirez    routines, the allocator initializes its internals based in part on various
249a78e148bSantirez    options that can be specified at compile- or run-time.</p><p>The string pointed to by the global variable
250a78e148bSantirez    <code class="varname">malloc_conf</code>, the &#8220;name&#8221; of the file
251a78e148bSantirez    referenced by the symbolic link named <code class="filename">/etc/malloc.conf</code>, and the value of the
252a78e148bSantirez    environment variable <code class="envar">MALLOC_CONF</code>, will be interpreted, in
253*fceef8e0Santirez    that order, from left to right as options.  Note that
254*fceef8e0Santirez    <code class="varname">malloc_conf</code> may be read before
255*fceef8e0Santirez    <code class="function">main</code>(<em class="parameter"><code></code></em>) is entered, so the declaration of
256*fceef8e0Santirez    <code class="varname">malloc_conf</code> should specify an initializer that contains
257*fceef8e0Santirez    the final value to be read by jemalloc.  <code class="varname">malloc_conf</code> is
258*fceef8e0Santirez    a compile-time setting, whereas <code class="filename">/etc/malloc.conf</code> and <code class="envar">MALLOC_CONF</code>
259*fceef8e0Santirez    can be safely set any time prior to program invocation.</p><p>An options string is a comma-separated list of option:value pairs.
260a78e148bSantirez    There is one key corresponding to each <a class="link" href="#opt.abort">
261a78e148bSantirez    "<code class="mallctl">opt.*</code>"
262a78e148bSantirez  </a> mallctl (see the <a class="xref" href="#mallctl_namespace" title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for options
263a78e148bSantirez    documentation).  For example, <code class="literal">abort:true,narenas:1</code> sets
264a78e148bSantirez    the <a class="link" href="#opt.abort">
265a78e148bSantirez    "<code class="mallctl">opt.abort</code>"
266a78e148bSantirez  </a> and <a class="link" href="#opt.narenas">
267a78e148bSantirez    "<code class="mallctl">opt.narenas</code>"
268a78e148bSantirez  </a> options.  Some
269a78e148bSantirez    options have boolean values (true/false), others have integer values (base
270a78e148bSantirez    8, 10, or 16, depending on prefix), and yet others have raw string
271*fceef8e0Santirez    values.</p></div><div class="refsect1"><a name="implementation_notes"></a><h2>IMPLEMENTATION NOTES</h2><p>Traditionally, allocators have used
272a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> to obtain memory, which is
273a78e148bSantirez    suboptimal for several reasons, including race conditions, increased
274a78e148bSantirez    fragmentation, and artificial limitations on maximum usable memory.  If
275a78e148bSantirez    <code class="option">--enable-dss</code> is specified during configuration, this
276ad4c0b41Santirez    allocator uses both <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> and
277ad4c0b41Santirez    <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>, in that order of preference;
278a78e148bSantirez    otherwise only <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> is used.</p><p>This allocator uses multiple arenas in order to reduce lock
279a78e148bSantirez    contention for threaded programs on multi-processor systems.  This works
280a78e148bSantirez    well with regard to threading scalability, but incurs some costs.  There is
281a78e148bSantirez    a small fixed per-arena overhead, and additionally, arenas manage memory
282a78e148bSantirez    completely independently of each other, which means a small fixed increase
283a78e148bSantirez    in overall memory fragmentation.  These overheads are not generally an
284a78e148bSantirez    issue, given the number of arenas normally used.  Note that using
285a78e148bSantirez    substantially more arenas than the default is not likely to improve
286a78e148bSantirez    performance, mainly due to reduced cache performance.  However, it may make
287a78e148bSantirez    sense to reduce the number of arenas if an application does not make much
288a78e148bSantirez    use of the allocation functions.</p><p>In addition to multiple arenas, unless
289a78e148bSantirez    <code class="option">--disable-tcache</code> is specified during configuration, this
290a78e148bSantirez    allocator supports thread-specific caching for small and large objects, in
291a78e148bSantirez    order to make it possible to completely avoid synchronization for most
292a78e148bSantirez    allocation requests.  Such caching allows very fast allocation in the
293a78e148bSantirez    common case, but it increases memory usage and fragmentation, since a
294a78e148bSantirez    bounded number of objects can remain allocated in each thread cache.</p><p>Memory is conceptually broken into equal-sized chunks, where the
295a78e148bSantirez    chunk size is a power of two that is greater than the page size.  Chunks
296a78e148bSantirez    are always aligned to multiples of the chunk size.  This alignment makes it
297a78e148bSantirez    possible to find metadata for user objects very quickly.</p><p>User objects are broken into three categories according to size:
298a78e148bSantirez    small, large, and huge.  Small objects are smaller than one page.  Large
299a78e148bSantirez    objects are smaller than the chunk size.  Huge objects are a multiple of
300a78e148bSantirez    the chunk size.  Small and large objects are managed by arenas; huge
301a78e148bSantirez    objects are managed separately in a single data structure that is shared by
302a78e148bSantirez    all threads.  Huge objects are used by applications infrequently enough
303a78e148bSantirez    that this single data structure is not a scalability issue.</p><p>Each chunk that is managed by an arena tracks its contents as runs of
304a78e148bSantirez    contiguous pages (unused, backing a set of small objects, or backing one
305a78e148bSantirez    large object).  The combination of chunk alignment and chunk page maps
306a78e148bSantirez    makes it possible to determine all metadata regarding small and large
307a78e148bSantirez    allocations in constant time.</p><p>Small objects are managed in groups by page runs.  Each run maintains
308ad4c0b41Santirez    a frontier and free list to track which regions are in use.  Allocation
309ad4c0b41Santirez    requests that are no more than half the quantum (8 or 16, depending on
310ad4c0b41Santirez    architecture) are rounded up to the nearest power of two that is at least
311ad4c0b41Santirez    <code class="code">sizeof(<span class="type">double</span>)</code>.  All other small
312ad4c0b41Santirez    object size classes are multiples of the quantum, spaced such that internal
313ad4c0b41Santirez    fragmentation is limited to approximately 25% for all but the smallest size
314ad4c0b41Santirez    classes.  Allocation requests that are larger than the maximum small size
315ad4c0b41Santirez    class, but small enough to fit in an arena-managed chunk (see the <a class="link" href="#opt.lg_chunk">
316a78e148bSantirez    "<code class="mallctl">opt.lg_chunk</code>"
317a78e148bSantirez  </a> option), are
318a78e148bSantirez    rounded up to the nearest run size.  Allocation requests that are too large
319a78e148bSantirez    to fit in an arena-managed chunk are rounded up to the nearest multiple of
320a78e148bSantirez    the chunk size.</p><p>Allocations are packed tightly together, which can be an issue for
321a78e148bSantirez    multi-threaded applications.  If you need to assure that allocations do not
322a78e148bSantirez    suffer from cacheline sharing, round your allocation requests up to the
323a78e148bSantirez    nearest multiple of the cacheline size, or specify cacheline alignment when
324a78e148bSantirez    allocating.</p><p>Assuming 4 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 64-bit
325*fceef8e0Santirez    system, the size classes in each category are as shown in <a class="xref" href="#size_classes" title="Table�1.�Size classes">Table 1</a>.</p><div class="table"><a name="size_classes"></a><p class="title"><b>Table�1.�Size classes</b></p><div class="table-contents"><table summary="Size classes" border="1"><colgroup><col align="left" class="c1"><col align="right" class="c2"><col align="left" class="c3"></colgroup><thead><tr><th align="left">Category</th><th align="right">Spacing</th><th align="left">Size</th></tr></thead><tbody><tr><td rowspan="7" align="left">Small</td><td align="right">lg</td><td align="left">[8]</td></tr><tr><td align="right">16</td><td align="left">[16, 32, 48, ..., 128]</td></tr><tr><td align="right">32</td><td align="left">[160, 192, 224, 256]</td></tr><tr><td align="right">64</td><td align="left">[320, 384, 448, 512]</td></tr><tr><td align="right">128</td><td align="left">[640, 768, 896, 1024]</td></tr><tr><td align="right">256</td><td align="left">[1280, 1536, 1792, 2048]</td></tr><tr><td align="right">512</td><td align="left">[2560, 3072, 3584]</td></tr><tr><td align="left">Large</td><td align="right">4 KiB</td><td align="left">[4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB]</td></tr><tr><td align="left">Huge</td><td align="right">4 MiB</td><td align="left">[4 MiB, 8 MiB, 12 MiB, ...]</td></tr></tbody></table></div></div><br class="table-break"></div><div class="refsect1"><a name="mallctl_namespace"></a><h2>MALLCTL NAMESPACE</h2><p>The following names are defined in the namespace accessible via the
326a78e148bSantirez    <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions.  Value types are
327a78e148bSantirez    specified in parentheses, their readable/writable statuses are encoded as
328a78e148bSantirez    <code class="literal">rw</code>, <code class="literal">r-</code>, <code class="literal">-w</code>, or
329a78e148bSantirez    <code class="literal">--</code>, and required build configuration flags follow, if
330a78e148bSantirez    any.  A name element encoded as <code class="literal">&lt;i&gt;</code> or
331a78e148bSantirez    <code class="literal">&lt;j&gt;</code> indicates an integer component, where the
332a78e148bSantirez    integer varies from 0 to some upper value that must be determined via
333a78e148bSantirez    introspection.  In the case of
334a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.*</code>"
335a78e148bSantirez  ,
336a78e148bSantirez    <code class="literal">&lt;i&gt;</code> equal to <a class="link" href="#arenas.narenas">
337a78e148bSantirez    "<code class="mallctl">arenas.narenas</code>"
338a78e148bSantirez  </a> can be
339a78e148bSantirez    used to access the summation of statistics from all arenas.  Take special
340a78e148bSantirez    note of the <a class="link" href="#epoch">
341a78e148bSantirez    "<code class="mallctl">epoch</code>"
342a78e148bSantirez  </a> mallctl,
343*fceef8e0Santirez    which controls refreshing of cached dynamic statistics.</p><div class="variablelist"><dl class="variablelist"><dt><a name="version"></a><span class="term">
344a78e148bSantirez
345a78e148bSantirez    "<code class="mallctl">version</code>"
346a78e148bSantirez
347a78e148bSantirez          (<span class="type">const char *</span>)
348a78e148bSantirez          <code class="literal">r-</code>
349a78e148bSantirez        </span></dt><dd><p>Return the jemalloc version string.</p></dd><dt><a name="epoch"></a><span class="term">
350a78e148bSantirez
351a78e148bSantirez    "<code class="mallctl">epoch</code>"
352a78e148bSantirez
353a78e148bSantirez          (<span class="type">uint64_t</span>)
354a78e148bSantirez          <code class="literal">rw</code>
355a78e148bSantirez        </span></dt><dd><p>If a value is passed in, refresh the data from which
356a78e148bSantirez        the <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions report values,
357a78e148bSantirez        and increment the epoch.  Return the current epoch.  This is useful for
358*fceef8e0Santirez        detecting whether another thread caused a refresh.</p></dd><dt><a name="config.debug"></a><span class="term">
359a78e148bSantirez
360a78e148bSantirez    "<code class="mallctl">config.debug</code>"
361a78e148bSantirez
362a78e148bSantirez          (<span class="type">bool</span>)
363a78e148bSantirez          <code class="literal">r-</code>
364a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-debug</code> was specified during
365*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.dss"></a><span class="term">
366a78e148bSantirez
367a78e148bSantirez    "<code class="mallctl">config.dss</code>"
368a78e148bSantirez
369a78e148bSantirez          (<span class="type">bool</span>)
370a78e148bSantirez          <code class="literal">r-</code>
371a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-dss</code> was specified during
372*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.fill"></a><span class="term">
373a78e148bSantirez
374a78e148bSantirez    "<code class="mallctl">config.fill</code>"
375a78e148bSantirez
376a78e148bSantirez          (<span class="type">bool</span>)
377a78e148bSantirez          <code class="literal">r-</code>
378a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-fill</code> was specified during
379*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.lazy_lock"></a><span class="term">
380a78e148bSantirez
381a78e148bSantirez    "<code class="mallctl">config.lazy_lock</code>"
382a78e148bSantirez
383a78e148bSantirez          (<span class="type">bool</span>)
384a78e148bSantirez          <code class="literal">r-</code>
385a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-lazy-lock</code> was specified
386*fceef8e0Santirez        during build configuration.</p></dd><dt><a name="config.mremap"></a><span class="term">
387a78e148bSantirez
388ad4c0b41Santirez    "<code class="mallctl">config.mremap</code>"
389ad4c0b41Santirez
390ad4c0b41Santirez          (<span class="type">bool</span>)
391ad4c0b41Santirez          <code class="literal">r-</code>
392ad4c0b41Santirez        </span></dt><dd><p><code class="option">--enable-mremap</code> was specified during
393*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.munmap"></a><span class="term">
394ad4c0b41Santirez
395ad4c0b41Santirez    "<code class="mallctl">config.munmap</code>"
396ad4c0b41Santirez
397ad4c0b41Santirez          (<span class="type">bool</span>)
398ad4c0b41Santirez          <code class="literal">r-</code>
399ad4c0b41Santirez        </span></dt><dd><p><code class="option">--enable-munmap</code> was specified during
400*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.prof"></a><span class="term">
401ad4c0b41Santirez
402a78e148bSantirez    "<code class="mallctl">config.prof</code>"
403a78e148bSantirez
404a78e148bSantirez          (<span class="type">bool</span>)
405a78e148bSantirez          <code class="literal">r-</code>
406a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-prof</code> was specified during
407*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.prof_libgcc"></a><span class="term">
408a78e148bSantirez
409a78e148bSantirez    "<code class="mallctl">config.prof_libgcc</code>"
410a78e148bSantirez
411a78e148bSantirez          (<span class="type">bool</span>)
412a78e148bSantirez          <code class="literal">r-</code>
413a78e148bSantirez        </span></dt><dd><p><code class="option">--disable-prof-libgcc</code> was not
414*fceef8e0Santirez        specified during build configuration.</p></dd><dt><a name="config.prof_libunwind"></a><span class="term">
415a78e148bSantirez
416a78e148bSantirez    "<code class="mallctl">config.prof_libunwind</code>"
417a78e148bSantirez
418a78e148bSantirez          (<span class="type">bool</span>)
419a78e148bSantirez          <code class="literal">r-</code>
420a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-prof-libunwind</code> was specified
421*fceef8e0Santirez        during build configuration.</p></dd><dt><a name="config.stats"></a><span class="term">
422a78e148bSantirez
423a78e148bSantirez    "<code class="mallctl">config.stats</code>"
424a78e148bSantirez
425a78e148bSantirez          (<span class="type">bool</span>)
426a78e148bSantirez          <code class="literal">r-</code>
427a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-stats</code> was specified during
428*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.tcache"></a><span class="term">
429a78e148bSantirez
430a78e148bSantirez    "<code class="mallctl">config.tcache</code>"
431a78e148bSantirez
432a78e148bSantirez          (<span class="type">bool</span>)
433a78e148bSantirez          <code class="literal">r-</code>
434a78e148bSantirez        </span></dt><dd><p><code class="option">--disable-tcache</code> was not specified
435*fceef8e0Santirez        during build configuration.</p></dd><dt><a name="config.tls"></a><span class="term">
436a78e148bSantirez
437a78e148bSantirez    "<code class="mallctl">config.tls</code>"
438a78e148bSantirez
439a78e148bSantirez          (<span class="type">bool</span>)
440a78e148bSantirez          <code class="literal">r-</code>
441a78e148bSantirez        </span></dt><dd><p><code class="option">--disable-tls</code> was not specified during
442*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.utrace"></a><span class="term">
443a78e148bSantirez
444ad4c0b41Santirez    "<code class="mallctl">config.utrace</code>"
445ad4c0b41Santirez
446ad4c0b41Santirez          (<span class="type">bool</span>)
447ad4c0b41Santirez          <code class="literal">r-</code>
448ad4c0b41Santirez        </span></dt><dd><p><code class="option">--enable-utrace</code> was specified during
449*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.valgrind"></a><span class="term">
450ad4c0b41Santirez
451ad4c0b41Santirez    "<code class="mallctl">config.valgrind</code>"
452ad4c0b41Santirez
453ad4c0b41Santirez          (<span class="type">bool</span>)
454ad4c0b41Santirez          <code class="literal">r-</code>
455ad4c0b41Santirez        </span></dt><dd><p><code class="option">--enable-valgrind</code> was specified during
456*fceef8e0Santirez        build configuration.</p></dd><dt><a name="config.xmalloc"></a><span class="term">
457ad4c0b41Santirez
458a78e148bSantirez    "<code class="mallctl">config.xmalloc</code>"
459a78e148bSantirez
460a78e148bSantirez          (<span class="type">bool</span>)
461a78e148bSantirez          <code class="literal">r-</code>
462a78e148bSantirez        </span></dt><dd><p><code class="option">--enable-xmalloc</code> was specified during
463a78e148bSantirez        build configuration.</p></dd><dt><a name="opt.abort"></a><span class="term">
464a78e148bSantirez
465a78e148bSantirez    "<code class="mallctl">opt.abort</code>"
466a78e148bSantirez
467a78e148bSantirez          (<span class="type">bool</span>)
468a78e148bSantirez          <code class="literal">r-</code>
469a78e148bSantirez        </span></dt><dd><p>Abort-on-warning enabled/disabled.  If true, most
470a78e148bSantirez        warnings are fatal.  The process will call
471a78e148bSantirez        <span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span> in these cases.  This option is
472a78e148bSantirez        disabled by default unless <code class="option">--enable-debug</code> is
473a78e148bSantirez        specified during configuration, in which case it is enabled by default.
474*fceef8e0Santirez        </p></dd><dt><a name="opt.dss"></a><span class="term">
4757383c3b1Santirez
4767383c3b1Santirez    "<code class="mallctl">opt.dss</code>"
4777383c3b1Santirez
4787383c3b1Santirez          (<span class="type">const char *</span>)
4797383c3b1Santirez          <code class="literal">r-</code>
4807383c3b1Santirez        </span></dt><dd><p>dss (<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>) allocation precedence as
4817383c3b1Santirez        related to <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> allocation.  The following
4827383c3b1Santirez        settings are supported: &#8220;disabled&#8221;, &#8220;primary&#8221;,
483*fceef8e0Santirez        and &#8220;secondary&#8221;.  The default is &#8220;secondary&#8221; if
484*fceef8e0Santirez        <a class="link" href="#config.dss">
485*fceef8e0Santirez    "<code class="mallctl">config.dss</code>"
486*fceef8e0Santirez  </a> is
487*fceef8e0Santirez        true, &#8220;disabled&#8221; otherwise.
488*fceef8e0Santirez        </p></dd><dt><a name="opt.lg_chunk"></a><span class="term">
489*fceef8e0Santirez
490*fceef8e0Santirez    "<code class="mallctl">opt.lg_chunk</code>"
491*fceef8e0Santirez
492*fceef8e0Santirez          (<span class="type">size_t</span>)
493*fceef8e0Santirez          <code class="literal">r-</code>
494*fceef8e0Santirez        </span></dt><dd><p>Virtual memory chunk size (log base 2).  If a chunk
495*fceef8e0Santirez        size outside the supported size range is specified, the size is
496*fceef8e0Santirez        silently clipped to the minimum/maximum supported size.  The default
497*fceef8e0Santirez        chunk size is 4 MiB (2^22).
498*fceef8e0Santirez        </p></dd><dt><a name="opt.narenas"></a><span class="term">
499a78e148bSantirez
500a78e148bSantirez    "<code class="mallctl">opt.narenas</code>"
501a78e148bSantirez
502a78e148bSantirez          (<span class="type">size_t</span>)
503a78e148bSantirez          <code class="literal">r-</code>
5047383c3b1Santirez        </span></dt><dd><p>Maximum number of arenas to use for automatic
5057383c3b1Santirez        multiplexing of threads and arenas.  The default is four times the
5067383c3b1Santirez        number of CPUs, or one if there is a single CPU.</p></dd><dt><a name="opt.lg_dirty_mult"></a><span class="term">
507a78e148bSantirez
508a78e148bSantirez    "<code class="mallctl">opt.lg_dirty_mult</code>"
509a78e148bSantirez
510a78e148bSantirez          (<span class="type">ssize_t</span>)
511a78e148bSantirez          <code class="literal">r-</code>
512a78e148bSantirez        </span></dt><dd><p>Per-arena minimum ratio (log base 2) of active to dirty
513a78e148bSantirez        pages.  Some dirty unused pages may be allowed to accumulate, within
514a78e148bSantirez        the limit set by the ratio (or one chunk worth of dirty pages,
515a78e148bSantirez        whichever is greater), before informing the kernel about some of those
516a78e148bSantirez        pages via <span class="citerefentry"><span class="refentrytitle">madvise</span>(2)</span> or a similar system call.  This
517a78e148bSantirez        provides the kernel with sufficient information to recycle dirty pages
518a78e148bSantirez        if physical memory becomes scarce and the pages remain unused.  The
5197383c3b1Santirez        default minimum ratio is 8:1 (2^3:1); an option value of -1 will
520a78e148bSantirez        disable dirty page purging.</p></dd><dt><a name="opt.stats_print"></a><span class="term">
521a78e148bSantirez
522a78e148bSantirez    "<code class="mallctl">opt.stats_print</code>"
523a78e148bSantirez
524a78e148bSantirez          (<span class="type">bool</span>)
525a78e148bSantirez          <code class="literal">r-</code>
526a78e148bSantirez        </span></dt><dd><p>Enable/disable statistics printing at exit.  If
527a78e148bSantirez        enabled, the <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>)
528a78e148bSantirez        function is called at program exit via an
529a78e148bSantirez        <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function.  If
530a78e148bSantirez        <code class="option">--enable-stats</code> is specified during configuration, this
531a78e148bSantirez        has the potential to cause deadlock for a multi-threaded process that
532a78e148bSantirez        exits while one or more threads are executing in the memory allocation
533a78e148bSantirez        functions.  Therefore, this option should only be used with care; it is
534a78e148bSantirez        primarily intended as a performance tuning aid during application
535a78e148bSantirez        development.  This option is disabled by default.</p></dd><dt><a name="opt.junk"></a><span class="term">
536a78e148bSantirez
537a78e148bSantirez    "<code class="mallctl">opt.junk</code>"
538a78e148bSantirez
539a78e148bSantirez          (<span class="type">bool</span>)
540a78e148bSantirez          <code class="literal">r-</code>
541a78e148bSantirez          [<code class="option">--enable-fill</code>]
542a78e148bSantirez        </span></dt><dd><p>Junk filling enabled/disabled.  If enabled, each byte
543a78e148bSantirez        of uninitialized allocated memory will be initialized to
544a78e148bSantirez        <code class="literal">0xa5</code>.  All deallocated memory will be initialized to
545a78e148bSantirez        <code class="literal">0x5a</code>.  This is intended for debugging and will
546a78e148bSantirez        impact performance negatively.  This option is disabled by default
547a78e148bSantirez        unless <code class="option">--enable-debug</code> is specified during
5487383c3b1Santirez        configuration, in which case it is enabled by default unless running
5497383c3b1Santirez        inside <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>.</p></dd><dt><a name="opt.quarantine"></a><span class="term">
550ad4c0b41Santirez
551ad4c0b41Santirez    "<code class="mallctl">opt.quarantine</code>"
552ad4c0b41Santirez
553ad4c0b41Santirez          (<span class="type">size_t</span>)
554ad4c0b41Santirez          <code class="literal">r-</code>
555ad4c0b41Santirez          [<code class="option">--enable-fill</code>]
556ad4c0b41Santirez        </span></dt><dd><p>Per thread quarantine size in bytes.  If non-zero, each
557ad4c0b41Santirez        thread maintains a FIFO object quarantine that stores up to the
558ad4c0b41Santirez        specified number of bytes of memory.  The quarantined memory is not
559ad4c0b41Santirez        freed until it is released from quarantine, though it is immediately
560ad4c0b41Santirez        junk-filled if the <a class="link" href="#opt.junk">
561ad4c0b41Santirez    "<code class="mallctl">opt.junk</code>"
562ad4c0b41Santirez  </a> option is
563ad4c0b41Santirez        enabled.  This feature is of particular use in combination with <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>, which can detect attempts
564ad4c0b41Santirez        to access quarantined objects.  This is intended for debugging and will
5657383c3b1Santirez        impact performance negatively.  The default quarantine size is 0 unless
5667383c3b1Santirez        running inside Valgrind, in which case the default is 16
5677383c3b1Santirez        MiB.</p></dd><dt><a name="opt.redzone"></a><span class="term">
568ad4c0b41Santirez
569ad4c0b41Santirez    "<code class="mallctl">opt.redzone</code>"
570ad4c0b41Santirez
571ad4c0b41Santirez          (<span class="type">bool</span>)
572ad4c0b41Santirez          <code class="literal">r-</code>
573ad4c0b41Santirez          [<code class="option">--enable-fill</code>]
574ad4c0b41Santirez        </span></dt><dd><p>Redzones enabled/disabled.  If enabled, small
575ad4c0b41Santirez        allocations have redzones before and after them.  Furthermore, if the
576ad4c0b41Santirez        <a class="link" href="#opt.junk">
577ad4c0b41Santirez    "<code class="mallctl">opt.junk</code>"
578ad4c0b41Santirez  </a> option is
579ad4c0b41Santirez        enabled, the redzones are checked for corruption during deallocation.
580ad4c0b41Santirez        However, the primary intended purpose of this feature is to be used in
581ad4c0b41Santirez        combination with <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>,
582ad4c0b41Santirez        which needs redzones in order to do effective buffer overflow/underflow
583ad4c0b41Santirez        detection.  This option is intended for debugging and will impact
584ad4c0b41Santirez        performance negatively.  This option is disabled by
5857383c3b1Santirez        default unless running inside Valgrind.</p></dd><dt><a name="opt.zero"></a><span class="term">
586a78e148bSantirez
587a78e148bSantirez    "<code class="mallctl">opt.zero</code>"
588a78e148bSantirez
589a78e148bSantirez          (<span class="type">bool</span>)
590a78e148bSantirez          <code class="literal">r-</code>
591a78e148bSantirez          [<code class="option">--enable-fill</code>]
592a78e148bSantirez        </span></dt><dd><p>Zero filling enabled/disabled.  If enabled, each byte
593a78e148bSantirez        of uninitialized allocated memory will be initialized to 0.  Note that
594a78e148bSantirez        this initialization only happens once for each byte, so
595*fceef8e0Santirez        <code class="function">realloc</code>(<em class="parameter"><code></code></em>),
596*fceef8e0Santirez        <code class="function">rallocx</code>(<em class="parameter"><code></code></em>) and
597a78e148bSantirez        <code class="function">rallocm</code>(<em class="parameter"><code></code></em>) calls do not zero memory that
598a78e148bSantirez        was previously allocated.  This is intended for debugging and will
599a78e148bSantirez        impact performance negatively.  This option is disabled by default.
600ad4c0b41Santirez        </p></dd><dt><a name="opt.utrace"></a><span class="term">
601a78e148bSantirez
602ad4c0b41Santirez    "<code class="mallctl">opt.utrace</code>"
603a78e148bSantirez
604a78e148bSantirez          (<span class="type">bool</span>)
605a78e148bSantirez          <code class="literal">r-</code>
606ad4c0b41Santirez          [<code class="option">--enable-utrace</code>]
607ad4c0b41Santirez        </span></dt><dd><p>Allocation tracing based on
608ad4c0b41Santirez        <span class="citerefentry"><span class="refentrytitle">utrace</span>(2)</span> enabled/disabled.  This option
609ad4c0b41Santirez        is disabled by default.</p></dd><dt><a name="opt.valgrind"></a><span class="term">
610ad4c0b41Santirez
611ad4c0b41Santirez    "<code class="mallctl">opt.valgrind</code>"
612ad4c0b41Santirez
613ad4c0b41Santirez          (<span class="type">bool</span>)
614ad4c0b41Santirez          <code class="literal">r-</code>
615ad4c0b41Santirez          [<code class="option">--enable-valgrind</code>]
616ad4c0b41Santirez        </span></dt><dd><p><a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>
6177383c3b1Santirez        support enabled/disabled.  This option is vestigal because jemalloc
6187383c3b1Santirez        auto-detects whether it is running inside Valgrind.  This option is
6197383c3b1Santirez        disabled by default, unless running inside Valgrind.</p></dd><dt><a name="opt.xmalloc"></a><span class="term">
620a78e148bSantirez
621a78e148bSantirez    "<code class="mallctl">opt.xmalloc</code>"
622a78e148bSantirez
623a78e148bSantirez          (<span class="type">bool</span>)
624a78e148bSantirez          <code class="literal">r-</code>
625a78e148bSantirez          [<code class="option">--enable-xmalloc</code>]
626a78e148bSantirez        </span></dt><dd><p>Abort-on-out-of-memory enabled/disabled.  If enabled,
627a78e148bSantirez        rather than returning failure for any allocation function, display a
628a78e148bSantirez        diagnostic message on <code class="constant">STDERR_FILENO</code> and cause the
629a78e148bSantirez        program to drop core (using
630a78e148bSantirez        <span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span>).  If an application is
631a78e148bSantirez        designed to depend on this behavior, set the option at compile time by
632a78e148bSantirez        including the following in the source code:
633a78e148bSantirez        </p><pre class="programlisting">
634a78e148bSantirezmalloc_conf = "xmalloc:true";</pre><p>
635a78e148bSantirez        This option is disabled by default.</p></dd><dt><a name="opt.tcache"></a><span class="term">
636a78e148bSantirez
637a78e148bSantirez    "<code class="mallctl">opt.tcache</code>"
638a78e148bSantirez
639a78e148bSantirez          (<span class="type">bool</span>)
640a78e148bSantirez          <code class="literal">r-</code>
641a78e148bSantirez          [<code class="option">--enable-tcache</code>]
642a78e148bSantirez        </span></dt><dd><p>Thread-specific caching enabled/disabled.  When there
643a78e148bSantirez        are multiple threads, each thread uses a thread-specific cache for
644a78e148bSantirez        objects up to a certain size.  Thread-specific caching allows many
645a78e148bSantirez        allocations to be satisfied without performing any thread
646a78e148bSantirez        synchronization, at the cost of increased memory use.  See the
647ad4c0b41Santirez        <a class="link" href="#opt.lg_tcache_max">
648a78e148bSantirez    "<code class="mallctl">opt.lg_tcache_max</code>"
649a78e148bSantirez  </a>
650ad4c0b41Santirez        option for related tuning information.  This option is enabled by
6517383c3b1Santirez        default unless running inside <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>.</p></dd><dt><a name="opt.lg_tcache_max"></a><span class="term">
652a78e148bSantirez
653a78e148bSantirez    "<code class="mallctl">opt.lg_tcache_max</code>"
654a78e148bSantirez
655a78e148bSantirez          (<span class="type">size_t</span>)
656a78e148bSantirez          <code class="literal">r-</code>
657a78e148bSantirez          [<code class="option">--enable-tcache</code>]
658a78e148bSantirez        </span></dt><dd><p>Maximum size class (log base 2) to cache in the
659a78e148bSantirez        thread-specific cache.  At a minimum, all small size classes are
660a78e148bSantirez        cached, and at a maximum all large size classes are cached.  The
661a78e148bSantirez        default maximum is 32 KiB (2^15).</p></dd><dt><a name="opt.prof"></a><span class="term">
662a78e148bSantirez
663a78e148bSantirez    "<code class="mallctl">opt.prof</code>"
664a78e148bSantirez
665a78e148bSantirez          (<span class="type">bool</span>)
666a78e148bSantirez          <code class="literal">r-</code>
667a78e148bSantirez          [<code class="option">--enable-prof</code>]
668a78e148bSantirez        </span></dt><dd><p>Memory profiling enabled/disabled.  If enabled, profile
669ad4c0b41Santirez        memory allocation activity.  See the <a class="link" href="#opt.prof_active">
670a78e148bSantirez    "<code class="mallctl">opt.prof_active</code>"
671a78e148bSantirez  </a>
672a78e148bSantirez        option for on-the-fly activation/deactivation.  See the <a class="link" href="#opt.lg_prof_sample">
673a78e148bSantirez    "<code class="mallctl">opt.lg_prof_sample</code>"
674a78e148bSantirez  </a>
675a78e148bSantirez        option for probabilistic sampling control.  See the <a class="link" href="#opt.prof_accum">
676a78e148bSantirez    "<code class="mallctl">opt.prof_accum</code>"
677a78e148bSantirez  </a>
678ad4c0b41Santirez        option for control of cumulative sample reporting.  See the <a class="link" href="#opt.lg_prof_interval">
679a78e148bSantirez    "<code class="mallctl">opt.lg_prof_interval</code>"
680a78e148bSantirez  </a>
681ad4c0b41Santirez        option for information on interval-triggered profile dumping, the <a class="link" href="#opt.prof_gdump">
682a78e148bSantirez    "<code class="mallctl">opt.prof_gdump</code>"
683a78e148bSantirez  </a>
684ad4c0b41Santirez        option for information on high-water-triggered profile dumping, and the
685ad4c0b41Santirez        <a class="link" href="#opt.prof_final">
686ad4c0b41Santirez    "<code class="mallctl">opt.prof_final</code>"
687ad4c0b41Santirez  </a>
688ad4c0b41Santirez        option for final profile dumping.  Profile output is compatible with
689ad4c0b41Santirez        the included <span class="command"><strong>pprof</strong></span> Perl script, which originates
690ad4c0b41Santirez        from the <a class="ulink" href="http://code.google.com/p/gperftools/" target="_top">gperftools
691a78e148bSantirez        package</a>.</p></dd><dt><a name="opt.prof_prefix"></a><span class="term">
692a78e148bSantirez
693a78e148bSantirez    "<code class="mallctl">opt.prof_prefix</code>"
694a78e148bSantirez
695a78e148bSantirez          (<span class="type">const char *</span>)
696a78e148bSantirez          <code class="literal">r-</code>
697a78e148bSantirez          [<code class="option">--enable-prof</code>]
698a78e148bSantirez        </span></dt><dd><p>Filename prefix for profile dumps.  If the prefix is
699a78e148bSantirez        set to the empty string, no automatic dumps will occur; this is
700a78e148bSantirez        primarily useful for disabling the automatic final heap dump (which
701a78e148bSantirez        also disables leak reporting, if enabled).  The default prefix is
702ad4c0b41Santirez        <code class="filename">jeprof</code>.</p></dd><dt><a name="opt.prof_active"></a><span class="term">
703a78e148bSantirez
704a78e148bSantirez    "<code class="mallctl">opt.prof_active</code>"
705a78e148bSantirez
706a78e148bSantirez          (<span class="type">bool</span>)
707*fceef8e0Santirez          <code class="literal">rw</code>
708a78e148bSantirez          [<code class="option">--enable-prof</code>]
709a78e148bSantirez        </span></dt><dd><p>Profiling activated/deactivated.  This is a secondary
710a78e148bSantirez        control mechanism that makes it possible to start the application with
711a78e148bSantirez        profiling enabled (see the <a class="link" href="#opt.prof">
712a78e148bSantirez    "<code class="mallctl">opt.prof</code>"
713a78e148bSantirez  </a> option) but
714a78e148bSantirez        inactive, then toggle profiling at any time during program execution
715a78e148bSantirez        with the <a class="link" href="#prof.active">
716a78e148bSantirez    "<code class="mallctl">prof.active</code>"
717a78e148bSantirez  </a> mallctl.
718a78e148bSantirez        This option is enabled by default.</p></dd><dt><a name="opt.lg_prof_sample"></a><span class="term">
719a78e148bSantirez
720a78e148bSantirez    "<code class="mallctl">opt.lg_prof_sample</code>"
721a78e148bSantirez
722a78e148bSantirez          (<span class="type">ssize_t</span>)
723a78e148bSantirez          <code class="literal">r-</code>
724a78e148bSantirez          [<code class="option">--enable-prof</code>]
725a78e148bSantirez        </span></dt><dd><p>Average interval (log base 2) between allocation
726a78e148bSantirez        samples, as measured in bytes of allocation activity.  Increasing the
727a78e148bSantirez        sampling interval decreases profile fidelity, but also decreases the
728ad4c0b41Santirez        computational overhead.  The default sample interval is 512 KiB (2^19
729ad4c0b41Santirez        B).</p></dd><dt><a name="opt.prof_accum"></a><span class="term">
730a78e148bSantirez
731a78e148bSantirez    "<code class="mallctl">opt.prof_accum</code>"
732a78e148bSantirez
733a78e148bSantirez          (<span class="type">bool</span>)
734a78e148bSantirez          <code class="literal">r-</code>
735a78e148bSantirez          [<code class="option">--enable-prof</code>]
736a78e148bSantirez        </span></dt><dd><p>Reporting of cumulative object/byte counts in profile
737a78e148bSantirez        dumps enabled/disabled.  If this option is enabled, every unique
738a78e148bSantirez        backtrace must be stored for the duration of execution.  Depending on
739a78e148bSantirez        the application, this can impose a large memory overhead, and the
740ad4c0b41Santirez        cumulative counts are not always of interest.  This option is disabled
741ad4c0b41Santirez        by default.</p></dd><dt><a name="opt.lg_prof_interval"></a><span class="term">
742a78e148bSantirez
743a78e148bSantirez    "<code class="mallctl">opt.lg_prof_interval</code>"
744a78e148bSantirez
745a78e148bSantirez          (<span class="type">ssize_t</span>)
746a78e148bSantirez          <code class="literal">r-</code>
747a78e148bSantirez          [<code class="option">--enable-prof</code>]
748a78e148bSantirez        </span></dt><dd><p>Average interval (log base 2) between memory profile
749a78e148bSantirez        dumps, as measured in bytes of allocation activity.  The actual
750a78e148bSantirez        interval between dumps may be sporadic because decentralized allocation
751a78e148bSantirez        counters are used to avoid synchronization bottlenecks.  Profiles are
752a78e148bSantirez        dumped to files named according to the pattern
753a78e148bSantirez        <code class="filename">&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.i&lt;iseq&gt;.heap</code>,
754a78e148bSantirez        where <code class="literal">&lt;prefix&gt;</code> is controlled by the
755a78e148bSantirez        <a class="link" href="#opt.prof_prefix">
756a78e148bSantirez    "<code class="mallctl">opt.prof_prefix</code>"
757a78e148bSantirez  </a>
758a78e148bSantirez        option.  By default, interval-triggered profile dumping is disabled
759a78e148bSantirez        (encoded as -1).
760a78e148bSantirez        </p></dd><dt><a name="opt.prof_gdump"></a><span class="term">
761a78e148bSantirez
762a78e148bSantirez    "<code class="mallctl">opt.prof_gdump</code>"
763a78e148bSantirez
764a78e148bSantirez          (<span class="type">bool</span>)
765a78e148bSantirez          <code class="literal">r-</code>
766a78e148bSantirez          [<code class="option">--enable-prof</code>]
767a78e148bSantirez        </span></dt><dd><p>Trigger a memory profile dump every time the total
768a78e148bSantirez        virtual memory exceeds the previous maximum.  Profiles are dumped to
769a78e148bSantirez        files named according to the pattern
770a78e148bSantirez        <code class="filename">&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.u&lt;useq&gt;.heap</code>,
771a78e148bSantirez        where <code class="literal">&lt;prefix&gt;</code> is controlled by the <a class="link" href="#opt.prof_prefix">
772a78e148bSantirez    "<code class="mallctl">opt.prof_prefix</code>"
773a78e148bSantirez  </a>
774ad4c0b41Santirez        option.  This option is disabled by default.</p></dd><dt><a name="opt.prof_final"></a><span class="term">
775ad4c0b41Santirez
776ad4c0b41Santirez    "<code class="mallctl">opt.prof_final</code>"
777ad4c0b41Santirez
778ad4c0b41Santirez          (<span class="type">bool</span>)
779ad4c0b41Santirez          <code class="literal">r-</code>
780ad4c0b41Santirez          [<code class="option">--enable-prof</code>]
781ad4c0b41Santirez        </span></dt><dd><p>Use an
782ad4c0b41Santirez        <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function to dump final memory
783ad4c0b41Santirez        usage to a file named according to the pattern
784ad4c0b41Santirez        <code class="filename">&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.f.heap</code>,
785ad4c0b41Santirez        where <code class="literal">&lt;prefix&gt;</code> is controlled by the <a class="link" href="#opt.prof_prefix">
786ad4c0b41Santirez    "<code class="mallctl">opt.prof_prefix</code>"
787ad4c0b41Santirez  </a>
788ad4c0b41Santirez        option.  This option is enabled by default.</p></dd><dt><a name="opt.prof_leak"></a><span class="term">
789a78e148bSantirez
790a78e148bSantirez    "<code class="mallctl">opt.prof_leak</code>"
791a78e148bSantirez
792a78e148bSantirez          (<span class="type">bool</span>)
793a78e148bSantirez          <code class="literal">r-</code>
794a78e148bSantirez          [<code class="option">--enable-prof</code>]
795a78e148bSantirez        </span></dt><dd><p>Leak reporting enabled/disabled.  If enabled, use an
796a78e148bSantirez        <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function to report memory leaks
797a78e148bSantirez        detected by allocation sampling.  See the
798a78e148bSantirez        <a class="link" href="#opt.prof">
799a78e148bSantirez    "<code class="mallctl">opt.prof</code>"
800a78e148bSantirez  </a> option for
801a78e148bSantirez        information on analyzing heap profile output.  This option is disabled
802*fceef8e0Santirez        by default.</p></dd><dt><a name="thread.arena"></a><span class="term">
803a78e148bSantirez
804a78e148bSantirez    "<code class="mallctl">thread.arena</code>"
805a78e148bSantirez
806a78e148bSantirez          (<span class="type">unsigned</span>)
807a78e148bSantirez          <code class="literal">rw</code>
808a78e148bSantirez        </span></dt><dd><p>Get or set the arena associated with the calling
8097383c3b1Santirez        thread.  If the specified arena was not initialized beforehand (see the
8107383c3b1Santirez        <a class="link" href="#arenas.initialized">
811a78e148bSantirez    "<code class="mallctl">arenas.initialized</code>"
812a78e148bSantirez  </a>
813a78e148bSantirez        mallctl), it will be automatically initialized as a side effect of
814a78e148bSantirez        calling this interface.</p></dd><dt><a name="thread.allocated"></a><span class="term">
815a78e148bSantirez
816a78e148bSantirez    "<code class="mallctl">thread.allocated</code>"
817a78e148bSantirez
818a78e148bSantirez          (<span class="type">uint64_t</span>)
819a78e148bSantirez          <code class="literal">r-</code>
820a78e148bSantirez          [<code class="option">--enable-stats</code>]
821a78e148bSantirez        </span></dt><dd><p>Get the total number of bytes ever allocated by the
822a78e148bSantirez        calling thread.  This counter has the potential to wrap around; it is
823a78e148bSantirez        up to the application to appropriately interpret the counter in such
824*fceef8e0Santirez        cases.</p></dd><dt><a name="thread.allocatedp"></a><span class="term">
825a78e148bSantirez
826a78e148bSantirez    "<code class="mallctl">thread.allocatedp</code>"
827a78e148bSantirez
828a78e148bSantirez          (<span class="type">uint64_t *</span>)
829a78e148bSantirez          <code class="literal">r-</code>
830a78e148bSantirez          [<code class="option">--enable-stats</code>]
831a78e148bSantirez        </span></dt><dd><p>Get a pointer to the the value that is returned by the
832a78e148bSantirez        <a class="link" href="#thread.allocated">
833a78e148bSantirez    "<code class="mallctl">thread.allocated</code>"
834a78e148bSantirez  </a>
835a78e148bSantirez        mallctl.  This is useful for avoiding the overhead of repeated
836a78e148bSantirez        <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) calls.</p></dd><dt><a name="thread.deallocated"></a><span class="term">
837a78e148bSantirez
838a78e148bSantirez    "<code class="mallctl">thread.deallocated</code>"
839a78e148bSantirez
840a78e148bSantirez          (<span class="type">uint64_t</span>)
841a78e148bSantirez          <code class="literal">r-</code>
842a78e148bSantirez          [<code class="option">--enable-stats</code>]
843a78e148bSantirez        </span></dt><dd><p>Get the total number of bytes ever deallocated by the
844a78e148bSantirez        calling thread.  This counter has the potential to wrap around; it is
845a78e148bSantirez        up to the application to appropriately interpret the counter in such
846*fceef8e0Santirez        cases.</p></dd><dt><a name="thread.deallocatedp"></a><span class="term">
847a78e148bSantirez
848a78e148bSantirez    "<code class="mallctl">thread.deallocatedp</code>"
849a78e148bSantirez
850a78e148bSantirez          (<span class="type">uint64_t *</span>)
851a78e148bSantirez          <code class="literal">r-</code>
852a78e148bSantirez          [<code class="option">--enable-stats</code>]
853a78e148bSantirez        </span></dt><dd><p>Get a pointer to the the value that is returned by the
854a78e148bSantirez        <a class="link" href="#thread.deallocated">
855a78e148bSantirez    "<code class="mallctl">thread.deallocated</code>"
856a78e148bSantirez  </a>
857a78e148bSantirez        mallctl.  This is useful for avoiding the overhead of repeated
858*fceef8e0Santirez        <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) calls.</p></dd><dt><a name="thread.tcache.enabled"></a><span class="term">
859ad4c0b41Santirez
860ad4c0b41Santirez    "<code class="mallctl">thread.tcache.enabled</code>"
861ad4c0b41Santirez
862ad4c0b41Santirez          (<span class="type">bool</span>)
863ad4c0b41Santirez          <code class="literal">rw</code>
864ad4c0b41Santirez          [<code class="option">--enable-tcache</code>]
865ad4c0b41Santirez        </span></dt><dd><p>Enable/disable calling thread's tcache.  The tcache is
866ad4c0b41Santirez        implicitly flushed as a side effect of becoming
867ad4c0b41Santirez        disabled (see
868ad4c0b41Santirez    "<code class="mallctl">thread.tcache.flush</code>"
869ad4c0b41Santirez  ).
870*fceef8e0Santirez        </p></dd><dt><a name="thread.tcache.flush"></a><span class="term">
871ad4c0b41Santirez
872ad4c0b41Santirez    "<code class="mallctl">thread.tcache.flush</code>"
873ad4c0b41Santirez
874ad4c0b41Santirez          (<span class="type">void</span>)
875ad4c0b41Santirez          <code class="literal">--</code>
876ad4c0b41Santirez          [<code class="option">--enable-tcache</code>]
877ad4c0b41Santirez        </span></dt><dd><p>Flush calling thread's tcache.  This interface releases
878ad4c0b41Santirez        all cached objects and internal data structures associated with the
879ad4c0b41Santirez        calling thread's thread-specific cache.  Ordinarily, this interface
880ad4c0b41Santirez        need not be called, since automatic periodic incremental garbage
881ad4c0b41Santirez        collection occurs, and the thread cache is automatically discarded when
882ad4c0b41Santirez        a thread exits.  However, garbage collection is triggered by allocation
883ad4c0b41Santirez        activity, so it is possible for a thread that stops
884ad4c0b41Santirez        allocating/deallocating to retain its cache indefinitely, in which case
8857383c3b1Santirez        the developer may find manual flushing useful.</p></dd><dt><a name="arena.i.purge"></a><span class="term">
8867383c3b1Santirez
8877383c3b1Santirez    "<code class="mallctl">arena.&lt;i&gt;.purge</code>"
8887383c3b1Santirez
8897383c3b1Santirez          (<span class="type">unsigned</span>)
8907383c3b1Santirez          <code class="literal">--</code>
8917383c3b1Santirez        </span></dt><dd><p>Purge unused dirty pages for arena &lt;i&gt;, or for
8927383c3b1Santirez        all arenas if &lt;i&gt; equals <a class="link" href="#arenas.narenas">
8937383c3b1Santirez    "<code class="mallctl">arenas.narenas</code>"
8947383c3b1Santirez  </a>.
8957383c3b1Santirez        </p></dd><dt><a name="arena.i.dss"></a><span class="term">
8967383c3b1Santirez
8977383c3b1Santirez    "<code class="mallctl">arena.&lt;i&gt;.dss</code>"
8987383c3b1Santirez
8997383c3b1Santirez          (<span class="type">const char *</span>)
9007383c3b1Santirez          <code class="literal">rw</code>
9017383c3b1Santirez        </span></dt><dd><p>Set the precedence of dss allocation as related to mmap
9027383c3b1Santirez        allocation for arena &lt;i&gt;, or for all arenas if &lt;i&gt; equals
9037383c3b1Santirez        <a class="link" href="#arenas.narenas">
9047383c3b1Santirez    "<code class="mallctl">arenas.narenas</code>"
905*fceef8e0Santirez  </a>.  Note
906*fceef8e0Santirez        that even during huge allocation this setting is read from the arena
907*fceef8e0Santirez        that would be chosen for small or large allocation so that applications
908*fceef8e0Santirez        can depend on consistent dss versus mmap allocation regardless of
909*fceef8e0Santirez        allocation size.  See <a class="link" href="#opt.dss">
9107383c3b1Santirez    "<code class="mallctl">opt.dss</code>"
9117383c3b1Santirez  </a> for supported
9127383c3b1Santirez        settings.
9137383c3b1Santirez        </p></dd><dt><a name="arenas.narenas"></a><span class="term">
914a78e148bSantirez
915a78e148bSantirez    "<code class="mallctl">arenas.narenas</code>"
916a78e148bSantirez
917a78e148bSantirez          (<span class="type">unsigned</span>)
918a78e148bSantirez          <code class="literal">r-</code>
9197383c3b1Santirez        </span></dt><dd><p>Current limit on number of arenas.</p></dd><dt><a name="arenas.initialized"></a><span class="term">
920a78e148bSantirez
921a78e148bSantirez    "<code class="mallctl">arenas.initialized</code>"
922a78e148bSantirez
923a78e148bSantirez          (<span class="type">bool *</span>)
924a78e148bSantirez          <code class="literal">r-</code>
925a78e148bSantirez        </span></dt><dd><p>An array of <a class="link" href="#arenas.narenas">
926a78e148bSantirez    "<code class="mallctl">arenas.narenas</code>"
927a78e148bSantirez  </a>
928a78e148bSantirez        booleans.  Each boolean indicates whether the corresponding arena is
929*fceef8e0Santirez        initialized.</p></dd><dt><a name="arenas.quantum"></a><span class="term">
930a78e148bSantirez
931a78e148bSantirez    "<code class="mallctl">arenas.quantum</code>"
932a78e148bSantirez
933a78e148bSantirez          (<span class="type">size_t</span>)
934a78e148bSantirez          <code class="literal">r-</code>
935*fceef8e0Santirez        </span></dt><dd><p>Quantum size.</p></dd><dt><a name="arenas.page"></a><span class="term">
936a78e148bSantirez
937ad4c0b41Santirez    "<code class="mallctl">arenas.page</code>"
938a78e148bSantirez
939a78e148bSantirez          (<span class="type">size_t</span>)
940a78e148bSantirez          <code class="literal">r-</code>
941*fceef8e0Santirez        </span></dt><dd><p>Page size.</p></dd><dt><a name="arenas.tcache_max"></a><span class="term">
942a78e148bSantirez
943a78e148bSantirez    "<code class="mallctl">arenas.tcache_max</code>"
944a78e148bSantirez
945a78e148bSantirez          (<span class="type">size_t</span>)
946a78e148bSantirez          <code class="literal">r-</code>
947a78e148bSantirez          [<code class="option">--enable-tcache</code>]
948*fceef8e0Santirez        </span></dt><dd><p>Maximum thread-cached size class.</p></dd><dt><a name="arenas.nbins"></a><span class="term">
949a78e148bSantirez
950a78e148bSantirez    "<code class="mallctl">arenas.nbins</code>"
951a78e148bSantirez
952a78e148bSantirez          (<span class="type">unsigned</span>)
953a78e148bSantirez          <code class="literal">r-</code>
954*fceef8e0Santirez        </span></dt><dd><p>Number of bin size classes.</p></dd><dt><a name="arenas.nhbins"></a><span class="term">
955a78e148bSantirez
956a78e148bSantirez    "<code class="mallctl">arenas.nhbins</code>"
957a78e148bSantirez
958a78e148bSantirez          (<span class="type">unsigned</span>)
959a78e148bSantirez          <code class="literal">r-</code>
960a78e148bSantirez          [<code class="option">--enable-tcache</code>]
961a78e148bSantirez        </span></dt><dd><p>Total number of thread cache bin size
962a78e148bSantirez        classes.</p></dd><dt><a name="arenas.bin.i.size"></a><span class="term">
963a78e148bSantirez
964a78e148bSantirez    "<code class="mallctl">arenas.bin.&lt;i&gt;.size</code>"
965a78e148bSantirez
966a78e148bSantirez          (<span class="type">size_t</span>)
967a78e148bSantirez          <code class="literal">r-</code>
968*fceef8e0Santirez        </span></dt><dd><p>Maximum size supported by size class.</p></dd><dt><a name="arenas.bin.i.nregs"></a><span class="term">
969a78e148bSantirez
970a78e148bSantirez    "<code class="mallctl">arenas.bin.&lt;i&gt;.nregs</code>"
971a78e148bSantirez
972a78e148bSantirez          (<span class="type">uint32_t</span>)
973a78e148bSantirez          <code class="literal">r-</code>
974*fceef8e0Santirez        </span></dt><dd><p>Number of regions per page run.</p></dd><dt><a name="arenas.bin.i.run_size"></a><span class="term">
975a78e148bSantirez
976a78e148bSantirez    "<code class="mallctl">arenas.bin.&lt;i&gt;.run_size</code>"
977a78e148bSantirez
978a78e148bSantirez          (<span class="type">size_t</span>)
979a78e148bSantirez          <code class="literal">r-</code>
980*fceef8e0Santirez        </span></dt><dd><p>Number of bytes per page run.</p></dd><dt><a name="arenas.nlruns"></a><span class="term">
981a78e148bSantirez
982a78e148bSantirez    "<code class="mallctl">arenas.nlruns</code>"
983a78e148bSantirez
984a78e148bSantirez          (<span class="type">size_t</span>)
985a78e148bSantirez          <code class="literal">r-</code>
986*fceef8e0Santirez        </span></dt><dd><p>Total number of large size classes.</p></dd><dt><a name="arenas.lrun.i.size"></a><span class="term">
987a78e148bSantirez
988a78e148bSantirez    "<code class="mallctl">arenas.lrun.&lt;i&gt;.size</code>"
989a78e148bSantirez
990a78e148bSantirez          (<span class="type">size_t</span>)
991a78e148bSantirez          <code class="literal">r-</code>
992a78e148bSantirez        </span></dt><dd><p>Maximum size supported by this large size
993*fceef8e0Santirez        class.</p></dd><dt><a name="arenas.purge"></a><span class="term">
994a78e148bSantirez
995a78e148bSantirez    "<code class="mallctl">arenas.purge</code>"
996a78e148bSantirez
997a78e148bSantirez          (<span class="type">unsigned</span>)
998a78e148bSantirez          <code class="literal">-w</code>
999a78e148bSantirez        </span></dt><dd><p>Purge unused dirty pages for the specified arena, or
1000*fceef8e0Santirez        for all arenas if none is specified.</p></dd><dt><a name="arenas.extend"></a><span class="term">
10017383c3b1Santirez
10027383c3b1Santirez    "<code class="mallctl">arenas.extend</code>"
10037383c3b1Santirez
10047383c3b1Santirez          (<span class="type">unsigned</span>)
10057383c3b1Santirez          <code class="literal">r-</code>
10067383c3b1Santirez        </span></dt><dd><p>Extend the array of arenas by appending a new arena,
10077383c3b1Santirez        and returning the new arena index.</p></dd><dt><a name="prof.active"></a><span class="term">
1008a78e148bSantirez
1009a78e148bSantirez    "<code class="mallctl">prof.active</code>"
1010a78e148bSantirez
1011a78e148bSantirez          (<span class="type">bool</span>)
1012a78e148bSantirez          <code class="literal">rw</code>
1013a78e148bSantirez          [<code class="option">--enable-prof</code>]
1014a78e148bSantirez        </span></dt><dd><p>Control whether sampling is currently active.  See the
1015a78e148bSantirez        <a class="link" href="#opt.prof_active">
1016a78e148bSantirez    "<code class="mallctl">opt.prof_active</code>"
1017a78e148bSantirez  </a>
1018a78e148bSantirez        option for additional information.
1019*fceef8e0Santirez        </p></dd><dt><a name="prof.dump"></a><span class="term">
1020a78e148bSantirez
1021a78e148bSantirez    "<code class="mallctl">prof.dump</code>"
1022a78e148bSantirez
1023a78e148bSantirez          (<span class="type">const char *</span>)
1024a78e148bSantirez          <code class="literal">-w</code>
1025a78e148bSantirez          [<code class="option">--enable-prof</code>]
1026a78e148bSantirez        </span></dt><dd><p>Dump a memory profile to the specified file, or if NULL
1027a78e148bSantirez        is specified, to a file according to the pattern
1028a78e148bSantirez        <code class="filename">&lt;prefix&gt;.&lt;pid&gt;.&lt;seq&gt;.m&lt;mseq&gt;.heap</code>,
1029a78e148bSantirez        where <code class="literal">&lt;prefix&gt;</code> is controlled by the
1030a78e148bSantirez        <a class="link" href="#opt.prof_prefix">
1031a78e148bSantirez    "<code class="mallctl">opt.prof_prefix</code>"
1032a78e148bSantirez  </a>
1033*fceef8e0Santirez        option.</p></dd><dt><a name="prof.interval"></a><span class="term">
1034a78e148bSantirez
1035a78e148bSantirez    "<code class="mallctl">prof.interval</code>"
1036a78e148bSantirez
1037a78e148bSantirez          (<span class="type">uint64_t</span>)
1038a78e148bSantirez          <code class="literal">r-</code>
1039a78e148bSantirez          [<code class="option">--enable-prof</code>]
1040a78e148bSantirez        </span></dt><dd><p>Average number of bytes allocated between
1041a78e148bSantirez        inverval-based profile dumps.  See the
1042a78e148bSantirez        <a class="link" href="#opt.lg_prof_interval">
1043a78e148bSantirez    "<code class="mallctl">opt.lg_prof_interval</code>"
1044a78e148bSantirez  </a>
1045a78e148bSantirez        option for additional information.</p></dd><dt><a name="stats.cactive"></a><span class="term">
1046a78e148bSantirez
1047a78e148bSantirez    "<code class="mallctl">stats.cactive</code>"
1048a78e148bSantirez
1049a78e148bSantirez          (<span class="type">size_t *</span>)
1050a78e148bSantirez          <code class="literal">r-</code>
1051a78e148bSantirez          [<code class="option">--enable-stats</code>]
1052a78e148bSantirez        </span></dt><dd><p>Pointer to a counter that contains an approximate count
1053a78e148bSantirez        of the current number of bytes in active pages.  The estimate may be
1054a78e148bSantirez        high, but never low, because each arena rounds up to the nearest
1055a78e148bSantirez        multiple of the chunk size when computing its contribution to the
1056a78e148bSantirez        counter.  Note that the <a class="link" href="#epoch">
1057a78e148bSantirez    "<code class="mallctl">epoch</code>"
1058a78e148bSantirez  </a> mallctl has no bearing
1059a78e148bSantirez        on this counter.  Furthermore, counter consistency is maintained via
1060a78e148bSantirez        atomic operations, so it is necessary to use an atomic operation in
1061a78e148bSantirez        order to guarantee a consistent read when dereferencing the pointer.
1062a78e148bSantirez        </p></dd><dt><a name="stats.allocated"></a><span class="term">
1063a78e148bSantirez
1064a78e148bSantirez    "<code class="mallctl">stats.allocated</code>"
1065a78e148bSantirez
1066a78e148bSantirez          (<span class="type">size_t</span>)
1067a78e148bSantirez          <code class="literal">r-</code>
1068a78e148bSantirez          [<code class="option">--enable-stats</code>]
1069a78e148bSantirez        </span></dt><dd><p>Total number of bytes allocated by the
1070a78e148bSantirez        application.</p></dd><dt><a name="stats.active"></a><span class="term">
1071a78e148bSantirez
1072a78e148bSantirez    "<code class="mallctl">stats.active</code>"
1073a78e148bSantirez
1074a78e148bSantirez          (<span class="type">size_t</span>)
1075a78e148bSantirez          <code class="literal">r-</code>
1076a78e148bSantirez          [<code class="option">--enable-stats</code>]
1077a78e148bSantirez        </span></dt><dd><p>Total number of bytes in active pages allocated by the
1078a78e148bSantirez        application.  This is a multiple of the page size, and greater than or
1079a78e148bSantirez        equal to <a class="link" href="#stats.allocated">
1080a78e148bSantirez    "<code class="mallctl">stats.allocated</code>"
1081a78e148bSantirez  </a>.
10827383c3b1Santirez        This does not include <a class="link" href="#stats.arenas.i.pdirty">
10837383c3b1Santirez
10847383c3b1Santirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.pdirty</code>"
10857383c3b1Santirez  </a> and pages
1086*fceef8e0Santirez        entirely devoted to allocator metadata.</p></dd><dt><a name="stats.mapped"></a><span class="term">
1087a78e148bSantirez
1088a78e148bSantirez    "<code class="mallctl">stats.mapped</code>"
1089a78e148bSantirez
1090a78e148bSantirez          (<span class="type">size_t</span>)
1091a78e148bSantirez          <code class="literal">r-</code>
1092a78e148bSantirez          [<code class="option">--enable-stats</code>]
1093a78e148bSantirez        </span></dt><dd><p>Total number of bytes in chunks mapped on behalf of the
1094a78e148bSantirez        application.  This is a multiple of the chunk size, and is at least as
1095a78e148bSantirez        large as <a class="link" href="#stats.active">
1096a78e148bSantirez    "<code class="mallctl">stats.active</code>"
1097a78e148bSantirez  </a>.  This
1098*fceef8e0Santirez        does not include inactive chunks.</p></dd><dt><a name="stats.chunks.current"></a><span class="term">
1099a78e148bSantirez
1100a78e148bSantirez    "<code class="mallctl">stats.chunks.current</code>"
1101a78e148bSantirez
1102a78e148bSantirez          (<span class="type">size_t</span>)
1103a78e148bSantirez          <code class="literal">r-</code>
1104a78e148bSantirez          [<code class="option">--enable-stats</code>]
1105a78e148bSantirez        </span></dt><dd><p>Total number of chunks actively mapped on behalf of the
1106ad4c0b41Santirez        application.  This does not include inactive chunks.
1107*fceef8e0Santirez        </p></dd><dt><a name="stats.chunks.total"></a><span class="term">
1108a78e148bSantirez
1109a78e148bSantirez    "<code class="mallctl">stats.chunks.total</code>"
1110a78e148bSantirez
1111a78e148bSantirez          (<span class="type">uint64_t</span>)
1112a78e148bSantirez          <code class="literal">r-</code>
1113a78e148bSantirez          [<code class="option">--enable-stats</code>]
1114*fceef8e0Santirez        </span></dt><dd><p>Cumulative number of chunks allocated.</p></dd><dt><a name="stats.chunks.high"></a><span class="term">
1115a78e148bSantirez
1116a78e148bSantirez    "<code class="mallctl">stats.chunks.high</code>"
1117a78e148bSantirez
1118a78e148bSantirez          (<span class="type">size_t</span>)
1119a78e148bSantirez          <code class="literal">r-</code>
1120a78e148bSantirez          [<code class="option">--enable-stats</code>]
1121a78e148bSantirez        </span></dt><dd><p>Maximum number of active chunks at any time thus far.
1122*fceef8e0Santirez        </p></dd><dt><a name="stats.huge.allocated"></a><span class="term">
1123a78e148bSantirez
1124a78e148bSantirez    "<code class="mallctl">stats.huge.allocated</code>"
1125a78e148bSantirez
1126a78e148bSantirez          (<span class="type">size_t</span>)
1127a78e148bSantirez          <code class="literal">r-</code>
1128a78e148bSantirez          [<code class="option">--enable-stats</code>]
1129a78e148bSantirez        </span></dt><dd><p>Number of bytes currently allocated by huge objects.
1130*fceef8e0Santirez        </p></dd><dt><a name="stats.huge.nmalloc"></a><span class="term">
1131a78e148bSantirez
1132a78e148bSantirez    "<code class="mallctl">stats.huge.nmalloc</code>"
1133a78e148bSantirez
1134a78e148bSantirez          (<span class="type">uint64_t</span>)
1135a78e148bSantirez          <code class="literal">r-</code>
1136a78e148bSantirez          [<code class="option">--enable-stats</code>]
1137a78e148bSantirez        </span></dt><dd><p>Cumulative number of huge allocation requests.
1138*fceef8e0Santirez        </p></dd><dt><a name="stats.huge.ndalloc"></a><span class="term">
1139a78e148bSantirez
1140a78e148bSantirez    "<code class="mallctl">stats.huge.ndalloc</code>"
1141a78e148bSantirez
1142a78e148bSantirez          (<span class="type">uint64_t</span>)
1143a78e148bSantirez          <code class="literal">r-</code>
1144a78e148bSantirez          [<code class="option">--enable-stats</code>]
1145a78e148bSantirez        </span></dt><dd><p>Cumulative number of huge deallocation requests.
1146*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.dss"></a><span class="term">
1147a78e148bSantirez
11487383c3b1Santirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.dss</code>"
11497383c3b1Santirez
11507383c3b1Santirez          (<span class="type">const char *</span>)
11517383c3b1Santirez          <code class="literal">r-</code>
11527383c3b1Santirez        </span></dt><dd><p>dss (<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>) allocation precedence as
11537383c3b1Santirez        related to <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> allocation.  See <a class="link" href="#opt.dss">
11547383c3b1Santirez    "<code class="mallctl">opt.dss</code>"
11557383c3b1Santirez  </a> for details.
1156*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.nthreads"></a><span class="term">
11577383c3b1Santirez
1158a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.nthreads</code>"
1159a78e148bSantirez
1160a78e148bSantirez          (<span class="type">unsigned</span>)
1161a78e148bSantirez          <code class="literal">r-</code>
1162a78e148bSantirez        </span></dt><dd><p>Number of threads currently assigned to
1163*fceef8e0Santirez        arena.</p></dd><dt><a name="stats.arenas.i.pactive"></a><span class="term">
1164a78e148bSantirez
1165a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.pactive</code>"
1166a78e148bSantirez
1167a78e148bSantirez          (<span class="type">size_t</span>)
1168a78e148bSantirez          <code class="literal">r-</code>
11697383c3b1Santirez        </span></dt><dd><p>Number of pages in active runs.</p></dd><dt><a name="stats.arenas.i.pdirty"></a><span class="term">
1170a78e148bSantirez
1171a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.pdirty</code>"
1172a78e148bSantirez
1173a78e148bSantirez          (<span class="type">size_t</span>)
1174a78e148bSantirez          <code class="literal">r-</code>
1175a78e148bSantirez        </span></dt><dd><p>Number of pages within unused runs that are potentially
1176a78e148bSantirez        dirty, and for which <code class="function">madvise</code>(<em class="parameter"><code>...</code></em>,
1177a78e148bSantirez        <em class="parameter"><code><code class="constant">MADV_DONTNEED</code></code></em>) or
1178*fceef8e0Santirez        similar has not been called.</p></dd><dt><a name="stats.arenas.i.mapped"></a><span class="term">
1179a78e148bSantirez
1180a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.mapped</code>"
1181a78e148bSantirez
1182a78e148bSantirez          (<span class="type">size_t</span>)
1183a78e148bSantirez          <code class="literal">r-</code>
1184a78e148bSantirez          [<code class="option">--enable-stats</code>]
1185*fceef8e0Santirez        </span></dt><dd><p>Number of mapped bytes.</p></dd><dt><a name="stats.arenas.i.npurge"></a><span class="term">
1186a78e148bSantirez
1187a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.npurge</code>"
1188a78e148bSantirez
1189a78e148bSantirez          (<span class="type">uint64_t</span>)
1190a78e148bSantirez          <code class="literal">r-</code>
1191a78e148bSantirez          [<code class="option">--enable-stats</code>]
1192a78e148bSantirez        </span></dt><dd><p>Number of dirty page purge sweeps performed.
1193*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.nmadvise"></a><span class="term">
1194a78e148bSantirez
1195a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.nmadvise</code>"
1196a78e148bSantirez
1197a78e148bSantirez          (<span class="type">uint64_t</span>)
1198a78e148bSantirez          <code class="literal">r-</code>
1199a78e148bSantirez          [<code class="option">--enable-stats</code>]
1200a78e148bSantirez        </span></dt><dd><p>Number of <code class="function">madvise</code>(<em class="parameter"><code>...</code></em>,
1201a78e148bSantirez        <em class="parameter"><code><code class="constant">MADV_DONTNEED</code></code></em>) or
1202*fceef8e0Santirez        similar calls made to purge dirty pages.</p></dd><dt><a name="stats.arenas.i.purged"></a><span class="term">
1203a78e148bSantirez
1204*fceef8e0Santirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.purged</code>"
1205a78e148bSantirez
1206a78e148bSantirez          (<span class="type">uint64_t</span>)
1207a78e148bSantirez          <code class="literal">r-</code>
1208a78e148bSantirez          [<code class="option">--enable-stats</code>]
1209*fceef8e0Santirez        </span></dt><dd><p>Number of pages purged.</p></dd><dt><a name="stats.arenas.i.small.allocated"></a><span class="term">
1210a78e148bSantirez
1211a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.small.allocated</code>"
1212a78e148bSantirez
1213a78e148bSantirez          (<span class="type">size_t</span>)
1214a78e148bSantirez          <code class="literal">r-</code>
1215a78e148bSantirez          [<code class="option">--enable-stats</code>]
1216a78e148bSantirez        </span></dt><dd><p>Number of bytes currently allocated by small objects.
1217*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.small.nmalloc"></a><span class="term">
1218a78e148bSantirez
1219a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.small.nmalloc</code>"
1220a78e148bSantirez
1221a78e148bSantirez          (<span class="type">uint64_t</span>)
1222a78e148bSantirez          <code class="literal">r-</code>
1223a78e148bSantirez          [<code class="option">--enable-stats</code>]
1224a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocation requests served by
1225*fceef8e0Santirez        small bins.</p></dd><dt><a name="stats.arenas.i.small.ndalloc"></a><span class="term">
1226a78e148bSantirez
1227a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.small.ndalloc</code>"
1228a78e148bSantirez
1229a78e148bSantirez          (<span class="type">uint64_t</span>)
1230a78e148bSantirez          <code class="literal">r-</code>
1231a78e148bSantirez          [<code class="option">--enable-stats</code>]
1232a78e148bSantirez        </span></dt><dd><p>Cumulative number of small objects returned to bins.
1233*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.small.nrequests"></a><span class="term">
1234a78e148bSantirez
1235a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.small.nrequests</code>"
1236a78e148bSantirez
1237a78e148bSantirez          (<span class="type">uint64_t</span>)
1238a78e148bSantirez          <code class="literal">r-</code>
1239a78e148bSantirez          [<code class="option">--enable-stats</code>]
1240a78e148bSantirez        </span></dt><dd><p>Cumulative number of small allocation requests.
1241*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.large.allocated"></a><span class="term">
1242a78e148bSantirez
1243a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.large.allocated</code>"
1244a78e148bSantirez
1245a78e148bSantirez          (<span class="type">size_t</span>)
1246a78e148bSantirez          <code class="literal">r-</code>
1247a78e148bSantirez          [<code class="option">--enable-stats</code>]
1248a78e148bSantirez        </span></dt><dd><p>Number of bytes currently allocated by large objects.
1249*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.large.nmalloc"></a><span class="term">
1250a78e148bSantirez
1251a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.large.nmalloc</code>"
1252a78e148bSantirez
1253a78e148bSantirez          (<span class="type">uint64_t</span>)
1254a78e148bSantirez          <code class="literal">r-</code>
1255a78e148bSantirez          [<code class="option">--enable-stats</code>]
1256a78e148bSantirez        </span></dt><dd><p>Cumulative number of large allocation requests served
1257*fceef8e0Santirez        directly by the arena.</p></dd><dt><a name="stats.arenas.i.large.ndalloc"></a><span class="term">
1258a78e148bSantirez
1259a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.large.ndalloc</code>"
1260a78e148bSantirez
1261a78e148bSantirez          (<span class="type">uint64_t</span>)
1262a78e148bSantirez          <code class="literal">r-</code>
1263a78e148bSantirez          [<code class="option">--enable-stats</code>]
1264a78e148bSantirez        </span></dt><dd><p>Cumulative number of large deallocation requests served
1265*fceef8e0Santirez        directly by the arena.</p></dd><dt><a name="stats.arenas.i.large.nrequests"></a><span class="term">
1266a78e148bSantirez
1267a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.large.nrequests</code>"
1268a78e148bSantirez
1269a78e148bSantirez          (<span class="type">uint64_t</span>)
1270a78e148bSantirez          <code class="literal">r-</code>
1271a78e148bSantirez          [<code class="option">--enable-stats</code>]
1272a78e148bSantirez        </span></dt><dd><p>Cumulative number of large allocation requests.
1273*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.bins.j.allocated"></a><span class="term">
1274a78e148bSantirez
1275a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.allocated</code>"
1276a78e148bSantirez
1277a78e148bSantirez          (<span class="type">size_t</span>)
1278a78e148bSantirez          <code class="literal">r-</code>
1279a78e148bSantirez          [<code class="option">--enable-stats</code>]
1280a78e148bSantirez        </span></dt><dd><p>Current number of bytes allocated by
1281*fceef8e0Santirez        bin.</p></dd><dt><a name="stats.arenas.i.bins.j.nmalloc"></a><span class="term">
1282a78e148bSantirez
1283a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nmalloc</code>"
1284a78e148bSantirez
1285a78e148bSantirez          (<span class="type">uint64_t</span>)
1286a78e148bSantirez          <code class="literal">r-</code>
1287a78e148bSantirez          [<code class="option">--enable-stats</code>]
1288a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocations served by bin.
1289*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.bins.j.ndalloc"></a><span class="term">
1290a78e148bSantirez
1291a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.ndalloc</code>"
1292a78e148bSantirez
1293a78e148bSantirez          (<span class="type">uint64_t</span>)
1294a78e148bSantirez          <code class="literal">r-</code>
1295a78e148bSantirez          [<code class="option">--enable-stats</code>]
1296a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocations returned to bin.
1297*fceef8e0Santirez        </p></dd><dt><a name="stats.arenas.i.bins.j.nrequests"></a><span class="term">
1298a78e148bSantirez
1299a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nrequests</code>"
1300a78e148bSantirez
1301a78e148bSantirez          (<span class="type">uint64_t</span>)
1302a78e148bSantirez          <code class="literal">r-</code>
1303a78e148bSantirez          [<code class="option">--enable-stats</code>]
1304a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocation
1305*fceef8e0Santirez        requests.</p></dd><dt><a name="stats.arenas.i.bins.j.nfills"></a><span class="term">
1306a78e148bSantirez
1307a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nfills</code>"
1308a78e148bSantirez
1309a78e148bSantirez          (<span class="type">uint64_t</span>)
1310a78e148bSantirez          <code class="literal">r-</code>
1311a78e148bSantirez          [<code class="option">--enable-stats</code> <code class="option">--enable-tcache</code>]
1312*fceef8e0Santirez        </span></dt><dd><p>Cumulative number of tcache fills.</p></dd><dt><a name="stats.arenas.i.bins.j.nflushes"></a><span class="term">
1313a78e148bSantirez
1314a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nflushes</code>"
1315a78e148bSantirez
1316a78e148bSantirez          (<span class="type">uint64_t</span>)
1317a78e148bSantirez          <code class="literal">r-</code>
1318a78e148bSantirez          [<code class="option">--enable-stats</code> <code class="option">--enable-tcache</code>]
1319*fceef8e0Santirez        </span></dt><dd><p>Cumulative number of tcache flushes.</p></dd><dt><a name="stats.arenas.i.bins.j.nruns"></a><span class="term">
1320a78e148bSantirez
1321a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nruns</code>"
1322a78e148bSantirez
1323a78e148bSantirez          (<span class="type">uint64_t</span>)
1324a78e148bSantirez          <code class="literal">r-</code>
1325a78e148bSantirez          [<code class="option">--enable-stats</code>]
1326*fceef8e0Santirez        </span></dt><dd><p>Cumulative number of runs created.</p></dd><dt><a name="stats.arenas.i.bins.j.nreruns"></a><span class="term">
1327a78e148bSantirez
1328a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.nreruns</code>"
1329a78e148bSantirez
1330a78e148bSantirez          (<span class="type">uint64_t</span>)
1331a78e148bSantirez          <code class="literal">r-</code>
1332a78e148bSantirez          [<code class="option">--enable-stats</code>]
1333a78e148bSantirez        </span></dt><dd><p>Cumulative number of times the current run from which
1334*fceef8e0Santirez        to allocate changed.</p></dd><dt><a name="stats.arenas.i.bins.j.curruns"></a><span class="term">
1335a78e148bSantirez
1336a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.bins.&lt;j&gt;.curruns</code>"
1337a78e148bSantirez
1338a78e148bSantirez          (<span class="type">size_t</span>)
1339a78e148bSantirez          <code class="literal">r-</code>
1340a78e148bSantirez          [<code class="option">--enable-stats</code>]
1341*fceef8e0Santirez        </span></dt><dd><p>Current number of runs.</p></dd><dt><a name="stats.arenas.i.lruns.j.nmalloc"></a><span class="term">
1342a78e148bSantirez
1343a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.nmalloc</code>"
1344a78e148bSantirez
1345a78e148bSantirez          (<span class="type">uint64_t</span>)
1346a78e148bSantirez          <code class="literal">r-</code>
1347a78e148bSantirez          [<code class="option">--enable-stats</code>]
1348a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocation requests for this size
1349*fceef8e0Santirez        class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.lruns.j.ndalloc"></a><span class="term">
1350a78e148bSantirez
1351a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.ndalloc</code>"
1352a78e148bSantirez
1353a78e148bSantirez          (<span class="type">uint64_t</span>)
1354a78e148bSantirez          <code class="literal">r-</code>
1355a78e148bSantirez          [<code class="option">--enable-stats</code>]
1356a78e148bSantirez        </span></dt><dd><p>Cumulative number of deallocation requests for this
1357*fceef8e0Santirez        size class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.lruns.j.nrequests"></a><span class="term">
1358a78e148bSantirez
1359a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.nrequests</code>"
1360a78e148bSantirez
1361a78e148bSantirez          (<span class="type">uint64_t</span>)
1362a78e148bSantirez          <code class="literal">r-</code>
1363a78e148bSantirez          [<code class="option">--enable-stats</code>]
1364a78e148bSantirez        </span></dt><dd><p>Cumulative number of allocation requests for this size
1365*fceef8e0Santirez        class.</p></dd><dt><a name="stats.arenas.i.lruns.j.curruns"></a><span class="term">
1366a78e148bSantirez
1367a78e148bSantirez    "<code class="mallctl">stats.arenas.&lt;i&gt;.lruns.&lt;j&gt;.curruns</code>"
1368a78e148bSantirez
1369a78e148bSantirez          (<span class="type">size_t</span>)
1370a78e148bSantirez          <code class="literal">r-</code>
1371a78e148bSantirez          [<code class="option">--enable-stats</code>]
1372a78e148bSantirez        </span></dt><dd><p>Current number of runs for this size class.
1373*fceef8e0Santirez        </p></dd></dl></div></div><div class="refsect1"><a name="debugging_malloc_problems"></a><h2>DEBUGGING MALLOC PROBLEMS</h2><p>When debugging, it is a good idea to configure/build jemalloc with
1374a78e148bSantirez    the <code class="option">--enable-debug</code> and <code class="option">--enable-fill</code>
1375a78e148bSantirez    options, and recompile the program with suitable options and symbols for
1376a78e148bSantirez    debugger support.  When so configured, jemalloc incorporates a wide variety
1377a78e148bSantirez    of run-time assertions that catch application errors such as double-free,
1378a78e148bSantirez    write-after-free, etc.</p><p>Programs often accidentally depend on &#8220;uninitialized&#8221;
1379a78e148bSantirez    memory actually being filled with zero bytes.  Junk filling
1380a78e148bSantirez    (see the <a class="link" href="#opt.junk">
1381a78e148bSantirez    "<code class="mallctl">opt.junk</code>"
1382a78e148bSantirez  </a>
1383a78e148bSantirez    option) tends to expose such bugs in the form of obviously incorrect
1384a78e148bSantirez    results and/or coredumps.  Conversely, zero
1385a78e148bSantirez    filling (see the <a class="link" href="#opt.zero">
1386a78e148bSantirez    "<code class="mallctl">opt.zero</code>"
1387a78e148bSantirez  </a> option) eliminates
1388a78e148bSantirez    the symptoms of such bugs.  Between these two options, it is usually
1389a78e148bSantirez    possible to quickly detect, diagnose, and eliminate such bugs.</p><p>This implementation does not provide much detail about the problems
1390a78e148bSantirez    it detects, because the performance impact for storing such information
1391ad4c0b41Santirez    would be prohibitive.  However, jemalloc does integrate with the most
1392ad4c0b41Santirez    excellent <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a> tool if the
1393*fceef8e0Santirez    <code class="option">--enable-valgrind</code> configuration option is enabled.</p></div><div class="refsect1"><a name="diagnostic_messages"></a><h2>DIAGNOSTIC MESSAGES</h2><p>If any of the memory allocation/deallocation functions detect an
1394a78e148bSantirez    error or warning condition, a message will be printed to file descriptor
1395a78e148bSantirez    <code class="constant">STDERR_FILENO</code>.  Errors will result in the process
1396a78e148bSantirez    dumping core.  If the <a class="link" href="#opt.abort">
1397a78e148bSantirez    "<code class="mallctl">opt.abort</code>"
1398a78e148bSantirez  </a> option is set, most
1399a78e148bSantirez    warnings are treated as errors.</p><p>The <code class="varname">malloc_message</code> variable allows the programmer
1400a78e148bSantirez    to override the function which emits the text strings forming the errors
1401a78e148bSantirez    and warnings if for some reason the <code class="constant">STDERR_FILENO</code> file
1402a78e148bSantirez    descriptor is not suitable for this.
1403a78e148bSantirez    <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) takes the
1404a78e148bSantirez    <em class="parameter"><code>cbopaque</code></em> pointer argument that is
1405a78e148bSantirez    <code class="constant">NULL</code> unless overridden by the arguments in a call to
1406a78e148bSantirez    <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>), followed by a string
1407a78e148bSantirez    pointer.  Please note that doing anything which tries to allocate memory in
1408a78e148bSantirez    this function is likely to result in a crash or deadlock.</p><p>All messages are prefixed by
1409*fceef8e0Santirez    &#8220;<code class="computeroutput">&lt;jemalloc&gt;: </code>&#8221;.</p></div><div class="refsect1"><a name="return_values"></a><h2>RETURN VALUES</h2><div class="refsect2"><a name="idm316388028784"></a><h3>Standard API</h3><p>The <code class="function">malloc</code>(<em class="parameter"><code></code></em>) and
1410a78e148bSantirez      <code class="function">calloc</code>(<em class="parameter"><code></code></em>) functions return a pointer to the
1411a78e148bSantirez      allocated memory if successful; otherwise a <code class="constant">NULL</code>
1412a78e148bSantirez      pointer is returned and <code class="varname">errno</code> is set to
1413a78e148bSantirez      <span class="errorname">ENOMEM</span>.</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function
1414a78e148bSantirez      returns the value 0 if successful; otherwise it returns an error value.
1415a78e148bSantirez      The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function will fail
1416a78e148bSantirez      if:
1417*fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorname">EINVAL</span></span></dt><dd><p>The <em class="parameter"><code>alignment</code></em> parameter is
1418a78e148bSantirez            not a power of 2 at least as large as
1419a78e148bSantirez            <code class="code">sizeof(<span class="type">void *</span>)</code>.
1420a78e148bSantirez            </p></dd><dt><span class="term"><span class="errorname">ENOMEM</span></span></dt><dd><p>Memory allocation error.</p></dd></dl></div><p>
1421ad4c0b41Santirez      </p><p>The <code class="function">aligned_alloc</code>(<em class="parameter"><code></code></em>) function returns
1422ad4c0b41Santirez      a pointer to the allocated memory if successful; otherwise a
1423ad4c0b41Santirez      <code class="constant">NULL</code> pointer is returned and
1424ad4c0b41Santirez      <code class="varname">errno</code> is set.  The
1425ad4c0b41Santirez      <code class="function">aligned_alloc</code>(<em class="parameter"><code></code></em>) function will fail if:
1426*fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorname">EINVAL</span></span></dt><dd><p>The <em class="parameter"><code>alignment</code></em> parameter is
1427ad4c0b41Santirez            not a power of 2.
1428ad4c0b41Santirez            </p></dd><dt><span class="term"><span class="errorname">ENOMEM</span></span></dt><dd><p>Memory allocation error.</p></dd></dl></div><p>
1429a78e148bSantirez      </p><p>The <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function returns a
1430a78e148bSantirez      pointer, possibly identical to <em class="parameter"><code>ptr</code></em>, to the
1431a78e148bSantirez      allocated memory if successful; otherwise a <code class="constant">NULL</code>
1432a78e148bSantirez      pointer is returned, and <code class="varname">errno</code> is set to
1433a78e148bSantirez      <span class="errorname">ENOMEM</span> if the error was the result of an
1434a78e148bSantirez      allocation failure.  The <code class="function">realloc</code>(<em class="parameter"><code></code></em>)
1435a78e148bSantirez      function always leaves the original buffer intact when an error occurs.
1436a78e148bSantirez      </p><p>The <code class="function">free</code>(<em class="parameter"><code></code></em>) function returns no
1437*fceef8e0Santirez      value.</p></div><div class="refsect2"><a name="idm316388003104"></a><h3>Non-standard API</h3><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) and
1438*fceef8e0Santirez      <code class="function">rallocx</code>(<em class="parameter"><code></code></em>) functions return a pointer to
1439*fceef8e0Santirez      the allocated memory if successful; otherwise a <code class="constant">NULL</code>
1440*fceef8e0Santirez      pointer is returned to indicate insufficient contiguous memory was
1441*fceef8e0Santirez      available to service the allocation request.  </p><p>The <code class="function">xallocx</code>(<em class="parameter"><code></code></em>) function returns the
1442*fceef8e0Santirez      real size of the resulting resized allocation pointed to by
1443*fceef8e0Santirez      <em class="parameter"><code>ptr</code></em>, which is a value less than
1444*fceef8e0Santirez      <em class="parameter"><code>size</code></em> if the allocation could not be adequately
1445*fceef8e0Santirez      grown in place.  </p><p>The <code class="function">sallocx</code>(<em class="parameter"><code></code></em>) function returns the
1446*fceef8e0Santirez      real size of the allocation pointed to by <em class="parameter"><code>ptr</code></em>.
1447*fceef8e0Santirez      </p><p>The <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) returns the real size
1448*fceef8e0Santirez      that would result from a successful equivalent
1449*fceef8e0Santirez      <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function call, or zero if
1450*fceef8e0Santirez      insufficient memory is available to perform the size computation.  </p><p>The <code class="function">mallctl</code>(<em class="parameter"><code></code></em>),
1451a78e148bSantirez      <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>), and
1452a78e148bSantirez      <code class="function">mallctlbymib</code>(<em class="parameter"><code></code></em>) functions return 0 on
1453a78e148bSantirez      success; otherwise they return an error value.  The functions will fail
1454a78e148bSantirez      if:
1455*fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorname">EINVAL</span></span></dt><dd><p><em class="parameter"><code>newp</code></em> is not
1456a78e148bSantirez            <code class="constant">NULL</code>, and <em class="parameter"><code>newlen</code></em> is too
1457a78e148bSantirez            large or too small.  Alternatively, <em class="parameter"><code>*oldlenp</code></em>
1458a78e148bSantirez            is too large or too small; in this case as much data as possible
1459*fceef8e0Santirez            are read despite the error.</p></dd><dt><span class="term"><span class="errorname">ENOENT</span></span></dt><dd><p><em class="parameter"><code>name</code></em> or
1460a78e148bSantirez            <em class="parameter"><code>mib</code></em> specifies an unknown/invalid
1461a78e148bSantirez            value.</p></dd><dt><span class="term"><span class="errorname">EPERM</span></span></dt><dd><p>Attempt to read or write void value, or attempt to
1462a78e148bSantirez            write read-only value.</p></dd><dt><span class="term"><span class="errorname">EAGAIN</span></span></dt><dd><p>A memory allocation failure
1463a78e148bSantirez            occurred.</p></dd><dt><span class="term"><span class="errorname">EFAULT</span></span></dt><dd><p>An interface with side effects failed in some way
1464a78e148bSantirez            not directly related to <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>)
1465a78e148bSantirez            read/write processing.</p></dd></dl></div><p>
1466*fceef8e0Santirez      </p><p>The <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function
1467*fceef8e0Santirez      returns the usable size of the allocation pointed to by
1468*fceef8e0Santirez      <em class="parameter"><code>ptr</code></em>.  </p></div><div class="refsect2"><a name="idm316387973360"></a><h3>Experimental API</h3><p>The <code class="function">allocm</code>(<em class="parameter"><code></code></em>),
1469a78e148bSantirez      <code class="function">rallocm</code>(<em class="parameter"><code></code></em>),
1470ad4c0b41Santirez      <code class="function">sallocm</code>(<em class="parameter"><code></code></em>),
1471ad4c0b41Santirez      <code class="function">dallocm</code>(<em class="parameter"><code></code></em>), and
1472ad4c0b41Santirez      <code class="function">nallocm</code>(<em class="parameter"><code></code></em>) functions return
1473a78e148bSantirez      <code class="constant">ALLOCM_SUCCESS</code> on success; otherwise they return an
1474ad4c0b41Santirez      error value.  The <code class="function">allocm</code>(<em class="parameter"><code></code></em>),
1475ad4c0b41Santirez      <code class="function">rallocm</code>(<em class="parameter"><code></code></em>), and
1476ad4c0b41Santirez      <code class="function">nallocm</code>(<em class="parameter"><code></code></em>) functions will fail if:
1477*fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorname">ALLOCM_ERR_OOM</span></span></dt><dd><p>Out of memory.  Insufficient contiguous memory was
1478a78e148bSantirez            available to service the allocation request.  The
1479a78e148bSantirez            <code class="function">allocm</code>(<em class="parameter"><code></code></em>) function additionally sets
1480a78e148bSantirez            <em class="parameter"><code>*ptr</code></em> to <code class="constant">NULL</code>, whereas
1481a78e148bSantirez            the <code class="function">rallocm</code>(<em class="parameter"><code></code></em>) function leaves
1482a78e148bSantirez            <code class="constant">*ptr</code> unmodified.</p></dd></dl></div><p>
1483a78e148bSantirez      The <code class="function">rallocm</code>(<em class="parameter"><code></code></em>) function will also
1484a78e148bSantirez      fail if:
1485*fceef8e0Santirez        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="errorname">ALLOCM_ERR_NOT_MOVED</span></span></dt><dd><p><code class="constant">ALLOCM_NO_MOVE</code> was specified,
1486a78e148bSantirez            but the reallocation request could not be serviced without moving
1487a78e148bSantirez            the object.</p></dd></dl></div><p>
1488*fceef8e0Santirez      </p></div></div><div class="refsect1"><a name="environment"></a><h2>ENVIRONMENT</h2><p>The following environment variable affects the execution of the
1489a78e148bSantirez    allocation functions:
1490*fceef8e0Santirez      </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">MALLOC_CONF</code></span></dt><dd><p>If the environment variable
1491a78e148bSantirez          <code class="envar">MALLOC_CONF</code> is set, the characters it contains
1492a78e148bSantirez          will be interpreted as options.</p></dd></dl></div><p>
1493*fceef8e0Santirez    </p></div><div class="refsect1"><a name="examples"></a><h2>EXAMPLES</h2><p>To dump core whenever a problem occurs:
1494a78e148bSantirez      </p><pre class="screen">ln -s 'abort:true' /etc/malloc.conf</pre><p>
1495a78e148bSantirez    </p><p>To specify in the source a chunk size that is 16 MiB:
1496a78e148bSantirez      </p><pre class="programlisting">
1497*fceef8e0Santirezmalloc_conf = "lg_chunk:24";</pre></div><div class="refsect1"><a name="see_also"></a><h2>SEE ALSO</h2><p><span class="citerefentry"><span class="refentrytitle">madvise</span>(2)</span>,
1498a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span>,
1499a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>,
1500ad4c0b41Santirez    <span class="citerefentry"><span class="refentrytitle">utrace</span>(2)</span>,
1501a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">alloca</span>(3)</span>,
1502a78e148bSantirez    <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span>,
1503*fceef8e0Santirez    <span class="citerefentry"><span class="refentrytitle">getpagesize</span>(3)</span></p></div><div class="refsect1"><a name="standards"></a><h2>STANDARDS</h2><p>The <code class="function">malloc</code>(<em class="parameter"><code></code></em>),
1504a78e148bSantirez    <code class="function">calloc</code>(<em class="parameter"><code></code></em>),
1505a78e148bSantirez    <code class="function">realloc</code>(<em class="parameter"><code></code></em>), and
1506a78e148bSantirez    <code class="function">free</code>(<em class="parameter"><code></code></em>) functions conform to ISO/IEC
1507a78e148bSantirez    9899:1990 (&#8220;ISO C90&#8221;).</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function conforms
1508a78e148bSantirez    to IEEE Std 1003.1-2001 (&#8220;POSIX.1&#8221;).</p></div></div></body></html>
1509