--- src/share/man/man9/Attic/malloc.9	2005/08/01 01:49:17	1.4
+++ src/share/man/man9/Attic/malloc.9	2006/01/01 00:53:28	1.4.2.1
@@ -34,24 +34,28 @@
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
 .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
-.\" $FreeBSD: src/share/man/man9/malloc.9,v 1.13.2.6 2002/03/16 02:20:28 archie Exp $
+.\" $FreeBSD: src/share/man/man9/malloc.9,v 1.42 2005/02/22 17:20:20 brueffer Exp $
 .\" $DragonFly$
 .\"
-.Dd June 16, 1996
+.Dd June 12, 2003
 .Dt MALLOC 9
 .Os
 .Sh NAME
 .Nm malloc ,
 .Nm MALLOC ,
 .Nm free ,
-.Nm FREE
+.Nm FREE ,
+.Nm realloc ,
+.Nm reallocf ,
+.Nm MALLOC_DEFINE ,
+.Nm MALLOC_DECLARE
 .Nd kernel memory management routines
 .Sh SYNOPSIS
 .In sys/types.h
 .In sys/malloc.h
 .Ft void *
 .Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
-.Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type  *type" "int flags"
+.Fn MALLOC space cast "unsigned long size" "struct malloc_type *type" "int flags"
 .Ft void
 .Fn free "void *addr" "struct malloc_type *type"
 .Fn FREE "void *addr" "struct malloc_type *type"
@@ -59,6 +63,11 @@
 .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
 .Ft void *
 .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
+.Fn MALLOC_DECLARE type
+.In sys/param.h
+.In sys/malloc.h
+.In sys/kernel.h
+.Fn MALLOC_DEFINE type shortdesc longdesc
 .Sh DESCRIPTION
 The
 .Fn malloc
@@ -66,8 +75,9 @@ function allocates uninitialized memory
 object whose size is specified by
 .Fa size .
 .Pp
+The
 .Fn free
-releases memory at address
+function releases memory at address
 .Fa addr
 that was previously allocated by
 .Fn malloc
@@ -108,7 +118,9 @@ for the specified size.
 .Pp
 The
 .Fn reallocf
-function call is identical to the realloc function call, except that it
+function is identical to
+.Fn realloc
+except that it
 will free the passed pointer when the requested memory cannot be allocated.
 .Pp
 The
@@ -127,80 +139,62 @@ free((addr), type)
 .Pp
 Unlike its standard C library counterpart
 .Pq Xr malloc 3 ,
-the kernel version takes two more arguments.  The
+the kernel version takes two more arguments.
+The
 .Fa flags
 argument further qualifies
 .Fn malloc Ns 's
 operational characteristics as follows:
 .Bl -tag -width indent
+.It Dv M_ZERO
+Causes the allocated memory to be set to all zeros.
 .It Dv M_NOWAIT
 Causes
 .Fn malloc ,
 .Fn realloc ,
-or
+and
 .Fn reallocf
 to return
 .Dv NULL
 if the request cannot be immediately fulfilled due to resource shortage.
-Otherwise, the current process may be put to sleep to wait for
-resources to be released by other processes.
-If this flag is set,
-.Fn malloc
-will return
-.Dv NULL
-rather then block.
 Note that
-.Dv M_WAITOK
-is defined to be 0, meaning that blocking operation is the default.
-Also note that
 .Dv M_NOWAIT
 is required when running in an interrupt context.
-.It Dv M_ASLEEP
-Causes
-.Fn malloc ,
-.Fn realloc ,
-or
-.Fn reallocf
-to call
-.Fn asleep
-if the request cannot be immediately fulfilled due to a resource shortage.
-M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow
-the function to call
-.Fn asleep
-and return
-.Dv NULL
-immediately.  It is expected that the caller will at some point call
-.Fn await
-and then retry the allocation.  Depending on the routine in question, the
-caller may decide to propagate the temporary failure up the call chain
-and actually have some other higher level routine block on the async wait
-that the function queued.
 .It Dv M_WAITOK
-Indicates that it is Ok to wait for resources.  It is unconveniently
-defined as 0 so care should be taken never to compare against this value
-directly or try to AND it as a flag.  The default operation is to block
-until the memory allocation succeeds.
+Indicates that it is OK to wait for resources.
+If the request cannot be immediately fulfilled, the current process is put
+to sleep to wait for resources to be released by other processes.
+The
 .Fn malloc ,
 .Fn realloc ,
 and
 .Fn reallocf
-can only return
+functions cannot return
 .Dv NULL
 if
-.Dv M_NOWAIT
+.Dv M_WAITOK
 is specified.
 .It Dv M_USE_RESERVE
 Indicates that the system can dig into its reserve in order to obtain the
-requested memory.  This option used to be called M_KERNEL but has been
-renamed to something more obvious.  This option has been deprecated and is
-slowly being removed from the kernel, and so should not be used with any new
-programming.
+requested memory.
+This option used to be called
+.Dv M_KERNEL
+but has been renamed to something more obvious.
+This option has been deprecated and is slowly being removed from the kernel,
+and so should not be used with any new programming.
 .El
 .Pp
+Exactly one of either
+.Dv M_WAITOK
+or
+.Dv M_NOWAIT
+must be specified.
+.Pp
 The
 .Fa type
 argument is used to perform statistics on memory usage, and for
 basic sanity checks.
+It can be used to identify multiple allocations.
 The statistics can be examined by
 .Sq vmstat -m .
 .Pp
@@ -228,35 +222,27 @@ MALLOC_DEFINE(M_FOOBUF, "foobuffers", "B
 MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
 
 .Ed
+.Sh IMPLEMENTATION NOTES
+The memory allocator allocates memory in chunks that have size a power
+of two for requests up to the size of a page of memory.
+For larger requests, one or more pages is allocated.
+While it should not be relied upon, this information may be useful for
+optimizing the efficiency of memory use.
 .Sh RETURN VALUES
+The
 .Fn malloc ,
 .Fn realloc ,
 and
 .Fn reallocf
-return a kernel virtual address that is suitably aligned for storage of
-any type of object, or
+functions return a kernel virtual address that is suitably aligned for
+storage of any type of object, or
 .Dv NULL
 if the request could not be satisfied (implying that
 .Dv M_NOWAIT
 was set).
-If
-.Dv M_ASLEEP
-was set and the function returns
-.Dv NULL ,
-it will call
-.Fn asleep
-as a side effect.
-.Sh IMPLEMENTATION NOTES
-The memory allocator allocates memory in chunks that have size a power
-of two for requests up to the size of a page of memory.
-For larger requests, one or more pages is allocated.
-While it should not be relied upon, this information may be useful for
-optimizing the efficiency of memory use.
-.Sh SEE ALSO
-.Xr vmstat 8
 .Sh DIAGNOSTICS
 A kernel compiled with the
-.Dv DIAGNOSTIC
+.Dv INVARIANTS
 configuration option attempts to detect memory corruption caused by
 such things as writing outside the allocated area and imbalanced calls to the
 .Fn malloc
@@ -264,36 +250,7 @@ and
 .Fn free
 functions.
 Failing consistency checks will cause a panic or a system console
-message:
-.Bl -bullet -offset indent -compact
-.Pp
-.It
-panic:
-.Dq malloc: bogus type
-.It
-panic:
-.Dq malloc: allocation too large
-.It
-panic:
-.Dq malloc: wrong bucket
-.It
-panic:
-.Dq malloc: lost data
-.It
-panic:
-.Dq free: address 0x%x out of range
-.It
-panic:
-.Dq free: type %d out of range
-.It
-panic:
-.Dq free: unaligned addr Aq description of object
-.It
-panic:
-.Dq free: item modified
-.It
-panic:
-.Dq free: multiple free[s]
-.It
-.Dq Data modified on freelist: Aq description of object
-.El
+message.
+.Sh SEE ALSO
+.Xr vmstat 8 ,
+.Xr vnode 9