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