share/man/man9/malloc.9

   1 .\"
   2 .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
   3 .\" All rights reserved.
   4 .\"
   5 .\" This code is derived from software contributed to The NetBSD Foundation
   6 .\" by Paul Kranenburg.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  18 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  19 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  20 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
  21 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 .\" POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
  30 .\" $FreeBSD$
  31 .\"
  32 .Dd January 28, 2012
  33 .Dt MALLOC 9
  34 .Os
  35 .Sh NAME
  36 .Nm malloc ,
  37 .Nm free ,
  38 .Nm realloc ,
  39 .Nm reallocf ,
  40 .Nm MALLOC_DEFINE ,
  41 .Nm MALLOC_DECLARE
  42 .Nd kernel memory management routines
  43 .Sh SYNOPSIS
  44 .In sys/types.h
  45 .In sys/malloc.h
  46 .Ft void *
  47 .Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
  48 .Ft void
  49 .Fn free "void *addr" "struct malloc_type *type"
  50 .Ft void *
  51 .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
  52 .Ft void *
  53 .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
  54 .Fn MALLOC_DECLARE type
  55 .In sys/param.h
  56 .In sys/malloc.h
  57 .In sys/kernel.h
  58 .Fn MALLOC_DEFINE type shortdesc longdesc
  59 .Sh DESCRIPTION
  60 The
  61 .Fn malloc
  62 function allocates uninitialized memory in kernel address space for an
  63 object whose size is specified by
  64 .Fa size .
  65 .Pp
  66 The
  67 .Fn free
  68 function releases memory at address
  69 .Fa addr
  70 that was previously allocated by
  71 .Fn malloc
  72 for re-use.
  73 The memory is not zeroed.
  74 If
  75 .Fa addr
  76 is
  77 .Dv NULL ,
  78 then
  79 .Fn free
  80 does nothing.
  81 .Pp
  82 The
  83 .Fn realloc
  84 function changes the size of the previously allocated memory referenced by
  85 .Fa addr
  86 to
  87 .Fa size
  88 bytes.
  89 The contents of the memory are unchanged up to the lesser of the new and
  90 old sizes.
  91 Note that the returned value may differ from
  92 .Fa addr .
  93 If the requested memory cannot be allocated,
  94 .Dv NULL
  95 is returned and the memory referenced by
  96 .Fa addr
  97 is valid and unchanged.
  98 If
  99 .Fa addr
 100 is
 101 .Dv NULL ,
 102 the
 103 .Fn realloc
 104 function behaves identically to
 105 .Fn malloc
 106 for the specified size.
 107 .Pp
 108 The
 109 .Fn reallocf
 110 function is identical to
 111 .Fn realloc
 112 except that it
 113 will free the passed pointer when the requested memory cannot be allocated.
 114 .Pp
 115 Unlike its standard C library counterpart
 116 .Pq Xr malloc 3 ,
 117 the kernel version takes two more arguments.
 118 The
 119 .Fa flags
 120 argument further qualifies
 121 .Fn malloc Ns 's
 122 operational characteristics as follows:
 123 .Bl -tag -width indent
 124 .It Dv M_ZERO
 125 Causes the allocated memory to be set to all zeros.
 126 .It Dv M_NODUMP
 127 For allocations greater than page size, causes the allocated
 128 memory to be excluded from kernel core dumps.
 129 .It Dv M_NOWAIT
 130 Causes
 131 .Fn malloc ,
 132 .Fn realloc ,
 133 and
 134 .Fn reallocf
 135 to return
 136 .Dv NULL
 137 if the request cannot be immediately fulfilled due to resource shortage.
 138 Note that
 139 .Dv M_NOWAIT
 140 is required when running in an interrupt context.
 141 .It Dv M_WAITOK
 142 Indicates that it is OK to wait for resources.
 143 If the request cannot be immediately fulfilled, the current process is put
 144 to sleep to wait for resources to be released by other processes.
 145 The
 146 .Fn malloc ,
 147 .Fn realloc ,
 148 and
 149 .Fn reallocf
 150 functions cannot return
 151 .Dv NULL
 152 if
 153 .Dv M_WAITOK
 154 is specified.
 155 .It Dv M_USE_RESERVE
 156 Indicates that the system can dig into its reserve in order to obtain the
 157 requested memory.
 158 This option used to be called
 159 .Dv M_KERNEL
 160 but has been renamed to something more obvious.
 161 This option has been deprecated and is slowly being removed from the kernel,
 162 and so should not be used with any new programming.
 163 .El
 164 .Pp
 165 Exactly one of either
 166 .Dv M_WAITOK
 167 or
 168 .Dv M_NOWAIT
 169 must be specified.
 170 .Pp
 171 The
 172 .Fa type
 173 argument is used to perform statistics on memory usage, and for
 174 basic sanity checks.
 175 It can be used to identify multiple allocations.
 176 The statistics can be examined by
 177 .Sq vmstat -m .
 178 .Pp
 179 A
 180 .Fa type
 181 is defined using
 182 .Vt "struct malloc_type"
 183 via the
 184 .Fn MALLOC_DECLARE
 185 and
 186 .Fn MALLOC_DEFINE
 187 macros.
 188 .Bd -literal -offset indent
 189 /* sys/something/foo_extern.h */
 190
 191 MALLOC_DECLARE(M_FOOBUF);
 192
 193 /* sys/something/foo_main.c */
 194
 195 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
 196
 197 /* sys/something/foo_subr.c */
 198
 199 \&...
 200 buf = malloc(sizeof *buf, M_FOOBUF, M_NOWAIT);
 201
 202 .Ed
 203 .Pp
 204 In order to use
 205 .Fn MALLOC_DEFINE ,
 206 one must include
 207 .In sys/param.h
 208 (instead of
 209 .In sys/types.h )
 210 and
 211 .In sys/kernel.h .
 212 .Sh IMPLEMENTATION NOTES
 213 The memory allocator allocates memory in chunks that have size a power
 214 of two for requests up to the size of a page of memory.
 215 For larger requests, one or more pages is allocated.
 216 While it should not be relied upon, this information may be useful for
 217 optimizing the efficiency of memory use.
 218 .Pp
 219 Programmers should be careful not to confuse the malloc flags
 220 .Dv M_NOWAIT
 221 and
 222 .Dv M_WAITOK
 223 with the
 224 .Xr mbuf 9
 225 flags
 226 .Dv M_DONTWAIT
 227 and
 228 .Dv M_WAIT .
 229 .Sh CONTEXT
 230 .Fn malloc ,
 231 .Fn realloc
 232 and
 233 .Fn reallocf
 234 may not be called from fast interrupts handlers.
 235 When called from threaded interrupts,
 236 .Fa flags
 237 must contain
 238 .Dv M_NOWAIT .
 239 .Pp
 240 .Fn malloc ,
 241 .Fn realloc
 242 and
 243 .Fn reallocf
 244 may sleep when called with
 245 .Dv M_WAITOK .
 246 .Fn free
 247 never sleeps.
 248 .Pp
 249 Any calls to
 250 .Fn malloc
 251 (even with
 252 .Dv M_NOWAIT )
 253 or
 254 .Fn free
 255 when holding a
 256 .Xr vnode 9
 257 interlock, will cause a LOR (Lock Order Reversal) due to the
 258 intertwining of VM Objects and Vnodes.
 259 .Sh RETURN VALUES
 260 The
 261 .Fn malloc ,
 262 .Fn realloc ,
 263 and
 264 .Fn reallocf
 265 functions return a kernel virtual address that is suitably aligned for
 266 storage of any type of object, or
 267 .Dv NULL
 268 if the request could not be satisfied (implying that
 269 .Dv M_NOWAIT
 270 was set).
 271 .Sh DIAGNOSTICS
 272 A kernel compiled with the
 273 .Dv INVARIANTS
 274 configuration option attempts to detect memory corruption caused by
 275 such things as writing outside the allocated area and imbalanced calls to the
 276 .Fn malloc
 277 and
 278 .Fn free
 279 functions.
 280 Failing consistency checks will cause a panic or a system console
 281 message.
 282 .Sh SEE ALSO
 283 .Xr vmstat 8 ,
 284 .Xr contigmalloc 9 ,
 285 .Xr memguard 9 ,
 286 .Xr vnode 9