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