Mac Developer Library

Developer

OSMalloc.h Reference

Options
Deployment Target:

On This Page

OSMalloc.h Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

This header declares the OSMalloc memory-allocation KPI.

Kernel extensions can use these functions to allocate and deallocate memory blocks that are tracked under named tags. A kernel extension can create whatever tags it needs, but typically just creates one with its bundle identifier.

Tags are required; attempting to use these functions without one will result in a panic.

Use Restrictions

None of the OSMalloc functions are safe to call in a primary interrupt handler.

Included Headers

  • <sys/cdefs.h>

  • <stdint.h>

Functions

  • Frees a block of memory allocated by OSMalloc.

    Declaration

    Objective-C

    void OSFree ( void *addr, uint32_t size, OSMallocTag tag );

    Parameters

    addr

    A pointer to the memory block to free.

    size

    The size of the memory block to free.

    tag

    The OSMallocTag with which addr was originally allocated.

    Import Statement

    Objective-C

    #include <OSMalloc.h>;

    Availability

    Available in OS X v10.4 and later.

  • Allocates a block of memory associated with a given OSMallocTag.

    Declaration

    Objective-C

    void * OSMalloc ( uint32_t size, OSMallocTag tag );

    Parameters

    size

    The size of the memory block to allocate.

    tag

    The OSMallocTag under which to allocate the memory.

    Return Value

    A pointer to the memory on success, NULL on failure.

    Discussion

    If tag was created with the OSMT_PAGEABLE attribute and size is a full page or larger, the allocated memory is pageable; otherwise it is wired.

    Import Statement

    Objective-C

    #include <OSMalloc.h>;

    Availability

    Available in OS X v10.4 and later.

  • Allocates a block of memory associated with a given OSMallocTag, returning NULL if it would block.

    Declaration

    Objective-C

    void * OSMalloc_noblock ( uint32_t size, OSMallocTag tag );

    Parameters

    size

    The size of the memory block to allocate.

    tag

    The OSMallocTag under which to allocate the memory.

    Return Value

    A pointer to the memory on success, NULL on failure or if allocation would block.

    Discussion

    If tag was created with the OSMT_PAGEABLE attribute and size is a full page or larger, the allocated memory is pageable; otherwise it is wired.

    This function is guaranteed not to block.

    Import Statement

    Objective-C

    #include <OSMalloc.h>;

    Availability

    Available in OS X v10.4 and later.

  • Equivalent to OSMalloc_noblock.

    Declaration

    Objective-C

    void * OSMalloc_nowait ( uint32_t size, OSMallocTag tag );

    Import Statement

    Objective-C

    #include <OSMalloc.h>;

    Availability

    Available in OS X v10.4 and later.

  • Creates a tag for use with OSMalloc functions.

    Declaration

    Objective-C

    OSMallocTag OSMalloc_Tagalloc ( const char *name, uint32_t flags );

    Parameters

    name

    The name of the tag to create.

    flags

    A bitmask that controls allocation behavior; see description.

    Return Value

    An opaque tag to be used with OSMalloc functions for tracking memory usage.

    Discussion

    OSMalloc tags can have arbitrary names of a length up to 63 characters. Calling this function twice with the same name creates two tags, which share that name.

    flags can be the bitwise OR of the following flags:

    • OSMT_DEFAULT - allocations are wired. This is the 'zero' bitmask value and is overridden by any other flag specified.

    • OSMT_PAGEABLE - allocations of a full page size or greater are pageable; allocations smaller than a page are wired.

    Import Statement

    Objective-C

    #include <OSMalloc.h>;

    Availability

    Available in OS X v10.4 and later.

  • Frees a tag used with OSMalloc functions.

    Declaration

    Objective-C

    void OSMalloc_Tagfree ( OSMallocTag tag );

    Parameters

    tag

    The OSMallocTag to free.

    Discussion

    OSMalloc tags must not be freed while any memory blocks allocated with them still exist. Any OSMalloc function called on those blocks will result in a panic.

    Import Statement

    Objective-C

    #include <OSMalloc.h>;

    Availability

    Available in OS X v10.4 and later.

Data Types

See the Overview section above for header-level documentation.

  • An opaque type used to track memory allocations.

    Declaration

    Objective-C

    typedef struct __OSMallocTag__ * OSMallocTag;

    Import Statement

    Objective-C

    #include <OSMalloc.h>;

    Availability

    Available in OS X v10.4 and later.

  • Declaration

    Objective-C

    typedef struct __OSMallocTag__ * OSMallocTag_t;

    Import Statement

    Objective-C

    #include <OSMalloc.h>;

    Availability

    Available in OS X v10.4 and later.

Constants

See the Overview section above for header-level documentation.

  • Declaration

    Objective-C

    #define OSMT_DEFAULT 0x00 #define OSMT_PAGEABLE 0x01

    Constants

    • OSMT_DEFAULT

      OSMT_DEFAULT

      Indicates that an OSMallocTag be created with default attributes.

      An OSMallocTag created with this attribute allocates all blocks in wired memory.

      Available in OS X v10.4 and later.

    • OSMT_PAGEABLE

      OSMT_PAGEABLE

      Indicates that an OSMallocTag should allocate pageable memory when possible.

      An OSMallocTag created with this attribute allocates blocks of a full page size or larger in pageable memory, and blocks smaller than a full page size in wired memory.

      Available in OS X v10.4 and later.