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