1 files changed, 118 insertions, 6 deletions

diff --git a/src/lib/libc/stdlib/malloc.3 b/src/lib/libc/stdlib/malloc.3
index c0472ee2b9..49a5b993f4 100644
--- a/src/lib/libc/stdlib/malloc.3
+++ b/src/lib/libc/stdlib/malloc.3
@@ -30,7 +30,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"     $OpenBSD: malloc.3,v 1.120 2018/11/21 06:57:04 otto Exp $
+.\"     $OpenBSD: malloc.3,v 1.121 2018/11/21 09:22:58 jmc Exp $
 .\"
 .Dd $Mdocdate: November 21 2018 $
 .Dt MALLOC 3
@@ -234,6 +234,115 @@ If
 is not a multiple of
 .Fa alignment ,
 behavior is undefined.
+.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.
+.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 statistics to the file
+.Pa ./malloc.out ,
+if it already exists,
+at exit.
+This option requires the library to have been compiled with -DMALLOC_STATS in
+order to have any effect.
+.It Cm F
+.Dq Freecheck .
+Enable more extensive double free and use after free detection.
+All chunks in the delayed free list will be checked for double 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;
+freed chunks are filled with 0xdf.
+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
+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 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 number of free pages cached is 64 per malloc pool.
+Multi-threaded programs use multiple pools.
 .Sh RETURN VALUES
 Upon successful completion, the allocation functions
 return a pointer to the allocated space; otherwise,
@@ -404,8 +513,7 @@ Deallocation of such an object should be done by calling
 .Sh ENVIRONMENT
 .Bl -tag -width "MALLOC_OPTIONS"
 .It Ev MALLOC_OPTIONS
-String of flags documented in
-.Xr malloc.conf 5 .
+String of option flags.
 .El
 .Sh EXAMPLES
 If
@@ -460,6 +568,11 @@ or at the cost of initialization:
 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
@@ -525,11 +638,10 @@ consult sources and/or wizards.
 .Xr brk 2 ,
 .Xr mmap 2 ,
 .Xr munmap 2 ,
+.Xr sysctl 2 ,
 .Xr alloca 3 ,
 .Xr getpagesize 3 ,
-.Xr posix_memalign 3 ,
-.Xr sysconf 3 ,
-.Xr malloc.conf 5
+.Xr posix_memalign 3
 .Sh STANDARDS
 The
 .Fn malloc ,