1 .\" Copyright (c) 1980, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" the American National Standards Committee X3, on Information
6 .\" Processing Systems.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)malloc.3 8.1 (Berkeley) 6/4/93
39 .Nm malloc , calloc , realloc , free , reallocf , malloc_usable_size
40 .Nd general purpose memory allocation functions
46 .Fn malloc "size_t size"
48 .Fn calloc "size_t number" "size_t size"
50 .Fn realloc "void *ptr" "size_t size"
52 .Fn reallocf "void *ptr" "size_t size"
58 .Fn \*(lp*_malloc_message\*(rp "const char *p1" "const char *p2" "const char *p3" "const char *p4"
61 .Fn malloc_usable_size "const void *ptr"
67 bytes of uninitialized memory.
68 The allocated space is suitably aligned (after possible pointer coercion)
69 for storage of any type of object.
73 function allocates space for
79 The result is identical to calling
83 with the exception that the allocated memory is explicitly initialized
88 function changes the size of the previously allocated memory referenced by
93 The contents of the memory are unchanged up to the lesser of the new and
95 If the new size is larger,
96 the contents of the newly allocated portion of the memory are undefined.
97 Upon success, the memory referenced by
99 is freed and a pointer to the newly allocated memory is returned.
104 may move the memory allocation, resulting in a different return value than
112 function behaves identically to
114 for the specified size.
118 function is identical to the
120 function, except that it
121 will free the passed pointer when the requested memory cannot be allocated.
124 specific API designed to ease the problems with traditional coding styles
127 causing memory leaks in libraries.
131 function causes the allocated memory referenced by
133 to be made available for future allocations.
141 .Fn malloc_usable_size
142 function returns the usable size of the allocation pointed to by
144 The return value may be larger than the size that was requested during
147 .Fn malloc_usable_size
148 function is not a mechanism for in-place
150 rather it is provided solely as a tool for introspection purposes.
151 Any discrepancy between the requested allocation size and the size reported by
152 .Fn malloc_usable_size
153 should not be depended on, since such behavior is entirely
154 implementation-dependent.
156 Once, when the first call is made to one of these memory allocation
157 routines, various flags will be set or reset, which affects the
158 workings of this allocator implementation.
162 of the file referenced by the symbolic link named
163 .Pa /etc/malloc.conf ,
164 the value of the environment variable
166 and the string pointed to by the global variable
168 will be interpreted, in that order, from left to right as flags.
170 Each flag is a single letter, optionally prefixed by a non-negative base 10
171 integer repetition count.
176 Some flags control parameter magnitudes, where uppercase increases the
177 magnitude, and lowercase decreases the magnitude.
178 Other flags control boolean parameters, where uppercase indicates that a
179 behavior is set, or on, and lowercase means that a behavior is not set, or off.
180 .Bl -tag -width indent
182 All warnings (except for the warning about unknown
183 flags being set) become fatal.
184 The process will call
188 Double/halve the size of the maximum size class that is a multiple of the
190 Above this size, subpage spacing (256 bytes) is used for size classes.
191 The default value is 512 bytes.
195 to acquire memory in the data storage segment (DSS).
196 This option is enabled by default.
199 option for related information and interactions.
201 Double/halve the size of the maximum medium size class.
202 The valid range is from one page to one half chunk.
203 The default value is 32 KiB.
205 Halve/double the per-arena minimum ratio of active to dirty pages.
206 Some dirty unused pages may be allowed to accumulate, within the limit set by
207 the ratio, before informing the kernel about at least half of those pages via
209 This provides the kernel with sufficient information to recycle dirty pages if
210 physical memory becomes scarce and the pages remain unused.
211 The default minimum ratio is 32:1;
212 .Ev MALLOC_OPTIONS=6F
213 will disable dirty page purging.
215 Double/halve the approximate interval (counted in terms of
216 thread-specific cache allocation/deallocation events) between full
217 thread-specific cache garbage collection sweeps.
218 Garbage collection is actually performed incrementally, one size
219 class at a time, in order to avoid large collection pauses.
220 The default sweep interval is 8192;
221 .Ev MALLOC_OPTIONS=14g
222 will disable garbage collection.
224 Double/halve the number of thread-specific cache slots per size
226 When there are multiple threads, each thread uses a
227 thread-specific cache for small and medium objects.
228 Thread-specific caching allows many allocations to be satisfied
229 without performing any thread synchronization, at the cost of
230 increased memory use.
233 option for related tuning information.
234 The default number of cache slots is 128;
235 .Ev MALLOC_OPTIONS=7h
236 will disable thread-specific caching.
237 Note that one cache slot per size class is not a valid
238 configuration due to implementation details.
240 Each byte of new memory allocated by
245 will be initialized to 0xa5.
246 All memory returned by
251 will be initialized to 0x5a.
252 This is intended for debugging and will impact performance negatively.
254 Double/halve the virtual memory chunk size.
255 The default chunk size is 4 MiB.
259 to acquire anonymously mapped memory.
260 This option is enabled by default.
265 options are enabled, the allocator prefers anonymous mappings over the DSS,
266 but allocation only fails if memory cannot be acquired via either method.
267 If neither option is enabled, then the
269 option is implicitly enabled in order to assure that there is a method for
272 Double/halve the number of arenas.
273 The default number of arenas is two times the number of CPUs, or one if there
276 Various statistics are printed at program exit via an
279 This has the potential to cause deadlock for a multi-threaded process that exits
280 while one or more threads are executing in the memory allocation functions.
281 Therefore, this option should only be used with care; it is primarily intended
282 as a performance tuning aid during application development.
284 Double/halve the size of the maximum size class that is a multiple of the
285 quantum (8 or 16 bytes, depending on architecture).
286 Above this size, cacheline spacing is used for size classes.
287 The default value is 128 bytes.
294 Consult the source for details on this option.
296 Attempting to allocate zero bytes will return a
298 pointer instead of a valid pointer.
299 (The default behavior is to make a minimal allocation and return a
301 This option is provided for System V compatibility.
302 This option is incompatible with the
306 Rather than return failure for any allocation function, display a diagnostic
309 and cause the program to drop core (using
311 This option should be set at compile time by including the following in the
313 .Bd -literal -offset indent
314 _malloc_options = "X";
317 Each byte of new memory allocated by
322 will be initialized to 0.
323 Note that this initialization only happens once for each byte, so
327 calls do not zero memory that was previously allocated.
328 This is intended for debugging and will impact performance negatively.
335 options are intended for testing and debugging.
336 An application which changes its behavior when these options are used
338 .Sh IMPLEMENTATION NOTES
339 Traditionally, allocators have used
341 to obtain memory, which is suboptimal for several reasons, including race
342 conditions, increased fragmentation, and artificial limitations on maximum
344 This allocator uses both
348 by default, but it can be configured at run time to use only one or the other.
349 If resource limits are not a primary concern, the preferred configuration is
350 .Ev MALLOC_OPTIONS=dM
352 .Ev MALLOC_OPTIONS=DM .
353 When so configured, the
355 resource limit has little practical effect for typical applications; use
356 .Ev MALLOC_OPTIONS=Dm
357 if that is a concern.
358 Regardless of allocator configuration, the
360 resource limit can be used to bound the total virtual memory used by a
361 process, as described in
364 This allocator uses multiple arenas in order to reduce lock contention for
365 threaded programs on multi-processor systems.
366 This works well with regard to threading scalability, but incurs some costs.
367 There is a small fixed per-arena overhead, and additionally, arenas manage
368 memory completely independently of each other, which means a small fixed
369 increase in overall memory fragmentation.
370 These overheads are not generally an issue, given the number of arenas normally
372 Note that using substantially more arenas than the default is not likely to
373 improve performance, mainly due to reduced cache performance.
374 However, it may make sense to reduce the number of arenas if an application
375 does not make much use of the allocation functions.
377 In addition to multiple arenas, this allocator supports thread-specific caching
378 for small and medium objects, in order to make it possible to completely avoid
379 synchronization for most small and medium allocation requests.
380 Such caching allows very fast allocation in the common case, but it increases
381 memory usage and fragmentation, since a bounded number of objects can remain
382 allocated in each thread cache.
384 Memory is conceptually broken into equal-sized chunks, where the chunk size is
385 a power of two that is greater than the page size.
386 Chunks are always aligned to multiples of the chunk size.
387 This alignment makes it possible to find metadata for user objects very
390 User objects are broken into four categories according to size: small, medium,
392 Small objects are smaller than one page.
393 Medium objects range from one page to an upper limit determined at run time (see
397 Large objects are smaller than the chunk size.
398 Huge objects are a multiple of the chunk size.
399 Small, medium, and large objects are managed by arenas; huge objects are managed
400 separately in a single data structure that is shared by all threads.
401 Huge objects are used by applications infrequently enough that this single
402 data structure is not a scalability issue.
404 Each chunk that is managed by an arena tracks its contents as runs of
405 contiguous pages (unused, backing a set of small or medium objects, or backing
407 The combination of chunk alignment and chunk page maps makes it possible to
408 determine all metadata regarding small and large allocations in constant time.
410 Small and medium objects are managed in groups by page runs.
411 Each run maintains a bitmap that tracks which regions are in use.
412 Allocation requests that are no more than half the quantum (8 or 16, depending
413 on architecture) are rounded up to the nearest power of two.
414 Allocation requests that are more than half the quantum, but no more than the
415 minimum cacheline-multiple size class (see the
417 option) are rounded up to the nearest multiple of the quantum.
418 Allocation requests that are more than the minimum cacheline-multiple size
419 class, but no more than the minimum subpage-multiple size class (see the
421 option) are rounded up to the nearest multiple of the cacheline size (64).
422 Allocation requests that are more than the minimum subpage-multiple size class,
423 but no more than the maximum subpage-multiple size class are rounded up to the
424 nearest multiple of the subpage size (256).
425 Allocation requests that are more than the maximum subpage-multiple size class,
426 but no more than the maximum medium size class (see the
428 option) are rounded up to the nearest medium size class; spacing is an
429 automatically determined power of two and ranges from the subpage size to the
431 Allocation requests that are more than the maximum medium size class, but small
432 enough to fit in an arena-managed chunk (see the
434 option), are rounded up to the nearest run size.
435 Allocation requests that are too large to fit in an arena-managed chunk are
436 rounded up to the nearest multiple of the chunk size.
438 Allocations are packed tightly together, which can be an issue for
439 multi-threaded applications.
440 If you need to assure that allocations do not suffer from cacheline sharing,
441 round your allocation requests up to the nearest multiple of the cacheline
443 .Sh DEBUGGING MALLOC PROBLEMS
444 The first thing to do is to set the
447 This option forces a coredump (if possible) at the first sign of trouble,
448 rather than the normal policy of trying to continue if at all possible.
450 It is probably also a good idea to recompile the program with suitable
451 options and symbols for debugger support.
453 If the program starts to give unusual results, coredump or generally behave
454 differently without emitting any of the messages mentioned in the next
455 section, it is likely because it depends on the storage being filled with
457 Try running it with the
460 if that improves the situation, this diagnosis has been confirmed.
461 If the program still misbehaves,
462 the likely problem is accessing memory outside the allocated area.
464 Alternatively, if the symptoms are not easy to reproduce, setting the
466 option may help provoke the problem.
468 In truly difficult cases, the
470 option, if supported by the kernel, can provide a detailed trace of
471 all calls made to these functions.
473 Unfortunately this implementation does not provide much detail about
474 the problems it detects; the performance impact for storing such information
475 would be prohibitive.
476 There are a number of allocator implementations available on the Internet
477 which focus on detecting and pinpointing problems by trading performance for
478 extra sanity checks and detailed diagnostics.
479 .Sh DIAGNOSTIC MESSAGES
480 If any of the memory allocation/deallocation functions detect an error or
481 warning condition, a message will be printed to file descriptor
483 Errors will result in the process dumping core.
486 option is set, all warnings are treated as errors.
490 variable allows the programmer to override the function which emits the text
491 strings forming the errors and warnings if for some reason the
493 file descriptor is not suitable for this.
494 Please note that doing anything which tries to allocate memory in this function
495 is likely to result in a crash or deadlock.
497 All messages are prefixed by
498 .Dq Ao Ar progname Ac Ns Li : (malloc) .
504 functions return a pointer to the allocated memory if successful; otherwise
507 pointer is returned and
516 functions return a pointer, possibly identical to
518 to the allocated memory
519 if successful; otherwise a
521 pointer is returned, and
525 if the error was the result of an allocation failure.
528 function always leaves the original buffer intact
529 when an error occurs, whereas
531 deallocates it in this case.
535 function returns no value.
538 .Fn malloc_usable_size
539 function returns the usable size of the allocation pointed to by
542 The following environment variables affect the execution of the allocation
544 .Bl -tag -width ".Ev MALLOC_OPTIONS"
545 .It Ev MALLOC_OPTIONS
546 If the environment variable
548 is set, the characters it contains will be interpreted as flags to the
549 allocation functions.
552 To dump core whenever a problem occurs:
553 .Bd -literal -offset indent
554 ln -s 'A' /etc/malloc.conf
557 To specify in the source that a program does no return value checking
558 on calls to these functions:
559 .Bd -literal -offset indent
560 _malloc_options = "X";
585 function first appeared in
589 .Fn malloc_usable_size
590 function first appeared in