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