unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

MALLOC(9)                BSD Kernel Developer's Manual               MALLOC(9)

NAME
     malloc, mallocarray, free -- kernel memory allocator

SYNOPSIS
     #include <&lt;sys/types.h>&gt;
     #include <&lt;sys/malloc.h>&gt;

     void *
     malloc(size_t size, int type, int flags);

     void *
     mallocarray(size_t nmemb, size_t size, int type, int flags);

     void
     free(void *addr, int type, size_t size);

DESCRIPTION
     The malloc() function allocates uninitialized memory in kernel address
     space for an object whose size is specified by size.

     The mallocarray() function is the same as malloc(), but allocates space
     for an array of nmemb objects and checks for arithmetic overflow.

     The free() function releases memory at address addr that was previously
     allocated by malloc() or mallocarray() for re-use.  The same object size
     originally provided to malloc() should be specified by size, because
     free() will operate faster knowing this.  If tracking the size is diffi-
     cult, specify size as 0.  If addr is a null pointer, no action occurs.

     The flags argument affects the operational characteristics of malloc()
     and mallocarray() as follows:

           M_WAITOK
                If memory is currently unavailable, malloc() may call sleep to
                wait for resources to be released by other processes.

           M_NOWAIT
                Causes malloc() to return NULL if the request cannot be imme-
                diately fulfilled due to resource shortage.

           M_CANFAIL
                In the M_WAITOK case, if not enough memory is available,
                return NULL instead of calling panic(9).  If mallocarray()
                detects an overflow or malloc() detects an excessive alloca-
                tion, return NULL instead of calling panic(9).

           M_ZERO
                Causes allocated memory to be zeroed.

     One of M_NOWAIT or M_WAITOK must be specified via the flags argument.

     The 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
     vmstat(8) or systat(1) if either of the kernel options(4) KMEMSTATS or
     DEBUG are enabled.

     The following types are currently defined:

           M_FREE          Should be on free list.
           M_DEVBUF        Device driver memory.
           M_DEBUG         malloc debug structures.
           M_PCB           Protocol control blocks.
           M_RTABLE        Routing tables.
           M_FTABLE        Fragment reassembly headers.
           M_IFADDR        Interface addresses.
           M_SOOPTS        Socket options.
           M_SYSCTL        Sysctl persistent buffers.
           M_IOCTLOPS      Ioctl data buffers.
           M_IOV           Large IOVs.
           M_MOUNT         VFS mount structs.
           M_NFSREQ        NFS request headers.
           M_NFSMNT        NFS mount structures.
           M_VNODE         Dynamically allocated vnodes.
           M_CACHE         Dynamically allocated cache entries.
           M_DQUOT         UFS quota entries.
           M_UFSMNT        UFS mount structures.
           M_SHM           SVID compatible shared memory segments.
           M_VMMAP         VM map structures.
           M_SEM           SVID compatible semaphores.
           M_DIRHASH       UFS directory hash structures.
           M_ACPI          ACPI structures.
           M_VMPMAP        VM pmap data.
           M_FILE          Open file structures.
           M_FILEDESC      Open file descriptor tables.
           M_PROC          Proc structures.
           M_SUBPROC       Proc sub-structures.
           M_VCLUSTER      Cluster for VFS.
           M_MFSNODE       MFS vnode private part.
           M_NETADDR       Export host address structures.
           M_NFSSVC        NFS server structures.
           M_NFSD          NFS server daemon structures.
           M_IPMOPTS       Internet multicast options.
           M_IPMADDR       Internet multicast addresses.
           M_IFMADDR       Link-level multicast addresses.
           M_MRTABLE       Multicast routing tables.
           M_ISOFSMNT      ISOFS mount structures.
           M_ISOFSNODE     ISOFS vnode private part.
           M_MSDOSFSMNT    MSDOS FS mount structures.
           M_MSDOSFSFAT    MSDOS FS FAT tables.
           M_MSDOSFSNODE   MSDOS FS vnode private part.
           M_TTYS          Allocated tty structures.
           M_EXEC          Argument lists & other mem used by exec.
           M_MISCFSMNT     Miscellaneous FS mount structures.
           M_FUSEFS        FUSE FS mount structures.
           M_PFKEY         Pfkey data.
           M_TDB           Transforms database.
           M_XDATA         IPsec data.
           M_PAGEDEP       File page dependencies.
           M_INODEDEP      Inode dependencies.
           M_NEWBLK        New block allocation.
           M_INDIRDEP      Indirect block dependencies.
           M_VMSWAP        VM swap structures.
           M_UVMAMAP       UVM amap and related.
           M_UVMAOBJ       UVM aobj and related.
           M_USB           USB general.
           M_USBDEV        USB device driver.
           M_USBHC         USB host controller.
           M_MEMDESC       Memory range.
           M_CRYPTO_DATA   crypto(9) data buffers.
           M_CREDENTIALS   ipsec(4) related credentials.
           M_EMULDATA      Per process emulation data.
           M_IP6OPT        IPv6 options.
           M_IP6NDP        IPv6 neighbour discovery structures.
           M_TEMP          Miscellaneous temporary data buffers.
           M_NTFSMNT       NTFS mount structures.
           M_NTFSNTNODE    NTFS ntnode information.
           M_NTFSNODE      NTFS fnode information.
           M_NTFSDIR       NTFS directory buffers.
           M_NTFSHASH      NTFS ntnode hash tables.
           M_NTFSVATTR     NTFS file attribute information.
           M_NTFSRDATA     NTFS resident data.
           M_NTFSDECOMP    NTFS decompression temporary storage.
           M_NTFSRUN       NTFS vrun storage.
           M_KEVENT        kqueue(2) data structures.
           M_BWMETER       Multicast upcall bandwidth meters.
           M_UDFMOUNT      UDF mount structures.
           M_UDFFENTRY     UDF file entries.
           M_UDFFID        UDF file ID.
           M_AGP           AGP memory.
           M_DRM           Direct Rendering Manager.

CONTEXT
     malloc() and mallocarray() can be called during autoconf, from process
     context, or from interrupt context if M_NOWAIT is passed via flags.  They
     can't be called from interrupt context if M_WAITOK is passed via flags.

     free() can be called during autoconf, from process context, or from
     interrupt context.

RETURN VALUES
     malloc() and mallocarray() return a kernel virtual address that is suit-
     ably aligned for storage of any type of object.

DIAGNOSTICS
     A kernel compiled with the DIAGNOSTIC configuration option attempts to
     detect memory corruption caused by such things as writing outside the
     allocated area and unbalanced calls to malloc() or mallocarray(), and
     free().  Failing consistency checks will cause a panic or a system con-
     sole message:

           o   panic: ``malloc: bogus type''
           o   panic: ``malloc: out of space in kmem_map''
           o   panic: ``malloc: allocation too large''
           o   panic: ``malloc: wrong bucket''
           o   panic: ``malloc: lost data''
           o   panic: ``mallocarray: overflow''
           o   panic: ``free: unaligned addr''
           o   panic: ``free: duplicated free''
           o   panic: ``free: multiple frees''
           o   panic: ``free: non-malloced addr''
           o   panic: ``free: size too large''
           o   panic: ``free: size too small''
           o   panic: ``kmeminit: minbucket too small/struct freelist too
               big''
           o   ``multiply freed item <addr>''
           o   ``Data modified on freelist: <data object description>''

DEBUGGING
     A kernel compiled with the MALLOC_DEBUG option allows for more extensive
     debugging of memory allocations.  The debug_malloc_type,
     debug_malloc_size, debug_malloc_size_lo and debug_malloc_size_hi vari-
     ables choose which allocation to debug.  debug_malloc_type should be set
     to the memory type and debug_malloc_size should be set to the memory size
     to debug.  0 can be used as a wildcard.  debug_malloc_size_lo and
     debug_malloc_size_hi can be used to specify a range of sizes if the exact
     size to debug is not known.  When those are used, debug_malloc_size needs
     to be set to the wildcard.  M_DEBUG can also be specified as an alloca-
     tion type to force allocation with debugging.

     Every call to malloc() or mallocarray() with a memory type and size that
     matches the debugged type and size will allocate two virtual pages.  The
     pointer returned will be aligned so that the requested area will end at
     the page boundary and the second virtual page will be left unmapped.
     This way we can catch reads and writes outside the allocated area.

     Every call to free() with memory that was returned by the debugging allo-
     cators will cause the memory area to become unmapped so that we can catch
     dangling reads and writes to freed memory.

     There are no special diagnostics if any errors are caught by the debug-
     ging malloc.  The errors will look like normal access to unmapped memory.
     On a memory access error, the show malloc command in ddb(4) can be
     invoked to see what memory areas are allocated and freed.  If the fault-
     ing address is within two pages from an address on the allocated list,
     there was an access outside the allocated area.  If the faulting address
     is within two pages from an address on the free list, there was an access
     to freed memory.

     Care needs to be taken when using the MALLOC_DEBUG option:  the memory
     consumption can run away pretty quickly and there is a severe performance
     degradation when allocating and freeing debugged memory types.

SEE ALSO
     systat(1), vmstat(8)

BSD                            November 19, 2014                           BSD