xref: /openbsd-src/share/man/man9/malloc.9 (revision c90a81c56dcebd6a1b73fe4aff9b03385b8e63b3) 
1.\"	$OpenBSD: malloc.9,v 1.65 2017/11/27 09:23:44 mpi 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: November 27 2017 $
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_PROC
203Proc structures.
204.It Dv M_SUBPROC
205Proc sub-structures.
206.It Dv M_VCLUSTER
207Cluster for VFS.
208.It Dv M_MFSNODE
209MFS vnode private part.
210.It Dv M_NETADDR
211Export host address structures.
212.It Dv M_NFSSVC
213NFS server structures.
214.It Dv M_NFSD
215NFS server daemon structures.
216.It Dv M_IPMOPTS
217Internet multicast options.
218.It Dv M_IPMADDR
219Internet multicast addresses.
220.It Dv M_IFMADDR
221Link-level multicast addresses.
222.It Dv M_MRTABLE
223Multicast routing tables.
224.It Dv M_ISOFSMNT
225ISOFS mount structures.
226.It Dv M_ISOFSNODE
227ISOFS vnode private part.
228.It Dv M_MSDOSFSMNT
229MSDOS FS mount structures.
230.It Dv M_MSDOSFSFAT
231MSDOS FS FAT tables.
232.It Dv M_MSDOSFSNODE
233MSDOS FS vnode private part.
234.It Dv M_TTYS
235Allocated tty structures.
236.It Dv M_EXEC
237Argument lists & other mem used by exec.
238.It Dv M_MISCFSMNT
239Miscellaneous FS mount structures.
240.It Dv M_FUSEFS
241FUSE FS mount structures.
242.It Dv M_PFKEY
243Pfkey data.
244.It Dv M_TDB
245Transforms database.
246.It Dv M_XDATA
247IPsec data.
248.It Dv M_PAGEDEP
249File page dependencies.
250.It Dv M_INODEDEP
251Inode dependencies.
252.It Dv M_NEWBLK
253New block allocation.
254.It Dv M_INDIRDEP
255Indirect block dependencies.
256.It Dv M_VMSWAP
257VM swap structures.
258.It Dv M_UVMAMAP
259UVM amap and related.
260.It Dv M_UVMAOBJ
261UVM aobj and related.
262.It Dv M_USB
263USB general.
264.It Dv M_USBDEV
265USB device driver.
266.It Dv M_USBHC
267USB host controller.
268.It Dv M_MEMDESC
269Memory range.
270.It Dv M_CRYPTO_DATA
271.Xr crypto 9
272data buffers.
273.It Dv M_CREDENTIALS
274.Xr ipsec 4
275related credentials.
276.It Dv M_EMULDATA
277Per process emulation data.
278.It Dv M_IP6OPT
279IPv6 options.
280.It Dv M_IP6NDP
281IPv6 neighbour discovery structures.
282.It Dv M_TEMP
283Miscellaneous temporary data buffers.
284.It Dv M_NTFSMNT
285NTFS mount structures.
286.It Dv M_NTFSNTNODE
287NTFS ntnode information.
288.It Dv M_NTFSNODE
289NTFS fnode information.
290.It Dv M_NTFSDIR
291NTFS directory buffers.
292.It Dv M_NTFSHASH
293NTFS ntnode hash tables.
294.It Dv M_NTFSVATTR
295NTFS file attribute information.
296.It Dv M_NTFSRDATA
297NTFS resident data.
298.It Dv M_NTFSDECOMP
299NTFS decompression temporary storage.
300.It Dv M_NTFSRUN
301NTFS vrun storage.
302.It Dv M_KEVENT
303.Xr kqueue 2
304data structures.
305.It Dv M_UDFMOUNT
306UDF mount structures.
307.It Dv M_UDFFENTRY
308UDF file entries.
309.It Dv M_UDFFID
310UDF file ID.
311.It Dv M_AGP
312AGP memory.
313.It Dv M_DRM
314Direct Rendering Manager.
315.El
316.Sh CONTEXT
317.Fn malloc
318and
319.Fn mallocarray
320can be called during autoconf, from process context, or from interrupt context
321if
322.Dv M_NOWAIT
323is passed via
324.Fa flags .
325They can't be called from interrupt context if
326.Dv M_WAITOK
327is passed via
328.Fa flags .
329.Pp
330.Fn free
331can be called during autoconf, from process context, or from interrupt context.
332.Sh RETURN VALUES
333.Fn malloc
334and
335.Fn mallocarray
336return a kernel virtual address that is suitably aligned for storage of
337any type of object.
338.Sh DIAGNOSTICS
339A kernel compiled with the
340.Dv DIAGNOSTIC
341configuration option attempts to detect memory corruption caused by
342such things as writing outside the allocated area and unbalanced calls to
343.Fn malloc
344or
345.Fn mallocarray ,
346and
347.Fn free .
348Failing consistency checks will cause a panic or a system console message:
349.Pp
350.Bl -bullet -offset indent -compact
351.It
352panic:
353.Dq malloc: bogus type
354.It
355panic:
356.Dq malloc: out of space in kmem_map
357.It
358panic:
359.Dq malloc: allocation too large
360.It
361panic:
362.Dq malloc: wrong bucket
363.It
364panic:
365.Dq malloc: lost data
366.It
367panic:
368.Dq mallocarray: overflow
369.It
370panic:
371.Dq free: unaligned addr
372.It
373panic:
374.Dq free: duplicated free
375.It
376panic:
377.Dq free: multiple frees
378.It
379panic:
380.Dq free: non-malloced addr
381.It
382panic:
383.Dq free: size too large
384.It
385panic:
386.Dq free: size too small
387.It
388panic:
389.Dq kmeminit: minbucket too small/struct freelist too big
390.It
391.Dq multiply freed item Aq addr
392.It
393.Dq Data modified on freelist: Aq data object description
394.El
395.Sh SEE ALSO
396.Xr systat 1 ,
397.Xr vmstat 8
398