Legacy Document

Inside Macintosh: Memory /

Chapter 2 - Memory Manager / Memory Manager Reference

Memory Manager Routines / Manipulating Blocks of Memory

HandToHand

Use the HandToHand function to copy all of the data from one relocatable block to a new relocatable block.

FUNCTION HandToHand (VAR theHndl: Handle): OSErr;

theHndl

On entry, a handle to the relocatable block whose data is to be copied. On exit, a handle to a new relocatable block whose data duplicates that of
the original.

DESCRIPTION

The HandToHand function attempts to copy the information in the relocatable block to which theHndl is a handle; if successful, HandToHand returns a handle to the new relocatable block in theHndl. The new relocatable block is created in the same heap zone as the original block (which might not be the current heap zone).

Because HandToHand replaces its input parameter with the new handle, you should retain the original value of the input parameter somewhere else, or you won't be able to access it. Here is an example:

VAR 
   original, copy: Handle; 
   myErr: OSErr;
...
   copy := original;          {both handles access same block}
   myErr := HandToHand(copy); {copy now points to copy of block}

SPECIAL CONSIDERATIONS

If successful in creating a new relocatable block, the HandToHand function does not duplicate the properties of the original block. The new block is unlocked, unpurgeable, and not a resource. You might need to call HLock, HPurge, or HSetRBit (or the combination of HGetState and HSetState) to adjust the properties of the new block.

Because HandToHand allocates memory, you should not call it at interrupt time.

ASSEMBLY-LANGUAGE INFORMATION

The registers on entry and exit for HandToHand are

Registers on entry
A0	Handle to original data

Registers on exit
A0	Handle to copy of data
D0	Result code

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough memory
nilHandleErr	-109	NIL master pointer
memWZErr	-111	Attempt to operate on a free block

SEE ALSO

If you want to copy only part of a relocatable block into a new relocatable block, use the PtrToHand function, described on page 2-60, after locking and dereferencing a handle to the relocatable block to be copied.