Carbon


ReallocateHandle

Header: MacMemory.h Carbon status: Supported

Allocates a new relocatable block of a specified size and sets a handle’s master pointer to point to the new block.

void ReallocateHandle (
    Handle h, 
    Size byteCount
);
Parameter descriptions
h

A handle to a relocatable block.

byteCount

The desired new logical size (in bytes) of the relocatable block. The new block is unlocked and unpurgeable.

DISCUSSION

Usually you use ReallocateHandle to reallocate space for a block that you have emptied or the Memory Manager has purged. If the handle references an existing block, ReallocateHandle releases that block before creating a new one.

In case of an error, ReallocateHandle neither allocates a new block nor changes the master pointer to which handle h points.

If many handles reference a single purged, relocatable block, you need to call ReallocateHandle on just one of them.

To reallocate space for a resource that has been purged, you should call LoadResource, not ReallocateHandle.

Because ReallocateHandle releases any existing relocatable block referenced by the handle h before allocating a new one, it does not provide an efficient technique for resizing relocatable blocks. To do that, use the SetHandleSize function.

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

Because ReallocateHandle might purge and allocate memory, you should not call it at interrupt time.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.


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