OSMalloc.h Reference

Declared in
OSMalloc.h

Overview

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

See the Overview section above for header-level documentation.

OSFree

Frees a block of memory allocated by OSMalloc.

extern 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.

Availability
  • Available in OS X v10.4 and later.
Declared In
OSMalloc.h

OSMalloc

Allocates a block of memory associated with a given OSMallocTag.

extern 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.

Availability
  • Available in OS X v10.4 and later.
Declared In
OSMalloc.h

OSMalloc_noblock

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

extern 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.

Availability
  • Available in OS X v10.4 and later.
Declared In
OSMalloc.h

OSMalloc_nowait

Equivalent to OSMalloc_noblock.

extern void * OSMalloc_nowait(
   uint32_t size,
   OSMallocTag tag);
Availability
  • Available in OS X v10.4 and later.
Declared In
OSMalloc.h

OSMalloc_Tagalloc

Creates a tag for use with OSMalloc functions.

extern 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.

Availability
  • Available in OS X v10.4 and later.
Declared In
OSMalloc.h

OSMalloc_Tagfree

Frees a tag used with OSMalloc functions.

extern 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.

Availability
  • Available in OS X v10.4 and later.
Declared In
OSMalloc.h

Data Types

See the Overview section above for header-level documentation.

OSMallocTag

An opaque type used to track memory allocations.

typedef struct __OSMallocTag__ * OSMallocTag;
Availability
  • Available in OS X v10.4 and later.
Declared In
OSMalloc.h

OSMallocTag_t

See OSMallocTag.

typedef struct __OSMallocTag__ * OSMallocTag_t;
Availability
  • Available in OS X v10.4 and later.
Declared In
OSMalloc.h

Constants

See the Overview section above for header-level documentation.

Miscellaneous Defines

   
#define OSMT_DEFAULT 0x00
#define OSMT_PAGEABLE 0x01
Constants
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.

Declared in OSMalloc.h.

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.

Declared in OSMalloc.h.