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 August 3, 2020
  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 "size_t size" "struct malloc_type *type" "int flags"
  48 .Ft void *
  49 .Fn mallocarray "size_t nmemb" "size_t size" "struct malloc_type *type" "int flags"
  50 .Ft void
  51 .Fn free "void *addr" "struct malloc_type *type"
  52 .Ft void
  53 .Fn zfree "void *addr" "struct malloc_type *type"
  54 .Ft void *
  55 .Fn realloc "void *addr" "size_t size" "struct malloc_type *type" "int flags"
  56 .Ft void *
  57 .Fn reallocf "void *addr" "size_t size" "struct malloc_type *type" "int flags"
  58 .Fn MALLOC_DECLARE type
  59 .In sys/param.h
  60 .In sys/malloc.h
  61 .In sys/kernel.h
  62 .Fn MALLOC_DEFINE type shortdesc longdesc
  63 .In sys/param.h
  64 .In sys/domainset.h
  65 .Ft void *
  66 .Fn malloc_domainset "size_t size" "struct malloc_type *type" "struct domainset *ds" "int flags"
  67 .Sh DESCRIPTION
  68 The
  69 .Fn malloc
  70 function allocates uninitialized memory in kernel address space for an
  71 object whose size is specified by
  72 .Fa size .
  73 .Pp
  74 The
  75 .Fn malloc_domainset
  76 variant allocates memory from a specific
  77 .Xr numa 4
  78 domain using the specified domain selection policy.
  79 See
  80 .Xr domainset 9
  81 for some example policies.
  82 .Pp
  83 The
  84 .Fn mallocarray
  85 function allocates uninitialized memory in kernel address space for an
  86 array of
  87 .Fa nmemb
  88 entries whose size is specified by
  89 .Fa size .
  90 .Pp
  91 The
  92 .Fn free
  93 function releases memory at address
  94 .Fa addr
  95 that was previously allocated by
  96 .Fn malloc
  97 for re-use.
  98 The memory is not zeroed.
  99 If
 100 .Fa addr
 101 is
 102 .Dv NULL ,
 103 then
 104 .Fn free
 105 does nothing.
 106 .Pp
 107 Like
 108 .Fn free ,
 109 the
 110 .Fn zfree
 111 function releases memory at address
 112 .Fa addr
 113 that was previously allocated by
 114 .Fn malloc
 115 for re-use.
 116 However,
 117 .Fn zfree
 118 will zero the memory before it is released.
 119 .Pp
 120 The
 121 .Fn realloc
 122 function changes the size of the previously allocated memory referenced by
 123 .Fa addr
 124 to
 125 .Fa size
 126 bytes.
 127 The contents of the memory are unchanged up to the lesser of the new and
 128 old sizes.
 129 Note that the returned value may differ from
 130 .Fa addr .
 131 If the requested memory cannot be allocated,
 132 .Dv NULL
 133 is returned and the memory referenced by
 134 .Fa addr
 135 is valid and unchanged.
 136 If
 137 .Fa addr
 138 is
 139 .Dv NULL ,
 140 the
 141 .Fn realloc
 142 function behaves identically to
 143 .Fn malloc
 144 for the specified size.
 145 .Pp
 146 The
 147 .Fn reallocf
 148 function is identical to
 149 .Fn realloc
 150 except that it
 151 will free the passed pointer when the requested memory cannot be allocated.
 152 .Pp
 153 Unlike its standard C library counterpart
 154 .Pq Xr malloc 3 ,
 155 the kernel version takes two more arguments.
 156 The
 157 .Fa flags
 158 argument further qualifies
 159 .Fn malloc Ns 's
 160 operational characteristics as follows:
 161 .Bl -tag -width indent
 162 .It Dv M_ZERO
 163 Causes the allocated memory to be set to all zeros.
 164 .It Dv M_NODUMP
 165 For allocations greater than page size, causes the allocated
 166 memory to be excluded from kernel core dumps.
 167 .It Dv M_NOWAIT
 168 Causes
 169 .Fn malloc ,
 170 .Fn realloc ,
 171 and
 172 .Fn reallocf
 173 to return
 174 .Dv NULL
 175 if the request cannot be immediately fulfilled due to resource shortage.
 176 Note that
 177 .Dv M_NOWAIT
 178 is required when running in an interrupt context.
 179 .It Dv M_WAITOK
 180 Indicates that it is OK to wait for resources.
 181 If the request cannot be immediately fulfilled, the current process is put
 182 to sleep to wait for resources to be released by other processes.
 183 The
 184 .Fn malloc ,
 185 .Fn mallocarray ,
 186 .Fn realloc ,
 187 and
 188 .Fn reallocf
 189 functions cannot return
 190 .Dv NULL
 191 if
 192 .Dv M_WAITOK
 193 is specified.
 194 If the multiplication of
 195 .Fa nmemb
 196 and
 197 .Fa size
 198 would cause an integer overflow, the
 199 .Fn mallocarray
 200 function induces a panic.
 201 .It Dv M_USE_RESERVE
 202 Indicates that the system can use its reserve of memory to satisfy the
 203 request.
 204 This option should only be used in combination with
 205 .Dv M_NOWAIT
 206 when an allocation failure cannot be tolerated by the caller without
 207 catastrophic effects on the system.
 208 .It Dv M_EXEC
 209 Indicates that the system should allocate executable memory.
 210 If this flag is not set, the system will not allocate executable memory.
 211 Not all platforms enforce a distinction between executable and
 212 non-executable memory.
 213 .El
 214 .Pp
 215 Exactly one of either
 216 .Dv M_WAITOK
 217 or
 218 .Dv M_NOWAIT
 219 must be specified.
 220 .Pp
 221 The
 222 .Fa type
 223 argument is used to perform statistics on memory usage, and for
 224 basic sanity checks.
 225 It can be used to identify multiple allocations.
 226 The statistics can be examined by
 227 .Sq vmstat -m .
 228 .Pp
 229 A
 230 .Fa type
 231 is defined using
 232 .Vt "struct malloc_type"
 233 via the
 234 .Fn MALLOC_DECLARE
 235 and
 236 .Fn MALLOC_DEFINE
 237 macros.
 238 .Bd -literal -offset indent
 239 /* sys/something/foo_extern.h */
 240
 241 MALLOC_DECLARE(M_FOOBUF);
 242
 243 /* sys/something/foo_main.c */
 244
 245 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
 246
 247 /* sys/something/foo_subr.c */
 248
 249 \&...
 250 buf = malloc(sizeof(*buf), M_FOOBUF, M_NOWAIT);
 251
 252 .Ed
 253 .Pp
 254 In order to use
 255 .Fn MALLOC_DEFINE ,
 256 one must include
 257 .In sys/param.h
 258 (instead of
 259 .In sys/types.h )
 260 and
 261 .In sys/kernel.h .
 262 .Sh CONTEXT
 263 .Fn malloc ,
 264 .Fn realloc
 265 and
 266 .Fn reallocf
 267 may not be called from fast interrupts handlers.
 268 When called from threaded interrupts,
 269 .Fa flags
 270 must contain
 271 .Dv M_NOWAIT .
 272 .Pp
 273 .Fn malloc ,
 274 .Fn realloc
 275 and
 276 .Fn reallocf
 277 may sleep when called with
 278 .Dv M_WAITOK .
 279 .Fn free
 280 never sleeps.
 281 However,
 282 .Fn malloc ,
 283 .Fn realloc ,
 284 .Fn reallocf
 285 and
 286 .Fn free
 287 may not be called in a critical section or while holding a spin lock.
 288 .Pp
 289 Any calls to
 290 .Fn malloc
 291 (even with
 292 .Dv M_NOWAIT )
 293 or
 294 .Fn free
 295 when holding a
 296 .Xr vnode 9
 297 interlock, will cause a LOR (Lock Order Reversal) due to the
 298 intertwining of VM Objects and Vnodes.
 299 .Sh IMPLEMENTATION NOTES
 300 The memory allocator allocates memory in chunks that have size a power
 301 of two for requests up to the size of a page of memory.
 302 For larger requests, one or more pages is allocated.
 303 While it should not be relied upon, this information may be useful for
 304 optimizing the efficiency of memory use.
 305 .Sh RETURN VALUES
 306 The
 307 .Fn malloc ,
 308 .Fn realloc ,
 309 and
 310 .Fn reallocf
 311 functions return a kernel virtual address that is suitably aligned for
 312 storage of any type of object, or
 313 .Dv NULL
 314 if the request could not be satisfied (implying that
 315 .Dv M_NOWAIT
 316 was set).
 317 .Sh DIAGNOSTICS
 318 A kernel compiled with the
 319 .Dv INVARIANTS
 320 configuration option attempts to detect memory corruption caused by
 321 such things as writing outside the allocated area and imbalanced calls to the
 322 .Fn malloc
 323 and
 324 .Fn free
 325 functions.
 326 Failing consistency checks will cause a panic or a system console
 327 message.
 328 .Sh SEE ALSO
 329 .Xr numa 4 ,
 330 .Xr vmstat 8 ,
 331 .Xr contigmalloc 9 ,
 332 .Xr domainset 9 ,
 333 .Xr memguard 9 ,
 334 .Xr vnode 9