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