👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

NetBSD 6.1.5 - man page for malloc_roundup (netbsd section 9)

MALLOC(9)			  BSD Kernel Developer's Manual 			MALLOC(9)

NAME
     malloc, MALLOC, realloc, free, FREE, malloc_roundup, malloc_type_attach, malloc_type_detach,
     malloc_type_setlimit, MALLOC_DEFINE_LIMIT, MALLOC_DEFINE, MALLOC_DECLARE -- general-purpose
     kernel memory allocator

SYNOPSIS
     #include <sys/malloc.h>

     void *
     malloc(unsigned long size, struct malloc_type *type, int flags);

     void *
     realloc(void *addr, unsigned long newsize, struct malloc_type *type, int flags);

     void
     free(void *addr, struct malloc_type *type);

     unsigned long
     malloc_roundup(unsigned long size);

     void
     malloc_type_attach(struct malloc_type *type);

     void
     malloc_type_detach(struct malloc_type *type);

     void
     malloc_type_setlimit(struct malloc_type *type, unsigned long limit);

     #include <sys/mallocvar.h>

     MALLOC_DEFINE_LIMIT(type, shortdesc, longdesc, limit);

     MALLOC_JUSTDEFINE_LIMIT(type, shortdesc, longdesc, limit);

     MALLOC_DEFINE(type, shortdesc, longdesc);

     MALLOC_JUSTDEFINE(type, shortdesc, longdesc);

     MALLOC_DECLARE(type);

DESCRIPTION
     These interfaces are being obsoleted and their new use is discouraged.  For new code, use
     kmem(9) or pool_cache(9) instead.

     The malloc() function allocates uninitialized memory in kernel address space for an object
     whose size is specified by size.  malloc_roundup() returns the actual size of the allocation
     unit for the given value.	free() releases memory at address addr that was previously allo-
     cated by malloc() for re-use.  Unlike free(3), free() does not accept an addr argument that
     is NULL.

     The realloc() function changes the size of the previously allocated memory referenced by
     addr to size and returns a pointer to the (possibly moved) object.  The memory contents are
     unchanged up to the lesser of the new and old sizes.  If the new size is larger, the newly
     allocated memory is uninitialized.  If the requested memory cannot be allocated, NULL is
     returned and the memory referenced by addr is unchanged.  If addr is NULL, then realloc()
     behaves exactly as malloc().  If the new size is 0, then realloc() behaves exactly as
     free().

     Unlike its standard C library counterpart (malloc(3)), the kernel version takes two more
     arguments.

     The flags argument further qualifies malloc() operational characteristics as follows:

	   M_NOWAIT   Causes malloc() to return NULL if the request cannot be immediately ful-
		      filled due to resource shortage.	If this flag is not set (see M_WAITOK),
		      malloc() will never return NULL.

	   M_WAITOK   By default, malloc() may call cv_wait(9) to wait for resources to be
		      released by other processes, and this flag represents this behaviour.  Note
		      that M_WAITOK is conveniently defined to be 0, and hence may be or'ed into
		      the flags argument to indicate that it's ok to wait for resources.

	   M_ZERO     Causes the allocated memory to be set to all zeros.

	   M_CANFAIL  Changes behaviour for M_WAITOK case - if the requested memory size is big-
		      ger than malloc() can ever allocate, return failure, rather than calling
		      panic(9).  This is different to M_NOWAIT, since the call can still wait for
		      resources.

		      Rather than depending on M_CANFAIL, kernel code should do proper bound
		      checking itself.	This flag should only be used in cases where this is not
		      feasible.  Since it can hide real kernel bugs, its usage is strongly
		      discouraged.

     The type argument describes the subsystem and/or use within a subsystem for which the allo-
     cated memory was needed, and is commonly used to maintain statistics about kernel memory
     usage and, optionally, enforce limits on this usage for certain memory types.

     In addition to some built-in generic types defined by the kernel memory allocator, subsys-
     tems may define their own types.

     The MALLOC_DEFINE_LIMIT() macro defines a malloc type named type with the short description
     shortdesc, which must be a constant string; this description will be used for kernel memory
     statistics reporting.  The longdesc argument, also a constant string, is intended as way to
     place a comment in the actual type definition, and is not currently stored in the type
     structure.  The limit argument specifies the maximum amount of memory, in bytes, that this
     malloc type can consume.

     The MALLOC_DEFINE() macro is equivalent to the MALLOC_DEFINE_LIMIT() macro with a limit
     argument of 0.  If kernel memory statistics are being gathered, the system will choose a
     reasonable default limit for the malloc type.

     The MALLOC_DECLARE() macro is intended for use in header files which are included by code
     which needs to use the malloc type, providing the necessary extern declaration.

     Code which includes <sys/malloc.h> does not need to include <sys/mallocvar.h> to get these
     macro definitions.  The <sys/mallocvar.h> header file is intended for other header files
     which need to use the MALLOC_DECLARE() macro.

     The malloc_type_attach() function attaches the malloc type type to the kernel memory alloca-
     tor.

     The malloc_type_detach() function detaches the malloc type type previously attached with
     malloc_type_attach().

     The malloc_type_setlimit() function sets the memory limit of the malloc type type to limit
     bytes.  The type must already be registered with the kernel memory allocator.

     The following generic malloc types are currently defined:

	   M_DEVBUF	   Device driver memory.
	   M_DMAMAP	   bus_dma(9) structures.
	   M_FREE	   Should be on free list.
	   M_PCB	   Protocol control block.
	   M_SOFTINTR	   Softinterrupt structures.
	   M_TEMP	   Misc temporary data buffers.

     Other malloc types are defined by the corresponding subsystem; see the documentation for
     that subsystem for information its available malloc types.

     Statistics based on the type argument are maintained only if the kernel option KMEMSTATS is
     used when compiling the kernel (the default in current NetBSD kernels) and can be examined
     by using 'vmstat -m'.

RETURN VALUES
     malloc() returns a kernel virtual address that is suitably aligned for storage of any type
     of object.

DIAGNOSTICS
     A kernel compiled with the DIAGNOSTIC configuration option attempts to detect memory corrup-
     tion caused by such things as writing outside the allocated area and imbalanced calls to the
     malloc() and free() functions.  Failing consistency checks will cause a panic or a system
     console message:

	   o   panic: ``malloc - bogus type''
	   o   panic: ``malloc: out of space in kmem_map''
	   o   panic: ``malloc: allocation too large''
	   o   panic: ``malloc: wrong bucket''
	   o   panic: ``malloc: lost data''
	   o   panic: ``free: unaligned addr''
	   o   panic: ``free: duplicated free''
	   o   panic: ``free: multiple frees''
	   o   panic: ``init: minbucket too small/struct freelist too big''
	   o   ``multiply freed item <addr>''
	   o   ``Data modified on freelist: <data object description>''

SEE ALSO
     vmstat(1), memoryallocators(9)

BSD					December 29, 2008				      BSD


All times are GMT -4. The time now is 06:54 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password