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: src/share/man/man9/malloc.9,v 1.13.2.6 2002/03/16 02:20:28 archie Exp $
  38 .\" $DragonFly: src/share/man/man9/Attic/malloc.9,v 1.3 2004/03/12 22:29:21 joerg Exp $
  39 .\"
  40 .Dd June 16, 1996
  41 .Dt MALLOC 9
  42 .Os
  43 .Sh NAME
  44 .Nm malloc ,
  45 .Nm MALLOC ,
  46 .Nm free ,
  47 .Nm FREE
  48 .Nd kernel memory management routines
  49 .Sh SYNOPSIS
  50 .In sys/types.h
  51 .In sys/malloc.h
  52 .Ft void *
  53 .Fn malloc "unsigned long size" "struct malloc_type *type" "int flags"
  54 .Fn MALLOC "space" "cast" "unsigned long size" "struct malloc_type  *type" "int flags"
  55 .Ft void
  56 .Fn free "void *addr" "struct malloc_type *type"
  57 .Fn FREE "void *addr" "struct malloc_type *type"
  58 .Ft void *
  59 .Fn realloc "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
  60 .Ft void *
  61 .Fn reallocf "void *addr" "unsigned long size" "struct malloc_type *type" "int flags"
  62 .Sh DESCRIPTION
  63 The
  64 .Fn malloc
  65 function allocates uninitialized memory in kernel address space for an
  66 object whose size is specified by
  67 .Fa size .
  68 .Pp
  69 .Fn free
  70 releases memory at address
  71 .Fa addr
  72 that was previously allocated by
  73 .Fn malloc
  74 for re-use.
  75 The memory is not zeroed.
  76 The kernel implementation of
  77 .Fn free
  78 does not allow
  79 .Fa addr
  80 to be
  81 .Dv NULL .
  82 .Pp
  83 The
  84 .Fn realloc
  85 function changes the size of the previously allocated memory referenced by
  86 .Fa addr
  87 to
  88 .Fa size
  89 bytes.
  90 The contents of the memory are unchanged up to the lesser of the new and
  91 old sizes.
  92 Note that the returned value may differ from
  93 .Fa addr .
  94 If the requested memory cannot be allocated,
  95 .Dv NULL
  96 is returned and the memory referenced by
  97 .Fa addr
  98 is valid and unchanged.
  99 If
 100 .Fa addr
 101 is
 102 .Dv NULL ,
 103 the
 104 .Fn realloc
 105 function behaves identically to
 106 .Fn malloc
 107 for the specified size.
 108 .Pp
 109 The
 110 .Fn reallocf
 111 function call is identical to the realloc function call, except that it
 112 will free the passed pointer when the requested memory cannot be allocated.
 113 .Pp
 114 The
 115 .Fn MALLOC
 116 macro variant is functionally equivalent to
 117 .Bd -literal -offset indent
 118 (space) = (cast)malloc((u_long)(size), type, flags)
 119 .Ed
 120 .Pp
 121 and the
 122 .Fn FREE
 123 macro variant is equivalent to
 124 .Bd -literal -offset indent
 125 free((addr), type)
 126 .Ed
 127 .Pp
 128 Unlike its standard C library counterpart
 129 .Pq Xr malloc 3 ,
 130 the kernel version takes two more arguments.  The
 131 .Fa flags
 132 argument further qualifies
 133 .Fn malloc Ns 's
 134 operational characteristics as follows:
 135 .Bl -tag -width indent
 136 .It Dv M_NOWAIT
 137 Causes
 138 .Fn malloc ,
 139 .Fn realloc ,
 140 or
 141 .Fn reallocf
 142 to return
 143 .Dv NULL
 144 if the request cannot be immediately fulfilled due to resource shortage.
 145 Otherwise, the current process may be put to sleep to wait for
 146 resources to be released by other processes.
 147 If this flag is set,
 148 .Fn malloc
 149 will return
 150 .Dv NULL
 151 rather then block.
 152 Note that
 153 .Dv M_WAITOK
 154 is defined to be 0, meaning that blocking operation is the default.
 155 Also note that
 156 .Dv M_NOWAIT
 157 is required when running in an interrupt context.
 158 .It Dv M_ASLEEP
 159 Causes
 160 .Fn malloc ,
 161 .Fn realloc ,
 162 or
 163 .Fn reallocf
 164 to call
 165 .Fn asleep
 166 if the request cannot be immediately fulfilled due to a resource shortage.
 167 M_ASLEEP is not useful alone and should always be or'd with M_NOWAIT to allow
 168 the function to call
 169 .Fn asleep
 170 and return
 171 .Dv NULL
 172 immediately.  It is expected that the caller will at some point call
 173 .Fn await
 174 and then retry the allocation.  Depending on the routine in question, the
 175 caller may decide to propagate the temporary failure up the call chain
 176 and actually have some other higher level routine block on the async wait
 177 that the function queued.
 178 .It Dv M_WAITOK
 179 Indicates that it is Ok to wait for resources.  It is unconveniently
 180 defined as 0 so care should be taken never to compare against this value
 181 directly or try to AND it as a flag.  The default operation is to block
 182 until the memory allocation succeeds.
 183 .Fn malloc ,
 184 .Fn realloc ,
 185 and
 186 .Fn reallocf
 187 can only return
 188 .Dv NULL
 189 if
 190 .Dv M_NOWAIT
 191 is specified.
 192 .It Dv M_USE_RESERVE
 193 Indicates that the system can dig into its reserve in order to obtain the
 194 requested memory.  This option used to be called M_KERNEL but has been
 195 renamed to something more obvious.  This option has been deprecated and is
 196 slowly being removed from the kernel, and so should not be used with any new
 197 programming.
 198 .El
 199 .Pp
 200 The
 201 .Fa type
 202 argument is used to perform statistics on memory usage, and for
 203 basic sanity checks.
 204 The statistics can be examined by
 205 .Sq vmstat -m .
 206 .Pp
 207 A
 208 .Fa type
 209 is defined using the
 210 .Va malloc_type_t
 211 typedef via the
 212 .Fn MALLOC_DECLARE
 213 and
 214 .Fn MALLOC_DEFINE
 215 macros.
 216 .Bd -literal -offset indent
 217 /* sys/something/foo_extern.h */
 218
 219 MALLOC_DECLARE(M_FOOBUF);
 220
 221 /* sys/something/foo_main.c */
 222
 223 MALLOC_DEFINE(M_FOOBUF, "foobuffers", "Buffers to foo data into the ether");
 224
 225 /* sys/something/foo_subr.c */
 226
 227 \&...
 228 MALLOC(buf, struct foo_buf *, sizeof *buf, M_FOOBUF, M_NOWAIT);
 229
 230 .Ed
 231 .Sh RETURN VALUES
 232 .Fn malloc ,
 233 .Fn realloc ,
 234 and
 235 .Fn reallocf
 236 return a kernel virtual address that is suitably aligned for storage of
 237 any type of object, or
 238 .Dv NULL
 239 if the request could not be satisfied (implying that
 240 .Dv M_NOWAIT
 241 was set).
 242 If
 243 .Dv M_ASLEEP
 244 was set and the function returns
 245 .Dv NULL ,
 246 it will call
 247 .Fn asleep
 248 as a side effect.
 249 .Sh IMPLEMENTATION NOTES
 250 The memory allocator allocates memory in chunks that have size a power
 251 of two for requests up to the size of a page of memory.
 252 For larger requests, one or more pages is allocated.
 253 While it should not be relied upon, this information may be useful for
 254 optimizing the efficiency of memory use.
 255 .Sh SEE ALSO
 256 .Xr vmstat 8
 257 .Sh DIAGNOSTICS
 258 A kernel compiled with the
 259 .Dv DIAGNOSTIC
 260 configuration option attempts to detect memory corruption caused by
 261 such things as writing outside the allocated area and imbalanced calls to the
 262 .Fn malloc
 263 and
 264 .Fn free
 265 functions.
 266 Failing consistency checks will cause a panic or a system console
 267 message:
 268 .Bl -bullet -offset indent -compact
 269 .Pp
 270 .It
 271 panic:
 272 .Dq malloc: bogus type
 273 .It
 274 panic:
 275 .Dq malloc: allocation too large
 276 .It
 277 panic:
 278 .Dq malloc: wrong bucket
 279 .It
 280 panic:
 281 .Dq malloc: lost data
 282 .It
 283 panic:
 284 .Dq free: address 0x%x out of range
 285 .It
 286 panic:
 287 .Dq free: type %d out of range
 288 .It
 289 panic:
 290 .Dq free: unaligned addr Aq description of object
 291 .It
 292 panic:
 293 .Dq free: item modified
 294 .It
 295 panic:
 296 .Dq free: multiple free[s]
 297 .It
 298 .Dq Data modified on freelist: Aq description of object
 299 .El