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 .Fo \*(lp*_malloc_message\*(rp
59 .Fa "const char *p1" "const char *p2" "const char *p3" "const char *p4"
63 .Fn malloc_usable_size "const void *ptr"
69 bytes of uninitialized memory.
70 The allocated space is suitably aligned (after possible pointer coercion)
71 for storage of any type of object.
75 function allocates space for
81 The result is identical to calling
85 with the exception that the allocated memory is explicitly initialized
90 function changes the size of the previously allocated memory referenced by
95 The contents of the memory are unchanged up to the lesser of the new and
97 If the new size is larger,
98 the contents of the newly allocated portion of the memory are undefined.
99 Upon success, the memory referenced by
101 is freed and a pointer to the newly allocated memory is returned.
106 may move the memory allocation, resulting in a different return value than
114 function behaves identically to
116 for the specified size.
120 function is identical to the
122 function, except that it
123 will free the passed pointer when the requested memory cannot be allocated.
126 specific API designed to ease the problems with traditional coding styles
127 for realloc 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 per-arena lock contention threshold at which a thread is
189 randomly re-assigned to an arena.
190 This dynamic load balancing tends to push threads away from highly contended
191 arenas, which avoids worst case contention scenarios in which threads
192 disproportionately utilize arenas.
193 However, due to the highly dynamic load that applications may place on the
194 allocator, it is impossible for the allocator to know in advance how sensitive
195 it should be to contention over arenas.
196 Therefore, some applications may benefit from increasing or decreasing this
198 This option is not available for some configurations (non-PIC).
200 Double/halve the size of the maximum size class that is a multiple of the
202 Above this size, subpage spacing (256 bytes) is used for size classes.
203 The default value is 512 bytes.
207 to acquire memory in the data storage segment (DSS).
208 This option is enabled by default.
211 option for related information and interactions.
213 Double/halve the per-arena maximum number of dirty unused pages that are
214 allowed to accumulate before informing the kernel about at least half of those
217 This provides the kernel with sufficient information to recycle dirty pages if
218 physical memory becomes scarce and the pages remain unused.
219 The default is 512 pages per arena;
220 .Ev MALLOC_OPTIONS=10f
221 will prevent any dirty unused pages from accumulating.
223 When there are multiple threads, use thread-specific caching for objects that
224 are smaller than one page.
225 This option is enabled by default.
226 Thread-specific caching allows many allocations to be satisfied without
227 performing any thread synchronization, at the cost of increased memory use.
230 option for related tuning information.
231 This option is not available for some configurations (non-PIC).
233 Each byte of new memory allocated by
238 will be initialized to 0xa5.
239 All memory returned by
244 will be initialized to 0x5a.
245 This is intended for debugging and will impact performance negatively.
247 Double/halve the virtual memory chunk size.
248 The default chunk size is 1 MB.
252 to acquire anonymously mapped memory.
253 This option is enabled by default.
258 options are enabled, the allocator prefers the DSS over anonymous mappings,
259 but allocation only fails if memory cannot be acquired via either method.
260 If neither option is enabled, then the
262 option is implicitly enabled in order to assure that there is a method for
265 Double/halve the number of arenas.
266 The default number of arenas is two times the number of CPUs, or one if there
269 Various statistics are printed at program exit via an
272 This has the potential to cause deadlock for a multi-threaded process that exits
273 while one or more threads are executing in the memory allocation functions.
274 Therefore, this option should only be used with care; it is primarily intended
275 as a performance tuning aid during application development.
277 Double/halve the size of the maximum size class that is a multiple of the
278 quantum (8 or 16 bytes, depending on architecture).
279 Above this size, cacheline spacing is used for size classes.
280 The default value is 128 bytes.
282 Double/halve magazine size, which approximately doubles/halves the number of
283 rounds in each magazine.
284 Magazines are used by the thread-specific caching machinery to acquire and
285 release objects in bulk.
286 Increasing the magazine size decreases locking overhead, at the expense of
287 increased memory usage.
288 This option is not available for some configurations (non-PIC).
295 Consult the source for details on this option.
297 Attempting to allocate zero bytes will return a
301 (The default behavior is to make a minimal allocation and return a
303 This option is provided for System V compatibility.
304 This option is incompatible with the
308 Rather than return failure for any allocation function,
309 display a diagnostic message on
311 and cause the program to drop
314 This option should be set at compile time by including the following in
316 .Bd -literal -offset indent
317 _malloc_options = "X";
320 Each byte of new memory allocated by
325 will be initialized to 0.
326 Note that this initialization only happens once for each byte, so
330 calls do not zero memory that was previously allocated.
331 This is intended for debugging and will impact performance negatively.
338 options are intended for testing and debugging.
339 An application which changes its behavior when these options are used
341 .Sh IMPLEMENTATION NOTES
342 Traditionally, allocators have used
344 to obtain memory, which is suboptimal for several reasons, including race
345 conditions, increased fragmentation, and artificial limitations on maximum
347 This allocator uses both
351 by default, but it can be configured at run time to use only one or the other.
352 If resource limits are not a primary concern, the preferred configuration is
353 .Ev MALLOC_OPTIONS=dM
355 .Ev MALLOC_OPTIONS=DM .
356 When so configured, the
358 resource limit has little practical effect for typical applications; use
359 .Ev MALLOC_OPTIONS=Dm
360 if that is a concern.
361 Regardless of allocator configuration, the
363 resource limit can be used to bound the total virtual memory used by a
364 process, as described in
367 This allocator uses multiple arenas in order to reduce lock contention for
368 threaded programs on multi-processor systems.
369 This works well with regard to threading scalability, but incurs some costs.
370 There is a small fixed per-arena overhead, and additionally, arenas manage
371 memory completely independently of each other, which means a small fixed
372 increase in overall memory fragmentation.
373 These overheads are not generally an issue, given the number of arenas normally
375 Note that using substantially more arenas than the default is not likely to
376 improve performance, mainly due to reduced cache performance.
377 However, it may make sense to reduce the number of arenas if an application
378 does not make much use of the allocation functions.
380 In addition to multiple arenas, this allocator supports thread-specific
381 caching for small objects (smaller than one page), in order to make it
382 possible to completely avoid synchronization for most small allocation requests.
383 Such caching allows very fast allocation in the common case, but it increases
384 memory usage and fragmentation, since a bounded number of objects can remain
385 allocated in each thread cache.
387 Memory is conceptually broken into equal-sized chunks, where the chunk size is
388 a power of two that is greater than the page size.
389 Chunks are always aligned to multiples of the chunk size.
390 This alignment makes it possible to find metadata for user objects very
393 User objects are broken into three categories according to size: small, large,
395 Small objects are smaller than one page.
396 Large objects are smaller than the chunk size.
397 Huge objects are a multiple of the chunk size.
398 Small and large objects are managed by arenas; huge objects are managed
399 separately in a single data structure that is shared by all threads.
400 Huge objects are used by applications infrequently enough that this single
401 data structure is not a scalability issue.
403 Each chunk that is managed by an arena tracks its contents as runs of
404 contiguous pages (unused, backing a set of small objects, or backing one large
406 The combination of chunk alignment and chunk page maps makes it possible to
407 determine all metadata regarding small and large allocations in constant time.
409 Small objects are managed in groups by page runs.
410 Each run maintains a bitmap that tracks which regions are in use.
411 Allocation requests that are no more than half the quantum (8 or 16, depending
412 on architecture) are rounded up to the nearest power of two.
413 Allocation requests that are more than half the quantum, but no more than the
414 minimum cacheline-multiple size class (see the
416 option) are rounded up to the nearest multiple of the quantum.
417 Allocation requests that are more than the minumum cacheline-multiple size
418 class, but no more than the minimum subpage-multiple size class (see the
420 option) are rounded up to the nearest multiple of the cacheline size (64).
421 Allocation requests that are more than the minimum subpage-multiple size class
422 are rounded up to the nearest multiple of the subpage size (256).
423 Allocation requests that are more than one page, but small enough to fit in
424 an arena-managed chunk (see the
426 option), are rounded up to the nearest run size.
427 Allocation requests that are too large to fit in an arena-managed chunk are
428 rounded up to the nearest multiple of the chunk size.
430 Allocations are packed tightly together, which can be an issue for
431 multi-threaded applications.
432 If you need to assure that allocations do not suffer from cacheline sharing,
433 round your allocation requests up to the nearest multiple of the cacheline
435 .Sh DEBUGGING MALLOC PROBLEMS
436 The first thing to do is to set the
439 This option forces a coredump (if possible) at the first sign of trouble,
440 rather than the normal policy of trying to continue if at all possible.
442 It is probably also a good idea to recompile the program with suitable
443 options and symbols for debugger support.
445 If the program starts to give unusual results, coredump or generally behave
446 differently without emitting any of the messages mentioned in the next
447 section, it is likely because it depends on the storage being filled with
449 Try running it with the
452 if that improves the situation, this diagnosis has been confirmed.
453 If the program still misbehaves,
454 the likely problem is accessing memory outside the allocated area.
456 Alternatively, if the symptoms are not easy to reproduce, setting the
458 option may help provoke the problem.
460 In truly difficult cases, the
462 option, if supported by the kernel, can provide a detailed trace of
463 all calls made to these functions.
465 Unfortunately this implementation does not provide much detail about
466 the problems it detects; the performance impact for storing such information
467 would be prohibitive.
468 There are a number of allocator implementations available on the Internet
469 which focus on detecting and pinpointing problems by trading performance for
470 extra sanity checks and detailed diagnostics.
471 .Sh DIAGNOSTIC MESSAGES
472 If any of the memory allocation/deallocation functions detect an error or
473 warning condition, a message will be printed to file descriptor
475 Errors will result in the process dumping core.
478 option is set, all warnings are treated as errors.
482 variable allows the programmer to override the function which emits
483 the text strings forming the errors and warnings if for some reason
486 file descriptor is not suitable for this.
487 Please note that doing anything which tries to allocate memory in
488 this function is likely to result in a crash or deadlock.
490 All messages are prefixed by
491 .Dq Ao Ar progname Ac Ns Li : (malloc) .
497 functions return a pointer to the allocated memory if successful; otherwise
500 pointer is returned and
509 functions return a pointer, possibly identical to
511 to the allocated memory
512 if successful; otherwise a
514 pointer is returned, and
518 if the error was the result of an allocation failure.
521 function always leaves the original buffer intact
522 when an error occurs, whereas
524 deallocates it in this case.
528 function returns no value.
531 .Fn malloc_usable_size
532 function returns the usable size of the allocation pointed to by
535 The following environment variables affect the execution of the allocation
537 .Bl -tag -width ".Ev MALLOC_OPTIONS"
538 .It Ev MALLOC_OPTIONS
539 If the environment variable
541 is set, the characters it contains will be interpreted as flags to the
542 allocation functions.
545 To dump core whenever a problem occurs:
547 .Bd -literal -offset indent
548 ln -s 'A' /etc/malloc.conf
551 To specify in the source that a program does no return value checking
552 on calls to these functions:
553 .Bd -literal -offset indent
554 _malloc_options = "X";
578 function first appeared in
582 .Fn malloc_usable_size
583 function first appeared in