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