Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
JEMALLOC(3)			  User Manual			   JEMALLOC(3)

NAME
       jemalloc	- general purpose memory allocation functions

LIBRARY
       This manual describes jemalloc
       3.4.0-0-g0ed518e5dab789ad2171bb38977a8927e2a26775. More information can
       be found	at the jemalloc	website[1].

       The following configuration options are enabled in libc's built-in
       jemalloc: --enable-dss, --enable-experimental, --enable-fill,
       --enable-lazy-lock, --enable-munmap, --enable-stats, --enable-tcache,
       --enable-tls, --enable-utrace, and --enable-xmalloc. Additionally,
       --enable-debug is enabled in development	versions of FreeBSD
       (controlled by the MALLOC_PRODUCTION make variable).

SYNOPSIS
       #include	<stdlib.h>
       #include	<malloc_np.h>

   Standard API
       void *malloc(size_t size);

       void *calloc(size_t number, size_t size);

       int posix_memalign(void **ptr, size_t alignment,	size_t size);

       void *aligned_alloc(size_t alignment, size_t size);

       void *realloc(void *ptr,	size_t size);

       void free(void *ptr);

   Non-standard	API
       size_t malloc_usable_size(const void *ptr);

       void malloc_stats_print(void (*write_cb)	(void *, const char *),
			       void *cbopaque, const char *opts);

       int mallctl(const char *name, void *oldp, size_t	*oldlenp, void *newp,
		   size_t newlen);

       int mallctlnametomib(const char *name, size_t *mibp, size_t *miblenp);

       int mallctlbymib(const size_t *mib, size_t miblen, void *oldp,
			size_t *oldlenp, void *newp, size_t newlen);

       void (*malloc_message)(void *cbopaque, const char *s);

       const char *malloc_conf;

   Experimental	API
       int allocm(void **ptr, size_t *rsize, size_t size, int flags);

       int rallocm(void	**ptr, size_t *rsize, size_t size, size_t extra,
		   int flags);

       int sallocm(const void *ptr, size_t *rsize, int flags);

       int dallocm(void	*ptr, int flags);

       int nallocm(size_t *rsize, size_t size, int flags);

DESCRIPTION
   Standard API
       The malloc function allocates size bytes	of uninitialized memory. The
       allocated space is suitably aligned (after possible pointer coercion)
       for storage of any type of object.

       The calloc function allocates space for number objects, each size bytes
       in length. The result is	identical to calling malloc with an argument
       of number * size, with the exception that the allocated memory is
       explicitly initialized to zero bytes.

       The posix_memalign function allocates size bytes	of memory such that
       the allocation's	base address is	an even	multiple of alignment, and
       returns the allocation in the value pointed to by ptr. The requested
       alignment must be a power of 2 at least as large	as sizeof(void *).

       The aligned_alloc function allocates size bytes of memory such that the
       allocation's base address is an even multiple of	alignment. The
       requested alignment must	be a power of 2. Behavior is undefined if size
       is not an integral multiple of alignment.

       The realloc function changes the	size of	the previously allocated
       memory referenced by ptr	to 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 ptr is	freed and a
       pointer to the newly allocated memory is	returned. Note that realloc
       may move	the memory allocation, resulting in a different	return value
       than ptr. If ptr	is NULL, the realloc function behaves identically to
       malloc for the specified	size.

       The free	function causes	the allocated memory referenced	by ptr to be
       made available for future allocations. If ptr is	NULL, no action
       occurs.

   Non-standard	API
       The malloc_usable_size function returns the usable size of the
       allocation pointed to by	ptr. The return	value may be larger than the
       size that was requested during allocation. The malloc_usable_size
       function	is not a mechanism for in-place	realloc; rather	it is provided
       solely as a tool	for introspection purposes. Any	discrepancy between
       the requested allocation	size and the size reported by
       malloc_usable_size should not be	depended on, since such	behavior is
       entirely	implementation-dependent.

       The malloc_stats_print function writes human-readable summary
       statistics via the write_cb callback function pointer and cbopaque data
       passed to write_cb, or malloc_message if	write_cb is NULL. This
       function	can be called repeatedly. General information that never
       changes during execution	can be omitted by specifying "g" as a
       character within	the opts string. Note that malloc_message uses the
       mallctl*	functions internally, so inconsistent statistics can be
       reported	if multiple threads use	these functions	simultaneously.	If
       --enable-stats is specified during configuration, "m" and "a" can be
       specified to omit merged	arena and per arena statistics,	respectively;
       "b" and "l" can be specified to omit per	size class statistics for bins
       and large objects, respectively.	Unrecognized characters	are silently
       ignored.	Note that thread caching may prevent some statistics from
       being completely	up to date, since extra	locking	would be required to
       merge counters that track thread	cache operations.

       The mallctl function provides a general interface for introspecting the
       memory allocator, as well as setting modifiable parameters and
       triggering actions. The period-separated	name argument specifies	a
       location	in a tree-structured namespace;	see the	MALLCTL	NAMESPACE
       section for documentation on the	tree contents. To read a value,	pass a
       pointer via oldp	to adequate space to contain the value,	and a pointer
       to its length via oldlenp; otherwise pass NULL and NULL.	Similarly, to
       write a value, pass a pointer to	the value via newp, and	its length via
       newlen; otherwise pass NULL and 0.

       The 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 "Management Information Base"
       (MIB) that can be passed	repeatedly to mallctlbymib. Upon successful
       return from mallctlnametomib, mibp contains an array of *miblenp
       integers, where *miblenp	is the lesser of the number of components in
       name and	the input value	of *miblenp. Thus it is	possible to pass a
       *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 "arenas.bin.2.size"), the corresponding MIB
       component will always be	that integer. Therefore, it is legitimate to
       construct code like the following:

	   unsigned nbins, i;

	   int mib[4];
	   size_t len, miblen;

	   len = sizeof(nbins);
	   mallctl("arenas.nbins", &nbins, &len, NULL, 0);

	   miblen = 4;
	   mallnametomib("arenas.bin.0.size", mib, &miblen);
	   for (i = 0; i < nbins; i++) {
		size_t bin_size;

		mib[2] = i;
		len = sizeof(bin_size);
		mallctlbymib(mib, miblen, &bin_size, &len, NULL, 0);
		/* Do something	with bin_size... */
	   }

   Experimental	API
       The experimental	API is subject to change or removal without regard for
       backward	compatibility. If --disable-experimental is specified during
       configuration, the experimental API is omitted.

       The allocm, rallocm, sallocm, dallocm, and nallocm functions all	have a
       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:

       ALLOCM_LG_ALIGN(la)
	   Align the memory allocation to start	at an address that is a
	   multiple of (1 << la). This macro does not validate that la is
	   within the valid range.

       ALLOCM_ALIGN(a)
	   Align the memory allocation to start	at an address that is a
	   multiple of a, where	a is a power of	two. This macro	does not
	   validate that a is a	power of 2.

       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.

       ALLOCM_NO_MOVE
	   For reallocation, fail rather than moving the object. This
	   constraint can apply	to both	growth and shrinkage.

       ALLOCM_ARENA(a)
	   Use the arena specified by the index	a. This	macro does not
	   validate that a specifies an	arena in the valid range.

       The allocm function allocates at	least size bytes of memory, sets *ptr
       to the base address of the allocation, and sets *rsize to the real size
       of the allocation if rsize is not NULL. Behavior	is undefined if	size
       is 0.

       The rallocm function resizes the	allocation at *ptr to be at least size
       bytes, sets *ptr	to the base address of the allocation if it moved, and
       sets *rsize to the real size of the allocation if rsize is not NULL. If
       extra is	non-zero, an attempt is	made to	resize the allocation to be at
       least size + extra) bytes, though inability to allocate the extra
       byte(s) will not	by itself result in failure. Behavior is undefined if
       size is 0, or if	(size +	extra >	SIZE_T_MAX).

       The sallocm function sets *rsize	to the real size of the	allocation.

       The dallocm function causes the memory referenced by ptr	to be made
       available for future allocations.

       The nallocm function allocates no memory, but it	performs the same size
       computation as the allocm function, and if rsize	is not NULL it sets
       *rsize to the real size of the allocation that would result from	the
       equivalent allocm function call.	Behavior is undefined if size is 0.

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.

       The string pointed to by	the global variable malloc_conf, the "name" of
       the file	referenced by the symbolic link	named /etc/malloc.conf,	and
       the value of the	environment variable MALLOC_CONF, will be interpreted,
       in that order, from left	to right as options. Note that malloc_conf may
       be read before main is entered, so the declaration of malloc_conf
       should specify an initializer that contains the final value to be read
       by jemalloc.  malloc_conf is a compile-time setting, whereas
       /etc/malloc.conf	and MALLOC_CONF	can be safely set any time prior to
       program invocation.

       An options string is a comma-separated list of option:value pairs.
       There is	one key	corresponding to each "opt.*"  mallctl (see the
       MALLCTL NAMESPACE section for options documentation). For example,
       abort:true,narenas:1 sets the "opt.abort" and "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.

IMPLEMENTATION NOTES
       Traditionally, allocators have used sbrk(2) to obtain memory, which is
       suboptimal for several reasons, including race conditions, increased
       fragmentation, and artificial limitations on maximum usable memory. If
       --enable-dss is specified during	configuration, this allocator uses
       both mmap(2) and	sbrk(2), in that order of preference; otherwise	only
       mmap(2) is used.

       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.

       In addition to multiple arenas, unless --disable-tcache is specified
       during configuration, this allocator supports thread-specific caching
       for small and large objects, in order to	make it	possible to completely
       avoid synchronization for most allocation requests. Such	caching	allows
       very fast allocation in the common case,	but it increases memory	usage
       and fragmentation, since	a bounded number of objects can	remain
       allocated in each thread	cache.

       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.

       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.

       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.

       Small objects are managed in groups by page runs. Each run maintains a
       frontier	and free list to track which regions are in use. Allocation
       requests	that are no more than half the quantum (8 or 16, depending on
       architecture) are rounded up to the nearest power of two	that is	at
       least sizeof(double). All other small object size classes are multiples
       of the quantum, spaced such that	internal fragmentation is limited to
       approximately 25% for all but the smallest size classes.	Allocation
       requests	that are larger	than the maximum small size class, but small
       enough to fit in	an arena-managed chunk (see the	"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.

       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.

       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	shown in Table 1.

       Table 1.	Size classes
       +---------+---------+---------------------+
       |Category | Spacing | Size		 |
       +---------+---------+---------------------+
       |	 |	lg | [8]		 |
       |	 +---------+---------------------+
       |	 |	16 | [16, 32, 48, ...,	 |
       |	 |	   | 128]		 |
       |	 +---------+---------------------+
       |	 |	32 | [160, 192,	224,	 |
       |	 |	   | 256]		 |
       |	 +---------+---------------------+
       |Small	 |	64 | [320, 384,	448,	 |
       |	 |	   | 512]		 |
       |	 +---------+---------------------+
       |	 |     128 | [640, 768,	896,	 |
       |	 |	   | 1024]		 |
       |	 +---------+---------------------+
       |	 |     256 | [1280, 1536, 1792,	 |
       |	 |	   | 2048]		 |
       |	 +---------+---------------------+
       |	 |     512 | [2560, 3072, 3584]	 |
       +---------+---------+---------------------+
       |Large	 |   4 KiB | [4	KiB, 8 KiB, 12	 |
       |	 |	   | KiB, ..., 4072 KiB] |
       +---------+---------+---------------------+
       |Huge	 |   4 MiB | [4	MiB, 8 MiB, 12	 |
       |	 |	   | MiB, ...]		 |
       +---------+---------+---------------------+

MALLCTL	NAMESPACE
       The following names are defined in the namespace	accessible via the
       mallctl*	functions. Value types are specified in	parentheses, their
       readable/writable statuses are encoded as rw, r-, -w, or	--, and
       required	build configuration flags follow, if any. 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. In the case of "stats.arenas.<i>.*", <i> equal to
       "arenas.narenas"	can be used to access the summation of statistics from
       all arenas. Take	special	note of	the "epoch" mallctl, which controls
       refreshing of cached dynamic statistics.

       "version" (const	char *)	r-
	   Return the jemalloc version string.

       "epoch" (uint64_t) rw
	   If a	value is passed	in, refresh the	data from which	the mallctl*
	   functions report values, and	increment the epoch. Return the
	   current epoch. This is useful for detecting whether another thread
	   caused a refresh.

       "config.debug" (bool) r-
	   --enable-debug was specified	during build configuration.

       "config.dss" (bool) r-
	   --enable-dss	was specified during build configuration.

       "config.fill" (bool) r-
	   --enable-fill was specified during build configuration.

       "config.lazy_lock" (bool) r-
	   --enable-lazy-lock was specified during build configuration.

       "config.mremap" (bool) r-
	   --enable-mremap was specified during	build configuration.

       "config.munmap" (bool) r-
	   --enable-munmap was specified during	build configuration.

       "config.prof" (bool) r-
	   --enable-prof was specified during build configuration.

       "config.prof_libgcc" (bool) r-
	   --disable-prof-libgcc was not specified during build	configuration.

       "config.prof_libunwind" (bool) r-
	   --enable-prof-libunwind was specified during	build configuration.

       "config.stats" (bool) r-
	   --enable-stats was specified	during build configuration.

       "config.tcache" (bool) r-
	   --disable-tcache was	not specified during build configuration.

       "config.tls" (bool) r-
	   --disable-tls was not specified during build	configuration.

       "config.utrace" (bool) r-
	   --enable-utrace was specified during	build configuration.

       "config.valgrind" (bool)	r-
	   --enable-valgrind was specified during build	configuration.

       "config.xmalloc"	(bool) r-
	   --enable-xmalloc was	specified during build configuration.

       "opt.abort" (bool) r-
	   Abort-on-warning enabled/disabled. If true, most warnings are
	   fatal. The process will call	abort(3) in these cases. This option
	   is disabled by default unless --enable-debug	is specified during
	   configuration, in which case	it is enabled by default.

       "opt.lg_chunk" (size_t) r-
	   Virtual memory chunk	size (log base 2). If a	chunk size outside the
	   supported size range	is specified, the size is silently clipped to
	   the minimum/maximum supported size. The default chunk size is 4 MiB
	   (2^22).

       "opt.dss" (const	char *)	r-
	   dss (sbrk(2)) allocation precedence as related to mmap(2)
	   allocation. The following settings are supported: "disabled",
	   "primary", and "secondary" (default).

       "opt.narenas" (size_t) r-
	   Maximum number of arenas to use for automatic multiplexing of
	   threads and arenas. The default is four times the number of CPUs,
	   or one if there is a	single CPU.

       "opt.lg_dirty_mult" (ssize_t) r-
	   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
	   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 8:1	(2^3:1); an option value of -1 will disable dirty page
	   purging.

       "opt.stats_print" (bool)	r-
	   Enable/disable statistics printing at exit. If enabled, the
	   malloc_stats_print function is called at program exit via an
	   atexit(3) function. If --enable-stats is specified during
	   configuration, this has the potential to cause deadlock for a
	   multi-threaded process that exits while one or more threads are
	   executing in	the memory allocation functions. Therefore, this
	   option should only be used with care; it is primarily intended as a
	   performance tuning aid during application development. This option
	   is disabled by default.

       "opt.junk" (bool) r- [--enable-fill]
	   Junk	filling	enabled/disabled. If enabled, each byte	of
	   uninitialized allocated memory will be initialized to 0xa5. All
	   deallocated memory will be initialized to 0x5a. This	is intended
	   for debugging and will impact performance negatively. This option
	   is disabled by default unless --enable-debug	is specified during
	   configuration, in which case	it is enabled by default unless
	   running inside Valgrind[2].

       "opt.quarantine"	(size_t) r- [--enable-fill]
	   Per thread quarantine size in bytes.	If non-zero, each thread
	   maintains a FIFO object quarantine that stores up to	the specified
	   number of bytes of memory. The quarantined memory is	not freed
	   until it is released	from quarantine, though	it is immediately
	   junk-filled if the "opt.junk" option	is enabled. This feature is of
	   particular use in combination with Valgrind[2], which can detect
	   attempts to access quarantined objects. This	is intended for
	   debugging and will impact performance negatively. The default
	   quarantine size is 0	unless running inside Valgrind,	in which case
	   the default is 16 MiB.

       "opt.redzone" (bool) r- [--enable-fill]
	   Redzones enabled/disabled. If enabled, small	allocations have
	   redzones before and after them. Furthermore,	if the "opt.junk"
	   option is enabled, the redzones are checked for corruption during
	   deallocation. However, the primary intended purpose of this feature
	   is to be used in combination	with Valgrind[2], which	needs redzones
	   in order to do effective buffer overflow/underflow detection. This
	   option is intended for debugging and	will impact performance
	   negatively. This option is disabled by default unless running
	   inside Valgrind.

       "opt.zero" (bool) r- [--enable-fill]
	   Zero	filling	enabled/disabled. If enabled, each byte	of
	   uninitialized allocated memory will be initialized to 0. Note that
	   this	initialization only happens once for each byte,	so realloc and
	   rallocm calls do not	zero memory that was previously	allocated.
	   This	is intended for	debugging and will impact performance
	   negatively. This option is disabled by default.

       "opt.utrace" (bool) r- [--enable-utrace]
	   Allocation tracing based on utrace(2) enabled/disabled. This	option
	   is disabled by default.

       "opt.valgrind" (bool) r-	[--enable-valgrind]
	   Valgrind[2] support enabled/disabled. This option is	vestigal
	   because jemalloc auto-detects whether it is running inside
	   Valgrind. This option is disabled by	default, unless	running	inside
	   Valgrind.

       "opt.xmalloc" (bool) r- [--enable-xmalloc]
	   Abort-on-out-of-memory enabled/disabled. If enabled,	rather than
	   returning failure for any allocation	function, display a diagnostic
	   message on STDERR_FILENO and	cause the program to drop core (using
	   abort(3)). If an application	is designed to depend on this
	   behavior, set the option at compile time by including the following
	   in the source code:

	       malloc_conf = "xmalloc:true";

	   This	option is disabled by default.

       "opt.tcache" (bool) r- [--enable-tcache]
	   Thread-specific caching enabled/disabled. When there	are multiple
	   threads, each thread	uses a thread-specific cache for objects up to
	   a certain size. Thread-specific caching allows many allocations to
	   be satisfied	without	performing any thread synchronization, at the
	   cost	of increased memory use. See the "opt.lg_tcache_max" option
	   for related tuning information. This	option is enabled by default
	   unless running inside Valgrind[2].

       "opt.lg_tcache_max" (size_t) r- [--enable-tcache]
	   Maximum size	class (log base	2) to cache in the thread-specific
	   cache. At a minimum,	all small size classes are cached, and at a
	   maximum all large size classes are cached. The default maximum is
	   32 KiB (2^15).

       "opt.prof" (bool) r- [--enable-prof]
	   Memory profiling enabled/disabled. If enabled, profile memory
	   allocation activity.	See the	"opt.prof_active" option for
	   on-the-fly activation/deactivation. See the "opt.lg_prof_sample"
	   option for probabilistic sampling control. See the "opt.prof_accum"
	   option for control of cumulative sample reporting. See the
	   "opt.lg_prof_interval" option for information on interval-triggered
	   profile dumping, the	"opt.prof_gdump" option	for information	on
	   high-water-triggered	profile	dumping, and the "opt.prof_final"
	   option for final profile dumping. Profile output is compatible with
	   the included	pprof Perl script, which originates from the
	   gperftools package[3].

       "opt.prof_prefix" (const	char *)	r- [--enable-prof]
	   Filename prefix for profile dumps. If the prefix is set to the
	   empty string, no automatic dumps will occur;	this is	primarily
	   useful for disabling	the automatic final heap dump (which also
	   disables leak reporting, if enabled). The default prefix is jeprof.

       "opt.prof_active" (bool)	r- [--enable-prof]
	   Profiling activated/deactivated. This is a secondary	control
	   mechanism that makes	it possible to start the application with
	   profiling enabled (see the "opt.prof" option) but inactive, then
	   toggle profiling at any time	during program execution with the
	   "prof.active" mallctl. This option is enabled by default.

       "opt.lg_prof_sample" (ssize_t) r- [--enable-prof]
	   Average interval (log base 2) between allocation samples, as
	   measured in bytes of	allocation activity. Increasing	the sampling
	   interval decreases profile fidelity,	but also decreases the
	   computational overhead. The default sample interval is 512 KiB
	   (2^19 B).

       "opt.prof_accum"	(bool) r- [--enable-prof]
	   Reporting of	cumulative object/byte counts in profile dumps
	   enabled/disabled. If	this option is enabled,	every unique backtrace
	   must	be stored for the duration of execution. Depending on the
	   application,	this can impose	a large	memory overhead, and the
	   cumulative counts are not always of interest. This option is
	   disabled by default.

       "opt.lg_prof_interval" (ssize_t)	r- [--enable-prof]
	   Average interval (log base 2) between memory	profile	dumps, as
	   measured in bytes of	allocation activity. The actual	interval
	   between dumps may be	sporadic because decentralized allocation
	   counters are	used to	avoid synchronization bottlenecks. Profiles
	   are dumped to files named according to the pattern
	   <prefix>.<pid>.<seq>.i<iseq>.heap, where <prefix> is	controlled by
	   the "opt.prof_prefix" option. By default, interval-triggered
	   profile dumping is disabled (encoded	as -1).

       "opt.prof_gdump"	(bool) r- [--enable-prof]
	   Trigger a memory profile dump every time the	total virtual memory
	   exceeds the previous	maximum. Profiles are dumped to	files named
	   according to	the pattern <prefix>.<pid>.<seq>.u<useq>.heap, where
	   <prefix> is controlled by the "opt.prof_prefix" option. This	option
	   is disabled by default.

       "opt.prof_final"	(bool) r- [--enable-prof]
	   Use an atexit(3) function to	dump final memory usage	to a file
	   named according to the pattern <prefix>.<pid>.<seq>.f.heap, where
	   <prefix> is controlled by the "opt.prof_prefix" option. This	option
	   is enabled by default.

       "opt.prof_leak" (bool) r- [--enable-prof]
	   Leak	reporting enabled/disabled. If enabled,	use an atexit(3)
	   function to report memory leaks detected by allocation sampling.
	   See the "opt.prof" option for information on	analyzing heap profile
	   output. This	option is disabled by default.

       "thread.arena" (unsigned) rw
	   Get or set the arena	associated with	the calling thread. If the
	   specified arena was not initialized beforehand (see the
	   "arenas.initialized"	mallctl), it will be automatically initialized
	   as a	side effect of calling this interface.

       "thread.allocated" (uint64_t) r-	[--enable-stats]
	   Get the total number	of bytes ever allocated	by the calling thread.
	   This	counter	has the	potential to wrap around; it is	up to the
	   application to appropriately	interpret the counter in such cases.

       "thread.allocatedp" (uint64_t *)	r- [--enable-stats]
	   Get a pointer to the	the value that is returned by the
	   "thread.allocated" mallctl. This is useful for avoiding the
	   overhead of repeated	mallctl* calls.

       "thread.deallocated" (uint64_t) r- [--enable-stats]
	   Get the total number	of bytes ever deallocated by the calling
	   thread. This	counter	has the	potential to wrap around; it is	up to
	   the application to appropriately interpret the counter in such
	   cases.

       "thread.deallocatedp" (uint64_t *) r- [--enable-stats]
	   Get a pointer to the	the value that is returned by the
	   "thread.deallocated"	mallctl. This is useful	for avoiding the
	   overhead of repeated	mallctl* calls.

       "thread.tcache.enabled" (bool) rw [--enable-tcache]
	   Enable/disable calling thread's tcache. The tcache is implicitly
	   flushed as a	side effect of becoming	disabled (see
	   "thread.tcache.flush").

       "thread.tcache.flush" (void) -- [--enable-tcache]
	   Flush calling thread's tcache. This interface releases all cached
	   objects and internal	data structures	associated with	the calling
	   thread's thread-specific cache. Ordinarily, this interface need not
	   be called, since automatic periodic incremental garbage collection
	   occurs, and the thread cache	is automatically discarded when	a
	   thread exits. However, garbage collection is	triggered by
	   allocation activity,	so it is possible for a	thread that stops
	   allocating/deallocating to retain its cache indefinitely, in	which
	   case	the developer may find manual flushing useful.

       "arena.<i>.purge" (unsigned) --
	   Purge unused	dirty pages for	arena <i>, or for all arenas if	<i>
	   equals "arenas.narenas".

       "arena.<i>.dss" (const char *) rw
	   Set the precedence of dss allocation	as related to mmap allocation
	   for arena <i>, or for all arenas if <i> equals "arenas.narenas".
	   See "opt.dss" for supported settings.

       "arenas.narenas"	(unsigned) r-
	   Current limit on number of arenas.

       "arenas.initialized" (bool *) r-
	   An array of "arenas.narenas"	booleans. Each boolean indicates
	   whether the corresponding arena is initialized.

       "arenas.quantum"	(size_t) r-
	   Quantum size.

       "arenas.page" (size_t) r-
	   Page	size.

       "arenas.tcache_max" (size_t) r- [--enable-tcache]
	   Maximum thread-cached size class.

       "arenas.nbins" (unsigned) r-
	   Number of bin size classes.

       "arenas.nhbins" (unsigned) r- [--enable-tcache]
	   Total number	of thread cache	bin size classes.

       "arenas.bin.<i>.size" (size_t) r-
	   Maximum size	supported by size class.

       "arenas.bin.<i>.nregs" (uint32_t) r-
	   Number of regions per page run.

       "arenas.bin.<i>.run_size" (size_t) r-
	   Number of bytes per page run.

       "arenas.nlruns" (size_t)	r-
	   Total number	of large size classes.

       "arenas.lrun.<i>.size" (size_t) r-
	   Maximum size	supported by this large	size class.

       "arenas.purge" (unsigned) -w
	   Purge unused	dirty pages for	the specified arena, or	for all	arenas
	   if none is specified.

       "arenas.extend" (unsigned) r-
	   Extend the array of arenas by appending a new arena,	and returning
	   the new arena index.

       "prof.active" (bool) rw [--enable-prof]
	   Control whether sampling is currently active. See the
	   "opt.prof_active" option for	additional information.

       "prof.dump" (const char *) -w [--enable-prof]
	   Dump	a memory profile to the	specified file,	or if NULL is
	   specified, to a file	according to the pattern
	   <prefix>.<pid>.<seq>.m<mseq>.heap, where <prefix> is	controlled by
	   the "opt.prof_prefix" option.

       "prof.interval" (uint64_t) r- [--enable-prof]
	   Average number of bytes allocated between inverval-based profile
	   dumps. See the "opt.lg_prof_interval" option	for additional
	   information.

       "stats.cactive" (size_t *) r- [--enable-stats]
	   Pointer to a	counter	that contains an approximate count of the
	   current number of bytes in active pages. The	estimate may be	high,
	   but never low, because each arena rounds up to the nearest multiple
	   of the chunk	size when computing its	contribution to	the counter.
	   Note	that the "epoch" mallctl has no	bearing	on this	counter.
	   Furthermore,	counter	consistency is maintained via atomic
	   operations, so it is	necessary to use an atomic operation in	order
	   to guarantee	a consistent read when dereferencing the pointer.

       "stats.allocated" (size_t) r- [--enable-stats]
	   Total number	of bytes allocated by the application.

       "stats.active" (size_t) r- [--enable-stats]
	   Total number	of bytes in active pages allocated by the application.
	   This	is a multiple of the page size,	and greater than or equal to
	   "stats.allocated". This does	not include "stats.arenas.<i>.pdirty"
	   and pages entirely devoted to allocator metadata.

       "stats.mapped" (size_t) r- [--enable-stats]
	   Total number	of bytes in chunks mapped on behalf of the
	   application.	This is	a multiple of the chunk	size, and is at	least
	   as large as "stats.active". This does not include inactive chunks.

       "stats.chunks.current" (size_t) r- [--enable-stats]
	   Total number	of chunks actively mapped on behalf of the
	   application.	This does not include inactive chunks.

       "stats.chunks.total" (uint64_t) r- [--enable-stats]
	   Cumulative number of	chunks allocated.

       "stats.chunks.high" (size_t) r- [--enable-stats]
	   Maximum number of active chunks at any time thus far.

       "stats.huge.allocated" (size_t) r- [--enable-stats]
	   Number of bytes currently allocated by huge objects.

       "stats.huge.nmalloc" (uint64_t) r- [--enable-stats]
	   Cumulative number of	huge allocation	requests.

       "stats.huge.ndalloc" (uint64_t) r- [--enable-stats]
	   Cumulative number of	huge deallocation requests.

       "stats.arenas.<i>.dss" (const char *) r-
	   dss (sbrk(2)) allocation precedence as related to mmap(2)
	   allocation. See "opt.dss" for details.

       "stats.arenas.<i>.nthreads" (unsigned) r-
	   Number of threads currently assigned	to arena.

       "stats.arenas.<i>.pactive" (size_t) r-
	   Number of pages in active runs.

       "stats.arenas.<i>.pdirty" (size_t) r-
	   Number of pages within unused runs that are potentially dirty, and
	   for which madvise...	MADV_DONTNEED or similar has not been called.

       "stats.arenas.<i>.mapped" (size_t) r- [--enable-stats]
	   Number of mapped bytes.

       "stats.arenas.<i>.npurge" (uint64_t) r- [--enable-stats]
	   Number of dirty page	purge sweeps performed.

       "stats.arenas.<i>.nmadvise" (uint64_t) r- [--enable-stats]
	   Number of madvise...	MADV_DONTNEED or similar calls made to purge
	   dirty pages.

       "stats.arenas.<i>.npurged" (uint64_t) r-	[--enable-stats]
	   Number of pages purged.

       "stats.arenas.<i>.small.allocated" (size_t) r- [--enable-stats]
	   Number of bytes currently allocated by small	objects.

       "stats.arenas.<i>.small.nmalloc"	(uint64_t) r- [--enable-stats]
	   Cumulative number of	allocation requests served by small bins.

       "stats.arenas.<i>.small.ndalloc"	(uint64_t) r- [--enable-stats]
	   Cumulative number of	small objects returned to bins.

       "stats.arenas.<i>.small.nrequests" (uint64_t) r-	[--enable-stats]
	   Cumulative number of	small allocation requests.

       "stats.arenas.<i>.large.allocated" (size_t) r- [--enable-stats]
	   Number of bytes currently allocated by large	objects.

       "stats.arenas.<i>.large.nmalloc"	(uint64_t) r- [--enable-stats]
	   Cumulative number of	large allocation requests served directly by
	   the arena.

       "stats.arenas.<i>.large.ndalloc"	(uint64_t) r- [--enable-stats]
	   Cumulative number of	large deallocation requests served directly by
	   the arena.

       "stats.arenas.<i>.large.nrequests" (uint64_t) r-	[--enable-stats]
	   Cumulative number of	large allocation requests.

       "stats.arenas.<i>.bins.<j>.allocated" (size_t) r- [--enable-stats]
	   Current number of bytes allocated by	bin.

       "stats.arenas.<i>.bins.<j>.nmalloc" (uint64_t) r- [--enable-stats]
	   Cumulative number of	allocations served by bin.

       "stats.arenas.<i>.bins.<j>.ndalloc" (uint64_t) r- [--enable-stats]
	   Cumulative number of	allocations returned to	bin.

       "stats.arenas.<i>.bins.<j>.nrequests" (uint64_t)	r- [--enable-stats]
	   Cumulative number of	allocation requests.

       "stats.arenas.<i>.bins.<j>.nfills" (uint64_t) r-	[--enable-stats
       --enable-tcache]
	   Cumulative number of	tcache fills.

       "stats.arenas.<i>.bins.<j>.nflushes" (uint64_t) r- [--enable-stats
       --enable-tcache]
	   Cumulative number of	tcache flushes.

       "stats.arenas.<i>.bins.<j>.nruns" (uint64_t) r- [--enable-stats]
	   Cumulative number of	runs created.

       "stats.arenas.<i>.bins.<j>.nreruns" (uint64_t) r- [--enable-stats]
	   Cumulative number of	times the current run from which to allocate
	   changed.

       "stats.arenas.<i>.bins.<j>.curruns" (size_t) r- [--enable-stats]
	   Current number of runs.

       "stats.arenas.<i>.lruns.<j>.nmalloc" (uint64_t) r- [--enable-stats]
	   Cumulative number of	allocation requests for	this size class	served
	   directly by the arena.

       "stats.arenas.<i>.lruns.<j>.ndalloc" (uint64_t) r- [--enable-stats]
	   Cumulative number of	deallocation requests for this size class
	   served directly by the arena.

       "stats.arenas.<i>.lruns.<j>.nrequests" (uint64_t) r- [--enable-stats]
	   Cumulative number of	allocation requests for	this size class.

       "stats.arenas.<i>.lruns.<j>.curruns" (size_t) r-	[--enable-stats]
	   Current number of runs for this size	class.

DEBUGGING MALLOC PROBLEMS
       When debugging, it is a good idea to configure/build jemalloc with the
       --enable-debug and --enable-fill	options, and recompile the program
       with suitable options and symbols for debugger support. When so
       configured, jemalloc incorporates a wide	variety	of run-time assertions
       that catch application errors such as double-free, write-after-free,
       etc.

       Programs	often accidentally depend on "uninitialized" memory actually
       being filled with zero bytes. Junk filling (see the "opt.junk" option)
       tends to	expose such bugs in the	form of	obviously incorrect results
       and/or coredumps. Conversely, zero filling (see the "opt.zero" option)
       eliminates the symptoms of such bugs. Between these two options,	it is
       usually possible	to quickly detect, diagnose, and eliminate such	bugs.

       This implementation does	not provide much detail	about the problems it
       detects,	because	the performance	impact for storing such	information
       would be	prohibitive. However, jemalloc does integrate with the most
       excellent Valgrind[2] tool if the --enable-valgrind configuration
       option is enabled.

DIAGNOSTIC MESSAGES
       If any of the memory allocation/deallocation functions detect an	error
       or warning condition, a message will be printed to file descriptor
       STDERR_FILENO. Errors will result in the	process	dumping	core. If the
       "opt.abort" option is set, most warnings	are treated as errors.

       The 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 STDERR_FILENO file descriptor is not suitable
       for this.  malloc_message takes the cbopaque pointer argument that is
       NULL unless overridden by the arguments in a call to
       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.

       All messages are	prefixed by "<jemalloc>:".

RETURN VALUES
   Standard API
       The malloc and calloc functions return a	pointer	to the allocated
       memory if successful; otherwise a NULL pointer is returned and errno is
       set to ENOMEM.

       The posix_memalign function returns the value 0 if successful;
       otherwise it returns an error value. The	posix_memalign function	will
       fail if:

       EINVAL
	   The alignment parameter is not a power of 2 at least	as large as
	   sizeof(void *).

       ENOMEM
	   Memory allocation error.

       The aligned_alloc function returns a pointer to the allocated memory if
       successful; otherwise a NULL pointer is returned	and errno is set. The
       aligned_alloc function will fail	if:

       EINVAL
	   The alignment parameter is not a power of 2.

       ENOMEM
	   Memory allocation error.

       The realloc function returns a pointer, possibly	identical to ptr, to
       the allocated memory if successful; otherwise a NULL pointer is
       returned, and errno is set to ENOMEM if the error was the result	of an
       allocation failure. The realloc function	always leaves the original
       buffer intact when an error occurs.

       The free	function returns no value.

   Non-standard	API
       The malloc_usable_size function returns the usable size of the
       allocation pointed to by	ptr.

       The mallctl, mallctlnametomib, and mallctlbymib functions return	0 on
       success;	otherwise they return an error value. The functions will fail
       if:

       EINVAL
	   newp	is not NULL, and newlen	is too large or	too small.
	   Alternatively, *oldlenp is too large	or too small; in this case as
	   much	data as	possible are read despite the error.

       ENOMEM
	   *oldlenp is too short to hold the requested value.

       ENOENT
	   name	or mib specifies an unknown/invalid value.

       EPERM
	   Attempt to read or write void value,	or attempt to write read-only
	   value.

       EAGAIN
	   A memory allocation failure occurred.

       EFAULT
	   An interface	with side effects failed in some way not directly
	   related to mallctl* read/write processing.

   Experimental	API
       The allocm, rallocm, sallocm, dallocm, and nallocm functions return
       ALLOCM_SUCCESS on success; otherwise they return	an error value.	The
       allocm, rallocm,	and nallocm functions will fail	if:

       ALLOCM_ERR_OOM
	   Out of memory. Insufficient contiguous memory was available to
	   service the allocation request. The allocm function additionally
	   sets	*ptr to	NULL, whereas the rallocm function leaves *ptr
	   unmodified.
       The rallocm function will also fail if:

       ALLOCM_ERR_NOT_MOVED
	   ALLOCM_NO_MOVE was specified, but the reallocation request could
	   not be serviced without moving the object.

ENVIRONMENT
       The following environment variable affects the execution	of the
       allocation functions:

       MALLOC_CONF
	   If the environment variable MALLOC_CONF is set, the characters it
	   contains will be interpreted	as options.

EXAMPLES
       To dump core whenever a problem occurs:

	   ln -s 'abort:true' /etc/malloc.conf

       To specify in the source	a chunk	size that is 16	MiB:

	   malloc_conf = "lg_chunk:24";

SEE ALSO
       madvise(2), mmap(2), sbrk(2), utrace(2),	alloca(3), atexit(3),
       getpagesize(3)

STANDARDS
       The malloc, calloc, realloc, and	free functions conform to ISO/IEC
       9899:1990 ("ISO C90").

       The posix_memalign function conforms to IEEE Std	1003.1-2001
       ("POSIX.1").

HISTORY
       The malloc_usable_size and posix_memalign functions first appeared in
       FreeBSD 7.0.

       The aligned_alloc, malloc_stats_print, mallctl*,	and *allocm functions
       first appeared in FreeBSD 10.0.

AUTHOR
       Jason Evans

NOTES
	1. jemalloc website
	   http://www.canonware.com/jemalloc/

	2. Valgrind
	   http://valgrind.org/

	3. gperftools package
	   http://code.google.com/p/gperftools/

jemalloc 3.4.0-0-g0ed518e5dab7	  06/02/2013			   JEMALLOC(3)

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | TUNING | IMPLEMENTATION NOTES | MALLCTL NAMESPACE | DEBUGGING MALLOC PROBLEMS | DIAGNOSTIC MESSAGES | RETURN VALUES | ENVIRONMENT | EXAMPLES | SEE ALSO | STANDARDS | HISTORY | AUTHOR | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=free&sektion=3&manpath=FreeBSD+10.0-RELEASE>

home | help