xref: /openbsd/share/man/man9/malloc.9 (revision 73471bf0) 
1.\"	$OpenBSD: malloc.9,v 1.67 2019/02/07 15:11:38 visa 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: February 7 2019 $
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.It Dv M_FREE
152Should be on free list.
153.It Dv M_DEVBUF
154Device driver memory.
155.It Dv M_PCB
156Protocol control blocks.
157.It Dv M_RTABLE
158Routing tables.
159.It Dv M_IFADDR
160Interface addresses.
161.It Dv M_SOOPTS
162Socket options.
163.It Dv M_SYSCTL
164Sysctl persistent buffers.
165.It Dv M_COUNTERS
166Per-CPU Counters for use via
167.Xr counters_alloc 9 .
168.It Dv M_IOCTLOPS
169Ioctl data buffers.
170.It Dv M_IOV
171Large IOVs.
172.It Dv M_MOUNT
173VFS mount structs.
174.It Dv M_NFSREQ
175NFS request headers.
176.It Dv M_NFSMNT
177NFS mount structures.
178.It Dv M_VNODE
179Dynamically allocated vnodes.
180.It Dv M_CACHE
181Dynamically allocated cache entries.
182.It Dv M_DQUOT
183UFS quota entries.
184.It Dv M_UFSMNT
185UFS mount structures.
186.It Dv M_SHM
187SVID compatible shared memory segments.
188.It Dv M_VMMAP
189VM map structures.
190.It Dv M_SEM
191SVID compatible semaphores.
192.It Dv M_DIRHASH
193UFS directory hash structures.
194.It Dv M_ACPI
195ACPI structures.
196.It Dv M_VMPMAP
197VM pmap data.
198.It Dv M_FILE
199Open file structures.
200.It Dv M_FILEDESC
201Open file descriptor tables.
202.It Dv M_SIGIO
203Sigio structures.
204.It Dv M_PROC
205Proc structures.
206.It Dv M_SUBPROC
207Proc sub-structures.
208.It Dv M_VCLUSTER
209Cluster for VFS.
210.It Dv M_MFSNODE
211MFS vnode private part.
212.It Dv M_NETADDR
213Export host address structures.
214.It Dv M_NFSSVC
215NFS server structures.
216.It Dv M_NFSD
217NFS server daemon structures.
218.It Dv M_IPMOPTS
219Internet multicast options.
220.It Dv M_IPMADDR
221Internet multicast addresses.
222.It Dv M_IFMADDR
223Link-level multicast addresses.
224.It Dv M_MRTABLE
225Multicast routing tables.
226.It Dv M_ISOFSMNT
227ISOFS mount structures.
228.It Dv M_ISOFSNODE
229ISOFS vnode private part.
230.It Dv M_MSDOSFSMNT
231MSDOS FS mount structures.
232.It Dv M_MSDOSFSFAT
233MSDOS FS FAT tables.
234.It Dv M_MSDOSFSNODE
235MSDOS FS vnode private part.
236.It Dv M_TTYS
237Allocated tty structures.
238.It Dv M_EXEC
239Argument lists & other mem used by exec.
240.It Dv M_MISCFSMNT
241Miscellaneous FS mount structures.
242.It Dv M_FUSEFS
243FUSE FS mount structures.
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_EMULDATA
282Per process emulation data.
283.It Dv M_IP6OPT
284IPv6 options.
285.It Dv M_IP6NDP
286IPv6 neighbour discovery structures.
287.It Dv M_TEMP
288Miscellaneous temporary data buffers.
289.It Dv M_NTFSMNT
290NTFS mount structures.
291.It Dv M_NTFSNTNODE
292NTFS ntnode information.
293.It Dv M_NTFSFNODE
294NTFS fnode information.
295.It Dv M_NTFSDIR
296NTFS directory buffers.
297.It Dv M_NTFSNTHASH
298NTFS ntnode hash tables.
299.It Dv M_NTFSNTVATTR
300NTFS file attribute information.
301.It Dv M_NTFSRDATA
302NTFS resident data.
303.It Dv M_NTFSDECOMP
304NTFS decompression temporary storage.
305.It Dv M_NTFSRUN
306NTFS vrun storage.
307.It Dv M_KEVENT
308.Xr kqueue 2
309data structures.
310.It Dv M_SYNCACHE
311SYN cache hash array.
312.It Dv M_UDFMOUNT
313UDF mount structures.
314.It Dv M_UDFFENTRY
315UDF file entries.
316.It Dv M_UDFFID
317UDF file ID.
318.It Dv M_AGP
319AGP memory.
320.It Dv M_DRM
321Direct Rendering Manager.
322.El
323.Sh CONTEXT
324.Fn malloc
325and
326.Fn mallocarray
327can be called during autoconf, from process context, or from interrupt context
328if
329.Dv M_NOWAIT
330is passed via
331.Fa flags .
332They can't be called from interrupt context if
333.Dv M_WAITOK
334is passed via
335.Fa flags .
336.Pp
337.Fn free
338can be called during autoconf, from process context, or from interrupt context.
339.Sh RETURN VALUES
340.Fn malloc
341and
342.Fn mallocarray
343return a kernel virtual address that is suitably aligned for storage of
344any type of object.
345.Sh DIAGNOSTICS
346A kernel compiled with the
347.Dv DIAGNOSTIC
348configuration option attempts to detect memory corruption caused by
349such things as writing outside the allocated area and unbalanced calls to
350.Fn malloc
351or
352.Fn mallocarray ,
353and
354.Fn free .
355Failing consistency checks will cause a panic or a system console message:
356.Pp
357.Bl -bullet -offset indent -compact
358.It
359panic:
360.Dq malloc: bogus type
361.It
362panic:
363.Dq malloc: out of space in kmem_map
364.It
365panic:
366.Dq malloc: allocation too large
367.It
368panic:
369.Dq malloc: wrong bucket
370.It
371panic:
372.Dq malloc: lost data
373.It
374panic:
375.Dq mallocarray: overflow
376.It
377panic:
378.Dq free: unaligned addr
379.It
380panic:
381.Dq free: duplicated free
382.It
383panic:
384.Dq free: multiple frees
385.It
386panic:
387.Dq free: non-malloced addr
388.It
389panic:
390.Dq free: size too large
391.It
392panic:
393.Dq free: size too small
394.It
395panic:
396.Dq kmeminit: minbucket too small/struct freelist too big
397.It
398.Dq multiply freed item Aq addr
399.It
400.Dq Data modified on freelist: Aq data object description
401.El
402.Sh SEE ALSO
403.Xr systat 1 ,
404.Xr vmstat 8
405