1 <?xml version='
1.0' encoding='UTF-
8'
?>
2 <?xml-stylesheet type=
"text/xsl"
3 href=
"http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl"?>
4 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.4//EN"
5 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
10 <title>User Manual
</title>
11 <productname>jemalloc
</productname>
12 <releaseinfo role=
"version">@jemalloc_version@
</releaseinfo>
15 <firstname>Jason
</firstname>
16 <surname>Evans
</surname>
17 <personblurb>Author
</personblurb>
22 <refentrytitle>JEMALLOC
</refentrytitle>
23 <manvolnum>3</manvolnum>
26 <refdescriptor>jemalloc
</refdescriptor>
27 <refname>jemalloc
</refname>
28 <!-- Each refname causes a man page file to be created. Only if this were
29 the system malloc(3) implementation would these files be appropriate.
30 <refname>malloc</refname>
31 <refname>calloc</refname>
32 <refname>posix_memalign</refname>
33 <refname>realloc</refname>
34 <refname>free</refname>
35 <refname>malloc_usable_size</refname>
36 <refname>malloc_stats_print</refname>
37 <refname>mallctl</refname>
38 <refname>mallctlnametomib</refname>
39 <refname>mallctlbymib</refname>
40 <refname>allocm</refname>
41 <refname>rallocm</refname>
42 <refname>sallocm</refname>
43 <refname>dallocm</refname>
45 <refpurpose>general purpose memory allocation functions
</refpurpose>
47 <refsect1 id=
"library">
48 <title>LIBRARY
</title>
49 <para>This manual describes jemalloc @jemalloc_version@. More information
50 can be found at the
<ulink
51 url=
"http://www.canonware.com/jemalloc/">jemalloc website
</ulink>.
</para>
54 <title>SYNOPSIS
</title>
56 <funcsynopsisinfo>#include
<<filename class=
"headerfile">stdlib.h
</filename>>
57 #include
<<filename class=
"headerfile">jemalloc/jemalloc.h
</filename>></funcsynopsisinfo>
59 <title>Standard API
</title>
61 <funcdef>void *
<function>malloc
</function></funcdef>
62 <paramdef>size_t
<parameter>size
</parameter></paramdef>
65 <funcdef>void *
<function>calloc
</function></funcdef>
66 <paramdef>size_t
<parameter>number
</parameter></paramdef>
67 <paramdef>size_t
<parameter>size
</parameter></paramdef>
70 <funcdef>int
<function>posix_memalign
</function></funcdef>
71 <paramdef>void **
<parameter>ptr
</parameter></paramdef>
72 <paramdef>size_t
<parameter>alignment
</parameter></paramdef>
73 <paramdef>size_t
<parameter>size
</parameter></paramdef>
76 <funcdef>void *
<function>realloc
</function></funcdef>
77 <paramdef>void *
<parameter>ptr
</parameter></paramdef>
78 <paramdef>size_t
<parameter>size
</parameter></paramdef>
81 <funcdef>void
<function>free
</function></funcdef>
82 <paramdef>void *
<parameter>ptr
</parameter></paramdef>
86 <title>Non-standard API
</title>
88 <funcdef>size_t
<function>malloc_usable_size
</function></funcdef>
89 <paramdef>const void *
<parameter>ptr
</parameter></paramdef>
92 <funcdef>void
<function>malloc_stats_print
</function></funcdef>
93 <paramdef>void
<parameter>(*write_cb)
</parameter>
94 <funcparams>void *, const char *
</funcparams>
96 <paramdef>void *
<parameter>cbopaque
</parameter></paramdef>
97 <paramdef>const char *
<parameter>opts
</parameter></paramdef>
100 <funcdef>int
<function>mallctl
</function></funcdef>
101 <paramdef>const char *
<parameter>name
</parameter></paramdef>
102 <paramdef>void *
<parameter>oldp
</parameter></paramdef>
103 <paramdef>size_t *
<parameter>oldlenp
</parameter></paramdef>
104 <paramdef>void *
<parameter>newp
</parameter></paramdef>
105 <paramdef>size_t
<parameter>newlen
</parameter></paramdef>
108 <funcdef>int
<function>mallctlnametomib
</function></funcdef>
109 <paramdef>const char *
<parameter>name
</parameter></paramdef>
110 <paramdef>size_t *
<parameter>mibp
</parameter></paramdef>
111 <paramdef>size_t *
<parameter>miblenp
</parameter></paramdef>
114 <funcdef>int
<function>mallctlbymib
</function></funcdef>
115 <paramdef>const size_t *
<parameter>mib
</parameter></paramdef>
116 <paramdef>size_t
<parameter>miblen
</parameter></paramdef>
117 <paramdef>void *
<parameter>oldp
</parameter></paramdef>
118 <paramdef>size_t *
<parameter>oldlenp
</parameter></paramdef>
119 <paramdef>void *
<parameter>newp
</parameter></paramdef>
120 <paramdef>size_t
<parameter>newlen
</parameter></paramdef>
123 <funcdef>void
<function>(*malloc_message)
</function></funcdef>
124 <paramdef>void *
<parameter>cbopaque
</parameter></paramdef>
125 <paramdef>const char *
<parameter>s
</parameter></paramdef>
127 <para><type>const char *
</type><varname>malloc_conf
</varname>;
</para>
130 <title>Experimental API
</title>
132 <funcdef>int
<function>allocm
</function></funcdef>
133 <paramdef>void **
<parameter>ptr
</parameter></paramdef>
134 <paramdef>size_t *
<parameter>rsize
</parameter></paramdef>
135 <paramdef>size_t
<parameter>size
</parameter></paramdef>
136 <paramdef>int
<parameter>flags
</parameter></paramdef>
139 <funcdef>int
<function>rallocm
</function></funcdef>
140 <paramdef>void **
<parameter>ptr
</parameter></paramdef>
141 <paramdef>size_t *
<parameter>rsize
</parameter></paramdef>
142 <paramdef>size_t
<parameter>size
</parameter></paramdef>
143 <paramdef>size_t
<parameter>extra
</parameter></paramdef>
144 <paramdef>int
<parameter>flags
</parameter></paramdef>
147 <funcdef>int
<function>sallocm
</function></funcdef>
148 <paramdef>const void *
<parameter>ptr
</parameter></paramdef>
149 <paramdef>size_t *
<parameter>rsize
</parameter></paramdef>
150 <paramdef>int
<parameter>flags
</parameter></paramdef>
153 <funcdef>int
<function>dallocm
</function></funcdef>
154 <paramdef>void *
<parameter>ptr
</parameter></paramdef>
155 <paramdef>int
<parameter>flags
</parameter></paramdef>
160 <refsect1 id=
"description">
161 <title>DESCRIPTION
</title>
163 <title>Standard API
</title>
165 <para>The
<function>malloc
<parameter/></function> function allocates
166 <parameter>size
</parameter> bytes of uninitialized memory. The allocated
167 space is suitably aligned (after possible pointer coercion) for storage
168 of any type of object.
</para>
170 <para>The
<function>calloc
<parameter/></function> function allocates
171 space for
<parameter>number
</parameter> objects, each
172 <parameter>size
</parameter> bytes in length. The result is identical to
173 calling
<function>malloc
<parameter/></function> with an argument of
174 <parameter>number
</parameter> *
<parameter>size
</parameter>, with the
175 exception that the allocated memory is explicitly initialized to zero
178 <para>The
<function>posix_memalign
<parameter/></function> function
179 allocates
<parameter>size
</parameter> bytes of memory such that the
180 allocation's base address is an even multiple of
181 <parameter>alignment
</parameter>, and returns the allocation in the value
182 pointed to by
<parameter>ptr
</parameter>. The requested
183 <parameter>alignment
</parameter> must be a power of
2 at least as large
184 as
<code language=
"C">sizeof(
<type>void *
</type>)
</code>.
</para>
186 <para>The
<function>realloc
<parameter/></function> function changes the
187 size of the previously allocated memory referenced by
188 <parameter>ptr
</parameter> to
<parameter>size
</parameter> bytes. The
189 contents of the memory are unchanged up to the lesser of the new and old
190 sizes. If the new size is larger, the contents of the newly allocated
191 portion of the memory are undefined. Upon success, the memory referenced
192 by
<parameter>ptr
</parameter> is freed and a pointer to the newly
193 allocated memory is returned. Note that
194 <function>realloc
<parameter/></function> may move the memory allocation,
195 resulting in a different return value than
<parameter>ptr
</parameter>.
196 If
<parameter>ptr
</parameter> is
<constant>NULL
</constant>, the
197 <function>realloc
<parameter/></function> function behaves identically to
198 <function>malloc
<parameter/></function> for the specified size.
</para>
200 <para>The
<function>free
<parameter/></function> function causes the
201 allocated memory referenced by
<parameter>ptr
</parameter> to be made
202 available for future allocations. If
<parameter>ptr
</parameter> is
203 <constant>NULL
</constant>, no action occurs.
</para>
206 <title>Non-standard API
</title>
208 <para>The
<function>malloc_usable_size
<parameter/></function> function
209 returns the usable size of the allocation pointed to by
210 <parameter>ptr
</parameter>. The return value may be larger than the size
211 that was requested during allocation. The
212 <function>malloc_usable_size
<parameter/></function> function is not a
213 mechanism for in-place
<function>realloc
<parameter/></function>; rather
214 it is provided solely as a tool for introspection purposes. Any
215 discrepancy between the requested allocation size and the size reported
216 by
<function>malloc_usable_size
<parameter/></function> should not be
217 depended on, since such behavior is entirely implementation-dependent.
220 <para>The
<function>malloc_stats_print
<parameter/></function> function
221 writes human-readable summary statistics via the
222 <parameter>write_cb
</parameter> callback function pointer and
223 <parameter>cbopaque
</parameter> data passed to
224 <parameter>write_cb
</parameter>, or
225 <function>malloc_message
<parameter/></function> if
226 <parameter>write_cb
</parameter> is
<constant>NULL
</constant>. This
227 function can be called repeatedly. General information that never
228 changes during execution can be omitted by specifying "g" as a character
229 within the
<parameter>opts
</parameter> string. Note that
230 <function>malloc_message
<parameter/></function> uses the
231 <function>mallctl*
<parameter/></function> functions internally, so
232 inconsistent statistics can be reported if multiple threads use these
233 functions simultaneously. If
<option>--enable-stats
</option> is
234 specified during configuration,
“m
” and
“a
” can
235 be specified to omit merged arena and per arena statistics, respectively;
236 “b
” and
“l
” can be specified to omit per size
237 class statistics for bins and large objects, respectively. Unrecognized
238 characters are silently ignored. Note that thread caching may prevent
239 some statistics from being completely up to date, since extra locking
240 would be required to merge counters that track thread cache operations.
243 <para>The
<function>mallctl
<parameter/></function> function provides a
244 general interface for introspecting the memory allocator, as well as
245 setting modifiable parameters and triggering actions. The
246 period-separated
<parameter>name
</parameter> argument specifies a
247 location in a tree-structured namespace; see the
<xref
248 linkend=
"mallctl_namespace" xrefstyle=
"template:%t"/> section for
249 documentation on the tree contents. To read a value, pass a pointer via
250 <parameter>oldp
</parameter> to adequate space to contain the value, and a
251 pointer to its length via
<parameter>oldlenp
</parameter>; otherwise pass
252 <constant>NULL
</constant> and
<constant>NULL
</constant>. Similarly, to
253 write a value, pass a pointer to the value via
254 <parameter>newp
</parameter>, and its length via
255 <parameter>newlen
</parameter>; otherwise pass
<constant>NULL
</constant>
256 and
<constant>0</constant>.
</para>
258 <para>The
<function>mallctlnametomib
<parameter/></function> function
259 provides a way to avoid repeated name lookups for applications that
260 repeatedly query the same portion of the namespace, by translating a name
261 to a
“Management Information Base
” (MIB) that can be passed
262 repeatedly to
<function>mallctlbymib
<parameter/></function>. Upon
263 successful return from
<function>mallctlnametomib
<parameter/></function>,
264 <parameter>mibp
</parameter> contains an array of
265 <parameter>*miblenp
</parameter> integers, where
266 <parameter>*miblenp
</parameter> is the lesser of the number of components
267 in
<parameter>name
</parameter> and the input value of
268 <parameter>*miblenp
</parameter>. Thus it is possible to pass a
269 <parameter>*miblenp
</parameter> that is smaller than the number of
270 period-separated name components, which results in a partial MIB that can
271 be used as the basis for constructing a complete MIB. For name
272 components that are integers (e.g. the
2 in
274 linkend=
"arenas.bin.i.size"><mallctl>arenas.bin
.2.size
</mallctl></link>),
275 the corresponding MIB component will always be that integer. Therefore,
276 it is legitimate to construct code like the following:
<programlisting
277 language=
"C"><![CDATA[
284 mallctl("arenas.nbins", &nbins, &len, NULL,
0);
287 mallnametomib("arenas.bin
.0.size", mib, &miblen);
288 for (i =
0; i < nbins; i++) {
292 len = sizeof(bin_size);
293 mallctlbymib(mib, miblen, &bin_size, &len, NULL,
0);
294 /* Do something with bin_size... */
295 }]]
></programlisting></para>
298 <title>Experimental API
</title>
299 <para>The experimental API is subject to change or removal without regard
300 for backward compatibility.
</para>
302 <para>The
<function>allocm
<parameter/></function>,
303 <function>rallocm
<parameter/></function>,
304 <function>sallocm
<parameter/></function>, and
305 <function>dallocm
<parameter/></function> functions all have a
306 <parameter>flags
</parameter> argument that can be used to specify
307 options. The functions only check the options that are contextually
308 relevant. Use bitwise or (
<code language=
"C">|
</code>) operations to
309 specify one or more of the following:
312 <term><constant>ALLOCM_LG_ALIGN(
<parameter>la
</parameter>)
315 <listitem><para>Align the memory allocation to start at an address
316 that is a multiple of
<code language=
"C">(
1 <<
317 <parameter>la
</parameter>)
</code>. This macro does not validate
318 that
<parameter>la
</parameter> is within the valid
319 range.
</para></listitem>
322 <term><constant>ALLOCM_ALIGN(
<parameter>a
</parameter>)
325 <listitem><para>Align the memory allocation to start at an address
326 that is a multiple of
<parameter>a
</parameter>, where
327 <parameter>a
</parameter> is a power of two. This macro does not
328 validate that
<parameter>a
</parameter> is a power of
2.
332 <term><constant>ALLOCM_ZERO
</constant></term>
334 <listitem><para>Initialize newly allocated memory to contain zero
335 bytes. In the growing reallocation case, the real size prior to
336 reallocation defines the boundary between untouched bytes and those
337 that are initialized to contain zero bytes. If this option is
338 absent, newly allocated memory is uninitialized.
</para></listitem>
341 <term><constant>ALLOCM_NO_MOVE
</constant></term>
343 <listitem><para>For reallocation, fail rather than moving the
344 object. This constraint can apply to both growth and
345 shrinkage.
</para></listitem>
350 <para>The
<function>allocm
<parameter/></function> function allocates at
351 least
<parameter>size
</parameter> bytes of memory, sets
352 <parameter>*ptr
</parameter> to the base address of the allocation, and
353 sets
<parameter>*rsize
</parameter> to the real size of the allocation if
354 <parameter>rsize
</parameter> is not
<constant>NULL
</constant>.
</para>
356 <para>The
<function>rallocm
<parameter/></function> function resizes the
357 allocation at
<parameter>*ptr
</parameter> to be at least
358 <parameter>size
</parameter> bytes, sets
<parameter>*ptr
</parameter> to
359 the base address of the allocation if it moved, and sets
360 <parameter>*rsize
</parameter> to the real size of the allocation if
361 <parameter>rsize
</parameter> is not
<constant>NULL
</constant>. If
362 <parameter>extra
</parameter> is non-zero, an attempt is made to resize
363 the allocation to be at least
<code
364 language=
"C"><parameter>size
</parameter> +
365 <parameter>extra
</parameter>)
</code> bytes, though inability to allocate
366 the extra byte(s) will not by itself result in failure. Behavior is
367 undefined if
<code language=
"C">(
<parameter>size
</parameter> +
368 <parameter>extra
</parameter> >
369 <constant>SIZE_T_MAX
</constant>)
</code>.
</para>
371 <para>The
<function>sallocm
<parameter/></function> function sets
372 <parameter>*rsize
</parameter> to the real size of the allocation.
</para>
374 <para>The
<function>dallocm
<parameter/></function> function causes the
375 memory referenced by
<parameter>ptr
</parameter> to be made available for
376 future allocations.
</para>
379 <refsect1 id=
"tuning">
380 <title>TUNING
</title>
381 <para>Once, when the first call is made to one of the memory allocation
382 routines, the allocator initializes its internals based in part on various
383 options that can be specified at compile- or run-time.
</para>
385 <para>The string pointed to by the global variable
386 <varname>malloc_conf
</varname>, the
“name
” of the file
387 referenced by the symbolic link named
<filename
388 class=
"symlink">/etc/malloc.conf
</filename>, and the value of the
389 environment variable
<envar>MALLOC_CONF
</envar>, will be interpreted, in
390 that order, from left to right as options.
</para>
392 <para>An options string is a comma-separated list of option:value pairs.
393 There is one key corresponding to each
<link
394 linkend=
"opt.abort"><mallctl>opt.*
</mallctl></link> mallctl (see the
<xref
395 linkend=
"mallctl_namespace" xrefstyle=
"template:%t"/> section for options
396 documentation). For example,
<literal>abort:true,narenas:
1</literal> sets
397 the
<link linkend=
"opt.abort"><mallctl>opt.abort
</mallctl></link> and
<link
398 linkend=
"opt.narenas"><mallctl>opt.narenas
</mallctl></link> options. Some
399 options have boolean values (true/false), others have integer values (base
400 8,
10, or
16, depending on prefix), and yet others have raw string
403 <refsect1 id=
"implementation_notes">
404 <title>IMPLEMENTATION NOTES
</title>
405 <para>Traditionally, allocators have used
406 <citerefentry><refentrytitle>sbrk
</refentrytitle>
407 <manvolnum>2</manvolnum></citerefentry> to obtain memory, which is
408 suboptimal for several reasons, including race conditions, increased
409 fragmentation, and artificial limitations on maximum usable memory. If
410 <option>--enable-dss
</option> is specified during configuration, this
411 allocator uses both
<citerefentry><refentrytitle>sbrk
</refentrytitle>
412 <manvolnum>2</manvolnum></citerefentry> and
413 <citerefentry><refentrytitle>mmap
</refentrytitle>
414 <manvolnum>2</manvolnum></citerefentry>, in that order of preference;
415 otherwise only
<citerefentry><refentrytitle>mmap
</refentrytitle>
416 <manvolnum>2</manvolnum></citerefentry> is used.
</para>
418 <para>This allocator uses multiple arenas in order to reduce lock
419 contention for threaded programs on multi-processor systems. This works
420 well with regard to threading scalability, but incurs some costs. There is
421 a small fixed per-arena overhead, and additionally, arenas manage memory
422 completely independently of each other, which means a small fixed increase
423 in overall memory fragmentation. These overheads are not generally an
424 issue, given the number of arenas normally used. Note that using
425 substantially more arenas than the default is not likely to improve
426 performance, mainly due to reduced cache performance. However, it may make
427 sense to reduce the number of arenas if an application does not make much
428 use of the allocation functions.
</para>
430 <para>In addition to multiple arenas, unless
431 <option>--disable-tcache
</option> is specified during configuration, this
432 allocator supports thread-specific caching for small and large objects, in
433 order to make it possible to completely avoid synchronization for most
434 allocation requests. Such caching allows very fast allocation in the
435 common case, but it increases memory usage and fragmentation, since a
436 bounded number of objects can remain allocated in each thread cache.
</para>
438 <para>Memory is conceptually broken into equal-sized chunks, where the
439 chunk size is a power of two that is greater than the page size. Chunks
440 are always aligned to multiples of the chunk size. This alignment makes it
441 possible to find metadata for user objects very quickly.
</para>
443 <para>User objects are broken into three categories according to size:
444 small, large, and huge. Small objects are smaller than one page. Large
445 objects are smaller than the chunk size. Huge objects are a multiple of
446 the chunk size. Small and large objects are managed by arenas; huge
447 objects are managed separately in a single data structure that is shared by
448 all threads. Huge objects are used by applications infrequently enough
449 that this single data structure is not a scalability issue.
</para>
451 <para>Each chunk that is managed by an arena tracks its contents as runs of
452 contiguous pages (unused, backing a set of small objects, or backing one
453 large object). The combination of chunk alignment and chunk page maps
454 makes it possible to determine all metadata regarding small and large
455 allocations in constant time.
</para>
457 <para>Small objects are managed in groups by page runs. Each run maintains
458 a frontier and free list to track which regions are in use. Unless
459 <option>--disable-tiny
</option> is specified during configuration,
460 allocation requests that are no more than half the quantum (
8 or
16,
461 depending on architecture) are rounded up to the nearest power of two that
462 is at least
<code language=
"C">sizeof(
<type>void *
</type>)
</code>.
463 Allocation requests that are more than half the quantum, but no more than
464 the minimum cacheline-multiple size class (see the
<link
465 linkend=
"opt.lg_qspace_max"><mallctl>opt.lg_qspace_max
</mallctl></link>
466 option) are rounded up to the nearest multiple of the quantum. Allocation
467 requests that are more than the minimum cacheline-multiple size class, but
468 no more than the minimum subpage-multiple size class (see the
<link
469 linkend=
"opt.lg_cspace_max"><mallctl>opt.lg_cspace_max
</mallctl></link>
470 option) are rounded up to the nearest multiple of the cacheline size (
64).
471 Allocation requests that are more than the minimum subpage-multiple size
472 class, but no more than the maximum subpage-multiple size class are rounded
473 up to the nearest multiple of the subpage size (
256). Allocation requests
474 that are more than the maximum subpage-multiple size class, but small
475 enough to fit in an arena-managed chunk (see the
<link
476 linkend=
"opt.lg_chunk"><mallctl>opt.lg_chunk
</mallctl></link> option), are
477 rounded up to the nearest run size. Allocation requests that are too large
478 to fit in an arena-managed chunk are rounded up to the nearest multiple of
479 the chunk size.
</para>
481 <para>Allocations are packed tightly together, which can be an issue for
482 multi-threaded applications. If you need to assure that allocations do not
483 suffer from cacheline sharing, round your allocation requests up to the
484 nearest multiple of the cacheline size, or specify cacheline alignment when
487 <para>Assuming
4 MiB chunks,
4 KiB pages, and a
16-byte quantum on a
64-bit
488 system, the size classes in each category are as shown in
<xref
489 linkend=
"size_classes" xrefstyle=
"template:Table %n"/>.
</para>
491 <table xml:
id=
"size_classes" frame=
"all">
492 <title>Size classes
</title>
493 <tgroup cols=
"3" align=
"left" colsep=
"1" rowsep=
"1">
494 <colspec colname=
"c1"/>
495 <colspec colname=
"c2"/>
496 <colspec colname=
"c3"/>
499 <entry>Category
</entry>
500 <entry>Subcategory
</entry>
506 <entry morerows=
"3">Small
</entry>
511 <entry>Quantum-spaced
</entry>
512 <entry>[
16,
32,
48, ...,
128]
</entry>
515 <entry>Cacheline-spaced
</entry>
516 <entry>[
192,
256,
320, ...,
512]
</entry>
519 <entry>Subpage-spaced
</entry>
520 <entry>[
768,
1024,
1280, ...,
3840]
</entry>
523 <entry namest=
"c1" nameend=
"c2">Large
</entry>
524 <entry>[
4 KiB,
8 KiB,
12 KiB, ...,
4072 KiB]
</entry>
527 <entry namest=
"c1" nameend=
"c2">Huge
</entry>
528 <entry>[
4 MiB,
8 MiB,
12 MiB, ...]
</entry>
534 <refsect1 id=
"mallctl_namespace">
535 <title>MALLCTL NAMESPACE
</title>
536 <para>The following names are defined in the namespace accessible via the
537 <function>mallctl*
<parameter/></function> functions. Value types are
538 specified in parentheses, their readable/writable statuses are encoded as
539 <literal>rw
</literal>,
<literal>r-
</literal>,
<literal>-w
</literal>, or
540 <literal>--
</literal>, and required build configuration flags follow, if
541 any. A name element encoded as
<literal><i
></literal> or
542 <literal><j
></literal> indicates an integer component, where the
543 integer varies from
0 to some upper value that must be determined via
544 introspection. In the case of
<mallctl>stats.arenas.
<i
>.*
</mallctl>,
545 <literal><i
></literal> equal to
<link
546 linkend=
"arenas.narenas"><mallctl>arenas.narenas
</mallctl></link> can be
547 used to access the summation of statistics from all arenas. Take special
548 note of the
<link linkend=
"epoch"><mallctl>epoch
</mallctl></link> mallctl,
549 which controls refreshing of cached dynamic statistics.
</para>
554 <mallctl>version
</mallctl>
555 (
<type>const char *
</type>)
556 <literal>r-
</literal>
558 <listitem><para>Return the jemalloc version string.
</para></listitem>
561 <varlistentry id=
"epoch">
563 <mallctl>epoch
</mallctl>
564 (
<type>uint64_t
</type>)
565 <literal>rw
</literal>
567 <listitem><para>If a value is passed in, refresh the data from which
568 the
<function>mallctl*
<parameter/></function> functions report values,
569 and increment the epoch. Return the current epoch. This is useful for
570 detecting whether another thread caused a refresh.
</para></listitem>
575 <mallctl>config.debug
</mallctl>
577 <literal>r-
</literal>
579 <listitem><para><option>--enable-debug
</option> was specified during
580 build configuration.
</para></listitem>
585 <mallctl>config.dss
</mallctl>
587 <literal>r-
</literal>
589 <listitem><para><option>--enable-dss
</option> was specified during
590 build configuration.
</para></listitem>
595 <mallctl>config.dynamic_page_shift
</mallctl>
597 <literal>r-
</literal>
599 <listitem><para><option>--enable-dynamic-page-shift
</option> was
600 specified during build configuration.
</para></listitem>
605 <mallctl>config.fill
</mallctl>
607 <literal>r-
</literal>
609 <listitem><para><option>--enable-fill
</option> was specified during
610 build configuration.
</para></listitem>
615 <mallctl>config.lazy_lock
</mallctl>
617 <literal>r-
</literal>
619 <listitem><para><option>--enable-lazy-lock
</option> was specified
620 during build configuration.
</para></listitem>
625 <mallctl>config.prof
</mallctl>
627 <literal>r-
</literal>
629 <listitem><para><option>--enable-prof
</option> was specified during
630 build configuration.
</para></listitem>
635 <mallctl>config.prof_libgcc
</mallctl>
637 <literal>r-
</literal>
639 <listitem><para><option>--disable-prof-libgcc
</option> was not
640 specified during build configuration.
</para></listitem>
645 <mallctl>config.prof_libunwind
</mallctl>
647 <literal>r-
</literal>
649 <listitem><para><option>--enable-prof-libunwind
</option> was specified
650 during build configuration.
</para></listitem>
655 <mallctl>config.stats
</mallctl>
657 <literal>r-
</literal>
659 <listitem><para><option>--enable-stats
</option> was specified during
660 build configuration.
</para></listitem>
665 <mallctl>config.swap
</mallctl>
667 <literal>r-
</literal>
669 <listitem><para><option>--enable-swap
</option> was specified during
670 build configuration.
</para></listitem>
675 <mallctl>config.sysv
</mallctl>
677 <literal>r-
</literal>
679 <listitem><para><option>--enable-sysv
</option> was specified during
680 build configuration.
</para></listitem>
685 <mallctl>config.tcache
</mallctl>
687 <literal>r-
</literal>
689 <listitem><para><option>--disable-tcache
</option> was not specified
690 during build configuration.
</para></listitem>
695 <mallctl>config.tiny
</mallctl>
697 <literal>r-
</literal>
699 <listitem><para><option>--disable-tiny
</option> was not specified
700 during build configuration.
</para></listitem>
705 <mallctl>config.tls
</mallctl>
707 <literal>r-
</literal>
709 <listitem><para><option>--disable-tls
</option> was not specified during
710 build configuration.
</para></listitem>
715 <mallctl>config.xmalloc
</mallctl>
717 <literal>r-
</literal>
719 <listitem><para><option>--enable-xmalloc
</option> was specified during
720 build configuration.
</para></listitem>
723 <varlistentry id=
"opt.abort">
725 <mallctl>opt.abort
</mallctl>
727 <literal>r-
</literal>
729 <listitem><para>Abort-on-warning enabled/disabled. If true, most
730 warnings are fatal. The process will call
731 <citerefentry><refentrytitle>abort
</refentrytitle>
732 <manvolnum>3</manvolnum></citerefentry> in these cases. This option is
733 disabled by default unless
<option>--enable-debug
</option> is
734 specified during configuration, in which case it is enabled by default.
738 <varlistentry id=
"opt.lg_qspace_max">
740 <mallctl>opt.lg_qspace_max
</mallctl>
741 (
<type>size_t
</type>)
742 <literal>r-
</literal>
744 <listitem><para>Size (log base
2) of the maximum size class that is a
745 multiple of the quantum (
8 or
16 bytes, depending on architecture).
746 Above this size, cacheline spacing is used for size classes. The
747 default value is
128 bytes (
2^
7).
</para></listitem>
750 <varlistentry id=
"opt.lg_cspace_max">
752 <mallctl>opt.lg_cspace_max
</mallctl>
753 (
<type>size_t
</type>)
754 <literal>r-
</literal>
756 <listitem><para>Size (log base
2) of the maximum size class that is a
757 multiple of the cacheline size (
64). Above this size, subpage spacing
758 (
256 bytes) is used for size classes. The default value is
512 bytes
759 (
2^
9).
</para></listitem>
762 <varlistentry id=
"opt.lg_chunk">
764 <mallctl>opt.lg_chunk
</mallctl>
765 (
<type>size_t
</type>)
766 <literal>r-
</literal>
768 <listitem><para>Virtual memory chunk size (log base
2). The default
769 chunk size is
4 MiB (
2^
22).
</para></listitem>
772 <varlistentry id=
"opt.narenas">
774 <mallctl>opt.narenas
</mallctl>
775 (
<type>size_t
</type>)
776 <literal>r-
</literal>
778 <listitem><para>Maximum number of arenas to use. The default maximum
779 number of arenas is four times the number of CPUs, or one if there is a
780 single CPU.
</para></listitem>
783 <varlistentry id=
"opt.lg_dirty_mult">
785 <mallctl>opt.lg_dirty_mult
</mallctl>
786 (
<type>ssize_t
</type>)
787 <literal>r-
</literal>
789 <listitem><para>Per-arena minimum ratio (log base
2) of active to dirty
790 pages. Some dirty unused pages may be allowed to accumulate, within
791 the limit set by the ratio (or one chunk worth of dirty pages,
792 whichever is greater), before informing the kernel about some of those
793 pages via
<citerefentry><refentrytitle>madvise
</refentrytitle>
794 <manvolnum>2</manvolnum></citerefentry> or a similar system call. This
795 provides the kernel with sufficient information to recycle dirty pages
796 if physical memory becomes scarce and the pages remain unused. The
797 default minimum ratio is
32:
1 (
2^
5:
1); an option value of -
1 will
798 disable dirty page purging.
</para></listitem>
801 <varlistentry id=
"opt.stats_print">
803 <mallctl>opt.stats_print
</mallctl>
805 <literal>r-
</literal>
807 <listitem><para>Enable/disable statistics printing at exit. If
808 enabled, the
<function>malloc_stats_print
<parameter/></function>
809 function is called at program exit via an
810 <citerefentry><refentrytitle>atexit
</refentrytitle>
811 <manvolnum>3</manvolnum></citerefentry> function. If
812 <option>--enable-stats
</option> is specified during configuration, this
813 has the potential to cause deadlock for a multi-threaded process that
814 exits while one or more threads are executing in the memory allocation
815 functions. Therefore, this option should only be used with care; it is
816 primarily intended as a performance tuning aid during application
817 development. This option is disabled by default.
</para></listitem>
820 <varlistentry id=
"opt.junk">
822 <mallctl>opt.junk
</mallctl>
824 <literal>r-
</literal>
825 [
<option>--enable-fill
</option>]
827 <listitem><para>Junk filling enabled/disabled. If enabled, each byte
828 of uninitialized allocated memory will be initialized to
829 <literal>0xa5</literal>. All deallocated memory will be initialized to
830 <literal>0x5a</literal>. This is intended for debugging and will
831 impact performance negatively. This option is disabled by default
832 unless
<option>--enable-debug
</option> is specified during
833 configuration, in which case it is enabled by default.
</para></listitem>
836 <varlistentry id=
"opt.zero">
838 <mallctl>opt.zero
</mallctl>
840 <literal>r-
</literal>
841 [
<option>--enable-fill
</option>]
843 <listitem><para>Zero filling enabled/disabled. If enabled, each byte
844 of uninitialized allocated memory will be initialized to
0. Note that
845 this initialization only happens once for each byte, so
846 <function>realloc
<parameter/></function> and
847 <function>rallocm
<parameter/></function> calls do not zero memory that
848 was previously allocated. This is intended for debugging and will
849 impact performance negatively. This option is disabled by default.
853 <varlistentry id=
"opt.sysv">
855 <mallctl>opt.sysv
</mallctl>
857 <literal>r-
</literal>
858 [
<option>--enable-sysv
</option>]
860 <listitem><para>If enabled, attempting to allocate zero bytes will
861 return a
<constant>NULL
</constant> pointer instead of a valid pointer.
862 (The default behavior is to make a minimal allocation and return a
863 pointer to it.) This option is provided for System V compatibility.
864 This option is incompatible with the
<link
865 linkend=
"opt.xmalloc"><mallctl>opt.xmalloc
</mallctl></link> option.
866 This option is disabled by default.
</para></listitem>
869 <varlistentry id=
"opt.xmalloc">
871 <mallctl>opt.xmalloc
</mallctl>
873 <literal>r-
</literal>
874 [
<option>--enable-xmalloc
</option>]
876 <listitem><para>Abort-on-out-of-memory enabled/disabled. If enabled,
877 rather than returning failure for any allocation function, display a
878 diagnostic message on
<constant>STDERR_FILENO
</constant> and cause the
879 program to drop core (using
880 <citerefentry><refentrytitle>abort
</refentrytitle>
881 <manvolnum>3</manvolnum></citerefentry>). If an application is
882 designed to depend on this behavior, set the option at compile time by
883 including the following in the source code:
884 <programlisting language=
"C"><![CDATA[
885 malloc_conf = "xmalloc:true";]]
></programlisting>
886 This option is disabled by default.
</para></listitem>
889 <varlistentry id=
"opt.tcache">
891 <mallctl>opt.tcache
</mallctl>
893 <literal>r-
</literal>
894 [
<option>--enable-tcache
</option>]
896 <listitem><para>Thread-specific caching enabled/disabled. When there
897 are multiple threads, each thread uses a thread-specific cache for
898 objects up to a certain size. Thread-specific caching allows many
899 allocations to be satisfied without performing any thread
900 synchronization, at the cost of increased memory use. See the
902 linkend=
"opt.lg_tcache_gc_sweep"><mallctl>opt.lg_tcache_gc_sweep
</mallctl></link>
904 linkend=
"opt.lg_tcache_max"><mallctl>opt.lg_tcache_max
</mallctl></link>
905 options for related tuning information. This option is enabled by
906 default.
</para></listitem>
909 <varlistentry id=
"opt.lg_tcache_gc_sweep">
911 <mallctl>opt.lg_tcache_gc_sweep
</mallctl>
912 (
<type>ssize_t
</type>)
913 <literal>r-
</literal>
914 [
<option>--enable-tcache
</option>]
916 <listitem><para>Approximate interval (log base
2) between full
917 thread-specific cache garbage collection sweeps, counted in terms of
918 thread-specific cache allocation/deallocation events. Garbage
919 collection is actually performed incrementally, one size class at a
920 time, in order to avoid large collection pauses. The default sweep
921 interval is
8192 (
2^
13); setting this option to -
1 will disable garbage
922 collection.
</para></listitem>
925 <varlistentry id=
"opt.lg_tcache_max">
927 <mallctl>opt.lg_tcache_max
</mallctl>
928 (
<type>size_t
</type>)
929 <literal>r-
</literal>
930 [
<option>--enable-tcache
</option>]
932 <listitem><para>Maximum size class (log base
2) to cache in the
933 thread-specific cache. At a minimum, all small size classes are
934 cached, and at a maximum all large size classes are cached. The
935 default maximum is
32 KiB (
2^
15).
</para></listitem>
938 <varlistentry id=
"opt.prof">
940 <mallctl>opt.prof
</mallctl>
942 <literal>r-
</literal>
943 [
<option>--enable-prof
</option>]
945 <listitem><para>Memory profiling enabled/disabled. If enabled, profile
946 memory allocation activity, and use an
947 <citerefentry><refentrytitle>atexit
</refentrytitle>
948 <manvolnum>3</manvolnum></citerefentry> function to dump final memory
949 usage to a file named according to the pattern
950 <filename><prefix
>.
<pid
>.
<seq
>.f.heap
</filename>,
951 where
<literal><prefix
></literal> is controlled by the
<link
952 linkend=
"opt.prof_prefix"><mallctl>opt.prof_prefix
</mallctl></link>
953 option. See the
<link
954 linkend=
"opt.lg_prof_bt_max"><mallctl>opt.lg_prof_bt_max
</mallctl></link>
955 option for backtrace depth control. See the
<link
956 linkend=
"opt.prof_active"><mallctl>opt.prof_active
</mallctl></link>
957 option for on-the-fly activation/deactivation. See the
<link
958 linkend=
"opt.lg_prof_sample"><mallctl>opt.lg_prof_sample
</mallctl></link>
959 option for probabilistic sampling control. See the
<link
960 linkend=
"opt.prof_accum"><mallctl>opt.prof_accum
</mallctl></link>
961 option for control of cumulative sample reporting. See the
<link
962 linkend=
"opt.lg_prof_tcmax"><mallctl>opt.lg_prof_tcmax
</mallctl></link>
963 option for control of per thread backtrace caching. See the
<link
964 linkend=
"opt.lg_prof_interval"><mallctl>opt.lg_prof_interval
</mallctl></link>
965 option for information on interval-triggered profile dumping, and the
966 <link linkend=
"opt.prof_gdump"><mallctl>opt.prof_gdump
</mallctl></link>
967 option for information on high-water-triggered profile dumping.
968 Profile output is compatible with the included
<command>pprof
</command>
969 Perl script, which originates from the
<ulink
970 url=
"http://code.google.com/p/google-perftools/">google-perftools
971 package
</ulink>.
</para></listitem>
974 <varlistentry id=
"opt.prof_prefix">
976 <mallctl>opt.prof_prefix
</mallctl>
977 (
<type>const char *
</type>)
978 <literal>r-
</literal>
979 [
<option>--enable-prof
</option>]
981 <listitem><para>Filename prefix for profile dumps. If the prefix is
982 set to the empty string, no automatic dumps will occur; this is
983 primarily useful for disabling the automatic final heap dump (which
984 also disables leak reporting, if enabled). The default prefix is
985 <filename>jeprof
</filename>.
</para></listitem>
988 <varlistentry id=
"opt.lg_prof_bt_max">
990 <mallctl>opt.lg_prof_bt_max
</mallctl>
991 (
<type>size_t
</type>)
992 <literal>r-
</literal>
993 [
<option>--enable-prof
</option>]
995 <listitem><para>Maximum backtrace depth (log base
2) when profiling
996 memory allocation activity. The default is
128 (
2^
7).
</para></listitem>
999 <varlistentry id=
"opt.prof_active">
1001 <mallctl>opt.prof_active
</mallctl>
1003 <literal>r-
</literal>
1004 [
<option>--enable-prof
</option>]
1006 <listitem><para>Profiling activated/deactivated. This is a secondary
1007 control mechanism that makes it possible to start the application with
1008 profiling enabled (see the
<link
1009 linkend=
"opt.prof"><mallctl>opt.prof
</mallctl></link> option) but
1010 inactive, then toggle profiling at any time during program execution
1012 linkend=
"prof.active"><mallctl>prof.active
</mallctl></link> mallctl.
1013 This option is enabled by default.
</para></listitem>
1016 <varlistentry id=
"opt.lg_prof_sample">
1018 <mallctl>opt.lg_prof_sample
</mallctl>
1019 (
<type>ssize_t
</type>)
1020 <literal>r-
</literal>
1021 [
<option>--enable-prof
</option>]
1023 <listitem><para>Average interval (log base
2) between allocation
1024 samples, as measured in bytes of allocation activity. Increasing the
1025 sampling interval decreases profile fidelity, but also decreases the
1026 computational overhead. The default sample interval is
1 (
2^
0) (i.e.
1027 all allocations are sampled).
</para></listitem>
1030 <varlistentry id=
"opt.prof_accum">
1032 <mallctl>opt.prof_accum
</mallctl>
1034 <literal>r-
</literal>
1035 [
<option>--enable-prof
</option>]
1037 <listitem><para>Reporting of cumulative object/byte counts in profile
1038 dumps enabled/disabled. If this option is enabled, every unique
1039 backtrace must be stored for the duration of execution. Depending on
1040 the application, this can impose a large memory overhead, and the
1041 cumulative counts are not always of interest. See the
1043 linkend=
"opt.lg_prof_tcmax"><mallctl>opt.lg_prof_tcmax
</mallctl></link>
1044 option for control of per thread backtrace caching, which has important
1045 interactions. This option is enabled by default.
</para></listitem>
1048 <varlistentry id=
"opt.lg_prof_tcmax">
1050 <mallctl>opt.lg_prof_tcmax
</mallctl>
1051 (
<type>ssize_t
</type>)
1052 <literal>r-
</literal>
1053 [
<option>--enable-prof
</option>]
1055 <listitem><para>Maximum per thread backtrace cache (log base
2) used
1056 for heap profiling. A backtrace can only be discarded if the
1057 <link linkend=
"opt.prof_accum"><mallctl>opt.prof_accum
</mallctl></link>
1058 option is disabled, and no thread caches currently refer to the
1059 backtrace. Therefore, a backtrace cache limit should be imposed if the
1060 intention is to limit how much memory is used by backtraces. By
1061 default, no limit is imposed (encoded as -
1).
1065 <varlistentry id=
"opt.lg_prof_interval">
1067 <mallctl>opt.lg_prof_interval
</mallctl>
1068 (
<type>ssize_t
</type>)
1069 <literal>r-
</literal>
1070 [
<option>--enable-prof
</option>]
1072 <listitem><para>Average interval (log base
2) between memory profile
1073 dumps, as measured in bytes of allocation activity. The actual
1074 interval between dumps may be sporadic because decentralized allocation
1075 counters are used to avoid synchronization bottlenecks. Profiles are
1076 dumped to files named according to the pattern
1077 <filename><prefix
>.
<pid
>.
<seq
>.i
<iseq
>.heap
</filename>,
1078 where
<literal><prefix
></literal> is controlled by the
1080 linkend=
"opt.prof_prefix"><mallctl>opt.prof_prefix
</mallctl></link>
1081 option. By default, interval-triggered profile dumping is disabled
1086 <varlistentry id=
"opt.prof_gdump">
1088 <mallctl>opt.prof_gdump
</mallctl>
1090 <literal>r-
</literal>
1091 [
<option>--enable-prof
</option>]
1093 <listitem><para>Trigger a memory profile dump every time the total
1094 virtual memory exceeds the previous maximum. Profiles are dumped to
1095 files named according to the pattern
1096 <filename><prefix
>.
<pid
>.
<seq
>.u
<useq
>.heap
</filename>,
1097 where
<literal><prefix
></literal> is controlled by the
<link
1098 linkend=
"opt.prof_prefix"><mallctl>opt.prof_prefix
</mallctl></link>
1099 option. This option is disabled by default.
</para></listitem>
1102 <varlistentry id=
"opt.prof_leak">
1104 <mallctl>opt.prof_leak
</mallctl>
1106 <literal>r-
</literal>
1107 [
<option>--enable-prof
</option>]
1109 <listitem><para>Leak reporting enabled/disabled. If enabled, use an
1110 <citerefentry><refentrytitle>atexit
</refentrytitle>
1111 <manvolnum>3</manvolnum></citerefentry> function to report memory leaks
1112 detected by allocation sampling. See the
1114 linkend=
"opt.lg_prof_bt_max"><mallctl>opt.lg_prof_bt_max
</mallctl></link>
1115 option for backtrace depth control. See the
1116 <link linkend=
"opt.prof"><mallctl>opt.prof
</mallctl></link> option for
1117 information on analyzing heap profile output. This option is disabled
1118 by default.
</para></listitem>
1121 <varlistentry id=
"opt.overcommit">
1123 <mallctl>opt.overcommit
</mallctl>
1125 <literal>r-
</literal>
1126 [
<option>--enable-swap
</option>]
1128 <listitem><para>Over-commit enabled/disabled. If enabled, over-commit
1129 memory as a side effect of using anonymous
1130 <citerefentry><refentrytitle>mmap
</refentrytitle>
1131 <manvolnum>2</manvolnum></citerefentry> or
1132 <citerefentry><refentrytitle>sbrk
</refentrytitle>
1133 <manvolnum>2</manvolnum></citerefentry> for virtual memory allocation.
1134 In order for overcommit to be disabled, the
<link
1135 linkend=
"swap.fds"><mallctl>swap.fds
</mallctl></link> mallctl must have
1136 been successfully written to. This option is enabled by
1137 default.
</para></listitem>
1142 <mallctl>tcache.flush
</mallctl>
1144 <literal>--
</literal>
1145 [
<option>--enable-tcache
</option>]
1147 <listitem><para>Flush calling thread's tcache. This interface releases
1148 all cached objects and internal data structures associated with the
1149 calling thread's thread-specific cache. Ordinarily, this interface
1150 need not be called, since automatic periodic incremental garbage
1151 collection occurs, and the thread cache is automatically discarded when
1152 a thread exits. However, garbage collection is triggered by allocation
1153 activity, so it is possible for a thread that stops
1154 allocating/deallocating to retain its cache indefinitely, in which case
1155 the developer may find manual flushing useful.
</para></listitem>
1160 <mallctl>thread.arena
</mallctl>
1161 (
<type>unsigned
</type>)
1162 <literal>rw
</literal>
1164 <listitem><para>Get or set the arena associated with the calling
1165 thread. The arena index must be less than the maximum number of arenas
1167 linkend=
"arenas.narenas"><mallctl>arenas.narenas
</mallctl></link>
1168 mallctl). If the specified arena was not initialized beforehand (see
1170 linkend=
"arenas.initialized"><mallctl>arenas.initialized
</mallctl></link>
1171 mallctl), it will be automatically initialized as a side effect of
1172 calling this interface.
</para></listitem>
1175 <varlistentry id=
"thread.allocated">
1177 <mallctl>thread.allocated
</mallctl>
1178 (
<type>uint64_t
</type>)
1179 <literal>r-
</literal>
1180 [
<option>--enable-stats
</option>]
1182 <listitem><para>Get the total number of bytes ever allocated by the
1183 calling thread. This counter has the potential to wrap around; it is
1184 up to the application to appropriately interpret the counter in such
1185 cases.
</para></listitem>
1190 <mallctl>thread.allocatedp
</mallctl>
1191 (
<type>uint64_t *
</type>)
1192 <literal>r-
</literal>
1193 [
<option>--enable-stats
</option>]
1195 <listitem><para>Get a pointer to the the value that is returned by the
1197 linkend=
"thread.allocated"><mallctl>thread.allocated
</mallctl></link>
1198 mallctl. This is useful for avoiding the overhead of repeated
1199 <function>mallctl*
<parameter/></function> calls.
</para></listitem>
1202 <varlistentry id=
"thread.deallocated">
1204 <mallctl>thread.deallocated
</mallctl>
1205 (
<type>uint64_t
</type>)
1206 <literal>r-
</literal>
1207 [
<option>--enable-stats
</option>]
1209 <listitem><para>Get the total number of bytes ever deallocated by the
1210 calling thread. This counter has the potential to wrap around; it is
1211 up to the application to appropriately interpret the counter in such
1212 cases.
</para></listitem>
1217 <mallctl>thread.deallocatedp
</mallctl>
1218 (
<type>uint64_t *
</type>)
1219 <literal>r-
</literal>
1220 [
<option>--enable-stats
</option>]
1222 <listitem><para>Get a pointer to the the value that is returned by the
1224 linkend=
"thread.deallocated"><mallctl>thread.deallocated
</mallctl></link>
1225 mallctl. This is useful for avoiding the overhead of repeated
1226 <function>mallctl*
<parameter/></function> calls.
</para></listitem>
1229 <varlistentry id=
"arenas.narenas">
1231 <mallctl>arenas.narenas
</mallctl>
1232 (
<type>unsigned
</type>)
1233 <literal>r-
</literal>
1235 <listitem><para>Maximum number of arenas.
</para></listitem>
1238 <varlistentry id=
"arenas.initialized">
1240 <mallctl>arenas.initialized
</mallctl>
1241 (
<type>bool *
</type>)
1242 <literal>r-
</literal>
1244 <listitem><para>An array of
<link
1245 linkend=
"arenas.narenas"><mallctl>arenas.narenas
</mallctl></link>
1246 booleans. Each boolean indicates whether the corresponding arena is
1247 initialized.
</para></listitem>
1252 <mallctl>arenas.quantum
</mallctl>
1253 (
<type>size_t
</type>)
1254 <literal>r-
</literal>
1256 <listitem><para>Quantum size.
</para></listitem>
1261 <mallctl>arenas.cacheline
</mallctl>
1262 (
<type>size_t
</type>)
1263 <literal>r-
</literal>
1265 <listitem><para>Assumed cacheline size.
</para></listitem>
1270 <mallctl>arenas.subpage
</mallctl>
1271 (
<type>size_t
</type>)
1272 <literal>r-
</literal>
1274 <listitem><para>Subpage size class interval.
</para></listitem>
1279 <mallctl>arenas.pagesize
</mallctl>
1280 (
<type>size_t
</type>)
1281 <literal>r-
</literal>
1283 <listitem><para>Page size.
</para></listitem>
1288 <mallctl>arenas.chunksize
</mallctl>
1289 (
<type>size_t
</type>)
1290 <literal>r-
</literal>
1292 <listitem><para>Chunk size.
</para></listitem>
1297 <mallctl>arenas.tspace_min
</mallctl>
1298 (
<type>size_t
</type>)
1299 <literal>r-
</literal>
1301 <listitem><para>Minimum tiny size class. Tiny size classes are powers
1302 of two.
</para></listitem>
1307 <mallctl>arenas.tspace_max
</mallctl>
1308 (
<type>size_t
</type>)
1309 <literal>r-
</literal>
1311 <listitem><para>Maximum tiny size class. Tiny size classes are powers
1312 of two.
</para></listitem>
1317 <mallctl>arenas.qspace_min
</mallctl>
1318 (
<type>size_t
</type>)
1319 <literal>r-
</literal>
1321 <listitem><para>Minimum quantum-spaced size class.
</para></listitem>
1326 <mallctl>arenas.qspace_max
</mallctl>
1327 (
<type>size_t
</type>)
1328 <literal>r-
</literal>
1330 <listitem><para>Maximum quantum-spaced size class.
</para></listitem>
1335 <mallctl>arenas.cspace_min
</mallctl>
1336 (
<type>size_t
</type>)
1337 <literal>r-
</literal>
1339 <listitem><para>Minimum cacheline-spaced size class.
</para></listitem>
1344 <mallctl>arenas.cspace_max
</mallctl>
1345 (
<type>size_t
</type>)
1346 <literal>r-
</literal>
1348 <listitem><para>Maximum cacheline-spaced size class.
</para></listitem>
1353 <mallctl>arenas.sspace_min
</mallctl>
1354 (
<type>size_t
</type>)
1355 <literal>r-
</literal>
1357 <listitem><para>Minimum subpage-spaced size class.
</para></listitem>
1362 <mallctl>arenas.sspace_max
</mallctl>
1363 (
<type>size_t
</type>)
1364 <literal>r-
</literal>
1366 <listitem><para>Maximum subpage-spaced size class.
</para></listitem>
1371 <mallctl>arenas.tcache_max
</mallctl>
1372 (
<type>size_t
</type>)
1373 <literal>r-
</literal>
1374 [
<option>--enable-tcache
</option>]
1376 <listitem><para>Maximum thread-cached size class.
</para></listitem>
1381 <mallctl>arenas.ntbins
</mallctl>
1382 (
<type>unsigned
</type>)
1383 <literal>r-
</literal>
1385 <listitem><para>Number of tiny bin size classes.
</para></listitem>
1390 <mallctl>arenas.nqbins
</mallctl>
1391 (
<type>unsigned
</type>)
1392 <literal>r-
</literal>
1394 <listitem><para>Number of quantum-spaced bin size
1395 classes.
</para></listitem>
1400 <mallctl>arenas.ncbins
</mallctl>
1401 (
<type>unsigned
</type>)
1402 <literal>r-
</literal>
1404 <listitem><para>Number of cacheline-spaced bin size
1405 classes.
</para></listitem>
1410 <mallctl>arenas.nsbins
</mallctl>
1411 (
<type>unsigned
</type>)
1412 <literal>r-
</literal>
1414 <listitem><para>Number of subpage-spaced bin size
1415 classes.
</para></listitem>
1420 <mallctl>arenas.nbins
</mallctl>
1421 (
<type>unsigned
</type>)
1422 <literal>r-
</literal>
1424 <listitem><para>Total number of bin size classes.
</para></listitem>
1429 <mallctl>arenas.nhbins
</mallctl>
1430 (
<type>unsigned
</type>)
1431 <literal>r-
</literal>
1432 [
<option>--enable-tcache
</option>]
1434 <listitem><para>Total number of thread cache bin size
1435 classes.
</para></listitem>
1438 <varlistentry id=
"arenas.bin.i.size">
1440 <mallctl>arenas.bin.
<i
>.size
</mallctl>
1441 (
<type>size_t
</type>)
1442 <literal>r-
</literal>
1444 <listitem><para>Maximum size supported by size class.
</para></listitem>
1449 <mallctl>arenas.bin.
<i
>.nregs
</mallctl>
1450 (
<type>uint32_t
</type>)
1451 <literal>r-
</literal>
1453 <listitem><para>Number of regions per page run.
</para></listitem>
1458 <mallctl>arenas.bin.
<i
>.run_size
</mallctl>
1459 (
<type>size_t
</type>)
1460 <literal>r-
</literal>
1462 <listitem><para>Number of bytes per page run.
</para></listitem>
1467 <mallctl>arenas.nlruns
</mallctl>
1468 (
<type>size_t
</type>)
1469 <literal>r-
</literal>
1471 <listitem><para>Total number of large size classes.
</para></listitem>
1476 <mallctl>arenas.lrun.
<i
>.size
</mallctl>
1477 (
<type>size_t
</type>)
1478 <literal>r-
</literal>
1480 <listitem><para>Maximum size supported by this large size
1481 class.
</para></listitem>
1486 <mallctl>arenas.purge
</mallctl>
1487 (
<type>unsigned
</type>)
1488 <literal>-w
</literal>
1490 <listitem><para>Purge unused dirty pages for the specified arena, or
1491 for all arenas if none is specified.
</para></listitem>
1494 <varlistentry id=
"prof.active">
1496 <mallctl>prof.active
</mallctl>
1498 <literal>rw
</literal>
1499 [
<option>--enable-prof
</option>]
1501 <listitem><para>Control whether sampling is currently active. See the
1503 linkend=
"opt.prof_active"><mallctl>opt.prof_active
</mallctl></link>
1504 option for additional information.
1510 <mallctl>prof.dump
</mallctl>
1511 (
<type>const char *
</type>)
1512 <literal>-w
</literal>
1513 [
<option>--enable-prof
</option>]
1515 <listitem><para>Dump a memory profile to the specified file, or if NULL
1516 is specified, to a file according to the pattern
1517 <filename><prefix
>.
<pid
>.
<seq
>.m
<mseq
>.heap
</filename>,
1518 where
<literal><prefix
></literal> is controlled by the
1520 linkend=
"opt.prof_prefix"><mallctl>opt.prof_prefix
</mallctl></link>
1521 option.
</para></listitem>
1526 <mallctl>prof.interval
</mallctl>
1527 (
<type>uint64_t
</type>)
1528 <literal>r-
</literal>
1529 [
<option>--enable-prof
</option>]
1531 <listitem><para>Average number of bytes allocated between
1532 inverval-based profile dumps. See the
1534 linkend=
"opt.lg_prof_interval"><mallctl>opt.lg_prof_interval
</mallctl></link>
1535 option for additional information.
</para></listitem>
1538 <varlistentry id=
"stats.cactive">
1540 <mallctl>stats.cactive
</mallctl>
1541 (
<type>size_t *
</type>)
1542 <literal>r-
</literal>
1543 [
<option>--enable-stats
</option>]
1545 <listitem><para>Pointer to a counter that contains an approximate count
1546 of the current number of bytes in active pages. The estimate may be
1547 high, but never low, because each arena rounds up to the nearest
1548 multiple of the chunk size when computing its contribution to the
1549 counter. Note that the
<link
1550 linkend=
"epoch"><mallctl>epoch
</mallctl></link> mallctl has no bearing
1551 on this counter. Furthermore, counter consistency is maintained via
1552 atomic operations, so it is necessary to use an atomic operation in
1553 order to guarantee a consistent read when dereferencing the pointer.
1557 <varlistentry id=
"stats.allocated">
1559 <mallctl>stats.allocated
</mallctl>
1560 (
<type>size_t
</type>)
1561 <literal>r-
</literal>
1562 [
<option>--enable-stats
</option>]
1564 <listitem><para>Total number of bytes allocated by the
1565 application.
</para></listitem>
1568 <varlistentry id=
"stats.active">
1570 <mallctl>stats.active
</mallctl>
1571 (
<type>size_t
</type>)
1572 <literal>r-
</literal>
1573 [
<option>--enable-stats
</option>]
1575 <listitem><para>Total number of bytes in active pages allocated by the
1576 application. This is a multiple of the page size, and greater than or
1578 linkend=
"stats.allocated"><mallctl>stats.allocated
</mallctl></link>.
1584 <mallctl>stats.mapped
</mallctl>
1585 (
<type>size_t
</type>)
1586 <literal>r-
</literal>
1587 [
<option>--enable-stats
</option>]
1589 <listitem><para>Total number of bytes in chunks mapped on behalf of the
1590 application. This is a multiple of the chunk size, and is at least as
1592 linkend=
"stats.active"><mallctl>stats.active
</mallctl></link>. This
1593 does not include inactive chunks backed by swap files. his does not
1594 include inactive chunks embedded in the DSS.
</para></listitem>
1599 <mallctl>stats.chunks.current
</mallctl>
1600 (
<type>size_t
</type>)
1601 <literal>r-
</literal>
1602 [
<option>--enable-stats
</option>]
1604 <listitem><para>Total number of chunks actively mapped on behalf of the
1605 application. This does not include inactive chunks backed by swap
1606 files. This does not include inactive chunks embedded in the DSS.
1612 <mallctl>stats.chunks.total
</mallctl>
1613 (
<type>uint64_t
</type>)
1614 <literal>r-
</literal>
1615 [
<option>--enable-stats
</option>]
1617 <listitem><para>Cumulative number of chunks allocated.
</para></listitem>
1622 <mallctl>stats.chunks.high
</mallctl>
1623 (
<type>size_t
</type>)
1624 <literal>r-
</literal>
1625 [
<option>--enable-stats
</option>]
1627 <listitem><para>Maximum number of active chunks at any time thus far.
1633 <mallctl>stats.huge.allocated
</mallctl>
1634 (
<type>size_t
</type>)
1635 <literal>r-
</literal>
1636 [
<option>--enable-stats
</option>]
1638 <listitem><para>Number of bytes currently allocated by huge objects.
1644 <mallctl>stats.huge.nmalloc
</mallctl>
1645 (
<type>uint64_t
</type>)
1646 <literal>r-
</literal>
1647 [
<option>--enable-stats
</option>]
1649 <listitem><para>Cumulative number of huge allocation requests.
1655 <mallctl>stats.huge.ndalloc
</mallctl>
1656 (
<type>uint64_t
</type>)
1657 <literal>r-
</literal>
1658 [
<option>--enable-stats
</option>]
1660 <listitem><para>Cumulative number of huge deallocation requests.
1666 <mallctl>stats.arenas.
<i
>.nthreads
</mallctl>
1667 (
<type>unsigned
</type>)
1668 <literal>r-
</literal>
1670 <listitem><para>Number of threads currently assigned to
1671 arena.
</para></listitem>
1676 <mallctl>stats.arenas.
<i
>.pactive
</mallctl>
1677 (
<type>size_t
</type>)
1678 <literal>r-
</literal>
1680 <listitem><para>Number of pages in active runs.
</para></listitem>
1685 <mallctl>stats.arenas.
<i
>.pdirty
</mallctl>
1686 (
<type>size_t
</type>)
1687 <literal>r-
</literal>
1689 <listitem><para>Number of pages within unused runs that are potentially
1690 dirty, and for which
<function>madvise
<parameter>...
</parameter>
1691 <parameter><constant>MADV_DONTNEED
</constant></parameter></function> or
1692 similar has not been called.
</para></listitem>
1697 <mallctl>stats.arenas.
<i
>.mapped
</mallctl>
1698 (
<type>size_t
</type>)
1699 <literal>r-
</literal>
1700 [
<option>--enable-stats
</option>]
1702 <listitem><para>Number of mapped bytes.
</para></listitem>
1707 <mallctl>stats.arenas.
<i
>.npurge
</mallctl>
1708 (
<type>uint64_t
</type>)
1709 <literal>r-
</literal>
1710 [
<option>--enable-stats
</option>]
1712 <listitem><para>Number of dirty page purge sweeps performed.
1718 <mallctl>stats.arenas.
<i
>.nmadvise
</mallctl>
1719 (
<type>uint64_t
</type>)
1720 <literal>r-
</literal>
1721 [
<option>--enable-stats
</option>]
1723 <listitem><para>Number of
<function>madvise
<parameter>...
</parameter>
1724 <parameter><constant>MADV_DONTNEED
</constant></parameter></function> or
1725 similar calls made to purge dirty pages.
</para></listitem>
1730 <mallctl>stats.arenas.
<i
>.npurged
</mallctl>
1731 (
<type>uint64_t
</type>)
1732 <literal>r-
</literal>
1733 [
<option>--enable-stats
</option>]
1735 <listitem><para>Number of pages purged.
</para></listitem>
1740 <mallctl>stats.arenas.
<i
>.small.allocated
</mallctl>
1741 (
<type>size_t
</type>)
1742 <literal>r-
</literal>
1743 [
<option>--enable-stats
</option>]
1745 <listitem><para>Number of bytes currently allocated by small objects.
1751 <mallctl>stats.arenas.
<i
>.small.nmalloc
</mallctl>
1752 (
<type>uint64_t
</type>)
1753 <literal>r-
</literal>
1754 [
<option>--enable-stats
</option>]
1756 <listitem><para>Cumulative number of allocation requests served by
1757 small bins.
</para></listitem>
1762 <mallctl>stats.arenas.
<i
>.small.ndalloc
</mallctl>
1763 (
<type>uint64_t
</type>)
1764 <literal>r-
</literal>
1765 [
<option>--enable-stats
</option>]
1767 <listitem><para>Cumulative number of small objects returned to bins.
1773 <mallctl>stats.arenas.
<i
>.small.nrequests
</mallctl>
1774 (
<type>uint64_t
</type>)
1775 <literal>r-
</literal>
1776 [
<option>--enable-stats
</option>]
1778 <listitem><para>Cumulative number of small allocation requests.
1784 <mallctl>stats.arenas.
<i
>.large.allocated
</mallctl>
1785 (
<type>size_t
</type>)
1786 <literal>r-
</literal>
1787 [
<option>--enable-stats
</option>]
1789 <listitem><para>Number of bytes currently allocated by large objects.
1795 <mallctl>stats.arenas.
<i
>.large.nmalloc
</mallctl>
1796 (
<type>uint64_t
</type>)
1797 <literal>r-
</literal>
1798 [
<option>--enable-stats
</option>]
1800 <listitem><para>Cumulative number of large allocation requests served
1801 directly by the arena.
</para></listitem>
1806 <mallctl>stats.arenas.
<i
>.large.ndalloc
</mallctl>
1807 (
<type>uint64_t
</type>)
1808 <literal>r-
</literal>
1809 [
<option>--enable-stats
</option>]
1811 <listitem><para>Cumulative number of large deallocation requests served
1812 directly by the arena.
</para></listitem>
1817 <mallctl>stats.arenas.
<i
>.large.nrequests
</mallctl>
1818 (
<type>uint64_t
</type>)
1819 <literal>r-
</literal>
1820 [
<option>--enable-stats
</option>]
1822 <listitem><para>Cumulative number of large allocation requests.
1828 <mallctl>stats.arenas.
<i
>.bins.
<j
>.allocated
</mallctl>
1829 (
<type>size_t
</type>)
1830 <literal>r-
</literal>
1831 [
<option>--enable-stats
</option>]
1833 <listitem><para>Current number of bytes allocated by
1834 bin.
</para></listitem>
1839 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nmalloc
</mallctl>
1840 (
<type>uint64_t
</type>)
1841 <literal>r-
</literal>
1842 [
<option>--enable-stats
</option>]
1844 <listitem><para>Cumulative number of allocations served by bin.
1850 <mallctl>stats.arenas.
<i
>.bins.
<j
>.ndalloc
</mallctl>
1851 (
<type>uint64_t
</type>)
1852 <literal>r-
</literal>
1853 [
<option>--enable-stats
</option>]
1855 <listitem><para>Cumulative number of allocations returned to bin.
1861 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nrequests
</mallctl>
1862 (
<type>uint64_t
</type>)
1863 <literal>r-
</literal>
1864 [
<option>--enable-stats
</option>]
1866 <listitem><para>Cumulative number of allocation
1867 requests.
</para></listitem>
1872 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nfills
</mallctl>
1873 (
<type>uint64_t
</type>)
1874 <literal>r-
</literal>
1875 [
<option>--enable-stats
</option> <option>--enable-tcache
</option>]
1877 <listitem><para>Cumulative number of tcache fills.
</para></listitem>
1882 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nflushes
</mallctl>
1883 (
<type>uint64_t
</type>)
1884 <literal>r-
</literal>
1885 [
<option>--enable-stats
</option> <option>--enable-tcache
</option>]
1887 <listitem><para>Cumulative number of tcache flushes.
</para></listitem>
1892 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nruns
</mallctl>
1893 (
<type>uint64_t
</type>)
1894 <literal>r-
</literal>
1895 [
<option>--enable-stats
</option>]
1897 <listitem><para>Cumulative number of runs created.
</para></listitem>
1902 <mallctl>stats.arenas.
<i
>.bins.
<j
>.nreruns
</mallctl>
1903 (
<type>uint64_t
</type>)
1904 <literal>r-
</literal>
1905 [
<option>--enable-stats
</option>]
1907 <listitem><para>Cumulative number of times the current run from which
1908 to allocate changed.
</para></listitem>
1913 <mallctl>stats.arenas.
<i
>.bins.
<j
>.highruns
</mallctl>
1914 (
<type>size_t
</type>)
1915 <literal>r-
</literal>
1916 [
<option>--enable-stats
</option>]
1918 <listitem><para>Maximum number of runs at any time thus far.
1924 <mallctl>stats.arenas.
<i
>.bins.
<j
>.curruns
</mallctl>
1925 (
<type>size_t
</type>)
1926 <literal>r-
</literal>
1927 [
<option>--enable-stats
</option>]
1929 <listitem><para>Current number of runs.
</para></listitem>
1934 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.nmalloc
</mallctl>
1935 (
<type>uint64_t
</type>)
1936 <literal>r-
</literal>
1937 [
<option>--enable-stats
</option>]
1939 <listitem><para>Cumulative number of allocation requests for this size
1940 class served directly by the arena.
</para></listitem>
1945 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.ndalloc
</mallctl>
1946 (
<type>uint64_t
</type>)
1947 <literal>r-
</literal>
1948 [
<option>--enable-stats
</option>]
1950 <listitem><para>Cumulative number of deallocation requests for this
1951 size class served directly by the arena.
</para></listitem>
1956 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.nrequests
</mallctl>
1957 (
<type>uint64_t
</type>)
1958 <literal>r-
</literal>
1959 [
<option>--enable-stats
</option>]
1961 <listitem><para>Cumulative number of allocation requests for this size
1962 class.
</para></listitem>
1967 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.highruns
</mallctl>
1968 (
<type>size_t
</type>)
1969 <literal>r-
</literal>
1970 [
<option>--enable-stats
</option>]
1972 <listitem><para>Maximum number of runs at any time thus far for this
1973 size class.
</para></listitem>
1978 <mallctl>stats.arenas.
<i
>.lruns.
<j
>.curruns
</mallctl>
1979 (
<type>size_t
</type>)
1980 <literal>r-
</literal>
1981 [
<option>--enable-stats
</option>]
1983 <listitem><para>Current number of runs for this size class.
1989 <mallctl>swap.avail
</mallctl>
1990 (
<type>size_t
</type>)
1991 <literal>r-
</literal>
1992 [
<option>--enable-stats --enable-swap
</option>]
1994 <listitem><para>Number of swap file bytes that are currently not
1995 associated with any chunk (i.e. mapped, but otherwise completely
1996 unmanaged).
</para></listitem>
1999 <varlistentry id=
"swap.prezeroed">
2001 <mallctl>swap.prezeroed
</mallctl>
2003 <literal>rw
</literal>
2004 [
<option>--enable-swap
</option>]
2006 <listitem><para>If true, the allocator assumes that the swap file(s)
2007 contain nothing but nil bytes. If this assumption is violated,
2008 allocator behavior is undefined. This value becomes read-only after
2009 <link linkend=
"swap.fds"><mallctl>swap.fds
</mallctl></link> is
2010 successfully written to.
</para></listitem>
2015 <mallctl>swap.nfds
</mallctl>
2016 (
<type>size_t
</type>)
2017 <literal>r-
</literal>
2018 [
<option>--enable-swap
</option>]
2020 <listitem><para>Number of file descriptors in use for swap.
2024 <varlistentry id=
"swap.fds">
2026 <mallctl>swap.fds
</mallctl>
2027 (
<type>int *
</type>)
2028 <literal>r-
</literal>
2029 [
<option>--enable-swap
</option>]
2031 <listitem><para>When written to, the files associated with the
2032 specified file descriptors are contiguously mapped via
2033 <citerefentry><refentrytitle>mmap
</refentrytitle>
2034 <manvolnum>2</manvolnum></citerefentry>. The resulting virtual memory
2035 region is preferred over anonymous
2036 <citerefentry><refentrytitle>mmap
</refentrytitle>
2037 <manvolnum>2</manvolnum></citerefentry> and
2038 <citerefentry><refentrytitle>sbrk
</refentrytitle>
2039 <manvolnum>2</manvolnum></citerefentry> memory. Note that if a file's
2040 size is not a multiple of the page size, it is automatically truncated
2041 to the nearest page size multiple. See the
2042 <link linkend=
"swap.prezeroed"><mallctl>swap.prezeroed
</mallctl></link>
2043 mallctl for specifying that the files are pre-zeroed.
</para></listitem>
2047 <refsect1 id=
"debugging_malloc_problems">
2048 <title>DEBUGGING MALLOC PROBLEMS
</title>
2049 <para>When debugging, it is a good idea to configure/build jemalloc with
2050 the
<option>--enable-debug
</option> and
<option>--enable-fill
</option>
2051 options, and recompile the program with suitable options and symbols for
2052 debugger support. When so configured, jemalloc incorporates a wide variety
2053 of run-time assertions that catch application errors such as double-free,
2054 write-after-free, etc.
</para>
2056 <para>Programs often accidentally depend on
“uninitialized
”
2057 memory actually being filled with zero bytes. Junk filling
2058 (see the
<link linkend=
"opt.junk"><mallctl>opt.junk
</mallctl></link>
2059 option) tends to expose such bugs in the form of obviously incorrect
2060 results and/or coredumps. Conversely, zero
2061 filling (see the
<link
2062 linkend=
"opt.zero"><mallctl>opt.zero
</mallctl></link> option) eliminates
2063 the symptoms of such bugs. Between these two options, it is usually
2064 possible to quickly detect, diagnose, and eliminate such bugs.
</para>
2066 <para>This implementation does not provide much detail about the problems
2067 it detects, because the performance impact for storing such information
2068 would be prohibitive. There are a number of allocator implementations
2069 available on the Internet which focus on detecting and pinpointing problems
2070 by trading performance for extra sanity checks and detailed
2073 <refsect1 id=
"diagnostic_messages">
2074 <title>DIAGNOSTIC MESSAGES
</title>
2075 <para>If any of the memory allocation/deallocation functions detect an
2076 error or warning condition, a message will be printed to file descriptor
2077 <constant>STDERR_FILENO
</constant>. Errors will result in the process
2078 dumping core. If the
<link
2079 linkend=
"opt.abort"><mallctl>opt.abort
</mallctl></link> option is set, most
2080 warnings are treated as errors.
</para>
2082 <para>The
<varname>malloc_message
</varname> variable allows the programmer
2083 to override the function which emits the text strings forming the errors
2084 and warnings if for some reason the
<constant>STDERR_FILENO
</constant> file
2085 descriptor is not suitable for this.
2086 <function>malloc_message
<parameter/></function> takes the
2087 <parameter>cbopaque
</parameter> pointer argument that is
2088 <constant>NULL
</constant> unless overridden by the arguments in a call to
2089 <function>malloc_stats_print
<parameter/></function>, followed by a string
2090 pointer. Please note that doing anything which tries to allocate memory in
2091 this function is likely to result in a crash or deadlock.
</para>
2093 <para>All messages are prefixed by
2094 “<computeroutput><jemalloc
>:
</computeroutput>”.
</para>
2096 <refsect1 id=
"return_values">
2097 <title>RETURN VALUES
</title>
2099 <title>Standard API
</title>
2100 <para>The
<function>malloc
<parameter/></function> and
2101 <function>calloc
<parameter/></function> functions return a pointer to the
2102 allocated memory if successful; otherwise a
<constant>NULL
</constant>
2103 pointer is returned and
<varname>errno
</varname> is set to
2104 <errorname>ENOMEM
</errorname>.
</para>
2106 <para>The
<function>posix_memalign
<parameter/></function> function
2107 returns the value
0 if successful; otherwise it returns an error value.
2108 The
<function>posix_memalign
<parameter/></function> function will fail
2112 <term><errorname>EINVAL
</errorname></term>
2114 <listitem><para>The
<parameter>alignment
</parameter> parameter is
2115 not a power of
2 at least as large as
2116 <code language=
"C">sizeof(
<type>void *
</type>)
</code>.
2120 <term><errorname>ENOMEM
</errorname></term>
2122 <listitem><para>Memory allocation error.
</para></listitem>
2127 <para>The
<function>realloc
<parameter/></function> function returns a
2128 pointer, possibly identical to
<parameter>ptr
</parameter>, to the
2129 allocated memory if successful; otherwise a
<constant>NULL
</constant>
2130 pointer is returned, and
<varname>errno
</varname> is set to
2131 <errorname>ENOMEM
</errorname> if the error was the result of an
2132 allocation failure. The
<function>realloc
<parameter/></function>
2133 function always leaves the original buffer intact when an error occurs.
2136 <para>The
<function>free
<parameter/></function> function returns no
2140 <title>Non-standard API
</title>
2141 <para>The
<function>malloc_usable_size
<parameter/></function> function
2142 returns the usable size of the allocation pointed to by
2143 <parameter>ptr
</parameter>.
</para>
2145 <para>The
<function>mallctl
<parameter/></function>,
2146 <function>mallctlnametomib
<parameter/></function>, and
2147 <function>mallctlbymib
<parameter/></function> functions return
0 on
2148 success; otherwise they return an error value. The functions will fail
2152 <term><errorname>EINVAL
</errorname></term>
2154 <listitem><para><parameter>newp
</parameter> is not
2155 <constant>NULL
</constant>, and
<parameter>newlen
</parameter> is too
2156 large or too small. Alternatively,
<parameter>*oldlenp
</parameter>
2157 is too large or too small; in this case as much data as possible
2158 are read despite the error.
</para></listitem>
2161 <term><errorname>ENOMEM
</errorname></term>
2163 <listitem><para><parameter>*oldlenp
</parameter> is too short to
2164 hold the requested value.
</para></listitem>
2167 <term><errorname>ENOENT
</errorname></term>
2169 <listitem><para><parameter>name
</parameter> or
2170 <parameter>mib
</parameter> specifies an unknown/invalid
2171 value.
</para></listitem>
2174 <term><errorname>EPERM
</errorname></term>
2176 <listitem><para>Attempt to read or write void value, or attempt to
2177 write read-only value.
</para></listitem>
2180 <term><errorname>EAGAIN
</errorname></term>
2182 <listitem><para>A memory allocation failure
2183 occurred.
</para></listitem>
2186 <term><errorname>EFAULT
</errorname></term>
2188 <listitem><para>An interface with side effects failed in some way
2189 not directly related to
<function>mallctl*
<parameter/></function>
2190 read/write processing.
</para></listitem>
2196 <title>Experimental API
</title>
2197 <para>The
<function>allocm
<parameter/></function>,
2198 <function>rallocm
<parameter/></function>,
2199 <function>sallocm
<parameter/></function>, and
2200 <function>dallocm
<parameter/></function> functions return
2201 <constant>ALLOCM_SUCCESS
</constant> on success; otherwise they return an
2202 error value. The
<function>allocm
<parameter/></function> and
2203 <function>rallocm
<parameter/></function> functions will fail if:
2206 <term><errorname>ALLOCM_ERR_OOM
</errorname></term>
2208 <listitem><para>Out of memory. Insufficient contiguous memory was
2209 available to service the allocation request. The
2210 <function>allocm
<parameter/></function> function additionally sets
2211 <parameter>*ptr
</parameter> to
<constant>NULL
</constant>, whereas
2212 the
<function>rallocm
<parameter/></function> function leaves
2213 <constant>*ptr
</constant> unmodified.
</para></listitem>
2216 The
<function>rallocm
<parameter/></function> function will also
2220 <term><errorname>ALLOCM_ERR_NOT_MOVED
</errorname></term>
2222 <listitem><para><constant>ALLOCM_NO_MOVE
</constant> was specified,
2223 but the reallocation request could not be serviced without moving
2224 the object.
</para></listitem>
2230 <refsect1 id=
"environment">
2231 <title>ENVIRONMENT
</title>
2232 <para>The following environment variable affects the execution of the
2233 allocation functions:
2236 <term><envar>MALLOC_CONF
</envar></term>
2238 <listitem><para>If the environment variable
2239 <envar>MALLOC_CONF
</envar> is set, the characters it contains
2240 will be interpreted as options.
</para></listitem>
2245 <refsect1 id=
"examples">
2246 <title>EXAMPLES
</title>
2247 <para>To dump core whenever a problem occurs:
2248 <screen>ln -s 'abort:true' /etc/malloc.conf
</screen>
2250 <para>To specify in the source a chunk size that is
16 MiB:
2251 <programlisting language=
"C"><![CDATA[
2252 malloc_conf = "lg_chunk:
24";]]
></programlisting></para>
2254 <refsect1 id=
"see_also">
2255 <title>SEE ALSO
</title>
2256 <para><citerefentry><refentrytitle>madvise
</refentrytitle>
2257 <manvolnum>2</manvolnum></citerefentry>,
2258 <citerefentry><refentrytitle>mmap
</refentrytitle>
2259 <manvolnum>2</manvolnum></citerefentry>,
2260 <citerefentry><refentrytitle>sbrk
</refentrytitle>
2261 <manvolnum>2</manvolnum></citerefentry>,
2262 <citerefentry><refentrytitle>alloca
</refentrytitle>
2263 <manvolnum>3</manvolnum></citerefentry>,
2264 <citerefentry><refentrytitle>atexit
</refentrytitle>
2265 <manvolnum>3</manvolnum></citerefentry>,
2266 <citerefentry><refentrytitle>getpagesize
</refentrytitle>
2267 <manvolnum>3</manvolnum></citerefentry></para>
2269 <refsect1 id=
"standards">
2270 <title>STANDARDS
</title>
2271 <para>The
<function>malloc
<parameter/></function>,
2272 <function>calloc
<parameter/></function>,
2273 <function>realloc
<parameter/></function>, and
2274 <function>free
<parameter/></function> functions conform to ISO/IEC
2275 9899:
1990 (
“ISO C90
”).
</para>
2277 <para>The
<function>posix_memalign
<parameter/></function> function conforms
2278 to IEEE Std
1003.1-
2001 (
“POSIX
.1”).
</para>
projects / redis.git / blob