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