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