xref: /openbsd/share/man/man9/malloc.9 (revision 4bdff4be) 
1.\"	$OpenBSD: malloc.9,v 1.72 2024/01/19 15:10:27 deraadt 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: January 19 2024 $
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 mallocarray "size_t nmemb" "size_t size" "int type" "int flags"
46.Ft void
47.Fn free "void *addr" "int type" "size_t size"
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 .
54.Pp
55The
56.Fn mallocarray
57function is the same as
58.Fn malloc ,
59but allocates space for an array of
60.Fa nmemb
61objects and checks for arithmetic overflow.
62.Pp
63The
64.Fn free
65function releases memory at address
66.Fa addr
67that was previously allocated by
68.Fn malloc
69or
70.Fn mallocarray
71for re-use.
72The same object size originally provided to
73.Fn malloc
74should be specified by
75.Fa size ,
76because
77.Fn free
78will operate faster knowing this.
79If tracking the size is difficult, specify
80.Ar size
81as 0.
82If
83.Fa addr
84is a null pointer, no action occurs.
85.Pp
86The
87.Fa flags
88argument affects the operational characteristics of
89.Fn malloc
90and
91.Fn mallocarray
92as follows:
93.Bl -tag -width xxx -offset indent
94.It Dv M_WAITOK
95If memory is currently unavailable,
96.Fn malloc
97may call sleep to wait for resources to be released by other processes.
98.It Dv M_NOWAIT
99Causes
100.Fn malloc
101to return
102.Dv NULL
103if the request cannot be immediately fulfilled due to resource shortage.
104.It Dv M_CANFAIL
105In the
106.Dv M_WAITOK
107case, if not enough memory is available, return
108.Dv NULL
109instead of calling
110.Xr panic 9 .
111If
112.Fn mallocarray
113detects an overflow
114or
115.Fn malloc
116detects an excessive allocation, return
117.Dv NULL
118instead of calling
119.Xr panic 9 .
120.It Dv M_ZERO
121Causes allocated memory to be zeroed.
122.El
123.Pp
124One of
125.Dv M_NOWAIT
126or
127.Dv M_WAITOK
128must be specified via the
129.Fa flags
130argument.
131.Pp
132The
133.Fa type
134argument broadly identifies the kernel subsystem for which the allocated
135memory was needed, and is commonly used to maintain statistics about
136kernel memory usage.
137These statistics can be examined using
138.Xr vmstat 8
139or
140.Xr systat 1
141if either of the kernel
142.Xr options 4
143.Cm KMEMSTATS
144or
145.Cm DEBUG
146are enabled.
147.Pp
148The following types are currently defined:
149.Pp
150.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact
151.\"	START DEFINES	sys/malloc.h	(M_FREE,M_LAST)
152.It Dv M_DEVBUF
153Device driver memory.
154.It Dv M_PCB
155Protocol control blocks.
156.It Dv M_RTABLE
157Routing tables.
158.It Dv M_PF
159Packet filter structures.
160.It Dv M_IFADDR
161Interface addresses.
162.It Dv M_IFGROUP
163Interface groups.
164.It Dv M_SYSCTL
165Sysctl persistent buffers.
166.It Dv M_COUNTERS
167Per-CPU counters via
168.Xr counters_alloc 9 .
169.It Dv M_IOCTLOPS
170Ioctl data buffers.
171.It Dv M_IOV
172Large IOVs.
173.It Dv M_MOUNT
174VFS mount structs.
175.It Dv M_NFSREQ
176NFS request headers.
177.It Dv M_NFSMNT
178NFS mount structures.
179.It Dv M_LOG
180Messages in kernel log stash.
181.It Dv M_VNODE
182Dynamically allocated vnodes.
183.It Dv M_DQUOT
184UFS quota entries.
185.It Dv M_UFSMNT
186UFS mount structures.
187.It Dv M_SHM
188SVID compatible shared memory segments.
189.It Dv M_VMMAP
190VM map structures.
191.It Dv M_SEM
192SVID compatible semaphores.
193.It Dv M_DIRHASH
194UFS directory hash structures.
195.It Dv M_ACPI
196ACPI structures.
197.It Dv M_VMPMAP
198VM pmap data.
199.It Dv M_FILEDESC
200Open file descriptor tables.
201.It Dv M_SIGIO
202Sigio structures.
203.It Dv M_PROC
204Proc structures.
205.It Dv M_SUBPROC
206Proc sub-structures.
207.It Dv M_MFSNODE
208MFS vnode private part.
209.It Dv M_NETADDR
210Export host address structures.
211.It Dv M_NFSSVC
212NFS server structures.
213.It Dv M_NFSD
214NFS server daemon structures.
215.It Dv M_IPMOPTS
216Internet multicast options.
217.It Dv M_IPMADDR
218Internet multicast addresses.
219.It Dv M_IFMADDR
220Link-level multicast addresses.
221.It Dv M_MRTABLE
222Multicast routing tables.
223.It Dv M_ISOFSMNT
224ISOFS mount structures.
225.It Dv M_ISOFSNODE
226ISOFS vnode private part.
227.It Dv M_MSDOSFSMNT
228MSDOS FS mount structures.
229.It Dv M_MSDOSFSFAT
230MSDOS FS FAT tables.
231.It Dv M_MSDOSFSNODE
232MSDOS FS vnode private part.
233.It Dv M_TTYS
234Allocated tty structures.
235.It Dv M_EXEC
236Argument lists & other mem used by exec.
237.It Dv M_MISCFSMNT
238Miscellaneous FS mount structures.
239.It Dv M_FUSEFS
240FUSE FS mount structures.
241.It Dv M_PINSYSCALL
242.Xr pinsyscalls 2
243related data.
244.It Dv M_PFKEY
245Pfkey data.
246.It Dv M_TDB
247Transforms database.
248.It Dv M_XDATA
249IPsec data.
250.It Dv M_PAGEDEP
251File page dependencies.
252.It Dv M_INODEDEP
253Inode dependencies.
254.It Dv M_NEWBLK
255New block allocation.
256.It Dv M_INDIRDEP
257Indirect block dependencies.
258.It Dv M_VMSWAP
259VM swap structures.
260.It Dv M_UVMAMAP
261UVM amap and related.
262.It Dv M_UVMAOBJ
263UVM aobj and related.
264.It Dv M_USB
265USB general.
266.It Dv M_USBDEV
267USB device driver.
268.It Dv M_USBHC
269USB host controller.
270.It Dv M_WITNESS
271.Xr witness 4
272memory.
273.It Dv M_MEMDESC
274Memory range.
275.It Dv M_CRYPTO_DATA
276.Xr crypto 9
277data buffers.
278.It Dv M_CREDENTIALS
279.Xr ipsec 4
280related credentials.
281.It Dv M_IP6OPT
282IPv6 options.
283.It Dv M_IP6NDP
284IPv6 Neighbor Discovery structures.
285.It Dv M_TEMP
286Miscellaneous temporary data buffers.
287.It Dv M_NTFSMNT
288NTFS mount structures.
289.It Dv M_NTFSNTNODE
290NTFS ntnode information.
291.It Dv M_NTFSFNODE
292NTFS fnode information.
293.It Dv M_NTFSDIR
294NTFS directory buffers.
295.It Dv M_NTFSNTHASH
296NTFS ntnode hash tables.
297.It Dv M_NTFSNTVATTR
298NTFS file attribute information.
299.It Dv M_NTFSRDATA
300NTFS resident data.
301.It Dv M_NTFSDECOMP
302NTFS decompression temporary storage.
303.It Dv M_NTFSRUN
304NTFS vrun storage.
305.It Dv M_KEVENT
306.Xr kqueue 2
307data structures.
308.It Dv M_SYNCACHE
309SYN cache hash array.
310.It Dv M_UDFMOUNT
311UDF mount structures.
312.It Dv M_UDFFENTRY
313UDF file entries.
314.It Dv M_UDFFID
315UDF file IDs.
316.It Dv M_AGP
317AGP memory.
318.It Dv M_DRM
319Direct Rendering Manager.
320.\"	END DEFINES
321.El
322.Sh CONTEXT
323.Fn malloc
324and
325.Fn mallocarray
326can be called during autoconf, from process context, or from interrupt context
327if
328.Dv M_NOWAIT
329is passed via
330.Fa flags .
331They can't be called from interrupt context if
332.Dv M_WAITOK
333is passed via
334.Fa flags .
335.Pp
336.Fn free
337can be called during autoconf, from process context, or from interrupt context.
338.Sh RETURN VALUES
339.Fn malloc
340and
341.Fn mallocarray
342return a kernel virtual address that is suitably aligned for storage of
343any type of object.
344.Sh DIAGNOSTICS
345A kernel compiled with the
346.Dv DIAGNOSTIC
347configuration option attempts to detect memory corruption caused by
348such things as writing outside the allocated area and unbalanced calls to
349.Fn malloc
350or
351.Fn mallocarray ,
352and
353.Fn free .
354Failing consistency checks will cause a panic or a system console message:
355.Pp
356.Bl -bullet -offset indent -compact
357.It
358panic:
359.Dq malloc: bogus type
360.It
361panic:
362.Dq malloc: out of space in kmem_map
363.It
364panic:
365.Dq malloc: allocation too large
366.It
367panic:
368.Dq malloc: wrong bucket
369.It
370panic:
371.Dq malloc: lost data
372.It
373panic:
374.Dq mallocarray: overflow
375.It
376panic:
377.Dq free: unaligned addr
378.It
379panic:
380.Dq free: duplicated free
381.It
382panic:
383.Dq free: multiple frees
384.It
385panic:
386.Dq free: non-malloced addr
387.It
388panic:
389.Dq free: size too large
390.It
391panic:
392.Dq free: size too small
393.It
394panic:
395.Dq kmeminit: minbucket too small/struct freelist too big
396.It
397.Dq multiply freed item Aq addr
398.It
399.Dq Data modified on freelist: Aq data object description
400.El
401.Sh SEE ALSO
402.Xr systat 1 ,
403.Xr vmstat 8
404