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