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