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