malloc(3) is in the "comp" install set, malloc.conf(5) in "man",

breaking the hardlink between file system entries, confusing apropos(1).
Split malloc.conf(5) out of malloc(3) as suggested by deraadt@.
Feedback and OK jmc@, OK deraadt@ tedu@ jasper@.

1 files changed, 8 insertions, 126 deletions

diff --git a/lib/libc/stdlib/malloc.3 b/lib/libc/stdlib/malloc.3
index 3ce9d2e28ca..153fd54dbd6 100644
--- a/lib/libc/stdlib/malloc.3
+++ b/lib/libc/stdlib/malloc.3
@@ -30,9 +30,9 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.\"	$OpenBSD: malloc.3,v 1.85 2014/10/30 21:47:47 deraadt Exp $
+.\"	$OpenBSD: malloc.3,v 1.86 2014/12/06 18:54:55 schwarze Exp $
 .\"
-.Dd $Mdocdate: October 30 2014 $
+.Dd $Mdocdate: December 6 2014 $
 .Dt MALLOC 3
 .Os
 .Sh NAME
@@ -285,14 +285,15 @@ Use the following:
 newp = realloc(p, newsize);
 .Ed
 .Sh ENVIRONMENT
-.Bl -tag -width Ev
+.Bl -tag -width "/etc/malloc.conf"
 .It Ev MALLOC_OPTIONS
-See below.
+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
+Symbolic link to filename containing option flags.
 .El
 .Sh EXAMPLES
 If
@@ -420,126 +421,6 @@ An inconsistent guard size was detected.
 detected an internal error;
 consult sources and/or wizards.
 .El
-.Sh MALLOC_OPTIONS
-Malloc will first look for a symbolic link called
-.Pa /etc/malloc.conf
-and next check the environment for a variable called
-.Ev MALLOC_OPTIONS
-and finally for the global variable
-.Va malloc_options
-and scan them for flags in that order.
-Flags are single letters, uppercase means on, lowercase means off.
-.Bl -tag -width indent
-.It Cm A
-.Dq Abort .
-.Fn malloc
-will coredump the process, rather than tolerate internal
-inconsistencies or incorrect usage.
-This is the default and a very handy debugging aid,
-since the core file represents the time of failure,
-rather than when the bogus pointer was used.
-.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 Freeguard .
-Enable use after free detection.
-Unused pages on the freelist are read and write protected to
-cause a segmentation fault upon access.
-This will also switch off the delayed freeing of chunks,
-reducing random behaviour but detecting double
-.Fn free
-calls as early as possible.
-This option is intended for debugging rather than improved security
-(use the
-.Cm U
-option for security).
-.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 H
-.Dq Hint .
-Pass a hint to the kernel about pages we don't use.
-If the machine is paging a lot this may help a bit.
-.It Cm J
-.Dq Junk .
-Fill some junk into the area allocated.
-Currently junk is bytes of 0xd0 when allocating; this is pronounced
-.Dq Duh .
-\&:-)
-Freed chunks are filled with 0xdf.
-.It Cm j
-.Dq Don't Junk .
-By default, small chunks are always junked, and the first part of pages
-is junked after free.
-This option ensures that no junking is performed.
-.It Cm P
-.Dq Move allocations within a page.
-Allocations larger than half a page but smaller than a page
-are aligned to the end of a page to catch buffer overruns in more
-cases.
-This is the default.
-.It Cm R
-.Dq realloc .
-Always reallocate when
-.Fn realloc
-is called, even if the initial allocation was big enough.
-This can substantially aid in compacting memory.
-.\".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 Half 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
-So to set a systemwide reduction of the cache to a quarter of the
-default size and use guard pages:
-.Dl # ln -s 'G<<' /etc/malloc.conf
-.Pp
-The flags are mostly for testing and debugging.
-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.
 .Sh SEE ALSO
 .Xr brk 2 ,
 .Xr mmap 2 ,
@@ -547,7 +428,8 @@ The default number of free pages cached is 64.
 .Xr alloca 3 ,
 .Xr getpagesize 3 ,
 .Xr posix_memalign 3 ,
-.Xr sysconf 3
+.Xr sysconf 3 ,
+.Xr malloc.conf 5
 .Sh STANDARDS
 The
 .Fn malloc ,