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