1<?xml version='1.0' encoding='UTF-8'?> 2<?xml-stylesheet type="text/xsl" 3 href="http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?> 4<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" 5 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [ 6]> 7 8<refentry> 9 <refentryinfo> 10 <title>User Manual</title> 11 <productname>jemalloc</productname> 12 <releaseinfo role="version">@jemalloc_version@</releaseinfo> 13 <authorgroup> 14 <author> 15 <firstname>Jason</firstname> 16 <surname>Evans</surname> 17 <personblurb>Author</personblurb> 18 </author> 19 </authorgroup> 20 </refentryinfo> 21 <refmeta> 22 <refentrytitle>JEMALLOC</refentrytitle> 23 <manvolnum>3</manvolnum> 24 </refmeta> 25 <refnamediv> 26 <refdescriptor>jemalloc</refdescriptor> 27 <refname>jemalloc</refname> 28 <!-- Each refname causes a man page file to be created. Only if this were 29 the system malloc(3) implementation would these files be appropriate. 30 <refname>malloc</refname> 31 <refname>calloc</refname> 32 <refname>posix_memalign</refname> 33 <refname>aligned_alloc</refname> 34 <refname>realloc</refname> 35 <refname>free</refname> 36 <refname>mallocx</refname> 37 <refname>rallocx</refname> 38 <refname>xallocx</refname> 39 <refname>sallocx</refname> 40 <refname>dallocx</refname> 41 <refname>nallocx</refname> 42 <refname>mallctl</refname> 43 <refname>mallctlnametomib</refname> 44 <refname>mallctlbymib</refname> 45 <refname>malloc_stats_print</refname> 46 <refname>malloc_usable_size</refname> 47 <refname>allocm</refname> 48 <refname>rallocm</refname> 49 <refname>sallocm</refname> 50 <refname>dallocm</refname> 51 <refname>nallocm</refname> 52 --> 53 <refpurpose>general purpose memory allocation functions</refpurpose> 54 </refnamediv> 55 <refsect1 id="library"> 56 <title>LIBRARY</title> 57 <para>This manual describes jemalloc @jemalloc_version@. More information 58 can be found at the <ulink 59 url="http://www.canonware.com/jemalloc/">jemalloc website</ulink>.</para> 60 </refsect1> 61 <refsynopsisdiv> 62 <title>SYNOPSIS</title> 63 <funcsynopsis> 64 <funcsynopsisinfo>#include <<filename class="headerfile">stdlib.h</filename>> 65#include <<filename class="headerfile">jemalloc/jemalloc.h</filename>></funcsynopsisinfo> 66 <refsect2> 67 <title>Standard API</title> 68 <funcprototype> 69 <funcdef>void *<function>malloc</function></funcdef> 70 <paramdef>size_t <parameter>size</parameter></paramdef> 71 </funcprototype> 72 <funcprototype> 73 <funcdef>void *<function>calloc</function></funcdef> 74 <paramdef>size_t <parameter>number</parameter></paramdef> 75 <paramdef>size_t <parameter>size</parameter></paramdef> 76 </funcprototype> 77 <funcprototype> 78 <funcdef>int <function>posix_memalign</function></funcdef> 79 <paramdef>void **<parameter>ptr</parameter></paramdef> 80 <paramdef>size_t <parameter>alignment</parameter></paramdef> 81 <paramdef>size_t <parameter>size</parameter></paramdef> 82 </funcprototype> 83 <funcprototype> 84 <funcdef>void *<function>aligned_alloc</function></funcdef> 85 <paramdef>size_t <parameter>alignment</parameter></paramdef> 86 <paramdef>size_t <parameter>size</parameter></paramdef> 87 </funcprototype> 88 <funcprototype> 89 <funcdef>void *<function>realloc</function></funcdef> 90 <paramdef>void *<parameter>ptr</parameter></paramdef> 91 <paramdef>size_t <parameter>size</parameter></paramdef> 92 </funcprototype> 93 <funcprototype> 94 <funcdef>void <function>free</function></funcdef> 95 <paramdef>void *<parameter>ptr</parameter></paramdef> 96 </funcprototype> 97 </refsect2> 98 <refsect2> 99 <title>Non-standard API</title> 100 <funcprototype> 101 <funcdef>void *<function>mallocx</function></funcdef> 102 <paramdef>size_t <parameter>size</parameter></paramdef> 103 <paramdef>int <parameter>flags</parameter></paramdef> 104 </funcprototype> 105 <funcprototype> 106 <funcdef>void *<function>rallocx</function></funcdef> 107 <paramdef>void *<parameter>ptr</parameter></paramdef> 108 <paramdef>size_t <parameter>size</parameter></paramdef> 109 <paramdef>int <parameter>flags</parameter></paramdef> 110 </funcprototype> 111 <funcprototype> 112 <funcdef>size_t <function>xallocx</function></funcdef> 113 <paramdef>void *<parameter>ptr</parameter></paramdef> 114 <paramdef>size_t <parameter>size</parameter></paramdef> 115 <paramdef>size_t <parameter>extra</parameter></paramdef> 116 <paramdef>int <parameter>flags</parameter></paramdef> 117 </funcprototype> 118 <funcprototype> 119 <funcdef>size_t <function>sallocx</function></funcdef> 120 <paramdef>void *<parameter>ptr</parameter></paramdef> 121 <paramdef>int <parameter>flags</parameter></paramdef> 122 </funcprototype> 123 <funcprototype> 124 <funcdef>void <function>dallocx</function></funcdef> 125 <paramdef>void *<parameter>ptr</parameter></paramdef> 126 <paramdef>int <parameter>flags</parameter></paramdef> 127 </funcprototype> 128 <funcprototype> 129 <funcdef>size_t <function>nallocx</function></funcdef> 130 <paramdef>size_t <parameter>size</parameter></paramdef> 131 <paramdef>int <parameter>flags</parameter></paramdef> 132 </funcprototype> 133 <funcprototype> 134 <funcdef>int <function>mallctl</function></funcdef> 135 <paramdef>const char *<parameter>name</parameter></paramdef> 136 <paramdef>void *<parameter>oldp</parameter></paramdef> 137 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 138 <paramdef>void *<parameter>newp</parameter></paramdef> 139 <paramdef>size_t <parameter>newlen</parameter></paramdef> 140 </funcprototype> 141 <funcprototype> 142 <funcdef>int <function>mallctlnametomib</function></funcdef> 143 <paramdef>const char *<parameter>name</parameter></paramdef> 144 <paramdef>size_t *<parameter>mibp</parameter></paramdef> 145 <paramdef>size_t *<parameter>miblenp</parameter></paramdef> 146 </funcprototype> 147 <funcprototype> 148 <funcdef>int <function>mallctlbymib</function></funcdef> 149 <paramdef>const size_t *<parameter>mib</parameter></paramdef> 150 <paramdef>size_t <parameter>miblen</parameter></paramdef> 151 <paramdef>void *<parameter>oldp</parameter></paramdef> 152 <paramdef>size_t *<parameter>oldlenp</parameter></paramdef> 153 <paramdef>void *<parameter>newp</parameter></paramdef> 154 <paramdef>size_t <parameter>newlen</parameter></paramdef> 155 </funcprototype> 156 <funcprototype> 157 <funcdef>void <function>malloc_stats_print</function></funcdef> 158 <paramdef>void <parameter>(*write_cb)</parameter> 159 <funcparams>void *, const char *</funcparams> 160 </paramdef> 161 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 162 <paramdef>const char *<parameter>opts</parameter></paramdef> 163 </funcprototype> 164 <funcprototype> 165 <funcdef>size_t <function>malloc_usable_size</function></funcdef> 166 <paramdef>const void *<parameter>ptr</parameter></paramdef> 167 </funcprototype> 168 <funcprototype> 169 <funcdef>void <function>(*malloc_message)</function></funcdef> 170 <paramdef>void *<parameter>cbopaque</parameter></paramdef> 171 <paramdef>const char *<parameter>s</parameter></paramdef> 172 </funcprototype> 173 <para><type>const char *</type><varname>malloc_conf</varname>;</para> 174 </refsect2> 175 <refsect2> 176 <title>Experimental API</title> 177 <funcprototype> 178 <funcdef>int <function>allocm</function></funcdef> 179 <paramdef>void **<parameter>ptr</parameter></paramdef> 180 <paramdef>size_t *<parameter>rsize</parameter></paramdef> 181 <paramdef>size_t <parameter>size</parameter></paramdef> 182 <paramdef>int <parameter>flags</parameter></paramdef> 183 </funcprototype> 184 <funcprototype> 185 <funcdef>int <function>rallocm</function></funcdef> 186 <paramdef>void **<parameter>ptr</parameter></paramdef> 187 <paramdef>size_t *<parameter>rsize</parameter></paramdef> 188 <paramdef>size_t <parameter>size</parameter></paramdef> 189 <paramdef>size_t <parameter>extra</parameter></paramdef> 190 <paramdef>int <parameter>flags</parameter></paramdef> 191 </funcprototype> 192 <funcprototype> 193 <funcdef>int <function>sallocm</function></funcdef> 194 <paramdef>const void *<parameter>ptr</parameter></paramdef> 195 <paramdef>size_t *<parameter>rsize</parameter></paramdef> 196 <paramdef>int <parameter>flags</parameter></paramdef> 197 </funcprototype> 198 <funcprototype> 199 <funcdef>int <function>dallocm</function></funcdef> 200 <paramdef>void *<parameter>ptr</parameter></paramdef> 201 <paramdef>int <parameter>flags</parameter></paramdef> 202 </funcprototype> 203 <funcprototype> 204 <funcdef>int <function>nallocm</function></funcdef> 205 <paramdef>size_t *<parameter>rsize</parameter></paramdef> 206 <paramdef>size_t <parameter>size</parameter></paramdef> 207 <paramdef>int <parameter>flags</parameter></paramdef> 208 </funcprototype> 209 </refsect2> 210 </funcsynopsis> 211 </refsynopsisdiv> 212 <refsect1 id="description"> 213 <title>DESCRIPTION</title> 214 <refsect2> 215 <title>Standard API</title> 216 217 <para>The <function>malloc<parameter/></function> function allocates 218 <parameter>size</parameter> bytes of uninitialized memory. The allocated 219 space is suitably aligned (after possible pointer coercion) for storage 220 of any type of object.</para> 221 222 <para>The <function>calloc<parameter/></function> function allocates 223 space for <parameter>number</parameter> objects, each 224 <parameter>size</parameter> bytes in length. The result is identical to 225 calling <function>malloc<parameter/></function> with an argument of 226 <parameter>number</parameter> * <parameter>size</parameter>, with the 227 exception that the allocated memory is explicitly initialized to zero 228 bytes.</para> 229 230 <para>The <function>posix_memalign<parameter/></function> function 231 allocates <parameter>size</parameter> bytes of memory such that the 232 allocation's base address is an even multiple of 233 <parameter>alignment</parameter>, and returns the allocation in the value 234 pointed to by <parameter>ptr</parameter>. The requested 235 <parameter>alignment</parameter> must be a power of 2 at least as large 236 as <code language="C">sizeof(<type>void *</type>)</code>.</para> 237 238 <para>The <function>aligned_alloc<parameter/></function> function 239 allocates <parameter>size</parameter> bytes of memory such that the 240 allocation's base address is an even multiple of 241 <parameter>alignment</parameter>. The requested 242 <parameter>alignment</parameter> must be a power of 2. Behavior is 243 undefined if <parameter>size</parameter> is not an integral multiple of 244 <parameter>alignment</parameter>.</para> 245 246 <para>The <function>realloc<parameter/></function> function changes the 247 size of the previously allocated memory referenced by 248 <parameter>ptr</parameter> to <parameter>size</parameter> bytes. The 249 contents of the memory are unchanged up to the lesser of the new and old 250 sizes. If the new size is larger, the contents of the newly allocated 251 portion of the memory are undefined. Upon success, the memory referenced 252 by <parameter>ptr</parameter> is freed and a pointer to the newly 253 allocated memory is returned. Note that 254 <function>realloc<parameter/></function> may move the memory allocation, 255 resulting in a different return value than <parameter>ptr</parameter>. 256 If <parameter>ptr</parameter> is <constant>NULL</constant>, the 257 <function>realloc<parameter/></function> function behaves identically to 258 <function>malloc<parameter/></function> for the specified size.</para> 259 260 <para>The <function>free<parameter/></function> function causes the 261 allocated memory referenced by <parameter>ptr</parameter> to be made 262 available for future allocations. If <parameter>ptr</parameter> is 263 <constant>NULL</constant>, no action occurs.</para> 264 </refsect2> 265 <refsect2> 266 <title>Non-standard API</title> 267 <para>The <function>mallocx<parameter/></function>, 268 <function>rallocx<parameter/></function>, 269 <function>xallocx<parameter/></function>, 270 <function>sallocx<parameter/></function>, 271 <function>dallocx<parameter/></function>, and 272 <function>nallocx<parameter/></function> functions all have a 273 <parameter>flags</parameter> argument that can be used to specify 274 options. The functions only check the options that are contextually 275 relevant. Use bitwise or (<code language="C">|</code>) operations to 276 specify one or more of the following: 277 <variablelist> 278 <varlistentry> 279 <term><constant>MALLOCX_LG_ALIGN(<parameter>la</parameter>) 280 </constant></term> 281 282 <listitem><para>Align the memory allocation to start at an address 283 that is a multiple of <code language="C">(1 << 284 <parameter>la</parameter>)</code>. This macro does not validate 285 that <parameter>la</parameter> is within the valid 286 range.</para></listitem> 287 </varlistentry> 288 <varlistentry> 289 <term><constant>MALLOCX_ALIGN(<parameter>a</parameter>) 290 </constant></term> 291 292 <listitem><para>Align the memory allocation to start at an address 293 that is a multiple of <parameter>a</parameter>, where 294 <parameter>a</parameter> is a power of two. This macro does not 295 validate that <parameter>a</parameter> is a power of 2. 296 </para></listitem> 297 </varlistentry> 298 <varlistentry> 299 <term><constant>MALLOCX_ZERO</constant></term> 300 301 <listitem><para>Initialize newly allocated memory to contain zero 302 bytes. In the growing reallocation case, the real size prior to 303 reallocation defines the boundary between untouched bytes and those 304 that are initialized to contain zero bytes. If this macro is 305 absent, newly allocated memory is uninitialized.</para></listitem> 306 </varlistentry> 307 <varlistentry> 308 <term><constant>MALLOCX_ARENA(<parameter>a</parameter>) 309 </constant></term> 310 311 <listitem><para>Use the arena specified by the index 312 <parameter>a</parameter> (and by necessity bypass the thread 313 cache). This macro has no effect for huge regions, nor for regions 314 that were allocated via an arena other than the one specified. 315 This macro does not validate that <parameter>a</parameter> 316 specifies an arena index in the valid range.</para></listitem> 317 </varlistentry> 318 </variablelist> 319 </para> 320 321 <para>The <function>mallocx<parameter/></function> function allocates at 322 least <parameter>size</parameter> bytes of memory, and returns a pointer 323 to the base address of the allocation. Behavior is undefined if 324 <parameter>size</parameter> is <constant>0</constant>, or if request size 325 overflows due to size class and/or alignment constraints.</para> 326 327 <para>The <function>rallocx<parameter/></function> function resizes the 328 allocation at <parameter>ptr</parameter> to be at least 329 <parameter>size</parameter> bytes, and returns a pointer to the base 330 address of the resulting allocation, which may or may not have moved from 331 its original location. Behavior is undefined if 332 <parameter>size</parameter> is <constant>0</constant>, or if request size 333 overflows due to size class and/or alignment constraints.</para> 334 335 <para>The <function>xallocx<parameter/></function> function resizes the 336 allocation at <parameter>ptr</parameter> in place to be at least 337 <parameter>size</parameter> bytes, and returns the real size of the 338 allocation. If <parameter>extra</parameter> is non-zero, an attempt is 339 made to resize the allocation to be at least <code 340 language="C">(<parameter>size</parameter> + 341 <parameter>extra</parameter>)</code> bytes, though inability to allocate 342 the extra byte(s) will not by itself result in failure to resize. 343 Behavior is undefined if <parameter>size</parameter> is 344 <constant>0</constant>, or if <code 345 language="C">(<parameter>size</parameter> + <parameter>extra</parameter> 346 > <constant>SIZE_T_MAX</constant>)</code>.</para> 347 348 <para>The <function>sallocx<parameter/></function> function returns the 349 real size of the allocation at <parameter>ptr</parameter>.</para> 350 351 <para>The <function>dallocx<parameter/></function> function causes the 352 memory referenced by <parameter>ptr</parameter> to be made available for 353 future allocations.</para> 354 355 <para>The <function>nallocx<parameter/></function> function allocates no 356 memory, but it performs the same size computation as the 357 <function>mallocx<parameter/></function> function, and returns the real 358 size of the allocation that would result from the equivalent 359 <function>mallocx<parameter/></function> function call. Behavior is 360 undefined if <parameter>size</parameter> is <constant>0</constant>, or if 361 request size overflows due to size class and/or alignment 362 constraints.</para> 363 364 <para>The <function>mallctl<parameter/></function> function provides a 365 general interface for introspecting the memory allocator, as well as 366 setting modifiable parameters and triggering actions. The 367 period-separated <parameter>name</parameter> argument specifies a 368 location in a tree-structured namespace; see the <xref 369 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for 370 documentation on the tree contents. To read a value, pass a pointer via 371 <parameter>oldp</parameter> to adequate space to contain the value, and a 372 pointer to its length via <parameter>oldlenp</parameter>; otherwise pass 373 <constant>NULL</constant> and <constant>NULL</constant>. Similarly, to 374 write a value, pass a pointer to the value via 375 <parameter>newp</parameter>, and its length via 376 <parameter>newlen</parameter>; otherwise pass <constant>NULL</constant> 377 and <constant>0</constant>.</para> 378 379 <para>The <function>mallctlnametomib<parameter/></function> function 380 provides a way to avoid repeated name lookups for applications that 381 repeatedly query the same portion of the namespace, by translating a name 382 to a “Management Information Base” (MIB) that can be passed 383 repeatedly to <function>mallctlbymib<parameter/></function>. Upon 384 successful return from <function>mallctlnametomib<parameter/></function>, 385 <parameter>mibp</parameter> contains an array of 386 <parameter>*miblenp</parameter> integers, where 387 <parameter>*miblenp</parameter> is the lesser of the number of components 388 in <parameter>name</parameter> and the input value of 389 <parameter>*miblenp</parameter>. Thus it is possible to pass a 390 <parameter>*miblenp</parameter> that is smaller than the number of 391 period-separated name components, which results in a partial MIB that can 392 be used as the basis for constructing a complete MIB. For name 393 components that are integers (e.g. the 2 in 394 <link 395 linkend="arenas.bin.i.size"><mallctl>arenas.bin.2.size</mallctl></link>), 396 the corresponding MIB component will always be that integer. Therefore, 397 it is legitimate to construct code like the following: <programlisting 398 language="C"><![CDATA[ 399unsigned nbins, i; 400size_t mib[4]; 401size_t len, miblen; 402 403len = sizeof(nbins); 404mallctl("arenas.nbins", &nbins, &len, NULL, 0); 405 406miblen = 4; 407mallctlnametomib("arenas.bin.0.size", mib, &miblen); 408for (i = 0; i < nbins; i++) { 409 size_t bin_size; 410 411 mib[2] = i; 412 len = sizeof(bin_size); 413 mallctlbymib(mib, miblen, &bin_size, &len, NULL, 0); 414 /* Do something with bin_size... */ 415}]]></programlisting></para> 416 417 <para>The <function>malloc_stats_print<parameter/></function> function 418 writes human-readable summary statistics via the 419 <parameter>write_cb</parameter> callback function pointer and 420 <parameter>cbopaque</parameter> data passed to 421 <parameter>write_cb</parameter>, or 422 <function>malloc_message<parameter/></function> if 423 <parameter>write_cb</parameter> is <constant>NULL</constant>. This 424 function can be called repeatedly. General information that never 425 changes during execution can be omitted by specifying "g" as a character 426 within the <parameter>opts</parameter> string. Note that 427 <function>malloc_message<parameter/></function> uses the 428 <function>mallctl*<parameter/></function> functions internally, so 429 inconsistent statistics can be reported if multiple threads use these 430 functions simultaneously. If <option>--enable-stats</option> is 431 specified during configuration, “m” and “a” can 432 be specified to omit merged arena and per arena statistics, respectively; 433 “b” and “l” can be specified to omit per size 434 class statistics for bins and large objects, respectively. Unrecognized 435 characters are silently ignored. Note that thread caching may prevent 436 some statistics from being completely up to date, since extra locking 437 would be required to merge counters that track thread cache operations. 438 </para> 439 440 <para>The <function>malloc_usable_size<parameter/></function> function 441 returns the usable size of the allocation pointed to by 442 <parameter>ptr</parameter>. The return value may be larger than the size 443 that was requested during allocation. The 444 <function>malloc_usable_size<parameter/></function> function is not a 445 mechanism for in-place <function>realloc<parameter/></function>; rather 446 it is provided solely as a tool for introspection purposes. Any 447 discrepancy between the requested allocation size and the size reported 448 by <function>malloc_usable_size<parameter/></function> should not be 449 depended on, since such behavior is entirely implementation-dependent. 450 </para> 451 </refsect2> 452 <refsect2> 453 <title>Experimental API</title> 454 <para>The experimental API is subject to change or removal without regard 455 for backward compatibility. If <option>--disable-experimental</option> 456 is specified during configuration, the experimental API is 457 omitted.</para> 458 459 <para>The <function>allocm<parameter/></function>, 460 <function>rallocm<parameter/></function>, 461 <function>sallocm<parameter/></function>, 462 <function>dallocm<parameter/></function>, and 463 <function>nallocm<parameter/></function> functions all have a 464 <parameter>flags</parameter> argument that can be used to specify 465 options. The functions only check the options that are contextually 466 relevant. Use bitwise or (<code language="C">|</code>) operations to 467 specify one or more of the following: 468 <variablelist> 469 <varlistentry> 470 <term><constant>ALLOCM_LG_ALIGN(<parameter>la</parameter>) 471 </constant></term> 472 473 <listitem><para>Align the memory allocation to start at an address 474 that is a multiple of <code language="C">(1 << 475 <parameter>la</parameter>)</code>. This macro does not validate 476 that <parameter>la</parameter> is within the valid 477 range.</para></listitem> 478 </varlistentry> 479 <varlistentry> 480 <term><constant>ALLOCM_ALIGN(<parameter>a</parameter>) 481 </constant></term> 482 483 <listitem><para>Align the memory allocation to start at an address 484 that is a multiple of <parameter>a</parameter>, where 485 <parameter>a</parameter> is a power of two. This macro does not 486 validate that <parameter>a</parameter> is a power of 2. 487 </para></listitem> 488 </varlistentry> 489 <varlistentry> 490 <term><constant>ALLOCM_ZERO</constant></term> 491 492 <listitem><para>Initialize newly allocated memory to contain zero 493 bytes. In the growing reallocation case, the real size prior to 494 reallocation defines the boundary between untouched bytes and those 495 that are initialized to contain zero bytes. If this macro is 496 absent, newly allocated memory is uninitialized.</para></listitem> 497 </varlistentry> 498 <varlistentry> 499 <term><constant>ALLOCM_NO_MOVE</constant></term> 500 501 <listitem><para>For reallocation, fail rather than moving the 502 object. This constraint can apply to both growth and 503 shrinkage.</para></listitem> 504 </varlistentry> 505 <varlistentry> 506 <term><constant>ALLOCM_ARENA(<parameter>a</parameter>) 507 </constant></term> 508 509 <listitem><para>Use the arena specified by the index 510 <parameter>a</parameter> (and by necessity bypass the thread 511 cache). This macro has no effect for huge regions, nor for regions 512 that were allocated via an arena other than the one specified. 513 This macro does not validate that <parameter>a</parameter> 514 specifies an arena index in the valid range.</para></listitem> 515 </varlistentry> 516 </variablelist> 517 </para> 518 519 <para>The <function>allocm<parameter/></function> function allocates at 520 least <parameter>size</parameter> bytes of memory, sets 521 <parameter>*ptr</parameter> to the base address of the allocation, and 522 sets <parameter>*rsize</parameter> to the real size of the allocation if 523 <parameter>rsize</parameter> is not <constant>NULL</constant>. Behavior 524 is undefined if <parameter>size</parameter> is <constant>0</constant>, or 525 if request size overflows due to size class and/or alignment 526 constraints.</para> 527 528 <para>The <function>rallocm<parameter/></function> function resizes the 529 allocation at <parameter>*ptr</parameter> to be at least 530 <parameter>size</parameter> bytes, sets <parameter>*ptr</parameter> to 531 the base address of the allocation if it moved, and sets 532 <parameter>*rsize</parameter> to the real size of the allocation if 533 <parameter>rsize</parameter> is not <constant>NULL</constant>. If 534 <parameter>extra</parameter> is non-zero, an attempt is made to resize 535 the allocation to be at least <code 536 language="C">(<parameter>size</parameter> + 537 <parameter>extra</parameter>)</code> bytes, though inability to allocate 538 the extra byte(s) will not by itself result in failure. Behavior is 539 undefined if <parameter>size</parameter> is <constant>0</constant>, if 540 request size overflows due to size class and/or alignment constraints, or 541 if <code language="C">(<parameter>size</parameter> + 542 <parameter>extra</parameter> > 543 <constant>SIZE_T_MAX</constant>)</code>.</para> 544 545 <para>The <function>sallocm<parameter/></function> function sets 546 <parameter>*rsize</parameter> to the real size of the allocation.</para> 547 548 <para>The <function>dallocm<parameter/></function> function causes the 549 memory referenced by <parameter>ptr</parameter> to be made available for 550 future allocations.</para> 551 552 <para>The <function>nallocm<parameter/></function> function allocates no 553 memory, but it performs the same size computation as the 554 <function>allocm<parameter/></function> function, and if 555 <parameter>rsize</parameter> is not <constant>NULL</constant> it sets 556 <parameter>*rsize</parameter> to the real size of the allocation that 557 would result from the equivalent <function>allocm<parameter/></function> 558 function call. Behavior is undefined if <parameter>size</parameter> is 559 <constant>0</constant>, or if request size overflows due to size class 560 and/or alignment constraints.</para> 561 </refsect2> 562 </refsect1> 563 <refsect1 id="tuning"> 564 <title>TUNING</title> 565 <para>Once, when the first call is made to one of the memory allocation 566 routines, the allocator initializes its internals based in part on various 567 options that can be specified at compile- or run-time.</para> 568 569 <para>The string pointed to by the global variable 570 <varname>malloc_conf</varname>, the “name” of the file 571 referenced by the symbolic link named <filename 572 class="symlink">/etc/malloc.conf</filename>, and the value of the 573 environment variable <envar>MALLOC_CONF</envar>, will be interpreted, in 574 that order, from left to right as options. Note that 575 <varname>malloc_conf</varname> may be read before 576 <function>main<parameter/></function> is entered, so the declaration of 577 <varname>malloc_conf</varname> should specify an initializer that contains 578 the final value to be read by jemalloc. <varname>malloc_conf</varname> is 579 a compile-time setting, whereas <filename 580 class="symlink">/etc/malloc.conf</filename> and <envar>MALLOC_CONF</envar> 581 can be safely set any time prior to program invocation.</para> 582 583 <para>An options string is a comma-separated list of option:value pairs. 584 There is one key corresponding to each <link 585 linkend="opt.abort"><mallctl>opt.*</mallctl></link> mallctl (see the <xref 586 linkend="mallctl_namespace" xrefstyle="template:%t"/> section for options 587 documentation). For example, <literal>abort:true,narenas:1</literal> sets 588 the <link linkend="opt.abort"><mallctl>opt.abort</mallctl></link> and <link 589 linkend="opt.narenas"><mallctl>opt.narenas</mallctl></link> options. Some 590 options have boolean values (true/false), others have integer values (base 591 8, 10, or 16, depending on prefix), and yet others have raw string 592 values.</para> 593 </refsect1> 594 <refsect1 id="implementation_notes"> 595 <title>IMPLEMENTATION NOTES</title> 596 <para>Traditionally, allocators have used 597 <citerefentry><refentrytitle>sbrk</refentrytitle> 598 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is 599 suboptimal for several reasons, including race conditions, increased 600 fragmentation, and artificial limitations on maximum usable memory. If 601 <option>--enable-dss</option> is specified during configuration, this 602 allocator uses both <citerefentry><refentrytitle>mmap</refentrytitle> 603 <manvolnum>2</manvolnum></citerefentry> and 604 <citerefentry><refentrytitle>sbrk</refentrytitle> 605 <manvolnum>2</manvolnum></citerefentry>, in that order of preference; 606 otherwise only <citerefentry><refentrytitle>mmap</refentrytitle> 607 <manvolnum>2</manvolnum></citerefentry> is used.</para> 608 609 <para>This allocator uses multiple arenas in order to reduce lock 610 contention for threaded programs on multi-processor systems. This works 611 well with regard to threading scalability, but incurs some costs. There is 612 a small fixed per-arena overhead, and additionally, arenas manage memory 613 completely independently of each other, which means a small fixed increase 614 in overall memory fragmentation. These overheads are not generally an 615 issue, given the number of arenas normally used. Note that using 616 substantially more arenas than the default is not likely to improve 617 performance, mainly due to reduced cache performance. However, it may make 618 sense to reduce the number of arenas if an application does not make much 619 use of the allocation functions.</para> 620 621 <para>In addition to multiple arenas, unless 622 <option>--disable-tcache</option> is specified during configuration, this 623 allocator supports thread-specific caching for small and large objects, in 624 order to make it possible to completely avoid synchronization for most 625 allocation requests. Such caching allows very fast allocation in the 626 common case, but it increases memory usage and fragmentation, since a 627 bounded number of objects can remain allocated in each thread cache.</para> 628 629 <para>Memory is conceptually broken into equal-sized chunks, where the 630 chunk size is a power of two that is greater than the page size. Chunks 631 are always aligned to multiples of the chunk size. This alignment makes it 632 possible to find metadata for user objects very quickly.</para> 633 634 <para>User objects are broken into three categories according to size: 635 small, large, and huge. Small objects are smaller than one page. Large 636 objects are smaller than the chunk size. Huge objects are a multiple of 637 the chunk size. Small and large objects are managed by arenas; huge 638 objects are managed separately in a single data structure that is shared by 639 all threads. Huge objects are used by applications infrequently enough 640 that this single data structure is not a scalability issue.</para> 641 642 <para>Each chunk that is managed by an arena tracks its contents as runs of 643 contiguous pages (unused, backing a set of small objects, or backing one 644 large object). The combination of chunk alignment and chunk page maps 645 makes it possible to determine all metadata regarding small and large 646 allocations in constant time.</para> 647 648 <para>Small objects are managed in groups by page runs. Each run maintains 649 a frontier and free list to track which regions are in use. Allocation 650 requests that are no more than half the quantum (8 or 16, depending on 651 architecture) are rounded up to the nearest power of two that is at least 652 <code language="C">sizeof(<type>double</type>)</code>. All other small 653 object size classes are multiples of the quantum, spaced such that internal 654 fragmentation is limited to approximately 25% for all but the smallest size 655 classes. Allocation requests that are larger than the maximum small size 656 class, but small enough to fit in an arena-managed chunk (see the <link 657 linkend="opt.lg_chunk"><mallctl>opt.lg_chunk</mallctl></link> option), are 658 rounded up to the nearest run size. Allocation requests that are too large 659 to fit in an arena-managed chunk are rounded up to the nearest multiple of 660 the chunk size.</para> 661 662 <para>Allocations are packed tightly together, which can be an issue for 663 multi-threaded applications. If you need to assure that allocations do not 664 suffer from cacheline sharing, round your allocation requests up to the 665 nearest multiple of the cacheline size, or specify cacheline alignment when 666 allocating.</para> 667 668 <para>Assuming 4 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 64-bit 669 system, the size classes in each category are as shown in <xref 670 linkend="size_classes" xrefstyle="template:Table %n"/>.</para> 671 672 <table xml:id="size_classes" frame="all"> 673 <title>Size classes</title> 674 <tgroup cols="3" colsep="1" rowsep="1"> 675 <colspec colname="c1" align="left"/> 676 <colspec colname="c2" align="right"/> 677 <colspec colname="c3" align="left"/> 678 <thead> 679 <row> 680 <entry>Category</entry> 681 <entry>Spacing</entry> 682 <entry>Size</entry> 683 </row> 684 </thead> 685 <tbody> 686 <row> 687 <entry morerows="6">Small</entry> 688 <entry>lg</entry> 689 <entry>[8]</entry> 690 </row> 691 <row> 692 <entry>16</entry> 693 <entry>[16, 32, 48, ..., 128]</entry> 694 </row> 695 <row> 696 <entry>32</entry> 697 <entry>[160, 192, 224, 256]</entry> 698 </row> 699 <row> 700 <entry>64</entry> 701 <entry>[320, 384, 448, 512]</entry> 702 </row> 703 <row> 704 <entry>128</entry> 705 <entry>[640, 768, 896, 1024]</entry> 706 </row> 707 <row> 708 <entry>256</entry> 709 <entry>[1280, 1536, 1792, 2048]</entry> 710 </row> 711 <row> 712 <entry>512</entry> 713 <entry>[2560, 3072, 3584]</entry> 714 </row> 715 <row> 716 <entry>Large</entry> 717 <entry>4 KiB</entry> 718 <entry>[4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB]</entry> 719 </row> 720 <row> 721 <entry>Huge</entry> 722 <entry>4 MiB</entry> 723 <entry>[4 MiB, 8 MiB, 12 MiB, ...]</entry> 724 </row> 725 </tbody> 726 </tgroup> 727 </table> 728 </refsect1> 729 <refsect1 id="mallctl_namespace"> 730 <title>MALLCTL NAMESPACE</title> 731 <para>The following names are defined in the namespace accessible via the 732 <function>mallctl*<parameter/></function> functions. Value types are 733 specified in parentheses, their readable/writable statuses are encoded as 734 <literal>rw</literal>, <literal>r-</literal>, <literal>-w</literal>, or 735 <literal>--</literal>, and required build configuration flags follow, if 736 any. A name element encoded as <literal><i></literal> or 737 <literal><j></literal> indicates an integer component, where the 738 integer varies from 0 to some upper value that must be determined via 739 introspection. In the case of <mallctl>stats.arenas.<i>.*</mallctl>, 740 <literal><i></literal> equal to <link 741 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> can be 742 used to access the summation of statistics from all arenas. Take special 743 note of the <link linkend="epoch"><mallctl>epoch</mallctl></link> mallctl, 744 which controls refreshing of cached dynamic statistics.</para> 745 746 <variablelist> 747 <varlistentry id="version"> 748 <term> 749 <mallctl>version</mallctl> 750 (<type>const char *</type>) 751 <literal>r-</literal> 752 </term> 753 <listitem><para>Return the jemalloc version string.</para></listitem> 754 </varlistentry> 755 756 <varlistentry id="epoch"> 757 <term> 758 <mallctl>epoch</mallctl> 759 (<type>uint64_t</type>) 760 <literal>rw</literal> 761 </term> 762 <listitem><para>If a value is passed in, refresh the data from which 763 the <function>mallctl*<parameter/></function> functions report values, 764 and increment the epoch. Return the current epoch. This is useful for 765 detecting whether another thread caused a refresh.</para></listitem> 766 </varlistentry> 767 768 <varlistentry id="config.debug"> 769 <term> 770 <mallctl>config.debug</mallctl> 771 (<type>bool</type>) 772 <literal>r-</literal> 773 </term> 774 <listitem><para><option>--enable-debug</option> was specified during 775 build configuration.</para></listitem> 776 </varlistentry> 777 778 <varlistentry id="config.dss"> 779 <term> 780 <mallctl>config.dss</mallctl> 781 (<type>bool</type>) 782 <literal>r-</literal> 783 </term> 784 <listitem><para><option>--enable-dss</option> was specified during 785 build configuration.</para></listitem> 786 </varlistentry> 787 788 <varlistentry id="config.fill"> 789 <term> 790 <mallctl>config.fill</mallctl> 791 (<type>bool</type>) 792 <literal>r-</literal> 793 </term> 794 <listitem><para><option>--enable-fill</option> was specified during 795 build configuration.</para></listitem> 796 </varlistentry> 797 798 <varlistentry id="config.lazy_lock"> 799 <term> 800 <mallctl>config.lazy_lock</mallctl> 801 (<type>bool</type>) 802 <literal>r-</literal> 803 </term> 804 <listitem><para><option>--enable-lazy-lock</option> was specified 805 during build configuration.</para></listitem> 806 </varlistentry> 807 808 <varlistentry id="config.mremap"> 809 <term> 810 <mallctl>config.mremap</mallctl> 811 (<type>bool</type>) 812 <literal>r-</literal> 813 </term> 814 <listitem><para><option>--enable-mremap</option> was specified during 815 build configuration.</para></listitem> 816 </varlistentry> 817 818 <varlistentry id="config.munmap"> 819 <term> 820 <mallctl>config.munmap</mallctl> 821 (<type>bool</type>) 822 <literal>r-</literal> 823 </term> 824 <listitem><para><option>--enable-munmap</option> was specified during 825 build configuration.</para></listitem> 826 </varlistentry> 827 828 <varlistentry id="config.prof"> 829 <term> 830 <mallctl>config.prof</mallctl> 831 (<type>bool</type>) 832 <literal>r-</literal> 833 </term> 834 <listitem><para><option>--enable-prof</option> was specified during 835 build configuration.</para></listitem> 836 </varlistentry> 837 838 <varlistentry id="config.prof_libgcc"> 839 <term> 840 <mallctl>config.prof_libgcc</mallctl> 841 (<type>bool</type>) 842 <literal>r-</literal> 843 </term> 844 <listitem><para><option>--disable-prof-libgcc</option> was not 845 specified during build configuration.</para></listitem> 846 </varlistentry> 847 848 <varlistentry id="config.prof_libunwind"> 849 <term> 850 <mallctl>config.prof_libunwind</mallctl> 851 (<type>bool</type>) 852 <literal>r-</literal> 853 </term> 854 <listitem><para><option>--enable-prof-libunwind</option> was specified 855 during build configuration.</para></listitem> 856 </varlistentry> 857 858 <varlistentry id="config.stats"> 859 <term> 860 <mallctl>config.stats</mallctl> 861 (<type>bool</type>) 862 <literal>r-</literal> 863 </term> 864 <listitem><para><option>--enable-stats</option> was specified during 865 build configuration.</para></listitem> 866 </varlistentry> 867 868 <varlistentry id="config.tcache"> 869 <term> 870 <mallctl>config.tcache</mallctl> 871 (<type>bool</type>) 872 <literal>r-</literal> 873 </term> 874 <listitem><para><option>--disable-tcache</option> was not specified 875 during build configuration.</para></listitem> 876 </varlistentry> 877 878 <varlistentry id="config.tls"> 879 <term> 880 <mallctl>config.tls</mallctl> 881 (<type>bool</type>) 882 <literal>r-</literal> 883 </term> 884 <listitem><para><option>--disable-tls</option> was not specified during 885 build configuration.</para></listitem> 886 </varlistentry> 887 888 <varlistentry id="config.utrace"> 889 <term> 890 <mallctl>config.utrace</mallctl> 891 (<type>bool</type>) 892 <literal>r-</literal> 893 </term> 894 <listitem><para><option>--enable-utrace</option> was specified during 895 build configuration.</para></listitem> 896 </varlistentry> 897 898 <varlistentry id="config.valgrind"> 899 <term> 900 <mallctl>config.valgrind</mallctl> 901 (<type>bool</type>) 902 <literal>r-</literal> 903 </term> 904 <listitem><para><option>--enable-valgrind</option> was specified during 905 build configuration.</para></listitem> 906 </varlistentry> 907 908 <varlistentry id="config.xmalloc"> 909 <term> 910 <mallctl>config.xmalloc</mallctl> 911 (<type>bool</type>) 912 <literal>r-</literal> 913 </term> 914 <listitem><para><option>--enable-xmalloc</option> was specified during 915 build configuration.</para></listitem> 916 </varlistentry> 917 918 <varlistentry id="opt.abort"> 919 <term> 920 <mallctl>opt.abort</mallctl> 921 (<type>bool</type>) 922 <literal>r-</literal> 923 </term> 924 <listitem><para>Abort-on-warning enabled/disabled. If true, most 925 warnings are fatal. The process will call 926 <citerefentry><refentrytitle>abort</refentrytitle> 927 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is 928 disabled by default unless <option>--enable-debug</option> is 929 specified during configuration, in which case it is enabled by default. 930 </para></listitem> 931 </varlistentry> 932 933 <varlistentry id="opt.dss"> 934 <term> 935 <mallctl>opt.dss</mallctl> 936 (<type>const char *</type>) 937 <literal>r-</literal> 938 </term> 939 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 940 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 941 related to <citerefentry><refentrytitle>mmap</refentrytitle> 942 <manvolnum>2</manvolnum></citerefentry> allocation. The following 943 settings are supported: “disabled”, “primary”, 944 and “secondary”. The default is “secondary” if 945 <link linkend="config.dss"><mallctl>config.dss</mallctl></link> is 946 true, “disabled” otherwise. 947 </para></listitem> 948 </varlistentry> 949 950 <varlistentry id="opt.lg_chunk"> 951 <term> 952 <mallctl>opt.lg_chunk</mallctl> 953 (<type>size_t</type>) 954 <literal>r-</literal> 955 </term> 956 <listitem><para>Virtual memory chunk size (log base 2). If a chunk 957 size outside the supported size range is specified, the size is 958 silently clipped to the minimum/maximum supported size. The default 959 chunk size is 4 MiB (2^22). 960 </para></listitem> 961 </varlistentry> 962 963 <varlistentry id="opt.narenas"> 964 <term> 965 <mallctl>opt.narenas</mallctl> 966 (<type>size_t</type>) 967 <literal>r-</literal> 968 </term> 969 <listitem><para>Maximum number of arenas to use for automatic 970 multiplexing of threads and arenas. The default is four times the 971 number of CPUs, or one if there is a single CPU.</para></listitem> 972 </varlistentry> 973 974 <varlistentry id="opt.lg_dirty_mult"> 975 <term> 976 <mallctl>opt.lg_dirty_mult</mallctl> 977 (<type>ssize_t</type>) 978 <literal>r-</literal> 979 </term> 980 <listitem><para>Per-arena minimum ratio (log base 2) of active to dirty 981 pages. Some dirty unused pages may be allowed to accumulate, within 982 the limit set by the ratio (or one chunk worth of dirty pages, 983 whichever is greater), before informing the kernel about some of those 984 pages via <citerefentry><refentrytitle>madvise</refentrytitle> 985 <manvolnum>2</manvolnum></citerefentry> or a similar system call. This 986 provides the kernel with sufficient information to recycle dirty pages 987 if physical memory becomes scarce and the pages remain unused. The 988 default minimum ratio is 8:1 (2^3:1); an option value of -1 will 989 disable dirty page purging.</para></listitem> 990 </varlistentry> 991 992 <varlistentry id="opt.stats_print"> 993 <term> 994 <mallctl>opt.stats_print</mallctl> 995 (<type>bool</type>) 996 <literal>r-</literal> 997 </term> 998 <listitem><para>Enable/disable statistics printing at exit. If 999 enabled, the <function>malloc_stats_print<parameter/></function> 1000 function is called at program exit via an 1001 <citerefentry><refentrytitle>atexit</refentrytitle> 1002 <manvolnum>3</manvolnum></citerefentry> function. If 1003 <option>--enable-stats</option> is specified during configuration, this 1004 has the potential to cause deadlock for a multi-threaded process that 1005 exits while one or more threads are executing in the memory allocation 1006 functions. Therefore, this option should only be used with care; it is 1007 primarily intended as a performance tuning aid during application 1008 development. This option is disabled by default.</para></listitem> 1009 </varlistentry> 1010 1011 <varlistentry id="opt.junk"> 1012 <term> 1013 <mallctl>opt.junk</mallctl> 1014 (<type>bool</type>) 1015 <literal>r-</literal> 1016 [<option>--enable-fill</option>] 1017 </term> 1018 <listitem><para>Junk filling enabled/disabled. If enabled, each byte 1019 of uninitialized allocated memory will be initialized to 1020 <literal>0xa5</literal>. All deallocated memory will be initialized to 1021 <literal>0x5a</literal>. This is intended for debugging and will 1022 impact performance negatively. This option is disabled by default 1023 unless <option>--enable-debug</option> is specified during 1024 configuration, in which case it is enabled by default unless running 1025 inside <ulink 1026 url="http://valgrind.org/">Valgrind</ulink>.</para></listitem> 1027 </varlistentry> 1028 1029 <varlistentry id="opt.quarantine"> 1030 <term> 1031 <mallctl>opt.quarantine</mallctl> 1032 (<type>size_t</type>) 1033 <literal>r-</literal> 1034 [<option>--enable-fill</option>] 1035 </term> 1036 <listitem><para>Per thread quarantine size in bytes. If non-zero, each 1037 thread maintains a FIFO object quarantine that stores up to the 1038 specified number of bytes of memory. The quarantined memory is not 1039 freed until it is released from quarantine, though it is immediately 1040 junk-filled if the <link 1041 linkend="opt.junk"><mallctl>opt.junk</mallctl></link> option is 1042 enabled. This feature is of particular use in combination with <ulink 1043 url="http://valgrind.org/">Valgrind</ulink>, which can detect attempts 1044 to access quarantined objects. This is intended for debugging and will 1045 impact performance negatively. The default quarantine size is 0 unless 1046 running inside Valgrind, in which case the default is 16 1047 MiB.</para></listitem> 1048 </varlistentry> 1049 1050 <varlistentry id="opt.redzone"> 1051 <term> 1052 <mallctl>opt.redzone</mallctl> 1053 (<type>bool</type>) 1054 <literal>r-</literal> 1055 [<option>--enable-fill</option>] 1056 </term> 1057 <listitem><para>Redzones enabled/disabled. If enabled, small 1058 allocations have redzones before and after them. Furthermore, if the 1059 <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> option is 1060 enabled, the redzones are checked for corruption during deallocation. 1061 However, the primary intended purpose of this feature is to be used in 1062 combination with <ulink url="http://valgrind.org/">Valgrind</ulink>, 1063 which needs redzones in order to do effective buffer overflow/underflow 1064 detection. This option is intended for debugging and will impact 1065 performance negatively. This option is disabled by 1066 default unless running inside Valgrind.</para></listitem> 1067 </varlistentry> 1068 1069 <varlistentry id="opt.zero"> 1070 <term> 1071 <mallctl>opt.zero</mallctl> 1072 (<type>bool</type>) 1073 <literal>r-</literal> 1074 [<option>--enable-fill</option>] 1075 </term> 1076 <listitem><para>Zero filling enabled/disabled. If enabled, each byte 1077 of uninitialized allocated memory will be initialized to 0. Note that 1078 this initialization only happens once for each byte, so 1079 <function>realloc<parameter/></function>, 1080 <function>rallocx<parameter/></function> and 1081 <function>rallocm<parameter/></function> calls do not zero memory that 1082 was previously allocated. This is intended for debugging and will 1083 impact performance negatively. This option is disabled by default. 1084 </para></listitem> 1085 </varlistentry> 1086 1087 <varlistentry id="opt.utrace"> 1088 <term> 1089 <mallctl>opt.utrace</mallctl> 1090 (<type>bool</type>) 1091 <literal>r-</literal> 1092 [<option>--enable-utrace</option>] 1093 </term> 1094 <listitem><para>Allocation tracing based on 1095 <citerefentry><refentrytitle>utrace</refentrytitle> 1096 <manvolnum>2</manvolnum></citerefentry> enabled/disabled. This option 1097 is disabled by default.</para></listitem> 1098 </varlistentry> 1099 1100 <varlistentry id="opt.valgrind"> 1101 <term> 1102 <mallctl>opt.valgrind</mallctl> 1103 (<type>bool</type>) 1104 <literal>r-</literal> 1105 [<option>--enable-valgrind</option>] 1106 </term> 1107 <listitem><para><ulink url="http://valgrind.org/">Valgrind</ulink> 1108 support enabled/disabled. This option is vestigal because jemalloc 1109 auto-detects whether it is running inside Valgrind. This option is 1110 disabled by default, unless running inside Valgrind.</para></listitem> 1111 </varlistentry> 1112 1113 <varlistentry id="opt.xmalloc"> 1114 <term> 1115 <mallctl>opt.xmalloc</mallctl> 1116 (<type>bool</type>) 1117 <literal>r-</literal> 1118 [<option>--enable-xmalloc</option>] 1119 </term> 1120 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled, 1121 rather than returning failure for any allocation function, display a 1122 diagnostic message on <constant>STDERR_FILENO</constant> and cause the 1123 program to drop core (using 1124 <citerefentry><refentrytitle>abort</refentrytitle> 1125 <manvolnum>3</manvolnum></citerefentry>). If an application is 1126 designed to depend on this behavior, set the option at compile time by 1127 including the following in the source code: 1128 <programlisting language="C"><![CDATA[ 1129malloc_conf = "xmalloc:true";]]></programlisting> 1130 This option is disabled by default.</para></listitem> 1131 </varlistentry> 1132 1133 <varlistentry id="opt.tcache"> 1134 <term> 1135 <mallctl>opt.tcache</mallctl> 1136 (<type>bool</type>) 1137 <literal>r-</literal> 1138 [<option>--enable-tcache</option>] 1139 </term> 1140 <listitem><para>Thread-specific caching enabled/disabled. When there 1141 are multiple threads, each thread uses a thread-specific cache for 1142 objects up to a certain size. Thread-specific caching allows many 1143 allocations to be satisfied without performing any thread 1144 synchronization, at the cost of increased memory use. See the 1145 <link 1146 linkend="opt.lg_tcache_max"><mallctl>opt.lg_tcache_max</mallctl></link> 1147 option for related tuning information. This option is enabled by 1148 default unless running inside <ulink 1149 url="http://valgrind.org/">Valgrind</ulink>.</para></listitem> 1150 </varlistentry> 1151 1152 <varlistentry id="opt.lg_tcache_max"> 1153 <term> 1154 <mallctl>opt.lg_tcache_max</mallctl> 1155 (<type>size_t</type>) 1156 <literal>r-</literal> 1157 [<option>--enable-tcache</option>] 1158 </term> 1159 <listitem><para>Maximum size class (log base 2) to cache in the 1160 thread-specific cache. At a minimum, all small size classes are 1161 cached, and at a maximum all large size classes are cached. The 1162 default maximum is 32 KiB (2^15).</para></listitem> 1163 </varlistentry> 1164 1165 <varlistentry id="opt.prof"> 1166 <term> 1167 <mallctl>opt.prof</mallctl> 1168 (<type>bool</type>) 1169 <literal>r-</literal> 1170 [<option>--enable-prof</option>] 1171 </term> 1172 <listitem><para>Memory profiling enabled/disabled. If enabled, profile 1173 memory allocation activity. See the <link 1174 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 1175 option for on-the-fly activation/deactivation. See the <link 1176 linkend="opt.lg_prof_sample"><mallctl>opt.lg_prof_sample</mallctl></link> 1177 option for probabilistic sampling control. See the <link 1178 linkend="opt.prof_accum"><mallctl>opt.prof_accum</mallctl></link> 1179 option for control of cumulative sample reporting. See the <link 1180 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 1181 option for information on interval-triggered profile dumping, the <link 1182 linkend="opt.prof_gdump"><mallctl>opt.prof_gdump</mallctl></link> 1183 option for information on high-water-triggered profile dumping, and the 1184 <link linkend="opt.prof_final"><mallctl>opt.prof_final</mallctl></link> 1185 option for final profile dumping. Profile output is compatible with 1186 the included <command>pprof</command> Perl script, which originates 1187 from the <ulink url="http://code.google.com/p/gperftools/">gperftools 1188 package</ulink>.</para></listitem> 1189 </varlistentry> 1190 1191 <varlistentry id="opt.prof_prefix"> 1192 <term> 1193 <mallctl>opt.prof_prefix</mallctl> 1194 (<type>const char *</type>) 1195 <literal>r-</literal> 1196 [<option>--enable-prof</option>] 1197 </term> 1198 <listitem><para>Filename prefix for profile dumps. If the prefix is 1199 set to the empty string, no automatic dumps will occur; this is 1200 primarily useful for disabling the automatic final heap dump (which 1201 also disables leak reporting, if enabled). The default prefix is 1202 <filename>jeprof</filename>.</para></listitem> 1203 </varlistentry> 1204 1205 <varlistentry id="opt.prof_active"> 1206 <term> 1207 <mallctl>opt.prof_active</mallctl> 1208 (<type>bool</type>) 1209 <literal>rw</literal> 1210 [<option>--enable-prof</option>] 1211 </term> 1212 <listitem><para>Profiling activated/deactivated. This is a secondary 1213 control mechanism that makes it possible to start the application with 1214 profiling enabled (see the <link 1215 linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option) but 1216 inactive, then toggle profiling at any time during program execution 1217 with the <link 1218 linkend="prof.active"><mallctl>prof.active</mallctl></link> mallctl. 1219 This option is enabled by default.</para></listitem> 1220 </varlistentry> 1221 1222 <varlistentry id="opt.lg_prof_sample"> 1223 <term> 1224 <mallctl>opt.lg_prof_sample</mallctl> 1225 (<type>ssize_t</type>) 1226 <literal>r-</literal> 1227 [<option>--enable-prof</option>] 1228 </term> 1229 <listitem><para>Average interval (log base 2) between allocation 1230 samples, as measured in bytes of allocation activity. Increasing the 1231 sampling interval decreases profile fidelity, but also decreases the 1232 computational overhead. The default sample interval is 512 KiB (2^19 1233 B).</para></listitem> 1234 </varlistentry> 1235 1236 <varlistentry id="opt.prof_accum"> 1237 <term> 1238 <mallctl>opt.prof_accum</mallctl> 1239 (<type>bool</type>) 1240 <literal>r-</literal> 1241 [<option>--enable-prof</option>] 1242 </term> 1243 <listitem><para>Reporting of cumulative object/byte counts in profile 1244 dumps enabled/disabled. If this option is enabled, every unique 1245 backtrace must be stored for the duration of execution. Depending on 1246 the application, this can impose a large memory overhead, and the 1247 cumulative counts are not always of interest. This option is disabled 1248 by default.</para></listitem> 1249 </varlistentry> 1250 1251 <varlistentry id="opt.lg_prof_interval"> 1252 <term> 1253 <mallctl>opt.lg_prof_interval</mallctl> 1254 (<type>ssize_t</type>) 1255 <literal>r-</literal> 1256 [<option>--enable-prof</option>] 1257 </term> 1258 <listitem><para>Average interval (log base 2) between memory profile 1259 dumps, as measured in bytes of allocation activity. The actual 1260 interval between dumps may be sporadic because decentralized allocation 1261 counters are used to avoid synchronization bottlenecks. Profiles are 1262 dumped to files named according to the pattern 1263 <filename><prefix>.<pid>.<seq>.i<iseq>.heap</filename>, 1264 where <literal><prefix></literal> is controlled by the 1265 <link 1266 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1267 option. By default, interval-triggered profile dumping is disabled 1268 (encoded as -1). 1269 </para></listitem> 1270 </varlistentry> 1271 1272 <varlistentry id="opt.prof_gdump"> 1273 <term> 1274 <mallctl>opt.prof_gdump</mallctl> 1275 (<type>bool</type>) 1276 <literal>r-</literal> 1277 [<option>--enable-prof</option>] 1278 </term> 1279 <listitem><para>Trigger a memory profile dump every time the total 1280 virtual memory exceeds the previous maximum. Profiles are dumped to 1281 files named according to the pattern 1282 <filename><prefix>.<pid>.<seq>.u<useq>.heap</filename>, 1283 where <literal><prefix></literal> is controlled by the <link 1284 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1285 option. This option is disabled by default.</para></listitem> 1286 </varlistentry> 1287 1288 <varlistentry id="opt.prof_final"> 1289 <term> 1290 <mallctl>opt.prof_final</mallctl> 1291 (<type>bool</type>) 1292 <literal>r-</literal> 1293 [<option>--enable-prof</option>] 1294 </term> 1295 <listitem><para>Use an 1296 <citerefentry><refentrytitle>atexit</refentrytitle> 1297 <manvolnum>3</manvolnum></citerefentry> function to dump final memory 1298 usage to a file named according to the pattern 1299 <filename><prefix>.<pid>.<seq>.f.heap</filename>, 1300 where <literal><prefix></literal> is controlled by the <link 1301 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1302 option. This option is enabled by default.</para></listitem> 1303 </varlistentry> 1304 1305 <varlistentry id="opt.prof_leak"> 1306 <term> 1307 <mallctl>opt.prof_leak</mallctl> 1308 (<type>bool</type>) 1309 <literal>r-</literal> 1310 [<option>--enable-prof</option>] 1311 </term> 1312 <listitem><para>Leak reporting enabled/disabled. If enabled, use an 1313 <citerefentry><refentrytitle>atexit</refentrytitle> 1314 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks 1315 detected by allocation sampling. See the 1316 <link linkend="opt.prof"><mallctl>opt.prof</mallctl></link> option for 1317 information on analyzing heap profile output. This option is disabled 1318 by default.</para></listitem> 1319 </varlistentry> 1320 1321 <varlistentry id="thread.arena"> 1322 <term> 1323 <mallctl>thread.arena</mallctl> 1324 (<type>unsigned</type>) 1325 <literal>rw</literal> 1326 </term> 1327 <listitem><para>Get or set the arena associated with the calling 1328 thread. If the specified arena was not initialized beforehand (see the 1329 <link 1330 linkend="arenas.initialized"><mallctl>arenas.initialized</mallctl></link> 1331 mallctl), it will be automatically initialized as a side effect of 1332 calling this interface.</para></listitem> 1333 </varlistentry> 1334 1335 <varlistentry id="thread.allocated"> 1336 <term> 1337 <mallctl>thread.allocated</mallctl> 1338 (<type>uint64_t</type>) 1339 <literal>r-</literal> 1340 [<option>--enable-stats</option>] 1341 </term> 1342 <listitem><para>Get the total number of bytes ever allocated by the 1343 calling thread. This counter has the potential to wrap around; it is 1344 up to the application to appropriately interpret the counter in such 1345 cases.</para></listitem> 1346 </varlistentry> 1347 1348 <varlistentry id="thread.allocatedp"> 1349 <term> 1350 <mallctl>thread.allocatedp</mallctl> 1351 (<type>uint64_t *</type>) 1352 <literal>r-</literal> 1353 [<option>--enable-stats</option>] 1354 </term> 1355 <listitem><para>Get a pointer to the the value that is returned by the 1356 <link 1357 linkend="thread.allocated"><mallctl>thread.allocated</mallctl></link> 1358 mallctl. This is useful for avoiding the overhead of repeated 1359 <function>mallctl*<parameter/></function> calls.</para></listitem> 1360 </varlistentry> 1361 1362 <varlistentry id="thread.deallocated"> 1363 <term> 1364 <mallctl>thread.deallocated</mallctl> 1365 (<type>uint64_t</type>) 1366 <literal>r-</literal> 1367 [<option>--enable-stats</option>] 1368 </term> 1369 <listitem><para>Get the total number of bytes ever deallocated by the 1370 calling thread. This counter has the potential to wrap around; it is 1371 up to the application to appropriately interpret the counter in such 1372 cases.</para></listitem> 1373 </varlistentry> 1374 1375 <varlistentry id="thread.deallocatedp"> 1376 <term> 1377 <mallctl>thread.deallocatedp</mallctl> 1378 (<type>uint64_t *</type>) 1379 <literal>r-</literal> 1380 [<option>--enable-stats</option>] 1381 </term> 1382 <listitem><para>Get a pointer to the the value that is returned by the 1383 <link 1384 linkend="thread.deallocated"><mallctl>thread.deallocated</mallctl></link> 1385 mallctl. This is useful for avoiding the overhead of repeated 1386 <function>mallctl*<parameter/></function> calls.</para></listitem> 1387 </varlistentry> 1388 1389 <varlistentry id="thread.tcache.enabled"> 1390 <term> 1391 <mallctl>thread.tcache.enabled</mallctl> 1392 (<type>bool</type>) 1393 <literal>rw</literal> 1394 [<option>--enable-tcache</option>] 1395 </term> 1396 <listitem><para>Enable/disable calling thread's tcache. The tcache is 1397 implicitly flushed as a side effect of becoming 1398 disabled (see <link 1399 lenkend="thread.tcache.flush"><mallctl>thread.tcache.flush</mallctl></link>). 1400 </para></listitem> 1401 </varlistentry> 1402 1403 <varlistentry id="thread.tcache.flush"> 1404 <term> 1405 <mallctl>thread.tcache.flush</mallctl> 1406 (<type>void</type>) 1407 <literal>--</literal> 1408 [<option>--enable-tcache</option>] 1409 </term> 1410 <listitem><para>Flush calling thread's tcache. This interface releases 1411 all cached objects and internal data structures associated with the 1412 calling thread's thread-specific cache. Ordinarily, this interface 1413 need not be called, since automatic periodic incremental garbage 1414 collection occurs, and the thread cache is automatically discarded when 1415 a thread exits. However, garbage collection is triggered by allocation 1416 activity, so it is possible for a thread that stops 1417 allocating/deallocating to retain its cache indefinitely, in which case 1418 the developer may find manual flushing useful.</para></listitem> 1419 </varlistentry> 1420 1421 <varlistentry id="arena.i.purge"> 1422 <term> 1423 <mallctl>arena.<i>.purge</mallctl> 1424 (<type>unsigned</type>) 1425 <literal>--</literal> 1426 </term> 1427 <listitem><para>Purge unused dirty pages for arena <i>, or for 1428 all arenas if <i> equals <link 1429 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link>. 1430 </para></listitem> 1431 </varlistentry> 1432 1433 <varlistentry id="arena.i.dss"> 1434 <term> 1435 <mallctl>arena.<i>.dss</mallctl> 1436 (<type>const char *</type>) 1437 <literal>rw</literal> 1438 </term> 1439 <listitem><para>Set the precedence of dss allocation as related to mmap 1440 allocation for arena <i>, or for all arenas if <i> equals 1441 <link 1442 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link>. Note 1443 that even during huge allocation this setting is read from the arena 1444 that would be chosen for small or large allocation so that applications 1445 can depend on consistent dss versus mmap allocation regardless of 1446 allocation size. See <link 1447 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for supported 1448 settings. 1449 </para></listitem> 1450 </varlistentry> 1451 1452 <varlistentry id="arenas.narenas"> 1453 <term> 1454 <mallctl>arenas.narenas</mallctl> 1455 (<type>unsigned</type>) 1456 <literal>r-</literal> 1457 </term> 1458 <listitem><para>Current limit on number of arenas.</para></listitem> 1459 </varlistentry> 1460 1461 <varlistentry id="arenas.initialized"> 1462 <term> 1463 <mallctl>arenas.initialized</mallctl> 1464 (<type>bool *</type>) 1465 <literal>r-</literal> 1466 </term> 1467 <listitem><para>An array of <link 1468 linkend="arenas.narenas"><mallctl>arenas.narenas</mallctl></link> 1469 booleans. Each boolean indicates whether the corresponding arena is 1470 initialized.</para></listitem> 1471 </varlistentry> 1472 1473 <varlistentry id="arenas.quantum"> 1474 <term> 1475 <mallctl>arenas.quantum</mallctl> 1476 (<type>size_t</type>) 1477 <literal>r-</literal> 1478 </term> 1479 <listitem><para>Quantum size.</para></listitem> 1480 </varlistentry> 1481 1482 <varlistentry id="arenas.page"> 1483 <term> 1484 <mallctl>arenas.page</mallctl> 1485 (<type>size_t</type>) 1486 <literal>r-</literal> 1487 </term> 1488 <listitem><para>Page size.</para></listitem> 1489 </varlistentry> 1490 1491 <varlistentry id="arenas.tcache_max"> 1492 <term> 1493 <mallctl>arenas.tcache_max</mallctl> 1494 (<type>size_t</type>) 1495 <literal>r-</literal> 1496 [<option>--enable-tcache</option>] 1497 </term> 1498 <listitem><para>Maximum thread-cached size class.</para></listitem> 1499 </varlistentry> 1500 1501 <varlistentry id="arenas.nbins"> 1502 <term> 1503 <mallctl>arenas.nbins</mallctl> 1504 (<type>unsigned</type>) 1505 <literal>r-</literal> 1506 </term> 1507 <listitem><para>Number of bin size classes.</para></listitem> 1508 </varlistentry> 1509 1510 <varlistentry id="arenas.nhbins"> 1511 <term> 1512 <mallctl>arenas.nhbins</mallctl> 1513 (<type>unsigned</type>) 1514 <literal>r-</literal> 1515 [<option>--enable-tcache</option>] 1516 </term> 1517 <listitem><para>Total number of thread cache bin size 1518 classes.</para></listitem> 1519 </varlistentry> 1520 1521 <varlistentry id="arenas.bin.i.size"> 1522 <term> 1523 <mallctl>arenas.bin.<i>.size</mallctl> 1524 (<type>size_t</type>) 1525 <literal>r-</literal> 1526 </term> 1527 <listitem><para>Maximum size supported by size class.</para></listitem> 1528 </varlistentry> 1529 1530 <varlistentry id="arenas.bin.i.nregs"> 1531 <term> 1532 <mallctl>arenas.bin.<i>.nregs</mallctl> 1533 (<type>uint32_t</type>) 1534 <literal>r-</literal> 1535 </term> 1536 <listitem><para>Number of regions per page run.</para></listitem> 1537 </varlistentry> 1538 1539 <varlistentry id="arenas.bin.i.run_size"> 1540 <term> 1541 <mallctl>arenas.bin.<i>.run_size</mallctl> 1542 (<type>size_t</type>) 1543 <literal>r-</literal> 1544 </term> 1545 <listitem><para>Number of bytes per page run.</para></listitem> 1546 </varlistentry> 1547 1548 <varlistentry id="arenas.nlruns"> 1549 <term> 1550 <mallctl>arenas.nlruns</mallctl> 1551 (<type>size_t</type>) 1552 <literal>r-</literal> 1553 </term> 1554 <listitem><para>Total number of large size classes.</para></listitem> 1555 </varlistentry> 1556 1557 <varlistentry id="arenas.lrun.i.size"> 1558 <term> 1559 <mallctl>arenas.lrun.<i>.size</mallctl> 1560 (<type>size_t</type>) 1561 <literal>r-</literal> 1562 </term> 1563 <listitem><para>Maximum size supported by this large size 1564 class.</para></listitem> 1565 </varlistentry> 1566 1567 <varlistentry id="arenas.purge"> 1568 <term> 1569 <mallctl>arenas.purge</mallctl> 1570 (<type>unsigned</type>) 1571 <literal>-w</literal> 1572 </term> 1573 <listitem><para>Purge unused dirty pages for the specified arena, or 1574 for all arenas if none is specified.</para></listitem> 1575 </varlistentry> 1576 1577 <varlistentry id="arenas.extend"> 1578 <term> 1579 <mallctl>arenas.extend</mallctl> 1580 (<type>unsigned</type>) 1581 <literal>r-</literal> 1582 </term> 1583 <listitem><para>Extend the array of arenas by appending a new arena, 1584 and returning the new arena index.</para></listitem> 1585 </varlistentry> 1586 1587 <varlistentry id="prof.active"> 1588 <term> 1589 <mallctl>prof.active</mallctl> 1590 (<type>bool</type>) 1591 <literal>rw</literal> 1592 [<option>--enable-prof</option>] 1593 </term> 1594 <listitem><para>Control whether sampling is currently active. See the 1595 <link 1596 linkend="opt.prof_active"><mallctl>opt.prof_active</mallctl></link> 1597 option for additional information. 1598 </para></listitem> 1599 </varlistentry> 1600 1601 <varlistentry id="prof.dump"> 1602 <term> 1603 <mallctl>prof.dump</mallctl> 1604 (<type>const char *</type>) 1605 <literal>-w</literal> 1606 [<option>--enable-prof</option>] 1607 </term> 1608 <listitem><para>Dump a memory profile to the specified file, or if NULL 1609 is specified, to a file according to the pattern 1610 <filename><prefix>.<pid>.<seq>.m<mseq>.heap</filename>, 1611 where <literal><prefix></literal> is controlled by the 1612 <link 1613 linkend="opt.prof_prefix"><mallctl>opt.prof_prefix</mallctl></link> 1614 option.</para></listitem> 1615 </varlistentry> 1616 1617 <varlistentry id="prof.interval"> 1618 <term> 1619 <mallctl>prof.interval</mallctl> 1620 (<type>uint64_t</type>) 1621 <literal>r-</literal> 1622 [<option>--enable-prof</option>] 1623 </term> 1624 <listitem><para>Average number of bytes allocated between 1625 inverval-based profile dumps. See the 1626 <link 1627 linkend="opt.lg_prof_interval"><mallctl>opt.lg_prof_interval</mallctl></link> 1628 option for additional information.</para></listitem> 1629 </varlistentry> 1630 1631 <varlistentry id="stats.cactive"> 1632 <term> 1633 <mallctl>stats.cactive</mallctl> 1634 (<type>size_t *</type>) 1635 <literal>r-</literal> 1636 [<option>--enable-stats</option>] 1637 </term> 1638 <listitem><para>Pointer to a counter that contains an approximate count 1639 of the current number of bytes in active pages. The estimate may be 1640 high, but never low, because each arena rounds up to the nearest 1641 multiple of the chunk size when computing its contribution to the 1642 counter. Note that the <link 1643 linkend="epoch"><mallctl>epoch</mallctl></link> mallctl has no bearing 1644 on this counter. Furthermore, counter consistency is maintained via 1645 atomic operations, so it is necessary to use an atomic operation in 1646 order to guarantee a consistent read when dereferencing the pointer. 1647 </para></listitem> 1648 </varlistentry> 1649 1650 <varlistentry id="stats.allocated"> 1651 <term> 1652 <mallctl>stats.allocated</mallctl> 1653 (<type>size_t</type>) 1654 <literal>r-</literal> 1655 [<option>--enable-stats</option>] 1656 </term> 1657 <listitem><para>Total number of bytes allocated by the 1658 application.</para></listitem> 1659 </varlistentry> 1660 1661 <varlistentry id="stats.active"> 1662 <term> 1663 <mallctl>stats.active</mallctl> 1664 (<type>size_t</type>) 1665 <literal>r-</literal> 1666 [<option>--enable-stats</option>] 1667 </term> 1668 <listitem><para>Total number of bytes in active pages allocated by the 1669 application. This is a multiple of the page size, and greater than or 1670 equal to <link 1671 linkend="stats.allocated"><mallctl>stats.allocated</mallctl></link>. 1672 This does not include <link linkend="stats.arenas.i.pdirty"> 1673 <mallctl>stats.arenas.<i>.pdirty</mallctl></link> and pages 1674 entirely devoted to allocator metadata.</para></listitem> 1675 </varlistentry> 1676 1677 <varlistentry id="stats.mapped"> 1678 <term> 1679 <mallctl>stats.mapped</mallctl> 1680 (<type>size_t</type>) 1681 <literal>r-</literal> 1682 [<option>--enable-stats</option>] 1683 </term> 1684 <listitem><para>Total number of bytes in chunks mapped on behalf of the 1685 application. This is a multiple of the chunk size, and is at least as 1686 large as <link 1687 linkend="stats.active"><mallctl>stats.active</mallctl></link>. This 1688 does not include inactive chunks.</para></listitem> 1689 </varlistentry> 1690 1691 <varlistentry id="stats.chunks.current"> 1692 <term> 1693 <mallctl>stats.chunks.current</mallctl> 1694 (<type>size_t</type>) 1695 <literal>r-</literal> 1696 [<option>--enable-stats</option>] 1697 </term> 1698 <listitem><para>Total number of chunks actively mapped on behalf of the 1699 application. This does not include inactive chunks. 1700 </para></listitem> 1701 </varlistentry> 1702 1703 <varlistentry id="stats.chunks.total"> 1704 <term> 1705 <mallctl>stats.chunks.total</mallctl> 1706 (<type>uint64_t</type>) 1707 <literal>r-</literal> 1708 [<option>--enable-stats</option>] 1709 </term> 1710 <listitem><para>Cumulative number of chunks allocated.</para></listitem> 1711 </varlistentry> 1712 1713 <varlistentry id="stats.chunks.high"> 1714 <term> 1715 <mallctl>stats.chunks.high</mallctl> 1716 (<type>size_t</type>) 1717 <literal>r-</literal> 1718 [<option>--enable-stats</option>] 1719 </term> 1720 <listitem><para>Maximum number of active chunks at any time thus far. 1721 </para></listitem> 1722 </varlistentry> 1723 1724 <varlistentry id="stats.huge.allocated"> 1725 <term> 1726 <mallctl>stats.huge.allocated</mallctl> 1727 (<type>size_t</type>) 1728 <literal>r-</literal> 1729 [<option>--enable-stats</option>] 1730 </term> 1731 <listitem><para>Number of bytes currently allocated by huge objects. 1732 </para></listitem> 1733 </varlistentry> 1734 1735 <varlistentry id="stats.huge.nmalloc"> 1736 <term> 1737 <mallctl>stats.huge.nmalloc</mallctl> 1738 (<type>uint64_t</type>) 1739 <literal>r-</literal> 1740 [<option>--enable-stats</option>] 1741 </term> 1742 <listitem><para>Cumulative number of huge allocation requests. 1743 </para></listitem> 1744 </varlistentry> 1745 1746 <varlistentry id="stats.huge.ndalloc"> 1747 <term> 1748 <mallctl>stats.huge.ndalloc</mallctl> 1749 (<type>uint64_t</type>) 1750 <literal>r-</literal> 1751 [<option>--enable-stats</option>] 1752 </term> 1753 <listitem><para>Cumulative number of huge deallocation requests. 1754 </para></listitem> 1755 </varlistentry> 1756 1757 <varlistentry id="stats.arenas.i.dss"> 1758 <term> 1759 <mallctl>stats.arenas.<i>.dss</mallctl> 1760 (<type>const char *</type>) 1761 <literal>r-</literal> 1762 </term> 1763 <listitem><para>dss (<citerefentry><refentrytitle>sbrk</refentrytitle> 1764 <manvolnum>2</manvolnum></citerefentry>) allocation precedence as 1765 related to <citerefentry><refentrytitle>mmap</refentrytitle> 1766 <manvolnum>2</manvolnum></citerefentry> allocation. See <link 1767 linkend="opt.dss"><mallctl>opt.dss</mallctl></link> for details. 1768 </para></listitem> 1769 </varlistentry> 1770 1771 <varlistentry id="stats.arenas.i.nthreads"> 1772 <term> 1773 <mallctl>stats.arenas.<i>.nthreads</mallctl> 1774 (<type>unsigned</type>) 1775 <literal>r-</literal> 1776 </term> 1777 <listitem><para>Number of threads currently assigned to 1778 arena.</para></listitem> 1779 </varlistentry> 1780 1781 <varlistentry id="stats.arenas.i.pactive"> 1782 <term> 1783 <mallctl>stats.arenas.<i>.pactive</mallctl> 1784 (<type>size_t</type>) 1785 <literal>r-</literal> 1786 </term> 1787 <listitem><para>Number of pages in active runs.</para></listitem> 1788 </varlistentry> 1789 1790 <varlistentry id="stats.arenas.i.pdirty"> 1791 <term> 1792 <mallctl>stats.arenas.<i>.pdirty</mallctl> 1793 (<type>size_t</type>) 1794 <literal>r-</literal> 1795 </term> 1796 <listitem><para>Number of pages within unused runs that are potentially 1797 dirty, and for which <function>madvise<parameter>...</parameter> 1798 <parameter><constant>MADV_DONTNEED</constant></parameter></function> or 1799 similar has not been called.</para></listitem> 1800 </varlistentry> 1801 1802 <varlistentry id="stats.arenas.i.mapped"> 1803 <term> 1804 <mallctl>stats.arenas.<i>.mapped</mallctl> 1805 (<type>size_t</type>) 1806 <literal>r-</literal> 1807 [<option>--enable-stats</option>] 1808 </term> 1809 <listitem><para>Number of mapped bytes.</para></listitem> 1810 </varlistentry> 1811 1812 <varlistentry id="stats.arenas.i.npurge"> 1813 <term> 1814 <mallctl>stats.arenas.<i>.npurge</mallctl> 1815 (<type>uint64_t</type>) 1816 <literal>r-</literal> 1817 [<option>--enable-stats</option>] 1818 </term> 1819 <listitem><para>Number of dirty page purge sweeps performed. 1820 </para></listitem> 1821 </varlistentry> 1822 1823 <varlistentry id="stats.arenas.i.nmadvise"> 1824 <term> 1825 <mallctl>stats.arenas.<i>.nmadvise</mallctl> 1826 (<type>uint64_t</type>) 1827 <literal>r-</literal> 1828 [<option>--enable-stats</option>] 1829 </term> 1830 <listitem><para>Number of <function>madvise<parameter>...</parameter> 1831 <parameter><constant>MADV_DONTNEED</constant></parameter></function> or 1832 similar calls made to purge dirty pages.</para></listitem> 1833 </varlistentry> 1834 1835 <varlistentry id="stats.arenas.i.purged"> 1836 <term> 1837 <mallctl>stats.arenas.<i>.purged</mallctl> 1838 (<type>uint64_t</type>) 1839 <literal>r-</literal> 1840 [<option>--enable-stats</option>] 1841 </term> 1842 <listitem><para>Number of pages purged.</para></listitem> 1843 </varlistentry> 1844 1845 <varlistentry id="stats.arenas.i.small.allocated"> 1846 <term> 1847 <mallctl>stats.arenas.<i>.small.allocated</mallctl> 1848 (<type>size_t</type>) 1849 <literal>r-</literal> 1850 [<option>--enable-stats</option>] 1851 </term> 1852 <listitem><para>Number of bytes currently allocated by small objects. 1853 </para></listitem> 1854 </varlistentry> 1855 1856 <varlistentry id="stats.arenas.i.small.nmalloc"> 1857 <term> 1858 <mallctl>stats.arenas.<i>.small.nmalloc</mallctl> 1859 (<type>uint64_t</type>) 1860 <literal>r-</literal> 1861 [<option>--enable-stats</option>] 1862 </term> 1863 <listitem><para>Cumulative number of allocation requests served by 1864 small bins.</para></listitem> 1865 </varlistentry> 1866 1867 <varlistentry id="stats.arenas.i.small.ndalloc"> 1868 <term> 1869 <mallctl>stats.arenas.<i>.small.ndalloc</mallctl> 1870 (<type>uint64_t</type>) 1871 <literal>r-</literal> 1872 [<option>--enable-stats</option>] 1873 </term> 1874 <listitem><para>Cumulative number of small objects returned to bins. 1875 </para></listitem> 1876 </varlistentry> 1877 1878 <varlistentry id="stats.arenas.i.small.nrequests"> 1879 <term> 1880 <mallctl>stats.arenas.<i>.small.nrequests</mallctl> 1881 (<type>uint64_t</type>) 1882 <literal>r-</literal> 1883 [<option>--enable-stats</option>] 1884 </term> 1885 <listitem><para>Cumulative number of small allocation requests. 1886 </para></listitem> 1887 </varlistentry> 1888 1889 <varlistentry id="stats.arenas.i.large.allocated"> 1890 <term> 1891 <mallctl>stats.arenas.<i>.large.allocated</mallctl> 1892 (<type>size_t</type>) 1893 <literal>r-</literal> 1894 [<option>--enable-stats</option>] 1895 </term> 1896 <listitem><para>Number of bytes currently allocated by large objects. 1897 </para></listitem> 1898 </varlistentry> 1899 1900 <varlistentry id="stats.arenas.i.large.nmalloc"> 1901 <term> 1902 <mallctl>stats.arenas.<i>.large.nmalloc</mallctl> 1903 (<type>uint64_t</type>) 1904 <literal>r-</literal> 1905 [<option>--enable-stats</option>] 1906 </term> 1907 <listitem><para>Cumulative number of large allocation requests served 1908 directly by the arena.</para></listitem> 1909 </varlistentry> 1910 1911 <varlistentry id="stats.arenas.i.large.ndalloc"> 1912 <term> 1913 <mallctl>stats.arenas.<i>.large.ndalloc</mallctl> 1914 (<type>uint64_t</type>) 1915 <literal>r-</literal> 1916 [<option>--enable-stats</option>] 1917 </term> 1918 <listitem><para>Cumulative number of large deallocation requests served 1919 directly by the arena.</para></listitem> 1920 </varlistentry> 1921 1922 <varlistentry id="stats.arenas.i.large.nrequests"> 1923 <term> 1924 <mallctl>stats.arenas.<i>.large.nrequests</mallctl> 1925 (<type>uint64_t</type>) 1926 <literal>r-</literal> 1927 [<option>--enable-stats</option>] 1928 </term> 1929 <listitem><para>Cumulative number of large allocation requests. 1930 </para></listitem> 1931 </varlistentry> 1932 1933 <varlistentry id="stats.arenas.i.bins.j.allocated"> 1934 <term> 1935 <mallctl>stats.arenas.<i>.bins.<j>.allocated</mallctl> 1936 (<type>size_t</type>) 1937 <literal>r-</literal> 1938 [<option>--enable-stats</option>] 1939 </term> 1940 <listitem><para>Current number of bytes allocated by 1941 bin.</para></listitem> 1942 </varlistentry> 1943 1944 <varlistentry id="stats.arenas.i.bins.j.nmalloc"> 1945 <term> 1946 <mallctl>stats.arenas.<i>.bins.<j>.nmalloc</mallctl> 1947 (<type>uint64_t</type>) 1948 <literal>r-</literal> 1949 [<option>--enable-stats</option>] 1950 </term> 1951 <listitem><para>Cumulative number of allocations served by bin. 1952 </para></listitem> 1953 </varlistentry> 1954 1955 <varlistentry id="stats.arenas.i.bins.j.ndalloc"> 1956 <term> 1957 <mallctl>stats.arenas.<i>.bins.<j>.ndalloc</mallctl> 1958 (<type>uint64_t</type>) 1959 <literal>r-</literal> 1960 [<option>--enable-stats</option>] 1961 </term> 1962 <listitem><para>Cumulative number of allocations returned to bin. 1963 </para></listitem> 1964 </varlistentry> 1965 1966 <varlistentry id="stats.arenas.i.bins.j.nrequests"> 1967 <term> 1968 <mallctl>stats.arenas.<i>.bins.<j>.nrequests</mallctl> 1969 (<type>uint64_t</type>) 1970 <literal>r-</literal> 1971 [<option>--enable-stats</option>] 1972 </term> 1973 <listitem><para>Cumulative number of allocation 1974 requests.</para></listitem> 1975 </varlistentry> 1976 1977 <varlistentry id="stats.arenas.i.bins.j.nfills"> 1978 <term> 1979 <mallctl>stats.arenas.<i>.bins.<j>.nfills</mallctl> 1980 (<type>uint64_t</type>) 1981 <literal>r-</literal> 1982 [<option>--enable-stats</option> <option>--enable-tcache</option>] 1983 </term> 1984 <listitem><para>Cumulative number of tcache fills.</para></listitem> 1985 </varlistentry> 1986 1987 <varlistentry id="stats.arenas.i.bins.j.nflushes"> 1988 <term> 1989 <mallctl>stats.arenas.<i>.bins.<j>.nflushes</mallctl> 1990 (<type>uint64_t</type>) 1991 <literal>r-</literal> 1992 [<option>--enable-stats</option> <option>--enable-tcache</option>] 1993 </term> 1994 <listitem><para>Cumulative number of tcache flushes.</para></listitem> 1995 </varlistentry> 1996 1997 <varlistentry id="stats.arenas.i.bins.j.nruns"> 1998 <term> 1999 <mallctl>stats.arenas.<i>.bins.<j>.nruns</mallctl> 2000 (<type>uint64_t</type>) 2001 <literal>r-</literal> 2002 [<option>--enable-stats</option>] 2003 </term> 2004 <listitem><para>Cumulative number of runs created.</para></listitem> 2005 </varlistentry> 2006 2007 <varlistentry id="stats.arenas.i.bins.j.nreruns"> 2008 <term> 2009 <mallctl>stats.arenas.<i>.bins.<j>.nreruns</mallctl> 2010 (<type>uint64_t</type>) 2011 <literal>r-</literal> 2012 [<option>--enable-stats</option>] 2013 </term> 2014 <listitem><para>Cumulative number of times the current run from which 2015 to allocate changed.</para></listitem> 2016 </varlistentry> 2017 2018 <varlistentry id="stats.arenas.i.bins.j.curruns"> 2019 <term> 2020 <mallctl>stats.arenas.<i>.bins.<j>.curruns</mallctl> 2021 (<type>size_t</type>) 2022 <literal>r-</literal> 2023 [<option>--enable-stats</option>] 2024 </term> 2025 <listitem><para>Current number of runs.</para></listitem> 2026 </varlistentry> 2027 2028 <varlistentry id="stats.arenas.i.lruns.j.nmalloc"> 2029 <term> 2030 <mallctl>stats.arenas.<i>.lruns.<j>.nmalloc</mallctl> 2031 (<type>uint64_t</type>) 2032 <literal>r-</literal> 2033 [<option>--enable-stats</option>] 2034 </term> 2035 <listitem><para>Cumulative number of allocation requests for this size 2036 class served directly by the arena.</para></listitem> 2037 </varlistentry> 2038 2039 <varlistentry id="stats.arenas.i.lruns.j.ndalloc"> 2040 <term> 2041 <mallctl>stats.arenas.<i>.lruns.<j>.ndalloc</mallctl> 2042 (<type>uint64_t</type>) 2043 <literal>r-</literal> 2044 [<option>--enable-stats</option>] 2045 </term> 2046 <listitem><para>Cumulative number of deallocation requests for this 2047 size class served directly by the arena.</para></listitem> 2048 </varlistentry> 2049 2050 <varlistentry id="stats.arenas.i.lruns.j.nrequests"> 2051 <term> 2052 <mallctl>stats.arenas.<i>.lruns.<j>.nrequests</mallctl> 2053 (<type>uint64_t</type>) 2054 <literal>r-</literal> 2055 [<option>--enable-stats</option>] 2056 </term> 2057 <listitem><para>Cumulative number of allocation requests for this size 2058 class.</para></listitem> 2059 </varlistentry> 2060 2061 <varlistentry id="stats.arenas.i.lruns.j.curruns"> 2062 <term> 2063 <mallctl>stats.arenas.<i>.lruns.<j>.curruns</mallctl> 2064 (<type>size_t</type>) 2065 <literal>r-</literal> 2066 [<option>--enable-stats</option>] 2067 </term> 2068 <listitem><para>Current number of runs for this size class. 2069 </para></listitem> 2070 </varlistentry> 2071 </variablelist> 2072 </refsect1> 2073 <refsect1 id="debugging_malloc_problems"> 2074 <title>DEBUGGING MALLOC PROBLEMS</title> 2075 <para>When debugging, it is a good idea to configure/build jemalloc with 2076 the <option>--enable-debug</option> and <option>--enable-fill</option> 2077 options, and recompile the program with suitable options and symbols for 2078 debugger support. When so configured, jemalloc incorporates a wide variety 2079 of run-time assertions that catch application errors such as double-free, 2080 write-after-free, etc.</para> 2081 2082 <para>Programs often accidentally depend on “uninitialized” 2083 memory actually being filled with zero bytes. Junk filling 2084 (see the <link linkend="opt.junk"><mallctl>opt.junk</mallctl></link> 2085 option) tends to expose such bugs in the form of obviously incorrect 2086 results and/or coredumps. Conversely, zero 2087 filling (see the <link 2088 linkend="opt.zero"><mallctl>opt.zero</mallctl></link> option) eliminates 2089 the symptoms of such bugs. Between these two options, it is usually 2090 possible to quickly detect, diagnose, and eliminate such bugs.</para> 2091 2092 <para>This implementation does not provide much detail about the problems 2093 it detects, because the performance impact for storing such information 2094 would be prohibitive. However, jemalloc does integrate with the most 2095 excellent <ulink url="http://valgrind.org/">Valgrind</ulink> tool if the 2096 <option>--enable-valgrind</option> configuration option is enabled.</para> 2097 </refsect1> 2098 <refsect1 id="diagnostic_messages"> 2099 <title>DIAGNOSTIC MESSAGES</title> 2100 <para>If any of the memory allocation/deallocation functions detect an 2101 error or warning condition, a message will be printed to file descriptor 2102 <constant>STDERR_FILENO</constant>. Errors will result in the process 2103 dumping core. If the <link 2104 linkend="opt.abort"><mallctl>opt.abort</mallctl></link> option is set, most 2105 warnings are treated as errors.</para> 2106 2107 <para>The <varname>malloc_message</varname> variable allows the programmer 2108 to override the function which emits the text strings forming the errors 2109 and warnings if for some reason the <constant>STDERR_FILENO</constant> file 2110 descriptor is not suitable for this. 2111 <function>malloc_message<parameter/></function> takes the 2112 <parameter>cbopaque</parameter> pointer argument that is 2113 <constant>NULL</constant> unless overridden by the arguments in a call to 2114 <function>malloc_stats_print<parameter/></function>, followed by a string 2115 pointer. Please note that doing anything which tries to allocate memory in 2116 this function is likely to result in a crash or deadlock.</para> 2117 2118 <para>All messages are prefixed by 2119 “<computeroutput><jemalloc>: </computeroutput>”.</para> 2120 </refsect1> 2121 <refsect1 id="return_values"> 2122 <title>RETURN VALUES</title> 2123 <refsect2> 2124 <title>Standard API</title> 2125 <para>The <function>malloc<parameter/></function> and 2126 <function>calloc<parameter/></function> functions return a pointer to the 2127 allocated memory if successful; otherwise a <constant>NULL</constant> 2128 pointer is returned and <varname>errno</varname> is set to 2129 <errorname>ENOMEM</errorname>.</para> 2130 2131 <para>The <function>posix_memalign<parameter/></function> function 2132 returns the value 0 if successful; otherwise it returns an error value. 2133 The <function>posix_memalign<parameter/></function> function will fail 2134 if: 2135 <variablelist> 2136 <varlistentry> 2137 <term><errorname>EINVAL</errorname></term> 2138 2139 <listitem><para>The <parameter>alignment</parameter> parameter is 2140 not a power of 2 at least as large as 2141 <code language="C">sizeof(<type>void *</type>)</code>. 2142 </para></listitem> 2143 </varlistentry> 2144 <varlistentry> 2145 <term><errorname>ENOMEM</errorname></term> 2146 2147 <listitem><para>Memory allocation error.</para></listitem> 2148 </varlistentry> 2149 </variablelist> 2150 </para> 2151 2152 <para>The <function>aligned_alloc<parameter/></function> function returns 2153 a pointer to the allocated memory if successful; otherwise a 2154 <constant>NULL</constant> pointer is returned and 2155 <varname>errno</varname> is set. The 2156 <function>aligned_alloc<parameter/></function> function will fail if: 2157 <variablelist> 2158 <varlistentry> 2159 <term><errorname>EINVAL</errorname></term> 2160 2161 <listitem><para>The <parameter>alignment</parameter> parameter is 2162 not a power of 2. 2163 </para></listitem> 2164 </varlistentry> 2165 <varlistentry> 2166 <term><errorname>ENOMEM</errorname></term> 2167 2168 <listitem><para>Memory allocation error.</para></listitem> 2169 </varlistentry> 2170 </variablelist> 2171 </para> 2172 2173 <para>The <function>realloc<parameter/></function> function returns a 2174 pointer, possibly identical to <parameter>ptr</parameter>, to the 2175 allocated memory if successful; otherwise a <constant>NULL</constant> 2176 pointer is returned, and <varname>errno</varname> is set to 2177 <errorname>ENOMEM</errorname> if the error was the result of an 2178 allocation failure. The <function>realloc<parameter/></function> 2179 function always leaves the original buffer intact when an error occurs. 2180 </para> 2181 2182 <para>The <function>free<parameter/></function> function returns no 2183 value.</para> 2184 </refsect2> 2185 <refsect2> 2186 <title>Non-standard API</title> 2187 <para>The <function>mallocx<parameter/></function> and 2188 <function>rallocx<parameter/></function> functions return a pointer to 2189 the allocated memory if successful; otherwise a <constant>NULL</constant> 2190 pointer is returned to indicate insufficient contiguous memory was 2191 available to service the allocation request. </para> 2192 2193 <para>The <function>xallocx<parameter/></function> function returns the 2194 real size of the resulting resized allocation pointed to by 2195 <parameter>ptr</parameter>, which is a value less than 2196 <parameter>size</parameter> if the allocation could not be adequately 2197 grown in place. </para> 2198 2199 <para>The <function>sallocx<parameter/></function> function returns the 2200 real size of the allocation pointed to by <parameter>ptr</parameter>. 2201 </para> 2202 2203 <para>The <function>nallocx<parameter/></function> returns the real size 2204 that would result from a successful equivalent 2205 <function>mallocx<parameter/></function> function call, or zero if 2206 insufficient memory is available to perform the size computation. </para> 2207 2208 <para>The <function>mallctl<parameter/></function>, 2209 <function>mallctlnametomib<parameter/></function>, and 2210 <function>mallctlbymib<parameter/></function> functions return 0 on 2211 success; otherwise they return an error value. The functions will fail 2212 if: 2213 <variablelist> 2214 <varlistentry> 2215 <term><errorname>EINVAL</errorname></term> 2216 2217 <listitem><para><parameter>newp</parameter> is not 2218 <constant>NULL</constant>, and <parameter>newlen</parameter> is too 2219 large or too small. Alternatively, <parameter>*oldlenp</parameter> 2220 is too large or too small; in this case as much data as possible 2221 are read despite the error.</para></listitem> 2222 </varlistentry> 2223 <varlistentry> 2224 <term><errorname>ENOENT</errorname></term> 2225 2226 <listitem><para><parameter>name</parameter> or 2227 <parameter>mib</parameter> specifies an unknown/invalid 2228 value.</para></listitem> 2229 </varlistentry> 2230 <varlistentry> 2231 <term><errorname>EPERM</errorname></term> 2232 2233 <listitem><para>Attempt to read or write void value, or attempt to 2234 write read-only value.</para></listitem> 2235 </varlistentry> 2236 <varlistentry> 2237 <term><errorname>EAGAIN</errorname></term> 2238 2239 <listitem><para>A memory allocation failure 2240 occurred.</para></listitem> 2241 </varlistentry> 2242 <varlistentry> 2243 <term><errorname>EFAULT</errorname></term> 2244 2245 <listitem><para>An interface with side effects failed in some way 2246 not directly related to <function>mallctl*<parameter/></function> 2247 read/write processing.</para></listitem> 2248 </varlistentry> 2249 </variablelist> 2250 </para> 2251 2252 <para>The <function>malloc_usable_size<parameter/></function> function 2253 returns the usable size of the allocation pointed to by 2254 <parameter>ptr</parameter>. </para> 2255 </refsect2> 2256 <refsect2> 2257 <title>Experimental API</title> 2258 <para>The <function>allocm<parameter/></function>, 2259 <function>rallocm<parameter/></function>, 2260 <function>sallocm<parameter/></function>, 2261 <function>dallocm<parameter/></function>, and 2262 <function>nallocm<parameter/></function> functions return 2263 <constant>ALLOCM_SUCCESS</constant> on success; otherwise they return an 2264 error value. The <function>allocm<parameter/></function>, 2265 <function>rallocm<parameter/></function>, and 2266 <function>nallocm<parameter/></function> functions will fail if: 2267 <variablelist> 2268 <varlistentry> 2269 <term><errorname>ALLOCM_ERR_OOM</errorname></term> 2270 2271 <listitem><para>Out of memory. Insufficient contiguous memory was 2272 available to service the allocation request. The 2273 <function>allocm<parameter/></function> function additionally sets 2274 <parameter>*ptr</parameter> to <constant>NULL</constant>, whereas 2275 the <function>rallocm<parameter/></function> function leaves 2276 <constant>*ptr</constant> unmodified.</para></listitem> 2277 </varlistentry> 2278 </variablelist> 2279 The <function>rallocm<parameter/></function> function will also 2280 fail if: 2281 <variablelist> 2282 <varlistentry> 2283 <term><errorname>ALLOCM_ERR_NOT_MOVED</errorname></term> 2284 2285 <listitem><para><constant>ALLOCM_NO_MOVE</constant> was specified, 2286 but the reallocation request could not be serviced without moving 2287 the object.</para></listitem> 2288 </varlistentry> 2289 </variablelist> 2290 </para> 2291 </refsect2> 2292 </refsect1> 2293 <refsect1 id="environment"> 2294 <title>ENVIRONMENT</title> 2295 <para>The following environment variable affects the execution of the 2296 allocation functions: 2297 <variablelist> 2298 <varlistentry> 2299 <term><envar>MALLOC_CONF</envar></term> 2300 2301 <listitem><para>If the environment variable 2302 <envar>MALLOC_CONF</envar> is set, the characters it contains 2303 will be interpreted as options.</para></listitem> 2304 </varlistentry> 2305 </variablelist> 2306 </para> 2307 </refsect1> 2308 <refsect1 id="examples"> 2309 <title>EXAMPLES</title> 2310 <para>To dump core whenever a problem occurs: 2311 <screen>ln -s 'abort:true' /etc/malloc.conf</screen> 2312 </para> 2313 <para>To specify in the source a chunk size that is 16 MiB: 2314 <programlisting language="C"><![CDATA[ 2315malloc_conf = "lg_chunk:24";]]></programlisting></para> 2316 </refsect1> 2317 <refsect1 id="see_also"> 2318 <title>SEE ALSO</title> 2319 <para><citerefentry><refentrytitle>madvise</refentrytitle> 2320 <manvolnum>2</manvolnum></citerefentry>, 2321 <citerefentry><refentrytitle>mmap</refentrytitle> 2322 <manvolnum>2</manvolnum></citerefentry>, 2323 <citerefentry><refentrytitle>sbrk</refentrytitle> 2324 <manvolnum>2</manvolnum></citerefentry>, 2325 <citerefentry><refentrytitle>utrace</refentrytitle> 2326 <manvolnum>2</manvolnum></citerefentry>, 2327 <citerefentry><refentrytitle>alloca</refentrytitle> 2328 <manvolnum>3</manvolnum></citerefentry>, 2329 <citerefentry><refentrytitle>atexit</refentrytitle> 2330 <manvolnum>3</manvolnum></citerefentry>, 2331 <citerefentry><refentrytitle>getpagesize</refentrytitle> 2332 <manvolnum>3</manvolnum></citerefentry></para> 2333 </refsect1> 2334 <refsect1 id="standards"> 2335 <title>STANDARDS</title> 2336 <para>The <function>malloc<parameter/></function>, 2337 <function>calloc<parameter/></function>, 2338 <function>realloc<parameter/></function>, and 2339 <function>free<parameter/></function> functions conform to ISO/IEC 2340 9899:1990 (“ISO C90”).</para> 2341 2342 <para>The <function>posix_memalign<parameter/></function> function conforms 2343 to IEEE Std 1003.1-2001 (“POSIX.1”).</para> 2344 </refsect1> 2345</refentry> 2346