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