Legacy Document

Inside Macintosh: Memory /

Chapter 2 - Memory Manager / Memory Manager Reference

Memory Manager Routines / Manipulating Blocks of Memory

PtrToHand

To copy data referenced by a pointer to a new relocatable block, use the PtrToHand function.

FUNCTION PtrToHand (srcPtr: Ptr; VAR dstHndl: Handle; 
                     size: LongInt): OSErr;

srcPtr

The address of the first byte to copy.

dstHndl

A handle for which you have not yet allocated any memory. The PtrToHand function allocates memory for the handle and copies size bytes beginning at srcPtr into it.

size

The number of bytes to copy.

DESCRIPTION

The PtrToHand function returns, in dstHndl, a newly created handle to a copy of the number of bytes specified by the size parameter, beginning at the location specified by srcPtr. The dstHndl parameter must be a handle variable that is not empty and is not a handle to an allocated block of size 0.

SPECIAL CONSIDERATIONS

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

ASSEMBLY-LANGUAGE INFORMATION

The registers on entry and exit for PtrToHand are

Registers on entry
A0	Pointer to source
D0	Number of bytes to copy

Registers on exit
A0	Destination handle
D0	Result code

RESULT CODES

noErr	0	No error
memFullErr	-108	Not enough memory

SEE ALSO

You can use the PtrToHand function to copy data from one handle to a new handle
if you dereference and lock the source handle. However, if you want to copy all of
the data from one handle to another, the HandToHand function (described on page 2-62) is more efficient.