xref: /openbsd/share/man/man9/malloc.9 (revision 2bb3378b) 
1.\"	$OpenBSD: malloc.9,v 1.53 2014/07/10 19:33:16 matthew Exp $
2.\"	$NetBSD: malloc.9,v 1.2 1996/10/30 05:29:54 lukem Exp $
3.\"
4.\" Copyright (c) 1996 The NetBSD Foundation, Inc.
5.\" All rights reserved.
6.\"
7.\" This code is derived from software contributed to The NetBSD Foundation
8.\" by Paul Kranenburg.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE
23.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29.\" POSSIBILITY OF SUCH DAMAGE.
30.\"
31.Dd $Mdocdate: July 10 2014 $
32.Dt MALLOC 9
33.Os
34.Sh NAME
35.Nm malloc ,
36.Nm mallocarray ,
37.Nm free
38.Nd kernel memory allocator
39.Sh SYNOPSIS
40.In sys/types.h
41.In sys/malloc.h
42.Ft void *
43.Fn malloc "size_t size" "int type" "int flags"
44.Ft void *
45.Fn malloc "size_t nmemb" "size_t size" "int type" "int flags"
46.Ft void
47.Fn free "void *addr" "int type"
48.Sh DESCRIPTION
49The
50.Fn malloc
51function allocates uninitialized memory in kernel address space for an
52object whose size is specified by
53.Fa size .
54The
55.Fn mallocarray
56function is the same as
57.Fn malloc ,
58except it allocates space for an array of
59.Fa nmemb
60objects and checks for arithmetic overflow.
61.Pp
62The
63.Fn free
64function releases memory at address
65.Fa addr
66that was previously allocated by
67.Fn malloc
68for re-use.
69If
70.Fa addr
71is a null pointer, no action occurs.
72.Pp
73The
74.Fa flags
75argument further qualifies
76.Fn malloc Ns 's
77operational characteristics as follows:
78.Bl -tag -width xxx -offset indent
79.It Dv M_WAITOK
80The same as having no other
81.Fa flags
82specified.
83If memory is currently unavailable,
84.Fn malloc
85may call sleep to wait for resources to be released by other processes.
86.It Dv M_NOWAIT
87Causes
88.Fn malloc
89to return
90.Dv NULL
91if the request cannot be immediately fulfilled due to resource shortage.
92One of
93.Dv M_NOWAIT
94or
95.Dv M_WAITOK
96must be specified.
97.It Dv M_CANFAIL
98In the
99.Dv M_WAITOK
100case, if not enough memory is available, return
101.Dv NULL
102instead of calling
103.Xr panic 9 .
104.Dv M_CANFAIL
105has no effect if
106.Dv M_NOWAIT
107is specified.
108.It Dv M_ZERO
109Causes
110.Fn malloc
111to return zeroed memory.
112.El
113.Pp
114The
115.Fa type
116argument broadly identifies the kernel subsystem for which the allocated
117memory was needed, and is commonly used to maintain statistics about
118kernel memory usage.
119These statistics can be examined using
120.Xr vmstat 8
121or
122.Xr systat 1
123if either of the kernel
124.Xr options 4
125.Cm KMEMSTATS
126or
127.Cm DEBUG
128are enabled.
129.Pp
130The following types are currently defined:
131.Pp
132.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact
133.It Dv M_FREE
134Should be on free list.
135.It Dv M_DEVBUF
136Device driver memory.
137.It Dv M_DEBUG
138.Nm malloc
139debug structures.
140.It Dv M_PCB
141Protocol control blocks.
142.It Dv M_RTABLE
143Routing tables.
144.It Dv M_FTABLE
145Fragment reassembly headers.
146.It Dv M_IFADDR
147Interface addresses.
148.It Dv M_SOOPTS
149Socket options.
150.It Dv M_SYSCTL
151Sysctl persistent buffers.
152.It Dv M_IOCTLOPS
153Ioctl data buffers.
154.It Dv M_IOV
155Large IOVs.
156.It Dv M_MOUNT
157VFS mount structs.
158.It Dv M_NFSREQ
159NFS request headers.
160.It Dv M_NFSMNT
161NFS mount structures.
162.It Dv M_VNODE
163Dynamically allocated vnodes.
164.It Dv M_CACHE
165Dynamically allocated cache entries.
166.It Dv M_DQUOT
167UFS quota entries.
168.It Dv M_UFSMNT
169UFS mount structures.
170.It Dv M_SHM
171SVID compatible shared memory segments.
172.It Dv M_VMMAP
173VM map structures.
174.It Dv M_SEM
175SVID compatible semaphores.
176.It Dv M_DIRHASH
177UFS directory hash structures.
178.It Dv M_ACPI
179ACPI structures.
180.It Dv M_VMPMAP
181VM pmap data.
182.It Dv M_FILE
183Open file structures.
184.It Dv M_FILEDESC
185Open file descriptor tables.
186.It Dv M_PROC
187Proc structures.
188.It Dv M_SUBPROC
189Proc sub-structures.
190.It Dv M_VCLUSTER
191Cluster for VFS.
192.It Dv M_MFSNODE
193MFS vnode private part.
194.It Dv M_NETADDR
195Export host address structures.
196.It Dv M_NFSSVC
197NFS server structures.
198.It Dv M_NFSD
199NFS server daemon structures.
200.It Dv M_IPMOPTS
201Internet multicast options.
202.It Dv M_IPMADDR
203Internet multicast addresses.
204.It Dv M_IFMADDR
205Link-level multicast addresses.
206.It Dv M_MRTABLE
207Multicast routing tables.
208.It Dv M_ISOFSMNT
209ISOFS mount structures.
210.It Dv M_ISOFSNODE
211ISOFS vnode private part.
212.It Dv M_MSDOSFSMNT
213MSDOS FS mount structures.
214.It Dv M_MSDOSFSFAT
215MSDOS FS FAT tables.
216.It Dv M_MSDOSFSNODE
217MSDOS FS vnode private part.
218.It Dv M_TTYS
219Allocated tty structures.
220.It Dv M_EXEC
221Argument lists & other mem used by exec.
222.It Dv M_MISCFSMNT
223Miscellaneous FS mount structures.
224.It Dv M_FUSEFS
225FUSE FS mount structures.
226.It Dv M_PFKEY
227Pfkey data.
228.It Dv M_TDB
229Transforms database.
230.It Dv M_XDATA
231IPsec data.
232.It Dv M_PAGEDEP
233File page dependencies.
234.It Dv M_INODEDEP
235Inode dependencies.
236.It Dv M_NEWBLK
237New block allocation.
238.It Dv M_INDIRDEP
239Indirect block dependencies.
240.It Dv M_VMSWAP
241VM swap structures.
242.It Dv M_UVMAMAP
243UVM amap and related.
244.It Dv M_UVMAOBJ
245UVM aobj and related.
246.It Dv M_USB
247USB general.
248.It Dv M_USBDEV
249USB device driver.
250.It Dv M_USBHC
251USB host controller.
252.It Dv M_MEMDESC
253Memory range.
254.It Dv M_CRYPTO_DATA
255.Xr crypto 4
256data buffers.
257.It Dv M_CREDENTIALS
258.Xr ipsec 4
259related credentials.
260.It Dv M_EMULDATA
261Per process emulation data.
262.It Dv M_IP6OPT
263IPv6 options.
264.It Dv M_IP6NDP
265IPv6 neighbour discovery structures.
266.It Dv M_TEMP
267Miscellaneous temporary data buffers.
268.It Dv M_NTFSMNT
269NTFS mount structures.
270.It Dv M_NTFSNTNODE
271NTFS ntnode information.
272.It Dv M_NTFSNODE
273NTFS fnode information.
274.It Dv M_NTFSDIR
275NTFS directory buffers.
276.It Dv M_NTFSHASH
277NTFS ntnode hash tables.
278.It Dv M_NTFSVATTR
279NTFS file attribute information.
280.It Dv M_NTFSRDATA
281NTFS resident data.
282.It Dv M_NTFSDECOMP
283NTFS decompression temporary storage.
284.It Dv M_NTFSRUN
285NTFS vrun storage.
286.It Dv M_KEVENT
287.Xr kqueue 2
288data structures.
289.It Dv M_BLUETOOTH
290Bluetooth data structures.
291.It Dv M_BWMETER
292Multicast upcall bandwidth meters.
293.It Dv M_UDFMOUNT
294UDF mount structures.
295.It Dv M_UDFFENTRY
296UDF file entries.
297.It Dv M_UDFFID
298UDF file ID.
299.It Dv M_BTHIDEV
300Bluetooth HID.
301.It Dv M_AGP
302AGP memory.
303.It Dv M_DRM
304Direct Rendering Manager.
305.El
306.Sh CONTEXT
307.Fn malloc
308can be called,
309if
310.Dv M_NOWAIT
311is passed via
312.Fa flags ,
313during autoconf, from process context, or from interrupt context;
314it can't be called from interrupt context if
315.Dv M_WAITOK
316is passed via
317.Fa flags .
318.Pp
319.Fn free
320can be called during autoconf, from process context, or from interrupt context.
321.Sh RETURN VALUES
322.Fn malloc
323returns a kernel virtual address that is suitably aligned for storage of
324any type of object.
325.Sh DIAGNOSTICS
326A kernel compiled with the
327.Dv DIAGNOSTIC
328configuration option attempts to detect memory corruption caused by
329such things as writing outside the allocated area and unbalanced calls to the
330.Fn malloc
331and
332.Fn free
333functions.
334Failing consistency checks will cause a panic or a system console message:
335.Pp
336.Bl -bullet -offset indent -compact
337.It
338panic:
339.Dq malloc - bogus type
340.It
341panic:
342.Dq malloc: out of space in kmem_map
343.It
344panic:
345.Dq malloc: allocation too large
346.It
347panic:
348.Dq malloc: wrong bucket
349.It
350panic:
351.Dq malloc: lost data
352.It
353panic:
354.Dq free: unaligned addr
355.It
356panic:
357.Dq free: duplicated free
358.It
359panic:
360.Dq free: multiple frees
361.It
362panic:
363.Dq kmeminit: minbucket too small/struct freelist too big
364.It
365.Dq multiply freed item Aq addr
366.It
367.Dq Data modified on freelist: Aq data object description
368.El
369.Sh DEBUGGING
370A kernel compiled with the
371.Cm MALLOC_DEBUG
372option allows for more extensive debugging of memory allocations.
373The
374.Va debug_malloc_type ,
375.Va debug_malloc_size ,
376.Va debug_malloc_size_lo
377and
378.Va debug_malloc_size_hi
379variables choose which allocation to debug.
380.Va debug_malloc_type
381should be set to the memory type and
382.Va debug_malloc_size
383should be set to the memory size to debug.
3840 can be used as a wildcard.
385.Va debug_malloc_size_lo
386and
387.Va debug_malloc_size_hi
388can be used to specify a range of sizes if the exact size to debug is not
389known.
390When those are used,
391.Va debug_malloc_size
392needs to be set to the wildcard.
393.Dv M_DEBUG
394can also be specified as an allocation type to force allocation with
395debugging.
396.Pp
397Every call to
398.Fn malloc
399with a memory type and size that matches the debugged type and size will
400allocate two virtual pages.
401The pointer returned will be aligned so that
402the requested area will end at the page boundary and the second virtual page
403will be left unmapped.
404This way we can catch reads and writes outside the allocated area.
405.Pp
406Every call to
407.Fn free
408with memory that was returned by the debugging malloc will cause the memory
409area to become unmapped so that we can catch dangling reads and writes to
410freed memory.
411.Pp
412There are no special diagnostics if any errors are caught by the debugging
413malloc.
414The errors will look like normal access to unmapped memory.
415On a memory access error, the
416.Ic show malloc
417command in
418.Xr ddb 4
419can be invoked to see what memory areas are allocated and freed.
420If the faulting address is within two pages from an address on the allocated
421list, there was an access outside the allocated area.
422If the faulting address is within two pages from an address on the free list,
423there was an access to freed memory.
424.Pp
425Care needs to be taken when using the
426.Cm MALLOC_DEBUG
427option:  the memory consumption can run away pretty quickly and there is
428a severe performance degradation when allocating and freeing debugged memory
429types.
430.Sh SEE ALSO
431.Xr systat 1 ,
432.Xr vmstat 8
433