This commit was manufactured by cvs2git to create tag 'tb_20250414'.tb_20250414

1 files changed, 0 insertions, 860 deletions

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.