• file
• revisions
• annotate
• diff
• comparison
• raw

memory/jemalloc/src/doc/jemalloc.xml.in@6474c204b198 (annotated)

memory/jemalloc/src/doc/jemalloc.xml.in

Wed, 31 Dec 2014 06:09:35 +0100

author

Michael Schloh von Bennewitz <michael@schloh.com>

date

Wed, 31 Dec 2014 06:09:35 +0100

changeset 0

6474c204b198

permissions

-rw-r--r--

Cloned upstream origin tor-browser at tor-browser-31.3.0esr-4.5-1-build1
revision ID fc1c9ff7c1b2defdbc039f12214767608f46423f for hacking purpose.

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