Carbon


EmptyHandle

Header: MacMemory.h Carbon status: Supported

Purges a relocatable block and sets the corresponding handle’s master pointer to NULL.

void EmptyHandle (
    Handle h
);
h

A handle to a relocatable block.

DISCUSSION

The EmptyHandle function purges the relocatable block whose handle is h and sets the handle’s master pointer to NULL. The EmptyHandle function allows you to free memory taken by a relocatable block without freeing the relocatable block’s master pointer for other uses. The block whose handle is h must be unlocked but need not be purgeable.

Note that if there are multiple handles to the relocatable block, then calling the EmptyHandle function empties them all, because all of the handles share a common master pointer. When you later use ReallocateHandle to reallocate space for the block, the master pointer is updated, and all of the handles reference the new block correctly.

To purge all of the blocks in a heap zone that are marked purgeable, use the PurgeMem function.

To free the memory taken up by a relocatable block and release the block’s master pointer for other uses, use the DisposeHandle function.

Call the function MemError to get the result code. See “Result Codes”.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when InterfaceLib 7.1 or later is installed. Exported by CarbonLib 1.0 and later and by InterfaceLib 7.1 and later.


© 2000 Apple Computer, Inc. — (Last Updated 4/6/2000)