diff options
Diffstat (limited to 'static/openbsd/man9/malloc.9')
| -rw-r--r-- | static/openbsd/man9/malloc.9 | 403 |
1 files changed, 403 insertions, 0 deletions
diff --git a/static/openbsd/man9/malloc.9 b/static/openbsd/man9/malloc.9 new file mode 100644 index 00000000..a1fa4be2 --- /dev/null +++ b/static/openbsd/man9/malloc.9 @@ -0,0 +1,403 @@ +.\" $OpenBSD: malloc.9,v 1.72 2024/01/19 15:10:27 deraadt Exp $ +.\" $NetBSD: malloc.9,v 1.2 1996/10/30 05:29:54 lukem Exp $ +.\" +.\" Copyright (c) 1996 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Paul Kranenburg. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE +.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd $Mdocdate: January 19 2024 $ +.Dt MALLOC 9 +.Os +.Sh NAME +.Nm malloc , +.Nm mallocarray , +.Nm free +.Nd kernel memory allocator +.Sh SYNOPSIS +.In sys/types.h +.In sys/malloc.h +.Ft void * +.Fn malloc "size_t size" "int type" "int flags" +.Ft void * +.Fn mallocarray "size_t nmemb" "size_t size" "int type" "int flags" +.Ft void +.Fn free "void *addr" "int type" "size_t size" +.Sh DESCRIPTION +The +.Fn malloc +function allocates uninitialized memory in kernel address space for an +object whose size is specified by +.Fa size . +.Pp +The +.Fn mallocarray +function is the same as +.Fn malloc , +but allocates space for an array of +.Fa nmemb +objects and checks for arithmetic overflow. +.Pp +The +.Fn free +function releases memory at address +.Fa addr +that was previously allocated by +.Fn malloc +or +.Fn mallocarray +for re-use. +The same object size originally provided to +.Fn malloc +should be specified by +.Fa size , +because +.Fn free +will operate faster knowing this. +If tracking the size is difficult, specify +.Ar size +as 0. +If +.Fa addr +is a null pointer, no action occurs. +.Pp +The +.Fa flags +argument affects the operational characteristics of +.Fn malloc +and +.Fn mallocarray +as follows: +.Bl -tag -width xxx -offset indent +.It Dv M_WAITOK +If memory is currently unavailable, +.Fn malloc +may call sleep to wait for resources to be released by other processes. +.It Dv M_NOWAIT +Causes +.Fn malloc +to return +.Dv NULL +if the request cannot be immediately fulfilled due to resource shortage. +.It Dv M_CANFAIL +In the +.Dv M_WAITOK +case, if not enough memory is available, return +.Dv NULL +instead of calling +.Xr panic 9 . +If +.Fn mallocarray +detects an overflow +or +.Fn malloc +detects an excessive allocation, return +.Dv NULL +instead of calling +.Xr panic 9 . +.It Dv M_ZERO +Causes allocated memory to be zeroed. +.El +.Pp +One of +.Dv M_NOWAIT +or +.Dv M_WAITOK +must be specified via the +.Fa flags +argument. +.Pp +The +.Fa type +argument broadly identifies the kernel subsystem for which the allocated +memory was needed, and is commonly used to maintain statistics about +kernel memory usage. +These statistics can be examined using +.Xr vmstat 8 +or +.Xr systat 1 +if either of the kernel +.Xr options 4 +.Cm KMEMSTATS +or +.Cm DEBUG +are enabled. +.Pp +The following types are currently defined: +.Pp +.Bl -tag -offset indent -width XXXXXXXXXXXXXX -compact +.\" START DEFINES sys/malloc.h (M_FREE,M_LAST) +.It Dv M_DEVBUF +Device driver memory. +.It Dv M_PCB +Protocol control blocks. +.It Dv M_RTABLE +Routing tables. +.It Dv M_PF +Packet filter structures. +.It Dv M_IFADDR +Interface addresses. +.It Dv M_IFGROUP +Interface groups. +.It Dv M_SYSCTL +Sysctl persistent buffers. +.It Dv M_COUNTERS +Per-CPU counters via +.Xr counters_alloc 9 . +.It Dv M_IOCTLOPS +Ioctl data buffers. +.It Dv M_IOV +Large IOVs. +.It Dv M_MOUNT +VFS mount structs. +.It Dv M_NFSREQ +NFS request headers. +.It Dv M_NFSMNT +NFS mount structures. +.It Dv M_LOG +Messages in kernel log stash. +.It Dv M_VNODE +Dynamically allocated vnodes. +.It Dv M_DQUOT +UFS quota entries. +.It Dv M_UFSMNT +UFS mount structures. +.It Dv M_SHM +SVID compatible shared memory segments. +.It Dv M_VMMAP +VM map structures. +.It Dv M_SEM +SVID compatible semaphores. +.It Dv M_DIRHASH +UFS directory hash structures. +.It Dv M_ACPI +ACPI structures. +.It Dv M_VMPMAP +VM pmap data. +.It Dv M_FILEDESC +Open file descriptor tables. +.It Dv M_SIGIO +Sigio structures. +.It Dv M_PROC +Proc structures. +.It Dv M_SUBPROC +Proc sub-structures. +.It Dv M_MFSNODE +MFS vnode private part. +.It Dv M_NETADDR +Export host address structures. +.It Dv M_NFSSVC +NFS server structures. +.It Dv M_NFSD +NFS server daemon structures. +.It Dv M_IPMOPTS +Internet multicast options. +.It Dv M_IPMADDR +Internet multicast addresses. +.It Dv M_IFMADDR +Link-level multicast addresses. +.It Dv M_MRTABLE +Multicast routing tables. +.It Dv M_ISOFSMNT +ISOFS mount structures. +.It Dv M_ISOFSNODE +ISOFS vnode private part. +.It Dv M_MSDOSFSMNT +MSDOS FS mount structures. +.It Dv M_MSDOSFSFAT +MSDOS FS FAT tables. +.It Dv M_MSDOSFSNODE +MSDOS FS vnode private part. +.It Dv M_TTYS +Allocated tty structures. +.It Dv M_EXEC +Argument lists & other mem used by exec. +.It Dv M_MISCFSMNT +Miscellaneous FS mount structures. +.It Dv M_FUSEFS +FUSE FS mount structures. +.It Dv M_PINSYSCALL +.Xr pinsyscalls 2 +related data. +.It Dv M_PFKEY +Pfkey data. +.It Dv M_TDB +Transforms database. +.It Dv M_XDATA +IPsec data. +.It Dv M_PAGEDEP +File page dependencies. +.It Dv M_INODEDEP +Inode dependencies. +.It Dv M_NEWBLK +New block allocation. +.It Dv M_INDIRDEP +Indirect block dependencies. +.It Dv M_VMSWAP +VM swap structures. +.It Dv M_UVMAMAP +UVM amap and related. +.It Dv M_UVMAOBJ +UVM aobj and related. +.It Dv M_USB +USB general. +.It Dv M_USBDEV +USB device driver. +.It Dv M_USBHC +USB host controller. +.It Dv M_WITNESS +.Xr witness 4 +memory. +.It Dv M_MEMDESC +Memory range. +.It Dv M_CRYPTO_DATA +.Xr crypto 9 +data buffers. +.It Dv M_CREDENTIALS +.Xr ipsec 4 +related credentials. +.It Dv M_IP6OPT +IPv6 options. +.It Dv M_IP6NDP +IPv6 Neighbor Discovery structures. +.It Dv M_TEMP +Miscellaneous temporary data buffers. +.It Dv M_NTFSMNT +NTFS mount structures. +.It Dv M_NTFSNTNODE +NTFS ntnode information. +.It Dv M_NTFSFNODE +NTFS fnode information. +.It Dv M_NTFSDIR +NTFS directory buffers. +.It Dv M_NTFSNTHASH +NTFS ntnode hash tables. +.It Dv M_NTFSNTVATTR +NTFS file attribute information. +.It Dv M_NTFSRDATA +NTFS resident data. +.It Dv M_NTFSDECOMP +NTFS decompression temporary storage. +.It Dv M_NTFSRUN +NTFS vrun storage. +.It Dv M_KEVENT +.Xr kqueue 2 +data structures. +.It Dv M_SYNCACHE +SYN cache hash array. +.It Dv M_UDFMOUNT +UDF mount structures. +.It Dv M_UDFFENTRY +UDF file entries. +.It Dv M_UDFFID +UDF file IDs. +.It Dv M_AGP +AGP memory. +.It Dv M_DRM +Direct Rendering Manager. +.\" END DEFINES +.El +.Sh CONTEXT +.Fn malloc +and +.Fn mallocarray +can be called during autoconf, from process context, or from interrupt context +if +.Dv M_NOWAIT +is passed via +.Fa flags . +They can't be called from interrupt context if +.Dv M_WAITOK +is passed via +.Fa flags . +.Pp +.Fn free +can be called during autoconf, from process context, or from interrupt context. +.Sh RETURN VALUES +.Fn malloc +and +.Fn mallocarray +return a kernel virtual address that is suitably aligned for storage of +any type of object. +.Sh DIAGNOSTICS +A kernel compiled with the +.Dv DIAGNOSTIC +configuration option attempts to detect memory corruption caused by +such things as writing outside the allocated area and unbalanced calls to +.Fn malloc +or +.Fn mallocarray , +and +.Fn free . +Failing consistency checks will cause a panic or a system console message: +.Pp +.Bl -bullet -offset indent -compact +.It +panic: +.Dq malloc: bogus type +.It +panic: +.Dq malloc: out of space in kmem_map +.It +panic: +.Dq malloc: allocation too large +.It +panic: +.Dq malloc: wrong bucket +.It +panic: +.Dq malloc: lost data +.It +panic: +.Dq mallocarray: overflow +.It +panic: +.Dq free: unaligned addr +.It +panic: +.Dq free: duplicated free +.It +panic: +.Dq free: multiple frees +.It +panic: +.Dq free: non-malloced addr +.It +panic: +.Dq free: size too large +.It +panic: +.Dq free: size too small +.It +panic: +.Dq kmeminit: minbucket too small/struct freelist too big +.It +.Dq multiply freed item Aq addr +.It +.Dq Data modified on freelist: Aq data object description +.El +.Sh SEE ALSO +.Xr systat 1 , +.Xr vmstat 8 |