/share/man/man9/malloc.9
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 286 lines · 280 code · 6 blank · 0 comment · 0 complexity · 9eba2447c53f83c96695b1d13cbf00af MD5 · raw file
- .\"
- .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
- .\" All rights reserved.
- .\"
- .\" This code is derived from software contributed to The NetBSD Foundation
- .\" by Paul Kranenburg.
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
- .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
- .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
- .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
- .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
- .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
- .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
- .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
- .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
- .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
- .\" POSSIBILITY OF SUCH DAMAGE.
- .\"
- .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
- .\" $FreeBSD$
- .\"
- .Dd January 28, 2012
- .Dt MALLOC 9
- .Os
- .Sh NAME
- .Nm malloc ,
- .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"
- .Ft void
- .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 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
- function allocates uninitialized memory in kernel address space for an
- object whose size is specified by
- .Fa size .
- .Pp
- The
- .Fn free
- function releases memory at address
- .Fa addr
- that was previously allocated by
- .Fn malloc
- for re-use.
- The memory is not zeroed.
- If
- .Fa addr
- is
- .Dv NULL ,
- then
- .Fn free
- does nothing.
- .Pp
- The
- .Fn realloc
- function changes the size of the previously allocated memory referenced by
- .Fa addr
- to
- .Fa size
- bytes.
- The contents of the memory are unchanged up to the lesser of the new and
- old sizes.
- Note that the returned value may differ from
- .Fa addr .
- If the requested memory cannot be allocated,
- .Dv NULL
- is returned and the memory referenced by
- .Fa addr
- is valid and unchanged.
- If
- .Fa addr
- is
- .Dv NULL ,
- the
- .Fn realloc
- function behaves identically to
- .Fn malloc
- 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
- Unlike its standard C library counterpart
- .Pq Xr malloc 3 ,
- 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_NODUMP
- For allocations greater than page size, causes the allocated
- memory to be excluded from kernel core dumps.
- .It Dv M_NOWAIT
- Causes
- .Fn malloc ,
- .Fn realloc ,
- and
- .Fn reallocf
- to return
- .Dv NULL
- if the request cannot be immediately fulfilled due to resource shortage.
- Note that
- .Dv M_NOWAIT
- is required when running in an interrupt context.
- .It Dv M_WAITOK
- 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
- functions cannot return
- .Dv NULL
- if
- .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
- .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
- A
- .Fa type
- is defined using
- .Vt "struct malloc_type"
- via the
- .Fn MALLOC_DECLARE
- and
- .Fn MALLOC_DEFINE
- macros.
- .Bd -literal -offset indent
- /* sys/something/foo_extern.h */
- MALLOC_DECLARE(M_FOOBUF);
- /* sys/something/foo_main.c */
- MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
- /* sys/something/foo_subr.c */
- \&...
- buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT);
- .Ed
- .Pp
- In order to use
- .Fn MALLOC_DEFINE ,
- one must include
- .In sys/param.h
- (instead of
- .In sys/types.h )
- and
- .In sys/kernel.h .
- .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.
- .Pp
- Programmers should be careful not to confuse the malloc flags
- .Dv M_NOWAIT
- and
- .Dv M_WAITOK
- with the
- .Xr mbuf 9
- flags
- .Dv M_DONTWAIT
- and
- .Dv M_WAIT .
- .Sh CONTEXT
- .Fn malloc ,
- .Fn realloc
- and
- .Fn reallocf
- may not be called from fast interrupts handlers.
- When called from threaded interrupts,
- .Fa flags
- must contain
- .Dv M_NOWAIT .
- .Pp
- .Fn malloc ,
- .Fn realloc
- and
- .Fn reallocf
- may sleep when called with
- .Dv M_WAITOK .
- .Fn free
- never sleeps.
- .Pp
- Any calls to
- .Fn malloc
- (even with
- .Dv M_NOWAIT )
- or
- .Fn free
- when holding a
- .Xr vnode 9
- interlock, will cause a LOR (Lock Order Reversal) due to the
- intertwining of VM Objects and Vnodes.
- .Sh RETURN VALUES
- The
- .Fn malloc ,
- .Fn realloc ,
- and
- .Fn reallocf
- 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).
- .Sh DIAGNOSTICS
- 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
- and
- .Fn free
- functions.
- Failing consistency checks will cause a panic or a system console
- message.
- .Sh SEE ALSO
- .Xr vmstat 8 ,
- .Xr contigmalloc 9 ,
- .Xr memguard 9 ,
- .Xr vnode 9