From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libc/stdlib/malloc.3 | 860 ------------------------------------------- 1 file changed, 860 deletions(-) delete mode 100644 src/lib/libc/stdlib/malloc.3 (limited to 'src/lib/libc/stdlib/malloc.3') diff --git a/src/lib/libc/stdlib/malloc.3 b/src/lib/libc/stdlib/malloc.3 deleted file mode 100644 index bea5575bf8..0000000000 --- a/src/lib/libc/stdlib/malloc.3 +++ /dev/null @@ -1,860 +0,0 @@ -.\" -.\" 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.142 2024/08/03 20:09:24 guenther Exp $ -.\" -.Dd $Mdocdate: August 3 2024 $ -.Dt MALLOC 3 -.Os -.Sh NAME -.Nm malloc , -.Nm calloc , -.Nm realloc , -.Nm free , -.Nm reallocarray , -.Nm recallocarray , -.Nm freezero , -.Nm aligned_alloc , -.Nm malloc_conceal , -.Nm calloc_conceal -.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 realloc "void *ptr" "size_t size" -.Ft void -.Fn free "void *ptr" -.Ft void * -.Fn reallocarray "void *ptr" "size_t nmemb" "size_t size" -.Ft void * -.Fn recallocarray "void *ptr" "size_t oldnmemb" "size_t nmemb" "size_t size" -.Ft void -.Fn freezero "void *ptr" "size_t size" -.Ft void * -.Fn aligned_alloc "size_t alignment" "size_t size" -.Ft void * -.Fn malloc_conceal "size_t size" -.Ft void * -.Fn calloc_conceal "size_t nmemb" "size_t size" -.Vt char *malloc_options ; -.Sh DESCRIPTION -The standard functions -.Fn malloc , -.Fn calloc , -and -.Fn realloc -allocate -.Em objects , -regions of memory to store values. -The -.Fn malloc -function allocates uninitialized space for an object of -the specified -.Fa size . -.Fn malloc -maintains multiple lists of free objects according to size, allocating -from the appropriate list or requesting memory from the kernel. -The allocated space is suitably aligned (after possible pointer coercion) for -storage of any type of object. -.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. -If -.Fa ptr -is not -.Dv NULL , -it must be a pointer returned by an earlier call to an allocation or -reallocation function that was not freed in between. -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 free -function causes the space pointed to by -.Fa ptr -to be either placed on a list of free blocks to make it available for future -allocation or, when appropriate, to be returned to the kernel using -.Xr munmap 2 . -If -.Fa ptr -is -.Dv NULL , -no action occurs. -If -.Fa ptr -was previously freed by -.Fn free -or a reallocation function, -the behavior is undefined and the double free is a security concern. -.Pp -Designed for safe allocation of arrays, -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 -Used for the allocation of memory holding sensitive data, -the -.Fn recallocarray -and -.Fn freezero -functions guarantee that memory becoming unallocated is explicitly -.Em discarded , -meaning pages of memory are disposed via -.Xr munmap 2 -and cached free objects are cleared with -.Xr explicit_bzero 3 . -.Pp -The -.Fn recallocarray -function is similar to -.Fn reallocarray -except it ensures newly allocated memory is cleared similar to -.Fn calloc . -If -.Fa ptr -is -.Dv NULL , -.Fa oldnmemb -is ignored and the call is equivalent to -.Fn calloc . -If -.Fa ptr -is not -.Dv NULL , -.Fa oldnmemb -must be a value such that -.Fa oldnmemb -* -.Fa size -is the size of the earlier allocation that returned -.Fa ptr , -otherwise the behavior is undefined. -.Pp -The -.Fn freezero -function is similar to the -.Fn free -function except it ensures memory is explicitly discarded. -If -.Fa ptr -is -.Dv NULL , -no action occurs. -If -.Fa ptr -is not -.Dv NULL , -the -.Fa size -argument must be equal to or smaller than the size of the earlier allocation -that returned -.Fa ptr . -.Fn freezero -guarantees the memory range starting at -.Fa ptr -with length -.Fa size -is discarded while deallocating the whole object originally allocated. -.Pp -The -.Fn aligned_alloc -function allocates -.Fa size -bytes of memory such that the allocation's base address is a multiple of -.Fa alignment . -The requested -.Fa alignment -must be a power of 2. -If -.Fa size -is not a multiple of -.Fa alignment , -behavior is undefined. -.Pp -The -.Fn malloc_conceal -and -.Fn calloc_conceal -functions behave the same as -.Fn malloc -and -.Fn calloc -respectively, -with the exception that the allocation returned is marked with the -.Dv MAP_CONCEAL -.Xr mmap 2 -flag and calling -.Fn free -on the allocation will discard the contents explicitly. -A reallocation of a concealed allocation will leave these properties intact. -.Sh MALLOC OPTIONS -Upon the first call to the -.Fn malloc -family of functions, an initialization sequence inspects the -value of the -.Va vm.malloc_conf -.Xr sysctl 2 , -next checks the environment for a variable called -.Ev MALLOC_OPTIONS , -and finally looks at the global variable -.Va malloc_options -in the program. -Each is scanned for the flags documented below. -Unless otherwise noted uppercase means on, lowercase means off. -During initialization, flags occurring later modify the behaviour -that was requested by flags processed earlier. -.Bl -tag -width indent -.It Cm C -.Dq Canaries . -Add canaries at the end of allocations in order to detect -heap overflows. -The canary's content is checked when -.Nm free -is called. -If it has been corrupted, the process is aborted. -.It Cm D -.Dq Dump . -.Fn malloc -will dump a leak report using -.Xr utrace 2 -at exit. -To record the dump: -.Pp -.Dl $ MALLOC_OPTIONS=D ktrace -tu program ... -.Pp -To view the leak report: -.Pp -.Dl $ kdump -u malloc ... -.Pp -By default, the immediate caller of a -.Nm -function will be recorded. -Use malloc option -.Cm 2 , -.Cm 3 -or -.Cm 4 -to record deeper call stacks. -These malloc options imply -.Cm D . -.It Cm F -.Dq Freecheck . -Enable more extensive double free and write after free detection. -All chunks in the delayed free list will be checked for double frees and -write after frees. -Unused pages on the freelist are read and write protected to -cause a segmentation fault upon access. -.It Cm G -.Dq Guard . -Enable guard pages. -Each page size or larger allocation is followed by a guard page that will -cause a segmentation fault upon any access. -.It Cm J -.Dq More junking . -Increase the junk level by one if it is smaller than 2. -.It Cm j -.Dq Less junking . -Decrease the junk level by one if it is larger than 0. -Junking writes some junk bytes into the area allocated. -Junk is bytes of 0xdb when allocating; -small allocations are initially junked with 0xdf as are freed allocations. -By default the junk level is 1: after free, -small chunks are completely junked; -for pages the first part is junked. -After a delay, -the filling pattern is validated and the process is aborted if the pattern -was modified. -For junk level 2, junking is done on allocation as well and without size -restrictions. -If the junk level is zero, no junking is performed. -.It Cm R -.Dq realloc . -Always reallocate when -.Fn realloc -is called, even if the initial allocation was big enough. -.\".Pp -.\".It Cm U -.\".Dq utrace . -.\"Generate entries for -.\".Xr ktrace 1 -.\"for all operations. -.\"Consult the source for this one. -.It Cm S -.\" Malloc option S is vaguely documented on purpose. -Enable all options suitable for security auditing. -.It Cm U -.Dq Free unmap . -Enable use after free protection for larger allocations. -Unused pages on the freelist are read and write protected to -cause a segmentation fault upon access. -.It Cm V -.Dq Verbose . -Use with -.Cm D -to get a verbose dump of malloc's internal state. -.It Cm X -.Dq xmalloc . -Rather than return failure, -.Xr abort 3 -the program with a diagnostic message on stderr. -It is the intention that this option be set at compile time by -including in the source: -.Bd -literal -offset indent -extern char *malloc_options; -malloc_options = "X"; -.Ed -.Pp -Note that this will cause code that is supposed to handle -out-of-memory conditions gracefully to abort instead. -.It Cm < -.Dq Halve the cache size . -Decrease the size of the free page cache by a factor of two. -.It Cm > -.Dq Double the cache size . -Increase the size of the free page cache by a factor of two. -.El -.Pp -If a program changes behavior if any of these options (except -.Cm X ) -are used, -it is buggy. -.Pp -The default size of the cache is 64 single page allocations. -It also caches a number of larger regions. -Multi-threaded programs use multiple pools. -.Sh RETURN VALUES -Upon successful completion, the allocation functions -return a pointer to the allocated space; otherwise, -.Dv NULL -is returned and -.Va errno -is set to -.Er ENOMEM . -The function -.Fn aligned_alloc -returns -.Dv NULL -and sets -.Va errno -to -.Er EINVAL -if -.Fa alignment -is not a power of 2. -.Pp -If -.Fa nmemb -or -.Fa size -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 , -.Fn reallocarray -and -.Fn recallocarray -return -.Dv NULL -and set -.Va errno -to -.Er ENOMEM . -.Pp -If -.Fa ptr -is not -.Dv NULL -and multiplying -.Fa oldnmemb -and -.Fa size -results in integer overflow, -.Fn recallocarray -returns -.Dv NULL -and sets -.Va errno -to -.Er EINVAL . -.Sh IDIOMS -Consider -.Fn calloc -or the extensions -.Fn reallocarray -and -.Fn recallocarray -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 -.Pp -The -.Fn recallocarray -function should be used for resizing objects containing sensitive data like -keys. -To avoid leaking information, -it guarantees memory is cleared before placing it on the internal free list. -Deallocation of such an object should be done by calling -.Fn freezero . -.Sh ENVIRONMENT -.Bl -tag -width "MALLOC_OPTIONS" -.It Ev MALLOC_OPTIONS -String of 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(num * size)) == 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(num * size)) == NULL) - err(1, NULL); -.Ed -.Pp -Assuming the implementation checks for integer overflow as -.Ox -does, it is much easier to use -.Fn calloc , -.Fn reallocarray , -or -.Fn recallocarray . -.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 -.Pp -Set a systemwide reduction of the cache to a quarter of the -default size and use guard pages: -.Pp -.Dl # sysctl vm.malloc_conf='G<<' -.Sh DIAGNOSTICS -If any of the functions 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 the allocation functions -to return -.Dv NULL . -.It Dq bogus pointer (double free?) -An attempt to -.Fn free -or -reallocate an unallocated pointer was made. -.It Dq double free -There was an attempt to free an allocation that had already been freed. -.It Dq write to free mem Va address Ns [ Va start Ns .. Ns Va end Ns ]@ Ns Va size -An allocation has been modified after it was freed, -or a chunk that was never allocated was written to. -The -.Va range -at which corruption was detected is printed between [ and ]. -.Pp -Enabling option -.Cm D -allows malloc to print information about where the allocation -was done. -.It Dq modified chunk-pointer -The pointer passed to -.Fn free -or a reallocation function has been modified. -.It Dq canary corrupted Va address Ns [ Va offset Ns ]@ Ns Va length Ns / Ns Va size -A byte after the requested -.Va length -has been overwritten, -indicating a heap overflow. -The -.Va offset -at which corruption was detected is printed between [ and ], -the requested -.Va length -of the allocation is printed before the / and the -.Va size -of the allocation after the /. -.It Dq recorded size Va oldsize No inconsistent with Va size -.Fn recallocarray -or -.Fn freezero -has detected that the given old size does not match the recorded size in its -meta data. -Enabling option -.Cm C -allows -.Fn recallocarray -to catch more of these cases. -.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 Ev MALLOC_OPTIONS -We found something we didn't understand. -.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 sysctl 2 , -.Xr alloca 3 , -.Xr getpagesize 3 , -.Xr posix_memalign 3 -.Sh STANDARDS -The -.Fn malloc , -.Fn calloc , -.Fn realloc , -and -.Fn free -functions conform to -.St -ansiC . -The -.Fn aligned_alloc -function conforms to -.St -isoC-2011 . -The -.Fn reallocarray -function conforms to -.St -p1003.1-2024 . -.Pp -If -.Fa nmemb -or -.Fa size -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 -.Va vm.malloc_conf -sysctl 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 . -The -.Fn recallocarray -function appeared in -.Ox 6.1 . -The -.Fn freezero -function appeared in -.Ox 6.2 . -The -.Fn aligned_alloc -function appeared in -.Ox 6.5 . -The -.Fn malloc_conceal -and -.Fn calloc_conceal -functions appeared in -.Ox 6.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 , -.Fn reallocarray -or -.Fn recallocarray -instead of using multiplication in -.Fn malloc -and -.Fn realloc -to avoid these problems on -.Ox . -.Pp -The mechanism to record caller functions when using malloc options -.Cm 2 , -.Cm 3 , -or -.Cm 4 -is not guaranteed to work for all platforms, compilers or compilation -options, -and might even crash your program. -Use -.Em only -for debugging purposes. -- cgit v1.2.3-55-g6feb