.\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" This code is derived from software contributed to Berkeley by .\" the American National Standards Committee X3, on Information .\" Processing Systems. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $OpenBSD: malloc.3,v 1.98 2016/10/08 12:56:18 otto Exp $ .\" .Dd $Mdocdate: October 8 2016 $ .Dt MALLOC 3 .Os .Sh NAME .Nm malloc , .Nm calloc , .Nm reallocarray , .Nm realloc , .Nm free .Nd memory allocation and deallocation .Sh SYNOPSIS .In stdlib.h .Ft void * .Fn malloc "size_t size" .Ft void * .Fn calloc "size_t nmemb" "size_t size" .Ft void * .Fn reallocarray "void *ptr" "size_t nmemb" "size_t size" .Ft void * .Fn realloc "void *ptr" "size_t size" .Ft void .Fn free "void *ptr" .Vt char *malloc_options ; .Sh DESCRIPTION The .Fn malloc function allocates uninitialized space for an object of the specified .Fa size . .Fn malloc maintains multiple lists of free blocks according to size, allocating space from the appropriate list. The allocated space is suitably aligned (after possible pointer coercion) for storage of any type of object. If the space is of .Em pagesize or larger, the memory returned will be page-aligned. .Pp The .Fn calloc function allocates space for an array of .Fa nmemb objects, each of the specified .Fa size . The space is initialized to zero. .Pp The .Fn realloc function changes the size of the object pointed to by .Fa ptr to .Fa size bytes and returns a pointer to the (possibly moved) object. The contents of the object are unchanged up to the lesser of the new and old sizes. If the new size is larger, the value of the newly allocated portion of the object is indeterminate and uninitialized. If the space cannot be allocated, the object pointed to by .Fa ptr is unchanged. If .Fa ptr is .Dv NULL , .Fn realloc behaves like .Fn malloc and allocates a new object. .Pp The .Fn reallocarray function is similar to .Fn realloc except it operates on .Fa nmemb members of size .Fa size and checks for integer overflow in the calculation .Fa nmemb * .Fa size . .Pp The .Fn free function causes the space pointed to by .Fa ptr to be either placed on a list of free pages to make it available for future allocation or, if required, to be returned to the kernel using .Xr munmap 2 . If .Fa ptr is a .Dv NULL pointer, no action occurs. If .Fa ptr was previously freed by .Fn free , .Fn realloc , or .Fn reallocarray , the behavior is undefined and the double free is a security concern. .Sh RETURN VALUES Upon successful completion, the functions .Fn malloc , .Fn calloc , .Fn realloc , and .Fn reallocarray return a pointer to the allocated space; otherwise, a .Dv NULL pointer is returned and .Va errno is set to .Er ENOMEM . .Pp If .Fa size or .Fa nmemb is equal to 0, a unique pointer to an access protected, zero sized object is returned. Access via this pointer will generate a .Dv SIGSEGV exception. .Pp If multiplying .Fa nmemb and .Fa size results in integer overflow, .Fn calloc and .Fn reallocarray return .Dv NULL and set .Va errno to .Er ENOMEM . .Sh IDIOMS Consider .Fn calloc or the extension .Fn reallocarray when there is multiplication in the .Fa size argument of .Fn malloc or .Fn realloc . For example, avoid this common idiom as it may lead to integer overflow: .Bd -literal -offset indent if ((p = malloc(num * size)) == NULL) err(1, NULL); .Ed .Pp A drop-in replacement is the .Ox extension .Fn reallocarray : .Bd -literal -offset indent if ((p = reallocarray(NULL, num, size)) == NULL) err(1, NULL); .Ed .Pp Alternatively, .Fn calloc may be used at the cost of initialization overhead. .Pp When using .Fn realloc , be careful to avoid the following idiom: .Bd -literal -offset indent size += 50; if ((p = realloc(p, size)) == NULL) return (NULL); .Ed .Pp Do not adjust the variable describing how much memory has been allocated until the allocation has been successful. This can cause aberrant program behavior if the incorrect size value is used. In most cases, the above sample will also result in a leak of memory. As stated earlier, a return value of .Dv NULL indicates that the old object still remains allocated. Better code looks like this: .Bd -literal -offset indent newsize = size + 50; if ((newp = realloc(p, newsize)) == NULL) { free(p); p = NULL; size = 0; return (NULL); } p = newp; size = newsize; .Ed .Pp As with .Fn malloc , it is important to ensure the new size value will not overflow; i.e. avoid allocations like the following: .Bd -literal -offset indent if ((newp = realloc(p, num * size)) == NULL) { ... .Ed .Pp Instead, use .Fn reallocarray : .Bd -literal -offset indent if ((newp = reallocarray(p, num, size)) == NULL) { ... .Ed .Pp Calling .Fn realloc with a .Dv NULL .Fa ptr is equivalent to calling .Fn malloc . Instead of this idiom: .Bd -literal -offset indent if (p == NULL) newp = malloc(newsize); else newp = realloc(p, newsize); .Ed .Pp Use the following: .Bd -literal -offset indent newp = realloc(p, newsize); .Ed .Sh ENVIRONMENT .Bl -tag -width "/etc/malloc.conf" .It Ev MALLOC_OPTIONS String of flags documented in .Xr malloc.conf 5 . .El .Sh FILES .Bl -tag -width "/etc/malloc.conf" .It Pa /etc/malloc.conf Symbolic link to filename containing option flags. .El .Sh EXAMPLES If .Fn malloc must be used with multiplication, be sure to test for overflow: .Bd -literal -offset indent size_t num, size; \&... /* Check for size_t overflow */ if (size && num > SIZE_MAX / size) errc(1, EOVERFLOW, "overflow"); if ((p = malloc(size * num)) == NULL) err(1, NULL); .Ed .Pp The above test is not sufficient in all cases. For example, multiplying ints requires a different set of checks: .Bd -literal -offset indent int num, size; \&... /* Avoid invalid requests */ if (size < 0 || num < 0) errc(1, EOVERFLOW, "overflow"); /* Check for signed int overflow */ if (size && num > INT_MAX / size) errc(1, EOVERFLOW, "overflow"); if ((p = malloc(size * num)) == NULL) err(1, NULL); .Ed .Pp Assuming the implementation checks for integer overflow as .Ox does, it is much easier to use .Fn calloc or .Fn reallocarray . .Pp The above examples could be simplified to: .Bd -literal -offset indent if ((p = reallocarray(NULL, num, size)) == NULL) err(1, NULL); .Ed .Pp or at the cost of initialization: .Bd -literal -offset indent if ((p = calloc(num, size)) == NULL) err(1, NULL); .Ed .Sh DIAGNOSTICS If .Fn malloc , .Fn calloc , .Fn realloc , .Fn reallocarray , or .Fn free detect an error condition, a message will be printed to file descriptor 2 (not using stdio). Errors will result in the process being aborted. .Pp Here is a brief description of the error messages and what they mean: .Bl -tag -width Ds .It Dq out of memory If the .Cm X option is specified it is an error for .Fn malloc , .Fn calloc , .Fn realloc , or .Fn reallocarray to return .Dv NULL . .It Dq malloc init mmap failed This is a rather weird condition that is most likely to indicate a seriously overloaded system or a ulimit restriction. .It Dq bogus pointer (double free?) An attempt to .Fn free , .Fn realloc , or .Fn reallocarray an unallocated pointer was made. .It Dq chunk is already free There was an attempt to free a chunk that had already been freed. .It Dq use after free A chunk has been modified after it was freed. .It Dq modified chunk-pointer The pointer passed to .Fn free , .Fn realloc , or .Fn reallocarray has been modified. .It Dq chunk canary corrupted 0xhhhhllll A byte after the requested size has been overwritten, indicating a heap overflow. The high word is the requested length of the chunk; the low word is the offset at which corruption was detected. .It Dq recursive call An attempt was made to call recursively into these functions, i.e., from a signal handler. This behavior is not supported. In particular, signal handlers should .Em not use any of the .Fn malloc functions nor utilize any other functions which may call .Fn malloc (e.g., .Xr stdio 3 routines). .It Dq unknown char in MALLOC_OPTIONS We found something we didn't understand. .It Dq malloc cache overflow/underflow The internal malloc page cache has been corrupted. .It Dq malloc free slot lost The internal malloc page cache has been corrupted. .It Dq guard size An inconsistent guard size was detected. .It any other error .Fn malloc detected an internal error; consult sources and/or wizards. .El .Sh SEE ALSO .Xr brk 2 , .Xr mmap 2 , .Xr munmap 2 , .Xr alloca 3 , .Xr getpagesize 3 , .Xr posix_memalign 3 , .Xr sysconf 3 , .Xr malloc.conf 5 .Sh STANDARDS The .Fn malloc , .Fn calloc , .Fn realloc , and .Fn free functions conform to .St -ansiC . .Pp If .Fa size or .Fa nmemb are 0, the return value is implementation defined; other conforming implementations may return .Dv NULL in this case. .Pp The .Ev MALLOC_OPTIONS environment variable, the file .Pa /etc/malloc.conf , and the .Sx DIAGNOSTICS output are extensions to the standard. .Sh HISTORY A .Fn free internal kernel function and a predecessor to .Fn malloc , .Fn alloc , first appeared in .At v1 . C library functions .Fn alloc and .Fn free appeared in .At v6 . The functions .Fn malloc , .Fn calloc , and .Fn realloc first appeared in .At v7 . .Pp A new implementation by Chris Kingsley was introduced in .Bx 4.2 , followed by a complete rewrite by Poul-Henning Kamp which appeared in .Fx 2.2 and was included in .Ox 2.0 . These implementations were all .Xr sbrk 2 based. In .Ox 3.8 , Thierry Deval rewrote .Nm to use the .Xr mmap 2 system call, making the page addresses returned by .Nm random. A rewrite by Otto Moerbeek introducing a new central data structure and more randomization appeared in .Ox 4.4 . .Pp The .Fn reallocarray function appeared in .Ox 5.6 . .Sh CAVEATS When using .Fn malloc , be wary of signed integer and .Vt size_t overflow especially when there is multiplication in the .Fa size argument. .Pp Signed integer overflow will cause undefined behavior which compilers typically handle by wrapping back around to negative numbers. Depending on the input, this can result in allocating more or less memory than intended. .Pp An unsigned overflow has defined behavior which will wrap back around and return less memory than intended. .Pp A signed or unsigned integer overflow is a .Em security risk if less memory is returned than intended. Subsequent code may corrupt the heap by writing beyond the memory that was allocated. An attacker may be able to leverage this heap corruption to execute arbitrary code. .Pp Consider using .Fn calloc or .Fn reallocarray instead of using multiplication in .Fn malloc and .Fn realloc to avoid these problems on .Ox .