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 value of the newly allocated portion of the memory is 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 affect 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, character by character as flags.
170 Most flags are single letters,
171 where uppercase indicates that the behavior is set, or on,
172 and lowercase means that the behavior is not set, or off.
173 .Bl -tag -width indent
175 All warnings (except for the warning about unknown
176 flags being set) become fatal.
177 The process will call
183 when pages within a chunk are no longer in use, but the chunk as a whole cannot
185 This is primarily of use when swapping is a real possibility, due to the high
190 Each byte of new memory allocated by
195 will be initialized to 0xa5.
196 All memory returned by
201 will be initialized to 0x5a.
202 This is intended for debugging and will impact performance negatively.
204 Increase/decrease the virtual memory chunk size by a factor of two.
205 The default chunk size is 2 MB.
206 This option can be specified multiple times.
208 Increase/decrease the number of arenas by a factor of two.
209 The default number of arenas is four times the number of CPUs, or one if there
211 This option can be specified multiple times.
213 Various statistics are printed at program exit via an
216 This has the potential to cause deadlock for a multi-threaded process that exits
217 while one or more threads are executing in the memory allocation functions.
218 Therefore, this option should only be used with care; it is primarily intended
219 as a performance tuning aid during application development.
221 Increase/decrease the size of the allocation quantum by a factor of two.
222 The default quantum is the minimum allowed by the architecture (typically 8 or
224 This option can be specified multiple times.
226 Increase/decrease the size of the maximum size class that is a multiple of the
227 quantum by a factor of two.
228 Above this size, power-of-two spacing is used for size classes.
229 The default value is 512 bytes.
230 This option can be specified multiple times.
237 Consult the source for details on this option.
239 Attempting to allocate zero bytes will return a
243 (The default behavior is to make a minimal allocation and return a
245 This option is provided for System V compatibility.
246 This option is incompatible with the
250 Rather than return failure for any allocation function,
251 display a diagnostic message on
253 and cause the program to drop
256 This option should be set at compile time by including the following in
258 .Bd -literal -offset indent
259 _malloc_options = "X";
262 Each byte of new memory allocated by
267 will be initialized to 0.
268 Note that this initialization only happens once for each byte, so
272 calls do not zero memory that was previously allocated.
273 This is intended for debugging and will impact performance negatively.
280 options are intended for testing and debugging.
281 An application which changes its behavior when these options are used
283 .Sh IMPLEMENTATION NOTES
284 This allocator uses multiple arenas in order to reduce lock contention for
285 threaded programs on multi-processor systems.
286 This works well with regard to threading scalability, but incurs some costs.
287 There is a small fixed per-arena overhead, and additionally, arenas manage
288 memory completely independently of each other, which means a small fixed
289 increase in overall memory fragmentation.
290 These overheads are not generally an issue, given the number of arenas normally
292 Note that using substantially more arenas than the default is not likely to
293 improve performance, mainly due to reduced cache performance.
294 However, it may make sense to reduce the number of arenas if an application
295 does not make much use of the allocation functions.
297 Chunks manage their pages by using a power-of-two buddy allocation strategy.
298 Each chunk maintains a page map that makes it possible to determine the state
299 of any page in the chunk in constant time.
300 Allocations that are no larger than one half of a page are managed in groups by
303 Each run maintains a bitmap that tracks which regions are in use.
304 Allocation requests that are no more than half the quantum (see the
306 option) are rounded up to the nearest power of two (typically 2, 4, or 8).
307 Allocation requests that are more than half the quantum, but no more than the
308 maximum quantum-multiple size class (see the
310 option) are rounded up to the nearest multiple of the quantum.
311 Allocation requests that are larger than the maximum quantum-multiple size
312 class, but no larger than one half of a page, are rounded up to the nearest
314 Allocation requests that are larger than half of a page, but no larger than half
317 option), are rounded up to the nearest run size.
318 Allocation requests that are larger than half of a chunk are rounded up to the
319 nearest multiple of the chunk size.
321 Allocations are packed tightly together, which can be an issue for
322 multi-threaded applications.
323 If you need to assure that allocations do not suffer from cache line sharing,
324 round your allocation requests up to the nearest multiple of the cache line
326 .Sh DEBUGGING MALLOC PROBLEMS
327 The first thing to do is to set the
330 This option forces a coredump (if possible) at the first sign of trouble,
331 rather than the normal policy of trying to continue if at all possible.
333 It is probably also a good idea to recompile the program with suitable
334 options and symbols for debugger support.
336 If the program starts to give unusual results, coredump or generally behave
337 differently without emitting any of the messages mentioned in the next
338 section, it is likely because it depends on the storage being filled with
340 Try running it with the
343 if that improves the situation, this diagnosis has been confirmed.
344 If the program still misbehaves,
345 the likely problem is accessing memory outside the allocated area.
347 Alternatively, if the symptoms are not easy to reproduce, setting the
349 option may help provoke the problem.
351 In truly difficult cases, the
353 option, if supported by the kernel, can provide a detailed trace of
354 all calls made to these functions.
356 Unfortunately this implementation does not provide much detail about
357 the problems it detects; the performance impact for storing such information
358 would be prohibitive.
359 There are a number of allocation implementations available on the Internet
360 which focus on detecting and pinpointing problems by trading performance for
361 extra sanity checks and detailed diagnostics.
362 .Sh DIAGNOSTIC MESSAGES
363 If any of the memory allocation/deallocation functions detect an error or
364 warning condition, a message will be printed to file descriptor
366 Errors will result in the process dumping core.
369 option is set, all warnings are treated as errors.
373 variable allows the programmer to override the function which emits
374 the text strings forming the errors and warnings if for some reason
377 file descriptor is not suitable for this.
378 Please note that doing anything which tries to allocate memory in
379 this function is likely to result in a crash or deadlock.
381 All messages are prefixed by
382 .Dq Ao Ar progname Ac Ns Li : (malloc) .
388 functions return a pointer to the allocated memory if successful; otherwise
391 pointer is returned and
400 functions return a pointer, possibly identical to
402 to the allocated memory
403 if successful; otherwise a
405 pointer is returned, and
409 if the error was the result of an allocation failure.
412 function always leaves the original buffer intact
413 when an error occurs, whereas
415 deallocates it in this case.
419 function returns no value.
422 .Fn malloc_usable_size
423 function returns the usable size of the allocation pointed to by
426 The following environment variables affect the execution of the allocation
428 .Bl -tag -width ".Ev MALLOC_OPTIONS"
429 .It Ev MALLOC_OPTIONS
430 If the environment variable
432 is set, the characters it contains will be interpreted as flags to the
433 allocation functions.
436 To dump core whenever a problem occurs:
438 .Bd -literal -offset indent
439 ln -s 'A' /etc/malloc.conf
442 To specify in the source that a program does no return value checking
443 on calls to these functions:
444 .Bd -literal -offset indent
445 _malloc_options = "X";
467 function first appeared in
471 .Fn malloc_usable_size
472 function first appeared in