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 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"        This product includes software developed by the NetBSD
  19 .\"        Foundation, Inc. and its contributors.
  20 .\" 4. Neither the name of The NetBSD Foundation nor the names of its
  21 .\"    contributors may be used to endorse or promote products derived
  22 .\"    from this software without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  25 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  26 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  27 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
  28 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  29 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  30 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  31 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  32 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  33 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  34 .\" POSSIBILITY OF SUCH DAMAGE.
  35 .\"
  36 .\" $NetBSD: malloc.9,v 1.3 1996/11/11 00:05:11 lukem Exp $
  37 .\" $FreeBSD$
  38 .\"
  39 .Dd June 12, 2003
  40 .Dt MALLOC 9
  41 .Os
  42 .Sh NAME
  43 .Nm malloc ,
  44 .Nm MALLOC ,
  45 .Nm free ,
  46 .Nm FREE ,
  47 .Nm realloc ,
  48 .Nm reallocf ,
  49 .Nm MALLOC_DEFINE ,
  50 .Nm MALLOC_DECLARE
  51 .Nd kernel memory management routines
  52 .Sh SYNOPSIS
  53 .In sys/types.h
  54 .In sys/malloc.h
  55 .Ft void *
  56 .Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
  57 .Fn MALLOC space cast "unsigned long size" "struct malloc_type *type" "int flags"
  58 .Ft void
  59 .Fn free "void *addr" "struct malloc_type *type"
  60 .Fn FREE "void *addr" "struct malloc_type *type"
  61 .Ft void *
  62 .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
  63 .Ft void *
  64 .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
  65 .Fn MALLOC_DECLARE type
  66 .In sys/param.h
  67 .In sys/malloc.h
  68 .In sys/kernel.h
  69 .Fn MALLOC_DEFINE type shortdesc longdesc
  70 .Sh DESCRIPTION
  71 The
  72 .Fn malloc
  73 function allocates uninitialized memory in kernel address space for an
  74 object whose size is specified by
  75 .Fa size .
  76 .Pp
  77 The
  78 .Fn free
  79 function releases memory at address
  80 .Fa addr
  81 that was previously allocated by
  82 .Fn malloc
  83 for re-use.
  84 The memory is not zeroed.
  85 If
  86 .Fa addr
  87 is
  88 .Dv NULL ,
  89 then
  90 .Fn free
  91 does nothing.
  92 .Pp
  93 The
  94 .Fn realloc
  95 function changes the size of the previously allocated memory referenced by
  96 .Fa addr
  97 to
  98 .Fa size
  99 bytes.
 100 The contents of the memory are unchanged up to the lesser of the new and
 101 old sizes.
 102 Note that the returned value may differ from
 103 .Fa addr .
 104 If the requested memory cannot be allocated,
 105 .Dv NULL
 106 is returned and the memory referenced by
 107 .Fa addr
 108 is valid and unchanged.
 109 If
 110 .Fa addr
 111 is
 112 .Dv NULL ,
 113 the
 114 .Fn realloc
 115 function behaves identically to
 116 .Fn malloc
 117 for the specified size.
 118 .Pp
 119 The
 120 .Fn reallocf
 121 function is identical to
 122 .Fn realloc
 123 except that it
 124 will free the passed pointer when the requested memory cannot be allocated.
 125 .Pp
 126 The
 127 .Fn MALLOC
 128 macro variant is functionally equivalent to
 129 .Bd -literal -offset indent
 130 (space) = (cast)malloc((u_long)(size), type, flags)
 131 .Ed
 132 .Pp
 133 and the
 134 .Fn FREE
 135 macro variant is equivalent to
 136 .Bd -literal -offset indent
 137 free((addr), type)
 138 .Ed
 139 .Pp
 140 Unlike its standard C library counterpart
 141 .Pq Xr malloc 3 ,
 142 the kernel version takes two more arguments.
 143 The
 144 .Fa flags
 145 argument further qualifies
 146 .Fn malloc Ns 's
 147 operational characteristics as follows:
 148 .Bl -tag -width indent
 149 .It Dv M_ZERO
 150 Causes the allocated memory to be set to all zeros.
 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 realloc ,
 170 and
 171 .Fn reallocf
 172 functions cannot return
 173 .Dv NULL
 174 if
 175 .Dv M_WAITOK
 176 is specified.
 177 .It Dv M_USE_RESERVE
 178 Indicates that the system can dig into its reserve in order to obtain the
 179 requested memory.
 180 This option used to be called
 181 .Dv M_KERNEL
 182 but has been renamed to something more obvious.
 183 This option has been deprecated and is slowly being removed from the kernel,
 184 and so should not be used with any new programming.
 185 .El
 186 .Pp
 187 Exactly one of either
 188 .Dv M_WAITOK
 189 or
 190 .Dv M_NOWAIT
 191 must be specified.
 192 .Pp
 193 The
 194 .Fa type
 195 argument is used to perform statistics on memory usage, and for
 196 basic sanity checks.
 197 It can be used to identify multiple allocations.
 198 The statistics can be examined by
 199 .Sq vmstat -m .
 200 .Pp
 201 A
 202 .Fa type
 203 is defined using
 204 .Vt "struct malloc_type"
 205 via the
 206 .Fn MALLOC_DECLARE
 207 and
 208 .Fn MALLOC_DEFINE
 209 macros.
 210 .Bd -literal -offset indent
 211 /* sys/something/foo_extern.h */
 212
 213 MALLOC_DECLARE(M_FOOBUF);
 214
 215 /* sys/something/foo_main.c */
 216
 217 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
 218
 219 /* sys/something/foo_subr.c */
 220
 221 \&...
 222 MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
 223
 224 .Ed
 225 .Pp
 226 In order to use
 227 .Fn MALLOC_DEFINE ,
 228 one must include
 229 .In sys/param.h
 230 (instead of
 231 .In sys/types.h )
 232 and
 233 .In sys/kernel.h .
 234 .Sh IMPLEMENTATION NOTES
 235 The memory allocator allocates memory in chunks that have size a power
 236 of two for requests up to the size of a page of memory.
 237 For larger requests, one or more pages is allocated.
 238 While it should not be relied upon, this information may be useful for
 239 optimizing the efficiency of memory use.
 240 .Pp
 241 Programmers should be careful not to confuse the malloc flags
 242 .Dv M_NOWAIT
 243 and
 244 .Dv M_WAITOK
 245 with the
 246 .Xr mbuf 9
 247 flags
 248 .Dv M_DONTWAIT
 249 and
 250 .Dv M_TRYWAIT .
 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 .Pp
 271 Any calls to
 272 .Fn malloc
 273 (even with
 274 .Dv M_NOWAIT )
 275 or
 276 .Fn free
 277 when holding a
 278 .Xr vnode 9
 279 interlock, will cause a LOR (Lock Order Reversal) due to the
 280 intertwining of VM Objects and Vnodes.
 281 .Sh RETURN VALUES
 282 The
 283 .Fn malloc ,
 284 .Fn realloc ,
 285 and
 286 .Fn reallocf
 287 functions return a kernel virtual address that is suitably aligned for
 288 storage of any type of object, or
 289 .Dv NULL
 290 if the request could not be satisfied (implying that
 291 .Dv M_NOWAIT
 292 was set).
 293 .Sh DIAGNOSTICS
 294 A kernel compiled with the
 295 .Dv INVARIANTS
 296 configuration option attempts to detect memory corruption caused by
 297 such things as writing outside the allocated area and imbalanced calls to the
 298 .Fn malloc
 299 and
 300 .Fn free
 301 functions.
 302 Failing consistency checks will cause a panic or a system console
 303 message.
 304 .Sh SEE ALSO
 305 .Xr vmstat 8 ,
 306 .Xr contigmalloc 9 ,
 307 .Xr memguard 9 ,
 308 .Xr vnode 9