| .\" Copyright (c) 2006-2010 Jason Evans <jasone@canonware.com>. |
| .\" All rights reserved. |
| .\" Copyright (c) 2009 Facebook, Inc. All rights reserved. |
| .\" |
| .\" See COPYING for licensing terms provided by the above copyright holders. |
| .\" |
| .\" Copyright (c) 1980, 1991, 1993 |
| .\" The Regents of the University of California. All rights reserved. |
| .\" |
| .\" This code is derived from software contributed to Berkeley by |
| .\" the American National Standards Committee X3, on Information |
| .\" Processing Systems. |
| .\" |
| .\" Redistribution and use in source and binary forms, with or without |
| .\" modification, are permitted provided that the following conditions |
| .\" are met: |
| .\" 1. Redistributions of source code must retain the above copyright |
| .\" notice, this list of conditions and the following disclaimer. |
| .\" 2. Redistributions in binary form must reproduce the above copyright |
| .\" notice, this list of conditions and the following disclaimer in the |
| .\" documentation and/or other materials provided with the distribution. |
| .\" 3. Neither the name of the University nor the names of its contributors |
| .\" may be used to endorse or promote products derived from this software |
| .\" without specific prior written permission. |
| .\" |
| .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND |
| .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE |
| .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE |
| .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE |
| .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL |
| .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS |
| .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) |
| .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT |
| .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY |
| .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF |
| .\" SUCH DAMAGE. |
| .\" |
| .\" @(#)malloc.3 8.1 (Berkeley) 6/4/93 |
| .\" $FreeBSD: head/lib/libc/stdlib/malloc.3 182225 2008-08-27 02:00:53Z jasone $ |
| .\" |
| .Dd October 24, 2010 |
| .Dt jemalloc 3 |
| .Os |
| .Sh NAME |
| .Nm @jemalloc_prefix@malloc , |
| .Nm @jemalloc_prefix@calloc , |
| .Nm @jemalloc_prefix@posix_memalign , |
| .Nm @jemalloc_prefix@realloc , |
| .Nm @jemalloc_prefix@free , |
| .Nm @jemalloc_prefix@malloc_usable_size , |
| .Nm @jemalloc_prefix@malloc_stats_print , |
| .Nm @jemalloc_prefix@mallctl , |
| .Nm @jemalloc_prefix@mallctlnametomib , |
| .Nm @jemalloc_prefix@mallctlbymib , |
| .Nm @jemalloc_prefix@allocm , |
| .Nm @jemalloc_prefix@rallocm , |
| .Nm @jemalloc_prefix@sallocm , |
| .Nm @jemalloc_prefix@dallocm |
| .Nd general purpose memory allocation functions |
| .Sh LIBRARY |
| .Sy libjemalloc@install_suffix@ |
| .Pp |
| This manual describes jemalloc @jemalloc_version@. |
| More information can be found at the |
| .UR http://\:www.canonware.com/\:jemalloc/ |
| jemalloc website |
| .UE . |
| .Sh SYNOPSIS |
| .In stdlib.h |
| .In jemalloc/jemalloc@install_suffix@.h |
| .Ss Standard API |
| .Ft void * |
| .Fn @jemalloc_prefix@malloc "size_t size" |
| .Ft void * |
| .Fn @jemalloc_prefix@calloc "size_t number" "size_t size" |
| .Ft int |
| .Fn @jemalloc_prefix@posix_memalign "void **ptr" "size_t alignment" "size_t size" |
| .Ft void * |
| .Fn @jemalloc_prefix@realloc "void *ptr" "size_t size" |
| .Ft void |
| .Fn @jemalloc_prefix@free "void *ptr" |
| .Ss Non-standard API |
| .Ft size_t |
| .Fn @jemalloc_prefix@malloc_usable_size "const void *ptr" |
| .Ft void |
| .Fn @jemalloc_prefix@malloc_stats_print "void (*write_cb)(void *" "const char *)" "void *cbopaque" "const char *opts" |
| .Ft int |
| .Fn @jemalloc_prefix@mallctl "const char *name" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" |
| .Ft int |
| .Fn @jemalloc_prefix@mallctlnametomib "const char *name" "int *mibp" "size_t *miblenp" |
| .Ft int |
| .Fn @jemalloc_prefix@mallctlbymib "const size_t *mib" "size_t miblen" "void *oldp" "size_t *oldlenp" "void *newp" "size_t newlen" |
| .Ft const char * |
| .Va @jemalloc_prefix@malloc_conf ; |
| .Ft void |
| .Fn \*(lp*@jemalloc_prefix@malloc_message\*(rp "void *cbopaque" "const char *s" |
| .Ss Experimental API |
| .Ft int |
| .Fn @jemalloc_prefix@allocm "void **ptr" "size_t *rsize" "size_t size" "int flags" |
| .Ft int |
| .Fn @jemalloc_prefix@rallocm "void **ptr" "size_t *rsize" "size_t size" "size_t extra" "int flags" |
| .Ft int |
| .Fn @jemalloc_prefix@sallocm "const void *ptr" "size_t *rsize" "int flags" |
| .Ft int |
| .Fn @jemalloc_prefix@dallocm "void *ptr" "int flags" |
| .Sh DESCRIPTION |
| .Ss Standard API |
| The |
| .Fn @jemalloc_prefix@malloc |
| function allocates |
| .Fa size |
| bytes of uninitialized memory. |
| The allocated space is suitably aligned |
| @roff_tiny@(after possible pointer coercion) |
| for storage of any type of object. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@calloc |
| function allocates space for |
| .Fa number |
| objects, |
| each |
| .Fa size |
| bytes in length. |
| The result is identical to calling |
| .Fn @jemalloc_prefix@malloc |
| with an argument of |
| .Dq "number * size" , |
| with the exception that the allocated memory is explicitly initialized |
| to zero bytes. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@posix_memalign |
| function allocates |
| .Fa size |
| bytes of memory such that the allocation's base address is an even multiple of |
| .Fa alignment , |
| and returns the allocation in the value pointed to by |
| .Fa ptr . |
| The requested |
| .Fa alignment |
| must be a power of 2 at least as large as |
| .Fn sizeof "void *" . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@realloc |
| function changes the size of the previously allocated memory referenced by |
| .Fa ptr |
| to |
| .Fa size |
| bytes. |
| The contents of the memory are unchanged up to the lesser of the new and |
| old sizes. |
| If the new size is larger, |
| the contents of the newly allocated portion of the memory are undefined. |
| Upon success, the memory referenced by |
| .Fa ptr |
| is freed and a pointer to the newly allocated memory is returned. |
| Note that |
| .Fn @jemalloc_prefix@realloc |
| may move the memory allocation, resulting in a different return value than |
| .Fa ptr . |
| If |
| .Fa ptr |
| is |
| .Dv NULL , |
| the |
| .Fn @jemalloc_prefix@realloc |
| function behaves identically to |
| .Fn @jemalloc_prefix@malloc |
| for the specified size. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@free |
| function causes the allocated memory referenced by |
| .Fa ptr |
| to be made available for future allocations. |
| If |
| .Fa ptr |
| is |
| .Dv NULL , |
| no action occurs. |
| .Ss Non-standard API |
| The |
| .Fn @jemalloc_prefix@malloc_usable_size |
| function returns the usable size of the allocation pointed to by |
| .Fa ptr . |
| The return value may be larger than the size that was requested during |
| allocation. |
| The |
| .Fn @jemalloc_prefix@malloc_usable_size |
| function is not a mechanism for in-place |
| .Fn @jemalloc_prefix@realloc ; |
| rather it is provided solely as a tool for introspection purposes. |
| Any discrepancy between the requested allocation size and the size reported by |
| .Fn @jemalloc_prefix@malloc_usable_size |
| should not be depended on, since such behavior is entirely |
| implementation-dependent. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@malloc_stats_print |
| function writes human-readable summary statistics via the |
| .Fa write_cb |
| callback function pointer and |
| .Fa cbopaque |
| data passed to |
| .Fn write_cb , |
| or |
| .Fn @jemalloc_prefix@malloc_message |
| if |
| .Fa write_cb |
| is |
| .Dv NULL . |
| This function can be called repeatedly. |
| General information that never changes |
| during execution can be omitted by specifying |
| .Dq g |
| as a character within the |
| .Fa opts |
| string. |
| Note that |
| .Fn @jemalloc_prefix@malloc_message |
| uses the |
| .Fn @jemalloc_prefix@mallctl* |
| functions internally, so inconsistent statistics can be reported if multiple |
| threads use these functions simultaneously. |
| @roff_stats@.Dq m |
| @roff_stats@and |
| @roff_stats@.Dq a |
| @roff_stats@can be specified to omit merged arena and per arena statistics, |
| @roff_stats@respectively. |
| @roff_stats@.Dq b |
| @roff_stats@and |
| @roff_stats@.Dq l |
| @roff_stats@can be specified to omit per size class statistics for bins and |
| @roff_stats@large objects, respectively. |
| Unrecognized characters are silently ignored. |
| @roff_tcache@Note that thread caching may prevent some statistics from being |
| @roff_tcache@completely up to date, since extra locking would be required to |
| @roff_tcache@merge counters that track thread cache operations. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@mallctl |
| function provides a general interface for introspecting the memory allocator, |
| as well as setting modifiable parameters and triggering actions. |
| The period-separated |
| .Fa name |
| argument specifies a location in a tree-structured namespace; see the |
| .Sx "MALLCTL NAMESPACE" |
| section for documentation on the tree contents. |
| To read a value, pass a pointer via |
| .Fa oldp |
| to adequate space to contain the value, and a pointer to its length via |
| .Fa oldlenp ; |
| otherwise pass |
| .Dv NULL |
| and |
| .Dv NULL . |
| Similarly, to write a value, pass a pointer to the value via |
| .Fa newp , |
| and its length via |
| .Fa newlen ; |
| otherwise pass |
| .Dv NULL |
| and 0. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@mallctlnametomib |
| function provides a way to avoid repeated name lookups for applications that |
| repeatedly query the same portion of the namespace, by translating a name to a |
| .Dq Management Information Base |
| (MIB) that can be passed repeatedly to |
| .Fn @jemalloc_prefix@mallctlbymib . |
| Upon successful return from |
| .Fn @jemalloc_prefix@mallctlnametomib , |
| .Fa mibp |
| contains an array of |
| .Fa *miblenp |
| integers, where |
| .Fa *miblenp |
| is the lesser of the number of components in |
| .Fa name |
| and the input value of |
| .Fa *miblenp . |
| Thus it is possible to pass a |
| .Fa *miblenp |
| that is smaller than the number of period-separated name components, which |
| results in a partial MIB that can be used as the basis for constructing a |
| complete MIB. |
| For name components that are integers (e.g. the 2 in |
| .Qq arenas.bin.2.size ) , |
| the corresponding MIB component will always be that integer. |
| Therefore, it is legitimate to construct code like the following: |
| .Pp |
| .Bd -literal -offset indent -compact |
| unsigned nbins, i; |
| int mib[4]; |
| size_t len, miblen; |
| |
| len = sizeof(nbins); |
| @jemalloc_prefix@mallctl("arenas.nbins", &nbins, &len, NULL, 0); |
| |
| miblen = 4; |
| @jemalloc_prefix@mallnametomib("arenas.bin.0.size", mib, &miblen); |
| for (i = 0; i < nbins; i++) { |
| size_t bin_size; |
| |
| mib[2] = i; |
| len = sizeof(bin_size); |
| @jemalloc_prefix@mallctlbymib(mib, miblen, &bin_size, &len, NULL, 0); |
| /* Do something with bin_size... */ |
| } |
| .Ed |
| .Ss Experimental API |
| The experimental API is subject to change or removal without regard for |
| backward compatibility. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@allocm , |
| .Fn @jemalloc_prefix@rallocm , |
| .Fn @jemalloc_prefix@sallocm , |
| and |
| .Fn @jemalloc_prefix@dallocm |
| functions all have a |
| .Fa flags |
| argument that can be used to specify options. |
| The functions only check the options that are contextually relevant. |
| Use bitwise or (|) operations to specify one or more of the following: |
| .Bl -tag -width ".Dv ALLOCM_LG_ALIGN(la)" |
| .It ALLOCM_LG_ALIGN(la) |
| Align the memory allocation to start at an address that is a multiple of |
| (1 << |
| .Fa la ) . |
| This macro does not validate that |
| .Fa la |
| is within the valid range. |
| .It ALLOCM_ALIGN(a) |
| Align the memory allocation to start at an address that is a multiple of |
| .Fa a , |
| where |
| .Fa a |
| is a power of two. |
| This macro does not validate that |
| .Fa a |
| is a power of 2. |
| .It ALLOCM_ZERO |
| Initialize newly allocated memory to contain zero bytes. |
| In the growing reallocation case, the real size prior to reallocation defines |
| the boundary between untouched bytes and those that are initialized to contain |
| zero bytes. |
| If this option is absent, newly allocated memory is uninitialized. |
| .It ALLOCM_NO_MOVE |
| For reallocation, fail rather than moving the object. |
| This constraint can apply to both growth and shrinkage. |
| .El |
| .Pp |
| The |
| .Fn @jemalloc_prefix@allocm |
| function allocates at least |
| .Fa size |
| bytes of memory, sets |
| .Fa *ptr |
| to the base address of the allocation, and sets |
| .Fa *rsize |
| to the real size of the allocation if |
| .Fa rsize |
| is not |
| .Dv NULL . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@rallocm |
| function resizes the allocation at |
| .Fa *ptr |
| to be at least |
| .Fa size |
| bytes, sets |
| .Fa *ptr |
| to the base address of the allocation if it moved, and sets |
| .Fa *rsize |
| to the real size of the allocation if |
| .Fa rsize |
| is not |
| .Dv NULL . |
| If |
| .Fa extra |
| is non-zero, an attempt is made to resize the allocation to be at least |
| .Fa ( size |
| + |
| .Fa extra ) |
| bytes, though inability to allocate the extra byte(s) will not by itself result |
| in failure. |
| Behavior is undefined if |
| .Fa ( size |
| + |
| .Fa extra |
| > |
| .Dv SIZE_T_MAX ) . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@sallocm |
| function sets |
| .Fa *rsize |
| to the real size of the allocation. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@dallocm |
| function causes the memory referenced by |
| .Fa ptr |
| to be made available for future allocations. |
| .Sh TUNING |
| Once, when the first call is made to one of the memory allocation routines, the |
| allocator initializes its internals based in part on various options that can |
| be specified at compile- or run-time. |
| .Pp |
| The string pointed to by the global variable |
| .Va @jemalloc_prefix@malloc_conf , |
| the |
| .Dq name |
| of the file referenced by the symbolic link named |
| .Pa /etc/@jemalloc_prefix@malloc.conf , |
| and the value of the environment variable |
| .Ev @jemalloc_cprefix@MALLOC_CONF , |
| will be interpreted, in that order, from left to right as options. |
| .Pp |
| An options string is a comma-separated list of option:value pairs. |
| There is one key corresponding to each |
| .Dq opt.* |
| mallctl. |
| For example, |
| .Dq abort:true,narenas:1 |
| sets the |
| .Dq opt.abort |
| and |
| .Dq opt.narenas |
| options. |
| Some options have boolean values (true/false), others have integer values (base |
| 8, 10, or 16, depending on prefix), and yet others have raw string values. |
| .Sh IMPLEMENTATION NOTES |
| @roff_dss@Traditionally, allocators have used |
| @roff_dss@.Xr sbrk 2 |
| @roff_dss@to obtain memory, which is suboptimal for several reasons, including |
| @roff_dss@race conditions, increased fragmentation, and artificial limitations |
| @roff_dss@on maximum usable memory. |
| @roff_dss@This allocator uses both |
| @roff_dss@.Xr sbrk 2 |
| @roff_dss@and |
| @roff_dss@.Xr mmap 2 , |
| @roff_dss@in that order of preference. |
| .Pp |
| This allocator uses multiple arenas in order to reduce lock contention for |
| threaded programs on multi-processor systems. |
| This works well with regard to threading scalability, but incurs some costs. |
| There is a small fixed per-arena overhead, and additionally, arenas manage |
| memory completely independently of each other, which means a small fixed |
| increase in overall memory fragmentation. |
| These overheads are not generally an issue, given the number of arenas normally |
| used. |
| Note that using substantially more arenas than the default is not likely to |
| improve performance, mainly due to reduced cache performance. |
| However, it may make sense to reduce the number of arenas if an application |
| does not make much use of the allocation functions. |
| .Pp |
| @roff_tcache@In addition to multiple arenas, this allocator supports |
| @roff_tcache@thread-specific caching for small and large objects, in order to |
| @roff_tcache@make it possible to completely avoid synchronization for most |
| @roff_tcache@allocation requests. |
| @roff_tcache@Such caching allows very fast allocation in the common case, but it |
| @roff_tcache@increases memory usage and fragmentation, since a bounded number of |
| @roff_tcache@objects can remain allocated in each thread cache. |
| @roff_tcache@.Pp |
| Memory is conceptually broken into equal-sized chunks, where the chunk size is |
| a power of two that is greater than the page size. |
| Chunks are always aligned to multiples of the chunk size. |
| This alignment makes it possible to find metadata for user objects very |
| quickly. |
| .Pp |
| User objects are broken into three categories according to size: small, large, |
| and huge. |
| Small objects are smaller than one page. |
| Large objects are smaller than the chunk size. |
| Huge objects are a multiple of the chunk size. |
| Small and large objects are managed by arenas; huge objects are managed |
| separately in a single data structure that is shared by all threads. |
| Huge objects are used by applications infrequently enough that this single |
| data structure is not a scalability issue. |
| .Pp |
| Each chunk that is managed by an arena tracks its contents as runs of |
| contiguous pages (unused, backing a set of small objects, or backing one large |
| object). |
| The combination of chunk alignment and chunk page maps makes it possible to |
| determine all metadata regarding small and large allocations in constant time. |
| .Pp |
| Small objects are managed in groups by page runs. |
| Each run maintains a frontier and free list to track which regions are in use. |
| @roff_tiny@Allocation requests that are no more than half the quantum (8 or 16, |
| @roff_tiny@depending on architecture) are rounded up to the nearest power of |
| @roff_tiny@two. |
| Allocation requests that are |
| @roff_tiny@more than half the quantum, but |
| no more than the minimum cacheline-multiple size class (see the |
| .Dq opt.lg_qspace_max |
| option) are rounded up to the nearest multiple of the |
| @roff_tiny@quantum. |
| @roff_no_tiny@quantum (8 or 16, depending on architecture). |
| Allocation requests that are more than the minimum cacheline-multiple size |
| class, but no more than the minimum subpage-multiple size class (see the |
| .Dq opt.lg_cspace_max |
| option) are rounded up to the nearest multiple of the cacheline size (64). |
| Allocation requests that are more than the minimum subpage-multiple size class, |
| but no more than the maximum subpage-multiple size class are rounded up to the |
| nearest multiple of the subpage size (256). |
| Allocation requests that are more than the maximum subpage-multiple size class, |
| but small enough to fit in an arena-managed chunk (see the |
| .Dq opt.lg_chunk |
| option), are rounded up to the nearest run size. |
| Allocation requests that are too large to fit in an arena-managed chunk are |
| rounded up to the nearest multiple of the chunk size. |
| .Pp |
| Allocations are packed tightly together, which can be an issue for |
| multi-threaded applications. |
| If you need to assure that allocations do not suffer from cacheline sharing, |
| round your allocation requests up to the nearest multiple of the cacheline |
| size, or specify cacheline alignment when allocating. |
| .Pp |
| Assuming 4 MiB chunks, 4 KiB pages, and a 16-byte quantum on a 64-bit system, |
| the size classes in each category are as follows: |
| .\"----------------------------------------------------------------------------- |
| .TS |
| allbox tab(;); |
| LLL |
| LLL |
| ^LL |
| ^LL |
| ^LL |
| LsL |
| LsL. |
| Category;Subcategory;Size |
| @roff_tiny@Small;Tiny;[8] |
| @roff_no_tiny@Small;Tiny;[disabled] |
| ;Quantum-spaced;[16, 32, 48, ..., 128] |
| ;Cacheline-spaced;[192, 256, 320, ..., 512] |
| ;Sub-page-spaced;[768, 1024, 1280, ..., 3840] |
| Large;[4 KiB, 8 KiB, 12 KiB, ..., 4072 KiB] |
| Huge;[4 MiB, 8 MiB, 12 MiB, ...] |
| .TE |
| .\"----------------------------------------------------------------------------- |
| .Sh MALLCTL NAMESPACE |
| The following names are defined in the namespace accessible via the |
| .Fn @jemalloc_prefix@mallctl* |
| functions. |
| Value types are specified in parentheses, and their readable/writable statuses |
| are encoded as rw, r-, -w, or --. |
| A name element encoded as <i> or <j> indicates an integer component, where the |
| integer varies from 0 to some upper value that must be determined via |
| introspection. |
| @roff_stats@In the case of |
| @roff_stats@.Dq stats.arenas.<i>.* , |
| @roff_stats@<i> equal to |
| @roff_stats@.Dq arenas.narenas |
| @roff_stats@can be used to access the summation of statistics from all arenas. |
| .Pp |
| Take special note of the |
| .Dq epoch |
| mallctl, which controls refreshing of cached dynamic statistics. |
| .Bl -ohang |
| .\"----------------------------------------------------------------------------- |
| .It Sy "version (const char *) r-" |
| .Bd -ragged -offset indent -compact |
| Return the jemalloc version string. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "epoch (uint64_t) rw" |
| .Bd -ragged -offset indent -compact |
| If a value is passed in, refresh the data from which the |
| .Fn @jemalloc_prefix@mallctl* |
| functions report values, and increment the epoch. |
| Return the current epoch. |
| This is useful for detecting whether another thread caused a refresh. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.debug (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-debug was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.dss (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-dss was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.dynamic_page_shift (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-dynamic-page-shift was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.fill (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-fill was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.lazy_lock (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-lazy-lock was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.prof (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-prof was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.prof_libgcc (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --disable-prof-libgcc was not specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.prof_libunwind (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-prof-libunwind was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.stats (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-stats was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.swap (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-swap was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.sysv (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-sysv was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.tcache (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --disable-tcache was not specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.tiny (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --disable-tiny was not specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.tls (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --disable-tls was not specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "config.xmalloc (bool) r-" |
| .Bd -ragged -offset indent -compact |
| --enable-xmalloc was specified during build configuration. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.abort (bool) r-" |
| .Bd -ragged -offset indent -compact |
| Abort-on-warning enabled/disabled. |
| If true, most warnings are fatal. |
| The process will call |
| .Xr abort 3 |
| in these cases. |
| This option is |
| @roff_debug@enabled |
| @roff_no_debug@disabled |
| by default. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.lg_qspace_max (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Size (log base 2) of the maximum size class that is a multiple of the quantum |
| (8 or 16 bytes, depending on architecture). |
| Above this size, cacheline spacing is used for size classes. |
| The default value is 128 bytes (2^7). |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.lg_cspace_max (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Size (log base 2) of the maximum size class that is a multiple of the cacheline |
| size (64). |
| Above this size, subpage spacing (256 bytes) is used for size classes. |
| The default value is 512 bytes (2^9). |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.lg_chunk (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Virtual memory chunk size (log base 2). |
| The default chunk size is 4 MiB (2^22). |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.narenas (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum number of arenas to use. |
| The default maximum number of arenas is four times the number of CPUs, or one |
| if there is a single CPU. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.lg_dirty_mult (ssize_t) r-" |
| .Bd -ragged -offset indent -compact |
| Per-arena minimum ratio (log base 2) of active to dirty pages. |
| Some dirty unused pages may be allowed to accumulate, within the limit set by |
| the ratio (or one chunk worth of dirty pages, whichever is greater), before |
| informing the kernel about some of those pages via |
| .Xr madvise 2 |
| or a similar system call. |
| This provides the kernel with sufficient information to recycle dirty pages if |
| physical memory becomes scarce and the pages remain unused. |
| The default minimum ratio is 32:1 (2^5:1); an option value of -1 will disable |
| dirty page purging. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.stats_print (bool) r-" |
| .Bd -ragged -offset indent -compact |
| Enable/disable statistics printing at exit. |
| If enabled, the |
| .Fn @jemalloc_prefix@malloc_stats_print |
| function is called at program exit via an |
| .Xr atexit 3 |
| function. |
| @roff_stats@This has the potential to cause deadlock for a multi-threaded |
| @roff_stats@process that exits while one or more threads are executing in the |
| @roff_stats@memory allocation functions. |
| @roff_stats@Therefore, this option should only be used with care; it is |
| @roff_stats@primarily intended as a performance tuning aid during application |
| @roff_stats@development. |
| This option is disabled by default. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_fill@.It Sy "opt.junk (bool) r-" |
| @roff_fill@.Bd -ragged -offset indent -compact |
| @roff_fill@Junk filling enabled/disabled. |
| @roff_fill@If enabled, each byte of uninitialized allocated memory will be |
| @roff_fill@initialized to 0xa5. |
| @roff_fill@All deallocated memory will be initialized to 0x5a. |
| @roff_fill@This is intended for debugging and will impact performance |
| @roff_fill@negatively. |
| @roff_fill@This option is |
| @roff_fill@@roff_debug@enabled |
| @roff_fill@@roff_no_debug@disabled |
| @roff_fill@by default. |
| @roff_fill@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_fill@.It Sy "opt.zero (bool) r-" |
| @roff_fill@.Bd -ragged -offset indent -compact |
| @roff_fill@Zero filling enabled/disabled. |
| @roff_fill@If enabled, each byte of uninitialized allocated memory will be |
| @roff_fill@initialized to 0. |
| @roff_fill@Note that this initialization only happens once for each byte, so |
| @roff_fill@.Fn @jemalloc_prefix@realloc |
| @roff_fill@calls do not zero memory that was previously allocated. |
| @roff_fill@This is intended for debugging and will impact performance |
| @roff_fill@negatively. |
| @roff_fill@This option is disabled by default. |
| @roff_fill@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_sysv@.It Sy "opt.sysv (bool) r-" |
| @roff_sysv@.Bd -ragged -offset indent -compact |
| @roff_sysv@If enabled, attempting to allocate zero bytes will return a |
| @roff_sysv@.Dv NULL |
| @roff_sysv@pointer instead of a valid pointer. |
| @roff_sysv@(The default behavior is to make a minimal allocation and return a |
| @roff_sysv@pointer to it.) |
| @roff_sysv@This option is provided for System V compatibility. |
| @roff_sysv@@roff_xmalloc@This option is incompatible with the |
| @roff_sysv@@roff_xmalloc@.Dq opt.xmalloc |
| @roff_sysv@@roff_xmalloc@option. |
| @roff_sysv@This option is disabled by default. |
| @roff_sysv@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_xmalloc@.It Sy "opt.xmalloc (bool) r-" |
| @roff_xmalloc@.Bd -ragged -offset indent -compact |
| @roff_xmalloc@Abort-on-out-of-memory enabled/disabled. |
| @roff_xmalloc@If enabled, rather than returning failure for any allocation |
| @roff_xmalloc@function, display a diagnostic message on |
| @roff_xmalloc@.Dv STDERR_FILENO |
| @roff_xmalloc@and cause the program to drop core (using |
| @roff_xmalloc@.Xr abort 3 ) . |
| @roff_xmalloc@If an application is designed to depend on this behavior, set the |
| @roff_xmalloc@option at compile time by including the following in the source |
| @roff_xmalloc@code: |
| @roff_xmalloc@.Bd -literal -offset indent |
| @roff_xmalloc@@jemalloc_prefix@malloc_conf = "xmalloc:true"; |
| @roff_xmalloc@.Ed |
| @roff_xmalloc@.Pp |
| @roff_xmalloc@This option is disabled by default. |
| @roff_xmalloc@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_tcache@.It Sy "opt.tcache (bool) r-" |
| @roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_tcache@Thread-specific caching enabled/disabled. |
| @roff_tcache@When there are multiple threads, each thread uses a |
| @roff_tcache@thread-specific cache for objects up to a certain size. |
| @roff_tcache@Thread-specific caching allows many allocations to be satisfied |
| @roff_tcache@without performing any thread synchronization, at the cost of |
| @roff_tcache@increased memory use. |
| @roff_tcache@See the |
| @roff_tcache@.Dq opt.lg_tcache_gc_sweep |
| @roff_tcache@and |
| @roff_tcache@.Dq opt.tcache_max |
| @roff_tcache@options for related tuning information. |
| @roff_tcache@This option is enabled by default. |
| @roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_tcache@.It Sy "opt.lg_tcache_gc_sweep (ssize_t) r-" |
| @roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_tcache@Approximate interval (log base 2) between full thread-specific |
| @roff_tcache@cache garbage collection sweeps, counted in terms of |
| @roff_tcache@thread-specific cache allocation/deallocation events. |
| @roff_tcache@Garbage collection is actually performed incrementally, one size |
| @roff_tcache@class at a time, in order to avoid large collection pauses. |
| @roff_tcache@The default sweep interval is 8192 (2^13); setting this option to |
| @roff_tcache@-1 will disable garbage collection. |
| @roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_tcache@.It Sy "opt.lg_tcache_max (size_t) r-" |
| @roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_tcache@Maximum size class (log base 2) to cache in the thread-specific |
| @roff_tcache@cache. |
| @roff_tcache@At a minimum, all small size classes are cached, and at a maximum |
| @roff_tcache@all large size classes are cached. |
| @roff_tcache@The default maximum is 32 KiB (2^15). |
| @roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof (bool) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Memory profiling enabled/disabled. |
| @roff_prof@If enabled, profile memory allocation activity, and use an |
| @roff_prof@.Xr atexit 3 |
| @roff_prof@function to dump final memory usage to a file named according to |
| @roff_prof@the pattern |
| @roff_prof@.Pa <prefix>.<pid>.<seq>.f.heap , |
| @roff_prof@where |
| @roff_prof@.Pa <prefix> |
| @roff_prof@is controlled by the |
| @roff_prof@.Dq opt.prof_prefix |
| @roff_prof@option. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.lg_prof_bt_max |
| @roff_prof@option for backtrace depth control. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.prof_active |
| @roff_prof@option for on-the-fly activation/deactivation. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.lg_prof_sample |
| @roff_prof@option for probabilistic sampling control. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.prof_accum |
| @roff_prof@option for control of cumulative sample reporting. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.lg_prof_tcmax |
| @roff_prof@option for control of per thread backtrace caching. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.lg_prof_interval |
| @roff_prof@option for information on interval-triggered profile dumping, and the |
| @roff_prof@.Dq opt.prof_gdump |
| @roff_prof@option for information on high-water-triggered profile dumping. |
| @roff_prof@Profile output is compatible with the included pprof Perl script, |
| @roff_prof@which originates from the |
| @roff_prof@.UR http://\:code.google.com/\:p/\:google-perftools/ |
| @roff_prof@google-perftools package |
| @roff_prof@.UE . |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof_prefix (const char *) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Filename prefix for profile dumps. |
| @roff_prof@If the prefix is set to the empty string, no automatic dumps will |
| @roff_prof@occur; this is primarily useful for disabling the automatic final |
| @roff_prof@heap dump (which also disables leak reporting, if enabled). |
| @roff_prof@The default prefix is |
| @roff_prof@.Pa jeprof . |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.lg_prof_bt_max (size_t) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Maximum backtrace depth (log base 2) when profiling memory |
| @roff_prof@allocation activity. |
| @roff_prof@The default is 128 (2^7). |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof_active (bool) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Profiling activated/deactivated. |
| @roff_prof@This is a secondary control mechanism that makes it possible to |
| @roff_prof@start the application with profiling enabled (see the |
| @roff_prof@.Dq opt.prof |
| @roff_prof@option) but inactive, then toggle profiling at any time during |
| @roff_prof@program execution with the |
| @roff_prof@.Dq prof.active |
| @roff_prof@mallctl. |
| @roff_prof@This option is enabled by default. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.lg_prof_sample (ssize_t) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Average interval (log base 2) between allocation samples, as |
| @roff_prof@measured in bytes of allocation activity. |
| @roff_prof@Increasing the sampling interval decreases profile fidelity, but |
| @roff_prof@also decreases the computational overhead. |
| @roff_prof@The default sample interval is 1 (2^0) (i.e. all allocations are |
| @roff_prof@sampled). |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof_accum (bool) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Reporting of cumulative object/byte counts in profile dumps |
| @roff_prof@enabled/disabled. |
| @roff_prof@If this option is enabled, every unique backtrace must be stored for |
| @roff_prof@the duration of execution. |
| @roff_prof@Depending on the application, this can impose a large memory |
| @roff_prof@overhead, and the cumulative counts are not always of interest. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.lg_prof_tcmax |
| @roff_prof@option for control of per thread backtrace caching, which has |
| @roff_prof@important interactions. |
| @roff_prof@This option is enabled by default. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.lg_prof_tcmax (ssize_t) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Maximum per thread backtrace cache (log base 2) used for heap |
| @roff_prof@profiling. |
| @roff_prof@A backtrace can only be discarded if the |
| @roff_prof@.Dq opt.prof_accum |
| @roff_prof@option is disabled, and no thread caches currently refer to the |
| @roff_prof@backtrace. |
| @roff_prof@Therefore, a backtrace cache limit should be imposed if the |
| @roff_prof@intention is to limit how much memory is used by backtraces. |
| @roff_prof@By default, no limit is imposed (encoded as -1). |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.lg_prof_interval (ssize_t) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Average interval (log base 2) between memory profile dumps, as |
| @roff_prof@measured in bytes of allocation activity. |
| @roff_prof@The actual interval between dumps may be sporadic because |
| @roff_prof@decentralized allocation counters are used to avoid synchronization |
| @roff_prof@bottlenecks. |
| @roff_prof@Profiles are dumped to files named according to the pattern |
| @roff_prof@.Pa <prefix>.<pid>.<seq>.i<iseq>.heap , |
| @roff_prof@where |
| @roff_prof@.Pa <prefix> |
| @roff_prof@is controlled by the |
| @roff_prof@.Dq opt.prof_prefix |
| @roff_prof@option. |
| @roff_prof@By default, interval-triggered profile dumping is disabled (encoded |
| @roff_prof@as -1). |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof_gdump (bool) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Trigger a memory profile dump every time the total virtual memory |
| @roff_prof@exceeds the previous maximum. |
| @roff_prof@Profiles are dumped to files named according to the pattern |
| @roff_prof@.Pa <prefix>.<pid>.<seq>.u<useq>.heap , |
| @roff_prof@where |
| @roff_prof@.Pa <prefix> |
| @roff_prof@is controlled by the |
| @roff_prof@.Dq opt.prof_prefix |
| @roff_prof@option. |
| @roff_prof@This option is disabled by default. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "opt.prof_leak (bool) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Leak reporting enabled/disabled. |
| @roff_prof@If enabled, use an |
| @roff_prof@.Xr atexit 3 |
| @roff_prof@function to report memory leaks detected by allocation sampling. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.lg_prof_bt_max |
| @roff_prof@option for backtrace depth control. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.prof |
| @roff_prof@option for information on analyzing heap profile output. |
| @roff_prof@This option is disabled by default. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "opt.overcommit (bool) r-" |
| .Bd -ragged -offset indent -compact |
| @roff_swap@Over-commit enabled/disabled. |
| @roff_swap@If enabled, over-commit memory as a side effect of using anonymous |
| @roff_swap@.Xr mmap 2 |
| @roff_swap@@roff_dss@ and |
| @roff_swap@@roff_dss@.Xr sbrk 2 |
| @roff_swap@for virtual memory allocation. |
| @roff_swap@In order for overcommit to be disabled, the |
| @roff_swap@.Dq swap.fds |
| @roff_swap@mallctl must have been successfully written to. |
| @roff_swap@This option is enabled by default. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_tcache@.It Sy "tcache.flush (void) --" |
| @roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_tcache@Flush calling thread's tcache. |
| @roff_tcache@This interface releases all cached objects and internal data |
| @roff_tcache@structures associated with the calling thread's thread-specific |
| @roff_tcache@cache. |
| @roff_tcache@Ordinarily, this interface need not be called, since automatic |
| @roff_tcache@periodic incremental garbage collection occurs, and the thread |
| @roff_tcache@cache is automatically discarded when a thread exits. |
| @roff_tcache@However, garbage collection is triggered by allocation activity, |
| @roff_tcache@so it is possible for a thread that stops allocating/deallocating |
| @roff_tcache@to retain its cache indefinitely, in which case the developer may |
| @roff_tcache@find manual flushing useful. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "thread.arena (unsigned) rw" |
| .Bd -ragged -offset indent -compact |
| Get or set the arena associated with the calling thread. |
| The arena index must be less than the maximum number of arenas (see the |
| .Dq arenas.narenas |
| mallctl). |
| If the specified arena was not initialized beforehand (see the |
| .Dq arenas.initialized |
| mallctl), it will be automatically initialized as a side effect of calling this |
| interface. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "thread.allocated (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Get the total number of bytes ever allocated by the calling thread. |
| @roff_stats@This counter has the potential to wrap around; it is up to the |
| @roff_stats@application to appropriately interpret the counter in such cases. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "thread.deallocated (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Get the total number of bytes ever deallocated by the calling |
| @roff_stats@thread. |
| @roff_stats@This counter has the potential to wrap around; it is up to the |
| @roff_stats@application to appropriately interpret the counter in such cases. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.narenas (unsigned) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum number of arenas. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.initialized (bool *) r-" |
| .Bd -ragged -offset indent -compact |
| An array of arenas.narenas booleans. |
| Each boolean indicates whether the corresponding arena is initialized. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.quantum (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Quantum size. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.cacheline (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Assumed cacheline size. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.subpage (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Subpage size class interval. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.pagesize (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Page size. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.chunksize (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Chunk size. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.tspace_min (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Minimum tiny size class. |
| Tiny size classes are powers of two. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.tspace_max (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum tiny size class. |
| Tiny size classes are powers of two. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.qspace_min (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Minimum quantum-spaced size class. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.qspace_max (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum quantum-spaced size class. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.cspace_min (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Minimum cacheline-spaced size class. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.cspace_max (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum cacheline-spaced size class. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.sspace_min (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Minimum subpage-spaced size class. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.sspace_max (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum subpage-spaced size class. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_tcache@.It Sy "arenas.tcache_max (size_t) r-" |
| @roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_tcache@Maximum thread-cached size class. |
| @roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.ntbins (unsigned) r-" |
| .Bd -ragged -offset indent -compact |
| Number of tiny bin size classes. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.nqbins (unsigned) r-" |
| .Bd -ragged -offset indent -compact |
| Number of quantum-spaced bin size classes. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.ncbins (unsigned) r-" |
| .Bd -ragged -offset indent -compact |
| Number of cacheline-spaced bin size classes. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.nsbins (unsigned) r-" |
| .Bd -ragged -offset indent -compact |
| Number of subpage-spaced bin size classes. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.nbins (unsigned) r-" |
| .Bd -ragged -offset indent -compact |
| Total number of bin size classes. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_tcache@.It Sy "arenas.nhbins (unsigned) r-" |
| @roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_tcache@Total number of thread cache bin size classes. |
| @roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.bin.<i>.size (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum size supported by size class. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.bin.<i>.nregs (uint32_t) r-" |
| .Bd -ragged -offset indent -compact |
| Number of regions per page run. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.bin.<i>.run_size (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Number of bytes per page run. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.nlruns (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Total number of large size classes. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.lrun.<i>.size (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Maximum size supported by this large size class. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "arenas.purge (unsigned) -w" |
| .Bd -ragged -offset indent -compact |
| Purge unused dirty pages for the specified arena, or for all arenas if none is |
| specified. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "prof.active (bool) rw" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Control whether sampling is currently active. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.prof_active |
| @roff_prof@option for additional information. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "prof.dump (const char *) -w" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Dump a memory profile to the specified file, or if NULL is specified, |
| @roff_prof@to a file according to the pattern |
| @roff_prof@.Pa <prefix>.<pid>.<seq>.m<mseq>.heap , |
| @roff_prof@where |
| @roff_prof@.Pa <prefix> |
| @roff_prof@is controlled by the |
| @roff_prof@.Dq opt.prof_prefix |
| @roff_prof@option. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_prof@.It Sy "prof.interval (uint64_t) r-" |
| @roff_prof@.Bd -ragged -offset indent -compact |
| @roff_prof@Average number of bytes allocated between inverval-based profile |
| @roff_prof@dumps. |
| @roff_prof@See the |
| @roff_prof@.Dq opt.lg_prof_interval |
| @roff_prof@option for additional information. |
| @roff_prof@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.allocated (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Total number of bytes allocated by the application. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.active (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Total number of bytes in active pages allocated by the application. |
| @roff_stats@This is a multiple of the page size, and greater than or equal to |
| @roff_stats@.Dq stats.allocated . |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.mapped (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Total number of bytes in chunks mapped on behalf of the application. |
| @roff_stats@This is a multiple of the chunk size, and is at least as large as |
| @roff_stats@.Dq stats.active . |
| @roff_stats@@roff_swap@This does not include inactive chunks backed by swap |
| @roff_stats@@roff_swap@files. |
| @roff_stats@@roff_dss@This does not include inactive chunks embedded in the DSS. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.chunks.current (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Total number of chunks actively mapped on behalf of the application. |
| @roff_stats@@roff_swap@This does not include inactive chunks backed by swap |
| @roff_stats@@roff_swap@files. |
| @roff_stats@@roff_dss@This does not include inactive chunks embedded in the DSS. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.chunks.total (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of chunks allocated. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.chunks.high (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Maximum number of active chunks at any time thus far. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.huge.allocated (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of bytes currently allocated by huge objects. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.huge.nmalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of huge allocation requests. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.huge.ndalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of huge deallocation requests. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "stats.arenas.<i>.pactive (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Number of pages in active runs. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| .It Sy "stats.arenas.<i>.pdirty (size_t) r-" |
| .Bd -ragged -offset indent -compact |
| Number of pages within unused runs that are potentially dirty, and for which |
| .Fn madvise "..." "MADV_DONTNEED" |
| has not been called. |
| .Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.mapped (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of mapped bytes. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.npurge (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of dirty page purge sweeps performed. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.nmadvise (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of |
| @roff_stats@.Fn madvise "..." "MADV_DONTNEED" |
| @roff_stats@calls made to purge dirty pages. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.npurged (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of pages purged. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.small.allocated (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of bytes currently allocated by small objects. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.small.nmalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of allocation requests served by small bins. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.small.ndalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of small objects returned to bins. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.small.nrequests (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of small allocation requests. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.large.allocated (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Number of bytes currently allocated by large objects. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.large.nmalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of large allocation requests served directly by |
| @roff_stats@the arena. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.large.ndalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of large deallocation requests served directly by |
| @roff_stats@the arena. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.large.nrequests (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of large allocation requests. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.allocated (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Current number of bytes allocated by bin. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.nmalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of allocations served by bin. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.ndalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of allocations returned to bin. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.nrequests (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of allocation requests. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@@roff_tcache@.It Sy "stats.arenas.<i>.bins.<j>.nfills (uint64_t) r-" |
| @roff_stats@@roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_stats@@roff_tcache@Cumulative number of tcache fills. |
| @roff_stats@@roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@@roff_tcache@.It Sy "stats.arenas.<i>.bins.<j>.nflushes (uint64_t) r-" |
| @roff_stats@@roff_tcache@.Bd -ragged -offset indent -compact |
| @roff_stats@@roff_tcache@Cumulative number of tcache flushes. |
| @roff_stats@@roff_tcache@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.nruns (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of runs created. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.nreruns (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of times the current run from which to allocate |
| @roff_stats@changed. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.highruns (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Maximum number of runs at any time thus far. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.bins.<j>.curruns (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Current number of runs. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.nmalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of allocation requests for this size class served |
| @roff_stats@directly by the arena. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.ndalloc (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of deallocation requests for this size class |
| @roff_stats@served directly by the arena. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.nrequests (uint64_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Cumulative number of allocation requests for this size class. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.highruns (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Maximum number of runs at any time thus far for this size class. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@.It Sy "stats.arenas.<i>.lruns.<j>.curruns (size_t) r-" |
| @roff_stats@.Bd -ragged -offset indent -compact |
| @roff_stats@Current number of runs for this size class. |
| @roff_stats@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_stats@@roff_swap@.It Sy "swap.avail (size_t) r-" |
| @roff_stats@@roff_swap@.Bd -ragged -offset indent -compact |
| @roff_stats@@roff_swap@Number of swap file bytes that are currently not |
| @roff_stats@@roff_swap@associated with any chunk (i.e. mapped, but otherwise |
| @roff_stats@@roff_swap@completely unmanaged). |
| @roff_stats@@roff_swap@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_swap@.It Sy "swap.prezeroed (bool) rw" |
| @roff_swap@.Bd -ragged -offset indent -compact |
| @roff_swap@If true, the allocator assumes that the swap file(s) contain nothing |
| @roff_swap@but nil bytes. |
| @roff_swap@If this assumption is violated, allocator behavior is undefined. |
| @roff_swap@This value becomes read-only after |
| @roff_swap@.Dq swap.fds |
| @roff_swap@is successfully written to. |
| @roff_swap@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_swap@.It Sy "swap.nfds (size_t) r-" |
| @roff_swap@.Bd -ragged -offset indent -compact |
| @roff_swap@Number of file descriptors in use for swap. |
| @roff_swap@.Ed |
| .\"----------------------------------------------------------------------------- |
| @roff_swap@.It Sy "swap.fds (int *) r-" |
| @roff_swap@.Bd -ragged -offset indent -compact |
| @roff_swap@When written to, the files associated with the specified file |
| @roff_swap@descriptors are contiguously mapped via |
| @roff_swap@.Xr mmap 2 . |
| @roff_swap@The resulting virtual memory region is preferred over anonymous |
| @roff_swap@.Xr mmap 2 |
| @roff_swap@@roff_dss@and |
| @roff_swap@@roff_dss@.Xr sbrk 2 |
| @roff_swap@memory. |
| @roff_swap@Note that if a file's size is not a multiple of the page size, it is |
| @roff_swap@automatically truncated to the nearest page size multiple. |
| @roff_swap@See the |
| @roff_swap@.Dq swap.prezeroed |
| @roff_swap@interface for specifying that the files are pre-zeroed. |
| @roff_swap@.Ed |
| .\"----------------------------------------------------------------------------- |
| .El |
| .Sh DEBUGGING MALLOC PROBLEMS |
| Start by setting the |
| .Dq opt.abort |
| option, which forces a coredump (if possible) at the first sign of trouble, |
| rather than the normal policy of trying to continue if at all possible. |
| .Pp |
| It is probably also a good idea to recompile the program with suitable |
| options and symbols for debugger support. |
| .Pp |
| @roff_fill@If the program starts to give unusual results, coredump or generally |
| @roff_fill@behave differently without emitting any of the messages mentioned in |
| @roff_fill@the next section, it is likely because the program depends on the |
| @roff_fill@storage being filled with zero bytes. |
| @roff_fill@Try running it with the |
| @roff_fill@.Dq opt.zero |
| @roff_fill@option set; |
| @roff_fill@if that improves the situation, this diagnosis has been confirmed. |
| @roff_fill@If the program still misbehaves, |
| @roff_fill@the likely problem is accessing memory outside the allocated area. |
| @roff_fill@.Pp |
| @roff_fill@Alternatively, if the symptoms are not easy to reproduce, setting the |
| @roff_fill@.Dq opt.junk |
| @roff_fill@option may help provoke the problem. |
| @roff_fill@.Pp |
| This implementation does not provide much detail about the problems it detects, |
| because the performance impact for storing such information would be |
| prohibitive. |
| There are a number of allocator implementations available on the Internet |
| which focus on detecting and pinpointing problems by trading performance for |
| extra sanity checks and detailed diagnostics. |
| .Sh DIAGNOSTIC MESSAGES |
| If any of the memory allocation/deallocation functions detect an error or |
| warning condition, a message will be printed to file descriptor |
| .Dv STDERR_FILENO . |
| Errors will result in the process dumping core. |
| If the |
| .Dq opt.abort |
| option is set, most warnings are treated as errors. |
| .Pp |
| The |
| .Va @jemalloc_prefix@malloc_message |
| variable allows the programmer to override the function which emits the text |
| strings forming the errors and warnings if for some reason the |
| .Dv STDERR_FILENO |
| file descriptor is not suitable for this. |
| .Va @jemalloc_prefix@malloc_message |
| takes the |
| .Fa cbopaque |
| pointer argument that is |
| .Dv NULL |
| unless overridden by the arguments in a call to |
| .Fn @jemalloc_prefix@malloc_stats_print , |
| followed by a string pointer. |
| Please note that doing anything which tries to allocate memory in this function |
| is likely to result in a crash or deadlock. |
| .Pp |
| All messages are prefixed by |
| .Dq <jemalloc>: . |
| .Sh RETURN VALUES |
| .Ss Standard API |
| The |
| .Fn @jemalloc_prefix@malloc |
| and |
| .Fn @jemalloc_prefix@calloc |
| functions return a pointer to the allocated memory if successful; otherwise |
| a |
| .Dv NULL |
| pointer is returned and |
| .Va errno |
| is set to |
| .Er ENOMEM . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@posix_memalign |
| function returns the value 0 if successful; otherwise it returns an error value. |
| The |
| .Fn @jemalloc_prefix@posix_memalign |
| function will fail if: |
| .Bl -tag -width Er |
| .It Bq Er EINVAL |
| The |
| .Fa alignment |
| parameter is not a power of 2 at least as large as |
| .Fn sizeof "void *" . |
| .It Bq Er ENOMEM |
| Memory allocation error. |
| .El |
| .Pp |
| The |
| .Fn @jemalloc_prefix@realloc |
| function returns a pointer, possibly identical to |
| .Fa ptr , |
| to the allocated memory |
| if successful; otherwise a |
| .Dv NULL |
| pointer is returned, and |
| .Va errno |
| is set to |
| .Er ENOMEM |
| if the error was the result of an allocation failure. |
| The |
| .Fn @jemalloc_prefix@realloc |
| function always leaves the original buffer intact |
| when an error occurs. |
| .Pp |
| The |
| .Fn @jemalloc_prefix@free |
| function returns no value. |
| .Ss Non-standard API |
| The |
| .Fn @jemalloc_prefix@malloc_usable_size |
| function returns the usable size of the allocation pointed to by |
| .Fa ptr . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@mallctl , |
| .Fn @jemalloc_prefix@mallctlnametomib , |
| and |
| .Fn @jemalloc_prefix@mallctlbymib |
| functions return 0 on success; otherwise they return an error value. |
| The functions will fail if: |
| .Bl -tag -width Er |
| .It Bq Er EINVAL |
| .Fa newp |
| is |
| .Dv non-NULL , |
| and |
| .Fa newlen |
| is too large or too small. |
| Alternatively, |
| .Fa *oldlenp |
| is too large or too small; in this case as much data as possible are read |
| despite the error. |
| .It Bq Er ENOMEM |
| .Fa *oldlenp |
| is too short to hold the requested value. |
| .It Bq Er ENOENT |
| .Fa name |
| or |
| .Fa mib |
| specifies an unknown/invalid value. |
| .It Bq Er EPERM |
| Attempt to read or write void value, or attempt to write read-only value. |
| .It Bq Er EAGAIN |
| A memory allocation failure occurred. |
| .It Bq Er EFAULT |
| An interface with side effects failed in some way not directly related to |
| .Fn @jemalloc_prefix@mallctl* |
| read/write processing. |
| .El |
| .Ss Experimental API |
| The |
| .Fn @jemalloc_prefix@allocm , |
| .Fn @jemalloc_prefix@rallocm , |
| .Fn @jemalloc_prefix@sallocm , |
| and |
| .Fn @jemalloc_prefix@dallocm |
| functions return |
| .Dv ALLOCM_SUCCESS |
| on success; otherwise they return an error value. |
| The |
| .Fn @jemalloc_prefix@allocm |
| and |
| .Fn @jemalloc_prefix@rallocm |
| functions will fail if: |
| .Bl -tag -width ".Bq Er ALLOCM_ERR_OOM" |
| .It Bq Er ALLOCM_ERR_OOM |
| Out of memory. |
| Insufficient contiguous memory was available to service the allocation request. |
| The |
| .Fn @jemalloc_prefix@allocm |
| function additionally sets |
| .Fa *ptr |
| to |
| .Dv NULL , |
| whereas the |
| .Fn @jemalloc_prefix@rallocm |
| function leaves |
| .Fa *ptr |
| unmodified. |
| .El |
| .Pp |
| The |
| .Fn @jemalloc_prefix@rallocm |
| function will also fail if: |
| .Bl -tag -width ".Bq Er ALLOCM_ERR_NOT_MOVED" |
| .It Bq Er ALLOCM_ERR_NOT_MOVED |
| .Dv ALLOCM_NO_MOVE |
| was specified, but the reallocation request could not be serviced without |
| moving the object. |
| .El |
| .Sh ENVIRONMENT |
| The following environment variable affects the execution of the allocation |
| functions: |
| .Bl -tag -width ".Ev @jemalloc_cprefix@MALLOC_CONF" |
| .It Ev @jemalloc_cprefix@MALLOC_CONF |
| If the environment variable |
| .Ev @jemalloc_cprefix@MALLOC_CONF |
| is set, the characters it contains will be interpreted as options. |
| .El |
| .Sh EXAMPLES |
| To dump core whenever a problem occurs: |
| .Pp |
| .Bd -literal -offset indent |
| ln -s 'abort:true' /etc/@jemalloc_prefix@malloc.conf |
| .Ed |
| .Pp |
| To specify in the source a chunk size that is 16 MiB: |
| .Bd -literal -offset indent |
| @jemalloc_prefix@malloc_conf = "lg_chunk:24"; |
| .Ed |
| .Sh SEE ALSO |
| .Xr madvise 2 , |
| .Xr mmap 2 , |
| @roff_dss@.Xr sbrk 2 , |
| .Xr alloca 3 , |
| .Xr atexit 3 , |
| .Xr getpagesize 3 |
| .Sh STANDARDS |
| The |
| .Fn @jemalloc_prefix@malloc , |
| .Fn @jemalloc_prefix@calloc , |
| .Fn @jemalloc_prefix@realloc |
| and |
| .Fn @jemalloc_prefix@free |
| functions conform to |
| .St -isoC . |
| .Pp |
| The |
| .Fn @jemalloc_prefix@posix_memalign |
| function conforms to |
| .St -p1003.1-2001 . |