1*5268379eSantirez<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="idp45223136"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>jemalloc — general purpose memory allocation functions</p></div><div class="refsect1"><a name="library"></a><h2>LIBRARY</h2><p>This manual describes jemalloc 4.0.3-0-ge9192eacf8935e29fc62fddc2701f7942b1cc02c. More information 2*5268379eSantirez 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 <<code class="filename">jemalloc/jemalloc.h</code>></pre><div class="refsect2"><a name="idp44244480"></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="idp46062768"></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">void <b class="fsfunc">sdallocx</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">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> 3a78e148bSantirez <code>(</code>void *, const char *<code>)</code> 4*5268379eSantirez , </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></div><div class="refsect1"><a name="description"></a><h2>DESCRIPTION</h2><div class="refsect2"><a name="idp46115952"></a><h3>Standard API</h3><p>The <code class="function">malloc</code>(<em class="parameter"><code></code></em>) function allocates 5a78e148bSantirez <em class="parameter"><code>size</code></em> bytes of uninitialized memory. The allocated 6a78e148bSantirez space is suitably aligned (after possible pointer coercion) for storage 7a78e148bSantirez of any type of object.</p><p>The <code class="function">calloc</code>(<em class="parameter"><code></code></em>) function allocates 8a78e148bSantirez space for <em class="parameter"><code>number</code></em> objects, each 9a78e148bSantirez <em class="parameter"><code>size</code></em> bytes in length. The result is identical to 10a78e148bSantirez calling <code class="function">malloc</code>(<em class="parameter"><code></code></em>) with an argument of 11a78e148bSantirez <em class="parameter"><code>number</code></em> * <em class="parameter"><code>size</code></em>, with the 12a78e148bSantirez exception that the allocated memory is explicitly initialized to zero 13a78e148bSantirez bytes.</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function 14a78e148bSantirez allocates <em class="parameter"><code>size</code></em> bytes of memory such that the 15*5268379eSantirez allocation's base address is a multiple of 16a78e148bSantirez <em class="parameter"><code>alignment</code></em>, and returns the allocation in the value 17a78e148bSantirez pointed to by <em class="parameter"><code>ptr</code></em>. The requested 18*5268379eSantirez <em class="parameter"><code>alignment</code></em> must be a power of 2 at least as large as 19*5268379eSantirez <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 20ad4c0b41Santirez allocates <em class="parameter"><code>size</code></em> bytes of memory such that the 21*5268379eSantirez allocation's base address is a multiple of 22ad4c0b41Santirez <em class="parameter"><code>alignment</code></em>. The requested 23ad4c0b41Santirez <em class="parameter"><code>alignment</code></em> must be a power of 2. Behavior is 24ad4c0b41Santirez undefined if <em class="parameter"><code>size</code></em> is not an integral multiple of 25ad4c0b41Santirez <em class="parameter"><code>alignment</code></em>.</p><p>The <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function changes the 26a78e148bSantirez size of the previously allocated memory referenced by 27a78e148bSantirez <em class="parameter"><code>ptr</code></em> to <em class="parameter"><code>size</code></em> bytes. The 28a78e148bSantirez contents of the memory are unchanged up to the lesser of the new and old 29a78e148bSantirez sizes. If the new size is larger, the contents of the newly allocated 30a78e148bSantirez portion of the memory are undefined. Upon success, the memory referenced 31a78e148bSantirez by <em class="parameter"><code>ptr</code></em> is freed and a pointer to the newly 32a78e148bSantirez allocated memory is returned. Note that 33a78e148bSantirez <code class="function">realloc</code>(<em class="parameter"><code></code></em>) may move the memory allocation, 34a78e148bSantirez resulting in a different return value than <em class="parameter"><code>ptr</code></em>. 35a78e148bSantirez If <em class="parameter"><code>ptr</code></em> is <code class="constant">NULL</code>, the 36a78e148bSantirez <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function behaves identically to 37a78e148bSantirez <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 38a78e148bSantirez allocated memory referenced by <em class="parameter"><code>ptr</code></em> to be made 39a78e148bSantirez available for future allocations. If <em class="parameter"><code>ptr</code></em> is 40*5268379eSantirez <code class="constant">NULL</code>, no action occurs.</p></div><div class="refsect2"><a name="idp46144704"></a><h3>Non-standard API</h3><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>), 41fceef8e0Santirez <code class="function">rallocx</code>(<em class="parameter"><code></code></em>), 42fceef8e0Santirez <code class="function">xallocx</code>(<em class="parameter"><code></code></em>), 43fceef8e0Santirez <code class="function">sallocx</code>(<em class="parameter"><code></code></em>), 44*5268379eSantirez <code class="function">dallocx</code>(<em class="parameter"><code></code></em>), 45*5268379eSantirez <code class="function">sdallocx</code>(<em class="parameter"><code></code></em>), and 46fceef8e0Santirez <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) functions all have a 47fceef8e0Santirez <em class="parameter"><code>flags</code></em> argument that can be used to specify 48fceef8e0Santirez options. The functions only check the options that are contextually 49fceef8e0Santirez relevant. Use bitwise or (<code class="code">|</code>) operations to 50fceef8e0Santirez specify one or more of the following: 51*5268379eSantirez </p><div class="variablelist"><dl class="variablelist"><dt><a name="MALLOCX_LG_ALIGN"></a><span class="term"><code class="constant">MALLOCX_LG_ALIGN(<em class="parameter"><code>la</code></em>) 52fceef8e0Santirez </code></span></dt><dd><p>Align the memory allocation to start at an address 53fceef8e0Santirez that is a multiple of <code class="code">(1 << 54fceef8e0Santirez <em class="parameter"><code>la</code></em>)</code>. This macro does not validate 55fceef8e0Santirez that <em class="parameter"><code>la</code></em> is within the valid 56*5268379eSantirez range.</p></dd><dt><a name="MALLOCX_ALIGN"></a><span class="term"><code class="constant">MALLOCX_ALIGN(<em class="parameter"><code>a</code></em>) 57fceef8e0Santirez </code></span></dt><dd><p>Align the memory allocation to start at an address 58fceef8e0Santirez that is a multiple of <em class="parameter"><code>a</code></em>, where 59fceef8e0Santirez <em class="parameter"><code>a</code></em> is a power of two. This macro does not 60fceef8e0Santirez validate that <em class="parameter"><code>a</code></em> is a power of 2. 61*5268379eSantirez </p></dd><dt><a name="MALLOCX_ZERO"></a><span class="term"><code class="constant">MALLOCX_ZERO</code></span></dt><dd><p>Initialize newly allocated memory to contain zero 62fceef8e0Santirez bytes. In the growing reallocation case, the real size prior to 63fceef8e0Santirez reallocation defines the boundary between untouched bytes and those 64fceef8e0Santirez that are initialized to contain zero bytes. If this macro is 65*5268379eSantirez absent, newly allocated memory is uninitialized.</p></dd><dt><a name="MALLOCX_TCACHE"></a><span class="term"><code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>) 66*5268379eSantirez </code></span></dt><dd><p>Use the thread-specific cache (tcache) specified by 67*5268379eSantirez the identifier <em class="parameter"><code>tc</code></em>, which must have been 68*5268379eSantirez acquired via the <a class="link" href="#tcache.create"> 69*5268379eSantirez "<code class="mallctl">tcache.create</code>" 70*5268379eSantirez </a> 71*5268379eSantirez mallctl. This macro does not validate that 72*5268379eSantirez <em class="parameter"><code>tc</code></em> specifies a valid 73*5268379eSantirez identifier.</p></dd><dt><a name="MALLOC_TCACHE_NONE"></a><span class="term"><code class="constant">MALLOCX_TCACHE_NONE</code></span></dt><dd><p>Do not use a thread-specific cache (tcache). Unless 74*5268379eSantirez <code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)</code> or 75*5268379eSantirez <code class="constant">MALLOCX_TCACHE_NONE</code> is specified, an 76*5268379eSantirez automatically managed tcache will be used under many circumstances. 77*5268379eSantirez This macro cannot be used in the same <em class="parameter"><code>flags</code></em> 78*5268379eSantirez argument as 79*5268379eSantirez <code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)</code>.</p></dd><dt><a name="MALLOCX_ARENA"></a><span class="term"><code class="constant">MALLOCX_ARENA(<em class="parameter"><code>a</code></em>) 80fceef8e0Santirez </code></span></dt><dd><p>Use the arena specified by the index 81*5268379eSantirez <em class="parameter"><code>a</code></em>. This macro has no effect for regions that 82*5268379eSantirez were allocated via an arena other than the one specified. This 83*5268379eSantirez macro does not validate that <em class="parameter"><code>a</code></em> specifies an 84*5268379eSantirez arena index in the valid range.</p></dd></dl></div><p> 85fceef8e0Santirez </p><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function allocates at 86fceef8e0Santirez least <em class="parameter"><code>size</code></em> bytes of memory, and returns a pointer 87fceef8e0Santirez to the base address of the allocation. Behavior is undefined if 88fceef8e0Santirez <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if request size 89fceef8e0Santirez 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 90fceef8e0Santirez allocation at <em class="parameter"><code>ptr</code></em> to be at least 91fceef8e0Santirez <em class="parameter"><code>size</code></em> bytes, and returns a pointer to the base 92fceef8e0Santirez address of the resulting allocation, which may or may not have moved from 93fceef8e0Santirez its original location. Behavior is undefined if 94fceef8e0Santirez <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if request size 95fceef8e0Santirez 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 96fceef8e0Santirez allocation at <em class="parameter"><code>ptr</code></em> in place to be at least 97fceef8e0Santirez <em class="parameter"><code>size</code></em> bytes, and returns the real size of the 98fceef8e0Santirez allocation. If <em class="parameter"><code>extra</code></em> is non-zero, an attempt is 99fceef8e0Santirez made to resize the allocation to be at least <code class="code">(<em class="parameter"><code>size</code></em> + 100fceef8e0Santirez <em class="parameter"><code>extra</code></em>)</code> bytes, though inability to allocate 101fceef8e0Santirez the extra byte(s) will not by itself result in failure to resize. 102fceef8e0Santirez Behavior is undefined if <em class="parameter"><code>size</code></em> is 103fceef8e0Santirez <code class="constant">0</code>, or if <code class="code">(<em class="parameter"><code>size</code></em> + <em class="parameter"><code>extra</code></em> 104fceef8e0Santirez > <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 105fceef8e0Santirez 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 106fceef8e0Santirez memory referenced by <em class="parameter"><code>ptr</code></em> to be made available for 107*5268379eSantirez future allocations.</p><p>The <code class="function">sdallocx</code>(<em class="parameter"><code></code></em>) function is an 108*5268379eSantirez extension of <code class="function">dallocx</code>(<em class="parameter"><code></code></em>) with a 109*5268379eSantirez <em class="parameter"><code>size</code></em> parameter to allow the caller to pass in the 110*5268379eSantirez allocation size as an optimization. The minimum valid input size is the 111*5268379eSantirez original requested size of the allocation, and the maximum valid input 112*5268379eSantirez size is the corresponding value returned by 113*5268379eSantirez <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) or 114*5268379eSantirez <code class="function">sallocx</code>(<em class="parameter"><code></code></em>).</p><p>The <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) function allocates no 115fceef8e0Santirez memory, but it performs the same size computation as the 116fceef8e0Santirez <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function, and returns the real 117fceef8e0Santirez size of the allocation that would result from the equivalent 118fceef8e0Santirez <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function call. Behavior is 119fceef8e0Santirez undefined if <em class="parameter"><code>size</code></em> is <code class="constant">0</code>, or if 120fceef8e0Santirez request size overflows due to size class and/or alignment 121fceef8e0Santirez constraints.</p><p>The <code class="function">mallctl</code>(<em class="parameter"><code></code></em>) function provides a 122a78e148bSantirez general interface for introspecting the memory allocator, as well as 123a78e148bSantirez setting modifiable parameters and triggering actions. The 124a78e148bSantirez period-separated <em class="parameter"><code>name</code></em> argument specifies a 125a78e148bSantirez location in a tree-structured namespace; see the <a class="xref" href="#mallctl_namespace" title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for 126a78e148bSantirez documentation on the tree contents. To read a value, pass a pointer via 127a78e148bSantirez <em class="parameter"><code>oldp</code></em> to adequate space to contain the value, and a 128a78e148bSantirez pointer to its length via <em class="parameter"><code>oldlenp</code></em>; otherwise pass 129a78e148bSantirez <code class="constant">NULL</code> and <code class="constant">NULL</code>. Similarly, to 130a78e148bSantirez write a value, pass a pointer to the value via 131a78e148bSantirez <em class="parameter"><code>newp</code></em>, and its length via 132a78e148bSantirez <em class="parameter"><code>newlen</code></em>; otherwise pass <code class="constant">NULL</code> 133a78e148bSantirez and <code class="constant">0</code>.</p><p>The <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>) function 134a78e148bSantirez provides a way to avoid repeated name lookups for applications that 135a78e148bSantirez repeatedly query the same portion of the namespace, by translating a name 136a78e148bSantirez to a “Management Information Base” (MIB) that can be passed 137a78e148bSantirez repeatedly to <code class="function">mallctlbymib</code>(<em class="parameter"><code></code></em>). Upon 138a78e148bSantirez successful return from <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>), 139a78e148bSantirez <em class="parameter"><code>mibp</code></em> contains an array of 140a78e148bSantirez <em class="parameter"><code>*miblenp</code></em> integers, where 141a78e148bSantirez <em class="parameter"><code>*miblenp</code></em> is the lesser of the number of components 142a78e148bSantirez in <em class="parameter"><code>name</code></em> and the input value of 143a78e148bSantirez <em class="parameter"><code>*miblenp</code></em>. Thus it is possible to pass a 144a78e148bSantirez <em class="parameter"><code>*miblenp</code></em> that is smaller than the number of 145a78e148bSantirez period-separated name components, which results in a partial MIB that can 146a78e148bSantirez be used as the basis for constructing a complete MIB. For name 147a78e148bSantirez components that are integers (e.g. the 2 in 148a78e148bSantirez <a class="link" href="#arenas.bin.i.size"> 149a78e148bSantirez "<code class="mallctl">arenas.bin.2.size</code>" 150a78e148bSantirez </a>), 151a78e148bSantirez the corresponding MIB component will always be that integer. Therefore, 152a78e148bSantirez it is legitimate to construct code like the following: </p><pre class="programlisting"> 153a78e148bSantirezunsigned nbins, i; 154fceef8e0Santirezsize_t mib[4]; 155a78e148bSantirezsize_t len, miblen; 156a78e148bSantirez 157a78e148bSantirezlen = sizeof(nbins); 158a78e148bSantirezmallctl("arenas.nbins", &nbins, &len, NULL, 0); 159a78e148bSantirez 160a78e148bSantirezmiblen = 4; 161fceef8e0Santirezmallctlnametomib("arenas.bin.0.size", mib, &miblen); 162a78e148bSantirezfor (i = 0; i < nbins; i++) { 163a78e148bSantirez size_t bin_size; 164a78e148bSantirez 165a78e148bSantirez mib[2] = i; 166a78e148bSantirez len = sizeof(bin_size); 167a78e148bSantirez mallctlbymib(mib, miblen, &bin_size, &len, NULL, 0); 168a78e148bSantirez /* Do something with bin_size... */ 169fceef8e0Santirez}</pre><p>The <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>) function 170fceef8e0Santirez writes human-readable summary statistics via the 171fceef8e0Santirez <em class="parameter"><code>write_cb</code></em> callback function pointer and 172fceef8e0Santirez <em class="parameter"><code>cbopaque</code></em> data passed to 173fceef8e0Santirez <em class="parameter"><code>write_cb</code></em>, or 174fceef8e0Santirez <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) if 175fceef8e0Santirez <em class="parameter"><code>write_cb</code></em> is <code class="constant">NULL</code>. This 176fceef8e0Santirez function can be called repeatedly. General information that never 177fceef8e0Santirez changes during execution can be omitted by specifying "g" as a character 178fceef8e0Santirez within the <em class="parameter"><code>opts</code></em> string. Note that 179fceef8e0Santirez <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) uses the 180fceef8e0Santirez <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions internally, so 181fceef8e0Santirez inconsistent statistics can be reported if multiple threads use these 182fceef8e0Santirez functions simultaneously. If <code class="option">--enable-stats</code> is 183fceef8e0Santirez specified during configuration, “m” and “a” can 184fceef8e0Santirez be specified to omit merged arena and per arena statistics, respectively; 185*5268379eSantirez “b”, “l”, and “h” can be specified to 186*5268379eSantirez omit per size class statistics for bins, large objects, and huge objects, 187*5268379eSantirez respectively. Unrecognized characters are silently ignored. Note that 188*5268379eSantirez thread caching may prevent some statistics from being completely up to 189*5268379eSantirez date, since extra locking would be required to merge counters that track 190*5268379eSantirez thread cache operations. 191fceef8e0Santirez </p><p>The <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function 192fceef8e0Santirez returns the usable size of the allocation pointed to by 193fceef8e0Santirez <em class="parameter"><code>ptr</code></em>. The return value may be larger than the size 194fceef8e0Santirez that was requested during allocation. The 195fceef8e0Santirez <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function is not a 196fceef8e0Santirez mechanism for in-place <code class="function">realloc</code>(<em class="parameter"><code></code></em>); rather 197fceef8e0Santirez it is provided solely as a tool for introspection purposes. Any 198fceef8e0Santirez discrepancy between the requested allocation size and the size reported 199fceef8e0Santirez by <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) should not be 200fceef8e0Santirez depended on, since such behavior is entirely implementation-dependent. 201*5268379eSantirez </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 202a78e148bSantirez routines, the allocator initializes its internals based in part on various 203a78e148bSantirez options that can be specified at compile- or run-time.</p><p>The string pointed to by the global variable 204a78e148bSantirez <code class="varname">malloc_conf</code>, the “name” of the file 205a78e148bSantirez referenced by the symbolic link named <code class="filename">/etc/malloc.conf</code>, and the value of the 206a78e148bSantirez environment variable <code class="envar">MALLOC_CONF</code>, will be interpreted, in 207fceef8e0Santirez that order, from left to right as options. Note that 208fceef8e0Santirez <code class="varname">malloc_conf</code> may be read before 209fceef8e0Santirez <code class="function">main</code>(<em class="parameter"><code></code></em>) is entered, so the declaration of 210fceef8e0Santirez <code class="varname">malloc_conf</code> should specify an initializer that contains 211fceef8e0Santirez the final value to be read by jemalloc. <code class="varname">malloc_conf</code> is 212fceef8e0Santirez a compile-time setting, whereas <code class="filename">/etc/malloc.conf</code> and <code class="envar">MALLOC_CONF</code> 213fceef8e0Santirez can be safely set any time prior to program invocation.</p><p>An options string is a comma-separated list of option:value pairs. 214a78e148bSantirez There is one key corresponding to each <a class="link" href="#opt.abort"> 215a78e148bSantirez "<code class="mallctl">opt.*</code>" 216a78e148bSantirez </a> mallctl (see the <a class="xref" href="#mallctl_namespace" title="MALLCTL NAMESPACE">MALLCTL NAMESPACE</a> section for options 217a78e148bSantirez documentation). For example, <code class="literal">abort:true,narenas:1</code> sets 218a78e148bSantirez the <a class="link" href="#opt.abort"> 219a78e148bSantirez "<code class="mallctl">opt.abort</code>" 220a78e148bSantirez </a> and <a class="link" href="#opt.narenas"> 221a78e148bSantirez "<code class="mallctl">opt.narenas</code>" 222a78e148bSantirez </a> options. Some 223a78e148bSantirez options have boolean values (true/false), others have integer values (base 224a78e148bSantirez 8, 10, or 16, depending on prefix), and yet others have raw string 225fceef8e0Santirez values.</p></div><div class="refsect1"><a name="implementation_notes"></a><h2>IMPLEMENTATION NOTES</h2><p>Traditionally, allocators have used 226a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> to obtain memory, which is 227a78e148bSantirez suboptimal for several reasons, including race conditions, increased 228a78e148bSantirez fragmentation, and artificial limitations on maximum usable memory. If 229*5268379eSantirez <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating 230*5268379eSantirez system, this allocator uses both 231*5268379eSantirez <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> and 232ad4c0b41Santirez <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>, in that order of preference; 233a78e148bSantirez 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 234a78e148bSantirez contention for threaded programs on multi-processor systems. This works 235a78e148bSantirez well with regard to threading scalability, but incurs some costs. There is 236a78e148bSantirez a small fixed per-arena overhead, and additionally, arenas manage memory 237a78e148bSantirez completely independently of each other, which means a small fixed increase 238a78e148bSantirez in overall memory fragmentation. These overheads are not generally an 239a78e148bSantirez issue, given the number of arenas normally used. Note that using 240a78e148bSantirez substantially more arenas than the default is not likely to improve 241a78e148bSantirez performance, mainly due to reduced cache performance. However, it may make 242a78e148bSantirez sense to reduce the number of arenas if an application does not make much 243a78e148bSantirez use of the allocation functions.</p><p>In addition to multiple arenas, unless 244a78e148bSantirez <code class="option">--disable-tcache</code> is specified during configuration, this 245a78e148bSantirez allocator supports thread-specific caching for small and large objects, in 246a78e148bSantirez order to make it possible to completely avoid synchronization for most 247a78e148bSantirez allocation requests. Such caching allows very fast allocation in the 248a78e148bSantirez common case, but it increases memory usage and fragmentation, since a 249a78e148bSantirez bounded number of objects can remain allocated in each thread cache.</p><p>Memory is conceptually broken into equal-sized chunks, where the 250a78e148bSantirez chunk size is a power of two that is greater than the page size. Chunks 251a78e148bSantirez are always aligned to multiples of the chunk size. This alignment makes it 252a78e148bSantirez possible to find metadata for user objects very quickly.</p><p>User objects are broken into three categories according to size: 253*5268379eSantirez small, large, and huge. Small and large objects are managed entirely by 254*5268379eSantirez arenas; huge objects are additionally aggregated in a single data structure 255*5268379eSantirez that is shared by all threads. Huge objects are typically used by 256*5268379eSantirez applications infrequently enough that this single data structure is not a 257*5268379eSantirez scalability issue.</p><p>Each chunk that is managed by an arena tracks its contents as runs of 258a78e148bSantirez contiguous pages (unused, backing a set of small objects, or backing one 259a78e148bSantirez large object). The combination of chunk alignment and chunk page maps 260a78e148bSantirez makes it possible to determine all metadata regarding small and large 261a78e148bSantirez allocations in constant time.</p><p>Small objects are managed in groups by page runs. Each run maintains 262*5268379eSantirez a bitmap to track which regions are in use. Allocation requests that are no 263*5268379eSantirez more than half the quantum (8 or 16, depending on architecture) are rounded 264*5268379eSantirez up to the nearest power of two that is at least <code class="code">sizeof(<span class="type">double</span>)</code>. All other object size 265*5268379eSantirez classes are multiples of the quantum, spaced such that there are four size 266*5268379eSantirez classes for each doubling in size, which limits internal fragmentation to 267*5268379eSantirez approximately 20% for all but the smallest size classes. Small size classes 268*5268379eSantirez are smaller than four times the page size, large size classes are smaller 269*5268379eSantirez than the chunk size (see the <a class="link" href="#opt.lg_chunk"> 270a78e148bSantirez "<code class="mallctl">opt.lg_chunk</code>" 271*5268379eSantirez </a> option), and 272*5268379eSantirez huge size classes extend from the chunk size up to one size class less than 273*5268379eSantirez the full address space size.</p><p>Allocations are packed tightly together, which can be an issue for 274a78e148bSantirez multi-threaded applications. If you need to assure that allocations do not 275a78e148bSantirez suffer from cacheline sharing, round your allocation requests up to the 276a78e148bSantirez nearest multiple of the cacheline size, or specify cacheline alignment when 277*5268379eSantirez allocating.</p><p>The <code class="function">realloc</code>(<em class="parameter"><code></code></em>), 278*5268379eSantirez <code class="function">rallocx</code>(<em class="parameter"><code></code></em>), and 279*5268379eSantirez <code class="function">xallocx</code>(<em class="parameter"><code></code></em>) functions may resize allocations 280*5268379eSantirez without moving them under limited circumstances. Unlike the 281*5268379eSantirez <code class="function">*allocx</code>(<em class="parameter"><code></code></em>) API, the standard API does not 282*5268379eSantirez officially round up the usable size of an allocation to the nearest size 283*5268379eSantirez class, so technically it is necessary to call 284*5268379eSantirez <code class="function">realloc</code>(<em class="parameter"><code></code></em>) to grow e.g. a 9-byte allocation to 285*5268379eSantirez 16 bytes, or shrink a 16-byte allocation to 9 bytes. Growth and shrinkage 286*5268379eSantirez trivially succeeds in place as long as the pre-size and post-size both round 287*5268379eSantirez up to the same size class. No other API guarantees are made regarding 288*5268379eSantirez in-place resizing, but the current implementation also tries to resize large 289*5268379eSantirez and huge allocations in place, as long as the pre-size and post-size are 290*5268379eSantirez both large or both huge. In such cases shrinkage always succeeds for large 291*5268379eSantirez size classes, but for huge size classes the chunk allocator must support 292*5268379eSantirez splitting (see <a class="link" href="#arena.i.chunk_hooks"> 293*5268379eSantirez "<code class="mallctl">arena.<i>.chunk_hooks</code>" 294*5268379eSantirez </a>). 295*5268379eSantirez Growth only succeeds if the trailing memory is currently available, and 296*5268379eSantirez additionally for huge size classes the chunk allocator must support 297*5268379eSantirez merging.</p><p>Assuming 2 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 298*5268379eSantirez 64-bit 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="9" 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, 64, 80, 96, 112, 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, 4096]</td></tr><tr><td align="right">1 KiB</td><td align="left">[5 KiB, 6 KiB, 7 KiB, 8 KiB]</td></tr><tr><td align="right">2 KiB</td><td align="left">[10 KiB, 12 KiB, 14 KiB]</td></tr><tr><td rowspan="8" align="left">Large</td><td align="right">2 KiB</td><td align="left">[16 KiB]</td></tr><tr><td align="right">4 KiB</td><td align="left">[20 KiB, 24 KiB, 28 KiB, 32 KiB]</td></tr><tr><td align="right">8 KiB</td><td align="left">[40 KiB, 48 KiB, 54 KiB, 64 KiB]</td></tr><tr><td align="right">16 KiB</td><td align="left">[80 KiB, 96 KiB, 112 KiB, 128 KiB]</td></tr><tr><td align="right">32 KiB</td><td align="left">[160 KiB, 192 KiB, 224 KiB, 256 KiB]</td></tr><tr><td align="right">64 KiB</td><td align="left">[320 KiB, 384 KiB, 448 KiB, 512 KiB]</td></tr><tr><td align="right">128 KiB</td><td align="left">[640 KiB, 768 KiB, 896 KiB, 1 MiB]</td></tr><tr><td align="right">256 KiB</td><td align="left">[1280 KiB, 1536 KiB, 1792 KiB]</td></tr><tr><td rowspan="7" align="left">Huge</td><td align="right">256 KiB</td><td align="left">[2 MiB]</td></tr><tr><td align="right">512 KiB</td><td align="left">[2560 KiB, 3 MiB, 3584 KiB, 4 MiB]</td></tr><tr><td align="right">1 MiB</td><td align="left">[5 MiB, 6 MiB, 7 MiB, 8 MiB]</td></tr><tr><td align="right">2 MiB</td><td align="left">[10 MiB, 12 MiB, 14 MiB, 16 MiB]</td></tr><tr><td align="right">4 MiB</td><td align="left">[20 MiB, 24 MiB, 28 MiB, 32 MiB]</td></tr><tr><td align="right">8 MiB</td><td align="left">[40 MiB, 48 MiB, 56 MiB, 64 MiB]</td></tr><tr><td align="right">...</td><td align="left">...</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 299a78e148bSantirez <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions. Value types are 300a78e148bSantirez specified in parentheses, their readable/writable statuses are encoded as 301a78e148bSantirez <code class="literal">rw</code>, <code class="literal">r-</code>, <code class="literal">-w</code>, or 302a78e148bSantirez <code class="literal">--</code>, and required build configuration flags follow, if 303a78e148bSantirez any. A name element encoded as <code class="literal"><i></code> or 304a78e148bSantirez <code class="literal"><j></code> indicates an integer component, where the 305a78e148bSantirez integer varies from 0 to some upper value that must be determined via 306a78e148bSantirez introspection. In the case of 307a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.*</code>" 308a78e148bSantirez , 309a78e148bSantirez <code class="literal"><i></code> equal to <a class="link" href="#arenas.narenas"> 310a78e148bSantirez "<code class="mallctl">arenas.narenas</code>" 311a78e148bSantirez </a> can be 312a78e148bSantirez used to access the summation of statistics from all arenas. Take special 313a78e148bSantirez note of the <a class="link" href="#epoch"> 314a78e148bSantirez "<code class="mallctl">epoch</code>" 315a78e148bSantirez </a> mallctl, 316fceef8e0Santirez which controls refreshing of cached dynamic statistics.</p><div class="variablelist"><dl class="variablelist"><dt><a name="version"></a><span class="term"> 317a78e148bSantirez 318a78e148bSantirez "<code class="mallctl">version</code>" 319a78e148bSantirez 320a78e148bSantirez (<span class="type">const char *</span>) 321a78e148bSantirez <code class="literal">r-</code> 322a78e148bSantirez </span></dt><dd><p>Return the jemalloc version string.</p></dd><dt><a name="epoch"></a><span class="term"> 323a78e148bSantirez 324a78e148bSantirez "<code class="mallctl">epoch</code>" 325a78e148bSantirez 326a78e148bSantirez (<span class="type">uint64_t</span>) 327a78e148bSantirez <code class="literal">rw</code> 328a78e148bSantirez </span></dt><dd><p>If a value is passed in, refresh the data from which 329a78e148bSantirez the <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) functions report values, 330a78e148bSantirez and increment the epoch. Return the current epoch. This is useful for 331*5268379eSantirez detecting whether another thread caused a refresh.</p></dd><dt><a name="config.cache_oblivious"></a><span class="term"> 332*5268379eSantirez 333*5268379eSantirez "<code class="mallctl">config.cache_oblivious</code>" 334*5268379eSantirez 335*5268379eSantirez (<span class="type">bool</span>) 336*5268379eSantirez <code class="literal">r-</code> 337*5268379eSantirez </span></dt><dd><p><code class="option">--enable-cache-oblivious</code> was specified 338*5268379eSantirez during build configuration.</p></dd><dt><a name="config.debug"></a><span class="term"> 339a78e148bSantirez 340a78e148bSantirez "<code class="mallctl">config.debug</code>" 341a78e148bSantirez 342a78e148bSantirez (<span class="type">bool</span>) 343a78e148bSantirez <code class="literal">r-</code> 344a78e148bSantirez </span></dt><dd><p><code class="option">--enable-debug</code> was specified during 345fceef8e0Santirez build configuration.</p></dd><dt><a name="config.fill"></a><span class="term"> 346a78e148bSantirez 347a78e148bSantirez "<code class="mallctl">config.fill</code>" 348a78e148bSantirez 349a78e148bSantirez (<span class="type">bool</span>) 350a78e148bSantirez <code class="literal">r-</code> 351a78e148bSantirez </span></dt><dd><p><code class="option">--enable-fill</code> was specified during 352fceef8e0Santirez build configuration.</p></dd><dt><a name="config.lazy_lock"></a><span class="term"> 353a78e148bSantirez 354a78e148bSantirez "<code class="mallctl">config.lazy_lock</code>" 355a78e148bSantirez 356a78e148bSantirez (<span class="type">bool</span>) 357a78e148bSantirez <code class="literal">r-</code> 358a78e148bSantirez </span></dt><dd><p><code class="option">--enable-lazy-lock</code> was specified 359*5268379eSantirez during build configuration.</p></dd><dt><a name="config.munmap"></a><span class="term"> 360ad4c0b41Santirez 361ad4c0b41Santirez "<code class="mallctl">config.munmap</code>" 362ad4c0b41Santirez 363ad4c0b41Santirez (<span class="type">bool</span>) 364ad4c0b41Santirez <code class="literal">r-</code> 365ad4c0b41Santirez </span></dt><dd><p><code class="option">--enable-munmap</code> was specified during 366fceef8e0Santirez build configuration.</p></dd><dt><a name="config.prof"></a><span class="term"> 367ad4c0b41Santirez 368a78e148bSantirez "<code class="mallctl">config.prof</code>" 369a78e148bSantirez 370a78e148bSantirez (<span class="type">bool</span>) 371a78e148bSantirez <code class="literal">r-</code> 372a78e148bSantirez </span></dt><dd><p><code class="option">--enable-prof</code> was specified during 373fceef8e0Santirez build configuration.</p></dd><dt><a name="config.prof_libgcc"></a><span class="term"> 374a78e148bSantirez 375a78e148bSantirez "<code class="mallctl">config.prof_libgcc</code>" 376a78e148bSantirez 377a78e148bSantirez (<span class="type">bool</span>) 378a78e148bSantirez <code class="literal">r-</code> 379a78e148bSantirez </span></dt><dd><p><code class="option">--disable-prof-libgcc</code> was not 380fceef8e0Santirez specified during build configuration.</p></dd><dt><a name="config.prof_libunwind"></a><span class="term"> 381a78e148bSantirez 382a78e148bSantirez "<code class="mallctl">config.prof_libunwind</code>" 383a78e148bSantirez 384a78e148bSantirez (<span class="type">bool</span>) 385a78e148bSantirez <code class="literal">r-</code> 386a78e148bSantirez </span></dt><dd><p><code class="option">--enable-prof-libunwind</code> was specified 387fceef8e0Santirez during build configuration.</p></dd><dt><a name="config.stats"></a><span class="term"> 388a78e148bSantirez 389a78e148bSantirez "<code class="mallctl">config.stats</code>" 390a78e148bSantirez 391a78e148bSantirez (<span class="type">bool</span>) 392a78e148bSantirez <code class="literal">r-</code> 393a78e148bSantirez </span></dt><dd><p><code class="option">--enable-stats</code> was specified during 394fceef8e0Santirez build configuration.</p></dd><dt><a name="config.tcache"></a><span class="term"> 395a78e148bSantirez 396a78e148bSantirez "<code class="mallctl">config.tcache</code>" 397a78e148bSantirez 398a78e148bSantirez (<span class="type">bool</span>) 399a78e148bSantirez <code class="literal">r-</code> 400a78e148bSantirez </span></dt><dd><p><code class="option">--disable-tcache</code> was not specified 401fceef8e0Santirez during build configuration.</p></dd><dt><a name="config.tls"></a><span class="term"> 402a78e148bSantirez 403a78e148bSantirez "<code class="mallctl">config.tls</code>" 404a78e148bSantirez 405a78e148bSantirez (<span class="type">bool</span>) 406a78e148bSantirez <code class="literal">r-</code> 407a78e148bSantirez </span></dt><dd><p><code class="option">--disable-tls</code> was not specified during 408fceef8e0Santirez build configuration.</p></dd><dt><a name="config.utrace"></a><span class="term"> 409a78e148bSantirez 410ad4c0b41Santirez "<code class="mallctl">config.utrace</code>" 411ad4c0b41Santirez 412ad4c0b41Santirez (<span class="type">bool</span>) 413ad4c0b41Santirez <code class="literal">r-</code> 414ad4c0b41Santirez </span></dt><dd><p><code class="option">--enable-utrace</code> was specified during 415fceef8e0Santirez build configuration.</p></dd><dt><a name="config.valgrind"></a><span class="term"> 416ad4c0b41Santirez 417ad4c0b41Santirez "<code class="mallctl">config.valgrind</code>" 418ad4c0b41Santirez 419ad4c0b41Santirez (<span class="type">bool</span>) 420ad4c0b41Santirez <code class="literal">r-</code> 421ad4c0b41Santirez </span></dt><dd><p><code class="option">--enable-valgrind</code> was specified during 422fceef8e0Santirez build configuration.</p></dd><dt><a name="config.xmalloc"></a><span class="term"> 423ad4c0b41Santirez 424a78e148bSantirez "<code class="mallctl">config.xmalloc</code>" 425a78e148bSantirez 426a78e148bSantirez (<span class="type">bool</span>) 427a78e148bSantirez <code class="literal">r-</code> 428a78e148bSantirez </span></dt><dd><p><code class="option">--enable-xmalloc</code> was specified during 429a78e148bSantirez build configuration.</p></dd><dt><a name="opt.abort"></a><span class="term"> 430a78e148bSantirez 431a78e148bSantirez "<code class="mallctl">opt.abort</code>" 432a78e148bSantirez 433a78e148bSantirez (<span class="type">bool</span>) 434a78e148bSantirez <code class="literal">r-</code> 435a78e148bSantirez </span></dt><dd><p>Abort-on-warning enabled/disabled. If true, most 436a78e148bSantirez warnings are fatal. The process will call 437a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span> in these cases. This option is 438a78e148bSantirez disabled by default unless <code class="option">--enable-debug</code> is 439a78e148bSantirez specified during configuration, in which case it is enabled by default. 440fceef8e0Santirez </p></dd><dt><a name="opt.dss"></a><span class="term"> 4417383c3b1Santirez 4427383c3b1Santirez "<code class="mallctl">opt.dss</code>" 4437383c3b1Santirez 4447383c3b1Santirez (<span class="type">const char *</span>) 4457383c3b1Santirez <code class="literal">r-</code> 4467383c3b1Santirez </span></dt><dd><p>dss (<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>) allocation precedence as 4477383c3b1Santirez related to <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> allocation. The following 448*5268379eSantirez settings are supported if 449*5268379eSantirez <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating 450*5268379eSantirez system: “disabled”, “primary”, and 451*5268379eSantirez “secondary”; otherwise only “disabled” is 452*5268379eSantirez supported. The default is “secondary” if 453*5268379eSantirez <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span> is supported by the operating 454*5268379eSantirez system; “disabled” otherwise. 455fceef8e0Santirez </p></dd><dt><a name="opt.lg_chunk"></a><span class="term"> 456fceef8e0Santirez 457fceef8e0Santirez "<code class="mallctl">opt.lg_chunk</code>" 458fceef8e0Santirez 459fceef8e0Santirez (<span class="type">size_t</span>) 460fceef8e0Santirez <code class="literal">r-</code> 461fceef8e0Santirez </span></dt><dd><p>Virtual memory chunk size (log base 2). If a chunk 462fceef8e0Santirez size outside the supported size range is specified, the size is 463fceef8e0Santirez silently clipped to the minimum/maximum supported size. The default 464*5268379eSantirez chunk size is 2 MiB (2^21). 465fceef8e0Santirez </p></dd><dt><a name="opt.narenas"></a><span class="term"> 466a78e148bSantirez 467a78e148bSantirez "<code class="mallctl">opt.narenas</code>" 468a78e148bSantirez 469a78e148bSantirez (<span class="type">size_t</span>) 470a78e148bSantirez <code class="literal">r-</code> 4717383c3b1Santirez </span></dt><dd><p>Maximum number of arenas to use for automatic 4727383c3b1Santirez multiplexing of threads and arenas. The default is four times the 4737383c3b1Santirez number of CPUs, or one if there is a single CPU.</p></dd><dt><a name="opt.lg_dirty_mult"></a><span class="term"> 474a78e148bSantirez 475a78e148bSantirez "<code class="mallctl">opt.lg_dirty_mult</code>" 476a78e148bSantirez 477a78e148bSantirez (<span class="type">ssize_t</span>) 478a78e148bSantirez <code class="literal">r-</code> 479a78e148bSantirez </span></dt><dd><p>Per-arena minimum ratio (log base 2) of active to dirty 480a78e148bSantirez pages. Some dirty unused pages may be allowed to accumulate, within 481a78e148bSantirez the limit set by the ratio (or one chunk worth of dirty pages, 482a78e148bSantirez whichever is greater), before informing the kernel about some of those 483a78e148bSantirez pages via <span class="citerefentry"><span class="refentrytitle">madvise</span>(2)</span> or a similar system call. This 484a78e148bSantirez provides the kernel with sufficient information to recycle dirty pages 485a78e148bSantirez if physical memory becomes scarce and the pages remain unused. The 4867383c3b1Santirez default minimum ratio is 8:1 (2^3:1); an option value of -1 will 487*5268379eSantirez disable dirty page purging. See <a class="link" href="#arenas.lg_dirty_mult"> 488*5268379eSantirez "<code class="mallctl">arenas.lg_dirty_mult</code>" 489*5268379eSantirez </a> 490*5268379eSantirez and <a class="link" href="#arena.i.lg_dirty_mult"> 491*5268379eSantirez "<code class="mallctl">arena.<i>.lg_dirty_mult</code>" 492*5268379eSantirez </a> 493*5268379eSantirez for related dynamic control options.</p></dd><dt><a name="opt.stats_print"></a><span class="term"> 494a78e148bSantirez 495a78e148bSantirez "<code class="mallctl">opt.stats_print</code>" 496a78e148bSantirez 497a78e148bSantirez (<span class="type">bool</span>) 498a78e148bSantirez <code class="literal">r-</code> 499a78e148bSantirez </span></dt><dd><p>Enable/disable statistics printing at exit. If 500a78e148bSantirez enabled, the <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>) 501a78e148bSantirez function is called at program exit via an 502a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function. If 503a78e148bSantirez <code class="option">--enable-stats</code> is specified during configuration, this 504a78e148bSantirez has the potential to cause deadlock for a multi-threaded process that 505a78e148bSantirez exits while one or more threads are executing in the memory allocation 506*5268379eSantirez functions. Furthermore, <code class="function">atexit</code>(<em class="parameter"><code></code></em>) may 507*5268379eSantirez allocate memory during application initialization and then deadlock 508*5268379eSantirez internally when jemalloc in turn calls 509*5268379eSantirez <code class="function">atexit</code>(<em class="parameter"><code></code></em>), so this option is not 510*5268379eSantirez univerally usable (though the application can register its own 511*5268379eSantirez <code class="function">atexit</code>(<em class="parameter"><code></code></em>) function with equivalent 512*5268379eSantirez functionality). Therefore, this option should only be used with care; 513*5268379eSantirez it is primarily intended as a performance tuning aid during application 514a78e148bSantirez development. This option is disabled by default.</p></dd><dt><a name="opt.junk"></a><span class="term"> 515a78e148bSantirez 516a78e148bSantirez "<code class="mallctl">opt.junk</code>" 517a78e148bSantirez 518*5268379eSantirez (<span class="type">const char *</span>) 519a78e148bSantirez <code class="literal">r-</code> 520a78e148bSantirez [<code class="option">--enable-fill</code>] 521*5268379eSantirez </span></dt><dd><p>Junk filling. If set to "alloc", each byte of 522*5268379eSantirez uninitialized allocated memory will be initialized to 523*5268379eSantirez <code class="literal">0xa5</code>. If set to "free", all deallocated memory will 524*5268379eSantirez be initialized to <code class="literal">0x5a</code>. If set to "true", both 525*5268379eSantirez allocated and deallocated memory will be initialized, and if set to 526*5268379eSantirez "false", junk filling be disabled entirely. This is intended for 527*5268379eSantirez debugging and will impact performance negatively. This option is 528*5268379eSantirez "false" by default unless <code class="option">--enable-debug</code> is specified 529*5268379eSantirez during configuration, in which case it is "true" by default unless 530*5268379eSantirez running inside <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>.</p></dd><dt><a name="opt.quarantine"></a><span class="term"> 531ad4c0b41Santirez 532ad4c0b41Santirez "<code class="mallctl">opt.quarantine</code>" 533ad4c0b41Santirez 534ad4c0b41Santirez (<span class="type">size_t</span>) 535ad4c0b41Santirez <code class="literal">r-</code> 536ad4c0b41Santirez [<code class="option">--enable-fill</code>] 537ad4c0b41Santirez </span></dt><dd><p>Per thread quarantine size in bytes. If non-zero, each 538ad4c0b41Santirez thread maintains a FIFO object quarantine that stores up to the 539ad4c0b41Santirez specified number of bytes of memory. The quarantined memory is not 540ad4c0b41Santirez freed until it is released from quarantine, though it is immediately 541ad4c0b41Santirez junk-filled if the <a class="link" href="#opt.junk"> 542ad4c0b41Santirez "<code class="mallctl">opt.junk</code>" 543ad4c0b41Santirez </a> option is 544ad4c0b41Santirez 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 545ad4c0b41Santirez to access quarantined objects. This is intended for debugging and will 5467383c3b1Santirez impact performance negatively. The default quarantine size is 0 unless 5477383c3b1Santirez running inside Valgrind, in which case the default is 16 5487383c3b1Santirez MiB.</p></dd><dt><a name="opt.redzone"></a><span class="term"> 549ad4c0b41Santirez 550ad4c0b41Santirez "<code class="mallctl">opt.redzone</code>" 551ad4c0b41Santirez 552ad4c0b41Santirez (<span class="type">bool</span>) 553ad4c0b41Santirez <code class="literal">r-</code> 554ad4c0b41Santirez [<code class="option">--enable-fill</code>] 555ad4c0b41Santirez </span></dt><dd><p>Redzones enabled/disabled. If enabled, small 556ad4c0b41Santirez allocations have redzones before and after them. Furthermore, if the 557ad4c0b41Santirez <a class="link" href="#opt.junk"> 558ad4c0b41Santirez "<code class="mallctl">opt.junk</code>" 559ad4c0b41Santirez </a> option is 560ad4c0b41Santirez enabled, the redzones are checked for corruption during deallocation. 561ad4c0b41Santirez However, the primary intended purpose of this feature is to be used in 562ad4c0b41Santirez combination with <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>, 563ad4c0b41Santirez which needs redzones in order to do effective buffer overflow/underflow 564ad4c0b41Santirez detection. This option is intended for debugging and will impact 565ad4c0b41Santirez performance negatively. This option is disabled by 5667383c3b1Santirez default unless running inside Valgrind.</p></dd><dt><a name="opt.zero"></a><span class="term"> 567a78e148bSantirez 568a78e148bSantirez "<code class="mallctl">opt.zero</code>" 569a78e148bSantirez 570a78e148bSantirez (<span class="type">bool</span>) 571a78e148bSantirez <code class="literal">r-</code> 572a78e148bSantirez [<code class="option">--enable-fill</code>] 573a78e148bSantirez </span></dt><dd><p>Zero filling enabled/disabled. If enabled, each byte 574a78e148bSantirez of uninitialized allocated memory will be initialized to 0. Note that 575a78e148bSantirez this initialization only happens once for each byte, so 576*5268379eSantirez <code class="function">realloc</code>(<em class="parameter"><code></code></em>) and 577*5268379eSantirez <code class="function">rallocx</code>(<em class="parameter"><code></code></em>) calls do not zero memory that 578a78e148bSantirez was previously allocated. This is intended for debugging and will 579a78e148bSantirez impact performance negatively. This option is disabled by default. 580ad4c0b41Santirez </p></dd><dt><a name="opt.utrace"></a><span class="term"> 581a78e148bSantirez 582ad4c0b41Santirez "<code class="mallctl">opt.utrace</code>" 583a78e148bSantirez 584a78e148bSantirez (<span class="type">bool</span>) 585a78e148bSantirez <code class="literal">r-</code> 586ad4c0b41Santirez [<code class="option">--enable-utrace</code>] 587ad4c0b41Santirez </span></dt><dd><p>Allocation tracing based on 588ad4c0b41Santirez <span class="citerefentry"><span class="refentrytitle">utrace</span>(2)</span> enabled/disabled. This option 589*5268379eSantirez is disabled by default.</p></dd><dt><a name="opt.xmalloc"></a><span class="term"> 590a78e148bSantirez 591a78e148bSantirez "<code class="mallctl">opt.xmalloc</code>" 592a78e148bSantirez 593a78e148bSantirez (<span class="type">bool</span>) 594a78e148bSantirez <code class="literal">r-</code> 595a78e148bSantirez [<code class="option">--enable-xmalloc</code>] 596a78e148bSantirez </span></dt><dd><p>Abort-on-out-of-memory enabled/disabled. If enabled, 597a78e148bSantirez rather than returning failure for any allocation function, display a 598a78e148bSantirez diagnostic message on <code class="constant">STDERR_FILENO</code> and cause the 599a78e148bSantirez program to drop core (using 600a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">abort</span>(3)</span>). If an application is 601a78e148bSantirez designed to depend on this behavior, set the option at compile time by 602a78e148bSantirez including the following in the source code: 603a78e148bSantirez </p><pre class="programlisting"> 604a78e148bSantirezmalloc_conf = "xmalloc:true";</pre><p> 605a78e148bSantirez This option is disabled by default.</p></dd><dt><a name="opt.tcache"></a><span class="term"> 606a78e148bSantirez 607a78e148bSantirez "<code class="mallctl">opt.tcache</code>" 608a78e148bSantirez 609a78e148bSantirez (<span class="type">bool</span>) 610a78e148bSantirez <code class="literal">r-</code> 611a78e148bSantirez [<code class="option">--enable-tcache</code>] 612*5268379eSantirez </span></dt><dd><p>Thread-specific caching (tcache) enabled/disabled. When 613*5268379eSantirez there are multiple threads, each thread uses a tcache for objects up to 614*5268379eSantirez a certain size. Thread-specific caching allows many allocations to be 615*5268379eSantirez satisfied without performing any thread synchronization, at the cost of 616*5268379eSantirez increased memory use. See the <a class="link" href="#opt.lg_tcache_max"> 617a78e148bSantirez "<code class="mallctl">opt.lg_tcache_max</code>" 618a78e148bSantirez </a> 619ad4c0b41Santirez option for related tuning information. This option is enabled by 620*5268379eSantirez default unless running inside <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a>, in which case it is 621*5268379eSantirez forcefully disabled.</p></dd><dt><a name="opt.lg_tcache_max"></a><span class="term"> 622a78e148bSantirez 623a78e148bSantirez "<code class="mallctl">opt.lg_tcache_max</code>" 624a78e148bSantirez 625a78e148bSantirez (<span class="type">size_t</span>) 626a78e148bSantirez <code class="literal">r-</code> 627a78e148bSantirez [<code class="option">--enable-tcache</code>] 628a78e148bSantirez </span></dt><dd><p>Maximum size class (log base 2) to cache in the 629*5268379eSantirez thread-specific cache (tcache). At a minimum, all small size classes 630*5268379eSantirez are cached, and at a maximum all large size classes are cached. The 631a78e148bSantirez default maximum is 32 KiB (2^15).</p></dd><dt><a name="opt.prof"></a><span class="term"> 632a78e148bSantirez 633a78e148bSantirez "<code class="mallctl">opt.prof</code>" 634a78e148bSantirez 635a78e148bSantirez (<span class="type">bool</span>) 636a78e148bSantirez <code class="literal">r-</code> 637a78e148bSantirez [<code class="option">--enable-prof</code>] 638a78e148bSantirez </span></dt><dd><p>Memory profiling enabled/disabled. If enabled, profile 639ad4c0b41Santirez memory allocation activity. See the <a class="link" href="#opt.prof_active"> 640a78e148bSantirez "<code class="mallctl">opt.prof_active</code>" 641a78e148bSantirez </a> 642a78e148bSantirez option for on-the-fly activation/deactivation. See the <a class="link" href="#opt.lg_prof_sample"> 643a78e148bSantirez "<code class="mallctl">opt.lg_prof_sample</code>" 644a78e148bSantirez </a> 645a78e148bSantirez option for probabilistic sampling control. See the <a class="link" href="#opt.prof_accum"> 646a78e148bSantirez "<code class="mallctl">opt.prof_accum</code>" 647a78e148bSantirez </a> 648ad4c0b41Santirez option for control of cumulative sample reporting. See the <a class="link" href="#opt.lg_prof_interval"> 649a78e148bSantirez "<code class="mallctl">opt.lg_prof_interval</code>" 650a78e148bSantirez </a> 651ad4c0b41Santirez option for information on interval-triggered profile dumping, the <a class="link" href="#opt.prof_gdump"> 652a78e148bSantirez "<code class="mallctl">opt.prof_gdump</code>" 653a78e148bSantirez </a> 654ad4c0b41Santirez option for information on high-water-triggered profile dumping, and the 655ad4c0b41Santirez <a class="link" href="#opt.prof_final"> 656ad4c0b41Santirez "<code class="mallctl">opt.prof_final</code>" 657ad4c0b41Santirez </a> 658ad4c0b41Santirez option for final profile dumping. Profile output is compatible with 659*5268379eSantirez the <span class="command"><strong>jeprof</strong></span> command, which is based on the 660*5268379eSantirez <span class="command"><strong>pprof</strong></span> that is developed as part of the <a class="ulink" href="http://code.google.com/p/gperftools/" target="_top">gperftools 661a78e148bSantirez package</a>.</p></dd><dt><a name="opt.prof_prefix"></a><span class="term"> 662a78e148bSantirez 663a78e148bSantirez "<code class="mallctl">opt.prof_prefix</code>" 664a78e148bSantirez 665a78e148bSantirez (<span class="type">const char *</span>) 666a78e148bSantirez <code class="literal">r-</code> 667a78e148bSantirez [<code class="option">--enable-prof</code>] 668a78e148bSantirez </span></dt><dd><p>Filename prefix for profile dumps. If the prefix is 669a78e148bSantirez set to the empty string, no automatic dumps will occur; this is 670a78e148bSantirez primarily useful for disabling the automatic final heap dump (which 671a78e148bSantirez also disables leak reporting, if enabled). The default prefix is 672ad4c0b41Santirez <code class="filename">jeprof</code>.</p></dd><dt><a name="opt.prof_active"></a><span class="term"> 673a78e148bSantirez 674a78e148bSantirez "<code class="mallctl">opt.prof_active</code>" 675a78e148bSantirez 676a78e148bSantirez (<span class="type">bool</span>) 677*5268379eSantirez <code class="literal">r-</code> 678a78e148bSantirez [<code class="option">--enable-prof</code>] 679a78e148bSantirez </span></dt><dd><p>Profiling activated/deactivated. This is a secondary 680a78e148bSantirez control mechanism that makes it possible to start the application with 681a78e148bSantirez profiling enabled (see the <a class="link" href="#opt.prof"> 682a78e148bSantirez "<code class="mallctl">opt.prof</code>" 683a78e148bSantirez </a> option) but 684a78e148bSantirez inactive, then toggle profiling at any time during program execution 685a78e148bSantirez with the <a class="link" href="#prof.active"> 686a78e148bSantirez "<code class="mallctl">prof.active</code>" 687a78e148bSantirez </a> mallctl. 688*5268379eSantirez This option is enabled by default.</p></dd><dt><a name="opt.prof_thread_active_init"></a><span class="term"> 689*5268379eSantirez 690*5268379eSantirez "<code class="mallctl">opt.prof_thread_active_init</code>" 691*5268379eSantirez 692*5268379eSantirez (<span class="type">bool</span>) 693*5268379eSantirez <code class="literal">r-</code> 694*5268379eSantirez [<code class="option">--enable-prof</code>] 695*5268379eSantirez </span></dt><dd><p>Initial setting for <a class="link" href="#thread.prof.active"> 696*5268379eSantirez "<code class="mallctl">thread.prof.active</code>" 697*5268379eSantirez </a> 698*5268379eSantirez in newly created threads. The initial setting for newly created threads 699*5268379eSantirez can also be changed during execution via the <a class="link" href="#prof.thread_active_init"> 700*5268379eSantirez "<code class="mallctl">prof.thread_active_init</code>" 701*5268379eSantirez </a> 702*5268379eSantirez mallctl. This option is enabled by default.</p></dd><dt><a name="opt.lg_prof_sample"></a><span class="term"> 703a78e148bSantirez 704a78e148bSantirez "<code class="mallctl">opt.lg_prof_sample</code>" 705a78e148bSantirez 706*5268379eSantirez (<span class="type">size_t</span>) 707a78e148bSantirez <code class="literal">r-</code> 708a78e148bSantirez [<code class="option">--enable-prof</code>] 709a78e148bSantirez </span></dt><dd><p>Average interval (log base 2) between allocation 710a78e148bSantirez samples, as measured in bytes of allocation activity. Increasing the 711a78e148bSantirez sampling interval decreases profile fidelity, but also decreases the 712ad4c0b41Santirez computational overhead. The default sample interval is 512 KiB (2^19 713ad4c0b41Santirez B).</p></dd><dt><a name="opt.prof_accum"></a><span class="term"> 714a78e148bSantirez 715a78e148bSantirez "<code class="mallctl">opt.prof_accum</code>" 716a78e148bSantirez 717a78e148bSantirez (<span class="type">bool</span>) 718a78e148bSantirez <code class="literal">r-</code> 719a78e148bSantirez [<code class="option">--enable-prof</code>] 720a78e148bSantirez </span></dt><dd><p>Reporting of cumulative object/byte counts in profile 721a78e148bSantirez dumps enabled/disabled. If this option is enabled, every unique 722a78e148bSantirez backtrace must be stored for the duration of execution. Depending on 723a78e148bSantirez the application, this can impose a large memory overhead, and the 724ad4c0b41Santirez cumulative counts are not always of interest. This option is disabled 725ad4c0b41Santirez by default.</p></dd><dt><a name="opt.lg_prof_interval"></a><span class="term"> 726a78e148bSantirez 727a78e148bSantirez "<code class="mallctl">opt.lg_prof_interval</code>" 728a78e148bSantirez 729a78e148bSantirez (<span class="type">ssize_t</span>) 730a78e148bSantirez <code class="literal">r-</code> 731a78e148bSantirez [<code class="option">--enable-prof</code>] 732a78e148bSantirez </span></dt><dd><p>Average interval (log base 2) between memory profile 733a78e148bSantirez dumps, as measured in bytes of allocation activity. The actual 734a78e148bSantirez interval between dumps may be sporadic because decentralized allocation 735a78e148bSantirez counters are used to avoid synchronization bottlenecks. Profiles are 736a78e148bSantirez dumped to files named according to the pattern 737a78e148bSantirez <code class="filename"><prefix>.<pid>.<seq>.i<iseq>.heap</code>, 738a78e148bSantirez where <code class="literal"><prefix></code> is controlled by the 739a78e148bSantirez <a class="link" href="#opt.prof_prefix"> 740a78e148bSantirez "<code class="mallctl">opt.prof_prefix</code>" 741a78e148bSantirez </a> 742a78e148bSantirez option. By default, interval-triggered profile dumping is disabled 743a78e148bSantirez (encoded as -1). 744a78e148bSantirez </p></dd><dt><a name="opt.prof_gdump"></a><span class="term"> 745a78e148bSantirez 746a78e148bSantirez "<code class="mallctl">opt.prof_gdump</code>" 747a78e148bSantirez 748a78e148bSantirez (<span class="type">bool</span>) 749a78e148bSantirez <code class="literal">r-</code> 750a78e148bSantirez [<code class="option">--enable-prof</code>] 751*5268379eSantirez </span></dt><dd><p>Set the initial state of <a class="link" href="#prof.gdump"> 752*5268379eSantirez "<code class="mallctl">prof.gdump</code>" 753*5268379eSantirez </a>, which when 754*5268379eSantirez enabled triggers a memory profile dump every time the total virtual 755*5268379eSantirez memory exceeds the previous maximum. This option is disabled by 756*5268379eSantirez default.</p></dd><dt><a name="opt.prof_final"></a><span class="term"> 757ad4c0b41Santirez 758ad4c0b41Santirez "<code class="mallctl">opt.prof_final</code>" 759ad4c0b41Santirez 760ad4c0b41Santirez (<span class="type">bool</span>) 761ad4c0b41Santirez <code class="literal">r-</code> 762ad4c0b41Santirez [<code class="option">--enable-prof</code>] 763ad4c0b41Santirez </span></dt><dd><p>Use an 764ad4c0b41Santirez <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function to dump final memory 765ad4c0b41Santirez usage to a file named according to the pattern 766ad4c0b41Santirez <code class="filename"><prefix>.<pid>.<seq>.f.heap</code>, 767ad4c0b41Santirez where <code class="literal"><prefix></code> is controlled by the <a class="link" href="#opt.prof_prefix"> 768ad4c0b41Santirez "<code class="mallctl">opt.prof_prefix</code>" 769ad4c0b41Santirez </a> 770*5268379eSantirez option. Note that <code class="function">atexit</code>(<em class="parameter"><code></code></em>) may allocate 771*5268379eSantirez memory during application initialization and then deadlock internally 772*5268379eSantirez when jemalloc in turn calls <code class="function">atexit</code>(<em class="parameter"><code></code></em>), so 773*5268379eSantirez this option is not univerally usable (though the application can 774*5268379eSantirez register its own <code class="function">atexit</code>(<em class="parameter"><code></code></em>) function with 775*5268379eSantirez equivalent functionality). This option is disabled by 776*5268379eSantirez default.</p></dd><dt><a name="opt.prof_leak"></a><span class="term"> 777a78e148bSantirez 778a78e148bSantirez "<code class="mallctl">opt.prof_leak</code>" 779a78e148bSantirez 780a78e148bSantirez (<span class="type">bool</span>) 781a78e148bSantirez <code class="literal">r-</code> 782a78e148bSantirez [<code class="option">--enable-prof</code>] 783a78e148bSantirez </span></dt><dd><p>Leak reporting enabled/disabled. If enabled, use an 784a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span> function to report memory leaks 785a78e148bSantirez detected by allocation sampling. See the 786a78e148bSantirez <a class="link" href="#opt.prof"> 787a78e148bSantirez "<code class="mallctl">opt.prof</code>" 788a78e148bSantirez </a> option for 789a78e148bSantirez information on analyzing heap profile output. This option is disabled 790fceef8e0Santirez by default.</p></dd><dt><a name="thread.arena"></a><span class="term"> 791a78e148bSantirez 792a78e148bSantirez "<code class="mallctl">thread.arena</code>" 793a78e148bSantirez 794a78e148bSantirez (<span class="type">unsigned</span>) 795a78e148bSantirez <code class="literal">rw</code> 796a78e148bSantirez </span></dt><dd><p>Get or set the arena associated with the calling 7977383c3b1Santirez thread. If the specified arena was not initialized beforehand (see the 7987383c3b1Santirez <a class="link" href="#arenas.initialized"> 799a78e148bSantirez "<code class="mallctl">arenas.initialized</code>" 800a78e148bSantirez </a> 801a78e148bSantirez mallctl), it will be automatically initialized as a side effect of 802a78e148bSantirez calling this interface.</p></dd><dt><a name="thread.allocated"></a><span class="term"> 803a78e148bSantirez 804a78e148bSantirez "<code class="mallctl">thread.allocated</code>" 805a78e148bSantirez 806a78e148bSantirez (<span class="type">uint64_t</span>) 807a78e148bSantirez <code class="literal">r-</code> 808a78e148bSantirez [<code class="option">--enable-stats</code>] 809a78e148bSantirez </span></dt><dd><p>Get the total number of bytes ever allocated by the 810a78e148bSantirez calling thread. This counter has the potential to wrap around; it is 811a78e148bSantirez up to the application to appropriately interpret the counter in such 812fceef8e0Santirez cases.</p></dd><dt><a name="thread.allocatedp"></a><span class="term"> 813a78e148bSantirez 814a78e148bSantirez "<code class="mallctl">thread.allocatedp</code>" 815a78e148bSantirez 816a78e148bSantirez (<span class="type">uint64_t *</span>) 817a78e148bSantirez <code class="literal">r-</code> 818a78e148bSantirez [<code class="option">--enable-stats</code>] 819a78e148bSantirez </span></dt><dd><p>Get a pointer to the the value that is returned by the 820a78e148bSantirez <a class="link" href="#thread.allocated"> 821a78e148bSantirez "<code class="mallctl">thread.allocated</code>" 822a78e148bSantirez </a> 823a78e148bSantirez mallctl. This is useful for avoiding the overhead of repeated 824a78e148bSantirez <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) calls.</p></dd><dt><a name="thread.deallocated"></a><span class="term"> 825a78e148bSantirez 826a78e148bSantirez "<code class="mallctl">thread.deallocated</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 the total number of bytes ever deallocated by the 832a78e148bSantirez calling thread. This counter has the potential to wrap around; it is 833a78e148bSantirez up to the application to appropriately interpret the counter in such 834fceef8e0Santirez cases.</p></dd><dt><a name="thread.deallocatedp"></a><span class="term"> 835a78e148bSantirez 836a78e148bSantirez "<code class="mallctl">thread.deallocatedp</code>" 837a78e148bSantirez 838a78e148bSantirez (<span class="type">uint64_t *</span>) 839a78e148bSantirez <code class="literal">r-</code> 840a78e148bSantirez [<code class="option">--enable-stats</code>] 841a78e148bSantirez </span></dt><dd><p>Get a pointer to the the value that is returned by the 842a78e148bSantirez <a class="link" href="#thread.deallocated"> 843a78e148bSantirez "<code class="mallctl">thread.deallocated</code>" 844a78e148bSantirez </a> 845a78e148bSantirez mallctl. This is useful for avoiding the overhead of repeated 846fceef8e0Santirez <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) calls.</p></dd><dt><a name="thread.tcache.enabled"></a><span class="term"> 847ad4c0b41Santirez 848ad4c0b41Santirez "<code class="mallctl">thread.tcache.enabled</code>" 849ad4c0b41Santirez 850ad4c0b41Santirez (<span class="type">bool</span>) 851ad4c0b41Santirez <code class="literal">rw</code> 852ad4c0b41Santirez [<code class="option">--enable-tcache</code>] 853ad4c0b41Santirez </span></dt><dd><p>Enable/disable calling thread's tcache. The tcache is 854ad4c0b41Santirez implicitly flushed as a side effect of becoming 855*5268379eSantirez disabled (see <a class="link" href="#thread.tcache.flush"> 856ad4c0b41Santirez "<code class="mallctl">thread.tcache.flush</code>" 857*5268379eSantirez </a>). 858fceef8e0Santirez </p></dd><dt><a name="thread.tcache.flush"></a><span class="term"> 859ad4c0b41Santirez 860ad4c0b41Santirez "<code class="mallctl">thread.tcache.flush</code>" 861ad4c0b41Santirez 862ad4c0b41Santirez (<span class="type">void</span>) 863ad4c0b41Santirez <code class="literal">--</code> 864ad4c0b41Santirez [<code class="option">--enable-tcache</code>] 865*5268379eSantirez </span></dt><dd><p>Flush calling thread's thread-specific cache (tcache). 866*5268379eSantirez This interface releases all cached objects and internal data structures 867*5268379eSantirez associated with the calling thread's tcache. Ordinarily, this interface 868ad4c0b41Santirez need not be called, since automatic periodic incremental garbage 869ad4c0b41Santirez collection occurs, and the thread cache is automatically discarded when 870ad4c0b41Santirez a thread exits. However, garbage collection is triggered by allocation 871ad4c0b41Santirez activity, so it is possible for a thread that stops 872ad4c0b41Santirez allocating/deallocating to retain its cache indefinitely, in which case 873*5268379eSantirez the developer may find manual flushing useful.</p></dd><dt><a name="thread.prof.name"></a><span class="term"> 874*5268379eSantirez 875*5268379eSantirez "<code class="mallctl">thread.prof.name</code>" 876*5268379eSantirez 877*5268379eSantirez (<span class="type">const char *</span>) 878*5268379eSantirez <code class="literal">r-</code> or 879*5268379eSantirez <code class="literal">-w</code> 880*5268379eSantirez [<code class="option">--enable-prof</code>] 881*5268379eSantirez </span></dt><dd><p>Get/set the descriptive name associated with the calling 882*5268379eSantirez thread in memory profile dumps. An internal copy of the name string is 883*5268379eSantirez created, so the input string need not be maintained after this interface 884*5268379eSantirez completes execution. The output string of this interface should be 885*5268379eSantirez copied for non-ephemeral uses, because multiple implementation details 886*5268379eSantirez can cause asynchronous string deallocation. Furthermore, each 887*5268379eSantirez invocation of this interface can only read or write; simultaneous 888*5268379eSantirez read/write is not supported due to string lifetime limitations. The 889*5268379eSantirez name string must nil-terminated and comprised only of characters in the 890*5268379eSantirez sets recognized 891*5268379eSantirez by <span class="citerefentry"><span class="refentrytitle">isgraph</span>(3)</span> and 892*5268379eSantirez <span class="citerefentry"><span class="refentrytitle">isblank</span>(3)</span>.</p></dd><dt><a name="thread.prof.active"></a><span class="term"> 893*5268379eSantirez 894*5268379eSantirez "<code class="mallctl">thread.prof.active</code>" 895*5268379eSantirez 896*5268379eSantirez (<span class="type">bool</span>) 897*5268379eSantirez <code class="literal">rw</code> 898*5268379eSantirez [<code class="option">--enable-prof</code>] 899*5268379eSantirez </span></dt><dd><p>Control whether sampling is currently active for the 900*5268379eSantirez calling thread. This is an activation mechanism in addition to <a class="link" href="#prof.active"> 901*5268379eSantirez "<code class="mallctl">prof.active</code>" 902*5268379eSantirez </a>; both must 903*5268379eSantirez be active for the calling thread to sample. This flag is enabled by 904*5268379eSantirez default.</p></dd><dt><a name="tcache.create"></a><span class="term"> 905*5268379eSantirez 906*5268379eSantirez "<code class="mallctl">tcache.create</code>" 907*5268379eSantirez 908*5268379eSantirez (<span class="type">unsigned</span>) 909*5268379eSantirez <code class="literal">r-</code> 910*5268379eSantirez [<code class="option">--enable-tcache</code>] 911*5268379eSantirez </span></dt><dd><p>Create an explicit thread-specific cache (tcache) and 912*5268379eSantirez return an identifier that can be passed to the <a class="link" href="#MALLOCX_TCACHE"><code class="constant">MALLOCX_TCACHE(<em class="parameter"><code>tc</code></em>)</code></a> 913*5268379eSantirez macro to explicitly use the specified cache rather than the 914*5268379eSantirez automatically managed one that is used by default. Each explicit cache 915*5268379eSantirez can be used by only one thread at a time; the application must assure 916*5268379eSantirez that this constraint holds. 917*5268379eSantirez </p></dd><dt><a name="tcache.flush"></a><span class="term"> 918*5268379eSantirez 919*5268379eSantirez "<code class="mallctl">tcache.flush</code>" 920*5268379eSantirez 921*5268379eSantirez (<span class="type">unsigned</span>) 922*5268379eSantirez <code class="literal">-w</code> 923*5268379eSantirez [<code class="option">--enable-tcache</code>] 924*5268379eSantirez </span></dt><dd><p>Flush the specified thread-specific cache (tcache). The 925*5268379eSantirez same considerations apply to this interface as to <a class="link" href="#thread.tcache.flush"> 926*5268379eSantirez "<code class="mallctl">thread.tcache.flush</code>" 927*5268379eSantirez </a>, 928*5268379eSantirez except that the tcache will never be automatically be discarded. 929*5268379eSantirez </p></dd><dt><a name="tcache.destroy"></a><span class="term"> 930*5268379eSantirez 931*5268379eSantirez "<code class="mallctl">tcache.destroy</code>" 932*5268379eSantirez 933*5268379eSantirez (<span class="type">unsigned</span>) 934*5268379eSantirez <code class="literal">-w</code> 935*5268379eSantirez [<code class="option">--enable-tcache</code>] 936*5268379eSantirez </span></dt><dd><p>Flush the specified thread-specific cache (tcache) and 937*5268379eSantirez make the identifier available for use during a future tcache creation. 938*5268379eSantirez </p></dd><dt><a name="arena.i.purge"></a><span class="term"> 9397383c3b1Santirez 9407383c3b1Santirez "<code class="mallctl">arena.<i>.purge</code>" 9417383c3b1Santirez 942*5268379eSantirez (<span class="type">void</span>) 9437383c3b1Santirez <code class="literal">--</code> 9447383c3b1Santirez </span></dt><dd><p>Purge unused dirty pages for arena <i>, or for 9457383c3b1Santirez all arenas if <i> equals <a class="link" href="#arenas.narenas"> 9467383c3b1Santirez "<code class="mallctl">arenas.narenas</code>" 9477383c3b1Santirez </a>. 9487383c3b1Santirez </p></dd><dt><a name="arena.i.dss"></a><span class="term"> 9497383c3b1Santirez 9507383c3b1Santirez "<code class="mallctl">arena.<i>.dss</code>" 9517383c3b1Santirez 9527383c3b1Santirez (<span class="type">const char *</span>) 9537383c3b1Santirez <code class="literal">rw</code> 9547383c3b1Santirez </span></dt><dd><p>Set the precedence of dss allocation as related to mmap 9557383c3b1Santirez allocation for arena <i>, or for all arenas if <i> equals 9567383c3b1Santirez <a class="link" href="#arenas.narenas"> 9577383c3b1Santirez "<code class="mallctl">arenas.narenas</code>" 958*5268379eSantirez </a>. See 959*5268379eSantirez <a class="link" href="#opt.dss"> 9607383c3b1Santirez "<code class="mallctl">opt.dss</code>" 9617383c3b1Santirez </a> for supported 962*5268379eSantirez settings.</p></dd><dt><a name="arena.i.lg_dirty_mult"></a><span class="term"> 963*5268379eSantirez 964*5268379eSantirez "<code class="mallctl">arena.<i>.lg_dirty_mult</code>" 965*5268379eSantirez 966*5268379eSantirez (<span class="type">ssize_t</span>) 967*5268379eSantirez <code class="literal">rw</code> 968*5268379eSantirez </span></dt><dd><p>Current per-arena minimum ratio (log base 2) of active 969*5268379eSantirez to dirty pages for arena <i>. Each time this interface is set and 970*5268379eSantirez the ratio is increased, pages are synchronously purged as necessary to 971*5268379eSantirez impose the new ratio. See <a class="link" href="#opt.lg_dirty_mult"> 972*5268379eSantirez "<code class="mallctl">opt.lg_dirty_mult</code>" 973*5268379eSantirez </a> 974*5268379eSantirez for additional information.</p></dd><dt><a name="arena.i.chunk_hooks"></a><span class="term"> 975*5268379eSantirez 976*5268379eSantirez "<code class="mallctl">arena.<i>.chunk_hooks</code>" 977*5268379eSantirez 978*5268379eSantirez (<span class="type">chunk_hooks_t</span>) 979*5268379eSantirez <code class="literal">rw</code> 980*5268379eSantirez </span></dt><dd><p>Get or set the chunk management hook functions for arena 981*5268379eSantirez <i>. The functions must be capable of operating on all extant 982*5268379eSantirez chunks associated with arena <i>, usually by passing unknown 983*5268379eSantirez chunks to the replaced functions. In practice, it is feasible to 984*5268379eSantirez control allocation for arenas created via <a class="link" href="#arenas.extend"> 985*5268379eSantirez "<code class="mallctl">arenas.extend</code>" 986*5268379eSantirez </a> such 987*5268379eSantirez that all chunks originate from an application-supplied chunk allocator 988*5268379eSantirez (by setting custom chunk hook functions just after arena creation), but 989*5268379eSantirez the automatically created arenas may have already created chunks prior 990*5268379eSantirez to the application having an opportunity to take over chunk 991*5268379eSantirez allocation.</p><pre class="programlisting"> 992*5268379eSantireztypedef struct { 993*5268379eSantirez chunk_alloc_t *alloc; 994*5268379eSantirez chunk_dalloc_t *dalloc; 995*5268379eSantirez chunk_commit_t *commit; 996*5268379eSantirez chunk_decommit_t *decommit; 997*5268379eSantirez chunk_purge_t *purge; 998*5268379eSantirez chunk_split_t *split; 999*5268379eSantirez chunk_merge_t *merge; 1000*5268379eSantirez} chunk_hooks_t;</pre><p>The <span class="type">chunk_hooks_t</span> structure comprises function 1001*5268379eSantirez pointers which are described individually below. jemalloc uses these 1002*5268379eSantirez functions to manage chunk lifetime, which starts off with allocation of 1003*5268379eSantirez mapped committed memory, in the simplest case followed by deallocation. 1004*5268379eSantirez However, there are performance and platform reasons to retain chunks for 1005*5268379eSantirez later reuse. Cleanup attempts cascade from deallocation to decommit to 1006*5268379eSantirez purging, which gives the chunk management functions opportunities to 1007*5268379eSantirez reject the most permanent cleanup operations in favor of less permanent 1008*5268379eSantirez (and often less costly) operations. The chunk splitting and merging 1009*5268379eSantirez operations can also be opted out of, but this is mainly intended to 1010*5268379eSantirez support platforms on which virtual memory mappings provided by the 1011*5268379eSantirez operating system kernel do not automatically coalesce and split, e.g. 1012*5268379eSantirez Windows.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef void *<b class="fsfunc">(chunk_alloc_t)</b>(</code></td><td>void *<var class="pdparam">chunk</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">alignment</var>, </td></tr><tr><td>�</td><td>bool *<var class="pdparam">zero</var>, </td></tr><tr><td>�</td><td>bool *<var class="pdparam">commit</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk allocation function conforms to the 1013*5268379eSantirez <span class="type">chunk_alloc_t</span> type and upon success returns a pointer to 1014*5268379eSantirez <em class="parameter"><code>size</code></em> bytes of mapped memory on behalf of arena 1015*5268379eSantirez <em class="parameter"><code>arena_ind</code></em> such that the chunk's base address is a 1016*5268379eSantirez multiple of <em class="parameter"><code>alignment</code></em>, as well as setting 1017*5268379eSantirez <em class="parameter"><code>*zero</code></em> to indicate whether the chunk is zeroed and 1018*5268379eSantirez <em class="parameter"><code>*commit</code></em> to indicate whether the chunk is 1019*5268379eSantirez committed. Upon error the function returns <code class="constant">NULL</code> 1020*5268379eSantirez and leaves <em class="parameter"><code>*zero</code></em> and 1021*5268379eSantirez <em class="parameter"><code>*commit</code></em> unmodified. The 1022*5268379eSantirez <em class="parameter"><code>size</code></em> parameter is always a multiple of the chunk 1023*5268379eSantirez size. The <em class="parameter"><code>alignment</code></em> parameter is always a power 1024*5268379eSantirez of two at least as large as the chunk size. Zeroing is mandatory if 1025*5268379eSantirez <em class="parameter"><code>*zero</code></em> is true upon function entry. Committing is 1026*5268379eSantirez mandatory if <em class="parameter"><code>*commit</code></em> is true upon function entry. 1027*5268379eSantirez If <em class="parameter"><code>chunk</code></em> is not <code class="constant">NULL</code>, the 1028*5268379eSantirez returned pointer must be <em class="parameter"><code>chunk</code></em> on success or 1029*5268379eSantirez <code class="constant">NULL</code> on error. Committed memory may be committed 1030*5268379eSantirez in absolute terms as on a system that does not overcommit, or in 1031*5268379eSantirez implicit terms as on a system that overcommits and satisfies physical 1032*5268379eSantirez memory needs on demand via soft page faults. Note that replacing the 1033*5268379eSantirez default chunk allocation function makes the arena's <a class="link" href="#arena.i.dss"> 1034*5268379eSantirez "<code class="mallctl">arena.<i>.dss</code>" 1035*5268379eSantirez </a> 1036*5268379eSantirez setting irrelevant.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_dalloc_t)</b>(</code></td><td>void *<var class="pdparam">chunk</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size</var>, </td></tr><tr><td>�</td><td>bool <var class="pdparam">committed</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p> 1037*5268379eSantirez A chunk deallocation function conforms to the 1038*5268379eSantirez <span class="type">chunk_dalloc_t</span> type and deallocates a 1039*5268379eSantirez <em class="parameter"><code>chunk</code></em> of given <em class="parameter"><code>size</code></em> with 1040*5268379eSantirez <em class="parameter"><code>committed</code></em>/decommited memory as indicated, on 1041*5268379eSantirez behalf of arena <em class="parameter"><code>arena_ind</code></em>, returning false upon 1042*5268379eSantirez success. If the function returns true, this indicates opt-out from 1043*5268379eSantirez deallocation; the virtual memory mapping associated with the chunk 1044*5268379eSantirez remains mapped, in the same commit state, and available for future use, 1045*5268379eSantirez in which case it will be automatically retained for later reuse.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_commit_t)</b>(</code></td><td>void *<var class="pdparam">chunk</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">offset</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">length</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk commit function conforms to the 1046*5268379eSantirez <span class="type">chunk_commit_t</span> type and commits zeroed physical memory to 1047*5268379eSantirez back pages within a <em class="parameter"><code>chunk</code></em> of given 1048*5268379eSantirez <em class="parameter"><code>size</code></em> at <em class="parameter"><code>offset</code></em> bytes, 1049*5268379eSantirez extending for <em class="parameter"><code>length</code></em> on behalf of arena 1050*5268379eSantirez <em class="parameter"><code>arena_ind</code></em>, returning false upon success. 1051*5268379eSantirez Committed memory may be committed in absolute terms as on a system that 1052*5268379eSantirez does not overcommit, or in implicit terms as on a system that 1053*5268379eSantirez overcommits and satisfies physical memory needs on demand via soft page 1054*5268379eSantirez faults. If the function returns true, this indicates insufficient 1055*5268379eSantirez physical memory to satisfy the request.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_decommit_t)</b>(</code></td><td>void *<var class="pdparam">chunk</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">offset</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">length</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk decommit function conforms to the 1056*5268379eSantirez <span class="type">chunk_decommit_t</span> type and decommits any physical memory 1057*5268379eSantirez that is backing pages within a <em class="parameter"><code>chunk</code></em> of given 1058*5268379eSantirez <em class="parameter"><code>size</code></em> at <em class="parameter"><code>offset</code></em> bytes, 1059*5268379eSantirez extending for <em class="parameter"><code>length</code></em> on behalf of arena 1060*5268379eSantirez <em class="parameter"><code>arena_ind</code></em>, returning false upon success, in which 1061*5268379eSantirez case the pages will be committed via the chunk commit function before 1062*5268379eSantirez being reused. If the function returns true, this indicates opt-out from 1063*5268379eSantirez decommit; the memory remains committed and available for future use, in 1064*5268379eSantirez which case it will be automatically retained for later reuse.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_purge_t)</b>(</code></td><td>void *<var class="pdparam">chunk</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">offset</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">length</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk purge function conforms to the <span class="type">chunk_purge_t</span> 1065*5268379eSantirez type and optionally discards physical pages within the virtual memory 1066*5268379eSantirez mapping associated with <em class="parameter"><code>chunk</code></em> of given 1067*5268379eSantirez <em class="parameter"><code>size</code></em> at <em class="parameter"><code>offset</code></em> bytes, 1068*5268379eSantirez extending for <em class="parameter"><code>length</code></em> on behalf of arena 1069*5268379eSantirez <em class="parameter"><code>arena_ind</code></em>, returning false if pages within the 1070*5268379eSantirez purged virtual memory range will be zero-filled the next time they are 1071*5268379eSantirez accessed.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_split_t)</b>(</code></td><td>void *<var class="pdparam">chunk</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">size_a</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size_b</var>, </td></tr><tr><td>�</td><td>bool <var class="pdparam">committed</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk split function conforms to the <span class="type">chunk_split_t</span> 1072*5268379eSantirez type and optionally splits <em class="parameter"><code>chunk</code></em> of given 1073*5268379eSantirez <em class="parameter"><code>size</code></em> into two adjacent chunks, the first of 1074*5268379eSantirez <em class="parameter"><code>size_a</code></em> bytes, and the second of 1075*5268379eSantirez <em class="parameter"><code>size_b</code></em> bytes, operating on 1076*5268379eSantirez <em class="parameter"><code>committed</code></em>/decommitted memory as indicated, on 1077*5268379eSantirez behalf of arena <em class="parameter"><code>arena_ind</code></em>, returning false upon 1078*5268379eSantirez success. If the function returns true, this indicates that the chunk 1079*5268379eSantirez remains unsplit and therefore should continue to be operated on as a 1080*5268379eSantirez whole.</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">typedef bool <b class="fsfunc">(chunk_merge_t)</b>(</code></td><td>void *<var class="pdparam">chunk_a</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size_a</var>, </td></tr><tr><td>�</td><td>void *<var class="pdparam">chunk_b</var>, </td></tr><tr><td>�</td><td>size_t <var class="pdparam">size_b</var>, </td></tr><tr><td>�</td><td>bool <var class="pdparam">committed</var>, </td></tr><tr><td>�</td><td>unsigned <var class="pdparam">arena_ind</var><code>)</code>;</td></tr></table><div class="funcprototype-spacer">�</div></div><div class="literallayout"><p></p></div><p>A chunk merge function conforms to the <span class="type">chunk_merge_t</span> 1081*5268379eSantirez type and optionally merges adjacent chunks, 1082*5268379eSantirez <em class="parameter"><code>chunk_a</code></em> of given <em class="parameter"><code>size_a</code></em> 1083*5268379eSantirez and <em class="parameter"><code>chunk_b</code></em> of given 1084*5268379eSantirez <em class="parameter"><code>size_b</code></em> into one contiguous chunk, operating on 1085*5268379eSantirez <em class="parameter"><code>committed</code></em>/decommitted memory as indicated, on 1086*5268379eSantirez behalf of arena <em class="parameter"><code>arena_ind</code></em>, returning false upon 1087*5268379eSantirez success. If the function returns true, this indicates that the chunks 1088*5268379eSantirez remain distinct mappings and therefore should continue to be operated on 1089*5268379eSantirez independently.</p></dd><dt><a name="arenas.narenas"></a><span class="term"> 1090a78e148bSantirez 1091a78e148bSantirez "<code class="mallctl">arenas.narenas</code>" 1092a78e148bSantirez 1093a78e148bSantirez (<span class="type">unsigned</span>) 1094a78e148bSantirez <code class="literal">r-</code> 10957383c3b1Santirez </span></dt><dd><p>Current limit on number of arenas.</p></dd><dt><a name="arenas.initialized"></a><span class="term"> 1096a78e148bSantirez 1097a78e148bSantirez "<code class="mallctl">arenas.initialized</code>" 1098a78e148bSantirez 1099a78e148bSantirez (<span class="type">bool *</span>) 1100a78e148bSantirez <code class="literal">r-</code> 1101a78e148bSantirez </span></dt><dd><p>An array of <a class="link" href="#arenas.narenas"> 1102a78e148bSantirez "<code class="mallctl">arenas.narenas</code>" 1103a78e148bSantirez </a> 1104a78e148bSantirez booleans. Each boolean indicates whether the corresponding arena is 1105*5268379eSantirez initialized.</p></dd><dt><a name="arenas.lg_dirty_mult"></a><span class="term"> 1106*5268379eSantirez 1107*5268379eSantirez "<code class="mallctl">arenas.lg_dirty_mult</code>" 1108*5268379eSantirez 1109*5268379eSantirez (<span class="type">ssize_t</span>) 1110*5268379eSantirez <code class="literal">rw</code> 1111*5268379eSantirez </span></dt><dd><p>Current default per-arena minimum ratio (log base 2) of 1112*5268379eSantirez active to dirty pages, used to initialize <a class="link" href="#arena.i.lg_dirty_mult"> 1113*5268379eSantirez "<code class="mallctl">arena.<i>.lg_dirty_mult</code>" 1114*5268379eSantirez </a> 1115*5268379eSantirez during arena creation. See <a class="link" href="#opt.lg_dirty_mult"> 1116*5268379eSantirez "<code class="mallctl">opt.lg_dirty_mult</code>" 1117*5268379eSantirez </a> 1118*5268379eSantirez for additional information.</p></dd><dt><a name="arenas.quantum"></a><span class="term"> 1119a78e148bSantirez 1120a78e148bSantirez "<code class="mallctl">arenas.quantum</code>" 1121a78e148bSantirez 1122a78e148bSantirez (<span class="type">size_t</span>) 1123a78e148bSantirez <code class="literal">r-</code> 1124fceef8e0Santirez </span></dt><dd><p>Quantum size.</p></dd><dt><a name="arenas.page"></a><span class="term"> 1125a78e148bSantirez 1126ad4c0b41Santirez "<code class="mallctl">arenas.page</code>" 1127a78e148bSantirez 1128a78e148bSantirez (<span class="type">size_t</span>) 1129a78e148bSantirez <code class="literal">r-</code> 1130fceef8e0Santirez </span></dt><dd><p>Page size.</p></dd><dt><a name="arenas.tcache_max"></a><span class="term"> 1131a78e148bSantirez 1132a78e148bSantirez "<code class="mallctl">arenas.tcache_max</code>" 1133a78e148bSantirez 1134a78e148bSantirez (<span class="type">size_t</span>) 1135a78e148bSantirez <code class="literal">r-</code> 1136a78e148bSantirez [<code class="option">--enable-tcache</code>] 1137fceef8e0Santirez </span></dt><dd><p>Maximum thread-cached size class.</p></dd><dt><a name="arenas.nbins"></a><span class="term"> 1138a78e148bSantirez 1139a78e148bSantirez "<code class="mallctl">arenas.nbins</code>" 1140a78e148bSantirez 1141a78e148bSantirez (<span class="type">unsigned</span>) 1142a78e148bSantirez <code class="literal">r-</code> 1143fceef8e0Santirez </span></dt><dd><p>Number of bin size classes.</p></dd><dt><a name="arenas.nhbins"></a><span class="term"> 1144a78e148bSantirez 1145a78e148bSantirez "<code class="mallctl">arenas.nhbins</code>" 1146a78e148bSantirez 1147a78e148bSantirez (<span class="type">unsigned</span>) 1148a78e148bSantirez <code class="literal">r-</code> 1149a78e148bSantirez [<code class="option">--enable-tcache</code>] 1150a78e148bSantirez </span></dt><dd><p>Total number of thread cache bin size 1151a78e148bSantirez classes.</p></dd><dt><a name="arenas.bin.i.size"></a><span class="term"> 1152a78e148bSantirez 1153a78e148bSantirez "<code class="mallctl">arenas.bin.<i>.size</code>" 1154a78e148bSantirez 1155a78e148bSantirez (<span class="type">size_t</span>) 1156a78e148bSantirez <code class="literal">r-</code> 1157fceef8e0Santirez </span></dt><dd><p>Maximum size supported by size class.</p></dd><dt><a name="arenas.bin.i.nregs"></a><span class="term"> 1158a78e148bSantirez 1159a78e148bSantirez "<code class="mallctl">arenas.bin.<i>.nregs</code>" 1160a78e148bSantirez 1161a78e148bSantirez (<span class="type">uint32_t</span>) 1162a78e148bSantirez <code class="literal">r-</code> 1163fceef8e0Santirez </span></dt><dd><p>Number of regions per page run.</p></dd><dt><a name="arenas.bin.i.run_size"></a><span class="term"> 1164a78e148bSantirez 1165a78e148bSantirez "<code class="mallctl">arenas.bin.<i>.run_size</code>" 1166a78e148bSantirez 1167a78e148bSantirez (<span class="type">size_t</span>) 1168a78e148bSantirez <code class="literal">r-</code> 1169fceef8e0Santirez </span></dt><dd><p>Number of bytes per page run.</p></dd><dt><a name="arenas.nlruns"></a><span class="term"> 1170a78e148bSantirez 1171a78e148bSantirez "<code class="mallctl">arenas.nlruns</code>" 1172a78e148bSantirez 1173*5268379eSantirez (<span class="type">unsigned</span>) 1174a78e148bSantirez <code class="literal">r-</code> 1175fceef8e0Santirez </span></dt><dd><p>Total number of large size classes.</p></dd><dt><a name="arenas.lrun.i.size"></a><span class="term"> 1176a78e148bSantirez 1177a78e148bSantirez "<code class="mallctl">arenas.lrun.<i>.size</code>" 1178a78e148bSantirez 1179a78e148bSantirez (<span class="type">size_t</span>) 1180a78e148bSantirez <code class="literal">r-</code> 1181a78e148bSantirez </span></dt><dd><p>Maximum size supported by this large size 1182*5268379eSantirez class.</p></dd><dt><a name="arenas.nhchunks"></a><span class="term"> 1183a78e148bSantirez 1184*5268379eSantirez "<code class="mallctl">arenas.nhchunks</code>" 1185a78e148bSantirez 1186a78e148bSantirez (<span class="type">unsigned</span>) 1187*5268379eSantirez <code class="literal">r-</code> 1188*5268379eSantirez </span></dt><dd><p>Total number of huge size classes.</p></dd><dt><a name="arenas.hchunk.i.size"></a><span class="term"> 1189*5268379eSantirez 1190*5268379eSantirez "<code class="mallctl">arenas.hchunk.<i>.size</code>" 1191*5268379eSantirez 1192*5268379eSantirez (<span class="type">size_t</span>) 1193*5268379eSantirez <code class="literal">r-</code> 1194*5268379eSantirez </span></dt><dd><p>Maximum size supported by this huge size 1195*5268379eSantirez class.</p></dd><dt><a name="arenas.extend"></a><span class="term"> 11967383c3b1Santirez 11977383c3b1Santirez "<code class="mallctl">arenas.extend</code>" 11987383c3b1Santirez 11997383c3b1Santirez (<span class="type">unsigned</span>) 12007383c3b1Santirez <code class="literal">r-</code> 12017383c3b1Santirez </span></dt><dd><p>Extend the array of arenas by appending a new arena, 1202*5268379eSantirez and returning the new arena index.</p></dd><dt><a name="prof.thread_active_init"></a><span class="term"> 1203*5268379eSantirez 1204*5268379eSantirez "<code class="mallctl">prof.thread_active_init</code>" 1205*5268379eSantirez 1206*5268379eSantirez (<span class="type">bool</span>) 1207*5268379eSantirez <code class="literal">rw</code> 1208*5268379eSantirez [<code class="option">--enable-prof</code>] 1209*5268379eSantirez </span></dt><dd><p>Control the initial setting for <a class="link" href="#thread.prof.active"> 1210*5268379eSantirez "<code class="mallctl">thread.prof.active</code>" 1211*5268379eSantirez </a> 1212*5268379eSantirez in newly created threads. See the <a class="link" href="#opt.prof_thread_active_init"> 1213*5268379eSantirez "<code class="mallctl">opt.prof_thread_active_init</code>" 1214*5268379eSantirez </a> 1215*5268379eSantirez option for additional information.</p></dd><dt><a name="prof.active"></a><span class="term"> 1216a78e148bSantirez 1217a78e148bSantirez "<code class="mallctl">prof.active</code>" 1218a78e148bSantirez 1219a78e148bSantirez (<span class="type">bool</span>) 1220a78e148bSantirez <code class="literal">rw</code> 1221a78e148bSantirez [<code class="option">--enable-prof</code>] 1222a78e148bSantirez </span></dt><dd><p>Control whether sampling is currently active. See the 1223a78e148bSantirez <a class="link" href="#opt.prof_active"> 1224a78e148bSantirez "<code class="mallctl">opt.prof_active</code>" 1225a78e148bSantirez </a> 1226*5268379eSantirez option for additional information, as well as the interrelated <a class="link" href="#thread.prof.active"> 1227*5268379eSantirez "<code class="mallctl">thread.prof.active</code>" 1228*5268379eSantirez </a> 1229*5268379eSantirez mallctl.</p></dd><dt><a name="prof.dump"></a><span class="term"> 1230a78e148bSantirez 1231a78e148bSantirez "<code class="mallctl">prof.dump</code>" 1232a78e148bSantirez 1233a78e148bSantirez (<span class="type">const char *</span>) 1234a78e148bSantirez <code class="literal">-w</code> 1235a78e148bSantirez [<code class="option">--enable-prof</code>] 1236a78e148bSantirez </span></dt><dd><p>Dump a memory profile to the specified file, or if NULL 1237a78e148bSantirez is specified, to a file according to the pattern 1238a78e148bSantirez <code class="filename"><prefix>.<pid>.<seq>.m<mseq>.heap</code>, 1239a78e148bSantirez where <code class="literal"><prefix></code> is controlled by the 1240a78e148bSantirez <a class="link" href="#opt.prof_prefix"> 1241a78e148bSantirez "<code class="mallctl">opt.prof_prefix</code>" 1242a78e148bSantirez </a> 1243*5268379eSantirez option.</p></dd><dt><a name="prof.gdump"></a><span class="term"> 1244*5268379eSantirez 1245*5268379eSantirez "<code class="mallctl">prof.gdump</code>" 1246*5268379eSantirez 1247*5268379eSantirez (<span class="type">bool</span>) 1248*5268379eSantirez <code class="literal">rw</code> 1249*5268379eSantirez [<code class="option">--enable-prof</code>] 1250*5268379eSantirez </span></dt><dd><p>When enabled, trigger a memory profile dump every time 1251*5268379eSantirez the total virtual memory exceeds the previous maximum. Profiles are 1252*5268379eSantirez dumped to files named according to the pattern 1253*5268379eSantirez <code class="filename"><prefix>.<pid>.<seq>.u<useq>.heap</code>, 1254*5268379eSantirez where <code class="literal"><prefix></code> is controlled by the <a class="link" href="#opt.prof_prefix"> 1255*5268379eSantirez "<code class="mallctl">opt.prof_prefix</code>" 1256*5268379eSantirez </a> 1257*5268379eSantirez option.</p></dd><dt><a name="prof.reset"></a><span class="term"> 1258*5268379eSantirez 1259*5268379eSantirez "<code class="mallctl">prof.reset</code>" 1260*5268379eSantirez 1261*5268379eSantirez (<span class="type">size_t</span>) 1262*5268379eSantirez <code class="literal">-w</code> 1263*5268379eSantirez [<code class="option">--enable-prof</code>] 1264*5268379eSantirez </span></dt><dd><p>Reset all memory profile statistics, and optionally 1265*5268379eSantirez update the sample rate (see <a class="link" href="#opt.lg_prof_sample"> 1266*5268379eSantirez "<code class="mallctl">opt.lg_prof_sample</code>" 1267*5268379eSantirez </a> 1268*5268379eSantirez and <a class="link" href="#prof.lg_sample"> 1269*5268379eSantirez "<code class="mallctl">prof.lg_sample</code>" 1270*5268379eSantirez </a>). 1271*5268379eSantirez </p></dd><dt><a name="prof.lg_sample"></a><span class="term"> 1272*5268379eSantirez 1273*5268379eSantirez "<code class="mallctl">prof.lg_sample</code>" 1274*5268379eSantirez 1275*5268379eSantirez (<span class="type">size_t</span>) 1276*5268379eSantirez <code class="literal">r-</code> 1277*5268379eSantirez [<code class="option">--enable-prof</code>] 1278*5268379eSantirez </span></dt><dd><p>Get the current sample rate (see <a class="link" href="#opt.lg_prof_sample"> 1279*5268379eSantirez "<code class="mallctl">opt.lg_prof_sample</code>" 1280*5268379eSantirez </a>). 1281*5268379eSantirez </p></dd><dt><a name="prof.interval"></a><span class="term"> 1282a78e148bSantirez 1283a78e148bSantirez "<code class="mallctl">prof.interval</code>" 1284a78e148bSantirez 1285a78e148bSantirez (<span class="type">uint64_t</span>) 1286a78e148bSantirez <code class="literal">r-</code> 1287a78e148bSantirez [<code class="option">--enable-prof</code>] 1288a78e148bSantirez </span></dt><dd><p>Average number of bytes allocated between 1289a78e148bSantirez inverval-based profile dumps. See the 1290a78e148bSantirez <a class="link" href="#opt.lg_prof_interval"> 1291a78e148bSantirez "<code class="mallctl">opt.lg_prof_interval</code>" 1292a78e148bSantirez </a> 1293a78e148bSantirez option for additional information.</p></dd><dt><a name="stats.cactive"></a><span class="term"> 1294a78e148bSantirez 1295a78e148bSantirez "<code class="mallctl">stats.cactive</code>" 1296a78e148bSantirez 1297a78e148bSantirez (<span class="type">size_t *</span>) 1298a78e148bSantirez <code class="literal">r-</code> 1299a78e148bSantirez [<code class="option">--enable-stats</code>] 1300a78e148bSantirez </span></dt><dd><p>Pointer to a counter that contains an approximate count 1301a78e148bSantirez of the current number of bytes in active pages. The estimate may be 1302*5268379eSantirez high, but never low, because each arena rounds up when computing its 1303*5268379eSantirez contribution to the counter. Note that the <a class="link" href="#epoch"> 1304a78e148bSantirez "<code class="mallctl">epoch</code>" 1305a78e148bSantirez </a> mallctl has no bearing 1306a78e148bSantirez on this counter. Furthermore, counter consistency is maintained via 1307a78e148bSantirez atomic operations, so it is necessary to use an atomic operation in 1308a78e148bSantirez order to guarantee a consistent read when dereferencing the pointer. 1309a78e148bSantirez </p></dd><dt><a name="stats.allocated"></a><span class="term"> 1310a78e148bSantirez 1311a78e148bSantirez "<code class="mallctl">stats.allocated</code>" 1312a78e148bSantirez 1313a78e148bSantirez (<span class="type">size_t</span>) 1314a78e148bSantirez <code class="literal">r-</code> 1315a78e148bSantirez [<code class="option">--enable-stats</code>] 1316a78e148bSantirez </span></dt><dd><p>Total number of bytes allocated by the 1317a78e148bSantirez application.</p></dd><dt><a name="stats.active"></a><span class="term"> 1318a78e148bSantirez 1319a78e148bSantirez "<code class="mallctl">stats.active</code>" 1320a78e148bSantirez 1321a78e148bSantirez (<span class="type">size_t</span>) 1322a78e148bSantirez <code class="literal">r-</code> 1323a78e148bSantirez [<code class="option">--enable-stats</code>] 1324a78e148bSantirez </span></dt><dd><p>Total number of bytes in active pages allocated by the 1325a78e148bSantirez application. This is a multiple of the page size, and greater than or 1326a78e148bSantirez equal to <a class="link" href="#stats.allocated"> 1327a78e148bSantirez "<code class="mallctl">stats.allocated</code>" 1328a78e148bSantirez </a>. 13297383c3b1Santirez This does not include <a class="link" href="#stats.arenas.i.pdirty"> 13307383c3b1Santirez 13317383c3b1Santirez "<code class="mallctl">stats.arenas.<i>.pdirty</code>" 1332*5268379eSantirez </a>, nor pages 1333*5268379eSantirez entirely devoted to allocator metadata.</p></dd><dt><a name="stats.metadata"></a><span class="term"> 1334*5268379eSantirez 1335*5268379eSantirez "<code class="mallctl">stats.metadata</code>" 1336*5268379eSantirez 1337*5268379eSantirez (<span class="type">size_t</span>) 1338*5268379eSantirez <code class="literal">r-</code> 1339*5268379eSantirez [<code class="option">--enable-stats</code>] 1340*5268379eSantirez </span></dt><dd><p>Total number of bytes dedicated to metadata, which 1341*5268379eSantirez comprise base allocations used for bootstrap-sensitive internal 1342*5268379eSantirez allocator data structures, arena chunk headers (see <a class="link" href="#stats.arenas.i.metadata.mapped"> 1343*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.metadata.mapped</code>" 1344*5268379eSantirez </a>), 1345*5268379eSantirez and internal allocations (see <a class="link" href="#stats.arenas.i.metadata.allocated"> 1346*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.metadata.allocated</code>" 1347*5268379eSantirez </a>).</p></dd><dt><a name="stats.resident"></a><span class="term"> 1348*5268379eSantirez 1349*5268379eSantirez "<code class="mallctl">stats.resident</code>" 1350*5268379eSantirez 1351*5268379eSantirez (<span class="type">size_t</span>) 1352*5268379eSantirez <code class="literal">r-</code> 1353*5268379eSantirez [<code class="option">--enable-stats</code>] 1354*5268379eSantirez </span></dt><dd><p>Maximum number of bytes in physically resident data 1355*5268379eSantirez pages mapped by the allocator, comprising all pages dedicated to 1356*5268379eSantirez allocator metadata, pages backing active allocations, and unused dirty 1357*5268379eSantirez pages. This is a maximum rather than precise because pages may not 1358*5268379eSantirez actually be physically resident if they correspond to demand-zeroed 1359*5268379eSantirez virtual memory that has not yet been touched. This is a multiple of the 1360*5268379eSantirez page size, and is larger than <a class="link" href="#stats.active"> 1361*5268379eSantirez "<code class="mallctl">stats.active</code>" 1362*5268379eSantirez </a>.</p></dd><dt><a name="stats.mapped"></a><span class="term"> 1363a78e148bSantirez 1364a78e148bSantirez "<code class="mallctl">stats.mapped</code>" 1365a78e148bSantirez 1366a78e148bSantirez (<span class="type">size_t</span>) 1367a78e148bSantirez <code class="literal">r-</code> 1368a78e148bSantirez [<code class="option">--enable-stats</code>] 1369*5268379eSantirez </span></dt><dd><p>Total number of bytes in active chunks mapped by the 1370*5268379eSantirez allocator. This is a multiple of the chunk size, and is larger than 1371*5268379eSantirez <a class="link" href="#stats.active"> 1372a78e148bSantirez "<code class="mallctl">stats.active</code>" 1373*5268379eSantirez </a>. 1374*5268379eSantirez This does not include inactive chunks, even those that contain unused 1375*5268379eSantirez dirty pages, which means that there is no strict ordering between this 1376*5268379eSantirez and <a class="link" href="#stats.resident"> 1377*5268379eSantirez "<code class="mallctl">stats.resident</code>" 1378*5268379eSantirez </a>.</p></dd><dt><a name="stats.arenas.i.dss"></a><span class="term"> 1379a78e148bSantirez 13807383c3b1Santirez "<code class="mallctl">stats.arenas.<i>.dss</code>" 13817383c3b1Santirez 13827383c3b1Santirez (<span class="type">const char *</span>) 13837383c3b1Santirez <code class="literal">r-</code> 13847383c3b1Santirez </span></dt><dd><p>dss (<span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>) allocation precedence as 13857383c3b1Santirez related to <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span> allocation. See <a class="link" href="#opt.dss"> 13867383c3b1Santirez "<code class="mallctl">opt.dss</code>" 13877383c3b1Santirez </a> for details. 1388*5268379eSantirez </p></dd><dt><a name="stats.arenas.i.lg_dirty_mult"></a><span class="term"> 1389*5268379eSantirez 1390*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.lg_dirty_mult</code>" 1391*5268379eSantirez 1392*5268379eSantirez (<span class="type">ssize_t</span>) 1393*5268379eSantirez <code class="literal">r-</code> 1394*5268379eSantirez </span></dt><dd><p>Minimum ratio (log base 2) of active to dirty pages. 1395*5268379eSantirez See <a class="link" href="#opt.lg_dirty_mult"> 1396*5268379eSantirez "<code class="mallctl">opt.lg_dirty_mult</code>" 1397*5268379eSantirez </a> 1398*5268379eSantirez for details.</p></dd><dt><a name="stats.arenas.i.nthreads"></a><span class="term"> 13997383c3b1Santirez 1400a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.nthreads</code>" 1401a78e148bSantirez 1402a78e148bSantirez (<span class="type">unsigned</span>) 1403a78e148bSantirez <code class="literal">r-</code> 1404a78e148bSantirez </span></dt><dd><p>Number of threads currently assigned to 1405fceef8e0Santirez arena.</p></dd><dt><a name="stats.arenas.i.pactive"></a><span class="term"> 1406a78e148bSantirez 1407a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.pactive</code>" 1408a78e148bSantirez 1409a78e148bSantirez (<span class="type">size_t</span>) 1410a78e148bSantirez <code class="literal">r-</code> 14117383c3b1Santirez </span></dt><dd><p>Number of pages in active runs.</p></dd><dt><a name="stats.arenas.i.pdirty"></a><span class="term"> 1412a78e148bSantirez 1413a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.pdirty</code>" 1414a78e148bSantirez 1415a78e148bSantirez (<span class="type">size_t</span>) 1416a78e148bSantirez <code class="literal">r-</code> 1417a78e148bSantirez </span></dt><dd><p>Number of pages within unused runs that are potentially 1418a78e148bSantirez dirty, and for which <code class="function">madvise</code>(<em class="parameter"><code>...</code></em>, 1419a78e148bSantirez <em class="parameter"><code><code class="constant">MADV_DONTNEED</code></code></em>) or 1420fceef8e0Santirez similar has not been called.</p></dd><dt><a name="stats.arenas.i.mapped"></a><span class="term"> 1421a78e148bSantirez 1422a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.mapped</code>" 1423a78e148bSantirez 1424a78e148bSantirez (<span class="type">size_t</span>) 1425a78e148bSantirez <code class="literal">r-</code> 1426a78e148bSantirez [<code class="option">--enable-stats</code>] 1427*5268379eSantirez </span></dt><dd><p>Number of mapped bytes.</p></dd><dt><a name="stats.arenas.i.metadata.mapped"></a><span class="term"> 1428*5268379eSantirez 1429*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.metadata.mapped</code>" 1430*5268379eSantirez 1431*5268379eSantirez (<span class="type">size_t</span>) 1432*5268379eSantirez <code class="literal">r-</code> 1433*5268379eSantirez [<code class="option">--enable-stats</code>] 1434*5268379eSantirez </span></dt><dd><p>Number of mapped bytes in arena chunk headers, which 1435*5268379eSantirez track the states of the non-metadata pages.</p></dd><dt><a name="stats.arenas.i.metadata.allocated"></a><span class="term"> 1436*5268379eSantirez 1437*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.metadata.allocated</code>" 1438*5268379eSantirez 1439*5268379eSantirez (<span class="type">size_t</span>) 1440*5268379eSantirez <code class="literal">r-</code> 1441*5268379eSantirez [<code class="option">--enable-stats</code>] 1442*5268379eSantirez </span></dt><dd><p>Number of bytes dedicated to internal allocations. 1443*5268379eSantirez Internal allocations differ from application-originated allocations in 1444*5268379eSantirez that they are for internal use, and that they are omitted from heap 1445*5268379eSantirez profiles. This statistic is reported separately from <a class="link" href="#stats.metadata"> 1446*5268379eSantirez "<code class="mallctl">stats.metadata</code>" 1447*5268379eSantirez </a> and 1448*5268379eSantirez <a class="link" href="#stats.arenas.i.metadata.mapped"> 1449*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.metadata.mapped</code>" 1450*5268379eSantirez </a> 1451*5268379eSantirez because it overlaps with e.g. the <a class="link" href="#stats.allocated"> 1452*5268379eSantirez "<code class="mallctl">stats.allocated</code>" 1453*5268379eSantirez </a> and 1454*5268379eSantirez <a class="link" href="#stats.active"> 1455*5268379eSantirez "<code class="mallctl">stats.active</code>" 1456*5268379eSantirez </a> 1457*5268379eSantirez statistics, whereas the other metadata statistics do 1458*5268379eSantirez not.</p></dd><dt><a name="stats.arenas.i.npurge"></a><span class="term"> 1459a78e148bSantirez 1460a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.npurge</code>" 1461a78e148bSantirez 1462a78e148bSantirez (<span class="type">uint64_t</span>) 1463a78e148bSantirez <code class="literal">r-</code> 1464a78e148bSantirez [<code class="option">--enable-stats</code>] 1465a78e148bSantirez </span></dt><dd><p>Number of dirty page purge sweeps performed. 1466fceef8e0Santirez </p></dd><dt><a name="stats.arenas.i.nmadvise"></a><span class="term"> 1467a78e148bSantirez 1468a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.nmadvise</code>" 1469a78e148bSantirez 1470a78e148bSantirez (<span class="type">uint64_t</span>) 1471a78e148bSantirez <code class="literal">r-</code> 1472a78e148bSantirez [<code class="option">--enable-stats</code>] 1473a78e148bSantirez </span></dt><dd><p>Number of <code class="function">madvise</code>(<em class="parameter"><code>...</code></em>, 1474a78e148bSantirez <em class="parameter"><code><code class="constant">MADV_DONTNEED</code></code></em>) or 1475fceef8e0Santirez similar calls made to purge dirty pages.</p></dd><dt><a name="stats.arenas.i.purged"></a><span class="term"> 1476a78e148bSantirez 1477fceef8e0Santirez "<code class="mallctl">stats.arenas.<i>.purged</code>" 1478a78e148bSantirez 1479a78e148bSantirez (<span class="type">uint64_t</span>) 1480a78e148bSantirez <code class="literal">r-</code> 1481a78e148bSantirez [<code class="option">--enable-stats</code>] 1482fceef8e0Santirez </span></dt><dd><p>Number of pages purged.</p></dd><dt><a name="stats.arenas.i.small.allocated"></a><span class="term"> 1483a78e148bSantirez 1484a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.small.allocated</code>" 1485a78e148bSantirez 1486a78e148bSantirez (<span class="type">size_t</span>) 1487a78e148bSantirez <code class="literal">r-</code> 1488a78e148bSantirez [<code class="option">--enable-stats</code>] 1489a78e148bSantirez </span></dt><dd><p>Number of bytes currently allocated by small objects. 1490fceef8e0Santirez </p></dd><dt><a name="stats.arenas.i.small.nmalloc"></a><span class="term"> 1491a78e148bSantirez 1492a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.small.nmalloc</code>" 1493a78e148bSantirez 1494a78e148bSantirez (<span class="type">uint64_t</span>) 1495a78e148bSantirez <code class="literal">r-</code> 1496a78e148bSantirez [<code class="option">--enable-stats</code>] 1497a78e148bSantirez </span></dt><dd><p>Cumulative number of allocation requests served by 1498fceef8e0Santirez small bins.</p></dd><dt><a name="stats.arenas.i.small.ndalloc"></a><span class="term"> 1499a78e148bSantirez 1500a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.small.ndalloc</code>" 1501a78e148bSantirez 1502a78e148bSantirez (<span class="type">uint64_t</span>) 1503a78e148bSantirez <code class="literal">r-</code> 1504a78e148bSantirez [<code class="option">--enable-stats</code>] 1505a78e148bSantirez </span></dt><dd><p>Cumulative number of small objects returned to bins. 1506fceef8e0Santirez </p></dd><dt><a name="stats.arenas.i.small.nrequests"></a><span class="term"> 1507a78e148bSantirez 1508a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.small.nrequests</code>" 1509a78e148bSantirez 1510a78e148bSantirez (<span class="type">uint64_t</span>) 1511a78e148bSantirez <code class="literal">r-</code> 1512a78e148bSantirez [<code class="option">--enable-stats</code>] 1513a78e148bSantirez </span></dt><dd><p>Cumulative number of small allocation requests. 1514fceef8e0Santirez </p></dd><dt><a name="stats.arenas.i.large.allocated"></a><span class="term"> 1515a78e148bSantirez 1516a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.large.allocated</code>" 1517a78e148bSantirez 1518a78e148bSantirez (<span class="type">size_t</span>) 1519a78e148bSantirez <code class="literal">r-</code> 1520a78e148bSantirez [<code class="option">--enable-stats</code>] 1521a78e148bSantirez </span></dt><dd><p>Number of bytes currently allocated by large objects. 1522fceef8e0Santirez </p></dd><dt><a name="stats.arenas.i.large.nmalloc"></a><span class="term"> 1523a78e148bSantirez 1524a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.large.nmalloc</code>" 1525a78e148bSantirez 1526a78e148bSantirez (<span class="type">uint64_t</span>) 1527a78e148bSantirez <code class="literal">r-</code> 1528a78e148bSantirez [<code class="option">--enable-stats</code>] 1529a78e148bSantirez </span></dt><dd><p>Cumulative number of large allocation requests served 1530fceef8e0Santirez directly by the arena.</p></dd><dt><a name="stats.arenas.i.large.ndalloc"></a><span class="term"> 1531a78e148bSantirez 1532a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.large.ndalloc</code>" 1533a78e148bSantirez 1534a78e148bSantirez (<span class="type">uint64_t</span>) 1535a78e148bSantirez <code class="literal">r-</code> 1536a78e148bSantirez [<code class="option">--enable-stats</code>] 1537a78e148bSantirez </span></dt><dd><p>Cumulative number of large deallocation requests served 1538fceef8e0Santirez directly by the arena.</p></dd><dt><a name="stats.arenas.i.large.nrequests"></a><span class="term"> 1539a78e148bSantirez 1540a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.large.nrequests</code>" 1541a78e148bSantirez 1542a78e148bSantirez (<span class="type">uint64_t</span>) 1543a78e148bSantirez <code class="literal">r-</code> 1544a78e148bSantirez [<code class="option">--enable-stats</code>] 1545a78e148bSantirez </span></dt><dd><p>Cumulative number of large allocation requests. 1546*5268379eSantirez </p></dd><dt><a name="stats.arenas.i.huge.allocated"></a><span class="term"> 1547a78e148bSantirez 1548*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.huge.allocated</code>" 1549a78e148bSantirez 1550a78e148bSantirez (<span class="type">size_t</span>) 1551a78e148bSantirez <code class="literal">r-</code> 1552a78e148bSantirez [<code class="option">--enable-stats</code>] 1553*5268379eSantirez </span></dt><dd><p>Number of bytes currently allocated by huge objects. 1554*5268379eSantirez </p></dd><dt><a name="stats.arenas.i.huge.nmalloc"></a><span class="term"> 1555*5268379eSantirez 1556*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.huge.nmalloc</code>" 1557*5268379eSantirez 1558*5268379eSantirez (<span class="type">uint64_t</span>) 1559*5268379eSantirez <code class="literal">r-</code> 1560*5268379eSantirez [<code class="option">--enable-stats</code>] 1561*5268379eSantirez </span></dt><dd><p>Cumulative number of huge allocation requests served 1562*5268379eSantirez directly by the arena.</p></dd><dt><a name="stats.arenas.i.huge.ndalloc"></a><span class="term"> 1563*5268379eSantirez 1564*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.huge.ndalloc</code>" 1565*5268379eSantirez 1566*5268379eSantirez (<span class="type">uint64_t</span>) 1567*5268379eSantirez <code class="literal">r-</code> 1568*5268379eSantirez [<code class="option">--enable-stats</code>] 1569*5268379eSantirez </span></dt><dd><p>Cumulative number of huge deallocation requests served 1570*5268379eSantirez directly by the arena.</p></dd><dt><a name="stats.arenas.i.huge.nrequests"></a><span class="term"> 1571*5268379eSantirez 1572*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.huge.nrequests</code>" 1573*5268379eSantirez 1574*5268379eSantirez (<span class="type">uint64_t</span>) 1575*5268379eSantirez <code class="literal">r-</code> 1576*5268379eSantirez [<code class="option">--enable-stats</code>] 1577*5268379eSantirez </span></dt><dd><p>Cumulative number of huge allocation requests. 1578*5268379eSantirez </p></dd><dt><a name="stats.arenas.i.bins.j.nmalloc"></a><span class="term"> 1579a78e148bSantirez 1580a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.nmalloc</code>" 1581a78e148bSantirez 1582a78e148bSantirez (<span class="type">uint64_t</span>) 1583a78e148bSantirez <code class="literal">r-</code> 1584a78e148bSantirez [<code class="option">--enable-stats</code>] 1585a78e148bSantirez </span></dt><dd><p>Cumulative number of allocations served by bin. 1586fceef8e0Santirez </p></dd><dt><a name="stats.arenas.i.bins.j.ndalloc"></a><span class="term"> 1587a78e148bSantirez 1588a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.ndalloc</code>" 1589a78e148bSantirez 1590a78e148bSantirez (<span class="type">uint64_t</span>) 1591a78e148bSantirez <code class="literal">r-</code> 1592a78e148bSantirez [<code class="option">--enable-stats</code>] 1593a78e148bSantirez </span></dt><dd><p>Cumulative number of allocations returned to bin. 1594fceef8e0Santirez </p></dd><dt><a name="stats.arenas.i.bins.j.nrequests"></a><span class="term"> 1595a78e148bSantirez 1596a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.nrequests</code>" 1597a78e148bSantirez 1598a78e148bSantirez (<span class="type">uint64_t</span>) 1599a78e148bSantirez <code class="literal">r-</code> 1600a78e148bSantirez [<code class="option">--enable-stats</code>] 1601a78e148bSantirez </span></dt><dd><p>Cumulative number of allocation 1602*5268379eSantirez requests.</p></dd><dt><a name="stats.arenas.i.bins.j.curregs"></a><span class="term"> 1603*5268379eSantirez 1604*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.curregs</code>" 1605*5268379eSantirez 1606*5268379eSantirez (<span class="type">size_t</span>) 1607*5268379eSantirez <code class="literal">r-</code> 1608*5268379eSantirez [<code class="option">--enable-stats</code>] 1609*5268379eSantirez </span></dt><dd><p>Current number of regions for this size 1610*5268379eSantirez class.</p></dd><dt><a name="stats.arenas.i.bins.j.nfills"></a><span class="term"> 1611a78e148bSantirez 1612a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.nfills</code>" 1613a78e148bSantirez 1614a78e148bSantirez (<span class="type">uint64_t</span>) 1615a78e148bSantirez <code class="literal">r-</code> 1616a78e148bSantirez [<code class="option">--enable-stats</code> <code class="option">--enable-tcache</code>] 1617fceef8e0Santirez </span></dt><dd><p>Cumulative number of tcache fills.</p></dd><dt><a name="stats.arenas.i.bins.j.nflushes"></a><span class="term"> 1618a78e148bSantirez 1619a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.nflushes</code>" 1620a78e148bSantirez 1621a78e148bSantirez (<span class="type">uint64_t</span>) 1622a78e148bSantirez <code class="literal">r-</code> 1623a78e148bSantirez [<code class="option">--enable-stats</code> <code class="option">--enable-tcache</code>] 1624fceef8e0Santirez </span></dt><dd><p>Cumulative number of tcache flushes.</p></dd><dt><a name="stats.arenas.i.bins.j.nruns"></a><span class="term"> 1625a78e148bSantirez 1626a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.nruns</code>" 1627a78e148bSantirez 1628a78e148bSantirez (<span class="type">uint64_t</span>) 1629a78e148bSantirez <code class="literal">r-</code> 1630a78e148bSantirez [<code class="option">--enable-stats</code>] 1631fceef8e0Santirez </span></dt><dd><p>Cumulative number of runs created.</p></dd><dt><a name="stats.arenas.i.bins.j.nreruns"></a><span class="term"> 1632a78e148bSantirez 1633a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.nreruns</code>" 1634a78e148bSantirez 1635a78e148bSantirez (<span class="type">uint64_t</span>) 1636a78e148bSantirez <code class="literal">r-</code> 1637a78e148bSantirez [<code class="option">--enable-stats</code>] 1638a78e148bSantirez </span></dt><dd><p>Cumulative number of times the current run from which 1639fceef8e0Santirez to allocate changed.</p></dd><dt><a name="stats.arenas.i.bins.j.curruns"></a><span class="term"> 1640a78e148bSantirez 1641a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.bins.<j>.curruns</code>" 1642a78e148bSantirez 1643a78e148bSantirez (<span class="type">size_t</span>) 1644a78e148bSantirez <code class="literal">r-</code> 1645a78e148bSantirez [<code class="option">--enable-stats</code>] 1646fceef8e0Santirez </span></dt><dd><p>Current number of runs.</p></dd><dt><a name="stats.arenas.i.lruns.j.nmalloc"></a><span class="term"> 1647a78e148bSantirez 1648a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.lruns.<j>.nmalloc</code>" 1649a78e148bSantirez 1650a78e148bSantirez (<span class="type">uint64_t</span>) 1651a78e148bSantirez <code class="literal">r-</code> 1652a78e148bSantirez [<code class="option">--enable-stats</code>] 1653a78e148bSantirez </span></dt><dd><p>Cumulative number of allocation requests for this size 1654fceef8e0Santirez class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.lruns.j.ndalloc"></a><span class="term"> 1655a78e148bSantirez 1656a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.lruns.<j>.ndalloc</code>" 1657a78e148bSantirez 1658a78e148bSantirez (<span class="type">uint64_t</span>) 1659a78e148bSantirez <code class="literal">r-</code> 1660a78e148bSantirez [<code class="option">--enable-stats</code>] 1661a78e148bSantirez </span></dt><dd><p>Cumulative number of deallocation requests for this 1662fceef8e0Santirez size class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.lruns.j.nrequests"></a><span class="term"> 1663a78e148bSantirez 1664a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.lruns.<j>.nrequests</code>" 1665a78e148bSantirez 1666a78e148bSantirez (<span class="type">uint64_t</span>) 1667a78e148bSantirez <code class="literal">r-</code> 1668a78e148bSantirez [<code class="option">--enable-stats</code>] 1669a78e148bSantirez </span></dt><dd><p>Cumulative number of allocation requests for this size 1670fceef8e0Santirez class.</p></dd><dt><a name="stats.arenas.i.lruns.j.curruns"></a><span class="term"> 1671a78e148bSantirez 1672a78e148bSantirez "<code class="mallctl">stats.arenas.<i>.lruns.<j>.curruns</code>" 1673a78e148bSantirez 1674a78e148bSantirez (<span class="type">size_t</span>) 1675a78e148bSantirez <code class="literal">r-</code> 1676a78e148bSantirez [<code class="option">--enable-stats</code>] 1677a78e148bSantirez </span></dt><dd><p>Current number of runs for this size class. 1678*5268379eSantirez </p></dd><dt><a name="stats.arenas.i.hchunks.j.nmalloc"></a><span class="term"> 1679*5268379eSantirez 1680*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.hchunks.<j>.nmalloc</code>" 1681*5268379eSantirez 1682*5268379eSantirez (<span class="type">uint64_t</span>) 1683*5268379eSantirez <code class="literal">r-</code> 1684*5268379eSantirez [<code class="option">--enable-stats</code>] 1685*5268379eSantirez </span></dt><dd><p>Cumulative number of allocation requests for this size 1686*5268379eSantirez class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.hchunks.j.ndalloc"></a><span class="term"> 1687*5268379eSantirez 1688*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.hchunks.<j>.ndalloc</code>" 1689*5268379eSantirez 1690*5268379eSantirez (<span class="type">uint64_t</span>) 1691*5268379eSantirez <code class="literal">r-</code> 1692*5268379eSantirez [<code class="option">--enable-stats</code>] 1693*5268379eSantirez </span></dt><dd><p>Cumulative number of deallocation requests for this 1694*5268379eSantirez size class served directly by the arena.</p></dd><dt><a name="stats.arenas.i.hchunks.j.nrequests"></a><span class="term"> 1695*5268379eSantirez 1696*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.hchunks.<j>.nrequests</code>" 1697*5268379eSantirez 1698*5268379eSantirez (<span class="type">uint64_t</span>) 1699*5268379eSantirez <code class="literal">r-</code> 1700*5268379eSantirez [<code class="option">--enable-stats</code>] 1701*5268379eSantirez </span></dt><dd><p>Cumulative number of allocation requests for this size 1702*5268379eSantirez class.</p></dd><dt><a name="stats.arenas.i.hchunks.j.curhchunks"></a><span class="term"> 1703*5268379eSantirez 1704*5268379eSantirez "<code class="mallctl">stats.arenas.<i>.hchunks.<j>.curhchunks</code>" 1705*5268379eSantirez 1706*5268379eSantirez (<span class="type">size_t</span>) 1707*5268379eSantirez <code class="literal">r-</code> 1708*5268379eSantirez [<code class="option">--enable-stats</code>] 1709*5268379eSantirez </span></dt><dd><p>Current number of huge allocations for this size class. 1710fceef8e0Santirez </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 1711a78e148bSantirez the <code class="option">--enable-debug</code> and <code class="option">--enable-fill</code> 1712a78e148bSantirez options, and recompile the program with suitable options and symbols for 1713a78e148bSantirez debugger support. When so configured, jemalloc incorporates a wide variety 1714a78e148bSantirez of run-time assertions that catch application errors such as double-free, 1715a78e148bSantirez write-after-free, etc.</p><p>Programs often accidentally depend on “uninitialized” 1716a78e148bSantirez memory actually being filled with zero bytes. Junk filling 1717a78e148bSantirez (see the <a class="link" href="#opt.junk"> 1718a78e148bSantirez "<code class="mallctl">opt.junk</code>" 1719a78e148bSantirez </a> 1720a78e148bSantirez option) tends to expose such bugs in the form of obviously incorrect 1721a78e148bSantirez results and/or coredumps. Conversely, zero 1722a78e148bSantirez filling (see the <a class="link" href="#opt.zero"> 1723a78e148bSantirez "<code class="mallctl">opt.zero</code>" 1724a78e148bSantirez </a> option) eliminates 1725a78e148bSantirez the symptoms of such bugs. Between these two options, it is usually 1726a78e148bSantirez possible to quickly detect, diagnose, and eliminate such bugs.</p><p>This implementation does not provide much detail about the problems 1727a78e148bSantirez it detects, because the performance impact for storing such information 1728ad4c0b41Santirez would be prohibitive. However, jemalloc does integrate with the most 1729ad4c0b41Santirez excellent <a class="ulink" href="http://valgrind.org/" target="_top">Valgrind</a> tool if the 1730fceef8e0Santirez <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 1731a78e148bSantirez error or warning condition, a message will be printed to file descriptor 1732a78e148bSantirez <code class="constant">STDERR_FILENO</code>. Errors will result in the process 1733a78e148bSantirez dumping core. If the <a class="link" href="#opt.abort"> 1734a78e148bSantirez "<code class="mallctl">opt.abort</code>" 1735a78e148bSantirez </a> option is set, most 1736a78e148bSantirez warnings are treated as errors.</p><p>The <code class="varname">malloc_message</code> variable allows the programmer 1737a78e148bSantirez to override the function which emits the text strings forming the errors 1738a78e148bSantirez and warnings if for some reason the <code class="constant">STDERR_FILENO</code> file 1739a78e148bSantirez descriptor is not suitable for this. 1740a78e148bSantirez <code class="function">malloc_message</code>(<em class="parameter"><code></code></em>) takes the 1741a78e148bSantirez <em class="parameter"><code>cbopaque</code></em> pointer argument that is 1742a78e148bSantirez <code class="constant">NULL</code> unless overridden by the arguments in a call to 1743a78e148bSantirez <code class="function">malloc_stats_print</code>(<em class="parameter"><code></code></em>), followed by a string 1744a78e148bSantirez pointer. Please note that doing anything which tries to allocate memory in 1745a78e148bSantirez this function is likely to result in a crash or deadlock.</p><p>All messages are prefixed by 1746*5268379eSantirez “<code class="computeroutput"><jemalloc>: </code>”.</p></div><div class="refsect1"><a name="return_values"></a><h2>RETURN VALUES</h2><div class="refsect2"><a name="idp46949776"></a><h3>Standard API</h3><p>The <code class="function">malloc</code>(<em class="parameter"><code></code></em>) and 1747a78e148bSantirez <code class="function">calloc</code>(<em class="parameter"><code></code></em>) functions return a pointer to the 1748a78e148bSantirez allocated memory if successful; otherwise a <code class="constant">NULL</code> 1749a78e148bSantirez pointer is returned and <code class="varname">errno</code> is set to 1750a78e148bSantirez <span class="errorname">ENOMEM</span>.</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function 1751a78e148bSantirez returns the value 0 if successful; otherwise it returns an error value. 1752a78e148bSantirez The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function will fail 1753a78e148bSantirez if: 1754fceef8e0Santirez </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 1755a78e148bSantirez not a power of 2 at least as large as 1756a78e148bSantirez <code class="code">sizeof(<span class="type">void *</span>)</code>. 1757a78e148bSantirez </p></dd><dt><span class="term"><span class="errorname">ENOMEM</span></span></dt><dd><p>Memory allocation error.</p></dd></dl></div><p> 1758ad4c0b41Santirez </p><p>The <code class="function">aligned_alloc</code>(<em class="parameter"><code></code></em>) function returns 1759ad4c0b41Santirez a pointer to the allocated memory if successful; otherwise a 1760ad4c0b41Santirez <code class="constant">NULL</code> pointer is returned and 1761ad4c0b41Santirez <code class="varname">errno</code> is set. The 1762ad4c0b41Santirez <code class="function">aligned_alloc</code>(<em class="parameter"><code></code></em>) function will fail if: 1763fceef8e0Santirez </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 1764ad4c0b41Santirez not a power of 2. 1765ad4c0b41Santirez </p></dd><dt><span class="term"><span class="errorname">ENOMEM</span></span></dt><dd><p>Memory allocation error.</p></dd></dl></div><p> 1766a78e148bSantirez </p><p>The <code class="function">realloc</code>(<em class="parameter"><code></code></em>) function returns a 1767a78e148bSantirez pointer, possibly identical to <em class="parameter"><code>ptr</code></em>, to the 1768a78e148bSantirez allocated memory if successful; otherwise a <code class="constant">NULL</code> 1769a78e148bSantirez pointer is returned, and <code class="varname">errno</code> is set to 1770a78e148bSantirez <span class="errorname">ENOMEM</span> if the error was the result of an 1771a78e148bSantirez allocation failure. The <code class="function">realloc</code>(<em class="parameter"><code></code></em>) 1772a78e148bSantirez function always leaves the original buffer intact when an error occurs. 1773a78e148bSantirez </p><p>The <code class="function">free</code>(<em class="parameter"><code></code></em>) function returns no 1774*5268379eSantirez value.</p></div><div class="refsect2"><a name="idp46974576"></a><h3>Non-standard API</h3><p>The <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) and 1775fceef8e0Santirez <code class="function">rallocx</code>(<em class="parameter"><code></code></em>) functions return a pointer to 1776fceef8e0Santirez the allocated memory if successful; otherwise a <code class="constant">NULL</code> 1777fceef8e0Santirez pointer is returned to indicate insufficient contiguous memory was 1778fceef8e0Santirez available to service the allocation request. </p><p>The <code class="function">xallocx</code>(<em class="parameter"><code></code></em>) function returns the 1779fceef8e0Santirez real size of the resulting resized allocation pointed to by 1780fceef8e0Santirez <em class="parameter"><code>ptr</code></em>, which is a value less than 1781fceef8e0Santirez <em class="parameter"><code>size</code></em> if the allocation could not be adequately 1782fceef8e0Santirez grown in place. </p><p>The <code class="function">sallocx</code>(<em class="parameter"><code></code></em>) function returns the 1783fceef8e0Santirez real size of the allocation pointed to by <em class="parameter"><code>ptr</code></em>. 1784fceef8e0Santirez </p><p>The <code class="function">nallocx</code>(<em class="parameter"><code></code></em>) returns the real size 1785fceef8e0Santirez that would result from a successful equivalent 1786fceef8e0Santirez <code class="function">mallocx</code>(<em class="parameter"><code></code></em>) function call, or zero if 1787fceef8e0Santirez insufficient memory is available to perform the size computation. </p><p>The <code class="function">mallctl</code>(<em class="parameter"><code></code></em>), 1788a78e148bSantirez <code class="function">mallctlnametomib</code>(<em class="parameter"><code></code></em>), and 1789a78e148bSantirez <code class="function">mallctlbymib</code>(<em class="parameter"><code></code></em>) functions return 0 on 1790a78e148bSantirez success; otherwise they return an error value. The functions will fail 1791a78e148bSantirez if: 1792fceef8e0Santirez </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 1793a78e148bSantirez <code class="constant">NULL</code>, and <em class="parameter"><code>newlen</code></em> is too 1794a78e148bSantirez large or too small. Alternatively, <em class="parameter"><code>*oldlenp</code></em> 1795a78e148bSantirez is too large or too small; in this case as much data as possible 1796fceef8e0Santirez 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 1797a78e148bSantirez <em class="parameter"><code>mib</code></em> specifies an unknown/invalid 1798a78e148bSantirez 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 1799a78e148bSantirez write read-only value.</p></dd><dt><span class="term"><span class="errorname">EAGAIN</span></span></dt><dd><p>A memory allocation failure 1800a78e148bSantirez 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 1801a78e148bSantirez not directly related to <code class="function">mallctl*</code>(<em class="parameter"><code></code></em>) 1802a78e148bSantirez read/write processing.</p></dd></dl></div><p> 1803fceef8e0Santirez </p><p>The <code class="function">malloc_usable_size</code>(<em class="parameter"><code></code></em>) function 1804fceef8e0Santirez returns the usable size of the allocation pointed to by 1805*5268379eSantirez <em class="parameter"><code>ptr</code></em>. </p></div></div><div class="refsect1"><a name="environment"></a><h2>ENVIRONMENT</h2><p>The following environment variable affects the execution of the 1806a78e148bSantirez allocation functions: 1807fceef8e0Santirez </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 1808a78e148bSantirez <code class="envar">MALLOC_CONF</code> is set, the characters it contains 1809a78e148bSantirez will be interpreted as options.</p></dd></dl></div><p> 1810fceef8e0Santirez </p></div><div class="refsect1"><a name="examples"></a><h2>EXAMPLES</h2><p>To dump core whenever a problem occurs: 1811a78e148bSantirez </p><pre class="screen">ln -s 'abort:true' /etc/malloc.conf</pre><p> 1812a78e148bSantirez </p><p>To specify in the source a chunk size that is 16 MiB: 1813a78e148bSantirez </p><pre class="programlisting"> 1814fceef8e0Santirezmalloc_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>, 1815a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">mmap</span>(2)</span>, 1816a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">sbrk</span>(2)</span>, 1817ad4c0b41Santirez <span class="citerefentry"><span class="refentrytitle">utrace</span>(2)</span>, 1818a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">alloca</span>(3)</span>, 1819a78e148bSantirez <span class="citerefentry"><span class="refentrytitle">atexit</span>(3)</span>, 1820fceef8e0Santirez <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>), 1821a78e148bSantirez <code class="function">calloc</code>(<em class="parameter"><code></code></em>), 1822a78e148bSantirez <code class="function">realloc</code>(<em class="parameter"><code></code></em>), and 1823a78e148bSantirez <code class="function">free</code>(<em class="parameter"><code></code></em>) functions conform to ISO/IEC 1824a78e148bSantirez 9899:1990 (“ISO C90”).</p><p>The <code class="function">posix_memalign</code>(<em class="parameter"><code></code></em>) function conforms 1825a78e148bSantirez to IEEE Std 1003.1-2001 (“POSIX.1”).</p></div></div></body></html> 1826