1.\" Copyright (c) 2005 Christian Brueffer 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd August 2, 2010 28.Dt MEMGUARD 9 29.Os 30.Sh NAME 31.Nm MemGuard 32.Nd "memory allocator for debugging purposes" 33.Sh SYNOPSIS 34.Cd "options DEBUG_MEMGUARD" 35.Sh DESCRIPTION 36.Nm 37is a simple and small replacement memory allocator designed 38to help detect tamper-after-free scenarios. 39These problems are more and more common and likely with 40multithreaded kernels where race conditions are more prevalent. 41.Pp 42Currently, 43.Nm 44can take over 45.Fn malloc , 46.Fn realloc 47and 48.Fn free 49for a single malloc type. 50.Nm 51can also guard all allocations larger than 52.Dv PAGE_SIZE , 53and can guard a random fraction of all allocations. 54There is also a knob to prevent allocations smaller than a specified 55size from being guarded, to limit memory waste. 56.Sh EXAMPLES 57To use 58.Nm 59for a memory type, either add an entry to 60.Pa /boot/loader.conf : 61.Bd -literal -offset indent 62vm.memguard.desc=<memory_type> 63.Ed 64.Pp 65Or set the 66.Va vm.memguard.desc 67.Xr sysctl 8 68variable at run-time: 69.Bd -literal -offset indent 70sysctl vm.memguard.desc=<memory_type> 71.Ed 72.Pp 73Where 74.Ar memory_type 75is a short description of the memory type to monitor. 76Only allocations from that 77.Ar memory_type 78made after 79.Va vm.memguard.desc 80is set will potentially be guarded. 81If 82.Va vm.memguard.desc 83is modified at run-time then only allocations of the new 84.Ar memory_type 85will potentially be guarded once the 86.Xr sysctl 8 87is set. 88Existing guarded allocations will still be properly released by 89.Xr free 9 . 90.Pp 91The short description of a 92.Xr malloc 9 93type is the second argument to 94.Xr MALLOC_DEFINE 9 , 95so one has to find it in the kernel source. 96.Pp 97The 98.Va vm.memguard.divisor 99boot-time tunable is used to scale how much of the system's physical 100memory 101.Nm 102is allowed to consume. 103The default is 10, so up to 104.Va cnt.v_page_count Ns /10 105pages can be used. 106.Nm 107will reserve 108.Va vm_kmem_max 109/ 110.Va vm.memguard.divisor 111bytes of virtual address space, limited by twice the physical memory 112size. 113The physical limit is reported as 114.Va vm.memguard.phys_limit 115and the virtual space reserved for 116.Nm 117is reported as 118.Va vm.memguard.mapsize . 119.Pp 120.Nm 121will not do page promotions for any allocation smaller than 122.Va vm.memguard.minsize 123bytes. 124The default is 0, meaning all allocations can potentially be guarded. 125.Nm 126can guard sufficiently large allocations randomly, with average 127frequency of every one in 100000 / 128.Va vm.memguard.frequency 129allocations. 130The default is 0, meaning no allocations are randomly guarded. 131.Pp 132.Nm 133can optionally add unmapped guard pages around each allocation to 134detect overflow and underflow, if 135.Va vm.memguard.options 136has the 1 bit set. 137This option is enabled by default. 138.Nm 139will optionally guard all allocations of 140.Dv PAGE_SIZE 141or larger if 142.Va vm.memguard.options 143has the 2 bit set. 144This option is off by default. 145.Sh SEE ALSO 146.Xr sysctl 8 , 147.Xr vmstat 8 , 148.Xr contigmalloc 9 , 149.Xr malloc 9 , 150.Xr redzone 9 151.Sh HISTORY 152.Nm 153first appeared in 154.Fx 6.0 . 155.Sh AUTHORS 156.An -nosplit 157.Nm 158was originally written by 159.An Bosko Milekic Aq bmilekic@FreeBSD.org . 160This manual page was originally written by 161.An Christian Brueffer Aq brueffer@FreeBSD.org . 162Additions have been made by 163.An Matthew Fleming Aq mdf@FreeBSD.org 164to both the implementation and the documentation. 165.Sh BUGS 166Currently, it is not possible to override UMA 167.Xr zone 9 168allocations. 169