/share/man/man9/malloc.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 286 lines · 280 code · 6 blank · 0 comment · 0 complexity · 9eba2447c53f83c96695b1d13cbf00af MD5 · raw file

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