From e6c0de236b4644cf7f75c76028e82a7775bfac1d Mon Sep 17 00:00:00 2001 From: Victor Balada Diaz Date: Wed, 18 Oct 2006 21:30:06 +0000 Subject: [PATCH] update man page: malloc - kmalloc free - kfree realloc - krealloc reallocf - no longer in tree, deleted --- share/man/man9/Makefile | 5 ++-- share/man/man9/kmalloc.9 | 65 ++++++++++++++++------------------------ share/man/man9/malloc.9 | 65 ++++++++++++++++------------------------ 3 files changed, 55 insertions(+), 80 deletions(-) diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 0f3b026ef7..6eaad7e3b3 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -1,5 +1,5 @@ # $FreeBSD: src/share/man/man9/Makefile,v 1.60.2.26 2003/06/13 01:04:17 hmp Exp $ -# $DragonFly: src/share/man/man9/Makefile,v 1.32 2006/07/05 18:32:20 swildner Exp $ +# $DragonFly: src/share/man/man9/Makefile,v 1.33 2006/10/18 21:30:06 victor Exp $ MAN= DECLARE_MODULE.9 DELAY.9 DEV_MODULE.9 KASSERT.9 MD5.9 \ MODULE_DEPEND.9 MODULE_VERSION.9 SYSCALL_MODULE.9 \ @@ -165,7 +165,8 @@ MLINKS+=kobj.9 kobj_delete.9 MLINKS+=kobj.9 kobj_init.9 MLINKS+=make_dev.9 destroy_dev.9 MLINKS+=malloc.9 FREE.9 malloc.9 MALLOC.9 malloc.9 free.9 -MLINKS+=malloc.9 realloc.9 malloc.9 reallocf.9 +MLINKS+=malloc.9 kmalloc.9 malloc.9 kfree.9 +MLINKS+=malloc.9 krealloc.9 malloc.9 realloc.9 MLINKS+=malloc.9 MALLOC_DEFINE.9 malloc.9 MALLOC_DECLARE.9 MLINKS+=mi_switch.9 cpu_switch.9 MLINKS+=pci.9 pci_read_config.9 pci.9 pci_write_config.9 diff --git a/share/man/man9/kmalloc.9 b/share/man/man9/kmalloc.9 index bb85d988fe..994f7ce96e 100644 --- a/share/man/man9/kmalloc.9 +++ b/share/man/man9/kmalloc.9 @@ -35,18 +35,17 @@ .\" .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ .\" $FreeBSD: src/share/man/man9/malloc.9,v 1.42 2005/02/22 17:20:20 brueffer Exp $ -.\" $DragonFly: src/share/man/man9/kmalloc.9,v 1.5 2005/12/27 22:45:23 swildner Exp $ +.\" $DragonFly: src/share/man/man9/kmalloc.9,v 1.6 2006/10/18 21:30:06 victor Exp $ .\" .Dd June 12, 2003 .Dt MALLOC 9 .Os .Sh NAME -.Nm malloc , +.Nm kmalloc , .Nm MALLOC , -.Nm free , +.Nm kfree , .Nm FREE , -.Nm realloc , -.Nm reallocf , +.Nm krealloc , .Nm MALLOC_DEFINE , .Nm MALLOC_DECLARE .Nd kernel memory management routines @@ -54,15 +53,13 @@ .In sys/types.h .In sys/malloc.h .Ft void * -.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" +.Fn kmalloc "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 kfree "void *addr" "struct malloc_type *type" .Fn FREE "void *addr" "struct malloc_type *type" .Ft void * -.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 krealloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" .Fn MALLOC_DECLARE type .In sys/param.h .In sys/malloc.h @@ -70,28 +67,28 @@ .Fn MALLOC_DEFINE type shortdesc longdesc .Sh DESCRIPTION The -.Fn malloc +.Fn kmalloc function allocates uninitialized memory in kernel address space for an object whose size is specified by .Fa size . .Pp The -.Fn free +.Fn kfree function releases memory at address .Fa addr that was previously allocated by -.Fn malloc +.Fn kmalloc for re-use. The memory is not zeroed. The kernel implementation of -.Fn free +.Fn kfree does not allow .Fa addr to be .Dv NULL . .Pp The -.Fn realloc +.Fn krealloc function changes the size of the previously allocated memory referenced by .Fa addr to @@ -111,30 +108,23 @@ If is .Dv NULL , the -.Fn realloc +.Fn krealloc function behaves identically to -.Fn malloc +.Fn kmalloc for the specified size. .Pp The -.Fn reallocf -function is identical to -.Fn realloc -except that it -will free the passed pointer when the requested memory cannot be allocated. -.Pp -The .Fn MALLOC macro variant is functionally equivalent to .Bd -literal -offset indent -(space) = (cast)malloc((u_long)(size), type, flags) +(space) = (cast)kmalloc((u_long)(size), type, flags) .Ed .Pp and the .Fn FREE macro variant is equivalent to .Bd -literal -offset indent -free((addr), type) +kfree((addr), type) .Ed .Pp Unlike its standard C library counterpart @@ -143,17 +133,16 @@ the kernel version takes two more arguments. The .Fa flags argument further qualifies -.Fn malloc Ns 's +.Fn kmalloc 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 , +.Fn kmalloc and -.Fn reallocf +.Fn krealloc , to return .Dv NULL if the request cannot be immediately fulfilled due to resource shortage. @@ -165,10 +154,9 @@ 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 , +.Fn kmalloc and -.Fn reallocf +.Fn krealloc , functions cannot return .Dv NULL if @@ -181,7 +169,7 @@ 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. +and so should not be used with any new code. .El .Pp Exactly one of either @@ -230,10 +218,9 @@ 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 , +.Fn kmalloc and -.Fn reallocf +.Fn krealloc , functions return a kernel virtual address that is suitably aligned for storage of any type of object, or .Dv NULL @@ -245,9 +232,9 @@ A kernel compiled with the .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 +.Fn kmalloc and -.Fn free +.Fn kfree functions. Failing consistency checks will cause a panic or a system console message. diff --git a/share/man/man9/malloc.9 b/share/man/man9/malloc.9 index 817657bbe4..a66426bf04 100644 --- a/share/man/man9/malloc.9 +++ b/share/man/man9/malloc.9 @@ -35,18 +35,17 @@ .\" .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $ .\" $FreeBSD: src/share/man/man9/malloc.9,v 1.42 2005/02/22 17:20:20 brueffer Exp $ -.\" $DragonFly: src/share/man/man9/Attic/malloc.9,v 1.5 2005/12/27 22:45:23 swildner Exp $ +.\" $DragonFly: src/share/man/man9/Attic/malloc.9,v 1.6 2006/10/18 21:30:06 victor Exp $ .\" .Dd June 12, 2003 .Dt MALLOC 9 .Os .Sh NAME -.Nm malloc , +.Nm kmalloc , .Nm MALLOC , -.Nm free , +.Nm kfree , .Nm FREE , -.Nm realloc , -.Nm reallocf , +.Nm krealloc , .Nm MALLOC_DEFINE , .Nm MALLOC_DECLARE .Nd kernel memory management routines @@ -54,15 +53,13 @@ .In sys/types.h .In sys/malloc.h .Ft void * -.Fn malloc "unsigned long size" "struct malloc_type *type" "int flags" +.Fn kmalloc "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 kfree "void *addr" "struct malloc_type *type" .Fn FREE "void *addr" "struct malloc_type *type" .Ft void * -.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 krealloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags" .Fn MALLOC_DECLARE type .In sys/param.h .In sys/malloc.h @@ -70,28 +67,28 @@ .Fn MALLOC_DEFINE type shortdesc longdesc .Sh DESCRIPTION The -.Fn malloc +.Fn kmalloc function allocates uninitialized memory in kernel address space for an object whose size is specified by .Fa size . .Pp The -.Fn free +.Fn kfree function releases memory at address .Fa addr that was previously allocated by -.Fn malloc +.Fn kmalloc for re-use. The memory is not zeroed. The kernel implementation of -.Fn free +.Fn kfree does not allow .Fa addr to be .Dv NULL . .Pp The -.Fn realloc +.Fn krealloc function changes the size of the previously allocated memory referenced by .Fa addr to @@ -111,30 +108,23 @@ If is .Dv NULL , the -.Fn realloc +.Fn krealloc function behaves identically to -.Fn malloc +.Fn kmalloc for the specified size. .Pp The -.Fn reallocf -function is identical to -.Fn realloc -except that it -will free the passed pointer when the requested memory cannot be allocated. -.Pp -The .Fn MALLOC macro variant is functionally equivalent to .Bd -literal -offset indent -(space) = (cast)malloc((u_long)(size), type, flags) +(space) = (cast)kmalloc((u_long)(size), type, flags) .Ed .Pp and the .Fn FREE macro variant is equivalent to .Bd -literal -offset indent -free((addr), type) +kfree((addr), type) .Ed .Pp Unlike its standard C library counterpart @@ -143,17 +133,16 @@ the kernel version takes two more arguments. The .Fa flags argument further qualifies -.Fn malloc Ns 's +.Fn kmalloc 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 , +.Fn kmalloc and -.Fn reallocf +.Fn krealloc , to return .Dv NULL if the request cannot be immediately fulfilled due to resource shortage. @@ -165,10 +154,9 @@ 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 , +.Fn kmalloc and -.Fn reallocf +.Fn krealloc , functions cannot return .Dv NULL if @@ -181,7 +169,7 @@ 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. +and so should not be used with any new code. .El .Pp Exactly one of either @@ -230,10 +218,9 @@ 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 , +.Fn kmalloc and -.Fn reallocf +.Fn krealloc , functions return a kernel virtual address that is suitably aligned for storage of any type of object, or .Dv NULL @@ -245,9 +232,9 @@ A kernel compiled with the .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 +.Fn kmalloc and -.Fn free +.Fn kfree functions. Failing consistency checks will cause a panic or a system console message. -- 2.41.0